dynamodb-reactive 0.1.22 → 0.2.1

package/dist/server.d.ts

@@ -1,35 +1,22 @@
 import { z } from 'zod';
-import { D as DynamoTable } from './table-tN3D4Tm-.js';
-import { A as AnyDynamoTable, F as FieldRef, a as FilterCondition, Q as QueryMetadata, J as JsonPatch } from './types-ISMJfyIv.js';
+import { A as AnyDynamoTable, a as FilterCondition } from './types-LMLk8JVC.js';
+import { FieldRef, QueryMetadata, ConnectionEntry } from './core.js';
+import { DynamoTable } from './core.js';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import { DynamoDBStreamEvent, APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import * as aws_lambda from 'aws-lambda';
+import { APIGatewayProxyEvent, APIGatewayProxyResult, DynamoDBStreamEvent } from 'aws-lambda';
+import { ApiGatewayManagementApiClient } from '@aws-sdk/client-apigatewaymanagementapi';
 
-/**
- * Context type for procedures
- */
-interface ProcedureContext<TContext = unknown> {
-    ctx: TContext & {
-        db: DatabaseContext;
-    };
-    input: unknown;
-}
 /**
  * Database context provided to procedures
  */
 interface DatabaseContext {
     query<TTable extends AnyDynamoTable>(table: TTable): QueryBuilder<TTable>;
-    /**
-     * 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>;
+    get<TTable extends AnyDynamoTable>(table: TTable, key: TableKeyInput<TTable>): Promise<TableItem<TTable> | null>;
     put<TTable extends AnyDynamoTable>(table: TTable, item: TableItem<TTable>): Promise<void>;
     delete<TTable extends AnyDynamoTable>(table: TTable, key: TableKeyInput<TTable>): Promise<void>;
-    /**
-     * 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>;
+    update<TTable extends AnyDynamoTable>(table: TTable, key: TableKeyInput<TTable>, updates: Partial<TableItem<TTable>>): Promise<TableItem<TTable>>;
 }
 /**
  * Extract the item type from a DynamoTable
@@ -52,9 +39,8 @@ type TableKeyInput<T extends AnyDynamoTable> = T extends DynamoTable<infer TSche
  */
 interface QueryBuilder<TTable extends AnyDynamoTable> {
     filter(fn: (q: FilterBuilder<TTable>) => FilterCondition): QueryBuilder<TTable>;
-    useIndex(indexName: keyof TableIndexes<TTable>): QueryBuilder<TTable>;
+    useIndex(indexName: keyof TTable['indexes'] & string): QueryBuilder<TTable>;
     take(limit: number): QueryBuilder<TTable>;
-    startFrom(key: TableKeyInput<TTable>): QueryBuilder<TTable>;
     sortAscending(): QueryBuilder<TTable>;
     sortDescending(): QueryBuilder<TTable>;
     execute(): Promise<TableItem<TTable>[]>;
@@ -76,12 +62,6 @@ interface FilterBuilder<TTable extends AnyDynamoTable> {
     or(...conditions: FilterCondition[]): FilterCondition;
     not(condition: FilterCondition): FilterCondition;
 }
-/**
- * Extract indexes from a DynamoTable
- */
-type TableIndexes<T extends AnyDynamoTable> = T extends DynamoTable<any, any, any, infer TIndexes> ? TIndexes : T extends {
-    indexes: infer TIndexes;
-} ? TIndexes : never;
 /**
  * Procedure types
  */
@@ -89,8 +69,8 @@ type ProcedureType = 'query' | 'mutation';
 /**
  * Procedure definition
  */
-interface ProcedureDefinition<TContext, TInput extends z.ZodTypeAny = z.ZodUndefined, TOutput = unknown> {
-    type: ProcedureType;
+interface ProcedureDefinition<TContext, TInput extends z.ZodTypeAny = z.ZodUndefined, TOutput = unknown, TType extends ProcedureType = ProcedureType> {
+    type: TType;
     inputSchema?: TInput;
     resolver: (opts: {
         ctx: TContext & {
@@ -103,7 +83,7 @@ interface ProcedureDefinition<TContext, TInput extends z.ZodTypeAny = z.ZodUndef
  * Any procedure definition - used for generic constraints
  * Uses 'any' for input/output to allow covariant assignment
  */
-type AnyProcedureDefinition<TContext> = ProcedureDefinition<TContext, any, any>;
+type AnyProcedureDefinition<TContext> = ProcedureDefinition<TContext, any, any, ProcedureType>;
 /**
  * Router definition
  */
@@ -117,14 +97,13 @@ interface QueryDependency {
     tableName: string;
     fieldName: string;
     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, // eslint-disable-line @typescript-eslint/no-explicit-any -- conditional type inference requires `any` for contravariant TContext
-    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;
+    infer TInput, infer TOutput, infer TType> ? TType extends 'query' ? TInput extends z.ZodTypeAny ? (input: z.infer<TInput>) => Promise<TOutput> : () => Promise<TOutput> : never : TRouter[K] extends Record<string, unknown> ? RouterCaller<TRouter[K]> : never;
 };
 /**
  * Tracked query operation (for dependency extraction and stream processing)
@@ -133,10 +112,9 @@ interface TrackedQueryOperation {
     tableName: string;
     filters: FilterCondition[];
     indexName?: string;
-    /** Primary key field name for the table */
-    pkField: string;
-    /** Sort key field name for the table (if any) */
-    skField?: string;
+    /** Field names selected by useIndex, used to preserve sparse membership. */
+    indexPkField?: string;
+    indexSkField?: string;
     /** Sort field for ordering results */
     sortField?: string;
     /** Sort direction */
@@ -163,7 +141,7 @@ declare class ProcedureBuilder<TContext, TInput extends z.ZodType = z.ZodUndefin
             db: DatabaseContext;
         };
         input: z.infer<TInput>;
-    }) => Promise<TOutput> | TOutput): ProcedureDefinition<TContext, TInput, TOutput>;
+    }) => Promise<TOutput> | TOutput): ProcedureDefinition<TContext, TInput, TOutput, 'query'>;
     /**
      * Define a mutation procedure (write operation)
      */
@@ -172,18 +150,8 @@ declare class ProcedureBuilder<TContext, TInput extends z.ZodType = z.ZodUndefin
             db: DatabaseContext;
         };
         input: z.infer<TInput>;
