@absolutejs/sync 0.8.0 → 0.10.0

package/README.md

@@ -33,10 +33,11 @@ top-N ordering are maintained incrementally through a composable operator graph
 > write-behind cache), Tier 2 (Drizzle + Prisma topic adapters, `createLiveQuery`),
 > and Tier 3 (sync engine: collections, WebSocket diff transport, optimistic
 > mutations + offline queue, a local-first client cache, declarative row-level
-> permissions, live full-text + vector search, scheduled functions, a live
-> devtools dashboard, CDC for Postgres/MySQL/SQLite, incremental aggregations +
-> joins, and a declarative operator graph) are in place. Everything ships as
-> subpaths of this one package.
+> permissions, schema validation + lazy migrations, live full-text + vector
+> search, scheduled functions, a live devtools dashboard, conflict-free
+> collaborative editing (CRDTs), CDC for Postgres/MySQL/SQLite, incremental
+> aggregations + joins, and a declarative operator graph) are in place.
+> Everything ships as subpaths of this one package.
 
 ## Install
 
@@ -403,11 +404,24 @@ mutate({
 | `defineGraphCollection({ name, query, key, authorize? })`                                | Run a `query` as a live collection.                                                                                                                                                                                    |
 | `defineReactiveQuery({ name, run, key })` + `registerReactive` / `registerReader`        | Read-set-tracked query: `run(ctx)` reads via `ctx.db` (`all`/`get`/`where`) and re-runs only when the rows/ranges it read change — no `match`, no manual emit.                                                         |
 | `definePermissions({ [table]: { read?, insert?, update?, delete?, write? } })`           | Declarative row-level access control. Pass as `createSyncEngine({ permissions })` or `registerPermissions(table, rules)`. Read rules filter every row emitted; write rules gate `actions.insert/update/delete`.        |
+| `defineSchema({ [table]: { fields, version?, migrate? } })` + `field` kit                | Declarative row schema. Pass as `createSyncEngine({ schemas })` or `registerSchema(table, schema)`. Writes are validated (bad write → `SchemaError`); `migrate` lazily upcasts rows on read (no DB migration needed).  |
 | `defineSearchCollection({ name, table, index, source, key, limit? })` + `registerSearch` | Live search collection: the subscription's `params` are the query (string/vector), the ranked top-K stream back as a normal collection, re-ranked as rows change. Each row carries its score under `_score`.           |
 | `createTextIndex({ key, fields, tokenize?, stopwords?, k1?, b? })`                       | Incremental BM25 full-text index (keyword search). Implements `SearchIndex`; usable standalone or inside a search collection.                                                                                          |
 | `createVectorIndex({ key, embedding, metric? })`                                         | Incremental vector index (cosine/dot/euclidean exact k-NN) for semantic search — pairs with `@absolutejs/ai` / `@absolutejs/rag` for RAG retrieval on your own data.                                                   |
 | `defineSchedule({ name, pattern, run })` + `registerSchedule` / `runSchedule`            | Scheduled function: `run({ db, actions })` fires on a cron `pattern`; its writes go live through the change feed. Wire triggers with the `scheduled` plugin (or call `runSchedule(name)` on demand).                   |
 
+### `@absolutejs/sync/crdt`
+
+Conflict-free replicated data types — pure, **zero-dependency**, and isomorphic (same code client and server). They merge concurrent edits from different tabs/devices without a server round-trip per keystroke and without clobbering: every `merge` is commutative, associative, and idempotent, so replicas converge no matter the order. They ride the existing engine with no engine changes — store the CRDT state as a row field and have a mutation `merge` the incoming state into the stored one.
+
+| Export                                       | What it is                                                                                                                                                                                                                         |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `counter`                                    | PN-counter: `create/value/increment/decrement/merge`. Concurrent increments and decrements across replicas all survive.                                                                                                            |
+| `lww`                                        | Last-write-wins register: `create/set/merge`. The latest timestamp wins (replica id breaks ties) — for "just take the newest value" fields.                                                                                        |
+| `createTextCrdt(replica, initial?)`          | Collaborative text (an RGA sequence CRDT): `text/insert/delete/setText/merge/state`. Drive it from an input via `setText`; broadcast `state()`; apply remote state via `merge` — concurrent edits merge and converge.              |
+| `textOf(state)` / `mergeTextState(a, b)`     | Pure helpers for the text state — use them server-side (e.g. a merge-on-write mutation) with no live instance.                                                                                                                     |
+| `CrdtText<State>` / `TextCrdtAdapter<State>` | The pluggable collaborative-text contract. `rgaText` is the first-party (zero-dep) backend; swap in an adapter from the `sync-adapters` repo (e.g. `@absolutejs/sync-yjs`, which wraps the Yjs staple) behind the same call sites. |
+
 ### `@absolutejs/sync/postgres`
 
 | Export                                                       | What it is                                                       |

package/dist/crdt/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Conflict-free replicated data types (CRDTs) for multiplayer/offline editing —
+ * pure, dependency-free, and isomorphic (use the same code client and server).
+ *
+ * These are *state-based* CRDTs (CvRDTs): every `merge` is commutative,
+ * associative, and idempotent, so replicas that exchange state in any order
+ * converge to the same value. That fits the sync engine without engine changes:
+ * store the CRDT state as a row field, have a mutation `merge` the incoming
+ * state into the stored one (concurrent writes combine instead of clobbering),
+ * and have each client merge the broadcast state into its local edits.
+ */
+/** A counter that survives concurrent increments/decrements across replicas. */
+export type CounterState = {
+    increments: Record<string, number>;
+    decrements: Record<string, number>;
+};
+export declare const counter: {
+    create: () => CounterState;
+    /** Current value: total increments minus total decrements. */
+    value: (state: CounterState) => number;
+    increment: (state: CounterState, replica: string, by?: number) => CounterState;
+    decrement: (state: CounterState, replica: string, by?: number) => CounterState;
+    /** Merge by taking the max count seen per replica (monotonic). */
+    merge: (a: CounterState, b: CounterState) => CounterState;
+};
+/** A single value where the latest write wins (ties broken by replica id). */
+export type LwwState<T> = {
+    value: T;
+    timestamp: number;
+    replica: string;
+};
+export declare const lww: {
+    create: <T>(value: T, replica: string, timestamp?: number) => LwwState<T>;
+    set: <T>(value: T, replica: string, timestamp?: number) => LwwState<T>;
+    /** Keep the entry with the higher timestamp (replica id breaks ties). */
+    merge: <T>(a: LwwState<T>, b: LwwState<T>) => LwwState<T>;
+};
+/**
+ * The contract a collaborative-text CRDT exposes, independent of the algorithm
+ * behind it. Implemented first-party by the RGA below ({@link createTextCrdt})
+ * and by third-party backends in the `sync-adapters` repo (e.g.
+ * `@absolutejs/sync-yjs`). `State` is whatever that backend persists and
+ * broadcasts — JSON ({@link TextState}) for the RGA, a base64 update for Yjs.
+ */
+export type CrdtText<State> = {
+    /** The current visible text. */
+    text: () => string;
+    /** Reconcile the local text to `next` (the backend computes the edit). */
+    setText: (next: string) => void;
+    /** Merge another replica's state in (e.g. a broadcast from the server). */
+    merge: (state: State) => void;
+    /** The serializable state to persist/broadcast. */
+    state: () => State;
+};
+/**
+ * A pluggable collaborative-text backend. `create` mints a live doc for a
+ * replica; `merge` combines two persisted states server-side (no live instance
+ * needed — for the merge-on-write mutation); `empty`/`textOf` are conveniences.
+ * Swap the first-party {@link rgaText} for an adapter to get a different engine
+ * (e.g. Yjs) behind the exact same call sites.
+ */
+export type TextCrdtAdapter<State> = {
+    create: (replica: string, initial?: State) => CrdtText<State>;
+    merge: (a: State, b: State) => State;
+    empty: () => State;
+    textOf: (state: State) => string;
+};
+/** One inserted character in the replicated sequence (kept as a tombstone if deleted). */
+export type TextElement = {
+    id: string;
+    replica: string;
+    clock: number;
+    /** Id of the element this was inserted after (`null` = start of document). */
+    after: string | null;
+    value: string;
+    deleted: boolean;
+};
+/** Serializable state of a {@link TextCrdt} — safe to store as a row field. */
+export type TextState = {
+    elements: TextElement[];
+};
+/** The visible string of a text-CRDT state. Pure — use it server-side too. */
+export declare const textOf: (state: TextState) => string;
+/** Merge two text-CRDT states (commutative/idempotent). Pure — for server mutations. */
+export declare const mergeTextState: (a: TextState, b: TextState) => TextState;
+/** The RGA text CRDT — {@link CrdtText} plus direct positional edits. */
+export type TextCrdt = CrdtText<TextState> & {
+    /** Insert `value` at visible `index`. */
+    insert: (index: number, value: string) => void;
+    /** Tombstone `count` visible characters from `index`. */
+    delete: (index: number, count: number) => void;
+};
+/**
+ * A collaborative text buffer backed by an RGA sequence CRDT. Concurrent inserts
+ * and deletes from different replicas merge without conflict and converge. Drive
+ * it from an input via {@link TextCrdt.setText}; persist/broadcast
+ * {@link TextCrdt.state}; apply remote state via {@link TextCrdt.merge}.
+ */
+export declare const createTextCrdt: (replica: string, initial?: TextState) => TextCrdt;
+/**
+ * The first-party collaborative-text backend (the RGA above) packaged as a
+ * {@link TextCrdtAdapter}. Zero dependencies. Use it directly, or swap in an
+ * adapter from `sync-adapters` (e.g. `@absolutejs/sync-yjs`) for the same shape.
+ */
+export declare const rgaText: TextCrdtAdapter<TextState>;

package/dist/crdt/index.js

@@ -0,0 +1,256 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __name = (target, name) => {
+  Object.defineProperty(target, "name", {
+    value: name,
+    enumerable: false,
+    configurable: true
+  });
+  return target;
+};
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => (key in obj) ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateIn = (member, obj) => Object(obj) !== obj ? __typeError('Cannot use the "in" operator on this value') : member.has(obj);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+var __decoratorStart = (base) => [, , , __create(base?.[__knownSymbol("metadata")] ?? null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== undefined && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({
+  kind: __decoratorStrings[kind],
+  name,
+  metadata,
+  addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null))
+});
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length;i < n; i++)
+    flags & 1 ? fns[i].call(self) : value = fns[i].call(self, value);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var fn, it, done, ctx, access, k = flags & 7, s = !!(flags & 8), p = !!(flags & 16);
+  var j = k > 3 ? array.length + 1 : k ? s ? 1 : 2 : 0, key = __decoratorStrings[k + 5];
+  var initializers = k > 3 && (array[j - 1] = []), extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (!p && !s && (target = target.prototype), k < 5 && (k > 3 || !p) && __getOwnPropDesc(k < 4 ? target : {
+    get [name]() {
+      return __privateGet(this, extra);
+    },
+    set [name](x) {
+      __privateSet(this, extra, x);
+    }
+  }, name));
+  k ? p && k < 4 && __name(extra, (k > 2 ? "set " : k > 1 ? "get " : "") + name) : __name(target, name);
+  for (var i = decorators.length - 1;i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    if (k) {
+      ctx.static = s, ctx.private = p, access = ctx.access = { has: p ? (x) => __privateIn(target, x) : (x) => (name in x) };
+      if (k ^ 3)
+        access.get = p ? (x) => (k ^ 1 ? __privateGet : __privateMethod)(x, target, k ^ 4 ? extra : desc.get) : (x) => x[name];
+      if (k > 2)
+        access.set = p ? (x, y) => __privateSet(x, target, y, k ^ 4 ? extra : desc.set) : (x, y) => x[name] = y;
+    }
+    it = (0, decorators[i])(k ? k < 4 ? p ? extra : desc[key] : k > 4 ? undefined : { get: desc.get, set: desc.set } : target, ctx);
+    done._ = 1;
+    if (k ^ 4 || it === undefined)
+      __expectFn(it) && (k > 4 ? initializers.unshift(it) : k ? p ? extra = it : desc[key] = it : target = it);
+    else if (typeof it !== "object" || it === null)
+      __typeError("Object expected");
+    else
+      __expectFn(fn = it.get) && (desc.get = fn), __expectFn(fn = it.set) && (desc.set = fn), __expectFn(fn = it.init) && initializers.unshift(fn);
+  }
+  return k || __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+
+// src/crdt/index.ts
+var sumValues = (counts) => Object.values(counts).reduce((total, value) => total + value, 0);
+var mergeMax = (a, b) => {
+  const merged = { ...a };
+  for (const [replica, value] of Object.entries(b)) {
+    merged[replica] = Math.max(merged[replica] ?? 0, value);
+  }
+  return merged;
+};
+var counter = {
+  create: () => ({ increments: {}, decrements: {} }),
+  value: (state) => sumValues(state.increments) - sumValues(state.decrements),
+  increment: (state, replica, by = 1) => ({
+    increments: {
+      ...state.increments,
+      [replica]: (state.increments[replica] ?? 0) + by
+    },
+    decrements: state.decrements
+  }),
+  decrement: (state, replica, by = 1) => ({
+    increments: state.increments,
+    decrements: {
+      ...state.decrements,
+      [replica]: (state.decrements[replica] ?? 0) + by
+    }
+  }),
+  merge: (a, b) => ({
+    increments: mergeMax(a.increments, b.increments),
+    decrements: mergeMax(a.decrements, b.decrements)
+  })
+};
+var lww = {
+  create: (value, replica, timestamp = Date.now()) => ({ value, timestamp, replica }),
+  set: (value, replica, timestamp = Date.now()) => ({
+    value,
+    timestamp,
+    replica
+  }),
+  merge: (a, b) => {
+    if (b.timestamp > a.timestamp) {
+      return b;
+    }
+    if (b.timestamp < a.timestamp) {
+      return a;
+    }
+    return b.replica > a.replica ? b : a;
+  }
+};
+var compare = (a, b) => {
+  if (a.clock !== b.clock) {
+    return b.clock - a.clock;
+  }
+  if (a.replica === b.replica) {
+    return 0;
+  }
+  return a.replica > b.replica ? -1 : 1;
+};
+var linearize = (elements) => {
+  const children = new Map;
+  for (const element of elements) {
+    const list = children.get(element.after);
+    if (list === undefined) {
+      children.set(element.after, [element]);
+    } else {
+      list.push(element);
+    }
+  }
+  for (const list of children.values()) {
+    list.sort(compare);
+  }
+  const ordered = [];
+  const stack = [...children.get(null) ?? []].reverse();
+  while (stack.length > 0) {
+    const element = stack.pop();
+    ordered.push(element);
+    const kids = children.get(element.id);
+    if (kids !== undefined) {
+      for (let index = kids.length - 1;index >= 0; index -= 1) {
+        stack.push(kids[index]);
+      }
+    }
+  }
+  return ordered;
+};
+var textOf = (state) => linearize(state.elements).filter((element) => !element.deleted).map((element) => element.value).join("");
+var mergeTextState = (a, b) => {
+  const byId = new Map;
+  for (const element of [...a.elements, ...b.elements]) {
+    const existing = byId.get(element.id);
+    byId.set(element.id, existing === undefined ? element : { ...existing, deleted: existing.deleted || element.deleted });
+  }
+  return { elements: [...byId.values()] };
+};
+var createTextCrdt = (replica, initial) => {
+  const elements = new Map;
+  let clock = 0;
+  if (initial !== undefined) {
+    for (const element of initial.elements) {
+      elements.set(element.id, element);
+      clock = Math.max(clock, element.clock);
+    }
+  }
+  const visible = () => linearize([...elements.values()]).filter((element) => !element.deleted);
+  const insert = (index, value) => {
+    const seen = visible();
+    let after = index <= 0 ? null : seen[index - 1]?.id ?? null;
+    for (const char of [...value]) {
+      clock += 1;
+      const element = {
+        id: `${replica}:${clock}`,
+        replica,
+        clock,
+        after,
+        value: char,
+        deleted: false
+      };
+      elements.set(element.id, element);
+      after = element.id;
+    }
+  };
+  const remove = (index, count) => {
+    const seen = visible();
+    for (let offset = 0;offset < count; offset += 1) {
+      const target = seen[index + offset];
+      if (target !== undefined) {
+        elements.set(target.id, { ...target, deleted: true });
+      }
+    }
+  };
+  return {
+    text: () => textOf({ elements: [...elements.values()] }),
+    insert,
+    delete: remove,
+    merge: (state) => {
+      for (const element of state.elements) {
+        const existing = elements.get(element.id);
+        elements.set(element.id, existing === undefined ? element : {
+          ...existing,
+          deleted: existing.deleted || element.deleted
+        });
+        clock = Math.max(clock, element.clock);
+      }
+    },
+    setText: (next) => {
+      const current = textOf({ elements: [...elements.values()] });
+      if (current === next) {
+        return;
+      }
+      let prefix = 0;
+      const maxPrefix = Math.min(current.length, next.length);
+      while (prefix < maxPrefix && current[prefix] === next[prefix]) {
+        prefix += 1;
+      }
+      let suffix = 0;
+      while (suffix < maxPrefix - prefix && current[current.length - 1 - suffix] === next[next.length - 1 - suffix]) {
+        suffix += 1;
+      }
+      const removed = current.length - prefix - suffix;
+      if (removed > 0) {
+        remove(prefix, removed);
+      }
+      const inserted = next.slice(prefix, next.length - suffix);
+      if (inserted.length > 0) {
+        insert(prefix, inserted);
+      }
+    },
+    state: () => ({ elements: [...elements.values()] })
+  };
+};
+var rgaText = {
+  create: createTextCrdt,
+  empty: () => ({ elements: [] }),
+  merge: mergeTextState,
+  textOf
+};
+export {
+  textOf,
+  rgaText,
+  mergeTextState,
+  lww,
+  createTextCrdt,
+  counter
+};
+
+//# debugId=21FF50AD5A6B235464756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/crdt/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/crdt/index.ts"],
+  "sourcesContent": [
+    "/**\n * Conflict-free replicated data types (CRDTs) for multiplayer/offline editing —\n * pure, dependency-free, and isomorphic (use the same code client and server).\n *\n * These are *state-based* CRDTs (CvRDTs): every `merge` is commutative,\n * associative, and idempotent, so replicas that exchange state in any order\n * converge to the same value. That fits the sync engine without engine changes:\n * store the CRDT state as a row field, have a mutation `merge` the incoming\n * state into the stored one (concurrent writes combine instead of clobbering),\n * and have each client merge the broadcast state into its local edits.\n */\n\nconst sumValues = (counts: Record<string, number>) =>\n\tObject.values(counts).reduce((total, value) => total + value, 0);\n\nconst mergeMax = (\n\ta: Record<string, number>,\n\tb: Record<string, number>\n): Record<string, number> => {\n\tconst merged: Record<string, number> = { ...a };\n\tfor (const [replica, value] of Object.entries(b)) {\n\t\tmerged[replica] = Math.max(merged[replica] ?? 0, value);\n\t}\n\treturn merged;\n};\n\n/* ─── PN-counter ─── */\n\n/** A counter that survives concurrent increments/decrements across replicas. */\nexport type CounterState = {\n\tincrements: Record<string, number>;\n\tdecrements: Record<string, number>;\n};\n\nexport const counter = {\n\tcreate: (): CounterState => ({ increments: {}, decrements: {} }),\n\t/** Current value: total increments minus total decrements. */\n\tvalue: (state: CounterState) =>\n\t\tsumValues(state.increments) - sumValues(state.decrements),\n\tincrement: (\n\t\tstate: CounterState,\n\t\treplica: string,\n\t\tby = 1\n\t): CounterState => ({\n\t\tincrements: {\n\t\t\t...state.increments,\n\t\t\t[replica]: (state.increments[replica] ?? 0) + by\n\t\t},\n\t\tdecrements: state.decrements\n\t}),\n\tdecrement: (\n\t\tstate: CounterState,\n\t\treplica: string,\n\t\tby = 1\n\t): CounterState => ({\n\t\tincrements: state.increments,\n\t\tdecrements: {\n\t\t\t...state.decrements,\n\t\t\t[replica]: (state.decrements[replica] ?? 0) + by\n\t\t}\n\t}),\n\t/** Merge by taking the max count seen per replica (monotonic). */\n\tmerge: (a: CounterState, b: CounterState): CounterState => ({\n\t\tincrements: mergeMax(a.increments, b.increments),\n\t\tdecrements: mergeMax(a.decrements, b.decrements)\n\t})\n};\n\n/* ─── LWW register ─── */\n\n/** A single value where the latest write wins (ties broken by replica id). */\nexport type LwwState<T> = { value: T; timestamp: number; replica: string };\n\nexport const lww = {\n\tcreate: <T>(\n\t\tvalue: T,\n\t\treplica: string,\n\t\ttimestamp = Date.now()\n\t): LwwState<T> => ({ value, timestamp, replica }),\n\tset: <T>(\n\t\tvalue: T,\n\t\treplica: string,\n\t\ttimestamp = Date.now()\n\t): LwwState<T> => ({\n\t\tvalue,\n\t\ttimestamp,\n\t\treplica\n\t}),\n\t/** Keep the entry with the higher timestamp (replica id breaks ties). */\n\tmerge: <T>(a: LwwState<T>, b: LwwState<T>): LwwState<T> => {\n\t\tif (b.timestamp > a.timestamp) {\n\t\t\treturn b;\n\t\t}\n\t\tif (b.timestamp < a.timestamp) {\n\t\t\treturn a;\n\t\t}\n\t\treturn b.replica > a.replica ? b : a;\n\t}\n};\n\n/* ─── Collaborative text ─── */\n\n/**\n * The contract a collaborative-text CRDT exposes, independent of the algorithm\n * behind it. Implemented first-party by the RGA below ({@link createTextCrdt})\n * and by third-party backends in the `sync-adapters` repo (e.g.\n * `@absolutejs/sync-yjs`). `State` is whatever that backend persists and\n * broadcasts — JSON ({@link TextState}) for the RGA, a base64 update for Yjs.\n */\nexport type CrdtText<State> = {\n\t/** The current visible text. */\n\ttext: () => string;\n\t/** Reconcile the local text to `next` (the backend computes the edit). */\n\tsetText: (next: string) => void;\n\t/** Merge another replica's state in (e.g. a broadcast from the server). */\n\tmerge: (state: State) => void;\n\t/** The serializable state to persist/broadcast. */\n\tstate: () => State;\n};\n\n/**\n * A pluggable collaborative-text backend. `create` mints a live doc for a\n * replica; `merge` combines two persisted states server-side (no live instance\n * needed — for the merge-on-write mutation); `empty`/`textOf` are conveniences.\n * Swap the first-party {@link rgaText} for an adapter to get a different engine\n * (e.g. Yjs) behind the exact same call sites.\n */\nexport type TextCrdtAdapter<State> = {\n\tcreate: (replica: string, initial?: State) => CrdtText<State>;\n\tmerge: (a: State, b: State) => State;\n\tempty: () => State;\n\ttextOf: (state: State) => string;\n};\n\n/* ─── Collaborative text (RGA) — the first-party backend ─── */\n\n/** One inserted character in the replicated sequence (kept as a tombstone if deleted). */\nexport type TextElement = {\n\tid: string;\n\treplica: string;\n\tclock: number;\n\t/** Id of the element this was inserted after (`null` = start of document). */\n\tafter: string | null;\n\tvalue: string;\n\tdeleted: boolean;\n};\n\n/** Serializable state of a {@link TextCrdt} — safe to store as a row field. */\nexport type TextState = { elements: TextElement[] };\n\n// Sibling order (same `after`): higher clock first, then higher replica id.\nconst compare = (a: TextElement, b: TextElement) => {\n\tif (a.clock !== b.clock) {\n\t\treturn b.clock - a.clock;\n\t}\n\tif (a.replica === b.replica) {\n\t\treturn 0;\n\t}\n\treturn a.replica > b.replica ? -1 : 1;\n};\n\n/** Flatten the sequence into document order (an iterative RGA pre-order walk). */\nconst linearize = (elements: TextElement[]): TextElement[] => {\n\tconst children = new Map<string | null, TextElement[]>();\n\tfor (const element of elements) {\n\t\tconst list = children.get(element.after);\n\t\tif (list === undefined) {\n\t\t\tchildren.set(element.after, [element]);\n\t\t} else {\n\t\t\tlist.push(element);\n\t\t}\n\t}\n\tfor (const list of children.values()) {\n\t\tlist.sort(compare);\n\t}\n\tconst ordered: TextElement[] = [];\n\tconst stack = [...(children.get(null) ?? [])].reverse();\n\twhile (stack.length > 0) {\n\t\tconst element = stack.pop()!;\n\t\tordered.push(element);\n\t\tconst kids = children.get(element.id);\n\t\tif (kids !== undefined) {\n\t\t\tfor (let index = kids.length - 1; index >= 0; index -= 1) {\n\t\t\t\tstack.push(kids[index]!);\n\t\t\t}\n\t\t}\n\t}\n\treturn ordered;\n};\n\n/** The visible string of a text-CRDT state. Pure — use it server-side too. */\nexport const textOf = (state: TextState): string =>\n\tlinearize(state.elements)\n\t\t.filter((element) => !element.deleted)\n\t\t.map((element) => element.value)\n\t\t.join('');\n\n/** Merge two text-CRDT states (commutative/idempotent). Pure — for server mutations. */\nexport const mergeTextState = (a: TextState, b: TextState): TextState => {\n\tconst byId = new Map<string, TextElement>();\n\tfor (const element of [...a.elements, ...b.elements]) {\n\t\tconst existing = byId.get(element.id);\n\t\tbyId.set(\n\t\t\telement.id,\n\t\t\texisting === undefined\n\t\t\t\t? element\n\t\t\t\t: { ...existing, deleted: existing.deleted || element.deleted }\n\t\t);\n\t}\n\treturn { elements: [...byId.values()] };\n};\n\n/** The RGA text CRDT — {@link CrdtText} plus direct positional edits. */\nexport type TextCrdt = CrdtText<TextState> & {\n\t/** Insert `value` at visible `index`. */\n\tinsert: (index: number, value: string) => void;\n\t/** Tombstone `count` visible characters from `index`. */\n\tdelete: (index: number, count: number) => void;\n};\n\n/**\n * A collaborative text buffer backed by an RGA sequence CRDT. Concurrent inserts\n * and deletes from different replicas merge without conflict and converge. Drive\n * it from an input via {@link TextCrdt.setText}; persist/broadcast\n * {@link TextCrdt.state}; apply remote state via {@link TextCrdt.merge}.\n */\nexport const createTextCrdt = (\n\treplica: string,\n\tinitial?: TextState\n): TextCrdt => {\n\tconst elements = new Map<string, TextElement>();\n\tlet clock = 0;\n\tif (initial !== undefined) {\n\t\tfor (const element of initial.elements) {\n\t\t\telements.set(element.id, element);\n\t\t\tclock = Math.max(clock, element.clock);\n\t\t}\n\t}\n\n\tconst visible = () =>\n\t\tlinearize([...elements.values()]).filter((element) => !element.deleted);\n\n\tconst insert = (index: number, value: string) => {\n\t\tconst seen = visible();\n\t\tlet after = index <= 0 ? null : (seen[index - 1]?.id ?? null);\n\t\tfor (const char of [...value]) {\n\t\t\tclock += 1;\n\t\t\tconst element: TextElement = {\n\t\t\t\tid: `${replica}:${clock}`,\n\t\t\t\treplica,\n\t\t\t\tclock,\n\t\t\t\tafter,\n\t\t\t\tvalue: char,\n\t\t\t\tdeleted: false\n\t\t\t};\n\t\t\telements.set(element.id, element);\n\t\t\tafter = element.id;\n\t\t}\n\t};\n\n\tconst remove = (index: number, count: number) => {\n\t\tconst seen = visible();\n\t\tfor (let offset = 0; offset < count; offset += 1) {\n\t\t\tconst target = seen[index + offset];\n\t\t\tif (target !== undefined) {\n\t\t\t\telements.set(target.id, { ...target, deleted: true });\n\t\t\t}\n\t\t}\n\t};\n\n\treturn {\n\t\ttext: () => textOf({ elements: [...elements.values()] }),\n\t\tinsert,\n\t\tdelete: remove,\n\t\tmerge: (state) => {\n\t\t\tfor (const element of state.elements) {\n\t\t\t\tconst existing = elements.get(element.id);\n\t\t\t\telements.set(\n\t\t\t\t\telement.id,\n\t\t\t\t\texisting === undefined\n\t\t\t\t\t\t? element\n\t\t\t\t\t\t: {\n\t\t\t\t\t\t\t\t...existing,\n\t\t\t\t\t\t\t\tdeleted: existing.deleted || element.deleted\n\t\t\t\t\t\t\t}\n\t\t\t\t);\n\t\t\t\tclock = Math.max(clock, element.clock);\n\t\t\t}\n\t\t},\n\t\t// Reconcile to `next` by editing only the changed middle: keep the common\n\t\t// prefix/suffix, delete the old middle, insert the new — so two clients\n\t\t// typing in different places merge instead of overwriting.\n\t\tsetText: (next) => {\n\t\t\tconst current = textOf({ elements: [...elements.values()] });\n\t\t\tif (current === next) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tlet prefix = 0;\n\t\t\tconst maxPrefix = Math.min(current.length, next.length);\n\t\t\twhile (prefix < maxPrefix && current[prefix] === next[prefix]) {\n\t\t\t\tprefix += 1;\n\t\t\t}\n\t\t\tlet suffix = 0;\n\t\t\twhile (\n\t\t\t\tsuffix < maxPrefix - prefix &&\n\t\t\t\tcurrent[current.length - 1 - suffix] ===\n\t\t\t\t\tnext[next.length - 1 - suffix]\n\t\t\t) {\n\t\t\t\tsuffix += 1;\n\t\t\t}\n\t\t\tconst removed = current.length - prefix - suffix;\n\t\t\tif (removed > 0) {\n\t\t\t\tremove(prefix, removed);\n\t\t\t}\n\t\t\tconst inserted = next.slice(prefix, next.length - suffix);\n\t\t\tif (inserted.length > 0) {\n\t\t\t\tinsert(prefix, inserted);\n\t\t\t}\n\t\t},\n\t\tstate: () => ({ elements: [...elements.values()] })\n\t};\n};\n\n/**\n * The first-party collaborative-text backend (the RGA above) packaged as a\n * {@link TextCrdtAdapter}. Zero dependencies. Use it directly, or swap in an\n * adapter from `sync-adapters` (e.g. `@absolutejs/sync-yjs`) for the same shape.\n */\nexport const rgaText: TextCrdtAdapter<TextState> = {\n\tcreate: createTextCrdt,\n\tempty: () => ({ elements: [] }),\n\tmerge: mergeTextState,\n\ttextOf\n};\n"
+  ],
+  "mappings": "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",
+  "debugId": "21FF50AD5A6B235464756E2164756E21",
+  "names": []
+}

