effortless-aws 0.16.2 → 0.18.0

package/README.md

@@ -1,9 +1,8 @@
 # effortless-aws
 
 [![npm version](https://img.shields.io/npm/v/effortless-aws)](https://www.npmjs.com/package/effortless-aws)
-[![npm downloads](https://img.shields.io/npm/dw/effortless-aws)](https://www.npmjs.com/package/effortless-aws)
 
-TypeScript framework for AWS serverless. Export handlers, deploy with one command. No YAML, no CloudFormation, no state files.
+Code-first AWS Lambda framework. Export handlers, deploy with one command. No YAML, no CloudFormation, no state files.
 
 ```bash
 npm install effortless-aws
@@ -23,26 +22,33 @@ export const hello = defineHttp({
 });
 ```
 
-```bash
-npx eff deploy
-```
+## Handlers
 
-One export, one command. Lambda, API Gateway route, and IAM role created automatically.
+| Handler | Description |
+|---------|-------------|
+| `defineHttp` | HTTP endpoint via API Gateway |
+| `defineApi` | REST API with typed GET/POST routes |
+| `defineApp` | Generic Lambda (cron, custom events) |
+| `defineTable` | DynamoDB table with stream processing |
+| `defineFifoQueue` | SQS FIFO queue consumer |
+| `defineBucket` | S3 bucket with event triggers |
+| `defineMailer` | SES email sending |
+| `defineStaticSite` | CloudFront + S3 static site with optional middleware |
 
 ## Features
 
-- **Infrastructure from code** — export a handler, get the AWS resources. No config files.
-- **Typed everything** — `defineTable<Order>` gives you typed `put()`, typed `deps.orders.get()`, typed `record.new`.
-- **Direct AWS SDK deploys** — no CloudFormation. Deploy in ~5-10s, not minutes.
-- **No state files** — AWS resource tags are the source of truth.
-- **Cross-handler deps** — `deps: { orders }` auto-wires IAM and injects a typed `TableClient`.
-- **SSM params** — `param("stripe-key")` fetches from Parameter Store at cold start. Auto IAM, auto caching.
-- **Partial batch failures** — DynamoDB stream processing reports failed records individually.
-- **Cold start caching** — `context` factory runs once per cold start, cached across invocations.
+- **Infrastructure from code** — export a handler, get the AWS resources
+- **Typed everything** — `defineTable<Order>` gives you typed `put()`, typed `deps.orders.get()`, typed `record.new`
+- **Cross-handler deps** — `deps: { orders }` auto-wires IAM and injects a typed `TableClient`
+- **SSM params** — `param("stripe-key")` fetches from Parameter Store at cold start
+- **Static files** — `static: ["templates/*.ejs"]` bundles files into the Lambda ZIP
+- **Cold start caching** — `setup` factory runs once per cold start, cached across invocations
+
+Deploy with [`@effortless-aws/cli`](https://www.npmjs.com/package/@effortless-aws/cli).
 
 ## Documentation
 
-Full docs, examples, and API reference: **[effortless-aws docs](https://effortless-aws.website)**
+Full docs, examples, and API reference: **[effortless-aws.website](https://effortless-aws.website)**
 
 ## License
 

package/dist/index.d.ts

@@ -14,6 +14,13 @@
  * ```
  */
 type EffortlessConfig = {
+    /**
+     * Project root directory. All relative paths (handlers, server, assets, etc.)
+     * are resolved from this directory.
+     * Resolved relative to where the CLI runs (process.cwd()).
+     * @default "." (current working directory)
+     */
+    root?: string;
     /**
      * Project name used for resource naming and tagging.
      * This becomes part of Lambda function names, IAM roles, etc.
@@ -415,7 +422,7 @@ type FailedRecord<T = Record<string, unknown>> = {
  * Always receives `table: TableClient<T>` (self-client for the handler's own table).
  * Also receives `deps` and/or `config` when declared.
  */
-type SetupFactory$3<C, T, D, P, S extends string[] | undefined = undefined> = (args: {
+type SetupFactory$4<C, T, D, P, S extends string[] | undefined = undefined> = (args: {
     table: TableClient<T>;
 } & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
@@ -491,7 +498,7 @@ type DefineTableBase<T = Record<string, unknown>, C = undefined, D = undefined,
      * When deps/params are declared, receives them as argument.
      * Supports both sync and async return values.
      */
-    setup?: SetupFactory$3<C, T, D, P, S>;
+    setup?: SetupFactory$4<C, T, D, P, S>;
     /**
      * Dependencies on other handlers (tables, queues, etc.).
      * Typed clients are injected into the handler via the `deps` argument.
@@ -661,7 +668,7 @@ type BucketObjectRemovedFn<C = undefined, D = undefined, P = undefined, S extend
  * Always receives `bucket: BucketClient` (self-client for the handler's own bucket).
  * Also receives `deps` and/or `config` when declared.
  */
-type SetupFactory$2<C, D, P, S extends string[] | undefined = undefined> = (args: {
+type SetupFactory$3<C, D, P, S extends string[] | undefined = undefined> = (args: {
     bucket: BucketClient;
 } & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
@@ -683,7 +690,7 @@ type DefineBucketBase<C = undefined, D = undefined, P = undefined, S extends str
      * Always receives `bucket: BucketClient` (self-client). When deps/config
      * are declared, receives them as well.
      */
-    setup?: SetupFactory$2<C, D, P, S>;
+    setup?: SetupFactory$3<C, D, P, S>;
     /**
      * Dependencies on other handlers (tables, buckets, etc.).
      * Typed clients are injected into the handler via the `deps` argument.
@@ -853,7 +860,7 @@ type ResolveDeps<D> = {
 };
 
 /** HTTP methods supported by API Gateway */
-type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ANY";
 /** Short content-type aliases for common response formats */
 type ContentType = "json" | "html" | "text" | "css" | "js" | "xml" | "csv" | "svg";
 /**
@@ -932,7 +939,7 @@ type HttpHandlerFn<T = undefined, C = undefined, D = undefined, P = undefined, S
  * Setup factory type — always receives an args object.
  * Args include `deps` and/or `config` when declared (empty `{}` otherwise).
  */
-type SetupFactory$1<C, D, P, S extends string[] | undefined = undefined> = (args: ([D] extends [undefined] ? {} : {
+type SetupFactory$2<C, D, P, S extends string[] | undefined = undefined> = (args: ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
     config: ResolveConfig<P & {}>;
@@ -970,7 +977,7 @@ type DefineHttpOptions<T = undefined, C = undefined, D extends Record<string, An
      * When deps/params are declared, receives them as argument.
      * Supports both sync and async return values.
      */
-    setup?: SetupFactory$1<C, D, P, S>;
+    setup?: SetupFactory$2<C, D, P, S>;
     /**
      * Dependencies on other handlers (tables, queues, etc.).
      * Typed clients are injected into the handler via the `deps` argument.
@@ -1046,23 +1053,33 @@ type HttpHandler<T = undefined, C = undefined, D = undefined, P = undefined, S e
  *   })
  * });
  * ```
+ *
+ * @see {@link defineApi} for multi-route endpoints with typed GET routes and POST command handling (CQRS pattern)
  */
 declare const defineHttp: <T = undefined, C = undefined, D extends Record<string, AnyDepHandler> | 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)
+ * Configuration for deploying an SSR framework (Nuxt, Astro, etc.)
+ * via CloudFront + S3 (static assets) + Lambda Function URL (server-side rendering).
  */
-type AppConfig = LambdaConfig & {
-    /** Base URL path the site is served under (e.g., "/app") */
+type AppConfig = LambdaWithPermissions & {
+    /** Directory containing the Lambda server handler (e.g., ".output/server").
+     *  Must contain an `index.mjs` (or `index.js`) that exports a `handler` function. */
+    server: string;
+    /** Directory containing static assets for S3 (e.g., ".output/public") */
+    assets: string;
+    /** Base URL path (default: "/") */
     path?: string;
-    /** Directory containing the static site files, relative to project root */
-    dir: string;
-    /** Default file for directory requests (default: "index.html") */
-    index?: string;
-    /** SPA mode: serve index.html for all paths that don't match a file (default: false) */
-    spa?: boolean;
-    /** Shell command to run before deploy to generate site content (e.g., "npx astro build") */
+    /** Shell command to build the framework output (e.g., "nuxt build") */
     build?: string;
+    /** Custom domain name. String or stage-keyed record (e.g., { prod: "app.example.com" }). */
+    domain?: string | Record<string, string>;
+    /** CloudFront route overrides: path patterns forwarded to API Gateway instead of the SSR Lambda.
+     * Keys are CloudFront path patterns (e.g., "/api/*"), values are handler references.
+     * Example: `routes: { "/api/*": api }` */
+    routes?: Record<string, {
+        readonly __brand: string;
+    }>;
 };
 /**
  * Internal handler object created by defineApp
@@ -1073,25 +1090,33 @@ type AppHandler = {
     readonly __spec: AppConfig;
 };
 /**
- * Deploy a static site via Lambda + API Gateway.
- * Files are bundled into the Lambda ZIP and served with auto-detected content types.
+ * Deploy an SSR framework application via CloudFront + Lambda Function URL.
  *
- * For CDN-backed sites (S3 + CloudFront), use {@link defineStaticSite} instead.
+ * Static assets from the `assets` directory are served via S3 + CloudFront CDN.
+ * Server-rendered pages are handled by a Lambda function using the framework's
+ * built output from the `server` directory.
  *
- * @param options - Site configuration: path, directory, optional SPA mode
+ * For static-only sites (no SSR), use {@link defineStaticSite} instead.
+ *
+ * @param options - App configuration: server directory, assets directory, optional build command
  * @returns Handler object used by the deployment system
  *
- * @example Basic static site
+ * @example Nuxt SSR
  * ```typescript
  * export const app = defineApp({
- *   path: "/app",
- *   dir: "src/webapp",
+ *   build: "nuxt build",
+ *   server: ".output/server",
+ *   assets: ".output/public",
+ *   memory: 1024,
  * });
  * ```
  */
 declare const defineApp: (options: AppConfig) => AppHandler;
 
-type AnyHttpHandler = HttpHandler<any, any, any, any, any>;
+/** Any branded handler that deploys to API Gateway (HttpHandler, ApiHandler, etc.) */
+type AnyRoutableHandler = {
+    readonly __brand: string;
+};
 /** Simplified request object passed to middleware */
 type MiddlewareRequest = {
     uri: string;
@@ -1133,7 +1158,7 @@ type StaticSiteConfig = {
     /** CloudFront route overrides: path patterns forwarded to API Gateway instead of S3.
      * Keys are CloudFront path patterns (e.g., "/api/*"), values are HTTP handlers.
      * Example: `routes: { "/api/*": api }` */
-    routes?: Record<string, AnyHttpHandler>;
+    routes?: Record<string, AnyRoutableHandler>;
     /** Custom 404 error page path relative to `dir` (e.g. "404.html").
      * For non-SPA sites only. If not set, a default page is generated automatically. */
     errorPage?: string;
@@ -1234,7 +1259,7 @@ type FifoQueueConfig = LambdaWithPermissions & {
  * Setup factory type — always receives an args object.
  * Args include `deps` and/or `config` when declared (empty `{}` otherwise).
  */
-type SetupFactory<C, D, P, S extends string[] | undefined = undefined> = (args: ([D] extends [undefined] ? {} : {
+type SetupFactory$1<C, D, P, S extends string[] | undefined = undefined> = (args: ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
     config: ResolveConfig<P & {}>;
@@ -1288,7 +1313,7 @@ type DefineFifoQueueBase<T = unknown, C = undefined, D = undefined, P = undefine
      * Called once on cold start, result is cached and reused across invocations.
      * When deps/params are declared, receives them as argument.
      */
-    setup?: SetupFactory<C, D, P, S>;
+    setup?: SetupFactory$1<C, D, P, S>;
     /**
      * Dependencies on other handlers (tables, queues, etc.).
      * Typed clients are injected into the handler via the `deps` argument.
@@ -1364,4 +1389,127 @@ type FifoQueueHandler<T = unknown, C = undefined, D = undefined, P = undefined,
  */
 declare const defineFifoQueue: <T = unknown, C = undefined, D extends Record<string, AnyDepHandler> | 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>;
 
-export { type AppConfig, type AppHandler, type BucketClient, type BucketConfig, type BucketEvent, type BucketHandler, type BucketObjectCreatedFn, type BucketObjectRemovedFn, type ContentType, type DefineBucketOptions, type DefineFifoQueueOptions, type DefineHttpOptions, type DefineTableOptions, type EffortlessConfig, type EmailClient, 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 LambdaConfig, type LambdaWithPermissions, type LogLevel, type MailerConfig, type MailerHandler, type MiddlewareDeny, type MiddlewareHandler, type MiddlewareRedirect, type MiddlewareRequest, type MiddlewareResult, type ParamRef, type PutInput, type PutOptions, type QueryByTagParams, type QueryParams, type ResolveConfig, type ResolveDeps, type SendEmailOptions, type SkCondition, type StaticFiles, type StaticSiteConfig, type StaticSiteHandler, type StreamView, type TableBatchCompleteFn, type TableBatchFn, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type TableRecordFn, type UpdateActions, defineApp, defineBucket, defineConfig, defineFifoQueue, defineHttp, defineMailer, defineStaticSite, defineTable, param, typed };
+/** GET route handler — no schema, no data */
+type ApiGetHandlerFn<C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = (args: {
+    req: HttpRequest;
+} & ([C] extends [undefined] ? {} : {
+    ctx: C;
+}) & ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P>;
+}) & ([S] extends [undefined] ? {} : {
+    files: StaticFiles;
+})) => Promise<HttpResponse> | HttpResponse;
+/** POST handler — with typed data from schema */
+type ApiPostHandlerFn<T = undefined, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = (args: {
+    req: HttpRequest;
+} & ([T] extends [undefined] ? {} : {
+    data: T;
+}) & ([C] extends [undefined] ? {} : {
+    ctx: C;
+}) & ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P>;
+}) & ([S] extends [undefined] ? {} : {
+    files: StaticFiles;
+})) => Promise<HttpResponse> | HttpResponse;
+/** Setup factory — receives deps/config/files when declared */
+type SetupFactory<C, D, P, S extends string[] | undefined = undefined> = (args: ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P & {}>;
+}) & ([S] extends [undefined] ? {} : {
+    files: StaticFiles;
+})) => C | Promise<C>;
+/** Static config extracted by AST (no runtime callbacks) */
+type ApiConfig = LambdaWithPermissions & {
+    /** Base path prefix for all routes (e.g., "/api") */
+    basePath: string;
+};
+/**
+ * Options for defining a CQRS-style API endpoint.
+ *
+ * - `get` routes handle queries (path-based routing, no body)
+ * - `post` handles commands (single entry point, discriminated union via `schema`)
+ */
+type DefineApiOptions<T = undefined, C = undefined, D extends Record<string, AnyDepHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined> = LambdaWithPermissions & {
+    /** Base path prefix for all routes (e.g., "/api") */
+    basePath: string;
+    /**
+     * Factory function to initialize shared state.
+     * Called once on cold start, result is cached and reused across invocations.
+     */
+    setup?: SetupFactory<C, D, P, S>;
+    /** Dependencies on other handlers (tables, queues, etc.) */
+    deps?: D;
+    /** SSM Parameter Store parameters */
+    config?: P;
+    /** Static file glob patterns to bundle into the Lambda ZIP */
+    static?: S;
+    /** Error handler called when schema validation or handler throws */
+    onError?: (error: unknown, req: HttpRequest) => HttpResponse;
+    /** GET routes — query handlers keyed by relative path (e.g., "/users/{id}") */
+    get?: Record<string, ApiGetHandlerFn<C, D, P, S>>;
+    /**
+     * Schema for POST body validation. Use with discriminated unions:
+     * ```typescript
+     * schema: Action.parse,
+     * post: async ({ data }) => { switch (data.action) { ... } }
+     * ```
+     */
+    schema?: (input: unknown) => T;
+    /** POST handler — single entry point for commands */
+    post?: ApiPostHandlerFn<T, C, D, P, S>;
+};
+/** Internal handler object created by defineApi */
+type ApiHandler<T = undefined, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = {
+    readonly __brand: "effortless-api";
+    readonly __spec: ApiConfig;
+    readonly schema?: (input: unknown) => T;
+    readonly onError?: (error: unknown, req: HttpRequest) => HttpResponse;
+    readonly setup?: (...args: any[]) => C | Promise<C>;
+    readonly deps?: D;
+    readonly config?: P;
+    readonly static?: string[];
+    readonly get?: Record<string, ApiGetHandlerFn<C, D, P, S>>;
+    readonly post?: ApiPostHandlerFn<T, C, D, P, S>;
+};
+/**
+ * Define a CQRS-style API with typed GET routes and POST commands.
+ *
+ * GET routes handle queries — path-based routing, no request body.
+ * POST handles commands — single entry point with discriminated union schema.
+ * Deploys as a single Lambda (fat Lambda) with one API Gateway catch-all route.
+ *
+ * @example
+ * ```typescript
+ * export default defineApi({
+ *   basePath: "/api",
+ *   deps: { users },
+ *
+ *   get: {
+ *     "/users": async ({ req, deps }) => ({
+ *       status: 200,
+ *       body: await deps.users.scan()
+ *     }),
+ *     "/users/{id}": async ({ req, deps }) => ({
+ *       status: 200,
+ *       body: await deps.users.get(req.params.id)
+ *     }),
+ *   },
+ *
+ *   schema: Action.parse,
+ *   post: async ({ data, deps }) => {
+ *     switch (data.action) {
+ *       case "create": return { status: 201, body: await deps.users.put(data) }
+ *       case "delete": return { status: 200, body: await deps.users.delete(data.id) }
+ *     }
+ *   },
+ * })
+ * ```
+ */
+declare const defineApi: <T = undefined, C = undefined, D extends Record<string, AnyDepHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineApiOptions<T, C, D, P, S>) => ApiHandler<T, C, D, P, S>;
+
+export { type AnyParamRef, type ApiConfig, type ApiGetHandlerFn, type ApiHandler, type ApiPostHandlerFn, type AppConfig, type AppHandler, type BucketClient, type BucketConfig, type BucketEvent, type BucketHandler, type BucketObjectCreatedFn, type BucketObjectRemovedFn, type ContentType, type DefineApiOptions, type DefineBucketOptions, type DefineFifoQueueOptions, type DefineHttpOptions, type DefineTableOptions, type EffortlessConfig, type EmailClient, 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 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 ResolveConfig, type ResolveDeps, type SendEmailOptions, type SkCondition, type StaticFiles, type StaticSiteConfig, type StaticSiteHandler, type StreamView, type TableBatchCompleteFn, type TableBatchFn, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type TableRecordFn, type UpdateActions, defineApi, defineApp, defineBucket, defineConfig, defineFifoQueue, defineHttp, defineMailer, defineStaticSite, defineTable, param, typed };

package/dist/index.js

@@ -86,6 +86,23 @@ var defineMailer = (options) => ({
   __spec: options
 });
 
+// src/handlers/define-api.ts
+var defineApi = (options) => {
+  const { get, post, schema, onError, setup, deps, config, static: staticFiles, ...__spec } = options;
+  return {
+    __brand: "effortless-api",
+    __spec,
+    ...get ? { get } : {},
+    ...post ? { post } : {},
+    ...schema ? { schema } : {},
+    ...onError ? { onError } : {},
+    ...setup ? { setup } : {},
+    ...deps ? { deps } : {},
+    ...config ? { config } : {},
+    ...staticFiles ? { static: staticFiles } : {}
+  };
+};
+
 // src/handlers/handler-options.ts
 function param(key, transform) {
   return {
@@ -98,6 +115,7 @@ function typed() {
   return (input) => input;
 }
 export {
+  defineApi,
   defineApp,
   defineBucket,
   defineConfig,