@farm.js/sync 0.1.0-beta.1

package/dist/store.js

@@ -0,0 +1,128 @@
+/**
+ * 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 class SyncModelStore {
+    name;
+    descriptor;
+    confirmed = new Map();
+    layers = [];
+    listeners = new Set();
+    snapshot = [];
+    snapshotDirty = true;
+    status = "idle";
+    error = null;
+    cursor = null;
+    pending = 0;
+    paused = 0;
+    constructor(name, descriptor) {
+        this.name = name;
+        this.descriptor = descriptor;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Stable array identity between changes so `useSyncExternalStore` stays quiet. */
+    getRows() {
+        if (!this.snapshotDirty)
+            return this.snapshot;
+        const rows = new Map(this.confirmed);
+        for (const layer of this.layers) {
+            const id = String(layer.key);
+            if (layer.type === "delete")
+                rows.delete(id);
+            else
+                rows.set(id, layer.row);
+        }
+        this.snapshot = Array.from(rows.values());
+        this.snapshotDirty = false;
+        return this.snapshot;
+    }
+    get(key) {
+        return this.getRows().find((row) => String(row[this.descriptor.key]) === String(key));
+    }
+    setStatus(status, error = null) {
+        this.status = status;
+        this.error = error;
+        this.emit();
+    }
+    /** Apply a server snapshot or delta. A full result replaces confirmed rows. */
+    applyServerRows(rows, options) {
+        if (options.full)
+            this.confirmed.clear();
+        for (const row of rows) {
+            this.confirmed.set(String(row[this.descriptor.key]), row);
+        }
+        this.cursor = options.cursor ?? this.cursor;
+        this.status = "ready";
+        this.error = null;
+        this.invalidate();
+    }
+    addLayer(layer) {
+        this.layers.push(layer);
+        this.invalidate();
+        return () => this.removeLayer(layer);
+    }
+    removeLayer(layer) {
+        const index = this.layers.indexOf(layer);
+        if (index === -1)
+            return;
+        this.layers.splice(index, 1);
+        this.invalidate();
+    }
+    /** Fold a confirmed server row in and drop the layer that predicted it. */
+    commitLayer(layer, confirmed) {
+        const index = this.layers.indexOf(layer);
+        if (index !== -1)
+            this.layers.splice(index, 1);
+        if (layer.type === "delete") {
+            this.confirmed.delete(String(layer.key));
+        }
+        else if (confirmed) {
+            this.confirmed.set(String(confirmed[this.descriptor.key] ?? layer.key), confirmed);
+        }
+        else {
+            this.confirmed.set(String(layer.key), layer.row);
+        }
+        this.invalidate();
+    }
+    mergeRow(key, changes) {
+        const current = this.get(key) ?? { [this.descriptor.key]: key };
+        return { ...current, ...changes };
+    }
+    /** Rows worth persisting: confirmed only, never optimistic guesses. */
+    confirmedRows() {
+        return Array.from(this.confirmed.values());
+    }
+    hydrate(rows, cursor) {
+        if (this.confirmed.size > 0)
+            return; // live data always wins
+        for (const row of rows) {
+            this.confirmed.set(String(row[this.descriptor.key]), row);
+        }
+        this.cursor = cursor;
+        if (rows.length > 0)
+            this.status = "ready";
+        this.invalidate();
+    }
+    trackPending(delta) {
+        this.pending = Math.max(0, this.pending + delta);
+        this.emit();
+    }
+    trackPaused(delta) {
+        this.paused = Math.max(0, this.paused + delta);
+        this.emit();
+    }
+    invalidate() {
+        this.snapshotDirty = true;
+        this.emit();
+    }
+    emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+import type { FarmSchema, FarmSchemaField, FarmSchemaModel } from "@farm.js/core";
+/** Operations a browser may perform on a model. */
+export type SyncAccess = "read" | "write";
+export type SyncModelConfig = {
+    access?: SyncAccess;
+    /** Overrides the global row filter for this model. `false` disables scoping. */
+    where?: SyncWhere | false;
+    /** Persist this model's rows through the configured client cache adapter. */
+    persist?: boolean;
+};
+export type SyncModelSetting = SyncAccess | false | SyncModelConfig;
+export type SyncWhereContext = {
+    context: Record<string, unknown>;
+    request: Request;
+    model: string;
+    operation: SyncOperation;
+};
+export type SyncWhere = (context: SyncWhereContext) => Record<string, unknown> | Promise<Record<string, unknown>>;
+export type SyncOperation = "list" | "insert" | "update" | "delete";
+/** Wire payload for a single sync operation. */
+export type SyncRequestBody = {
+    model: string;
+    operation: SyncOperation;
+    /** Row data for insert, `{ [key]: value, ...changes }` for update, `{ [key] }` for delete. */
+    input?: Record<string, unknown>;
+    /** Incremental cursor for list; the largest `updatedAt` the client already holds. */
+    since?: string | null;
+};
+export type SyncListResult = {
+    rows: Record<string, unknown>[];
+    cursor: string | null;
+    /** True when the server sent a full snapshot rather than a delta. */
+    full: boolean;
+};
+export type SyncErrorCode = "unknown_model" | "read_only" | "not_exposed" | "invalid_input" | "not_found" | "unauthorized" | "server_error";
+export type SyncErrorBody = {
+    error: {
+        code: SyncErrorCode;
+        message: string;
+    };
+};
+/** Resolved, validated model metadata derived from the schema. */
+export type ResolvedSyncModel = {
+    name: string;
+    model: FarmSchemaModel;
+    /** Primary key field name. */
+    key: string;
+    access: SyncAccess;
+    where: SyncWhere | false | undefined;
+    persist: boolean;
+    /** Field carrying the incremental cursor, when the schema declares one. */
+    cursorField: string | undefined;
+    fields: Record<string, FarmSchemaField>;
+};
+export declare function resolveSyncModels(schema: FarmSchema, models: Record<string, SyncModelSetting> | undefined, globalWhere: SyncWhere | false | undefined, defaultPersist: boolean): Map<string, ResolvedSyncModel>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAElF,mDAAmD;AACnD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1C,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC1B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,KAAK,GAAG,eAAe,CAAC;AAEpE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,aAAa,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,CACtB,OAAO,EAAE,gBAAgB,KACtB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEhE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEpE,gDAAgD;AAChD,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,aAAa,CAAC;IACzB,8FAA8F;IAC9F,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,qEAAqE;IACrE,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,WAAW,GACX,aAAa,GACb,eAAe,GACf,WAAW,GACX,cAAc,GACd,cAAc,CAAC;AAEnB,MAAM,MAAM,aAAa,GAAG;IAAE,KAAK,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAEhF,kEAAkE;AAClE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,eAAe,CAAC;IACvB,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACzC,CAAC;AAEF,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACpD,WAAW,EAAE,SAAS,GAAG,KAAK,GAAG,SAAS,EAC1C,cAAc,EAAE,OAAO,GACtB,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAuChC"}

