@abloatai/ablo 0.25.0 → 0.27.0

package/dist/mutators/defineMutators.js

@@ -1,27 +1,21 @@
 /**
- * defineMutators — Zero-style custom mutator declaration.
+ * Declares a tree of named custom mutators grouped by model key. Each mutator is
+ * a plain async function that receives `{ tx, args }` and composes any number of
+ * `tx.mutations.*` and `tx.read.*` calls to carry out a named operation, such as
+ * `slides.createWithLayers`.
  *
- * Consumers declare a tree of named mutators grouped by model key. Each
- * mutator is a plain async function that receives `{ tx, args }`. The body
- * composes any number of `tx.mutate.*` / `tx.read.*` calls to implement a
- * named operation (e.g. `slides.createWithLayers`).
- *
- * This file is pure type scaffolding + a pass-through factory. The runtime
- * dispatcher lives in `./Transaction` (the `tx` object) and
- * `../react/useMutators` (the React-side invoker builder). Keeping those
- * concerns separate makes the types trivially inferable at the call site:
- * `defineMutators(schema, { ... })` returns the literal object the consumer
- * wrote, so `typeof mutators` carries every mutator's exact `args`/result
- * signature into `useMutators`.
+ * The function is purely a place for types to anchor and returns its input
+ * unchanged; the runtime that dispatches a mutator lives elsewhere — the
+ * transaction object it receives and the React hook that invokes it. Because
+ * `defineMutators(schema, { ... })` returns the exact object you wrote,
+ * `typeof mutators` carries every mutator's precise `args` and result types
+ * through to wherever they are invoked.
  */
 /**
- * Identity function that forwards the mutators object while constraining its
- * shape against the schema. The `S` generic pins model keys; the `M` generic
- * is `const`-inferred so each mutator's literal signature survives.
- *
- * Pattern mirrors Zero's own `defineMutators` / `createBuilder` — there is
- * no runtime work to do here, it's purely a location for type inference to
- * anchor.
+ * Returns the mutators object unchanged while constraining its shape against the
+ * schema. The `S` generic pins the model keys, and the `M` generic is inferred as
+ * a `const`, so each mutator's literal signature survives. There is no runtime
+ * work here; the function exists purely as a place for type inference to anchor.
  */
 export function defineMutators(_schema, mutators) {
     return mutators;

package/dist/mutators/inverseOp.d.ts

@@ -1,21 +1,18 @@
 /**
- * inverseOp.ts — the reversible-operation model for the undo system,
- * expressed as Zod schemas.
+ * The reversible-operation model for the undo system, expressed as Zod schemas.
  *
- * Why schemas (not bare TS types):
- *   - Single source of truth. The `InverseOp` / `UndoEntry` TypeScript types
- *     are *derived* from these schemas (`z.infer`), so the wire shape and the
- *     static type can't drift.
- *   - A real validation boundary. Inverse ops are stored as plain JSON-shaped
- *     records (model keys + row data) so the undo manager stays schema-agnostic
- *     — it replays them through a strongly-typed transaction it doesn't own.
- *     That JSON boundary is exactly where a runtime check belongs, and is the
- *     seam a future cross-session persistence layer (IndexedDB-backed history)
- *     would deserialize through. `parseUndoEntry` is that gate.
+ * These schemas serve two roles. First, the {@link InverseOp} and
+ * {@link UndoEntry} TypeScript types are derived from them with `z.infer`, so
+ * the runtime shape and the static type stay in step. Second, they form a
+ * validation boundary: an inverse operation is stored as a plain JSON record
+ * (a model key plus row data) so the undo manager can replay it without knowing
+ * your schema. {@link parseUndoEntry} validates an untrusted value at that
+ * boundary — for example, an entry restored from persisted history — before it
+ * re-enters the replay path.
  *
- * The op kinds mirror the mutator surface 1:1 — single (`create`/`update`/
- * `delete`) and batch (`createMany`/`updateMany`/`deleteMany`) — so a recorded
- * entry is symmetric with what was originally invoked.
+ * The operation kinds match the mutator surface one for one — single
+ * (`create`, `update`, `delete`) and batch (`createMany`, `updateMany`,
+ * `deleteMany`) — so a recorded entry mirrors the call that produced it.
  */
 import { z } from 'zod';
 /**

package/dist/mutators/inverseOp.js

@@ -1,21 +1,18 @@
 /**
- * inverseOp.ts — the reversible-operation model for the undo system,
- * expressed as Zod schemas.
+ * The reversible-operation model for the undo system, expressed as Zod schemas.
  *
- * Why schemas (not bare TS types):
- *   - Single source of truth. The `InverseOp` / `UndoEntry` TypeScript types
- *     are *derived* from these schemas (`z.infer`), so the wire shape and the
- *     static type can't drift.
- *   - A real validation boundary. Inverse ops are stored as plain JSON-shaped
- *     records (model keys + row data) so the undo manager stays schema-agnostic
- *     — it replays them through a strongly-typed transaction it doesn't own.
- *     That JSON boundary is exactly where a runtime check belongs, and is the
- *     seam a future cross-session persistence layer (IndexedDB-backed history)
- *     would deserialize through. `parseUndoEntry` is that gate.
+ * These schemas serve two roles. First, the {@link InverseOp} and
+ * {@link UndoEntry} TypeScript types are derived from them with `z.infer`, so
+ * the runtime shape and the static type stay in step. Second, they form a
+ * validation boundary: an inverse operation is stored as a plain JSON record
+ * (a model key plus row data) so the undo manager can replay it without knowing
+ * your schema. {@link parseUndoEntry} validates an untrusted value at that
+ * boundary — for example, an entry restored from persisted history — before it
+ * re-enters the replay path.
  *
- * The op kinds mirror the mutator surface 1:1 — single (`create`/`update`/
- * `delete`) and batch (`createMany`/`updateMany`/`deleteMany`) — so a recorded
- * entry is symmetric with what was originally invoked.
+ * The operation kinds match the mutator surface one for one — single
+ * (`create`, `update`, `delete`) and batch (`createMany`, `updateMany`,
+ * `deleteMany`) — so a recorded entry mirrors the call that produced it.
  */
 import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';

package/dist/mutators/mutateActions.d.ts

@@ -1,15 +1,16 @@
 import type { Schema, InferModel, InferCreate } from '../schema/schema.js';
 import type { SyncStoreContract } from '../react/context.js';
 /**
- * `create` / `update` / `delete` are overloaded: pass one row or an array
- * (Drizzle/Prisma `values(rowOrRows)` shape). Every entry in an array call
- * lands in the same synchronous tick (`Promise.all`), so the microtask
- * coalescer in `TransactionQueue` collapses N pushes into one wire commit.
+ * The create, update, and delete actions for one model. Each action is
+ * overloaded: pass a single row to act on one entity, or an array to act on
+ * many within the same synchronous tick. An array call stages every entry
+ * together through `Promise.all`, so the microtask coalescer in
+ * `TransactionQueue` collapses the whole batch into one commit on the wire.
  *
- * This module is the React-free core of CRUD staging. The transaction system
- * (`Transaction` / `RecordingTransaction`) and `BaseSyncedStore` build on it;
- * there is no React hook here (the legacy `useMutate` hook was removed —
- * callers use `ablo.<model>.create/update/delete`).
+ * These are plain imperative actions with no React dependency. The transaction
+ * system (`Transaction` and `RecordingTransaction`) and `BaseSyncedStore` build
+ * on them, and application code reaches them through `ablo.<model>.create`,
+ * `ablo.<model>.update`, and `ablo.<model>.delete`.
  */
 type UpdatePatch<S extends Schema, K extends keyof S['models'] & string> = {
     id: string;
@@ -39,6 +40,6 @@ export interface MutateActions<S extends Schema, K extends keyof S['models'] & s
     /** Restore an archived entity by ID. */
     unarchive: (id: string) => Promise<void>;
 }
-/** Pure factory — builds CRUD actions over a store for one model. React-free. */
+/** Builds the create, update, and delete actions for one model over a store. */
 export declare function createMutateActions<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K, store: SyncStoreContract, organizationId: string): MutateActions<S, K>;
 export {};