package/dist/engine/index.d.ts

@@ -42,8 +42,10 @@ export { defineSchedule } from './schedule';
 export type { ScheduleContext, ScheduleDefinition } from './schedule';
 export { defineMutation } from './mutation';
 export type { MutationActions, MutationDefinition, MutationHandler, TableWriter, TransactionRunner } from './mutation';
-export { createSyncEngine, UnauthorizedError } from './syncEngine';
+export { createSyncEngine, SchemaError, UnauthorizedError } from './syncEngine';
 export type { SubscribeArgs, Subscription, SyncEngine } from './syncEngine';
+export { defineSchema, field } from './schema';
+export type { FieldValidator, SchemaDefinition, TableSchema } from './schema';
 export type { CollectionInspection, CollectionKind, EngineActivity, EngineInspection } from './devtools';
 export { hydrateRoute, mutateRoute } from './routes';
 export type { SyncRouteContext } from './routes';

package/dist/engine/index.js

@@ -1046,6 +1046,13 @@ class UnauthorizedError extends Error {
     this.name = "UnauthorizedError";
   }
 }
+
+class SchemaError extends Error {
+  constructor(table, fieldName) {
+    super(`Schema violation on "${table}": invalid field "${fieldName}"`);
+    this.name = "SchemaError";
+  }
+}
 var defaultKey = (row) => row.id;
 var shallowEqual4 = (a, b) => {
   if (a === b) {
@@ -1082,6 +1089,30 @@ var createSyncEngine = (options = {}) => {
     const rules = permissions.get(table);
     return rules?.[op] ?? rules?.write;
   };
+  const schemas = new Map;
+  for (const [table, schema] of Object.entries(options.schemas ?? {})) {
+    schemas.set(table, schema);
+  }
+  const validateWrite = (table, op, row) => {
+    const schema = schemas.get(table);
+    if (schema === undefined || typeof row !== "object" || row === null) {
+      return;
+    }
+    const record = row;
+    for (const [fieldName, validate] of Object.entries(schema.fields)) {
+      const present = fieldName in record;
+      if (op === "update" && !present) {
+        continue;
+      }
+      if (!validate(record[fieldName])) {
+        throw new SchemaError(table, fieldName);
+      }
+    }
+  };
+  const migrateRow = (table, row) => {
+    const migrate = schemas.get(table)?.migrate;
+    return migrate ? migrate(row) : row;
+  };
   const reactiveSubs = new Set;
   const searchSubs = new Set;
   const searchIndexes = new Map;
@@ -1222,7 +1253,7 @@ var createSyncEngine = (options = {}) => {
     return {
       all: async (table) => {
         readTables.add(table);
-        const rows = [...await readerFor(table).all(ctx)];
+        const rows = [...await readerFor(table).all(ctx)].map((row) => migrateRow(table, row));
         const rule = ruleFor(table);
         return rule ? rows.filter((row) => rule(ctx, row)) : rows;
       },
@@ -1236,7 +1267,8 @@ var createSyncEngine = (options = {}) => {
         } else {
           readTables.add(table);
         }
-        const row = await reader.get(key, ctx);
+        const raw = await reader.get(key, ctx);
+        const row = raw === undefined ? undefined : migrateRow(table, raw);
         const rule = ruleFor(table);
         return rule && row !== undefined && !rule(ctx, row) ? undefined : row;
       },
@@ -1244,7 +1276,7 @@ var createSyncEngine = (options = {}) => {
         const reader = readerFor(table);
         const rule = ruleFor(table);
         const effective = rule ? (row) => predicate(row) && rule(ctx, row) : predicate;
-        const matched = [...await reader.all(ctx)].filter(effective);
+        const matched = [...await reader.all(ctx)].map((row) => migrateRow(table, row)).filter(effective);
         if (reader.key !== undefined) {
           const key = reader.key;
           rangeDeps.push({
@@ -1299,6 +1331,7 @@ var createSyncEngine = (options = {}) => {
         return Promise.resolve();
       },
       insert: async (table, data) => {
+        validateWrite(table, "insert", data);
         if (enforce) {
           await authorizeWrite(table, "insert", data, ctx);
         }
@@ -1307,6 +1340,7 @@ var createSyncEngine = (options = {}) => {
         return row;
       },
       update: async (table, data) => {
+        validateWrite(table, "update", data);
         if (enforce) {
           await authorizeWrite(table, "update", data, ctx);
         }
@@ -1725,8 +1759,13 @@ var createSyncEngine = (options = {}) => {
       const key = definition.key ?? defaultKey;
       const match = definition.match;
       const tables = definition.tables ?? [collection];
-      const readRule = tables.length === 1 ? readRuleFor(tables[0]) : undefined;
-      const rehydrate = readRule ? async () => [...await definition.hydrate(params, ctx)].filter((row) => readRule(ctx, row)) : async () => definition.hydrate(params, ctx);
+      const scopedTable = tables.length === 1 ? tables[0] : undefined;
+      const readRule = scopedTable !== undefined ? readRuleFor(scopedTable) : undefined;
+      const rehydrate = async () => {
+        const raw = [...await definition.hydrate(params, ctx)];
+        const rows = scopedTable !== undefined ? raw.map((row) => migrateRow(scopedTable, row)) : raw;
+        return readRule ? rows.filter((row) => readRule(ctx, row)) : rows;
+      };
       const incremental = match !== undefined && tables.length === 1;
       const boundMatch = incremental ? (row) => match(row, params, ctx) && (readRule ? readRule(ctx, row) : true) : () => true;
       const view = createMaterializedView({
@@ -1774,9 +1813,11 @@ var createSyncEngine = (options = {}) => {
           throw new UnauthorizedError(`hydrate collection "${collection}"`);
         }
       }
-      const rows = [...await definition.hydrate(params, ctx)];
+      const raw = [...await definition.hydrate(params, ctx)];
       const tables = definition.tables ?? [collection];
-      const readRule = tables.length === 1 ? readRuleFor(tables[0]) : undefined;
+      const scopedTable = tables.length === 1 ? tables[0] : undefined;
+      const rows = scopedTable !== undefined ? raw.map((row) => migrateRow(scopedTable, row)) : raw;
+      const readRule = scopedTable !== undefined ? readRuleFor(scopedTable) : undefined;
       return readRule ? rows.filter((row) => readRule(ctx, row)) : rows;
     },
     applyChange: (table, change) => applyChange(table, change),
@@ -1824,6 +1865,10 @@ var createSyncEngine = (options = {}) => {
     registerPermissions: (table, rules) => {
       permissions.set(table, rules);
     },
+    registerSchema: (table, schema) => {
+      schemas.set(table, schema);
+    },
+    migrate: (table, row) => migrateRow(table, row),
     runMutation: async (name, args, ctx) => {
       const mutation = mutations.get(name);
       if (mutation === undefined) {
@@ -1927,6 +1972,18 @@ var createSyncEngine = (options = {}) => {
     }
   };
 };
+// src/engine/schema.ts
+var defineSchema = (schemas) => schemas;
+var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+var field = {
+  string: (value) => typeof value === "string",
+  number: isFiniteNumber,
+  boolean: (value) => typeof value === "boolean",
+  any: () => true,
+  optional: (inner) => (value) => value === undefined || inner(value),
+  array: (inner) => (value) => Array.isArray(value) && value.every(inner),
+  enum: (...values) => (value) => values.includes(value)
+};
 // src/engine/routes.ts
 var emptyContext = () => ({});
 var hydrateRoute = (engine, collection, resolveContext = emptyContext) => {
@@ -2174,7 +2231,9 @@ export {
   hydrateRoute,
   fromRowChange,
   filterOp,
+  field,
   defineSearchCollection,
+  defineSchema,
   defineSchedule,
   defineReactiveQuery,
   definePermissions,
@@ -2195,8 +2254,9 @@ export {
   chain,
   aggregateOp,
   UnauthorizedError,
+  SchemaError,
   SEARCH_SCORE_FIELD
 };
 
-//# debugId=B0B398375CBCC30B64756E2164756E21
+//# debugId=B040890280D3C67864756E2164756E21
 //# sourceMappingURL=index.js.map