@farm.js/sync 0.1.0-beta.1

package/dist/index.js

@@ -0,0 +1,201 @@
+import { declareSchemaTables, definePlugin } from "@farm.js/core";
+import { executeSyncOperation, SyncOperationError } from "./server.js";
+import { resolveSyncModels, } from "./types.js";
+const DEFAULT_PATH = "/_farm/sync";
+export function sync(options) {
+    if (!options?.schema?.models) {
+        throw new TypeError("sync() requires a `schema` created with defineSchema().");
+    }
+    const path = options.path ?? DEFAULT_PATH;
+    const models = resolveSyncModels(options.schema, options.models, options.where, options.persist ?? true);
+    if (models.size === 0) {
+        throw new Error("sync(): no models are exposed. Add at least one entry to `models`.");
+    }
+    let ormPromise;
+    const resolveOrm = () => {
+        ormPromise ??= resolveSyncClient(options, models);
+        return ormPromise;
+    };
+    const plugin = definePlugin({
+        name: "farm:sync",
+        client: {
+            // Serializable descriptor the browser runtime reads at startup.
+            public: {
+                path,
+                models: Object.fromEntries(Array.from(models.values(), (model) => [
+                    model.name,
+                    {
+                        key: model.key,
+                        access: model.access,
+                        persist: model.persist,
+                        cursor: model.cursorField ?? null,
+                    },
+                ])),
+            },
+            setup({ public: config }) {
+                // Hand the descriptor to the runtime, which the app bundle imports.
+                const scope = globalThis;
+                scope.__FARM_SYNC_CONFIG__ = config;
+                scope.__FARM_SYNC__?.start?.(config);
+            },
+        },
+        async beforeRequest(req, res) {
+            const pathname = (req.url ?? "").split("?")[0];
+            if (pathname !== path)
+                return;
+            if (req.method !== "POST") {
+                sendJson(res, 405, { error: { code: "invalid_input", message: "Sync uses POST." } });
+                return;
+            }
+            let body;
+            try {
+                body = await readJsonBody(req);
+            }
+            catch {
+                sendJson(res, 400, {
+                    error: { code: "invalid_input", message: "Request body must be JSON." },
+                });
+                return;
+            }
+            if (!body || typeof body.model !== "string" || typeof body.operation !== "string") {
+                sendJson(res, 400, {
+                    error: { code: "invalid_input", message: "Request body needs `model` and `operation`." },
+                });
+                return;
+            }
+            // The operation layer works in web-standard terms, so adapt once here.
+            const request = toWebRequest(req, path);
+            try {
+                const context = await runMiddleware(options.middleware, request);
+                const orm = await resolveOrm();
+                const result = await executeSyncOperation({ body, models, orm, request, context });
+                sendJson(res, 200, result);
+            }
+            catch (error) {
+                if (error instanceof SyncOperationError) {
+                    sendJson(res, error.status, { error: { code: error.code, message: error.message } });
+                    return;
+                }
+                // Never leak an internal message to the browser.
+                console.error("[farm:sync] operation failed", error);
+                sendJson(res, 500, {
+                    error: { code: "server_error", message: "The sync operation failed." },
+                });
+            }
+        },
+    });
+    // Declare the tables sync owns, so `farm sync migrate` can create them
+    // without re-reading or re-validating configuration.
+    return declareSchemaTables(plugin, {
+        name: "sync",
+        schema: options.schema,
+        // A model the app has not opened to the browser is not sync's to create.
+        models: Array.from(models.keys()),
+        dialect: options.dialect,
+        resolveClient: async () => {
+            if (options.client) {
+                return typeof options.client === "function"
+                    ? await options.client()
+                    : options.client;
+            }
+            if (options.storage) {
+                const { getStorage } = await import("@farm.js/core/storage");
+                return getStorage(options.storage);
+            }
+            return undefined;
+        },
+    });
+}
+async function runMiddleware(middleware, request) {
+    let context = {};
+    for (const entry of middleware ?? []) {
+        const produced = await entry({ request, context });
+        if (produced)
+            context = { ...context, ...produced };
+    }
+    return context;
+}
+async function resolveSyncClient(options, models) {
+    if (options.client) {
+        const provided = typeof options.client === "function"
+            ? await options.client()
+            : options.client;
+        // Already model-shaped: an @farming-labs/orm client, or anything exposing
+        // the same four methods. Use it directly.
+        if (isModelClient(provided, models))
+            return provided;
+        return buildOrm(options.schema, provided);
+    }
+    if (options.storage) {
+        const mount = options.storage;
+        // Imported lazily so the storage runtime never reaches a browser bundle.
+        const { getStorage } = await import("@farm.js/core/storage");
+        // A mount is an unstorage instance, which the orm runtime drives like any
+        // other backend — so this is the same code path as a real database.
+        return buildOrm(options.schema, getStorage(mount));
+    }
+    throw new Error("sync(): no data source is configured. Set `storage` to a mount name from " +
+        "storage.mounts in farm.config.ts, or pass `client` with your database connection.");
+}
+/** Let the orm runtime detect the driver and build the model client. */
+async function buildOrm(schema, client) {
+    const { createIntegrationOrm } = await import("@farm.js/core");
+    return (await createIntegrationOrm({ schema, client }));
+}
+/**
+ * Write a JSON response using the Node primitives every Farm runtime provides.
+ * The richer `res.status().json()` helpers are not present on every path.
+ */
+function sendJson(res, status, payload) {
+    if (typeof res.writeHead === "function") {
+        res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify(payload));
+        return;
+    }
+    res.statusCode = status;
+    res.setHeader?.("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(payload));
+}
+/** True when every exposed model is already reachable with the methods sync calls. */
+function isModelClient(value, models) {
+    if (!value || typeof value !== "object")
+        return false;
+    for (const name of models.keys()) {
+        const model = value[name];
+        if (!model || typeof model !== "object")
+            return false;
+        if (typeof model.findMany !== "function" || typeof model.create !== "function")
+            return false;
+    }
+    return true;
+}
+/** Read and parse a JSON body, tolerating a body already parsed upstream. */
+async function readJsonBody(req) {
+    if (req.body && typeof req.body === "object")
+        return req.body;
+    if (typeof req.body === "string")
+        return JSON.parse(req.body);
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    const raw = Buffer.concat(chunks).toString("utf8");
+    if (!raw)
+        throw new SyntaxError("Empty body");
+    return JSON.parse(raw);
+}
+/** Minimal web Request view over the Node request, for middleware and filters. */
+function toWebRequest(req, path) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers ?? {})) {
+        if (typeof value === "string")
+            headers.set(name, value);
+        else if (Array.isArray(value))
+            headers.set(name, value.join(", "));
+    }
+    const host = headers.get("host") ?? "localhost";
+    const url = new URL(req.url ?? path, `http://${host}`);
+    return new Request(url, { method: req.method ?? "POST", headers });
+}
+/** @internal Exposed for tests. */
+export { resolveSyncModels, executeSyncOperation, SyncOperationError };

