dynamodb-reactive 0.1.1 → 0.1.4

package/dist/{react-BMZQ8Mth.d.ts → react-B8Q_XoCk.d.ts}

@@ -29,10 +29,17 @@ interface CallMessage {
     path: string;
     input: unknown;
 }
-type ClientMessage = SubscribeMessage | UnsubscribeMessage | CallMessage;
+interface InitMessage {
+    type: 'init';
+}
+type ClientMessage = InitMessage | SubscribeMessage | UnsubscribeMessage | CallMessage;
 /**
  * Messages sent from server to client
  */
+interface ConnectedMessage {
+    type: 'connected';
+    connectionId: string;
+}
 interface SnapshotMessage {
     type: 'snapshot';
     subscriptionId: string;
@@ -54,7 +61,7 @@ interface ErrorMessage {
     subscriptionId?: string;
     callId?: string;
 }
-type ServerMessage = SnapshotMessage | PatchMessage | ResultMessage | ErrorMessage;
+type ServerMessage = ConnectedMessage | SnapshotMessage | PatchMessage | ResultMessage | ErrorMessage;
 /**
  * Client configuration
  */
@@ -63,10 +70,21 @@ interface ReactiveClientConfig {
      * WebSocket URL to connect to
      */
     url: string;
+    /**
+     * HTTP URL for subscribe/call requests.
+     * Defaults to '/api/reactive' for Next.js apps.
+     */
+    httpUrl?: string;
     /**
      * Authentication token or getter function
      */
     auth?: string | (() => string | Promise<string>);
+    /**
+     * Custom headers to send with HTTP requests.
+     * Can be a static object or a getter function for dynamic headers.
+     * Useful for passing auth tokens or user context to the server.
+     */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
     /**
      * Enable automatic reconnection
      * @default true
@@ -121,6 +139,10 @@ interface SubscriptionOptions<TInput> {
  * Active subscription
  */
 interface Subscription<TData> {
+    /**
+     * Subscription ID (used for registering listeners)
+     */
+    id: string;
     /**
      * Current data
      */
@@ -155,6 +177,28 @@ type InferInput<T> = T extends {
 type InferOutput<T> = T extends {
     output: infer TOutput;
 } ? TOutput : unknown;
+/**
+ * Mutation options for optimistic updates
+ */
+interface MutationOptions<TInput = unknown, TOutput = unknown> {
+    /**
+     * Subscription path to optimistically update (e.g., 'todos.list')
+     * If not provided, auto-detected from mutation path (e.g., 'todos.toggle' -> 'todos.list')
+     */
+    invalidates?: string;
+    /**
+     * How to apply the mutation result to subscription data (applied INSTANTLY before HTTP)
+     * - 'merge': Find item by input.id and merge input fields into it
+     * - 'remove': Remove item by input.id
+     * - Custom function for complex cases
+     */
+    optimisticUpdate?: 'merge' | 'remove' | ((currentData: unknown[], input: TInput, result?: TOutput) => unknown[]);
+    /**
+     * For create operations (no input.id), provide the optimistic item to add.
+     * Can be the item object or a function that receives input and current data.
+     */
+    optimisticData?: TOutput | ((input: TInput, currentData: unknown[]) => TOutput | undefined);
+}
 
 /**
  * Internal subscription state
@@ -174,10 +218,14 @@ interface SubscriptionState<TData> {
  */
 declare class ReactiveClient {
     private wsManager;
+    private httpUrl;
+    private authGetter?;
+    private headersGetter?;
     private subscriptions;
     private pendingCalls;
     private connectionState;
     private stateListeners;
+    private optimisticUpdates;
     constructor(config: ReactiveClientConfig);
     /**
      * Connect to the server
@@ -187,6 +235,11 @@ declare class ReactiveClient {
      * Disconnect from the server
      */
     disconnect(): void;
+    /**
+     * Update the headers getter for HTTP requests.
+     * Useful for dynamically setting auth or user context headers.
+     */
+    setHeaders(headers: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>)): void;
     /**
      * Get current connection state
      */
@@ -196,23 +249,30 @@ declare class ReactiveClient {
      */
     onConnectionStateChange(listener: (state: ConnectionState) => void): () => void;
     /**
-     * Subscribe to a procedure
+     * Subscribe to a procedure via HTTP.
+     * Snapshot is returned via HTTP, patches come via WebSocket.
      */
     subscribe<TData>(path: string, options?: SubscriptionOptions<unknown>): Subscription<TData>;
     /**
-     * Call a mutation procedure
+     * Send subscribe request via HTTP
      */
-    call<TInput, TOutput>(path: string, input: TInput): Promise<TOutput>;
+    private sendSubscribeRequest;
+    /**
+     * Call a mutation procedure via HTTP with optimistic update support.
+     * All optimistic updates are applied INSTANTLY (before HTTP request).
+     */
+    call<TInput, TOutput>(path: string, input: TInput, options?: MutationOptions<TInput, TOutput>): Promise<TOutput>;
     /**
      * Unsubscribe from a subscription
      */
     private unsubscribe;
     /**
-     * Refetch a subscription
+     * Refetch a subscription via HTTP
      */
     private refetch;
     /**
-     * Handle incoming server messages
+     * Handle incoming server messages.
+     * Note: 'connected' messages are handled by WebSocketManager before reaching here.
      */
     private handleMessage;
     /**
@@ -232,7 +292,7 @@ declare class ReactiveClient {
      */
     private handleError;
     /**
-     * Resubscribe to all subscriptions after reconnect
+     * Resubscribe to all subscriptions after reconnect via HTTP
      */
     private resubscribeAll;
     /**
@@ -253,6 +313,22 @@ declare class ReactiveClient {
      * Used internally by React hooks
      */
     getSubscriptionState<TData>(id: string): SubscriptionState<TData> | undefined;
+    /**
+     * Find subscription by path
+     */
+    private findSubscriptionByPath;
+    /**
+     * Apply an optimistic update to a subscription's data
+     */
+    private applyOptimisticUpdate;
+    /**
+     * Rollback an optimistic update
+     */
+    private rollbackOptimisticUpdate;
+    /**
+     * Clear optimistic state (called when real data arrives)
+     */
+    private clearOptimisticUpdate;
 }
 /**
  * Create a type-safe reactive client
@@ -314,10 +390,15 @@ declare function useSubscription<TData>(path: string, options?: SubscriptionOpti
     refetch: () => Promise<void>;
 };
 /**
- * Hook for mutations
- * Throws if called when WebSocket is not configured
+ * Hook for mutations with automatic optimistic updates
+ *
+ * Auto-detection:
+ * - `invalidates`: Auto-detected from path (e.g., 'todos.toggle' -> 'todos.list')
+ * - `optimisticUpdate`: Auto-detected from path ('*.delete' -> 'remove', others -> 'merge')
+ *
+ * You can override these with explicit options.
  */
-declare function useMutation<TInput, TOutput>(path: string): {
+declare function useMutation<TInput, TOutput>(path: string, options?: MutationOptions<TInput, TOutput>): {
     mutate: (input: TInput) => Promise<TOutput>;
     data: TOutput | undefined;
     loading: boolean;
@@ -326,7 +407,93 @@ declare function useMutation<TInput, TOutput>(path: string): {
     reset: () => void;
 };
 /**
- * Create typed React hooks from a router type
+ * Type helper for extracting procedure input type from ProcedureDefinition
+ * Uses Zod's internal _output property to extract the parsed type
+ * (Zod schemas have _input/_output as actual properties for type inference)
+ */
+type ProcedureInput<T> = T extends {
+    inputSchema?: {
+        _output: infer I;
+    };
+} ? I : undefined;
+/**
+ * Type helper for extracting procedure output type from ProcedureDefinition
+ * Extracts from resolver return type using any[] for flexible argument matching
+ */
+type ProcedureOutput<T> = T extends {
+    resolver: (...args: any[]) => infer TReturn;
+} ? Awaited<TReturn> : unknown;
+/**
+ * Typed client hooks for a router procedure
+ * Provides both useQuery and useMutation - use whichever matches your procedure type
+ */
+type TypedProcedureHooks<TInput, TOutput> = {
+    useQuery: (input: TInput, options?: Omit<SubscriptionOptions<TInput>, 'input'>) => {
+        data: TOutput | undefined;
+        loading: boolean;
+        error: Error | undefined;
+        disabled: boolean;
+        refetch: () => Promise<void>;
+    };
+    useMutation: (options?: MutationOptions<TInput, TOutput>) => {
+        mutate: (input: TInput) => Promise<TOutput>;
+        data: TOutput | undefined;
+        loading: boolean;
+        error: Error | undefined;
+        disabled: boolean;
+        reset: () => void;
+    };
+};
+/**
+ * Extract router definition from Router class or use T directly
+ */
+type ExtractRouterDefinition<T> = T extends {
+    definition: infer TDef;
+} ? TDef : T;
+/**
+ * Recursive type for typed client proxy
+ * Checks for 'resolver' property to identify procedures (all procedures have it)
+ */
+type TypedClientProxyRecursive<T> = T extends {
+    resolver: unknown;
+} ? TypedProcedureHooks<ProcedureInput<T>, ProcedureOutput<T>> : {
+    [K in keyof T]: TypedClientProxyRecursive<T[K]>;
+};
+/**
+ * Client utilities available at the root level
+ */
+interface ClientUtilities {
+    /**
+     * Set custom headers to be sent with HTTP requests.
+     * Useful for auth context (e.g., user tokens, session info).
+     */
+    setHeaders: (headers: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>)) => void;
+}
+/**
+ * Typed client proxy combining router procedures and client utilities
+ */
+type TypedClientProxy<T> = TypedClientProxyRecursive<ExtractRouterDefinition<T>> & ClientUtilities;
+/**
+ * Create a typed client proxy for use in React components.
+ *
+ * @example
+ * ```tsx
+ * const client = useClient<AppRouter>();
+ *
+ * // Queries (subscriptions)
+ * const { data, loading } = client.todos.list.useQuery({});
+ *
+ * // Mutations
+ * const { mutate, loading } = client.todos.toggle.useMutation();
+ * await mutate({ id: '123' });
+ *
+ * // Set custom headers for HTTP requests (e.g., for auth context)
+ * client.setHeaders({ 'Authorization': 'Bearer token' });
+ * ```
+ */
+declare function useClient<TRouter>(): TypedClientProxy<TRouter>;
+/**
+ * @deprecated Use useClient<TRouter>() instead for typed proxy access
  */
 declare function createReactiveHooks(): {
     useSubscription: <TPath extends string, TData = unknown>(path: TPath, options?: SubscriptionOptions<unknown>) => {
@@ -336,7 +503,7 @@ declare function createReactiveHooks(): {
         disabled: boolean;
         refetch: () => Promise<void>;
     };
-    useMutation: <TPath extends string, TInput = unknown, TOutput = unknown>(path: TPath) => {
+    useMutation: <TPath extends string, TInput = unknown, TOutput = unknown>(path: TPath, options?: MutationOptions<TInput, TOutput>) => {
         mutate: (input: TInput) => Promise<TOutput>;
         data: TOutput | undefined;
         loading: boolean;
@@ -348,7 +515,7 @@ declare function createReactiveHooks(): {
     useReactiveClient: typeof useReactiveClient;
 };
 /**
- * Type-safe hook creator for a specific procedure path
+ * @deprecated Use useClient<TRouter>() instead for typed proxy access
  */
 declare function createProcedureHooks<TInput, TOutput>(path: string): {
     useSubscription: (input?: TInput, options?: Omit<SubscriptionOptions<TInput>, "input">) => {
@@ -358,7 +525,7 @@ declare function createProcedureHooks<TInput, TOutput>(path: string): {
         disabled: boolean;
         refetch: () => Promise<void>;
     };
-    useMutation: () => {
+    useMutation: (options?: MutationOptions<TInput, TOutput>) => {
         mutate: (input: TInput) => Promise<TOutput>;
         data: TOutput | undefined;
         loading: boolean;
@@ -368,4 +535,4 @@ declare function createProcedureHooks<TInput, TOutput>(path: string): {
     };
 };
 
-export { type ConnectionState as C, type ErrorMessage as E, type InferInput as I, type JsonPatch as J, type PatchMessage as P, type ReactiveClientConfig as R, type ServerMessage as S, type TypedReactiveClient as T, type UnsubscribeMessage as U, type ClientMessage as a, ReactiveClient as b, createReactiveClient as c, type CallMessage as d, type InferOutput as e, type ResultMessage as f, type SnapshotMessage as g, type SubscribeMessage as h, type Subscription as i, type SubscriptionOptions as j, createProcedureHooks as k, createReactiveHooks as l, ReactiveClientProvider as m, useMutation as n, useReactiveClient as o, useReactiveClientOrThrow as p, useSubscription as q, useConnectionState as u };
+export { type ConnectionState as C, type ErrorMessage as E, type InferInput as I, type JsonPatch as J, type MutationOptions as M, type PatchMessage as P, type ReactiveClientConfig as R, type ServerMessage as S, type TypedReactiveClient as T, type UnsubscribeMessage as U, type ClientMessage as a, ReactiveClient as b, createReactiveClient as c, type CallMessage as d, type InferOutput as e, type ResultMessage as f, type SnapshotMessage as g, type SubscribeMessage as h, type Subscription as i, type SubscriptionOptions as j, createProcedureHooks as k, createReactiveHooks as l, ReactiveClientProvider as m, useConnectionState as n, useMutation as o, useReactiveClient as p, useReactiveClientOrThrow as q, useSubscription as r, useClient as u };

package/dist/react.d.ts

@@ -1,3 +1,3 @@
-export { m as ReactiveClientProvider, k as createProcedureHooks, l as createReactiveHooks, u as useConnectionState, n as useMutation, o as useReactiveClient, p as useReactiveClientOrThrow, q as useSubscription } from './react-BMZQ8Mth.js';
+export { m as ReactiveClientProvider, k as createProcedureHooks, l as createReactiveHooks, u as useClient, n as useConnectionState, o as useMutation, p as useReactiveClient, q as useReactiveClientOrThrow, r as useSubscription } from './react-B8Q_XoCk.js';
 import 'react/jsx-runtime';
 import 'react';

package/dist/react.js

@@ -1,3 +1,3 @@
-export { ReactiveClientProvider, createProcedureHooks, createReactiveHooks, useConnectionState, useMutation, useReactiveClient, useReactiveClientOrThrow, useSubscription } from './chunk-KRZQWA2W.js';
+export { ReactiveClientProvider, createProcedureHooks, createReactiveHooks, useClient, useConnectionState, useMutation, useReactiveClient, useReactiveClientOrThrow, useSubscription } from './chunk-MI2ZLLB2.js';
 //# sourceMappingURL=react.js.map
 //# sourceMappingURL=react.js.map

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { D as DynamoTable } from './table-CSJysZPQ.js';
-import { A as AnyDynamoTable, F as FieldRef, a as FilterCondition, Q as QueryMetadata, J as JsonPatch } from './types-Ci7IieDA.js';
+import { D as DynamoTable } from './table-CfIWxbuJ.js';
+import { A as AnyDynamoTable, F as FieldRef, a as FilterCondition, Q as QueryMetadata, J as JsonPatch } from './types-DeshTSf5.js';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBStreamEvent, APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
 
@@ -18,10 +18,18 @@ interface ProcedureContext<TContext = unknown> {
  */
 interface DatabaseContext {
     query<TTable extends AnyDynamoTable>(table: TTable): QueryBuilder<TTable>;
-    get<TTable extends AnyDynamoTable>(table: TTable, key: TableKeyInput<TTable>): Promise<TableItem<TTable> | null>;
+    /**
+     * Get a single item by key
+     * @template TItem - Optional explicit item type (defaults to TableItem<TTable>)
+     */
+    get<TItem = never, TTable extends AnyDynamoTable = AnyDynamoTable>(table: TTable, key: TableKeyInput<TTable>): Promise<([TItem] extends [never] ? TableItem<TTable> : TItem) | null>;
     put<TTable extends AnyDynamoTable>(table: TTable, item: TableItem<TTable>): Promise<void>;
     delete<TTable extends AnyDynamoTable>(table: TTable, key: TableKeyInput<TTable>): Promise<void>;
-    update<TTable extends AnyDynamoTable>(table: TTable, key: TableKeyInput<TTable>, updates: Partial<TableItem<TTable>>): Promise<TableItem<TTable>>;
+    /**
+     * Update an item and return the updated item
+     * @template TItem - Optional explicit item type (defaults to TableItem<TTable>)
+     */
+    update<TItem = never, TTable extends AnyDynamoTable = AnyDynamoTable>(table: TTable, key: TableKeyInput<TTable>, updates: Partial<[TItem] extends [never] ? TableItem<TTable> : TItem>): Promise<[TItem] extends [never] ? TableItem<TTable> : TItem>;
 }
 /**
  * Extract the item type from a DynamoTable
@@ -111,6 +119,12 @@ interface QueryDependency {
     fieldValue: string;
     indexName?: string;
 }
+/**
+ * Transform a router definition into a callable structure (for queries only)
+ */
+type RouterCaller<TRouter> = {
+    [K in keyof TRouter]: TRouter[K] extends ProcedureDefinition<any, infer TInput, infer TOutput> ? TInput extends z.ZodTypeAny ? (input: z.infer<TInput>) => Promise<TOutput> : () => Promise<TOutput> : TRouter[K] extends Record<string, unknown> ? RouterCaller<TRouter[K]> : never;
+};
 /**
  * Tracked query operation (for dependency extraction and stream processing)
  */
@@ -435,20 +449,24 @@ declare function optimizePatches(patches: JsonPatch[]): JsonPatch[];
 declare function batchPatches(patchSets: JsonPatch[][]): JsonPatch[];
 
 /**
- * Request types for the reactive handler
+ * Request types for the reactive handler.
+ * All requests include connectionId from the WebSocket connection.
  */
 interface SubscribeRequest {
     type: 'subscribe';
+    connectionId: string;
     subscriptionId: string;
     path: string;
     input: unknown;
 }
 interface UnsubscribeRequest {
     type: 'unsubscribe';
+    connectionId: string;
     subscriptionId: string;
 }
 interface CallRequest {
     type: 'call';
+    connectionId: string;
     path: string;
     input: unknown;
 }
@@ -473,31 +491,41 @@ interface ResultResponse {
 interface ErrorResponse {
     type: 'error';
     message: string;
+    /** HTTP status code (e.g., 400, 403, 404, 500) */
+    code?: number;
     subscriptionId?: string;
 }
 type ReactiveResponse = SnapshotResponse | PatchResponse | ResultResponse | ErrorResponse;
+/**
+ * Request info passed to getContext for extracting user context
+ */
+interface RequestInfo {
+    connectionId: string;
+    /** Headers from the HTTP request (for auth, user info, etc.) */
+    headers?: Record<string, string>;
+}
 /**
  * Configuration for the reactive handler
  */
-interface ReactiveHandlerConfig<TContext> {
-    router: Router<TContext, any>;
+interface ReactiveHandlerConfig<TContext, TRouter extends RouterDefinition<TContext> = RouterDefinition<TContext>> {
+    router: Router<TContext, TRouter>;
     dbConfig?: DbContextConfig;
-    getContext: (connectionId: string) => Promise<TContext>;
+    getContext: (requestInfo: RequestInfo) => Promise<TContext>;
     ttlSeconds?: number;
-    /** Table names (uses defaults if not provided) */
-    connectionsTableName?: string;
-    dependenciesTableName?: string;
-    queriesTableName?: string;
+    /** Prefix for system table names (e.g., 'TodoApp' creates 'TodoApp-ReactiveConnections') */
+    tablePrefix?: string;
 }
 /**
  * Create a reactive handler for Next.js API routes or other HTTP servers.
  * This handler is used for subscribe/call requests and stores queryMetadata
  * for the stream handler to use later.
  */
-declare function createReactiveHandler<TContext>(config: ReactiveHandlerConfig<TContext>): {
-    handleRequest: (connectionId: string, request: ReactiveRequest) => Promise<ReactiveResponse>;
+declare function createReactiveHandler<TContext, TRouter extends RouterDefinition<TContext>>(config: ReactiveHandlerConfig<TContext, TRouter>): {
+    handleRequest: (request: ReactiveRequest, headers?: Record<string, string>) => Promise<ReactiveResponse>;
     registerConnection: (connectionId: string, context?: Record<string, unknown>) => Promise<void>;
     unregisterConnection: (connectionId: string) => Promise<void>;
+    query: <T = unknown>(path: string, input?: unknown, headers?: Record<string, string>) => Promise<T>;
+    createCaller: () => RouterCaller<TRouter>;
 };
 
 /**
@@ -628,4 +656,4 @@ declare function sortRecords(records: Record<string, unknown>[], sortField?: str
  */
 declare function getRecordKey(record: Record<string, unknown>, pkField: string, skField?: string): string;
 
-export { AnyDynamoTable, type AnyProcedureDefinition, type CallRequest, type DatabaseContext, type DbContextConfig, DependencyTracker, type ErrorResponse, type FilterBuilder, FilterCondition, type InferProcedureInput, type InferProcedureOutput, type InferRouterType, type PartiQLStatement, type PatchResponse, ProcedureBuilder, type ProcedureContext, type ProcedureDefinition, type ProcedureType, type QueryBuilder, QueryBuilderImpl, type QueryDependency, type ReactiveBuilder, type ReactiveHandlerConfig, type ReactiveHarness, type ReactiveHarnessConfig, type ReactiveRequest, type ReactiveResponse, type ResultResponse, Router, type RouterDefinition, type SnapshotResponse, type StreamHandlerConfig, type SubscribeRequest, type TableItem, type TableKeyInput, type TrackedQueryOperation, type UnsubscribeRequest, applyPatches, batchPatches, buildDeleteStatement, buildGetStatement, buildInsertStatement, buildSelectStatement, buildUpdateStatement, createConnectHandler, createDbContext, createDependencyKey, createDisconnectHandler, createFilterBuilder, createLambdaHandlers, createReactiveHandler, createReactiveHarness, createRouter, createStreamHandler, evaluateFilter, evaluateFilters, executeProcedure, extractAffectedKeys, extractDependencies, generatePatches, getRecordKey, hasChanges, initReactive, isProcedure, mergeRouters, operationToQueryMetadata, optimizePatches, parseDependencyKey, sortRecords };
+export { AnyDynamoTable, type AnyProcedureDefinition, type CallRequest, type DatabaseContext, type DbContextConfig, DependencyTracker, type ErrorResponse, type FilterBuilder, FilterCondition, type InferProcedureInput, type InferProcedureOutput, type InferRouterType, type PartiQLStatement, type PatchResponse, ProcedureBuilder, type ProcedureContext, type ProcedureDefinition, type ProcedureType, type QueryBuilder, QueryBuilderImpl, type QueryDependency, type ReactiveBuilder, type ReactiveHandlerConfig, type ReactiveHarness, type ReactiveHarnessConfig, type ReactiveRequest, type ReactiveResponse, type RequestInfo, type ResultResponse, Router, type RouterDefinition, type SnapshotResponse, type StreamHandlerConfig, type SubscribeRequest, type TableItem, type TableKeyInput, type TrackedQueryOperation, type UnsubscribeRequest, applyPatches, batchPatches, buildDeleteStatement, buildGetStatement, buildInsertStatement, buildSelectStatement, buildUpdateStatement, createConnectHandler, createDbContext, createDependencyKey, createDisconnectHandler, createFilterBuilder, createLambdaHandlers, createReactiveHandler, createReactiveHarness, createRouter, createStreamHandler, evaluateFilter, evaluateFilters, executeProcedure, extractAffectedKeys, extractDependencies, generatePatches, getRecordKey, hasChanges, initReactive, isProcedure, mergeRouters, operationToQueryMetadata, optimizePatches, parseDependencyKey, sortRecords };