@abloatai/ablo 0.34.1 → 0.36.0

package/dist/testing/mocks/MockSyncStore.js

@@ -1,171 +0,0 @@
-/**
- * An in-memory {@link SyncStoreContract} for tests. It lets you seed rows,
- * read and write them synchronously, and inspect every call the code under
- * test made — all without a real sync backend.
- */
-import { ViewRegistry } from '../../core/ViewRegistry.js';
-import { AbloValidationError } from '../../errors.js';
-/**
- * An in-memory implementation of {@link SyncStoreContract}. Seed rows with
- * {@link MockSyncStore.setModels}, then read and write through the contract
- * methods; every call is recorded on {@link MockSyncStore.calls} so tests can
- * assert on what happened.
- */
-export class MockSyncStore {
-    // Seeded data, keyed by model class
-    byClass = new Map();
-    // Call tracking for assertions
-    calls = {
-        retrieve: [],
-        query: [],
-        save: [],
-        delete: [],
-        archive: [],
-        unarchive: [],
-    };
-    /**
-     * Seed the store with models of a specific class.
-     *
-     * @example
-     * mockStore.setModels(Task, [task1, task2]);
-     */
-    setModels(modelClass, models) {
-        const map = new Map();
-        for (const m of models) {
-            map.set(m.id, m);
-        }
-        this.byClass.set(modelClass, map);
-    }
-    /**
-     * Adds or replaces a single model, keyed by its id.
-     */
-    addModel(modelClass, model) {
-        let map = this.byClass.get(modelClass);
-        if (!map) {
-            map = new Map();
-            this.byClass.set(modelClass, map);
-        }
-        map.set(model.id, model);
-    }
-    /**
-     * Remove a model by ID.
-     */
-    removeModel(modelClass, id) {
-        this.byClass.get(modelClass)?.delete(id);
-    }
-    /**
-     * Clear all seeded data and call history.
-     */
-    reset() {
-        this.byClass.clear();
-        this.calls = {
-            retrieve: [],
-            query: [],
-            save: [],
-            delete: [],
-            archive: [],
-            unarchive: [],
-        };
-    }
-    // ── SyncStoreContract implementation ──────────────────────────────────
-    retrieve(modelClass, id) {
-        this.calls.retrieve.push({ modelClass: modelClass, id });
-        return this.byClass.get(modelClass)?.get(id);
-    }
-    queryByClass(modelClass, options) {
-        this.calls.query.push({
-            modelClass: modelClass,
-            options: options,
-        });
-        const map = this.byClass.get(modelClass);
-        if (!map) {
-            return { data: [] };
-        }
-        let data = Array.from(map.values());
-        // Apply predicate
-        if (options?.predicate) {
-            data = data.filter(options.predicate);
-        }
-        // Apply ordering
-        if (options?.orderBy) {
-            const key = options.orderBy;
-            const order = options.order ?? 'asc';
-            data.sort((a, b) => {
-                const av = a[key];
-                const bv = b[key];
-                if (av === bv)
-                    return 0;
-                const cmp = av < bv ? -1 : 1;
-                return order === 'asc' ? cmp : -cmp;
-            });
-        }
-        // Apply pagination
-        if (options?.offset) {
-            data = data.slice(options.offset);
-        }
-        if (options?.limit !== undefined) {
-            data = data.slice(0, options.limit);
-        }
-        return { data };
-    }
-    async save(model) {
-        this.calls.save.push(model);
-        // Store the model under its constructor so a later retrieve or query
-        // returns it.
-        const ctor = model.constructor;
-        this.addModel(ctor, model);
-    }
-    async delete(model) {
-        this.calls.delete.push(model);
-        const ctor = model.constructor;
-        this.removeModel(ctor, model.id);
-    }
-    async archive(model) {
-        this.calls.archive.push(model);
-    }
-    async unarchive(model) {
-        this.calls.unarchive.push(model);
-    }
-    // Sync-status getters default to "ready, idle". Tests that exercise
-    // offline/reconnect flows can set these before rendering.
-    isReady = true;
-    isSyncing = false;
-    isOffline = false;
-    isReconnecting = false;
-    isError = false;
-    hasUnsyncedChanges = false;
-    syncStatus = {
-        state: 'idle',
-        progress: 100,
-        pendingChanges: 0,
-        isSessionError: false,
-    };
-    /** A minimal object pool backing the useEntity and useEntities hooks in tests. */
-    pool = {
-        get: (id) => {
-            for (const models of this.byClass.values()) {
-                const model = models.get(id);
-                if (model)
-                    return model;
-            }
-            return undefined;
-        },
-        getByTypeName: (_typename) => [],
-        getByForeignKey: () => [],
-        createFromData: () => null,
-        hasForeignKeyIndex: () => false,
-        createView: () => {
-            throw new AbloValidationError('MockSyncStore does not support createView', {
-                code: 'mock_unsupported_operation',
-            });
-        },
-        viewRegistry: new ViewRegistry(),
-    };
-}
-/**
- * Create a new MockSyncStore.
- * Shorthand for `new MockSyncStore()`.
- */
-export function createMockSyncStore() {
-    return new MockSyncStore();
-}