package/dist/react.d.ts

@@ -0,0 +1,31 @@
+import { type SyncModelClient } from "./client.js";
+import type { SyncRow, SyncStoreStatus } from "./store.js";
+export type LiveQueryOptions<TRow> = {
+    orderBy?: (row: TRow) => string | number | Date;
+    direction?: "asc" | "desc";
+    limit?: number;
+    offset?: number;
+    enabled?: boolean;
+};
+export type LiveQueryResult<TRow> = {
+    rows: TRow[];
+    status: SyncStoreStatus;
+    error: Error | null;
+    /** Writes in flight against this model. */
+    pending: number;
+    /** Writes waiting for the connection to return. */
+    paused: number;
+    isEmpty: boolean;
+    refresh(): Promise<void>;
+};
+/**
+ * Subscribe to rows of a model, filtered in the browser.
+ *
+ * The predicate runs over the model's rows on every change; it never leaves
+ * the browser, so any expression is fair game. Which rows reach the device is
+ * decided separately by the server's row filter.
+ */
+export declare function useLiveQuery<TRow extends SyncRow = SyncRow>(model: SyncModelClient, predicate?: (row: TRow) => boolean, options?: LiveQueryOptions<TRow>): LiveQueryResult<TRow>;
+/** Subscribe to a single row by key. */
+export declare function useRow<TRow extends SyncRow = SyncRow>(model: SyncModelClient, key: unknown): TRow | undefined;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAGA,OAAO,EAA8B,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAI3D,MAAM,MAAM,gBAAgB,CAAC,IAAI,IAAI;IACnC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAChD,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,eAAe,CAAC,IAAI,IAAI;IAClC,IAAI,EAAE,IAAI,EAAE,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,SAAS,OAAO,GAAG,OAAO,EACzD,KAAK,EAAE,eAAe,EACtB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,OAAO,EAClC,OAAO,GAAE,gBAAgB,CAAC,IAAI,CAAM,GACnC,eAAe,CAAC,IAAI,CAAC,CA6EvB;AAED,wCAAwC;AACxC,wBAAgB,MAAM,CAAC,IAAI,SAAS,OAAO,GAAG,OAAO,EACnD,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,OAAO,GACX,IAAI,GAAG,SAAS,CAYlB"}

