effortless-aws 0.7.2 → 0.8.1

package/dist/index.d.ts

@@ -113,7 +113,7 @@ type LambdaWithPermissions = LambdaConfig & {
     /** Additional IAM permissions for the Lambda */
     permissions?: Permission[];
 };
-type AnyParamRef = ParamRef<any>;
+type AnyParamRef = ParamRef<any> | string;
 /**
  * Reference to an SSM Parameter Store parameter.
  *
@@ -125,12 +125,13 @@ type ParamRef<T = string> = {
     readonly transform?: (raw: string) => T;
 };
 /**
- * Maps a params declaration to resolved value types.
+ * Maps a config declaration to resolved value types.
+ * Plain strings resolve to `string`, `ParamRef<T>` resolves to `T`.
  *
- * @typeParam P - Record of param names to ParamRef instances
+ * @typeParam P - Record of config keys to string or ParamRef instances
  */
-type ResolveParams<P> = {
-    [K in keyof P]: P[K] extends ParamRef<infer T> ? T : never;
+type ResolveConfig<P> = {
+    [K in keyof P]: P[K] extends ParamRef<infer T> ? T : string;
 };
 /**
  * Declare an SSM Parameter Store parameter.
@@ -144,7 +145,7 @@ type ResolveParams<P> = {
  *
  * @example Simple string parameter
  * ```typescript
- * params: {
+ * config: {
  *   dbUrl: param("database-url"),
  * }
  * ```
@@ -153,8 +154,8 @@ type ResolveParams<P> = {
  * ```typescript
  * import TOML from "smol-toml";
  *
- * params: {
- *   config: param("app-config", TOML.parse),
+ * config: {
+ *   appConfig: param("app-config", TOML.parse),
  * }
  * ```
  */
@@ -175,7 +176,7 @@ declare function param<T>(key: string, transform: (raw: string) => T): ParamRef<
  * ```typescript
  * type User = { id: string; email: string };
  *
- * // Before (breaks inference for context, deps, params):
+ * // Before (breaks inference for setup, deps, config):
  * export const users = defineTable<User>({ pk: { name: "id", type: "string" } });
  *
  * // After (all generics inferred correctly):
@@ -190,7 +191,7 @@ declare function param<T>(key: string, transform: (raw: string) => T): ParamRef<
  * export const orders = defineTable({
  *   pk: { name: "id", type: "string" },
  *   schema: typed<Order>(),
- *   context: async () => ({ db: createClient() }),
+ *   setup: async () => ({ db: createClient() }),
  *   onRecord: async ({ record, ctx }) => {
  *     // record.new is Order, ctx is { db: Client } — all inferred
  *   },
@@ -275,7 +276,7 @@ type TableKey = {
 /** DynamoDB Streams view type - determines what data is captured in stream records */
 type StreamView = "NEW_AND_OLD_IMAGES" | "NEW_IMAGE" | "OLD_IMAGE" | "KEYS_ONLY";
 /**
- * Configuration options extracted from DefineTableOptions (without onRecord/context)
+ * Configuration options extracted from DefineTableOptions (without onRecord/setup)
  */
 type TableConfig = LambdaWithPermissions & {
     /** Partition key definition */
@@ -326,13 +327,15 @@ type FailedRecord<T = Record<string, unknown>> = {
     error: unknown;
 };
 /**
- * Context factory type — conditional on whether params are declared.
- * Without params: `() => C | Promise<C>`
- * With params: `(args: { params: ResolveParams<P> }) => C | Promise<C>`
+ * Setup factory type — conditional on whether deps/config are declared.
+ * No deps/config: `() => C | Promise<C>`
+ * With deps/config: `(args: { deps?, config? }) => C | Promise<C>`
  */
-type ContextFactory$2<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (args: {
-    params: ResolveParams<P & {}>;
-}) => C | Promise<C>;
+type SetupFactory$2<C, D, P> = [D | P] extends [undefined] ? () => C | Promise<C> : (args: ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps$2<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P & {}>;
+})) => C | Promise<C>;
 /**
  * Callback function type for processing a single DynamoDB stream record
  */
@@ -344,7 +347,7 @@ type TableRecordFn<T = Record<string, unknown>, C = undefined, R = void, D = und
 }) & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps$2<D>;
 }) & ([P] extends [undefined] ? {} : {
-    params: ResolveParams<P>;
+    config: ResolveConfig<P>;
 }) & ([S] extends [undefined] ? {} : {
     readStatic: (path: string) => string;
 })) => Promise<R>;
@@ -360,7 +363,7 @@ type TableBatchCompleteFn<T = Record<string, unknown>, C = undefined, R = void,
 }) & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps$2<D>;
 }) & ([P] extends [undefined] ? {} : {
-    params: ResolveParams<P>;
+    config: ResolveConfig<P>;
 }) & ([S] extends [undefined] ? {} : {
     readStatic: (path: string) => string;
 })) => Promise<void>;
@@ -375,7 +378,7 @@ type TableBatchFn<T = Record<string, unknown>, C = undefined, D = undefined, P =
 }) & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps$2<D>;
 }) & ([P] extends [undefined] ? {} : {
-    params: ResolveParams<P>;
+    config: ResolveConfig<P>;
 }) & ([S] extends [undefined] ? {} : {
     readStatic: (path: string) => string;
 })) => Promise<void>;
@@ -393,12 +396,12 @@ type DefineTableBase<T = Record<string, unknown>, C = undefined, D = undefined,
      */
     onError?: (error: unknown) => void;
     /**
-     * Factory function to create context/dependencies for callbacks.
+     * Factory function to initialize shared state for callbacks.
      * Called once on cold start, result is cached and reused across invocations.
-     * When params are declared, receives resolved params as argument.
+     * When deps/params are declared, receives them as argument.
      * Supports both sync and async return values.
      */
-    context?: ContextFactory$2<C, P>;
+    setup?: SetupFactory$2<C, D, P>;
     /**
      * Dependencies on other handlers (tables, queues, etc.).
      * Typed clients are injected into the handler via the `deps` argument.
@@ -407,9 +410,9 @@ type DefineTableBase<T = Record<string, unknown>, C = undefined, D = undefined,
     /**
      * SSM Parameter Store parameters.
      * Declare with `param()` helper. Values are fetched and cached at cold start.
-     * Typed values are injected into the handler via the `params` argument.
+     * Typed values are injected into the handler via the `config` argument.
      */
-    params?: P;
+    config?: P;
     /**
      * Static file glob patterns to bundle into the Lambda ZIP.
      * Files are accessible at runtime via the `readStatic` callback argument.
@@ -441,12 +444,12 @@ type DefineTableOptions<T = Record<string, unknown>, C = undefined, R = void, D
  */
 type TableHandler<T = Record<string, unknown>, C = undefined, R = void, D = undefined, P = undefined, S extends string[] | undefined = undefined> = {
     readonly __brand: "effortless-table";
-    readonly config: TableConfig;
+    readonly __spec: TableConfig;
     readonly schema?: (input: unknown) => T;
     readonly onError?: (error: unknown) => void;
-    readonly context?: (...args: any[]) => C | Promise<C>;
+    readonly setup?: (...args: any[]) => C | Promise<C>;
     readonly deps?: D;
-    readonly params?: P;
+    readonly config?: P;
     readonly static?: string[];
     readonly onRecord?: TableRecordFn<T, C, R, D, P, S>;
     readonly onBatchComplete?: TableBatchCompleteFn<T, C, R, D, P, S>;
@@ -549,7 +552,7 @@ type HttpConfig = LambdaWithPermissions & {
  * Handler function type for HTTP endpoints
  *
  * @typeParam T - Type of the validated request body (from schema function)
- * @typeParam C - Type of the context/dependencies (from context function)
+ * @typeParam C - Type of the setup result (from setup function)
  * @typeParam D - Type of the deps (from deps declaration)
  * @typeParam P - Type of the params (from params declaration)
  */
@@ -562,23 +565,25 @@ type HttpHandlerFn<T = undefined, C = undefined, D = undefined, P = undefined, S
 }) & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps$1<D>;
 }) & ([P] extends [undefined] ? {} : {
-    params: ResolveParams<P>;
+    config: ResolveConfig<P>;
 }) & ([S] extends [undefined] ? {} : {
     readStatic: (path: string) => string;
 })) => Promise<HttpResponse>;
 /**
- * Context factory type — conditional on whether params are declared.
- * Without params: `() => C | Promise<C>`
- * With params: `(args: { params: ResolveParams<P> }) => C | Promise<C>`
+ * Setup factory type — conditional on whether deps/config are declared.
+ * No deps/config: `() => C | Promise<C>`
+ * With deps/config: `(args: { deps?, config? }) => C | Promise<C>`
  */
-type ContextFactory$1<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (args: {
-    params: ResolveParams<P & {}>;
-}) => C | Promise<C>;
+type SetupFactory$1<C, D, P> = [D | P] extends [undefined] ? () => C | Promise<C> : (args: ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps$1<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P & {}>;
+})) => C | Promise<C>;
 /**
  * Options for defining an HTTP endpoint
  *
  * @typeParam T - Type of the validated request body (inferred from schema function)
- * @typeParam C - Type of the context/dependencies returned by context function
+ * @typeParam C - Type of the setup result returned by setup function
  * @typeParam D - Type of the deps (from deps declaration)
  * @typeParam P - Type of the params (from params declaration)
  */
@@ -600,12 +605,12 @@ type DefineHttpOptions<T = undefined, C = undefined, D extends Record<string, An
      */
     onError?: (error: unknown, req: HttpRequest) => HttpResponse;
     /**
-     * Factory function to create context/dependencies for the request handler.
+     * Factory function to initialize shared state for the request handler.
      * Called once on cold start, result is cached and reused across invocations.
-     * When params are declared, receives resolved params as argument.
+     * When deps/params are declared, receives them as argument.
      * Supports both sync and async return values.
      */
-    context?: ContextFactory$1<C, P>;
+    setup?: SetupFactory$1<C, D, P>;
     /**
      * Dependencies on other handlers (tables, queues, etc.).
      * Typed clients are injected into the handler via the `deps` argument.
@@ -614,9 +619,9 @@ type DefineHttpOptions<T = undefined, C = undefined, D extends Record<string, An
     /**
      * SSM Parameter Store parameters.
      * Declare with `param()` helper. Values are fetched and cached at cold start.
-     * Typed values are injected into the handler via the `params` argument.
+     * Typed values are injected into the handler via the `config` argument.
      */
-    params?: P;
+    config?: P;
     /**
      * Static file glob patterns to bundle into the Lambda ZIP.
      * Files are accessible at runtime via the `readStatic` callback argument.
@@ -631,12 +636,12 @@ type DefineHttpOptions<T = undefined, C = undefined, D extends Record<string, An
  */
 type HttpHandler<T = undefined, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = {
     readonly __brand: "effortless-http";
-    readonly config: HttpConfig;
+    readonly __spec: HttpConfig;
     readonly schema?: (input: unknown) => T;
     readonly onError?: (error: unknown, req: HttpRequest) => HttpResponse;
-    readonly context?: (...args: any[]) => C | Promise<C>;
+    readonly setup?: (...args: any[]) => C | Promise<C>;
     readonly deps?: D;
-    readonly params?: P;
+    readonly config?: P;
     readonly static?: string[];
     readonly onRequest: HttpHandlerFn<T, C, D, P, S>;
 };
@@ -644,10 +649,10 @@ type HttpHandler<T = undefined, C = undefined, D = undefined, P = undefined, S e
  * Define an HTTP endpoint that creates an API Gateway route + Lambda function
  *
  * @typeParam T - Type of the validated request body (inferred from schema function)
- * @typeParam C - Type of the context/dependencies (inferred from context function)
+ * @typeParam C - Type of the setup result (inferred from setup function)
  * @typeParam D - Type of the deps (from deps declaration)
  * @typeParam P - Type of the params (from params declaration)
- * @param options - Configuration, optional schema, optional context factory, and request handler
+ * @param options - Configuration, optional schema, optional setup factory, and request handler
  * @returns Handler object used by the deployment system
  *
  * @example Basic GET endpoint
@@ -669,15 +674,15 @@ type HttpHandler<T = undefined, C = undefined, D = undefined, P = undefined, S e
  * export const api = defineHttp({
  *   method: "GET",
  *   path: "/orders",
- *   params: {
+ *   config: {
  *     dbUrl: param("database-url"),
  *   },
- *   context: async ({ params }) => ({
- *     pool: createPool(params.dbUrl),
+ *   setup: async ({ config }) => ({
+ *     pool: createPool(config.dbUrl),
  *   }),
- *   onRequest: async ({ req, ctx, params }) => ({
+ *   onRequest: async ({ req, ctx, config }) => ({
  *     status: 200,
- *     body: { dbUrl: params.dbUrl }
+ *     body: { dbUrl: config.dbUrl }
  *   })
  * });
  * ```
@@ -705,7 +710,7 @@ type AppConfig = LambdaConfig & {
  */
 type AppHandler = {
     readonly __brand: "effortless-app";
-    readonly config: AppConfig;
+    readonly __spec: AppConfig;
 };
 /**
  * Deploy a static site via Lambda + API Gateway.
@@ -747,7 +752,7 @@ type StaticSiteConfig = {
  */
 type StaticSiteHandler = {
     readonly __brand: "effortless-static-site";
-    readonly config: StaticSiteConfig;
+    readonly __spec: StaticSiteConfig;
 };
 /**
  * Deploy a static site via S3 + CloudFront CDN.
@@ -825,13 +830,15 @@ type FifoQueueConfig = LambdaWithPermissions & {
     contentBasedDeduplication?: boolean;
 };
 /**
- * Context factory type — conditional on whether params are declared.
- * Without params: `() => C | Promise<C>`
- * With params: `(args: { params: ResolveParams<P> }) => C | Promise<C>`
+ * Setup factory type — conditional on whether deps/config are declared.
+ * No deps/config: `() => C | Promise<C>`
+ * With deps/config: `(args: { deps?, config? }) => C | Promise<C>`
  */
-type ContextFactory<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (args: {
-    params: ResolveParams<P & {}>;
-}) => C | Promise<C>;
+type SetupFactory<C, D, P> = [D | P] extends [undefined] ? () => C | Promise<C> : (args: ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P & {}>;
+})) => C | Promise<C>;
 /**
  * Per-message handler function.
  * Called once per message in the batch. Failures are reported individually.
@@ -843,7 +850,7 @@ type FifoQueueMessageFn<T = unknown, C = undefined, D = undefined, P = undefined
 }) & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
-    params: ResolveParams<P>;
+    config: ResolveConfig<P>;
 }) & ([S] extends [undefined] ? {} : {
     readStatic: (path: string) => string;
 })) => Promise<void>;
@@ -858,7 +865,7 @@ type FifoQueueBatchFn<T = unknown, C = undefined, D = undefined, P = undefined,
 }) & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
-    params: ResolveParams<P>;
+    config: ResolveConfig<P>;
 }) & ([S] extends [undefined] ? {} : {
     readStatic: (path: string) => string;
 })) => Promise<void>;
@@ -875,11 +882,11 @@ type DefineFifoQueueBase<T = unknown, C = undefined, D = undefined, P = undefine
      */
     onError?: (error: unknown) => void;
     /**
-     * Factory function to create context/dependencies for the handler.
+     * Factory function to initialize shared state for the handler.
      * Called once on cold start, result is cached and reused across invocations.
-     * When params are declared, receives resolved params as argument.
+     * When deps/params are declared, receives them as argument.
      */
