naro-js 0.3.0 → 0.4.0

package/README.md

@@ -492,11 +492,54 @@ const { data: link } = await naro.storage
   (`bucketId`, `createdAt`, `size`, `contentType`, …); naro-js's `info`
   answers the same snake_case `FileObject` as `list`, with the size and type
   in `metadata.size` and `metadata.mimetype`.
-- An upload sends the file's own bytes, 50 MiB at most, typed as the file
-  is (`Blob.type`, or `application/octet-stream`; a string is
-  `text/plain;charset=utf-8`). The body is a `Blob`, `File`, `ArrayBuffer`,
-  typed array or string — not a stream or `FormData`, and not a buffer
-  transferred away (detached), which has no bytes left: `INVALID_BODY`.
+- An upload sends the file's own bytes, typed as the file is (`Blob.type`,
+  or `application/octet-stream`; a string is `text/plain;charset=utf-8`).
+  The body is a `Blob`, `File`, `ArrayBuffer`, typed array or string — not
+  a stream or `FormData`, and not a buffer transferred away (detached),
+  which has no bytes left: `INVALID_BODY`.
+- One request carries 50 MiB. A larger body goes in parts by itself, up to
+  the plan's largest object: 16–64 MiB parts, four at a time, each tried
+  again up to three times after `NETWORK_ERROR`, a `5xx` or
+  `OBJECT_RATE_LIMITED` (waiting 1, 2, then 4 seconds, or the seconds the
+  429 says) — not after `507 STORAGE_QUOTA_EXCEEDED`, which lasts until
+  files are deleted. A part that still fails fails the upload with its
+  error, and the upload is called off. The last step is never tried again: if its
+  answer is lost (`NETWORK_ERROR`), ask `info(path)` whether the file is
+  there; if the backend refuses it, the upload is called off too and the
+  refusal is the answer. A part answered `UPLOAD_NOT_FOUND` belongs to an
+  upload that has ended — one left unsent for about an hour has. An upload in
+  parts must finish within 24 hours of its start (R2 ends unfinished
+  multipart uploads after a day). Replacing a file in parts (`update`, or
+  `upload` with `upsert` over a file that is there) needs room in the
+  project's capacity for the old file and the new one until it completes: if
+  the two together are over it, the upload answers
+  `507 STORAGE_QUOTA_EXCEEDED` before any part is sent.
+- `onProgress: (sentBytes, totalBytes) => void` is called after each part
+  of an upload over 50 MiB, the last time with both the same. An upload of
+  50 MiB or less is one request and does not call it. A `File` is sliced
+  into the parts, never read whole first. What the callback throws — or an
+  `async` one rejects with — does not stop the upload.
+
+- `signal: AbortSignal` stops an upload (`upload` and `update`): what has
+  not been answered yet is called off, and the upload answers `ABORTED`
+  ("The upload was stopped before it finished."). An upload in parts is
+  called off on the backend too — no part starts after the signal, and
+  `onProgress` is not called again — so its name and the space it reserved
+  are free at once, not after the hour its lock lasts. Its first step is
+  never cut short (a signal during it is acted on once it answers), and once
+  its last step is sent the signal stops nothing: that step's answer is the
+  upload's. A signal already aborted sends nothing. A page closed or a
+  network lost mid-upload sends no abort: the name waits for the lock.
+
+```ts
+const stop = new AbortController();
+cancelButton.onclick = () => stop.abort();
+await naro.storage.from("videos").upload(`${user.id}/talk.mp4`, file, {
+  onProgress: (sent, total) => setPercent(Math.round((sent / total) * 100)),
+  signal: stop.signal,
+});
+```
+
 - A `contentType` or `cacheControl` no header can carry (a CR, LF or NUL
   inside, or a character past U+00FF) is answered before a request, as the
   backend answers one it cannot read: `INVALID_CONTENT_TYPE`, and
@@ -512,7 +555,15 @@ const { data: link } = await naro.storage
   check.
 - `exists` answers `false` for `OBJECT_NOT_FOUND` and passes every other
   error on. `getPublicUrl` makes no request and answers `{ data, error }`.
