@abloatai/humans 0.37.0

package/dist/local/client/createModelProxy.d.ts

@@ -0,0 +1,248 @@
+/**
+ * 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
+ * `get` and `list`, with the same point lookup 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 '@abloatai/transaction/coordination/schema';
+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 '@abloatai/transaction/types/streams';
+export type { ModelListScope, ModelTrackParams, ModelTrackResult, LocalReadOptions, LocalCountOptions, ServerReadOptions, ServerGetOptions, ServerRetrieveOptions, ClaimTargetOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimOptions, ClaimReadApi, AwaitedClaimMethod, ClaimApi, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, JoinOptions, } from '@abloatai/transaction/resources/modelOperations';
+export type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease };
+import type { ClaimApi, JoinOptions, LocalCountOptions, LocalReadOptions } from '@abloatai/transaction/resources/modelOperations';
+import type { HttpModelClient } from '@abloatai/transaction/transport/httpClient';
+import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+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;
+        /** Cap on the queued wait before rejecting with `grant_timeout`. */
+        waitTimeoutMs?: number;
+        /** Abort the queued wait — rejects with `claim_wait_aborted`. */
+        signal?: AbortSignal;
+    }): 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;
+    /**
+     * Every active claim on a target, not just one. Sub-row claims on disjoint
+     * parts of a row are all granted, so a row can have several holders at once
+     * and `state` answers with only the first of them.
+     */
+    holders(target: EntityHalf): readonly Claim[];
+    /**
+     * 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: `get` consults the local graph and then the network,
+ * while `local.get` 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.get(id))`.
+     */
+    get(id: string): T | undefined;
+    /**
+     * Snapshot of a filtered collection from the local graph. Empty until
+     * `get`, `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, Fields = 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, Fields>;
+    /**
+     * 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, CreateInput>;
+export declare function createModelProxy<T, C>(schemaKey: string, registeredModelName: string, objectPool: Pick<InstanceCache, 'get' | 'getByType' | 'getOfType'>, syncClient: Pick<SyncClient, 'add' | 'delete' | 'getMutationQueue' | 'getOrganizationId' | 'syncNow' | 'update' | 'waitForConfirmation'>, registry: Pick<ModelRegistry, 'getModelByName'>, 
+/**
+ * The one thing this factory asks of the loader: fetch rows for a model.
+ *
+ * Declared as the slice rather than the whole `OnDemandLoader` because the
+ * whole is a class, and a parameter typed as a class can only ever be
+ * satisfied by an instance of it — so every caller that has a narrower
+ * collaborator, a test most of all, is pushed into a cast through `unknown`
+ * to supply the one method that is actually read.
+ */
+hydration: Pick<OnDemandLoader, 'fetch'>, collaboration?: ModelCollaboration, 
+/** The client-wide `wait` default; a per-call `wait` still wins over it. */
+defaultWait?: 'queued' | 'confirmed'): ModelOperations<T, C>;