@voltro/client 0.28.0 → 0.30.0

package/dist/index.d.ts

@@ -7,6 +7,10 @@ import { EventDescriptor as EventDescriptor_2 } from '@voltro/protocol';
 import { Fiber } from 'effect';
 import { ManagedRuntime } from 'effect';
 import { ReactNode } from 'react';
+import { Rpc } from '@effect/rpc';
+import { RpcClient } from '@effect/rpc';
+import { RpcClientError } from '@effect/rpc';
+import { RpcGroup } from '@effect/rpc';
 import { Schema } from 'effect';
 import { Stream } from 'effect';
 import { SubscriptionEvent } from '@voltro/protocol';
@@ -175,6 +179,13 @@ export declare interface ApiHandle {
     readonly errorBus: RpcErrorBus;
 }
 
+/**
+ * Apply preload seeds from the hydration payload, BEFORE the first client
+ * render. Idempotent (a Map upsert) so a re-hydration or a repeated key is
+ * harmless — last write wins, matching the store-seed rule.
+ */
+export declare const applyPreloadSeeds: (seeds: ReadonlyArray<PreloadSeed> | undefined) => void;
+
 /**
  * Apply seeds from the hydration payload, BEFORE the first client render.
  *
@@ -226,6 +237,43 @@ export declare interface AutoApplyTarget {
     readonly shapeItem?: ((input: Record<string, unknown>, currentOrOptimisticId: unknown) => Record<string, unknown>) | undefined;
 }
 
+/**
+ * Build one api's runtime + rpc client + subscription cache over a WebSocket.
+ *
+ * The returned `runtime` owns the socket; dispose it (`runtime.dispose()`, after
+ * `cache.destroy(runtime)`) to tear the connection down. A fresh cache is bound
+ * per resolved runtime — cross-runtime cache reuse is unsafe (its fibers
+ * reference the old runtime).
+ *
+ * Rejects if the runtime fails to resolve the client (e.g. the socket never
+ * opens); the caller's reconnect logic decides what to do with that.
+ */
+export declare const buildApiRuntime: (options: BuildApiRuntimeOptions) => Promise<BuiltApiRuntime>;
+
+export declare interface BuildApiRuntimeOptions {
+    /** Stable api name — used only to tag the client's Context. */
+    readonly name: string;
+    /** WebSocket URL of the api (`ws(s)://host:port/ws`). */
+    readonly wsUrl: string;
+    /** The api's rpc group (its typed procedure surface). */
+    readonly group: RpcGroup.RpcGroup<Rpc.Any>;
+    /** Per-connection auth headers (see {@link ResolvableHeaders}). */
+    readonly headers?: ResolvableHeaders | undefined;
+    /** How to construct a WebSocket. Web wraps `globalThis.WebSocket` with
+     *  tracking + a connect-timeout; RN passes a plain `globalThis.WebSocket`.
+     *  Injected so this module touches no environment global directly. */
+    readonly webSocketConstructor: (url: string, protocols?: string | ReadonlyArray<string>) => globalThis.WebSocket;
+}
+
+/** The transport-level pieces of one api's client stack. Combined with the
+ *  api's descriptor map + inspect base URL, this is an `ApiHandle`. */
+export declare interface BuiltApiRuntime {
+    readonly runtime: AnyRuntime;
+    readonly cache: SubscriptionCache;
+    readonly client: RpcClient.RpcClient<Rpc.Any, RpcClientError.RpcClientError>;
+    readonly errorBus: RpcErrorBus;
+}
+
 declare interface CacheEntry {
     readonly key: string;
     /** First element of the keyArr — the rpc tag (e.g. 'todos.list'). Used
@@ -820,6 +868,8 @@ export declare class LoadingSubscriptionCache extends SubscriptionCache {
     };
 }
 
+export declare const makePreloadSeedBag: () => PreloadSeedBag;
+
 export declare const makeStoreSeedBag: () => StoreSeedBag;
 
 /** Exported for tests: the inspect URL this hook fetches. */
@@ -1000,6 +1050,27 @@ export declare interface PersistOptions<S> {
     readonly migrate?: (stored: unknown) => Partial<S> | undefined;
 }
 
+/** Options `usePreloadedSubscription` accepts. It OWNS `initialSnapshot` (the
+ *  preload payload supplies it), so callers pass only `skip` — `fallback` and
+ *  `initialSnapshot` are its own concern. */
+export declare type PreloadedSubscriptionOptions = Pick<SubscriptionOptions<never>, 'skip'>;
+
+/** One preloaded subscription snapshot, as it travels in the hydration payload. */
+export declare interface PreloadSeed {
+    /** The api mount name the subscription reads from (first arg of `useSubscription`). */
+    readonly api: string;
+    /** `stableKey([rpcTag, input])` — identical to the SubscriptionCache's own key,
+     *  so the seed and the live subscription address the same entry. */
+    readonly key: string;
+    /** The server-fetched snapshot value. */
+    readonly value: unknown;
+}
+
+/** Collects preload seeds for ONE request. The server creates one per render. */
+export declare interface PreloadSeedBag {
+    readonly seeds: PreloadSeed[];
+}
+
 /** Structural mirror of @voltro/runtime's PreviewDiff (client stays decoupled). */
 export declare interface PreviewDiff {
     readonly rows: ReadonlyArray<PreviewRowDiff>;
@@ -1089,6 +1160,17 @@ export declare interface QueryFiltersState<Row> {
     readonly error: unknown | undefined;
 }
 
+/**
+ * The preloaded snapshot for `(api, rpcTag, input)`, or `undefined` when none was
+ * seeded. On the SERVER it reads the current request's bag directly, so the SSR
+ * markup and the client hydration render see the SAME value (no hydration
+ * flicker); on the CLIENT it reads the hydration-applied registry.
+ *
+ * A seed value is never `undefined` (it round-trips through JSON, so the worst
+ * case is `null`), which is why `undefined` unambiguously means "not seeded".
+ */
+export declare const readPreloadedSnapshot: (api: string, rpcTag: string, input: Readonly<Record<string, unknown>>) => unknown;
+
 export declare interface RecordState<R> {
     readonly record: R | undefined;
     readonly loading: boolean;
@@ -1112,9 +1194,17 @@ export declare const reportClientError: (error: unknown, context?: Record<string
  *  module-global flags + any pending grace-period timer). */
 export declare const _resetFrameworkRuntimesWarning: () => void;
 
+/** Drop all applied client-side seeds. Tests only. */
+export declare const resetPreloadSeeds: () => void;
+
 /** Test helper: forget every defined store. NEVER call this in app code. */
 export declare const resetStoreRegistryForTests: () => void;
 
+/** Auth headers to attach to every rpc MESSAGE frame, resolved on EVERY
+ *  (re)connect so a rotating token (a `() => Promise<…>` thunk) is fetched anew
+ *  each connection rather than frozen at first build. */
+export declare type ResolvableHeaders = Readonly<Record<string, string>> | (() => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>);
+
 export declare const resolveByTag: (client: unknown, tag: string) => unknown;
 
 /** Resolve one map entry against the props. Pure. */
@@ -1282,6 +1372,14 @@ export declare const schemaToColumns: (schema: Schema.Schema.Any) => ReadonlyArr
  */
 export declare const schemaToFields: (schema: Schema.Schema.Any) => ReadonlyArray<FieldDescriptor>;
 
+/**
+ * Seed a subscription's first value for THIS request's hydration. Call it on the
+ * server during a render — a loader, a layout loader — with the value a
+ * `ctx.query` already fetched, and `usePreloadedSubscription(api, rpcTag, input)`
+ * shows it at the first paint without any serialization step of your own.
+ */
+export declare const seedPreloadedSubscription: (api: string, rpcTag: string, input: Readonly<Record<string, unknown>>, value: unknown) => void;
+
 /**
  * Seed a store for THIS request's hydration. Call it anywhere on the server
  * during a render — a loader, a layout loader — and the value reaches the
@@ -1351,6 +1449,12 @@ export declare type SequenceResult<Ctx> = {
  *  at boot, next to your toast provider. */
 export declare const setMutationNotifier: (notifier: MutationNotifier | undefined) => void;
 
+/**
+ * Install the request-scoped bag resolver. Server-side only; pass `null` to
+ * uninstall (tests). `@voltro/web/ssr` registers it, backed by its own ALS.
+ */
+export declare const setPreloadSeedResolver: (resolver: (() => PreloadSeedBag | null) | null) => void;
+
 /**
  * Install the request-scoped bag resolver. Server-side only; pass `null` to
  * uninstall (tests).
@@ -2134,13 +2238,6 @@ export declare interface UploadResult {
 
 export declare type UploadStatus = 'idle' | 'uploading' | 'success' | 'error';
 
-/**
- * Invoke a server `defineAction` procedure by tag. Unlike `useMutation`,
- * an action has no optimistic / cache surface — it's a unary call whose
- * effects (sends, captures, side-effecting writes the framework must NOT
- * preview locally) only become visible when the server pushes a delta on
- * an independent subscription.
- */
 export declare const useAction: <Input = unknown, Output = unknown>(apiName: string, rpcTag: string) => ActionState<Input, Output>;
 
 export declare const useAgent: (apiName: string, rpcTag: string) => AgentControls;
@@ -2332,6 +2429,19 @@ export declare interface UseOutboxOptions {
 /** The current subject's scopes (defaults to none if no provider). */
 export declare const usePermissions: () => PermissionState_2;
 
+/**
+ * Subscribe to a streaming rpc, seeding the first value from the SSR preload
+ * payload when one exists.
+ *
+ * @param apiName  The api mount name (as in `useSubscription`).
+ * @param rpcTag   The rpc tag (e.g. `'projects.list'`).
+ * @param input    The rpc payload; part of the preload lookup key AND the
+ *                 subscription's cache key (identical `stableKey`).
+ * @param options  `{ skip }` — defers the subscription. `initialSnapshot`
+ *                 comes from the preload payload, not from here.
+ */
+export declare function usePreloadedSubscription<T = unknown>(apiName: string, rpcTag: string, input?: Readonly<Record<string, unknown>>, options?: PreloadedSubscriptionOptions): SubscriptionState<T> | SubscriptionIdle;
+
 export declare const usePreview: <Input = Record<string, unknown>>(apiName: string, previewTag: string) => PreviewState<Input>;
 
 export declare const useProvenance: (apiName: string, table: string, id: string, column?: string) => ProvenanceState;