@abloatai/humans 0.37.0

package/dist/local/mutators/Transaction.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The typed transaction object passed to a custom mutator. A mutator receives
+ * `{ tx, args }` and uses `tx.mutations.<modelKey>.*` to write and
+ * `tx.read.<modelKey>.*` to take synchronous snapshots of the current data.
+ *
+ * Writes are applied eagerly as they are called, with no buffering: if a mutator
+ * throws partway through, the writes it already made stand. Reads are synchronous
+ * snapshots and use a fast index lookup where one is available for the field.
+ *
+ * The write surface deliberately works one row at a time. To write a batch,
+ * compose the calls yourself — `Promise.all(rows.map((r) => tx.mutations.x.create(r)))`.
+ * Every call stages its write in the same synchronous tick and the engine
+ * coalesces them into a single commit on the wire, so there is no separate
+ * bulk-insert method to learn.
+ */
+import type { Schema } from '@abloatai/transaction/schema/schema';
+import type { SyncStoreContract } from '../storeContract.js';
+import { type MutateActions } from './mutateActions.js';
+import { type ReaderActions, type ReaderFindOptions } from './readerActions.js';
+/**
+ * The full transaction surface: `tx.mutations.<key>.*` for writes and
+ * `tx.read.<key>.*` for reads. It also re-exports the read-options type so a
+ * mutator author can type a `where` payload without importing it separately. The
+ * property is named `mutations` to match the corresponding React hook.
+ */
+export interface Transaction<S extends Schema> {
+    mutations: {
+        [K in keyof S['models'] & string]: MutateActions<S, K>;
+    };
+    read: {
+        [K in keyof S['models'] & string]: ReaderActions<S, K>;
+    };
+}
+export type { ReaderFindOptions };
+/**
+ * Builds a {@link Transaction} for a single mutator invocation. The returned
+ * object creates each model's actions lazily on first access, so a mutator pays
+ * nothing for the models it never touches.
+ */
+export declare function createTransaction<S extends Schema>(schema: S, store: SyncStoreContract, organizationId: string): Transaction<S>;

package/dist/local/mutators/Transaction.js

@@ -0,0 +1,58 @@
+/**
+ * The typed transaction object passed to a custom mutator. A mutator receives
+ * `{ tx, args }` and uses `tx.mutations.<modelKey>.*` to write and
+ * `tx.read.<modelKey>.*` to take synchronous snapshots of the current data.
+ *
+ * Writes are applied eagerly as they are called, with no buffering: if a mutator
+ * throws partway through, the writes it already made stand. Reads are synchronous
+ * snapshots and use a fast index lookup where one is available for the field.
+ *
+ * The write surface deliberately works one row at a time. To write a batch,
+ * compose the calls yourself — `Promise.all(rows.map((r) => tx.mutations.x.create(r)))`.
+ * Every call stages its write in the same synchronous tick and the engine
+ * coalesces them into a single commit on the wire, so there is no separate
+ * bulk-insert method to learn.
+ */
+import { createMutateActions } from './mutateActions.js';
+import { createReaderActions } from './readerActions.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+/**
+ * Builds a {@link Transaction} for a single mutator invocation. The returned
+ * object creates each model's actions lazily on first access, so a mutator pays
+ * nothing for the models it never touches.
+ */
+export function createTransaction(schema, store, organizationId) {
+    const mutateCache = new Map();
+    const readCache = new Map();
+    const mutations = new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== 'string')
+                return undefined;
+            const cached = mutateCache.get(prop);
+            if (cached)
+                return cached;
+            if (!(prop in schema.models)) {
+                throw new AbloValidationError(`Transaction.mutations: unknown model key "${prop}". Known keys: ${Object.keys(schema.models).join(', ')}`, { code: 'transaction_mutate_unknown_model' });
+            }
+            const actions = createMutateActions(schema, prop, store, organizationId);
+            mutateCache.set(prop, actions);
+            return actions;
+        },
+    });
+    const read = new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== 'string')
+                return undefined;
+            const cached = readCache.get(prop);
+            if (cached)
+                return cached;
+            if (!(prop in schema.models)) {
+                throw new AbloValidationError(`Transaction.read: unknown model key "${prop}". Known keys: ${Object.keys(schema.models).join(', ')}`, { code: 'transaction_read_unknown_model' });
+            }
+            const actions = createReaderActions(schema, prop, store);
+            readCache.set(prop, actions);
+            return actions;
+        },
+    });
+    return { mutations, read };
+}