+- `objectRoute(bucket, path)` names an object the way the client does:
+  `{ ok: true, encoded }` with `<bucket>/<path>` as the object routes carry
+  it (each segment `encodeURIComponent`-ed), or `{ ok: false, error }` with
+  the client's own `INVALID_PATH` (type `ObjectRouteResult`). A tool that
+  streams an object itself builds `/_naro/v1/storage/object/<encoded>` from
+  it and gets the URL and the refusals the client would — `naro storage cp`
+  downloads that way.
 - `OBJECT_RATE_LIMITED` and `STORAGE_OPS_QUOTA_EXCEEDED` carry
   `details.retryAfter`, in seconds.
-- Not yet: `move`, `copy`, `createSignedUrls`, `list`'s `search`, files over
-  50 MiB, and bucket methods (buckets are made with `naro storage bucket`).
+- Not yet: `move`, `copy`, `createSignedUrls`, `list`'s `search`, resuming
+  an upload in another session, and bucket methods (buckets are made with
+  `naro storage bucket`).

package/dist/errors.d.ts

@@ -25,6 +25,11 @@ export declare function networkError(cause: unknown): NaroError;
  * code exchange a page runs on load (PR #68 review 10). It is called off.
  */
 export declare function requestTimeout(ms: number): NaroError;
+/**
+ * An upload the caller's `signal` stopped (PR #111 review r1): what was not
+ * answered yet was called off. Never tried again.
+ */
+export declare function uploadAborted(): NaroError;
 /** An answer, but not one a Naro worker gives: HTML, empty, or the wrong shape. */
 export declare function invalidResponse(status: number): NaroError;
 /**

package/dist/http.d.ts

@@ -15,7 +15,7 @@ export type HttpConfig = {
     tokens: TokenStore;
 };
 export type CallOptions = {
-    method: "GET" | "POST" | "DELETE";
+    method: "GET" | "POST" | "PUT" | "DELETE";
     /** Below `/_naro/v1`, e.g. `/data/query`. */
     path: string;
     /** Sent as JSON. */
@@ -60,9 +60,21 @@ export type SendOptions = {
     headers?: Record<string, string>;
     body?: BodyInit;
     withToken: boolean;
+    /**
+     * An upload's `signal` (PR #111 review r1): it calls the request off until
+     * its answer comes — ABORTED, not NETWORK_ERROR — and never the reading
+     * of an answer that came, which may be a success.
+     */
+    signal?: AbortSignal | undefined;
 };
+/**
+ * A failure carries the answer's HTTP status, or null when nothing answered
+ * (NETWORK_ERROR): a multipart upload tries a part again on a 5xx, whatever
+ * the body said (Storage 3-1f, plan C7).
+ */
 export type SendResult = {
     error: NaroError;
+    status: number | null;
 } | {
     error: null;
     response: Response;

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export type { AuthStorage } from "./auth/storage.js";
 export type { NaroError } from "./errors.js";
 export type { FetchLike } from "./http.js";
 export type { StorageClient, StorageFileApi } from "./storage/client.js";
+export { objectRoute, type Encoded as ObjectRouteResult, } from "./storage/path.js";
 export type { DownloadOption, FileObject, FolderEntry, ListOptions, UpdateOptions, UploadBody, UploadOptions, UploadResult, } from "./storage/types.js";
 export type { ArrayValues, FilterGroup, FilterGroupCallback, InsertBuilder, MatchQuery, MutationBuilder, RawFilterValue, SelectBuilder, TableBuilder, } from "./query/builder.js";
 export { quoteFilterValue, type FilterOperatorName } from "./query/filters.js";

package/dist/index.js

@@ -14,6 +14,12 @@ function requestTimeout(ms) {
     message: `The Naro backend did not answer within ${String(Math.round(ms / 1e3))} seconds. Check the network and try again.`
   };
 }
+function uploadAborted() {
+  return {
+    code: "ABORTED",
+    message: "The upload was stopped before it finished."
+  };
+}
 function invalidResponse(status) {
   return {
     code: "INVALID_RESPONSE",
@@ -181,6 +187,12 @@ async function send(config, options) {
     credentials: "omit"
   };
   if (options.body !== void 0) init.body = options.body;
+  const { signal } = options;
+  if (signal?.aborted) return { error: uploadAborted(), status: null };
+  const controller = signal ? new AbortController() : null;
+  const stop = () => controller?.abort();
+  if (controller) init.signal = controller.signal;
+  signal?.addEventListener("abort", stop);
   let response;
   try {
     const fetchImpl = config.fetch ?? globalThis.fetch;
@@ -189,26 +201,34 @@ async function send(config, options) {
       init
     );
   } catch (error2) {
-    return { error: networkError(error2) };
+    return {
+      error: signal?.aborted ? uploadAborted() : networkError(error2),
+      status: null
+    };
+  } finally {
+    signal?.removeEventListener("abort", stop);
   }
-  if (response.status >= 200 && response.status < 300)
-    return { error: null, response };
+  const { status } = response;
+  if (status >= 200 && status < 300) return { error: null, response };
   let text;
   try {
     text = await response.text();
   } catch (error2) {
-    return { error: networkError(error2) };
+    return { error: networkError(error2), status: null };
   }
   let body;
   if (text.trim() !== "") {
     try {
       body = JSON.parse(text);
     } catch {
-      return { error: invalidResponse(response.status) };
+      return { error: invalidResponse(status), status };
     }
   }
-  const error = errorFromBody(response.status, body) ?? invalidResponse(response.status);
-  return { error: await settled(config, error, response.headers, token) };
+  const error = errorFromBody(status, body) ?? invalidResponse(status);
+  return {
+    error: await settled(config, error, response.headers, token),
+    status
+  };
 }
 var RETRY_AFTER_CODES = /* @__PURE__ */ new Set([
   "RATE_LIMITED",
@@ -1806,11 +1826,181 @@ var TableBuilder = class {
   }
 };
 
+// src/storage/answer.ts
+function fail(error) {
+  return { data: null, error };
+}
+var isUploadResult = (value) => isRecord(value) && typeof value.id === "string" && typeof value.path === "string" && typeof value.fullPath === "string";
+function dataOf2(status, body, guard) {
+  if (isRecord(body) && Object.hasOwn(body, "data") && guard(body.data))
+    return { data: body.data, error: null };
+  return fail(invalidResponse(status));
+}
+async function readJson(response, guard) {
+  let text;
+  try {
+    text = await response.text();
+  } catch (error) {
+    return fail(networkError(error));
+  }
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return fail(invalidResponse(response.status));
+  }
+  return dataOf2(response.status, body, guard);
+}
+
+// src/storage/multipart.ts
+var ROUTE = "/storage/upload/multipart";
+var CONCURRENCY = 4;
+var ATTEMPTS = 4;
+var BACKOFF_MS = [1e3, 2e3, 4e3];
+var UPLOAD_ID = /^[\w-][\w.-]*$/;
+var positive = (value) => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+var planFor = (size) => (value) => isRecord(value) && typeof value.uploadId === "string" && UPLOAD_ID.test(value.uploadId) && positive(value.partSize) && positive(value.partCount) && (value.partCount - 1) * value.partSize < size && value.partCount * value.partSize >= size;
+var partAnswer = (n) => (value) => isRecord(value) && value.partNumber === n && typeof value.etag === "string" && value.etag !== "";
+var retryable = (error, status) => error.code === "NETWORK_ERROR" || error.code === "OBJECT_RATE_LIMITED" || status !== null && status >= 500 && error.code !== "STORAGE_QUOTA_EXCEEDED";
+function waitAfter(error, attempt2) {
+  const after = isRecord(error.details) ? error.details.retryAfter : void 0;
+  if (typeof after === "number") return after * 1e3;
+  if (error.code === "OBJECT_RATE_LIMITED") return 1e3;
+  return BACKOFF_MS[attempt2 - 1] ?? 4e3;
+}
+var sleepFor = (ms, signal) => new Promise((done) => {
+  if (signal?.aborted) {
+    done();
+    return;
+  }
+  const end = () => {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", end);
+    done();
+  };
+  const timer = setTimeout(end, ms);
+  signal?.addEventListener("abort", end);
+});
+async function uploadInParts(a) {
+  const { signal } = a;
+  const sleep = a.sleep ?? sleepFor;
+  if (signal?.aborted) return fail(uploadAborted());
+  const started = await call(a.http, {
+    method: a.method,
+    path: ROUTE,
+    body: {
+      bucket: a.bucket,
+      path: a.path,
+      size: a.size,
+      contentType: a.contentType,
+      cacheControl: a.cacheControl,
+      // PUT always replaces: the worker refuses `upsert` on it.
+      ...a.method === "POST" && a.upsert ? { upsert: true } : {}
+    },
+    withToken: true
+  });
+  if (started.error !== null) return fail(started.error);
+  const plan = dataOf2(
+    started.answer.status,
+    started.answer.body,
+    planFor(a.size)
+  );
+  if (plan.error !== null) return fail(plan.error);
+  const { uploadId, partSize, partCount } = plan.data;
+  const base = `${ROUTE}/${uploadId}`;
+  const progress = (sentBytes2) => {
+    if (signal?.aborted) return;
+    try {
+      const result = a.onProgress?.(sentBytes2, a.size);
+      if (isThenable(result)) result.then(void 0, () => void 0);
+    } catch {
+    }
+  };
+  const callOff = async () => {
+    await call(a.http, { method: "DELETE", path: base, withToken: true }).catch(
+      () => void 0
+    );
+  };
+  const etags = [];
+  const failure = {
+    error: signal?.aborted ? uploadAborted() : null
+  };
+  let next = 1;
+  let sentBytes = 0;
+  const onAbort = () => {
+    failure.error ??= uploadAborted();
+  };
+  const tryPart = async (n, bytes) => {
+    const sent = await send(a.http, {
+      method: "PUT",
+      path: `${base}/${String(n)}`,
+      headers: { "content-type": "application/octet-stream" },
+      body: bytes,
+      withToken: true,
+      signal
+    });
+    if (sent.error !== null) return sent;
+    const read = await readJson(sent.response, partAnswer(n));
+    if (read.error !== null)
+      return { error: read.error, status: sent.response.status };
+    return { etag: read.data.etag };
+  };
+  const sendPart = async (n) => {
+    const from = (n - 1) * partSize;
+    const to = Math.min(from + partSize, a.size);
+    const bytes = a.body instanceof Uint8Array ? a.body.subarray(from, to) : a.body.slice(from, to);
+    for (let attempt2 = 1; ; attempt2 += 1) {
+      const tried = await tryPart(n, bytes);
+      if ("etag" in tried) {
+        etags[n - 1] = tried.etag;
+        sentBytes += to - from;
+        progress(sentBytes);
+        return null;
+      }
+      if (attempt2 === ATTEMPTS || failure.error !== null || !retryable(tried.error, tried.status))
+        return tried.error;
+      await sleep(waitAfter(tried.error, attempt2), signal);
+      if (failure.error !== null) return tried.error;
+    }
+  };
+  const worker = async () => {
+    while (failure.error === null && next <= partCount) {
+      const n = next;
+      next += 1;
+      const error = await sendPart(n);
+      if (error !== null) failure.error ??= error;
+    }
+  };
+  signal?.addEventListener("abort", onAbort);
+  await Promise.all(
+    Array.from({ length: Math.min(CONCURRENCY, partCount) }, worker)
+  );
+  signal?.removeEventListener("abort", onAbort);
+  if (failure.error !== null) {
+    await callOff();
+    return fail(failure.error);
+  }
+  const completed = await call(a.http, {
+    method: "POST",
+    path: `${base}/complete`,
+    body: {
+      parts: etags.map((etag, i) => ({ partNumber: i + 1, etag }))
+    },
+    withToken: true
+  });
+  if (completed.error !== null) {
+    if (completed.answer !== null && completed.error.code !== "INVALID_RESPONSE")
+      await callOff();
+    return fail(completed.error);
+  }
+  return dataOf2(completed.answer.status, completed.answer.body, isUploadResult);
+}
+var isThenable = (value) => typeof value === "object" && value !== null && typeof value.then === "function";
+
 // src/storage/path.ts
 var MAX_SINGLE_UPLOAD_BYTES = 52428800;
 var STORAGE_MESSAGES = {
   bucket: "The bucket name is not valid.",
-  tooLarge: "Uploads over 50 MiB are not supported yet.",
   request: "The storage request is not valid.",
   body: "upload takes a Blob, File, ArrayBuffer, typed array or string."
 };
@@ -1835,9 +2025,6 @@ function invalidPath(reason) {
     message: `The object path is not valid: it ${reason}.`
   };
 }
-function objectTooLarge() {
-  return { code: "OBJECT_TOO_LARGE", message: STORAGE_MESSAGES.tooLarge };
-}
 function encodePath(path) {
   if (typeof path !== "string" || path === "")
     return { ok: false, error: invalidPath("is empty") };
@@ -1874,6 +2061,16 @@ function encodeBucket(bucket) {
     };
   return { ok: true, encoded: encodeURIComponent(bucket) };
 }
+function objectRoute(bucket, path) {
+  const encodedBucket = encodeBucket(bucket);
+  if (!encodedBucket.ok) return encodedBucket;
+  const encodedPath = encodePath(path);
+  if (!encodedPath.ok) return encodedPath;
+  return {
+    ok: true,
+    encoded: `${encodedBucket.encoded}/${encodedPath.encoded}`
+  };
+}
 var isArrayBuffer = (value) => Object.prototype.toString.call(value) === "[object ArrayBuffer]";
 function isDetached(buffer) {
   if (!isArrayBuffer(buffer)) return false;
@@ -1956,36 +2153,12 @@ function payloadOf(body, contentType) {
 
 // src/storage/client.ts
 var SIGNED_PREFIX = "/_naro/v1/storage/object/sign/";
-function fail(error) {
-  return { data: null, error };
-}
-var isUploadResult = (value) => isRecord(value) && typeof value.id === "string" && typeof value.path === "string" && typeof value.fullPath === "string";
 var isFileObject = (value) => isRecord(value) && typeof value.id === "string" && typeof value.name === "string" && isRecord(value.metadata);
 var isEntry2 = (value) => isRecord(value) && typeof value.name === "string" && (value.id === null || isFileObject(value));
 var isSigned = (value) => isRecord(value) && typeof value.signedUrl === "string" && value.signedUrl.startsWith(SIGNED_PREFIX);
 function listOf(guard) {
   return (value) => Array.isArray(value) && value.every(guard);
 }
-function dataOf2(status, body, guard) {
-  if (isRecord(body) && Object.hasOwn(body, "data") && guard(body.data))
-    return { data: body.data, error: null };
-  return fail(invalidResponse(status));
-}
-async function readJson(response, guard) {
-  let text;
-  try {
-    text = await response.text();
-  } catch (error) {
-    return fail(networkError(error));
-  }
-  let body;
-  try {
-    body = JSON.parse(text);
-  } catch {
-    return fail(invalidResponse(response.status));
-  }
-  return dataOf2(response.status, body, guard);
-}
 var StorageFileApi = class {
   #http;
   #auth;
@@ -1997,14 +2170,9 @@ var StorageFileApi = class {
   }
   /** `/storage/object/<route><bucket>/<path>`, or the refusal no request needs. */
   #objectPath(route, path) {
-    const bucket = encodeBucket(this.#bucket);
-    if (!bucket.ok) return bucket;
-    const name = encodePath(path);
-    if (!name.ok) return name;
-    return {
-      ok: true,
-      path: `/storage/object/${route}${bucket.encoded}/${name.encoded}`
-    };
+    const target = objectRoute(this.#bucket, path);
+    if (!target.ok) return target;
+    return { ok: true, path: `/storage/object/${route}${target.encoded}` };
   }
   /** `/storage/object/<route><bucket>`, for the routes that take names in the body. */
   #bucketPath(route) {
@@ -2026,8 +2194,24 @@ var StorageFileApi = class {
     const cache = `max-age=${options.cacheControl ?? "3600"}`;
     const unreadable = headerProblem(options.contentType, cache);
     if (unreadable !== null) return fail(unreadable);
-    if (payload.size > MAX_SINGLE_UPLOAD_BYTES) return fail(objectTooLarge());
+    const { signal } = options;
+    if (signal?.aborted) return fail(uploadAborted());
     await this.#auth.ready();
+    if (payload.size > MAX_SINGLE_UPLOAD_BYTES)
+      return uploadInParts({
+        http: this.#http,
+        method,
+        bucket: this.#bucket,
+        path,
+        // No copy: a Blob stays lazy, a Uint8Array is viewed, an ArrayBuffer wrapped.
+        body: isArrayBuffer(payload.body) ? new Uint8Array(payload.body) : payload.body,
+        size: payload.size,
+        contentType: payload.type,
+        cacheControl: cache,
+        upsert,
+        ...options.onProgress ? { onProgress: options.onProgress } : {},
+        signal
+      });
     const headers = {
       "content-type": payload.type,
       "cache-control": cache
@@ -2038,7 +2222,9 @@ var StorageFileApi = class {
       path: target.path,
       headers,
       body: payload.body,
-      withToken: true
+      withToken: true,
+      // The fetch stops with the body: the worker undoes its claim at once.
+      signal
     });
     if (sent.error !== null) return fail(sent.error);
     return readJson(sent.response, isUploadResult);
@@ -2282,5 +2468,6 @@ function createClient(options) {
 export {
   NaroClient,
   createClient,
+  objectRoute,
   quoteFilterValue
 };

package/dist/storage/answer.d.ts

@@ -0,0 +1,9 @@
+import { type NaroError } from "../errors.js";
+import type { NaroResponse } from "../types.js";
+import type { UploadResult } from "./types.js";
+export declare function fail<T>(error: NaroError): NaroResponse<T>;
+export declare const isUploadResult: (value: unknown) => value is UploadResult;
+/** `{ data }` of a worker's JSON answer that passes `guard`, else INVALID_RESPONSE. */
+export declare function dataOf<T>(status: number, body: unknown, guard: (value: unknown) => value is T): NaroResponse<T>;
+/** A 2xx answer `send` handed back unread, read as `dataOf` reads one. */
+export declare function readJson<T>(response: Response, guard: (value: unknown) => value is T): Promise<NaroResponse<T>>;

package/dist/storage/multipart.d.ts

@@ -0,0 +1,23 @@
+import { type HttpConfig } from "../http.js";
+import type { NaroResponse } from "../types.js";
+import type { UploadResult } from "./types.js";
+export type PartsArgs = {
+    http: HttpConfig;
+    /** POST for `upload` (a new name, or `upsert`), PUT for `update`. */
+    method: "POST" | "PUT";
+    bucket: string;
+    /** The object's name as given: the start carries it in JSON, not a URL. */
+    path: string;
+    body: Blob | Uint8Array<ArrayBuffer>;
+    size: number;
+    contentType: string;
+    /** As the upload's header says it: `max-age=<seconds>`. */
+    cacheControl: string;
+    upsert: boolean;
+    onProgress?: (sentBytes: number, totalBytes: number) => void;
+    /** The caller's: stops the upload until the complete is sent. */
+    signal?: AbortSignal | undefined;
+    /** How a retry waits — `ms`, or until the signal aborts; tests pass their own. */
+    sleep?: (ms: number, signal: AbortSignal | undefined) => Promise<void>;
+};
+export declare function uploadInParts(a: PartsArgs): Promise<NaroResponse<UploadResult>>;

package/dist/storage/path.d.ts

@@ -3,13 +3,12 @@ import type { NaroError } from "../errors.js";
  * The most one upload request carries (original spec §9.1): 50 MiB.
  * data-core's MAX_SINGLE_UPLOAD_BYTES — storage/wire.test.ts holds them
  * equal. Over it, the edge cuts the body off and the browser often cannot
- * read the answer: the SDK refuses first.
+ * read the answer: the SDK sends a larger body in parts (Storage 3-1f).
  */
 export declare const MAX_SINGLE_UPLOAD_BYTES = 52428800;
 /** The worker's words (data-core's catalog) for what the SDK refuses itself. */
 export declare const STORAGE_MESSAGES: {
     readonly bucket: "The bucket name is not valid.";
-    readonly tooLarge: "Uploads over 50 MiB are not supported yet.";
     readonly request: "The storage request is not valid.";
     readonly body: "upload takes a Blob, File, ArrayBuffer, typed array or string.";
 };
@@ -29,7 +28,6 @@ export type Encoded = {
     error: NaroError;
 };
 export declare function invalidPath(reason: string): NaroError;
-export declare function objectTooLarge(): NaroError;
 /**
  * An object path as a URL carries it, each segment encoded once and `/`
  * kept as the separator — or the worker's INVALID_PATH for the paths no
@@ -53,6 +51,19 @@ export declare function downloadQuery(download: boolean | string | undefined): E
  * empty, `.`, `..`, a lone surrogate and the routes' own words.
  */
 export declare function encodeBucket(bucket: string): Encoded;
+/**
+ * `<bucket>/<path>` as the object routes carry it — the bucket by
+ * `encodeBucket`, the path by `encodePath` — or the INVALID_PATH either is
+ * refused with. Every object call builds its URL from it, and the package
+ * exports it for a tool that streams an object itself (naro-cli's
+ * download): it names the same URL, and is refused the same names.
+ */
+export declare function objectRoute(bucket: string, path: string): Encoded;
+/**
+ * `instanceof ArrayBuffer` is false for one made in another realm (an
+ * iframe, a vm context); the tag is the same in every realm.
+ */
+export declare const isArrayBuffer: (value: unknown) => value is ArrayBuffer;
 /** Why the worker refuses a cache-control it cannot read (its upload.ts). */
 export declare const CACHE_CONTROL_REASON = "must be max-age=<seconds> from 0 to 31536000";
 /**

package/dist/storage/types.d.ts

@@ -34,6 +34,25 @@ export type UploadOptions = {
     cacheControl?: string;
     /** Replace an object of the same name. Default false. */
     upsert?: boolean;
+    /**
+     * Called each time a part of an upload over 50 MiB is sent: the bytes
+     * sent so far and the body's size, ending with both the same. An upload
+     * of 50 MiB or less is one request and never calls it. What it throws is
+     * ignored: the upload goes on.
+     */
+    onProgress?: (sentBytes: number, totalBytes: number) => void;
+    /**
+     * Stops the upload: what has not been answered yet is called off, and the
+     * upload answers `ABORTED` ("The upload was stopped before it finished.").
+     * One over 50 MiB is called off on the backend too, so its name and the
+     * space it reserved are free at once — not after the hour its lock lasts;
+     * no part starts and `onProgress` is not called after the signal. Its
+     * first and last steps are never cut short: a signal during the first is
+     * acted on once it answers, and once the last is sent the signal stops
+     * nothing and that step's answer is the upload's. A signal already aborted
+     * sends nothing.
+     */
+    signal?: AbortSignal;
 };
 export type UpdateOptions = Omit<UploadOptions, "upsert">;
 export type UploadResult = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naro-js",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Auth, data and files for your Naro project, from the browser or the server.",
   "type": "module",
   "sideEffects": false,