effortless-aws 0.30.0 → 0.32.0

package/dist/index.d.ts

@@ -1,17 +1,7 @@
 /**
  * Configuration for an Effortless project.
  *
- * @example
- * ```typescript
- * // effortless.config.ts
- * import { defineConfig } from "effortless-aws";
- *
- * export default defineConfig({
- *   name: "my-service",
- *   region: "eu-central-1",
- *   handlers: "src",
- * });
- * ```
+ * @see {@link https://effortless-aws.website/configuration | Configuration guide}
  */
 type EffortlessConfig = {
     /**
@@ -78,21 +68,7 @@ type EffortlessConfig = {
         runtime?: string;
     };
 };
-/**
- * Helper function for type-safe configuration.
- * Returns the config object as-is, but provides TypeScript autocompletion.
- *
- * @example
- * ```typescript
- * import { defineConfig } from "effortless-aws";
- *
- * export default defineConfig({
- *   name: "my-service",
- *   region: "eu-central-1",
- *   handlers: "src",
- * });
- * ```
- */
+/** Helper function for type-safe configuration with TypeScript autocompletion. */
 declare const defineConfig: (config: EffortlessConfig) => EffortlessConfig;
 
 /** Generator spec for auto-creating secrets at deploy time. */
@@ -136,6 +112,20 @@ type LambdaWithPermissions = LambdaConfig & {
     /** Additional IAM permissions for the Lambda */
     permissions?: Permission[];
 };
+/**
+ * Lambda configuration passed as argument to `.setup()`.
+ * Common across all handler types that create a Lambda function.
+ */
+type LambdaOptions = {
+    /** Lambda memory in MB (default: 256) */
+    memory?: number;
+    /** Lambda timeout (default: 30s). Accepts seconds or duration string: `"30s"`, `"5m"` */
+    timeout?: Duration;
+    /** Additional IAM permissions for the Lambda */
+    permissions?: Permission[];
+    /** Logging verbosity: "error" (errors only), "info" (+ execution summary), "debug" (+ input/output). Default: "info" */
+    logLevel?: LogLevel;
+};
 type AnySecretRef = SecretRef<any>;
 /**
  * Reference to an SSM Parameter Store secret.
@@ -236,22 +226,6 @@ type PutInput<T> = {
     data: T;
     ttl?: number;
 };
-/**
- * Create a schema function that casts input to T without runtime validation.
- * Use when you need T inference alongside other generics (deps, config).
- * For handlers without deps/config, prefer `defineTable<Order>({...})`.
- * For untrusted input, prefer a real parser (Zod, Effect Schema).
- *
- * @example
- * ```typescript
- * export const orders = defineTable({
- *   schema: unsafeAs<Order>(),
- *   deps: () => ({ notifications }),
- *   onRecord: async ({ record, deps }) => { ... }
- * });
- * ```
- */
-declare function unsafeAs<T>(): (input: unknown) => T;
 
 /** HTTP methods supported by Lambda Function URLs */
 type HttpMethod$1 = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ANY";
@@ -387,9 +361,9 @@ type BucketEvent = {
     bucketName: string;
 };
 /** Spread ctx into callback args (empty when no setup) */
-type SpreadCtx$3<C> = [C] extends [undefined] ? {} : C & {};
+type SpreadCtx$5<C> = [C] extends [undefined] ? {} : C & {};
 /** Setup factory — receives bucket/deps/config/files based on what was declared */
-type SetupArgs$3<D, P, HasFiles extends boolean> = {
+type SetupArgs$5<D, P, HasFiles extends boolean> = {
     bucket: BucketClient;
 } & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
@@ -403,13 +377,13 @@ type SetupArgs$3<D, P, HasFiles extends boolean> = {
  */
 type BucketObjectCreatedFn<C = undefined> = (args: {
     event: BucketEvent;
-} & SpreadCtx$3<C>) => Promise<void>;
+} & SpreadCtx$5<C>) => Promise<void>;
 /**
  * Callback function type for S3 ObjectRemoved events
  */
 type BucketObjectRemovedFn<C = undefined> = (args: {
     event: BucketEvent;
-} & SpreadCtx$3<C>) => Promise<void>;
+} & SpreadCtx$5<C>) => Promise<void>;
 /**
  * Internal handler object created by defineBucket
  * @internal
@@ -428,34 +402,30 @@ type BucketHandler<C = any> = {
 };
 /** Options passed to `defineBucket()` — static config */
 type BucketOptions = {
-    /** Lambda memory in MB (default: 256) */
-    memory?: number;
-    /** Lambda timeout (default: 30s) */
-    timeout?: Duration;
-    /** Additional IAM permissions for the Lambda */
-    permissions?: Permission[];
-    /** Logging verbosity */
-    logLevel?: LogLevel;
     /** S3 key prefix filter for event notifications (e.g., "uploads/") */
     prefix?: string;
     /** S3 key suffix filter for event notifications (e.g., ".jpg") */
     suffix?: string;
-    /** Static file glob patterns to bundle into the Lambda ZIP */
-    static?: string[];
 };
 interface BucketBuilder<D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
     /** Declare handler dependencies */
     deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): BucketBuilder<D2, P, C, HasFiles>;
     /** Declare SSM secrets */
     config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): BucketBuilder<D, P2, C, HasFiles>;
+    /** Include static files in the Lambda ZIP */
+    include(glob: string): BucketBuilder<D, P, C, true>;
+    /** Initialize shared state on cold start with lambda options */
+    setup(lambda: LambdaOptions): BucketBuilder<D, P, C, HasFiles>;
     /** Initialize shared state on cold start. Receives bucket (self-client), deps, config, files. */
-    setup<C2>(fn: (args: SetupArgs$3<D, P, HasFiles>) => C2 | Promise<C2>): BucketBuilder<D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$5<D, P, HasFiles>) => C2 | Promise<C2>): BucketBuilder<D, P, C2, HasFiles>;
+    /** Initialize shared state on cold start with lambda options. Receives bucket (self-client), deps, config, files. */
+    setup<C2>(fn: (args: SetupArgs$5<D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): BucketBuilder<D, P, C2, HasFiles>;
     /** Handle errors thrown by callbacks */
     onError(fn: (args: {
         error: unknown;
-    } & SpreadCtx$3<C>) => void): BucketBuilder<D, P, C, HasFiles>;
+    } & SpreadCtx$5<C>) => void | Promise<void>): BucketBuilder<D, P, C, HasFiles>;
     /** Cleanup callback — runs after each invocation, before Lambda freezes */
