aws-lambda-devkit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to **aws-lambda-devkit** are documented in this file.
+
+## [0.1.0] - 2026-06-23
+
+**Initial public release** of `aws-lambda-devkit` — a local development toolkit for Node.js AWS Lambda handlers.
+
+### Added
+
+#### CLI (`lamkit`)
+
+- `init` — scaffold `lamkit.config.js`, `.env.example`, sample event, VS Code launch config
+- `test` — invoke handlers locally with AWS-shaped events (no deploy required)
+- `list` — show registered functions from config
+- `config` — print resolved config (secrets redacted)
+- `send sqs` / `send sns` — publish to real dev queues/topics (optional AWS SDK peers)
+- `listen` — poll a real SQS queue and run the handler locally
+
+#### Local invoke & events
+
+- Simulated invokes for triggers: `sqs`, `http`, `sns`, `s3`, `eventbridge`, `schedule`
+- Plain Node.js handler loading — entry must export `handler` (or default export)
+- CloudWatch-style `START` / `END` / `REPORT` log output
+- Structured logging via `logFormat: 'json'` (global or per-function)
+- Handler module cache with `clearHandlerCache()` / `clearAllHandlerCaches()`
+- `lamkit test` flags: `--data`, `--data-file`, `@file`, `--event`, `--batch-size`, `--reload`, `--cold`, `--dry-run`, `--inspect-brk`, `--strict-batch`, `--env`, `--cwd`
+- `lamkit listen` flags: `--once`, `--expect-messages`, `--batch-invoke` (default), `--no-batch-invoke`, visibility timeout extension
+
+#### Configuration
+
+- Config loader for `lamkit.config.{js,mjs,cjs,ts}`
+- Zod validation with readable errors via `formatZodError()`
+- `defineConfig()` helper for TypeScript projects
+- `defaults` block — shared runtime, memory, timeout, region, log format
+- `functions[]` — multiple Lambdas in one config; single-function shorthand at root
+- `test.data` — default payload when CLI flags are omitted
+- `aws` block per function — `queueUrl`, `topicArn`, `region`, `endpoint`
+- **`loadProjectEnv()`** — load parent/shared `.env` files, env aliases, conditional rules, and safe endpoint stripping for real IAM keys
+- **`assetLinks`** — symlink dev asset folders (e.g. `contracts` → `src/contracts`) before handler load
+
+#### TypeScript & programmatic API
+
+- Documented public interfaces with JSDoc (`FunctionConfig`, `LamkitConfigInput`, `AssetLink`, `Trigger`, …)
+- Hover docs in editors when using `defineConfig()` in `lamkit.config.ts`
+- Type-only import path: `aws-lambda-devkit/config`
+- Exports: `buildSqsEvent`, `invokeHandler`, `ensureAssetLinks`, `parseConfig`, `loadProjectEnv`, and related helpers
+
+#### AWS (optional)
+
+- SQS send and long-poll listen via `@aws-sdk/client-sqs` peer
+- SNS publish via `@aws-sdk/client-sns` peer
+- FIFO queue support (`MessageGroupId`, `MessageDeduplicationId`)
+- Custom endpoint via `aws.endpoint` (LocalStack, private gateways)
+- SQS `MessageAttributes` preserved when building events from polled messages
+
+#### Documentation & templates
+
+- User guides in `docs/`: getting started, commands, configuration, recipes (22 scenarios), troubleshooting
+- `templates/lamkit.config.js` and `templates/lamkit.config.ts`
+- `templates/events/sample.json`, `.env.example`, `.vscode/launch.json`
+
+#### Quality
+
+- Unit tests for event builders, invoke pipeline, config loading, asset links, and SQS helpers
+
+### Notes
+
+- Complements SAM, CDK, and SST — does **not** deploy Lambdas or create AWS resources
+- Default install: 4 runtime dependencies (`zod`, `commander`, `picocolors`, `@types/aws-lambda`)
+- Optional peers: `@aws-sdk/client-sqs`, `@aws-sdk/client-sns`, `tsx`
+- Requires Node.js 20+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lambda DevKit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# Lambda DevKit
+
+**Test AWS Lambda handlers on your laptop** — same `handler` export, realistic events, CloudWatch-style logs. Optional real SQS/SNS against a dev account.
+
+| | Name |
+|---|------|
+| **npm package** | [`aws-lambda-devkit`](https://www.npmjs.com/package/aws-lambda-devkit) |
+| **CLI command** | `lamkit` |
+| **Config file** | `lamkit.config.js` (also `.mjs`, `.cjs`, `.ts`) |
+
+Install as a dev dependency. Complements SAM, CDK, and SST; does not deploy infrastructure.
+
+---
+
+## Documentation
+
+**New here?** Start with the guides below. They use plain language and generic examples only.
+
+| Guide | Description |
+|-------|-------------|
+| **[Getting started](docs/getting-started.md)** | Install → first successful `lamkit test` (~15 min walkthrough with sample output) |
+| **[Commands reference](docs/commands.md)** | Every CLI command and flag with copy-paste examples |
+| **[Configuration reference](docs/configuration.md)** | Every config field, `loadProjectEnv`, `assetLinks`, full examples |
+| **[Recipes](docs/recipes.md)** | 22 end-to-end setups with layouts, handlers, commands, and expected results |
+| **[Troubleshooting](docs/troubleshooting.md)** | Symptom → cause → fix for common errors |
+
+---
+
+## What this package does
+
+| Feature | Command | Needs AWS? |
+|---------|---------|------------|
+| Simulate invoke | `lamkit test` | No |
+| List / inspect config | `lamkit list`, `lamkit config` | No |
+| Send message to SQS | `lamkit send sqs` | Yes |
+| Poll SQS → local handler | `lamkit listen` | Yes |
+| Publish to SNS | `lamkit send sns` | Yes |
+| Scaffold project files | `lamkit init` | No |
+
+## What it does not do
+
+- Deploy Lambdas or create queues/topics
+- Replace SAM Docker emulation or full IaC workflows
+- Require changes inside your production handler code
+
+---
+
+## Five-minute quick start
+
+```bash
+npm install -D aws-lambda-devkit
+npx lamkit init
+cp .env.example .env
+```
+
+Create `src/lambda/handler.js`:
+
+```js
+export const handler = async (event) => {
+  console.log(event);
+  return { ok: true };
+};
+```
+
+`lamkit.config.js` (created by init):
+
+```js
+export default {
+  functions: [
+    {
+      name: 'worker',
+      entry: './src/lambda/handler.js',
+      trigger: 'sqs',
+    },
+  ],
+};
+```
+
+Run:
+
+```bash
+npx lamkit test --data '{"id":"1"}'
+```
+
+You should see `START`, your logs, `END`, and `REPORT` lines.
+
+**Next:** [Getting started](docs/getting-started.md) · [Recipes](docs/recipes.md)
+
+---
+
+## Config at a glance
+
+```js
+export default {
+  defaults: {
+    runtime: 'nodejs20.x',
+    memorySize: 512,
+    timeout: 30,
+    logFormat: 'text',
+    aws: { region: 'us-east-1' },
+  },
+  assetLinks: [
+    { path: 'contracts', target: 'src/contracts' },
+  ],
+  functions: [
+    {
+      name: 'worker',
+      entry: './dist/handler.js',
+      trigger: 'sqs',
+      aws: { queueUrl: process.env.WORKER_QUEUE_URL },
+      test: { data: { id: '1' } },
+    },
+  ],
+};
+```
+
+| Block | Purpose |
+|-------|---------|
+| `defaults` | Shared memory, timeout, region, log format |
+| `assetLinks` | Symlink local asset folders before invoke (see [docs](docs/configuration.md#assetlinks)) |
+| `functions` | One entry per Lambda; `entry` must export `handler` |
+
+**Monorepo / shared `.env`:** call `loadProjectEnv()` at the top of your config — [example in recipes](docs/recipes.md#recipe-10--monorepo-with-shared-root-env).
+
+Config file names: `lamkit.config.{js,mjs,cjs,ts}` (`.ts` needs optional `tsx` peer).
+
+---
+
+## Commands
+
+### Daily development
+
+```bash
+lamkit test [name] --data '{"key":"value"}'
+lamkit test --data-file events/payload.json
+lamkit test --event events/captured-sqs.json
+lamkit test --all
+lamkit test --inspect-brk
+lamkit list
+lamkit config [name]
+```
+
+### Real AWS (dev account only)
+
+```bash
+npm install -D @aws-sdk/client-sqs   # for send/listen
+lamkit send sqs worker --data '{"id":"1"}'
+lamkit listen worker --once
+```
+
+Use a **dev queue** — do not run `listen` against production while deployed Lambdas consume the same queue.
+
+Full command reference: [Commands](docs/commands.md)
+
+---
+
+## Optional peers
+
+| Install when… | Package |
+|---------------|---------|
+| TypeScript handler or `lamkit.config.ts` | `tsx` |
+| `lamkit send sqs` / `lamkit listen` | `@aws-sdk/client-sqs` |
+| `lamkit send sns` | `@aws-sdk/client-sns` |
+
+Default install is **4 small dependencies** (~5 MB): `zod`, `commander`, `picocolors`, `@types/aws-lambda`.
+
+---
+
+## Triggers (simulated `lamkit test`)
+
+| `trigger` | Event type |
+|-----------|------------|
+| `sqs` | SQS (default) |
+| `http` | API Gateway HTTP |
+| `sns` | SNS notification |
+| `s3` | S3 object event |
+| `eventbridge` | EventBridge |
+| `schedule` | Scheduled / cron |
+
+Examples per trigger: [Recipes](docs/recipes.md)
+
+---
+
+## vs SAM / SST
+
+| Tool | Best for |
+|------|----------|
+| **Lambda DevKit** | Fast edit-test loop on Node handlers; optional real SQS poll |
+| **SAM** | Docker parity, deploy, broader AWS emulation |
+| **SST `dev`** | Live AWS proxy tied to SST stacks |
+
+---
+
+## Programmatic API
+
+```ts
+import {
+  defineConfig,
+  loadProjectEnv,
+  buildSqsEvent,
+  ensureAssetLinks,
+} from 'aws-lambda-devkit';
+
+// Types only (no runtime import):
+import type { FunctionConfig, LamkitConfigInput } from 'aws-lambda-devkit/config';
+```
+
+Use `defineConfig()` in `lamkit.config.ts` so every config field shows docs on hover. Most users only need the CLI and `lamkit.config.*`.
+
+---
+
+## License
+
+MIT

package/dist/aws/batch-response.d.ts

@@ -0,0 +1,8 @@
+export type BatchItemFailure = {
+    itemIdentifier: string;
+};
+export declare function isBatchItemFailures(value: unknown): value is {
+    batchItemFailures: BatchItemFailure[];
+};
+export declare function countBatchItemFailures(result: unknown): number;
+//# sourceMappingURL=batch-response.d.ts.map

package/dist/aws/batch-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-response.d.ts","sourceRoot":"","sources":["../../src/aws/batch-response.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI;IAAE,iBAAiB,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAMpD;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAM9D"}

package/dist/aws/batch-response.js

@@ -0,0 +1,12 @@
+export function isBatchItemFailures(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        Array.isArray(value.batchItemFailures));
+}
+export function countBatchItemFailures(result) {
+    if (!isBatchItemFailures(result)) {
+        return 0;
+    }
+    return result.batchItemFailures.length;
+}
+//# sourceMappingURL=batch-response.js.map

package/dist/aws/batch-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-response.js","sourceRoot":"","sources":["../../src/aws/batch-response.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,mBAAmB,CACjC,KAAc;IAEd,OAAO,CACL,CAAC,CAAC,KAAK;QACP,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,OAAO,CAAE,KAAyC,CAAC,iBAAiB,CAAC,CAC5E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,MAAe;IACpD,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAC;QACjC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC;AACzC,CAAC"}

package/dist/aws/clients.d.ts

@@ -0,0 +1,6 @@
+export { MissingPeerError } from '../peer-resolve.js';
+export declare function importSqsSdk(cwd?: string): Promise<Record<string, unknown>>;
+export declare function importSnsSdk(cwd?: string): Promise<Record<string, unknown>>;
+export declare function loadSqsClient(region: string, cwd?: string, endpoint?: string): Promise<unknown>;
+export declare function loadSnsClient(region: string, cwd?: string, endpoint?: string): Promise<unknown>;
+//# sourceMappingURL=clients.d.ts.map

package/dist/aws/clients.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.d.ts","sourceRoot":"","sources":["../../src/aws/clients.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,wBAAsB,YAAY,CAAC,GAAG,GAAE,MAAsB,oCAE7D;AAED,wBAAsB,YAAY,CAAC,GAAG,GAAE,MAAsB,oCAE7D;AAMD,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,EAAE,QAAQ,CAAC,EAAE,MAAM,oBAQjG;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,EAAE,QAAQ,CAAC,EAAE,MAAM,oBAQjG"}

package/dist/aws/clients.js

@@ -0,0 +1,30 @@
+import { importPeerFromConsumer } from '../peer-resolve.js';
+export { MissingPeerError } from '../peer-resolve.js';
+export async function importSqsSdk(cwd = process.cwd()) {
+    return importPeerFromConsumer(cwd, '@aws-sdk/client-sqs', 'lamkit send sqs / lamkit listen');
+}
+export async function importSnsSdk(cwd = process.cwd()) {
+    return importPeerFromConsumer(cwd, '@aws-sdk/client-sns', 'lamkit send sns');
+}
+function resolveEndpoint(explicit) {
+    return explicit ?? process.env.AWS_ENDPOINT_URL;
+}
+export async function loadSqsClient(region, cwd = process.cwd(), endpoint) {
+    const { SQSClient } = await importSqsSdk(cwd);
+    const clientConfig = { region };
+    const resolvedEndpoint = resolveEndpoint(endpoint);
+    if (resolvedEndpoint) {
+        clientConfig.endpoint = resolvedEndpoint;
+    }
+    return new SQSClient(clientConfig);
+}
+export async function loadSnsClient(region, cwd = process.cwd(), endpoint) {
+    const { SNSClient } = await importSnsSdk(cwd);
+    const clientConfig = { region };
+    const resolvedEndpoint = resolveEndpoint(endpoint);
+    if (resolvedEndpoint) {
+        clientConfig.endpoint = resolvedEndpoint;
+    }
+    return new SNSClient(clientConfig);
+}
+//# sourceMappingURL=clients.js.map

package/dist/aws/clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.js","sourceRoot":"","sources":["../../src/aws/clients.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAc,OAAO,CAAC,GAAG,EAAE;IAC5D,OAAO,sBAAsB,CAAC,GAAG,EAAE,qBAAqB,EAAE,iCAAiC,CAAC,CAAC;AAC/F,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAc,OAAO,CAAC,GAAG,EAAE;IAC5D,OAAO,sBAAsB,CAAC,GAAG,EAAE,qBAAqB,EAAE,iBAAiB,CAAC,CAAC;AAC/E,CAAC;AAED,SAAS,eAAe,CAAC,QAAiB;IACxC,OAAO,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAc,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE,EAAE,QAAiB;IAChG,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;IAC9C,MAAM,YAAY,GAA0C,EAAE,MAAM,EAAE,CAAC;IACvE,MAAM,gBAAgB,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACnD,IAAI,gBAAgB,EAAE,CAAC;QACrB,YAAY,CAAC,QAAQ,GAAG,gBAAgB,CAAC;IAC3C,CAAC;IACD,OAAO,IAAK,SAA8C,CAAC,YAAY,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAc,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE,EAAE,QAAiB;IAChG,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;IAC9C,MAAM,YAAY,GAA0C,EAAE,MAAM,EAAE,CAAC;IACvE,MAAM,gBAAgB,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACnD,IAAI,gBAAgB,EAAE,CAAC;QACrB,YAAY,CAAC,QAAQ,GAAG,gBAAgB,CAAC;IAC3C,CAAC;IACD,OAAO,IAAK,SAA8C,CAAC,YAAY,CAAC,CAAC;AAC3E,CAAC"}

package/dist/aws/sns-publish.d.ts

@@ -0,0 +1,10 @@
+export type PublishSnsOptions = {
+    topicArn: string;
+    region: string;
+    cwd?: string;
+    endpoint?: string;
+    data?: unknown;
+    message?: string;
+};
+export declare function publishSnsMessage(options: PublishSnsOptions): Promise<string>;
+//# sourceMappingURL=sns-publish.d.ts.map

package/dist/aws/sns-publish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sns-publish.d.ts","sourceRoot":"","sources":["../../src/aws/sns-publish.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBnF"}

package/dist/aws/sns-publish.js

@@ -0,0 +1,17 @@
+import { importSnsSdk, loadSnsClient } from './clients.js';
+import { serializePayload } from '../events/util.js';
+export async function publishSnsMessage(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const { PublishCommand } = (await importSnsSdk(cwd));
+    const client = (await loadSnsClient(options.region, cwd, options.endpoint));
+    const message = options.message ?? serializePayload(options.data ?? { message: 'hello from lamkit' });
+    const response = (await client.send(new PublishCommand({
+        TopicArn: options.topicArn,
+        Message: message,
+    })));
+    if (!response.MessageId) {
+        throw new Error('Publish succeeded but no MessageId returned');
+    }
+    return response.MessageId;
+}
+//# sourceMappingURL=sns-publish.js.map

package/dist/aws/sns-publish.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sns-publish.js","sourceRoot":"","sources":["../../src/aws/sns-publish.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAWrD,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAA0B;IAChE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,EAAE,cAAc,EAAE,GAAG,CAAC,MAAM,YAAY,CAAC,GAAG,CAAC,CAElD,CAAC;IACF,MAAM,MAAM,GAAG,CAAC,MAAM,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAEzE,CAAC;IACF,MAAM,OAAO,GACX,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAExF,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,IAAI,CACjC,IAAI,cAAc,CAAC;QACjB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,OAAO,EAAE,OAAO;KACjB,CAAC,CACH,CAA2B,CAAC;IAE7B,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,QAAQ,CAAC,SAAS,CAAC;AAC5B,CAAC"}

package/dist/aws/sqs-listen.d.ts

@@ -0,0 +1,17 @@
+import type { MergedFunctionConfig } from '../config/merge.js';
+import { type ListenResult } from './sqs-process.js';
+export type { ListenResult, SqsMessage } from './sqs-process.js';
+export { buildSqsEventFromMessage, buildSqsEventFromMessages, countBatchItemFailures, isMessageFailed, processSqsMessages, queueArnFromUrl, } from './sqs-process.js';
+export type ListenOptions = {
+    fn: MergedFunctionConfig;
+    cwd?: string;
+    batchSize?: number;
+    batchInvoke?: boolean;
+    deleteOnSuccess?: boolean;
+    once?: boolean;
+    reload?: boolean;
+    extendVisibility?: boolean;
+    onMessage?: (messageId: string, status: 'success' | 'failure') => void;
+};
+export declare function listenSqsQueue(options: ListenOptions): Promise<ListenResult>;
+//# sourceMappingURL=sqs-listen.d.ts.map

package/dist/aws/sqs-listen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqs-listen.d.ts","sourceRoot":"","sources":["../../src/aws/sqs-listen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAQ/D,OAAO,EAGL,KAAK,YAAY,EAElB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,oBAAoB,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,SAAS,KAAK,IAAI,CAAC;CACxE,CAAC;AAEF,wBAAsB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAyJlF"}

package/dist/aws/sqs-listen.js

@@ -0,0 +1,113 @@
+import { loadHandler } from '../runtime/loader.js';
+import { clearAllHandlerCaches } from '../runtime/clear-caches.js';
+import { createVisibilityHeartbeat, resolveVisibilityExtensionSeconds, } from './sqs-visibility.js';
+import { importSqsSdk, loadSqsClient } from './clients.js';
+import { processSqsMessages, queueArnFromUrl, } from './sqs-process.js';
+export { buildSqsEventFromMessage, buildSqsEventFromMessages, countBatchItemFailures, isMessageFailed, processSqsMessages, queueArnFromUrl, } from './sqs-process.js';
+export async function listenSqsQueue(options) {
+    const cwd = options.cwd ?? process.cwd();
+    if (options.reload) {
+        clearAllHandlerCaches();
+    }
+    const { ReceiveMessageCommand, DeleteMessageCommand, ChangeMessageVisibilityCommand, GetQueueAttributesCommand } = (await importSqsSdk(cwd));
+    const client = (await loadSqsClient(options.fn.region, cwd, options.fn.aws.endpoint));
+    const queueUrl = options.fn.aws.queueUrl;
+    if (!queueUrl) {
+        throw new Error('queueUrl is required. Set functions[].aws.queueUrl in lamkit.config.js or pass --queue-url');
+    }
+    const batchSize = options.batchSize ?? 10;
+    const deleteOnSuccess = options.deleteOnSuccess ?? true;
+    const batchInvoke = options.batchInvoke ?? true;
+    const extendVisibility = options.extendVisibility ?? true;
+    const handler = await loadHandler(options.fn, cwd, { reload: options.reload });
+    const queueArn = queueArnFromUrl(queueUrl, options.fn.region);
+    let queueVisibilitySeconds = 30;
+    if (extendVisibility) {
+        try {
+            const attrs = (await client.send(new GetQueueAttributesCommand({
+                QueueUrl: queueUrl,
+                AttributeNames: ['VisibilityTimeout'],
+            })));
+            queueVisibilitySeconds = Number(attrs.Attributes?.VisibilityTimeout ?? 30);
+        }
+        catch {
+            queueVisibilitySeconds = 30;
+        }
+    }
+    const visibilitySeconds = resolveVisibilityExtensionSeconds(options.fn.timeout, queueVisibilitySeconds);
+    const visibilityHeartbeat = extendVisibility
+        ? createVisibilityHeartbeat({
+            visibilitySeconds,
+            extendVisibility: async (receiptHandles, seconds) => {
+                await Promise.all(receiptHandles.map((receiptHandle) => client.send(new ChangeMessageVisibilityCommand({
+                    QueueUrl: queueUrl,
+                    ReceiptHandle: receiptHandle,
+                    VisibilityTimeout: seconds,
+                }))));
+            },
+        })
+        : undefined;
+    let running = true;
+    const stop = () => {
+        running = false;
+    };
+    let processed = 0;
+    let failures = 0;
+    let messagesReceived = 0;
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    try {
+        while (running) {
+            const response = (await client.send(new ReceiveMessageCommand({
+                QueueUrl: queueUrl,
+                MaxNumberOfMessages: batchSize,
+                WaitTimeSeconds: 20,
+                MessageAttributeNames: ['All'],
+                AttributeNames: ['All'],
+            })));
+            const messages = response.Messages ?? [];
+            if (messages.length === 0) {
+                if (options.once) {
+                    break;
+                }
+                continue;
+            }
+            const batchResult = await processSqsMessages({
+                messages,
+                handler,
+                fn: options.fn,
+                queueArn,
+                region: options.fn.region,
+                batchInvoke,
+                deleteOnSuccess,
+                deleteMessage: async (receiptHandle) => {
+                    await client.send(new DeleteMessageCommand({
+                        QueueUrl: queueUrl,
+                        ReceiptHandle: receiptHandle,
+                    }));
+                },
+                onMessage: options.onMessage,
+                visibilityHeartbeat,
+            });
+            processed += batchResult.processed;
+            failures += batchResult.failures;
+            messagesReceived += batchResult.messagesReceived;
+            for (const line of batchResult.logs) {
+                console.log(line);
+            }
+            if (!running) {
+                break;
+            }
+            if (options.once) {
+                break;
+            }
+        }
+    }
+    finally {
+        process.off('SIGINT', stop);
+        process.off('SIGTERM', stop);
+        visibilityHeartbeat?.stop();
+    }
+    return { processed, failures, messagesReceived };
+}
+//# sourceMappingURL=sqs-listen.js.map

package/dist/aws/sqs-listen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqs-listen.js","sourceRoot":"","sources":["../../src/aws/sqs-listen.ts"],"names":[],"mappings":"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"}

package/dist/aws/sqs-process.d.ts

@@ -0,0 +1,39 @@
+import type { MergedFunctionConfig } from '../config/merge.js';
+import { queueArnFromUrl, type AwsSqsMessage } from '../events/sqs-record.js';
+import type { VisibilityHeartbeat } from '../aws/sqs-visibility.js';
+import type { Handler } from '../runtime/invoke.js';
+export type SqsMessage = AwsSqsMessage;
+export type ListenResult = {
+    processed: number;
+    failures: number;
+    messagesReceived: number;
+};
+export { isBatchItemFailures, countBatchItemFailures } from '../aws/batch-response.js';
+export declare function buildSqsRecordFromMessage(message: SqsMessage, queueArn: string, region: string): import("../events/sqs-record.js").SqsRecord;
+export declare function buildSqsEventFromMessage(message: SqsMessage, queueArn: string, region: string): {
+    Records: import("../events/sqs-record.js").SqsRecord[];
+};
+export declare function buildSqsEventFromMessages(messages: SqsMessage[], queueArn: string, region: string): {
+    Records: import("../events/sqs-record.js").SqsRecord[];
+};
+export declare function isMessageFailed(result: {
+    success: boolean;
+    result?: unknown;
+}, messageId: string): boolean;
+export type ProcessSqsMessagesOptions = {
+    messages: SqsMessage[];
+    handler: Handler;
+    fn: MergedFunctionConfig;
+    queueArn: string;
+    region: string;
+    batchInvoke?: boolean;
+    deleteOnSuccess?: boolean;
+    deleteMessage?: (receiptHandle: string) => Promise<void>;
+    onMessage?: (messageId: string, status: 'success' | 'failure') => void;
+    visibilityHeartbeat?: VisibilityHeartbeat;
+};
+export declare function processSqsMessages(options: ProcessSqsMessagesOptions): Promise<ListenResult & {
+    logs: string[];
+}>;
+export { queueArnFromUrl };
+//# sourceMappingURL=sqs-process.d.ts.map

package/dist/aws/sqs-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqs-process.d.ts","sourceRoot":"","sources":["../../src/aws/sqs-process.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,OAAO,EAEL,eAAe,EACf,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAGpD,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvF,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,+CAGf;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;;EAKf;AAED,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,UAAU,EAAE,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;;EAKf;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAU1G;AAED,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,EAAE,EAAE,oBAAoB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,SAAS,KAAK,IAAI,CAAC;IACvE,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C,CAAC;AAEF,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA6E5C;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}