@nxgt/s3 0.2.0 → 0.2.1

package/README.md

@@ -34,12 +34,15 @@ everything this package does not wrap is still there.
 ## Install
 
 ```sh
-bun add @nxgt/s3 typescript
+bun add @nxgt/s3 typescript @types/bun
 ```
 
 - **Bun 1.4 or later, and Bun only.** `S3Client` is built into Bun, which is
   why there is no SDK to install — and why this package does not run on Node.
 - `typescript` `^6.0.3`: required peer, the version every `@nxgt` package pins.
+- `@types/bun`: required to typecheck. The shipped declarations name Bun's own
+  `S3Client`, `S3File` and `S3Options`, so without Bun's types the first `tsc`
+  fails with `Cannot find module 'bun'`.
 - Tested against SeaweedFS 4.47's S3 gateway. Anything S3-compatible that Bun
   can sign for will do; a service that is not AWS wants
   `virtualHostedStyle: false`.
@@ -265,6 +268,15 @@ Each is a `@ts-expect-error` case in `test/types/s3.ts`.
   `undefined`; every other failure — a wrong secret, a refused request, a
   service that is down — comes back as the error it is.
 
+## Documentation
+
+- [docs/README.md](docs/README.md) — the guide index: buckets, reading,
+  writing and presigned URLs, each with its options and a worked example.
+- [docs/troubleshooting.md](docs/troubleshooting.md) — every error this
+  package can raise, by the message you will see.
+- [docs/roadmap.md](docs/roadmap.md) — what is coming, and what has been
+  ruled out.
+
 ## License
 
 MIT

package/docs/README.md

@@ -0,0 +1,16 @@
+# `@nxgt/s3` documentation
+
+S3 on Bun's own `S3Client`. `S3Client` is built into Bun, so this package has
+**no dependency at all** — no AWS SDK — and does not run on Node.
+
+| Page | Read it when |
+| --- | --- |
+| [Buckets](guide/buckets.md) | you are describing a bucket, building its keys, or binding it to credentials |
+| [Reading](guide/reads.md) | you want an object's bytes, its text, whether it is there, what the service knows about it, or a page of the bucket |
+| [Writing](guide/writes.md) | you are storing an object, choosing what a write says about it, or handling a refusal |
+| [Presigned URLs](guide/presigned-urls.md) | a browser or another service should read or write an object directly, without your credentials |
+| [Troubleshooting](troubleshooting.md) | a call threw, an upload was refused, or a signed URL did not do what you expected |
+| [Roadmap](roadmap.md) | you want to know what is coming, and what has been ruled out |
+
+The [README](../README.md) is the short version: install, one example per
+area, and the traps in one line each.

package/docs/guide/buckets.md