-    onCleanup(fn: (args: SpreadCtx$3<C>) => void | Promise<void>): BucketBuilder<D, P, C, HasFiles>;
+    onCleanup(fn: (args: SpreadCtx$5<C>) => void | Promise<void>): BucketBuilder<D, P, C, HasFiles>;
     /** Handle S3 ObjectCreated events (terminal — returns finalized handler) */
     onObjectCreated(fn: BucketObjectCreatedFn<C>): BucketHandler<C>;
     /** Handle S3 ObjectRemoved events (terminal — returns finalized handler) */
@@ -466,24 +436,17 @@ interface BucketBuilder<D = undefined, P = undefined, C = undefined, HasFiles ex
 /**
  * Define an S3 bucket with optional event handlers.
  *
- * @example Bucket with event handler
+ * @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);
  *   })
- *
- * ```
- *
- * @example Resource-only bucket (no Lambda)
- * ```typescript
- * export const assets = defineBucket().build()
  * ```
  */
 declare function defineBucket(): BucketBuilder;
-declare function defineBucket(options: BucketOptions & {
-    static: string[];
-}): BucketBuilder<undefined, undefined, undefined, true>;
 declare function defineBucket(options: BucketOptions): BucketBuilder;
 
 /**
@@ -510,6 +473,8 @@ type MailerHandler = {
  * On first deploy, DKIM DNS records are printed to the console.
  * 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
  *
@@ -591,9 +556,9 @@ type FifoQueueConfig = {
     maxReceiveCount?: number;
 };
 /** Spread ctx into callback args (empty when no setup) */
-type SpreadCtx$2<C> = [C] extends [undefined] ? {} : C & {};
+type SpreadCtx$4<C> = [C] extends [undefined] ? {} : C & {};
 /** Setup factory — receives deps/config/files based on what was declared */
-type SetupArgs$2<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} : {
+type SetupArgs$4<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
     config: ResolveConfig<P & {}>;
@@ -606,7 +571,7 @@ type SetupArgs$2<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {}
  */
 type FifoQueueMessageFn<T = unknown, C = undefined> = (args: {
     message: FifoQueueMessage<T>;
-} & SpreadCtx$2<C>) => Promise<void>;
+} & SpreadCtx$4<C>) => Promise<void>;
 /**
  * Batch handler function.
  * Called once with all messages in the batch.
@@ -614,7 +579,7 @@ type FifoQueueMessageFn<T = unknown, C = undefined> = (args: {
  */
 type FifoQueueBatchFn<T = unknown, C = undefined> = (args: {
     messages: FifoQueueMessage<T>[];
-} & SpreadCtx$2<C>) => Promise<void | {
+} & SpreadCtx$4<C>) => Promise<void | {
     failures: string[];
 }>;
 /**
@@ -636,14 +601,6 @@ type FifoQueueHandler<T = unknown, C = any> = {
 };
 /** Options passed to `defineFifoQueue()` — static config */
 type FifoQueueOptions<T> = {
-    /** Lambda memory in MB (default: 256) */
-    memory?: number;
-    /** Lambda timeout (default: 30s) */
-    timeout?: Duration;
-    /** Additional IAM permissions for the Lambda */
-    permissions?: Permission[];
-    /** Logging verbosity */
-    logLevel?: LogLevel;
     /** Number of messages per Lambda invocation (1-10 for FIFO, default: 10) */
     batchSize?: number;
     /** Maximum time to gather messages before invoking (default: 0) */
@@ -660,22 +617,26 @@ type FifoQueueOptions<T> = {
     maxReceiveCount?: number;
     /** Decode/validate function for the message body */
     schema?: (input: unknown) => T;
-    /** Static file glob patterns to bundle into the Lambda ZIP */
-    static?: string[];
 };
 interface FifoQueueBuilder<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>;
     /** Declare SSM secrets */
     config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): FifoQueueBuilder<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>;
+    /** Configure Lambda settings only (memory, timeout, permissions, etc.) */
+    setup(lambda: LambdaOptions): FifoQueueBuilder<T, D, P, C, HasFiles>;
     /** Initialize shared state on cold start. Receives deps, config, files. */
-    setup<C2>(fn: (args: SetupArgs$2<D, P, HasFiles>) => C2 | Promise<C2>): FifoQueueBuilder<T, D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$4<D, P, HasFiles>) => C2 | Promise<C2>): FifoQueueBuilder<T, D, P, C2, HasFiles>;
+    /** Initialize shared state on cold start + configure Lambda settings. */
+    setup<C2>(fn: (args: SetupArgs$4<D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): FifoQueueBuilder<T, D, P, C2, HasFiles>;
     /** Handle errors thrown by message handlers */
     onError(fn: (args: {
         error: unknown;
-    } & SpreadCtx$2<C>) => void): FifoQueueBuilder<T, D, P, C, HasFiles>;
+    } & SpreadCtx$4<C>) => void | Promise<void>): FifoQueueBuilder<T, D, P, C, HasFiles>;
     /** Cleanup callback — runs after each invocation, before Lambda freezes */
-    onCleanup(fn: (args: SpreadCtx$2<C>) => void | Promise<void>): FifoQueueBuilder<T, D, P, C, HasFiles>;
+    onCleanup(fn: (args: SpreadCtx$4<C>) => void | Promise<void>): FifoQueueBuilder<T, D, P, C, HasFiles>;
     /** Per-message handler (terminal — returns finalized handler) */
     onMessage(fn: FifoQueueMessageFn<T, C>): FifoQueueHandler<T, C>;
     /** Batch handler (terminal — returns finalized handler) */
@@ -684,30 +645,115 @@ interface FifoQueueBuilder<T = unknown, D = undefined, P = undefined, C = undefi
 /**
  * Define a FIFO SQS queue with a Lambda message handler.
  *
- * @example Per-message processing
- * ```typescript
- * export const orderQueue = defineFifoQueue<OrderEvent>()
- *   .onMessage(async ({ message }) => {
- *     console.log("Processing order:", message.body.orderId);
- *   })
- *
- * ```
+ * @see {@link https://effortless-aws.website/use-cases/queue | Queue guide}
  *
- * @example Batch processing with schema
+ * @example
  * ```typescript
  * export const notifications = defineFifoQueue({ batchSize: 5, schema: (i) => NotifSchema.parse(i) })
  *   .onMessageBatch(async ({ messages }) => {
  *     await sendAll(messages.map(m => m.body));
  *   })
- *
  * ```
  */
 declare function defineFifoQueue<T = unknown>(): FifoQueueBuilder<T>;
-declare function defineFifoQueue<T = unknown>(options: FifoQueueOptions<T> & {
-    static: string[];
-}): FifoQueueBuilder<T, undefined, undefined, undefined, true>;
 declare function defineFifoQueue<T = unknown>(options: FifoQueueOptions<T>): FifoQueueBuilder<T>;
 
