@stowage/core 0.1.0 → 0.2.0

package/README.md

@@ -12,7 +12,7 @@ npm install @stowage/core
 ## Example
 
 A function written against `Storage` runs against every adapter: `memoryStorage()` in a test,
-`fsStorage()` on a laptop, `s3Storage()` in production.
+`fsStorage()` on a laptop, `s3Storage()` or `azureBlobStorage()` in production.
 
 ```ts
 import { isStorageError, type Storage } from "@stowage/core";
@@ -32,23 +32,23 @@ export async function readSettings(storage: Storage): Promise<unknown> {
 
 ## Runtimes
 
-Node 24 and later, Bun, Deno and `workerd` at the compatibility date `2026-09-01`. CI last ran green on Bun 1.4.2 and Deno 2.9.6.
+Node 24 and later, Bun, Deno and `workerd` at the compatibility date `2026-09-01` without Node APIs. CI last ran green on Bun 1.4.2 and Deno 2.9.6.
 
-The bundle measures 1.3 kB minified and gzipped.
+The bundle measures 3.3 kB minified and gzipped.
 
 ## Limits
 
 This section is empty. `@stowage/core` declares no capability; each storage declares its own, out
-of the four names of [spec 4.9](https://github.com/stowage-js/stowage/blob/@stowage/core@0.1.0/docs/spec.md#49-capabilities).
+of the five names of [spec 4.9](https://github.com/stowage-js/stowage/blob/@stowage/core@0.2.0/docs/spec.md#49-capabilities).
 
 ## Notes
 
 A failure reaches the caller in one of two shapes: a `StorageError`, which `isStorageError` tells
 apart, or the runtime's `AbortError` once a signal fired
-([spec 4.10](https://github.com/stowage-js/stowage/blob/@stowage/core@0.1.0/docs/spec.md#410-errors)).
+([spec 4.10](https://github.com/stowage-js/stowage/blob/@stowage/core@0.2.0/docs/spec.md#410-errors)).
 A name added to `StorageErrorCode` or `capabilityNames` is a minor release, so a `switch` over
 either needs a default branch
-([spec 9](https://github.com/stowage-js/stowage/blob/@stowage/core@0.1.0/docs/spec.md#9-versions)).
+([spec 10](https://github.com/stowage-js/stowage/blob/@stowage/core@0.2.0/docs/spec.md#10-versions)).
 
 ```ts
 import { isStorageError } from "@stowage/core";