package/dist/react.js

@@ -0,0 +1,71 @@
+"use client";
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { getSyncStore, hydrateModel } from "./client.js";
+const EMPTY_ROWS = [];
+/**
+ * Subscribe to rows of a model, filtered in the browser.
+ *
+ * The predicate runs over the model's rows on every change; it never leaves
+ * the browser, so any expression is fair game. Which rows reach the device is
+ * decided separately by the server's row filter.
+ */
+export function useLiveQuery(model, predicate, options = {}) {
+    const name = model.__farmSyncModel;
+    const store = getSyncStore(name);
+    const predicateRef = useRef(predicate);
+    predicateRef.current = predicate;
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const subscribe = useCallback((listener) => store.subscribe(listener), [store]);
+    // Rows live in the browser, so the server has none. Both sides must agree on
+    // that first snapshot or hydration mismatches; the real rows arrive on the
+    // store's first update right after.
+    const rows = useSyncExternalStore(subscribe, () => store.getRows(), () => EMPTY_ROWS);
+    const status = useSyncExternalStore(subscribe, () => store.status, () => "loading");
+    const error = useSyncExternalStore(subscribe, () => store.error, () => null);
+    const pending = useSyncExternalStore(subscribe, () => store.pending, () => 0);
+    const paused = useSyncExternalStore(subscribe, () => store.paused, () => 0);
+    useEffect(() => {
+        if (options.enabled === false)
+            return;
+        hydrateModel(name);
+    }, [name, options.enabled]);
+    // Recompute only when the underlying rows change; the predicate is read from
+    // a ref so an inline arrow does not invalidate the memo every render.
+    const visible = useMemo(() => {
+        const current = predicateRef.current;
+        const opts = optionsRef.current;
+        let result = current ? rows.filter((row) => current(row)) : rows;
+        if (opts.orderBy) {
+            const direction = opts.direction === "desc" ? -1 : 1;
+            result = [...result].sort((a, b) => {
+                const left = opts.orderBy(a);
+                const right = opts.orderBy(b);
+                if (left === right)
+                    return 0;
+                return (left < right ? -1 : 1) * direction;
+            });
+        }
+        if (opts.offset || opts.limit !== undefined) {
+            const start = opts.offset ?? 0;
+            result = result.slice(start, opts.limit === undefined ? undefined : start + opts.limit);
+        }
+        return result;
+    }, [rows]);
+    return {
+        rows: visible,
+        status,
+        error,
+        pending,
+        paused,
+        isEmpty: visible.length === 0,
+        refresh: () => model.refresh(),
+    };
+}
+/** Subscribe to a single row by key. */
+export function useRow(model, key) {
+    const store = getSyncStore(model.__farmSyncModel);
+    const subscribe = useCallback((listener) => store.subscribe(listener), [store]);
+    const rows = useSyncExternalStore(subscribe, () => store.getRows(), () => store.getRows());
+    return useMemo(() => rows.find((row) => String(row[store.descriptor.key]) === String(key)), [rows, key, store.descriptor.key]);
+}

package/dist/server.d.ts