+/** Fargate container size presets */
+type FargateSize = "0.25vCPU-512mb" | "0.5vCPU-1gb" | "1vCPU-2gb" | "2vCPU-4gb" | "4vCPU-8gb";
+/** Static config extracted at deploy time */
+type WorkerConfig = {
+    /** Lambda function settings (memory, timeout, permissions, etc.) */
+    lambda?: LambdaWithPermissions;
+    /** Fargate size (default: "0.5vCPU-1gb") */
+    size?: FargateSize;
+    /** How long the worker stays alive without messages before shutting down (default: "5m") */
+    idleTimeout?: Duration;
+    /** Max messages processed in parallel (default: 1, max: 10) */
+    concurrency?: number;
+};
+/** Setup factory — receives deps/config/files based on what was declared */
+type SetupArgs$3<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P & {}>;
+}) & (HasFiles extends true ? {
+    files: StaticFiles;
+} : {});
+/** Spread ctx into callback args (empty when no setup) */
+type SpreadCtx$3<C> = [C] extends [undefined] ? {} : C & {};
+/** Callback function for the worker's onMessage */
+type WorkerMessageFn<T, C = undefined> = (msg: T, ctx: SpreadCtx$3<C>) => Promise<void> | void;
+/**
+ * Handler object created by defineWorker.
+ * @internal
+ */
+type WorkerHandler<T = any, C = any> = {
+    readonly __brand: "effortless-worker";
+    readonly __spec: WorkerConfig;
+    readonly onError?: (...args: any[]) => any;
+    readonly onCleanup?: (...args: any[]) => any;
+    readonly setup?: (...args: any[]) => C | Promise<C>;
+    readonly deps?: Record<string, unknown> | (() => Record<string, unknown>);
+    readonly config?: Record<string, unknown>;
+    readonly static?: string[];
+    readonly onMessage?: (...args: any[]) => any;
+};
+/** Options passed to `defineWorker()` — resource config only */
+type WorkerOptions = {
+    /** Fargate size (default: "0.5vCPU-1gb") */
+    size?: FargateSize;
+    /** How long the worker stays alive without messages before shutting down (default: "5m") */
+    idleTimeout?: Duration;
+    /** Max messages processed in parallel (default: 1, max: 10) */
+    concurrency?: number;
+};
+interface WorkerBuilder<T, D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
+    /** Declare handler dependencies (tables, queues, buckets, mailers, workers) */
+    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): WorkerBuilder<T, D2, P, C, HasFiles>;
+    /** Declare SSM secrets */
+    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): WorkerBuilder<T, D, P2, C, HasFiles>;
+    /** Include static files in the bundle. Chainable — call multiple times. */
+    include(glob: string): WorkerBuilder<T, D, P, C, true>;
+    /** Configure Lambda settings only (memory, timeout, permissions, logLevel) */
+    setup(lambda: LambdaOptions): WorkerBuilder<T, D, P, C, HasFiles>;
+    /** Initialize shared state on cold start. Receives deps, config, files. */
+    setup<C2>(fn: (args: SetupArgs$3<D, P, HasFiles>) => C2 | Promise<C2>): WorkerBuilder<T, D, P, C2, HasFiles>;
+    /** Initialize shared state on cold start + configure Lambda settings. */
+    setup<C2>(fn: (args: SetupArgs$3<D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): WorkerBuilder<T, D, P, C2, HasFiles>;
+    /** Handle errors thrown by onMessage. Return "delete" to discard, "retry" to reprocess (default). */
+    onError(fn: (args: {
+        error: unknown;
+        msg: T;
+        retryCount: number;
+    } & SpreadCtx$3<C>) => "retry" | "delete" | void | Promise<"retry" | "delete" | void>): WorkerBuilder<T, D, P, C, HasFiles>;
+    /** Cleanup callback — runs when the worker shuts down */
+    onCleanup(fn: (args: SpreadCtx$3<C>) => void | Promise<void>): WorkerBuilder<T, D, P, C, HasFiles>;
+    /** Process a single message from the queue (terminal) */
+    onMessage(fn: WorkerMessageFn<T, C>): WorkerHandler<T, C>;
+}
+/**
+ * Define a worker — a long-running Fargate container with an SQS queue.
+ *
+ * The worker stays alive while processing messages and shuts down after
+ * an idle timeout with no new messages. Other handlers can send messages
+ * to the worker via `deps.worker.send(msg)`.
+ *
+ * @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)
+ *   })
+ * ```
+ */
+declare function defineWorker<T = unknown>(options?: WorkerOptions): WorkerBuilder<T>;
+
 /**
  * Sort key condition for TableClient.query()
  */
@@ -872,11 +918,27 @@ type QueueClient<T = unknown> = {
     queueName: string;
 };
 
+/** Options for sending a message to a worker */
+type WorkerSendOptions = {
+    /** Delay before the message becomes visible in the queue (max "15m") */
+    delay?: Duration;
+    /** Whether to start the worker container (default: true) */
+    start?: boolean;
+};
+type WorkerClient<T = unknown> = {
+    /** Send a message to the worker's queue. Wakes up the worker by default. */
+    send(msg: T, options?: WorkerSendOptions): Promise<void>;
+    /** Check if the worker is currently running */
+    status(): Promise<"running" | "idle">;
+    /** Stop the worker (scale ECS service to 0) */
+    stop(): Promise<void>;
+};
+
 /** Dep value types supported by the deps declaration */
-type AnyDepHandler = TableHandler<any, any> | BucketHandler<any> | MailerHandler | FifoQueueHandler<any, any>;
+type AnyDepHandler = TableHandler<any, any> | BucketHandler<any> | MailerHandler | FifoQueueHandler<any, any> | WorkerHandler<any, any>;
 /** Maps a deps declaration to resolved runtime client types */
 type ResolveDeps<D> = {
-    [K in keyof D]: D[K] extends TableHandler<infer T> ? TableClient<T> : D[K] extends BucketHandler ? BucketClient : D[K] extends MailerHandler ? EmailClient : D[K] extends FifoQueueHandler<infer T> ? QueueClient<T> : never;
+    [K in keyof D]: D[K] extends TableHandler<infer T> ? TableClient<T> : D[K] extends BucketHandler ? BucketClient : D[K] extends MailerHandler ? EmailClient : D[K] extends FifoQueueHandler<infer T> ? QueueClient<T> : D[K] extends WorkerHandler<infer T> ? WorkerClient<T> : never;
 };
 
 /** DynamoDB Streams view type - determines what data is captured in stream records */
