@lunora/storage 1.0.0-alpha.50 → 1.0.0-alpha.52

package/dist/index.d.mts

@@ -59,11 +59,20 @@ interface UploadOptions {
   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.
+   * known up front and rejected before the upload starts.
+   *
+   * A `ReadableStream` has no length to check, and R2 refuses any stream whose
+   * length it cannot read — so a capped stream is READ INTO MEMORY under the
+   * cap and uploaded as a sized body. Nothing reaches the bucket if the body
+   * crosses the limit.
+   *
+   * `maxSize` is therefore also the memory ceiling for a streamed upload, and
+   * the isolate's ~128 MB is shared by every concurrent request — so on the
+   * stream path `maxSize` is itself capped at 16 MiB and rejected above it.
+   * For objects larger than that use `createMultipartUpload` /
+   * `createUploadHandler`, which upload without ever holding the whole object.
+   * Must be a finite, non-negative number; anything else (`Number(undefined)`
+   * is the usual source) is rejected as a `VALIDATION_ERROR`.
    */
   maxSize?: number;
   /**
@@ -80,7 +89,10 @@ interface ListOptions {
   cursor?: string;
   /** R2 list delimiter — when set, common prefixes group instead of listing. */
   delimiter?: string;
-  /** Defaults to 100, capped at 1000 (R2 limit). */
+  /**
+   * Defaults to 100, capped at 1000 (R2 limit). A ceiling, not a promise: R2
+   * may return fewer per page to fit the entry metadata.
+   */
   limit?: number;
 }
 interface SignedUrlOptions {
@@ -190,6 +202,10 @@ interface Storage {
    * segment are rolled up into `delimitedPrefixes` (the "folders") and are NOT
    * in `objects` — a folder browser needs both, so a listing whose `objects` is
    * empty is not an empty directory.
+   *
+   * A page may hold FEWER objects than `options.limit`: R2 shrinks a page to
+   * fit the per-entry metadata this call asks for. Paginate on `truncated` /
+   * `cursor`, never on `objects.length === limit`.
    */
   list: (prefix?: string, options?: ListOptions) => Promise<{
     cursor?: string;

package/dist/index.d.ts

@@ -59,11 +59,20 @@ interface UploadOptions {
   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.
+   * known up front and rejected before the upload starts.
+   *
+   * A `ReadableStream` has no length to check, and R2 refuses any stream whose
+   * length it cannot read — so a capped stream is READ INTO MEMORY under the
+   * cap and uploaded as a sized body. Nothing reaches the bucket if the body
+   * crosses the limit.
+   *
+   * `maxSize` is therefore also the memory ceiling for a streamed upload, and
+   * the isolate's ~128 MB is shared by every concurrent request — so on the
+   * stream path `maxSize` is itself capped at 16 MiB and rejected above it.
+   * For objects larger than that use `createMultipartUpload` /
+   * `createUploadHandler`, which upload without ever holding the whole object.
+   * Must be a finite, non-negative number; anything else (`Number(undefined)`
+   * is the usual source) is rejected as a `VALIDATION_ERROR`.
    */
   maxSize?: number;
   /**
@@ -80,7 +89,10 @@ interface ListOptions {
   cursor?: string;
   /** R2 list delimiter — when set, common prefixes group instead of listing. */
   delimiter?: string;
-  /** Defaults to 100, capped at 1000 (R2 limit). */
+  /**
+   * Defaults to 100, capped at 1000 (R2 limit). A ceiling, not a promise: R2
+   * may return fewer per page to fit the entry metadata.
+   */
   limit?: number;
 }
 interface SignedUrlOptions {
@@ -190,6 +202,10 @@ interface Storage {
    * segment are rolled up into `delimitedPrefixes` (the "folders") and are NOT
    * in `objects` — a folder browser needs both, so a listing whose `objects` is
    * empty is not an empty directory.
+   *
+   * A page may hold FEWER objects than `options.limit`: R2 shrinks a page to
+   * fit the per-entry metadata this call asks for. Paginate on `truncated` /
+   * `cursor`, never on `objects.length === limit`.
    */
   list: (prefix?: string, options?: ListOptions) => Promise<{
     cursor?: string;

package/dist/index.mjs

@@ -1 +1 @@
-import{createBucketStorage as o}from"./packem_shared/createBucketStorage-D9fBoaEi.mjs";import{createStorage as i,scopeKey as d}from"./packem_shared/createStorage-B-E6dH3Q.mjs";import{buildPresignedUrl as g}from"./packem_shared/buildPresignedUrl-U55ktL8x.mjs";import{buildSignedUrl as p,verifySignedUrl as a}from"./packem_shared/buildSignedUrl-czz1xjLU.mjs";export{g as buildPresignedUrl,p as buildSignedUrl,o as createBucketStorage,i as createStorage,d as scopeKey,a as verifySignedUrl};
+import{createBucketStorage as o}from"./packem_shared/createBucketStorage-D9fBoaEi.mjs";import{createStorage as i,scopeKey as d}from"./packem_shared/createStorage-C5wU9cbC.mjs";import{buildPresignedUrl as g}from"./packem_shared/buildPresignedUrl-U55ktL8x.mjs";import{buildSignedUrl as p,verifySignedUrl as a}from"./packem_shared/buildSignedUrl-czz1xjLU.mjs";export{g as buildPresignedUrl,p as buildSignedUrl,o as createBucketStorage,i as createStorage,d as scopeKey,a as verifySignedUrl};

package/dist/packem_shared/createStorage-C5wU9cbC.mjs

@@ -0,0 +1 @@
+import{LunoraError as n}from"@lunora/errors";import{t as U,h as S,a as A,b as f}from"./internal-B5yyxF10.mjs";import{buildPresignedUrl as _}from"./buildPresignedUrl-U55ktL8x.mjs";import{buildSignedUrl as k}from"./buildSignedUrl-czz1xjLU.mjs";const w=1024,v=1e3,D=100,T=16*1024*1024,O=e=>{const a=e.checksums?.sha256;if(a===void 0)return e;const i=f(a),g=A(new Uint8Array(a));return new Proxy(e,{get(u,s){if(s==="sha256")return i;if(s==="sha256Base64")return g;const d=Reflect.get(u,s,u);return typeof d=="function"?d.bind(u):d},has(u,s){return s==="sha256"||s==="sha256Base64"||Reflect.has(u,s)}})},x=e=>{const a=e.checksums?.sha256;return{contentType:e.httpMetadata?.contentType,customMetadata:e.customMetadata,key:e.key,sha256:a===void 0?void 0:f(a),size:e.size,uploaded:e.uploaded===void 0?void 0:e.uploaded.getTime()}},y=e=>{const a=e.checksums?.sha256;return{checksums:e.checksums,customMetadata:e.customMetadata,etag:e.etag,httpEtag:e.httpEtag,httpMetadata:e.httpMetadata,key:e.key,sha256:a===void 0?void 0:f(a),sha256Base64:a===void 0?void 0:A(new Uint8Array(a)),size:e.size,uploaded:e.uploaded}},B=async(e,a)=>{let i=0;const g=s=>s instanceof ArrayBuffer?new Uint8Array(s):ArrayBuffer.isView(s)?new Uint8Array(s.buffer,s.byteOffset,s.byteLength):void 0,u=new TransformStream({transform(s,d){const h=g(s);if(h===void 0){d.error(new n("VALIDATION_ERROR","@lunora/storage: stream chunk is not a byte chunk; cannot enforce maxSize"));return}if(i+=h.byteLength,i>a){d.error(new n("PAYLOAD_TOO_LARGE",`@lunora/storage: stream body exceeds maxSize (> ${String(a)} bytes)`));return}d.enqueue(h)}});return await new Response(e.pipeThrough(u)).blob()},V=async(e,a)=>{if(!Number.isFinite(a)||a<0)throw new n("VALIDATION_ERROR",`@lunora/storage: maxSize must be a finite, non-negative number (received ${String(a)})`);if(e instanceof ReadableStream){if(a>T)throw new n("VALIDATION_ERROR",`@lunora/storage: maxSize ${String(a)} exceeds the ${String(T)}-byte ceiling for a streamed body, which must be buffered to be capped — use createMultipartUpload() or createUploadHandler() for objects this large`);return await B(e,a)}const i=e instanceof ArrayBuffer?e.byteLength:e.size;if(i>a)throw new n("PAYLOAD_TOO_LARGE",`@lunora/storage: body exceeds maxSize (${String(i)} > ${String(a)})`);return e},$=new TextEncoder,b=e=>$.encode(e).length,o=e=>{if(typeof e!="string"||e.length===0)throw new n("VALIDATION_ERROR","@lunora/storage: key must be a non-empty string");if(b(e)>w)throw new n("VALIDATION_ERROR",`@lunora/storage: key exceeds ${String(w)}-byte limit`);if(e.includes("\0"))throw new n("VALIDATION_ERROR","@lunora/storage: key contains NUL byte");if(S(e))throw new n("VALIDATION_ERROR","@lunora/storage: key contains a control character (including CR/LF)");if(e.startsWith("/"))throw new n("VALIDATION_ERROR","@lunora/storage: key must not start with `/`");if(e.split("/").includes(".."))throw new n("VALIDATION_ERROR","@lunora/storage: key contains a `..` path component")},q=e=>{if(e.allowedContentTypes!==void 0){if(e.contentType===void 0)throw new n("VALIDATION_ERROR","@lunora/storage: contentType is required when allowedContentTypes is set");if(!e.allowedContentTypes.includes(e.contentType))throw new n("VALIDATION_ERROR",`@lunora/storage: contentType "${e.contentType}" not in allowedContentTypes`)}},F=(e,a)=>{o(e),o(a);const g=`${e.endsWith("/")?e.slice(0,-1):e}/${a}`;if(b(g)>w)throw new n("VALIDATION_ERROR",`@lunora/storage: scoped key exceeds ${String(w)}-byte limit`);return g},X=e=>{if(!e.bucket)throw new n("INTERNAL","@lunora/storage: `bucket` is required");if(typeof e.bucketName!="string"||e.bucketName==="")throw new n("INTERNAL",'@lunora/storage: `bucketName` is required — pass the name this bucket is registered under (`"default"` for a single-bucket app)');const a=async(t,r,c={})=>{o(t),q(c);const m=c.maxSize===void 0?r:await V(r,c.maxSize),l=await e.bucket.put(t,m,{customMetadata:c.customMetadata,httpMetadata:c.contentType?{contentType:c.contentType}:void 0,...c.sha256===void 0?{}:{sha256:c.sha256}});return{etag:l.etag,httpEtag:l.httpEtag??`"${l.etag}"`,key:l.key}},i=async(t,r={})=>{o(t);const c=await(r.range?e.bucket.get(t,{range:r.range}):e.bucket.get(t));return c&&O(c)},g=async t=>{o(t),await e.bucket.delete(t)},u=async t=>{o(t);const r=e.bucket.head?await e.bucket.head(t):await e.bucket.get(t,{range:{length:0}});return r&&y(r)},s=async t=>{const r=await u(t);return r&&x(r)},d=async(t,r={})=>{if(t?.includes("\0"))throw new n("VALIDATION_ERROR","@lunora/storage: prefix contains NUL byte");const c=r.limit??D,m=Math.min(Math.max(1,Math.floor(c)),v),l=await e.bucket.list({cursor:r.cursor,delimiter:r.delimiter,include:["customMetadata","httpMetadata"],limit:m,prefix:t}),{delimitedPrefixes:E}=l;return{cursor:l.cursor,delimitedPrefixes:E,objects:l.objects.map(M=>y(M)),truncated:l.truncated}},h=t=>{if(!e.publicBaseUrl)throw new n("INTERNAL","@lunora/storage: `publicBaseUrl` is required for getUrl()");o(t);const r=t.split("/").map(c=>encodeURIComponent(c)).join("/");return`${U(e.publicBaseUrl)}/${r}`},R=async(t,r={})=>{if(!e.publicBaseUrl)throw new n("INTERNAL","@lunora/storage: `publicBaseUrl` is required for getSignedUrl()");if(!e.signingSecret)throw new n("INTERNAL","@lunora/storage: `signingSecret` is required for getSignedUrl()");return o(t),k({baseUrl:e.publicBaseUrl,bucketName:e.bucketName,contentType:r.contentType,expiresInSeconds:r.expiresInSeconds,key:t,method:r.method,secret:e.signingSecret})},I=async(t,r={})=>{if(o(t),!e.bucket.createMultipartUpload)throw new n("INTERNAL","@lunora/storage: bucket binding does not support multipart uploads (createMultipartUpload)");return e.bucket.createMultipartUpload(t,{customMetadata:r.customMetadata,httpMetadata:r.contentType?{contentType:r.contentType}:void 0})},p=(t,r)=>{if(o(t),typeof r!="string"||r.length===0)throw new n("VALIDATION_ERROR","@lunora/storage: resumeMultipartUpload requires a non-empty uploadId");if(!e.bucket.resumeMultipartUpload)throw new n("INTERNAL","@lunora/storage: bucket binding does not support multipart uploads (resumeMultipartUpload)");return e.bucket.resumeMultipartUpload(t,r)},N=async(t,r={})=>{if(!e.s3)throw new n("INTERNAL","@lunora/storage: `s3` credentials are required for getPresignedUrl() — pass { accountId, accessKeyId, secretAccessKey, bucket }");return o(t),_({credentials:e.s3,expiresInSeconds:r.expiresInSeconds,key:t,method:r.method})},L=async(t,r={})=>R(t,{contentType:r.contentType,expiresInSeconds:r.expiresInSeconds,method:"PUT"});return{bucketName:e.bucketName,createMultipartUpload:I,delete:g,download:i,generateUploadUrl:L,getMetadata:s,getPresignedUrl:N,getSignedUrl:R,getUrl:h,head:u,list:d,resumeMultipartUpload:p,store:a,upload:a}};export{X as createStorage,F as scopeKey};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/storage",
-  "version": "1.0.0-alpha.50",
+  "version": "1.0.0-alpha.52",
   "description": "R2-backed storage for Lunora: typed buckets and signed URLs",
   "keywords": [
     "cloudflare",
@@ -50,8 +50,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.31",
-    "@lunora/platform": "1.0.0-alpha.26",
+    "@lunora/errors": "1.0.0-alpha.32",
+    "@lunora/platform": "1.0.0-alpha.27",
     "@visulima/storage": "2.0.0",
     "aws4fetch": "1.0.20"
   },

package/dist/packem_shared/createStorage-B-E6dH3Q.mjs

@@ -1 +0,0 @@
-import{LunoraError as n}from"@lunora/errors";import{t as U,h as M,a as I,b as T}from"./internal-B5yyxF10.mjs";import{buildPresignedUrl as p}from"./buildPresignedUrl-U55ktL8x.mjs";import{buildSignedUrl as k}from"./buildSignedUrl-czz1xjLU.mjs";const w=1024,x=1e3,_=100,v=e=>{const a=e.checksums?.sha256;if(a===void 0)return e;const h=T(a),l=I(new Uint8Array(a));return new Proxy(e,{get(i,s){if(s==="sha256")return h;if(s==="sha256Base64")return l;const u=Reflect.get(i,s,i);return typeof u=="function"?u.bind(i):u},has(i,s){return s==="sha256"||s==="sha256Base64"||Reflect.has(i,s)}})},B=e=>{const a=e.checksums?.sha256;return{contentType:e.httpMetadata?.contentType,customMetadata:e.customMetadata,key:e.key,sha256:a===void 0?void 0:T(a),size:e.size,uploaded:e.uploaded===void 0?void 0:e.uploaded.getTime()}},R=e=>{const a=e.checksums?.sha256;return{checksums:e.checksums,customMetadata:e.customMetadata,etag:e.etag,httpEtag:e.httpEtag,httpMetadata:e.httpMetadata,key:e.key,sha256:a===void 0?void 0:T(a),sha256Base64:a===void 0?void 0:I(new Uint8Array(a)),size:e.size,uploaded:e.uploaded}},D=(e,a)=>{let h=0;const l=s=>s instanceof ArrayBuffer||ArrayBuffer.isView(s)?s.byteLength:void 0,i=new TransformStream({transform(s,u){const m=l(s);if(m===void 0){u.error(new Error("@lunora/storage: stream chunk is not a byte chunk; cannot enforce maxSize"));return}if(h+=m,h>a){u.error(new Error(`@lunora/storage: stream body exceeds maxSize (> ${String(a)} bytes)`));return}u.enqueue(s)}});return e.pipeThrough(i)},z=new TextEncoder,A=e=>z.encode(e).length,o=e=>{if(typeof e!="string"||e.length===0)throw new n("VALIDATION_ERROR","@lunora/storage: key must be a non-empty string");if(A(e)>w)throw new n("VALIDATION_ERROR",`@lunora/storage: key exceeds ${String(w)}-byte limit`);if(e.includes("\0"))throw new n("VALIDATION_ERROR","@lunora/storage: key contains NUL byte");if(M(e))throw new n("VALIDATION_ERROR","@lunora/storage: key contains a control character (including CR/LF)");if(e.startsWith("/"))throw new n("VALIDATION_ERROR","@lunora/storage: key must not start with `/`");if(e.split("/").includes(".."))throw new n("VALIDATION_ERROR","@lunora/storage: key contains a `..` path component")},V=e=>{if(e.allowedContentTypes!==void 0){if(e.contentType===void 0)throw new n("VALIDATION_ERROR","@lunora/storage: contentType is required when allowedContentTypes is set");if(!e.allowedContentTypes.includes(e.contentType))throw new n("VALIDATION_ERROR",`@lunora/storage: contentType "${e.contentType}" not in allowedContentTypes`)}},O=(e,a)=>{o(e),o(a);const l=`${e.endsWith("/")?e.slice(0,-1):e}/${a}`;if(A(l)>w)throw new n("VALIDATION_ERROR",`@lunora/storage: scoped key exceeds ${String(w)}-byte limit`);return l},K=e=>{if(!e.bucket)throw new n("INTERNAL","@lunora/storage: `bucket` is required");if(typeof e.bucketName!="string"||e.bucketName==="")throw new n("INTERNAL",'@lunora/storage: `bucketName` is required — pass the name this bucket is registered under (`"default"` for a single-bucket app)');const a=async(r,t,c={})=>{o(r),V(c);let f=t;if(typeof c.maxSize=="number"){let g;if(t instanceof ArrayBuffer?g=t.byteLength:t instanceof Blob&&(g=t.size),g!==void 0&&g>c.maxSize)throw new n("PAYLOAD_TOO_LARGE",`@lunora/storage: body exceeds maxSize (${String(g)} > ${String(c.maxSize)})`);t instanceof ReadableStream&&(f=D(t,c.maxSize))}const d=await e.bucket.put(r,f,{customMetadata:c.customMetadata,httpMetadata:c.contentType?{contentType:c.contentType}:void 0,...c.sha256===void 0?{}:{sha256:c.sha256}});return{etag:d.etag,httpEtag:d.httpEtag??`"${d.etag}"`,key:d.key}},h=async(r,t={})=>{o(r);const c=await(t.range?e.bucket.get(r,{range:t.range}):e.bucket.get(r));return c&&v(c)},l=async r=>{o(r),await e.bucket.delete(r)},i=async r=>{o(r);const t=e.bucket.head?await e.bucket.head(r):await e.bucket.get(r,{range:{length:0}});return t&&R(t)},s=async r=>{const t=await i(r);return t&&B(t)},u=async(r,t={})=>{if(r?.includes("\0"))throw new n("VALIDATION_ERROR","@lunora/storage: prefix contains NUL byte");const c=t.limit??_,f=Math.min(Math.max(1,Math.floor(c)),x),d=await e.bucket.list({cursor:t.cursor,delimiter:t.delimiter,limit:f,prefix:r}),{delimitedPrefixes:g}=d;return{cursor:d.cursor,delimitedPrefixes:g,objects:d.objects.map(S=>R(S)),truncated:d.truncated}},m=r=>{if(!e.publicBaseUrl)throw new n("INTERNAL","@lunora/storage: `publicBaseUrl` is required for getUrl()");o(r);const t=r.split("/").map(c=>encodeURIComponent(c)).join("/");return`${U(e.publicBaseUrl)}/${t}`},y=async(r,t={})=>{if(!e.publicBaseUrl)throw new n("INTERNAL","@lunora/storage: `publicBaseUrl` is required for getSignedUrl()");if(!e.signingSecret)throw new n("INTERNAL","@lunora/storage: `signingSecret` is required for getSignedUrl()");return o(r),k({baseUrl:e.publicBaseUrl,bucketName:e.bucketName,contentType:t.contentType,expiresInSeconds:t.expiresInSeconds,key:r,method:t.method,secret:e.signingSecret})},b=async(r,t={})=>{if(o(r),!e.bucket.createMultipartUpload)throw new n("INTERNAL","@lunora/storage: bucket binding does not support multipart uploads (createMultipartUpload)");return e.bucket.createMultipartUpload(r,{customMetadata:t.customMetadata,httpMetadata:t.contentType?{contentType:t.contentType}:void 0})},N=(r,t)=>{if(o(r),typeof t!="string"||t.length===0)throw new n("VALIDATION_ERROR","@lunora/storage: resumeMultipartUpload requires a non-empty uploadId");if(!e.bucket.resumeMultipartUpload)throw new n("INTERNAL","@lunora/storage: bucket binding does not support multipart uploads (resumeMultipartUpload)");return e.bucket.resumeMultipartUpload(r,t)},L=async(r,t={})=>{if(!e.s3)throw new n("INTERNAL","@lunora/storage: `s3` credentials are required for getPresignedUrl() — pass { accountId, accessKeyId, secretAccessKey, bucket }");return o(r),p({credentials:e.s3,expiresInSeconds:t.expiresInSeconds,key:r,method:t.method})},E=async(r,t={})=>y(r,{contentType:t.contentType,expiresInSeconds:t.expiresInSeconds,method:"PUT"});return{bucketName:e.bucketName,createMultipartUpload:b,delete:l,download:h,generateUploadUrl:E,getMetadata:s,getPresignedUrl:L,getSignedUrl:y,getUrl:m,head:i,list:u,resumeMultipartUpload:N,store:a,upload:a}};export{K as createStorage,O as scopeKey};