@stowage/core 0.0.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Kaufmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# @stowage/core
+
+The types every stowage adapter implements, `StorageError`, and the utilities an adapter calls. It
+does nothing without an adapter.
+
+## Install
+
+```sh
+npm install @stowage/core
+```
+
+## Example
+
+A function written against `Storage` runs against every adapter: `memoryStorage()` in a test,
+`fsStorage()` on a laptop, `s3Storage()` or `azureBlobStorage()` in production.
+
+```ts
+import { isStorageError, type Storage } from "@stowage/core";
+
+export async function readSettings(storage: Storage): Promise<unknown> {
+  try {
+    const object = await storage.get("settings.json");
+
+    return await object.json();
+  } catch (failure) {
+    if (isStorageError(failure) && failure.code === "NotFound") return {};
+
+    throw failure;
+  }
+}
+```
+
+## Runtimes
+
+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 3.3 kB minified and gzipped.
+
+## Limits
+
+This section is empty. `@stowage/core` declares no capability; each storage declares its own, out
+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.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 10](https://github.com/stowage-js/stowage/blob/@stowage/core@0.2.0/docs/spec.md#10-versions)).
+
+```ts
+import { isStorageError } from "@stowage/core";
+
+export function describeFailure(failure: unknown): string {
+  if (failure instanceof Error && failure.name === "AbortError") return "canceled";
+  if (!isStorageError(failure)) throw failure;
+
+  switch (failure.code) {
+    case "NotFound":
+      return "missing";
+    case "AccessDenied":
+    case "InvalidCredentials":
+    case "Expired":
+      return "refused";
+    default:
+      return failure.retryable ? "try again" : "failed";
+  }
+}
+```
+
+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.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.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
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,348 @@
+//#region src/capabilities.d.ts
+/**
+ * Every capability a storage can declare (spec 4.9). The list grows in minor releases, so a
+ * `switch` over it needs a default branch.
+ *
+ * - `keyBytesPreserved`: a key comes back byte for byte as it was written. Where not
+ *   declared, it comes back Unicode-equivalent.
+ * - `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` 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", "userMetadataTokenKeys"];
+/** One name out of {@link capabilityNames}. */
+type CapabilityName = (typeof capabilityNames)[number];
+//#endregion
+//#region src/credentials.d.ts
+/** What a resolver is told when the adapter asks for a credential again (spec 4.12). */
+type ResolverOptions = {
+  forceRefresh: boolean;
+};
+/** 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
+ * minor release, so a `switch` over it needs a default branch.
+ *
+ * - `NotFound`: no object under the key, or no bucket; `stat` cannot tell the two apart.
+ * - `AccessDenied`: the credential is valid and may not do this.
+ * - `InvalidCredentials`: the provider does not accept the credential, or a required
+ *   credential field is empty or unknown.
+ * - `Expired`: the credential or session token has expired.
+ * - `InvalidRequest`: the provider or stowage refused the request for what it asked, such as
+ *   metadata over the limit, an unsatisfiable range, a copy onto itself or a second read of a
+ *   body.
+ * - `NetworkError`: the request received no response.
+ * - `ProviderError`: the provider answered with a failure stowage has no other name for;
+ *   `providerCode` carries its string.
+ * - `InvalidKey`: the key violates the key rule, or a rule the adapter adds to it.
+ * - `InvalidOption`: an option or configuration value stowage refused, such as an unknown key,
+ *   a value out of range or a cursor it did not produce.
+ * - `Unsupported`: the call needs a capability the storage does not declare; `capability`
+ *   names it.
+ */
+type StorageErrorCode = "NotFound" | "AccessDenied" | "InvalidCredentials" | "Expired" | "InvalidRequest" | "NetworkError" | "ProviderError" | "InvalidKey" | "InvalidOption" | "Unsupported";
+interface StorageErrorFields {
+  readonly code: StorageErrorCode;
+  readonly message: string;
+  readonly operation: string;
+  readonly bucket: string;
+  readonly provider: string;
+  readonly attempts: number;
+  readonly key?: string;
+  readonly status?: number;
+  readonly providerCode?: string;
+  readonly requestId?: string;
+  readonly retryable?: boolean;
+  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;
+  readonly bucket: string;
+  readonly provider: string;
+  /**
+   * How often the failing step was attempted: `0` where stowage refused before the first
+   * attempt, `1` where a single attempt failed, more where the adapter repeated it.
+   */
+  readonly attempts: number;
+  /** The condition is transient. It says nothing about whether stowage sent the request again. */
+  readonly retryable: boolean;
+  readonly key?: string;
+  readonly status?: number;
+  readonly providerCode?: string;
+  readonly requestId?: string;
+  /** The capability an `Unsupported` failure needs, and set for no other code. */
+  readonly capability?: CapabilityName;
+  constructor(fields: StorageErrorFields);
+}
+export declare function isStorageError(value: unknown): value is StorageError;
+//#endregion
+//#region src/keys.d.ts
+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/presigned-put.d.ts
+/**
+ * What `presignPut` resolves with on every adapter that declares `presignedUrls`, so the code
+ * that uploads through it never names the provider (ADR 0022).
+ */
+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>;
+interface OperationOptions {
+  signal?: AbortSignal;
+}
+interface PutOptions extends OperationOptions {
+  contentType?: string;
+  /**
+   * 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`. A key outside ASCII identifiers, such as `content-hash`, is
+   * `Unsupported` where the storage does not declare `userMetadataTokenKeys`.
+   */
+  userMetadata?: Record<string, string>;
+}
+/** Both ends inclusive; `end` absent means to the end of the object. */
+interface ByteRange {
+  /**
+   * A non-negative integer no greater than `end`, else `InvalidOption`. At or beyond the
+   * object's size it is `InvalidRequest`.
+   */
+  start: number;
+  /** A non-negative integer, else `InvalidOption`. Beyond the object's size it is clipped. */
+  end?: number;
+}
+interface GetOptions extends OperationOptions {
+  range?: ByteRange;
+}
+interface ListOptions extends OperationOptions {
+  prefix?: string;
+  /** One or more characters; an empty string is `InvalidOption`. */
+  delimiter?: string;
+  /** 1 to 1000, and 1000 where absent. Outside that range it is `InvalidOption`. */
+  pageSize?: number;
+  /**
+   * The `cursor` of a page this storage produced, which a new listing in another process may
+   * continue from. Any other string is `InvalidOption`.
+   */
+  cursor?: string;
+}
+interface ObjectEntry {
+  readonly key: string;
+  readonly size: number;
+  readonly lastModified: Date;
+  readonly etag?: string;
+}
+interface ObjectStat extends ObjectEntry {
+  readonly contentType: string;
+  readonly userMetadata: Readonly<Record<string, string>>;
+}
+interface StoredObject {
+  readonly stat: ObjectStat;
+  stream(): ReadableStream<Uint8Array>;
+  bytes(): Promise<Uint8Array>;
+  text(): Promise<string>;
+  json<T = unknown>(): Promise<T>;
+}
+interface ListPage {
+  readonly objects: readonly ObjectEntry[];
+  readonly prefixes: readonly string[];
+  readonly cursor?: string;
+}
+interface ObjectListing extends AsyncIterable<ObjectEntry> {
+  page(): Promise<ListPage>;
+}
+interface DeleteReport {
+  readonly requested: number;
+  readonly failed: readonly StorageError[];
+}
+interface Storage {
+  readonly provider: string;
+  readonly bucket: string;
+  /** Every capability the storage implements, each once, fixed when it was constructed. */
+  readonly capabilities: readonly CapabilityName[];
+  put(key: string, body: PutBody, options?: PutOptions): Promise<ObjectStat>;
+  get(key: string, options?: GetOptions): Promise<StoredObject>;
+  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
+//#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

@@ -0,0 +1,832 @@
+//#region src/capabilities.ts
+/**
+* Every capability a storage can declare (spec 4.9). The list grows in minor releases, so a
+* `switch` over it needs a default branch.
+*
+* - `keyBytesPreserved`: a key comes back byte for byte as it was written. Where not
+*   declared, it comes back Unicode-equivalent.
+* - `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` 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",
+	"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 {
+	code;
+	operation;
+	bucket;
+	provider;
+	/**
+	* How often the failing step was attempted: `0` where stowage refused before the first
+	* attempt, `1` where a single attempt failed, more where the adapter repeated it.
+	*/
+	attempts;
+	/** The condition is transient. It says nothing about whether stowage sent the request again. */
+	retryable;
+	key;
+	status;
+	providerCode;
+	requestId;
+	/** The capability an `Unsupported` failure needs, and set for no other code. */
+	capability;
+	constructor(fields) {
+		super(fields.message);
+		if (fields.code === "Unsupported" && fields.capability === void 0) throw new TypeError("An `Unsupported` storage error names the capability it needs");
+		this.name = "StorageError";
+		this.code = fields.code;
+		this.operation = fields.operation;
+		this.bucket = fields.bucket;
+		this.provider = fields.provider;
+		this.attempts = fields.attempts;
+		this.retryable = fields.retryable ?? false;
+		this.key = fields.key;
+		this.status = fields.status;
+		this.providerCode = fields.providerCode;
+		this.requestId = fields.requestId;
+		this.capability = fields.capability;
+		if (fields.cause !== void 0) this.cause = fields.cause;
+		Object.defineProperty(this, storageErrorBrand, { value: true });
+	}
+};
+function isStorageError(value) {
+	return typeof value === "object" && value !== null && storageErrorBrand in value;
+}
+/**
+* The same failure counting the attempts a whole retry loop made rather than the one it
+* was raised in. It lives beside the field list, because every field has to be named
+* again here or it is dropped on the way through; the stack travels along, because it
+* points at where the request failed and this is no other place it could have failed.
+*
+* Not published: spec 4.13 lists what an adapter calls, and `withRetry` is the one
+* caller this has.
+*/
+function withAttempts(failure, attempts) {
+	if (failure.attempts === attempts) return failure;
+	const counted = new StorageError({
+		code: failure.code,
+		message: failure.message,
+		operation: failure.operation,
+		bucket: failure.bucket,
+		provider: failure.provider,
+		attempts,
+		key: failure.key,
+		status: failure.status,
+		providerCode: failure.providerCode,
+		requestId: failure.requestId,
+		retryable: failure.retryable,
+		capability: failure.capability,
+		cause: failure.cause
+	});
+	counted.stack = failure.stack;
+	return counted;
+}
+//#endregion
+//#region src/keys.ts
+const writableKeyLimit = 1024;
+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$1.encode(key).length;
+		if (bytes > writableKeyLimit) return `is ${bytes} UTF-8 bytes, above the limit of ${writableKeyLimit}`;
+	}
+	return invalidSegmentReason(key);
+}
+function firstControlCharacter(key) {
+	for (let index = 0; index < key.length; index += 1) {
+		const code = key.charCodeAt(index);
+		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()) {
+		if (segment === "." || segment === "..") return `holds ${JSON.stringify(segment)} as a segment`;
+		if (segment !== "") continue;
+		if (index === 0) return "starts with a slash";
+		if (index < segments.length - 1) return "holds an empty segment";
+	}
+}
+//#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;
+/**
+* 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.
+*/
+async function withRetry(attempt, options) {
+	let requestsSent = 0;
+	for (let attemptsMade = 1;; attemptsMade += 1) try {
+		return await attempt();
+	} catch (failure) {
+		requestsSent += costOf(failure);
+		if (!isStorageError(failure)) throw failure;
+		if (!failure.retryable || attemptsMade >= options.maxAttempts) throw withAttempts(failure, requestsSent);
+		await waitBefore(attemptsMade, options.signal);
+	}
+}
+function costOf(failure) {
+	return isStorageError(failure) ? failure.attempts : 1;
+}
+/** Full jitter (ADR 0013), interrupted by the signal that is the caller's whole budget. */
+async function waitBefore(attemptsMade, signal) {
+	const milliseconds = Math.random() * Math.min(maximumDelay, baseDelay * 2 ** attemptsMade);
+	await new Promise((resolve, reject) => {
+		if (signal === void 0) {
+			setTimeout(resolve, milliseconds);
+			return;
+		}
+		signal.throwIfAborted();
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", aborted);
+			resolve();
+		}, milliseconds);
+		const aborted = () => {
+			clearTimeout(timer);
+			reject(signal.reason);
+		};
+		signal.addEventListener("abort", aborted, { once: true });
+	});
+}
+//#endregion
+//#region src/status.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.
+*/
+function errorCodeForStatus(status) {
+	if (status >= 200 && status <= 299) return void 0;
+	if (status === 401) return "InvalidCredentials";
+	if (status === 403) return "AccessDenied";
+	if (status === 404) return "NotFound";
+	return "ProviderError";
+}
+/** Whether the status names a condition that may be gone a moment later (spec 4.10). */
+function isTransientStatus(status) {
+	return status === 408 || status === 429 || status >= 500 && status <= 599;
+}
+//#endregion
+//#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 +1,38 @@
-{"name":"@stowage/core","version":"0.0.0","description":"Placeholder that reserves the name for trusted publishing; the first release is 0.1.0.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/stowage-js/stowage.git","directory":"packages/core"}}
+{
+  "name": "@stowage/core",
+  "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",
+    "object-storage",
+    "s3",
+    "storage",
+    "stowage",
+    "typescript"
+  ],
+  "homepage": "https://github.com/stowage-js/stowage/tree/main/packages/core#readme",
+  "bugs": "https://github.com/stowage-js/stowage/issues",
+  "license": "MIT",
+  "author": "Alexander Kaufmann",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stowage-js/stowage.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}