@@ -0,0 +1,170 @@
+# Buckets
+
+Describing a bucket once — which bucket, how a key is built, and what this
+application is willing to put there — then binding that description to
+credentials.
+
+## The smallest thing that works
+
+```ts
+import { bindBucket, defineBucket } from '@nxgt/s3';
+
+export const avatars = defineBucket({
+	bucket: 'avatars',
+	key: (p: { userId: string }) => `${p.userId}.png`,
+	contentType: ['image/png', 'image/jpeg'],
+	maxSize: 2 * 1024 * 1024, // bytes
+});
+
+const store = bindBucket(avatars, {
+	endpoint: process.env.S3_ENDPOINT,
+	accessKeyId: process.env.S3_KEY,
+	secretAccessKey: process.env.S3_SECRET,
+});
+
+store.keyFor({ userId: 'u1' }); // 'u1.png'
+```
+
+`defineBucket` talks to nothing, so the definition is what a server, a worker
+and a test import; `bindBucket` is the half that needs credentials.
+`S3Client` is built into Bun, which is why there is no SDK in `bun add` — and
+why this package does not run on Node.
+
+## The signatures
+
+```ts
+import type { S3Client, S3File, S3Options, S3Stats } from 'bun';
+
+interface BucketDefinition<P> {
+	readonly bucket: string;
+	readonly key: (params: P) => string;
+	readonly contentType?: string | readonly string[];
+	readonly maxSize?: number;
+}
+
+function defineBucket<P>(definition: BucketDefinition<P>): BucketDefinition<P>;
+
+function bindBucket<P>(
+	definition: BucketDefinition<P>,
+	options?: Omit<S3Options, 'bucket'>,
+): BoundBucket<P>;
+
+interface BoundBucket<P> {
+	readonly client: S3Client;
+	keyFor(params: P): string;
+	file(params: P): S3File;
+	put(params: P, body: PutBody, options?: PutOptions): Promise<void>;
+	bytes(params: P): Promise<Uint8Array | undefined>;
+	text(params: P): Promise<string | undefined>;
+	exists(params: P): Promise<boolean>;
+	stat(params: P): Promise<S3Stats | undefined>;
+	delete(params: P): Promise<void>;
+	list(options?: {
+		prefix?: string;
+		limit?: number;
+		cursor?: string | null;
+	}): Promise<ObjectPage>;
+	presignGet(params: P, options?: PresignOptions): string;
+	presignPut(params: P, options?: PresignOptions): string;
+}
+```
+
+## The definition
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `bucket` | `string` | required | the bucket's name on the service |
+| `key` | `(params: P) => string` | required | the object's key, from whatever identifies it |
+| `contentType` | `string \| readonly string[]` | anything goes | the content types this bucket accepts; a write of anything else is refused **before it is sent** |
+| `maxSize` | `number` | anything goes | the biggest body, in **bytes**, refused before it is sent |
+
+The key is a **function**, not a template, so nothing is spelled by hand at a
+call site and a renamed parameter is a compile error. `P` is whatever that
+function takes:
+
+```ts
+const uploads = defineBucket({
+	bucket: 'uploads',
+	key: (p: { folder: string; name: string }) => `${p.folder}/${p.name}`,
+});
+
+bindBucket(uploads).keyFor({ folder: 'a', name: 'b.txt' }); // 'a/b.txt'
+```
+
+`keyFor` exists so a caller that needs the string gets *the* string. Building
+one by hand somewhere else is how a bucket ends up with two spellings of the
+same object.
+
+What `contentType` and `maxSize` do is [Writing](writes.md); they are guards
+on `put`, and nothing else on the object goes through them.
+
+`defineBucket` refuses a definition that could never work, at import time:
+
+```ts
+defineBucket({ bucket: '', key: () => 'k' });
+// TypeError: defineBucket: a bucket definition needs a bucket
+
+defineBucket({ bucket: 'b', key: () => 'k', maxSize: 0 });
+// TypeError: defineBucket: "b" has a maxSize of 0; it is a number of bytes…
+
+defineBucket({ bucket: 'b', key: () => 'k', contentType: [] });
+// TypeError: … accepts an empty list of content types, so nothing could ever
+// be written. Leave `contentType` out to accept anything
+```
+
+The definition it gives back is frozen, so it cannot drift once it is shared.
+
+## Binding it
+
+`options` is Bun's own `S3Options` without `bucket` — the bucket comes from
+the definition, and a call may never change it. It is optional: given none,
+Bun reads its own `S3_*` / `AWS_*` environment variables.
+
+```ts
+const store = bindBucket(avatars); // credentials from the environment
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `endpoint` | `string` | AWS | the service's URL; anything S3-compatible Bun can sign for |
+| `accessKeyId` / `secretAccessKey` | `string` | `$S3_*` / `$AWS_*` | the credentials |
+| `sessionToken` | `string` | `$AWS_SESSION_TOKEN` | for temporary credentials |
+| `region` | `string` | `$S3_REGION` / `$AWS_REGION` | the region to sign for |
+| `virtualHostedStyle` | `boolean` | `false` | `bucket.host` URLs instead of `host/bucket`; a service that is not AWS usually wants it left off |
+| `acl`, `storageClass` | see [Writing](writes.md) | — | a default for every object this client writes |
+| `retry`, `partSize`, `queueSize` | `number` | Bun's | the client's own transfer tuning. A [`put`](writes.md) takes none of these: it is one PUT |
+
+Each bound bucket holds an `S3Client` of its own. S3 is stateless HTTP —
+there is no connection to share, and **nothing to close**.
+
+## Everything this package does not wrap
+
+```ts
+store.client;               // Bun's S3Client
+store.file({ userId: 'u1' }); // Bun's lazy S3File
+```
+
+`file(params)` is the handle for `.stream()`, `.slice()`, `.writer()` and the
+rest, keyed by the definition rather than by a string you typed. It is also
+the way to write a body in parts, which `put` does not do.
+
+## Types a caller names
+
+```ts
+import type { BoundBucket, ParamsOf } from '@nxgt/s3';
+
+type AvatarParams = ParamsOf<typeof avatars>; // { userId: string }
+
+async function purge(bucket: BoundBucket<AvatarParams>, userId: string) {
+	await bucket.delete({ userId });
+}
+```
+
+`stat` gives back Bun's own `S3Stats`, which this package does not re-export:
+import it from `bun` where you need to name it.
+
+## Next
+
+- [Writing](writes.md) — `put`, its options, and the guards.
+- [Reading](reads.md) — `bytes`, `text`, `stat`, `exists` and `list`.
+- [Presigned URLs](presigned-urls.md) — the same definition, signed.

package/docs/guide/presigned-urls.md

@@ -0,0 +1,153 @@
+# Presigned URLs
+
+Handing a browser or another service a URL that reads or writes one object,
+for a while, without ever handing over a credential.
+
+## The smallest thing that works
+
+```ts
+import { bindBucket, defineBucket } from '@nxgt/s3';
+
+const avatars = defineBucket({
+	bucket: 'avatars',
+	key: (p: { userId: string }) => `${p.userId}.png`,
+	contentType: ['image/png', 'image/jpeg'],
+	maxSize: 2 * 1024 * 1024,
+});
+
+const store = bindBucket(avatars);
+
+const download = store.presignGet({ userId: 'u1' }, { expiresIn: 300 }); // seconds
+const upload = store.presignPut({ userId: 'u1' }, { expiresIn: 300 });
+```
+
+Both are synchronous: signing is arithmetic, not a request. The key comes
+from the definition, so a signed URL and a `put` can never disagree about
+which object they mean — see [Buckets](buckets.md).
+
+## The signatures
+
+```ts
+import type { S3Options } from 'bun';
+
+presignGet(params: P, options?: PresignOptions): string;
+presignPut(params: P, options?: PresignOptions): string;
+
+interface PresignOptions {
+	expiresIn?: number;
+	acl?: S3Options['acl'];
+}
+```
+
+## Options
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `expiresIn` | `number` | Bun's, one day | **seconds** until the URL expires. Always pass one |
+| `acl` | `'private' \| 'public-read' \| …` | none | the ACL the URL is signed for, where the service honours it |
+
+A day is a long time for a URL that anyone can forward. Sign for the time the
+page actually needs:
+
+```ts
+const url = store.presignGet({ userId: 'u1' }, { expiresIn: 60 });
+const answer = await fetch(url);
+answer.status; // 200 — it really reads the object
+```
+
+## A presigned PUT constrains the key and the deadline, and nothing else
+
+Not the size. Not the content type.
+
+```ts
+const url = store.presignPut({ userId: 'u1' }, { expiresIn: 60 });
+
+await fetch(url, {
+	method: 'PUT',
+	body: Bun.file('archive.zip'),
+	headers: { 'content-type': 'application/zip' },
+});
+// 200 — stored, in a bucket whose definition says image/png only
+```
+
+That is why `presignPut` takes no `type`: it would read as a guarantee it
+cannot make. Measured on bun 1.4.2, `presign`'s `type` only adds
+`response-content-type` — S3's override for what a *download* is labelled —
+and `X-Amz-SignedHeaders` stays `host`, so the uploader's `Content-Type` is
+never signed.
+
+The bucket's `contentType` and `maxSize` are [`put`'s guards](writes.md),
+and whoever holds a signed URL is not going through `put`. Where it matters:
+
+- check with `stat` after the upload and delete what does not belong, or
+- enforce it in the service's own bucket policy.
+
+```ts
+const found = await store.stat({ userId: 'u1' });
+if (!found || !found.type.startsWith('image/')) {
+	await store.delete({ userId: 'u1' });
+}
+```
+
+## A URL is signed for the bound bucket, whatever the options say
+
+`PresignOptions` carries no `bucket`, `endpoint`, `region` or credential, and
+the run time signs with only the two keys above — anything else is dropped.
+
+```ts
+import type { PresignOptions } from '@nxgt/s3';
+
+// A bag off a request body never met the types.
+const bag = { expiresIn: 60, bucket: 'somewhere-else' } as PresignOptions;
+
+store.presignGet({ userId: 'u1' }, bag); // …/avatars/u1.png, on this endpoint
+```
+
+Measured before that filter existed, such a bag redirected the URL: a
+`bucket` key signed it for another bucket, and a credential key signed it
+against another endpoint entirely.
+
+## A real one: upload from the browser, read it back
+
+```ts
+import { Hono } from 'hono';
+import { bindBucket, defineBucket } from '@nxgt/s3';
+
+const avatars = defineBucket({
+	bucket: 'avatars',
+	key: (p: { userId: string }) => `${p.userId}.png`,
+	contentType: ['image/png', 'image/jpeg'],
+	maxSize: 2 * 1024 * 1024,
+});
+
+const store = bindBucket(avatars);
+const app = new Hono();
+
+// The browser PUTs the file straight to the service: no body through here.
+app.post('/users/:id/avatar/upload-url', (c) => {
+	const userId = c.req.param('id');
+	return c.json({
+		url: store.presignPut({ userId }, { expiresIn: 120 }),
+		key: store.keyFor({ userId }),
+	});
+});
+
+// …and the browser is told, later, where to read it.
+app.get('/users/:id/avatar', async (c) => {
+	const userId = c.req.param('id');
+	if (!(await store.exists({ userId }))) {
+		return c.json({ error: 'No avatar' }, 404);
+	}
+	return c.redirect(store.presignGet({ userId }, { expiresIn: 300 }));
+});
+```
+
+The upload route authorises the *user*; the URL it hands back authorises
+nothing else. Keep `expiresIn` close to how long an upload should take, and
+verify the object afterwards if the bucket's own policy does not.
+
+## Next
+
+- [Writing](writes.md) — the guards a presigned PUT bypasses.
+- [Reading](reads.md) — `stat` and `exists`, for checking what was uploaded.
+- [Troubleshooting](../troubleshooting.md) — a URL that 403s or expired.

package/docs/guide/reads.md

@@ -0,0 +1,186 @@
+# Reading
+
+Getting an object back — its bytes, its text, whether it is there, what the
+service knows about it — and walking a bucket page by page.
+
+## The smallest thing that works
+
+```ts
+import { bindBucket, defineBucket } from '@nxgt/s3';
+
+const reports = defineBucket({
+	bucket: 'reports',
+	key: (id: string) => `${id}.csv`,
+	contentType: 'text/csv',
+});
+
+const store = bindBucket(reports);
+
+const csv = await store.text('q1'); // string, or undefined
+if (csv === undefined) throw new Error('no such report'); // nothing stored
+```
+
+Describing and binding a bucket is [Buckets](buckets.md).
+
+## The signatures
+
+```ts
+import type { S3File, S3Stats } from 'bun';
+
+bytes(params: P): Promise<Uint8Array | undefined>;
+text(params: P): Promise<string | undefined>;
+stat(params: P): Promise<S3Stats | undefined>;
+exists(params: P): Promise<boolean>;
+file(params: P): S3File;
+
+list(options?: {
+	prefix?: string;
+	limit?: number;
+	cursor?: string | null;
+}): Promise<ObjectPage>;
+
+interface ObjectPage {
+	items: StoredObject[];
+	nextCursor: string | null;
+}
+
+interface StoredObject {
+	key: string;
+	size: number | undefined;
+	lastModified: Date | undefined;
+	eTag: string | undefined;
+}
+```
+
+## `undefined` means "no such object", and nothing else
+
+```ts
+await store.bytes('nobody'); // undefined
+await store.text('nobody');  // undefined
+await store.stat('nobody');  // undefined
+await store.exists('nobody'); // false
+```
+
+Each read goes straight at the object and turns S3's own `NoSuchKey` into
+`undefined`: one round trip, and no window in which an object deleted between
+a check and a read turns a promised `undefined` into a throw. **Every other
+failure comes back as the error it is** — a wrong secret, a refused request,
+a service that is down. A missing object and a missing permission must not
+read the same way.
+
+```ts
+const wrong = bindBucket(reports, { secretAccessKey: 'wrong-secret' });
+await wrong.text('q1'); // throws Bun's own S3Error, not undefined
+```
+
+## What the service knows
+
+```ts
+const found = await store.stat('q1');
+if (found) {
+	found.size;         // bytes
+	found.type;         // 'text/csv'
+	found.lastModified;
+	found.etag;         // note: lower case — that is Bun's field
+}
+```
+
+`stat` is Bun's own `S3Stats`, which this package does not re-export; import
+it from `bun` where you need to name it. A listing's `StoredObject` says
+`eTag`, because that is what S3 calls it there.
+
+## Big bodies, and everything else
+
+```ts
+const stream = store.file('q1').stream();
+const head = await store.file('q1').slice(0, 1024).text();
+```
+
+`file(params)` is Bun's lazy `S3File`, keyed by the definition. Use it to
+stream a body rather than hold it in memory, and to reach anything this
+package does not wrap.
+
+## Listing a bucket
+
+```ts
+let cursor: string | null = null;
+
+do {
+	const page = await store.list({ prefix: 'q1/', limit: 100, cursor });
+	for (const object of page.items) console.log(object.key, object.size);
+	cursor = page.nextCursor;
+} while (cursor !== null);
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `prefix` | `string` | the whole bucket | only keys that start with it |
+| `limit` | `number` | the service's | the **maximum** number of objects in a page, not a promise |
+| `cursor` | `string \| null` | `null` | the `nextCursor` of the previous page |
+
+`ObjectPage` is the same shape as the `CursorPage` of `@nxgt/drizzle` and
+`@nxgt/mongo`, so a caller pages the same way everywhere. S3's
+`continuationToken` is what `nextCursor` carries, and it is `null` on the
+last page.
+
+Page **until `nextCursor` is `null`**, never until a page is short: a listing
+is eventually consistent on some services, and a page may come back with
+fewer items than `limit` while there is still more to read. A prefix with
+nothing under it gives an empty page rather than nothing:
+
+```ts
+await store.list({ prefix: 'nothing-here/' }); // { items: [], nextCursor: null }
+```
+
+`list` is the bucket's, not an object's, so it takes no key parameters — and
+it does not count: S3 does not say how many objects there are, so there is no
+`total` and no page number.
+
+## A real one: a download route
+
+```ts
+import { Hono } from 'hono';
+import { bindBucket, defineBucket } from '@nxgt/s3';
+
+const reports = defineBucket({
+	bucket: 'reports',
+	key: (id: string) => `${id}.csv`,
+	contentType: 'text/csv',
+});
+
+const store = bindBucket(reports);
+const app = new Hono();
+
+app.get('/reports/:id', async (c) => {
+	const id = c.req.param('id');
+	const found = await store.stat(id);
+	if (!found) return c.json({ error: 'No such report' }, 404);
+
+	return new Response(store.file(id).stream(), {
+		headers: {
+			'content-type': found.type,
+			'content-length': String(found.size),
+			'content-disposition': `attachment; filename="${id}.csv"`,
+		},
+	});
+});
+
+app.get('/reports', async (c) => {
+	const page = await store.list({
+		limit: 50,
+		cursor: c.req.query('cursor') ?? null,
+	});
+	return c.json(page);
+});
+```
+
+`stat` is a HEAD, so this costs one round trip before the body is streamed —
+and it is what turns a missing object into a 404 rather than a broken stream.
+
+## Next
+
+- [Writing](writes.md) — `put`, its options and the guards.
+- [Presigned URLs](presigned-urls.md) — handing the download to the client
+  instead of streaming it through your server.
+- [Troubleshooting](../troubleshooting.md) — a read that threw instead of
+  answering `undefined`.

