@effect-native/libcrsql 0.16.3-1

package/README.md

@@ -0,0 +1,176 @@
+# @effect-native/libcrsql
+
+[![npm version](https://badge.fury.io/js/%40effect-native%2Flibcrsql.svg)](https://badge.fury.io/js/%40effect-native%2Flibcrsql)
+
+Pure-Nix CR-SQLite extension for conflict-free replicated databases. Just Works™ everywhere - Mac, Linux, Pi, Docker, Vercel, etc.
+
+## What is CR-SQLite?
+
+CR-SQLite is a run-time loadable extension for SQLite that enables Conflict-free Replicated Data Types (CRDTs). It allows you to create tables that can be replicated across multiple devices/servers and automatically merge changes without conflicts.
+
+This package provides pre-built CR-SQLite extensions via Nix, eliminating the need to build from source.
+
+## Installation
+
+```bash
+npm install @effect-native/libcrsql
+```
+
+## Quick Start
+
+```javascript
+import { pathToCRSQLiteExtension } from '@effect-native/libcrsql';
+import Database from 'better-sqlite3';
+
+const db = new Database(':memory:');
+db.loadExtension(pathToCRSQLiteExtension);
+
+// Convert table to conflict-free replicated relation
+db.exec(`
+  CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);
+  SELECT crsql_as_crr('users');
+`);
+
+// Insert data - changes are automatically tracked
+db.exec(`INSERT INTO users (name) VALUES ('Alice')`);
+
+// Get changes for synchronization
+const changes = db.prepare(`SELECT * FROM crsql_changes`).all();
+console.log('Changes to sync:', changes);
+```
+
+## API
+
+### `pathToCRSQLiteExtension`
+
+Path to the CR-SQLite extension file. Use this with your SQLite library's `loadExtension()` method.
+
+```javascript
+import { pathToCRSQLiteExtension } from '@effect-native/libcrsql';
+console.log(pathToCRSQLiteExtension); // /path/to/crsqlite-darwin-aarch64.dylib
+```
+
+### `getExtensionPath()`
+
+Function that returns the path to the CR-SQLite extension.
+
+```javascript
+import { getExtensionPath } from '@effect-native/libcrsql';
+const extensionPath = getExtensionPath();
+```
+
+## CLI Usage
+
+```bash
+npx libcrsql-extension-path
+# /path/to/crsqlite-darwin-aarch64.dylib
+```
+
+## Supported Platforms
+
+- ✅ **macOS** (Intel & Apple Silicon)
+- ✅ **Linux** (x86_64 & ARM64)  
+- ✅ **Docker** containers
+- ✅ **Vercel**, Netlify, Railway
+- ✅ **Raspberry Pi** 4+
+- ✅ **AWS Lambda** (with custom runtime)
+
+## Database Libraries
+
+Works with any SQLite library that supports loading extensions:
+
+### better-sqlite3
+```javascript
+import Database from 'better-sqlite3';
+import { pathToCRSQLiteExtension } from '@effect-native/libcrsql';
+
+const db = new Database('my-app.db');
+db.loadExtension(pathToCRSQLiteExtension);
+```
+
+### sqlite3  
+```javascript
+import sqlite3 from 'sqlite3';
+import { pathToCRSQLiteExtension } from '@effect-native/libcrsql';
+
+const db = new sqlite3.Database('my-app.db');
+db.loadExtension(pathToCRSQLiteExtension);
+```
+
+### Bun SQLite
+```javascript
+import { Database } from 'bun:sqlite';
+import { pathToCRSQLiteExtension } from '@effect-native/libcrsql';
+
+const db = new Database('my-app.db');
+db.loadExtension(pathToCRSQLiteExtension);
+```
+
+## React Native
+
+This package is for **Node.js/Bun server environments only**. For React Native, use:
+
+- [@op-engineering/op-sqlite](https://www.npmjs.com/package/@op-engineering/op-sqlite)
+- [expo-sqlite](https://docs.expo.dev/versions/latest/sdk/sqlite/)
+
+## CR-SQLite Functions
+
+Once loaded, CR-SQLite provides these functions:
+
+- `crsql_as_crr(table_name)` - Convert table to conflict-free replicated relation
+- `crsql_version()` - Get CR-SQLite version
+- `crsql_changes` - Virtual table containing changes for sync
+- `crsql_begin_alter(table_name)` - Begin schema changes
+- `crsql_commit_alter(table_name)` - Commit schema changes
+
+See [CR-SQLite Documentation](https://vlcn.io/docs/cr-sqlite/intro) for complete API reference.
+
+## Development
+
+### Prerequisites
+- [Nix](https://nixos.org/download.html) package manager
+- Node.js 16+
+
+### Building
+
+```bash
+# Build CR-SQLite extensions for all platforms
+npm run bundle-lib
+
+# Build production package
+npm run build-production
+
+# Run tests
+npm test
+npm run test:docker
+```
+
+## Troubleshooting
+
+### "Extension not found" Error
+
+```bash
+# Check what platforms are available
+npm list @effect-native/libcrsql
+ls node_modules/@effect-native/libcrsql/lib/
+
+# Get extension path for debugging  
+npx libcrsql-extension-path
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch: `git checkout -b my-feature`
+3. Make your changes and run tests: `npm test`
+4. Submit a pull request
+
+## License
+
+MIT
+
+## Related
+
+- [CR-SQLite](https://github.com/vlcn-io/cr-sqlite) - The upstream CR-SQLite project
+- [@effect-native/libsqlite](https://github.com/effect-native/libsqlite) - Nix-built SQLite library
+- [vlcn.io](https://vlcn.io) - CR-SQLite documentation and tools

package/bin/libcrsql-extension-path.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { pathToCRSQLiteExtension } from '../index.js';
+
+try {
+  console.log(pathToCRSQLiteExtension);
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Get the absolute path to the bundled CR-SQLite extension
+ * @returns Absolute path to crsqlite.dylib/.so
+ */
+export declare function getExtensionPath(): string;
+
+/**
+ * Path to CR-SQLite extension - for use with db.loadExtension()
+ */
+export declare const pathToCRSQLiteExtension: string;
+
+/**
+ * Default export - same as pathToCRSQLiteExtension
+ */
+declare const _default: string;
+export default _default;

package/index.js

@@ -0,0 +1,67 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Get the absolute path to the bundled CR-SQLite extension
+ * Automatically detects platform and architecture
+ * @returns {string} Absolute path to crsqlite.dylib/.so
+ */
+export function getExtensionPath() {
+  // Browser check - prevent misuse in browsers
+  if (typeof window !== 'undefined') {
+    throw new Error(
+      '@effect-native/libcrsql is for Node.js server environments only. ' +
+      'For browsers, use sql.js or a server-side database API.'
+    );
+  }
+
+  // Detect current platform and architecture
+  const platform = process.platform === 'darwin' ? 'darwin' : 'linux';
+  const arch = process.arch === 'arm64' ? 'aarch64' : 'x86_64';
+  const ext = platform === 'darwin' ? 'dylib' : 'so';
+
+  const libDir = resolve(__dirname, 'lib');
+
+  // Try platform-specific extension first (highest priority)
+  const specificExt = resolve(libDir, `crsqlite-${platform}-${arch}.${ext}`);
+  if (existsSync(specificExt)) {
+    return specificExt;
+  }
+
+  // Fallback to any available extension for the current platform
+  const fallbackCandidates = [
+    resolve(libDir, `crsqlite.${ext}`),        // Generic for platform
+    resolve(libDir, 'crsqlite.dylib'),         // macOS generic
+    resolve(libDir, 'crsqlite.so'),            // Linux generic
+  ];
+
+  for (const candidate of fallbackCandidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  // Helpful error message with available platforms
+  const availablePlatforms = [];
+  const expectedExt = `crsqlite-${platform}-${arch}.${ext}`;
+  throw new Error(
+    `CR-SQLite extension not found for ${platform}/${arch}. ` +
+    `Expected: ${expectedExt}. ` +
+    `Available platforms: ${availablePlatforms.join(', ')}. ` +
+    `This package supports: Intel/AMD Linux (Docker, most servers), ARM64 Linux (Raspberry Pi 4+, AWS Graviton), Intel Mac, Apple Silicon Mac (M1/M2/M3)`
+  );
+}
+
+/**
+ * Path to CR-SQLite extension - for use with db.loadExtension()
+ * Automatically detects your platform and returns the right extension
+ */
+export const pathToCRSQLiteExtension = getExtensionPath();
+
+/**
+ * Default export - same as pathToCRSQLiteExtension
+ */
+export default pathToCRSQLiteExtension;

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@effect-native/libcrsql",
+  "version": "0.16.3-1",
+  "description": "Pure-Nix CR-SQLite extension (.dylib/.so) for conflict-free replicated databases",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "react-native": "./react-native.js",
+      "default": "./index.js"
+    },
+    "./react-native": {
+      "import": "./react-native.js",
+      "types": "./react-native.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {},
+  "bin": {
+    "@effect-native/libcrsql": "./bin/libcrsql-extension-path.js",
+    "libcrsql-extension-path": "./bin/libcrsql-extension-path.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "react-native.js",
+    "react-native.d.ts",
+    "lib/",
+    "bin/",
+    "README.md"
+  ],
+  "keywords": [
+    "sqlite",
+    "sqlite3",
+    "cr-sqlite",
+    "crsqlite",
+    "crdt",
+    "conflict-free",
+    "replicated",
+    "extension",
+    "nix",
+    "dylib",
+    "shared-library"
+  ],
+  "author": "Tom Aylott",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/effect-native/cr-sqlite.git"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "peerDependencies": {},
+  "dependencies": {},
+  "devDependencies": {
+    "@effect-native/libsqlite": "^3.50.2-1",
+    "@effect/platform": "^0.66.3",
+    "@effect/platform-bun": "^0.46.0",
+    "@types/bun": "latest",
+    "@types/node": "^22.0.0",
+    "effect": "^3.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/react-native.d.ts

@@ -0,0 +1,13 @@
+/**
+ * React Native placeholder for getExtensionPath
+ * @throws Always throws with helpful message for React Native users
+ */
+export declare function getExtensionPath(): never;
+
+/**
+ * React Native placeholder for pathToCRSQLiteExtension
+ * @throws Always throws with helpful message for React Native users
+ */
+export declare const pathToCRSQLiteExtension: never;
+
+export default pathToCRSQLiteExtension;

package/react-native.js

@@ -0,0 +1,32 @@
+// React Native specific entry point
+// CR-SQLite extensions don't work in React Native
+
+/**
+ * React Native placeholder for getExtensionPath
+ * @throws Always throws with helpful message for React Native users
+ */
+export function getExtensionPath() {
+  throw new Error(
+    '\u{1f6ab} @effect-native/libcrsql is for Node.js / Bun server environments only.\n\n' +
+    '\u{1f4f1} For React Native, use one of these instead:\n' +
+    '  \u2022 @op-engineering/op-sqlite: https://www.npmjs.com/package/@op-engineering/op-sqlite\n' +
+    '  \u2022 expo-sqlite: https://docs.expo.dev/versions/latest/sdk/sqlite/\n' +
+    '\u{1f4a1} This package provides native CR-SQLite extensions for Node.js / Bun servers, not mobile apps.'
+  );
+}
+
+/**
+ * React Native placeholder for pathToCRSQLiteExtension
+ * @throws Always throws with helpful message
+ */
+export const pathToCRSQLiteExtension = (() => {
+  throw new Error(
+    '\u{1f6ab} @effect-native/libcrsql is for Node.js / Bun server environments only.\n\n' +
+    '\u{1f4f1} For React Native, use one of these instead:\n' +
+    '  \u2022 @op-engineering/op-sqlite: https://www.npmjs.com/package/@op-engineering/op-sqlite\n' +
+    '  \u2022 expo-sqlite: https://docs.expo.dev/versions/latest/sdk/sqlite/\n' +
+    '\u{1f4a1} This package provides native CR-SQLite extensions for Node.js / Bun servers, not mobile apps.'
+  );
+})();
+
+export default pathToCRSQLiteExtension;