effortless-aws 0.0.2 → 0.1.0

package/README.md

@@ -0,0 +1,153 @@
+# effortless-aws
+
+Code-first AWS Lambda framework. Export handlers, deploy to AWS. No infrastructure files needed.
+
+```bash
+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" });
+    }
+  },
+});
+
+// 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 } };
+  },
+});
+```
+
+```bash
+npx eff deploy
+```
+
+That's it. No YAML, no CloudFormation, no state files.
+
+## Why
+
+Traditional Lambda development splits infrastructure and code across multiple files and languages. Adding a single endpoint means touching CloudFormation/CDK/Terraform templates, IAM policies, and handler code separately.
+
+**Effortless** derives infrastructure from your TypeScript exports. One `defineHttp` call creates the API Gateway route, Lambda function, and IAM role. One `defineTable` call creates the DynamoDB table, stream, event source mapping, and processor Lambda.
+
+## Killer features
+
+**Infrastructure from code** — export a handler, get the AWS resources. No config files, no YAML.
+
+**Typed everything** — `defineTable` schema gives you typed `table.put()`, typed `deps.orders.get()`, typed `record.new`. One definition, types flow everywhere.
+
+**Direct AWS SDK deploys** — no CloudFormation, no Pulumi. Direct API calls. Deploy in ~5-10s, not 5-10 minutes.
+
+**No state files** — AWS resource tags are the source of truth. No tfstate, no S3 backends, no drift.
+
+**Cross-handler deps** — `deps: { orders }` auto-wires IAM permissions and injects a typed `TableClient`. Zero config.
+
+**SSM params** — `param("stripe-key")` fetches from Parameter Store at cold start. Auto IAM, auto caching, supports transforms.
+
+**Partial batch failures** — DynamoDB stream processing reports failed records individually. No batch-level retries for one bad record.
+
+**Cold start caching** — `context` factory runs once per cold start, cached across invocations. Put DB connections, SDK clients, config there.
+
+## Handler types
+
+### HTTP
+
+```typescript
+export const getUser = defineHttp({
+  method: "GET",
+  path: "/users/{id}",
+  onRequest: async ({ req }) => {
+    return { status: 200, body: { id: req.params.id } };
+  },
+});
+```
+
+### DynamoDB Table + Stream
+
+```typescript
+export const users = defineTable({
+  pk: { name: "id", type: "string" },
+  sk: { name: "email", type: "string" },
+  ttlAttribute: "expiresAt",
+  onRecord: async ({ record, table }) => {
+    console.log(record.eventName, record.new);
+  },
+});
+```
+
+### Table (resource only, no stream)
+
+```typescript
+export const sessions = defineTable({
+  pk: { name: "id", type: "string" },
+  ttlAttribute: "expiresAt",
+});
+```
+
+## Configuration
+
+```typescript
+// effortless.config.ts
+import { defineConfig } from "effortless-aws";
+
+export default defineConfig({
+  name: "my-app",
+  region: "eu-central-1",
+  handlers: ["src/**/*.ts"],
+});
+```
+
+## CLI
+
+```bash
+npx eff deploy              # deploy all handlers
+npx eff deploy --stage prod # deploy to specific stage
+npx eff deploy --only users # deploy single handler
+npx eff destroy             # remove all resources
+npx eff logs users --follow # stream CloudWatch logs
+npx eff list                # show deployed resources
+```
+
+## How it works
+
+1. **Static analysis** (ts-morph) — reads your exports, extracts handler config from AST
+2. **Bundle** (esbuild) — wraps each handler with a runtime adapter
+3. **Deploy** (AWS SDK) — creates/updates Lambda, API Gateway, DynamoDB, IAM directly
+
+No CloudFormation stacks. No Terraform state. Tags on AWS resources are the only state.
+
+## Compared to
+
+| | SST v3 | Nitric | Serverless | **Effortless** |
+|---|---|---|---|---|
+| Infra from code (not config) | No | Yes | No | **Yes** |
+| Typed client from schema | No | No | No | **Yes** |
+| No state files | No | No | No | **Yes** |
+| Deploy speed | ~30s | ~30s | minutes | **~5-10s** |
+| Runs in your AWS account | Yes | Yes | Yes | **Yes** |
+| Open source | Yes | Yes | Yes | **Yes** |
+
+## License
+
+MIT

package/dist/chunk-I5TS7O5S.js

