@nxgt/s3 0.1.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`.
@@ -53,7 +56,8 @@ bun add @nxgt/s3 typescript
 - **No copy or move.** `store.client` is where those live when Bun grows them.
 - **It adds no retry and no cache of its own.** A failed request comes back
   with S3's own error. Bun's client does retry — `retry`, three attempts by
-  default — and that option is passed through like the rest.
+  default — and that option is passed through to `bindBucket` like the rest;
+  a `put` does not take it.
 
 ## API
 
@@ -84,7 +88,7 @@ stateless HTTP, so there is no connection to share and nothing to close.
 | `client` | the `S3Client` this holds |
 | `keyFor(params)` | the key it would use |
 | `file(params)` | Bun's lazy `S3File`: `.stream()`, `.slice()`, `.writer()` |
-| `put(params, body, options?)` | writes it, once the content type and size have accepted it. `options.type` names the body's content type; a `Blob` is asked for its own when none is given |
+| `put(params, body, options?)` | writes it, once the content type and size have accepted it. See `PutOptions` below |
 | `bytes(params)` | the bytes, or `undefined` when there is no such object |
 | `text(params)` | the body as text, or `undefined` |
 | `exists(params)` | |
@@ -94,6 +98,33 @@ stateless HTTP, so there is no connection to share and nothing to close.
 | `presignGet(params, { expiresIn, acl })` | a signed URL that reads it |
 | `presignPut(params, { expiresIn, acl })` | a signed URL that writes it. It takes no `type` — see the Traps |
 
+### What a write may say
+
+```ts
+await store.put({ userId: 'u1' }, Bun.file('ada.png'));   // the type comes from the file
+await store.put({ userId: 'u1' }, png, {
+	type: 'image/png',
+	contentDisposition: 'attachment; filename="ada.png"',
+	storageClass: 'STANDARD_IA',
+});
+```
+
+| `PutOptions` | |
+| --- | --- |
+| `type` | the body's content type. A `Blob` — `Bun.file` included — is asked for its own when none is given, and *that* is the type the guard checks and the service receives |
+| `contentDisposition` | how a reader should present it: measured, it comes back on a `GET` |
+| `contentEncoding` | how the body is encoded, likewise returned on a read |
+| `acl` | who may read it, where the service implements ACLs |
+| `storageClass` | what it costs to keep, returned 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. Every
+one of them describes the **object**; a write says nothing about where it
+goes, or how it gets there — see the Traps.
+
+Given both here and to `bindBucket`, the one on the write wins: it is the
+last thing handed to the client.
+
 ### Listing
 
 ```ts
@@ -121,6 +152,7 @@ it carries.
 | `PresignOptions` | `{ expiresIn?: number; acl?: … }` |
 | `ParamsOf<D>` | what a definition's `key` takes, for a caller writing its own helper |
 | `PutBody` | everything Bun's `write` takes |
+| `PutOptions` | what one write may say about the object — see above |
 
 `stat` gives back Bun's own `S3Stats`, which this package does not re-export;
 import it from `bun` where you need to name it.
@@ -156,6 +188,10 @@ Each is a `@ts-expect-error` case in `test/types/s3.ts`.
 
 - An object read, written, deleted or signed for with the wrong key
   parameters, and a `put` given a misspelt option.
+- A `put` or a presigned URL naming a `bucket`, an `endpoint`, a `region` or
+  a credential: a write says what the object is, never where it goes.
+- A `put` given `partSize`, `queueSize` or `retry`: those are the client's,
+  and a `put` is one PUT.
 - A `presignPut` given a `type`: a presigned PUT constrains no content type,
   so it takes none.
 - A definition with no `bucket`, no `key`, a `key` that gives something other
@@ -188,9 +224,33 @@ Each is a `@ts-expect-error` case in `test/types/s3.ts`.
   memory first, or leave `maxSize` out and let the service refuse it.
 - **A content type is compared on its essence.** `text/csv` accepts
   `text/csv;charset=utf-8` and `TEXT/CSV`, because that is what real bodies
-  carry: `Bun.file('a.csv').type` is `text/csv;charset=utf-8`, and a text
-  `Blob` adds the charset by itself. Parameters and case are ignored; nothing
-  else is.
+  carry. Measured on bun 1.4.2, `Bun.file` puts a charset on some types and
+  not others — `.txt` is `text/plain;charset=utf-8` and `.json` is
+  `application/json;charset=utf-8`, while `.csv` is the bare `text/csv` — so
+  a definition that named either form would refuse half the files it exists
+  for. Parameters and case are ignored; nothing else is.
+- **A write names the object, never where it goes.** `PutOptions` and
+  `PresignOptions` carry no `bucket`, `endpoint`, `region` or credential, and
+  the run time forwards only the keys they list. The types are not enough on
+  their own: a bag that arrives in a request body never met them. Measured,
+  spreading it straight through let a `bucket` key store the object in
+  **another bucket** and report success, and sign a URL for that bucket —
+  a credential key signed one against another endpoint entirely.
+- **A `put` is one PUT, so it takes no upload tuning.** `partSize`,
+  `queueSize` and `retry` belong to `bindBucket`, 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. Use `file(params).writer()`
+  for a body that wants parts.
+- **An option's *value* is Bun's to check, and it throws Bun's error.** The
+  guards refuse a content type and a size before anything is sent, and raise
+  `S3Error`. An `acl` or a `storageClass` outside what Bun accepts raises
+  Bun's own `TypeError` instead — measured:
+  `storageClass: 'NOPE'` gives `TypeError: storageClass must be one of …`, and
+  `instanceof S3Error` is false. `contentDisposition` and `contentEncoding`
+  are plain strings to Bun and accept anything. Nothing is sent either way; it
+  is the class a handler catches that differs, so validate a bag from a
+  request body before passing it on.
 - **A string body is measured in bytes, not in characters**, and `maxSize` is
   inclusive: 1024 passes, 1025 does not.
 - **`expiresIn` is seconds, and Bun's default is a day.** Always pass one.
