@btravstack/storage

---

@btravstack/storage / s3

s3

Type Aliases

S3StorageEnv

type S3StorageEnv = EnvReading<
  | "STORAGE_S3_ENDPOINT"
  | "STORAGE_S3_BUCKET"
  | "STORAGE_S3_ACCESS_KEY_ID"
  | "STORAGE_S3_SECRET_ACCESS_KEY", 
  | "STORAGE_S3_REGION"
  | "STORAGE_S3_MAX_SOCKETS"
  | "STORAGE_S3_STREAM_MAX_SOCKETS"
  | "STORAGE_S3_CONNECTION_TIMEOUT_MS"
  | "STORAGE_S3_SOCKET_TIMEOUT_MS"
  | "STORAGE_S3_REQUEST_TIMEOUT_MS"
  | "STORAGE_S3_STREAM_CONNECTION_TIMEOUT_MS"
  | "STORAGE_S3_STREAM_SOCKET_TIMEOUT_MS"
  | "STORAGE_S3_STREAM_REQUEST_TIMEOUT_MS">;

Defined in: packages/storage/src/s3.ts:831

The variables s3Storage reads: four required, the rest defaulted or pinnable.

---

S3StorageOptions

type S3StorageOptions = object;

Defined in: packages/storage/src/s3.ts:79

The socket pools' options, each pinning its variable. Every default is the AWS SDK's own, except the stream pool's timeouts, which default to the shared ones.

Properties

Property	Modifier	Type	Description	Defined in
connectionTimeoutMs?	readonly	number	Pins STORAGE_S3_CONNECTION_TIMEOUT_MS (default 0, none): how long an attempt may wait for a socket, a free one or a new connection.	packages/storage/src/s3.ts:96
maxSockets?	readonly	number	Pins STORAGE_S3_MAX_SOCKETS (default 50, the SDK's own): the sockets every call but the streamed ones shares.	packages/storage/src/s3.ts:84
requestTimeoutMs?	readonly	number	Pins STORAGE_S3_REQUEST_TIMEOUT_MS (default 0, none): how long an attempt may take until the store starts answering, its request body included. Past it the attempt fails, where the SDK alone would only log a warning. Every timeout is per attempt: the SDK retries a timed-out one (3 attempts by default), so a call can take about three times as long.	packages/storage/src/s3.ts:111
socketTimeoutMs?	readonly	number	Pins STORAGE_S3_SOCKET_TIMEOUT_MS (default 0, none): how long an attempt's socket may stay idle. Under 6 s it is armed at once, and bounds a response body read too; from 6 s the SDK arms it 3 s into the attempt, only if the store has not answered by then.	packages/storage/src/s3.ts:103
streamConnectionTimeoutMs?	readonly	number	Pins STORAGE_S3_STREAM_CONNECTION_TIMEOUT_MS (default connectionTimeoutMs): the stream pool's own connection timeout.	packages/storage/src/s3.ts:116
streamMaxSockets?	readonly	number	Pins STORAGE_S3_STREAM_MAX_SOCKETS (default 50, the SDK's own): the sockets of the pool getStream, putStream and putStreamIfAbsent use, and so how many of them may run at once. One more is refused with StreamPoolFull.	packages/storage/src/s3.ts:91
streamRequestTimeoutMs?	readonly	number	Pins STORAGE_S3_STREAM_REQUEST_TIMEOUT_MS (default requestTimeoutMs): the stream pool's own request timeout, which for a streamed write bounds each part's attempt, its 8 MiB body included.	packages/storage/src/s3.ts:128
streamSocketTimeoutMs?	readonly	number	Pins STORAGE_S3_STREAM_SOCKET_TIMEOUT_MS (default socketTimeoutMs): the stream pool's own socket timeout, so a reader that legitimately pauses is not cut by the bound a short call needs.	packages/storage/src/s3.ts:122

---

S3Streams

type S3Streams = object;

Defined in: packages/storage/src/s3.ts:248

The pool the streamed calls use: its own client, and how many may hold one of its sockets at once.

Properties

Property	Modifier	Type	Defined in
client	readonly	S3Client	packages/storage/src/s3.ts:248
maxSockets	readonly	number	packages/storage/src/s3.ts:248

Functions

s3Storage()

function s3Storage(options?): Module<StorageBackend, ConfigInvalid, S3StorageEnv | Scope>;

Defined in: packages/storage/src/s3.ts:793

The S3 adapter: two clients, built with the scope and destroyed with it, and StorageBackend over them. Each has a socket pool of its own: the streamed calls use one, every other call the other, so a stream a slow reader holds open never takes a socket a short call needs. Its two AWS SDK peers are optional and reached only through this subpath, so an application composing the memory adapter installs neither.

storage({ adapter: s3Storage({ streamMaxSockets: 20 }) });

Parameters

Parameter	Type
options?	S3StorageOptions

Returns

Module<StorageBackend, ConfigInvalid, S3StorageEnv | Scope>

---

s3StorageBackend()

function s3StorageBackend(
   client, 
   bucket, 
   streams?
): StorageService;

Defined in: packages/storage/src/s3.ts:554

The adapter's service over a client and a bucket. A delete of a key nobody stored answers Ok, which is S3's own idempotent behaviour rather than a fiction layered over it.

The streamed calls go through streams: getStream, putStream and putStreamIfAbsent each hold one of its maxSockets slots, from the call until the object's stream closes or the write settles, and one more answers StreamPoolFull at once. Without it they share client, unbounded.

Parameters

Parameter	Type
client	S3Client
bucket	string
streams?	S3Streams

Returns

StorageService