partial-content 1.0.0

package/dist/s3.js

@@ -0,0 +1,263 @@
+/**
+ * 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, GetObjectCommand, HeadObjectCommand, NoSuchKey, NotFound, } from "@aws-sdk/client-s3";
+import { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError, classifyStoreRead, nodeStreamToWeb, guardStreamLength, resolveServedRange, buildContentDisposition, isOpenEndedRange, } from "./index.js";
+// Re-export for convenience
+export { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError };
+// ─── S3 Body -> Web ReadableStream ──────────────────────────────────────────
+/**
+ * Convert an S3 SDK response Body to a web ReadableStream.
+ *
+ * The SDK Body is a web ReadableStream in Bun/Deno, a Node Readable in
+ * Node.js, and may expose `transformToWebStream()` as a convenience.
+ * We try each path in order of preference.
+ */
+function toWebStream(body, signal, expectedBytes) {
+    // Every branch enforces the committed length: an S3-compatible backend that
+    // ends a body cleanly but short of ContentLength (some do in-flight body
+    // retries) must error the stream, not silently under-run the response. The
+    // web-stream branches are the ones Node aws-sdk v3 and Bun/Deno actually take,
+    // so guarding only the Node-Readable fallback would leave the guard dead.
+    if (body instanceof ReadableStream) {
+        return guardStreamLength(body, expectedBytes);
+    }
+    if (typeof body.transformToWebStream === "function") {
+        return guardStreamLength(body.transformToWebStream(), expectedBytes);
+    }
+    // Node Readable fallback: the shared utility auto-detects destroy() and
+    // applies the same length guard internally.
+    return nodeStreamToWeb(body, { signal, expectedBytes });
+}
+// ─── Factory ────────────────────────────────────────────────────────────────
+/**
+ * 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 function s3Store(opts) {
+    const { client, bucket } = opts;
+    return {
+        supportsRange: true,
+        // 206 bounds/total are parsed from S3's actual Content-Range: the
+        // orchestrator may skip the validating HEAD for plain range requests.
+        authoritativeRange: true,
+        async headObject(key, opts) {
+            const response = await classifyStoreRead(key, () => client.send(
+            // ChecksumMode is required for S3 to return ChecksumSHA256 at all;
+            // without it the digest would silently never be emitted.
+            new HeadObjectCommand({ Bucket: bucket, Key: key, ChecksumMode: "ENABLED" }), { abortSignal: opts?.signal }), s3Classifiers);
+            if (response.ContentLength == null) {
+                throw new Error(`HeadObject returned no ContentLength for ${key}`);
+            }
+            return {
+                contentLength: response.ContentLength,
+                etag: response.ETag,
+                lastModified: response.LastModified?.toUTCString(),
+                digest: toReprDigest(response.ChecksumSHA256),
+            };
+        },
+        async getObject(key, opts) {
+            const { range, signal, ifMatch } = opts ?? {};
+            // Open-ended fast-path ranges (`bytes=a-`) carry the OPEN_ENDED
+            // sentinel end; emit the bare open form so no 16-digit last-byte-pos
+            // reaches the wire (S3 clamps it, but strict proxies may reject it).
+            const rangeHeader = range
+                ? (isOpenEndedRange(range) ? `bytes=${range.start}-` : `bytes=${range.start}-${range.end}`)
+                : undefined;
+            const response = await classifyStoreRead(key, () => client.send(new GetObjectCommand({
+                Bucket: bucket,
+                Key: key,
+                ChecksumMode: "ENABLED",
+                // Pin the read to the validated representation: S3 rejects with
+                // 412 PreconditionFailed if the object changed since HEAD.
+                ...(ifMatch ? { IfMatch: ifMatch } : {}),
+                ...(rangeHeader ? { Range: rangeHeader } : {}),
+            }), { abortSignal: signal }), s3Classifiers);
+            if (!response.Body) {
+                throw new Error(`S3 GetObject returned empty body for ${key}`);
+            }
+            const stream = toWebStream(response.Body, signal, response.ContentLength);
+            // A null ContentLength on a GET with a live body is a degenerate response:
+            // fabricating `0` would commit `Content-Length: 0` over real bytes (a wire
+            // framing error) and silently disable the short-read guard. headObject
+            // already fails loudly on this; mirror it -- cancel the body and throw.
+            if (response.ContentLength == null) {
+                stream.cancel().catch(() => { });
+                throw new Error(`S3 GetObject returned no ContentLength for ${key}`);
+            }
+            const contentLength = response.ContentLength;
+            // Extract served bounds + total size from Content-Range
+            // (e.g. "bytes 0-999/5000") via the shared resolver, or fall back to
+            // ContentLength for full responses. A Content-Range S3 emits but the
+            // resolver cannot parse means the byte accounting is untrustworthy:
+            // cancel the live body and fail loudly rather than guess.
+            let totalSize;
+            let served;
+            if (response.ContentRange) {
+                const resolved = resolveServedRange(response.ContentRange);
+                if (!resolved) {
+                    stream.cancel().catch(() => { });
+                    throw new Error(`S3 returned unparseable Content-Range for ${key}: ${response.ContentRange}`);
+                }
+                served = resolved.served;
+                totalSize = resolved.totalSize;
+            }
+            else {
+                totalSize = contentLength;
+            }
+            return {
+                body: stream,
+                contentLength,
+                totalSize,
+                range: served,
+                etag: response.ETag,
+                lastModified: response.LastModified?.toUTCString(),
+                // Repr-Digest MUST hash the full representation. AWS omits the checksum
+                // on ranged GETs, but a non-conforming S3-compatible backend could
+                // return a range-scoped one; never advertise it as a whole-object
+                // digest. HEAD (always whole-object) and full 200s still carry it.
+                digest: served ? undefined : toReprDigest(response.ChecksumSHA256),
+            };
+        },
+        async createSignedUrl(key, signOpts) {
+            try {
+                // A signed URL is a 302 redirect target: the client fetches bytes
+                // DIRECTLY from S3, bypassing the serve route's security headers
+                // (nosniff, CSP, CORP). Force a download disposition AND an inert
+                // content type so a stored SVG/HTML polyglot cannot render inline off
+                // the header-less origin response. Both are S3 query-parameter
+                // overrides honored on the presigned GET; the stored object is
+                // untouched. `downloadFilename` only customizes the name.
+                const command = new GetObjectCommand({
+                    Bucket: bucket,
+                    Key: key,
+                    ResponseContentType: "application/octet-stream",
+                    ResponseContentDisposition: buildContentDisposition(signOpts.downloadFilename ?? "download", { type: "attachment" }),
+                });
+                // Lazy import: the presigner is an optional peer needed ONLY for
+                // signed URLs. A static import would crash `partial-content/s3` at
+                // module load for every consumer who installed just
+                // @aws-sdk/client-s3 (the documented baseline) and never presigns.
+                const { getSignedUrl } = await import("@aws-sdk/s3-request-presigner");
+                const url = await getSignedUrl(client, command, {
+                    expiresIn: signOpts.expiresInSeconds,
+                });
+                return { ok: true, url };
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    error: err instanceof Error ? err.message : String(err),
+                };
+            }
+        },
+    };
+}
+// ─── Internal Helpers ───────────────────────────────────────────────────────
+/** A raw base64-encoded SHA-256 hash: exactly 43 base64 chars plus padding. */
+const SHA256_BASE64_RE = /^[A-Za-z0-9+/]{43}=$/;
+/**
+ * Validate an S3 checksum for use as an RFC 9530 representation digest.
+ *
+ * Multipart uploads produce composite checksums ("checksum-of-checksums")
+ * in the form `<base64>-<partCount>`, which do NOT hash the object bytes
+ * and are invalid inside `Repr-Digest: sha-256=:...:`. Only a plain
+ * base64 SHA-256 of the full object passes through.
+ */
+function toReprDigest(checksum) {
+    return checksum && SHA256_BASE64_RE.test(checksum) ? checksum : undefined;
+}
+/**
+ * Check if an S3 error indicates the object does not exist.
+ *
+ * Covers:
+ *   - AWS SDK v3 `NoSuchKey` and `NotFound` error classes
+ *   - Generic S3-compatible providers that set `$metadata.httpStatusCode: 404`
+ *   - Providers that set `name: "NotFound"` without using the SDK error classes
+ */
+function isNotFoundError(err) {
+    if (err instanceof NoSuchKey || err instanceof NotFound)
+        return true;
+    if (err instanceof Error && err.name === "NotFound")
+        return true;
+    const meta = err.$metadata;
+    if (meta?.httpStatusCode === 404)
+        return true;
+    return false;
+}
+/**
+ * Check if an S3 error is a failed IfMatch precondition (object changed).
+ * The SDK surfaces this as name "PreconditionFailed" with HTTP 412.
+ */
+function isPreconditionFailedError(err) {
+    if (err instanceof Error && err.name === "PreconditionFailed")
+        return true;
+    const meta = err.$metadata;
+    return meta?.httpStatusCode === 412;
+}
+/**
+ * Check if an S3 error is a transient throttle/overload the client should
+ * retry (mapped to a 503, not a 502). The AWS SDK exhausts its own adaptive
+ * retries first, so reaching here means sustained pressure.
+ *
+ * Covers:
+ *   - `$retryable.throttling` (the SDK's own throttle classification)
+ *   - HTTP 503 (`SlowDown`) and 429 (`TooManyRequests`) on `$metadata`
+ *   - the named throttle errors S3-compatible backends raise without setting
+ *     an HTTP status code
+ */
+function isThrottledError(err) {
+    if (err.$retryable?.throttling === true)
+        return true;
+    const meta = err.$metadata;
+    if (meta?.httpStatusCode === 503 || meta?.httpStatusCode === 429)
+        return true;
+    if (err instanceof Error) {
+        const name = err.name;
+        return (name === "SlowDown" ||
+            name === "ThrottlingException" ||
+            name === "TooManyRequestsException" ||
+            name === "RequestThrottled" ||
+            name === "RequestThrottledException" ||
+            name === "ProvisionedThroughputExceededException");
+    }
+    return false;
+}
+/** The ordered error-classification set shared by headObject and getObject. */
+const s3Classifiers = {
+    notFound: isNotFoundError,
+    changed: isPreconditionFailedError,
+    throttled: isThrottledError,
+};
+//# sourceMappingURL=s3.js.map

