@photostructure/sqlite
    Preparing search index...

    Development

    Information about the development of @photostructure/sqlite.

    • Full API compliance running in both ESM and CJS modes
    • Multi-platform CI/CD with dedicated ARM64 and x64 build jobs across all platforms
    • Security scanning and memory leak detection
    • Automated sync from Node.js and SQLite upstream
    • Benchmarking suite covering popular Node.js SQLite libraries

    This project was built with substantial assistance from Claude Code, an AI coding assistant.

    1. Analysis: Claude analyzed the Node.js SQLite source code and architecture
    2. Shim layer: Developed compatibility layer for Node.js internals
    3. Implementation: Ported C++ code with N-API adaptations
    4. Testing: Created test suite
    5. Documentation: Generated user and API documentation
    6. CI/CD: Set up multi-platform build and release pipeline

    All code was reviewed by a human and validated by automated tests before merging:

    • Automated testing across platforms
    • Memory and undefined-behavior detection (AddressSanitizer, LeakSanitizer, UndefinedBehaviorSanitizer, Valgrind)
    • Native static analysis (clang-tidy, gating on ownership/lifetime checks)
    • Security scanning (npm audit, OSV, CodeQL)
    • Performance benchmarking
    • Node.js 22+
    • Python 3.8+
    • C++ compiler:
      • Linux: GCC 10+ or Clang 10+
      • macOS: Xcode Command Line Tools
      • Windows: Visual Studio 2019+
    # Install dependencies
    npm install

    # Build native module
    npm run build:native

    # Run tests
    npm test

    # Run benchmarks
    npm run benchmark

    # Watch mode for TypeScript
    npm run watch

    # Lint code
    npm run lint

    # Format code
    npm run fmt

    # Run specific test file
    npm test -- working-with-data.test.ts

    See Architecture Documentation for details on:

    • Shim layer design
    • Node.js compatibility approach
    • Memory management strategy
    • Threading model
    1. Fork the repository
    2. Create a feature branch
    3. Make your changes
    4. Add tests for new functionality
    5. Ensure all tests pass
    6. Submit a pull request
    • TypeScript/JavaScript: Prettier with project config
    • C++: clang-format with project style
    • Commit messages: Conventional Commits format
    • New features must include tests
    • Tests must pass on all platforms
    • Memory leak tests for native code
    • Benchmark comparisons for performance changes

    Releases are cut from CI: the Build & Release workflow (.github/workflows/build.yml) is triggered manually via workflow_dispatch with a version bump (patch / minor / major), builds the prebuilds for every platform, and publishes to npm with provenance using OIDC trusted publishing. The version field in package.json is owned by that workflow — do not bump it by hand.

    Before dispatching a release, run npm run all (full build, lint, clang-tidy, cross-platform tests, and the sanitizer/Valgrind memory suite) and confirm no workflow is red for the commit being released.

    The project maintains synchronization with:

    • Node.js SQLite implementation
    • SQLite amalgamation source

    To avoid rate limiting when syncing from GitHub (60 requests/hour for unauthenticated requests), set up authentication:

    # Set your GitHub personal access token
    export GITHUB_TOKEN=your_personal_access_token

    # Now sync commands will use authentication (5000 requests/hour)
    npm run sync:node
    npm run sync:sqlite

    You can create a personal access token at: https://github.com/settings/tokens

    The token only needs public repository read access.

    # Sync from Node.js
    npm run sync:node

    # Update SQLite version
    npm run sync:sqlite

    Settings
    Member Visibility

    On This Page
    Development