@abloatai/ablo 0.35.0 → 0.37.0

package/dist/client/coreClient.js

@@ -1,118 +0,0 @@
-/**
- * The core client over the socket: the stateless surface plus the live feed
- * (ADR 0016). `Ablo({ ..., plugins: [] })` returns this — the empty list says
- * it plainly: nothing beyond the core. Reads and writes travel over
- * request-response, exactly as they do for the `transport: 'http'` client;
- * the socket adds push — deltas, presence frames, and the claim lifecycle
- * (granted, queued, lost) — without a local copy of anything.
- *
- * This is the membership test made constructible: a caller with no socket
- * loses only push, and polls instead; a caller with this client gets the
- * push back and still never holds a store it did not ask for. It also
- * satisfies the core coordination ports structurally — `awaitClaimGrant`
- * needs only `subscribe`, which this client has.
- */
-import { createAbloHttpClient, } from '../transaction/transport/httpClient.js';
-import { WsTransport } from '../transaction/transport/wsTransport.js';
-import { createClaimStream } from '../sync/createClaimStream.js';
-import { AbloConnectionError } from '../transaction/errors.js';
-/** How long `connect()` waits before reporting the feed did not come up. */
-const CONNECT_TIMEOUT_MS = 10_000;
-export function createCoreClient(args) {
-    const { options } = args;
-    // The stateless surface — the same construction `transport: 'http'` uses,
-    // fed the same option slice. The endpoint-form `apiKey` (or the legacy
-    // `authEndpoint`) mints and renews exactly as it does there.
-    const http = createAbloHttpClient({
-        schema: options.schema,
-        apiKey: options.apiKey ?? options.authEndpoint,
-        baseURL: args.baseUrl,
-        fetch: options.fetch,
-        defaultHeaders: options.defaultHeaders,
-        defaultQuery: options.defaultQuery,
-        dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
-        observability: args.observability,
-        durableWrites: options.durableWrites,
-        // Forwarding the compatibility aliases IS the compatibility: a caller still
-        // on the old pair reaches the HTTP client only through here, so this hand-off
-        // has to outlive the deprecation notice. It goes when the aliases do.
-        // eslint-disable-next-line @typescript-eslint/no-deprecated -- see above
-        commitOutbox: options.commitOutbox,
-        // eslint-disable-next-line @typescript-eslint/no-deprecated -- see above
-        commitOutboxScope: options.commitOutboxScope,
-    });
-    // The live feed. Constructed eagerly (a socket object holds no connection
-    // until `connect()`), with identity riding the bearer — the server never
-    // reads identity fields from the client.
-    const socket = new WsTransport({
-        baseUrl: args.baseUrl,
-        kind: args.kind,
-        getAuthToken: args.getAuthToken,
-        syncGroups: [...args.syncGroups],
-        collaborationEvents: [...(options.collaborationEvents ?? [])],
-        logger: args.logger,
-        observability: args.observability,
-    });
-    // Claim push is core coordination: the stream attaches to the socket now
-    // and starts reporting the moment the feed opens.
-    const claims = createClaimStream({ participantId: args.participantId, logger: args.logger }, socket);
-    function connect(opts) {
-        if (socket.isConnected())
-            return Promise.resolve();
-        const timeoutMs = opts?.timeoutMs ?? CONNECT_TIMEOUT_MS;
-        return new Promise((resolve, reject) => {
-            const offs = [];
-            let done = false;
-            const settle = (fn) => {
-                if (done)
-                    return;
-                done = true;
-                clearTimeout(timer);
-                for (const off of offs)
-                    off();
-                fn();
-            };
-            offs.push(socket.subscribe('connected', () => { settle(resolve); }));
-            offs.push(socket.subscribe('handshake_failed', (event) => {
-                settle(() => {
-                    reject(new AbloConnectionError(`The live feed's connection was refused (close code ${event.code}). ` +
-                        'Check the credential and the server URL; reads and writes still work without the feed.', { code: 'ws_not_ready' }));
-                });
-            }));
-            offs.push(socket.subscribe('reconnect_failed', ({ attempts }) => {
-                settle(() => {
-                    reject(new AbloConnectionError(`The live feed did not come up after ${attempts} attempts. ` +
-                        'Reads and writes still work without it; call connect() again to retry.', { code: 'ws_not_ready' }));
-                });
-            }));
-            const timer = setTimeout(() => {
-                settle(() => {
-                    reject(new AbloConnectionError(`The live feed did not connect within ${timeoutMs}ms. ` +
-                        'Reads and writes still work without it; call connect() again to retry.', { code: 'ws_not_ready' }));
-                });
-            }, timeoutMs);
-            socket.connect();
-        });
-    }
-    // The feed members layered over the stateless surface. `dispose` is
-    // deliberately shadowed: closing the client closes the feed too.
-    const feed = {
-        connect,
-        disconnect: () => { socket.disconnect(); },
-        isConnected: () => socket.isConnected(),
-        subscribe: socket.subscribe.bind(socket),
-        claims,
-        dispose: async () => {
-            claims.dispose();
-            socket.disconnect();
-            await http.dispose();
-        },
-    };
-    return new Proxy(http, {
-        get(target, prop, receiver) {
-            if (typeof prop === 'string' && prop in feed)
-                return feed[prop];
-            return Reflect.get(target, prop, receiver);
-        },
-    });
-}

