skuba 12.1.0-hoist-less-20250722131939 → 12.1.0-main-20250810101347

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skuba",
-  "version": "12.1.0-hoist-less-20250722131939",
+  "version": "12.1.0-main-20250810101347",
   "private": false,
   "description": "SEEK development toolkit for backend applications and packages",
   "homepage": "https://github.com/seek-oss/skuba#readme",
@@ -61,7 +61,6 @@
     "@types/node": "^22.0.0",
     "chalk": "^4.1.0",
     "concurrently": "^9.0.0",
-    "dotenv": "^16.0.0",
     "ejs": "^3.1.6",
     "enquirer": "^2.3.6",
     "esbuild": "~0.25.0",
@@ -96,38 +95,38 @@
     "tsconfig-paths": "^4.0.0",
     "tsconfig-seek": "2.0.0",
     "tsx": "^4.16.2",
-    "typescript": "~5.8.0",
-    "zod": "^3.25.67",
-    "eslint-config-skuba": "7.0.2"
+    "typescript": "~5.9.0",
+    "zod": "^4.0.0",
+    "eslint-config-skuba": "7.1.0-main-20250810101347"
   },
   "devDependencies": {
     "@changesets/cli": "2.29.5",
     "@changesets/get-github-info": "0.6.0",
-    "@jest/reporters": "30.0.4",
-    "@jest/test-result": "30.0.4",
+    "@jest/reporters": "30.0.5",
+    "@jest/test-result": "30.0.5",
     "@types/ejs": "3.1.5",
     "@types/express": "5.0.3",
     "@types/fs-extra": "11.0.4",
-    "@types/koa": "2.15.0",
+    "@types/koa": "3.0.0",
     "@types/lodash.mergewith": "4.6.9",
     "@types/minimist": "1.2.5",
     "@types/module-alias": "2.0.4",
     "@types/npm-registry-fetch": "8.0.8",
     "@types/npm-which": "3.0.4",
-    "@types/picomatch": "4.0.0",
+    "@types/picomatch": "4.0.2",
     "@types/semver": "7.7.0",
     "@types/supertest": "6.0.3",
     "enhanced-resolve": "5.18.2",
     "express": "5.1.0",
     "fastify": "5.4.0",
-    "jest-diff": "30.0.4",
+    "jest-diff": "30.0.5",
     "jsonfile": "6.1.0",
-    "koa": "3.0.0",
-    "memfs": "4.17.2",
+    "koa": "3.0.1",
+    "memfs": "4.36.0",
     "remark-cli": "12.0.1",
     "remark-preset-lint-recommended": "7.0.1",
     "semver": "7.7.2",
-    "supertest": "7.1.3",
+    "supertest": "7.1.4",
     "type-fest": "2.19.0"
   },
   "peerDependencies": {
@@ -149,7 +148,7 @@
     "entryPoint": "src/index.ts",
     "template": null,
     "type": "package",
-    "version": "11.1.0"
+    "version": "12.0.2"
   },
   "scripts": {
     "build": "scripts/build.sh",
@@ -163,7 +162,7 @@
     "lint:packages": "pnpm --filter '!./template/**' lint",
     "release": "pnpm --silent build && changeset publish",
     "skuba": "pnpm --silent build && pnpm --silent skuba:exec",
-    "skuba:exec": "node --experimental-vm-modules --no-warnings=ExperimentalWarning lib/skuba",
+    "skuba:exec": "node lib/skuba",
     "stage": "changeset version && node ./.changeset/inject.js && pnpm format",
     "test": "pnpm --silent skuba test --selectProjects unit",
     "test:ci": "pnpm --silent skuba test --runInBand",

package/template/base/_pnpm-workspace.yaml

@@ -8,4 +8,5 @@ publicHoistPattern:
   - esbuild
   - jest
   - tsconfig-seek
+  - typescript
   # end managed by skuba

package/template/express-rest-api/package.json

@@ -13,10 +13,10 @@
     "test:watch": "skuba test --watch"
   },
   "dependencies": {
-    "@seek/logger": "^10.0.0",
+    "@seek/logger": "master",
     "express": "^5.0.0",
-    "hot-shots": "^10.0.0",
-    "seek-datadog-custom-metrics": "^4.6.3",
+    "hot-shots": "^11.0.0",
+    "seek-datadog-custom-metrics": "^5.0.0",
     "skuba-dive": "^2.0.0"
   },
   "devDependencies": {
@@ -28,7 +28,7 @@
     "skuba": "*",
     "supertest": "^7.0.0"
   },
