@missionmind/sync-api 0.0.0 → 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Rows deleted from the tables the app pulls by cursor, written by a trigger
+ * (`syncTriggersSql`) so that cascades are recorded too. No foreign key to
+ * the users table, which is the app's: the trigger writes none for a row
+ * deleted with its account.
+ */
+export declare const syncTombstones: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "sync_tombstones";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "sync_tombstones";
+            dataType: "number";
+            columnType: "PgBigSerial53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        userId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "userId";
+            tableName: "sync_tombstones";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 255;
+        }>;
+        tableName: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tableName";
+            tableName: "sync_tombstones";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 64;
+        }>;
+        rowId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "rowId";
+            tableName: "sync_tombstones";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 255;
+        }>;
+        deletedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "deletedAt";
+            tableName: "sync_tombstones";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiB1B,CAAC"}

package/dist/schema.js

@@ -0,0 +1,18 @@
+import { sql } from "drizzle-orm";
+import { bigserial, index, pgTable, timestamp, varchar, } from "drizzle-orm/pg-core";
+/**
+ * Rows deleted from the tables the app pulls by cursor, written by a trigger
+ * (`syncTriggersSql`) so that cascades are recorded too. No foreign key to
+ * the users table, which is the app's: the trigger writes none for a row
+ * deleted with its account.
+ */
+export const syncTombstones = pgTable("sync_tombstones", {
+    id: bigserial({ mode: "number" }).primaryKey(),
+    userId: varchar({ length: 255 }).notNull(),
+    tableName: varchar({ length: 64 }).notNull(),
+    rowId: varchar({ length: 255 }).notNull(),
+    deletedAt: timestamp({ withTimezone: true }).notNull().default(sql `now()`),
+}, (table) => [
+    index("syncTombstones_sync_idx").on(table.userId, table.tableName, table.deletedAt, table.id),
+]);
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EACL,SAAS,EACT,KAAK,EACL,OAAO,EACP,SAAS,EACT,OAAO,GACR,MAAM,qBAAqB,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CACnC,iBAAiB,EACjB;IACE,EAAE,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,UAAU,EAAE;IAC9C,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,OAAO,EAAE;IAC1C,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE;IAC5C,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,OAAO,EAAE;IACzC,SAAS,EAAE,SAAS,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,CAAA,OAAO,CAAC;CAC3E,EACD,CAAC,KAAK,EAAE,EAAE,CAAC;IACT,KAAK,CAAC,yBAAyB,CAAC,CAAC,EAAE,CACjC,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,SAAS,EACf,KAAK,CAAC,SAAS,EACf,KAAK,CAAC,EAAE,CACT;CACF,CACF,CAAC"}

package/dist/triggers.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The SQL that keeps the tables an app pulls by cursor ready for it: each
+ * write stamps the row's "updatedAt", and each deletion records a tombstone
+ * in `sync_tombstones`. Run it in a migration, after the tables and
+ * `sync_tombstones` exist, and again whenever a pulled table is added; it can
+ * be run more than once.
+ *
+ * Inserts are stamped too: a row restored or imported with an old
+ * "updatedAt" would otherwise sit behind every cursor.
+ *
+ * Triggers rather than application code, so that every write counts: foreign
+ * keys' ON DELETE SET NULL / CASCADE, scripts, and upserts whose conflict
+ * branch Drizzle does not stamp.
+ */
+export declare function syncTriggersSql(options: {
+    /** The pulled tables, by their SQL names. */
+    tables: string[];
+    /**
+     * The table of users, by its SQL name (Better Auth's is "user"). A row
+     * deleted with its user leaves no tombstone: nobody will pull it.
+     */
+    usersTable: string;
+}): string;
+//# sourceMappingURL=triggers.d.ts.map

package/dist/triggers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../src/triggers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,6CAA6C;IAC7C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB,UAiDA"}

package/dist/triggers.js

