@stowage/conformance 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,187 @@
+# @stowage/conformance
+
+The cases every stowage adapter has to pass, as plain cases a test framework maps onto its own
+runner. An adapter written outside this repository passes the same cases as the ones inside it.
+
+## Install
+
+```sh
+npm install --save-dev @stowage/conformance
+```
+
+## Write a target
+
+A `ConformanceTarget` tells the suite how to construct the storage under test. `createStorage`
+returns a storage the run may write to below any prefix, constructed from outside the adapter the
+way a caller would construct it
+([spec 9.3](https://github.com/stowage-js/stowage/blob/@stowage/conformance@0.2.0/docs/spec.md#93-what-the-target-promises)).
+
+```ts
+import { memoryStorage } from "@stowage/adapter-memory";
+import type { ConformanceTarget } from "@stowage/conformance";
+
+export const target: ConformanceTarget = {
+  name: "@stowage/adapter-memory",
+  createStorage: () => memoryStorage(),
+};
+```
+
+The optional members widen the run:
+
+- `cleanup(keyPrefix)` runs once at the end, and defaults to `deleteAll(keyPrefix)` on a fresh
+  storage. Every key a run writes begins with its prefix, so two runs against one bucket do not
+  interfere.
+- `createStorageWithBadCredentials`, `createStorageWithExpiredCredentials` and
+  `createStorageWithDeniedCredentials` return storages whose credential the provider refuses, has
+  expired, or accepts for reading alone. A case that needs a factory the target leaves out is
+  reported `skipped`.
+
+## Fill the declaration
+
+The suite reads what the storage supports from its `capabilities`, once per run, before the first
+case. The storage lists every name out of `capabilityNames` it implements, each once, and the list
+is fixed when it is constructed
+([spec 4.9](https://github.com/stowage-js/stowage/blob/@stowage/conformance@0.2.0/docs/spec.md#49-capabilities)).
+Every storage the target creates in one run declares the same; two configurations are two targets.
+
+A case whose `requires` the storage declares runs its `run` half. A case missing a name of its
+`requires` runs the `runWithout` half, which checks what the storage does without the capability:
+most refuse the call with `Unsupported` naming it, `presignedUrls` has `presignGet` and
+`presignPut` absent from the storage, and a few check the weaker behavior, such as a copy whose
+destination reads `{}`
+([spec 9.5](https://github.com/stowage-js/stowage/blob/@stowage/conformance@0.2.0/docs/spec.md#95-cases)).
+An adapter refuses such a call like this:
+
+```ts
+import { StorageError } from "@stowage/core";
+
+export function refuseUserMetadata(bucket: string): StorageError {
+  return new StorageError({
+    code: "Unsupported",
+    message: "This storage keeps no user metadata",
+    operation: "put",
+    bucket,
+    provider: "my-provider",
+    attempts: 0,
+    capability: "userMetadata",
+  });
+}
+```
+
+`expectUnsupported(call, capability)` asserts that refusal in a test of the adapter's own.
+
+## Run the cases
+
+`describeConformance(target, framework)` maps every case onto the `describe` and `test` of the
+framework it is handed
+([spec 9.2](https://github.com/stowage-js/stowage/blob/@stowage/conformance@0.2.0/docs/spec.md#92-running-the-suite)).
+It runs the `fast` cases, and both tiers with `includeSlow: true`.
+
+Vitest:
+
+```ts
+import { memoryStorage } from "@stowage/adapter-memory";
+import { describeConformance } from "@stowage/conformance";
+import { describe, test } from "vitest";
+
+describeConformance(
+  { name: "@stowage/adapter-memory", createStorage: () => memoryStorage() },
+  { describe, test, includeSlow: true },
+);
+```
+
+`bun:test`:
+
+```ts
+import { describe, test } from "bun:test";
+
+import { memoryStorage } from "@stowage/adapter-memory";
+import { describeConformance } from "@stowage/conformance";
+
+describeConformance(
+  { name: "@stowage/adapter-memory", createStorage: () => memoryStorage() },
+  { describe, test },
+);
+```
+
+`Deno.test` has no `describe` beside it, so a block becomes the leading part of each test's name:
+
+```ts
+import { memoryStorage } from "@stowage/adapter-memory";
+import { describeConformance } from "@stowage/conformance";
+
+const enclosingNames: string[] = [];
+
+describeConformance(
+  { name: "@stowage/adapter-memory", createStorage: () => memoryStorage() },
+  {
+    describe(name, body) {
+      enclosingNames.push(name);
+
+      try {
+        body();
+      } finally {
+        enclosingNames.pop();
+      }
+    },
+    test(name, body) {
+      Deno.test([...enclosingNames, name].join(" > "), body);
+    },
+  },
+);
+```
+
+## Run the cases on `workerd`
+
+`workerd` has no test framework. `runAll(target)` runs every case and returns the results, which a
+worker answers with for the process that started it to report:
+
+```ts
+import { memoryStorage } from "@stowage/adapter-memory";
+import { runAll } from "@stowage/conformance";
+
+export default {
+  async fetch(): Promise<Response> {
+    const results = await runAll({
+      name: "@stowage/adapter-memory",
+      createStorage: () => memoryStorage(),
+    });
+    const failed = results.filter((result) => result.status === "failed");
+
+    return Response.json(results, { status: failed.length === 0 ? 200 : 500 });
+  },
+};
+```
+
+A failed result carries the error as `name`, `message`, `stack` and, for a `StorageError`, `code`.
+
+## Read an adapter
+
+[`@stowage/adapter-memory`](https://github.com/stowage-js/stowage/tree/@stowage/adapter-memory@0.2.0/packages/adapter-memory/src)
+is the implementation a third-party adapter is read against, out of the four adapters of this
+repository that pass these cases: `@stowage/adapter-memory`, `@stowage/adapter-fs`,
+`@stowage/adapter-s3` and `@stowage/adapter-azure-blob`. It enforces the key rule exactly,
+declares four of the five capabilities, and has no network in the way. The cases themselves are
+written against the behavior of S3, not against it.
+
+What the suite leaves to an adapter's own tests, such as flat memory during a large upload or the
+retry curve, is listed in
+[spec 9.4](https://github.com/stowage-js/stowage/blob/@stowage/conformance@0.2.0/docs/spec.md#94-what-the-suite-does-not-assert).
+
+## 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 11.6 kB minified and gzipped, `@stowage/core` included.
+
+## Specification
+
+[`docs/spec.md` at `@stowage/conformance@0.2.0`](https://github.com/stowage-js/stowage/blob/@stowage/conformance@0.2.0/docs/spec.md#9-stowageconformance)
+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/conformance@0.2.0/CONTEXT.md)
+and the [decisions behind it](https://github.com/stowage-js/stowage/tree/@stowage/conformance@0.2.0/docs/adr)
+are at the same tag.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import { CapabilityName, Storage, StorageErrorCode } from "@stowage/core";
+//#region src/assertions.d.ts
+/**
+ * Spec 4.9 leaves a call needing a capability the storage does not declare with an
+ * `Unsupported` error naming it, and spec 9.2 has most of the `runWithout` halves assert
+ * that through this.
+ */
+export declare function expectUnsupported(call: () => Promise<unknown>, capability: CapabilityName): Promise<void>;
+//#endregion
+//#region src/target.d.ts
+interface ConformanceTarget {
+  readonly name: string;
+  createStorage(): Storage | Promise<Storage>;
+  cleanup?(keyPrefix: string): Promise<void>;
+  createStorageWithBadCredentials?(): Storage | Promise<Storage>;
+  createStorageWithExpiredCredentials?(): Storage | Promise<Storage>;
+  createStorageWithDeniedCredentials?(): Storage | Promise<Storage>;
+}
+interface ConformanceContext {
+  readonly storage: Storage;
+  readonly keyPrefix: string;
+  readonly target: ConformanceTarget;
+  declares(name: CapabilityName): boolean;
+}
+//#endregion
+//#region src/case.d.ts
+type ConformanceCase = {
+  readonly name: string;
+  readonly requires: readonly [];
+  readonly cost: "fast" | "slow";
+  run(ctx: ConformanceContext): Promise<void>;
+} | {
+  readonly name: string;
+  readonly requires: readonly [CapabilityName, ...CapabilityName[]];
+  readonly cost: "fast" | "slow";
+  run(ctx: ConformanceContext): Promise<void>;
+  runWithout(ctx: ConformanceContext): Promise<void>;
+};
+interface ConformanceCaseMetadata {
+  readonly name: string;
+  readonly requires: readonly CapabilityName[];
+  readonly cost: "fast" | "slow";
+}
+//#endregion
+//#region src/cases/index.d.ts
+/** The same cases as the package publishes them, without the factory of spec 9.3. */
+export declare const conformanceCases: readonly ConformanceCase[];
+//#endregion
+//#region src/result.d.ts
+type ConformanceMode = "declared" | "without";
+interface SerializedConformanceError {
+  readonly name: string;
+  readonly message: string;
+  readonly stack?: string;
+  readonly code?: StorageErrorCode;
+}
+type ConformanceResult = {
+  readonly case: ConformanceCaseMetadata;
+  readonly status: "passed";
+  readonly mode: ConformanceMode;
+} | {
+  readonly case: ConformanceCaseMetadata;
+  readonly status: "skipped";
+  readonly reason: string;
+} | {
+  readonly case: ConformanceCaseMetadata;
+  readonly status: "failed";
+  readonly mode: ConformanceMode;
+  readonly error: SerializedConformanceError;
+};
+//#endregion
+//#region src/run.d.ts
+interface ConformanceRunOptions {
+  includeSlow?: boolean;
+}
+//#endregion
+//#region src/describe.d.ts
+interface ConformanceFramework extends ConformanceRunOptions {
+  describe(name: string, body: () => void): void;
+  test(name: string, body: () => Promise<void>): void;
+}
+/**
+ * Maps every case onto one test of Vitest, `bun:test` or `Deno.test`, whose `describe`
+ * and `test` agree in shape (ADR 0006), so that a failing case is a failing test of its
+ * own rather than one red line covering the suite.
+ */
+export declare function describeConformance(target: ConformanceTarget, framework: ConformanceFramework): void;
+//#endregion
+//#region src/run-all.d.ts
+/**
+ * Runs the cases without a test framework and reports them, which is how a runtime that
+ * has none — `workerd` — runs the suite (ADR 0006). A failing case is one result among
+ * the others; only a target that cannot produce a storage at all rejects the run.
+ */
+export declare function runAll(target: ConformanceTarget, options?: ConformanceRunOptions): Promise<readonly ConformanceResult[]>;
+//#endregion
+export type { ConformanceCase, ConformanceCaseMetadata, ConformanceContext, ConformanceFramework, ConformanceMode, ConformanceResult, ConformanceRunOptions, ConformanceTarget, SerializedConformanceError };