@chainsaws/aws-core

Shared AWS client helpers for Chainsaws Node packages.

This package is intentionally small. It exists to keep the common transport-facing contract aligned across service packages without introducing a heavy Session or base-client abstraction.

Installation

npm install @chainsaws/aws-core
yarn add @chainsaws/aws-core
pnpm add @chainsaws/aws-core

This package is ESM-only.

Package Surface

@chainsaws/aws-core exports four things:

• AWSCredentialsInput
• AWSClientConfig
• create_aws_client_config(...)
• create_aws_request_handler(...)
• extract_aws_service_error(...)

These are the shared pieces used by @chainsaws/s3, @chainsaws/sqs, @chainsaws/sns, @chainsaws/ssm, @chainsaws/dynamodb, and @chainsaws/lambda.

Shared Config

import { create_aws_client_config } from "@chainsaws/aws-core";

const config = create_aws_client_config({
  region: "ap-northeast-2",
  endpoint: "http://localhost:4566",
  max_pool_connections: 100,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    sessionToken: process.env.AWS_SESSION_TOKEN,
  },
});

Shared keys:

• region
• endpoint
• credentials
• max_pool_connections

create_aws_client_config(...) only keeps these common keys. That lets a service package merge shared AWS config with its own options without creating a cross-service base class.

Shared Transport Helper

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { create_aws_request_handler } from "@chainsaws/aws-core";

const client = new DynamoDBClient({
  region: "ap-northeast-2",
  requestHandler: create_aws_request_handler(100),
});

Use this when constructing AWS SDK v3 clients that should share the same HTTP connection-pool behavior. When max_pool_connections is missing or <= 0, the helper returns undefined so the SDK falls back to its default transport.

Shared Error Extraction

import { extract_aws_service_error } from "@chainsaws/aws-core";

try {
  // AWS SDK call
} catch (error) {
  const serviceError = extract_aws_service_error(error);
  console.error(
    serviceError?.code,
    serviceError?.message,
    serviceError?.request_id,
  );
}

This reads the common Smithy-style error payload:

• error.response.Error.Code
• error.response.Error.Message
• error.response.ResponseMetadata.RequestId
• error.response.ResponseMetadata.HTTPStatusCode

It is deliberately conservative. If the error does not match that shape, the helper returns undefined.

Typical Usage in a Service Package

import { SQSClient } from "@aws-sdk/client-sqs";
import {
  create_aws_client_config,
  create_aws_request_handler,
} from "@chainsaws/aws-core";

const config = create_aws_client_config({
  region: "ap-northeast-2",
  endpoint: process.env.SQS_ENDPOINT,
  max_pool_connections: 50,
});

const client = new SQSClient({
  region: config.region,
  endpoint: config.endpoint,
  credentials: config.credentials,
  requestHandler: create_aws_request_handler(config.max_pool_connections),
});

What This Package Does Not Do

It intentionally does not provide:

• a boto-style Session
• a generic AWS service base class
• global retry or backoff policy orchestration
• shared request serialization across unrelated AWS services

Those abstractions are broader than the current common surface and would add more ceremony than value.