skuba 13.0.0-subpath-imports-20250722044721 → 13.0.0-subpath-imports-20251003044159

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 * as app from './app.js';
 import { stdoutMock } from './framework/logging.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' },
+      {
+        error: {
+          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: {
+        error: {
           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: {
+        error: {
           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,8 +203,7 @@ describe('handler', () => {
 
     expect(stdoutMock.calls).toMatchObject([
       {
-        awsRequestId: '-',
-        err: {
+        error: {
           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

@@ -1,7 +1,10 @@
 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';
@@ -34,19 +37,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/config.ts

@@ -1,27 +1,25 @@
 import { Env } from 'skuba-dive';
 
 interface Config {
-  environment: Environment;
+  deployment: Deployment;
 
   logLevel: string;
-  metrics: boolean;
   name: string;
   version: string;
 
   destinationSnsTopicArn: string;
 }
 
-type Environment = (typeof environments)[number];
+type Deployment = (typeof deployments)[number];
 
-const environments = ['local', 'test', 'dev', 'prod'] as const;
+const deployments = ['local', 'test', 'dev', 'prod'] as const;
 
-const environment = Env.oneOf(environments)('ENVIRONMENT');
+const deployment = Env.oneOf(deployments)('DEPLOYMENT');
 
 /* istanbul ignore next: config verification makes more sense in a smoke test */
-const configs: Record<Environment, () => Omit<Config, 'environment'>> = {
+const configs: Record<Deployment, () => Omit<Config, 'deployment'>> = {
   local: () => ({
     logLevel: 'debug',
-    metrics: false,
     name: '<%- serviceName %>',
     version: 'local',
 
@@ -30,7 +28,6 @@ const configs: Record<Environment, () => Omit<Config, 'environment'>> = {
 
   test: () => ({
     logLevel: Env.string('LOG_LEVEL', { default: 'debug' }),
-    metrics: false,
     name: '<%- serviceName %>',
     version: 'test',
 
@@ -39,24 +36,22 @@ const configs: Record<Environment, () => Omit<Config, 'environment'>> = {
 
   dev: () => ({
     logLevel: 'debug',
-    metrics: true,
-    name: Env.string('SERVICE'),
-    version: Env.string('VERSION'),
+    name: Env.string('DD_SERVICE'),
+    version: Env.string('DD_VERSION'),
 
     destinationSnsTopicArn: Env.string('DESTINATION_SNS_TOPIC_ARN'),
   }),
 
   prod: () => ({
     logLevel: 'info',
-    metrics: true,
-    name: Env.string('SERVICE'),
-    version: Env.string('VERSION'),
+    name: Env.string('DD_SERVICE'),
+    version: Env.string('DD_VERSION'),
 
     destinationSnsTopicArn: Env.string('DESTINATION_SNS_TOPIC_ARN'),
   }),
 };
 
 export const config: Config = {
-  ...configs[environment](),
-  environment,
+  ...configs[deployment](),
+  deployment,
 };

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

@@ -1,3 +1,5 @@
+import type { SQSEvent } from 'aws-lambda';
+
 import { createHandler } from './handler.js';
 import { logger, stdoutMock } from './logging.js';
 
@@ -6,12 +8,14 @@ import { chance } from '#src/testing/types.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',
       },
     ]);
   });
@@ -47,7 +52,7 @@ describe('createHandler', () => {
     expect(stdoutMock.calls).toMatchObject([
       {
         awsRequestId: '-',
-        err: {
+        error: {
           message: err.message,
           type: 'Error',
         },
@@ -69,7 +74,7 @@ describe('createHandler', () => {
     expect(stdoutMock.calls).toMatchObject([
       {
         awsRequestId: '-',
-        err: {
+        error: {
           message: err.message,
           type: 'Error',
         },

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

@@ -1,40 +1,64 @@
-import type { Context as LambdaContext } from 'aws-lambda';
-import { datadog } from 'datadog-lambda-js';
+import type {
+  Context as LambdaContext,
+  SQSBatchItemFailure,
+  SQSBatchResponse,
+  SQSEvent,
+  SQSRecord,
+} from 'aws-lambda';
 
-import { config } from '#src/config.js';
-import { logger, loggerContext } from '#src/framework/logging.js';
+import {
+  lambdaContext,
+  logger,
+  recordContext,
+} from '#src/framework/logging.js';
 
 type Handler<Event, Output> = (
   event: Event,
   ctx: LambdaContext,
 ) => Promise<Output>;
 
-/**
- * Conditionally applies the Datadog wrapper to a Lambda handler.
- *
- * This also "fixes" its broken type definitions.
- */
-const withDatadog = <Event, Output = unknown>(
-  fn: Handler<Event, Output>,
-): Handler<Event, Output> =>
-  // istanbul ignore next
-  config.metrics ? (datadog(fn) as Handler<Event, Output>) : fn;
-
-export const createHandler = <Event, Output = unknown>(
-  fn: (event: Event, ctx: LambdaContext) => Promise<Output>,
-) =>
-  withDatadog<Event>((event, ctx) =>
-    loggerContext.run({ awsRequestId: ctx.awsRequestId }, async () => {
+export const createHandler =
+  <Event extends SQSEvent, Output = unknown>(
+    fn: (event: Event, ctx: LambdaContext) => Promise<Output>,
+  ): Handler<Event, Output> =>
+  async (event, ctx) =>
+    lambdaContext.run({ awsRequestId: ctx.awsRequestId }, async () => {
       try {
         const output = await fn(event, ctx);
 
-        logger.debug('Function succeeded');
+        logger.debug({ output }, 'Function completed');
 
         return output;
       } catch (err) {
-        logger.error({ err }, 'Function failed');
+        logger.error(err, 'Function failed');
 
         throw new Error('Function failed');
       }
-    }),
-  );
+    });
+
+export const createBatchSQSHandler =
+  (
+    fn: (record: SQSRecord, ctx: LambdaContext) => Promise<unknown>,
+  ): Handler<SQSEvent, SQSBatchResponse> =>
+  async (event, ctx) => {
+    const processRecord = (
+      record: SQSRecord,
+    ): Promise<SQSBatchItemFailure | undefined> =>
+      recordContext.run({ sqsMessageId: record.messageId }, async () => {
+        try {
+          await fn(record, ctx);
+          return;
+        } catch (err) {
+          logger.error(err, 'Processing record failed');
+          return {
+            itemIdentifier: record.messageId,
+          };
+        }
+      });
+
+    const results = await Promise.all(event.Records.map(processRecord));
+
+    return {
+      batchItemFailures: results.filter((item) => item !== undefined),
+    };
+  };

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

@@ -1,17 +1,22 @@
 import { AsyncLocalStorage } from 'async_hooks';
 
-import createLogger, { createDestination } from '@seek/logger';
+import { createDestination, createLogger } from '@seek/logger';
 
 import { config } from '#src/config.js';
 
-interface LoggerContext {
+interface LambdaContext {
   awsRequestId: string;
 }
 
-export const loggerContext = new AsyncLocalStorage<LoggerContext>();
+interface RecordContext {
+  sqsMessageId: string;
+}
+
+export const lambdaContext = new AsyncLocalStorage<LambdaContext>();
+export const recordContext = new AsyncLocalStorage<RecordContext>();
 
 const { destination, stdoutMock } = createDestination({
-  mock: config.environment === 'test' && {
+  mock: config.deployment === 'test' && {
     redact: ['awsRequestId'],
   },
 });
@@ -20,19 +25,26 @@ export { stdoutMock };
 
 export const logger = createLogger(
   {
-    base: {
-      environment: config.environment,
-      version: config.version,
+    eeeoh: {
+      /**
+       * TODO: choose an appropriate Datadog log tier.
+       *
+       * https://github.com/seek-oss/logger/blob/master/docs/eeeoh.md#datadog-log-tiers
+       */
+      datadog: 'tin',
+      team: '<%- teamName %>',
+      use: 'environment',
     },
 
     level: config.logLevel,
 
-    mixin: () => ({ ...loggerContext.getStore() }),
-
-    name: config.name,
+    mixin: () => ({
+      ...lambdaContext.getStore(),
+      ...recordContext.getStore(),
+    }),
 
     transport:
-      config.environment === 'local' ? { target: 'pino-pretty' } : undefined,
+      config.deployment === 'local' ? { target: 'pino-pretty' } : undefined,
   },
   destination,
 );

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

@@ -7,8 +7,5 @@ const prefix = `${config.name}.`;
 export const metricsClient = {
   distribution: (
     ...[name, ...rest]: Parameters<typeof sendDistributionMetric>
-  ) =>
-    config.metrics
-      ? sendDistributionMetric(`${prefix}${name}`, ...rest)
-      : undefined,
+  ) => sendDistributionMetric(`${prefix}${name}`, ...rest),
 };

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

@@ -9,5 +9,8 @@ export const createCtx = () =>
 
 export const createSqsEvent = (bodies: string[]) =>
   ({
-    Records: bodies.map((body) => ({ body })),
+    Records: bodies.map((body) => ({
+      body,
+      messageId: chance.guid({ version: 4 }),
+    })),
   }) as SQSEvent;

package/template/oss-npm-package/.github/workflows/release.yml

@@ -3,7 +3,7 @@ name: Release
 on:
   push:
     branches:
-      - $default-branch
+      - main
       - beta
 
 permissions: {}
@@ -18,17 +18,17 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Check out repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
-          node-version: ^22.14
-
-      - name: Set up pnpm
-        run: corepack enable pnpm && corepack install
+          node-version-file: .nvmrc
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -37,4 +37,3 @@ jobs:
         run: pnpm release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/template/oss-npm-package/.github/workflows/validate.yml

@@ -16,15 +16,15 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Check out repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
-          node-version: ^22.14
-
-      - name: Set up pnpm
-        run: corepack enable pnpm && corepack install
+          node-version-file: .nvmrc
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile

package/template/oss-npm-package/README.md

@@ -82,7 +82,7 @@ on:
   push:
     branches:
       # add others as necessary
-      - $default-branch
+      - main
       - beta
       # - alpha
 ```

package/template/oss-npm-package/_package.json

@@ -47,8 +47,5 @@
   "packageManager": "pnpm@10.7.0",
   "engines": {
     "node": ">=20.9.0"
-  },
-  "publishConfig": {
-    "provenance": true
   }
 }

package/template/oss-npm-package/skuba.template.js

@@ -2,7 +2,7 @@
  * Run `skuba configure` to finish templating and remove this file.
  */
 
-export default {
+module.exports = {
   entryPoint: 'src/index.ts',
   fields: [
     {

package/lib/api/buildkite/annotate.d.ts

@@ -1,28 +0,0 @@
-export type AnnotationStyle = 'success' | 'info' | 'warning' | 'error';
-interface AnnotationOptions {
-    context?: string;
-    /**
-     * Scopes an annotation's context to the Buildkite step ID.
-     *
-     * This lets you emit distinct annotations per step, and only takes effect if
-     * the `BUILDKITE_STEP_ID` environment variable is present.
-     */
-    scopeContextToStep?: boolean;
-    style?: AnnotationStyle;
-}
-export declare const MAX_SIZE: number;
-export declare const TRUNCATION_WARNING = "... [Truncated due to size limit]";
-/**
- * Asynchronously uploads a Buildkite annotation.
- *
- * If the following environment variables are not present,
- * the function will silently return without attempting to annotate:
- *
- * - `BUILDKITE`
- * - `BUILDKITE_AGENT_ACCESS_TOKEN`
- * - `BUILDKITE_JOB_ID`
- *
- * The `buildkite-agent` binary must also be on your `PATH`.
- */
-export declare const annotate: (markdown: string, opts?: AnnotationOptions) => Promise<void>;
-export {};