-    context?: ContextFactory<C, P>;
+    setup?: SetupFactory<C, D, P>;
     /**
      * Dependencies on other handlers (tables, queues, etc.).
      * Typed clients are injected into the handler via the `deps` argument.
@@ -889,7 +896,7 @@ type DefineFifoQueueBase<T = unknown, C = undefined, D = undefined, P = undefine
      * SSM Parameter Store parameters.
      * Declare with `param()` helper. Values are fetched and cached at cold start.
      */
-    params?: P;
+    config?: P;
     /**
      * Static file glob patterns to bundle into the Lambda ZIP.
      * Files are accessible at runtime via the `readStatic` callback argument.
@@ -913,12 +920,12 @@ type DefineFifoQueueOptions<T = unknown, C = undefined, D extends Record<string,
  */
 type FifoQueueHandler<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = {
     readonly __brand: "effortless-fifo-queue";
-    readonly config: FifoQueueConfig;
+    readonly __spec: FifoQueueConfig;
     readonly schema?: (input: unknown) => T;
     readonly onError?: (error: unknown) => void;
-    readonly context?: (...args: any[]) => C | Promise<C>;
+    readonly setup?: (...args: any[]) => C | Promise<C>;
     readonly deps?: D;
-    readonly params?: P;
+    readonly config?: P;
     readonly static?: string[];
     readonly onMessage?: FifoQueueMessageFn<T, C, D, P, S>;
     readonly onBatch?: FifoQueueBatchFn<T, C, D, P, S>;
@@ -955,4 +962,4 @@ type FifoQueueHandler<T = unknown, C = undefined, D = undefined, P = undefined,
  */
 declare const defineFifoQueue: <T = unknown, C = undefined, D extends Record<string, AnyTableHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineFifoQueueOptions<T, C, D, P, S>) => FifoQueueHandler<T, C, D, P, S>;
 
