partial-content 1.0.0

package/dist/object-store.js

@@ -0,0 +1,335 @@
+/**
+ * Storage backend contract for partial-content adapters.
+ *
+ * Implementations adapt a concrete store (S3, R2, Hetzner, GCS, fs) down to
+ * this surface. The kernel and framework adapters depend only on these types,
+ * never on a storage SDK.
+ *
+ * @packageDocumentation
+ */
+import { parseContentRange } from "./kernel.js";
+// ─── Error Types ────────────────────────────────────────────────────────────
+/**
+ * Thrown when an object does not exist in a storage backend.
+ *
+ * All built-in adapters (S3, R2, GCS, Azure, fs) throw this error
+ * for missing objects. Framework adapters (e.g. `partial-content/web`)
+ * use the `status` property to distinguish "object not found" (404)
+ * from a transiently unavailable backend (503, {@link StoreUnavailableError})
+ * and other store failures (502).
+ */
+export class ObjectNotFoundError extends Error {
+    /** HTTP status hint for downstream handlers. */
+    status = 404;
+    /** The storage key that was not found. */
+    key;
+    constructor(key, cause) {
+        super(`Object not found: ${key}`);
+        this.name = "ObjectNotFoundError";
+        this.key = key;
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+/**
+ * Thrown when a pinned read ({@link GetObjectOptions.ifMatch}) finds the
+ * object changed since its validator was captured.
+ *
+ * Adapters map their backend's native rejection to this error (S3 412
+ * PreconditionFailed, R2 `onlyIf` body-less response, Azure 412
+ * ConditionNotMet, GCS etag mismatch). The web adapter treats it as a
+ * signal to re-validate the request against the object's new state.
+ */
+export class ObjectChangedError extends Error {
+    /** HTTP status hint: the pinned read's precondition failed. */
+    status = 412;
+    /** The storage key whose object changed. */
+    key;
+    constructor(key, cause) {
+        super(`Object changed since validation: ${key}`);
+        this.name = "ObjectChangedError";
+        this.key = key;
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+/**
+ * Thrown when a storage backend is transiently unavailable: overloaded,
+ * throttling, or timing out after the adapter's own retries are exhausted.
+ *
+ * A generic store failure (a malformed response, an unparseable
+ * `Content-Range`, an empty body) is reported by the framework adapter as
+ * `502 Bad Gateway` -- "the upstream returned something invalid." This error
+ * is the distinct RETRYABLE case: the upstream is healthy but momentarily
+ * cannot serve. The web adapter maps it to `503 Service Unavailable` and, when
+ * {@link retryAfterSeconds} is set, emits a `Retry-After` header so clients and
+ * shared caches back off instead of hammering an origin that is already shedding
+ * load. Adapters map their backend's throttle signals here (S3/R2/Hetzner
+ * `503 SlowDown`, `429 TooManyRequests`, request timeouts).
+ */
+export class StoreUnavailableError extends Error {
+    /** HTTP status hint: the backend is transiently unavailable. */
+    status = 503;
+    /** The storage key whose read failed. */
+    key;
+    /**
+     * Suggested back-off in whole seconds, echoed as `Retry-After`. Normalized at
+     * construction: a non-negative finite hint is floored to an integer (a
+     * fractional `2.9` -> `2`), and a NaN/negative/infinite/out-of-safe-range hint
+     * (from a hostile backend header or a buggy third-party classifier) is dropped
+     * entirely. So every consumer -- the web adapter AND anyone reading
+     * `.retryAfterSeconds` directly off the frozen contract -- sees a clean
+     * non-negative integer or `undefined`. Absent means the adapter emits `503`
+     * without a `Retry-After` (RFC 9110 Section 15.6.4 permits its absence).
+     */
+    retryAfterSeconds;
+    constructor(key, opts) {
+        super(`Storage backend unavailable: ${key}`);
+        this.name = "StoreUnavailableError";
+        this.key = key;
+        const hint = parseRetryAfterSeconds(opts?.retryAfterSeconds);
+        if (hint !== undefined)
+            this.retryAfterSeconds = hint;
+        if (opts?.cause !== undefined)
+            this.cause = opts.cause;
+    }
+}
+/**
+ * Normalize a `Retry-After` value to whole non-negative seconds, or `undefined`.
+ *
+ * The single sanctioned parser shared by every adapter and the web layer.
+ * Accepts the delay-seconds form (a number, or a numeric string) and -- when
+ * `allowHttpDate` is set -- the HTTP-date form (RFC 9110 Section 10.2.3) as a
+ * non-negative delta from now. Everything else yields `undefined`: NaN,
+ * Infinity, negatives, and any value whose floor exceeds `Number.MAX_SAFE_INTEGER`
+ * (so a huge finite hint can never serialize as `1e+21`, which violates the
+ * `delay-seconds = DIGIT+` grammar), plus non-numeric text. A hostile header or
+ * a buggy third-party classifier therefore can never emit a malformed header.
+ */
+export function parseRetryAfterSeconds(raw, opts) {
+    if (typeof raw === "number") {
+        if (!Number.isFinite(raw) || raw < 0)
+            return undefined;
+        const floored = Math.floor(raw);
+        return Number.isSafeInteger(floored) ? floored : undefined;
+    }
+    if (typeof raw !== "string")
+        return undefined;
+    const trimmed = raw.trim();
+    if (/^\d+$/.test(trimmed)) {
+        const n = Number(trimmed);
+        return Number.isSafeInteger(n) ? n : undefined;
+    }
+    if (opts?.allowHttpDate) {
+        const when = Date.parse(trimmed);
+        if (Number.isNaN(when))
+            return undefined;
+        return Math.max(0, Math.round((when - Date.now()) / 1000));
+    }
+    return undefined;
+}
+/**
+ * Run a backend read and normalize its failures to the contract's error types.
+ *
+ * This is the single ordered classification pipeline every SDK-backed adapter
+ * shares: `notFound` -> `changed` -> `throttled` -> rethrow. Centralizing it
+ * means the "which errors are handled, in what order" contract is structural
+ * rather than copy-pasted into each adapter's head/get catch blocks, so a
+ * classifier can never be present on one path and silently missing on another.
+ * The predicates MUST be mutually exclusive on a given backend (a 404, 412, and
+ * 429/503 are distinct); the order only decides precedence if they are not.
+ *
+ * @example
+ * ```typescript
+ * const meta = await classifyStoreRead(key, () => client.headObject(key), {
+ *   notFound: isNotFound,
+ *   changed: isPreconditionFailed,
+ *   throttled: isThrottled,
+ * });
+ * ```
+ */
+export async function classifyStoreRead(key, op, classifiers) {
+    try {
+        return await op();
+    }
+    catch (err) {
+        if (classifiers.notFound(err))
+            throw new ObjectNotFoundError(key, err);
+        if (classifiers.changed?.(err))
+            throw new ObjectChangedError(key, err);
+        const throttled = classifiers.throttled(err);
+        if (throttled) {
+            throw new StoreUnavailableError(key, {
+                cause: err,
+                // `throttled` may return the backend's advised back-off; a bare `true`
+                // means "throttled, no hint" and emits a 503 without `Retry-After`.
+                retryAfterSeconds: typeof throttled === "object" ? throttled.retryAfterSeconds : undefined,
+            });
+        }
+        throw err;
+    }
+}
+// ─── Node Stream Conversion ─────────────────────────────────────────────────
+/**
+ * Convert a Node.js readable stream (async iterable) to a web ReadableStream
+ * with proper backpressure, Buffer coercion, signal propagation, and cleanup.
+ *
+ * This is the single implementation shared by all Node.js-based adapters
+ * (fs, GCS, Azure, S3 fallback). It handles:
+ *
+ * - **Pull-based backpressure**: the web ReadableStream's `pull()` method
+ *   drives the async iterator, so chunks are only read when the consumer
+ *   is ready.
+ * - **Buffer to Uint8Array coercion**: Node.js streams yield `Buffer`
+ *   instances. We coerce to `Uint8Array` for cross-runtime compatibility
+ *   (Buffer extends Uint8Array in Node, but the `instanceof` check
+ *   ensures correctness in edge cases).
+ * - **AbortSignal propagation**: when the client disconnects (signal aborts),
+ *   the underlying node stream is destroyed immediately to stop I/O.
+ * - **Cancel cleanup**: when the web ReadableStream is cancelled (e.g. by
+ *   `Response.body.cancel()`), the node stream is destroyed.
+ *
+ * @param iterable - The async iterable (Node.js Readable stream). Typed
+ *   `AsyncIterable<Uint8Array>` (Node `Buffer` extends `Uint8Array`, so Buffer
+ *   streams satisfy it) to keep the `Buffer` name -- and its `@types/node`
+ *   coupling -- out of the package's public type surface.
+ * @param opts.destroy - Destroys the underlying stream on cancel/abort. When
+ *   omitted, a `destroy()` method on the iterable is auto-detected and used.
+ * @param opts.signal - Optional AbortSignal for client-disconnect detection
+ * @param opts.expectedBytes - Exact byte count the source promised. When set,
+ *   a graceful end that delivered a different total (a file truncated or grown
+ *   in place mid-read) errors the web stream instead of closing it short, so a
+ *   torn body can never masquerade as a complete response under the committed
+ *   `Content-Length`. A client abort tears down via a thrown iterator error,
+ *   not a graceful end, so it is unaffected by this check.
+ */
+export function nodeStreamToWeb(iterable, opts) {
+    const { signal, expectedBytes } = opts ?? {};
+    let seen = 0;
+    // Auto-detect the Node-stream destroy capability when the caller doesn't
+    // supply one: every adapter was hand-rolling the same
+    // `typeof stream.destroy === "function"` guard.
+    const nativeDestroy = iterable.destroy;
+    const destroy = opts?.destroy ?? (typeof nativeDestroy === "function" ? () => nativeDestroy.call(iterable) : undefined);
+    // Propagate abort signal to the underlying stream. The listener MUST be
+    // removed once the stream settles: a consumer that reuses one long-lived
+    // signal across many getObject calls would otherwise accumulate one
+    // listener (and one retained stream reference) per completed transfer
+    // until the signal is aborted or GC'd.
+    const abortListener = signal && destroy ? destroy : undefined;
+    if (signal && abortListener)
+        signal.addEventListener("abort", abortListener);
+    const detach = () => {
+        if (signal && abortListener)
+            signal.removeEventListener?.("abort", abortListener);
+    };
+    const iterator = iterable[Symbol.asyncIterator]();
+    return new ReadableStream({
+        async pull(controller) {
+            let result;
+            try {
+                result = await iterator.next();
+            }
+            catch (err) {
+                // Stop backend I/O when iteration fails, then error the web stream.
+                // Without this, a mid-transfer backend failure leaks the socket.
+                detach();
+                destroy?.();
+                throw err;
+            }
+            if (result.done) {
+                detach();
+                // A graceful end that under- or over-ran the promised length means the
+                // source changed under an already-committed Content-Length: fail the
+                // body loudly (a reset the client sees as a failed transfer) rather
+                // than deliver a truncated stream that looks complete.
+                if (expectedBytes !== undefined && seen !== expectedBytes) {
+                    destroy?.();
+                    controller.error(new Error(`stream delivered ${seen} bytes, expected ${expectedBytes} (source changed mid-read)`));
+                    return;
+                }
+                controller.close();
+            }
+            else {
+                // Node.js streams yield Buffer; ensure Uint8Array for cross-runtime compat.
+                // Node Buffers and adapter chunks are ArrayBuffer-backed, so the narrow
+                // is runtime-safe and lets the web stream advertise a BodyInit-assignable
+                // Uint8Array<ArrayBuffer> (see F5 rationale in guardStreamLength).
+                const raw = result.value instanceof Uint8Array ? result.value : Buffer.from(result.value);
+                const chunk = raw;
+                seen += chunk.byteLength;
+                controller.enqueue(chunk);
+            }
+        },
+        async cancel(reason) {
+            detach();
+            try {
+                await iterator.return?.(reason);
+            }
+            catch {
+                // Iterator cleanup failed; socket will be GC'd
+            }
+            destroy?.();
+        },
+    });
+}
+/**
+ * Wrap a web `ReadableStream` so a graceful end that delivered a byte count
+ * other than `expectedBytes` errors the stream instead of closing it short.
+ *
+ * The Node-stream path gets this guard inside {@link nodeStreamToWeb}. This is
+ * the equivalent for adapters whose SDK hands back a web `ReadableStream`
+ * directly (S3 in Bun/Deno or via `transformToWebStream`, R2's native binding,
+ * a browser `Blob` stream) rather than a Node `Readable`. Without it, an
+ * S3-compatible backend that ends a body cleanly but short of the committed
+ * `Content-Length` (some do in-flight body retries) would under-run the
+ * response undetected -- the exact truncation `expectedBytes` exists to catch.
+ * Passing `undefined` disables the check and returns the stream unwrapped.
+ */
+export function guardStreamLength(stream, expectedBytes) {
+    // Return position narrows to <ArrayBuffer> (backend byte chunks are always
+    // ArrayBuffer-backed) so the guarded body stays `new Response(...)`-assignable
+    // under DOM lib; the input stays wide for callers.
+    if (expectedBytes === undefined)
+        return stream;
+    let seen = 0;
+    return stream.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            seen += chunk.byteLength;
+            controller.enqueue(chunk);
+        },
+        flush(controller) {
+            // A short (or long) graceful end means the source diverged from the
+            // committed length: fail the body loudly rather than deliver a
+            // truncated stream that looks complete. Mirrors nodeStreamToWeb.
+            if (seen !== expectedBytes) {
+                controller.error(new Error(`stream delivered ${seen} bytes, expected ${expectedBytes} (source changed mid-read)`));
+            }
+        },
+    }));
+}
+/**
+ * Parse a backend `Content-Range` response header into served bounds plus an
+ * honest total, applying the parser's `-1` unknown-total sentinel -> `undefined`
+ * mapping that every SDK adapter needs identically. Returns `null` ONLY when the
+ * header is present but unparseable -- the exact "byte accounting is
+ * untrustworthy, tear down and fail loudly" signal, which each adapter pairs
+ * with its own live-body cleanup (S3 `stream.cancel()`, Azure
+ * `destroyAzureDownload`, http `drain`) before throwing.
+ *
+ * Adapters that treat an ABSENT header as a full 200 (S3, Azure) check for the
+ * header before calling; callers that already know the response is partial
+ * (http's 206 branch) treat both an absent header and a `null` here as the same
+ * malformed-206 failure. Adapters that know their bounds natively (fs, memory,
+ * GCS, R2) construct {@link ServedRange} directly and never call this.
+ */
+export function resolveServedRange(contentRange) {
+    const parsed = parseContentRange(contentRange);
+    if (!parsed)
+        return null;
+    return {
+        served: { start: parsed.start, end: parsed.end },
+        totalSize: parsed.totalSize < 0 ? undefined : parsed.totalSize,
+    };
+}
+//# sourceMappingURL=object-store.js.map

