@abloatai/ablo 0.35.0 → 0.37.0

package/dist/mutators/undoApply.js

@@ -1,117 +0,0 @@
-/**
- * Conflict-aware replay of undo and redo operations, so undo reverts only your
- * own changes.
- *
- * 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.
- *
- * {@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.
- *
- * 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 '../transaction/utils/json.js';
-export const DEFAULT_UNDO_CONFLICT_POLICY = 'skip-stale';
-/**
- * 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 };
-/**
- * Map `id → { field: establishedValue }` from the paired ops. Only update-family
- * ops carry per-field values worth comparing.
- */
-function buildEstablished(paired) {
-    const map = new Map();
-    for (const op of paired) {
-        if (op.kind === 'update') {
-            map.set(op.patch.id, op.patch);
-        }
-        else if (op.kind === 'updateMany') {
-            for (const p of op.patches)
-                map.set(p.id, p);
-        }
-    }
-    return map;
-}
-/** Read the live value of a field from the store's pool, or `undefined`. */
-function readCurrentField(store, id, field) {
-    const model = store.pool.get(id);
-    if (!model)
-        return undefined;
-    const json = model.toJSON?.();
-    return json ? json[field] : undefined;
-}
-/**
- * Keep only the fields whose live value still equals what this op established
- * (`established[field]`). Returns `null` if nothing survives (the whole op is a
- * no-op — every field was superseded by a collaborator).
- */
-function filterStalePatch(store, patch, established) {
-    const out = { id: patch.id };
-    let kept = 0;
-    for (const field of Object.keys(patch)) {
-        if (field === 'id')
-            continue;
-        if (established && field in established) {
-            // 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++;
-            }
-        }
-        else {
-            // No paired value to compare against. The recorder always pairs fields,
-            // so this is theoretical; apply to preserve undo functionality.
-            out[field] = patch[field];
-            kept++;
-        }
-    }
-    return kept > 0 ? out : null;
-}
-/**
- * Filter the ops to apply so they don't clobber concurrent collaborator edits.
- * See the module docblock. `last-writer-wins` returns the ops unchanged.
- */
-export function resolveOps(apply, paired, store, policy) {
-    if (policy === 'last-writer-wins')
-        return apply;
-    const established = buildEstablished(paired);
-    const out = [];
-    for (const op of apply) {
-        if (op.kind === 'update') {
-            const filtered = filterStalePatch(store, op.patch, established.get(op.patch.id));
-            if (filtered)
-                out.push({ kind: 'update', modelKey: op.modelKey, patch: filtered });
-        }
-        else if (op.kind === 'updateMany') {
-            const patches = op.patches
-                .map((p) => filterStalePatch(store, p, established.get(p.id)))
-                .filter((p) => p !== null);
-            if (patches.length > 0) {
-                out.push({ kind: 'updateMany', modelKey: op.modelKey, patches });
-            }
-        }
-        else {
-            // create / createMany / delete / deleteMany — structural, applied as-is.
-            out.push(op);
-        }
-    }
-    return out;
-}

package/dist/policy/index.d.ts

@@ -1,21 +0,0 @@
-/**
- * Pluggable conflict resolution.
- *
- * 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';
- *
- * export const myPolicy: ConflictPolicy = (ctx) => {
- *   if (ctx.committer.id.startsWith('linter:')) {
- *     return { action: 'allow', note: 'cosmetic writer' };
- *   }
- *   return defaultPolicy(ctx);
- * };
- * ```
- */
-export type { Conflict, ConflictAxis, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, ClaimHeldConflict, } from '../transaction/policy/types.js';
-export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../transaction/policy/types.js';

package/dist/policy/index.js

@@ -1,20 +0,0 @@
-/**
- * Pluggable conflict resolution.
- *
- * 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';
- *
- * export const myPolicy: ConflictPolicy = (ctx) => {
- *   if (ctx.committer.id.startsWith('linter:')) {
- *     return { action: 'allow', note: 'cosmetic writer' };
- *   }
- *   return defaultPolicy(ctx);
- * };
- * ```
- */
-export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../transaction/policy/types.js';

package/dist/query/client.d.ts

