@abloatai/ablo 0.36.0 → 0.37.1

package/dist/stores/openIDBWithTimeout.js

@@ -1,153 +0,0 @@
-/**
- * The error raised when opening an IndexedDB database does not complete in a
- * bounded time. {@link openIDBWithTimeout} throws it in two situations: another
- * browser tab is holding an older version of the database open and blocking the
- * upgrade (`reason: 'blocked'`), or the open request produced no result at all
- * within the timeout (`reason: 'timeout'`).
- *
- * The native open request can otherwise hang indefinitely — when a blocking tab
- * never closes its connection, neither the success nor the error callback fires,
- * and any code awaiting the open waits forever. Turning that into a thrown error
- * lets the surrounding application show a recoverable failure instead of an
- * unbreakable spinner.
- */
-export class IDBOpenTimeoutError extends Error {
-    dbName;
-    reason;
-    /**
-     * A stable identifier for this failure, independent of the message text. When
-     * this error is wrapped into an {@link AbloError} by `toAbloError`, the string
-     * code is preserved, so error handlers can recognize a wedged-storage failure
-     * and offer a recovery path rather than matching on the message.
-     */
-    code = 'storage_open_timeout';
-    constructor(dbName, reason, message) {
-        super(message);
-        this.dbName = dbName;
-        this.reason = reason;
-        this.name = 'IDBOpenTimeoutError';
-    }
-}
-/**
- * Returns true when a caught value is the storage-open-timeout failure. It
- * detects the failure by its stable `code`, so it still matches after the error
- * has been wrapped into an {@link AbloError} or another error type.
- */
-export function isStorageOpenTimeout(err) {
-    return (typeof err === 'object' &&
-        err !== null &&
-        err.code === 'storage_open_timeout');
-}
-export function openIDBWithTimeout(name, version, options = {}) {
-    const timeoutMs = options.timeoutMs ?? 10_000;
-    return new Promise((resolve, reject) => {
-        const request = version === undefined
-            ? indexedDB.open(name)
-            : indexedDB.open(name, version);
-        let settled = false;
-        const settle = (fn) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            fn();
-        };
-        if (options.onUpgrade) {
-            request.onupgradeneeded = (event) => {
-                options.onUpgrade(request, event);
-            };
-        }
-        request.onsuccess = () => {
-            // If we already timed out or were blocked and rejected, this is a late
-            // success: the native open eventually completed after we gave up. The
-            // resulting connection is orphaned — nothing up the stack holds it, so
-            // nothing will close it. A leaked open connection holds an IndexedDB lock
-            // that wedges every later open or delete of this database name, so close
-            // it here to keep a timed-out attempt from poisoning the store.
-            if (settled) {
-                try {
-                    request.result.close();
-                }
-                catch {
-                    // Best-effort — a half-open connection may already be unusable.
-                }
-                return;
-            }
-            const db = request.result;
-            // Required resilience handler per the IndexedDB specification: close this
-            // connection as soon as any other context wants to upgrade or delete the
-            // database. Without it, a connection that ignores `versionchange` blocks
-            // the other context's request indefinitely — a common cause of a database
-            // that stays wedged across reloads. Closing here makes the store release
-            // itself.
-            db.onversionchange = () => {
-                try {
-                    db.close();
-                }
-                catch {
-                    // Already closing/closed — nothing to do.
-                }
-                try {
-                    options.onVersionChange?.();
-                }
-                catch {
-                    // A consumer reaction must never break the close.
-                }
-            };
-            settle(() => { resolve(db); });
-        };
-        request.onerror = () => { settle(() => { reject(request.error); }); };
-        // The critical handler: another tab is blocking us. Native API leaves
-        // the request pending indefinitely; we fail fast with a clear error so
-        // the UI can tell the user to close other tabs.
-        request.onblocked = () => {
-            settle(() => {
-                reject(new IDBOpenTimeoutError(name, 'blocked', `IndexedDB \"${name}\" open blocked — another tab is holding an ` +
-                    `older version. Close other Ablo tabs and reload.`));
-            });
-        };
-        // Catch-all timeout: even without `onblocked`, some browsers in some
-        // storage states hang without firing any event. Bounded wait →
-        // deterministic error.
-        const timer = setTimeout(() => {
-            settle(() => {
-                reject(new IDBOpenTimeoutError(name, 'timeout', `IndexedDB \"${name}\" open did not resolve within ${timeoutMs}ms. ` +
-                    `Storage may be in a bad state — clearing site data and reloading ` +
-                    `usually fixes this.`));
-            });
-        }, timeoutMs);
-    });
-}
-/**
- * Deletes an IndexedDB database within a bounded time — the delete counterpart
- * to {@link openIDBWithTimeout}. It is used to recover from a wedged backing
- * store: when opening a database times out, the caller can delete it and start
- * fresh, which is safe for any database whose contents can be rebuilt on the
- * next load.
- *
- * Like an open request, a native delete can hang indefinitely — it fires a
- * blocked event and waits when another connection still holds the database, and
- * on a truly stuck store it fires no event at all. Both cases become a bounded,
- * resolved result here, so the caller never spins.
- *
- * Resolves to `true` on a clean delete and `false` when the delete was blocked
- * or timed out. Either way the caller can decide whether to retry the open; a
- * delete that did nothing leaves the store no worse off.
- */
-export function deleteIDBWithTimeout(name, timeoutMs = 5_000) {
-    return new Promise((resolve) => {
-        let settled = false;
-        const settle = (value) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            resolve(value);
-        };
-        const request = indexedDB.deleteDatabase(name);
-        request.onsuccess = () => { settle(true); };
-        request.onerror = () => { settle(false); };
-        request.onblocked = () => { settle(false); };
-        const timer = setTimeout(() => { settle(false); }, timeoutMs);
-    });
-}