@@ -208,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/dist/bucket/bind-bucket.d.ts

@@ -1,6 +1,6 @@
 import { S3Client, type S3File, type S3Options, type S3Stats } from 'bun';
 import { type PresignOptions } from './operations/presign';
-import type { BucketDefinition, ObjectPage, PutBody } from './types';
+import type { BucketDefinition, ObjectPage, PutBody, PutOptions } from './types';
 export type { PresignOptions };
 /** A bucket bound to credentials: the definition, with somewhere to put it. */
 export interface BoundBucket<P> {
@@ -10,10 +10,15 @@ export interface BoundBucket<P> {
     keyFor(params: P): string;
     /** Bun's own lazy handle: `.stream()`, `.slice()`, `.writer()` and the rest. */
     file(params: P): S3File;
-    /** Writes it, once the bucket's content type and size have accepted it. */
-    put(params: P, body: PutBody, options?: {
-        type?: string;
-    }): Promise<void>;
+    /**
+     * Writes it, once the bucket's content type and size have accepted it.
+     *
+     * Beyond `type`, an option here describes **this object** — how it is
+     * served back (`contentDisposition`, `contentEncoding`), who may read it
+     * (`acl`), what it costs to keep (`storageClass`) — or how a large body is
+     * uploaded (`partSize`, `queueSize`, `retry`).
+     */
+    put(params: P, body: PutBody, options?: PutOptions): Promise<void>;
     /** The bytes, or `undefined` when there is no such object. */
     bytes(params: P): Promise<Uint8Array | undefined>;
     /** The body as text, or `undefined` when there is no such object. */

package/dist/bucket/bind-bucket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bind-bucket.d.ts","sourceRoot":"","sources":["../../src/bucket/bind-bucket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAG1E,OAAO,EACN,KAAK,cAAc,EAGnB,MAAM,sBAAsB,CAAC;AAQ9B,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAErE,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B,+EAA+E;AAC/E,MAAM,WAAW,WAAW,CAAC,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,yEAAyE;IACzE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC;IAC1B,gFAAgF;IAChF,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC;IACxB,2EAA2E;IAC3E,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,8DAA8D;IAC9D,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAClD,qEAAqE;IACrE,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,4EAA4E;IAC5E,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IAC9C,iFAAiF;IACjF,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,iEAAiE;IACjE,IAAI,CAAC,OAAO,CAAC,EAAE;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACxB,4CAA4C;IAC5C,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC;IACxD;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC;CACxD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC3B,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,OAAO,GAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAM,GACrC,WAAW,CAAC,CAAC,CAAC,CAoBhB"}
+{"version":3,"file":"bind-bucket.d.ts","sourceRoot":"","sources":["../../src/bucket/bind-bucket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAG1E,OAAO,EACN,KAAK,cAAc,EAGnB,MAAM,sBAAsB,CAAC;AAQ9B,OAAO,KAAK,EACX,gBAAgB,EAChB,UAAU,EACV,OAAO,EACP,UAAU,EACV,MAAM,SAAS,CAAC;AAEjB,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B,+EAA+E;AAC/E,MAAM,WAAW,WAAW,CAAC,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,yEAAyE;IACzE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC;IAC1B,gFAAgF;IAChF,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,8DAA8D;IAC9D,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAClD,qEAAqE;IACrE,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,4EAA4E;IAC5E,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IAC9C,iFAAiF;IACjF,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,iEAAiE;IACjE,IAAI,CAAC,OAAO,CAAC,EAAE;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACxB,4CAA4C;IAC5C,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC;IACxD;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC;CACxD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC3B,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,OAAO,GAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAM,GACrC,WAAW,CAAC,CAAC,CAAC,CAoBhB"}

package/dist/bucket/operations/presign.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presign.d.ts","sourceRoot":"","sources":["../../../src/bucket/operations/presign.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,EAAE,KAAK,aAAa,EAAS,MAAM,YAAY,CAAC;AAEvD,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC9B,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;CACvB;AAED,wBAAgB,aAAa,CAAC,CAAC,EAC9B,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,cAAc,GACtB,MAAM,CAKR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC9B,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,cAAc,GACtB,MAAM,CAKR"}
+{"version":3,"file":"presign.d.ts","sourceRoot":"","sources":["../../../src/bucket/operations/presign.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,EAAE,KAAK,aAAa,EAAS,MAAM,YAAY,CAAC;AAEvD,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC9B,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;CACvB;AA4BD,wBAAgB,aAAa,CAAC,CAAC,EAC9B,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,cAAc,GACtB,MAAM,CAKR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC9B,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,cAAc,GACtB,MAAM,CAKR"}

package/dist/bucket/operations/writes.d.ts

@@ -1,12 +1,10 @@
 import { type BucketContext } from '../context';
-import type { PutBody } from '../types';
+import type { PutBody, PutOptions } from '../types';
 /**
  * Writes it, once the bucket's content type and size have accepted it. Both
  * guards run before `write` is called, so a refused body is never sent.
  */
-export declare function putObject<P>(context: BucketContext<P>, params: P, body: PutBody, options?: {
-    type?: string;
-}): Promise<void>;
+export declare function putObject<P>(context: BucketContext<P>, params: P, body: PutBody, options?: PutOptions): Promise<void>;
 /** Removes it. S3 does not say whether anything was there, and nor does this. */
 export declare function deleteObject<P>(context: BucketContext<P>, params: P): Promise<void>;
 //# sourceMappingURL=writes.d.ts.map

package/dist/bucket/operations/writes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writes.d.ts","sourceRoot":"","sources":["../../../src/bucket/operations/writes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAS,MAAM,YAAY,CAAC;AAEvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC;;;GAGG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAChC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACzB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,CAAC,EAC7B,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,CAAC,GACP,OAAO,CAAC,IAAI,CAAC,CAEf"}
+{"version":3,"file":"writes.d.ts","sourceRoot":"","sources":["../../../src/bucket/operations/writes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAS,MAAM,YAAY,CAAC;AAEvD,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEpD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAChC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,UAAe,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AAyCD,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,CAAC,EAC7B,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,CAAC,GACP,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/bucket/types.d.ts

@@ -42,11 +42,32 @@ export interface ObjectPage {
 }
 /** What a definition's `key` takes, so a caller can write its own helper. */
 export type ParamsOf<D> = D extends BucketDefinition<infer P> ? P : never;
-import type { S3Client } from 'bun';
+import type { S3Client, S3Options } from 'bun';
 /**
  * Everything Bun's own `write` takes — a string, bytes, a `Blob`, a stream, a
  * `Response`. A bucket with a `maxSize` refuses the ones whose size cannot be
  * known before sending; one without accepts them all.
  */
 export type PutBody = Parameters<S3Client['write']>[1];
+/**
+ * What a single write may say about **the object it stores**.
+ *
+ * Picked out of Bun's own `S3Options` rather than written again here, so a
+ * Bun release that changes one of these is a compile error instead of a
+ * silent drift.
+ *
+ * Only what describes the object is here. The credentials, the endpoint, the
+ * bucket and the region belong to the bound bucket — naming them per write
+ * would let one call store the object somewhere the definition never
+ * described. `partSize`, `queueSize` and `retry` are not here either:
+ * measured on bun 1.4.2 against a 12 MiB body, a `put` with `partSize` set
+ * and one without produce the **same** ETag, with no `-<parts>` suffix — so
+ * a single PUT either way, and offering them would promise a multipart
+ * upload this package does not do. `bindBucket` still takes them, where they
+ * are the client's own.
+ *
+ * `type` is the one the guards read — see `effectiveType`. The rest reach
+ * the service untouched.
+ */
+export type PutOptions = Pick<S3Options, 'type' | 'acl' | 'storageClass' | 'contentDisposition' | 'contentEncoding'>;
 //# sourceMappingURL=types.d.ts.map

package/dist/bucket/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/bucket/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IAClC,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAClD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,YAAY,EAAE,IAAI,GAAG,SAAS,CAAC;IAC/B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,qEAAqE;IACrE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,6EAA6E;AAC7E,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,gBAAgB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE1E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAEpC;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/bucket/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IAClC,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAClD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,YAAY,EAAE,IAAI,GAAG,SAAS,CAAC;IAC/B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,qEAAqE;IACrE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,6EAA6E;AAC7E,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,gBAAgB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE1E,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAE/C;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAC5B,SAAS,EACT,MAAM,GAAG,KAAK,GAAG,cAAc,GAAG,oBAAoB,GAAG,iBAAiB,CAC1E,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export type { BoundBucket, PresignOptions } from './bucket/bind-bucket';
 export { bindBucket } from './bucket/bind-bucket';
 export { defineBucket } from './bucket/define-bucket';
-export type { BucketDefinition, ObjectPage, ParamsOf, PutBody, StoredObject, } from './bucket/types';
+export type { BucketDefinition, ObjectPage, ParamsOf, PutBody, PutOptions, StoredObject, } from './bucket/types';
 export type { S3ErrorCode } from './errors/s3-error';
 export { S3Error } from './errors/s3-error';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EACX,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACR,OAAO,EACP,YAAY,GACZ,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EACX,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACR,OAAO,EACP,UAAU,EACV,YAAY,GACZ,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -37,15 +37,24 @@ async function listObjects(context, options = {}) {
 }
 
 // src/bucket/operations/presign.ts
+var SIGNED = ["expiresIn", "acl"];
+function signed(options) {
+  const forwarded = {};
+  for (const key of SIGNED) {
+    if (options?.[key] !== undefined)
+      forwarded[key] = options[key];
+  }
+  return forwarded;
+}
 function presignGetUrl(context, params, options) {
   return context.client.presign(keyOf(context, params), {
-    ...options,
+    ...signed(options),
     method: "GET"
   });
 }
 function presignPutUrl(context, params, options) {
   return context.client.presign(keyOf(context, params), {
-    ...options,
+    ...signed(options),
     method: "PUT"
   });
 }
@@ -128,12 +137,29 @@ function checkSize(context, key, body) {
 }
 
 // src/bucket/operations/writes.ts
-async function putObject(context, params, body, options) {
+async function putObject(context, params, body, options = {}) {
   const key = keyOf(context, params);
-  const type = effectiveType(body, options?.type);
+  const type = effectiveType(body, options.type);
   checkType(context, key, type);
   checkSize(context, key, body);
-  await context.client.write(key, body, type ? { type } : undefined);
+  await context.client.write(key, body, {
+    ...passed(options),
+    ...type ? { type } : {}
+  });
+}
+var PASSED = [
+  "acl",
+  "storageClass",
+  "contentDisposition",
+  "contentEncoding"
+];
+function passed(options) {
+  const forwarded = {};
+  for (const key of PASSED) {
+    if (options[key] !== undefined)
+      forwarded[key] = options[key];
+  }
+  return forwarded;
 }
 function deleteObject(context, params) {
   return context.client.delete(keyOf(context, params));
@@ -181,5 +207,5 @@ export {
   defineBucket
 };
 
-//# debugId=4049B661AFFFECB264756E2164756E21
+//# debugId=F9842873CB32A8B764756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -2,17 +2,17 @@
   "version": 3,
   "sources": ["../src/bucket/bind-bucket.ts", "../src/bucket/context.ts", "../src/bucket/operations/list.ts", "../src/bucket/operations/presign.ts", "../src/bucket/operations/reads.ts", "../src/errors/s3-error.ts", "../src/bucket/guards.ts", "../src/bucket/operations/writes.ts", "../src/bucket/define-bucket.ts"],
   "sourcesContent": [
-    "import { S3Client, type S3File, type S3Options, type S3Stats } from 'bun';\nimport { bucketContext, keyOf } from './context';\nimport { listObjects } from './operations/list';\nimport {\n\ttype PresignOptions,\n\tpresignGetUrl,\n\tpresignPutUrl,\n} from './operations/presign';\nimport {\n\tobjectExists,\n\treadBytes,\n\treadText,\n\tstatObject,\n} from './operations/reads';\nimport { deleteObject, putObject } from './operations/writes';\nimport type { BucketDefinition, ObjectPage, PutBody } from './types';\n\nexport type { PresignOptions };\n\n/** A bucket bound to credentials: the definition, with somewhere to put it. */\nexport interface BoundBucket<P> {\n\t/** The client this holds, for anything this package does not wrap. */\n\treadonly client: S3Client;\n\t/** The key this would use, for a caller that needs the string itself. */\n\tkeyFor(params: P): string;\n\t/** Bun's own lazy handle: `.stream()`, `.slice()`, `.writer()` and the rest. */\n\tfile(params: P): S3File;\n\t/** Writes it, once the bucket's content type and size have accepted it. */\n\tput(params: P, body: PutBody, options?: { type?: string }): Promise<void>;\n\t/** The bytes, or `undefined` when there is no such object. */\n\tbytes(params: P): Promise<Uint8Array | undefined>;\n\t/** The body as text, or `undefined` when there is no such object. */\n\ttext(params: P): Promise<string | undefined>;\n\texists(params: P): Promise<boolean>;\n\t/** What the service knows about it, or `undefined` when it is not there. */\n\tstat(params: P): Promise<S3Stats | undefined>;\n\t/** Removes it. S3 does not say whether anything was there, and nor does this. */\n\tdelete(params: P): Promise<void>;\n\t/** One page of the bucket, in this repository's cursor shape. */\n\tlist(options?: {\n\t\tprefix?: string;\n\t\tlimit?: number;\n\t\tcursor?: string | null;\n\t}): Promise<ObjectPage>;\n\t/** A URL that reads this object, signed. */\n\tpresignGet(params: P, options?: PresignOptions): string;\n\t/**\n\t * A URL that writes this object, signed. It constrains the key and the\n\t * deadline, and **nothing else** — not the size, not the content type.\n\t */\n\tpresignPut(params: P, options?: PresignOptions): string;\n}\n\n/**\n * Binds a bucket definition to credentials.\n *\n * ```ts\n * const store = bindBucket(avatars, {\n * \tendpoint: process.env.S3_ENDPOINT,\n * \taccessKeyId: process.env.S3_KEY,\n * \tsecretAccessKey: process.env.S3_SECRET,\n * });\n * await store.put({ userId: 'u1' }, png, { type: 'image/png' });\n * ```\n *\n * Given no options, Bun reads its own `S3_*` / `AWS_*` environment variables.\n *\n * Each bound bucket holds an `S3Client` of its own. S3 is stateless HTTP —\n * there is no connection to share, and nothing to close.\n */\nexport function bindBucket<P>(\n\tdefinition: BucketDefinition<P>,\n\toptions: Omit<S3Options, 'bucket'> = {},\n): BoundBucket<P> {\n\tconst client = new S3Client({ ...options, bucket: definition.bucket });\n\tconst context = bucketContext(client, definition);\n\treturn {\n\t\tclient,\n\t\tkeyFor: (params) => keyOf(context, params),\n\t\tfile: (params) => client.file(keyOf(context, params)),\n\t\tput: (params, body, putOptions) =>\n\t\t\tputObject(context, params, body, putOptions),\n\t\tbytes: (params) => readBytes(context, params),\n\t\ttext: (params) => readText(context, params),\n\t\texists: (params) => objectExists(context, params),\n\t\tstat: (params) => statObject(context, params),\n\t\tdelete: (params) => deleteObject(context, params),\n\t\tlist: (listOptions) => listObjects(context, listOptions),\n\t\tpresignGet: (params, presignOptions) =>\n\t\t\tpresignGetUrl(context, params, presignOptions),\n\t\tpresignPut: (params, presignOptions) =>\n\t\t\tpresignPutUrl(context, params, presignOptions),\n\t};\n}\n",
+    "import { S3Client, type S3File, type S3Options, type S3Stats } from 'bun';\nimport { bucketContext, keyOf } from './context';\nimport { listObjects } from './operations/list';\nimport {\n\ttype PresignOptions,\n\tpresignGetUrl,\n\tpresignPutUrl,\n} from './operations/presign';\nimport {\n\tobjectExists,\n\treadBytes,\n\treadText,\n\tstatObject,\n} from './operations/reads';\nimport { deleteObject, putObject } from './operations/writes';\nimport type {\n\tBucketDefinition,\n\tObjectPage,\n\tPutBody,\n\tPutOptions,\n} from './types';\n\nexport type { PresignOptions };\n\n/** A bucket bound to credentials: the definition, with somewhere to put it. */\nexport interface BoundBucket<P> {\n\t/** The client this holds, for anything this package does not wrap. */\n\treadonly client: S3Client;\n\t/** The key this would use, for a caller that needs the string itself. */\n\tkeyFor(params: P): string;\n\t/** Bun's own lazy handle: `.stream()`, `.slice()`, `.writer()` and the rest. */\n\tfile(params: P): S3File;\n\t/**\n\t * Writes it, once the bucket's content type and size have accepted it.\n\t *\n\t * Beyond `type`, an option here describes **this object** — how it is\n\t * served back (`contentDisposition`, `contentEncoding`), who may read it\n\t * (`acl`), what it costs to keep (`storageClass`) — or how a large body is\n\t * uploaded (`partSize`, `queueSize`, `retry`).\n\t */\n\tput(params: P, body: PutBody, options?: PutOptions): Promise<void>;\n\t/** The bytes, or `undefined` when there is no such object. */\n\tbytes(params: P): Promise<Uint8Array | undefined>;\n\t/** The body as text, or `undefined` when there is no such object. */\n\ttext(params: P): Promise<string | undefined>;\n\texists(params: P): Promise<boolean>;\n\t/** What the service knows about it, or `undefined` when it is not there. */\n\tstat(params: P): Promise<S3Stats | undefined>;\n\t/** Removes it. S3 does not say whether anything was there, and nor does this. */\n\tdelete(params: P): Promise<void>;\n\t/** One page of the bucket, in this repository's cursor shape. */\n\tlist(options?: {\n\t\tprefix?: string;\n\t\tlimit?: number;\n\t\tcursor?: string | null;\n\t}): Promise<ObjectPage>;\n\t/** A URL that reads this object, signed. */\n\tpresignGet(params: P, options?: PresignOptions): string;\n\t/**\n\t * A URL that writes this object, signed. It constrains the key and the\n\t * deadline, and **nothing else** — not the size, not the content type.\n\t */\n\tpresignPut(params: P, options?: PresignOptions): string;\n}\n\n/**\n * Binds a bucket definition to credentials.\n *\n * ```ts\n * const store = bindBucket(avatars, {\n * \tendpoint: process.env.S3_ENDPOINT,\n * \taccessKeyId: process.env.S3_KEY,\n * \tsecretAccessKey: process.env.S3_SECRET,\n * });\n * await store.put({ userId: 'u1' }, png, { type: 'image/png' });\n * ```\n *\n * Given no options, Bun reads its own `S3_*` / `AWS_*` environment variables.\n *\n * Each bound bucket holds an `S3Client` of its own. S3 is stateless HTTP —\n * there is no connection to share, and nothing to close.\n */\nexport function bindBucket<P>(\n\tdefinition: BucketDefinition<P>,\n\toptions: Omit<S3Options, 'bucket'> = {},\n): BoundBucket<P> {\n\tconst client = new S3Client({ ...options, bucket: definition.bucket });\n\tconst context = bucketContext(client, definition);\n\treturn {\n\t\tclient,\n\t\tkeyFor: (params) => keyOf(context, params),\n\t\tfile: (params) => client.file(keyOf(context, params)),\n\t\tput: (params, body, putOptions) =>\n\t\t\tputObject(context, params, body, putOptions),\n\t\tbytes: (params) => readBytes(context, params),\n\t\ttext: (params) => readText(context, params),\n\t\texists: (params) => objectExists(context, params),\n\t\tstat: (params) => statObject(context, params),\n\t\tdelete: (params) => deleteObject(context, params),\n\t\tlist: (listOptions) => listObjects(context, listOptions),\n\t\tpresignGet: (params, presignOptions) =>\n\t\t\tpresignGetUrl(context, params, presignOptions),\n\t\tpresignPut: (params, presignOptions) =>\n\t\t\tpresignPutUrl(context, params, presignOptions),\n\t};\n}\n",
     "import type { S3Client } from 'bun';\nimport type { BucketDefinition } from './types';\n\n/**\n * What every operation of a bound bucket works from, resolved once: the\n * client, the definition, and the accepted content types as a list.\n *\n * It holds **data only**. The operations are plain functions that take it as\n * their first argument, in `guards.ts` and `operations/` — a context of\n * closures would only be the factory this package split up, one size down.\n */\nexport interface BucketContext<P> {\n\treadonly client: S3Client;\n\treadonly definition: BucketDefinition<P>;\n\t/**\n\t * The types the definition accepts, always as a list, **as written** —\n\t * an error message quotes these, and the comparison normalises them.\n\t * `undefined` when the bucket accepts anything.\n\t */\n\treadonly accepted: readonly string[] | undefined;\n}\n\n/** The types a definition accepts, as a list. */\nfunction acceptedTypes(\n\tcontentType: string | readonly string[] | undefined,\n): readonly string[] | undefined {\n\tif (contentType === undefined) return undefined;\n\treturn typeof contentType === 'string' ? [contentType] : contentType;\n}\n\nexport function bucketContext<P>(\n\tclient: S3Client,\n\tdefinition: BucketDefinition<P>,\n): BucketContext<P> {\n\treturn {\n\t\tclient,\n\t\tdefinition,\n\t\taccepted: acceptedTypes(definition.contentType),\n\t};\n}\n\n/** The key this definition builds for these parameters. */\nexport function keyOf<P>(context: BucketContext<P>, params: P): string {\n\treturn context.definition.key(params);\n}\n",
     "import type { S3ListObjectsResponse } from 'bun';\nimport type { BucketContext } from '../context';\nimport type { ObjectPage, StoredObject } from '../types';\n\n/** One page of the bucket, in this repository's cursor shape. */\nexport async function listObjects<P>(\n\tcontext: BucketContext<P>,\n\toptions: { prefix?: string; limit?: number; cursor?: string | null } = {},\n): Promise<ObjectPage> {\n\tconst answer = await context.client.list({\n\t\tprefix: options.prefix,\n\t\tmaxKeys: options.limit,\n\t\tcontinuationToken: options.cursor ?? undefined,\n\t});\n\tconst contents: NonNullable<S3ListObjectsResponse['contents']> =\n\t\tanswer.contents ?? [];\n\tconst items: StoredObject[] = contents.map((found) => ({\n\t\tkey: found.key,\n\t\tsize: found.size,\n\t\tlastModified: found.lastModified ? new Date(found.lastModified) : undefined,\n\t\teTag: found.eTag,\n\t}));\n\t// `isTruncated` is what says there is more, and it is the only thing that\n\t// does: a service that sends a token on the last page anyway would page\n\t// for ever if the token alone decided. `null` is this repository's\n\t// \"no next page\".\n\tconst next = answer.isTruncated\n\t\t? (answer.nextContinuationToken ?? null)\n\t\t: null;\n\treturn { items, nextCursor: next };\n}\n",
-    "import type { S3Options } from 'bun';\nimport { type BucketContext, keyOf } from '../context';\n\n/** How a presigned URL is asked for. `expiresIn` is **seconds**, as S3's is. */\nexport interface PresignOptions {\n\t/** Seconds until it expires. Bun's default is a day; give one. */\n\texpiresIn?: number;\n\t/** `public-read` and the rest, when the service honours it. */\n\tacl?: S3Options['acl'];\n}\n\nexport function presignGetUrl<P>(\n\tcontext: BucketContext<P>,\n\tparams: P,\n\toptions?: PresignOptions,\n): string {\n\treturn context.client.presign(keyOf(context, params), {\n\t\t...options,\n\t\tmethod: 'GET',\n\t});\n}\n\n/**\n * A URL that writes this object, signed.\n *\n * It carries **no content type**, and takes none. Measured on bun 1.4.2:\n * `presign`'s `type` only adds `response-content-type`, S3's override for\n * what a *download* is labelled; `X-Amz-SignedHeaders` stays `host`, so the\n * `Content-Type` the uploader sends is not signed and not constrained. A PUT\n * signed for a `text/csv` bucket stores an `application/zip` body happily —\n * measured against this package's own test service, status 200. Naming a type\n * here would only look like a guarantee.\n */\nexport function presignPutUrl<P>(\n\tcontext: BucketContext<P>,\n\tparams: P,\n\toptions?: PresignOptions,\n): string {\n\treturn context.client.presign(keyOf(context, params), {\n\t\t...options,\n\t\tmethod: 'PUT',\n\t});\n}\n",
+    "import type { S3Options } from 'bun';\nimport { type BucketContext, keyOf } from '../context';\n\n/** How a presigned URL is asked for. `expiresIn` is **seconds**, as S3's is. */\nexport interface PresignOptions {\n\t/** Seconds until it expires. Bun's default is a day; give one. */\n\texpiresIn?: number;\n\t/** `public-read` and the rest, when the service honours it. */\n\tacl?: S3Options['acl'];\n}\n\n/**\n * The options this package signs with, and only those.\n *\n * The same rule as a write's, for the same measured reason: Bun's second\n * parameter extends `S3Options`, so a value carrying extra keys at run time —\n * an options bag off a request body, anything that is not a fresh object\n * literal — **redirects the signed URL**. Measured: a `bucket` key signs a\n * URL for another bucket, and a credential key signs it against another\n * endpoint entirely. The types refuse both; a value that never met the types\n * does not.\n */\nconst SIGNED = ['expiresIn', 'acl'] as const satisfies readonly Signable[];\n\ntype Signable = keyof PresignOptions;\ntype Unsigned = Exclude<Signable, (typeof SIGNED)[number]>;\nconst _nothingForgotten: [Unsigned] extends [never] ? true : Unsigned = true;\nvoid _nothingForgotten;\n\nfunction signed(options: PresignOptions | undefined): PresignOptions {\n\tconst forwarded: Record<string, unknown> = {};\n\tfor (const key of SIGNED) {\n\t\tif (options?.[key] !== undefined) forwarded[key] = options[key];\n\t}\n\treturn forwarded as PresignOptions;\n}\n\nexport function presignGetUrl<P>(\n\tcontext: BucketContext<P>,\n\tparams: P,\n\toptions?: PresignOptions,\n): string {\n\treturn context.client.presign(keyOf(context, params), {\n\t\t...signed(options),\n\t\tmethod: 'GET',\n\t});\n}\n\n/**\n * A URL that writes this object, signed.\n *\n * It carries **no content type**, and takes none. Measured on bun 1.4.2:\n * `presign`'s `type` only adds `response-content-type`, S3's override for\n * what a *download* is labelled; `X-Amz-SignedHeaders` stays `host`, so the\n * `Content-Type` the uploader sends is not signed and not constrained. A PUT\n * signed for a `text/csv` bucket stores an `application/zip` body happily —\n * measured against this package's own test service, status 200. Naming a type\n * here would only look like a guarantee.\n */\nexport function presignPutUrl<P>(\n\tcontext: BucketContext<P>,\n\tparams: P,\n\toptions?: PresignOptions,\n): string {\n\treturn context.client.presign(keyOf(context, params), {\n\t\t...signed(options),\n\t\tmethod: 'PUT',\n\t});\n}\n",
     "import type { S3File, S3Stats } from 'bun';\nimport { type BucketContext, keyOf } from '../context';\n\n/**\n * `undefined` rather than a throw when the object is simply not there.\n *\n * It reads straight away and catches the service's own `NoSuchKey`, rather\n * than asking `exists` first: one round trip instead of two, and no window in\n * which an object deleted between the two turns a promised `undefined` into a\n * throw. `stat` is itself a HEAD, so asking first bought nothing at all.\n */\nasync function whenPresent<P, T>(\n\tcontext: BucketContext<P>,\n\tparams: P,\n\tread: (file: S3File) => Promise<T>,\n): Promise<T | undefined> {\n\ttry {\n\t\treturn await read(context.client.file(keyOf(context, params)));\n\t} catch (reason) {\n\t\t// Bun names its own S3 failures `S3Error` too, and carries S3's code.\n\t\tif ((reason as { code?: unknown }).code === 'NoSuchKey') return undefined;\n\t\tthrow reason;\n\t}\n}\n\nexport function readBytes<P>(\n\tcontext: BucketContext<P>,\n\tparams: P,\n): Promise<Uint8Array | undefined> {\n\treturn whenPresent(context, params, (file) => file.bytes());\n}\n\nexport function readText<P>(\n\tcontext: BucketContext<P>,\n\tparams: P,\n): Promise<string | undefined> {\n\treturn whenPresent(context, params, (file) => file.text());\n}\n\nexport function statObject<P>(\n\tcontext: BucketContext<P>,\n\tparams: P,\n): Promise<S3Stats | undefined> {\n\treturn whenPresent(context, params, (file) => file.stat());\n}\n\nexport function objectExists<P>(\n\tcontext: BucketContext<P>,\n\tparams: P,\n): Promise<boolean> {\n\treturn context.client.exists(keyOf(context, params));\n}\n",
     "/** What went wrong. Each one is documented in the README's Traps. */\nexport type S3ErrorCode =\n\t/** The body's content type is not one this bucket accepts. */\n\t| 'WRONG_TYPE'\n\t/** The body is bigger than this bucket's `maxSize`. */\n\t| 'TOO_LARGE'\n\t/** The body's size cannot be known before sending, and `maxSize` is set. */\n\t| 'UNMEASURABLE';\n\n/**\n * This package's only error, and every one of them is thrown **before**\n * anything is sent. S3's own failures come back as they are, from Bun's\n * client.\n */\nexport class S3Error extends Error {\n\treadonly code: S3ErrorCode;\n\t/** The object key it was about — the bucket and the key, never the body. */\n\treadonly key: string;\n\n\tconstructor(code: S3ErrorCode, key: string, message: string) {\n\t\tsuper(message);\n\t\tthis.name = 'S3Error';\n\t\tthis.code = code;\n\t\tthis.key = key;\n\t}\n}\n",
     "import { S3Error } from '../errors/s3-error';\nimport type { BucketContext } from './context';\nimport type { PutBody } from './types';\n\n/**\n * A content type without its parameters, lower-cased: `text/plain` from\n * `text/plain;charset=utf-8`.\n *\n * Both sides of the comparison go through this, because the type a body\n * carries is rarely the bare one a definition names — `Bun.file('a.json')`\n * reports `application/json;charset=utf-8` (measured on bun 1.4.2), and an\n * explicit `IMAGE/PNG` is the same type as `image/png`.\n */\nexport function essenceOf(type: string): string {\n\treturn (type.split(';')[0] ?? '').trim().toLowerCase();\n}\n\n/**\n * The type a write would carry: the one the caller named, or the one the\n * body knows about itself. One function, so the type `check` approves and\n * the type `put` sends can never be two different answers.\n */\nexport function effectiveType(\n\tbody: PutBody,\n\tnamed: string | undefined,\n): string | undefined {\n\t// A Blob carries its own type; anything else has to be told.\n\treturn named ?? (body instanceof Blob ? body.type || undefined : undefined);\n}\n\n/** The body's size, or `undefined` when it cannot be known before sending. */\nexport function sizeOf(body: PutBody): number | undefined {\n\tif (typeof body === 'string') return Buffer.byteLength(body, 'utf8');\n\t// An `S3File` **is** a `Blob` — measured on bun 1.4.2 — and its `size` is\n\t// `NaN`, because nothing has asked the service yet. Returning that would\n\t// pass the guard silently: `NaN > maxSize` is false, whatever `maxSize` is.\n\tif (body instanceof Blob) {\n\t\treturn Number.isFinite(body.size) ? body.size : undefined;\n\t}\n\tif (body instanceof ArrayBuffer) return body.byteLength;\n\tif (ArrayBuffer.isView(body)) return body.byteLength;\n\t// A stream, a `Response`: nothing says how long it is until it has been\n\t// read, which is what `UNMEASURABLE` is about.\n\treturn undefined;\n}\n\n/** Refuses a type the bucket does not accept. Shared by `put` and `presign`. */\nexport function checkType<P>(\n\tcontext: BucketContext<P>,\n\tkey: string,\n\ttype: string | undefined,\n): void {\n\tconst { accepted } = context;\n\tif (!accepted) return;\n\tconst list = accepted.join(', ');\n\tif (!type) {\n\t\tthrow new S3Error(\n\t\t\t'WRONG_TYPE',\n\t\t\tkey,\n\t\t\t`\"${context.definition.bucket}\" accepts ${list}, and this write ` +\n\t\t\t\t'names no content type. Pass `type`',\n\t\t);\n\t}\n\tif (!accepted.some((one) => essenceOf(one) === essenceOf(type))) {\n\t\tthrow new S3Error(\n\t\t\t'WRONG_TYPE',\n\t\t\tkey,\n\t\t\t`\"${context.definition.bucket}\" accepts ${list}, not ${type}`,\n\t\t);\n\t}\n}\n\n/** Refuses a body the bucket does not accept, before anything is sent. */\nexport function checkSize<P>(\n\tcontext: BucketContext<P>,\n\tkey: string,\n\tbody: PutBody,\n): void {\n\tconst { maxSize, bucket } = context.definition;\n\tif (maxSize === undefined) return;\n\tconst size = sizeOf(body);\n\tif (size === undefined) {\n\t\tthrow new S3Error(\n\t\t\t'UNMEASURABLE',\n\t\t\tkey,\n\t\t\t`\"${bucket}\" has a maxSize, and this body's size cannot be known ` +\n\t\t\t\t'before sending it. Read it into memory first, or drop `maxSize` ' +\n\t\t\t\t'and let the service refuse it',\n\t\t);\n\t}\n\tif (size > maxSize) {\n\t\tthrow new S3Error(\n\t\t\t'TOO_LARGE',\n\t\t\tkey,\n\t\t\t`\"${bucket}\" accepts ${maxSize} bytes at most, and this body is ${size}`,\n\t\t);\n\t}\n}\n",
-    "import { type BucketContext, keyOf } from '../context';\nimport { checkSize, checkType, effectiveType } from '../guards';\nimport type { PutBody } from '../types';\n\n/**\n * Writes it, once the bucket's content type and size have accepted it. Both\n * guards run before `write` is called, so a refused body is never sent.\n */\nexport async function putObject<P>(\n\tcontext: BucketContext<P>,\n\tparams: P,\n\tbody: PutBody,\n\toptions?: { type?: string },\n): Promise<void> {\n\tconst key = keyOf(context, params);\n\tconst type = effectiveType(body, options?.type);\n\tcheckType(context, key, type);\n\tcheckSize(context, key, body);\n\t// The very type `checkType` approved, and nothing else.\n\tawait context.client.write(key, body, type ? { type } : undefined);\n}\n\n/** Removes it. S3 does not say whether anything was there, and nor does this. */\nexport function deleteObject<P>(\n\tcontext: BucketContext<P>,\n\tparams: P,\n): Promise<void> {\n\treturn context.client.delete(keyOf(context, params));\n}\n",
+    "import { type BucketContext, keyOf } from '../context';\nimport { checkSize, checkType, effectiveType } from '../guards';\nimport type { PutBody, PutOptions } from '../types';\n\n/**\n * Writes it, once the bucket's content type and size have accepted it. Both\n * guards run before `write` is called, so a refused body is never sent.\n */\nexport async function putObject<P>(\n\tcontext: BucketContext<P>,\n\tparams: P,\n\tbody: PutBody,\n\toptions: PutOptions = {},\n): Promise<void> {\n\tconst key = keyOf(context, params);\n\tconst type = effectiveType(body, options.type);\n\tcheckType(context, key, type);\n\tcheckSize(context, key, body);\n\t// The very type `checkType` approved, and nothing else: `type` is not one\n\t// of the keys `passed` forwards, so no option can carry a second one in\n\t// beside it.\n\tawait context.client.write(key, body, {\n\t\t...passed(options),\n\t\t...(type ? { type } : {}),\n\t});\n}\n\n/**\n * The options this package forwards, and only those.\n *\n * `PutOptions` refuses the rest at compile time, and that is not enough:\n * measured, spreading the caller's object straight through let a `bucket`\n * key **redirect the write to another bucket** — the object was stored\n * somewhere the definition never described, and the call reported success.\n * Options that arrive from outside a handler are not typed, so the list is\n * applied at run time as well. A key that is not here is dropped, never sent.\n */\ntype Forwardable = Exclude<keyof PutOptions, 'type'>;\n\nconst PASSED = [\n\t'acl',\n\t'storageClass',\n\t'contentDisposition',\n\t'contentEncoding',\n] as const satisfies readonly Forwardable[];\n\n/**\n * `satisfies` proves every key listed is real; it proves nothing about one\n * that is **missing**. Widen `PutOptions` and forget to list the new key\n * here, and the type would advertise an option the run time silently drops —\n * which is the failure this allowlist exists to prevent, in the other\n * direction. This line is what fails the build instead.\n */\ntype Unforwarded = Exclude<Forwardable, (typeof PASSED)[number]>;\nconst _nothingForgotten: [Unforwarded] extends [never] ? true : Unforwarded =\n\ttrue;\nvoid _nothingForgotten;\n\nfunction passed(options: PutOptions): PutOptions {\n\tconst forwarded: Record<string, unknown> = {};\n\tfor (const key of PASSED) {\n\t\tif (options[key] !== undefined) forwarded[key] = options[key];\n\t}\n\treturn forwarded as PutOptions;\n}\n\n/** Removes it. S3 does not say whether anything was there, and nor does this. */\nexport function deleteObject<P>(\n\tcontext: BucketContext<P>,\n\tparams: P,\n): Promise<void> {\n\treturn context.client.delete(keyOf(context, params));\n}\n",
     "import type { BucketDefinition } from './types';\n\n/**\n * Describes a bucket. It talks to nothing: `bindBucket` is what needs\n * credentials.\n *\n * ```ts\n * export const avatars = defineBucket({\n * \tbucket: 'avatars',\n * \tkey: (p: { userId: string }) => `${p.userId}.png`,\n * \tcontentType: ['image/png', 'image/jpeg'],\n * \tmaxSize: 2 * 1024 * 1024,\n * });\n * ```\n */\nexport function defineBucket<P>(\n\tdefinition: BucketDefinition<P>,\n): BucketDefinition<P> {\n\tif (definition.bucket.length === 0) {\n\t\tthrow new TypeError('defineBucket: a bucket definition needs a bucket');\n\t}\n\tif (definition.maxSize !== undefined) {\n\t\tconst { maxSize } = definition;\n\t\tif (!Number.isFinite(maxSize) || maxSize <= 0) {\n\t\t\tthrow new TypeError(\n\t\t\t\t`defineBucket: \"${definition.bucket}\" has a maxSize of ${maxSize}; ` +\n\t\t\t\t\t'it is a number of bytes, and must be above zero',\n\t\t\t);\n\t\t}\n\t}\n\tconst types = definition.contentType;\n\tif (Array.isArray(types) && types.length === 0) {\n\t\tthrow new TypeError(\n\t\t\t`defineBucket: \"${definition.bucket}\" accepts an empty list of ` +\n\t\t\t\t'content types, so nothing could ever be written. Leave ' +\n\t\t\t\t'`contentType` out to accept anything',\n\t\t);\n\t}\n\treturn Object.freeze({ ...definition });\n}\n"
   ],
-  "mappings": "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",
-  "debugId": "4049B661AFFFECB264756E2164756E21",
+  "mappings": "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",
+  "debugId": "F9842873CB32A8B764756E2164756E21",
   "names": []
 }

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.