@stowage/adapter-memory 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,92 @@
+# @stowage/adapter-memory
+
+A storage held in process memory, and the implementation a third-party adapter is read against.
+
+## Install
+
+```sh
+npm install @stowage/adapter-memory
+```
+
+## Example
+
+```ts
+import { memoryStorage } from "@stowage/adapter-memory";
+
+const storage = memoryStorage();
+
+await storage.put("greeting.txt", "Hello", {
+  contentType: "text/plain",
+  userMetadata: { author: "stowage" },
+});
+
+const object = await storage.get("greeting.txt");
+console.log(object.stat.contentType, object.stat.userMetadata, await object.text());
+```
+
+## 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 3.3 kB minified and gzipped, `@stowage/core` included.
+
+## Limits
+
+- `presignedUrls` is not declared: `MemoryStorage` has neither `presignGet` nor `presignPut`
+  ([spec 4.9](https://github.com/stowage-js/stowage/blob/@stowage/adapter-memory@0.1.0/docs/spec.md#49-capabilities)).
+- Every object is held whole in memory, with no size limit of its own, so memory grows with what
+  the storage holds ([spec 5](https://github.com/stowage-js/stowage/blob/@stowage/adapter-memory@0.1.0/docs/spec.md#5-stowageadapter-memory)).
+
+## Notes
+
+`put` takes no `Blob`. A caller holding one passes its stream
+([spec 4.2](https://github.com/stowage-js/stowage/blob/@stowage/adapter-memory@0.1.0/docs/spec.md#42-bodies)):
+
+```ts
+import { memoryStorage } from "@stowage/adapter-memory";
+
+const storage = memoryStorage();
+const blob = new Blob(["region,revenue\n"], { type: "text/csv" });
+
+await storage.put("report.csv", blob.stream(), { contentType: blob.type });
+```
+
+stowage reports no progress
+([spec 11](https://github.com/stowage-js/stowage/blob/@stowage/adapter-memory@0.1.0/docs/spec.md#11-non-goals)).
+A caller who wants it counts the bytes on their way into `put`:
+
+```ts
+import { memoryStorage } from "@stowage/adapter-memory";
+
+const storage = memoryStorage();
+
+function countBytes(report: (bytes: number) => void): TransformStream<Uint8Array, Uint8Array> {
+  let bytes = 0;
+
+  return new TransformStream({
+    transform(chunk, controller) {
+      bytes += chunk.byteLength;
+      report(bytes);
+      controller.enqueue(chunk);
+    },
+  });
+}
+
+const response = await fetch("https://example.com/fixture.json");
+
+if (response.body === null) throw new Error("The response carries no body");
+
+await storage.put("fixture.json", response.body.pipeThrough(countBytes(console.log)));
+```
+
+## Specification
+
+[`docs/spec.md` at `@stowage/adapter-memory@0.1.0`](https://github.com/stowage-js/stowage/blob/@stowage/adapter-memory@0.1.0/docs/spec.md#5-stowageadapter-memory)
+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/adapter-memory@0.1.0/CONTEXT.md)
+and the [decisions behind it](https://github.com/stowage-js/stowage/tree/@stowage/adapter-memory@0.1.0/docs/adr)
+are at the same tag.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { Storage } from "@stowage/core";
+//#region src/index.d.ts
+export interface MemoryStorage extends Storage {
+  readonly provider: "memory";
+}
+export declare function memoryStorage(): MemoryStorage;
+//#endregion

package/dist/index.js

@@ -0,0 +1,470 @@
+import { StorageError, invalidKeyReason } from "@stowage/core";
+//#region src/bytes.ts
+async function readBody(body, signal) {
+	if (isStream(body)) return await readStream(body, signal);
+	signal?.throwIfAborted();
+	return typeof body === "string" ? new TextEncoder().encode(body) : new Uint8Array(body);
+}
+/** Spec 4.2 leaves a stream at its end or canceled once `put` settled, read or not. */
+async function cancelBody(body, reason) {
+	if (isStream(body)) await body.cancel(reason);
+}
+function isStream(body) {
+	return typeof body !== "string" && !(body instanceof Uint8Array);
+}
+async function readStream(stream, signal) {
+	const chunks = [];
+	await stream.pipeTo(new WritableStream({ write(chunk) {
+		chunks.push(chunk.slice());
+	} }), { signal });
+	return join(chunks);
+}
+function join(chunks) {
+	const bytes = new Uint8Array(chunks.reduce((size, chunk) => size + chunk.byteLength, 0));
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return bytes;
+}
+//#endregion
+//#region src/etag.ts
+async function etagOf(bytes) {
+	const digest = await crypto.subtle.digest("SHA-256", bytes);
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+//#endregion
+//#region src/storage-error.ts
+function memoryError(fields) {
+	return new StorageError({
+		...fields,
+		bucket: "memory",
+		provider: "memory"
+	});
+}
+//#endregion
+//#region src/key.ts
+/** The error the key violating the rule is reported as, or `undefined` where it holds. */
+function keyError(key, rule, operation) {
+	const reason = invalidKeyReason(key, rule);
+	if (reason === void 0) return void 0;
+	return memoryError({
+		code: "InvalidKey",
+		message: `The key ${JSON.stringify(key)} ${reason}`,
+		operation,
+		key,
+		attempts: 0
+	});
+}
+function requireKey(key, rule, operation) {
+	const error = keyError(key, rule, operation);
+	if (error !== void 0) throw error;
+}
+//#endregion
+//#region src/cursor.ts
+const cursorTag = "stowage-memory-1:";
+const unitDigits = 4;
+const hexPosition = new RegExp(`^(?:[\\da-f]{${unitDigits}})*$`);
+/** The key a page ended on, as the opaque string that continues from there. */
+function encodeCursor(after) {
+	return btoa(`${cursorTag}${hexOf(after)}`);
+}
+/** The key the cursor continues from, or `undefined` for one this adapter did not produce. */
+function decodeCursor(cursor) {
+	let decoded;
+	try {
+		decoded = atob(cursor);
+	} catch {
+		return;
+	}
+	if (!decoded.startsWith(cursorTag)) return void 0;
+	const position = decoded.slice(17);
+	return position.length > 0 && hexPosition.test(position) ? keyOf(position) : void 0;
+}
+function hexOf(key) {
+	const units = [];
+	for (let index = 0; index < key.length; index += 1) units.push(key.charCodeAt(index).toString(16).padStart(unitDigits, "0"));
+	return units.join("");
+}
+function keyOf(position) {
+	const units = [];
+	for (let index = 0; index < position.length; index += unitDigits) units.push(String.fromCharCode(Number.parseInt(position.slice(index, index + unitDigits), 16)));
+	return units.join("");
+}
+//#endregion
+//#region src/options.ts
+const operationOptionKeys = ["signal"];
+const putOptionKeys = [
+	...operationOptionKeys,
+	"contentType",
+	"userMetadata"
+];
+const getOptionKeys = [...operationOptionKeys, "range"];
+const listOptionKeys = [
+	...operationOptionKeys,
+	"prefix",
+	"delimiter",
+	"pageSize",
+	"cursor"
+];
+/**
+* Refuses an option key the spec does not list (spec 4.3). TypeScript catches one at the
+* call site; this catches the rest.
+*/
+function requireKnownOptions(options, known, operation) {
+	if (options === void 0) return;
+	for (const key of Object.keys(options)) {
+		if (known.includes(key)) continue;
+		throw optionError(key, "is not one this storage takes", operation);
+	}
+}
+function optionError(option, expectation, operation) {
+	return memoryError({
+		code: "InvalidOption",
+		message: `The option \`${option}\` ${expectation}`,
+		operation,
+		attempts: 0
+	});
+}
+//#endregion
+//#region src/listing.ts
+const defaultPageSize = 1e3;
+const maxPageSize = 1e3;
+/** `readEntries` hands over the whole storage sorted by key, afresh for every page. */
+function createListing(readEntries, options) {
+	return {
+		async page() {
+			const request = read(options);
+			options?.signal?.throwIfAborted();
+			const slice = take(readEntries(), request);
+			return {
+				objects: slice.objects,
+				prefixes: slice.prefixes,
+				cursor: slice.after === void 0 ? void 0 : encodeCursor(slice.after)
+			};
+		},
+		async *[Symbol.asyncIterator]() {
+			const request = read(options);
+			for (let after = request.after;;) {
+				options?.signal?.throwIfAborted();
+				const slice = take(readEntries(), {
+					...request,
+					after
+				});
+				yield* slice.objects;
+				if (slice.after === void 0) return;
+				after = slice.after;
+			}
+		}
+	};
+}
+function read(options) {
+	requireKnownOptions(options, listOptionKeys, "list");
+	const prefix = options?.prefix ?? "";
+	requireKey(prefix, "prefix", "list");
+	const pageSize = options?.pageSize ?? defaultPageSize;
+	if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > maxPageSize) throw optionError("pageSize", `takes a whole number from 1 to ${maxPageSize}`, "list");
+	if (options?.delimiter === "") throw optionError("delimiter", "takes at least one character", "list");
+	const after = options?.cursor === void 0 ? void 0 : decodeCursor(options.cursor);
+	if (options?.cursor !== void 0 && after === void 0) throw optionError("cursor", "takes a cursor this storage handed out", "list");
+	return {
+		prefix,
+		delimiter: options?.delimiter,
+		pageSize,
+		after
+	};
+}
+function take(entries, request) {
+	const objects = [];
+	const prefixes = [];
+	let after;
+	for (const entry of entries) {
+		if (!entry.key.startsWith(request.prefix)) continue;
+		if (request.after !== void 0 && entry.key <= request.after) continue;
+		const pseudoDirectory = pseudoDirectoryOf(entry.key, request);
+		if (pseudoDirectory !== void 0 && prefixes.at(-1) === pseudoDirectory) {
+			after = entry.key;
+			continue;
+		}
+		if (objects.length + prefixes.length === request.pageSize) return {
+			objects,
+			prefixes,
+			after
+		};
+		if (pseudoDirectory === void 0) objects.push(entry);
+		else prefixes.push(pseudoDirectory);
+		after = entry.key;
+	}
+	return {
+		objects,
+		prefixes
+	};
+}
+function pseudoDirectoryOf(key, { prefix, delimiter }) {
+	if (delimiter === void 0) return void 0;
+	const end = key.indexOf(delimiter, prefix.length);
+	return end === -1 ? void 0 : key.slice(0, end + delimiter.length);
+}
+//#endregion
+//#region src/range.ts
+/** Refuses bounds the spec does not allow, before the key is looked up (spec 4.3). */
+function requireRange(range) {
+	if (range === void 0) return;
+	const { start, end } = range;
+	if (!isOffset(start) || end !== void 0 && (!isOffset(end) || end < start)) throw optionError("range", "takes two whole numbers from zero up, `start` at most `end`", "get");
+}
+/** The bytes the range names, both ends inclusive, clipped to what the object holds. */
+function sliceRange(bytes, range, key) {
+	if (range === void 0) return bytes;
+	if (range.start >= bytes.byteLength) throw memoryError({
+		code: "InvalidRequest",
+		message: `The range starts beyond the ${bytes.byteLength} bytes under the key ${JSON.stringify(key)}`,
+		operation: "get",
+		key,
+		attempts: 1
+	});
+	const end = Math.min(range.end ?? bytes.byteLength - 1, bytes.byteLength - 1);
+	return bytes.subarray(range.start, end + 1);
+}
+function isOffset(value) {
+	return Number.isInteger(value) && value >= 0;
+}
+//#endregion
+//#region src/stored-object.ts
+function createStoredObject(stat, bytes) {
+	let read = false;
+	const take = () => {
+		if (read) throw memoryError({
+			code: "InvalidRequest",
+			message: "The body of this stored object has already been read",
+			operation: "get",
+			key: stat.key,
+			attempts: 0
+		});
+		read = true;
+		return bytes;
+	};
+	const decoder = new TextDecoder();
+	return {
+		stat,
+		stream() {
+			let taken;
+			try {
+				taken = take();
+			} catch (error) {
+				return new ReadableStream({ start(controller) {
+					controller.error(error);
+				} });
+			}
+			return new ReadableStream({ start(controller) {
+				controller.enqueue(new Uint8Array(taken));
+				controller.close();
+			} });
+		},
+		async bytes() {
+			return new Uint8Array(take());
+		},
+		async text() {
+			return decoder.decode(take());
+		},
+		async json() {
+			return JSON.parse(decoder.decode(take()));
+		}
+	};
+}
+//#endregion
+//#region src/user-metadata.ts
+/** Spec 4.3 bounds the set at 2 KB of the header bytes it costs once it is encoded. */
+const headerByteLimit = 2048;
+/** The characters RFC 9110 allows in a field name, which is what a metadata key is. */
+const httpToken = /^[!#$%&'*+.^_`|~\dA-Za-z-]+$/;
+/** What travels in a header field as it stands, so it costs one byte per character. */
+const printableAscii = /^[\x20-\x7e]*$/;
+/** `=?UTF-8?B?` and the `?=` that closes it. */
+const encodedWordOverhead = 12;
+const utf8 = new TextEncoder();
+/**
+* The metadata as it is held: keys folded to lower case, as a header field name is.
+* Rejects with `InvalidRequest` before anything is written (spec 4.3).
+*/
+function readUserMetadata(userMetadata, key) {
+	const held = Object.create(null);
+	let headerBytes = 0;
+	for (const [name, value] of Object.entries(userMetadata ?? {})) {
+		if (!httpToken.test(name)) throw refusal(`The user metadata key ${JSON.stringify(name)} is no ASCII HTTP token`, key);
+		const folded = name.toLowerCase();
+		if (folded in held) throw refusal(`The user metadata key ${JSON.stringify(folded)} is given more than once`, key);
+		held[folded] = value;
+		headerBytes += folded.length + encodedValueBytes(value);
+	}
+	if (headerBytes > headerByteLimit) throw refusal(`The user metadata is ${headerBytes} encoded header bytes, above the limit of ${headerByteLimit}`, key);
+	return Object.freeze(held);
+}
+function encodedValueBytes(value) {
+	if (printableAscii.test(value)) return value.length;
+	return encodedWordOverhead + 4 * Math.ceil(utf8.encode(value).length / 3);
+}
+function refusal(message, key) {
+	return memoryError({
+		code: "InvalidRequest",
+		message,
+		operation: "put",
+		key,
+		attempts: 0
+	});
+}
+//#endregion
+//#region src/index.ts
+function memoryStorage() {
+	return new InMemoryStorage();
+}
+const defaultContentType = "application/octet-stream";
+const memoryCapabilities = Object.freeze([
+	"keyBytesPreserved",
+	"rangeReads",
+	"userMetadata"
+]);
+var InMemoryStorage = class {
+	provider = "memory";
+	bucket = "memory";
+	capabilities = memoryCapabilities;
+	#objects = /* @__PURE__ */ new Map();
+	async put(key, body, options) {
+		const userMetadata = await this.#accept(key, body, options);
+		const bytes = await readBody(body, options?.signal);
+		const object = {
+			key,
+			bytes,
+			contentType: options?.contentType ?? defaultContentType,
+			userMetadata,
+			etag: await etagOf(bytes),
+			lastModified: /* @__PURE__ */ new Date()
+		};
+		this.#objects.set(key, object);
+		return describe(object);
+	}
+	/**
+	* What `put` checks in front of the body, answering with the metadata to hold. Spec 4.2
+	* leaves a stream at its end or canceled once `put` settled, so a refusal here cancels
+	* the body it is not going to read.
+	*/
+	async #accept(key, body, options) {
+		try {
+			requireKey(key, "writable", "put");
+			requireKnownOptions(options, putOptionKeys, "put");
+			return readUserMetadata(options?.userMetadata, key);
+		} catch (refusal) {
+			try {
+				await cancelBody(body, refusal);
+			} finally {
+				throw refusal;
+			}
+		}
+	}
+	async get(key, options) {
+		requireKey(key, "addressable", "get");
+		requireKnownOptions(options, getOptionKeys, "get");
+		requireRange(options?.range);
+		options?.signal?.throwIfAborted();
+		const object = this.#require(key, "get");
+		return createStoredObject(describe(object), sliceRange(object.bytes, options?.range, key));
+	}
+	async stat(key, options) {
+		requireKey(key, "addressable", "stat");
+		requireKnownOptions(options, operationOptionKeys, "stat");
+		options?.signal?.throwIfAborted();
+		return describe(this.#require(key, "stat"));
+	}
+	async exists(key, options) {
+		requireKey(key, "addressable", "exists");
+		requireKnownOptions(options, operationOptionKeys, "exists");
+		options?.signal?.throwIfAborted();
+		return this.#objects.has(key);
+	}
+	list(options) {
+		return createListing(() => this.#entries(), options);
+	}
+	async delete(...keys) {
+		const failed = [];
+		for (const key of keys) {
+			const error = keyError(key, "addressable", "delete");
+			if (error === void 0) this.#objects.delete(key);
+			else failed.push(error);
+		}
+		return {
+			requested: keys.length,
+			failed
+		};
+	}
+	async deleteAll(prefix, options) {
+		requireKey(prefix, "prefix", "deleteAll");
+		requireKnownOptions(options, operationOptionKeys, "deleteAll");
+		options?.signal?.throwIfAborted();
+		const keys = [...this.#objects.keys()].filter((key) => key.startsWith(prefix));
+		for (const key of keys) this.#objects.delete(key);
+		return {
+			requested: keys.length,
+			failed: []
+		};
+	}
+	async copy(from, to, options) {
+		return this.#copy(from, to, "copy", options);
+	}
+	async move(from, to, options) {
+		const destination = this.#copy(from, to, "move", options);
+		this.#objects.delete(from);
+		return destination;
+	}
+	#copy(from, to, operation, options) {
+		requireKey(from, "addressable", operation);
+		requireKey(to, "writable", operation);
+		requireKnownOptions(options, operationOptionKeys, operation);
+		options?.signal?.throwIfAborted();
+		if (from === to) throw memoryError({
+			code: "InvalidRequest",
+			message: `The key ${JSON.stringify(from)} is both the source and the destination`,
+			operation,
+			key: from,
+			attempts: 0
+		});
+		const object = {
+			...this.#require(from, operation),
+			key: to,
+			lastModified: /* @__PURE__ */ new Date()
+		};
+		this.#objects.set(to, object);
+		return describe(object);
+	}
+	#entries() {
+		return Array.from(this.#objects.values(), entryOf).toSorted((one, other) => one.key < other.key ? -1 : one.key > other.key ? 1 : 0);
+	}
+	#require(key, operation) {
+		const object = this.#objects.get(key);
+		if (object === void 0) throw memoryError({
+			code: "NotFound",
+			message: `No object under the key ${JSON.stringify(key)}`,
+			operation,
+			key,
+			attempts: 1
+		});
+		return object;
+	}
+};
+function describe(object) {
+	return {
+		...entryOf(object),
+		contentType: object.contentType,
+		userMetadata: object.userMetadata
+	};
+}
+function entryOf(object) {
+	return {
+		key: object.key,
+		size: object.bytes.byteLength,
+		lastModified: new Date(object.lastModified),
+		etag: object.etag
+	};
+}
+//#endregion
+export { memoryStorage };

package/package.json

@@ -1 +1,41 @@
-{"name":"@stowage/adapter-memory","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/adapter-memory"}}
+{
+  "name": "@stowage/adapter-memory",
+  "version": "0.1.0",
+  "description": "stowage adapter holding a storage in process memory, and the implementation a third-party adapter is read against.",
+  "keywords": [
+    "adapter",
+    "memory",
+    "object-storage",
+    "storage",
+    "stowage",
+    "testing"
+  ],
+  "homepage": "https://github.com/stowage-js/stowage/tree/main/packages/adapter-memory#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/adapter-memory"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@stowage/core": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}