S3 adapters (@healthzkit/s3)

The @healthzkit/s3 package provides HealthAdapter helpers for AWS SDK v2 aws-sdk and v3 @aws-sdk/client-s3. Successful checks call ListBuckets and return ok with metadata.latencyMs, metadata.bucketCount, plus any fields from an optional metadata hook; failures return fail with the caught error.

Install the adapter package and one AWS SDK:

pnpm add @healthzkit/s3 healthzkit
# plus one of:
pnpm add aws-sdk
pnpm add @aws-sdk/client-s3

Both SDKs are optional peers—install only the one you use.

Package entrypoints

• @healthzkit/s3 - s3V2Adapter, s3V3Adapter, and their option types.
• @healthzkit/s3/v2 - s3V2Adapter only.
• @healthzkit/s3/v3 - s3V3Adapter only.

Use subpath imports when you want to avoid pulling the unused SDK into your bundle analysis path.

Shared options

Both factories accept BaseS3Options:

Option	Description
metadata	Optional (client) => Record<string, unknown> (sync or async) merged into metadata with latencyMs.

Pass either config or an existing client (not both). The shape depends on the adapter (see below).

s3V2Adapter (aws-sdk)

Peer: aws-sdk >= 2.

Uses the v2 S3 client and listBuckets(). Suitable for legacy services still on AWS SDK for JavaScript v2.

Config

The adapter lazily imports aws-sdk, constructs new AWS.S3(config) once, and reuses it across checks.

import { createHealthKit } from "healthzkit";
import { s3V2Adapter } from "@healthzkit/s3";

const kit = createHealthKit({
  checks: [
    {
      name: "s3",
      type: ["readiness"],
      adapter: s3V2Adapter({
        config: { region: process.env.AWS_REGION ?? "us-east-1" },
      }),
    },
  ],
});

Existing client

import AWS from "aws-sdk";
import { s3V2Adapter } from "@healthzkit/s3/v2";

const client = new AWS.S3({ region: "us-east-1" });

const adapter = s3V2Adapter({
  client,
  metadata: () => ({ sdk: "v2" }),
});

s3V3Adapter (@aws-sdk/client-s3)

Peer: @aws-sdk/client-s3 >= 3.

Uses S3Client and ListBucketsCommand. Prefer this for new code on AWS SDK for JavaScript v3.

Config

The adapter lazily imports @aws-sdk/client-s3, constructs new S3Client(config) once, and reuses it across checks.

import { s3V3Adapter } from "@healthzkit/s3/v3";

const adapter = s3V3Adapter({
  config: { region: process.env.AWS_REGION ?? "us-east-1" },
});

Existing client

import { S3Client } from "@aws-sdk/client-s3";
import { s3V3Adapter } from "@healthzkit/s3";

const client = new S3Client({ region: "us-east-1" });

const adapter = s3V3Adapter({
  client,
  metadata: async () => ({ sdk: "v3" }),
});

Scheduling

For S3 buckets that should not be queried on every probe, pair these adapters with a schedule on the check so readiness reads cached results (see Scheduling).