effortless-aws 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -191,9 +191,9 @@ type ResolveParams<P> = {
 declare function param(key: string): ParamRef<string>;
 declare function param<T>(key: string, transform: (raw: string) => T): ParamRef<T>;
 
-type AnyTableHandler$1 = TableHandler<any, any, any, any, any, any>;
+type AnyTableHandler$2 = TableHandler<any, any, any, any, any, any>;
 /** Maps a deps declaration to resolved runtime client types */
-type ResolveDeps$1<D> = {
+type ResolveDeps$2<D> = {
     [K in keyof D]: D[K] extends TableHandler<infer T, any, any, any, any> ? TableClient<T> : never;
 };
 /** DynamoDB attribute types for keys */
@@ -275,7 +275,7 @@ type FailedRecord<T = Record<string, unknown>> = {
  * Without params: `() => C | Promise<C>`
  * With params: `(args: { params: ResolveParams<P> }) => C | Promise<C>`
  */
-type ContextFactory$1<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (args: {
+type ContextFactory$2<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (args: {
     params: ResolveParams<P & {}>;
 }) => C | Promise<C>;
 /**
@@ -287,7 +287,7 @@ type TableRecordFn<T = Record<string, unknown>, C = undefined, R = void, D = und
 } & ([C] extends [undefined] ? {} : {
     ctx: C;
 }) & ([D] extends [undefined] ? {} : {
-    deps: ResolveDeps$1<D>;
+    deps: ResolveDeps$2<D>;
 }) & ([P] extends [undefined] ? {} : {
     params: ResolveParams<P>;
 }) & ([S] extends [undefined] ? {} : {
@@ -303,7 +303,7 @@ type TableBatchCompleteFn<T = Record<string, unknown>, C = undefined, R = void,
 } & ([C] extends [undefined] ? {} : {
     ctx: C;
 }) & ([D] extends [undefined] ? {} : {
-    deps: ResolveDeps$1<D>;
+    deps: ResolveDeps$2<D>;
 }) & ([P] extends [undefined] ? {} : {
     params: ResolveParams<P>;
 }) & ([S] extends [undefined] ? {} : {
@@ -318,7 +318,7 @@ type TableBatchFn<T = Record<string, unknown>, C = undefined, D = undefined, P =
 } & ([C] extends [undefined] ? {} : {
     ctx: C;
 }) & ([D] extends [undefined] ? {} : {
-    deps: ResolveDeps$1<D>;
+    deps: ResolveDeps$2<D>;
 }) & ([P] extends [undefined] ? {} : {
     params: ResolveParams<P>;
 }) & ([S] extends [undefined] ? {} : {
@@ -343,7 +343,7 @@ type DefineTableBase<T = Record<string, unknown>, C = undefined, D = undefined,
      * When params are declared, receives resolved params as argument.
      * Supports both sync and async return values.
      */
-    context?: ContextFactory$1<C, P>;
+    context?: ContextFactory$2<C, P>;
     /**
      * Dependencies on other handlers (tables, queues, etc.).
      * Typed clients are injected into the handler via the `deps` argument.
@@ -379,7 +379,7 @@ type DefineTableResourceOnly<T = Record<string, unknown>, C = undefined, D = und
     onBatch?: never;
     onBatchComplete?: never;
 };
-type DefineTableOptions<T = Record<string, unknown>, C = undefined, R = void, D extends Record<string, AnyTableHandler$1> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined> = DefineTableWithOnRecord<T, C, R, D, P, S> | DefineTableWithOnBatch<T, C, D, P, S> | DefineTableResourceOnly<T, C, D, P, S>;
+type DefineTableOptions<T = Record<string, unknown>, C = undefined, R = void, D extends Record<string, AnyTableHandler$2> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined> = DefineTableWithOnRecord<T, C, R, D, P, S> | DefineTableWithOnBatch<T, C, D, P, S> | DefineTableResourceOnly<T, C, D, P, S>;
 /**
  * Internal handler object created by defineTable
  * @internal
@@ -428,11 +428,11 @@ type TableHandler<T = Record<string, unknown>, C = undefined, R = void, D = unde
  * });
  * ```
  */
-declare const defineTable: <T = Record<string, unknown>, C = undefined, R = void, D extends Record<string, AnyTableHandler$1> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineTableOptions<T, C, R, D, P, S>) => TableHandler<T, C, R, D, P, S>;
+declare const defineTable: <T = Record<string, unknown>, C = undefined, R = void, D extends Record<string, AnyTableHandler$2> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineTableOptions<T, C, R, D, P, S>) => TableHandler<T, C, R, D, P, S>;
 
-type AnyTableHandler = TableHandler<any, any, any, any, any, any>;
+type AnyTableHandler$1 = TableHandler<any, any, any, any, any, any>;
 /** Maps a deps declaration to resolved runtime client types */
-type ResolveDeps<D> = {
+type ResolveDeps$1<D> = {
     [K in keyof D]: D[K] extends TableHandler<infer T, any, any, any, any> ? TableClient<T> : never;
 };
 /** HTTP methods supported by API Gateway */
@@ -515,7 +515,7 @@ type HttpHandlerFn<T = undefined, C = undefined, D = undefined, P = undefined, S
 }) & ([C] extends [undefined] ? {} : {
     ctx: C;
 }) & ([D] extends [undefined] ? {} : {
-    deps: ResolveDeps<D>;
+    deps: ResolveDeps$1<D>;
 }) & ([P] extends [undefined] ? {} : {
     params: ResolveParams<P>;
 }) & ([S] extends [undefined] ? {} : {
@@ -526,7 +526,7 @@ type HttpHandlerFn<T = undefined, C = undefined, D = undefined, P = undefined, S
  * Without params: `() => C | Promise<C>`
  * With params: `(args: { params: ResolveParams<P> }) => C | Promise<C>`
  */
-type ContextFactory<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (args: {
+type ContextFactory$1<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (args: {
     params: ResolveParams<P & {}>;
 }) => C | Promise<C>;
 /**
@@ -537,7 +537,7 @@ type ContextFactory<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (ar
  * @typeParam D - Type of the deps (from deps declaration)
  * @typeParam P - Type of the params (from params declaration)
  */
-type DefineHttpOptions<T = undefined, C = undefined, D extends Record<string, AnyTableHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined> = HttpConfig & {
+type DefineHttpOptions<T = undefined, C = undefined, D extends Record<string, AnyTableHandler$1> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined> = HttpConfig & {
     /**
      * Decode/validate function for the request body.
      * Called with the parsed body; should return typed data or throw on validation failure.
@@ -560,7 +560,7 @@ type DefineHttpOptions<T = undefined, C = undefined, D extends Record<string, An
      * When params are declared, receives resolved params as argument.
      * Supports both sync and async return values.
      */
-    context?: ContextFactory<C, P>;
+    context?: ContextFactory$1<C, P>;
     /**
      * Dependencies on other handlers (tables, queues, etc.).
      * Typed clients are injected into the handler via the `deps` argument.
@@ -637,7 +637,7 @@ type HttpHandler<T = undefined, C = undefined, D = undefined, P = undefined, S e
  * });
  * ```
  */
-declare const defineHttp: <T = undefined, C = undefined, D extends Record<string, AnyTableHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineHttpOptions<T, C, D, P, S>) => HttpHandler<T, C, D, P, S>;
+declare const defineHttp: <T = undefined, C = undefined, D extends Record<string, AnyTableHandler$1> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineHttpOptions<T, C, D, P, S>) => HttpHandler<T, C, D, P, S>;
 
 /**
  * Configuration for a Lambda-served static site (API Gateway + Lambda)
@@ -737,6 +737,236 @@ type StaticSiteHandler = {
  */
 declare const defineStaticSite: (options: StaticSiteConfig) => StaticSiteHandler;
 
+type AnyTableHandler = TableHandler<any, any, any, any, any, any>;
+/** Maps a deps declaration to resolved runtime client types */
+type ResolveDeps<D> = {
+    [K in keyof D]: D[K] extends TableHandler<infer T, any, any, any, any> ? TableClient<T> : never;
+};
+/**
+ * Parsed SQS FIFO message passed to the handler callbacks.
+ *
+ * @typeParam T - Type of the decoded message body (from schema function)
+ */
+type FifoQueueMessage<T = unknown> = {
+    /** Unique message identifier */
+    messageId: string;
+    /** Receipt handle for acknowledgement */
+    receiptHandle: string;
+    /** Parsed message body (JSON-decoded, then optionally schema-validated) */
+    body: T;
+    /** Raw unparsed message body string */
+    rawBody: string;
+    /** Message group ID (FIFO ordering key) */
+    messageGroupId: string;
+    /** Message deduplication ID */
+    messageDeduplicationId?: string;
+    /** SQS message attributes */
+    messageAttributes: Record<string, {
+        dataType?: string;
+        stringValue?: string;
+    }>;
+    /** Approximate first receive timestamp */
+    approximateFirstReceiveTimestamp?: string;
+    /** Approximate receive count */
+    approximateReceiveCount?: string;
+    /** Sent timestamp */
+    sentTimestamp?: string;
+};
+/**
+ * Configuration options for a FIFO queue handler
+ */
+type FifoQueueConfig = {
+    /** Handler name. Defaults to export name if not specified */
+    name?: string;
+    /** Number of messages per Lambda invocation (1-10 for FIFO, default: 10) */
+    batchSize?: number;
+    /** Maximum time in seconds to gather messages before invoking (0-300, default: 0) */
+    batchWindow?: number;
+    /** Visibility timeout in seconds (default: max of timeout or 30) */
+    visibilityTimeout?: number;
+    /** Message retention period in seconds (60-1209600, default: 345600 = 4 days) */
+    retentionPeriod?: number;
+    /** Enable content-based deduplication (default: true) */
+    contentBasedDeduplication?: boolean;
+    /** Lambda memory in MB (default: 256) */
+    memory?: number;
+    /** Lambda timeout in seconds (default: 30) */
+    timeout?: number;
+    /** Additional IAM permissions for the Lambda */
+    permissions?: Permission[];
+    /** Enable observability logging to platform table (default: true) */
+    observe?: boolean;
+};
+/**
+ * Context factory type — conditional on whether params are declared.
+ * Without params: `() => C | Promise<C>`
+ * With params: `(args: { params: ResolveParams<P> }) => C | Promise<C>`
+ */
+type ContextFactory<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (args: {
+    params: ResolveParams<P & {}>;
+}) => C | Promise<C>;
+/**
+ * Per-message handler function.
+ * Called once per message in the batch. Failures are reported individually.
+ */
+type FifoQueueMessageFn<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = (args: {
+    message: FifoQueueMessage<T>;
+} & ([C] extends [undefined] ? {} : {
+    ctx: C;
+}) & ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    params: ResolveParams<P>;
+}) & ([S] extends [undefined] ? {} : {
+    readStatic: (path: string) => string;
+})) => Promise<void>;
+/**
+ * Batch handler function.
+ * Called once with all messages in the batch.
+ */
+type FifoQueueBatchFn<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = (args: {
+    messages: FifoQueueMessage<T>[];
+} & ([C] extends [undefined] ? {} : {
+    ctx: C;
+}) & ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    params: ResolveParams<P>;
+}) & ([S] extends [undefined] ? {} : {
+    readStatic: (path: string) => string;
+})) => Promise<void>;
+/** Base options shared by all defineFifoQueue variants */
+type DefineFifoQueueBase<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = FifoQueueConfig & {
+    /**
+     * Decode/validate function for the message body.
+     * Called with the JSON-parsed body; should return typed data or throw on validation failure.
+     */
+    schema?: (input: unknown) => T;
+    /**
+     * Error handler called when onMessage or onBatch throws.
+     * If not provided, defaults to `console.error`.
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * Factory function to create context/dependencies for the handler.
+     * Called once on cold start, result is cached and reused across invocations.
+     * When params are declared, receives resolved params as argument.
+     */
+    context?: ContextFactory<C, P>;
+    /**
+     * Dependencies on other handlers (tables, queues, etc.).
+     * Typed clients are injected into the handler via the `deps` argument.
+     */
+    deps?: D;
+    /**
+     * SSM Parameter Store parameters.
+     * Declare with `param()` helper. Values are fetched and cached at cold start.
+     */
+    params?: P;
+    /**
+     * Static file glob patterns to bundle into the Lambda ZIP.
+     * Files are accessible at runtime via the `readStatic` callback argument.
+     */
+    static?: S;
+};
+/** Per-message processing */
+type DefineFifoQueueWithOnMessage<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = DefineFifoQueueBase<T, C, D, P, S> & {
+    onMessage: FifoQueueMessageFn<T, C, D, P, S>;
+    onBatch?: never;
+};
+/** Batch processing: all messages at once */
+type DefineFifoQueueWithOnBatch<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = DefineFifoQueueBase<T, C, D, P, S> & {
+    onBatch: FifoQueueBatchFn<T, C, D, P, S>;
+    onMessage?: never;
+};
+type DefineFifoQueueOptions<T = unknown, C = undefined, D extends Record<string, AnyTableHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined> = DefineFifoQueueWithOnMessage<T, C, D, P, S> | DefineFifoQueueWithOnBatch<T, C, D, P, S>;
+/**
+ * Internal handler object created by defineFifoQueue
+ * @internal
+ */
+type FifoQueueHandler<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = {
+    readonly __brand: "effortless-fifo-queue";
+    readonly config: FifoQueueConfig;
+    readonly schema?: (input: unknown) => T;
+    readonly onError?: (error: unknown) => void;
+    readonly context?: (...args: any[]) => C | Promise<C>;
+    readonly deps?: D;
+    readonly params?: P;
+    readonly static?: string[];
+    readonly onMessage?: FifoQueueMessageFn<T, C, D, P, S>;
+    readonly onBatch?: FifoQueueBatchFn<T, C, D, P, S>;
+};
+/**
+ * Define a FIFO SQS queue with a Lambda message handler
+ *
+ * Creates:
+ * - SQS FIFO queue (with `.fifo` suffix)
+ * - Lambda function triggered by the queue
+ * - Event source mapping with partial batch failure support
+ *
+ * @example Per-message processing
+ * ```typescript
+ * type OrderEvent = { orderId: string; action: string };
+ *
+ * export const orderQueue = defineFifoQueue<OrderEvent>({
+ *   onMessage: async ({ message }) => {
+ *     console.log("Processing order:", message.body.orderId);
+ *   }
+ * });
+ * ```
+ *
+ * @example Batch processing with schema
+ * ```typescript
+ * export const notifications = defineFifoQueue({
+ *   schema: (input) => NotificationSchema.parse(input),
+ *   batchSize: 5,
+ *   onBatch: async ({ messages }) => {
+ *     await sendAll(messages.map(m => m.body));
+ *   }
+ * });
+ * ```
+ */
+declare const defineFifoQueue: <T = unknown, C = undefined, D extends Record<string, AnyTableHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineFifoQueueOptions<T, C, D, P, S>) => FifoQueueHandler<T, C, D, P, S>;
+
+/**
+ * Type-only schema helper for handlers.
+ *
+ * Use this instead of explicit generic parameters like `defineTable<Order>(...)`.
+ * It enables TypeScript to infer all generic types from the options object,
+ * avoiding the partial-inference problem where specifying one generic
+ * forces all others to their defaults.
+ *
+ * At runtime this is a no-op identity function — it simply returns the input unchanged.
+ * The type narrowing happens entirely at the TypeScript level.
+ *
+ * @example Resource-only table
+ * ```typescript
+ * type User = { id: string; email: string };
+ *
+ * // Before (breaks inference for context, deps, params):
+ * export const users = defineTable<User>({ pk: { name: "id", type: "string" } });
+ *
+ * // After (all generics inferred correctly):
+ * export const users = defineTable({
+ *   pk: { name: "id", type: "string" },
+ *   schema: typed<User>(),
+ * });
+ * ```
+ *
+ * @example Table with stream handler
+ * ```typescript
+ * export const orders = defineTable({
+ *   pk: { name: "id", type: "string" },
+ *   schema: typed<Order>(),
+ *   context: async () => ({ db: createClient() }),
+ *   onRecord: async ({ record, ctx }) => {
+ *     // record.new is Order, ctx is { db: Client } — all inferred
+ *   },
+ * });
+ * ```
+ */
+declare function typed<T>(): (input: unknown) => T;
+
 type BasePlatformEntity = {
     pk: string;
     sk: string;
@@ -760,15 +990,15 @@ type ErrorEntry = {
 type ExecutionLogEntity = BasePlatformEntity & {
     type: "execution-log";
     handlerName: string;
-    handlerType: "http" | "table";
+    handlerType: "http" | "table" | "app" | "fifo-queue";
     executions: ExecutionEntry[];
     errors: ErrorEntry[];
 };
 type PlatformEntity = ExecutionLogEntity;
 
 type PlatformClient = {
-    appendExecution(handlerName: string, handlerType: "http" | "table" | "app", entry: ExecutionEntry): Promise<void>;
-    appendError(handlerName: string, handlerType: "http" | "table" | "app", entry: ErrorEntry): Promise<void>;
+    appendExecution(handlerName: string, handlerType: "http" | "table" | "app" | "fifo-queue", entry: ExecutionEntry): Promise<void>;
+    appendError(handlerName: string, handlerType: "http" | "table" | "app" | "fifo-queue", entry: ErrorEntry): Promise<void>;
     get<T extends PlatformEntity>(pk: string, sk: string): Promise<T | undefined>;
     query<T extends PlatformEntity>(pk: string, skPrefix?: string): Promise<T[]>;
     put(entity: PlatformEntity): Promise<void>;
@@ -776,4 +1006,4 @@ type PlatformClient = {
 };
 declare const createPlatformClient: () => PlatformClient | undefined;
 
-export { type AppConfig, type AppHandler, type BasePlatformEntity, type ContentType, type DefineHttpOptions, type DefineTableOptions, type EffortlessConfig, type ErrorEntry, type ExecutionEntry, type ExecutionLogEntity, type FailedRecord, type HttpConfig, type HttpHandler, type HttpHandlerFn, type HttpMethod, type HttpRequest, type HttpResponse, type KeyType, type ParamRef, type PlatformClient, type PlatformEntity, type QueryParams, type ResolveDeps, type ResolveParams, type StaticSiteConfig, type StaticSiteHandler, type StreamView, type TableBatchCompleteFn, type TableBatchFn, type TableClient, type TableConfig, type TableHandler, type TableKey, type TableRecord, type TableRecordFn, createPlatformClient, defineApp, defineConfig, defineHttp, defineStaticSite, defineTable, param };
+export { type AppConfig, type AppHandler, type BasePlatformEntity, type ContentType, type DefineFifoQueueOptions, type DefineHttpOptions, type DefineTableOptions, type EffortlessConfig, type ErrorEntry, type ExecutionEntry, type ExecutionLogEntity, type FailedRecord, type FifoQueueBatchFn, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type FifoQueueMessageFn, type HttpConfig, type HttpHandler, type HttpHandlerFn, type HttpMethod, type HttpRequest, type HttpResponse, type KeyType, type ParamRef, type PlatformClient, type PlatformEntity, type QueryParams, type ResolveDeps$1 as ResolveDeps, type ResolveParams, type StaticSiteConfig, type StaticSiteHandler, type StreamView, type TableBatchCompleteFn, type TableBatchFn, type TableClient, type TableConfig, type TableHandler, type TableKey, type TableRecord, type TableRecordFn, createPlatformClient, defineApp, defineConfig, defineFifoQueue, defineHttp, defineStaticSite, defineTable, param, typed };

package/dist/index.js

@@ -47,6 +47,23 @@ var defineStaticSite = (options) => ({
   config: options
 });
 
+// src/handlers/define-fifo-queue.ts
+var defineFifoQueue = (options) => {
+  const { onMessage, onBatch, onError, schema, context, deps, params, static: staticFiles, ...config } = options;
+  return {
+    __brand: "effortless-fifo-queue",
+    config,
+    ...schema ? { schema } : {},
+    ...onError ? { onError } : {},
+    ...context ? { context } : {},
+    ...deps ? { deps } : {},
+    ...params ? { params } : {},
+    ...staticFiles ? { static: staticFiles } : {},
+    ...onMessage ? { onMessage } : {},
+    ...onBatch ? { onBatch } : {}
+  };
+};
+
 // src/handlers/param.ts
 function param(key, transform) {
   return {
@@ -56,6 +73,11 @@ function param(key, transform) {
   };
 }
 
+// src/handlers/typed.ts
+function typed() {
+  return (input) => input;
+}
+
 // src/runtime/platform-client.ts
 import { DynamoDB } from "@aws-sdk/client-dynamodb";
 import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
@@ -150,9 +172,11 @@ export {
   createPlatformClient,
   defineApp,
   defineConfig,
+  defineFifoQueue,
   defineHttp,
   defineStaticSite,
   defineTable,
-  param
+  param,
+  typed
 };
 //# sourceMappingURL=index.js.map