feat(packages): add @sqliteai/sqlite-sync Node package

Author: Gioee

.github/workflows/main.yml

@@ -340,13 +340,82 @@ jobs:
         if: steps.tag.outputs.version != ''
         run: cd packages/android && ./gradlew publishAggregationToCentralPortal -PSIGNING_KEY="${{ secrets.SIGNING_KEY }}" -PSIGNING_PASSWORD="${{ secrets.SIGNING_PASSWORD }}" -PSONATYPE_USERNAME="${{ secrets.MAVEN_CENTRAL_USERNAME }}" -PSONATYPE_PASSWORD="${{ secrets.MAVEN_CENTRAL_TOKEN }}" -PVERSION="${{ steps.tag.outputs.version }}" -PAAR_PATH="../../artifacts/cloudsync-android-aar/cloudsync.aar"
 
+      - uses: actions/setup-node@v4
+        if: steps.tag.outputs.version != ''
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: build and publish npm packages
+        if: steps.tag.outputs.version != ''
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          cd packages/node
+
+          # Update version in package.json
+          echo "Updating versions to ${{ steps.tag.outputs.version }}..."
+
+          # Update package.json
+          jq --arg version "${{ steps.tag.outputs.version }}" \
+            '.version = $version | .optionalDependencies = (.optionalDependencies | with_entries(.value = $version))' \
+            package.json > package.tmp.json && mv package.tmp.json package.json
+
+          echo "✓ Updated package.json to version ${{ steps.tag.outputs.version }}"
+
+          # Generate platform packages
+          echo "Generating platform packages..."
+          node generate-platform-packages.js "${{ steps.tag.outputs.version }}" "../../artifacts" "./platform-packages"
+          echo "✓ Generated 7 platform packages"
+          ls -la platform-packages/
+
+          # Build main package
+          echo "Building main package..."
+          npm install
+          npm run build
+          npm test
+          echo "✓ Main package built and tested"
+
+          # Publish platform packages
+          echo "Publishing platform packages to npm..."
+          cd platform-packages
+          for platform_dir in */; do
+            platform_name=$(basename "$platform_dir")
+            echo "  Publishing @sqliteai/sqlite-sync-${platform_name}..."
+            cd "$platform_dir"
+            npm publish --access public
+            # TODO: Add --provenance flag after switching to OIDC (requires package to exist first)
+            cd ..
+            echo "  ✓ Published @sqliteai/sqlite-sync-${platform_name}"
+          done
+          cd ..
+
+          # Publish main package
+          echo "Publishing main package to npm..."
+          npm publish --access public
+          # TODO: Add --provenance flag after switching to OIDC (requires package to exist first)
+          echo "✓ Published @sqliteai/sqlite-sync@${{ steps.tag.outputs.version }}"
+
+          echo ""
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+          echo "✅ Successfully published 8 packages to npm"
+          echo "   Main: @sqliteai/sqlite-sync@${{ steps.tag.outputs.version }}"
+          echo "   Platform packages: 7"
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
       - uses: softprops/[email protected]
         if: steps.tag.outputs.version != ''
         with:
           body: |