-    }) => Promise<TOutput> | TOutput): ProcedureDefinition<TContext, TInput, TOutput>;
+    }) => Promise<TOutput> | TOutput): ProcedureDefinition<TContext, TInput, TOutput, 'mutation'>;
 }
-/**
- * Check if a value is a procedure definition
- */
-declare function isProcedure(value: unknown): value is ProcedureDefinition<any, any, any>;
-/**
- * Execute a procedure with the given context and input
- */
-declare function executeProcedure<TContext, TInput extends z.ZodType, TOutput>(procedure: ProcedureDefinition<TContext, TInput, TOutput>, ctx: TContext & {
-    db: DatabaseContext;
-}, rawInput: unknown): Promise<TOutput>;
 
 /**
  * Router class for organizing procedures
@@ -201,27 +169,7 @@ declare class Router<TContext, TRouter extends RouterDefinition<TContext>> {
     execute(path: string, ctx: TContext & {
         db: DatabaseContext;
     }, input: unknown): Promise<unknown>;
-    /**
-     * Get all procedure paths in the router
-     */
-    getProcedurePaths(): string[];
-    /**
-     * Check if a path is a query procedure
-     */
-    isQuery(path: string): boolean;
-    /**
-     * Check if a path is a mutation procedure
-     */
-    isMutation(path: string): boolean;
 }
-/**
- * Create a router from a definition
- */
-declare function createRouter<TContext, TRouter extends RouterDefinition<TContext>>(definition: TRouter): Router<TContext, TRouter>;
-/**
- * Merge multiple routers into one
- */
-declare function mergeRouters<TContext>(...routers: Router<TContext, RouterDefinition<TContext>>[]): Router<TContext, RouterDefinition<TContext>>;
 
 /**
  * ReactiveBuilder - The main builder returned by initReactive
@@ -278,29 +226,17 @@ type InferProcedureOutput<T> = T extends {
     resolver: (...args: any[]) => infer TOutput;
 } ? Awaited<TOutput> : unknown;
 
-/**
- * Extract dependencies from a tracked query operation
- */
-declare function extractDependencies(operation: TrackedQueryOperation): QueryDependency[];
-/**
- * Create a dependency key for the inverted index
- * Format: "TableName#FieldName#FieldValue"
- */
-declare function createDependencyKey(dependency: QueryDependency): string;
-/**
- * Parse a dependency key back into its components
- */
-declare function parseDependencyKey(key: string): QueryDependency | null;
-/**
- * Extract affected dependency keys from a DynamoDB stream record
- * This finds all keys that might be affected by a change
- */
-declare function extractAffectedKeys(tableName: string, item: Record<string, unknown>): string[];
-/**
- * Convert a TrackedQueryOperation to QueryMetadata for storage.
- * Normalizes filter operators for evaluation.
- */
-declare function operationToQueryMetadata(operation: TrackedQueryOperation): QueryMetadata;
+/** An error whose status and message are safe to return to an API caller. */
+declare class SafeRequestError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+/** Generic public error for malformed procedure input; Zod details stay private. */
+declare class InvalidInputError extends SafeRequestError {
+    constructor();
+}
+declare function isSafeRequestError(error: unknown): error is SafeRequestError;
+
 /**
  * DependencyTracker - Tracks query operations during procedure execution
  */