package/dist/testing/mocks/MockWebSocket.d.ts

@@ -1,71 +0,0 @@
-/**
- * A controllable WebSocket stand-in for sync engine tests. It reproduces the
- * event interface of the real connection without opening a socket, so tests
- * can drive connection changes, deltas, and bootstrap hints by hand.
- */
-import type { SyncActionType } from '../../types/index.js';
-import type { BootstrapReason } from '../../wire/bootstrapReason.js';
-/** The shape of a single delta — one change the server pushes to the client. */
-export interface MockDelta {
-    id: number;
-    modelName: string;
-    modelId: string;
-    action: SyncActionType;
-    data: Record<string, unknown>;
-}
-/**
- * A hint from the server that the client has fallen too far behind and should
- * rebuild its data from scratch rather than catch up one delta at a time.
- */
-export interface MockBootstrapHint {
-    reason: BootstrapReason;
-    tables?: string[];
-    staleTables?: string[];
-}
-type EventHandler = (...args: unknown[]) => void;
-/**
- * A controllable, event-based stand-in for the sync engine's WebSocket
- * connection. Subscribe with {@link MockWebSocket.on} exactly as production
- * code does, then use the `simulate*` and `receive*` methods to push
- * connection changes, deltas, and bootstrap hints. Every event the mock emits
- * is recorded on {@link MockWebSocket.emittedEvents} for assertions.
- */
-export declare class MockWebSocket {
-    private _connected;
-    private _sessionError;
-    private _listeners;
-    /** Every event the mock has emitted, in order, for assertions. */
-    readonly emittedEvents: {
-        type: string;
-        data: unknown;
-    }[];
-    get connected(): boolean;
-    get sessionError(): boolean;
-    on(event: string, handler: EventHandler): () => void;
-    private emit;
-    /** Fires a successful connection, emitting the `connected` event. */
-    simulateConnect(): void;
-    /** Drops the connection, emitting the `disconnected` event. */
-    simulateDisconnect(): void;
-    /** Emits a `reconnecting` event carrying the attempt number and retry delay. */
-    simulateReconnecting(attempt: number, delay: number): void;
-    /** Emits a `session_error` event, as when the server rejects the session as unauthorized. The code defaults to 401. */
-    simulateSessionError(code?: number): void;
-    /** Emits a `reconnect_failed` event, signaling the client gave up after exhausting its retries. */
-    simulateReconnectFailed(): void;
-    /** Delivers a single delta, emitting a `delta` event as if the server had sent it. */
-    receiveDelta(delta: MockDelta): void;
-    /** Delivers a batch of deltas, emitting a `delta_batch` event. */
-    receiveDeltas(deltas: MockDelta[]): void;
-    /** Emits a `bootstrap_required` hint, telling the client to rebuild its data instead of catching up. */
-    simulateBootstrapHint(hint: MockBootstrapHint): void;
-    /** Emits a `presence_update` event carrying the given payload. */
-    simulatePresenceUpdate(data: Record<string, unknown>): void;
-    /** Returns the payloads of every emitted event of the given type, in order. */
-    getEvents(type: string): unknown[];
-    /** Reports whether an event of the given type has been emitted. */
-    hasEmitted(type: string): boolean;
-    /** Clears connection state, listeners, and the record of emitted events. */
-    reset(): void;
-}
-export {};

package/dist/testing/mocks/MockWebSocket.js

