dynamodb-reactive 0.1.21 → 0.2.1

package/dist/server.d.cts

@@ -0,0 +1,364 @@
+import { z } from 'zod';
+import { A as AnyDynamoTable, a as FilterCondition } from './types-LMLk8JVC.js';
+import { FieldRef, QueryMetadata, ConnectionEntry } from './core.cjs';
+import { DynamoTable } from './core.cjs';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+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';
+
+/**
+ * Database context provided to procedures
+ */
+interface DatabaseContext {
+    query<TTable extends AnyDynamoTable>(table: TTable): QueryBuilder<TTable>;
+    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<TTable extends AnyDynamoTable>(table: TTable, key: TableKeyInput<TTable>, updates: Partial<TableItem<TTable>>): Promise<TableItem<TTable>>;
+}
+/**
+ * Extract the item type from a DynamoTable
+ * Works with both the DynamoTable class and AnyDynamoTable interface
+ */
+type TableItem<T extends AnyDynamoTable> = T extends DynamoTable<infer TSchema, any, any, any> ? z.infer<TSchema> : T extends {
+    schema: infer TSchema extends z.ZodTypeAny;
+} ? z.infer<TSchema> : never;
+/**
+ * Extract key input type from a DynamoTable
+ * Works with both the DynamoTable class and AnyDynamoTable interface
+ */
+type TableKeyInput<T extends AnyDynamoTable> = T extends DynamoTable<infer TSchema, infer TPk, infer TSk, any> ? TSk extends keyof z.infer<TSchema> ? Pick<z.infer<TSchema>, TPk | TSk> : Pick<z.infer<TSchema>, TPk> : T extends {
+    schema: infer TSchema extends z.ZodTypeAny;
+    pk: infer TPk;
+    sk: infer TSk;
+} ? TSk extends keyof z.infer<TSchema> ? Pick<z.infer<TSchema>, (TPk & keyof z.infer<TSchema>) | TSk> : Pick<z.infer<TSchema>, TPk & keyof z.infer<TSchema>> : never;
+/**
+ * Query builder for type-safe DynamoDB queries
+ */
+interface QueryBuilder<TTable extends AnyDynamoTable> {
+    filter(fn: (q: FilterBuilder<TTable>) => FilterCondition): QueryBuilder<TTable>;
+    useIndex(indexName: keyof TTable['indexes'] & string): QueryBuilder<TTable>;
+    take(limit: number): QueryBuilder<TTable>;
+    sortAscending(): QueryBuilder<TTable>;
+    sortDescending(): QueryBuilder<TTable>;
+    execute(): Promise<TableItem<TTable>[]>;
+}
+/**
+ * Filter builder for query conditions
+ */
+interface FilterBuilder<TTable extends AnyDynamoTable> {
+    eq<K extends keyof TableItem<TTable>>(field: FieldRef<K & string, TableItem<TTable>[K]>, value: TableItem<TTable>[K]): FilterCondition;
+    ne<K extends keyof TableItem<TTable>>(field: FieldRef<K & string, TableItem<TTable>[K]>, value: TableItem<TTable>[K]): FilterCondition;
+    gt<K extends keyof TableItem<TTable>>(field: FieldRef<K & string, TableItem<TTable>[K]>, value: TableItem<TTable>[K]): FilterCondition;
+    gte<K extends keyof TableItem<TTable>>(field: FieldRef<K & string, TableItem<TTable>[K]>, value: TableItem<TTable>[K]): FilterCondition;
+    lt<K extends keyof TableItem<TTable>>(field: FieldRef<K & string, TableItem<TTable>[K]>, value: TableItem<TTable>[K]): FilterCondition;
+    lte<K extends keyof TableItem<TTable>>(field: FieldRef<K & string, TableItem<TTable>[K]>, value: TableItem<TTable>[K]): FilterCondition;
+    between<K extends keyof TableItem<TTable>>(field: FieldRef<K & string, TableItem<TTable>[K]>, lower: TableItem<TTable>[K], upper: TableItem<TTable>[K]): FilterCondition;
+    beginsWith<K extends keyof TableItem<TTable>>(field: FieldRef<K & string, string>, prefix: string): FilterCondition;
+    contains<K extends keyof TableItem<TTable>>(field: FieldRef<K & string, string>, substring: string): FilterCondition;
+    and(...conditions: FilterCondition[]): FilterCondition;
+    or(...conditions: FilterCondition[]): FilterCondition;
+    not(condition: FilterCondition): FilterCondition;
+}
+/**
+ * Procedure types
+ */
+type ProcedureType = 'query' | 'mutation';
+/**
+ * Procedure definition
+ */
+interface ProcedureDefinition<TContext, TInput extends z.ZodTypeAny = z.ZodUndefined, TOutput = unknown, TType extends ProcedureType = ProcedureType> {
+    type: TType;
+    inputSchema?: TInput;
+    resolver: (opts: {
+        ctx: TContext & {
+            db: DatabaseContext;
+        };
+        input: z.infer<TInput>;
+    }) => Promise<TOutput> | TOutput;
+}
+/**
+ * Any procedure definition - used for generic constraints
+ * Uses 'any' for input/output to allow covariant assignment
+ */
+type AnyProcedureDefinition<TContext> = ProcedureDefinition<TContext, any, any, ProcedureType>;
+/**
+ * Router definition
+ */
+type RouterDefinition<TContext> = {
+    [key: string]: AnyProcedureDefinition<TContext> | RouterDefinition<TContext>;
+};
+/**
+ * Dependency information extracted from a query
+ */
+interface QueryDependency {
+    tableName: string;
+    fieldName: string;
+    fieldValue: 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, 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)
+ */
+interface TrackedQueryOperation {
+    tableName: string;
+    filters: FilterCondition[];
+    indexName?: string;
+    /** Field names selected by useIndex, used to preserve sparse membership. */
+    indexPkField?: string;
+    indexSkField?: string;
+    /** Sort field for ordering results */
+    sortField?: string;
+    /** Sort direction */
+    sortOrder?: 'asc' | 'desc';
+    /** Maximum number of results */
+    limit?: number;
+}
+
+/**
+ * Procedure builder for creating type-safe procedures
+ */
+declare class ProcedureBuilder<TContext, TInput extends z.ZodType = z.ZodUndefined> {
+    private inputSchema?;
+    constructor(inputSchema?: TInput);
+    /**
+     * Define the input schema for the procedure
+     */
+    input<TNewInput extends z.ZodType>(schema: TNewInput): ProcedureBuilder<TContext, TNewInput>;
+    /**
+     * Define a query procedure (read-only operation)
+     */
+    query<TOutput>(resolver: (opts: {
+        ctx: TContext & {
+            db: DatabaseContext;
+        };
+        input: z.infer<TInput>;
+    }) => Promise<TOutput> | TOutput): ProcedureDefinition<TContext, TInput, TOutput, 'query'>;
+    /**
+     * Define a mutation procedure (write operation)
+     */
+    mutation<TOutput>(resolver: (opts: {
+        ctx: TContext & {
+            db: DatabaseContext;
+        };
+        input: z.infer<TInput>;
+    }) => Promise<TOutput> | TOutput): ProcedureDefinition<TContext, TInput, TOutput, 'mutation'>;
+}
+
+/**
+ * Router class for organizing procedures
+ */
+declare class Router<TContext, TRouter extends RouterDefinition<TContext>> {
+    readonly definition: TRouter;
+    constructor(definition: TRouter);
+    /**
+     * Get a procedure by its path (e.g., "todos.list")
+     */
+    getProcedure(path: string): AnyProcedureDefinition<TContext> | null;
+    /**
+     * Execute a procedure by its path
+     */
+    execute(path: string, ctx: TContext & {
+        db: DatabaseContext;
+    }, input: unknown): Promise<unknown>;
+}
+
+/**
+ * ReactiveBuilder - The main builder returned by initReactive
+ */
+interface ReactiveBuilder<TContext> {
+    /**
+     * Create a new procedure builder
+     */
+    procedure: ProcedureBuilder<TContext>;
+    /**
+     * Create a router from procedure definitions
+     */
+    router<TRouter extends RouterDefinition<TContext>>(definition: TRouter): Router<TContext, TRouter>;
+}
+/**
+ * Initialize the reactive system with a context type
+ *
+ * @example
+ * ```ts
+ * const t = initReactive<{ userId: string }>();
+ *
+ * export const appRouter = t.router({
+ *   todos: {
+ *     list: t.procedure
+ *       .input(z.object({ taskListId: z.string() }))
+ *       .query(({ ctx, input }) => {
+ *         return ctx.db
+ *           .query(TodoTable)
+ *           .filter((q) => q.eq(TodoTable.field.taskListId, input.taskListId))
+ *           .take(50);
+ *       }),
+ *   }
+ * });
+ * ```
+ */
+declare function initReactive<TContext = Record<string, unknown>>(): ReactiveBuilder<TContext>;
+/**
+ * Type helper to infer the router type
+ */
+type InferRouterType<T> = T extends Router<infer TContext, infer TRouter> ? {
+    context: TContext;
+    router: TRouter;
+} : never;
+/**
+ * Type helper to get procedure input type
+ */
+type InferProcedureInput<T> = T extends {
+    inputSchema: infer TSchema;
+} ? TSchema extends z.ZodType ? z.infer<TSchema> : undefined : undefined;
+/**
+ * Type helper to get procedure output type
+ */
+type InferProcedureOutput<T> = T extends {
+    resolver: (...args: any[]) => infer TOutput;
+} ? Awaited<TOutput> : unknown;
+
+/** 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
+ */
+declare class DependencyTracker {
+    private operations;
+    /**
+     * Track a query operation
+     */
+    track(operation: TrackedQueryOperation, result: unknown[]): void;
+    /**
+     * Get all tracked operations
+     */
+    getOperations(): TrackedQueryOperation[];
+    /**
+     * Extract all dependencies from tracked operations
+     */
+    extractAll(): QueryDependency[];
+    /**
+     * Get query metadata for the first tracked operation.
+     * Used for storing subscription state.
+     */
+    getQueryMetadata(): QueryMetadata | null;
+    getCapturedResult(): {
+        reference: unknown[];
+        snapshot: unknown[];
+    } | null;
+}
+
+/**
+ * Configuration for creating a database context
+ */
+interface DbContextConfig {
+    client?: DynamoDBClient;
+    docClient?: DynamoDBDocumentClient;
+    region?: string;
+    endpoint?: string;
+}
+/**
+ * Creates a database context for procedure execution
+ */
+declare function createDbContext(config: DbContextConfig, dependencyTracker?: DependencyTracker): DatabaseContext;
+
+interface SubscribeRequest {
+    type: 'subscribe';
+    connectionId: string;
+    subscriptionId: string;
+    generation: number;
+    registrationId: string;
+    path: string;
+    input: unknown;
+}
+interface UnsubscribeRequest {
+    type: 'unsubscribe';
+    connectionId: string;
+    subscriptionId: string;
+    generation: number;
+    registrationId: string;
+}
+interface CallRequest {
+    type: 'call';
+    connectionId: string;
+    path: string;
+    input: unknown;
+}
+type ReactiveRequest = SubscribeRequest | UnsubscribeRequest | CallRequest;
+interface SnapshotResponse {
+    type: 'snapshot';
+    subscriptionId: string;
+    generation: number;
+    version: number;
+    data: unknown[];
+}
+interface ResultResponse {
+    type: 'result';
+    data: unknown;
+}
+interface ErrorResponse {
+    type: 'error';
+    message: string;
+    code?: number;
+    subscriptionId?: string;
+}
+type ReactiveResponse = SnapshotResponse | ResultResponse | ErrorResponse;
+interface RequestInfo {
+    connectionId: string;
+    headers?: Record<string, string>;
+}
+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;
+    tablePrefix: string;
+}
+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>;
+};
+
+interface LambdaHandlersConfig {
+    dbConfig?: DbContextConfig;
+    apiClient?: ApiGatewayManagementApiClient;
+    connectionsTableName?: string;
+    dependenciesTableName?: string;
+    queriesTableName?: string;
+    apiGatewayEndpoint?: string;
+}
+declare function createLambdaHandlers(config?: LambdaHandlersConfig): {
+    connectHandler: (event: APIGatewayProxyEvent) => Promise<APIGatewayProxyResult>;
+    disconnectHandler: (event: APIGatewayProxyEvent) => Promise<APIGatewayProxyResult>;
+    messageHandler: (event: APIGatewayProxyEvent) => Promise<APIGatewayProxyResult>;
+    streamHandler: (event: DynamoDBStreamEvent) => Promise<aws_lambda.DynamoDBBatchResponse>;
+};
+
+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 };