-  "packageManager": "pnpm@10.12.4",
+  "packageManager": "pnpm@10.14.0",
   "engines": {
     "node": ">=22"
   }

package/template/express-rest-api/src/listen.ts

@@ -21,3 +21,9 @@ const listener = app.listen(config.port, () => {
 // https://docs.aws.amazon.com/elasticloadbalancing/latest/application/application-load-balancers.html#connection-idle-timeout
 // AWS recommends setting an application timeout larger than the load balancer
 listener.keepAliveTimeout = 31000;
+
+// Report unhandled rejections instead of crashing the process
+// Make sure to monitor these reports and alert as appropriate
+process.on('unhandledRejection', (err) =>
+  logger.error(err, 'Unhandled promise rejection'),
+);

package/template/greeter/package.json

@@ -17,9 +17,9 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.10",
-    "skuba": "12.1.0-hoist-less-20250722131939"
+    "skuba": "12.1.0-main-20250810101347"
   },
-  "packageManager": "pnpm@10.12.4",
+  "packageManager": "pnpm@10.14.0",
   "engines": {
     "node": ">=22"
   }

package/template/koa-rest-api/package.json

@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@koa/bodyparser": "^6.0.0",
-    "@koa/router": "^13.0.0",
+    "@koa/router": "^14.0.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/core": "^2.0.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.203.0",
@@ -22,19 +22,19 @@
     "@opentelemetry/instrumentation-http": "^0.203.0",
     "@opentelemetry/propagator-b3": "^2.0.0",
     "@opentelemetry/sdk-node": "^0.203.0",
-    "@seek/logger": "^10.0.0",
-    "hot-shots": "^10.0.0",
-    "koa": "^2.16.1",
+    "@seek/logger": "master",
+    "hot-shots": "^11.0.0",
+    "koa": "^3.0.1",
     "koa-compose": "^4.1.0",
-    "seek-datadog-custom-metrics": "^4.6.3",
-    "seek-koala": "^7.0.0",
+    "seek-datadog-custom-metrics": "^5.0.0",
+    "seek-koala": "^7.1.0",
     "skuba-dive": "^2.0.0",
-    "zod": "^3.25.67"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "@types/chance": "^1.1.3",
     "@types/co-body": "^6.1.3",
-    "@types/koa": "^2.13.4",
+    "@types/koa": "^3.0.0",
     "@types/koa__router": "^12.0.0",
     "@types/node": "^22.13.10",
     "@types/supertest": "^6.0.0",
@@ -44,7 +44,7 @@
     "skuba": "*",
     "supertest": "^7.0.0"
   },
-  "packageManager": "pnpm@10.12.4",
+  "packageManager": "pnpm@10.14.0",
   "engines": {
     "node": ">=22"
   }

package/template/koa-rest-api/src/framework/server.test.ts

@@ -32,7 +32,6 @@ describe('createApp', () => {
 
     expect(stdoutMock.calls).toHaveLength(0);
 
-    metricsClient.expectTagSubset(['env:test', 'version:test']);
     metricsClient.expectTagSubset([
       'http_method:get',
       'http_status:200',

package/template/koa-rest-api/src/listen.ts

@@ -22,3 +22,9 @@ const listener = app.listen(config.port, () => {
 // https://docs.aws.amazon.com/elasticloadbalancing/latest/application/application-load-balancers.html#connection-idle-timeout
 // AWS recommends setting an application timeout larger than the load balancer
 listener.keepAliveTimeout = 31000;
+
+// Report unhandled rejections instead of crashing the process
+// Make sure to monitor these reports and alert as appropriate
+process.on('unhandledRejection', (err) =>
+  logger.error(err, 'Unhandled promise rejection'),
+);

package/template/lambda-sqs-worker-cdk/infra/__snapshots__/appStack.test.ts.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`returns expected CloudFormation stack for dev 1`] = `
 {
@@ -222,7 +222,7 @@ exports[`returns expected CloudFormation stack for dev 1`] = `
             ],
           },
         ],
-        "ReservedConcurrentExecutions": 2,
+        "ReservedConcurrentExecutions": 3,
         "Role": {
           "Fn::GetAtt": [
             "workerServiceRole2130CC7F",
@@ -332,6 +332,7 @@ exports[`returns expected CloudFormation stack for dev 1`] = `
     },
     "workerAliasLiveSqsEventSourceappStackworkerqueue8281B9F443B0CF93": {
       "Properties": {
+        "BatchSize": 10,
         "EventSourceArn": {
           "Fn::GetAtt": [
             "workerqueueA05CE5C6",
@@ -359,6 +360,12 @@ exports[`returns expected CloudFormation stack for dev 1`] = `
             ],
           ],
         },
+        "FunctionResponseTypes": [
+          "ReportBatchItemFailures",
+        ],
+        "ScalingConfig": {
+          "MaximumConcurrency": 2,
+        },
         "Tags": [
           {
             "Key": "aws-codedeploy-hooks",
@@ -1065,6 +1072,7 @@ exports[`returns expected CloudFormation stack for prod 1`] = `
     },
     "workerAliasLiveSqsEventSourceappStackworkerqueue8281B9F443B0CF93": {
       "Properties": {
+        "BatchSize": 10,
         "EventSourceArn": {
           "Fn::GetAtt": [
             "workerqueueA05CE5C6",
@@ -1092,6 +1100,12 @@ exports[`returns expected CloudFormation stack for prod 1`] = `
             ],
           ],
         },