package/dist/s3.js.map

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

package/dist/web.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Web / Fetch API adapter for partial-content.
+ *
+ * Composes a partial-content {@link ObjectStore} with the kernel's conditional
+ * request evaluation to produce a standards-compliant file-serving handler.
+ *
+ * Framework-agnostic: works with Next.js App Router, Hono, SvelteKit, Remix,
+ * Cloudflare Workers, Bun.serve, Deno.serve, or any runtime that uses the
+ * standard Request/Response API.
+ *
+ * Handles: 200 (full), 206 (partial), 304 (not modified), 412 (precondition
+ * failed), 416 (range not satisfiable), and HEAD (headers only).
+ *
+ * @example
+ * ```typescript
+ * import { serveObject } from "partial-content/web";
+ * import { s3Store } from "partial-content/s3";
+ *
+ * const store = s3Store({ client, bucket: "documents" });
+ *
+ * export const GET = serveObject(store, {
+ *   key: (req) => req.url.split("/").pop()!,
+ *   disposition: "inline",
+ * });
+ * export const HEAD = GET;
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { type ObjectStore } from "./index.js";
+export type { CancelSignal, ObjectStore, ObjectMetadata, ObjectStream, ParsedRange, ETagSource, } from "./index.js";
+/**
+ * The request surface the orchestrator actually consumes. A standard fetch
+ * `Request` satisfies it structurally; server adapters may pass a
+ * lightweight view instead, avoiding per-request construction of fetch
+ * primitives (an undici `Request` + `Headers` pair costs a measurable
+ * fraction of a small-file serve).
+ */
+export interface ServableRequest {
+    /** HTTP method. GET and HEAD are served; anything else gets a 405. */
+    method: string;
+    /** Case-insensitive header lookup: a `Headers` object or any equivalent view. */
+    headers: {
+        get(name: string): string | null;
+    };
+    /** Client-disconnect signal, forwarded to the storage backend. */
+    signal?: AbortSignal;
+}
+/** Metadata resolved by the consumer before the handler runs. */
+export interface ServeContext {
+    /** Storage key (path within the bucket). */
+    key: string;
+    /** Override MIME type. When omitted, defaults to "application/octet-stream". */
+    mime?: string;
+    /** Filename for Content-Disposition. When omitted, no disposition header is set. */
+    filename?: string;
+    /**
+     * Per-request Cache-Control, overriding {@link ServeObjectOptions.cacheControl}.
+     * Lets one handler serve mixed cacheability (immutable content-addressed
+     * blobs next to private user uploads) without instantiating N handlers.
+     * Used verbatim: the `immutable` option is NOT appended to it.
+     */
+    cacheControl?: string;
+}
+export interface ServeObjectOptions {
+    /**
+     * Content-Disposition strategy.
+     * - `"inline"` -- render in the browser (PDF, images, video)
+     * - `"attachment"` -- force download
+     * - A function mapping MIME to disposition type (for per-type policy)
+     *
+     * @default "attachment"
+     */
+    disposition?: "inline" | "attachment" | ((mime: string) => "inline" | "attachment");
+    /**
+     * Cache-Control value for 200/206 responses.
+     * @default "private, no-cache"
+     */
+    cacheControl?: string;
+    /**
+     * When true, appends `immutable` to the Cache-Control directive.
+     * Use for content-addressed storage where the key contains a hash
+     * (e.g. `<sha256>.pdf`) and the resource will never change.
+     *
+     * @default false
+     */
+    immutable?: boolean;
+    /**
+     * Security headers applied to every response that carries a body (200, 206).
+     * Receives the MIME type so the policy can vary per format (e.g. relaxed
+     * CSP for PDF.js, strict sandbox for images).
+     *
+     * @default No extra security headers.
+     */
+    securityHeaders?: (mime: string) => Record<string, string>;
+    /**
+     * Cross-Origin-Resource-Policy value for success responses.
+     *
+     * Controls which origins can embed this resource:
+     * - `"same-origin"` -- only your origin (most secure)
+     * - `"same-site"` -- same registrable domain
+     * - `"cross-origin"` -- any origin (for public CDN assets)
+     *
+     * Required for pages with `Cross-Origin-Embedder-Policy: require-corp`.
+     * When omitted, no CORP header is set (caller decides).
+     */
+    crossOriginResourcePolicy?: "same-origin" | "same-site" | "cross-origin";
+    /**
+     * Timing-Allow-Origin value for success responses.
+     *
+     * Allows cross-origin pages to read Server-Timing and Resource Timing data
+     * via the PerformanceObserver API. Without this, browser security policy
+     * zeros out timing metrics for cross-origin resources.
+     *
+     * Set to `"*"` for public assets, or a specific origin for private APIs.
+     */
+    timingAllowOrigin?: string;
+    /**
+     * When true, emits a `Server-Timing` header with storage and evaluation
+     * latency metrics. Also calls `onTiming` if provided.
+     *
+     * Caution: timing data may leak internal architecture details.
+     * Enable only when you control the deployment environment.
+     *
+     * @default false
+     */
+    timing?: boolean;
+    /**
+     * Timing callback for observability.
+     *
+     * Called with structured timing data for every request. Use to ship
+     * metrics to your RUM/APM backend.
+     */
+    onTiming?: (metrics: {
+        storeMs: number;
+        evaluateMs: number;
+        totalMs: number;
+    }) => void;
+    /**
+     * Fallback filename used by buildContentDisposition when no filename is
+     * provided and the disposition needs an ASCII fallback.
+     *
+     * @default "download"
+     */
+    fallbackFilename?: string;
+    /**
+     * Error callback for observability.
+     *
+     * Called when the storage backend throws during HEAD or GET operations.
+     * Use this to log errors with request IDs, correlation tokens, and
+     * structured metadata for production monitoring.
+     *
+     * The error is NOT exposed to the client (the response body is generic).
+     *
+     * @param error - The original error from the storage backend
+     * @param context - Additional context about the failed operation
+     * (`audit` = the consumer's own onServe hook threw; the response was
+     * still served, the hook failure is surfaced here instead of crashing).
+     */
+    onError?: (error: unknown, context: {
+        key: string;
+        operation: "head" | "get" | "audit";
+    }) => void;
+    /**
+     * Audit callback for compliance logging (SOC 2 CC7.2, ISO 27001 A.8.15).
+     *
+     * Called on every response that grants access (200, 206, 304, and 302
+     * signed-URL redirects) with structured metadata suitable for audit trail
+     * ingestion. Not called on errors (use `onError` for those).
+     *
+     * @example
+     * ```ts
+     * onServe: (event) => logger.info({ ...event }, "file.served")
+     * ```
+     */
+    onServe?: (event: ServeAuditEvent) => void;
+    /**
+     * Transfer-completion callback for true egress accounting and truncation
+     * detection.
+     *
+     * `onServe` fires when headers are committed and reports bytes *granted*
+     * (the response Content-Length). This fires once when the response body
+     * reaches its terminal state and reports bytes *actually transferred*
+     * through it, plus whether it drained fully or the client disconnected
+     * early. Use it for egress billing (`bytesTransferred`) or abandonment
+     * analytics (`completed === false`).
+     *
+     * Zero-cost when unset: the body is returned untouched, so byte bodies keep
+     * the runtime's static-body fast path. When set, the body is routed through
+     * a counting stream (byte bodies are wrapped too, so measurement is uniform
+     * across stores) -- a deliberate cost you opt into for the metering.
+     *
+     * Fires only for 200/206 GET responses (a body was served). Never fires for
+     * HEAD, 304, 302, 412, 416, or error responses. A throwing callback cannot
+     * corrupt the transfer: its error is routed to `onError` (operation
+     * `"audit"`).
+     *
+     * @example
+     * ```ts
+     * onTransfer: (e) => {
+     *   meter.recordEgress(e.key, e.bytesTransferred);
+     *   if (!e.completed) log.info({ ...e }, "download.abandoned");
+     * }
+     * ```
+     */
+    onTransfer?: (event: TransferEvent) => void;
+    /**
+     * Maximum number of distinct (coalesced) byte ranges to serve as
+     * multipart/byteranges before a multi-range request degrades to a full 200.
+     *
+     * A range-amplification defense: a client sending thousands of tiny or
+     * overlapping ranges would otherwise force a large multipart response.
+     * Overlapping/adjacent ranges are coalesced first, and if the result still
+     * exceeds this cap (or already covers the whole object) the full 200 is
+     * served instead. Matches the intent of nginx `max_ranges` and Go's
+     * sum-of-ranges check.
+     *
+     * @default 50
+     */
+    maxRanges?: number;
+    /**
+     * When true, appends `; charset=utf-8` to textual Content-Type values
+     * (text/*, application/json, application/xml, etc.) if not already present.
+     *
+     * Prevents UTF-7 encoding-sniffing XSS in legacy browsers that probe for
+     * a charset declaration and fall back to auto-detection when none is found.
+     *
+     * @default true
+     */
+    enforceCharset?: boolean;
+}
+/** Structured audit event for compliance logging. */
+export interface ServeAuditEvent {
+    /** Storage key that was served. */
+    key: string;
+    /**
+     * Request method. Distinguishes a HEAD metadata probe (no bytes transferred)
+     * from a GET, which otherwise both surface as `status: 200, bytesServed: 0`
+     * for an empty object.
+     */
+    method: "GET" | "HEAD";
+    /**
+     * HTTP status code. 302 = access granted via signed-URL redirect.
+     * 412/416 = access DENIED (failed precondition / unsatisfiable range):
+     * emitted so compliance trails capture denials, not only grants -- a 412
+     * is an optimistic-concurrency conflict signal auditors ask for.
+     */
+    status: 200 | 206 | 302 | 304 | 412 | 416;
+    /** MIME type of the served content. */
+    mime: string;
+    /**
+     * Body bytes GRANTED, not confirmed transferred: the body's
+     * Content-Length on a 200/206 GET (the event fires when headers are
+     * committed, before the stream drains, so a client disconnect can
+     * receive fewer bytes). 0 for HEAD, 304, 302, 412, and 416. Treat as
+     * access volume, never as exfiltration volume.
+     */
+    bytesServed: number;
+    /** Range start (inclusive), present only on 206. */
+    rangeStart?: number;
+    /** Range end (inclusive), present only on 206. */
+    rangeEnd?: number;
+    /** ETag of the served representation, if available. */
+    etag?: string;
+}
+/** Structured transfer-completion event ({@link ServeObjectOptions.onTransfer}). */
+export interface TransferEvent {
+    /** Storage key that was served. */
+    key: string;
+    /** Always GET: only GET responses carry a body to transfer. */
+    method: "GET";
+    /** HTTP status of the served body. */
+    status: 200 | 206;
+    /**
+     * Bytes GRANTED: the response body's Content-Length (206 range span or 200
+     * full size). Compare against {@link bytesTransferred} to detect truncation.
+     */
+    bytesExpected: number;
+    /**
+     * Bytes ACTUALLY read through the response body before it reached its
+     * terminal state. Equals {@link bytesExpected} on a fully-drained transfer;
+     * less when the client disconnected or cancelled early.
+     */
+    bytesTransferred: number;
+    /**
+     * `true` if the body drained completely, `false` if it was cancelled /
+     * the client disconnected before the last byte. The honest signal for
+     * egress billing and abandonment analytics.
+     */
+    completed: boolean;
+    /** Range start (inclusive), present only on 206. */
+    rangeStart?: number;
+    /** Range end (inclusive), present only on 206. */
+    rangeEnd?: number;
+}
+/**
+ * Serve an object from an {@link ObjectStore} with full RFC 7232/7233 support.
+ *
+ * Returns a function that takes a standard `Request` plus {@link ServeContext}
+ * and returns a `Response`. This is framework-agnostic: it works with Next.js
+ * App Router, Hono, SvelteKit, Remix, or any runtime that uses the Fetch API.
+ *
+ * The evaluation chain:
+ *   1. HEAD -> get metadata (ETag, Last-Modified, size)
+ *   2. Preconditions (If-Match / If-Unmodified-Since) -> 412
+ *   3. Freshness (If-None-Match / If-Modified-Since) -> 304
+ *   4. If-Range validation -> honor or ignore Range
+ *   5. Range parsing -> 206 or 416
+ *   6. Stream bytes -> 200 or 206
+ *
+ * TOCTOU guard: ETag/Last-Modified from the GET response are preferred over
+ * HEAD values. If the GET response omits Content-Range for a range request,
+ * the handler degrades to 200 (never emits a lying 206).
+ */
+export interface RawResponseParts {
+    status: number;
+    /** Reason phrase (e.g. "Partial Content", "Client Closed Request"). */
+    statusText: string;
+    headers: Record<string, string>;
+    /**
+     * `null` for bodyless statuses (HEAD, 304, 412, 416, 302, 405).
+     * `<ArrayBuffer>`-backed so `new Response(parts.body)` compiles under DOM lib.
+     */
+    body: ReadableStream<Uint8Array<ArrayBuffer>> | Uint8Array<ArrayBuffer> | null;
+}
+export declare function serveObject(store: ObjectStore, opts?: ServeObjectOptions): (req: ServableRequest, ctx: ServeContext) => Promise<Response>;
+/**
+ * The engine behind serveObject, exposed for server adapters: identical
+ * protocol behavior, but the result is RawResponseParts instead of a
+ * Response. Use this when your server writes status/headers/body natively
+ * (the bundled node adapter does) -- constructing a Response + Headers pair
+ * per request just to immediately deconstruct them is measurable overhead
+ * on hot paths.
+ */
+export declare function serveObjectRaw(store: ObjectStore, opts?: ServeObjectOptions): (req: ServableRequest, ctx: ServeContext) => Promise<RawResponseParts>;
+//# sourceMappingURL=web.d.ts.map

package/dist/web.d.ts.map

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