-export { type AppConfig, type AppHandler, type ContentType, type DefineFifoQueueOptions, type DefineHttpOptions, type DefineTableOptions, type EffortlessConfig, type FailedRecord, type FifoQueueBatchFn, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type FifoQueueMessageFn, type HttpConfig, type HttpHandler, type HttpHandlerFn, type HttpMethod, type HttpRequest, type HttpResponse, type KeyType, type LambdaConfig, type LambdaWithPermissions, type LogLevel, type ParamRef, type QueryParams, type ResolveDeps$1 as ResolveDeps, type ResolveParams, type StaticSiteConfig, type StaticSiteHandler, type StreamView, type TableBatchCompleteFn, type TableBatchFn, type TableClient, type TableConfig, type TableHandler, type TableKey, type TableRecord, type TableRecordFn, defineApp, defineConfig, defineFifoQueue, defineHttp, defineStaticSite, defineTable, param, typed };
+export { type AppConfig, type AppHandler, type ContentType, type DefineFifoQueueOptions, type DefineHttpOptions, type DefineTableOptions, type EffortlessConfig, type FailedRecord, type FifoQueueBatchFn, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type FifoQueueMessageFn, type HttpConfig, type HttpHandler, type HttpHandlerFn, type HttpMethod, type HttpRequest, type HttpResponse, type KeyType, type LambdaConfig, type LambdaWithPermissions, type LogLevel, type ParamRef, type QueryParams, type ResolveConfig, type ResolveDeps$1 as ResolveDeps, type StaticSiteConfig, type StaticSiteHandler, type StreamView, type TableBatchCompleteFn, type TableBatchFn, type TableClient, type TableConfig, type TableHandler, type TableKey, type TableRecord, type TableRecordFn, defineApp, defineConfig, defineFifoQueue, defineHttp, defineStaticSite, defineTable, param, typed };