package/dist/mutators/mutateActions.js

@@ -1,6 +1,6 @@
 import { Model, modelAsRow } from '../Model.js';
 import { AbloValidationError } from '../errors.js';
-/** Pure factory — builds CRUD actions over a store for one model. React-free. */
+/** Builds the create, update, and delete actions for one model over a store. */
 export function createMutateActions(schema, modelKey, store, organizationId) {
     const modelDef = schema.models[modelKey];
     const typename = modelDef?.typename ?? modelKey;

package/dist/mutators/readerActions.d.ts

@@ -1,15 +1,16 @@
 import type { Schema, InferModel } from '../schema/schema.js';
 import type { SyncStoreContract } from '../react/context.js';
 /**
- * React-free imperative reads over a store: one-off `retrieve`/`list`/`count`
- * snapshots that do NOT subscribe to changes. Used by the transaction system
- * and `BaseSyncedStore`. For reactive reads in components use
- * `useAblo((ablo) => ablo.<model>.retrieve({ id }) / .list(opts))`.
+ * Imperative, non-reactive reads over a store for one model. The `retrieve`,
+ * `list`, and `count` actions each return a one-time snapshot and do not
+ * subscribe to later changes; the transaction system and `BaseSyncedStore`
+ * build on them. For reactive reads inside a component, read through `useAblo`,
+ * for example `useAblo((ablo) => ablo.<model>.list(options))`.
  */
 export interface ReaderFindOptions<T> {
-    /** Equality filter — uses FK index when the field is registered. */
+    /** Equality filter. Uses a foreign-key index when the field has one registered. */
     where?: Partial<T>;
-    /** Predicate applied AFTER `where` filtering. */
+    /** A predicate applied after the `where` filter. */
     filter?: (entity: T) => boolean;
     /** Sort field. */
     orderBy?: keyof T & string;
@@ -21,12 +22,12 @@ export interface ReaderFindOptions<T> {
     offset?: number;
 }
 export interface ReaderActions<S extends Schema, K extends keyof S['models'] & string> {
-    /** Get a single entity by id. Returns undefined if not in pool. */
+    /** Get a single entity by id, or `undefined` if it is not loaded in the store. */
     retrieve: (id: string) => InferModel<S, K> | undefined;
     /** Read a collection with optional filters. Snapshot — not reactive. */
     list: (options?: ReaderFindOptions<InferModel<S, K>>) => InferModel<S, K>[];
     /** Count entities matching the options. */
     count: (options?: ReaderFindOptions<InferModel<S, K>>) => number;
 }
-/** Pure factory — builds imperative read actions over a store for one model. */
+/** Builds the read actions (`retrieve`, `list`, `count`) for one model over a store. */
 export declare function createReaderActions<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K, store: SyncStoreContract): ReaderActions<S, K>;

package/dist/mutators/readerActions.js

@@ -1,9 +1,9 @@
-/** Pure factory — builds imperative read actions over a store for one model. */
+/** Builds the read actions (`retrieve`, `list`, `count`) for one model over a store. */
 export function createReaderActions(schema, modelKey, store) {
     const modelDef = schema.models[modelKey];
     const typename = modelDef?.typename ?? modelKey;
     function read(options) {
-        // FK index fast path: single-field `where` on a registered FK index → O(1).
+        // Fast path: a single-field `where` on a registered foreign-key index is O(1).
         let candidates;
         const whereEntries = options?.where ? Object.entries(options.where) : [];
         const singleWhere = whereEntries.length === 1 ? whereEntries[0] : undefined;

package/dist/mutators/undoApply.d.ts

@@ -1,43 +1,47 @@
 /**
- * undoApply.ts — conflict-aware resolution of undo/redo ops (per-user undo).
+ * Conflict-aware replay of undo and redo operations, so undo reverts only your
+ * own changes.
  *
- * The undo stack is already per-client (only local mutator invocations call
- * `UndoScope.record`; a collaborator's edits arrive as inbound sync deltas and
- * never land here). What this module adds is the second half of "undo per
- * user": when replaying a recorded op, only touch a field whose CURRENT value
- * still equals what THIS op established — so undo reverts your own change only
- * where it still stands, and never clobbers a field a collaborator changed
- * after you (the Yjs/CRDT "selective undo" principle, adapted to our
- * field-level last-writer-wins model).
+ * The undo stack is already per-client: only your local mutator calls record
+ * onto it through `UndoScope.record`, and a collaborator's edits arrive as
+ * inbound sync deltas that never enter it. This module adds the other half of
+ * per-user undo. When replaying a recorded operation, it touches a field only
+ * if that field's current value still equals the value this operation
+ * established. Undo therefore reverts your change where it still stands and
+ * leaves alone any field a collaborator has since overwritten — selective undo
+ * applied to a field-level, last-writer-wins model.
  *
- * `resolveOps(apply, paired, store, policy)`:
- *   - `apply`  — the ops we're about to replay (inverses on undo, forwards on redo).
- *   - `paired` — their counterparts, carrying the value this op established
- *     (forwards on undo = "what I set"; inverses on redo = "what undo restored").
- *   - For `update`/`updateMany` ops it drops fields whose live value no longer
- *     matches the established value. `create`/`delete` families are structural
- *     and applied unconditionally (undoing your create removes the row you
- *     added; undoing your delete restores it).
+ * {@link resolveOps} does the filtering. It takes the operations about to be
+ * replayed (`apply` — the inverses on undo, the forwards on redo) and their
+ * counterparts (`paired`), which carry the value each operation established: on
+ * undo the forwards say what you set, and on redo the inverses say what undo
+ * restored. For `update` and `updateMany` operations it drops any field whose
+ * live value no longer matches that established value. The `create` and
+ * `delete` families are structural and always applied — undoing a create
+ * removes the row you added, and undoing a delete restores it.
  *
- * With no collaborator, the live value always equals what you set, so nothing
- * is dropped — single-user undo is byte-for-byte unchanged.
+ * When no collaborator is involved, the live value always equals what you set,
+ * so nothing is dropped and single-user undo behaves exactly as before.
  */
 import type { SyncStoreContract } from '../react/context.js';
 import type { InverseOp } from './inverseOp.js';
 import { deepEqual } from '../utils/json.js';
 /**
- * How undo/redo handles a field a collaborator changed after your op:
- *   - `skip-stale` (default): leave it — your change is already superseded, so
- *     reverting it would clobber theirs. This is the per-user guarantee.
- *   - `last-writer-wins`: apply the op verbatim (legacy behavior). Your undo
- *     overwrites their change.
+ * How undo and redo treat a field that a collaborator changed after your
+ * operation.
+ *
+ *   - `skip-stale` (the default): leave the field alone. Your change has
+ *     already been superseded, so reverting it would overwrite the
+ *     collaborator's value. This is what keeps undo scoped to your own edits.
+ *   - `last-writer-wins`: apply the operation verbatim, so your undo overwrites
+ *     the collaborator's change.
  */
 export type UndoConflictPolicy = 'skip-stale' | 'last-writer-wins';
 export declare const DEFAULT_UNDO_CONFLICT_POLICY: UndoConflictPolicy;
 /**
- * Structural equality for JSON-shaped values (scalars, arrays, plain objects).
- * Re-exported from the shared `utils/json` helper (key order is ignored) so the
- * undo path and app authors share one implementation.
+ * Structural equality for JSON-shaped values — scalars, arrays, and plain
+ * objects — ignoring object key order. Re-exported from the package's shared
+ * JSON helper so the undo path and your own code can share one implementation.
  */
 export { deepEqual };
 /**

package/dist/mutators/undoApply.js

@@ -1,33 +1,34 @@
 /**
- * undoApply.ts — conflict-aware resolution of undo/redo ops (per-user undo).
+ * Conflict-aware replay of undo and redo operations, so undo reverts only your
+ * own changes.
  *
- * The undo stack is already per-client (only local mutator invocations call
- * `UndoScope.record`; a collaborator's edits arrive as inbound sync deltas and
- * never land here). What this module adds is the second half of "undo per
- * user": when replaying a recorded op, only touch a field whose CURRENT value
- * still equals what THIS op established — so undo reverts your own change only
- * where it still stands, and never clobbers a field a collaborator changed
- * after you (the Yjs/CRDT "selective undo" principle, adapted to our
- * field-level last-writer-wins model).
+ * The undo stack is already per-client: only your local mutator calls record
+ * onto it through `UndoScope.record`, and a collaborator's edits arrive as
+ * inbound sync deltas that never enter it. This module adds the other half of
+ * per-user undo. When replaying a recorded operation, it touches a field only
+ * if that field's current value still equals the value this operation
+ * established. Undo therefore reverts your change where it still stands and
+ * leaves alone any field a collaborator has since overwritten — selective undo
+ * applied to a field-level, last-writer-wins model.
  *
- * `resolveOps(apply, paired, store, policy)`:
- *   - `apply`  — the ops we're about to replay (inverses on undo, forwards on redo).
- *   - `paired` — their counterparts, carrying the value this op established
- *     (forwards on undo = "what I set"; inverses on redo = "what undo restored").
- *   - For `update`/`updateMany` ops it drops fields whose live value no longer
- *     matches the established value. `create`/`delete` families are structural
- *     and applied unconditionally (undoing your create removes the row you
- *     added; undoing your delete restores it).
+ * {@link resolveOps} does the filtering. It takes the operations about to be
+ * replayed (`apply` — the inverses on undo, the forwards on redo) and their
+ * counterparts (`paired`), which carry the value each operation established: on
+ * undo the forwards say what you set, and on redo the inverses say what undo
+ * restored. For `update` and `updateMany` operations it drops any field whose
+ * live value no longer matches that established value. The `create` and
+ * `delete` families are structural and always applied — undoing a create
+ * removes the row you added, and undoing a delete restores it.
  *
- * With no collaborator, the live value always equals what you set, so nothing
- * is dropped — single-user undo is byte-for-byte unchanged.
+ * When no collaborator is involved, the live value always equals what you set,
+ * so nothing is dropped and single-user undo behaves exactly as before.
  */
 import { deepEqual } from '../utils/json.js';
 export const DEFAULT_UNDO_CONFLICT_POLICY = 'skip-stale';
 /**
- * Structural equality for JSON-shaped values (scalars, arrays, plain objects).
- * Re-exported from the shared `utils/json` helper (key order is ignored) so the
- * undo path and app authors share one implementation.
+ * Structural equality for JSON-shaped values — scalars, arrays, and plain
+ * objects — ignoring object key order. Re-exported from the package's shared
+ * JSON helper so the undo path and your own code can share one implementation.
  */
 export { deepEqual };
 /**
@@ -67,8 +68,9 @@ function filterStalePatch(store, patch, established) {
         if (field === 'id')
             continue;
         if (established && field in established) {
-            // Apply only if the field still holds the value WE established — i.e. no
-            // collaborator overwrote it since. Otherwise skip (don't clobber them).
+            // Apply only if the field still holds the value we established, meaning no
+            // collaborator has overwritten it since. Otherwise skip it, so the
+            // collaborator's change is left intact.
             if (deepEqual(readCurrentField(store, patch.id, field), established[field])) {
                 out[field] = patch[field];
                 kept++;

package/dist/policy/index.d.ts

@@ -1,8 +1,10 @@
 /**
- * @abloatai/ablo/policy — pluggable conflict resolution.
+ * Pluggable conflict resolution.
  *
- * The engine detects conflicts; the policy decides. Customer code
- * implements `ConflictPolicy` and registers it at the sync-server.
+ * The engine detects a conflict; a policy decides what to do about it. You
+ * implement {@link ConflictPolicy} and register it with the engine on your
+ * server. The example below allows writes from a cosmetic "linter" writer and
+ * defers everything else to {@link defaultPolicy}.
  *
  * ```ts
  * import { type ConflictPolicy, defaultPolicy } from '@abloatai/ablo/policy';

package/dist/policy/index.js

@@ -1,8 +1,10 @@
 /**
- * @abloatai/ablo/policy — pluggable conflict resolution.
+ * Pluggable conflict resolution.
  *
- * The engine detects conflicts; the policy decides. Customer code
- * implements `ConflictPolicy` and registers it at the sync-server.
+ * The engine detects a conflict; a policy decides what to do about it. You
+ * implement {@link ConflictPolicy} and register it with the engine on your
+ * server. The example below allows writes from a cosmetic "linter" writer and
+ * defers everything else to {@link defaultPolicy}.
  *
  * ```ts
  * import { type ConflictPolicy, defaultPolicy } from '@abloatai/ablo/policy';