package/dist/object-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-store.js","sourceRoot":"","sources":["../src/object-store.ts"],"names":[],"mappings":"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"}

package/dist/r2.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Cloudflare R2 native ObjectStore adapter for partial-content.
+ *
+ * Uses Cloudflare's native R2 bindings (`R2Bucket`) directly, without the
+ * AWS SDK. This eliminates the ~50-package `@aws-sdk/client-s3` dependency
+ * and its cold-start overhead in Workers.
+ *
+ * For S3-compatible access to R2 (e.g. from Node.js outside Workers),
+ * use `partial-content/s3` instead.
+ *
+ * @example
+ * ```typescript
+ * import { r2Store } from "partial-content/r2";
+ * import { serveObject } from "partial-content/hono";
+ *
+ * // In a Cloudflare Worker with R2 binding:
+ * app.get("/files/:key", serveObject(
+ *   r2Store({ bucket: env.MY_BUCKET }),
+ *   { key: (c) => c.req.param("key") },
+ * ));
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { ObjectNotFoundError, ObjectChangedError, type ObjectStore } from "./index.js";
+export { ObjectNotFoundError, ObjectChangedError };
+/**
+ * Minimal R2Bucket interface from Cloudflare Workers types.
+ *
+ * Declared locally to avoid a dependency on `@cloudflare/workers-types`.
+ * The shapes match the runtime behavior; type-checking is the caller's
+ * responsibility (their Worker project imports the full types).
+ */
+interface R2Bucket {
+    head(key: string): Promise<R2Object | null>;
+    /**
+     * With `onlyIf`, a failed precondition resolves to a body-less `R2Object`
+     * (not null, not an error) -- callers must check for `body`.
+     */
+    get(key: string, options?: R2GetOptions): Promise<R2Object | R2ObjectBody | null>;
+}
+interface R2Object {
+    key: string;
+    size: number;
+    etag: string;
+    uploaded: Date;
+    checksums: R2Checksums;
+    httpMetadata?: R2HttpMetadata;
+}
+interface R2ObjectBody extends R2Object {
+    body: ReadableStream<Uint8Array>;
+    range: R2Range;
+}
+interface R2Range {
+    offset: number;
+    length: number;
+}
+interface R2GetOptions {
+    range?: {
+        offset: number;
+        length?: number;
+    };
+    onlyIf?: {
+        etagMatches?: string;
+    };
+}
+interface R2Checksums {
+    sha256?: ArrayBuffer;
+}
+interface R2HttpMetadata {
+    contentType?: string;
+}
+export interface R2StoreOptions {
+    /** The R2 bucket binding from the Worker environment. */
+    bucket: R2Bucket;
+}
+/**
+ * Create an {@link ObjectStore} backed by a Cloudflare R2 bucket.
+ *
+ * @example
+ * ```typescript
+ * import { r2Store } from "partial-content/r2";
+ *
+ * export default {
+ *   async fetch(request, env) {
+ *     const store = r2Store({ bucket: env.MY_BUCKET });
+ *     const meta = await store.headObject("reports/q4.pdf");
+ *     // ...
+ *   },
+ * };
+ * ```
+ */
+export declare function r2Store(opts: R2StoreOptions): ObjectStore;
+//# sourceMappingURL=r2.d.ts.map

package/dist/r2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../src/r2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAGL,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,WAAW,EAIjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,CAAC;AAInD;;;;;;GAMG;AACH,UAAU,QAAQ;IAChB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC5C;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,GAAG,YAAY,GAAG,IAAI,CAAC,CAAC;CACnF;AAED,UAAU,QAAQ;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,IAAI,CAAC;IACf,SAAS,EAAE,WAAW,CAAC;IACvB,YAAY,CAAC,EAAE,cAAc,CAAC;CAC/B;AAED,UAAU,YAAa,SAAQ,QAAQ;IACrC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACjC,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,UAAU,OAAO;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,YAAY;IAGpB,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,MAAM,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACnC;AAED,UAAU,WAAW;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,UAAU,cAAc;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,MAAM,EAAE,QAAQ,CAAC;CAClB;AAwBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,WAAW,CA+FzD"}

package/dist/r2.js

@@ -0,0 +1,150 @@
+/**
+ * Cloudflare R2 native ObjectStore adapter for partial-content.
+ *
+ * Uses Cloudflare's native R2 bindings (`R2Bucket`) directly, without the
+ * AWS SDK. This eliminates the ~50-package `@aws-sdk/client-s3` dependency
+ * and its cold-start overhead in Workers.
+ *
+ * For S3-compatible access to R2 (e.g. from Node.js outside Workers),
+ * use `partial-content/s3` instead.
+ *
+ * @example
+ * ```typescript
+ * import { r2Store } from "partial-content/r2";
+ * import { serveObject } from "partial-content/hono";
+ *
+ * // In a Cloudflare Worker with R2 binding:
+ * app.get("/files/:key", serveObject(
+ *   r2Store({ bucket: env.MY_BUCKET }),
+ *   { key: (c) => c.req.param("key") },
+ * ));
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { isOpenEndedRange, guardStreamLength, ObjectNotFoundError, ObjectChangedError, } from "./index.js";
+// Re-export for convenience
+export { ObjectNotFoundError, ObjectChangedError };
+// ─── Helpers ────────────────────────────────────────────────────────────────
+/**
+ * Convert an ArrayBuffer SHA-256 checksum to base64 for RFC 9530 Repr-Digest.
+ *
+ * `checksums.sha256` is R2's whole-object SHA-256 as raw bytes, so unlike the
+ * S3 adapter there is no `<base64>-<partCount>` composite string form to
+ * reject: a 32-byte buffer always describes the full representation. If R2
+ * ever exposes a per-part checksum in this field, this digest would need the
+ * same whole-object guard S3 applies.
+ */
+function arrayBufferToBase64(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+// ─── Factory ────────────────────────────────────────────────────────────────
+/**
+ * Create an {@link ObjectStore} backed by a Cloudflare R2 bucket.
+ *
+ * @example
+ * ```typescript
+ * import { r2Store } from "partial-content/r2";
+ *
+ * export default {
+ *   async fetch(request, env) {
+ *     const store = r2Store({ bucket: env.MY_BUCKET });
+ *     const meta = await store.headObject("reports/q4.pdf");
+ *     // ...
+ *   },
+ * };
+ * ```
+ */
+export function r2Store(opts) {
+    const { bucket } = opts;
+    // No `classifyStoreRead` here (unlike s3/gcs/azure): the R2 Workers binding
+    // signals its recoverable outcomes structurally, not as classifiable errors.
+    // Not-found is a `null` return, a failed `onlyIf` pin is a body-less object,
+    // and both are handled inline below. R2 exposes NO documented throttle/503
+    // error shape on the native binding (rate limiting surfaces at the Workers
+    // platform layer, before the handler runs), so there is nothing to map to
+    // `StoreUnavailableError`. Inventing a classifier for an undocumented error
+    // shape would be guessing; the README correctly omits R2 from the throttle-
+    // classification list. Use `partial-content/s3` (R2's S3 endpoint) if you
+    // need SlowDown/429 -> 503 mapping.
+    return {
+        supportsRange: true,
+        // 206 bounds/total come from the R2ObjectBody's actual size/offset: the
+        // orchestrator may skip the validating HEAD for plain range requests.
+        authoritativeRange: true,
+        async headObject(key, opts) {
+            opts?.signal?.throwIfAborted();
+            const obj = await bucket.head(key);
+            if (!obj)
+                throw new ObjectNotFoundError(key);
+            return {
+                contentLength: obj.size,
+                etag: obj.etag,
+                lastModified: obj.uploaded.toUTCString(),
+                digest: obj.checksums.sha256
+                    ? arrayBufferToBase64(obj.checksums.sha256)
+                    : undefined,
+            };
+        },
+        async getObject(key, opts) {
+            const { range, ifMatch } = opts ?? {};
+            opts?.signal?.throwIfAborted();
+            // An open-ended fast-path range (OPEN_ENDED sentinel end) reads to the
+            // end of the object: pass offset alone so R2 streams the tail rather
+            // than requesting a ~9e15 length.
+            const r2Range = range
+                ? (isOpenEndedRange(range)
+                    ? { offset: range.start }
+                    : { offset: range.start, length: range.end - range.start + 1 })
+                : undefined;
+            const getOptions = r2Range || ifMatch
+                ? {
+                    ...(r2Range ? { range: r2Range } : {}),
+                    // Pin the read to the validated representation. On mismatch R2
+                    // returns the object WITHOUT a body (checked below).
+                    ...(ifMatch ? { onlyIf: { etagMatches: ifMatch } } : {}),
+                }
+                : undefined;
+            const obj = await bucket.get(key, getOptions);
+            if (!obj)
+                throw new ObjectNotFoundError(key);
+            // onlyIf precondition failed: R2 resolves with metadata but no body.
+            if (!("body" in obj) || !obj.body) {
+                throw new ObjectChangedError(key);
+            }
+            const body = obj;
+            const totalSize = obj.size;
+            // Content-Range must reflect what R2 ACTUALLY returned, not what was
+            // requested. `body.range` is R2's authoritative offset/length for this
+            // response; if R2 clamped the range (object changed between HEAD and
+            // GET), fabricating from the request would corrupt the client's bytes.
+            const returned = range ? body.range : undefined;
+            const start = returned?.offset ?? range?.start;
+            const length = returned?.length
+                ?? (range
+                    ? (isOpenEndedRange(range) ? totalSize - range.start : range.end - range.start + 1)
+                    : undefined);
+            const isRanged = start !== undefined && length !== undefined;
+            const contentLength = isRanged ? length : totalSize;
+            return {
+                // Guard the committed length: if R2 ever ends the body short of the
+                // computed contentLength, error the stream rather than under-run it.
+                body: guardStreamLength(body.body, contentLength),
+                contentLength,
+                totalSize,
+                range: isRanged ? { start, end: start + length - 1 } : undefined,
+                etag: obj.etag,
+                lastModified: obj.uploaded.toUTCString(),
+                digest: obj.checksums.sha256
+                    ? arrayBufferToBase64(obj.checksums.sha256)
+                    : undefined,
+            };
+        },
+    };
+}
+//# sourceMappingURL=r2.js.map

package/dist/r2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.js","sourceRoot":"","sources":["../src/r2.ts"],"names":[],"mappings":"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"}

package/dist/s3.d.ts

@@ -0,0 +1,49 @@
+/**
+ * S3-compatible ObjectStore adapter for partial-content.
+ *
+ * Implements the read-only {@link ObjectStore} interface from the kernel,
+ * wrapping `@aws-sdk/client-s3` HeadObject/GetObject commands. Covers:
+ *   - AWS S3
+ *   - Cloudflare R2 (S3-compatible mode)
+ *   - Hetzner Object Storage
+ *   - MinIO / Backblaze B2 / Wasabi
+ *
+ * For native R2 bindings (without the AWS SDK), use `partial-content/r2`.
+ *
+ * @example
+ * ```typescript
+ * import { S3Client } from "@aws-sdk/client-s3";
+ * import { s3Store } from "partial-content/s3";
+ *
+ * const client = new S3Client({ region: "eu-central-1" });
+ * const store = s3Store({ client, bucket: "documents" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { S3Client } from "@aws-sdk/client-s3";
+import { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError, type ObjectStore } from "./index.js";
+export { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError };
+export interface S3StoreOptions {
+    /** Pre-configured S3Client instance (BYOC, no config coupling). */
+    client: S3Client;
+    /** The S3 bucket name. */
+    bucket: string;
+}
+/**
+ * Create an {@link ObjectStore} backed by an S3-compatible bucket.
+ *
+ * @example
+ * ```typescript
+ * import { S3Client } from "@aws-sdk/client-s3";
+ * import { s3Store } from "partial-content/s3";
+ *
+ * const client = new S3Client({ region: "eu-central-1" });
+ * const store = s3Store({ client, bucket: "documents" });
+ *
+ * // Use with partial-content's evaluateConditionalRequest:
+ * const meta = await store.headObject("reports/q4.pdf");
+ * ```
+ */
+export declare function s3Store(opts: S3StoreOptions): ObjectStore;
+//# sourceMappingURL=s3.d.ts.map

package/dist/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../src/s3.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,QAAQ,EAKT,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EAOrB,KAAK,WAAW,EAKjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,CAAC;AAiC1E,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,MAAM,EAAE,QAAQ,CAAC;IACjB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,WAAW,CA0IzD"}