@@ -70,12 +70,49 @@ export function describeFailure(failure: unknown): string {
 }
 ```
 
+An adapter written outside this repository takes what two adapters here need on the wire from
+this package rather than writing it again
+([spec 4.13](https://github.com/stowage-js/stowage/blob/@stowage/core@0.2.0/docs/spec.md#413-exports-for-adapter-authors)):
+
+- `invalidKeyReason` checks a key against its rule of spec 4.8, as the first act of every
+  operation.
+- `errorCodeForStatus` and `isTransientStatus` are the status mapping of spec 4.10, and
+  `withRetry` the retry loop around one request.
+- `parseXml` reads the XML an answer document is written in, and rejects anything outside that
+  subset with `XmlSyntaxError`.
+- `readEnvironment` reads one environment variable, and answers `""` where it is unset or the
+  runtime cannot read it.
+- `isUserMetadataKey`, `encodeUserMetadataValue`, `decodeUserMetadataValue` and
+  `userMetadataByteLength` carry user metadata in headers, and measure the 2 KB of spec 4.3.
+- `PresignedPut` is what `presignPut` resolves with on every adapter that declares
+  `presignedUrls`.
+
+```ts
+import { invalidKeyReason, StorageError } from "@stowage/core";
+
+export function requireWritableKey(bucket: string, key: string): void {
+  const reason = invalidKeyReason(key, "writable");
+
+  if (reason === undefined) return;
+
+  throw new StorageError({
+    code: "InvalidKey",
+    message: reason,
+    operation: "put",
+    bucket,
+    provider: "my-provider",
+    key,
+    attempts: 0,
+  });
+}
+```
+
 ## Specification
 
-[`docs/spec.md` at `@stowage/core@0.1.0`](https://github.com/stowage-js/stowage/blob/@stowage/core@0.1.0/docs/spec.md#4-the-core-api-stowagecore)
+[`docs/spec.md` at `@stowage/core@0.2.0`](https://github.com/stowage-js/stowage/blob/@stowage/core@0.2.0/docs/spec.md#4-the-core-api-stowagecore)
 is the contract: a caller may rely on what it states and on nothing else this package happens to
-export. The [terms it uses](https://github.com/stowage-js/stowage/blob/@stowage/core@0.1.0/CONTEXT.md)
-and the [decisions behind it](https://github.com/stowage-js/stowage/tree/@stowage/core@0.1.0/docs/adr)
+export. The [terms it uses](https://github.com/stowage-js/stowage/blob/@stowage/core@0.2.0/CONTEXT.md)
+and the [decisions behind it](https://github.com/stowage-js/stowage/tree/@stowage/core@0.2.0/docs/adr)
 are at the same tag.
 
 ## License

package/dist/index.d.ts

@@ -8,10 +8,14 @@
  * - `presignedUrls`: the concrete type carries `presignGet` and `presignPut`. Where not
  *   declared, neither method exists on the type.
  * - `rangeReads`: `get` honors `range`. Where not declared, a `range` is `Unsupported`.
- * - `userMetadata`: `put` stores `userMetadata`, `stat` and `get` return it, `copy` keeps it.
- *   Where not declared, a non-empty `userMetadata` is `Unsupported` and reads return `{}`.
+ * - `userMetadata`: `put` stores `userMetadata` whose keys are ASCII identifiers,
+ *   `[A-Za-z_][A-Za-z0-9_]*`; `stat` and `get` return it, `copy` keeps it. Where not declared,
+ *   a non-empty `userMetadata` is `Unsupported` and reads return `{}`.
+ * - `userMetadataTokenKeys`: beside `userMetadata`, a key may be any ASCII HTTP token, such as
+ *   `content-hash`. Where not declared, a key outside identifiers is `Unsupported` naming it;
+ *   without `userMetadata` too, the call is `Unsupported` naming that.
  */
-export declare const capabilityNames: readonly ["keyBytesPreserved", "presignedUrls", "rangeReads", "userMetadata"];
+export declare const capabilityNames: readonly ["keyBytesPreserved", "presignedUrls", "rangeReads", "userMetadata", "userMetadataTokenKeys"];
 /** One name out of {@link capabilityNames}. */
 type CapabilityName = (typeof capabilityNames)[number];
 //#endregion
@@ -23,6 +27,16 @@ type ResolverOptions = {
 /** A value, or a function that yields one. No core signature mentions it (ADR 0007). */
 type Resolvable<T> = T | ((options?: ResolverOptions) => T | Promise<T>);
 //#endregion
+//#region src/environment.d.ts
+/**
+ * ADR 0007: `process.env` is the one route through Node, Bun, Deno's compatibility layer
+ * and a Worker under `nodejs_compat`. A Worker without it has no `process` at all, and
+ * Deno without `--allow-env` throws `NotCapable` rather than answering `undefined`, so
+ * both leave the value empty. A name is read on its own, because enumerating
+ * `process.env` needs the unscoped permission in Deno.
+ */
+export declare function readEnvironment(name: string): string;
+//#endregion
 //#region src/errors.d.ts
 /**
  * What went wrong, as the one field a caller branches on (spec 4.10). A code added here is a
@@ -61,6 +75,19 @@ interface StorageErrorFields {
   readonly capability?: CapabilityName;
   readonly cause?: unknown;
 }
+/**
+ * A failure the rules of spec section 4 decide, stated without the adapter that raises it:
+ * the adapter adds what only it knows, its bucket, the operation and the attempts, and
+ * raises it through its own error factory (spec 4.13).
+ */
+type Refusal = {
+  readonly code: "Unsupported";
+  readonly message: string;
+  readonly capability: CapabilityName;
+} | {
+  readonly code: "InvalidRequest" | "InvalidOption";
+  readonly message: string;
+};
 export declare class StorageError extends Error {
   readonly code: StorageErrorCode;
   readonly operation: string;
@@ -88,32 +115,16 @@ type KeyRule = "writable" | "addressable" | "prefix";
 /** The reason a key violates the rule, or `undefined` where it holds. */
 export declare function invalidKeyReason(key: string, rule: KeyRule): string | undefined;
 //#endregion
-//#region src/retry.d.ts
-interface RetryOptions {
-  readonly maxAttempts: number;
-  readonly signal?: AbortSignal;
-}
-/**
- * Repeats `attempt` while it rejects with a `StorageError` whose `retryable` is `true`,
- * up to `maxAttempts` times, waiting a random delay between zero and
- * `min(5 s, 100 ms × 2^n)` before attempt `n + 1`. The error it finally rejects with
- * carries the number of attempts made.
- *
- * Spec 4.13 has this be the one definition of the loop of spec 7.5, so that an adapter
- * written outside this repository repeats on the same curve. `adapter-fs` and
- * `adapter-memory` have no request to send again and do not call it.
- */
-export declare function withRetry<T>(attempt: () => Promise<T>, options: RetryOptions): Promise<T>;
-//#endregion
-//#region src/status.d.ts
+//#region src/presigned-put.d.ts
 /**
- * The code the status decides on its own, or `undefined` for a status that decides
- * nothing. It is the fallback of spec 4.10: an adapter maps a provider code first and
- * reaches here where it recognizes none.
+ * What `presignPut` resolves with on every adapter that declares `presignedUrls`, so the code
+ * that uploads through it never names the provider (ADR 0022).
  */
-export declare function errorCodeForStatus(status: number): StorageErrorCode | undefined;
-/** Whether the status names a condition that may be gone a moment later (spec 4.10). */
-export declare function isTransientStatus(status: number): boolean;
+interface PresignedPut {
+  readonly url: string;
+  /** The headers the client sends beside the body. `Content-Length` is never among them. */
+  readonly headers: Readonly<Record<string, string>>;
+}
 //#endregion
 //#region src/storage.d.ts
 type PutBody = Uint8Array | string | ReadableStream<Uint8Array>;
@@ -126,7 +137,8 @@ interface PutOptions extends OperationOptions {
    * Stored where the storage declares `userMetadata`, and `Unsupported` elsewhere unless it is
    * empty. Keys are non-empty ASCII HTTP tokens compared case-insensitively; values may hold
    * any Unicode. Keys and values together hold at most 2 KB of encoded header bytes, and more
-   * is `InvalidRequest`.
+   * is `InvalidRequest`. A key outside ASCII identifiers, such as `content-hash`, is
+   * `Unsupported` where the storage does not declare `userMetadataTokenKeys`.
    */
   userMetadata?: Record<string, string>;
 }
@@ -194,10 +206,143 @@ interface Storage {
   stat(key: string, options?: OperationOptions): Promise<ObjectStat>;
   exists(key: string, options?: OperationOptions): Promise<boolean>;
   list(options?: ListOptions): ObjectListing;
+  /**
+   * Sends the keys in batches, one request per batch, and each adapter states its batch
+   * size. A per-key failure fills the report; a failure of a request as a whole rejects.
+   */
   delete(...keys: readonly string[]): Promise<DeleteReport>;
   deleteAll(prefix: string, options?: OperationOptions): Promise<DeleteReport>;
   copy(from: string, to: string, options?: OperationOptions): Promise<ObjectStat>;
   move(from: string, to: string, options?: OperationOptions): Promise<ObjectStat>;
 }
 //#endregion
-export type { ByteRange, CapabilityName, DeleteReport, GetOptions, KeyRule, ListOptions, ListPage, ObjectEntry, ObjectListing, ObjectStat, OperationOptions, PutBody, PutOptions, Resolvable, ResolverOptions, RetryOptions, Storage, StorageErrorCode, StorageErrorFields, StoredObject };
+//#region src/range.d.ts
+/** Refuses bounds spec 4.3 does not allow, which is decided before the object is looked up. */
+export declare function rangeBoundsRefusal(range: ByteRange | undefined): Refusal | undefined;
+/**
+ * Refuses a range that starts at or beyond the object's `size` bytes, which spec 4.3 names a
+ * refusal of the request rather than of the option, because a provider answers it with `416`.
+ */
+export declare function rangeStartRefusal(range: ByteRange, size: number, key: string): Refusal | undefined;
+/** The last byte the range names, both ends inclusive, clipped to the object's `size` bytes. */
+export declare function lastByteOf(range: ByteRange | undefined, size: number): number;
+/**
+ * Whether the whole object is the body the range asks for, clipped as spec 4.3 clips it. A
+ * provider may answer a range with the whole object and `200`, which RFC 9110 allows, and
+ * that answer is the one asked for exactly where this holds. An empty object holds no byte a
+ * range could start at, so no range covers it.
+ */
+export declare function rangeCoversWhole(range: ByteRange, size: number): boolean;
+/** The `Range` field of RFC 9110, both ends inclusive as `ByteRange` is. */
+export declare function rangeHeader(range: ByteRange): string;
+/**
+ * The size of the whole object out of a `206`'s `Content-Range`, which is what spec 4.4 has a
+ * ranged `get` report rather than the length of the range.
+ */
+export declare function wholeSizeOf(contentRange: string | null): number | undefined;
+//#endregion
+//#region src/retry.d.ts
+interface RetryOptions {
+  readonly maxAttempts: number;
+  readonly signal?: AbortSignal;
+}
+/**
+ * Repeats `attempt` while it rejects with a `StorageError` whose `retryable` is `true`,
+ * up to `maxAttempts` times, waiting a random delay between zero and
+ * `min(5 s, 100 ms × 2^n)` before attempt `n + 1`. The error it finally rejects with
+ * carries the number of attempts made.
+ *
+ * Spec 4.13 has this be the one definition of the loop of spec 7.5, so that an adapter
+ * written outside this repository repeats on the same curve. `adapter-fs` and
+ * `adapter-memory` have no request to send again and do not call it.
+ */
+export declare function withRetry<T>(attempt: () => Promise<T>, options: RetryOptions): Promise<T>;
+//#endregion
+//#region src/status.d.ts
+/**
+ * The code the status decides on its own, or `undefined` for a status that decides
+ * nothing. It is the fallback of spec 4.10: an adapter maps a provider code first and
+ * reaches here where it recognizes none.
+ */
+export declare function errorCodeForStatus(status: number): StorageErrorCode | undefined;
+/** Whether the status names a condition that may be gone a moment later (spec 4.10). */
+export declare function isTransientStatus(status: number): boolean;
+//#endregion
+//#region src/upload-stream.d.ts
+interface StreamUploadOptions {
+  readonly partSize: number;
+  readonly concurrency: number;
+  /** The provider's limit on the parts of one upload. */
+  readonly maxParts: number;
+  /** What the `InvalidRequest` for a stream above `maxParts` is told against. */
+  readonly bucket: string;
+  readonly provider: string;
+  readonly key: string;
+  readonly signal?: AbortSignal;
+}
+interface StreamUpload<T> {
+  /** The stream ended within the first part: the bytes go as one request. */
+  whole(bytes: Uint8Array<ArrayBuffer>): Promise<T>;
+  /** The first part filled: the adapter starts, sends through `sendParts`, and commits. */
+  multipart(sendParts: SendParts): Promise<T>;
+}
+type SendParts = <R>(send: (index: number, bytes: Uint8Array<ArrayBuffer>, signal: AbortSignal) => Promise<R>) => Promise<{
+  readonly results: readonly R[];
+  readonly size: number;
+}>;
+/**
+ * Reads the stream into parts of `partSize` and hands a stream that ends within the first
+ * to `whole`, any other to `multipart`. The reader, its buffers and the cancellation of
+ * the source stay here, so the spec promises one call rather than the order of five
+ * (ADR 0030).
+ *
+ * The source is canceled wherever the upload settles before the stream ended, as spec 4.2
+ * has it for a `put` that rejects before reading its body to the end.
+ */
+export declare function uploadStream<T>(stream: ReadableStream<Uint8Array>, options: StreamUploadOptions, upload: StreamUpload<T>): Promise<T>;
+//#endregion
+//#region src/user-metadata.d.ts
+type UserMetadataKeyRule = "token" | "identifier";
+export declare function isUserMetadataKey(name: string, rule: UserMetadataKeyRule): boolean;
+/** The value as a header carries it: as written where it travels so, else as encoded words. */
+export declare function encodeUserMetadataValue(value: string, options?: {
+  always?: boolean;
+}): string;
+/**
+ * What spec 4.3 bounds at 2 KB: every key and its value as `encodeUserMetadataValue` writes
+ * it, without `always`, so the bound does not depend on what an adapter encodes beyond the rule.
+ */
+export declare function userMetadataByteLength(userMetadata: Readonly<Record<string, string>>): number;
+type UserMetadataCheck = {
+  readonly held: Readonly<Record<string, string>>;
+} | {
+  readonly refusal: Refusal;
+};
+/**
+ * The user metadata as a storage holds it, keys folded to lower case as a header field name
+ * is, or the first refusal of spec 4.3, read off what the storage declares.
+ */
+export declare function checkUserMetadata(userMetadata: Record<string, string> | undefined, capabilities: readonly CapabilityName[]): UserMetadataCheck;
+/** A header value read back, with every form of encoded word RFC 2047 allows decoded. */
+export declare function decodeUserMetadataValue(value: string): string;
+//#endregion
+//#region src/xml.d.ts
+interface XmlElement {
+  readonly name: string;
+  readonly attributes: Readonly<Record<string, string>>;
+  readonly children: readonly XmlElement[];
+  /** The text directly inside the element, its children's left out. */
+  readonly text: string;
+}
+/** A document outside the subset `parseXml` reads, reported rather than read around (ADR 0003). */
+export declare class XmlSyntaxError extends Error {
+  override readonly name = "XmlSyntaxError";
+}
+/**
+ * The root element of an XML document of the subset the providers answer with: elements,
+ * attributes, text, comments, the five named entities and a numeric character reference to
+ * any Unicode scalar value but `U+0000`, under one optional declaration (spec 4.13).
+ */
+export declare function parseXml(document: string): XmlElement;
+//#endregion
+export type { ByteRange, CapabilityName, DeleteReport, GetOptions, KeyRule, ListOptions, ListPage, ObjectEntry, ObjectListing, ObjectStat, OperationOptions, PresignedPut, PutBody, PutOptions, Refusal, Resolvable, ResolverOptions, RetryOptions, SendParts, Storage, StorageErrorCode, StorageErrorFields, StoredObject, StreamUpload, StreamUploadOptions, UserMetadataCheck, UserMetadataKeyRule, XmlElement };

package/dist/index.js

@@ -8,16 +8,38 @@
 * - `presignedUrls`: the concrete type carries `presignGet` and `presignPut`. Where not
 *   declared, neither method exists on the type.
 * - `rangeReads`: `get` honors `range`. Where not declared, a `range` is `Unsupported`.
-* - `userMetadata`: `put` stores `userMetadata`, `stat` and `get` return it, `copy` keeps it.
-*   Where not declared, a non-empty `userMetadata` is `Unsupported` and reads return `{}`.
+* - `userMetadata`: `put` stores `userMetadata` whose keys are ASCII identifiers,
+*   `[A-Za-z_][A-Za-z0-9_]*`; `stat` and `get` return it, `copy` keeps it. Where not declared,
+*   a non-empty `userMetadata` is `Unsupported` and reads return `{}`.
+* - `userMetadataTokenKeys`: beside `userMetadata`, a key may be any ASCII HTTP token, such as
+*   `content-hash`. Where not declared, a key outside identifiers is `Unsupported` naming it;
+*   without `userMetadata` too, the call is `Unsupported` naming that.
 */
 const capabilityNames = [
 	"keyBytesPreserved",
 	"presignedUrls",
 	"rangeReads",
-	"userMetadata"
+	"userMetadata",
+	"userMetadataTokenKeys"
 ];
 //#endregion
+//#region src/environment.ts
+/**
+* ADR 0007: `process.env` is the one route through Node, Bun, Deno's compatibility layer
+* and a Worker under `nodejs_compat`. A Worker without it has no `process` at all, and
+* Deno without `--allow-env` throws `NotCapable` rather than answering `undefined`, so
+* both leave the value empty. A name is read on its own, because enumerating
+* `process.env` needs the unscoped permission in Deno.
+*/
+function readEnvironment(name) {
+	try {
+		if (typeof process === "undefined") return "";
+		return process?.env?.[name] ?? "";
+	} catch {
+		return "";
+	}
+}
+//#endregion
 //#region src/errors.ts
 const storageErrorBrand = Symbol.for("stowage.error");
 var StorageError = class extends Error {
@@ -92,16 +114,18 @@ function withAttempts(failure, attempts) {
 //#endregion
 //#region src/keys.ts
 const writableKeyLimit = 1024;
-const utf8 = new TextEncoder();
+const utf8$1 = new TextEncoder();
 /** The reason a key violates the rule, or `undefined` where it holds. */
 function invalidKeyReason(key, rule) {
 	if (key === "") return rule === "prefix" ? void 0 : "is empty";
 	const controlCharacter = firstControlCharacter(key);
 	if (controlCharacter !== void 0) return `holds the control character ${controlCharacter}`;
+	const loneSurrogate = firstLoneSurrogate(key);
+	if (loneSurrogate !== void 0) return `holds the lone surrogate ${loneSurrogate}`;
 	if (rule === "writable") {
 		if (key.includes("\\")) return "holds a backslash";
 		if (key.endsWith("/")) return "ends with a slash";
-		const bytes = utf8.encode(key).length;
+		const bytes = utf8$1.encode(key).length;
 		if (bytes > writableKeyLimit) return `is ${bytes} UTF-8 bytes, above the limit of ${writableKeyLimit}`;
 	}
 	return invalidSegmentReason(key);
@@ -109,9 +133,19 @@ function invalidKeyReason(key, rule) {
 function firstControlCharacter(key) {
 	for (let index = 0; index < key.length; index += 1) {
 		const code = key.charCodeAt(index);
-		if (code <= 31 || code === 127) return `U+${code.toString(16).toUpperCase().padStart(4, "0")}`;
+		if (code <= 31 || code === 127) return codePointName(code);
+	}
+}
+function firstLoneSurrogate(key) {
+	if (key.isWellFormed()) return void 0;
+	for (const character of key) {
+		const code = character.codePointAt(0) ?? 0;
+		if (code >= 55296 && code <= 57343) return codePointName(code);
 	}
 }
+function codePointName(code) {
+	return `U+${code.toString(16).toUpperCase().padStart(4, "0")}`;
+}
 function invalidSegmentReason(key) {
 	const segments = key.split("/");
 	for (const [index, segment] of segments.entries()) {
@@ -122,6 +156,59 @@ function invalidSegmentReason(key) {
 	}
 }
 //#endregion
+//#region src/range.ts
+const invalidBounds = {
+	code: "InvalidOption",
+	message: "The option `range` takes two whole numbers from zero up, `start` at most `end`"
+};
+/** Refuses bounds spec 4.3 does not allow, which is decided before the object is looked up. */
+function rangeBoundsRefusal(range) {
+	if (range === void 0) return void 0;
+	const { start, end } = range;
+	if (!isOffset(start) || end !== void 0 && (!isOffset(end) || end < start)) return invalidBounds;
+}
+/**
+* Refuses a range that starts at or beyond the object's `size` bytes, which spec 4.3 names a
+* refusal of the request rather than of the option, because a provider answers it with `416`.
+*/
+function rangeStartRefusal(range, size, key) {
+	if (range.start < size) return void 0;
+	return {
+		code: "InvalidRequest",
+		message: `The range starts beyond the ${size} bytes under the key ${JSON.stringify(key)}`
+	};
+}
+/** The last byte the range names, both ends inclusive, clipped to the object's `size` bytes. */
+function lastByteOf(range, size) {
+	return Math.min(range?.end ?? size - 1, size - 1);
+}
+/**
+* Whether the whole object is the body the range asks for, clipped as spec 4.3 clips it. A
+* provider may answer a range with the whole object and `200`, which RFC 9110 allows, and
+* that answer is the one asked for exactly where this holds. An empty object holds no byte a
+* range could start at, so no range covers it.
+*/
+function rangeCoversWhole(range, size) {
+	return range.start === 0 && size > 0 && lastByteOf(range, size) === size - 1;
+}
+/** The `Range` field of RFC 9110, both ends inclusive as `ByteRange` is. */
+function rangeHeader(range) {
+	return `bytes=${range.start}-${range.end ?? ""}`;
+}
+const contentRangePattern = /^bytes (\d+)-(\d+)\/(\d+)$/u;
+/**
+* The size of the whole object out of a `206`'s `Content-Range`, which is what spec 4.4 has a
+* ranged `get` report rather than the length of the range.
+*/
+function wholeSizeOf(contentRange) {
+	const found = contentRangePattern.exec(contentRange?.trim() ?? "");
+	const size = Number(found?.[3]);
+	return Number.isSafeInteger(size) ? size : void 0;
+}
+function isOffset(value) {
+	return Number.isInteger(value) && value >= 0;
+}
+//#endregion
 //#region src/retry.ts
 const baseDelay = 100;
 const maximumDelay = 5e3;
@@ -188,4 +275,558 @@ function isTransientStatus(status) {
 	return status === 408 || status === 429 || status >= 500 && status <= 599;
 }
 //#endregion
-export { StorageError, capabilityNames, errorCodeForStatus, invalidKeyReason, isStorageError, isTransientStatus, withRetry };
+//#region src/part-reader.ts
+/** Where a buffer starts before the stream has shown whether it fills a part. */
+const initialCapacity = 65536;
+/**
+* A stream read into parts of one size (spec 4.13). A part is known to be the last only
+* once the stream has ended behind it, so a full part looks one chunk ahead; that chunk
+* is the stream's own and becomes the start of the next part.
+*
+* A part handed back through `recycle` lends its buffer to a later one. ADR 0016 bounds
+* an upload at `partSize × concurrency` of buffers, and a fresh buffer per part would
+* keep the settled ones alive until the collector noticed them.
+*
+* Until a part has filled, the buffer grows by doubling, because ADR 0009 has a body
+* shorter than a part allocate only what it needs. Once one has, the stream is known to
+* go as a multipart upload, and every buffer after it starts at the full part size.
+*/
+var PartReader = class {
+	#reader;
+	#partSize;
+	#signal;
+	#cancelOnAbort = () => {
+		this.#reader.cancel(this.#signal?.reason).catch(() => {});
+	};
+	#free = [];
+	#ahead;
+	#filledOnce = false;
+	constructor(stream, partSize, signal) {
+		this.#reader = stream.getReader();
+		this.#partSize = partSize;
+		this.#signal = signal;
+		signal?.addEventListener("abort", this.#cancelOnAbort, { once: true });
+	}
+	async next() {
+		let bytes = this.#freshBuffer();
+		let filled = 0;
+		while (filled < this.#partSize) {
+			const chunk = this.#ahead ?? await this.#read();
+			this.#ahead = void 0;
+			if (chunk === void 0) return {
+				bytes: bytes.subarray(0, filled),
+				last: true
+			};
+			const taken = Math.min(chunk.byteLength, this.#partSize - filled);
+			if (filled + taken > bytes.byteLength) bytes = this.#grown(bytes, filled + taken);
+			bytes.set(chunk.subarray(0, taken), filled);
+			filled += taken;
+			if (taken < chunk.byteLength) this.#ahead = chunk.subarray(taken);
+		}
+		this.#filledOnce = true;
+		this.#ahead ??= await this.#read();
+		return {
+			bytes,
+			last: this.#ahead === void 0
+		};
+	}
+	/** The part's request settled, so nothing reads its bytes any more. */
+	recycle(part) {
+		if (part.bytes.buffer.byteLength === this.#partSize) this.#free.push(part.bytes.buffer);
+	}
+	/** Spec 4.2 leaves the stream canceled where `put` rejects before reading it to its end. */
+	async cancel(reason) {
+		await this.#reader.cancel(reason).catch(() => {});
+	}
+	release() {
+		this.#signal?.removeEventListener("abort", this.#cancelOnAbort);
+		this.#reader.releaseLock();
+	}
+	#freshBuffer() {
+		const pooled = this.#free.pop();
+		if (pooled !== void 0) return new Uint8Array(pooled);
+		return new Uint8Array(this.#filledOnce ? this.#partSize : Math.min(this.#partSize, initialCapacity));
+	}
+	#grown(bytes, needed) {
+		let capacity = bytes.byteLength;
+		while (capacity < needed) capacity *= 2;
+		const larger = new Uint8Array(Math.min(capacity, this.#partSize));
+		larger.set(bytes);
+		return larger;
+	}
+	async #read() {
+		for (;;) {
+			const { done, value } = await this.#reader.read();
+			this.#signal?.throwIfAborted();
+			if (done) return void 0;
+			if (value.byteLength > 0) return value;
+		}
+	}
+};
+//#endregion
+//#region src/upload-stream.ts
+/**
+* Reads the stream into parts of `partSize` and hands a stream that ends within the first
+* to `whole`, any other to `multipart`. The reader, its buffers and the cancellation of
+* the source stay here, so the spec promises one call rather than the order of five
+* (ADR 0030).
+*
+* The source is canceled wherever the upload settles before the stream ended, as spec 4.2
+* has it for a `put` that rejects before reading its body to the end.
+*/
+async function uploadStream(stream, options, upload) {
+	const parts = new PartReader(stream, options.partSize, options.signal);
+	const uploadSettled = new AbortController();
+	let readToEnd = false;
+	let cancelReason = /* @__PURE__ */ new Error("The upload settled before the stream ended");
+	try {
+		const first = await parts.next();
+		if (first.last) {
+			readToEnd = true;
+			return await upload.whole(first.bytes);
+		}
+		let called = false;
+		const sendParts = async (send) => {
+			uploadSettled.signal.throwIfAborted();
+			if (called) throw new Error("`sendParts` sends the parts of one upload once");
+			called = true;
+			const sent = await sendAll(parts, first, options, uploadSettled.signal, send);
+			readToEnd = true;
+			return sent;
+		};
+		return await upload.multipart(sendParts);
+	} catch (failure) {
+		cancelReason = failure;
+		throw failure;
+	} finally {
+		uploadSettled.abort(cancelReason);
+		if (!readToEnd) await parts.cancel(cancelReason);
+		parts.release();
+	}
+}
+/**
+* `concurrency` parts in flight, and the next part read only once one of them settled,
+* so the part buffers never outnumber the parts in flight (ADR 0016). The first failure
+* stops the parts still in flight, and is what `sendParts` rejects with once they settled.
+*/
+async function sendAll(parts, first, options, uploadSettled, send) {
+	const stop = new AbortController();
+	const partSignal = options.signal === void 0 ? stop.signal : AbortSignal.any([options.signal, stop.signal]);
+	const inFlight = /* @__PURE__ */ new Set();
+	const results = [];
+	let failure;
+	let size = 0;
+	const fail = (reason) => {
+		failure ??= { reason };
+		stop.abort();
+		parts.cancel(reason);
+	};
+	const sendPart = async (index, part) => {
+		try {
+			results[index] = await send(index, part.bytes, partSignal);
+		} catch (reason) {
+			fail(reason);
+		} finally {
+			parts.recycle(part);
+		}
+	};
+	const stopWithUpload = () => {
+		fail(uploadSettled.reason);
+	};
+	uploadSettled.addEventListener("abort", stopWithUpload, { once: true });
+	try {
+		for (let index = 0, part = first; !stop.signal.aborted; index += 1) {
+			if (index === options.maxParts - 1 && !part.last) throw tooManyParts(options);
+			const sending = sendPart(index, part);
+			inFlight.add(sending);
+			sending.finally(() => inFlight.delete(sending));
+			size += part.bytes.byteLength;
+			if (part.last) break;
+			while (inFlight.size >= options.concurrency) await Promise.race(inFlight);
+			part = await parts.next();
+		}
+	} catch (reason) {
+		fail(reason);
+	}
+	await Promise.all(inFlight);
+	uploadSettled.removeEventListener("abort", stopWithUpload);
+	if (failure !== void 0) {
+		await parts.cancel(failure.reason);
+		throw failure.reason;
+	}
+	return {
+		results,
+		size
+	};
+}
+/**
+* Known once the last part the provider takes is full and the stream goes on. ADR 0016
+* fixes the part size before the first part, so the way past it is a larger one.
+*/
+function tooManyParts(options) {
+	return new StorageError({
+		code: "InvalidRequest",
+		message: `The stream needs more than ${options.maxParts} parts of the configured \`partSize\` of ${options.partSize} bytes; a larger \`multipart.partSize\` carries it`,
+		operation: "put",
+		bucket: options.bucket,
+		provider: options.provider,
+		key: options.key,
+		attempts: 0
+	});
+}
+//#endregion
+//#region src/user-metadata.ts
+const keyPatterns = {
+	/** The characters RFC 9110 allows in a field name, which is what a header carries. */
+	token: /^[!#$%&'*+.^_`|~\dA-Za-z-]+$/u,
+	/** An ASCII identifier, which Azure requires of a metadata name (ADR 0020). */
+	identifier: /^[A-Za-z_][A-Za-z\d_]*$/u
+};
+function isUserMetadataKey(name, rule) {
+	return keyPatterns[rule].test(name);
+}
+/**
+* What survives a header field as it stands: printable ASCII with no space at either end,
+* which HTTP trims, and no `=?`, which the reader would take for the start of an encoded
+* word.
+*/
+const travelsAsWritten = /^(?:[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?)?$/u;
+const encodedWordStart = "=?UTF-8?B?";
+const encodedWordEnd = "?=";
+/**
+* RFC 2047 bounds an encoded word at 75 characters; 45 bytes are 60 characters of base64,
+* which leaves room for the 12 the word's frame costs.
+*/
+const bytesPerEncodedWord = 45;
+const utf8 = new TextEncoder();
+/** The value as a header carries it: as written where it travels so, else as encoded words. */
+function encodeUserMetadataValue(value, options) {
+	if (value === "") return value;
+	if (options?.always !== true && travelsAsWritten.test(value) && !value.includes("=?")) return value;
+	return utf8PiecesOf(value).map((piece) => `${encodedWordStart}${btoa(String.fromCharCode(...piece))}${encodedWordEnd}`).join(" ");
+}
+/**
+* What spec 4.3 bounds at 2 KB: every key and its value as `encodeUserMetadataValue` writes
+* it, without `always`, so the bound does not depend on what an adapter encodes beyond the rule.
+*/
+function userMetadataByteLength(userMetadata) {
+	let bytes = 0;
+	for (const [name, value] of Object.entries(userMetadata)) bytes += utf8.encode(name).length + encodeUserMetadataValue(value).length;
+	return bytes;
+}
+/** Spec 4.3 bounds the set at 2 KB of the header bytes it costs once it is encoded. */
+const headerByteLimit = 2048;
+const noUserMetadata = { held: Object.freeze(Object.create(null)) };
+/**
+* The user metadata as a storage holds it, keys folded to lower case as a header field name
+* is, or the first refusal of spec 4.3, read off what the storage declares.
+*/
+function checkUserMetadata(userMetadata, capabilities) {
+	const entries = Object.entries(userMetadata ?? {});
+	if (entries.length === 0) return noUserMetadata;
+	if (!capabilities.includes("userMetadata")) return unsupported("userMetadata", "This storage holds no user metadata");
+	const held = Object.create(null);
+	for (const [name, value] of entries) {
+		if (!isUserMetadataKey(name, "token")) return refused(`The user metadata key ${JSON.stringify(name)} is no ASCII HTTP token`);
+		const folded = name.toLowerCase();
+		if (folded in held) return refused(`The user metadata key ${JSON.stringify(folded)} is given more than once`);
+		held[folded] = value;
+	}
+	const malformed = Object.entries(held).find(([, value]) => !value.isWellFormed());
+	if (malformed !== void 0) return refused(`The user metadata value of ${JSON.stringify(malformed[0])} holds a lone surrogate, which has no UTF-8 form`);
+	const headerBytes = userMetadataByteLength(held);
+	if (headerBytes > headerByteLimit) return refused(`The user metadata is ${headerBytes} encoded header bytes, above the limit of ${headerByteLimit}`);
+	const beyondIdentifiers = entries.find(([name]) => !isUserMetadataKey(name, "identifier"));
+	if (beyondIdentifiers !== void 0 && !capabilities.includes("userMetadataTokenKeys")) return unsupported("userMetadataTokenKeys", `This storage holds no user metadata key beyond identifiers, such as ${JSON.stringify(beyondIdentifiers[0])}`);
+	return { held: Object.freeze(held) };
+}
+function refused(message) {
+	return { refusal: {
+		code: "InvalidRequest",
+		message
+	} };
+}
+function unsupported(capability, message) {
+	return { refusal: {
+		code: "Unsupported",
+		message,
+		capability
+	} };
+}
+/** The UTF-8 bytes in pieces of at most one encoded word, each ending on a character. */
+function utf8PiecesOf(value) {
+	const pieces = [];
+	let pending = [];
+	for (const character of value) {
+		const bytes = utf8.encode(character);
+		if (pending.length + bytes.length > bytesPerEncodedWord) {
+			pieces.push(Uint8Array.from(pending));
+			pending = [];
+		}
+		pending.push(...bytes);
+	}
+	pieces.push(Uint8Array.from(pending));
+	return pieces;
+}
+const encodedWord = /=\?([^?\s]+)\?([BbQq])\?([^?\s]*)\?=/gu;
+const whitespaceOnly = /^[ \t]+$/u;
+const hexPair = /^[\dA-Fa-f]{2}$/u;
+/** A header value read back, with every form of encoded word RFC 2047 allows decoded. */
+function decodeUserMetadataValue(value) {
+	let decoded = "";
+	let last = 0;
+	let previousWasEncoded = false;
+	for (const match of value.matchAll(encodedWord)) {
+		const between = value.slice(last, match.index);
+		const word = decodeWord(match[1] ?? "", match[2] ?? "", match[3] ?? "");
+		if (!(previousWasEncoded && word !== void 0 && whitespaceOnly.test(between))) decoded += between;
+		decoded += word ?? match[0];
+		previousWasEncoded = word !== void 0;
+		last = match.index + match[0].length;
+	}
+	return decoded + value.slice(last);
+}
+/** The text of one encoded word, or `undefined` where it names what cannot be read. */
+function decodeWord(charset, encoding, text) {
+	const bytes = encoding.toUpperCase() === "B" ? base64Bytes(text) : quotedBytes(text);
+	if (bytes === void 0) return void 0;
+	try {
+		return new TextDecoder(charset, { fatal: true }).decode(bytes);
+	} catch {
+		return;
+	}
+}
+function base64Bytes(text) {
+	try {
+		return Uint8Array.from(atob(text), (character) => character.charCodeAt(0));
+	} catch {
+		return;
+	}
+}
+/** The `Q` encoding: `_` is a space and `=XX` one byte in hex. */
+function quotedBytes(text) {
+	const bytes = [];
+	for (let index = 0; index < text.length; index += 1) {
+		const character = text[index];
+		if (character === "_") bytes.push(32);
+		else if (character === "=") {
+			const pair = text.slice(index + 1, index + 3);
+			if (!hexPair.test(pair)) return void 0;
+			bytes.push(Number.parseInt(pair, 16));
+			index += 2;
+		} else bytes.push(text.charCodeAt(index));
+	}
+	return Uint8Array.from(bytes);
+}
+//#endregion
+//#region src/xml.ts
+/** A document outside the subset `parseXml` reads, reported rather than read around (ADR 0003). */
+var XmlSyntaxError = class extends Error {
+	name = "XmlSyntaxError";
+};
+/**
+* The root element of an XML document of the subset the providers answer with: elements,
+* attributes, text, comments, the five named entities and a numeric character reference to
+* any Unicode scalar value but `U+0000`, under one optional declaration (spec 4.13).
+*/
+function parseXml(document) {
+	const scanner = new Scanner(document);
+	scanner.skipDeclaration();
+	scanner.skipMisc();
+	const root = scanner.readElement();
+	scanner.skipMisc();
+	scanner.requireEnd();
+	return root;
+}
+const namePattern = /[:A-Z_a-z\u00C0-\uFFFF][:A-Z_a-z\u00C0-\uFFFF.\d-]*/uy;
+const whitespacePattern = /[ \t\r\n]*/y;
+const entityPattern = /&(?:#x([\da-fA-F]+)|#(\d+)|([A-Za-z]\w*));/uy;
+/**
+* What a character reference may name: any Unicode scalar value but `U+0000`. That is
+* wider than `Char` of XML 1.0 on purpose, because S3 writes a key character XML cannot
+* carry, such as `U+FFFE`, as a reference, and the key has to read back byte for byte
+* (ADR 0027).
+*/
+function isReferableCharacter(codePoint) {
+	return codePoint >= 1 && codePoint <= 55295 || codePoint >= 57344 && codePoint <= 1114111;
+}
+/** The five entities XML defines without a DTD, which is every one a document here has. */
+const predefinedEntities = /* @__PURE__ */ new Map([
+	["amp", "&"],
+	["lt", "<"],
+	["gt", ">"],
+	["quot", "\""],
+	["apos", "'"]
+]);
+var Scanner = class {
+	#document;
+	#position = 0;
+	constructor(document) {
+		this.#document = document;
+	}
+	skipDeclaration() {
+		if (!this.#startsWith("<?xml")) return;
+		this.#position = this.#positionPast("?>", "The XML declaration is never closed");
+	}
+	/** Whitespace and comments, which are all that may stand beside the root element. */
+	skipMisc() {
+		for (;;) {
+			this.#skipWhitespace();
+			if (this.#startsWith("<!DOCTYPE")) throw this.#error("A DTD is refused");
+			if (!this.#startsWith("<!--")) return;
+			this.#skipComment();
+		}
+	}
+	requireEnd() {
+		if (this.#position < this.#document.length) throw this.#error("Something follows the root element");
+	}
+	readElement() {
+		this.#expect("<");
+		const name = this.#readName();
+		const attributes = Object.create(null);
+		if (this.#readStartTagEnd(attributes) === "empty") return {
+			name,
+			attributes,
+			children: [],
+			text: ""
+		};
+		const children = [];
+		let text = "";
+		for (;;) {
+			if (this.#position >= this.#document.length) throw this.#error(`The element <${name}> is never closed`);
+			if (this.#startsWith("</")) {
+				this.#position += 2;
+				this.#closeElement(name);
+				return {
+					name,
+					attributes,
+					children,
+					text
+				};
+			}
+			if (this.#startsWith("<!--")) this.#skipComment();
+			else if (this.#startsWith("<![CDATA[")) throw this.#error("A CDATA section is refused");
+			else if (this.#startsWith("<")) children.push(this.readElement());
+			else text += this.#readText();
+		}
+	}
+	#closeElement(name) {
+		const closing = this.#readName();
+		if (closing !== name) throw this.#error(`The element <${name}> is closed by </${closing}>`);
+		this.#skipWhitespace();
+		this.#expect(">");
+	}
+	#readStartTagEnd(attributes) {
+		for (;;) {
+			const before = this.#position;
+			this.#skipWhitespace();
+			if (this.#startsWith("/>")) {
+				this.#position += 2;
+				return "empty";
+			}
+			if (this.#startsWith(">")) {
+				this.#position += 1;
+				return "open";
+			}
+			if (this.#position === before) throw this.#error("An attribute follows no whitespace");
+			const attribute = this.#readName();
+			if (attribute in attributes) throw this.#error(`The attribute ${attribute} is given twice`);
+			this.#skipWhitespace();
+			this.#expect("=");
+			this.#skipWhitespace();
+			attributes[attribute] = this.#readAttributeValue();
+		}
+	}
+	/**
+	* XML 1.0, section 3.3.3: without a DTD every attribute is CDATA, so each whitespace
+	* character written into the value reads as a space, and a line break as one space. A
+	* reference to one stays the character it names.
+	*/
+	#readAttributeValue() {
+		const quote = this.#document[this.#position];
+		if (quote !== "\"" && quote !== "'") throw this.#error("An attribute value is not quoted");
+		this.#position += 1;
+		let value = "";
+		for (;;) {
+			const character = this.#document[this.#position];
+			if (character === void 0) throw this.#error("An attribute value is never closed");
+			if (character === quote) {
+				this.#position += 1;
+				return value;
+			}
+			if (character === "<") throw this.#error("A `<` stands inside an attribute value");
+			if (character === "&") {
+				value += this.#readEntity();
+				continue;
+			}
+			this.#position += this.#startsWith("\r\n") ? 2 : 1;
+			value += character === "	" || character === "\n" || character === "\r" ? " " : character;
+		}
+	}
+	/** Text up to the next markup, every `&` in it the start of an entity it decodes. */
+	#readText() {
+		const markup = this.#document.indexOf("<", this.#position);
+		const end = markup === -1 ? this.#document.length : markup;
+		let text = "";
+		while (this.#position < end) {
+			const ampersand = this.#document.indexOf("&", this.#position);
+			if (ampersand === -1 || ampersand >= end) {
+				text += this.#document.slice(this.#position, end);
+				this.#position = end;
+				break;
+			}
+			text += this.#document.slice(this.#position, ampersand);
+			this.#position = ampersand;
+			text += this.#readEntity();
+		}
+		return text;
+	}
+	#readEntity() {
+		entityPattern.lastIndex = this.#position;
+		const found = entityPattern.exec(this.#document);
+		if (found === null) throw this.#error("An `&` starts no entity");
+		const [entity, hex, decimal, name] = found;
+		if (name !== void 0) {
+			const character = predefinedEntities.get(name);
+			if (character === void 0) throw this.#error(`The entity ${entity} is not defined`);
+			this.#position = entityPattern.lastIndex;
+			return character;
+		}
+		const codePoint = hex === void 0 ? Number(decimal) : Number.parseInt(hex, 16);
+		if (!isReferableCharacter(codePoint)) throw this.#error(`The reference ${entity} names U+0000, a surrogate or no Unicode scalar value at all`);
+		this.#position = entityPattern.lastIndex;
+		return String.fromCodePoint(codePoint);
+	}
+	#skipComment() {
+		this.#position = this.#positionPast("-->", "A comment is never closed", 4);
+	}
+	#readName() {
+		namePattern.lastIndex = this.#position;
+		const found = namePattern.exec(this.#document);
+		if (found === null) throw this.#error("A name is missing where one belongs");
+		this.#position = namePattern.lastIndex;
+		return found[0];
+	}
+	#skipWhitespace() {
+		whitespacePattern.lastIndex = this.#position;
+		whitespacePattern.exec(this.#document);
+		this.#position = whitespacePattern.lastIndex;
+	}
+	#expect(literal) {
+		if (!this.#startsWith(literal)) throw this.#error(`\`${literal}\` is missing`);
+		this.#position += literal.length;
+	}
+	#positionPast(terminator, unterminated, offset = 0) {
+		const end = this.#document.indexOf(terminator, this.#position + offset);
+		if (end === -1) throw this.#error(unterminated);
+		return end + terminator.length;
+	}
+	#startsWith(literal) {
+		return this.#document.startsWith(literal, this.#position);
+	}
+	#error(message) {
+		return new XmlSyntaxError(`${message} (at character ${this.#position})`);
+	}
+};
+//#endregion
+export { StorageError, XmlSyntaxError, capabilityNames, checkUserMetadata, decodeUserMetadataValue, encodeUserMetadataValue, errorCodeForStatus, invalidKeyReason, isStorageError, isTransientStatus, isUserMetadataKey, lastByteOf, parseXml, rangeBoundsRefusal, rangeCoversWhole, rangeHeader, rangeStartRefusal, readEnvironment, uploadStream, userMetadataByteLength, wholeSizeOf, withRetry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stowage/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "One typed API for object storage: the types every stowage adapter implements, StorageError, and the utilities an adapter calls.",
   "keywords": [
     "adapter",