package/dist/local/mutators/UndoManager.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Keeps a per-scope history of reversible changes so a surface can offer undo
+ * and redo. Each mutator invocation records an ordered list of inverse
+ * operations; `undo()` pops the most recent group and replays those inverses
+ * without recording them, then moves the entry onto the redo stack.
+ *
+ * History is divided into named scopes, one per surface — a report editor, a
+ * ledger grid, and so on — reached through {@link UndoManager.getScope}. Undo in
+ * one surface never affects another.
+ *
+ * Two things to know about its reach. History lives in memory and does not
+ * persist across sessions. And if the server rejects a change after it was
+ * applied optimistically, the undo stack is not invalidated automatically; call
+ * {@link UndoScope.clear} on a sync error if you need strict correctness.
+ */
+import type { Schema } from '@abloatai/transaction/schema/schema';
+import type { SyncStoreContract } from '../storeContract.js';
+import { type InverseOp, type UndoEntry } from './inverseOp.js';
+import { type UndoConflictPolicy } from './undoApply.js';
+export type { InverseOp, UndoEntry };
+export type { UndoConflictPolicy } from './undoApply.js';
+export interface UndoScopeOptions {
+    /** The maximum number of undo entries to keep. Older entries drop off the
+     *  bottom. Defaults to 100. */
+    maxHistory?: number;
+    /**
+     * How undo and redo treat a field a collaborator changed after your own
+     * change. The default, `skip-stale`, reverts your change only where it still
+     * stands, so undo never overwrites a concurrent edit — undo is per user.
+     * `last-writer-wins` restores the older behavior of overwriting regardless. See
+     * {@link UndoConflictPolicy}.
+     */
+    conflictPolicy?: UndoConflictPolicy;
+    /**
+     * A predicate selecting which models this surface owns. The scope records only
+     * mutations whose resolved schema key passes it, so, for example, a ledger
+     * edit never lands on a report editor's undo stack. Omit it to track every model,
+     * which is fine for a single-surface app but wrong when two surfaces with
+     * independent undo share one store.
+     */
+    tracksModel?: (schemaKey: string) => boolean;
+    /**
+     * When `true`, the scope records undo entries by observing the stream of local
+     * mutations, so every write through the store is captured automatically. When
+     * `false`, the default, the scope records nothing on its own and relies on
+     * explicit {@link UndoScope.record} calls. Use one mode or the other for a given
+     * surface, not both, or shared writes are counted twice.
+     */
+    recordFromStream?: boolean;
+}
+export declare class UndoScope<S extends Schema> {
+    private readonly schema;
+    private readonly store;
+    private readonly organizationId;
+    private undoStack;
+    private redoStack;
+    private readonly maxHistory;
+    private readonly conflictPolicy;
+    /**
+     * Observers notified after each successful {@link UndoScope.record}. They see
+     * forward user actions only: undo and redo move entries between the stacks
+     * without calling `record`, so a listener never observes a reversal. It is a
+     * deliberately generic hook — analytics or audit code can watch the stream of
+     * committed mutations without the scope knowing about it. A listener that throws
+     * is isolated so it cannot break recording.
+     */
+    private readonly recordListeners;
+    /**
+     * Observers notified after any stack change — record, undo, redo, or clear.
+     * Unlike {@link recordListeners}, which fires on forward actions only, this
+     * fires on reversals too, so a React consumer can keep `canUndo` and `canRedo`
+     * current. Because the stream-recording path adds entries without triggering a
+     * render, a component that read `canUndo` on its last render would otherwise go
+     * stale and a keyboard handler gated on it would quietly do nothing.
+     */
+    private readonly changeListeners;
+    /**
+     * The serialization tail. Recording, undo, and redo all chain off this one
+     * promise, so they run strictly in the order they were invoked and never
+     * interleave. This matters for correctness, not just throughput, in two ways.
+     * Ordering: callers often fire writes without awaiting them, so without
+     * serialization an entry would land on the stack when its mutator resolves, and
+     * a fast second write could record before a slow first — replaying undo in the
+     * wrong order. Snapshot integrity: each recording reads and clears a model's
+     * modified-field markers, which form the undo baseline, so two recordings
+     * interleaving on the same model would corrupt each other's before-image.
+     * Serializing the whole scope closes both gaps at once.
+     */
+    private tail;
+    /** Predicate selecting which models this surface records (see options). */
+    private readonly tracksModel?;
+    /** registered-name / alias → schema key, built once from the schema. */
+    private readonly schemaKeyByAlias;
+    /** Unsubscribe from the local-mutation stream. */
+    private readonly unsubscribe;
+    /**
+     * True while undo or redo is replaying operations. A replay writes through the
+     * normal commit path and therefore re-emits on the local-mutation stream; this
+     * flag tells the scope's own listener to ignore those writes so they are not
+     * recorded again.
+     */
+    private replaying;
+    /** Operations collected during the current tick, flushed together as one entry. */
+    private batch;
+    private flushScheduled;
+    /**
+     * An open grouping session. While set, stream operations accumulate here across
+     * ticks instead of flushing each tick, so a multi-tick action — a drag, or a
+     * whole streaming AI response — collapses into a single undo step.
+     * {@link UndoScope.endGroup} flushes it.
+     */
+    private group;
+    /**
+     * Suppression of a replay's asynchronous echo, keyed by `${modelKey}:${id}`.
+     *
+     * The synchronous {@link UndoScope.replaying} flag catches only echoes
+     * delivered inline while operations are applied. In practice the engine does not
+     * emit a replayed write's echo synchronously: the commit is deferred behind a
+     * local-store write, so the echo arrives on the stream after undo or redo has
+     * already reset `replaying` and pushed its entry. That late echo would be
+     * recorded as a new edit — and recording clears the redo stack, so every undo
+     * would quietly destroy its own redo. To prevent that, the row of each operation
+     * about to be replayed is marked here synchronously, before the write, and one
+     * mark is consumed when the matching mutation arrives, whenever that is. Marks
+     * carry a time-to-live so an echo that never arrives — because the write was
+     * skipped while offline — cannot linger and wrongly suppress a much later, real
+     * edit to the same row.
+     */
+    private readonly pendingReplayEchoes;
+    constructor(schema: S, store: SyncStoreContract, organizationId: string, options?: UndoScopeOptions);
+    /**
+     * Opens a grouping session: every stream-recorded operation until
+     * {@link UndoScope.endGroup} collapses into one undo entry. Call it at the start
+     * of a gesture, such as a pointer-down, or at the start of an AI response. A
+     * second call closes the previous group first.
+     */
+    beginGroup(label?: string): void;
+    /** Close the grouping session and record the accumulated ops as one entry. */
+    endGroup(label?: string): void;
+    /** Every `${modelKey}:${id}` a set of ops will touch (all op kinds). */
+    private replayEchoKeys;
+    /**
+     * Arms echo suppression for the rows a replay is about to write. Called
+     * synchronously, before the writes, so the marks exist however long the engine
+     * takes to surface each echo on the stream. See {@link UndoScope.pendingReplayEchoes}.
+     */
+    private markReplayEchoes;
+    /**
+     * If `${schemaKey}:${modelId}` has an armed mark, consume one and report that
+     * this mutation is the scope's own replay echo, so the caller drops it. Expired
+     * marks are pruned along the way, so an echo that never arrives cannot linger.
+     */
+    private consumeReplayEcho;
+    /** Resolve a stream mutation's registered name to its schema key, or null. */
+    private resolveSchemaKey;
+    /**
+     * The stream listener, and the only place stream-recorded entries originate. It
+     * skips replay echoes and out-of-scope models, derives the forward and inverse
+     * operations from the mutation's `data` and `previousData`, and defers the stack
+     * push to a per-tick flush, so a burst of writes — aligning five blocks at once,
+     * say — becomes a single undo step.
+     */
+    private onLocalMutation;
+    private scheduleFlush;
+    /** Coalesce the tick's collected ops into one entry and record it. */
+    private flushBatch;
+    /**
+     * Run `work` after every previously-enqueued scope operation has settled,
+     * in invocation order. The internal `tail` always resolves (failures are
+     * swallowed *for the chain only*) so one rejected mutator can't wedge the
+     * queue; the original settlement is still surfaced to this call's caller.
+     */
+    private enqueue;
+    /**
+     * Runs a recording mutator by itself on the scope's serialization chain, so its
+     * snapshot, write, and {@link UndoScope.record} happen atomically with respect to
+     * undo and redo. This is used by the explicit-record path; the stream-recording
+     * path does not need it, since it derives entries from already-committed
+     * mutations.
+     */
+    runRecorded<T>(work: () => Promise<T>): Promise<T>;
+    /**
+     * Records one entry onto the undo stack and clears the redo stack. It is fed
+     * both by the per-tick flush and grouping paths from the local-mutation stream
+     * and by direct callers using explicit recording. Entries are built internally
+     * and therefore trusted, so the schema check here runs only outside production:
+     * it catches recorder bugs early, rejecting a malformed operation at ingestion
+     * with a clear path rather than letting it fail later during replay, without
+     * paying a validation cost on every user action in production. The real
+     * validation boundary is {@link parseUndoEntry}, applied to entries loaded from
+     * persistence, which is untrusted input.
+     */
+    record(entry: UndoEntry): void;
+    /**
+     * Subscribes to every recorded mutation. The listener fires synchronously at the
+     * end of each {@link UndoScope.record} call, once the entry is on the undo stack,
+     * and the returned function unsubscribes it. The listener receives the full
+     * {@link UndoEntry} — its `forwards` carry the `{ kind, modelKey, data }`
+     * operations — so a consumer can tell what changed without querying again.
+     */
+    onRecord(listener: (entry: UndoEntry) => void): () => void;
+    private emitRecord;
+    /**
+     * Subscribes to any stack change — record, undo, redo, or clear. The React
+     * `useUndoScope` hook uses this to re-render so `canUndo` and `canRedo` stay
+     * current for every consumer, not only the component that invoked undo or redo.
+     * The returned function unsubscribes.
+     */
+    onChange(listener: () => void): () => void;
+    private emitChange;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /**
+     * Pops the most recent entry, applies its inverse operations, and pushes it onto
+     * the redo stack. Under the default `skip-stale` policy the inverses are first
+     * filtered against the current state — paired with the entry's forwards, which
+     * record what this change set — so a field a collaborator changed afterward is
+     * left untouched, and undo reverts the change only where it still stands.
+     */
+    undo(): Promise<void>;
+    /**
+     * Pops the most recently undone entry, re-applies its forward operations, and
+     * pushes it onto the undo stack. It mirrors {@link UndoScope.undo}: the forwards
+     * are filtered against the current state — paired with the entry's inverses,
+     * which record what undo restored — so redo re-asserts the change only where the
+     * undone value still stands.
+     */
+    redo(): Promise<void>;
+    /** Drop all history. Use after bootstrap / sync group change / sync error. */
+    clear(): void;
+    /** Introspection — for debug panels / e2e tests. */
+    size(): {
+        undo: number;
+        redo: number;
+    };
+    /**
+     * Detach from the local-mutation stream and drop listeners. Scopes are
+     * cached for the store's lifetime by `UndoManager`, so this is mainly for
+     * tests and explicit teardown.
+     */
+    dispose(): void;
+}
+/**
+ * The registry of named undo scopes. One instance is created per application
+ * during engine setup, and each surface finds its scope by name through
+ * {@link UndoManager.getScope}.
+ */
+export declare class UndoManager<S extends Schema> {
+    private readonly schema;
+    private readonly store;
+    private readonly organizationId;
+    private readonly scopes;
+    /** The options each scope was constructed with, for the mismatch warning below. */
+    private readonly creationOptions;
+    constructor(schema: S, store: SyncStoreContract, organizationId: string);
+    getScope(name: string, options?: UndoScopeOptions): UndoScope<S>;
+    clearAll(): void;
+}