+        "FunctionResponseTypes": [
+          "ReportBatchItemFailures",
+        ],
+        "ScalingConfig": {
+          "MaximumConcurrency": 19,
+        },
         "Tags": [
           {
             "Key": "aws-codedeploy-hooks",

package/template/lambda-sqs-worker-cdk/infra/appStack.ts

@@ -141,7 +141,11 @@ export class AppStack extends Stack {
     });
 
     workerDeployment.alias.addEventSource(
-      new aws_lambda_event_sources.SqsEventSource(queue),
+      new aws_lambda_event_sources.SqsEventSource(queue, {
+        maxConcurrency: config.workerLambda.reservedConcurrency - 1, // Ensure we have capacity reserved for our blue/green deployment
+        batchSize: config.workerLambda.batchSize,
+        reportBatchItemFailures: true,
+      }),
     );
   }
 }

package/template/lambda-sqs-worker-cdk/infra/config.ts

@@ -9,6 +9,7 @@ const environment = Env.oneOf(ENVIRONMENTS)('ENVIRONMENT');
 interface Config {
   appName: string;
   workerLambda: {
+    batchSize: number;
     reservedConcurrency: number;
     environment: {
       ENVIRONMENT: Environment;
@@ -24,7 +25,8 @@ const configs: Record<Environment, Config> = {
   dev: {
     appName: '<%- serviceName %>',
     workerLambda: {
-      reservedConcurrency: 2,
+      batchSize: 10,
+      reservedConcurrency: 3,
       environment: {
         ENVIRONMENT: 'dev',
         SERVICE: '<%- serviceName %>',
@@ -37,6 +39,7 @@ const configs: Record<Environment, Config> = {
   prod: {
     appName: '<%- serviceName %>',
     workerLambda: {
+      batchSize: 10,
       reservedConcurrency: 20,
       environment: {
         ENVIRONMENT: 'prod',

package/template/lambda-sqs-worker-cdk/package.json

@@ -18,11 +18,11 @@
     "@aws-sdk/client-lambda": "^3.363.0",
     "@aws-sdk/client-sns": "^3.363.0",
     "@seek/aws-codedeploy-hooks": "^2.0.0",
-    "@seek/logger": "^10.0.0",
-    "datadog-lambda-js": "^10.0.0",
+    "@seek/logger": "master",
+    "datadog-lambda-js": "^12.0.0",
     "dd-trace": "^5.0.0",
     "skuba-dive": "^2.0.0",
-    "zod": "^3.25.67"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "@seek/aws-codedeploy-infra": "^3.0.0",
@@ -37,9 +37,9 @@
     "constructs": "^10.0.17",
     "datadog-cdk-constructs-v2": "^2.0.0",
     "pino-pretty": "^13.0.0",
-    "skuba": "12.1.0-hoist-less-20250722131939"
+    "skuba": "12.1.0-main-20250810101347"
   },
-  "packageManager": "pnpm@10.12.4",
+  "packageManager": "pnpm@10.14.0",
   "engines": {
     "node": ">=22"
   }

package/template/lambda-sqs-worker-cdk/src/app.test.ts

@@ -1,4 +1,5 @@
 import { PublishCommand } from '@aws-sdk/client-sns';
+import type { SQSBatchResponse } from 'aws-lambda';
 
 import { metricsClient } from 'src/framework/metrics.js';
 import { createCtx, createSqsEvent } from 'src/testing/handler.js';
@@ -40,42 +41,100 @@ describe('handler', () => {
   it('handles one record', async () => {
     const event = createSqsEvent([JSON.stringify(jobPublished)]);
 
-    await expect(app.handler(event, ctx)).resolves.toBeUndefined();
+    await expect(app.handler(event, ctx)).resolves.toEqual<SQSBatchResponse>({
+      batchItemFailures: [],
+    });
 
     expect(scoringService.request).toHaveBeenCalledTimes(1);
 
     expect(stdoutMock.calls).toMatchObject([
+      { count: 1, level: 20, msg: 'Received jobs' },
       {
-        awsRequestId: '-',
-        count: 1,
         level: 20,
-        msg: 'Received jobs',
+        msg: 'Scored job',
+        snsMessageId: expect.any(String),
+        sqsMessageId: event.Records[0]!.messageId,
       },
+      { level: 20, msg: 'Function completed' },
+    ]);
+
+    expect(distribution.mock.calls).toEqual([
+      ['job.received', 1],
+      ['job.scored', 1],
+    ]);
+
+    expect(sns.client).toReceiveCommandTimes(PublishCommand, 1);
+  });
+
+  it('handles multiple records', async () => {
+    const event = createSqsEvent([
+      JSON.stringify(jobPublished),
+      JSON.stringify(jobPublished),
+    ]);
+
+    await expect(app.handler(event, ctx)).resolves.toEqual<SQSBatchResponse>({
+      batchItemFailures: [],
+    });
+
+    expect(stdoutMock.calls).toMatchObject([
+      { count: 2, level: 20, msg: 'Received jobs' },
       {
-        awsRequestId: '-',
         level: 20,
         msg: 'Scored job',
         snsMessageId: expect.any(String),
+        sqsMessageId: event.Records[0]!.messageId,
       },
       {
-        awsRequestId: '-',
         level: 20,
-        msg: 'Function succeeded',
+        msg: 'Scored job',
+        snsMessageId: expect.any(String),
+        sqsMessageId: event.Records[1]!.messageId,
       },
+      { level: 20, msg: 'Function completed' },
     ]);
+  });
 
-    expect(distribution.mock.calls).toEqual([
-      ['job.received', 1],
-      ['job.scored', 1],
+  it('handles partial batch failure', async () => {
+    const event = createSqsEvent([
+      JSON.stringify('}'),
+      JSON.stringify(jobPublished),
     ]);
 
-    expect(sns.client).toReceiveCommandTimes(PublishCommand, 1);
+    await expect(app.handler(event, ctx)).resolves.toEqual<SQSBatchResponse>({
+      batchItemFailures: [{ itemIdentifier: event.Records[0]!.messageId }],
+    });
+
+    expect(stdoutMock.calls).toMatchObject([
+      { count: 2, level: 20, msg: 'Received jobs' },
+      {
+        err: {
+          name: 'ZodError',
+          type: 'ZodError',
+        },
+        level: 50,
+        msg: 'Processing record failed',
+        sqsMessageId: event.Records[0]!.messageId,
+      },
+      {
+        level: 20,
+        msg: 'Scored job',
+        snsMessageId: expect.any(String),
+        sqsMessageId: event.Records[1]!.messageId,
+      },
+      { level: 20, msg: 'Function completed' },
+    ]);
   });
 
-  it('throws on invalid input', () => {
+  it('returns a batchItemFailure on invalid input', () => {
     const event = createSqsEvent(['}']);
 
-    return expect(app.handler(event, ctx)).rejects.toThrow('Function failed');
+    return expect(app.handler(event, ctx)).resolves.toEqual<SQSBatchResponse>({
+      batchItemFailures: [
+        {
+          itemIdentifier: event.Records[0]!.messageId,
+        },
+      ],
+    });
   });
 
   it('bubbles up scoring service error', async () => {
@@ -85,24 +144,22 @@ describe('handler', () => {
 
     const event = createSqsEvent([JSON.stringify(jobPublished)]);
 
-    await expect(app.handler(event, ctx)).rejects.toThrow('Function failed');
+    await expect(app.handler(event, ctx)).resolves.toEqual<SQSBatchResponse>({
+      batchItemFailures: [{ itemIdentifier: event.Records[0]!.messageId }],
+    });
 
     expect(stdoutMock.calls).toMatchObject([
+      { count: 1, level: 20, msg: 'Received jobs' },
       {
-        awsRequestId: '-',
-        count: 1,
-        level: 20,
-        msg: 'Received jobs',
-      },
-      {
-        awsRequestId: '-',
         err: {
           message: err.message,
           type: 'Error',
         },
         level: 50,
-        msg: 'Function failed',
+        msg: 'Processing record failed',
+        sqsMessageId: event.Records[0]!.messageId,
       },
+      { level: 20, msg: 'Function completed' },
     ]);
   });
 
@@ -113,23 +170,28 @@ describe('handler', () => {
 
     const event = createSqsEvent([JSON.stringify(jobPublished)]);
 
-    await expect(app.handler(event, ctx)).rejects.toThrow('Function failed');
+    await expect(app.handler(event, ctx)).resolves.toEqual<SQSBatchResponse>({
+      batchItemFailures: [{ itemIdentifier: event.Records[0]!.messageId }],
+    });
 
     expect(stdoutMock.calls).toMatchObject([
       {
-        awsRequestId: '-',
         count: 1,
         level: 20,
         msg: 'Received jobs',
       },
       {
-        awsRequestId: '-',
         err: {
           message: err.message,
           type: 'Error',
         },
         level: 50,
-        msg: 'Function failed',
+        msg: 'Processing record failed',
+        sqsMessageId: event.Records[0]!.messageId,
+      },
+      {
+        level: 20,
+        msg: 'Function completed',
       },
     ]);
   });
@@ -141,7 +203,6 @@ describe('handler', () => {
 
     expect(stdoutMock.calls).toMatchObject([
       {
-        awsRequestId: '-',
         err: {
           message: 'Received 0 records',
           type: 'Error',
@@ -151,25 +212,4 @@ describe('handler', () => {
       },
     ]);
   });
-
-  it('throws on multiple records', async () => {
-    const event = createSqsEvent([
-      JSON.stringify(jobPublished),
-      JSON.stringify(jobPublished),
-    ]);
-
-    await expect(app.handler(event, ctx)).rejects.toThrow('Function failed');
-
-    expect(stdoutMock.calls).toMatchObject([
-      {
-        awsRequestId: '-',
-        err: {
-          message: 'Received 2 records',
-          type: 'Error',
-        },
-        level: 50,
-        msg: 'Function failed',
-      },
-    ]);
-  });
 });

package/template/lambda-sqs-worker-cdk/src/app.ts

@@ -3,7 +3,7 @@ import 'skuba-dive/register';
 import { isLambdaHook } from '@seek/aws-codedeploy-hooks';
 import type { SQSEvent } from 'aws-lambda';
 
-import { createHandler } from 'src/framework/handler.js';
+import { createBatchSQSHandler, createHandler } from 'src/framework/handler.js';
 import { logger } from 'src/framework/logging.js';
 import { metricsClient } from 'src/framework/metrics.js';
 import { validateJson } from 'src/framework/validation.js';
@@ -36,19 +36,17 @@ export const handler = createHandler<SQSEvent>(async (event, ctx) => {
 
   const count = event.Records.length;
 
-  if (count !== 1) {
-    throw Error(`Received ${count} records`);
+  if (!count) {
+    throw Error('Received 0 records');
   }
-
   logger.debug({ count }, 'Received jobs');
 
-  metricsClient.distribution('job.received', event.Records.length);
+  metricsClient.distribution('job.received', count);
 
-  const record = event.Records[0];
-  if (!record) {
-    throw new Error('Malformed SQS event with no records');
-  }
+  return recordHandler(event, ctx);
+});
 
+const recordHandler = createBatchSQSHandler(async (record, _ctx) => {
   const { body } = record;
 
   // TODO: this throws an error, which will cause the Lambda function to retry

package/template/lambda-sqs-worker-cdk/src/framework/handler.test.ts

@@ -1,3 +1,5 @@
+import type { SQSEvent } from 'aws-lambda';
+
 import { createCtx } from 'src/testing/handler.js';
 import { chance } from 'src/testing/types.js';
 
@@ -6,12 +8,14 @@ import { logger, stdoutMock } from './logging.js';
 
 describe('createHandler', () => {
   const ctx = createCtx();
-  const input = chance.paragraph();
+  const input: SQSEvent = {
+    Records: [],
+  };
 
   afterEach(stdoutMock.clear);
 
   it('handles happy path', async () => {
-    const output = chance.paragraph();
+    const output = chance.sentence();
 
     const handler = createHandler((event) => {
       expect(event).toBe(input);
@@ -32,7 +36,8 @@ describe('createHandler', () => {
       {
         awsRequestId: '-',
         level: 20,
-        msg: 'Function succeeded',
+        output,
+        msg: 'Function completed',
       },
     ]);
   });