effortless-aws 0.37.0 → 0.39.0

package/dist/{chunk-3NKYT4OX.js → chunk-GQKZZ7G7.js}

@@ -112,7 +112,7 @@ var buildParams = async (params) => {
 var resolvePath = (filePath) => join(process.cwd(), filePath);
 var staticFiles = {
   read: (filePath) => readFileSync(resolvePath(filePath), "utf-8"),
-  readBuffer: (filePath) => readFileSync(resolvePath(filePath)),
+  readBytes: (filePath) => readFileSync(resolvePath(filePath)),
   path: resolvePath
 };
 var createHandlerRuntime = (handler, handlerType, logLevel = "info", extraSetupArgs) => {

package/dist/index.d.ts

@@ -101,7 +101,7 @@ type LambdaConfig = {
 };
 /**
  * Lambda configuration with additional IAM permissions.
- * Used by handler types that support custom permissions (http, table, fifo-queue).
+ * Used by handler types that support custom permissions (http, table, queue).
  */
 type LambdaWithPermissions = LambdaConfig & {
     /** Additional IAM permissions for the Lambda */
@@ -249,7 +249,12 @@ type HttpRequest = {
 type HttpResponse = {
     /** HTTP status code (e.g., 200, 404, 500) */
     status: number;
-    /** Response body — JSON-serialized by default, or sent as string when contentType is set */
+    /**
+     * Response body. Type determines serialization:
+     * - `Uint8Array` (incl. `Buffer`) — sent as binary, base64-encoded
+     * - `Blob` — sent as binary, base64-encoded; `Blob.type` is used as Content-Type when not set explicitly
+     * - other values — JSON-serialized by default, or sent as string when `contentType` is set
+     */
     body?: unknown;
     /**
      * Short content-type alias. Resolves to full MIME type automatically:
@@ -272,10 +277,14 @@ type HttpResponse = {
      */
     cookies?: string[];
     /**
-     * Set to `true` to return binary data.
-     * When enabled, `body` must be a base64-encoded string and the response
-     * will include `isBase64Encoded: true` so Lambda Function URLs / API Gateway
-     * decode it back to binary for the client.
+     * Force the client to download the response as a file with the given filename.
+     * Sets `Content-Disposition: attachment; filename="<value>"`. Works with any body type
+     * (JSON, text, binary). An explicit `Content-Disposition` header overrides this.
+     */
+    downloadAs?: string;
+    /**
+     * Set to `true` to return binary data when `body` is already a base64-encoded string.
+     * Prefer returning `Uint8Array` / `Buffer` / `Blob` directly — the runtime detects them automatically.
      */
     binary?: boolean;
 };
@@ -294,8 +303,8 @@ type ResponseStream = {
 type StaticFiles = {
     /** Read file as UTF-8 string */
     read(path: string): string;
-    /** Read file as Buffer (for binary content) */
-    readBuffer(path: string): Buffer;
+    /** Read file as raw bytes (for binary content) */
+    readBytes(path: string): Uint8Array;
     /** Resolve absolute path to the bundled file */
     path(path: string): string;
 };
@@ -480,14 +489,6 @@ interface BucketBuilder<D = undefined, P = undefined, C = undefined, HasFiles ex
  * Define an S3 bucket with optional event handlers.
  *
  * @see {@link https://effortless-aws.website/use-cases/storage | Storage guide}
- *
- * @example
- * ```typescript
- * export const uploads = defineBucket({ prefix: "images/", suffix: ".jpg" })
- *   .onObjectCreated(async ({ event, bucket }) => {
- *     console.log("New upload:", event.key);
- *   })
- * ```
  */
 declare function defineBucket(): BucketBuilder;
 declare function defineBucket(options: BucketOptions): BucketBuilder;
@@ -517,37 +518,15 @@ type MailerHandler = {
  * Add them to your DNS provider to verify the domain.
  *
  * @see {@link https://effortless-aws.website/use-cases/email | Email guide}
- *
- * @param options - Mailer configuration with the domain to send from
- * @returns Handler object used by the deployment system and as a `deps` value
- *
- * @example Basic mailer with HTTP handler
- * ```typescript
- * export const mailer = defineMailer({ domain: "myapp.com" });
- *
- * export const api = defineApi({
- *   basePath: "/signup",
- *   deps: { mailer },
- *   post: async ({ req, deps }) => {
- *     await deps.mailer.send({
- *       from: "hello@myapp.com",
- *       to: req.body.email,
- *       subject: "Welcome!",
- *       html: "<h1>Hi!</h1>",
- *     });
- *     return { status: 200, body: { ok: true } };
- *   },
- * });
- * ```
  */
 declare const defineMailer: () => (options: MailerConfig) => MailerHandler;
 
 /**
- * Parsed SQS FIFO message passed to the handler callbacks.
+ * Parsed SQS message passed to the handler callbacks.
  *
  * @typeParam T - Type of the decoded message body (from schema function)
  */
-type FifoQueueMessage<T = unknown> = {
+type QueueMessage<T = unknown> = {
     /** Unique message identifier */
     messageId: string;
     /** Receipt handle for acknowledgement */
@@ -556,9 +535,9 @@ type FifoQueueMessage<T = unknown> = {
     body: T;
     /** Raw unparsed message body string */
     rawBody: string;
-    /** Message group ID (FIFO ordering key) */
+    /** Message group ID (FIFO ordering key, empty string for standard queues) */
     messageGroupId: string;
-    /** Message deduplication ID */
+    /** Message deduplication ID (FIFO only) */
     messageDeduplicationId?: string;
     /** SQS message attributes */
     messageAttributes: Record<string, {
@@ -573,9 +552,18 @@ type FifoQueueMessage<T = unknown> = {
     sentTimestamp?: string;
 };
 /**
- * Configuration options for a FIFO queue handler
+ * Event source mapping (poller) configuration — how Lambda consumes the queue.
  */
-type FifoQueueConfig = {
+type QueuePollerConfig = {
+    /** Number of messages per Lambda invocation (1-10 for FIFO, default: 10) */
+    batchSize?: number;
+    /** Maximum time to gather messages before invoking (default: 0). Accepts `"5s"`, `"1m"`, etc. */
+    batchWindow?: Duration;
+};
+/**
+ * Configuration options for a queue handler.
+ */
+type QueueConfig = {
     /** Lambda function settings (memory, timeout, permissions, etc.) */
     lambda?: {
         memory?: number;
@@ -583,20 +571,23 @@ type FifoQueueConfig = {
         logLevel?: LogLevel;
         permissions?: Permission[];
     };
-    /** Number of messages per Lambda invocation (1-10 for FIFO, default: 10) */
-    batchSize?: number;
-    /** Maximum time to gather messages before invoking (default: 0). Accepts `"5s"`, `"1m"`, etc. */
-    batchWindow?: Duration;
+    /**
+     * Whether this is a FIFO queue (ordered, exactly-once).
+     * Currently only `true` is supported — standard queue support is planned.
+     */
+    fifo?: boolean;
     /** Visibility timeout (default: max of timeout or 30s). Accepts `"30s"`, `"5m"`, etc. */
     visibilityTimeout?: Duration;
     /** Message retention period (default: `"4d"`). Accepts `"1h"`, `"7d"`, etc. */
     retentionPeriod?: Duration;
     /** Delivery delay for all messages in the queue (default: 0). Accepts `"30s"`, `"5m"`, etc. */
     delay?: Duration;
-    /** Enable content-based deduplication (default: true) */
+    /** Enable content-based deduplication for FIFO queues (default: true) */
     contentBasedDeduplication?: boolean;
     /** Max number of receives before a message is sent to the dead-letter queue (default: 3) */
     maxReceiveCount?: number;
+    /** Event source mapping config — set via `.poller({...})` builder method. */
+    poller?: QueuePollerConfig;
 };
 /** Spread ctx into callback args (empty when no setup) */
 type SpreadCtx$5<C> = [C] extends [undefined] ? {} : C & {};
@@ -612,26 +603,26 @@ type SetupArgs$5<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {}
  * Per-message handler function.
  * Called once per message in the batch. Failures are reported individually.
  */
-type FifoQueueMessageFn<T = unknown, C = undefined> = (args: {
-    message: FifoQueueMessage<T>;
+type QueueMessageFn<T = unknown, C = undefined> = (args: {
+    message: QueueMessage<T>;
 } & SpreadCtx$5<C>) => Promise<void>;
 /**
  * Batch handler function.
  * Called once with all messages in the batch.
  * Return `{ failures: string[] }` (messageIds) for partial batch failure reporting.
  */
-type FifoQueueBatchFn<T = unknown, C = undefined> = (args: {
-    messages: FifoQueueMessage<T>[];
+type QueueBatchFn<T = unknown, C = undefined> = (args: {
+    messages: QueueMessage<T>[];
 } & SpreadCtx$5<C>) => Promise<void | {
     failures: string[];
 }>;
 /**
- * Internal handler object created by defineFifoQueue
+ * Internal handler object created by defineQueue.
  * @internal
  */
-type FifoQueueHandler$1<T = unknown, C = any> = {
-    readonly __brand: "effortless-fifo-queue";
-    readonly __spec: FifoQueueConfig;
+type QueueHandler$1<T = unknown, C = any> = {
+    readonly __brand: "effortless-queue";
+    readonly __spec: QueueConfig;
     readonly schema?: (input: unknown) => T;
     readonly onError?: (...args: any[]) => any;
     readonly onCleanup?: (...args: any[]) => any;
@@ -642,64 +633,69 @@ type FifoQueueHandler$1<T = unknown, C = any> = {
     readonly onMessage?: (...args: any[]) => any;
     readonly onMessageBatch?: (...args: any[]) => any;
 };
-/** Options passed to `defineFifoQueue()` — static config */
-type FifoQueueOptions<T> = {
-    /** Number of messages per Lambda invocation (1-10 for FIFO, default: 10) */
-    batchSize?: number;
-    /** Maximum time to gather messages before invoking (default: 0) */
-    batchWindow?: Duration;
+/** Options passed to `defineQueue()` — queue resource config */
+type QueueOptions<T> = {
+    /**
+     * Whether this is a FIFO queue (ordered, exactly-once).
+     * Currently only `true` is supported — standard queue support is planned.
+     */
+    fifo?: boolean;
     /** Visibility timeout (default: max of timeout or 30s) */
     visibilityTimeout?: Duration;
     /** Message retention period (default: "4d") */
     retentionPeriod?: Duration;
     /** Delivery delay for all messages in the queue (default: 0) */
     delay?: Duration;
-    /** Enable content-based deduplication (default: true) */
+    /** Enable content-based deduplication for FIFO queues (default: true) */
     contentBasedDeduplication?: boolean;
     /** Max number of receives before DLQ (default: 3) */
     maxReceiveCount?: number;
     /** Decode/validate function for the message body */
     schema?: (input: unknown) => T;
 };
-interface FifoQueueBuilder<T = unknown, D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
+interface QueueBuilder<T = unknown, D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
     /** Declare handler dependencies */
-    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): FifoQueueBuilder<T, D2, P, C, HasFiles>;
+    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): QueueBuilder<T, D2, P, C, HasFiles>;
     /** Declare SSM secrets */
-    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): FifoQueueBuilder<T, D, P2, C, HasFiles>;
+    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): QueueBuilder<T, D, P2, C, HasFiles>;
     /** Include static files in the Lambda bundle. Chainable — call multiple times. */
-    include(glob: string): FifoQueueBuilder<T, D, P, C, true>;
+    include(glob: string): QueueBuilder<T, D, P, C, true>;
     /** Configure Lambda settings only (memory, timeout, permissions, etc.) */
-    setup(lambda: LambdaOptions): FifoQueueBuilder<T, D, P, C, HasFiles>;
+    setup(lambda: LambdaOptions): QueueBuilder<T, D, P, C, HasFiles>;
     /** Initialize shared state on cold start. Receives deps, config, files. */
-    setup<C2>(fn: (args: SetupArgs$5<D, P, HasFiles>) => C2 | Promise<C2>): FifoQueueBuilder<T, D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$5<D, P, HasFiles>) => C2 | Promise<C2>): QueueBuilder<T, D, P, C2, HasFiles>;
     /** Initialize shared state on cold start + configure Lambda settings. */
-    setup<C2>(fn: (args: SetupArgs$5<D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): FifoQueueBuilder<T, D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$5<D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): QueueBuilder<T, D, P, C2, HasFiles>;
+    /**
+     * Configure the event source mapping (poller) that delivers messages to the Lambda.
+     * Call before the terminal `.onMessage` / `.onMessageBatch`.
+     */
+    poller(options: QueuePollerConfig): QueueBuilder<T, D, P, C, HasFiles>;
     /** Handle errors thrown by message handlers */
     onError(fn: (args: {
         error: unknown;
-    } & SpreadCtx$5<C>) => void | Promise<void>): FifoQueueBuilder<T, D, P, C, HasFiles>;
+    } & SpreadCtx$5<C>) => void | Promise<void>): QueueBuilder<T, D, P, C, HasFiles>;
     /** Cleanup callback — runs after each invocation, before Lambda freezes */
-    onCleanup(fn: (args: SpreadCtx$5<C>) => void | Promise<void>): FifoQueueBuilder<T, D, P, C, HasFiles>;
+    onCleanup(fn: (args: SpreadCtx$5<C>) => void | Promise<void>): QueueBuilder<T, D, P, C, HasFiles>;
     /** Per-message handler (terminal — returns finalized handler) */
-    onMessage(fn: FifoQueueMessageFn<T, C>): FifoQueueHandler$1<T, C>;
+    onMessage(fn: QueueMessageFn<T, C>): QueueHandler$1<T, C>;
     /** Batch handler (terminal — returns finalized handler) */
-    onMessageBatch(fn: FifoQueueBatchFn<T, C>): FifoQueueHandler$1<T, C>;
+    onMessageBatch(fn: QueueBatchFn<T, C>): QueueHandler$1<T, C>;
+    /** Finalize as a resource-only queue (no Lambda). Use when the SQS queue is consumed by an external system. */
+    build(): QueueHandler$1<T, C>;
 }
 /**
- * Define a FIFO SQS queue with a Lambda message handler.
+ * Define an SQS queue with a Lambda message handler.
  *
- * @see {@link https://effortless-aws.website/use-cases/queue | Queue guide}
+ * Currently only FIFO queues are supported — pass `{ fifo: true }` explicitly
+ * (standard queue support is planned). Poller/batch settings live on the
+ * `.poller({...})` builder method; queue-level properties stay in the options
+ * object.
  *
- * @example
- * ```typescript
- * export const notifications = defineFifoQueue({ batchSize: 5, schema: (i) => NotifSchema.parse(i) })
- *   .onMessageBatch(async ({ messages }) => {
- *     await sendAll(messages.map(m => m.body));
- *   })
- * ```
+ * @see {@link https://effortless-aws.website/use-cases/queue | Queue guide}
  */
-declare function defineFifoQueue<T = unknown>(): FifoQueueBuilder<T>;
-declare function defineFifoQueue<T = unknown>(options: FifoQueueOptions<T>): FifoQueueBuilder<T>;
+declare function defineQueue<T = unknown>(): QueueBuilder<T>;
+declare function defineQueue<T = unknown>(options: QueueOptions<T>): QueueBuilder<T>;
 
 /** Fargate container size presets */
 type FargateSize = "0.25vCPU-512mb" | "0.5vCPU-1gb" | "1vCPU-2gb" | "2vCPU-4gb" | "4vCPU-8gb";
@@ -783,17 +779,7 @@ interface WorkerBuilder<T, D = undefined, P = undefined, C = undefined, HasFiles
  *
  * @typeParam T - Type of messages the worker receives via its queue
  *
- * @example
- * ```typescript
- * type Job = { type: "export"; userId: string }
- *
- * export const worker = defineWorker<Job>({ memory: 2048, concurrency: 5 })
- *   .deps(() => ({ orders }))
- *   .setup(async ({ deps }) => ({ db: deps.orders }))
- *   .onMessage(async (msg, { db }) => {
- *     await processJob(msg, db)
- *   })
- * ```
+ * @see {@link https://effortless-aws.website/definitions#defineworker | Worker reference}
  */
 declare function defineWorker<T = unknown>(options?: WorkerOptions): WorkerBuilder<T>;
 
@@ -978,14 +964,32 @@ type WorkerClient<T = unknown> = {
 };
 
 /** Dep value types supported by the deps declaration */
-type AnyDepHandler = TableHandler$1<any, any> | BucketHandler$1<any, any> | MailerHandler | FifoQueueHandler$1<any, any> | WorkerHandler$1<any, any>;
+type AnyDepHandler = TableHandler$1<any, any> | BucketHandler$1<any, any> | MailerHandler | QueueHandler$1<any, any> | WorkerHandler$1<any, any>;
 /** Maps a deps declaration to resolved runtime client types */
 type ResolveDeps<D> = {
-    [K in keyof D]: D[K] extends TableHandler$1<infer T> ? TableClient<T> : D[K] extends BucketHandler$1<any, infer E> ? ({} extends E ? BucketClient : BucketClientWithEntities<E>) : D[K] extends MailerHandler ? EmailClient : D[K] extends FifoQueueHandler$1<infer T> ? QueueClient<T> : D[K] extends WorkerHandler$1<infer T> ? WorkerClient<T> : never;
+    [K in keyof D]: D[K] extends TableHandler$1<infer T> ? TableClient<T> : D[K] extends BucketHandler$1<any, infer E> ? ({} extends E ? BucketClient : BucketClientWithEntities<E>) : D[K] extends MailerHandler ? EmailClient : D[K] extends QueueHandler$1<infer T> ? QueueClient<T> : D[K] extends WorkerHandler$1<infer T> ? WorkerClient<T> : never;
 };
 
 /** DynamoDB Streams view type - determines what data is captured in stream records */
 type StreamView = "NEW_AND_OLD_IMAGES" | "NEW_IMAGE" | "OLD_IMAGE" | "KEYS_ONLY";
+/**
+ * Stream event source mapping configuration.
+ * @internal
+ */
+type TableStreamConfig = {
+    /** Stream view type - what data to include in stream records (default: "NEW_AND_OLD_IMAGES") */
+    streamView?: StreamView;
+    /** Number of records to process in each Lambda invocation (1-10000, default: 100) */
+    batchSize?: number;
+    /** Maximum time to gather records before invoking (default: `"2s"`). Accepts `"5s"`, `"1m"`, etc. */
+    batchWindow?: Duration;
+    /** Where to start reading the stream (default: "LATEST") */
+    startingPosition?: "LATEST" | "TRIM_HORIZON";
+    /** Number of records to process concurrently within a batch (default: 1 — sequential) */
+    concurrency?: number;
+    /** Max retry attempts for failed records before sending to DLQ (default: 1) */
+    maxRetries?: number;
+};
 /**
  * Configuration options for defineTable (single-table design).
  *
@@ -1002,22 +1006,14 @@ type TableConfig = {
     };
     /** DynamoDB billing mode (default: "PAY_PER_REQUEST") */
     billingMode?: "PAY_PER_REQUEST" | "PROVISIONED";
-    /** Stream view type - what data to include in stream records (default: "NEW_AND_OLD_IMAGES") */
-    streamView?: StreamView;
-    /** Number of records to process in each Lambda invocation (1-10000, default: 100) */
-    batchSize?: number;
-    /** Maximum time to gather records before invoking (default: `"2s"`). Accepts `"5s"`, `"1m"`, etc. */
-    batchWindow?: Duration;
-    /** Where to start reading the stream (default: "LATEST") */
-    startingPosition?: "LATEST" | "TRIM_HORIZON";
-    /** Number of records to process concurrently within a batch (default: 1 — sequential) */
-    concurrency?: number;
     /**
      * Name of the field in `data` that serves as the entity type discriminant.
      * Effortless auto-copies `data[tagField]` to the top-level DynamoDB `tag` attribute on `put()`.
      * Defaults to `"tag"`.
      */
     tagField?: string;
+    /** Stream event source mapping config — set via `.stream({...})` builder method. */
+    stream?: TableStreamConfig;
 };
 /**
  * DynamoDB stream record passed to onRecord callback.
@@ -1092,44 +1088,36 @@ type TableHandler$1<T = Record<string, unknown>, C = any> = {
     readonly onRecord?: (...args: any[]) => any;
     readonly onRecordBatch?: (...args: any[]) => any;
 };
-/** Options passed to `defineTable()` — resource config only, no Lambda settings */
+/** Options passed to `defineTable()` — resource config only. Stream options go in `.stream({...})`. */
 type TableOptions<T> = {
     /** DynamoDB billing mode (default: "PAY_PER_REQUEST") */
     billingMode?: "PAY_PER_REQUEST" | "PROVISIONED";
-    /** Stream view type (default: "NEW_AND_OLD_IMAGES") */
-    streamView?: StreamView;
-    /** Number of records to process in each Lambda invocation (1-10000, default: 100) */
-    batchSize?: number;
-    /** Maximum time to gather records before invoking (default: "2s") */
-    batchWindow?: Duration;
-    /** Where to start reading the stream (default: "LATEST") */
-    startingPosition?: "LATEST" | "TRIM_HORIZON";
-    /** Number of records to process concurrently within a batch (default: 1) */
-    concurrency?: number;
     /** Name of the field in `data` that serves as the entity type discriminant (default: "tag") */
     tagField?: Extract<keyof T, string>;
     /** Decode/validate function for the `data` portion of stream records */
     schema?: (input: unknown) => T;
 };
-interface TableBuilder<T = Record<string, unknown>, D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
+interface TableBuilder<T = Record<string, unknown>, D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false, HasStream extends boolean = false> {
     /** Declare handler dependencies (tables, queues, buckets, mailers) */
-    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): TableBuilder<T, D2, P, C, HasFiles>;
+    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): TableBuilder<T, D2, P, C, HasFiles, HasStream>;
     /** Declare SSM secrets */
-    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): TableBuilder<T, D, P2, C, HasFiles>;
+    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): TableBuilder<T, D, P2, C, HasFiles, HasStream>;
     /** Include static files in the Lambda bundle. Chainable — call multiple times. */
-    include(glob: string): TableBuilder<T, D, P, C, true>;
+    include(glob: string): TableBuilder<T, D, P, C, true, HasStream>;
+    /** Configure the DynamoDB stream event source mapping (batch size, retries, concurrency, etc.). */
+    stream: HasStream extends true ? never : (opts: TableStreamConfig) => TableBuilder<T, D, P, C, HasFiles, true>;
     /** Configure Lambda settings only (memory, timeout, permissions, etc.) */
-    setup(lambda: LambdaOptions): TableBuilder<T, D, P, C, HasFiles>;
+    setup(lambda: LambdaOptions): TableBuilder<T, D, P, C, HasFiles, HasStream>;
     /** Initialize shared state on cold start. Receives table (self-client), deps, config, files. */
-    setup<C2>(fn: (args: SetupArgs$3<T, D, P, HasFiles>) => C2 | Promise<C2>): TableBuilder<T, D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$3<T, D, P, HasFiles>) => C2 | Promise<C2>): TableBuilder<T, D, P, C2, HasFiles, HasStream>;
     /** Initialize shared state on cold start + configure Lambda settings. */
-    setup<C2>(fn: (args: SetupArgs$3<T, D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): TableBuilder<T, D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$3<T, D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): TableBuilder<T, D, P, C2, HasFiles, HasStream>;
     /** Handle errors thrown by onRecord/onRecordBatch */
     onError(fn: (args: {
         error: unknown;
-    } & SpreadCtx$3<C>) => void | Promise<void>): TableBuilder<T, D, P, C, HasFiles>;
+    } & SpreadCtx$3<C>) => void | Promise<void>): TableBuilder<T, D, P, C, HasFiles, HasStream>;
     /** Cleanup callback — runs after each invocation, before Lambda freezes */
-    onCleanup(fn: (args: SpreadCtx$3<C>) => void | Promise<void>): TableBuilder<T, D, P, C, HasFiles>;
+    onCleanup(fn: (args: SpreadCtx$3<C>) => void | Promise<void>): TableBuilder<T, D, P, C, HasFiles, HasStream>;
     /** Per-record stream handler (terminal — returns finalized handler) */
     onRecord(fn: TableRecordFn<T, C>): TableHandler$1<T, C>;
     /** Batch stream handler (terminal — returns finalized handler) */
@@ -1144,17 +1132,6 @@ interface TableBuilder<T = Record<string, unknown>, D = undefined, P = undefined
  * `data (M)`, and `ttl (N)` attributes. TTL is always enabled.
  *
  * @see {@link https://effortless-aws.website/use-cases/database | Database guide}
- *
- * @example
- * ```typescript
- * export const orders = defineTable<OrderData>({ batchSize: 10, concurrency: 5 })
- *   .setup(({ table }) => ({ table }))
- *   .onRecord(async ({ record, table }) => {
- *     if (record.eventName === "INSERT") {
- *       console.log("New order:", record.new?.data);
- *     }
- *   })
- * ```
  */
 declare function defineTable<T = Record<string, unknown>>(): TableBuilder<T>;
 declare function defineTable<T = Record<string, unknown>>(options: TableOptions<T>): TableBuilder<T>;
@@ -1509,16 +1486,6 @@ interface ApiBuilder<D = undefined, P = undefined, C = undefined, ST extends boo
  * Define an API with typed routes using a builder pattern.
  *
  * @see {@link https://effortless-aws.website/use-cases/http-api | HTTP API guide}
- *
- * @example
- * ```typescript
- * export const api = defineApi({ basePath: "/api" })
- *   .deps(() => ({ users }))
- *   .config(({ defineSecret }) => ({ authSecret: defineSecret() }))
- *   .auth<Session>(({ config }) => ({ secret: config.authSecret, expiresIn: "1h" }))
- *   .get({ path: "/me" }, async ({ users, auth, ok }) => ok(auth.session))
- *   .post({ path: "/login", public: true }, async ({ auth, ok }) => ok(await auth.createSession()))
- * ```
  */
 declare function defineApi<const O extends ApiOptions>(options: O): ApiBuilder<undefined, undefined, undefined, O["stream"] extends true ? true : false, false>;
 
@@ -1624,19 +1591,7 @@ interface CronBuilder<D = undefined, P = undefined, C = undefined, HasFiles exte
 /**
  * Define a cron job — scheduled Lambda invocation via EventBridge Scheduler.
  *
- * @example
- * ```typescript
- * export const sync = defineCron({ schedule: "cron(0 9 * * ? *)" })
- *   .deps(() => ({ orders }))
- *   .config(({ defineSecret }) => ({ apiKey: defineSecret() }))
- *   .include("templates/*.html")
- *   .setup(async ({ deps, config, files }) => ({
- *     db: deps.orders, key: config.apiKey, tpl: files,
- *   }), { memory: 512 })
- *   .onTick(async ({ db, key, tpl }) => {
- *     const html = tpl.read("templates/report.html")
- *   })
- * ```
+ * @see {@link https://effortless-aws.website/definitions#definecron | Cron reference}
  */
 declare function defineCron(options: CronOptions): CronBuilder;
 
@@ -1892,8 +1847,8 @@ interface McpBuilder<D = undefined, P = undefined, C = undefined, HasFiles exten
  * Creates a Lambda-backed MCP server that exposes tools, resources, and prompts
  * for AI models and MCP-compatible clients via Streamable HTTP (JSON-RPC over POST).
  *
- * @see https://modelcontextprotocol.io/specification/2025-03-26 — MCP specification
- * @see https://effortless-aws.com/use-cases/mcp-server/ — full documentation with examples
+ * @see {@link https://effortless-aws.website/use-cases/mcp-server | MCP Server guide}
+ * @see {@link https://modelcontextprotocol.io/specification/2025-03-26 | MCP specification}
  */
 declare function defineMcp(options: McpOptions): McpBuilder;
 
@@ -1904,10 +1859,10 @@ type McpResourceMap = McpResourceMap$1;
 type McpPromptDef = McpPromptDef$1;
 
 type TableHandler<T = Record<string, unknown>> = TableHandler$1<T, any>;
-type FifoQueueHandler<T = unknown> = FifoQueueHandler$1<T, any>;
+type QueueHandler<T = unknown> = QueueHandler$1<T, any>;
 type BucketHandler<Entities extends Record<string, any> = {}> = BucketHandler$1<any, Entities>;
 type CronHandler = CronHandler$1<any>;
 type WorkerHandler<T = any> = WorkerHandler$1<T, any>;
 type McpHandler = McpHandler$1<any>;
 
-export { type ApiConfig, type ApiHandler, type ApiRoutes, type AppConfig, type AppHandler, type AuthHelpers, type AuthOptions, type BucketClient, type BucketClientWithEntities, type BucketConfig, type BucketEntityConfig, type BucketEvent, type BucketHandler, type CacheOptions, type CdnPolicyOptions, type ConfigHelpers, type ContentType, type CronConfig, type CronHandler, type DefineSecretFn, type Duration, type EffortlessConfig, type EmailClient, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type HttpMethod$1 as HttpMethod, type HttpRequest, type HttpResponse, type LogLevel, type MailerConfig, type MailerHandler, type McpConfig, type McpEntries, type McpHandler, type McpInputSchema, type McpPromptArgument, type McpPromptContent, type McpPromptDef, type McpPromptMessage, type McpPromptResult, type McpResourceContent, type McpResourceDef, type McpResourceMap, type McpResourceTemplateDef, type McpToolContent, type McpToolDef, type McpToolResult, type MiddlewareDeny, type MiddlewareHandler, type MiddlewareRedirect, type MiddlewareRequest, type MiddlewareResult, type ParamRef, type Permission, type PutInput, type PutOptions, type QueryByTagParams, type QueryParams, type QueueClient, type ResponseStream, type SecretRef, type SendEmailOptions, type SendMessageInput, type SkCondition, type StaticFiles, type StaticSiteConfig, type StaticSiteHandler, type StaticSiteSeo, type StoreEntityClient, type StreamView, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type Timezone, type UpdateActions, type WorkerClient, type WorkerConfig, type WorkerHandler, type WorkerSendOptions, defineApi, defineApp, defineBucket, defineConfig, defineCron, defineFifoQueue, defineMailer, defineMcp, defineSecret, defineStaticSite, defineTable, defineWorker, generateBase64, generateHex, generateUuid, param, secret, toSeconds };
+export { type ApiConfig, type ApiHandler, type ApiRoutes, type AppConfig, type AppHandler, type AuthHelpers, type AuthOptions, type BucketClient, type BucketClientWithEntities, type BucketConfig, type BucketEntityConfig, type BucketEvent, type BucketHandler, type CacheOptions, type CdnPolicyOptions, type ConfigHelpers, type ContentType, type CronConfig, type CronHandler, type DefineSecretFn, type Duration, type EffortlessConfig, type EmailClient, type HttpMethod$1 as HttpMethod, type HttpRequest, type HttpResponse, type LogLevel, type MailerConfig, type MailerHandler, type McpConfig, type McpEntries, type McpHandler, type McpInputSchema, type McpPromptArgument, type McpPromptContent, type McpPromptDef, type McpPromptMessage, type McpPromptResult, type McpResourceContent, type McpResourceDef, type McpResourceMap, type McpResourceTemplateDef, type McpToolContent, type McpToolDef, type McpToolResult, type MiddlewareDeny, type MiddlewareHandler, type MiddlewareRedirect, type MiddlewareRequest, type MiddlewareResult, type ParamRef, type Permission, type PutInput, type PutOptions, type QueryByTagParams, type QueryParams, type QueueClient, type QueueConfig, type QueueHandler, type QueueMessage, type QueuePollerConfig, type ResponseStream, type SecretRef, type SendEmailOptions, type SendMessageInput, type SkCondition, type StaticFiles, type StaticSiteConfig, type StaticSiteHandler, type StaticSiteSeo, type StoreEntityClient, type StreamView, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type Timezone, type UpdateActions, type WorkerClient, type WorkerConfig, type WorkerHandler, type WorkerSendOptions, defineApi, defineApp, defineBucket, defineConfig, defineCron, defineMailer, defineMcp, defineQueue, defineSecret, defineStaticSite, defineTable, defineWorker, generateBase64, generateHex, generateUuid, param, secret, toSeconds };

package/dist/index.js

@@ -77,6 +77,10 @@ function defineTable(options) {
       state.static = [...state.static ?? [], glob];
       return builder;
     },
+    stream(opts) {
+      state.spec = { ...state.spec, stream: { ...state.spec.stream, ...opts } };
+      return builder;
+    },
     setup(fnOrLambda, maybeLambda) {
       if (typeof fnOrLambda === "function") {
         state.setup = fnOrLambda;
@@ -143,8 +147,8 @@ function defineStaticSite(options) {
   return builder;
 }
 
-// src/handlers/define-fifo-queue.ts
-function defineFifoQueue(options) {
+// src/handlers/define-queue.ts
+function defineQueue(options) {
   const {
     schema,
     ...queueConfig
@@ -160,7 +164,7 @@ function defineFifoQueue(options) {
     }
   };
   const finalize = () => ({
-    __brand: "effortless-fifo-queue",
+    __brand: "effortless-queue",
     __spec: state.spec,
     ...state.schema ? { schema: state.schema } : {},
     ...state.onError ? { onError: state.onError } : {},
@@ -194,6 +198,12 @@ function defineFifoQueue(options) {
       }
       return builder;
     },
+    poller(options2) {
+      if (Object.keys(options2).length > 0) {
+        state.spec = { ...state.spec, poller: { ...state.spec.poller, ...options2 } };
+      }
+      return builder;
+    },
     onMessage(fn) {
       state.onMessage = fn;
       return finalize();
@@ -209,6 +219,9 @@ function defineFifoQueue(options) {
     onCleanup(fn) {
       state.onCleanup = fn;
       return builder;
+    },
+    build() {
+      return finalize();
     }
   };
   return builder;
@@ -658,9 +671,9 @@ export {
   defineBucket,
   defineConfig,
   defineCron,
-  defineFifoQueue,
   defineMailer,
   defineMcp,
+  defineQueue,
   defineSecret,
   defineStaticSite,
   defineTable,