@@ -939,7 +1001,7 @@ type TableRecord<T = Record<string, unknown>> = {
     timestamp?: number;
 };
 /** Setup factory — receives table/deps/config/files based on what was declared */
-type SetupArgs$1<T, D, P, HasFiles extends boolean> = {
+type SetupArgs$2<T, D, P, HasFiles extends boolean> = {
     table: TableClient<T>;
 } & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
@@ -949,7 +1011,7 @@ type SetupArgs$1<T, D, P, HasFiles extends boolean> = {
     files: StaticFiles;
 } : {});
 /** Spread ctx into callback args (empty when no setup) */
-type SpreadCtx$1<C> = [C] extends [undefined] ? {} : C & {};
+type SpreadCtx$2<C> = [C] extends [undefined] ? {} : C & {};
 /**
  * Callback function type for processing a single DynamoDB stream record.
  * Receives the current record and the full batch for context.
@@ -957,7 +1019,7 @@ type SpreadCtx$1<C> = [C] extends [undefined] ? {} : C & {};
 type TableRecordFn<T = Record<string, unknown>, C = undefined> = (args: {
     record: TableRecord<T>;
     batch: readonly TableRecord<T>[];
-} & SpreadCtx$1<C>) => Promise<void>;
+} & SpreadCtx$2<C>) => Promise<void>;
 /**
  * Batch handler function for DynamoDB stream records.
  * Called once with all records in the batch.
@@ -965,7 +1027,7 @@ type TableRecordFn<T = Record<string, unknown>, C = undefined> = (args: {
  */
 type TableBatchFn<T = Record<string, unknown>, C = undefined> = (args: {
     records: readonly TableRecord<T>[];
-} & SpreadCtx$1<C>) => Promise<void | {
+} & SpreadCtx$2<C>) => Promise<void | {
     failures: string[];
 }>;
 /** Static config extracted by AST (no runtime callbacks) */
@@ -987,16 +1049,8 @@ type TableHandler<T = Record<string, unknown>, C = any> = {
     readonly onRecord?: (...args: any[]) => any;
     readonly onRecordBatch?: (...args: any[]) => any;
 };
-/** Options passed to `defineTable()` — static config, no generics needed for inference */
+/** Options passed to `defineTable()` — resource config only, no Lambda settings */
 type TableOptions<T> = {
-    /** Lambda memory in MB (default: 256) */
-    memory?: number;
-    /** Lambda timeout (default: 30s). Accepts seconds or duration string: `"30s"`, `"5m"` */
-    timeout?: Duration;
-    /** Additional IAM permissions for the Lambda */
-    permissions?: Permission[];
-    /** Logging verbosity */
-    logLevel?: LogLevel;
     /** DynamoDB billing mode (default: "PAY_PER_REQUEST") */
     billingMode?: "PAY_PER_REQUEST" | "PROVISIONED";
     /** Stream view type (default: "NEW_AND_OLD_IMAGES") */
@@ -1013,22 +1067,26 @@ type TableOptions<T> = {
     tagField?: Extract<keyof T, string>;
     /** Decode/validate function for the `data` portion of stream records */
     schema?: (input: unknown) => T;
-    /** Static file glob patterns to bundle into the Lambda ZIP */
-    static?: string[];
 };
 interface TableBuilder<T = Record<string, unknown>, D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
     /** Declare handler dependencies (tables, queues, buckets, mailers) */
     deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): TableBuilder<T, D2, P, C, HasFiles>;
     /** Declare SSM secrets */
     config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): TableBuilder<T, D, P2, C, HasFiles>;
+    /** Include static files in the Lambda bundle. Chainable — call multiple times. */
+    include(glob: string): TableBuilder<T, D, P, C, true>;
+    /** Configure Lambda settings only (memory, timeout, permissions, etc.) */
+    setup(lambda: LambdaOptions): TableBuilder<T, D, P, C, HasFiles>;
     /** Initialize shared state on cold start. Receives table (self-client), deps, config, files. */
-    setup<C2>(fn: (args: SetupArgs$1<T, D, P, HasFiles>) => C2 | Promise<C2>): TableBuilder<T, D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$2<T, D, P, HasFiles>) => C2 | Promise<C2>): TableBuilder<T, D, P, C2, HasFiles>;
+    /** Initialize shared state on cold start + configure Lambda settings. */
+    setup<C2>(fn: (args: SetupArgs$2<T, D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): TableBuilder<T, D, P, C2, HasFiles>;
     /** Handle errors thrown by onRecord/onRecordBatch */
     onError(fn: (args: {
         error: unknown;
-    } & SpreadCtx$1<C>) => void): TableBuilder<T, D, P, C, HasFiles>;
+    } & SpreadCtx$2<C>) => void | Promise<void>): TableBuilder<T, D, P, C, HasFiles>;
     /** Cleanup callback — runs after each invocation, before Lambda freezes */
-    onCleanup(fn: (args: SpreadCtx$1<C>) => void | Promise<void>): TableBuilder<T, D, P, C, HasFiles>;
+    onCleanup(fn: (args: SpreadCtx$2<C>) => void | Promise<void>): TableBuilder<T, D, P, C, HasFiles>;
     /** Per-record stream handler (terminal — returns finalized handler) */
     onRecord(fn: TableRecordFn<T, C>): TableHandler<T, C>;
     /** Batch stream handler (terminal — returns finalized handler) */
@@ -1042,7 +1100,9 @@ interface TableBuilder<T = Record<string, unknown>, D = undefined, P = undefined
  * Creates a table with fixed key schema: `pk (S)` + `sk (S)`, plus `tag (S)`,
  * `data (M)`, and `ttl (N)` attributes. TTL is always enabled.
  *