@@ -1,61 +0,0 @@
-/**
- * The HTTP client for the sync query endpoint.
- *
- * {@link postQuery} is a small wrapper over `fetch` that POSTs a
- * {@link QueryBatch} as JSON to `/sync/query`, attaches the bearer credential
- * as an `Authorization` header, and parses the response into a typed
- * {@link QueryBatchResult}. An HTTP failure is not thrown: it is logged, and
- * every query in the batch comes back with an empty result, so a
- * fire-and-forget caller cannot crash on an unhandled rejection.
- *
- * Higher-level query helpers build on this to issue structured queries without
- * repeating the fetch and error-handling boilerplate.
- */
-import type { QueryBatch, QueryBatchResult } from './types.js';
-import { type RecoveryClass } from '../transaction/errorCodes.js';
-import { type AuthTokenGetter } from '../transaction/auth/credentialSource.js';
-export interface PostQueryOptions {
-    /**
-     * Full base URL of the sync server including the `/api` prefix.
-     * The query endpoint is appended as `/sync/query`, so the final
-     * request hits `${baseUrl}/sync/query`.
-     */
-    baseUrl: string;
-    /** Timeout in ms for the fetch request. Default: 30000. */
-    fetchTimeout?: number;
-    /**
-     * Live bearer credential getter. Preferred over `capabilityToken` because it
-     * is read per request, so token refreshes propagate without reconstructing
-     * query helpers.
-     */
-    getAuthToken?: AuthTokenGetter;
-    /**
-     * A fixed credential string, for callers that hold only a copied token.
-     * Prefer `getAuthToken`, which is re-read on each request so a refresh takes
-     * effect without rebuilding the client.
-     */
-    capabilityToken?: string;
-    /**
-     * An optional hook that tries to recover from a rejected credential. When a
-     * query comes back with a 401, its {@link RecoveryClass} is passed here: a
-     * return of `'retry'` means a fresh credential has been obtained and the
-     * request is replayed exactly once, while `'stop'` ends the attempt. Because
-     * the replay happens at most once, a wedged credential cannot cause a retry
-     * loop. When this hook is absent, a 401 is logged and returns empty results
-     * like any other failure.
-     */
-    recoverCredential?: (recovery: RecoveryClass) => Promise<'retry' | 'stop'>;
-}
-/**
- * Sends a batch of queries to `/sync/query` and returns the parsed
- * {@link QueryBatchResult}. An HTTP failure is not thrown: it is logged, and
- * every query in the batch comes back with an empty result, which keeps a
- * fire-and-forget caller from crashing on an unhandled rejection. A 401 may
- * first be handed to {@link PostQueryOptions.recoverCredential} for a single
- * retry.
- *
- * The response preserves order: `results[i]` corresponds to the query at
- * `queries[i]`, so callers can rely on index alignment to pull typed results
- * out of a multi-query batch.
- */
-export declare function postQuery(options: PostQueryOptions, batch: QueryBatch): Promise<QueryBatchResult>;

package/dist/query/client.js

