@lunora/client 1.0.0-alpha.4 → 1.0.0-alpha.6

package/README.md

@@ -74,6 +74,8 @@ const unsubscribe = client.subscribe(api.messages.list, { room: "general" }, (ne
 client.close();
 ```
 
+`client.subscribeShape({ name, args }, cb)` is the [local-first sync engine](https://lunora.sh/docs/concepts/local-first)'s parallel to `subscribe`: it replicates a **partial view** of a table (a server-defined shape) over the poke diff protocol instead of re-running a query. Most apps consume it through [`@lunora/db`](https://www.npmjs.com/package/@lunora/db)'s `lunoraCollectionOptions({ shape })` rather than directly.
+
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/api/client)**.
 
 ## Related

package/dist/auth/index.d.mts

@@ -1,4 +1,4 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-CbnxmuqG.mjs";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-DzEWBYeP.mjs";
 import '@lunora/runtime';
 interface IdentityStore {
   /** Read the current resolved user, or `null` when signed out / not yet resolved. */

package/dist/auth/index.d.ts

@@ -1,4 +1,4 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-CbnxmuqG.js";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-DzEWBYeP.js";
 import '@lunora/runtime';
 interface IdentityStore {
   /** Read the current resolved user, or `null` when signed out / not yet resolved. */

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-CbnxmuqG.mjs";
-export { type C as CachedQuery, type e as ClientMessage, type f as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type g as FunctionArgumentDescriptor, type h as FunctionDescriptor, type G as GlobalFacetResult, type i as GlobalFacetValue, type j as GlobalFilterClause, type k as GlobalTableInfo, type l as GlobalTablePage, L as LunoraClient, type m as LunoraClientOptions, type n as OptimisticLocalStore, type o as OptimisticUpdate, type p as PersistedMutation, type P as Preloaded, type q as RpcEnvelope, type r as RpcResponseBody, type s as ScheduleRecord, type t as SchedulerPoolStatus, type u as SchedulerStatus, type v as ServerMessage, type w as ShardTrafficEntry, type x as ShardTrafficResult, type y as StorageListPage, type z as StorageObject, type E as StreamHandle, type H as StreamIterable, type I as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, J as SubscriptionRegistry, type K as SubscriptionState, type a as Unsubscribe, type U as User, type W as WorkflowInstanceAction, type N as WorkflowInstanceDetail, type T as WorkflowInstancePage, type V as WorkflowInstanceStatus, type X as WorkflowInstanceSummary, type Y as WorkflowStepDetail, Z as createLocalStore, _ as createStream } from "./packem_shared/lunora-client.d-CbnxmuqG.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-Bhq6DBSe.mjs";
+import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-DzEWBYeP.mjs";
+export { type C as CachedQuery, type e as ClientMessage, type f as ClientShapeSubscribeMessage, type g as ClientShapeUnsubscribeMessage, type h as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type i as FunctionArgumentDescriptor, type j as FunctionDescriptor, type G as GlobalFacetResult, type k as GlobalFacetValue, type l as GlobalFilterClause, type m as GlobalTableInfo, type n as GlobalTablePage, L as LunoraClient, type o as LunoraClientOptions, type p as OptimisticLocalStore, type q as OptimisticUpdate, type r as OutboxMutation, type s as OutboxSink, type t as PersistedMutation, type P as Preloaded, type u as RowOp, type v as RpcEnvelope, type w as RpcResponseBody, type x as ScheduleRecord, type y as SchedulerPoolStatus, type z as SchedulerStatus, type E as ServerMessage, type H as ServerPokeEndMessage, type I as ServerPokePartMessage, type J as ServerPokeStartMessage, type K as ShardTrafficEntry, type N as ShardTrafficResult, type T as StorageListPage, type V as StorageObject, type W as StreamHandle, type X as StreamIterable, type Y as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, Z as SubscriptionRegistry, type _ as SubscriptionState, type $ as SyncWatermark, type a as Unsubscribe, type U as User, type a0 as WorkflowInstanceAction, type a1 as WorkflowInstanceDetail, type a2 as WorkflowInstancePage, type a3 as WorkflowInstanceStatus, type a4 as WorkflowInstanceSummary, type a5 as WorkflowStepDetail, a6 as createLocalStore, a7 as createStream } from "./packem_shared/lunora-client.d-DzEWBYeP.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-DuYqEQ5J.mjs";
 export type { AuthCapabilities, AuthImpersonation, AuthPage, AuthSession, AuthUser, CronJobInfo, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
 /**
 * The slice of React Native's `AsyncStorage` (or any async key/value store —
@@ -136,6 +136,59 @@ interface MutationRunnerSinks<R> {
 * pass straight through to `client.mutation`.
 */
 declare const createMutationRunner: <F extends FunctionReference>(client: MutationCapableClient<F>, function_: F, sinks: MutationRunnerSinks<ReturnOf<F>>) => ((args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>);
+/**
+* The structural surface of a TanStack `Transaction` a bound custom mutator
+* returns — its `isPersisted.promise` resolves once the write is persisted and
+* rejects on failure. Typed structurally so the framework adapters need not
+* depend on `@tanstack/db` or `@lunora/db` (the handle is created app-side by
+* `bindMutators`).
+*/
+interface MutatorTransaction {
+  isPersisted: {
+    promise: Promise<unknown>;
+  };
+}
+/**
+* A bound custom-mutator handle produced by `bindMutators(client, ctx, mutators)`
+* in `@lunora/db`. Calling it applies the optimistic overlay to the local
+* collections and pushes the authoritative server write; it returns the TanStack
+* transaction whose `isPersisted` promise tracks completion.
+*/
+type MutatorHandle<TArgs> = (args: TArgs) => MutatorTransaction;
+/**
+* Reactive sinks an adapter binds to its own primitive's setters (a React
+* `useState`, a Solid signal, a Vue ref, a Svelte store). The runner pushes into
+* them; how they store the value is the adapter's concern.
+*/
+interface MutatorRunnerSinks {
+  /** Receives the normalized {@link Error} when an invocation rejects, or `undefined` on success / reset. */
+  setError: (error: Error | undefined) => void;
+  /** Receives `true` while at least one invocation is in flight (ref-counted across overlapping calls), else `false`. */
+  setPending: (pending: boolean) => void;
+}
+/**
+* Build the framework-neutral `mutate` / `reset` pair of an adapter's
+* custom-mutator hook (`useMutator` / `createMutator` / `mutator`).
+*
+* Owns the orchestration every adapter otherwise copy-pastes: ref-counts
+* overlapping invocations into `setPending` (so it only clears once the last
+* settles), awaits the bound handle's `isPersisted` promise, normalizes a thrown
+* non-`Error`, and routes failure to `setError` (clearing it on success) before
+* re-throwing. Each adapter (`@lunora/react`, `/solid`, `/svelte`, `/vue`) binds
+* the two sinks to its own reactive setters, so this logic lives in exactly one
+* place. The optimistic overlay + server push are owned by the bound handle.
+*
+* `error` tracks the LATEST invocation, not the last to settle: overlapping
+* calls can resolve out of order, so an earlier call that finishes later must
+* not clobber a newer call's outcome. Each invocation takes a monotonic token
+* and only writes `setError` while it is still the most recent one — otherwise
+* `error`/`isError` could surface a stale success or failure (the documented
+* "latest invocation's error" contract every adapter advertises).
+*/
+declare const createMutatorRunner: <TArgs>(handle: MutatorHandle<TArgs>, sinks: MutatorRunnerSinks) => {
+  mutate: (args: TArgs) => Promise<void>;
+  reset: () => void;
+};
 interface QueuedMutation<T = unknown> {
   readonly args: Record<string, unknown>;
   readonly functionPath: string;
@@ -153,6 +206,16 @@ interface QueuedMutation<T = unknown> {
   readonly shardKey?: string;
 }
 /**
+* A process-unique id, used both per-mutation and as the fallback `clientId`. It
+* MUST be globally unique: the server scopes a custom mutator's replay watermark
+* by `(verifiedIdentity, clientId)`, and an anonymous push has no verified
+* identity — so two anonymous clients that collide on `clientId` would share one
+* watermark namespace, letting one stall/suppress the other's ordered mutations.
+* `crypto.randomUUID` covers every modern runtime; the fallback still mixes
+* crypto-quality (or `Math.random`) entropy with the timestamp + counter so it
+* can't collide across two clients started in the same millisecond.
+*/
+/**
 * Bounded FIFO queue. Mutations issued while the client is offline are
 * enqueued and replayed in the order they were submitted once the WS
 * reconnects and identifies. If the queue exceeds `maxItems` the oldest
@@ -278,4 +341,4 @@ interface ReconnectCalculator {
   reset: () => void;
 }
 declare const createReconnect: (options?: ReconnectOptions, random?: () => number) => ReconnectCalculator;
-export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, CONFLICT_ERROR_CODE, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createReconnect, isConflictError, isMutationDelta, queryCacheKey };
+export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, CONFLICT_ERROR_CODE, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, isConflictError, isMutationDelta, queryCacheKey };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-CbnxmuqG.js";
-export { type C as CachedQuery, type e as ClientMessage, type f as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type g as FunctionArgumentDescriptor, type h as FunctionDescriptor, type G as GlobalFacetResult, type i as GlobalFacetValue, type j as GlobalFilterClause, type k as GlobalTableInfo, type l as GlobalTablePage, L as LunoraClient, type m as LunoraClientOptions, type n as OptimisticLocalStore, type o as OptimisticUpdate, type p as PersistedMutation, type P as Preloaded, type q as RpcEnvelope, type r as RpcResponseBody, type s as ScheduleRecord, type t as SchedulerPoolStatus, type u as SchedulerStatus, type v as ServerMessage, type w as ShardTrafficEntry, type x as ShardTrafficResult, type y as StorageListPage, type z as StorageObject, type E as StreamHandle, type H as StreamIterable, type I as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, J as SubscriptionRegistry, type K as SubscriptionState, type a as Unsubscribe, type U as User, type W as WorkflowInstanceAction, type N as WorkflowInstanceDetail, type T as WorkflowInstancePage, type V as WorkflowInstanceStatus, type X as WorkflowInstanceSummary, type Y as WorkflowStepDetail, Z as createLocalStore, _ as createStream } from "./packem_shared/lunora-client.d-CbnxmuqG.js";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-C73DT6bL.js";
+import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-DzEWBYeP.js";
+export { type C as CachedQuery, type e as ClientMessage, type f as ClientShapeSubscribeMessage, type g as ClientShapeUnsubscribeMessage, type h as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type i as FunctionArgumentDescriptor, type j as FunctionDescriptor, type G as GlobalFacetResult, type k as GlobalFacetValue, type l as GlobalFilterClause, type m as GlobalTableInfo, type n as GlobalTablePage, L as LunoraClient, type o as LunoraClientOptions, type p as OptimisticLocalStore, type q as OptimisticUpdate, type r as OutboxMutation, type s as OutboxSink, type t as PersistedMutation, type P as Preloaded, type u as RowOp, type v as RpcEnvelope, type w as RpcResponseBody, type x as ScheduleRecord, type y as SchedulerPoolStatus, type z as SchedulerStatus, type E as ServerMessage, type H as ServerPokeEndMessage, type I as ServerPokePartMessage, type J as ServerPokeStartMessage, type K as ShardTrafficEntry, type N as ShardTrafficResult, type T as StorageListPage, type V as StorageObject, type W as StreamHandle, type X as StreamIterable, type Y as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, Z as SubscriptionRegistry, type _ as SubscriptionState, type $ as SyncWatermark, type a as Unsubscribe, type U as User, type a0 as WorkflowInstanceAction, type a1 as WorkflowInstanceDetail, type a2 as WorkflowInstancePage, type a3 as WorkflowInstanceStatus, type a4 as WorkflowInstanceSummary, type a5 as WorkflowStepDetail, a6 as createLocalStore, a7 as createStream } from "./packem_shared/lunora-client.d-DzEWBYeP.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-CmMMC-wm.js";
 export type { AuthCapabilities, AuthImpersonation, AuthPage, AuthSession, AuthUser, CronJobInfo, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
 /**
 * The slice of React Native's `AsyncStorage` (or any async key/value store —
@@ -136,6 +136,59 @@ interface MutationRunnerSinks<R> {
 * pass straight through to `client.mutation`.
 */
 declare const createMutationRunner: <F extends FunctionReference>(client: MutationCapableClient<F>, function_: F, sinks: MutationRunnerSinks<ReturnOf<F>>) => ((args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>);
+/**
+* The structural surface of a TanStack `Transaction` a bound custom mutator
+* returns — its `isPersisted.promise` resolves once the write is persisted and
+* rejects on failure. Typed structurally so the framework adapters need not
+* depend on `@tanstack/db` or `@lunora/db` (the handle is created app-side by
+* `bindMutators`).
+*/
+interface MutatorTransaction {
+  isPersisted: {
+    promise: Promise<unknown>;
+  };
+}
+/**
+* A bound custom-mutator handle produced by `bindMutators(client, ctx, mutators)`
+* in `@lunora/db`. Calling it applies the optimistic overlay to the local
+* collections and pushes the authoritative server write; it returns the TanStack
+* transaction whose `isPersisted` promise tracks completion.
+*/
+type MutatorHandle<TArgs> = (args: TArgs) => MutatorTransaction;
+/**
+* Reactive sinks an adapter binds to its own primitive's setters (a React
+* `useState`, a Solid signal, a Vue ref, a Svelte store). The runner pushes into
+* them; how they store the value is the adapter's concern.
+*/
+interface MutatorRunnerSinks {
+  /** Receives the normalized {@link Error} when an invocation rejects, or `undefined` on success / reset. */
+  setError: (error: Error | undefined) => void;
+  /** Receives `true` while at least one invocation is in flight (ref-counted across overlapping calls), else `false`. */
+  setPending: (pending: boolean) => void;
+}
+/**
+* Build the framework-neutral `mutate` / `reset` pair of an adapter's
+* custom-mutator hook (`useMutator` / `createMutator` / `mutator`).
+*
+* Owns the orchestration every adapter otherwise copy-pastes: ref-counts
+* overlapping invocations into `setPending` (so it only clears once the last
+* settles), awaits the bound handle's `isPersisted` promise, normalizes a thrown
+* non-`Error`, and routes failure to `setError` (clearing it on success) before
+* re-throwing. Each adapter (`@lunora/react`, `/solid`, `/svelte`, `/vue`) binds
+* the two sinks to its own reactive setters, so this logic lives in exactly one
+* place. The optimistic overlay + server push are owned by the bound handle.
+*
+* `error` tracks the LATEST invocation, not the last to settle: overlapping
+* calls can resolve out of order, so an earlier call that finishes later must
+* not clobber a newer call's outcome. Each invocation takes a monotonic token
+* and only writes `setError` while it is still the most recent one — otherwise
+* `error`/`isError` could surface a stale success or failure (the documented
+* "latest invocation's error" contract every adapter advertises).
+*/
+declare const createMutatorRunner: <TArgs>(handle: MutatorHandle<TArgs>, sinks: MutatorRunnerSinks) => {
+  mutate: (args: TArgs) => Promise<void>;
+  reset: () => void;
+};
 interface QueuedMutation<T = unknown> {
   readonly args: Record<string, unknown>;
   readonly functionPath: string;
@@ -153,6 +206,16 @@ interface QueuedMutation<T = unknown> {
   readonly shardKey?: string;
 }
 /**
+* A process-unique id, used both per-mutation and as the fallback `clientId`. It
+* MUST be globally unique: the server scopes a custom mutator's replay watermark
+* by `(verifiedIdentity, clientId)`, and an anonymous push has no verified
+* identity — so two anonymous clients that collide on `clientId` would share one
+* watermark namespace, letting one stall/suppress the other's ordered mutations.
+* `crypto.randomUUID` covers every modern runtime; the fallback still mixes
+* crypto-quality (or `Math.random`) entropy with the timestamp + counter so it
+* can't collide across two clients started in the same millisecond.
+*/
+/**
 * Bounded FIFO queue. Mutations issued while the client is offline are
 * enqueued and replayed in the order they were submitted once the WS
 * reconnects and identifies. If the queue exceeds `maxItems` the oldest
@@ -278,4 +341,4 @@ interface ReconnectCalculator {
   reset: () => void;
 }
 declare const createReconnect: (options?: ReconnectOptions, random?: () => number) => ReconnectCalculator;
-export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, CONFLICT_ERROR_CODE, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createReconnect, isConflictError, isMutationDelta, queryCacheKey };
+export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, CONFLICT_ERROR_CODE, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, isConflictError, isMutationDelta, queryCacheKey };

package/dist/index.mjs

@@ -3,9 +3,10 @@ export { default as createInMemoryBookmarkStorage } from './packem_shared/create
 export { applyDelta, isMutationDelta } from './packem_shared/applyDelta-4jFGTPA3.mjs';
 export { CONFLICT_ERROR_CODE, isConflictError } from './packem_shared/CONFLICT_ERROR_CODE-aUdVbEDw.mjs';
 export { createLocalStore } from './packem_shared/createLocalStore-DSUfoLqY.mjs';
-export { LunoraClient } from './packem_shared/LunoraClient-DHMV-94j.mjs';
+export { LunoraClient } from './packem_shared/LunoraClient-DhwA_5Kj.mjs';
 export { createMutationRunner } from './packem_shared/createMutationRunner-BqsavzvG.mjs';
-export { OfflineQueue } from './packem_shared/OfflineQueue-D5p_QgF_.mjs';
+export { createMutatorRunner } from './packem_shared/createMutatorRunner-BETvCd0p.mjs';
+export { OfflineQueue } from './packem_shared/OfflineQueue-D-ASeqL7.mjs';
 export { createInMemoryPersistence, createIndexedDbPersistence } from './packem_shared/createInMemoryPersistence-CW82inU5.mjs';
 export { preloadQuery, preloadedQueryResult } from './packem_shared/preloadQuery-lobFkD2Z.mjs';
 export { createInMemoryQueryCache, createIndexedDbQueryCache, queryCacheKey } from './packem_shared/createInMemoryQueryCache-B1PQ9Twl.mjs';