- * @example Table with stream handler
+ * @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 }))
@@ -1052,21 +1112,8 @@ interface TableBuilder<T = Record<string, unknown>, D = undefined, P = undefined
  *     }
  *   })
  * ```
- *
- * @example Table only (no Lambda)
- * ```typescript
- * export const users = defineTable<User>().build()
- * ```
- *
- * @example Table as dependency (resource-only, no Lambda)
- * ```typescript
- * export const sessions = defineTable<Session>().build()
- * ```
  */
 declare function defineTable<T = Record<string, unknown>>(): TableBuilder<T>;
-declare function defineTable<T = Record<string, unknown>>(options: TableOptions<T> & {
-    static: string[];
-}): TableBuilder<T, undefined, undefined, undefined, true>;
 declare function defineTable<T = Record<string, unknown>>(options: TableOptions<T>): TableBuilder<T>;
 
 /**
@@ -1111,18 +1158,10 @@ type AppHandler = {
  *
  * For static-only sites (no SSR), use {@link defineStaticSite} instead.
  *
+ * @see {@link https://effortless-aws.website/use-cases/web-app | Web app guide}
+ *
  * @param options - App configuration: server directory, assets directory, optional build command
  * @returns Handler object used by the deployment system
- *
- * @example Nuxt SSR
- * ```typescript
- * export const app = defineApp({
- *   build: "nuxt build",
- *   server: ".output/server",
- *   assets: ".output/public",
- *   lambda: { memory: 1024 },
- * });
- * ```
  */
 declare const defineApp: () => (options: AppConfig) => AppHandler;
 
@@ -1199,26 +1238,10 @@ type StaticSiteHandler = {
 /**
  * Deploy a static site via S3 + CloudFront CDN.
  *
+ * @see {@link https://effortless-aws.website/use-cases/web-app | Web app guide}
+ *
  * @param options - Static site configuration: directory, optional SPA mode, build command
  * @returns Handler object used by the deployment system
- *
- * @example Documentation site
- * ```typescript
- * export const docs = defineStaticSite({
- *   dir: "dist",
- *   build: "npx astro build",
- * });
- * ```
- *
- * @example SPA with client-side routing
- * ```typescript
- * export const app = defineStaticSite({
- *   dir: "dist",
- *   spa: true,
- *   build: "npm run build",
- * });
- * ```
- *
  */
 declare const defineStaticSite: () => (options: StaticSiteConfig) => StaticSiteHandler;
 
@@ -1294,11 +1317,11 @@ type RouteEntry = {
     public?: boolean;
 };
 /** Spread ctx into route args: Omit auth config, add AuthHelpers if present */
-type SpreadCtx<C> = ([C] extends [undefined] ? {} : Omit<C & {}, 'auth'>) & ([ExtractAuth<C>] extends [undefined] ? {} : {
+type SpreadCtx$1<C> = ([C] extends [undefined] ? {} : Omit<C & {}, 'auth'>) & ([ExtractAuth<C>] extends [undefined] ? {} : {
     auth: AuthHelpers<ExtractAuth<C>>;
 });
 /** Callback args available inside each route — ctx is spread into args */
-type RouteArgs<C, ST> = SpreadCtx<C> & {
+type RouteArgs<C, ST> = SpreadCtx$1<C> & {
     req: HttpRequest;
     input: unknown;
     ok: OkHelper;
@@ -1313,7 +1336,7 @@ type RouteOptions = {
     public?: boolean;
 };
 /** Setup factory — receives deps/config/files/enableAuth based on what was declared */
-type SetupArgs<D, P, HasFiles extends boolean> = {
+type SetupArgs$1<D, P, HasFiles extends boolean> = {
     enableAuth: EnableAuth;
     ok: OkHelper;
     fail: FailHelper;
@@ -1341,7 +1364,7 @@ type ApiConfig = {
 type ApiHandler<C = undefined> = {
     readonly __brand: "effortless-api";
     readonly __spec: ApiConfig;
-    readonly onError?: (...args: any[]) => any;
+    readonly onError?: (...args: any[]) => any | Promise<any>;
     readonly onCleanup?: (...args: any[]) => any;
     readonly setup?: (...args: any[]) => C | Promise<C>;
     readonly deps?: Record<string, unknown> | (() => Record<string, unknown>);
@@ -1353,18 +1376,8 @@ type ApiHandler<C = undefined> = {
 type ApiOptions = {
     /** Base path prefix for all routes (e.g., "/api") */
     basePath: `/${string}`;
-    /** Lambda memory in MB (default: 256) */
-    memory?: number;
-    /** Lambda timeout (default: 30s). Accepts seconds or duration string: `"30s"`, `"5m"` */
-    timeout?: Duration;
-    /** Additional IAM permissions for the Lambda */
-    permissions?: Permission[];
-    /** Logging verbosity: "error" (errors only), "info" (+ execution summary), "debug" (+ input/output). Default: "info" */
-    logLevel?: LogLevel;
     /** Enable response streaming. When true, routes receive a `stream` arg for SSE. */
     stream?: boolean;
-    /** Static file glob patterns to bundle into the Lambda ZIP */
-    static?: string[];
 };
 /**
  * Finalized API handler with route-adding methods.
@@ -1388,17 +1401,23 @@ interface ApiBuilder<D = undefined, P = undefined, C = undefined, ST extends boo
     deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): ApiBuilder<D2, P, C, ST, HasFiles>;
     /** Declare SSM secrets */
     config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): ApiBuilder<D, P2, C, ST, HasFiles>;
+    /** Include static files by glob pattern */
+    include(glob: string): ApiBuilder<D, P, C, ST, true>;
+    /** Configure Lambda settings only (no init function) */
+    setup(lambda: LambdaOptions): ApiBuilder<D, P, C, ST, HasFiles>;
     /** Initialize shared state on cold start. Receives deps/config/files based on what was declared. */
-    setup<C2>(fn: (args: SetupArgs<D, P, HasFiles>) => ValidateSetupReturn<C2> | Promise<ValidateSetupReturn<C2>>): ApiBuilder<D, P, C2, ST, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$1<D, P, HasFiles>) => ValidateSetupReturn<C2> | Promise<ValidateSetupReturn<C2>>): ApiBuilder<D, P, C2, ST, HasFiles>;
+    /** Initialize shared state on cold start with Lambda config. */
+    setup<C2>(fn: (args: SetupArgs$1<D, P, HasFiles>) => ValidateSetupReturn<C2> | Promise<ValidateSetupReturn<C2>>, lambda: LambdaOptions): ApiBuilder<D, P, C2, ST, HasFiles>;
     /** Handle errors thrown by routes */
     onError(fn: (args: {
         error: unknown;
         req: HttpRequest;
         ok: OkHelper;
         fail: FailHelper;
-    } & SpreadCtx<C>) => HttpResponse): ApiBuilder<D, P, C, ST, HasFiles>;
+    } & SpreadCtx$1<C>) => HttpResponse | Promise<HttpResponse>): ApiBuilder<D, P, C, ST, HasFiles>;
     /** Cleanup callback — runs after each invocation, before Lambda freezes */
-    onCleanup(fn: (args: SpreadCtx<C>) => void | Promise<void>): ApiBuilder<D, P, C, ST, HasFiles>;
+    onCleanup(fn: (args: SpreadCtx$1<C>) => void | Promise<void>): ApiBuilder<D, P, C, ST, HasFiles>;
     /** Add a GET route (terminal — returns finalized handler with route methods) */
     get(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
     /** Add a POST route (terminal) */
@@ -1413,13 +1432,10 @@ 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
- * // Minimal
- * export default defineApi({ basePath: "/hello" })
- *   .get("/", async ({ req, ok }) => ok({ message: "Hello!" }))
- *
- * // Full
  * export const api = defineApi({ basePath: "/api", timeout: "30s" })
  *   .deps(() => ({ users }))
  *   .config(({ defineSecret }) => ({ dbUrl: defineSecret() }))
@@ -1432,9 +1448,124 @@ interface ApiBuilder<D = undefined, P = undefined, C = undefined, ST extends boo
  *   .post("/login", async ({ auth, ok }) => ok(await auth.createSession()), { public: true })
  * ```
  */