package/dist/stores/syncAction.d.ts

@@ -1,26 +0,0 @@
-/**
- * The persisted local action record consumed by `SyncActionStore`. It is a
- * client materialization artifact, not a transaction-layer wire shape: the
- * authoritative broadcast vocabulary is the settlement core's delta wire
- * schema, while this one adds the local `__class` discriminator IndexedDB uses.
- */
-import { z } from 'zod';
-export declare const syncActionSchema: z.ZodObject<{
-    id: z.ZodNumber;
-    modelName: z.ZodString;
-    modelId: z.ZodString;
-    action: z.ZodEnum<{
-        I: "I";
-        U: "U";
-        D: "D";
-        A: "A";
-        V: "V";
-        C: "C";
-        G: "G";
-        S: "S";
-    }>;
-    data: z.ZodUnknown;
-    __class: z.ZodDefault<z.ZodLiteral<"SyncAction">>;
-}, z.core.$strip>;
-export type SyncAction = z.infer<typeof syncActionSchema>;
-export type SyncActionType = SyncAction['action'];

package/dist/stores/syncAction.js

@@ -1,16 +0,0 @@
-/**
- * The persisted local action record consumed by `SyncActionStore`. It is a
- * client materialization artifact, not a transaction-layer wire shape: the
- * authoritative broadcast vocabulary is the settlement core's delta wire
- * schema, while this one adds the local `__class` discriminator IndexedDB uses.
- */
-import { z } from 'zod';
-import { syncDeltaActionSchema } from '../transaction/wire/delta.js';
-export const syncActionSchema = z.object({
-    id: z.number(),
-    modelName: z.string(),
-    modelId: z.string(),
-    action: syncDeltaActionSchema,
-    data: z.unknown(),
-    __class: z.literal('SyncAction').default('SyncAction'),
-});

package/dist/surface.d.ts