@@ -1,118 +0,0 @@
-/**
- * A controllable WebSocket stand-in for sync engine tests. It reproduces the
- * event interface of the real connection without opening a socket, so tests
- * can drive connection changes, deltas, and bootstrap hints by hand.
- */
-/**
- * A controllable, event-based stand-in for the sync engine's WebSocket
- * connection. Subscribe with {@link MockWebSocket.on} exactly as production
- * code does, then use the `simulate*` and `receive*` methods to push
- * connection changes, deltas, and bootstrap hints. Every event the mock emits
- * is recorded on {@link MockWebSocket.emittedEvents} for assertions.
- */
-export class MockWebSocket {
-    _connected = false;
-    _sessionError = false;
-    _listeners = new Map();
-    /** Every event the mock has emitted, in order, for assertions. */
-    emittedEvents = [];
-    get connected() {
-        return this._connected;
-    }
-    get sessionError() {
-        return this._sessionError;
-    }
-    // ─────────────────────────────────────────────
-    // Event subscription (matches the real connection's API)
-    // ─────────────────────────────────────────────
-    on(event, handler) {
-        if (!this._listeners.has(event)) {
-            this._listeners.set(event, new Set());
-        }
-        this._listeners.get(event).add(handler);
-        return () => {
-            this._listeners.get(event)?.delete(handler);
-        };
-    }
-    emit(event, ...args) {
-        this.emittedEvents.push({ type: event, data: args[0] });
-        const handlers = this._listeners.get(event);
-        if (handlers) {
-            for (const handler of handlers) {
-                handler(...args);
-            }
-        }
-    }
-    // ─────────────────────────────────────────────
-    // Test control: connection lifecycle
-    // ─────────────────────────────────────────────
-    /** Fires a successful connection, emitting the `connected` event. */
-    simulateConnect() {
-        this._connected = true;
-        this._sessionError = false;
-        this.emit('connected');
-    }
-    /** Drops the connection, emitting the `disconnected` event. */
-    simulateDisconnect() {
-        this._connected = false;
-        this.emit('disconnected');
-    }
-    /** Emits a `reconnecting` event carrying the attempt number and retry delay. */
-    simulateReconnecting(attempt, delay) {
-        this.emit('reconnecting', { attempt, delay });
-    }
-    /** Emits a `session_error` event, as when the server rejects the session as unauthorized. The code defaults to 401. */
-    simulateSessionError(code = 401) {
-        this._sessionError = true;
-        this._connected = false;
-        this.emit('session_error', { code });
-    }
-    /** Emits a `reconnect_failed` event, signaling the client gave up after exhausting its retries. */
-    simulateReconnectFailed() {
-        this._connected = false;
-        this.emit('reconnect_failed');
-    }
-    // ─────────────────────────────────────────────
-    // Test control: delta injection
-    // ─────────────────────────────────────────────
-    /** Delivers a single delta, emitting a `delta` event as if the server had sent it. */
-    receiveDelta(delta) {
-        this.emit('delta', delta);
-    }
-    /** Delivers a batch of deltas, emitting a `delta_batch` event. */
-    receiveDeltas(deltas) {
-        this.emit('delta_batch', deltas);
-    }
-    // ─────────────────────────────────────────────
-    // Test control: bootstrap hints
-    // ─────────────────────────────────────────────
-    /** Emits a `bootstrap_required` hint, telling the client to rebuild its data instead of catching up. */
-    simulateBootstrapHint(hint) {
-        this.emit('bootstrap_required', hint);
-    }
-    // ─────────────────────────────────────────────
-    // Test control: presence
-    // ─────────────────────────────────────────────
-    /** Emits a `presence_update` event carrying the given payload. */
-    simulatePresenceUpdate(data) {
-        this.emit('presence_update', data);
-    }
-    // ─────────────────────────────────────────────
-    // Assertions
-    // ─────────────────────────────────────────────
-    /** Returns the payloads of every emitted event of the given type, in order. */
-    getEvents(type) {
-        return this.emittedEvents.filter((e) => e.type === type).map((e) => e.data);
-    }
-    /** Reports whether an event of the given type has been emitted. */
-    hasEmitted(type) {
-        return this.emittedEvents.some((e) => e.type === type);
-    }
-    /** Clears connection state, listeners, and the record of emitted events. */
-    reset() {
-        this._connected = false;
-        this._sessionError = false;
-        this._listeners.clear();
-        this.emittedEvents.length = 0;
-    }
-}

package/dist/transactions/durableWriteStore.js