@@ -0,0 +1,71 @@
+/**
+ * The SQL that keeps the tables an app pulls by cursor ready for it: each
+ * write stamps the row's "updatedAt", and each deletion records a tombstone
+ * in `sync_tombstones`. Run it in a migration, after the tables and
+ * `sync_tombstones` exist, and again whenever a pulled table is added; it can
+ * be run more than once.
+ *
+ * Inserts are stamped too: a row restored or imported with an old
+ * "updatedAt" would otherwise sit behind every cursor.
+ *
+ * Triggers rather than application code, so that every write counts: foreign
+ * keys' ON DELETE SET NULL / CASCADE, scripts, and upserts whose conflict
+ * branch Drizzle does not stamp.
+ */
+export function syncTriggersSql(options) {
+    const tables = options.tables.map((table) => quoteLiteral(table)).join(", ");
+    const usersTable = quoteIdentifier(options.usersTable);
+    return `BEGIN;
+
+-- A row inserted again under a deleted id (a restore) must not be deleted
+-- again by its old tombstone on a device pulling both for the first time.
+CREATE OR REPLACE FUNCTION sync_touch_updated_at() RETURNS trigger AS $$
+BEGIN
+  NEW."updatedAt" := now();
+  IF TG_OP = 'INSERT' THEN
+    DELETE FROM sync_tombstones
+    WHERE "tableName" = TG_TABLE_NAME AND "rowId" = NEW.id;
+  END IF;
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Rows removed with their user leave no tombstone: nobody will pull them.
+CREATE OR REPLACE FUNCTION sync_record_tombstone() RETURNS trigger AS $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM ${usersTable} WHERE id = OLD."userId") THEN
+    INSERT INTO sync_tombstones ("userId", "tableName", "rowId")
+    VALUES (OLD."userId", TG_TABLE_NAME, OLD.id);
+  END IF;
+  RETURN OLD;
+END;
+$$ LANGUAGE plpgsql;
+
+DO $$
+DECLARE
+  t text;
+BEGIN
+  FOREACH t IN ARRAY ARRAY[${tables}]
+  LOOP
+    EXECUTE format('DROP TRIGGER IF EXISTS sync_touch_updated_at ON %I', t);
+    EXECUTE format(
+      'CREATE TRIGGER sync_touch_updated_at BEFORE INSERT OR UPDATE ON %I
+         FOR EACH ROW EXECUTE FUNCTION sync_touch_updated_at()', t);
+    EXECUTE format('DROP TRIGGER IF EXISTS sync_record_tombstone ON %I', t);
+    EXECUTE format(
+      'CREATE TRIGGER sync_record_tombstone AFTER DELETE ON %I
+         FOR EACH ROW EXECUTE FUNCTION sync_record_tombstone()', t);
+  END LOOP;
+END;
+$$;
+
+COMMIT;
+`;
+}
+function quoteLiteral(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function quoteIdentifier(value) {
+    return `"${value.replaceAll('"', '""')}"`;
+}
+//# sourceMappingURL=triggers.js.map

package/dist/triggers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"triggers.js","sourceRoot":"","sources":["../src/triggers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,OAQ/B;IACC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7E,MAAM,UAAU,GAAG,eAAe,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACvD,OAAO;;;;;;;;;;;;;;;;;;6BAkBoB,UAAU;;;;;;;;;;;;6BAYV,MAAM;;;;;;;;;;;;;;;CAelC,CAAC;AACF,CAAC;AAED,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;AAC5C,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;AAC5C,CAAC"}

package/package.json

@@ -1 +1,41 @@
-{"name":"@missionmind/sync-api","version":"0.0.0","description":"Placeholder: the first release is 0.1.0","license":"MIT"}
+{
+  "name": "@missionmind/sync-api",
+  "version": "0.1.0",
+  "description": "Server side of an offline-first app: applies the changes a device uploads, and serves its pulls by cursor (rows and tombstones) on Drizzle Postgres.",
+  "license": "MIT",
+  "author": "MissionMind",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "default": "./dist/schema.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "types:check": "tsc --noEmit",
+    "prepack": "node ../../scripts/package-manifest.mjs prepack",
+    "postpack": "node ../../scripts/package-manifest.mjs postpack"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "^0.45.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "drizzle-orm": "0.45.2",
+    "typescript": "6.0.3",
+    "zod": "4.4.3"
+  }
+}

package/src/changes.ts