@@ -1,137 +0,0 @@
-/**
- * The HTTP client for the sync query endpoint.
- *
- * {@link postQuery} is a small wrapper over `fetch` that POSTs a
- * {@link QueryBatch} as JSON to `/sync/query`, attaches the bearer credential
- * as an `Authorization` header, and parses the response into a typed
- * {@link QueryBatchResult}. An HTTP failure is not thrown: it is logged, and
- * every query in the batch comes back with an empty result, so a
- * fire-and-forget caller cannot crash on an unhandled rejection.
- *
- * Higher-level query helpers build on this to issue structured queries without
- * repeating the fetch and error-handling boilerplate.
- */
-import { z } from 'zod';
-import { translateHttpError } from '../transaction/errors.js';
-import { classifyRecovery } from '../transaction/errorCodes.js';
-import { withAuthHeaders } from '../transaction/auth/credentialSource.js';
-import { getContext } from '../context.js';
-// ── Response validation ─────────────────────────────────────────────────
-//
-// Each result slot is an array of rows, or an object for a bundled response.
-// A per-query failure on the server surfaces here as an empty array rather
-// than an error, so emptiness alone does not distinguish "no rows" from
-// "the query failed." Parsing through Zod normalizes a `null` slot into an
-// empty array, so callers never receive a raw null.
-const QueryResultSchema = z
-    .union([z.array(z.unknown()), z.record(z.string(), z.unknown()), z.null()])
-    .transform((val) => {
-    if (val === null)
-        return [];
-    return val;
-});
-const QueryBatchResultSchema = z
-    .object({
-    results: z.array(QueryResultSchema),
-})
-    .loose();
-/**
- * Sends a batch of queries to `/sync/query` and returns the parsed
- * {@link QueryBatchResult}. An HTTP failure is not thrown: it is logged, and
- * every query in the batch comes back with an empty result, which keeps a
- * fire-and-forget caller from crashing on an unhandled rejection. A 401 may
- * first be handed to {@link PostQueryOptions.recoverCredential} for a single
- * retry.
- *
- * The response preserves order: `results[i]` corresponds to the query at
- * `queries[i]`, so callers can rely on index alignment to pull typed results
- * out of a multi-query batch.
- */
-export async function postQuery(options, batch) {
-    const url = `${options.baseUrl}/sync/query`;
-    const timeout = options.fetchTimeout ?? 30_000;
-    // At most two attempts: the original request, plus one replay after a
-    // successful credential recovery (see `recoverCredential`). A second auth
-    // rejection falls through to the log-and-empty path, so a wedged credential
-    // can never retry-loop.
-    for (let attempt = 0;; attempt++) {
-        // Race the fetch against a timeout so hung requests don't block
-        // the calling helper indefinitely. Fresh controller per attempt.
-        const controller = new AbortController();
-        const timer = setTimeout(() => { controller.abort(); }, timeout);
-        try {
-            // Recomputed per attempt: `withAuthHeaders` reads the live credential
-            // source, so a replay after recovery carries the freshly-minted key.
-            const headers = withAuthHeaders(options.getAuthToken, { 'Content-Type': 'application/json' }, options.capabilityToken);
-            const response = await fetch(url, {
-                method: 'POST',
-                headers,
-                body: JSON.stringify(batch),
-                signal: controller.signal,
-            });
-            if (!response.ok) {
-                // Build the typed AbloError for this HTTP failure (the same
-                // code-to-class map the throwing paths use) so the log carries a
-                // registry `code` — for example an authentication error with
-                // `session_expired` on a 401 — rather than a bare status. This path
-                // deliberately does not throw, since a fire-and-forget caller could
-                // crash on an unhandled rejection. It returns empty slots while still
-                // logging a legible Ablo error.
-                let body = null;
-                try {
-                    body = await response.clone().json();
-                }
-                catch {
-                    // non-JSON error page — translateHttpError falls back to status text
-                }
-                const err = translateHttpError(response.status, body);
-                // On a 401, hand the failure to the recovery hook once. The recovery
-                // class routes the outcome: an expired access credential is re-minted
-                // and the request replays; a lost session is terminal and stops here;
-                // anything else stops. A bare 401 with no readable code is treated as
-                // an expired access credential, so the only terminal path is the
-                // re-mint itself coming back empty, never an ambiguous status.
-                if (attempt === 0 && response.status === 401 && options.recoverCredential) {
-                    const recovery = typeof err.code === 'string'
-                        ? classifyRecovery(err.code)
-                        : 'access_credential_expiry';
-                    const outcome = await options.recoverCredential(recovery);
-                    if (outcome === 'retry') {
-                        getContext().logger.debug('[postQuery] credential recovered — replaying query once', {
-                            code: err.code ?? response.status,
-                        });
-                        continue;
-                    }
-                }
-                // Logged through the level-gated logger, so it honors ABLO_LOG_LEVEL:
-                // a `warn` line the app developer can read (the models, the typed
-                // message, and a wire `code`), with the forensic detail on a companion
-                // `debug` line. The read stays empty until the underlying cause, such
-                // as auth or network, is resolved.
-                const models = batch.queries.map((q) => q.model).join(', ');
-                getContext().logger.warn(`Could not load ${models} — ${err.message} (code: ${err.code ?? response.status}). No results were returned.`);
-                getContext().logger.debug('[postQuery.error] query http failure', {
-                    type: err.type,
-                    code: err.code ?? response.status,
-                    models,
-                    message: err.message,
-                });
-                return { results: batch.queries.map(() => []) };
-            }
-            const raw = await response.json();
-            const parsed = QueryBatchResultSchema.safeParse(raw);
-            if (!parsed.success) {
-                // A malformed server response isn't something the consumer can act on
-                // (server/protocol issue) → debug, gated like everything else.
-                getContext().logger.debug('[postQuery.error] malformed response', {
-                    issues: parsed.error.issues,
-                });
-                return { results: batch.queries.map(() => []) };
-            }
-            return parsed.data;
-        }
-        finally {
-            clearTimeout(timer);
-        }
-    }
-}