@@ -0,0 +1,47 @@
+import type { ResolvedSyncModel, SyncErrorCode, SyncListResult, SyncRequestBody } from "./types.js";
+/** Minimal slice of the ORM client the sync runtime relies on. */
+export type SyncOrmModelClient = {
+    findMany(args?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    create(args: {
+        data: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    update(args: {
+        where: Record<string, unknown>;
+        data: Record<string, unknown>;
+    }): Promise<Record<string, unknown> | null>;
+    updateMany?(args: {
+        where: Record<string, unknown>;
+        data: Record<string, unknown>;
+    }): Promise<number>;
+    delete?(args: {
+        where: Record<string, unknown>;
+    }): Promise<number>;
+    deleteMany(args: {
+        where: Record<string, unknown>;
+    }): Promise<number>;
+};
+export type SyncOrmClient = Record<string, SyncOrmModelClient>;
+export declare class SyncOperationError extends Error {
+    readonly code: SyncErrorCode;
+    readonly status: number;
+    constructor(code: SyncErrorCode, message: string, status?: number);
+}
+export type ExecuteSyncOptions = {
+    body: SyncRequestBody;
+    models: Map<string, ResolvedSyncModel>;
+    orm: SyncOrmClient;
+    request: Request;
+    /** Context produced by the configured middleware chain. */
+    context: Record<string, unknown>;
+};
+/**
+ * Run one sync operation against the ORM with the model's row filter applied.
+ *
+ * The filter is merged into the query itself rather than checked against the
+ * client's arguments, so a write aimed at a row outside the caller's scope
+ * matches nothing instead of being trusted and rejected after the fact.
+ */
+export declare function executeSyncOperation(options: ExecuteSyncOptions): Promise<SyncListResult | Record<string, unknown> | {
+    deleted: number;
+}>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EAEd,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,kEAAkE;AAClE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IAC7E,MAAM,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClF,MAAM,CAAC,IAAI,EAAE;QACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5C,UAAU,CAAC,CAAC,IAAI,EAAE;QAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpB,MAAM,CAAC,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnE,UAAU,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAE/D,qBAAa,kBAAmB,SAAQ,KAAK;IAEzC,QAAQ,CAAC,IAAI,EAAE,aAAa;IAE5B,QAAQ,CAAC,MAAM;gBAFN,IAAI,EAAE,aAAa,EAC5B,OAAO,EAAE,MAAM,EACN,MAAM,SAAM;CAKxB;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACvC,GAAG,EAAE,aAAa,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CA0CzE"}

package/dist/server.js

@@ -0,0 +1,167 @@
+export class SyncOperationError extends Error {
+    code;
+    status;
+    constructor(code, message, status = 400) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "SyncOperationError";
+    }
+}
+/**
+ * Run one sync operation against the ORM with the model's row filter applied.
+ *
+ * The filter is merged into the query itself rather than checked against the
+ * client's arguments, so a write aimed at a row outside the caller's scope
+ * matches nothing instead of being trusted and rejected after the fact.
+ */
+export async function executeSyncOperation(options) {
+    const { body, models, orm, request, context } = options;
+    const resolved = models.get(body.model);
+    if (!resolved) {
+        throw new SyncOperationError("not_exposed", `Model "${body.model}" is not exposed to the browser.`, 404);
+    }
+    if (body.operation !== "list" && resolved.access !== "write") {
+        throw new SyncOperationError("read_only", `Model "${body.model}" is read-only from the browser.`, 403);
+    }
+    const client = orm[body.model];
+    if (!client) {
+        throw new SyncOperationError("unknown_model", `Model "${body.model}" is missing from the ORM client.`, 500);
+    }
+    const scope = await resolveScope(resolved, { context, request, operation: body.operation });
+    switch (body.operation) {
+        case "list":
+            return listRows(client, resolved, scope, body.since ?? null);
+        case "insert":
+            return insertRow(client, resolved, scope, body.input);
+        case "update":
+            return updateRow(client, resolved, scope, body.input);
+        case "delete":
+            return deleteRow(client, resolved, scope, body.input);
+        default:
+            throw new SyncOperationError("invalid_input", `Unknown operation "${body.operation}".`);
+    }
+}
+async function resolveScope(resolved, args) {
+    if (!resolved.where)
+        return {};
+    const scope = await resolved.where({
+        context: args.context,
+        request: args.request,
+        model: resolved.name,
+        operation: args.operation,
+    });
+    if (!scope || typeof scope !== "object" || Array.isArray(scope)) {
+        throw new SyncOperationError("server_error", `sync(): the row filter for "${resolved.name}" must return an object.`, 500);
+    }
+    return scope;
+}
+async function listRows(client, resolved, scope, since) {
+    const cursorField = resolved.cursorField;
+    const incremental = Boolean(cursorField && since);
+    const where = { ...scope };
+    if (incremental)
+        where[cursorField] = { gt: new Date(since) };
+    const rows = await client.findMany({ where });
+    return {
+        rows,
+        cursor: cursorField ? nextCursor(rows, cursorField, since) : null,
+        full: !incremental,
+    };
+}
+function nextCursor(rows, cursorField, previous) {
+    let latest = previous ? new Date(previous).getTime() : 0;
+    for (const row of rows) {
+        const value = row[cursorField];
+        const time = value instanceof Date
+            ? value.getTime()
+            : typeof value === "string" || typeof value === "number"
+                ? new Date(value).getTime()
+                : Number.NaN;
+        if (Number.isFinite(time) && time > latest)
+            latest = time;
+    }
+    return latest > 0 ? new Date(latest).toISOString() : previous;
+}
+async function insertRow(client, resolved, scope, input) {
+    const data = sanitizeInput(resolved, input, { allowKey: true });
+    // The browser generates keys so an optimistic row is addressable immediately,
+    // but a direct API call may omit one. Without this an id-less row is written
+    // that no update or delete can ever target.
+    if (data[resolved.key] === undefined || data[resolved.key] === null) {
+        const generated = generateKey(resolved);
+        if (generated === undefined) {
+            throw new SyncOperationError("invalid_input", `${resolved.name}.${resolved.key} is required: it has no generatable type.`);
+        }
+        data[resolved.key] = generated;
+    }
+    // Scope and cursor columns are server-owned: client-supplied values are
+    // discarded so a caller cannot widen its scope or stall everyone's
+    // incremental sync by writing a stale timestamp.
+    return client.create({ data: { ...data, ...scope, ...cursorStamp(resolved) } });
+}
+async function updateRow(client, resolved, scope, input) {
+    const data = sanitizeInput(resolved, input, { allowKey: false });
+    const key = requireKey(resolved, input);
+    const where = { ...scope, [resolved.key]: key };
+    const updated = await client.update({ where, data: { ...data, ...cursorStamp(resolved) } });
+    if (!updated) {
+        throw new SyncOperationError("not_found", `No ${resolved.name} row matched ${String(key)} within the current scope.`, 404);
+    }
+    return updated;
+}
+async function deleteRow(client, resolved, scope, input) {
+    const key = requireKey(resolved, input);
+    const deleted = await client.deleteMany({ where: { ...scope, [resolved.key]: key } });
+    if (deleted === 0) {
+        throw new SyncOperationError("not_found", `No ${resolved.name} row matched ${String(key)} within the current scope.`, 404);
+    }
+    return { deleted };
+}
+function requireKey(resolved, input) {
+    const key = input?.[resolved.key];
+    if (key === undefined || key === null || key === "") {
+        throw new SyncOperationError("invalid_input", `${resolved.name}.${resolved.key} is required for this operation.`);
+    }
+    return key;
+}
+/** Drop unknown columns so a client cannot write outside the declared schema. */
+function sanitizeInput(resolved, input, options) {
+    if (input !== undefined &&
+        (typeof input !== "object" || input === null || Array.isArray(input))) {
+        throw new SyncOperationError("invalid_input", "Operation input must be an object.");
+    }
+    const data = {};
+    for (const [field, value] of Object.entries(input ?? {})) {
+        if (!Object.hasOwn(resolved.fields, field))
+            continue;
+        if (field === resolved.key && !options.allowKey)
+            continue;
+        if (field === resolved.cursorField)
+            continue;
+        data[field] = value;
+    }
+    return data;
+}
+/**
+ * Value for the cursor column on a write.
+ *
+ * Drivers do not maintain this: the orm writes exactly the columns it is given.
+ * Stamping it here keeps incremental sync working the same way on every
+ * backend rather than depending on a database default or trigger.
+ */
+function cursorStamp(resolved) {
+    if (!resolved.cursorField)
+        return {};
+    return { [resolved.cursorField]: new Date().toISOString() };
+}
+/** Generate a key for schema types that carry one; other types must be supplied. */
+function generateKey(resolved) {
+    const type = resolved.fields[resolved.key]?.type;
+    if (type !== "uuid" && type !== "id" && type !== "string" && type !== "text")
+        return undefined;
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+        return crypto.randomUUID();
+    }
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}

package/dist/store.d.ts

@@ -0,0 +1,64 @@
+export type SyncRow = Record<string, unknown>;
+export type SyncModelDescriptor = {
+    key: string;
+    access: "read" | "write";
+    persist: boolean;
+    cursor: string | null;
+};
+export type SyncRuntimeConfig = {
+    path: string;
+    models: Record<string, SyncModelDescriptor>;
+};
+export type SyncStoreStatus = "idle" | "loading" | "ready" | "error";
+type OptimisticLayer = {
+    type: "upsert";
+    key: unknown;
+    row: SyncRow;
+} | {
+    type: "delete";
+    key: unknown;
+};
+/**
+ * In-memory rows for one model: confirmed server rows plus an ordered stack of
+ * optimistic layers. Visible rows are the confirmed set with layers applied, so
+ * a rollback is removing one layer rather than reconstructing prior state.
+ */
+export declare class SyncModelStore {
+    readonly name: string;
+    readonly descriptor: SyncModelDescriptor;
+    private confirmed;
+    private layers;
+    private listeners;
+    private snapshot;
+    private snapshotDirty;
+    status: SyncStoreStatus;
+    error: Error | null;
+    cursor: string | null;
+    pending: number;
+    paused: number;
+    constructor(name: string, descriptor: SyncModelDescriptor);
+    subscribe(listener: () => void): () => void;
+    /** Stable array identity between changes so `useSyncExternalStore` stays quiet. */
+    getRows(): SyncRow[];
+    get(key: unknown): SyncRow | undefined;
+    setStatus(status: SyncStoreStatus, error?: Error | null): void;
+    /** Apply a server snapshot or delta. A full result replaces confirmed rows. */
+    applyServerRows(rows: SyncRow[], options: {
+        full: boolean;
+        cursor: string | null;
+    }): void;
+    addLayer(layer: OptimisticLayer): () => void;
+    removeLayer(layer: OptimisticLayer): void;
+    /** Fold a confirmed server row in and drop the layer that predicted it. */
+    commitLayer(layer: OptimisticLayer, confirmed: SyncRow | null): void;
+    mergeRow(key: unknown, changes: SyncRow): SyncRow;
+    /** Rows worth persisting: confirmed only, never optimistic guesses. */
+    confirmedRows(): SyncRow[];
+    hydrate(rows: SyncRow[], cursor: string | null): void;
+    trackPending(delta: number): void;
+    trackPaused(delta: number): void;
+    private invalidate;
+    private emit;
+}
+export {};
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAErE,KAAK,eAAe,GAChB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC;AAErC;;;;GAIG;AACH,qBAAa,cAAc;IAcvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,UAAU,EAAE,mBAAmB;IAd1C,OAAO,CAAC,SAAS,CAA8B;IAC/C,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,aAAa,CAAQ;IAE7B,MAAM,EAAE,eAAe,CAAU;IACjC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAQ;IAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC7B,OAAO,SAAK;IACZ,MAAM,SAAK;gBAGA,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,mBAAmB;IAG1C,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C,mFAAmF;IACnF,OAAO,IAAI,OAAO,EAAE;IAepB,GAAG,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS;IAItC,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,GAAE,KAAK,GAAG,IAAW,GAAG,IAAI;IAMpE,+EAA+E;IAC/E,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAWzF,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,IAAI;IAM5C,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAOzC,2EAA2E;IAC3E,WAAW,CAAC,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI;IAcpE,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;IAKjD,uEAAuE;IACvE,aAAa,IAAI,OAAO,EAAE;IAI1B,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAUrD,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKjC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKhC,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,IAAI;CAGb"}