@rific/sync 0.1.2

package/README.md

@@ -0,0 +1,117 @@
+# @rific/sync
+
+A generic SQLite sync engine for Expo. Handles schema management, upsert/delete, and cursor-based sync state — so you can focus on fetching data, not wiring up tables.
+
+Works with `expo-sqlite`'s `SQLiteDatabase` out of the box.
+
+## Installation
+
+```sh
+npm install @rific/sync
+```
+
+## Usage
+
+```ts
+import * as SQLite from 'expo-sqlite'
+import { SyncEngine } from '@rific/sync'
+
+const db = await SQLite.openDatabaseAsync('my.db')
+
+const sync = new SyncEngine(db)
+
+sync.register({
+  name: 'products',
+  schema: {
+    id: 'TEXT',
+    name: 'TEXT',
+    price: 'REAL',
+    stock: 'INTEGER',
+  },
+  primaryKey: 'id',
+})
+
+// Creates _sync_state and all registered tables (safe to call on every launch)
+await sync.init()
+```
+
+### Syncing records
+
+```ts
+// Fetch from your API, using the last cursor to get only new changes
+const cursor = await sync.getCursor('products')
+const { records, nextCursor } = await fetchProducts({ since: cursor })
+
+for (const record of records) {
+  if (record.deleted) {
+    await sync.remove('products', record.id)
+  } else {
+    await sync.push('products', record)
+  }
+}
+
+await sync.setCursor('products', nextCursor)
+```
+
+### Transforming records
+
+Use `transform` to reshape API responses before they hit SQLite:
+
+```ts
+sync.register({
+  name: 'orders',
+  schema: {
+    id: 'TEXT',
+    customer_id: 'TEXT',
+    total: 'REAL',
+    placed_at: 'TEXT',
+  },
+  transform: (record: ApiOrder) => ({
+    id: record.id,
+    customer_id: record.customerId,
+    total: record.total,
+    placed_at: record.placedAt,
+  }),
+})
+```
+
+## API
+
+### `new SyncEngine(db)`
+
+Creates a sync engine. `db` must satisfy the `Database` interface (automatically satisfied by `expo-sqlite`'s `SQLiteDatabase`).
+
+### `.register(config)`
+
+Registers a channel (table). Returns `this` for chaining.
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Table name in SQLite |
+| `schema` | `Record<string, ColumnType>` | Column definitions |
+| `primaryKey` | `string` | Primary key column. Defaults to `'id'` |
+| `transform` | `(record: TRecord) => TRow \| Promise<TRow>` | Optional transform before write |
+
+### `.init()`
+
+Creates `_sync_state` and all registered tables if they don't exist. Safe to call on every app launch.
+
+### `.push(name, record)`
+
+Upserts a record into the named channel's table.
+
+### `.remove(name, id)`
+
+Deletes a record by primary key from the named channel's table.
+
+### `.getCursor(name)`
+
+Returns the last saved cursor for a channel, or `null` if none exists.
+
+### `.setCursor(name, cursor)`
+
+Saves a cursor for a channel along with a `syncedAt` timestamp.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,33 @@
+type SQLiteValue = string | number | null;
+type ColumnType = 'TEXT' | 'INTEGER' | 'REAL' | 'BLOB';
+/** Minimal database interface — satisfied by expo-sqlite's SQLiteDatabase out of the box. */
+interface Database {
+    execAsync(source: string): Promise<void>;
+    runAsync(source: string, params: SQLiteValue[]): Promise<unknown>;
+    getFirstAsync<T>(source: string, params: SQLiteValue[]): Promise<T | null>;
+}
+interface ChannelConfig<TRecord = unknown, TRow extends Record<string, SQLiteValue> = Record<string, SQLiteValue>> {
+    /** Table name in SQLite. */
+    name: string;
+    /** Column definitions: key = column name, value = SQLite type. */
+    schema: Record<string, ColumnType>;
+    /** Column used as the primary key. Defaults to 'id'. */
+    primaryKey?: string;
+    /** Optional transform applied to each record before it is written to SQLite. */
+    transform?: (record: TRecord) => TRow | Promise<TRow>;
+}
+
+declare class SyncEngine {
+    private readonly db;
+    private readonly channels;
+    constructor(db: Database);
+    register<TRecord, TRow extends Record<string, SQLiteValue>>(config: ChannelConfig<TRecord, TRow>): this;
+    init(): Promise<void>;
+    push<TRecord>(name: string, record: TRecord): Promise<void>;
+    remove(name: string, id: SQLiteValue): Promise<void>;
+    getCursor(name: string): Promise<string | null>;
+    setCursor(name: string, cursor: string): Promise<void>;
+    private requireChannel;
+}
+
+export { type ChannelConfig, type ColumnType, type Database, type SQLiteValue, SyncEngine };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+type SQLiteValue = string | number | null;
+type ColumnType = 'TEXT' | 'INTEGER' | 'REAL' | 'BLOB';
+/** Minimal database interface — satisfied by expo-sqlite's SQLiteDatabase out of the box. */
+interface Database {
+    execAsync(source: string): Promise<void>;
+    runAsync(source: string, params: SQLiteValue[]): Promise<unknown>;
+    getFirstAsync<T>(source: string, params: SQLiteValue[]): Promise<T | null>;
+}
+interface ChannelConfig<TRecord = unknown, TRow extends Record<string, SQLiteValue> = Record<string, SQLiteValue>> {
+    /** Table name in SQLite. */
+    name: string;
+    /** Column definitions: key = column name, value = SQLite type. */
+    schema: Record<string, ColumnType>;
+    /** Column used as the primary key. Defaults to 'id'. */
+    primaryKey?: string;
+    /** Optional transform applied to each record before it is written to SQLite. */
+    transform?: (record: TRecord) => TRow | Promise<TRow>;
+}
+
+declare class SyncEngine {
+    private readonly db;
+    private readonly channels;
+    constructor(db: Database);
+    register<TRecord, TRow extends Record<string, SQLiteValue>>(config: ChannelConfig<TRecord, TRow>): this;
+    init(): Promise<void>;
+    push<TRecord>(name: string, record: TRecord): Promise<void>;
+    remove(name: string, id: SQLiteValue): Promise<void>;
+    getCursor(name: string): Promise<string | null>;
+    setCursor(name: string, cursor: string): Promise<void>;
+    private requireChannel;
+}
+
+export { type ChannelConfig, type ColumnType, type Database, type SQLiteValue, SyncEngine };

package/dist/index.js

@@ -0,0 +1,73 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SyncEngine: () => SyncEngine
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/SyncEngine.ts
+var SyncEngine = class {
+  constructor(db) {
+    this.channels = /* @__PURE__ */ new Map();
+    this.db = db;
+  }
+  register(config) {
+    this.channels.set(config.name, config);
+    return this;
+  }
+  async init() {
+    await this.db.execAsync(`CREATE TABLE IF NOT EXISTS _sync_state (channel TEXT PRIMARY KEY, cursor TEXT, syncedAt TEXT)`);
+    for (const [, channel] of this.channels) {
+      const pk = channel.primaryKey ?? "id";
+      const cols = Object.entries(channel.schema).map(([col, type]) => `${col} ${type}${col === pk ? " PRIMARY KEY" : ""}`).join(", ");
+      await this.db.execAsync(`CREATE TABLE IF NOT EXISTS ${channel.name} (${cols})`);
+    }
+  }
+  async push(name, record) {
+    const channel = this.requireChannel(name);
+    const row = channel.transform ? await channel.transform(record) : record;
+    const cols = Object.keys(row);
+    const values = cols.map((k) => row[k]);
+    await this.db.runAsync(`INSERT OR REPLACE INTO ${name} (${cols.join(", ")}) VALUES (${cols.map(() => "?").join(", ")})`, values);
+  }
+  async remove(name, id) {
+    const channel = this.requireChannel(name);
+    const pk = channel.primaryKey ?? "id";
+    await this.db.runAsync(`DELETE FROM ${name} WHERE ${pk} = ?`, [id]);
+  }
+  async getCursor(name) {
+    const row = await this.db.getFirstAsync(`SELECT cursor FROM _sync_state WHERE channel = ?`, [name]);
+    return row?.cursor ?? null;
+  }
+  async setCursor(name, cursor) {
+    await this.db.runAsync(`INSERT OR REPLACE INTO _sync_state (channel, cursor, syncedAt) VALUES (?, ?, ?)`, [name, cursor, (/* @__PURE__ */ new Date()).toISOString()]);
+  }
+  requireChannel(name) {
+    const channel = this.channels.get(name);
+    if (!channel) throw new Error(`[expo-sync] Unknown channel: "${name}"`);
+    return channel;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SyncEngine
+});

package/dist/index.mjs

@@ -0,0 +1,46 @@
+// src/SyncEngine.ts
+var SyncEngine = class {
+  constructor(db) {
+    this.channels = /* @__PURE__ */ new Map();
+    this.db = db;
+  }
+  register(config) {
+    this.channels.set(config.name, config);
+    return this;
+  }
+  async init() {
+    await this.db.execAsync(`CREATE TABLE IF NOT EXISTS _sync_state (channel TEXT PRIMARY KEY, cursor TEXT, syncedAt TEXT)`);
+    for (const [, channel] of this.channels) {
+      const pk = channel.primaryKey ?? "id";
+      const cols = Object.entries(channel.schema).map(([col, type]) => `${col} ${type}${col === pk ? " PRIMARY KEY" : ""}`).join(", ");
+      await this.db.execAsync(`CREATE TABLE IF NOT EXISTS ${channel.name} (${cols})`);
+    }
+  }
+  async push(name, record) {
+    const channel = this.requireChannel(name);
+    const row = channel.transform ? await channel.transform(record) : record;
+    const cols = Object.keys(row);
+    const values = cols.map((k) => row[k]);
+    await this.db.runAsync(`INSERT OR REPLACE INTO ${name} (${cols.join(", ")}) VALUES (${cols.map(() => "?").join(", ")})`, values);
+  }
+  async remove(name, id) {
+    const channel = this.requireChannel(name);
+    const pk = channel.primaryKey ?? "id";
+    await this.db.runAsync(`DELETE FROM ${name} WHERE ${pk} = ?`, [id]);
+  }
+  async getCursor(name) {
+    const row = await this.db.getFirstAsync(`SELECT cursor FROM _sync_state WHERE channel = ?`, [name]);
+    return row?.cursor ?? null;
+  }
+  async setCursor(name, cursor) {
+    await this.db.runAsync(`INSERT OR REPLACE INTO _sync_state (channel, cursor, syncedAt) VALUES (?, ?, ?)`, [name, cursor, (/* @__PURE__ */ new Date()).toISOString()]);
+  }
+  requireChannel(name) {
+    const channel = this.channels.get(name);
+    if (!channel) throw new Error(`[expo-sync] Unknown channel: "${name}"`);
+    return channel;
+  }
+};
+export {
+  SyncEngine
+};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@rific/sync",
+  "version": "0.1.2",
+  "description": "Generic SQLite sync engine for Expo — schema management, upsert/delete, and cursor state persistence",
+  "keywords": [
+    "expo",
+    "sqlite",
+    "sync",
+    "offline-first",
+    "expo-sqlite"
+  ],
+  "homepage": "https://github.com/jayrdeaton/Expo-Sync#readme",
+  "bugs": {
+    "url": "https://github.com/jayrdeaton/Expo-Sync/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jayrdeaton/Expo-Sync.git"
+  },
+  "license": "MIT",
+  "author": "Jay Deaton",
+  "sideEffects": false,
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "fix": "eslint --fix",
+    "lint": "eslint",
+    "prepublishOnly": "npm run build",
+    "release": "git push --follow-tags",
+    "release:major": "npm version major && git push --follow-tags",
+    "release:minor": "npm version minor && git push --follow-tags",
+    "release:patch": "npm version patch && git push --follow-tags",
+    "test": "jest",
+    "test:watch": "jest --watchAll",
+    "typecheck": "tsc --noEmit",
+    "preversion": "npm run lint && npm test"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@typescript-eslint/parser": "^8.59.3",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-package-json": "^1.0.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-simple-import-sort": "^13.0.0",
+    "jest": "^30.4.2",
+    "prettier": "^3.8.3",
+    "ts-jest": "^29.4.9",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.59.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}