-declare function defineApi(options: ApiOptions & {
-    static: string[];
-}): ApiBuilder<undefined, undefined, undefined, false, true>;
-declare function defineApi<const O extends ApiOptions>(options: O): ApiBuilder<undefined, undefined, undefined, O["stream"] extends true ? true : false, O["static"] extends string[] ? true : false>;
+declare function defineApi<const O extends ApiOptions>(options: O): ApiBuilder<undefined, undefined, undefined, O["stream"] extends true ? true : false, false>;
+
+/**
+ * All IANA time zones.
+ * Generated from Intl.supportedValuesOf("timeZone") on Node.js 22.
+ */
+type Timezone = "UTC" | "Africa/Abidjan" | "Africa/Accra" | "Africa/Addis_Ababa" | "Africa/Algiers" | "Africa/Asmera" | "Africa/Bamako" | "Africa/Bangui" | "Africa/Banjul" | "Africa/Bissau" | "Africa/Blantyre" | "Africa/Brazzaville" | "Africa/Bujumbura" | "Africa/Cairo" | "Africa/Casablanca" | "Africa/Ceuta" | "Africa/Conakry" | "Africa/Dakar" | "Africa/Dar_es_Salaam" | "Africa/Djibouti" | "Africa/Douala" | "Africa/El_Aaiun" | "Africa/Freetown" | "Africa/Gaborone" | "Africa/Harare" | "Africa/Johannesburg" | "Africa/Juba" | "Africa/Kampala" | "Africa/Khartoum" | "Africa/Kigali" | "Africa/Kinshasa" | "Africa/Lagos" | "Africa/Libreville" | "Africa/Lome" | "Africa/Luanda" | "Africa/Lubumbashi" | "Africa/Lusaka" | "Africa/Malabo" | "Africa/Maputo" | "Africa/Maseru" | "Africa/Mbabane" | "Africa/Mogadishu" | "Africa/Monrovia" | "Africa/Nairobi" | "Africa/Ndjamena" | "Africa/Niamey" | "Africa/Nouakchott" | "Africa/Ouagadougou" | "Africa/Porto-Novo" | "Africa/Sao_Tome" | "Africa/Tripoli" | "Africa/Tunis" | "Africa/Windhoek" | "America/Adak" | "America/Anchorage" | "America/Anguilla" | "America/Antigua" | "America/Araguaina" | "America/Argentina/La_Rioja" | "America/Argentina/Rio_Gallegos" | "America/Argentina/Salta" | "America/Argentina/San_Juan" | "America/Argentina/San_Luis" | "America/Argentina/Tucuman" | "America/Argentina/Ushuaia" | "America/Aruba" | "America/Asuncion" | "America/Bahia" | "America/Bahia_Banderas" | "America/Barbados" | "America/Belem" | "America/Belize" | "America/Blanc-Sablon" | "America/Boa_Vista" | "America/Bogota" | "America/Boise" | "America/Buenos_Aires" | "America/Cambridge_Bay" | "America/Campo_Grande" | "America/Cancun" | "America/Caracas" | "America/Catamarca" | "America/Cayenne" | "America/Cayman" | "America/Chicago" | "America/Chihuahua" | "America/Ciudad_Juarez" | "America/Coral_Harbour" | "America/Cordoba" | "America/Costa_Rica" | "America/Coyhaique" | "America/Creston" | "America/Cuiaba" | "America/Curacao" | "America/Danmarkshavn" | "America/Dawson" | "America/Dawson_Creek" | "America/Denver" | "America/Detroit" | "America/Dominica" | "America/Edmonton" | "America/Eirunepe" | "America/El_Salvador" | "America/Fort_Nelson" | "America/Fortaleza" | "America/Glace_Bay" | "America/Godthab" | "America/Goose_Bay" | "America/Grand_Turk" | "America/Grenada" | "America/Guadeloupe" | "America/Guatemala" | "America/Guayaquil" | "America/Guyana" | "America/Halifax" | "America/Havana" | "America/Hermosillo" | "America/Indiana/Knox" | "America/Indiana/Marengo" | "America/Indiana/Petersburg" | "America/Indiana/Tell_City" | "America/Indiana/Vevay" | "America/Indiana/Vincennes" | "America/Indiana/Winamac" | "America/Indianapolis" | "America/Inuvik" | "America/Iqaluit" | "America/Jamaica" | "America/Jujuy" | "America/Juneau" | "America/Kentucky/Monticello" | "America/Kralendijk" | "America/La_Paz" | "America/Lima" | "America/Los_Angeles" | "America/Louisville" | "America/Lower_Princes" | "America/Maceio" | "America/Managua" | "America/Manaus" | "America/Marigot" | "America/Martinique" | "America/Matamoros" | "America/Mazatlan" | "America/Mendoza" | "America/Menominee" | "America/Merida" | "America/Metlakatla" | "America/Mexico_City" | "America/Miquelon" | "America/Moncton" | "America/Monterrey" | "America/Montevideo" | "America/Montserrat" | "America/Nassau" | "America/New_York" | "America/Nome" | "America/Noronha" | "America/North_Dakota/Beulah" | "America/North_Dakota/Center" | "America/North_Dakota/New_Salem" | "America/Ojinaga" | "America/Panama" | "America/Paramaribo" | "America/Phoenix" | "America/Port-au-Prince" | "America/Port_of_Spain" | "America/Porto_Velho" | "America/Puerto_Rico" | "America/Punta_Arenas" | "America/Rankin_Inlet" | "America/Recife" | "America/Regina" | "America/Resolute" | "America/Rio_Branco" | "America/Santarem" | "America/Santiago" | "America/Santo_Domingo" | "America/Sao_Paulo" | "America/Scoresbysund" | "America/Sitka" | "America/St_Barthelemy" | "America/St_Johns" | "America/St_Kitts" | "America/St_Lucia" | "America/St_Thomas" | "America/St_Vincent" | "America/Swift_Current" | "America/Tegucigalpa" | "America/Thule" | "America/Tijuana" | "America/Toronto" | "America/Tortola" | "America/Vancouver" | "America/Whitehorse" | "America/Winnipeg" | "America/Yakutat" | "Antarctica/Casey" | "Antarctica/Davis" | "Antarctica/DumontDUrville" | "Antarctica/Macquarie" | "Antarctica/Mawson" | "Antarctica/McMurdo" | "Antarctica/Palmer" | "Antarctica/Rothera" | "Antarctica/Syowa" | "Antarctica/Troll" | "Antarctica/Vostok" | "Arctic/Longyearbyen" | "Asia/Aden" | "Asia/Almaty" | "Asia/Amman" | "Asia/Anadyr" | "Asia/Aqtau" | "Asia/Aqtobe" | "Asia/Ashgabat" | "Asia/Atyrau" | "Asia/Baghdad" | "Asia/Bahrain" | "Asia/Baku" | "Asia/Bangkok" | "Asia/Barnaul" | "Asia/Beirut" | "Asia/Bishkek" | "Asia/Brunei" | "Asia/Calcutta" | "Asia/Chita" | "Asia/Colombo" | "Asia/Damascus" | "Asia/Dhaka" | "Asia/Dili" | "Asia/Dubai" | "Asia/Dushanbe" | "Asia/Famagusta" | "Asia/Gaza" | "Asia/Hebron" | "Asia/Hong_Kong" | "Asia/Hovd" | "Asia/Irkutsk" | "Asia/Jakarta" | "Asia/Jayapura" | "Asia/Jerusalem" | "Asia/Kabul" | "Asia/Kamchatka" | "Asia/Karachi" | "Asia/Katmandu" | "Asia/Khandyga" | "Asia/Krasnoyarsk" | "Asia/Kuala_Lumpur" | "Asia/Kuching" | "Asia/Kuwait" | "Asia/Macau" | "Asia/Magadan" | "Asia/Makassar" | "Asia/Manila" | "Asia/Muscat" | "Asia/Nicosia" | "Asia/Novokuznetsk" | "Asia/Novosibirsk" | "Asia/Omsk" | "Asia/Oral" | "Asia/Phnom_Penh" | "Asia/Pontianak" | "Asia/Pyongyang" | "Asia/Qatar" | "Asia/Qostanay" | "Asia/Qyzylorda" | "Asia/Rangoon" | "Asia/Riyadh" | "Asia/Saigon" | "Asia/Sakhalin" | "Asia/Samarkand" | "Asia/Seoul" | "Asia/Shanghai" | "Asia/Singapore" | "Asia/Srednekolymsk" | "Asia/Taipei" | "Asia/Tashkent" | "Asia/Tbilisi" | "Asia/Tehran" | "Asia/Thimphu" | "Asia/Tokyo" | "Asia/Tomsk" | "Asia/Ulaanbaatar" | "Asia/Urumqi" | "Asia/Ust-Nera" | "Asia/Vientiane" | "Asia/Vladivostok" | "Asia/Yakutsk" | "Asia/Yekaterinburg" | "Asia/Yerevan" | "Atlantic/Azores" | "Atlantic/Bermuda" | "Atlantic/Canary" | "Atlantic/Cape_Verde" | "Atlantic/Faeroe" | "Atlantic/Madeira" | "Atlantic/Reykjavik" | "Atlantic/South_Georgia" | "Atlantic/St_Helena" | "Atlantic/Stanley" | "Australia/Adelaide" | "Australia/Brisbane" | "Australia/Broken_Hill" | "Australia/Darwin" | "Australia/Eucla" | "Australia/Hobart" | "Australia/Lindeman" | "Australia/Lord_Howe" | "Australia/Melbourne" | "Australia/Perth" | "Australia/Sydney" | "Europe/Amsterdam" | "Europe/Andorra" | "Europe/Astrakhan" | "Europe/Athens" | "Europe/Belgrade" | "Europe/Berlin" | "Europe/Bratislava" | "Europe/Brussels" | "Europe/Bucharest" | "Europe/Budapest" | "Europe/Busingen" | "Europe/Chisinau" | "Europe/Copenhagen" | "Europe/Dublin" | "Europe/Gibraltar" | "Europe/Guernsey" | "Europe/Helsinki" | "Europe/Isle_of_Man" | "Europe/Istanbul" | "Europe/Jersey" | "Europe/Kaliningrad" | "Europe/Kiev" | "Europe/Kirov" | "Europe/Lisbon" | "Europe/Ljubljana" | "Europe/London" | "Europe/Luxembourg" | "Europe/Madrid" | "Europe/Malta" | "Europe/Mariehamn" | "Europe/Minsk" | "Europe/Monaco" | "Europe/Moscow" | "Europe/Oslo" | "Europe/Paris" | "Europe/Podgorica" | "Europe/Prague" | "Europe/Riga" | "Europe/Rome" | "Europe/Samara" | "Europe/San_Marino" | "Europe/Sarajevo" | "Europe/Saratov" | "Europe/Simferopol" | "Europe/Skopje" | "Europe/Sofia" | "Europe/Stockholm" | "Europe/Tallinn" | "Europe/Tirane" | "Europe/Ulyanovsk" | "Europe/Vaduz" | "Europe/Vatican" | "Europe/Vienna" | "Europe/Vilnius" | "Europe/Volgograd" | "Europe/Warsaw" | "Europe/Zagreb" | "Europe/Zurich" | "Indian/Antananarivo" | "Indian/Chagos" | "Indian/Christmas" | "Indian/Cocos" | "Indian/Comoro" | "Indian/Kerguelen" | "Indian/Mahe" | "Indian/Maldives" | "Indian/Mauritius" | "Indian/Mayotte" | "Indian/Reunion" | "Pacific/Apia" | "Pacific/Auckland" | "Pacific/Bougainville" | "Pacific/Chatham" | "Pacific/Easter" | "Pacific/Efate" | "Pacific/Enderbury" | "Pacific/Fakaofo" | "Pacific/Fiji" | "Pacific/Funafuti" | "Pacific/Galapagos" | "Pacific/Gambier" | "Pacific/Guadalcanal" | "Pacific/Guam" | "Pacific/Honolulu" | "Pacific/Kiritimati" | "Pacific/Kosrae" | "Pacific/Kwajalein" | "Pacific/Majuro" | "Pacific/Marquesas" | "Pacific/Midway" | "Pacific/Nauru" | "Pacific/Niue" | "Pacific/Norfolk" | "Pacific/Noumea" | "Pacific/Pago_Pago" | "Pacific/Palau" | "Pacific/Pitcairn" | "Pacific/Ponape" | "Pacific/Port_Moresby" | "Pacific/Rarotonga" | "Pacific/Saipan" | "Pacific/Tahiti" | "Pacific/Tarawa" | "Pacific/Tongatapu" | "Pacific/Truk" | "Pacific/Wake" | "Pacific/Wallis";
+
+/** Singular/plural unit for rate expressions */
+type RateUnit = "minute" | "minutes" | "hour" | "hours" | "day" | "days";
+/**
+ * Rate expression: `rate(1 hour)`, `rate(5 minutes)`, `rate(2 days)`
+ *
+ * Strictly typed — autocomplete and compile-time validation for unit.
+ */
+type RateExpression = `rate(${number} ${RateUnit})`;
+/**
+ * Cron expression: `cron(min hour dom month dow year)`
+ *
+ * Not deeply typed (too combinatorial for TS), but the `cron(...)` wrapper is enforced.
+ *
+ * @example
+ * ```
+ * "cron(0 9 * * ? *)"          // daily at 9:00 UTC
+ * "cron(0 9 ? * MON-FRI *)"    // weekdays at 9:00
+ * "cron(0/15 * * * ? *)"       // every 15 minutes
+ * ```
+ */
+type CronExpression = `cron(${string})`;
+/**
+ * EventBridge Scheduler schedule expression.
+ *
+ * - **Rate**: `"rate(5 minutes)"`, `"rate(1 hour)"`, `"rate(1 day)"` — strictly typed units
+ * - **Cron**: `"cron(0 9 * * ? *)"` — 6 fields: min hour dom month dow year
+ */
+type ScheduleExpression = RateExpression | CronExpression;
+/** Static config extracted at deploy time */
+type CronConfig = {
+    /** Lambda function settings (memory, timeout, permissions, etc.) */
+    lambda?: LambdaWithPermissions;
+    /** EventBridge Scheduler schedule expression */
+    schedule: ScheduleExpression;
+    /** IANA timezone for the schedule (default: UTC) */
+    timezone?: Timezone;
+};
+/** Setup factory — receives deps/config/files based on what was declared */
+type SetupArgs<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P & {}>;
+}) & (HasFiles extends true ? {
+    files: StaticFiles;
+} : {});
+/** Spread ctx into callback args (empty when no setup) */
+type SpreadCtx<C> = [C] extends [undefined] ? {} : C & {};
+/** Callback function for cron tick */
+type CronTickFn<C = undefined> = (args: SpreadCtx<C>) => Promise<void> | void;
+/**
+ * Handler object created by defineCron.
+ * @internal
+ */
+type CronHandler<C = any> = {
+    readonly __brand: "effortless-cron";
+    readonly __spec: CronConfig;
+    readonly onError?: (...args: any[]) => any;
+    readonly onCleanup?: (...args: any[]) => any;
+    readonly setup?: (...args: any[]) => C | Promise<C>;
+    readonly deps?: Record<string, unknown> | (() => Record<string, unknown>);
+    readonly config?: Record<string, unknown>;
+    readonly static?: string[];
+    readonly onTick?: (...args: any[]) => any;
+};
+/** Options passed to `defineCron()` — resource config only */
+type CronOptions = {
+    /** EventBridge Scheduler schedule expression: `"rate(5 minutes)"` or `"cron(0 9 * * ? *)"` */
+    schedule: ScheduleExpression;
+    /** IANA timezone for the schedule (default: UTC). Full autocomplete for all timezones. */
+    timezone?: Timezone;
+};
+interface CronBuilder<D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
+    /** Declare handler dependencies (tables, queues, buckets, mailers) */
+    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): CronBuilder<D2, P, C, HasFiles>;
+    /** Declare SSM secrets */
+    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): CronBuilder<D, P2, C, HasFiles>;
+    /** Include static files in the Lambda bundle. Chainable — call multiple times. */
+    include(glob: string): CronBuilder<D, P, C, true>;
+    /** Configure Lambda settings only (memory, timeout, permissions, logLevel) */
+    setup(lambda: LambdaOptions): CronBuilder<D, P, C, HasFiles>;
+    /** Initialize shared state on cold start. Receives deps, config, files. */
+    setup<C2>(fn: (args: SetupArgs<D, P, HasFiles>) => C2 | Promise<C2>): CronBuilder<D, P, C2, HasFiles>;
+    /** Initialize shared state on cold start + configure Lambda settings. */
+    setup<C2>(fn: (args: SetupArgs<D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): CronBuilder<D, P, C2, HasFiles>;
+    /** Handle errors thrown by onTick */
+    onError(fn: (args: {
+        error: unknown;
+    } & SpreadCtx<C>) => void | Promise<void>): CronBuilder<D, P, C, HasFiles>;
+    /** Cleanup callback — runs after each invocation, before Lambda freezes */
+    onCleanup(fn: (args: SpreadCtx<C>) => void | Promise<void>): CronBuilder<D, P, C, HasFiles>;
+    /** Tick handler — called on each scheduled invocation (terminal) */
+    onTick(fn: CronTickFn<C>): CronHandler<C>;
+}
+/**
+ * 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")
+ *   })
+ * ```
+ */
+declare function defineCron(options: CronOptions): CronBuilder;
 