package/docs/guide/writes.md

@@ -0,0 +1,260 @@
+# Writing
+
+Storing an object, saying what it is and how it should be served back, and
+getting a refusal **before** anything goes over the wire.
+
+## The smallest thing that works
+
+```ts
+import { bindBucket, defineBucket } from '@nxgt/s3';
+
+const avatars = defineBucket({
+	bucket: 'avatars',
+	key: (p: { userId: string }) => `${p.userId}.png`,
+	contentType: ['image/png', 'image/jpeg'],
+	maxSize: 2 * 1024 * 1024,
+});
+
+const store = bindBucket(avatars);
+
+await store.put({ userId: 'u1' }, png, { type: 'image/png' });
+await store.delete({ userId: 'u1' });
+```
+
+Describing the bucket is [Buckets](buckets.md). `put` resolves when the
+object is stored, and gives back nothing: S3 has nothing to say beyond that.
+
+## The signatures
+
+```ts
+import type { S3Client, S3Options } from 'bun';
+
+/** A string, bytes, a Blob, a Bun.file, a stream, a Response… */
+type PutBody = Parameters<S3Client['write']>[1];
+
+type PutOptions = Pick<
+	S3Options,
+	'type' | 'acl' | 'storageClass' | 'contentDisposition' | 'contentEncoding'
+>;
+
+put(params: P, body: PutBody, options?: PutOptions): Promise<void>;
+delete(params: P): Promise<void>;
+```
+
+## What a body may be
+
+Anything Bun's own `write` takes:
+
+```ts
+await store.put({ userId: 'u1' }, 'a,b\n1,2\n', { type: 'text/csv' });
+await store.put({ userId: 'u1' }, new Uint8Array([1, 2, 3]), { type: 'image/png' });
+await store.put({ userId: 'u1' }, Bun.file('ada.png')); // the type comes from the file
+await store.put({ userId: 'u1' }, await fetch(url));    // only without `maxSize`
+```
+
+A `Blob` — `Bun.file` included — carries its own content type, so a write
+that names none is still checked against one. A string is measured in
+**bytes**, not characters.
+
+## What a write may say about the object
+
+Every option here describes **the object being stored**. A write says nothing
+about where it goes or how it gets there: the bucket, the endpoint, the
+region and the credentials belong to the bound bucket.
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `type` | `string` | the body's own, for a `Blob` | the content type. It is the one the guard checks **and** the one the service receives — they can never be two different answers |
+| `acl` | `'private' \| 'public-read' \| 'public-read-write' \| 'aws-exec-read' \| 'authenticated-read' \| 'bucket-owner-read' \| 'bucket-owner-full-control' \| 'log-delivery-write'` | the client's, else the service's | who may read the object, where the service implements ACLs |
+| `storageClass` | `'STANDARD' \| 'STANDARD_IA' \| 'ONEZONE_IA' \| 'INTELLIGENT_TIERING' \| 'GLACIER' \| 'GLACIER_IR' \| 'DEEP_ARCHIVE' \| 'REDUCED_REDUNDANCY' \| 'EXPRESS_ONEZONE' \| 'OUTPOSTS' \| 'SNOW'` | the client's, else `STANDARD` | what it costs to keep it; comes back as `x-amz-storage-class` |
+| `contentDisposition` | `string` | none | how a reader should present it; comes back on a `GET` |
+| `contentEncoding` | `string` | none | how the body is encoded; comes back on a `GET` |
+
+```ts
+await store.put({ userId: 'u1' }, png, {
+	type: 'image/png',
+	contentDisposition: 'attachment; filename="ada.png"',
+	contentEncoding: 'identity',
+	storageClass: 'STANDARD_IA',
+	acl: 'public-read',
+});
+```
+
+Measured against a real service: `contentDisposition` and `contentEncoding`
+come back as the headers of the same name on a read, and `storageClass` as
+`x-amz-storage-class`.
+
+These are Bun's own names, picked out of its `S3Options`, so a Bun release
+that changes one is a compile error here rather than a silent drift. Given
+both here and to `bindBucket`, the one on the write wins: it is the last
+thing handed to the client.
+
+### An option's *value* is Bun's to check, and Bun throws its own error
+
+The guards below own the content type and the size, and raise `S3Error`. A
+value outside one of Bun's unions is Bun's to refuse, and it refuses with a
+plain `TypeError`:
+
+```ts
+import type { PutOptions } from '@nxgt/s3';
+
+const bad = { type: 'text/plain', storageClass: 'NOPE' } as unknown as PutOptions;
+
+await store.put({ userId: 'u1' }, 'x', bad);
+// TypeError: storageClass must be one of …
+// `error instanceof S3Error` is false. Nothing was stored.
+```
+
+`acl` behaves the same way. `contentDisposition` and `contentEncoding` are
+plain strings to Bun and accept **anything** — nothing there is refused, by
+this package or by Bun. Nothing is sent in either case; it is the class a
+handler catches that differs. Validate a bag that arrives from a request body
+before passing it on.
+
+### A write cannot change where it goes
+
+`PutOptions` carries no `bucket`, `endpoint`, `region` or credential, and the
+run time forwards only the five keys above — a key that is not in that list
+is dropped, never sent.
+
+```ts
+// A bag off a request body never met the types.
+const smuggled = {
+	type: 'text/plain',
+	bucket: 'somewhere-else',
+	accessKeyId: 'someone-else',
+} as PutOptions;
+
+await store.put({ userId: 'u1' }, 'x', smuggled);
+// Stored in `avatars`, with the credentials the bucket was bound with.
+```
+
+Measured before that filter existed, spreading the caller's options straight
+through let a `bucket` key store the object in another bucket — and report
+success.
+
+### A `put` is one PUT
+
+`partSize`, `queueSize` and `retry` are not `PutOptions`: they belong to
+[`bindBucket`](buckets.md), where they are the client's own. Measured on bun
+1.4.2 against a 12 MiB body, a `put` with `partSize` set and one without come
+back with the **same** ETag, and neither carries the `-<parts>` suffix a
+multipart upload leaves. For a body that wants parts, use
+`store.file(params).writer()`.
+
+## The guards
+
+`contentType` and `maxSize` on the definition are checked in `put`, before
+the request goes out. A refused body is never sent.
+
+```ts
+import { S3Error } from '@nxgt/s3';
+
+try {
+	await store.put({ userId: 'u1' }, pdf, { type: 'application/pdf' });
+} catch (error) {
+	if (error instanceof S3Error) {
+		error.code; // 'WRONG_TYPE'
+		error.key;  // 'u1.png' — the key, never the body
+	}
+}
+```
+
+| `S3ErrorCode` | When |
+| --- | --- |
+| `WRONG_TYPE` | the type is not one this bucket accepts — or the write named none and the body carries none, while the bucket names some |
+| `TOO_LARGE` | the body is bigger than `maxSize`. The limit is inclusive: with `maxSize: 1024`, 1024 bytes passes and 1025 does not |
+| `UNMEASURABLE` | `maxSize` is set and the body's size cannot be known before sending |
+
+A content type is compared on its **essence**: parameters and case are
+ignored, and nothing else is. A bucket that accepts `text/csv` accepts
+`text/csv;charset=utf-8` and `TEXT/CSV`, because that is what real bodies
+carry — measured, `Bun.file` labels `.txt` as `text/plain;charset=utf-8` and
+`.csv` as the bare `text/csv`.
+
+```ts
+const reports = defineBucket({
+	bucket: 'reports',
+	key: (id: string) => `${id}.csv`,
+	contentType: 'text/csv',
+});
+const csv = bindBucket(reports);
+
+await csv.put('q1', Bun.file('q1.csv'));  // stored
+await csv.put('q1', Bun.file('note.txt')); // S3Error WRONG_TYPE, nothing sent
+```
+
+`UNMEASURABLE` is the one that surprises: with `maxSize` set, a `Response`, a
+`Request`, a stream or another `S3File` is **refused, not streamed** —
+nothing can check a length it has not read, and an `S3File` reports its size
+as `NaN` until the service has been asked. Read it into memory first, or
+leave `maxSize` out and let the service refuse an oversized body.
+
+```ts
+const answer = await fetch(url);
+const body = new Uint8Array(await answer.arrayBuffer()); // now it has a length
+await store.put({ userId: 'u1' }, body, { type: 'image/png' });
+```
+
+The guards are `put`'s, not the bucket's: `store.file(params).writer()`,
+`store.client` and anyone holding a [presigned PUT](presigned-urls.md) write
+whatever they are given. Set the service's own policy too where it matters.
+
+## Deleting
+
+```ts
+await store.delete({ userId: 'u1' });
+```
+
+S3 does not say whether anything was there, and nor does this. Call `exists`
+first when it matters — see [Reading](reads.md).
+
+## A real one: an upload route
+
+```ts
+import { Hono } from 'hono';
+import { bindBucket, defineBucket, S3Error } from '@nxgt/s3';
+
+const avatars = defineBucket({
+	bucket: 'avatars',
+	key: (p: { userId: string }) => `${p.userId}.png`,
+	contentType: ['image/png', 'image/jpeg'],
+	maxSize: 2 * 1024 * 1024,
+});
+
+const store = bindBucket(avatars);
+const app = new Hono();
+
+app.put('/users/:id/avatar', async (c) => {
+	const userId = c.req.param('id');
+	const body = await c.req.blob(); // a Blob: it carries its own type
+
+	try {
+		await store.put({ userId }, body, {
+			contentDisposition: `inline; filename="${userId}.png"`,
+		});
+	} catch (error) {
+		if (error instanceof S3Error && error.code === 'WRONG_TYPE') {
+			return c.json({ error: 'Send a PNG or a JPEG' }, 415);
+		}
+		if (error instanceof S3Error && error.code === 'TOO_LARGE') {
+			return c.json({ error: 'That file is too big' }, 413);
+		}
+		throw error;
+	}
+
+	return c.json({ key: store.keyFor({ userId }) }, 201);
+});
+```
+
+Every `S3Error` is thrown before the request goes out, so a 413 costs no
+bandwidth. Bun names **its own** S3 failures `S3Error` too, with S3's codes:
+discriminate with `instanceof S3Error` on this package's class, never with
+`error.name`.
+
+## Next
+
+- [Reading](reads.md) — reading back what was written.
+- [Presigned URLs](presigned-urls.md) — letting a browser upload directly,
+  and what that does *not* constrain.
+- [Troubleshooting](../troubleshooting.md) — each error with its fix.