@@ -309,7 +245,7 @@ declare class DependencyTracker {
     /**
      * Track a query operation
      */
-    track(operation: TrackedQueryOperation): void;
+    track(operation: TrackedQueryOperation, result: unknown[]): void;
     /**
      * Get all tracked operations
      */
@@ -318,27 +254,15 @@ declare class DependencyTracker {
      * Extract all dependencies from tracked operations
      */
     extractAll(): QueryDependency[];
-    /**
-     * Get all dependency keys for the inverted index
-     */
-    getDependencyKeys(): string[];
     /**
      * Get query metadata for the first tracked operation.
      * Used for storing subscription state.
      */
     getQueryMetadata(): QueryMetadata | null;
-    /**
-     * Get the primary key field from the first operation
-     */
-    getPkField(): string | null;
-    /**
-     * Get the sort key field from the first operation
-     */
-    getSkField(): string | undefined;
-    /**
-     * Clear tracked operations
-     */
-    clear(): void;
+    getCapturedResult(): {
+        reference: unknown[];
+        snapshot: unknown[];
+    } | null;
 }
 
 /**
@@ -346,6 +270,7 @@ declare class DependencyTracker {
  */
 interface DbContextConfig {
     client?: DynamoDBClient;
+    docClient?: DynamoDBDocumentClient;
     region?: string;
     endpoint?: string;
 }
@@ -354,109 +279,12 @@ interface DbContextConfig {
  */
 declare function createDbContext(config: DbContextConfig, dependencyTracker?: DependencyTracker): DatabaseContext;
 
-/**
- * Query execution function type
- */
-type QueryExecutor<TTable extends AnyDynamoTable> = (operation: TrackedQueryOperation, options: QueryOptions) => Promise<TableItem<TTable>[]>;
-/**
- * Query options
- */
-interface QueryOptions {
-    limit?: number;
-    startKey?: Record<string, unknown>;
-    ascending: boolean;
-}
-/**
- * Implementation of QueryBuilder
- */
-declare class QueryBuilderImpl<TTable extends AnyDynamoTable> implements QueryBuilder<TTable> {
-    private table;
-    private filters;
-    private indexName?;
-    private limit?;
-    private startKey?;
-    private ascending;
-    private executor;
-    private operationTracker?;
-    constructor(table: TTable, executor: QueryExecutor<TTable>, operationTracker?: (op: TrackedQueryOperation) => void);
-    filter(fn: (q: FilterBuilder<TTable>) => FilterCondition): QueryBuilder<TTable>;
-    useIndex(indexName: string): QueryBuilder<TTable>;
-    take(limit: number): QueryBuilder<TTable>;
-    startFrom(key: TableKeyInput<TTable>): QueryBuilder<TTable>;
-    sortAscending(): QueryBuilder<TTable>;
-    sortDescending(): QueryBuilder<TTable>;
-    execute(): Promise<TableItem<TTable>[]>;
-    /**
-     * Get the current operation without executing
-     * Used for dependency extraction
-     */
-    getOperation(): TrackedQueryOperation;
-}
-/**
- * Create a filter builder instance
- */
-declare function createFilterBuilder<TTable extends AnyDynamoTable>(): FilterBuilder<TTable>;
-
-/**
- * PartiQL statement with parameters
- */
-interface PartiQLStatement {
-    statement: string;
-    parameters: unknown[];
-}
-/**
- * Build a PartiQL SELECT statement from a query operation
- */
-declare function buildSelectStatement(operation: TrackedQueryOperation): PartiQLStatement;
-/**
- * Build a PartiQL INSERT statement
- */
-declare function buildInsertStatement(tableName: string, item: Record<string, unknown>): PartiQLStatement;
-/**
- * Build a PartiQL UPDATE statement
- */
-declare function buildUpdateStatement(tableName: string, key: Record<string, unknown>, updates: Record<string, unknown>): PartiQLStatement;
-/**
- * Build a PartiQL DELETE statement
- */
-declare function buildDeleteStatement(tableName: string, key: Record<string, unknown>): PartiQLStatement;
-/**
- * Build a PartiQL GET statement (for single item by key)
- */
-declare function buildGetStatement(tableName: string, key: Record<string, unknown>): PartiQLStatement;
-
-/**
- * Generate JSON patches between two objects
- * Uses RFC 6902 JSON Patch format
- */
-declare function generatePatches(oldValue: unknown, newValue: unknown): JsonPatch[];
-/**
- * Apply JSON patches to an object
- * Returns the patched result
- */
-declare function applyPatches<T>(document: T, patches: JsonPatch[]): T;
-/**
- * Check if there are any changes between two values
- */
-declare function hasChanges(oldValue: unknown, newValue: unknown): boolean;
-/**
- * Create a minimal patch that only includes necessary operations
- * Optimizes the patch by removing redundant operations
- */
-declare function optimizePatches(patches: JsonPatch[]): JsonPatch[];
-/**
- * Batch multiple patch sets into a single set
- */
-declare function batchPatches(patchSets: JsonPatch[][]): JsonPatch[];
-
-/**
- * Request types for the reactive handler.
- * All requests include connectionId from the WebSocket connection.
- */
 interface SubscribeRequest {
     type: 'subscribe';
     connectionId: string;
     subscriptionId: string;
+    generation: number;
+    registrationId: string;
     path: string;
     input: unknown;
 }
@@ -464,6 +292,8 @@ interface UnsubscribeRequest {
     type: 'unsubscribe';
     connectionId: string;
     subscriptionId: string;
+    generation: number;
+    registrationId: string;
 }
 interface CallRequest {
     type: 'call';
@@ -472,18 +302,12 @@ interface CallRequest {
     input: unknown;
 }
 type ReactiveRequest = SubscribeRequest | UnsubscribeRequest | CallRequest;
-/**
- * Response types for the reactive handler
- */
 interface SnapshotResponse {
     type: 'snapshot';
     subscriptionId: string;
-    data: unknown;
-}
-interface PatchResponse {
-    type: 'patch';
-    subscriptionId: string;
-    patches: unknown[];
+    generation: number;
+    version: number;
+    data: unknown[];
 }
 interface ResultResponse {
     type: 'result';
@@ -492,35 +316,27 @@ 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
- */
+type ReactiveResponse = SnapshotResponse | ResultResponse | ErrorResponse;
 interface RequestInfo {
     connectionId: string;
-    /** Headers from the HTTP request (for auth, user info, etc.) */
     headers?: Record<string, string>;
 }
-/**
- * Configuration for the reactive handler
- */
+interface ConnectionAuthorization<TContext> {
+    context: TContext;
+    connection: ConnectionEntry;
+    requestInfo: RequestInfo;
+}
 interface ReactiveHandlerConfig<TContext, TRouter extends RouterDefinition<TContext> = RouterDefinition<TContext>> {
     router: Router<TContext, TRouter>;
     dbConfig?: DbContextConfig;
     getContext: (requestInfo: RequestInfo) => Promise<TContext>;
+    authorizeConnection: (authorization: ConnectionAuthorization<TContext>) => boolean | Promise<boolean>;
     ttlSeconds?: number;
-    /** Prefix for system table names (e.g., 'TodoApp' creates 'TodoApp-ReactiveConnections') */
-    tablePrefix?: string;
+    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, 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>;
@@ -529,91 +345,20 @@ declare function createReactiveHandler<TContext, TRouter extends RouterDefinitio
     createCaller: () => RouterCaller<TRouter>;
 };
 
-/**
- * Configuration for the stream handler.
- * NOTE: Router is no longer required - stream processing uses stored query metadata.
- */
-interface StreamHandlerConfig {
+interface LambdaHandlersConfig {
     dbConfig?: DbContextConfig;
-    apiGatewayEndpoint: string;
+    apiClient?: ApiGatewayManagementApiClient;
     connectionsTableName?: string;
     dependenciesTableName?: string;
     queriesTableName?: string;
+    apiGatewayEndpoint?: string;
 }
-/**
- * Create a DynamoDB stream handler for AWS Lambda.
- * Uses stored query metadata to re-execute queries WITHOUT router code.
- */
-declare function createStreamHandler(config: StreamHandlerConfig): {
-    handler: (event: DynamoDBStreamEvent) => Promise<void>;
-};
-/**
- * WebSocket connection handler for $connect
- */
-declare function createConnectHandler(config: Pick<StreamHandlerConfig, 'dbConfig' | 'connectionsTableName'>): (event: {
-    requestContext: {
-        connectionId: string;
-        authorizer?: Record<string, unknown>;
-    };
-}) => Promise<{
-    statusCode: number;
-}>;
-/**
- * WebSocket disconnection handler for $disconnect.
- * Fully cleans up connection entry, subscriptions, and dependencies.
- */
-declare function createDisconnectHandler(config: Pick<StreamHandlerConfig, 'dbConfig' | 'connectionsTableName' | 'queriesTableName' | 'dependenciesTableName' | 'apiGatewayEndpoint'>): (event: {
-    requestContext: {
-        connectionId: string;
-    };
-}) => Promise<{
-    statusCode: number;
-}>;
-
-/**
- * Lambda handler implementations for the reactive WebSocket system.
- *
- * These handlers process WebSocket events and DynamoDB stream events
- * WITHOUT requiring user router code at runtime.
- *
- * Stream processing uses stored query metadata to evaluate changes
- * directly, rather than re-executing queries through a router.
- */
-
-/**
- * Create all Lambda handlers.
- * No user code required - all configuration comes from environment variables.
- * The stream handler uses stored query metadata (PartiQL), not router code.
- */
-declare function createLambdaHandlers(): {
+declare function createLambdaHandlers(config?: LambdaHandlersConfig): {
     connectHandler: (event: APIGatewayProxyEvent) => Promise<APIGatewayProxyResult>;
     disconnectHandler: (event: APIGatewayProxyEvent) => Promise<APIGatewayProxyResult>;
     messageHandler: (event: APIGatewayProxyEvent) => Promise<APIGatewayProxyResult>;
-    streamHandler: (event: DynamoDBStreamEvent) => Promise<void>;
+    streamHandler: (event: DynamoDBStreamEvent) => Promise<aws_lambda.DynamoDBBatchResponse>;
 };
 
-/**
- * Filter evaluator for evaluating FilterCondition against DynamoDB records.
- * Used by the stream handler to determine if a record matches a subscription's query.
- */
-
-/**
- * Evaluate a filter condition against a record.
- * Returns true if the record matches the filter.
- */
-declare function evaluateFilter(filter: FilterCondition, record: Record<string, unknown>): boolean;
-/**
- * Evaluate multiple filter conditions (all must match - AND logic).
- */
-declare function evaluateFilters(filters: FilterCondition[], record: Record<string, unknown>): boolean;
-/**
- * Sort records by a field.
- */
-declare function sortRecords(records: Record<string, unknown>[], sortField?: string, sortOrder?: 'asc' | 'desc'): Record<string, unknown>[];
-/**
- * Find the primary key value(s) from a record.
- * Used to identify records for update/removal.
- */
-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 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, createRouter, createStreamHandler, evaluateFilter, evaluateFilters, executeProcedure, extractAffectedKeys, extractDependencies, generatePatches, getRecordKey, hasChanges, initReactive, isProcedure, mergeRouters, operationToQueryMetadata, optimizePatches, parseDependencyKey, sortRecords };
+export { AnyDynamoTable, FilterCondition, InvalidInputError, SafeRequestError, createDbContext, createLambdaHandlers, createReactiveHandler, initReactive, isSafeRequestError };
+export type { AnyProcedureDefinition, CallRequest, DatabaseContext, DbContextConfig, ErrorResponse, FilterBuilder, InferProcedureInput, InferProcedureOutput, InferRouterType, LambdaHandlersConfig, ProcedureDefinition, ProcedureType, QueryBuilder, ReactiveBuilder, ReactiveHandlerConfig, ReactiveRequest, ReactiveResponse, RequestInfo, ResultResponse, RouterDefinition, SnapshotResponse, SubscribeRequest, TableItem, TableKeyInput, UnsubscribeRequest };