-export { type AnyParamRef, type AnySecretRef, type ApiAuthConfig, type ApiConfig, type ApiHandler, type ApiRoutes, type AppConfig, type AppHandler, type AuthHelpers, type BucketClient, type BucketConfig, type BucketEvent, type BucketHandler, type ConfigHelpers, type ContentType, type DefineSecretFn, type Duration, type EffortlessConfig, type EmailClient, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type GenerateSpec, type HttpMethod$1 as HttpMethod, type HttpRequest, type HttpResponse, type LambdaConfig, type LambdaWithPermissions, type LogLevel, type MailerConfig, type MailerHandler, 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 StreamView, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type UpdateActions, defineApi, defineApp, defineBucket, defineConfig, defineFifoQueue, defineMailer, defineSecret, defineStaticSite, defineTable, generateBase64, generateHex, generateUuid, param, secret, toSeconds, unsafeAs };
+export { type AnyParamRef, type AnySecretRef, type ApiAuthConfig, type ApiConfig, type ApiHandler, type ApiRoutes, type AppConfig, type AppHandler, type AuthHelpers, type BucketClient, type BucketConfig, type BucketEvent, type BucketHandler, type ConfigHelpers, type ContentType, type CronConfig, type CronHandler, type DefineSecretFn, type Duration, type EffortlessConfig, type EmailClient, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type GenerateSpec, type HttpMethod$1 as HttpMethod, type HttpRequest, type HttpResponse, type LambdaConfig, type LambdaWithPermissions, type LogLevel, type MailerConfig, type MailerHandler, 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 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, defineSecret, defineStaticSite, defineTable, defineWorker, generateBase64, generateHex, generateUuid, param, secret, toSeconds };