package/dist/types.js

@@ -0,0 +1,49 @@
+export function resolveSyncModels(schema, models, globalWhere, defaultPersist) {
+    const resolved = new Map();
+    if (!models)
+        return resolved;
+    for (const [name, setting] of Object.entries(models)) {
+        if (setting === false || setting === undefined)
+            continue;
+        const model = schema.models[name];
+        if (!model) {
+            throw new Error(`sync(): models.${name} is not in the schema. Available models: ${Object.keys(schema.models).join(", ") || "(none)"}.`);
+        }
+        const config = typeof setting === "string" ? { access: setting } : (setting ?? {});
+        const access = config.access ?? "write";
+        const where = config.where !== undefined ? config.where : globalWhere;
+        if (access === "write" && where === undefined) {
+            throw new Error(`sync(): models.${name} allows writes but no row filter is configured. ` +
+                `Add a \`where\` to scope rows to the current session, or set \`where: false\` to expose every row deliberately.`);
+        }
+        resolved.set(name, {
+            name,
+            model,
+            key: resolvePrimaryKey(name, model),
+            access,
+            where,
+            persist: config.persist ?? defaultPersist,
+            cursorField: resolveCursorField(model),
+            fields: model.fields,
+        });
+    }
+    return resolved;
+}
+function resolvePrimaryKey(name, model) {
+    const keys = Object.entries(model.fields).filter(([, field]) => field.primaryKey);
+    if (keys.length === 1)
+        return keys[0][0];
+    if (keys.length === 0) {
+        throw new Error(`sync(): model "${name}" needs a field marked \`primaryKey: true\`.`);
+    }
+    throw new Error(`sync(): model "${name}" has ${keys.length} primary key fields; sync requires exactly one.`);
+}
+/** A `datetime` field named updatedAt enables incremental sync without extra config. */
+function resolveCursorField(model) {
+    for (const [name, field] of Object.entries(model.fields)) {
+        if (field.type === "datetime" && (name === "updatedAt" || field.name === "updated_at")) {
+            return name;
+        }
+    }
+    return undefined;
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@farm.js/sync",
+  "version": "0.1.0-beta.1",
+  "description": "Local-first collections for Farm.js: schema-driven reads, optimistic writes, offline queueing",
+  "keywords": [
+    "farm.js",
+    "local-first",
+    "offline",
+    "optimistic",
+    "sync"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-sync"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@farm.js/core": "0.1.0-beta.103"
+  },
+  "devDependencies": {
+    "@farming-labs/orm": "0.0.62",
+    "@farming-labs/orm-runtime": "0.0.62",
+    "@types/node": "^20.10.5",
+    "@types/react": "^19.0.0",
+    "jsdom": "^25.0.0",
+    "react": "^19.0.0",
+    "typescript": "^5.3.3",
+    "unstorage": "^1.16.1",
+    "vitest": "^3.2.7"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}