aws-lambda-devkit 0.1.0

package/docs/configuration.md

@@ -0,0 +1,652 @@
+# Configuration reference
+
+Everything you can put in **`lamkit.config.js`** (or `.mjs`, `.cjs`, `.ts`). Lamkit reads this file on every command and validates it with clear error messages.
+
+**Tip:** Run `lamkit config worker` after editing to see the merged result.
+
+---
+
+## Where the config file lives
+
+Lamkit searches the current directory (or `--cwd`) for the first match:
+
+1. `lamkit.config.ts`
+2. `lamkit.config.js`
+3. `lamkit.config.mjs`
+4. `lamkit.config.cjs`
+
+```bash
+# Run from the config directory
+cd my-lambda-worker
+npx lamkit test
+
+# Or point at another folder
+npx lamkit test --cwd ./packages/worker-service
+```
+
+---
+
+## Config file formats
+
+### JavaScript (default)
+
+**`lamkit.config.js`:**
+
+```js
+export default {
+  functions: [
+    { name: 'worker', entry: './dist/handler.js', trigger: 'sqs' },
+  ],
+};
+```
+
+### CommonJS
+
+**`lamkit.config.cjs`:**
+
+```js
+module.exports = {
+  functions: [
+    { name: 'worker', entry: './dist/handler.js', trigger: 'sqs' },
+  ],
+};
+```
+
+### TypeScript
+
+Requires optional peer `tsx`:
+
+```bash
+npm install -D tsx
+```
+
+**`lamkit.config.ts`:**
+
+```ts
+import { defineConfig } from 'aws-lambda-devkit';
+
+export default defineConfig({
+  defaults: {
+    aws: { region: 'us-east-1' },
+  },
+  functions: [
+    {
+      name: 'worker',
+      entry: './dist/handler.js',
+      trigger: 'sqs',
+    },
+  ],
+});
+```
+
+`defineConfig()` wraps your config with full TypeScript types. **Hover any key** (`entry`, `trigger`, `assetLinks`, …) in VS Code / Cursor for field descriptions, examples, and allowed values.
+
+Types are also available without importing runtime code:
+
+```ts
+import type { FunctionConfig, LamkitConfigInput } from 'aws-lambda-devkit/config';
+```
+
+See also `templates/lamkit.config.ts` in the package (copy after `lamkit init`).
+
+---
+
+## Full config shape
+
+```js
+export default {
+  // Shared defaults for all functions
+  defaults: {
+    runtime: 'nodejs20.x',
+    memorySize: 512,
+    timeout: 30,
+    logFormat: 'text',
+    tracing: false,
+    aws: {
+      region: 'us-east-1',
+      endpoint: undefined,
+    },
+  },
+
+  // Optional: symlink local asset folders before invoke
+  assetLinks: [
+    { path: 'contracts', target: 'src/contracts' },
+  ],
+
+  // One object per Lambda you want to test
+  functions: [
+    {
+      name: 'worker',
+      entry: './dist/handler.js',
+      trigger: 'sqs',
+      memorySize: 1024,
+      timeout: 120,
+      logFormat: 'json',
+      test: { data: { id: 'default' } },
+      aws: {
+        region: 'eu-west-1',
+        queueUrl: process.env.WORKER_QUEUE_URL,
+        topicArn: process.env.EVENTS_TOPIC_ARN,
+        endpoint: undefined,
+      },
+    },
+  ],
+};
+```
+
+### Single-function shortcut
+
+If you only have one Lambda, you can flatten the config:
+
+```js
+export default {
+  name: 'worker',
+  entry: './src/handler.js',
+  trigger: 'sqs',
+  test: { data: { id: '1' } },
+};
+```
+
+Lamkit converts this internally to `functions: [{ name: 'worker', ... }]`. If you omit `name`, it becomes `default`.
+
+---
+
+## `defaults` — shared settings
+
+Apply to every function unless the function overrides the same field.
+
+```js
+export default {
+  defaults: {
+    runtime: 'nodejs20.x',   // shown in logs
+    memorySize: 512,         // MB — used in REPORT line
+    timeout: 30,             // seconds — handler killed after this
+    logFormat: 'text',        // 'text' | 'json'
+    tracing: false,          // X-Ray fields in REPORT when true
+    aws: {
+      region: 'us-east-1',   // event region + SDK default
+      endpoint: undefined,   // optional custom endpoint for send/listen
+    },
+  },
+  functions: [/* ... */],
+};
+```
+
+**Example — JSON logs for all functions:**
+
+```js
+export default {
+  defaults: { logFormat: 'json' },
+  functions: [
+    { name: 'worker', entry: './src/handler.js', trigger: 'sqs' },
+  ],
+};
+```
+
+**Example — one function overrides timeout:**
+
+```js
+export default {
+  defaults: { timeout: 30 },
+  functions: [
+    {
+      name: 'slow-worker',
+      entry: './dist/slow.js',
+      trigger: 'sqs',
+      timeout: 300,
+    },
+  ],
+};
+```
+
+| Field | Default if omitted |
+|-------|-------------------|
+| `runtime` | `nodejs20.x` |
+| `memorySize` | `512` |
+| `timeout` | `30` |
+| `logFormat` | `text` |
+| `tracing` | `false` |
+| `aws.region` | `process.env.AWS_REGION` → `us-east-1` |
+
+---
+
+## `functions[]` — one entry per Lambda
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | CLI name: `lamkit test worker` |
+| `entry` | Yes | Path to module that exports `handler` |
+| `trigger` | No | Event builder (`sqs` default) |
+| `memorySize` | No | Overrides `defaults.memorySize` |
+| `timeout` | No | Overrides `defaults.timeout` |
+| `logFormat` | No | Overrides `defaults.logFormat` |
+| `test.data` | No | Default `--data` when CLI omits it |
+| `aws.*` | No | Queue/topic/region for send, listen, realistic ARNs |
+
+### `entry` — which file to load
+
+| Your setup | Set `entry` to |
+|------------|----------------|
+| Plain JavaScript | `./src/handler.js` |
+| Compiled TypeScript | `./dist/handler.js` (after `npm run build`) |
+| TypeScript via tsx | `./src/handler.ts` (requires `tsx` peer) |
+
+Handler module **must** export:
+
+```js
+export const handler = async (event, context) => {
+  // ...
+};
+```
+
+### `test.data` — default payload
+
+```js
+{
+  name: 'worker',
+  entry: './src/handler.js',
+  trigger: 'sqs',
+  test: {
+    data: {
+      type: 'ORDER_CREATED',
+      orderId: 'ord_local_1',
+    },
+  },
+}
+```
+
+```bash
+npx lamkit test
+# same payload as: npx lamkit test --data '{"type":"ORDER_CREATED",...}'
+```
+
+CLI `--data` always wins over `test.data`.
+
+---
+
+## `trigger` — event types for `lamkit test`
+
+The `trigger` field tells lamkit how to turn your `--data` JSON into a full AWS event.
+
+### `sqs` (default)
+
+**Config:**
+
+```js
+{ name: 'worker', entry: './dist/handler.js', trigger: 'sqs' }
+```
+
+**Handler pattern:**
+
+```js
+export const handler = async (event) => {
+  for (const record of event.Records) {
+    const body = JSON.parse(record.body);
+    console.log(body);
+  }
+};
+```
+
+**CLI:**
+
+```bash
+npx lamkit test --data '{"orderId":"1"}'
+npx lamkit test --data '{"orderId":"1"}' --batch-size 3
+npx lamkit test --data '[{"a":1},{"a":2}]'
+```
+
+**`--data` meaning:** JSON object (or array) stored in `Records[].body` as a string.
+
+If `aws.queueUrl` is set, lamkit also sets a realistic `eventSourceARN` on each record.
+
+---
+
+### `http` (API Gateway)
+
+**Config:**
+
+```js
+{ name: 'api', entry: './dist/http.js', trigger: 'http' }
+```
+
+**Handler pattern:**
+
+```js
+export const handler = async (event) => {
+  console.log(event.httpMethod, event.path);
+  console.log('Body:', event.body);
+  return {
+    statusCode: 200,
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ ok: true }),
+  };
+};
+```
+
+**CLI:**
+
+```bash
+npx lamkit test api --data '{"username":"ada"}'
+```
+
+**`--data` meaning:** HTTP request body (lamkit wraps it in an API Gateway proxy event).
+
+---
+
+### `sns`
+
+**Config:**
+
+```js
+{ name: 'subscriber', entry: './dist/handler.js', trigger: 'sns' }
+```
+
+**CLI:**
+
+```bash
+npx lamkit test subscriber --data '{"alert":"cpu high"}'
+```
+
+**`--data` meaning:** SNS `Message` string (object is JSON-stringified).
+
+---
+
+### `s3`, `eventbridge`, `schedule`
+
+```js
+{ name: 'on-upload', entry: './dist/handler.js', trigger: 's3' }
+{ name: 'on-bus', entry: './dist/handler.js', trigger: 'eventbridge' }
+{ name: 'cron', entry: './dist/handler.js', trigger: 'schedule' }
+```
+
+```bash
+npx lamkit test on-upload --data '{"key":"uploads/file.pdf"}'
+npx lamkit test on-bus --data '{"orderId":"1","status":"shipped"}'
+npx lamkit test cron --data '{}'
+```
+
+For full control, skip the builder and use a captured event:
+
+```bash
+npx lamkit test worker --event events/captured-from-cloudwatch.json
+```
+
+---
+
+## `aws` block — real queues and topics
+
+Only required for **`lamkit send`** and **`lamkit listen`**. Optional for `lamkit test` (improves SQS ARN realism).
+
+```js
+export default {
+  defaults: {
+    aws: { region: 'us-east-1' },
+  },
+  functions: [
+    {
+      name: 'worker',
+      entry: './dist/handler.js',
+      trigger: 'sqs',
+      aws: {
+        queueUrl: process.env.WORKER_QUEUE_URL,
+      },
+    },
+    {
+      name: 'notifier',
+      entry: './dist/notify.js',
+      trigger: 'sns',
+      aws: {
+        topicArn: process.env.EVENTS_TOPIC_ARN,
+      },
+    },
+  ],
+};
+```
+
+**`.env` example:**
+
+```env
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=AKIA...
+AWS_SECRET_ACCESS_KEY=...
+WORKER_QUEUE_URL=https://sqs.us-east-1.amazonaws.com/123456789012/dev-worker
+EVENTS_TOPIC_ARN=arn:aws:sns:us-east-1:123456789012:dev-events
+```
+
+**Custom endpoint** (private cloud / compatible API):
+
+```js
+defaults: {
+  aws: {
+    region: 'us-east-1',
+    endpoint: process.env.AWS_ENDPOINT_URL,
+  },
+},
+```
+
+---
+
+## `assetLinks` — local files your `dist/` code expects
+
+### The problem
+
+Compiled code often loads files relative to its own path:
+
+```
+dist/services/connector.js  →  require('../../contracts/abi.json')
+                              resolves to  ./contracts/abi.json
+```
+
+In your Docker image, `contracts/` is copied next to `dist/`. In git, files may live under `src/contracts/` instead. Local invoke fails with `Cannot find module`.
+
+### The solution
+
+```js
+export default {
+  assetLinks: [
+    { path: 'contracts', target: 'src/contracts' },
+    { path: 'email-templates', target: 'src/templates' },
+  ],
+  functions: [
+    { name: 'worker', entry: './dist/handler.js', trigger: 'sqs' },
+  ],
+};
+```
+
+Before `test` or `listen`, lamkit creates a symlink:
+
+```
+contracts  →  src/contracts
+```
+
+If `contracts/` already exists, lamkit leaves it alone.
+
+| Field | Example | Meaning |
+|-------|---------|---------|
+| `path` | `contracts` | Where compiled code looks |
+| `target` | `src/contracts` | Where files live in dev |
+
+---
+
+## Environment variables
+
+### Auto-loaded `.env`
+
+By default lamkit loads **`.env`** from the project root (same directory as config).
+
+```env
+# .env
+AWS_REGION=us-east-1
+DATABASE_URL=postgres://localhost:5432/app
+WORKER_QUEUE_URL=https://sqs.us-east-1.amazonaws.com/123456789012/dev-worker
+LOG_LEVEL=debug
+```
+
+Rules:
+
+- `KEY=value` per line
+- `# comment`
+- Quotes allowed: `KEY="value with spaces"`
+
+**Never commit `.env`** — use `.env.example` with placeholder values.
+
+### `loadProjectEnv()` — monorepos and name mapping
+
+When the Lambda package is in a subfolder and `.env` lives at the repo root:
+
+**Layout:**
+
+```
+repo/
+├── .env
+└── services/
+    └── worker/
+        ├── lamkit.config.mjs
+        └── dist/handler.js
+```
+
+**`services/worker/lamkit.config.mjs`:**
+
+```js
+import { loadProjectEnv } from 'aws-lambda-devkit';
+
+loadProjectEnv({
+  files: ['../../.env'],
+  skipDotenv: true,
+  aliases: {
+    APP_DATABASE_NAME: 'DB_NAME',
+    APP_DATABASE_PORT: 'DB_PORT',
+    APP_DATABASE_HOST: 'DB_HOST',
+  },
+  rules: [
+    { when: { USE_SSL: 'true' }, set: { DB_SSL: 'true' } },
+    { when: { NODE_ENV: 'development' }, set: { LOG_LEVEL: 'debug' } },
+  ],
+});
+
+const region = process.env.AWS_REGION ?? 'us-east-1';
+
+export default {
+  defaults: { aws: { region } },
+  functions: [
+    {
+      name: 'worker',
+      entry: './dist/handler.js',
+      trigger: 'sqs',
+      aws: { queueUrl: process.env.WORKER_QUEUE_URL, region },
+    },
+  ],
+};
+```
+
+| Option | What it does |
+|--------|----------------|
+| `files` | Load these env files first (paths relative to config dir) |
+| `skipDotenv: true` | Do not load `./.env` inside the worker package |
+| `aliases` | If `APP_DATABASE_NAME` is set and `DB_NAME` is not, copy value |
+| `rules` | When all `when` keys match, set `set` keys (if not already set) |
+| `stripCustomEndpointForRealAws` | Default `true` — strips `AWS_ENDPOINT_URL*` when using real `AKIA*` keys |
+
+Call `loadProjectEnv()` **before** `export default { ... }` so `process.env` is ready when the config object is built.
+
+---
+
+## Payload priority (`lamkit test`)
+
+| Priority | Source |
+|----------|--------|
+| 1 (highest) | `--event file.json` |
+| 2 | `--data` or `--data-file` |
+| 3 | `functions[].test.data` |
+| 4 | Builder default for trigger |
+
+Example:
+
+```js
+// config has test.data: { id: 'from-config' }
+npx lamkit test --data '{"id":"from-cli"}'   // uses from-cli
+npx lamkit test                              // uses from-config
+```
+
+---
+
+## CLI flags (quick reference)
+
+Full examples: [Commands reference](commands.md)
+
+| Flag | Example |
+|------|---------|
+| `--cwd` | `lamkit test --cwd ./services/worker` |
+| `--data` | `lamkit test --data '{"id":"1"}'` |
+| `--data-file` | `lamkit test --data-file events/p.json` |
+| `--event` | `lamkit test --event events/raw.json` |
+| `--batch-size` | `lamkit test --batch-size 5` |
+| `--env` | `lamkit test --env KEY=val` |
+| `--dry-run` | `lamkit test --dry-run` |
+| `--reload` | `lamkit test --reload` |
+| `--strict-batch` | `lamkit test --strict-batch` |
+| `--queue-url` | `lamkit listen --queue-url 'https://sqs...'` |
+
+---
+
+## Complete production-like example
+
+```js
+import { defineConfig, loadProjectEnv } from 'aws-lambda-devkit';
+
+loadProjectEnv({
+  files: ['../.env'],
+  skipDotenv: true,
+  aliases: { SHARED_DB_NAME: 'DB_NAME' },
+});
+
+const region = process.env.AWS_REGION ?? 'us-east-1';
+
+export default defineConfig({
+  defaults: {
+    runtime: 'nodejs20.x',
+    memorySize: 512,
+    timeout: 30,
+    logFormat: 'text',
+    aws: { region },
+  },
+  assetLinks: [
+    { path: 'contracts', target: 'src/contracts' },
+  ],
+  functions: [
+    {
+      name: 'queue-worker',
+      entry: './dist/worker.js',
+      trigger: 'sqs',
+      timeout: 120,
+      memorySize: 1024,
+      aws: { queueUrl: process.env.WORKER_QUEUE_URL },
+      test: { data: { type: 'ORDER_CREATED', id: 'local-1' } },
+    },
+    {
+      name: 'http-api',
+      entry: './dist/api.js',
+      trigger: 'http',
+      test: { data: { action: 'health' } },
+    },
+    {
+      name: 'sns-handler',
+      entry: './dist/events.js',
+      trigger: 'sns',
+      aws: { topicArn: process.env.EVENTS_TOPIC_ARN },
+      test: { data: { event: 'USER_SIGNUP' } },
+    },
+  ],
+});
+```
+
+**Verify:**
+
+```bash
+npx lamkit list
+npx lamkit config queue-worker
+npx lamkit test queue-worker
+npx lamkit test --all
+```
+
+More scenarios: [Recipes](recipes.md)