@@ -1,30 +0,0 @@
-/**
- * Product-facing persistence contract for writes that must survive a process
- * restart or an ambiguous network response.
- *
- * The engine implements this contract with a transactional outbox internally,
- * but callers should only need to think in terms of pending durable writes.
- */
-import { z } from 'zod';
-import { durableCommitEnvelopeSchema } from './commitEnvelope.js';
-import { durableHttpCommitEnvelopeSchema } from './httpCommitEnvelope.js';
-/** Every write shape that Ablo may ask an injected store to persist. */
-export const pendingWriteSchema = z.union([
-    durableCommitEnvelopeSchema,
-    durableHttpCommitEnvelopeSchema,
-]);
-/** Runtime validation for injected adapters, including JavaScript consumers. */
-export const durableWriteStoreSchema = z.custom((value) => {
-    if (typeof value !== 'object' || value === null)
-        return false;
-    const candidate = value;
-    return (typeof candidate.seal === 'function' &&
-        typeof candidate.list === 'function' &&
-        typeof candidate.remove === 'function');
-}, { message: 'store must implement seal(), list(), and remove()' });
-/** Options for crash-durable `create`, `update`, and `delete` calls. */
-export const durableWritesConfigSchema = z.strictObject({
-    store: durableWriteStoreSchema,
-    /** Separates deployments or workflow lanes that share an authenticated actor. */
-    namespace: z.string().trim().min(1).optional(),
-});

package/dist/utils/duration.d.ts

@@ -1,25 +0,0 @@
-/**
- * Parses a duration into milliseconds. A duration is either a number of seconds
- * or a string with a unit suffix — milliseconds, seconds, minutes, or hours:
- *
- *   - `'500ms'` → 500 ms
- *   - `'30s'`   → 30 000 ms
- *   - `'3m'`    → 180 000 ms
- *   - `'24h'`   → 86 400 000 ms
- *
- * A bare number is interpreted as seconds rather than milliseconds, matching the
- * `ttlSeconds` fields used throughout the SDK, so a numeric caller and a string
- * caller can pass the same field interchangeably. {@link toMs} returns
- * milliseconds; {@link toSeconds} returns whole seconds.
- */
-export type Duration = number | `${number}ms` | `${number}s` | `${number}m` | `${number}h`;
-/**
- * Parses a duration and returns the equivalent number of milliseconds. Accepts
- * either a bare number, interpreted as seconds, or a unit-suffixed string such
- * as `'500ms'`, `'30s'`, `'3m'`, or `'24h'`. Throws an
- * {@link AbloValidationError} with code `duration_invalid` when a string does
- * not match a supported unit.
- */
-export declare function toMs(input: Duration): number;
-/** Parses a duration like {@link toMs} but returns whole seconds, rounding down. */
-export declare function toSeconds(input: Duration): number;

package/dist/utils/json.js

