@lunora/storage 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 /**
-* A single-range read against R2: an `{ offset, length }` window (at least one
-* bound required, mirroring R2's own `R2Range`) or a `{ suffix }` tail. The
-* subset of `R2Range` that {@link Storage.download} forwards so a caller can
-* stream just the bytes it needs instead of the whole object.
-*/
+ * A single-range read against R2: an `{ offset, length }` window (at least one
+ * bound required, mirroring R2's own `R2Range`) or a `{ suffix }` tail. The
+ * subset of `R2Range` that {@link Storage.download} forwards so a caller can
+ * stream just the bytes it needs instead of the whole object.
+ */
 type R2RangeLike = {
   length: number;
   offset?: number;
@@ -14,15 +14,15 @@ type R2RangeLike = {
   suffix: number;
 };
 /**
-* Minimal projection of `R2Bucket`. Declared structurally so unit tests can
-* pass a plain object double; the real binding satisfies the same shape.
-*/
+ * Minimal projection of `R2Bucket`. Declared structurally so unit tests can
+ * pass a plain object double; the real binding satisfies the same shape.
+ */
 interface R2BucketLike {
   /**
-  * Begin a multipart upload (R2 `createMultipartUpload`). Optional so existing
-  * test doubles still satisfy the type; {@link Storage.createMultipartUpload}
-  * throws a clear error when the binding lacks it.
-  */
+   * Begin a multipart upload (R2 `createMultipartUpload`). Optional so existing
+   * test doubles still satisfy the type; {@link Storage.createMultipartUpload}
+   * throws a clear error when the binding lacks it.
+   */
   createMultipartUpload?: (key: string, options?: {
     customMetadata?: Record<string, string>;
     httpMetadata?: {
@@ -34,11 +34,11 @@ interface R2BucketLike {
     range?: R2RangeLike;
   }) => Promise<R2ObjectBodyLike | null>;
   /**
-  * Fetch an object's metadata without its body (R2 HEAD). Returns `null` when
-  * the object is absent. Declared optional so existing test doubles that only
-  * implement `get`/`put`/`list`/`delete` still satisfy the type; callers that
-  * need metadata fall back to a 0-length ranged `get()` when `head` is absent.
-  */
+   * Fetch an object's metadata without its body (R2 HEAD). Returns `null` when
+   * the object is absent. Declared optional so existing test doubles that only
+   * implement `get`/`put`/`list`/`delete` still satisfy the type; callers that
+   * need metadata fall back to a 0-length ranged `get()` when `head` is absent.
+   */
   head?: (key: string) => Promise<R2ObjectLike | null>;
   list: (options?: {
     cursor?: string;
@@ -65,11 +65,11 @@ interface R2UploadedPartLike {
   partNumber: number;
 }
 /**
-* An in-progress multipart upload, mirroring R2's `R2MultipartUpload`. Each part
-* (except the last) must be uniform in size. The object does not guarantee the
-* underlying upload still exists — a parallel `complete`/`abort` can invalidate
-* it — so wrap each call in error handling.
-*/
+ * An in-progress multipart upload, mirroring R2's `R2MultipartUpload`. Each part
+ * (except the last) must be uniform in size. The object does not guarantee the
+ * underlying upload still exists — a parallel `complete`/`abort` can invalidate
+ * it — so wrap each call in error handling.
+ */
 interface R2MultipartUploadLike {
   /** Abort the upload, discarding any uploaded parts. */
   abort: () => Promise<void>;
@@ -84,44 +84,44 @@ interface R2MultipartUploadLike {
 }
 interface R2ObjectLike {
   /**
-  * R2-computed checksums. The real binding exposes `sha256` as an
-  * `ArrayBuffer` (present only when R2 stored a SHA-256 for the object);
-  * declared optional so fakes and non-checksummed objects type-check.
-  */
+   * R2-computed checksums. The real binding exposes `sha256` as an
+   * `ArrayBuffer` (present only when R2 stored a SHA-256 for the object);
+   * declared optional so fakes and non-checksummed objects type-check.
+   */
   checksums?: {
     sha256?: ArrayBuffer;
   };
   customMetadata?: Record<string, string>;
   etag: string;
   /**
-  * The quoted form of {@link R2ObjectLike.etag} (e.g. `"abc123"`), suitable
-  * for emitting directly as an HTTP `ETag` header. The real binding always
-  * provides it; declared optional so existing doubles that only set `etag`
-  * still type-check (callers fall back to quoting `etag`).
-  */
+   * The quoted form of {@link R2ObjectLike.etag} (e.g. `"abc123"`), suitable
+   * for emitting directly as an HTTP `ETag` header. The real binding always
+   * provides it; declared optional so existing doubles that only set `etag`
+   * still type-check (callers fall back to quoting `etag`).
+   */
   httpEtag?: string;
   httpMetadata?: {
     contentType?: string;
   };
   key: string;
   /**
-  * Hex-encoded SHA-256 of the object body, surfaced by `download()`/`list()`
-  * when R2 carries a checksum (derived from {@link R2ObjectLike.checksums}).
-  */
+   * Hex-encoded SHA-256 of the object body, surfaced by `download()`/`list()`
+   * when R2 carries a checksum (derived from {@link R2ObjectLike.checksums}).
+   */
   sha256?: string;
   /**
-  * Base64-encoded SHA-256 of the object body, surfaced alongside
-  * {@link R2ObjectLike.sha256} from the same checksum. Base64 is the encoding
-  * RFC 9530 digest headers (`Repr-Digest`/`Content-Digest`) require, so HTTP
-  * layers can emit a spec-compliant digest without re-deriving it.
-  */
+   * Base64-encoded SHA-256 of the object body, surfaced alongside
+   * {@link R2ObjectLike.sha256} from the same checksum. Base64 is the encoding
+   * RFC 9530 digest headers (`Repr-Digest`/`Content-Digest`) require, so HTTP
+   * layers can emit a spec-compliant digest without re-deriving it.
+   */
   sha256Base64?: string;
   size: number;
   /**
-  * When the object was written. The real binding exposes this as a `Date`;
-  * declared optional so fakes that omit it still type-check.
-  * {@link Storage.getMetadata} normalises it to epoch ms.
-  */
+   * When the object was written. The real binding exposes this as a `Date`;
+   * declared optional so fakes that omit it still type-check.
+   * {@link Storage.getMetadata} normalises it to epoch ms.
+   */
   uploaded?: Date;
 }
 interface R2ObjectBodyLike extends R2ObjectLike {
@@ -130,11 +130,11 @@ interface R2ObjectBodyLike extends R2ObjectLike {
   text: () => Promise<string>;
 }
 /**
-* R2 S3-API credentials for {@link Storage.getPresignedUrl}. These are an R2 API
-* token's Access Key ID / Secret Access Key (NOT a Cloudflare API token), plus
-* the account id and bucket name. Required only if you call `getPresignedUrl`;
-* the worker-signed URL path (`getSignedUrl`) needs none of this.
-*/
+ * R2 S3-API credentials for {@link Storage.getPresignedUrl}. These are an R2 API
+ * token's Access Key ID / Secret Access Key (NOT a Cloudflare API token), plus
+ * the account id and bucket name. Required only if you call `getPresignedUrl`;
+ * the worker-signed URL path (`getSignedUrl`) needs none of this.
+ */
 interface R2S3Credentials {
   /** R2 S3 Access Key ID. */
   accessKeyId: string;
@@ -159,10 +159,10 @@ interface LunoraStorageOptions {
   /** Public base URL used by `getSignedUrl()`. Required for signed URLs. */
   publicBaseUrl?: string;
   /**
-  * R2 S3-API credentials enabling {@link Storage.getPresignedUrl} (native S3
-  * presigned URLs that hit R2 directly, bypassing the Worker). Omit to use
-  * only the worker-signed URL path.
-  */
+   * R2 S3-API credentials enabling {@link Storage.getPresignedUrl} (native S3
+   * presigned URLs that hit R2 directly, bypassing the Worker). Omit to use
+   * only the worker-signed URL path.
+   */
   s3?: R2S3Credentials;
   /** HMAC secret used by the worker-signed URL helper. Required for signed URLs. */
   signingSecret?: string;
@@ -173,13 +173,13 @@ interface UploadOptions {
   contentType?: string;
   customMetadata?: Record<string, string>;
   /**
-  * Maximum body size in bytes. For `ArrayBuffer`/`Blob` sources the length is
-  * known up front and rejected before the upload starts. For a
-  * `ReadableStream` the length isn't known synchronously, so the stream is
-  * piped through a byte counter that aborts the upload once the limit is
-  * exceeded — this also guards against R2 silently accepting/truncating an
-  * unbounded stream.
-  */
+   * Maximum body size in bytes. For `ArrayBuffer`/`Blob` sources the length is
+   * known up front and rejected before the upload starts. For a
+   * `ReadableStream` the length isn't known synchronously, so the stream is
+   * piped through a byte counter that aborts the upload once the limit is
+   * exceeded — this also guards against R2 silently accepting/truncating an
+   * unbounded stream.
+   */
   maxSize?: number;
 }
 interface ListOptions {
@@ -191,20 +191,20 @@ interface ListOptions {
 }
 interface SignedUrlOptions {
   /**
-  * Pin the `Content-Type` an uploader must send on a `method: "PUT"` URL.
-  * Baked into the HMAC canonical so the signature only authorizes a PUT with
-  * exactly this content-type; mirrored on the URL as `&amp;ct=...`. Ignored for
-  * `GET` URLs (a download has no request body content-type to pin).
-  */
+   * Pin the `Content-Type` an uploader must send on a `method: "PUT"` URL.
+   * Baked into the HMAC canonical so the signature only authorizes a PUT with
+   * exactly this content-type; mirrored on the URL as `&amp;ct=...`. Ignored for
+   * `GET` URLs (a download has no request body content-type to pin).
+   */
   contentType?: string;
   expiresInSeconds?: number;
   method?: "GET" | "PUT";
 }
 /**
-* Per-object metadata returned by {@link Storage.getMetadata} — a flat,
-* body-free projection of {@link R2ObjectLike}. Mirrors the shape Convex
-* surfaces for `ctx.storage.getMetadata` / the `_storage` system table.
-*/
+ * Per-object metadata returned by {@link Storage.getMetadata} — a flat,
+ * body-free projection of {@link R2ObjectLike}. Mirrors the shape Convex
+ * surfaces for `ctx.storage.getMetadata` / the `_storage` system table.
+ */
 interface ObjectMetadata {
   /** The object's `Content-Type` (R2 `httpMetadata.contentType`), if recorded. */
   contentType?: string;
@@ -221,49 +221,49 @@ interface ObjectMetadata {
 }
 interface Storage {
   /**
-  * Begin a native R2 **multipart upload** for very large objects — upload
-  * parts (each uniform in size except the last), then `complete` with the
-  * returned parts (or `abort`). Wraps R2's `createMultipartUpload`; throws if
-  * the bound bucket doesn't support it. For ordinary uploads use
-  * {@link Storage.upload} / {@link Storage.store}.
-  */
+   * Begin a native R2 **multipart upload** for very large objects — upload
+   * parts (each uniform in size except the last), then `complete` with the
+   * returned parts (or `abort`). Wraps R2's `createMultipartUpload`; throws if
+   * the bound bucket doesn't support it. For ordinary uploads use
+   * {@link Storage.upload} / {@link Storage.store}.
+   */
   createMultipartUpload: (key: string, options?: {
     contentType?: string;
     customMetadata?: Record<string, string>;
   }) => Promise<R2MultipartUploadLike>;
   delete: (key: string) => Promise<void>;
   /**
-  * Fetch a stored object's metadata + body. Pass `options.range` to stream
-  * only a byte window (R2 resolves the range server-side, so the unwanted
-  * bytes never reach the Worker) — `download(key)` reads the whole object.
-  */
+   * Fetch a stored object's metadata + body. Pass `options.range` to stream
+   * only a byte window (R2 resolves the range server-side, so the unwanted
+   * bytes never reach the Worker) — `download(key)` reads the whole object.
+   */
   download: (key: string, options?: {
     range?: R2RangeLike;
   }) => Promise<R2ObjectBodyLike | null>;
   /**
-  * Mint a short-lived signed `PUT` URL a client can upload directly to,
-  * optionally pinning the request `Content-Type`. Convex-compatible alias
-  * built on {@link Storage.getSignedUrl} with `method: "PUT"`.
-  */
+   * Mint a short-lived signed `PUT` URL a client can upload directly to,
+   * optionally pinning the request `Content-Type`. Convex-compatible alias
+   * built on {@link Storage.getSignedUrl} with `method: "PUT"`.
+   */
   generateUploadUrl: (key: string, options?: {
     contentType?: string;
     expiresInSeconds?: number;
   }) => Promise<string>;
   /**
-  * Read a stored object's metadata (size, content-type, sha256, upload time,
-  * custom metadata) without fetching its body. Returns `null` when the object
-  * is absent. Backed by an R2 HEAD (`bucket.head`) when available, falling
-  * back to a 0-length ranged `get()` otherwise. Mirrors Convex's
-  * `ctx.storage.getMetadata`.
-  */
+   * Read a stored object's metadata (size, content-type, sha256, upload time,
+   * custom metadata) without fetching its body. Returns `null` when the object
+   * is absent. Backed by an R2 HEAD (`bucket.head`) when available, falling
+   * back to a 0-length ranged `get()` otherwise. Mirrors Convex's
+   * `ctx.storage.getMetadata`.
+   */
   getMetadata: (key: string) => Promise<ObjectMetadata | null>;
   /**
-  * Mint a native S3 **presigned URL** (SigV4) that hits R2 directly, bypassing
-  * the Worker. Use for large downloads/uploads where you don't need per-request
-  * app gating and want the bytes off the Worker's CPU/bandwidth budget. Requires
-  * {@link LunoraStorageOptions.s3} credentials; throws if they're absent. For
-  * app-gated access (auth/policy/rate-limit) prefer {@link Storage.getSignedUrl}.
-  */
+   * Mint a native S3 **presigned URL** (SigV4) that hits R2 directly, bypassing
+   * the Worker. Use for large downloads/uploads where you don't need per-request
+   * app gating and want the bytes off the Worker's CPU/bandwidth budget. Requires
+   * {@link LunoraStorageOptions.s3} credentials; throws if they're absent. For
+   * app-gated access (auth/policy/rate-limit) prefer {@link Storage.getSignedUrl}.
+   */
   getPresignedUrl: (key: string, options?: PresignedUrlOptions) => Promise<string>;
   getSignedUrl: (key: string, options?: SignedUrlOptions) => Promise<string>;
   getUrl: (key: string) => string;
@@ -273,16 +273,16 @@ interface Storage {
     truncated?: boolean;
   }>;
   /**
-  * Resume an in-progress multipart upload by its `uploadId` (e.g. across
-  * requests). Wraps R2's `resumeMultipartUpload`; the id is not validated by
-  * R2, so a stale id surfaces as an error on the first `uploadPart`/`complete`.
-  */
+   * Resume an in-progress multipart upload by its `uploadId` (e.g. across
+   * requests). Wraps R2's `resumeMultipartUpload`; the id is not validated by
+   * R2, so a stale id surfaces as an error on the first `uploadPart`/`complete`.
+   */
   resumeMultipartUpload: (key: string, uploadId: string) => R2MultipartUploadLike;
   /**
-  * Upload `body` to `key`, returning the stored key + etag. Convex-compatible
-  * alias for {@link Storage.upload} — it accepts the same {@link UploadOptions}
-  * so the `maxSize` / `allowedContentTypes` guards aren't lost behind the alias.
-  */
+   * Upload `body` to `key`, returning the stored key + etag. Convex-compatible
+   * alias for {@link Storage.upload} — it accepts the same {@link UploadOptions}
+   * so the `maxSize` / `allowedContentTypes` guards aren't lost behind the alias.
+   */
   store: (key: string, body: ReadableStream | ArrayBuffer | Blob, options?: UploadOptions) => Promise<{
     etag: string;
     httpEtag: string;
@@ -295,11 +295,11 @@ interface Storage {
   }>;
 }
 /**
-* A bucket-aware {@link Storage}: the methods target a default bucket, and
-* `bucket(name)` selects a different named bucket (declared via
-* `v.storage("name")`). `bucketName` is the bucket the current accessor targets
-* — the storage-rules middleware reads it to scope `(bucket, operation)` rules.
-*/
+ * A bucket-aware {@link Storage}: the methods target a default bucket, and
+ * `bucket(name)` selects a different named bucket (declared via
+ * `v.storage("name")`). `bucketName` is the bucket the current accessor targets
+ * — the storage-rules middleware reads it to scope `(bucket, operation)` rules.
+ */
 interface BucketStorage extends Storage {
   /** Select a named bucket. Unknown names throw with the list of registered buckets. */
   bucket: (name: string) => BucketStorage;
@@ -307,36 +307,36 @@ interface BucketStorage extends Storage {
   readonly bucketName: string;
 }
 /**
-* Compose several per-bucket {@link Storage} instances into one bucket-aware
-* accessor. The bare methods (`download` / `store` / …) target the default
-* bucket; `bucket(name)` switches to another. Each accessor is tagged with its
-* `bucketName` so `storageRules(...)` can enforce per-bucket.
-*
-* ```ts
-* storage: (env) => createBucketStorage({
-*     default: createStorage({ bucket: env.FILES }),
-*     avatars: createStorage({ bucket: env.AVATARS }),
-* }),
-* // → ctx.storage.download(key)             // default bucket
-* // → ctx.storage.bucket("avatars").store() // the avatars bucket
-* ```
-*
-* The bare accessor is tagged `"default"` — the canonical name a
-* `defineStorageRule({ bucket: "default" })` rule and the generated
-* `StorageBucketName` union both use — unless `options.default` names another
-* bucket (then the bare accessor takes that name). The binding it delegates to is
-* `options.default`, else the `"default"` key when present, else the first
-* registered bucket. Named buckets are reached with `bucket(name)`.
-*/
+ * Compose several per-bucket {@link Storage} instances into one bucket-aware
+ * accessor. The bare methods (`download` / `store` / …) target the default
+ * bucket; `bucket(name)` switches to another. Each accessor is tagged with its
+ * `bucketName` so `storageRules(...)` can enforce per-bucket.
+ *
+ * ```ts
+ * storage: (env) => createBucketStorage({
+ *     default: createStorage({ bucket: env.FILES }),
+ *     avatars: createStorage({ bucket: env.AVATARS }),
+ * }),
+ * // → ctx.storage.download(key)             // default bucket
+ * // → ctx.storage.bucket("avatars").store() // the avatars bucket
+ * ```
+ *
+ * The bare accessor is tagged `"default"` — the canonical name a
+ * `defineStorageRule({ bucket: "default" })` rule and the generated
+ * `StorageBucketName` union both use — unless `options.default` names another
+ * bucket (then the bare accessor takes that name). The binding it delegates to is
+ * `options.default`, else the `"default"` key when present, else the first
+ * registered bucket. Named buckets are reached with `bucket(name)`.
+ */
 declare const createBucketStorage: (buckets: Record<string, Storage>, options?: {
   default?: string;
 }) => BucketStorage;
 /**
-* Compose a per-tenant key from a scope prefix and a caller-supplied key.
-* Both halves are validated — the prefix may not contain `..` or NUL either,
-* and the resulting key must stay under R2's length ceiling. Recommended for
-* any multi-tenant deployment so client-supplied keys can't address peer data.
-*/
+ * Compose a per-tenant key from a scope prefix and a caller-supplied key.
+ * Both halves are validated — the prefix may not contain `..` or NUL either,
+ * and the resulting key must stay under R2's length ceiling. Recommended for
+ * any multi-tenant deployment so client-supplied keys can't address peer data.
+ */
 declare const scopeKey: (prefix: string, key: string) => string;
 declare const createStorage: (options: LunoraStorageOptions) => Storage;
 /** Parameters accepted by {@link buildPresignedUrl}. */
@@ -353,25 +353,25 @@ interface PresignedUrlParams {
   now?: () => number;
 }
 /**
-* Build a native S3 presigned URL for an R2 object using SigV4 query-string
-* auth. The returned URL points at R2's S3 endpoint and carries the full
-* signature, so it authorizes a single `GET`/`PUT` on `key` until it expires —
-* no Worker round-trip.
-*/
+ * Build a native S3 presigned URL for an R2 object using SigV4 query-string
+ * auth. The returned URL points at R2's S3 endpoint and carries the full
+ * signature, so it authorizes a single `GET`/`PUT` on `key` until it expires —
+ * no Worker round-trip.
+ */
 declare const buildPresignedUrl: (parameters: PresignedUrlParams) => Promise<string>;
 /**
-* Worker-signed URL: the `publicBaseUrl` joined to the object `key`, plus a query
-* string carrying `exp` (unix seconds), `method` (`GET` or `PUT`) and `sig`
-* (a base64url HMAC).
-*
-* The HMAC canonical includes the URL host so a signature minted for one bucket
-* cannot be replayed against another host on the same signing secret. Even so,
-* the signing secret MUST NOT be shared across buckets/tenants — host binding
-* narrows replay surface but is not a substitute for per-tenant key isolation.
-*
-* The Worker handling `GET /storage/:key` should call {@link verifySignedUrl}
-* to validate the signature + expiry before streaming the R2 body.
-*/
+ * Worker-signed URL: the `publicBaseUrl` joined to the object `key`, plus a query
+ * string carrying `exp` (unix seconds), `method` (`GET` or `PUT`) and `sig`
+ * (a base64url HMAC).
+ *
+ * The HMAC canonical includes the URL host so a signature minted for one bucket
+ * cannot be replayed against another host on the same signing secret. Even so,
+ * the signing secret MUST NOT be shared across buckets/tenants — host binding
+ * narrows replay surface but is not a substitute for per-tenant key isolation.
+ *
+ * The Worker handling `GET /storage/:key` should call {@link verifySignedUrl}
+ * to validate the signature + expiry before streaming the R2 body.
+ */
 declare const buildSignedUrl: (args: SignedUrlOptions & {
   baseUrl: string;
   key: string;
@@ -383,23 +383,23 @@ interface VerifyResult {
   key?: string;
   method?: "GET" | "PUT";
   /**
-  * Internal-only failure reason for server logs/diagnostics. **Do not echo
-  * to clients** — a precise reason ("expired" vs "bad_signature") is a
-  * signing oracle. Public responses should expose only `valid`.
-  */
+   * Internal-only failure reason for server logs/diagnostics. **Do not echo
+   * to clients** — a precise reason ("expired" vs "bad_signature") is a
+   * signing oracle. Public responses should expose only `valid`.
+   */
   reason?: "bad_signature" | "expired" | "malformed";
   valid: boolean;
 }
 /**
-* Verify a {@link buildSignedUrl} output. By default the signature is
-* canonicalized against the inbound `url.host`, which matches the build-side
-* host whenever the URL being verified is the URL that was minted. In a
-* topology where the host the Worker sees differs from the configured
-* `publicBaseUrl` host (e.g. a CDN host vs a Worker route that rewrites
-* `Host`), pass `expectedHost` (the `publicBaseUrl` host) so verification
-* canonicalizes against the same host the signature was minted for instead of
-* failing every request as `bad_signature`.
-*/
+ * Verify a {@link buildSignedUrl} output. By default the signature is
+ * canonicalized against the inbound `url.host`, which matches the build-side
+ * host whenever the URL being verified is the URL that was minted. In a
+ * topology where the host the Worker sees differs from the configured
+ * `publicBaseUrl` host (e.g. a CDN host vs a Worker route that rewrites
+ * `Host`), pass `expectedHost` (the `publicBaseUrl` host) so verification
+ * canonicalizes against the same host the signature was minted for instead of
+ * failing every request as `bad_signature`.
+ */
 declare const verifySignedUrl: (input: string | URL, secret: string, options?: {
   expectedHost?: string;
 }) => Promise<VerifyResult>;