@stowage/core 0.0.0 → 0.1.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,83 @@
+# @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()` 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`. CI last ran green on Bun 1.4.2 and Deno 2.9.6.
+
+The bundle measures 1.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).
+
+## 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)).
+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)).
+
+```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";
+  }
+}
+```
+
+## 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)
+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)
+are at the same tag.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,203 @@
+//#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`, `stat` and `get` return it, `copy` keeps it.
+ *   Where not declared, a non-empty `userMetadata` is `Unsupported` and reads return `{}`.
+ */
+export declare const capabilityNames: readonly ["keyBytesPreserved", "presignedUrls", "rangeReads", "userMetadata"];
+/** 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/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;
+}
+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/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/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`.
+   */
+  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;
+  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 };

package/dist/index.js

@@ -0,0 +1,191 @@
+//#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`, `stat` and `get` return it, `copy` keeps it.
+*   Where not declared, a non-empty `userMetadata` is `Unsupported` and reads return `{}`.
+*/
+const capabilityNames = [
+	"keyBytesPreserved",
+	"presignedUrls",
+	"rangeReads",
+	"userMetadata"
+];
+//#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 = 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}`;
+	if (rule === "writable") {
+		if (key.includes("\\")) return "holds a backslash";
+		if (key.endsWith("/")) return "ends with a slash";
+		const bytes = utf8.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 `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/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
+export { StorageError, capabilityNames, errorCodeForStatus, invalidKeyReason, isStorageError, isTransientStatus, 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.1.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"
+  }
+}