@@ -0,0 +1,117 @@
+import z from "zod";
+
+/**
+ * A change the app queued: a whole row to create or replace, or a deletion.
+ * The endpoints take them in batches and answer with the ones they refused.
+ */
+export const syncChangeSchema = z.object({
+  id: z.string(),
+  operation: z.enum(["PUT", "DELETE"]),
+  data: z.record(z.string(), z.unknown()).nullable(),
+});
+
+export type SyncChange = z.infer<typeof syncChangeSchema>;
+
+/** A change the server refused for good; sending it again cannot help. */
+export interface RejectedChange {
+  id: string;
+  reason: string;
+}
+
+export interface TableSync<TInsert> {
+  allowedKeys: string[];
+  insertSchema: z.ZodType<TInsert>;
+  name: string;
+  ownerOf: (id: string) => Promise<string | undefined>;
+  /** Turns the app's stored values (ISO strings) into the column types. */
+  prepare?: (data: Record<string, unknown>) => void;
+  remove: (id: string, userId: string) => Promise<unknown>;
+  upsert: (id: string, userId: string, data: TInsert) => Promise<unknown>;
+}
+
+/**
+ * Applies the app's changes to one table. A change the server refuses
+ * (invalid data, a row of another user, a broken reference) is skipped and
+ * returned, so the app can put the server's version back; the rest of the
+ * batch still goes through. Any other failure throws, and the app sends the
+ * batch again.
+ */
+export async function applyChanges<TInsert>(
+  userId: string,
+  changes: SyncChange[],
+  sync: TableSync<TInsert>
+): Promise<RejectedChange[]> {
+  const rejected: RejectedChange[] = [];
+  const reject = (id: string, reason: string) => {
+    console.error(`[sync] SYNC_REJECTED ${sync.name} ${id}: ${reason}`);
+    rejected.push({ id, reason });
+  };
+
+  for (const change of changes) {
+    try {
+      if (change.operation === "DELETE") {
+        await sync.remove(change.id, userId);
+        continue;
+      }
+
+      const data = Object.fromEntries(
+        Object.entries(change.data ?? {}).filter(([key]) =>
+          sync.allowedKeys.includes(key)
+        )
+      );
+      if (Object.keys(data).length === 0) {
+        continue;
+      }
+      sync.prepare?.(data);
+
+      const parsed = sync.insertSchema.safeParse(data);
+      if (!parsed.success) {
+        reject(change.id, `INVALID_DATA: ${describeIssues(parsed.error)}`);
+        continue;
+      }
+      const owner = await sync.ownerOf(change.id);
+      if (owner && owner !== userId) {
+        reject(change.id, "NOT_OWNED");
+        continue;
+      }
+      await sync.upsert(change.id, userId, parsed.data);
+    } catch (error) {
+      // A broken reference or a value the column refuses is the change's own
+      // fault; anything else (the connection, a timeout) deserves a retry.
+      const code = postgresErrorCode(error);
+      if (code?.startsWith("23") || code?.startsWith("22")) {
+        reject(change.id, `CONSTRAINT: ${code}`);
+        continue;
+      }
+      throw error;
+    }
+  }
+  return rejected;
+}
+
+function describeIssues(error: z.ZodError) {
+  return error.issues
+    .map((issue) => `${issue.path.join(".")} ${issue.message}`)
+    .join("; ");
+}
+
+const SQLSTATE = /^[0-9A-Z]{5}$/;
+
+/** Drizzle wraps the driver's error; the SQLSTATE is on its cause. */
+function postgresErrorCode(error: unknown): string | undefined {
+  for (let current = error; current; ) {
+    if (
+      typeof current === "object" &&
+      "code" in current &&
+      typeof current.code === "string" &&
+      SQLSTATE.test(current.code)
+    ) {
+      return current.code;
+    }
+    current =
+      typeof current === "object" && "cause" in current
+        ? current.cause
+        : undefined;
+  }
+  return;
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/** biome-ignore-all lint/performance/noBarrelFile: the package's entry point */
+export {
+  applyChanges,
+  type RejectedChange,
+  type SyncChange,
+  syncChangeSchema,
+  type TableSync,
+} from "./changes.js";
+export {
+  type ChangesPage,
+  createSyncPull,
+  type PulledRow,
+  type PulledServerTable,
+  type SyncDatabase,
+  type SyncPullOptions,
+  type WholeTableReader,
+} from "./pull.js";
+export { createSyncPushMessage, type SyncPushMessage } from "./push.js";
+export { syncTriggersSql } from "./triggers.js";