@@ -1,36 +0,0 @@
-/**
- * A machine-checked manifest of this package's public API surface. It lists,
- * as string tuples, the method names on `ablo.<model>`, the keys accepted by
- * the list-style read options, and the keys of the client constructor
- * options. Each tuple is proven equal to the keys of its source interface at
- * compile time, so the lists cannot drift from the real types: add or remove
- * a name on either side without updating the matching tuple and this file
- * fails to compile, in both directions — no name the interface lacks, and no
- * interface key the tuple omits.
- *
- * Documentation tooling reads these tuples to describe the surface, which
- * guarantees a generated summary never names a method or option that does
- * not exist. The names are verified here; their prose descriptions are
- * written by hand, since prose cannot be type-checked.
- */
-/**
- * The names of every method available on `ablo.<model>`, matching the keys of
- * the {@link ModelOperations} interface. Documentation tooling reads this
- * tuple, so it is the one list of model-verb names a generated summary can
- * describe.
- */
-export declare const PUBLIC_MODEL_VERBS: readonly ["retrieve", "list", "local", "create", "update", "delete", "claim", "track", "join", "onChange"];
-/**
- * The option keys accepted by `local.list` and `onChange`, matching the
- * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named
- * `state`, not `scope`.
- */
-export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orderBy", "limit", "offset", "state"];
-/**
- * The keys of the client constructor options, {@link AbloOptions}. Only
- * `schema` is required; every other key is optional.
- */
-export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "authEndpoint", "persistence", "durableWrites", "commitOutbox", "commitOutboxScope", "transport", "debug", "logLevel", "logger", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser", "collaborationEvents", "plugins", "wait"];
-export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
-export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
-export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/dist/surface.js

@@ -1,75 +0,0 @@
-/**
- * A machine-checked manifest of this package's public API surface. It lists,
- * as string tuples, the method names on `ablo.<model>`, the keys accepted by
- * the list-style read options, and the keys of the client constructor
- * options. Each tuple is proven equal to the keys of its source interface at
- * compile time, so the lists cannot drift from the real types: add or remove
- * a name on either side without updating the matching tuple and this file
- * fails to compile, in both directions — no name the interface lacks, and no
- * interface key the tuple omits.
- *
- * Documentation tooling reads these tuples to describe the surface, which
- * guarantees a generated summary never names a method or option that does
- * not exist. The names are verified here; their prose descriptions are
- * written by hand, since prose cannot be type-checked.
- */
-// ── the per-`ablo.<model>` verb surface ────────────────────────────────────
-/**
- * The names of every method available on `ablo.<model>`, matching the keys of
- * the {@link ModelOperations} interface. Documentation tooling reads this
- * tuple, so it is the one list of model-verb names a generated summary can
- * describe.
- */
-export const PUBLIC_MODEL_VERBS = [
-    'retrieve',
-    'list',
-    'local',
-    'create',
-    'update',
-    'delete',
-    'claim',
-    'track',
-    'join',
-    'onChange',
-];
-// ── the read/list query option surface ─────────────────────────────────────
-/**
- * The option keys accepted by `local.list` and `onChange`, matching the
- * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named
- * `state`, not `scope`.
- */
-export const PUBLIC_LIST_OPTION_KEYS = [
-    'where',
-    'filter',
-    'orderBy',
-    'limit',
-    'offset',
-    'state',
-];
-// ── the `Ablo({ … })` constructor option surface ───────────────────────────
-/**
- * The keys of the client constructor options, {@link AbloOptions}. Only
- * `schema` is required; every other key is optional.
- */
-export const PUBLIC_ABLO_OPTION_KEYS = [
-    'schema',
-    'apiKey',
-    'authEndpoint',
-    'persistence',
-    'durableWrites',
-    'commitOutbox',
-    'commitOutboxScope',
-    'transport',
-    'debug',
-    'logLevel',
-    'logger',
-    'authToken',
-    'baseURL',
-    'fetch',
-    'defaultHeaders',
-    'defaultQuery',
-    'dangerouslyAllowBrowser',
-    'collaborationEvents',
-    'plugins',
-    'wait',
-];

package/dist/sync/BootstrapFetcher.d.ts