-            # WASM Releases
-            **WASM repository**: [sqlite-wasm](https://github.com/sqliteai/sqlite-wasm)
-            **WASM package** is available on npm: [@sqliteai/sqlite-wasm](https://www.npmjs.com/package/@sqliteai/sqlite-wasm)
+            # Packages
+
+            [**Node**](https://www.npmjs.com/package/@sqliteai/sqlite-sync): `npm install @sqliteai/sqlite-sync`
+            [**WASM**](https://www.npmjs.com/package/@sqliteai/sqlite-wasm): `npm install @sqliteai/sqlite-wasm`
+            [**Android**](https://central.sonatype.com/artifact/ai.sqlite/sync): `ai.sqlite:sync:${{ steps.tag.outputs.version }}`
+            [**Swift**](https://github.com/sqliteai/sqlite-sync#swift-package): [Installation Guide](https://github.com/sqliteai/sqlite-sync#swift-package)
+
+            ---
+
           generate_release_notes: true
           tag_name: ${{ steps.tag.outputs.version }}
           files: |

.gitignore

@@ -1,18 +1,28 @@
 # Build artifacts
 build/
-/dist
+dist/
 .build
 *.a
 *.sqlite
 /curl/src
-**/dist/**
 
 # Test artifacts
 /coverage
 unittest
-**/node_modules/**
 .env
+
+# Node.js
+**/node_modules/**
 package-lock.json
+*.tsbuildinfo
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+packages/node/platform-packages/
+packages/node/test-artifacts/
+packages/node/test-output/
+packages/node/test-platform-packages/
 
 # iOS/macOS
 *.xcworkspacedata
@@ -33,6 +43,9 @@ jniLibs/
 .vscode
 .idea/
 *.iml
+*.swp
+*.swo
 
 # System
-.DS_Store
+.DS_Store
+Thumbs.db

packages/node/.npmignore

@@ -0,0 +1,19 @@
+# Development and build files
+src/
+*.test.ts
+*.test.js
+tsconfig.json
+tsup.config.ts
+
+# Scripts (only for repo/CI)
+generate-platform-packages.js
+
+# Development files
+node_modules/
+package-lock.json
+coverage/
+*.log
+
+# Git
+.git/
+.gitignore

packages/node/LICENSE.md

@@ -0,0 +1 @@
+../../LICENSE.md

packages/node/README.md

@@ -0,0 +1,156 @@
+# @sqliteai/sqlite-sync
+
+[![npm version](https://badge.fury.io/js/@sqliteai%2Fsqlite-sync.svg)](https://www.npmjs.com/package/@sqliteai/sqlite-sync)
+[![License](https://img.shields.io/badge/license-Elastic%202.0-blue.svg)](LICENSE.md)
+[![sqlite-sync coverage](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fsqliteai.github.io%2Fsqlite-sync%2F&search=%3Ctd%20class%3D%22headerItem%22%3EFunctions%3A%3C%5C%2Ftd%3E%5Cs*%3Ctd%20class%3D%22headerCovTableEntryHi%22%3E(%5B%5Cd.%5D%2B)%26nbsp%3B%25%3C%5C%2Ftd%3E&replace=%241%25&label=coverage&labelColor=rgb(85%2C%2085%2C%2085)%3B&color=rgb(167%2C%20252%2C%20157)%3B&link=https%3A%2F%2Fsqliteai.github.io%2Fsqlite-sync%2F)](https://sqliteai.github.io/sqlite-sync/)
+
+> SQLite Sync extension packaged for Node.js
+
+**SQLite Sync** is a multi-platform extension that brings a true **local-first experience** to your applications with minimal effort. It extends standard SQLite tables with built-in support for offline work and automatic synchronization, allowing multiple devices to operate independently—even without a network connection—and seamlessly stay in sync. With SQLite Sync, developers can easily build **distributed, collaborative applications** while continuing to rely on the **simplicity, reliability, and performance of SQLite**.
+
+Under the hood, SQLite Sync uses advanced **CRDT (Conflict-free Replicated Data Type)** algorithms and data structures designed specifically for **collaborative, distributed systems**. This means:
+
+- Devices can update data independently, even without a network connection.
+- When they reconnect, all changes are **merged automatically and without conflicts**.
+- **No data loss. No overwrites. No manual conflict resolution.**
+
+In simple terms, CRDTs make it possible for multiple users to **edit shared data at the same time**, from anywhere, and everything just works.
+
+## Features
+
+- ✅ **Bidirectional Sync** - Sync local SQLite databases with cloud storage
+- ✅ **Conflict Resolution** - Intelligent conflict handling and resolution
+- ✅ **Offline-First** - Full functionality without network connectivity
+- ✅ **Cross-platform** - Works on macOS, Linux (glibc/musl), and Windows
+- ✅ **Zero configuration** - Automatically detects and loads the correct binary for your platform
+- ✅ **TypeScript native** - Full type definitions included
+- ✅ **Modern ESM + CJS** - Works with both ES modules and CommonJS
+
+## Installation
+
+```bash
+npm install @sqliteai/sqlite-sync
+```
+
+The package automatically downloads the correct native extension for your platform during installation.
+
+### Supported Platforms
+
+| Platform | Architecture | Package |
+|----------|-------------|---------|
+| macOS | ARM64 (Apple Silicon) | `@sqliteai/sqlite-sync-darwin-arm64` |
+| macOS | x86_64 (Intel) | `@sqliteai/sqlite-sync-darwin-x86_64` |
+| Linux | ARM64 (glibc) | `@sqliteai/sqlite-sync-linux-arm64` |
+| Linux | ARM64 (musl/Alpine) | `@sqliteai/sqlite-sync-linux-arm64-musl` |
+| Linux | x86_64 (glibc) | `@sqliteai/sqlite-sync-linux-x86_64` |
+| Linux | x86_64 (musl/Alpine) | `@sqliteai/sqlite-sync-linux-x86_64-musl` |
+| Windows | x86_64 | `@sqliteai/sqlite-sync-win32-x86_64` |
+
+## sqlite-sync API
+
+For detailed information on how to use the sync extension features, see the [main documentation](https://github.com/sqliteai/sqlite-sync/blob/main/API.md).
+
+## Usage
+
+```typescript
+import { getExtensionPath } from '@sqliteai/sqlite-sync';
+import Database from 'better-sqlite3';
+
+const db = new Database(':memory:');
+db.loadExtension(getExtensionPath());
+
+// Ready to use
+const version = db.prepare('SELECT cloudsync_version()').pluck().get();
+console.log('Sync extension version:', version);
+```
+
+## Examples
+
+For complete, runnable examples, see the [sqlite-extensions-guide](https://github.com/sqliteai/sqlite-extensions-guide/tree/main/examples/node).
+
+These examples are generic and work with all SQLite extensions: `sqlite-vector`, `sqlite-sync`, `sqlite-js`, and `sqlite-ai`.
+
+## API Reference
+
+### `getExtensionPath(): string`
+
+Returns the absolute path to the SQLite Sync extension binary for the current platform.
+
+**Returns:** `string` - Absolute path to the extension file (`.so`, `.dylib`, or `.dll`)
+
+**Throws:** `ExtensionNotFoundError` - If the extension binary cannot be found for the current platform
+
+---
+
+### `getExtensionInfo(): ExtensionInfo`
+
+Returns detailed information about the extension for the current platform.
+
+**Returns:** `ExtensionInfo` object with the following properties:
+- `platform: Platform` - Current platform identifier (e.g., `'darwin-arm64'`)
+- `packageName: string` - Name of the platform-specific npm package
+- `binaryName: string` - Filename of the binary (e.g., `'cloudsync.dylib'`)
+- `path: string` - Full path to the extension binary
+
+**Throws:** `ExtensionNotFoundError` - If the extension binary cannot be found
+
+**Example:**
+```typescript
+import { getExtensionInfo } from '@sqliteai/sqlite-sync';
+
+const info = getExtensionInfo();
+console.log(`Running on ${info.platform}`);
+console.log(`Extension path: ${info.path}`);
+```
+
+---
+
+### `getCurrentPlatform(): Platform`
+
+Returns the current platform identifier.
+
+**Returns:** `Platform` - One of:
+- `'darwin-arm64'` - macOS ARM64
+- `'darwin-x86_64'` - macOS x86_64
+- `'linux-arm64'` - Linux ARM64 (glibc)
+- `'linux-arm64-musl'` - Linux ARM64 (musl)
+- `'linux-x86_64'` - Linux x86_64 (glibc)
+- `'linux-x86_64-musl'` - Linux x86_64 (musl)
+- `'win32-x86_64'` - Windows x86_64
+
+**Throws:** `Error` - If the platform is unsupported
+
+---
+
+### `isMusl(): boolean`
+
+Detects if the system uses musl libc (Alpine Linux, etc.).
+
+**Returns:** `boolean` - `true` if musl is detected, `false` otherwise
+
+---
+
+### `class ExtensionNotFoundError extends Error`
+
+Error thrown when the SQLite Sync extension cannot be found for the current platform.
+
+## Related Projects
+
+- **[@sqliteai/sqlite-vector](https://www.npmjs.com/package/@sqliteai/sqlite-vector)** - Vector search and similarity matching
+- **[@sqliteai/sqlite-ai](https://www.npmjs.com/package/@sqliteai/sqlite-ai)** - On-device AI inference and embedding generation
+- **[@sqliteai/sqlite-js](https://www.npmjs.com/package/@sqliteai/sqlite-js)** - Define SQLite functions in JavaScript
+
+## License
+
+This project is licensed under the [Elastic License 2.0](LICENSE.md).
+
+For production or managed service use, please [contact SQLite Cloud, Inc](mailto:[email protected]) for a commercial license.
+
+## Contributing
+
+Contributions are welcome! Please see the [main repository](https://github.com/sqliteai/sqlite-sync) to open an issue.
+
+## Support
+
+- 📖 [Documentation](https://github.com/sqliteai/sqlite-sync/blob/main/API.md)
+- 🐛 [Report Issues](https://github.com/sqliteai/sqlite-sync/issues)