effortless-aws 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,14 @@
 # effortless-aws
 
-Code-first AWS Lambda framework. Export handlers, deploy to AWS. No infrastructure files needed.
+AWS serverless is the best way to run production software. Lambda gives you 99.95% availability out of the box, scales to zero, handles thousands of concurrent requests, and you never manage a server. DynamoDB, SQS, S3, EventBridge — these are battle-tested building blocks with guarantees most self-hosted infrastructure can't match. The event-driven model maps naturally to real business logic: an order is placed, a file is uploaded, a record changes.
+
+The problem is never AWS itself — it's the tooling. CloudFormation templates, IAM policies, Terraform state files, CDK constructs. You end up spending more time on infrastructure plumbing than on your actual product. And even when infrastructure is sorted out, wiring serverless resources together — connecting a Lambda to a DynamoDB stream, granting cross-service permissions, passing table names between functions — is tedious and error-prone.
+
+**Effortless** is a TypeScript framework for developers who build on AWS serverless. It handles three things:
+
+1. **Infrastructure from code.** You write handlers, export them, and deploy. The framework derives Lambda functions, API Gateway routes, DynamoDB tables, streams, and IAM roles directly from your TypeScript exports. No config files.
+2. **Bundling and packaging.** Your code is automatically bundled with [esbuild](https://esbuild.github.io/) — tree-shaken, split per function, with shared dependencies extracted into a common [Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html). No build config to maintain.
+3. **Typed cross-resource communication.** Reference one handler from another with `deps: { orders }` and get a fully typed client injected at runtime, with IAM permissions wired automatically. Serverless resources talk to each other through code, not through copied ARNs and manual policies.
 
 ```bash
 npm install effortless-aws
@@ -9,32 +17,13 @@ npm install effortless-aws
 ## What it looks like
 
 ```typescript
-// src/api.ts
-import { defineHttp, defineTable, param } from "effortless-aws";
-
-// DynamoDB table — just export it, get the table
-export const orders = defineTable<Order>({
-  pk: { name: "id", type: "string" },
-  onRecord: async ({ record, table }) => {
-    if (record.eventName === "INSERT") {
-      await table.put({ ...record.new!, status: "confirmed" });
-    }
-  },
-});
+import { defineHttp } from "effortless-aws";
 
-// HTTP endpoint — creates API Gateway + Lambda + route
-export const createOrder = defineHttp({
-  method: "POST",
-  path: "/orders",
-  schema: (input) => parseOrder(input),
-  deps: { orders },
-  params: { apiKey: param("stripe-key") },
-  context: async ({ params }) => ({
-    stripe: new Stripe(params.apiKey),
-  }),
-  onRequest: async ({ data, ctx, deps }) => {
-    await deps.orders.put({ id: crypto.randomUUID(), ...data });
-    return { status: 201, body: { ok: true } };
+export const hello = defineHttp({
+  method: "GET",
+  path: "/hello",
+  onRequest: async () => {
+    return { status: 200, body: { message: "Hello!" } };
   },
 });
 ```
@@ -43,7 +32,7 @@ export const createOrder = defineHttp({
 npx eff deploy
 ```
 
-That's it. No YAML, no CloudFormation, no state files.
+That's it — one export, one command. No YAML, no CloudFormation, no state files.
 
 ## Why
 
@@ -69,34 +58,105 @@ Traditional Lambda development splits infrastructure and code across multiple fi
 
 **Cold start caching** — `context` factory runs once per cold start, cached across invocations. Put DB connections, SDK clients, config there.
 
-## Handler types
+## Examples
 
-### HTTP
+### Path params
 
 ```typescript
 export const getUser = defineHttp({
   method: "GET",
   path: "/users/{id}",
   onRequest: async ({ req }) => {
-    return { status: 200, body: { id: req.params.id } };
+    const user = await findUser(req.params.id);
+    return { status: 200, body: user };
+  },
+});
+```
+
+> Creates: Lambda function, API Gateway `GET /users/{id}` route, IAM execution role.
+
+### Schema validation
+
+Works with any validation library — Zod, Effect Schema, or a plain function.
+
+```typescript
+export const createUser = defineHttp({
+  method: "POST",
+  path: "/users",
+  schema: (input) => parseUser(input),
+  onRequest: async ({ data }) => {
+    // data is typed from schema return type
+    return { status: 201, body: { id: data.id } };
+  },
+});
+```
+
+### Context (cold-start cache)
+
+`context` runs once per cold start. Put SDK clients, DB connections, config here.
+
+```typescript
+export const listOrders = defineHttp({
+  method: "GET",
+  path: "/orders",
+  context: () => ({
+    db: new DatabaseClient(),
+  }),
+  onRequest: async ({ ctx }) => {
+    const orders = await ctx.db.findAll();
+    return { status: 200, body: orders };
   },
 });
 ```
 
-### DynamoDB Table + Stream
+### SSM params
+
+`param("key")` reads from Parameter Store at cold start. Auto IAM, auto caching.
+
+```typescript
+export const charge = defineHttp({
+  method: "POST",
+  path: "/charge",
+  params: { apiKey: param("stripe-key") },
+  context: async ({ params }) => ({
+    stripe: new Stripe(params.apiKey),
+  }),
+  onRequest: async ({ ctx, data }) => {
+    await ctx.stripe.charges.create(data);
+    return { status: 200, body: { ok: true } };
+  },
+});
+```
+
+> Creates: Lambda, API Gateway route, IAM role with `ssm:GetParameter` on `/{project}/{stage}/stripe-key`.
+
+### Cross-handler deps
+
+`deps: { orders }` auto-wires IAM and injects a typed `TableClient`.
 
 ```typescript
-export const users = defineTable({
+type Order = { id: string; name: string };
+
+export const orders = defineTable<Order>({
   pk: { name: "id", type: "string" },
-  sk: { name: "email", type: "string" },
-  ttlAttribute: "expiresAt",
-  onRecord: async ({ record, table }) => {
-    console.log(record.eventName, record.new);
+});
+
+export const createOrder = defineHttp({
+  method: "POST",
+  path: "/orders",
+  deps: { orders },
+  onRequest: async ({ deps }) => {
+    await deps.orders.put({ id: crypto.randomUUID(), name: "New order" });
+    return { status: 201, body: { ok: true } };
   },
 });
 ```
 
-### Table (resource only, no stream)
+> Creates: DynamoDB table, Lambda, API Gateway route. The Lambda's IAM role gets DynamoDB read/write permissions on the `orders` table automatically. Table name is injected via environment variable.
+
+### DynamoDB table (resource only)
+
+Export a table — get the DynamoDB resource. No Lambda, no stream.
 
 ```typescript
 export const sessions = defineTable({
@@ -105,6 +165,61 @@ export const sessions = defineTable({
 });
 ```
 
+> Creates: DynamoDB table with TTL enabled. No Lambda, no stream — just the table.
+
+### DynamoDB table with stream
+
+Add `onRecord` to process changes. Each record is handled individually with automatic partial batch failure reporting.
+
+```typescript
+type User = { id: string; email: string; name: string };
+
+export const users = defineTable<User>({
+  pk: { name: "id", type: "string" },
+  sk: { name: "email", type: "string" },
+  onRecord: async ({ record }) => {
+    if (record.eventName === "INSERT") {
+      await sendWelcomeEmail(record.new!.email);
+    }
+  },
+});
+```
+
+> Creates: DynamoDB table with stream enabled, Lambda for stream processing, event source mapping between them, IAM role with DynamoDB read/write permissions. Failed records are reported individually via [partial batch responses](https://docs.aws.amazon.com/lambda/latest/dg/with-ddb.html#services-ddb-batchfailurereporting).
+
+### Full example
+
+Everything together — table, HTTP handler with validation, deps, params, and context.
+
+```typescript
+type Order = { id: string; total: number; chargeId?: string };
+
+export const orders = defineTable<Order>({
+  pk: { name: "id", type: "string" },
+  onRecord: async ({ record }) => {
+    if (record.eventName === "INSERT") {
+      await notifyWarehouse(record.new!);
+    }
+  },
+});
+
+export const createOrder = defineHttp({
+  method: "POST",
+  path: "/orders",
+  schema: (input) => parseOrder(input),
+  deps: { orders },
+  params: { apiKey: param("stripe-key") },
+  context: async ({ params }) => ({
+    stripe: new Stripe(params.apiKey),
+  }),
+  onRequest: async ({ data, ctx, deps }) => {
+    const charge = await ctx.stripe.charges.create({ amount: data.total });
+    await deps.orders.put({ id: crypto.randomUUID(), ...data, chargeId: charge.id });
+    return { status: 201, body: { ok: true } };
+  },
+});
+```
+
 ## Configuration
 
 ```typescript

package/dist/{chunk-7JVA4742.js → chunk-AHRNISIY.js}

@@ -113,6 +113,8 @@ var computeTtl = (ttlSeconds = DEFAULT_TTL_SECONDS) => Math.floor(Date.now() / 1
 
 // src/runtime/handler-utils.ts
 import { randomUUID } from "crypto";
+import { readFileSync } from "fs";
+import { join } from "path";
 
 // src/runtime/ssm-client.ts
 import { SSM } from "@aws-sdk/client-ssm";
@@ -253,6 +255,7 @@ var buildParams = async (params) => {
   }
   return result;
 };
+var readStatic = (filePath) => readFileSync(join(process.cwd(), filePath), "utf-8");
 var createHandlerRuntime = (handler, handlerType) => {
   const platform = createPlatformClient();
   const handlerName = process.env.EFF_HANDLER ?? "unknown";
@@ -280,6 +283,7 @@ var createHandlerRuntime = (handler, handlerType) => {
     if (deps) args.deps = deps;
     const params = await getParams();
     if (params) args.params = params;
+    if (handler.static) args.readStatic = readStatic;
     return args;
   };
   const logExecution = (startTime, input, output) => {

package/dist/cli/index.js

@@ -70498,7 +70498,7 @@ var parseSource = (source) => {
   const project2 = new Project({ useInMemoryFileSystem: true });
   return project2.createSourceFile("input.ts", source);
 };
-var RUNTIME_PROPS = ["onRequest", "onRecord", "onBatchComplete", "onBatch", "context", "schema", "onError", "deps", "params"];
+var RUNTIME_PROPS = ["onRequest", "onRecord", "onBatchComplete", "onBatch", "context", "schema", "onError", "deps", "params", "static"];
 var buildConfigWithoutRuntime = (obj) => {
   const props = obj.getProperties().filter((p3) => {
     if (p3.getKind() === SyntaxKind.PropertyAssignment) {
@@ -70572,6 +70572,19 @@ var extractParamEntries = (obj) => {
   }
   return entries2;
 };
+var extractStaticGlobs = (obj) => {
+  const staticProp = obj.getProperties().find((p3) => {
+    if (p3.getKind() === SyntaxKind.PropertyAssignment) {
+      return p3.getName() === "static";
+    }
+    return false;
+  });
+  if (!staticProp || staticProp.getKind() !== SyntaxKind.PropertyAssignment) return [];
+  const init = staticProp.getInitializer();
+  if (!init || init.getKind() !== SyntaxKind.ArrayLiteralExpression) return [];
+  const arrayLiteral = init;
+  return arrayLiteral.getElements().filter((e) => e.getKind() === SyntaxKind.StringLiteral).map((e) => e.asKindOrThrow(SyntaxKind.StringLiteral).getLiteralValue());
+};
 var handlerRegistry = {
   http: {
     defineFn: "defineHttp",
@@ -70605,7 +70618,8 @@ var extractHandlerConfigs = (source, type2) => {
           const hasHandler = handlerProps.some((p3) => extractPropertyFromObject(objLiteral, p3) !== void 0);
           const depsKeys = extractDepsKeys(objLiteral);
           const paramEntries = extractParamEntries(objLiteral);
-          results.push({ exportName: "default", config: configObj, hasHandler, depsKeys, paramEntries });
+          const staticGlobs = extractStaticGlobs(objLiteral);
+          results.push({ exportName: "default", config: configObj, hasHandler, depsKeys, paramEntries, staticGlobs });
         }
       }
     }
@@ -70626,7 +70640,8 @@ var extractHandlerConfigs = (source, type2) => {
         const hasHandler = handlerProps.some((p3) => extractPropertyFromObject(objLiteral, p3) !== void 0);
         const depsKeys = extractDepsKeys(objLiteral);
         const paramEntries = extractParamEntries(objLiteral);
-        results.push({ exportName: decl.getName(), config: configObj, hasHandler, depsKeys, paramEntries });
+        const staticGlobs = extractStaticGlobs(objLiteral);
+        results.push({ exportName: decl.getName(), config: configObj, hasHandler, depsKeys, paramEntries, staticGlobs });
       }
     });
   });
@@ -70687,8 +70702,27 @@ var zip12 = (input) => Effect_exports.async((resume2) => {
   archive.on("end", () => resume2(Effect_exports.succeed(Buffer.concat(chunks2))));
   archive.on("error", (err) => resume2(Effect_exports.fail(err)));
   archive.append(input.content, { name: input.filename ?? "index.mjs", date: FIXED_DATE2 });
+  if (input.staticFiles) {
+    for (const file6 of input.staticFiles) {
+      archive.append(file6.content, { name: file6.zipPath, date: FIXED_DATE2 });
+    }
+  }
   archive.finalize();
 });
+var resolveStaticFiles = (globs, projectDir) => {
+  const files = [];
+  for (const pattern2 of globs) {
+    const matches = globSync(pattern2, { cwd: projectDir });
+    for (const match18 of matches) {
+      const absPath = path5.join(projectDir, match18);
+      files.push({
+        content: fsSync2.readFileSync(absPath),
+        zipPath: match18
+      });
+    }
+  }
+  return files;
+};
 var findHandlerFiles = (patterns, cwd) => {
   const files = /* @__PURE__ */ new Set();
   for (const pattern2 of patterns) {
@@ -70750,7 +70784,8 @@ var deployCoreLambda = ({
   layerArn,
   external,
   depsEnv,
-  depsPermissions
+  depsPermissions,
+  staticGlobs
 }) => Effect_exports.gen(function* () {
   const tagCtx = {
     project: input.project,
@@ -70779,7 +70814,8 @@ var deployCoreLambda = ({
     ...bundleType ? { type: bundleType } : {},
     ...external && external.length > 0 ? { external } : {}
   });
-  const code2 = yield* zip12({ content: bundled });
+  const staticFiles = staticGlobs && staticGlobs.length > 0 ? resolveStaticFiles(staticGlobs, input.projectDir) : void 0;
+  const code2 = yield* zip12({ content: bundled, staticFiles });
   const environment2 = {
     EFF_PROJECT: input.project,
     EFF_STAGE: tagCtx.stage,
@@ -70803,7 +70839,7 @@ var deployCoreLambda = ({
 });
 
 // src/deploy/deploy-http.ts
-var deployLambda = ({ input, fn: fn2, layerArn, external, depsEnv, depsPermissions }) => Effect_exports.gen(function* () {
+var deployLambda = ({ input, fn: fn2, layerArn, external, depsEnv, depsPermissions, staticGlobs }) => Effect_exports.gen(function* () {
   const { exportName, config: config2 } = fn2;
   const handlerName = config2.name ?? exportName;
   const { functionArn } = yield* deployCoreLambda({
@@ -70817,7 +70853,8 @@ var deployLambda = ({ input, fn: fn2, layerArn, external, depsEnv, depsPermissio
     ...layerArn ? { layerArn } : {},
     ...external ? { external } : {},
     ...depsEnv ? { depsEnv } : {},
-    ...depsPermissions ? { depsPermissions } : {}
+    ...depsPermissions ? { depsPermissions } : {},
+    ...staticGlobs && staticGlobs.length > 0 ? { staticGlobs } : {}
   });
   return { exportName, functionArn, config: config2, handlerName };
 });
@@ -70940,7 +70977,7 @@ var deployAll = (input) => Effect_exports.gen(function* () {
 
 // src/deploy/deploy-table.ts
 var TABLE_DEFAULT_PERMISSIONS = ["dynamodb:*", "logs:*"];
-var deployTableFunction = ({ input, fn: fn2, layerArn, external, depsEnv, depsPermissions }) => Effect_exports.gen(function* () {
+var deployTableFunction = ({ input, fn: fn2, layerArn, external, depsEnv, depsPermissions, staticGlobs }) => Effect_exports.gen(function* () {
   const { exportName, config: config2 } = fn2;
   const handlerName = config2.name ?? exportName;
   const tagCtx = {
@@ -70971,7 +71008,8 @@ var deployTableFunction = ({ input, fn: fn2, layerArn, external, depsEnv, depsPe
     ...layerArn ? { layerArn } : {},
     ...external ? { external } : {},
     depsEnv: selfEnv,
-    ...depsPermissions ? { depsPermissions } : {}
+    ...depsPermissions ? { depsPermissions } : {},
+    ...staticGlobs && staticGlobs.length > 0 ? { staticGlobs } : {}
   });
   yield* Effect_exports.logInfo("Setting up event source mapping...");
   yield* ensureEventSourceMapping({
@@ -71184,7 +71222,8 @@ var deployHttpHandlers = (ctx) => Effect_exports.gen(function* () {
         ...ctx.layerArn ? { layerArn: ctx.layerArn } : {},
         ...ctx.external.length > 0 ? { external: ctx.external } : {},
         depsEnv: withPlatform.depsEnv,
-        depsPermissions: withPlatform.depsPermissions
+        depsPermissions: withPlatform.depsPermissions,
+        ...fn2.staticGlobs.length > 0 ? { staticGlobs: fn2.staticGlobs } : {}
       }).pipe(
         Effect_exports.provide(
           clients_exports.makeClients({
@@ -71240,7 +71279,8 @@ var deployTableHandlers = (ctx) => Effect_exports.gen(function* () {
         ...ctx.layerArn ? { layerArn: ctx.layerArn } : {},
         ...ctx.external.length > 0 ? { external: ctx.external } : {},
         depsEnv: withPlatform.depsEnv,
-        depsPermissions: withPlatform.depsPermissions
+        depsPermissions: withPlatform.depsPermissions,
+        ...fn2.staticGlobs.length > 0 ? { staticGlobs: fn2.staticGlobs } : {}
       }).pipe(
         Effect_exports.provide(
           clients_exports.makeClients({