@temporalio/lambda-worker 1.17.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2021-2025 Temporal Technologies Inc. All rights reserved.
+
+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,158 @@
+# lambda-worker
+
+A wrapper for running [Temporal](https://temporal.io) workers inside AWS Lambda. A single
+`runWorker` call handles the full per-invocation lifecycle: connecting to the Temporal server,
+creating a worker with Lambda-tuned defaults, polling for tasks, and gracefully shutting down before
+the invocation deadline.
+
+## Quick start
+
+```typescript
+// handler.ts
+import { runWorker } from '@temporalio/lambda-worker';
+import * as activities from './activities';
+
+export const handler = runWorker({ deploymentName: 'my-service', buildId: 'v1.0' }, (config) => {
+  config.workerOptions.taskQueue = 'my-task-queue';
+  config.workerOptions.workflowBundle = { code: require('./workflow-bundle.js') };
+  config.workerOptions.activities = activities;
+});
+```
+
+Prefer `workflowBundle` (pre-bundled with `bundleWorkflowCode`) over `workflowsPath` to avoid
+webpack bundling overhead on Lambda cold starts.
+
+## Configuration
+
+Client connection settings (address, namespace, TLS, API key) are loaded automatically from a TOML
+config file and/or environment variables via `@temporalio/envconfig`. The config file is resolved in
+order:
+
+1. `TEMPORAL_CONFIG_FILE` env var, if set.
+2. `temporal.toml` in `$LAMBDA_TASK_ROOT` (typically `/var/task`).
+3. `temporal.toml` in the current working directory.
+
+The file is optional -- if absent, only environment variables are used.
+
+The configure callback receives a `LambdaWorkerConfig` object with fields pre-populated with
+Lambda-appropriate defaults. Override any field directly in the callback. The `taskQueue` in
+`workerOptions` is pre-populated from the `TEMPORAL_TASK_QUEUE` environment variable if set.
+
+## Lambda-tuned worker defaults
+
+The package applies conservative concurrency limits suited to Lambda's resource constraints:
+
+| Setting                                | Default            |
+| -------------------------------------- | ------------------ |
+| `maxConcurrentActivityTaskExecutions`  | 2                  |
+| `maxConcurrentWorkflowTaskExecutions`  | 10                 |
+| `maxConcurrentLocalActivityExecutions` | 2                  |
+| `maxConcurrentNexusTaskExecutions`     | 5                  |
+| `workflowTaskPollerBehavior`           | `SimpleMaximum(2)` |
+| `activityTaskPollerBehavior`           | `SimpleMaximum(1)` |
+| `nexusTaskPollerBehavior`              | `SimpleMaximum(1)` |
+| `shutdownGraceTime`                    | 5 seconds          |
+| `maxCachedWorkflows`                   | 30                 |
+
+Worker Deployment Versioning is always enabled. The default versioning behavior is `PINNED`; to
+change it, override `workerDeploymentOptions.defaultVersioningBehavior` in the configure callback:
+
+```typescript
+config.workerOptions.workerDeploymentOptions = {
+  defaultVersioningBehavior: 'AUTO_UPGRADE',
+};
+```
+
+## Logging
+
+The Temporal `Runtime` is installed automatically by `runWorker`. If
+[`@aws-lambda-powertools/logger`](https://docs.aws.amazon.com/powertools/typescript/latest/features/logger/)
+is installed, the runtime is configured with a `PowertoolsLoggerAdapter` that produces structured
+JSON output automatically parsed by CloudWatch Logs. If Powertools is not installed, the SDK's
+default human-readable logger is used.
+
+To customize the logger or other runtime options, modify `config.runtimeOptions` in the configure
+callback:
+
+```typescript
+export const handler = runWorker({ deploymentName: 'my-service', buildId: 'v1.0' }, (config) => {
+  config.workerOptions.taskQueue = 'my-task-queue';
+  // Use a custom logger
+  config.runtimeOptions.logger = myCustomLogger;
+  // Or configure telemetry
+  config.runtimeOptions.telemetryOptions = { ... };
+});
+```
+
+Shutdown signals are disabled by default (`shutdownSignals: []`) since Lambda manages its own
+lifecycle.
+
+## Observability
+
+Metrics and tracing are opt-in. The `otel` module provides convenience helpers for
+[AWS Distro for OpenTelemetry (ADOT)](https://aws-otel.github.io/docs/getting-started/lambda).
+
+Call `applyDefaults(config)` in your configure callback to:
+
+- Register Temporal SDK interceptors (`@temporalio/interceptors-opentelemetry`) for tracing
+  Workflow, Activity, and Nexus calls.
+- Configure the Temporal Core SDK (Rust) to export its own metrics (task latencies, poll counts,
+  etc.) via OTLP to the collector.
+
+```typescript
+import { runWorker } from '@temporalio/lambda-worker';
+import { applyDefaults } from '@temporalio/lambda-worker/otel';
+import * as activities from './activities';
+
+export const handler = runWorker({ deploymentName: 'my-service', buildId: 'v1.0' }, (config) => {
+  applyDefaults(config);
+  config.workerOptions.taskQueue = 'my-task-queue';
+  config.workerOptions.workflowBundle = { code: require('./workflow-bundle.js') };
+  config.workerOptions.activities = activities;
+});
+```
+
+**Important**: When pre-bundling Workflow code with `bundleWorkflowCode()`, pass `makeOtelPlugin()`
+so that Workflow interceptor modules are included in the bundle:
+
+```typescript
+import { bundleWorkflowCode } from '@temporalio/worker';
+import { makeOtelPlugin } from '@temporalio/lambda-worker/otel';
+
+const { plugin } = makeOtelPlugin();
+const { code } = await bundleWorkflowCode({
+  workflowsPath: require.resolve('./workflows'),
+  plugins: [plugin],
+});
+```
+
+### AWS setup
+
+Attach two Lambda layers:
+
+1. **[ADOT JavaScript layer](https://aws-otel.github.io/docs/getting-started/lambda/lambda-js)** —
+   auto-instruments the handler and exports Node.js-side traces (Lambda invocation spans, HTTP
+   calls, etc.) to X-Ray.
+2. **[ADOT Collector layer](https://aws-otel.github.io/docs/getting-started/lambda)**
+   (`aws-otel-collector-amd64`) — runs the OTel Collector as a Lambda extension, receiving
+   Temporal Core SDK metrics and SDK trace spans via OTLP gRPC on `localhost:4317`, then
+   forwarding them to CloudWatch/X-Ray via a custom collector config.
+
+Set these environment variables:
+
+```
+AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument
+OPENTELEMETRY_COLLECTOR_CONFIG_URI=/var/task/otel-collector-config.yaml
+```
+
+`AWS_LAMBDA_EXEC_WRAPPER` enables the JS layer's auto-instrumentation.
+`OPENTELEMETRY_COLLECTOR_CONFIG_URI` points the collector at a custom config file bundled in
+your deployment package — use this to route metrics to CloudWatch EMF, traces to X-Ray, or any
+other supported exporter.
+
+Enable X-Ray active tracing on the Lambda function (required for traces to appear):
+
+```bash
+aws lambda update-function-configuration --function-name <function-name> \
+  --tracing-config Mode=Active
+```

package/lib/config.d.ts

@@ -0,0 +1,12 @@
+import { type ClientConnectConfig, type LoadClientProfileOptions } from '@temporalio/envconfig';
+/**
+ * Load client connection config with Lambda-aware config file resolution.
+ *
+ * Resolution order:
+ * 1. User-provided `configSource` in options (passthrough)
+ * 2. `TEMPORAL_CONFIG_FILE` env var (handled by envconfig)
+ * 3. `$LAMBDA_TASK_ROOT/temporal.toml`
+ * 4. `process.cwd()/temporal.toml`
+ * 5. Envconfig default (XDG paths / env-only)
+ */
+export declare function loadLambdaClientConnectConfig(options?: Partial<LoadClientProfileOptions>): ClientConnectConfig;

package/lib/config.js

@@ -0,0 +1,69 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadLambdaClientConnectConfig = loadLambdaClientConnectConfig;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const envconfig_1 = require("@temporalio/envconfig");
+/**
+ * Load client connection config with Lambda-aware config file resolution.
+ *
+ * Resolution order:
+ * 1. User-provided `configSource` in options (passthrough)
+ * 2. `TEMPORAL_CONFIG_FILE` env var (handled by envconfig)
+ * 3. `$LAMBDA_TASK_ROOT/temporal.toml`
+ * 4. `process.cwd()/temporal.toml`
+ * 5. Envconfig default (XDG paths / env-only)
+ */
+function loadLambdaClientConnectConfig(options) {
+    const resolvedOptions = { ...options };
+    // If the user provided a configSource or TEMPORAL_CONFIG_FILE is set, let envconfig handle it
+    if (!resolvedOptions.configSource && !process.env['TEMPORAL_CONFIG_FILE']) {
+        const lambdaConfigPath = findLambdaConfigFile();
+        if (lambdaConfigPath) {
+            resolvedOptions.configSource = { path: lambdaConfigPath };
+        }
+    }
+    return (0, envconfig_1.loadClientConnectConfig)(resolvedOptions);
+}
+function findLambdaConfigFile() {
+    const candidates = [];
+    const lambdaTaskRoot = process.env['LAMBDA_TASK_ROOT'];
+    if (lambdaTaskRoot) {
+        candidates.push(path.join(lambdaTaskRoot, 'temporal.toml'));
+    }
+    candidates.push(path.join(process.cwd(), 'temporal.toml'));
+    for (const candidate of candidates) {
+        try {
+            fs.accessSync(candidate, fs.constants.R_OK);
+            return candidate;
+        }
+        catch {
+            // File doesn't exist or isn't readable, try next
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=config.js.map

package/lib/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAkBA,sEAYC;AA9BD,4CAA8B;AAC9B,gDAAkC;AAClC,qDAI+B;AAE/B;;;;;;;;;GASG;AACH,SAAgB,6BAA6B,CAAC,OAA2C;IACvF,MAAM,eAAe,GAA6B,EAAE,GAAG,OAAO,EAAE,CAAC;IAEjE,8FAA8F;IAC9F,IAAI,CAAC,eAAe,CAAC,YAAY,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,EAAE,CAAC;QAC1E,MAAM,gBAAgB,GAAG,oBAAoB,EAAE,CAAC;QAChD,IAAI,gBAAgB,EAAE,CAAC;YACrB,eAAe,CAAC,YAAY,GAAG,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,OAAO,IAAA,mCAAuB,EAAC,eAAe,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,oBAAoB;IAC3B,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACvD,IAAI,cAAc,EAAE,CAAC;QACnB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC;IAE3D,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,EAAE,CAAC,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAC5C,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,iDAAiD;QACnD,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/lib/defaults.d.ts

@@ -0,0 +1,16 @@
+import type { WorkerOptions } from '@temporalio/worker';
+/** Minimum work time in ms — error if less. */
+export declare const MINIMUM_WORK_TIME_MS = 1000;
+/** Low work time threshold in ms — warn if less. */
+export declare const WARN_WORK_TIME_MS = 5000;
+/**
+ * Default buffer in ms before the Lambda deadline to begin shutdown.
+ * Equals the default shutdownGraceTime (5s) + 2s margin.
+ */
+export declare const DEFAULT_SHUTDOWN_DEADLINE_BUFFER_MS = 7000;
+/**
+ * Lambda-tuned worker defaults. These are conservative values appropriate for
+ * Lambda's memory and CPU constraints. Users can override any of these via the
+ * configure callback.
+ */
+export declare const LAMBDA_WORKER_DEFAULTS: Partial<WorkerOptions>;

package/lib/defaults.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LAMBDA_WORKER_DEFAULTS = exports.DEFAULT_SHUTDOWN_DEADLINE_BUFFER_MS = exports.WARN_WORK_TIME_MS = exports.MINIMUM_WORK_TIME_MS = void 0;
+/** Minimum work time in ms — error if less. */
+exports.MINIMUM_WORK_TIME_MS = 1000;
+/** Low work time threshold in ms — warn if less. */
+exports.WARN_WORK_TIME_MS = 5000;
+/**
+ * Default buffer in ms before the Lambda deadline to begin shutdown.
+ * Equals the default shutdownGraceTime (5s) + 2s margin.
+ */
+exports.DEFAULT_SHUTDOWN_DEADLINE_BUFFER_MS = 7000;
+/**
+ * Lambda-tuned worker defaults. These are conservative values appropriate for
+ * Lambda's memory and CPU constraints. Users can override any of these via the
+ * configure callback.
+ */
+exports.LAMBDA_WORKER_DEFAULTS = {
+    maxConcurrentActivityTaskExecutions: 2,
+    maxConcurrentWorkflowTaskExecutions: 10,
+    maxConcurrentLocalActivityExecutions: 2,
+    maxConcurrentNexusTaskExecutions: 5,
+    shutdownGraceTime: '5s',
+    maxCachedWorkflows: 30,
+    workflowTaskPollerBehavior: { type: 'simple-maximum', maximum: 2 },
+    activityTaskPollerBehavior: { type: 'simple-maximum', maximum: 1 },
+    nexusTaskPollerBehavior: { type: 'simple-maximum', maximum: 1 },
+};
+//# sourceMappingURL=defaults.js.map

package/lib/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":";;;AAEA,+CAA+C;AAClC,QAAA,oBAAoB,GAAG,IAAI,CAAC;AAEzC,oDAAoD;AACvC,QAAA,iBAAiB,GAAG,IAAI,CAAC;AAEtC;;;GAGG;AACU,QAAA,mCAAmC,GAAG,IAAI,CAAC;AAExD;;;;GAIG;AACU,QAAA,sBAAsB,GAA2B;IAC5D,mCAAmC,EAAE,CAAC;IACtC,mCAAmC,EAAE,EAAE;IACvC,oCAAoC,EAAE,CAAC;IACvC,gCAAgC,EAAE,CAAC;IACnC,iBAAiB,EAAE,IAAI;IACvB,kBAAkB,EAAE,EAAE;IACtB,0BAA0B,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAC,EAAE;IAClE,0BAA0B,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAC,EAAE;IAClE,uBAAuB,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAC,EAAE;CAChE,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export { runWorker } from './lambda-worker';
+export { PowertoolsLoggerAdapter } from './json-logger';
+export type { LambdaWorkerConfig, LambdaHandler, ShutdownHook } from './types';

package/lib/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PowertoolsLoggerAdapter = exports.runWorker = void 0;
+var lambda_worker_1 = require("./lambda-worker");
+Object.defineProperty(exports, "runWorker", { enumerable: true, get: function () { return lambda_worker_1.runWorker; } });
+var json_logger_1 = require("./json-logger");
+Object.defineProperty(exports, "PowertoolsLoggerAdapter", { enumerable: true, get: function () { return json_logger_1.PowertoolsLoggerAdapter; } });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,iDAA4C;AAAnC,0GAAA,SAAS,OAAA;AAClB,6CAAwD;AAA/C,sHAAA,uBAAuB,OAAA"}

package/lib/json-logger.d.ts

@@ -0,0 +1,29 @@
+import type { Logger as PowertoolsLogger } from '@aws-lambda-powertools/logger';
+import type { Context } from 'aws-lambda';
+import type { LogLevel, LogMetadata } from '@temporalio/common';
+import type { Logger } from '@temporalio/worker';
+/**
+ * Adapter that wraps an AWS Lambda Powertools Logger to implement the Temporal SDK Logger interface.
+ *
+ * This is used as the default logger for the Lambda worker, producing structured JSON output
+ * that CloudWatch Logs automatically parses.
+ *
+ * @example
+ * ```ts
+ * import { Logger } from '@aws-lambda-powertools/logger';
+ * import { PowertoolsLoggerAdapter } from '@temporalio/lambda-worker';
+ *
+ * const adapter = new PowertoolsLoggerAdapter(new Logger({ serviceName: 'my-worker' }));
+ * ```
+ */
+export declare class PowertoolsLoggerAdapter implements Logger {
+    private readonly ptLogger;
+    constructor(ptLogger: PowertoolsLogger);
+    addContext(context: Context): void;
+    log(level: LogLevel, message: string, meta?: LogMetadata): void;
+    trace(message: string, meta?: LogMetadata): void;
+    debug(message: string, meta?: LogMetadata): void;
+    info(message: string, meta?: LogMetadata): void;
+    warn(message: string, meta?: LogMetadata): void;
+    error(message: string, meta?: LogMetadata): void;
+}

package/lib/json-logger.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PowertoolsLoggerAdapter = void 0;
+/**
+ * Adapter that wraps an AWS Lambda Powertools Logger to implement the Temporal SDK Logger interface.
+ *
+ * This is used as the default logger for the Lambda worker, producing structured JSON output
+ * that CloudWatch Logs automatically parses.
+ *
+ * @example
+ * ```ts
+ * import { Logger } from '@aws-lambda-powertools/logger';
+ * import { PowertoolsLoggerAdapter } from '@temporalio/lambda-worker';
+ *
+ * const adapter = new PowertoolsLoggerAdapter(new Logger({ serviceName: 'my-worker' }));
+ * ```
+ */
+class PowertoolsLoggerAdapter {
+    ptLogger;
+    constructor(ptLogger) {
+        this.ptLogger = ptLogger;
+    }
+    addContext(context) {
+        this.ptLogger.addContext(context);
+    }
+    log(level, message, meta) {
+        switch (level) {
+            case 'TRACE':
+                this.ptLogger.debug(message, { ...meta, traceLevel: true });
+                break;
+            case 'DEBUG':
+                this.ptLogger.debug(message, meta);
+                break;
+            case 'INFO':
+                this.ptLogger.info(message, meta);
+                break;
+            case 'WARN':
+                this.ptLogger.warn(message, meta);
+                break;
+            case 'ERROR':
+                this.ptLogger.error(message, meta);
+                break;
+            default:
+                level;
+                break;
+        }
+    }
+    trace(message, meta) {
+        this.log('TRACE', message, meta);
+    }
+    debug(message, meta) {
+        this.log('DEBUG', message, meta);
+    }
+    info(message, meta) {
+        this.log('INFO', message, meta);
+    }
+    warn(message, meta) {
+        this.log('WARN', message, meta);
+    }
+    error(message, meta) {
+        this.log('ERROR', message, meta);
+    }
+}
+exports.PowertoolsLoggerAdapter = PowertoolsLoggerAdapter;
+//# sourceMappingURL=json-logger.js.map

package/lib/json-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-logger.js","sourceRoot":"","sources":["../src/json-logger.ts"],"names":[],"mappings":";;;AAKA;;;;;;;;;;;;;GAaG;AACH,MAAa,uBAAuB;IACL;IAA7B,YAA6B,QAA0B;QAA1B,aAAQ,GAAR,QAAQ,CAAkB;IAAG,CAAC;IAE3D,UAAU,CAAC,OAAgB;QACzB,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,GAAG,CAAC,KAAe,EAAE,OAAe,EAAE,IAAkB;QACtD,QAAQ,KAAK,EAAE,CAAC;YACd,KAAK,OAAO;gBACV,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC5D,MAAM;YACR,KAAK,OAAO;gBACV,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,IAA+B,CAAC,CAAC;gBAC9D,MAAM;YACR,KAAK,MAAM;gBACT,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,IAA+B,CAAC,CAAC;gBAC7D,MAAM;YACR,KAAK,MAAM;gBACT,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,IAA+B,CAAC,CAAC;gBAC7D,MAAM;YACR,KAAK,OAAO;gBACV,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,IAA+B,CAAC,CAAC;gBAC9D,MAAM;YACR;gBACE,KAAqB,CAAC;gBACtB,MAAM;QACV,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAkB;QACvC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAkB;QACvC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAAkB;QACtC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAAkB;QACtC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAkB;QACvC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;CACF;AAjDD,0DAiDC"}

package/lib/lambda-worker.d.ts

@@ -0,0 +1,51 @@
+import type { WorkerDeploymentVersion, Logger } from '@temporalio/common';
+import { type WorkerOptions, type NativeConnectionOptions, type RuntimeOptions } from '@temporalio/worker';
+import type { ClientConnectConfig } from '@temporalio/envconfig';
+import type { LambdaWorkerConfig, LambdaHandler } from './types';
+/**
+ * @internal Dependency injection interface for testing.
+ */
+export interface WorkerDeps {
+    connect: (options: NativeConnectionOptions) => Promise<{
+        close(): Promise<void>;
+    }>;
+    createWorker: (options: WorkerOptions) => Promise<{
+        runUntil(p: Promise<void>): Promise<void>;
+    }>;
+    loadConnectConfig: () => ClientConnectConfig;
+    installRuntime: (options: RuntimeOptions) => void;
+    getLogger: () => Logger;
+}
+/**
+ * Create an AWS Lambda handler that runs a Temporal Worker for the duration of each invocation.
+ *
+ * The handler connects to Temporal, creates a Worker, polls for tasks until the Lambda deadline
+ * approaches, then gracefully shuts down and runs any registered shutdown hooks.
+ *
+ * Calling this more than once will result in an error.
+ *
+ * @param version - The worker deployment version. Worker versioning is always enabled.
+ * @param configure - Callback to customize the pre-populated {@link LambdaWorkerConfig}.
+ *   Mutate the config object directly (e.g., set `config.workerOptions.taskQueue`).
+ * @returns A Lambda handler function.
+ *
+ * @example
+ * ```ts
+ * import { runWorker } from '@temporalio/lambda-worker';
+ * import * as activities from './activities';
+ *
+ * export const handler = runWorker(
+ *   { buildId: 'v1.0.0', deploymentName: 'my-service' },
+ *   (config) => {
+ *     config.workerOptions.taskQueue = 'my-task-queue';
+ *     config.workerOptions.workflowBundle = { code: require('./workflow-bundle.js') };
+ *     config.workerOptions.activities = activities;
+ *   },
+ * );
+ * ```
+ */
+export declare function runWorker(version: WorkerDeploymentVersion, configure: (config: LambdaWorkerConfig) => void): LambdaHandler;
+/**
+ * @internal Testable implementation of runWorker with injected dependencies.
+ */
+export declare function _runWorkerInternal(version: WorkerDeploymentVersion, configure: (config: LambdaWorkerConfig) => void, deps: WorkerDeps): LambdaHandler;

package/lib/lambda-worker.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWorker = runWorker;
+exports._runWorkerInternal = _runWorkerInternal;
+const promises_1 = require("timers/promises");
+const worker_1 = require("@temporalio/worker");
+const defaults_1 = require("./defaults");
+const config_1 = require("./config");
+const json_logger_1 = require("./json-logger");
+const logger_factory_1 = require("./logger-factory");
+const defaultDeps = {
+    connect: (opts) => worker_1.NativeConnection.connect(opts),
+    createWorker: (opts) => worker_1.Worker.create(opts),
+    loadConnectConfig: config_1.loadLambdaClientConnectConfig,
+    installRuntime: (opts) => worker_1.Runtime.install(opts),
+    getLogger: () => worker_1.Runtime.instance().logger,
+};
+/**
+ * Create an AWS Lambda handler that runs a Temporal Worker for the duration of each invocation.
+ *
+ * The handler connects to Temporal, creates a Worker, polls for tasks until the Lambda deadline
+ * approaches, then gracefully shuts down and runs any registered shutdown hooks.
+ *
+ * Calling this more than once will result in an error.
+ *
+ * @param version - The worker deployment version. Worker versioning is always enabled.
+ * @param configure - Callback to customize the pre-populated {@link LambdaWorkerConfig}.
+ *   Mutate the config object directly (e.g., set `config.workerOptions.taskQueue`).
+ * @returns A Lambda handler function.
+ *
+ * @example
+ * ```ts
+ * import { runWorker } from '@temporalio/lambda-worker';
+ * import * as activities from './activities';
+ *
+ * export const handler = runWorker(
+ *   { buildId: 'v1.0.0', deploymentName: 'my-service' },
+ *   (config) => {
+ *     config.workerOptions.taskQueue = 'my-task-queue';
+ *     config.workerOptions.workflowBundle = { code: require('./workflow-bundle.js') };
+ *     config.workerOptions.activities = activities;
+ *   },
+ * );
+ * ```
+ */
+function runWorker(version, configure) {
+    return _runWorkerInternal(version, configure, defaultDeps);
+}
+/**
+ * @internal Testable implementation of runWorker with injected dependencies.
+ */
+function _runWorkerInternal(version, configure, deps) {
+    const config = {
+        workerOptions: {
+            ...defaults_1.LAMBDA_WORKER_DEFAULTS,
+            workerDeploymentOptions: {
+                defaultVersioningBehavior: 'PINNED',
+            },
+        },
+        runtimeOptions: {
+            logger: (0, logger_factory_1.makePowertoolsLogger)(),
+            shutdownSignals: [],
+        },
+        shutdownHooks: [],
+    };
+    const envTaskQueue = process.env['TEMPORAL_TASK_QUEUE'];
+    if (envTaskQueue) {
+        config.workerOptions.taskQueue = envTaskQueue;
+    }
+    const connectConfig = deps.loadConnectConfig();
+    config.connectionOptions = { ...connectConfig.connectionOptions };
+    config.namespace = connectConfig.namespace || 'default';
+    configure(config);
+    const taskQueue = config.workerOptions.taskQueue;
+    if (!taskQueue) {
+        throw new Error('taskQueue is required: set config.workerOptions.taskQueue in the configure callback ' +
+            'or set the TEMPORAL_TASK_QUEUE environment variable');
+    }
+    // Install the Runtime with the (possibly user-modified) options
+    deps.installRuntime(config.runtimeOptions);
+    const shutdownDeadlineBufferMs = config.shutdownDeadlineBufferMs ?? defaults_1.DEFAULT_SHUTDOWN_DEADLINE_BUFFER_MS;
+    const runtimeLogger = config.runtimeOptions.logger;
+    return async (_event, context) => {
+        if (runtimeLogger instanceof json_logger_1.PowertoolsLoggerAdapter) {
+            runtimeLogger.addContext(context);
+        }
+        const logger = deps.getLogger();
+        const remainingMs = context.getRemainingTimeInMillis();
+        const workTimeMs = remainingMs - shutdownDeadlineBufferMs;
+        if (workTimeMs <= defaults_1.MINIMUM_WORK_TIME_MS) {
+            throw new Error(`Insufficient time for Lambda worker: ${remainingMs}ms remaining, ` +
+                `${shutdownDeadlineBufferMs}ms shutdown buffer, only ${workTimeMs}ms work time ` +
+                `(minimum: ${defaults_1.MINIMUM_WORK_TIME_MS}ms)`);
+        }
+        if (workTimeMs < defaults_1.WARN_WORK_TIME_MS) {
+            logger.warn('Low work time available for Lambda worker', {
+                remainingMs,
+                shutdownDeadlineBufferMs,
+                workTimeMs,
+            });
+        }
+        const identity = `${context.awsRequestId}@${context.invokedFunctionArn}`;
+        let connection;
+        try {
+            connection = await deps.connect(config.connectionOptions ?? {});
+            const workerOptions = {
+                ...config.workerOptions,
+                taskQueue,
+                connection: connection,
+                namespace: config.namespace,
+                identity,
+                workerDeploymentOptions: {
+                    version,
+                    useWorkerVersioning: true,
+                    defaultVersioningBehavior: config.workerOptions.workerDeploymentOptions?.defaultVersioningBehavior ?? 'PINNED',
+                },
+            };
+            const worker = await deps.createWorker(workerOptions);
+            await worker.runUntil((0, promises_1.setTimeout)(workTimeMs));
+        }
+        finally {
+            for (const hook of config.shutdownHooks) {
+                try {
+                    await hook();
+                }
+                catch (err) {
+                    logger.error('Lambda worker shutdown hook failed', { error: err });
+                }
+            }
+            try {
+                if (connection) {
+                    await connection.close();
+                }
+            }
+            catch (err) {
+                logger.error('Failed to close Temporal connection', { error: err });
+            }
+        }
+    };
+}
+//# sourceMappingURL=lambda-worker.js.map

package/lib/lambda-worker.js.map

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

package/lib/logger-factory.d.ts

@@ -0,0 +1,10 @@
+import type { Logger } from '@temporalio/worker';
+/**
+ * Create a Powertools-based logger for the Lambda worker.
+ *
+ * If `@aws-lambda-powertools/logger` is installed, returns a
+ * {@link PowertoolsLoggerAdapter} wrapping a Powertools Logger.
+ * Otherwise, returns `undefined`, causing the Runtime to fall back
+ * to its default logger.
+ */
+export declare function makePowertoolsLogger(): Logger | undefined;