@@ -0,0 +1,163 @@
+// src/runtime/table-client.ts
+import { DynamoDB } from "@aws-sdk/client-dynamodb";
+import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
+var createTableClient = (tableName) => {
+  let client2 = null;
+  const getClient2 = () => client2 ??= new DynamoDB({});
+  return {
+    tableName,
+    async put(item) {
+      await getClient2().putItem({
+        TableName: tableName,
+        Item: marshall(item, { removeUndefinedValues: true })
+      });
+    },
+    async get(key) {
+      const result = await getClient2().getItem({
+        TableName: tableName,
+        Key: marshall(key, { removeUndefinedValues: true })
+      });
+      return result.Item ? unmarshall(result.Item) : void 0;
+    },
+    async delete(key) {
+      await getClient2().deleteItem({
+        TableName: tableName,
+        Key: marshall(key, { removeUndefinedValues: true })
+      });
+    },
+    async update(key, actions) {
+      const names = {};
+      const values = {};
+      const setClauses = [];
+      const removeClauses = [];
+      let counter = 0;
+      if (actions.set) {
+        for (const [attr, val] of Object.entries(actions.set)) {
+          const alias = `#a${counter}`;
+          const valAlias = `:v${counter}`;
+          names[alias] = attr;
+          values[valAlias] = val;
+          setClauses.push(`${alias} = ${valAlias}`);
+          counter++;
+        }
+      }
+      if (actions.append) {
+        for (const [attr, val] of Object.entries(actions.append)) {
+          const alias = `#a${counter}`;
+          const valAlias = `:v${counter}`;
+          const emptyAlias = `:empty${counter}`;
+          names[alias] = attr;
+          values[valAlias] = val;
+          values[emptyAlias] = [];
+          setClauses.push(`${alias} = list_append(if_not_exists(${alias}, ${emptyAlias}), ${valAlias})`);
+          counter++;
+        }
+      }
+      if (actions.remove) {
+        for (const attr of actions.remove) {
+          const alias = `#a${counter}`;
+          names[alias] = attr;
+          removeClauses.push(alias);
+          counter++;
+        }
+      }
+      const parts = [];
+      if (setClauses.length) parts.push(`SET ${setClauses.join(", ")}`);
+      if (removeClauses.length) parts.push(`REMOVE ${removeClauses.join(", ")}`);
+      if (!parts.length) return;
+      await getClient2().updateItem({
+        TableName: tableName,
+        Key: marshall(key, { removeUndefinedValues: true }),
+        UpdateExpression: parts.join(" "),
+        ExpressionAttributeNames: names,
+        ...Object.keys(values).length ? { ExpressionAttributeValues: marshall(values, { removeUndefinedValues: true }) } : {}
+      });
+    },
+    async query(params) {
+      const names = { "#pk": params.pk.name };
+      const values = { ":pk": params.pk.value };
+      let keyCondition = "#pk = :pk";
+      if (params.sk) {
+        names["#sk"] = params.sk.name;
+        values[":sk"] = params.sk.value;
+        if (params.sk.condition === "begins_with") {
+          keyCondition += " AND begins_with(#sk, :sk)";
+        } else {
+          keyCondition += ` AND #sk ${params.sk.condition} :sk`;
+        }
+      }
+      const result = await getClient2().query({
+        TableName: tableName,
+        KeyConditionExpression: keyCondition,
+        ExpressionAttributeNames: names,
+        ExpressionAttributeValues: marshall(values, { removeUndefinedValues: true }),
+        ...params.limit ? { Limit: params.limit } : {},
+        ...params.scanIndexForward !== void 0 ? { ScanIndexForward: params.scanIndexForward } : {}
+      });
+      return (result.Items ?? []).map((item) => unmarshall(item));
+    }
+  };
+};
+
+// src/runtime/ssm-client.ts
+import { SSM } from "@aws-sdk/client-ssm";
+var client = null;
+var getClient = () => client ??= new SSM({});
+var getParameters = async (names) => {
+  const map = /* @__PURE__ */ new Map();
+  for (let i = 0; i < names.length; i += 10) {
+    const batch = names.slice(i, i + 10);
+    const result = await getClient().getParameters({
+      Names: batch,
+      WithDecryption: true
+    });
+    for (const p of result.Parameters ?? []) {
+      if (p.Name && p.Value !== void 0) {
+        map.set(p.Name, p.Value);
+      }
+    }
+  }
+  return map;
+};
+
+// src/runtime/handler-utils.ts
+var ENV_TABLE_PREFIX = "EFF_TABLE_";
+var ENV_PARAM_PREFIX = "EFF_PARAM_";
+var buildDeps = (deps) => {
+  if (!deps) return void 0;
+  const result = {};
+  for (const key of Object.keys(deps)) {
+    const tableName = process.env[`${ENV_TABLE_PREFIX}${key}`];
+    if (!tableName) {
+      throw new Error(`Missing environment variable ${ENV_TABLE_PREFIX}${key} for dep "${key}"`);
+    }
+    result[key] = createTableClient(tableName);
+  }
+  return result;
+};
+var buildParams = async (params) => {
+  if (!params) return void 0;
+  const entries = [];
+  for (const propName of Object.keys(params)) {
+    const ssmPath = process.env[`${ENV_PARAM_PREFIX}${propName}`];
+    if (!ssmPath) {
+      throw new Error(`Missing environment variable ${ENV_PARAM_PREFIX}${propName} for param "${propName}"`);
+    }
+    entries.push({ propName, ssmPath });
+  }
+  if (entries.length === 0) return void 0;
+  const values = await getParameters(entries.map((e) => e.ssmPath));
+  const result = {};
+  for (const { propName, ssmPath } of entries) {
+    const raw = values.get(ssmPath) ?? "";
+    const ref = params[propName];
+    result[propName] = ref?.transform ? ref.transform(raw) : raw;
+  }
+  return result;
+};
+
+export {
+  createTableClient,
+  buildDeps,
+  buildParams
+};