package/dist/query/types.d.ts

@@ -1,85 +0,0 @@
-/**
- * Structured query types for the `/sync/query` endpoint.
- *
- * A query describes a filtered read in a compact wire format. `where` is a flat
- * list of `[column, operator, value]` conditions combined with AND, and
- * `related` names the schema relations to fetch alongside each row. The server
- * compiles a query against your schema: it reads the model's relation metadata
- * to turn `related: ['blocks']` into the right join, and turns each condition
- * into a WHERE fragment. The protocol carries no model-specific logic, so
- * adding a model or relation is a schema change rather than a server change.
- *
- * The `IN` operator lets you batch a read by any column, including a foreign
- * key — for example, fetching every block whose `sectionId` falls in a set of
- * ids.
- */
-export type { WherePrimitive, WhereOp, WhereClause, LoadWhere, } from '../transaction/resources/where.js';
-import type { WhereClause } from '../transaction/resources/where.js';
-/** A single structured fetch request. */
-export interface Query {
-    /**
-     * Client-facing model name (e.g. "File", "Block", "Message").
-     * The server's adapter maps this to the actual database table.
-     */
-    model: string;
-    /**
-     * The conditions to filter by, combined with AND. Empty or omitted returns
-     * every row the caller may see; reads are still scoped to the caller's
-     * organization on the server. Use `['col', 'IN', values]` to batch a read by
-     * any column.
-     */
-    where?: readonly WhereClause[];
-    /**
-     * The relations to fetch with each row, named as they are declared on this
-     * model in the schema. The server resolves each name from the schema's
-     * relation metadata and joins the related rows in. They come back nested
-     * under the relation key:
-     *
-     *   { __typename: 'Section', id: '…', blocks: [{ __typename: 'Block', … }] }
-     */
-    related?: readonly string[];
-    /**
-     * Row limit. Applied after where + JOIN, before related nesting.
-     * Omit for no limit.
-     */
-    limit?: number;
-    /**
-     * Column to order by. For stable pagination. Omit for unordered.
-     */
-    orderBy?: string;
-    /** Order direction. Defaults to `'asc'`. */
-    order?: 'asc' | 'desc';
-}
-/** Request body for POST /sync/query. */
-export interface QueryBatch {
-    /**
-     * Batch of queries to execute in one round trip. Results are
-     * returned in request order at the same indices. Keep batches
-     * small — the server caps at 16 queries per batch by default.
-     */
-    queries: Query[];
-}
-/** Response body from POST /sync/query. */
-export interface QueryBatchResult {
-    /**
-     * The result of each query, in request order: `results[i]` corresponds to
-     * `queries[i]`. Each element is an array of rows, or an object bundling
-     * several named row collections when the source returns more than one. Every
-     * row carries a `__typename` field naming its model, so callers can dispatch
-     * on it, along with any requested `related` rows nested under their relation
-     * key.
-     *
-     * A query that fails on the server comes back as an empty array, which is
-     * indistinguishable from a query that simply matched nothing — treat an empty
-     * result as "no rows", not as proof the query succeeded. The element type is
-     * `unknown` because one batch can mix row shapes, so narrow each result
-     * before use.
-     */
-    results: unknown[];
-    /**
-     * The server watermark observed after the batch ran. Model reads expose this
-     * as `stamp`, and callers thread it into `commits.create({ readAt })` so the
-     * server can reject a write built on stale data.
-     */
-    lastSyncId?: number;
-}

package/dist/query/types.js

@@ -1,16 +0,0 @@
-/**
- * Structured query types for the `/sync/query` endpoint.
- *
- * A query describes a filtered read in a compact wire format. `where` is a flat
- * list of `[column, operator, value]` conditions combined with AND, and
- * `related` names the schema relations to fetch alongside each row. The server
- * compiles a query against your schema: it reads the model's relation metadata
- * to turn `related: ['blocks']` into the right join, and turns each condition
- * into a WHERE fragment. The protocol carries no model-specific logic, so
- * adding a model or relation is a schema change rather than a server change.
- *
- * The `IN` operator lets you batch a read by any column, including a foreign
- * key — for example, fetching every block whose `sectionId` falls in a set of
- * ids.
- */
-export {};