package/dist/client/createInternalComponents.d.ts

@@ -1,46 +0,0 @@
-/**
- * Builds the internal component graph the client runs on.
- *
- * From the caller's options and schema this wires together the model registry,
- * object pool, bootstrap helper, database, sync client, and hydration
- * coordinator. Each component depends on the one before it, so construction
- * order matters; keeping it here means the client constructor does not have to
- * know that order.
- */
-import { Database } from '../Database.js';
-import { ModelRegistry } from '../ModelRegistry.js';
-import { InstanceCache } from '../InstanceCache.js';
-import { SyncClient } from '../SyncClient.js';
-import { OnDemandLoader } from '../sync/OnDemandLoader.js';
-import { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
-import type { AuthCredentialSource } from '../transaction/auth/credentialSource.js';
-import type { Schema, SchemaRecord } from '../transaction/schema/schema.js';
-import { type AbloPersistence } from '../transaction/persistence.js';
-import type { DurableWriteStore, DurableWritesConfig } from '../transactions/mutations/durableWriteStore.js';
-export interface InternalComponentsInput<S extends SchemaRecord> {
-    readonly schema: Schema<S>;
-    /** The WebSocket URL. Used to derive the bootstrap HTTP base URL when the
-     * caller has not overridden `bootstrapBaseUrl`. */
-    readonly url: string;
-    readonly options: {
-        readonly maxPoolSize?: number;
-        readonly bootstrapBaseUrl?: string;
-        readonly syncGroups?: string[];
-        readonly persistence?: AbloPersistence;
-        readonly offline?: boolean;
-        readonly inMemory?: boolean;
-        readonly durableWrites?: DurableWritesConfig;
-        /** @deprecated Use `durableWrites`. */
-        readonly commitOutbox?: DurableWriteStore;
-    };
-    readonly auth?: AuthCredentialSource;
-}
-export interface InternalComponents {
-    readonly modelRegistry: ModelRegistry;
-    readonly objectPool: InstanceCache;
-    readonly bootstrapHelper: BootstrapFetcher;
-    readonly database: Database;
-    readonly syncClient: SyncClient;
-    readonly hydration: OnDemandLoader;
-}
-export declare function createInternalComponents<S extends SchemaRecord>(input: InternalComponentsInput<S>): InternalComponents;

package/dist/client/createInternalComponents.js

@@ -1,92 +0,0 @@
-/**
- * Builds the internal component graph the client runs on.
- *
- * From the caller's options and schema this wires together the model registry,
- * object pool, bootstrap helper, database, sync client, and hydration
- * coordinator. Each component depends on the one before it, so construction
- * order matters; keeping it here means the client constructor does not have to
- * know that order.
- */
-import { Database } from '../Database.js';
-import { ModelRegistry, setActiveRegistry } from '../ModelRegistry.js';
-import { InstanceCache } from '../InstanceCache.js';
-import { SyncClient } from '../SyncClient.js';
-import { OnDemandLoader } from '../sync/OnDemandLoader.js';
-import { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
-import { loadsAtBootstrap } from '../transaction/schema/loadStrategy.js';
-import { resolveBootstrapBaseUrl } from '../transaction/auth/apiKey.js';
-import { shouldUseInMemoryPersistence } from '../transaction/persistence.js';
-import { resolveDurableWrites } from '../transaction/durableWrites.js';
-export function createInternalComponents(input) {
-    const { schema, url, options, auth } = input;
-    // The registry is created here, but model registration happens in the caller,
-    // which owns the schema-to-class translation.
-    const modelRegistry = new ModelRegistry({
-        validateOnRegister: false,
-        allowLateReferences: true,
-    });
-    setActiveRegistry(modelRegistry);
-    const objectPool = new InstanceCache({ maxSize: options.maxPoolSize ?? 10000 }, modelRegistry);
-    const bootstrapBaseUrl = resolveBootstrapBaseUrl({
-        url,
-        bootstrapBaseUrl: options.bootstrapBaseUrl,
-    });
-    const bootstrapHelper = new BootstrapFetcher({
-        baseUrl: bootstrapBaseUrl,
-        syncGroups: options.syncGroups,
-        instantModels: deriveInstantModels(schema),
-        getAuthToken: auth?.getAuthToken,
-    });
-    const database = new Database(modelRegistry, bootstrapHelper, {
-        // By default there is no browser-local durable store unless the caller asks
-        // for one. Node and edge runtimes always use the in-memory store because
-        // IndexedDB is unavailable there.
-        inMemory: shouldUseInMemoryPersistence(options),
-    });
-    const durableWrites = resolveDurableWrites(options);
-    const syncClient = new SyncClient(objectPool, database, durableWrites.store, durableWrites.namespace ?? url);
-    // Lazy-load lane: hydrates the object pool and IndexedDB on demand for
-    // entities not in scope at bootstrap (`load: 'lazy'` models, or an entity
-    // reached by deep link before the pool warmed up). Single-flight, with
-    // write-through to IndexedDB.
-    const hydration = new OnDemandLoader({
-        objectPool,
-        database,
-        registry: modelRegistry,
-        schema,
-        baseUrl: bootstrapBaseUrl,
-        getAuthToken: auth?.getAuthToken,
-    });
-    // Drop the lazy-lane hydration ledger on reconnect. While connected, the
-    // WebSocket delta stream keeps hydrated rows fresh so repeat reads serve
-    // pure-local with no network; after a drop, deltas may have been missed, so
-    // the next read of each query must re-confirm with the server once.
-    syncClient.on('sync:reconnecting', () => { hydration.invalidate(); });
-    return {
-        modelRegistry,
-        objectPool,
-        bootstrapHelper,
-        database,
-        syncClient,
-        hydration,
-    };
-}
-/**
- * Derives the set of models to fetch in the initial bootstrap request from each
- * model's load strategy. Models declared `load: 'lazy'` are left out of the
- * bootstrap and fetched on demand instead. The default strategy is
- * `'instant'`, which includes the model.
- */
-function deriveInstantModels(schema) {
-    const schemaModels = schema.models ?? schema;
-    return Object.entries(schemaModels).flatMap(([key, def]) => {
-        if (!def || typeof def !== 'object' || !('load' in def)) {
-            return [key]; // no load → the default strategy
-        }
-        const load = def.load;
-        if (loadsAtBootstrap(load)) {
-            return [def.typename ?? key];
-        }
-        return [];
-    });
-}

package/dist/client/createModelProxy.d.ts

@@ -1,228 +0,0 @@
-/**
- * Builds the typed client for a single schema model — the object reached as
- * `ablo.<model>`.
- *
- * Each schema model gets one {@link ModelOperations}: the async server reads
- * `retrieve` and `list`, the same verbs restricted to the local graph under
- * `local`, the writes `create`, `update`, and `delete`, the coordination
- * namespace `claim` (callable as `claim({ id })`, plus `claim.state`,
- * `claim.queue`, `claim.release`, and `claim.reorder`), `join`, and `onChange`.
- * The factory returns a plain object; the client assembles the `ablo.<model>`
- * lookup table from one of these per model.
- */
-import type { ModelTarget } from '../transaction/coordination/schema.js';
-import type { ModelRegistry } from '../ModelRegistry.js';
-import type { InstanceCache } from '../InstanceCache.js';
-import type { SyncClient } from '../SyncClient.js';
-import type { OnDemandLoader } from '../sync/OnDemandLoader.js';
-import type { JoinedParticipant } from '../sync/participants.js';
-import type { Duration, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, ClaimWaitOptions, Snapshot } from '../transaction/types/streams.js';
-export type { ModelListScope, ModelTrackParams, ModelTrackResult, LocalReadOptions, LocalCountOptions, ServerReadOptions, ServerRetrieveOptions, ClaimTargetOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimOptions, ClaimReadApi, AwaitedClaimMethod, ClaimApi, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, JoinOptions, } from '../transaction/resources/modelOperations.js';
-export type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease };
-import type { ClaimApi, JoinOptions, LocalCountOptions, LocalReadOptions } from '../transaction/resources/modelOperations.js';
-import type { HttpModelClient } from '../transaction/transport/httpClient.js';
-import type { ParticipantKind } from '../transaction/types/participant.js';
-export interface ModelClientMeta {
-    readonly key: string;
-    readonly typename: string;
-}
-export declare function getModelClientMeta(modelClient: unknown): ModelClientMeta | undefined;
-/**
- * The entity a coordination read names, without the sub-entity narrowing —
- * projected from {@link ModelTarget} so the two members are spelled once.
- */
-type EntityHalf = Pick<ModelTarget, 'model' | 'id'>;
-export interface ModelCollaboration {
-    createClaim(options: {
-        /**
-         * The locator, in the spelling the SDK surface and the HTTP routes use.
-         * The canonical {@link ModelTarget} rather than a shape spelled here: this
-         * boundary is what a claim's narrowing has to cross, and a member missing
-         * from it dies before the socket sees it.
-         */
-        target: ModelTarget;
-        /** Peer-visible description of the work (`'rewriting the risk section'`). */
-        description?: string;
-        ttl?: Duration;
-        /**
-         * Block on the server's fair FIFO queue when the target is held, rather
-         * than failing. Resolves only once the lease is genuinely ours (the head
-         * of the line). `takeClaim` sets this so writers serialize on contention.
-         */
-        queue?: boolean;
-        /** Reject (don't wait) if the queue is already this deep when we join. */
-        maxQueueDepth?: number;
-    }): Promise<Claim>;
-    createSnapshot(modelKey: string, id: string): Snapshot;
-    /**
-     * Current coordination state on a target — who (if anyone) holds it.
-     * Synchronous reactive snapshot read off the presence/claim stream;
-     * `null` when the target is free. The wiring site computes it because
-     * only it knows the local participant id (needed to distinguish "I
-     * hold it" from "someone else holds it").
-     *
-     * Named `state` to match the public `ablo.<model>.claim.state({ id })` read —
-     * one verb for "who holds this" across every claim surface; the only
-     * difference is this internal contract takes an explicit `{ model, id }`
-     * target because it isn't bound to a single model.
-     */
-    state(target: EntityHalf): Claim | null;
-    /**
-     * The reactive wait queue on a target — the FIFO line of queued claims
-     * behind the holder. Synchronous snapshot off the synced claim stream.
-     */
-    queue(target: EntityHalf): readonly Claim[];
-    /**
-     * Re-rank the wait queue on a target (privileged — server-gated). `order` is
-     * the desired front-of-line ordering, taken from `queue(target)`.
-     */
-    reorder(target: EntityHalf, order: readonly Claim[]): void;
-    /**
-     * Resolve once no participant holds an active claim on the target.
-     * The contender's "wait until it's free" — delegates to the claim
-     * stream's `waitFor`.
-     */
-    waitFor(target: EntityHalf, options?: ClaimWaitOptions): Promise<void>;
-    /**
-     * The local participant's id. Used to distinguish "I already hold this"
-     * from "someone else holds it" in `claimOrWait`.
-     */
-    readonly selfParticipantId: string;
-    /**
-     * The local participant's kind (`'user' | 'agent' | 'system'`). Used to stamp
-     * the synthesized self-claim returned from `claim.state` when this client
-     * holds the lease: server presence frames exclude a holder's own claims, so
-     * the holder builds its own view.
-     */
-    readonly selfParticipantKind?: ParticipantKind;
-    /**
-     * Subscribes the connection to a scope's sync group(s) — read interest. The
-     * typed surface calls this on single-entity reads and claim observation so a
-     * client lands in the same entity-scoped group the holder's claim presence
-     * fans out on; a peer subscribed only to broader `org:` or `user:` groups
-     * would otherwise never see claim broadcasts. Fire-and-forget and best-effort:
-     * read interest must never make a read reject or stall. Optional so minimal
-     * test doubles can omit it.
-     */
-    enterScope?(scope: Record<string, string>): void | Promise<void>;
-    /**
-     * Pins a scope's sync group(s) — write intent: a row this client holds an
-     * active claim on stays subscribed regardless of navigation. Same
-     * fire-and-forget, best-effort semantics as `enterScope`.
-     */
-    pinScope?(scope: Record<string, string>): void | Promise<void>;
-    /**
-     * Opens a presence and claim subscription on this model's sync group(s) and
-     * returns the live participant handle. Backs `ablo.<model>.join(ids)`.
-     * WebSocket only, since presence needs a live socket; it is absent on other
-     * client constructions, where the proxy throws a clear error.
-     */
-    createJoin?(modelKey: string, ids: string | readonly string[], options?: JoinOptions): Promise<JoinedParticipant>;
-}
-/**
- * The synchronous, local-only reads — reached as `ablo.<model>.local.*`.
- *
- * Every verb mirrors its asynchronous sibling on the base surface, and the one
- * word in front is the whole difference. It is a narrowing, not a claim about
- * the other side: `retrieve` consults the local graph and then the network,
- * while `local.retrieve` is restricted to what is already resident — which is
- * also why it can return a value instead of a promise. There is nothing to
- * await.
- *
- * These reads exist only here. Exposing them at the top level too would undo
- * the distinction the namespace draws.
- */
-export interface LocalReads<T> {
-    /**
-     * Snapshot of a single row from the local graph. `undefined` when the row is
-     * not resident — a graph that is still empty, or a `lazy` model not yet
-     * loaded. Pairs with reactive selectors:
-     * `useAblo((ablo) => ablo.<model>.local.retrieve(id))`.
-     */
-    retrieve(id: string): T | undefined;
-    /**
-     * Snapshot of a filtered collection from the local graph. Empty until
-     * `retrieve`, `list`, or bootstrap has warmed the graph.
-     */
-    list(options?: LocalReadOptions<T>): T[];
-    /** Count rows in the local graph. */
-    count(options?: LocalCountOptions<T>): number;
-}
-/**
- * What a reactive client adds on top of the base per-model surface: a live
- * graph to read (`local`), the synchronous projection of the claim reads, and
- * the two subscriptions a persistent socket makes possible.
- *
- * `claim` is here rather than inherited because the two transports carry
- * deliberately different claim types, and the difference is load-bearing: a
- * stateless client has no local copy, so `state`/`queue`/`reorder` must be
- * awaited, while a reactive client resolves them synchronously — which is
- * precisely what lets a React render read claim state inline. The stateless
- * form is *derived* from this one through {@link AwaitedClaimMethod}, so the
- * only permitted difference between them is that promise wrapper.
- */
-interface ReactiveModelSurface<T> {
-    /** The synchronous local-graph reads. */
-    local: LocalReads<T>;
-    /**
-     * Claim a row so other writers wait or are rejected until you're done, and
-     * inspect or manage that coordination through the same namespace. Call it to
-     * take a claim handle; reach for its members to observe and steer the wait line:
-     *
-     * - `claim.state({ id })` — who holds the row now, or `null` when free
-     * - `claim.queue({ id })` — who's lined up behind the holder
-     * - `claim.release({ id })` — drop a claim early (usually implicit on scope exit)
-     * - `claim.reorder({ id, order })` — re-rank the wait line
-     *
-     * ```ts
-     * const claim = await ablo.weatherReports.claim({
-     *   id: 'report_stockholm',
-     *   description: 'Fetching fresh weather before updating the report.',
-     * });
-     * const weather = await getWeather(claim.data.location);
-     * await ablo.weatherReports.update({
-     *   id: claim.target.id,
-     *   data: { forecast: weather },
-     *   claim,
-     * });
-     * await claim.release();
-     *
-     * const holder = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
-     * ```
-     */
-    claim: ClaimApi<T>;
-    /**
-     * Joins the sync group(s) for one or more rows of this model and returns a
-     * live participant handle — presence (`.peers`), the scoped claim stream
-     * (`.claims`), and `.leave()` / `await using` disposal. This is a presence
-     * subscription: it reports who else is here and what they hold, not row
-     * values changing — for the latter, use `onChange`.
-     *
-     * WebSocket only: presence needs a live socket, so this is absent on HTTP
-     * clients and throws on any non-WebSocket construction.
-     *
-     * ```ts
-     * await using participant = await ablo.sections.join(sectionIds, { ttl: '5m' });
-     * participant.peers; // who else is here
-     * ```
-     */
-    join(ids: string | readonly string[], options?: JoinOptions): Promise<JoinedParticipant>;
-    /** Subscribe to changes; the callback runs on every change. */
-    onChange(callback: (entities: T[]) => void, options?: LocalReadOptions<T>): () => void;
-}
-/**
- * Everything reachable as `ablo.<model>` on a reactive client.
- *
- * The base is not written here — it is the transport-independent per-model
- * surface, taken whole. A reactive client is that surface plus what a live
- * graph makes possible, so this type states the relationship instead of
- * restating the members, and a verb added to the base arrives here on its own.
- *
- * `claim` is the one member the base cannot supply directly: the two forms
- * differ by an awaitedness transform, so it is replaced rather than inherited.
- * See {@link ReactiveModelSurface}.
- */
-export type ModelOperations<T, CreateInput> = Omit<HttpModelClient<T, CreateInput>, 'claim'> & ReactiveModelSurface<T>;
-export declare function createModelProxy<T, C>(schemaKey: string, registeredModelName: string, objectPool: InstanceCache, syncClient: SyncClient, registry: ModelRegistry, hydration: OnDemandLoader, collaboration?: ModelCollaboration, 
-/** The client-wide `wait` default; a per-call `wait` still wins over it. */
-defaultWait?: 'queued' | 'confirmed'): ModelOperations<T, C>;