@@ -1,88 +0,0 @@
-/**
- * json.ts — key-order-insensitive comparison helpers for JSON-shaped values.
- *
- * Why this exists as a first-class, exported util:
- *
- * A `field.json()` value may be backed by a Postgres `jsonb` column, and **jsonb
- * does not preserve object key order** (it reorders keys by length, then
- * bytewise, and drops insignificant whitespace — see
- * https://www.postgresql.org/docs/current/datatype-json.html). So a document an
- * app wrote as `{type,text}` streams back in a delta as `{text,type}`: the same
- * value, a different serialization.
- *
- * That bites any app that reconciles an Ablo row against an *external* state
- * container it doesn't control — a rich-text editor (Tiptap/ProseMirror/Slate),
- * a `useState`, a form buffer. The natural guard, `JSON.stringify(remote) ===
- * JSON.stringify(local)`, is silently wrong because the two sides serialize keys
- * in different orders, so it never matches — and the app re-applies the remote
- * value on every render, clobbering in-flight edits and fighting the cursor.
- *
- * The fix is to compare order-insensitively. `deepEqual` does structural
- * equality directly; `stableStringify` produces a canonical string (recursively
- * sorted keys) for when you need a stable cache key / dependency value. The SDK
- * already uses `deepEqual` internally for store-level echo detection; this
- * module makes the same guarantee available to app authors so they don't each
- * reinvent it.
- *
- * (If you need byte-exact key order preserved end-to-end, store the field in a
- * `text` column instead of `jsonb` — Ablo's adaptive codec serializes verbatim
- * there, matching Postgres's `json` type behavior.)
- */
-/** Structural equality for JSON-shaped values (scalars, arrays, plain objects); key order is ignored. */
-export function deepEqual(a, b) {
-    if (a === b)
-        return true;
-    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') {
-        return false;
-    }
-    const aArr = Array.isArray(a);
-    if (aArr !== Array.isArray(b))
-        return false;
-    if (aArr) {
-        const av = a;
-        const bv = b;
-        if (av.length !== bv.length)
-            return false;
-        for (let i = 0; i < av.length; i++) {
-            if (!deepEqual(av[i], bv[i]))
-                return false;
-        }
-        return true;
-    }
-    const ao = a;
-    const bo = b;
-    const ak = Object.keys(ao);
-    const bk = Object.keys(bo);
-    if (ak.length !== bk.length)
-        return false;
-    for (const k of ak) {
-        if (!Object.prototype.hasOwnProperty.call(bo, k))
-            return false;
-        if (!deepEqual(ao[k], bo[k]))
-            return false;
-    }
-    return true;
-}
-/**
- * Canonical JSON serialization: recursively sorts object keys so two values that
- * differ only in key order (e.g. a jsonb round-trip) produce the same string.
- * Use this when you need a comparable/cacheable string rather than a boolean —
- * e.g. an echo guard or a `useEffect`/`useMemo` dependency.
- */
-export function stableStringify(value) {
-    return JSON.stringify(sortKeysDeep(value));
-}
-function sortKeysDeep(value) {
-    if (Array.isArray(value))
-        return value.map(sortKeysDeep);
-    if (value && typeof value === 'object') {
-        const source = value;
-        return Object.keys(source)
-            .sort()
-            .reduce((acc, key) => {
-            acc[key] = sortKeysDeep(source[key]);
-            return acc;
-        }, {});
-    }
-    return value;
-}

package/dist/wire/errorEnvelope.d.ts

@@ -1,55 +0,0 @@
-/**
- * The fixed, public-facing message returned for an unclassified 500. A raw
- * `err.message` can carry driver text, connection strings, or stack fragments,
- * so it is never placed on the wire; a caller that needs those details logs the
- * original error server-side before formatting the response.
- */
-export declare const INTERNAL_ERROR_PUBLIC_MESSAGE = "An internal error occurred.";
-/** The canonical error envelope. Every HTTP error response and every structured
- *  frame error carries this exact set of keys, regardless of which route or
- *  transport produced it. */
-export interface ErrorEnvelope {
-    readonly type: string;
-    readonly code?: string;
-    readonly param?: string;
-    readonly message: string;
-    readonly doc_url?: string;
-    readonly request_id?: string;
-    /** Field-level failures collected together, so a single 4xx can report every
-     *  invalid input at once — for example a schema push, a batch commit, or CLI
-     *  argument validation — instead of failing on the first. Use `param` for the
-     *  single-field case. */
-    readonly errors?: readonly {
-        readonly code?: string;
-        readonly message: string;
-        readonly param?: string;
-    }[];
-    /** Additional typed details. {@link AbloError} serialization spreads its
-     *  `details` — such as `missingIds`, `conflicts`, or `retryAfterSeconds` — as
-     *  top-level members here. Ignore any member you do not recognize, so new ones
-     *  can be added without breaking you. */
-    readonly [key: string]: unknown;
-}
-/** Maps an {@link AbloError} subclass name to its default HTTP status. Each
- *  subclass is chosen to match the status — a validation error is a 400, a
- *  permission error a 403 — so a throw site picks the right class and code and
- *  the status follows. An explicit `httpStatus` is supplied only when it
- *  diverges, such as a 404 on the base class or a 503 on a server error. */
-export declare function statusForType(type: string): number;
-/**
- * Converts any thrown value into the canonical {@link ErrorEnvelope} and an HTTP
- * status. A typed {@link AbloError} is serialized through its own `toJSON`, so
- * its code, param, doc_url, and structured details survive, and its status comes
- * from an explicit `httpStatus` or, failing that, {@link statusForType}.
- * Anything else becomes a 500 `internal_error` envelope — never a bare framework
- * "Internal Server Error" body, and never a raw error string leaked onto the
- * wire as an unregistered code.
- *
- * When `requestId` is supplied and the error does not already carry one, it is
- * stamped into the body so the response and the `x-request-id` header agree for
- * support correlation.
- */
-export declare function errorEnvelope(err: unknown, requestId?: string): {
-    body: ErrorEnvelope;
-    status: number;
-};