@unikvs/s3.node

How to use @unikvs/s3.node, which stores byte sequences in S3-compatible object storage.

Overview

@unikvs/s3.node is a storage plugin that stores byte sequences in S3-compatible object storage. Node.js only Use it for persistence in the cloud or in S3-compatible storage.

• name is "S3", and isOpen reports whether it is open.
• open() creates the client, and close() discards it.
• This storage performs all operations against the bucket given in the constructor, using keys as-is as object keys.

Install it with the following command:

npm install @unikvs/s3.node

pnpm add @unikvs/s3.node

yarn add @unikvs/s3.node

bun add @unikvs/s3.node

nub add @unikvs/s3.node

aube add @unikvs/s3.node

S3-compatible object storage is required separately.

Usage

S3 implements IStorage. Pass it to UniKvs via persist().

import { S3 } from "@unikvs/s3.node";

S3

Storage that saves to S3-compatible storage. Callers open it with open() and close it with close() when done.

The constructor arguments are as follows:

S3StorageOptions

An option type reserved for future use. Currently an empty object with no settable fields.

The following example saves a value and reads it back:

import { S3 } from "@unikvs/s3.node";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.Value<Uint8Array> }>()
  .persist(new S3("my-bucket", { region: "us-east-1" }))
  .build();

await kvs.open();

await kvs.set("file", new Uint8Array([0, 1, 2]));

const data = await kvs.get("file");
console.log(data); // Uint8Array(3) [0, 1, 2]

await kvs.close();

Data types

• write / read use byte sequences (Uint8Array<ArrayBuffer>).
• Supports streamed reading and writing with Uint8Array<ArrayBuffer> chunks.
• Write streams use multipart upload. The part size can be changed with the runtime variable @unikvs/s3.node:partSize (or @unikvs/s3:partSize).
• clear() lists and deletes every object in the bucket.

Errors

This package throws the following errors.

InvalidPartSizeError

A shared @unikvs/core error. Thrown when the write-stream part size is not a positive integer.

Meaning

The runtime-variable part size (@unikvs/s3.node:partSize or @unikvs/s3:partSize) is not a positive integer. A shared @unikvs/core error.

How to fix

Specify a positive integer (in bytes) as the part size.

StorageAbortedError

A shared @unikvs/core error. Thrown when the signal is already aborted before acquiring a write stream.

Meaning

The AbortSignal is already aborted when getWritable() is called. A shared @unikvs/core error.

How to fix

Pass a signal that is not aborted, or check the signal state before requesting.

AggregateError

An error thrown when bulk deletion (clear()) fails to delete individual objects.

Meaning

DeleteObjects returns HTTP 200 even when some objects could not be deleted, and puts the failed keys in the Errors field of the response. clear() does not treat these failures as success; it throws an AggregateError whose errors property contains one Error per failed object.

How to fix

Check the errors property of the AggregateError, resolve the cause for each failed key (such as access permissions or the object’s state), and run clear() again.