package/docs/roadmap.md

@@ -0,0 +1,58 @@
+# Roadmap
+
+Where `@nxgt/s3` is going. A direction, not a commitment: the version an item
+shipped in is the only number on this page.
+
+## Now
+
+_Nothing in progress._
+
+## Next
+
+_Nothing queued._
+
+## Later
+
+- **Copy and move** — once Bun's own `S3Client` has them. Until then
+  `store.client` is where they live.
+
+## Not planned
+
+- **Running on Node** — the client is Bun's own `S3Client`, which is why this
+  package installs no AWS SDK at all. There is nothing to swap for Node, and a
+  build for it is not coming: it needs Bun 1.4 or later.
+- **Multipart upload** — a body goes out in one `put`. For anything bigger,
+  `store.file(params)` hands back Bun's own file handle and its `writer()`.
+- **Bucket administration** — creating, deleting or configuring a bucket is
+  not this package's, and Bun's client has no `createBucket` either.
+- **Retries or a cache of its own** — Bun's client already retries (three
+  attempts by default, and `retry` is passed through on `bindBucket`), and a
+  failed request comes back with S3's own error, as `S3Error`.
+- **Upload tuning on a `put`** — a `put` is a single PUT: measured against a
+  12 MiB body, `partSize` changes nothing, right down to the ETag carrying no
+  `-<parts>` suffix. `PutOptions` describes the object, not the transfer.
+- **An option that says where a write goes** — `bucket`, `endpoint`, `region`
+  and the credentials belong to the bound bucket, and are refused by the types
+  and again at run time. Measured: passing them through let a bag store the
+  object in a different bucket and report success, and redirected a signed URL
+  the same way.
+
+## Shipped
+
+- **Documentation that travels with the package** — a guide page for the
+  bucket definition, writes, reads and presigned URLs, a troubleshooting page
+  whose headings are the exact error text, and this roadmap, installed in
+  `docs/` rather than left on GitHub — 0.2.1.
+- **What a write may say about the object** — `contentDisposition`,
+  `contentEncoding`, `acl` and `storageClass` on `put`, with Bun's own names;
+  an option naming another bucket, endpoint, region or credential is refused,
+  on `put` and on both `presign` calls — 0.2.0.
+- **First release** — `defineBucket` naming the bucket, the key-building
+  function, the content types it accepts and the biggest body it takes, and
+  `bindBucket` giving `put`, `bytes`, `text`, `exists`, `stat`, `delete`, a
+  cursor `list` and `presignGet` / `presignPut`; the content type and the size
+  are checked before the request goes out, and its one error is `S3Error` —
+  0.1.0.
+
+Everything released is in [`CHANGELOG.md`](https://github.com/softistx/nxgt-data/blob/develop/packages/s3/CHANGELOG.md) — it is not in
+the published package, only in the repository.

package/docs/troubleshooting.md

@@ -0,0 +1,276 @@
+# Troubleshooting
+
+This package throws one error of its own, `S3Error`, with a `code` of
+`WRONG_TYPE`, `TOO_LARGE` or `UNMEASURABLE`, and the object `key` it was
+about — never the body. Every one of them is raised **before** anything is
+sent. The service's own failures, and the checks Bun makes on an option's
+value, come back as Bun raises them; the entries below say which is which.
+The Bun messages were measured on Bun 1.4.2.
+
+- **Install and import**
+  - [`Cannot find package 'bun'`](#cannot-find-package-bun)
+  - [`Cannot find module 'bun' or its corresponding type declarations.`](#cannot-find-module-bun-or-its-corresponding-type-declarations)
+- **Configuration**
+  - [`defineBucket: a bucket definition needs a bucket`](#definebucket-a-bucket-definition-needs-a-bucket)
+  - [`defineBucket: "avatars" has a maxSize of 0; it is a number of bytes, and must be above zero`](#definebucket-avatars-has-a-maxsize-of-0-it-is-a-number-of-bytes-and-must-be-above-zero)
+  - [`defineBucket: "avatars" accepts an empty list of content types, so nothing could ever be written. …`](#definebucket-avatars-accepts-an-empty-list-of-content-types-so-nothing-could-ever-be-written-)
+- **Writes refused before they are sent**
+  - [`"avatars" accepts image/png, image/jpeg, not application/pdf`](#avatars-accepts-imagepng-imagejpeg-not-applicationpdf)
+  - [``"avatars" accepts image/png, image/jpeg, and this write names no content type. Pass `type` ``](#avatars-accepts-imagepng-imagejpeg-and-this-write-names-no-content-type-pass-type-)
+  - [`"avatars" accepts 2097152 bytes at most, and this body is 5242880`](#avatars-accepts-2097152-bytes-at-most-and-this-body-is-5242880)
+  - [`"avatars" has a maxSize, and this body's size cannot be known before sending it. …`](#avatars-has-a-maxsize-and-this-bodys-size-cannot-be-known-before-sending-it-)
+  - [`storageClass must be one of "STANDARD", "STANDARD_IA", "INTELLIGENT_TIERING", …`](#storageclass-must-be-one-of-standard-standard_ia-intelligent_tiering-)
+  - [`acl must be one of "private", "public-read", "public-read-write", …`](#acl-must-be-one-of-private-public-read-public-read-write-)
+- **The service**
+  - [`Missing S3 credentials. 'accessKeyId', 'secretAccessKey', 'bucket', and 'endpoint' are required`](#missing-s3-credentials-accesskeyid-secretaccesskey-bucket-and-endpoint-are-required)
+  - [`The AWS Access Key Id you provided does not exist in our records.`](#the-aws-access-key-id-you-provided-does-not-exist-in-our-records)
+  - [A presigned upload stored a body the bucket would have refused](#a-presigned-upload-stored-a-body-the-bucket-would-have-refused)
+  - [A listing came back short with a cursor still set](#a-listing-came-back-short-with-a-cursor-still-set)
+
+## Install and import
+
+### `Cannot find package 'bun'`
+
+**When:** importing `@nxgt/s3` under Node — the full line names the file it
+was imported from.
+**Why:** the client is Bun's own `S3Client`, which is why there is no AWS SDK
+to install and why this package does not run on Node. Measured on Node 22.
+**Fix:**
+
+```sh
+bun run ./src/index.ts   # Bun 1.4 or later
+```
+
+### `Cannot find module 'bun' or its corresponding type declarations.`
+
+**When:** typechecking, on the first file that imports `@nxgt/s3`.
+**Why:** the shipped declarations import `S3Client`, `S3File` and `S3Options`
+from `bun`, so your project needs Bun's types. They are not a dependency of
+this package.
+**Fix:**
+
+```sh
+bun add -d @types/bun
+```
+
+## Configuration
+
+### `defineBucket: a bucket definition needs a bucket`
+
+**When:** at `defineBucket`, with an empty `bucket`.
+**Why:** the bucket name is what every key is written under; an empty one
+cannot be meant.
+**Fix:**
+
+```ts
+export const avatars = defineBucket({
+	bucket: 'avatars',
+	key: (p: { userId: string }) => `${p.userId}.png`,
+});
+```
+
+### `defineBucket: "avatars" has a maxSize of 0; it is a number of bytes, and must be above zero`
+
+**When:** at `defineBucket`.
+**Why:** `maxSize` is a number of **bytes**, and it is inclusive: 1024 passes
+and 1025 does not. A string body is measured in bytes, not in characters.
+**Fix:**
+
+```ts
+defineBucket({ bucket: 'avatars', key, maxSize: 2 * 1024 * 1024 });
+```
+
+### `defineBucket: "avatars" accepts an empty list of content types, so nothing could ever be written. …`
+
+**When:** at `defineBucket`, with `contentType: []`.
+**Why:** an empty list refuses every write. The message ends with the way out,
+``Leave `contentType` out to accept anything``: leaving the option out is what
+accepts anything, and `[]` is never what was meant.
+**Fix:**
+
+```ts
+defineBucket({ bucket: 'avatars', key, contentType: ['image/png', 'image/jpeg'] });
+```
+
+## Writes refused before they are sent
+
+### `"avatars" accepts image/png, image/jpeg, not application/pdf`
+
+**When:** `put` or `presignGet`, with a `type` the definition does not list.
+**Why:** an `S3Error` with `code: 'WRONG_TYPE'`. Nothing was sent. The type
+is compared on its **essence**: `text/csv` accepts `text/csv;charset=utf-8`
+and `TEXT/CSV`, because that is what real bodies carry — parameters and case
+are ignored, nothing else is.
+**Fix:**
+
+```ts
+import { S3Error } from '@nxgt/s3';
+
+try {
+	await avatars.put({ userId }, body, { type: file.type });
+} catch (error) {
+	if (error instanceof S3Error && error.code === 'WRONG_TYPE') return badRequest();
+	throw error;
+}
+```
+
+### ``"avatars" accepts image/png, image/jpeg, and this write names no content type. Pass `type` ``
+
+**When:** `put` on a bucket with `contentType`, for a body that carries no
+type of its own — a string, a typed array, a stream.
+**Why:** the guard cannot accept what it cannot read, so an unnamed type is
+refused rather than guessed. `code: 'WRONG_TYPE'`.
+**Fix:**
+
+```ts
+await avatars.put({ userId }, bytes, { type: 'image/png' });
+```
+
+`Bun.file(path)` carries its own type, and does not need the option.
+
+### `"avatars" accepts 2097152 bytes at most, and this body is 5242880`
+
+**When:** `put`, for a body whose size is known and above `maxSize`.
+**Why:** an `S3Error` with `code: 'TOO_LARGE'`, raised before the request goes
+out.
+**Fix:**
+
+```ts
+if (error instanceof S3Error && error.code === 'TOO_LARGE') return payloadTooLarge();
+```
+
+### `"avatars" has a maxSize, and this body's size cannot be known before sending it. …`
+
+**When:** `put` with `maxSize` set, for a `Response`, a `Request`, a stream or
+another `S3File`.
+**Why:** nothing can check a length it has not read — an `S3File` reports its
+size as `NaN` until the service has been asked — so the write is refused
+rather than streamed unchecked. `code: 'UNMEASURABLE'`. The message ends with
+the two ways out, ``Read it into memory first, or drop `maxSize` and let the
+service refuse it``.
+**Fix:**
+
+```ts
+await avatars.put({ userId }, await response.bytes()); // read it in first
+```
+
+Or drop `maxSize` from the definition and let the service refuse an oversized
+body.
+
+### `storageClass must be one of "STANDARD", "STANDARD_IA", "INTELLIGENT_TIERING", …`
+
+**When:** `put` or `presignPut` with a `storageClass` Bun does not know.
+**Why:** an option's **value** is Bun's to check, and it throws **Bun's own
+`TypeError`** — not an `S3Error`. `instanceof S3Error` is false, and
+`error.code` is not one of this package's. Nothing is sent either way; it is
+the class a handler catches that differs.
+**Fix:**
+
+```ts
+import type { PutOptions } from '@nxgt/s3';
+
+// the classes this application allows, proved against Bun's own list
+const CLASSES = ['STANDARD', 'STANDARD_IA'] as const satisfies readonly NonNullable<
+	PutOptions['storageClass']
+>[];
+
+function storageClassOf(value: string | undefined): PutOptions['storageClass'] {
+	return CLASSES.find((known) => known === value); // undefined: the bucket's default
+}
+
+await avatars.put({ userId }, bytes, { storageClass: storageClassOf(body.storageClass) });
+```
+
+Catch `TypeError` beside `S3Error` where such a value can reach a call.
+
+### `acl must be one of "private", "public-read", "public-read-write", …`
+
+**When:** `put`, `presignGet` or `presignPut` with an `acl` Bun does not
+know.
+**Why:** the same as `storageClass`: Bun's own `TypeError`, before anything is
+sent. `contentDisposition` and `contentEncoding`, by contrast, are plain
+strings to Bun and accept anything.
+**Fix:**
+
+```ts
+await avatars.put({ userId }, bytes, { acl: 'public-read' });
+```
+
+## The service
+
+### `Missing S3 credentials. 'accessKeyId', 'secretAccessKey', 'bucket', and 'endpoint' are required`
+
+**When:** the first call, when neither `bindBucket`'s options nor the
+environment gave the client credentials. Bun's error, `code:
+'ERR_S3_MISSING_CREDENTIALS'`.
+**Why:** `bindBucket` creates the `S3Client` for you and passes your options
+through; with none, Bun falls back to the environment, and to AWS's endpoint.
+**Fix:**
+
+```ts
+export const avatars = bindBucket(avatarsDefinition, {
+	endpoint: process.env.S3_ENDPOINT,
+	accessKeyId: process.env.S3_KEY,
+	secretAccessKey: process.env.S3_SECRET,
+	virtualHostedStyle: false, // for a service that is not AWS
+});
+```
+
+### `The AWS Access Key Id you provided does not exist in our records.`
+
+**When:** the first call, with credentials the service refuses — or with no
+`endpoint`, which sends the request to AWS whatever your service is.
+**Why:** it is the **service's** answer, raised by Bun as an error whose
+`name` is `S3Error` and whose `code` is the S3 code (`InvalidAccessKeyId`,
+`SignatureDoesNotMatch`, `NoSuchBucket`, `AccessDenied`). It is **not** this
+package's `S3Error` class: `instanceof S3Error` is false for it.
+**Fix:**
+
+```ts
+try {
+	await avatars.put({ userId }, bytes);
+} catch (error) {
+	if (error instanceof S3Error) return badRequest(error.code); // ours: the guards
+	throw error; // the service's, or Bun's: log the code it carries
+}
+```
+
+`bytes`, `text` and `stat` are the exception: they turn S3's own `NoSuchKey`
+into `undefined`, so `undefined` means "no such object" and nothing else.
+Every other failure comes back as the error it is.
+
+### A presigned upload stored a body the bucket would have refused
+
+**When:** after handing out a `presignPut` URL. No error anywhere.
+**Why:** a presigned PUT constrains the key and the deadline, and nothing
+else. Measured on Bun 1.4: `X-Amz-SignedHeaders` stays `host`, so the
+uploader's `Content-Type` is never signed and the size is never checked —
+which is why `presignPut` takes no `type` at all. The guards are `put`'s;
+`file(params).writer()` and `client` are Bun's own and write whatever they
+are given.
+**Fix:**
+
+```ts
+const url = avatars.presignPut({ userId }, { expiresIn: 300 });
+// after the upload, check what actually landed
+const stat = await avatars.stat({ userId });
+if (!stat || stat.size > maxSize) await avatars.delete({ userId });
+```
+
+Set the service's own bucket policy too where it matters.
+
+### A listing came back short with a cursor still set
+
+**When:** `list`, on an eventually consistent service.
+**Why:** `limit` is a maximum, not a promise.
+**Fix:**
+
+```ts
+let cursor: string | null = null;
+do {
+	const page = await avatars.list({ prefix, limit: 100, cursor });
+	cursor = page.nextCursor;
+} while (cursor !== null);
+```
+
+Page until `nextCursor` is `null`, never until a page is short.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/s3",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "S3 on Bun's own client: buckets described once, keys built by a typed function, uploads refused before they are sent, and presigned URLs from the same definition",
 	"license": "MIT",
 	"type": "module",
@@ -8,6 +8,7 @@
 	"types": "./dist/index.d.ts",
 	"files": [
 		"dist",
+		"docs",
 		"README.md",
 		"package.json",
 		"LICENSE"