@@ -1,284 +0,0 @@
-/**
- * Fetches the initial snapshot the sync engine needs before it can go live: the
- * current rows for the requested models plus the sync position from which to
- * resume live updates. It calls the sync server's `/sync/bootstrap` HTTP
- * endpoint, retries transient failures with backoff, and can fall back to a
- * cached snapshot when the device is offline. {@link BootstrapData} is the
- * shape it returns; {@link BootstrapOptions} configures it.
- */
-export interface BootstrapData {
-    type: 'full' | 'partial';
-    lastSyncId: number;
-    /**
-     * Model rows keyed by type name. Each row is opaque at this boundary; the
-     * engine asserts the per-model shape against the registered schema when it
-     * reduces the rows and writes them to local storage.
-     */
-    models?: Record<string, unknown[]>;
-    deltas?: ValidatedServerDelta[];
-    deltaCount?: number;
-    /** Model types whose server-side query failed (timeout, RLS error, and the like). */
-    failedModels?: string[];
-    timestamp: number;
-    /**
-     * The content hash of the schema the server currently has active for this
-     * tenant — the same hash `ablo push` computes. Present once a schema has been
-     * pushed. The client compares it against its own `expectedSchemaHash` to warn
-     * when the app's schema and the deployed schema have drifted apart.
-     */
-    schemaHash?: string;
-    /**
-     * Present when a paged single-model request stopped at its row limit with
-     * rows remaining: pass it back as the next page's `cursor`. Absent on the
-     * final page, on unpaged responses, and from servers that predate paging.
-     */
-    nextCursor?: string;
-}
-export interface BootstrapFetchResult {
-    notModified: boolean;
-    data?: BootstrapData;
-    etag?: string | null;
-}
-export interface BootstrapOptions {
-    /**
-     * Full base URL of the sync server's HTTP API, **including the `/api`
-     * prefix**. The bootstrap endpoint is appended as `/sync/bootstrap`, so
-     * the final request hits `${baseUrl}/sync/bootstrap`.
-     *
-     * Example: `'http://localhost:8080/api'` → `http://localhost:8080/api/sync/bootstrap`
-     *
-     * Default: `'http://localhost:8080/api'`.
-     */
-    baseUrl?: string;
-    /**
-     * Namespace for the offline bootstrap cache. Most callers leave this unset;
-     * the SDK fills it in once authentication has resolved the account scope, so
-     * the fallback cache is partitioned per account.
-     */
-    cacheScope?: string | null;
-    /**
-     * @deprecated Use `cacheScope`. Retained so code that constructs
-     * {@link BootstrapFetcher} directly keeps its cache namespace.
-     */
-    organizationId?: string;
-    syncGroups?: string[];
-    maxRetries?: number;
-    retryDelay?: number;
-    /**
-     * How long to wait for the server to START responding (response headers), in
-     * milliseconds. Default 20000 (20 seconds).
-     *
-     * Deliberately NOT a bound on the whole download: a cold-start snapshot can
-     * be tens of megabytes, and its transfer time depends on the connection. A
-     * healthy download that is actively delivering bytes is never aborted, no
-     * matter how long it takes — {@link stallTimeout} guards the body instead.
-     */
-    fetchTimeout?: number;
-    /**
-     * The longest quiet gap allowed between body chunks while downloading, in
-     * milliseconds. Default 15000 (15 seconds). This is the progress watchdog:
-     * it aborts a download whose stream has gone silent (dead connection,
-     * hung proxy) without ever penalizing a slow-but-moving transfer.
-     */
-    stallTimeout?: number;
-    /**
-     * The model names to request. When set, the server returns only these models
-     * and skips the rest. This is derived from each model's `load` strategy: only
-     * models loaded instantly (the default) are included. When unset, the server
-     * returns every model.
-     */
-    instantModels?: string[];
-    /**
-     * Getter for the current credential, read at request time so a refreshed
-     * token takes effect without recreating the helper. Preferred over
-     * {@link BootstrapFetcher.setAuthToken}.
-     */
-    getAuthToken?: AuthTokenGetter;
-    /** The owning client's runtime. Defaults to the module-global bridge. */
-    runtime?: RuntimeContext;
-}
-import type { RuntimeContext } from '../RuntimeContext.js';
-import { type AuthTokenGetter } from '../transaction/auth/credentialSource.js';
-import { type ValidatedServerDelta } from './schemas.js';
-export declare class BootstrapFetcher {
-    private options;
-    private readonly runtime;
-    /**
-     * Every in-flight request's controller, tagged with the lane it belongs to. A
-     * registry rather than a single field because a chunked cold start runs
-     * several model fetches concurrently — aborting one request (its own
-     * TTFB/stall watchdog) must never take its siblings down, while
-     * {@link abort} takes down all of them.
-     */
-    private readonly activeControllers;
-    /**
-     * Non-scoped bootstraps currently running, keyed by request identity. A
-     * second call for the same snapshot joins the one already in flight rather
-     * than cancelling and restarting it — see {@link fetchBootstrap}.
-     */
-    private readonly flights;
-    /** Warn about schema drift at most once per helper. */
-    private schemaDriftWarned;
-    /**
-     * Abort every in-flight request in `lane` — or in every lane when none is
-     * given — with an explicit reason.
-     *
-     * The reason is load-bearing, not decoration. `fetch` rejects with the exact
-     * value handed to `abort()`, so passing a typed error is what lets the retry
-     * loop below tell a deliberate cancellation apart from a dead connection. A
-     * bare `abort()` produces an `AbortError` indistinguishable from the one the
-     * browser's stop button produces, and a retry loop that cannot tell them
-     * apart re-issues the requests it just killed.
-     */
-    private cancelActive;
-    /**
-     * The longest a single bootstrap can run before every watchdog below has
-     * necessarily fired, derived from those watchdogs rather than guessed. A
-     * caller wanting an outer deadline reads this instead of picking a number,
-     * so it cannot set one shorter than the work it wraps. A cold start pages
-     * through its models {@link CHUNK_CONCURRENCY} at a time; each request may
-     * spend `fetchTimeout` waiting for response headers and `stallTimeout`
-     * waiting for the next body chunk, and may be retried `maxRetries` times.
-     */
-    get budgetMs(): number;
-    get baseUrl(): string;
-    /**
-     * Advisory schema-drift check: compare the server's active schema hash (on the
-     * bootstrap response) against the hash this client was built with. A mismatch
-     * means the app's schema and the deployed schema have diverged — reads/writes
-     * relying on undeployed changes will later fail with an opaque DB constraint
-     * error. Warn once, actionably; never throws or blocks the bootstrap.
-     *
-     * The message names the SERVER it connected to, and spans all three real
-     * causes rather than assuming "you forgot to push". Drift most often means the
-     * schema was pushed to a different server, project, or environment than this
-     * client points at (a bare `ablo push` targets the hosted default; a local app
-     * usually reads a local server) — so the first, load-bearing pointer is `ablo
-     * status`, which names the exact org/project/environment the key resolves to
-     * and the deployed hash, turning "which of these is it?" into one glance. The
-     * older "Run `ablo push`" copy sent everyone down one path and confused the
-     * common wrong-target and version-skew cases.
-     */
-    private warnOnSchemaDrift;
-    /** Fetch the server's per-model schema surface and warn precisely — or stay
-     *  silent when every model this client declares matches (additive lead). */
-    private resolveSemanticDrift;
-    private warnWholeHashDrift;
-    constructor(options: BootstrapOptions);
-    /**
-     * Update the offline-cache namespace once auth has resolved the server-side
-     * account scope. This is intentionally not a public organizationId input.
-     */
-    setCacheScope(cacheScope: string): void;
-    setSyncGroups(syncGroups: readonly string[] | undefined): void;
-    /**
-     * Sets a fixed credential for callers that construct the helper directly.
-     * The SDK instead supplies `getAuthToken` and never calls this.
-     */
-    setAuthToken(authToken: string | undefined): void;
-    /**
-     * Fetch bootstrap data from sync engine with partial bootstrap support
-     * @param lastSyncId - Optional: client's current lastSyncId for partial bootstrap
-     * @returns Bootstrap data (either full snapshot or delta batch)
-     */
-    fetchBootstrap(lastSyncId?: number, 
-    /**
-     * A per-call set of sync groups for a scoped hydrate-on-enter. When given,
-     * the request uses these groups instead of the configured `syncGroups`, and
-     * does so without mutating the shared options, so a concurrent full
-     * bootstrap is unaffected. It also bypasses the offline snapshot cache,
-     * which holds the full bootstrap and would be a wrong answer to a subset
-     * request.
-     */
-    syncGroupsOverride?: readonly string[]): Promise<BootstrapData>;
-    /**
-     * The identity of a bootstrap request: everything that determines its answer.
-     * Two calls with the same key are asking the same question, so the second can
-     * take the first's result.
-     */
-    private flightKey;
-    /** One bootstrap, start to finish. {@link fetchBootstrap} owns whether it runs. */
-    private runBootstrap;
-    /**
-     * One bootstrap URL, fetched with backoff. Session errors and other
-     * non-retryable failures throw immediately; only transient failures
-     * (5xx, 429, timeouts, network blips) consume attempts. A cancellation is
-     * deliberate and therefore non-retryable — it leaves through the same gate.
-     */
-    private fetchWithRetries;
-    /**
-     * Cold-start bootstrap, one request per instant model with a small
-     * concurrency cap. Any chunk's terminal failure fails the whole
-     * bootstrap (a partial snapshot must never masquerade as a full one)
-     * and cancels its siblings.
-     */
-    private fetchChunkedBootstrap;
-    /**
-     * Fetch bootstrap with ETag, returning 304 hints
-     */
-    fetchBootstrapWithETag(): Promise<BootstrapFetchResult>;
-    private fetchWithETagUsing;
-    /**
-     * Read a response body as a stream under a progress watchdog: the stall
-     * timer re-arms on every chunk, so only a silent stream is aborted — a
-     * slow-but-moving download is never killed for total duration. A cold-start
-     * snapshot can be tens of megabytes; bounding its total transfer time was
-     * what trapped large orgs in an endless full-bootstrap retry loop.
-     *
-     * Falls back to `response.json()` when the response exposes no readable
-     * stream (empty bodies, some test doubles).
-     */
-    private readJsonWithStallGuard;
-    /**
-     * Perform one fetch. The timeout here bounds time to response headers
-     * only; the body download is guarded by the stall watchdog in
-     * {@link readJsonWithStallGuard}. Superseding an older in-flight
-     * bootstrap is the caller's job ({@link fetchBootstrap} cancels the
-     * registry) — chunk requests run through here concurrently and must
-     * not cancel each other.
-     */
-    private fetchOnce;
-    private fetchOnceWith;
-    /**
-     * Fetch a single entity by ID (on-demand self-healing).
-     * Returns `null` for 404 (entity deleted) — this is an expected state, not an error.
-     * Throws for unexpected HTTP errors (5xx, network failures).
-     */
-    fetchEntity(modelName: string, id: string): Promise<Record<string, unknown> | null>;
-    /**
-     * Clear all cached bootstrap data
-     */
-    clearCache(): void;
-    private getBootstrapCacheKey;
-    private saveCachedBootstrap;
-    private loadCachedBootstrap;
-    /**
-     * Abort every ongoing bootstrap request (including all chunks of a
-     * chunked cold start). Entity self-heal fetches are unaffected.
-     *
-     * The flight registry is cleared first and synchronously, so a caller that
-     * bootstraps again in the same tick starts a fresh request rather than
-     * joining the one being torn down.
-     */
-    abort(): void;
-    /**
-     * Helper to delay execution
-     */
-    private delay;
-    /**
-     * Get health status of sync engine
-     */
-    checkHealth(): Promise<boolean>;
-}
-/**
- * Assemble per-model chunk responses into one full snapshot.
- *
- * Each chunk is internally consistent at its own sync position, and the
- * positions differ (the chunks were served seconds apart). Anchoring the
- * merged snapshot at the MINIMUM position turns that skew into an ordinary
- * "briefly offline client": the WS catch-up replays every delta from the
- * anchor, and since deltas carry full rows, re-applying one a later chunk
- * already reflects converges to the same state. Anchoring at anything later
- * would silently skip deltas for the earliest-fetched models.
- */
-export declare function mergeBootstrapChunks(chunks: readonly BootstrapData[]): BootstrapData;