package/dist/index.js

@@ -3,15 +3,15 @@ var defineConfig = (config) => config;
 
 // src/handlers/define-http.ts
 var defineHttp = (options) => {
-  const { onRequest, onError, context, schema, deps, params, static: staticFiles, ...config } = options;
+  const { onRequest, onError, setup, schema, deps, config, static: staticFiles, ...__spec } = options;
   return {
     __brand: "effortless-http",
-    config,
+    __spec,
     ...schema ? { schema } : {},
     ...onError ? { onError } : {},
-    ...context ? { context } : {},
+    ...setup ? { setup } : {},
     ...deps ? { deps } : {},
-    ...params ? { params } : {},
+    ...config ? { config } : {},
     ...staticFiles ? { static: staticFiles } : {},
     onRequest
   };
@@ -19,15 +19,15 @@ var defineHttp = (options) => {
 
 // src/handlers/define-table.ts
 var defineTable = (options) => {
-  const { onRecord, onBatchComplete, onBatch, onError, schema, context, deps, params, static: staticFiles, ...config } = options;
+  const { onRecord, onBatchComplete, onBatch, onError, schema, setup, deps, config, static: staticFiles, ...__spec } = options;
   return {
     __brand: "effortless-table",
-    config,
+    __spec,
     ...schema ? { schema } : {},
     ...onError ? { onError } : {},
-    ...context ? { context } : {},
+    ...setup ? { setup } : {},
     ...deps ? { deps } : {},
-    ...params ? { params } : {},
+    ...config ? { config } : {},
     ...staticFiles ? { static: staticFiles } : {},
     ...onRecord ? { onRecord } : {},
     ...onBatchComplete ? { onBatchComplete } : {},
@@ -38,26 +38,26 @@ var defineTable = (options) => {
 // src/handlers/define-app.ts
 var defineApp = (options) => ({
   __brand: "effortless-app",
-  config: options
+  __spec: options
 });
 
 // src/handlers/define-static-site.ts
 var defineStaticSite = (options) => ({
   __brand: "effortless-static-site",
-  config: options
+  __spec: options
 });
 
 // src/handlers/define-fifo-queue.ts
 var defineFifoQueue = (options) => {
-  const { onMessage, onBatch, onError, schema, context, deps, params, static: staticFiles, ...config } = options;
+  const { onMessage, onBatch, onError, schema, setup, deps, config, static: staticFiles, ...__spec } = options;
   return {
     __brand: "effortless-fifo-queue",
-    config,
+    __spec,
     ...schema ? { schema } : {},
     ...onError ? { onError } : {},
-    ...context ? { context } : {},
+    ...setup ? { setup } : {},
     ...deps ? { deps } : {},
-    ...params ? { params } : {},
+    ...config ? { config } : {},
     ...staticFiles ? { static: staticFiles } : {},
     ...onMessage ? { onMessage } : {},
     ...onBatch ? { onBatch } : {}