@midsummer-ai/sdk 0.0.0-stage → 0.1.0-next.1305

package/index-DdoK0y7D.d.mts

@@ -0,0 +1,192 @@
+import { z } from "zod";
+//#region src/vector/errors.d.ts
+/**
+ * Why a Vector DB call failed. `invalid`: a name, Vector, filter or option is wrong, or a Vector's
+ * dimension is not its namespace's. `not_found`: the Vector namespace does not exist. `conflict`:
+ * a namespace by that name exists with another dimension or metric. `forbidden`: the caller may not
+ * do this. `unavailable`: try again.
+ */
+type VectorErrorCode = "invalid" | "not_found" | "conflict" | "forbidden" | "unavailable";
+declare const vectorErrorCodes: ReadonlyArray<VectorErrorCode>;
+declare class VectorError extends Error {
+  readonly code: VectorErrorCode;
+  constructor(code: VectorErrorCode, why: string);
+}
+//#endregion
+//#region src/vector/schema.d.ts
+/** Most numbers a Vector holds. */
+declare const MAX_DIMENSION = 4096;
+/** Most Vectors one upsert takes, and most ids one fetch or delete names. */
+declare const MAX_BATCH = 1000;
+/** The most matches one query returns. */
+declare const MAX_TOP_K = 100;
+/** Most characters a text to embed has. */
+declare const MAX_TEXT = 30000;
+/** Most bytes a Vector's metadata takes, as JSON. */
+declare const MAX_METADATA_BYTES = 10240;
+/**
+ * The largest value a Vector holds. Engines keep values and scores as 32-bit floats, and within it
+ * every score of 4,096 values is one, finite: a squared distance is at most 4,096 · (2e17)², about
+ * 1.6e38, under a 32-bit float's 3.4e38. Scores are exact to a 32-bit float's precision for values
+ * from 1e-17 up.
+ */
+declare const MAX_VALUE = 100000000000000000;
+//#endregion
+//#region src/vector/index.d.ts
+/** How closeness is measured: fixed when a Vector namespace is made. */
+type Metric = "cosine" | "euclidean" | "dot";
+/** A metadata value: a string, a finite number or a boolean. */
+type MetadataValue = string | number | boolean;
+/** One Vector: its id in its namespace, its numbers, and the caller's own fields to filter on. */
+interface Vector {
+  /** 1 to 512 characters. */
+  readonly id: string;
+  /** Exactly the namespace's dimension of finite numbers. With `cosine`, not all zero. */
+  readonly values: ReadonlyArray<number>;
+  /** Up to 10 KiB as JSON; field names do not start with `$`. */
+  readonly metadata?: Readonly<Record<string, MetadataValue>>;
+}
+/** A Vector given as text, for a namespace made with an embedding model: its values are the text's embedding. */
+interface TextVector {
+  /** 1 to 512 characters. */
+  readonly id: string;
+  /** 1 to 30,000 characters, not all of them spaces. */
+  readonly text: string;
+  readonly metadata?: Readonly<Record<string, MetadataValue>>;
+}
+/**
+ * What a field's metadata must be. A bare value is `$eq`. `$gt`, `$gte`, `$lt` and `$lte` compare a
+ * number with a number and a string with a string, in code-unit order; anything else fails them.
+ * A Vector without the field fails every condition but `$ne` and `$nin`.
+ */
+type Condition = MetadataValue | {
+  readonly $eq?: MetadataValue;
+  readonly $ne?: MetadataValue;
+  readonly $in?: ReadonlyArray<MetadataValue>;
+  readonly $nin?: ReadonlyArray<MetadataValue>;
+  readonly $gt?: number | string;
+  readonly $gte?: number | string;
+  readonly $lt?: number | string;
+  readonly $lte?: number | string;
+};
+/** Each field's condition; a Vector matches when all of them hold. */
+type Filter = Readonly<Record<string, Condition>>;
+interface QueryOptions {
+  /** How many matches, closest first: 1 to 100, default 10. */
+  readonly topK?: number;
+  readonly filter?: Filter;
+  /** Answer each match's values too. */
+  readonly includeValues?: boolean;
+  /** Answer each match's metadata too. */
+  readonly includeMetadata?: boolean;
+  /**
+   * `strong` (the default): every write made before the query is seen, and it runs in the namespace's
+   * home region. `eventual`: it runs where it is asked, on what the engine has indexed, which lags
+   * writes by up to about 15 seconds.
+   */
+  readonly consistency?: Consistency;
+}
+/** Whether a query sees every write made before it, or runs nearest and may lag them. */
+type Consistency = "strong" | "eventual";
+/**
+ * One Vector a query found. `score` is the metric's own number: the cosine similarity (1 is the
+ * same direction), the dot product, or the euclidean distance (0 is the same point). Matches come
+ * closest first, so highest score first except for `euclidean`, lowest first; equal scores in id order.
+ */
+interface Match {
+  readonly id: string;
+  readonly score: number;
+  readonly values?: ReadonlyArray<number>;
+  readonly metadata?: Readonly<Record<string, MetadataValue>>;
+}
+/** A Vector namespace as it is now. */
+interface NamespaceInfo {
+  readonly dimension: number;
+  readonly metric: Metric;
+  /** How many Vectors it holds. */
+  readonly count: number;
+}
+/** The Vectors of one Vector namespace. */
+interface Namespace {
+  readonly name: string;
+  /** Stores each Vector under its id, replacing what was there; one given as text is embedded first. The next query anywhere sees it. */
+  upsert(vectors: ReadonlyArray<Vector | TextVector>): Promise<{
+    readonly upserted: number;
+  }>;
+  /** The `topK` Vectors closest to `vector`, or to a text's embedding, that match `filter`, closest first. */
+  query(vector: ReadonlyArray<number> | string, options?: QueryOptions): Promise<ReadonlyArray<Match>>;
+  /** The Vectors with these ids, in the order asked, values and metadata included; ids it does not hold are left out. */
+  fetch(ids: ReadonlyArray<string>): Promise<ReadonlyArray<Vector>>;
+  /** Removes the Vectors with these ids. Removing one that is not there is not an error. */
+  delete(ids: ReadonlyArray<string>): Promise<void>;
+  describe(): Promise<NamespaceInfo>;
+}
+interface VectorDb {
+  /** A Vector namespace by name: 1 to 63 lowercase letters, digits and hyphens, starting with a letter or digit. */
+  namespace(name: string): Namespace;
+}
+/** A query as an engine takes it: checked, with its defaults filled in; by a vector, or a text to embed. */
+type EngineQuery = ({
+  readonly vector: ReadonlyArray<number>;
+} | {
+  readonly text: string;
+}) & {
+  readonly topK: number;
+  readonly filter?: Filter;
+  readonly includeValues: boolean;
+  readonly includeMetadata: boolean;
+  readonly consistency?: Consistency;
+};
+/**
+ * Where Vectors live: the Seam under `vectorDb()`. The Stand-in and the real Capability are its
+ * Adapters. A call arrives checked: names, ids, values, filters and limits valid. The engine checks
+ * what only it knows: that the namespace exists, and that each Vector has its dimension. An engine
+ * that keeps only values takes text through `embedded`.
+ */
+interface VectorEngine {
+  describe(namespace: string): Promise<NamespaceInfo>;
+  upsert(namespace: string, vectors: ReadonlyArray<Vector | TextVector>): Promise<{
+    readonly upserted: number;
+  }>;
+  query(namespace: string, query: EngineQuery): Promise<ReadonlyArray<Match>>;
+  fetch(namespace: string, ids: ReadonlyArray<string>): Promise<ReadonlyArray<Vector>>;
+  delete(namespace: string, ids: ReadonlyArray<string>): Promise<void>;
+}
+/** An engine that keeps only values, as most do: `VectorEngine` without text, which `embedded` gives it. */
+interface ValuesEngine {
+  describe(namespace: string): Promise<NamespaceInfo>;
+  upsert(namespace: string, vectors: ReadonlyArray<Vector>): Promise<{
+    readonly upserted: number;
+  }>;
+  query(namespace: string, query: Extract<EngineQuery, {
+    readonly vector: ReadonlyArray<number>;
+  }>): Promise<ReadonlyArray<Match>>;
+  fetch(namespace: string, ids: ReadonlyArray<string>): Promise<ReadonlyArray<Vector>>;
+  delete(namespace: string, ids: ReadonlyArray<string>): Promise<void>;
+}
+/**
+ * Making and dropping Vector namespaces: the platform's, never a Site's. `create` of one that exists
+ * with the same settings does nothing, and with others is `conflict`; `drop` of one that does not
+ * exist does nothing.
+ */
+interface VectorControl {
+  /** `embed` is the embedding model whose vectors the namespace holds; without one, it takes values only. */
+  create(namespace: string, settings: {
+    readonly dimension: number;
+    readonly metric: Metric;
+    readonly embed?: string;
+  }): Promise<void>;
+  drop(namespace: string): Promise<void>;
+}
+/** Vector DB over `engine`. */
+declare function vectorDb(engine: VectorEngine): VectorDb;
+/**
+ * `engine`, which keeps only values, taking text too: the texts of each call are embedded by `embed`,
+ * given the namespace and the texts in order, before `engine` sees the call. `embed` returns
+ * `undefined` for a namespace made without an embedding model, which is `invalid`.
+ *
+ *   const site = embedded(engine, (namespace, texts) => vector.embed(namespace, texts))
+ */
+declare function embedded(engine: ValuesEngine, embed: (namespace: string, texts: ReadonlyArray<string>) => Promise<ReadonlyArray<ReadonlyArray<number>> | undefined>): VectorEngine;
+//#endregion
+export { MAX_TOP_K as C, vectorErrorCodes as D, VectorErrorCode as E, MAX_TEXT as S, VectorError as T, embedded as _, Match as a, MAX_DIMENSION as b, Namespace as c, TextVector as d, ValuesEngine as f, VectorEngine as g, VectorDb as h, Filter as i, NamespaceInfo as l, VectorControl as m, Consistency as n, MetadataValue as o, Vector as p, EngineQuery as r, Metric as s, Condition as t, QueryOptions as u, vectorDb as v, MAX_VALUE as w, MAX_METADATA_BYTES as x, MAX_BATCH as y };

package/index-sgdyoA2P.d.mts

@@ -0,0 +1,212 @@
+//#region src/errors.d.ts
+/**
+ * Why a Storage call failed. `invalid`: a name, range or option is wrong. `not_found`: what the
+ * call needs is missing. `conflict`: a condition on the call did not hold. `forbidden`: the
+ * caller may not do this. `quota`: over the Project's plan. `unavailable`: try again.
+ */
+type StorageErrorCode = "invalid" | "not_found" | "conflict" | "forbidden" | "quota" | "unavailable";
+/**
+ * Which rule a failure broke, where a caller acts on it: `range` (it starts past the end),
+ * `upload` (no such upload, or it is finished), `part` (a part to complete is missing or its etag
+ * differs), `part-order` (the parts to complete are not in ascending order), `part-too-small`
+ * (a part other than the last is under 5 MiB).
+ */
+type StorageErrorReason = "range" | "upload" | "part" | "part-order" | "part-too-small";
+declare class StorageError extends Error {
+  readonly code: StorageErrorCode;
+  readonly reason?: StorageErrorReason | undefined;
+  constructor(code: StorageErrorCode, why: string, reason?: StorageErrorReason | undefined);
+}
+//#endregion
+//#region src/index.d.ts
+/** What a Bucket holds under one key. */
+interface StoredObject {
+  readonly key: string;
+  readonly size: number;
+  /** The SHA-256 of the bytes, in hex. The same bytes have the same etag in every Bucket: it identifies the content, not a version. */
+  readonly etag: string;
+  readonly contentType: string;
+  /** The caller's own pairs, as put: lowercase keys, at most 2 KiB in all. */
+  readonly metadata: Readonly<Record<string, string>>;
+  /** When this content was put, in milliseconds since the epoch. */
+  readonly uploadedAt: number;
+}
+/** An Object read: its description and the bytes asked for. */
+interface ObjectRead extends StoredObject {
+  /** The whole Object, or only the range asked for. */
+  readonly body: Uint8Array;
+  /** Set on a range read: where `body` sits in the Object, whose whole size is `size`. */
+  readonly range?: {
+    readonly offset: number;
+    readonly length: number;
+  };
+}
+/** Bytes to put. A string is stored as its UTF-8 bytes. */
+type Body = Uint8Array | ArrayBuffer | string | Blob;
+/**
+ * Part of an Object: from `offset`, `length` bytes or to the end; or the last `suffix` bytes. A
+ * range that runs past the end is cut at the end. One that starts at or past it is `invalid`.
+ */
+type Range = {
+  readonly offset: number;
+  readonly length?: number;
+} | {
+  readonly suffix: number;
+};
+interface PutOptions {
+  /** Defaults to `application/octet-stream`. */
+  readonly contentType?: string;
+  readonly metadata?: Readonly<Record<string, string>>;
+  /** `"*"`: put only if nothing is stored under the key, else `conflict`. */
+  readonly ifNoneMatch?: "*";
+  /** Put only if the key holds content with this etag, else `conflict`. */
+  readonly ifMatch?: string;
+}
+interface ListOptions {
+  /** Only keys that start with this. */
+  readonly prefix?: string;
+  /** Keys with this after the prefix are folded into one entry of `prefixes`, up to and including it. */
+  readonly delimiter?: string;
+  /** Start after this key or folded prefix: the `next` of the page before. */
+  readonly after?: string;
+  /** At most this many entries, Objects and prefixes together: 1 to 1,000, default 1,000. */
+  readonly limit?: number;
+}
+/** One page of a listing, in UTF-8 byte order of key. `next` is set when there is more. */
+interface Listing {
+  readonly objects: ReadonlyArray<StoredObject>;
+  readonly prefixes: ReadonlyArray<string>;
+  readonly next?: string;
+}
+/** The Objects of one Bucket. */
+interface Bucket {
+  readonly name: string;
+  /** Stores `body` under `key`, replacing what was there. The next read anywhere sees it. */
+  put(key: string, body: Body, options?: PutOptions): Promise<StoredObject>;
+  /** The Object under `key`, or the range asked for; `null` if nothing is stored under the key. */
+  get(key: string, options?: {
+    readonly range?: Range;
+  }): Promise<ObjectRead | null>;
+  /** The Object's description without its bytes; `null` if nothing is stored under the key. */
+  head(key: string): Promise<StoredObject | null>;
+  /** Removes what `key` holds. Removing nothing is not an error. */
+  delete(key: string): Promise<void>;
+  list(options?: ListOptions): Promise<Listing>;
+  /** Puts the content of `from` under `to` as well, with its content type and metadata. `not_found` if nothing is stored under `from`. */
+  copy(from: string, to: string, options?: {
+    readonly ifNoneMatch?: "*";
+  }): Promise<StoredObject>;
+  /**
+   * Starts putting `key` in parts, for an Object too big for one call or sent in parallel. The key
+   * keeps what it holds until the upload completes. `ifNoneMatch` is checked when it completes.
+   */
+  createUpload(key: string, options?: Omit<PutOptions, "ifMatch">): Promise<{
+    readonly uploadId: string;
+  }>;
+  /**
+   * Sends part `partNumber` (1 to 10,000) of an upload; sending a number again replaces that part.
+   * Every part except the last must have the same size and contain at least 5 MiB. The last part
+   * must be no larger than the first. Checked on completion.
+   */
+  uploadPart(key: string, uploadId: string, partNumber: number, body: Body): Promise<Part>;
+  /**
+   * Joins the parts named, in ascending part number, into the Object under `key`, whose etag is the
+   * SHA-256 of the whole. Pass each `partNumber` and `etag` returned by `uploadPart`. A completed
+   * upload takes no more parts; one refused stays open, to be completed again.
+   */
+  completeUpload(key: string, uploadId: string, parts: ReadonlyArray<Pick<Part, "partNumber" | "etag">>): Promise<StoredObject>;
+  /** Drops an upload and its parts. Aborting one that is finished or unknown is `not_found`. */
+  abortUpload(key: string, uploadId: string): Promise<void>;
+}
+/** One uploaded part. Its etag identifies that upload of the part; pass it unchanged to `completeUpload`. */
+interface Part {
+  readonly partNumber: number;
+  readonly etag: string;
+  readonly size: number;
+}
+interface Storage {
+  /** A Bucket by name: 3 to 63 lowercase letters, digits and hyphens, starting and ending with a letter or digit. */
+  bucket(name: string): Bucket;
+}
+/**
+ * Where Objects live: the Seam under `storage()`. The Stand-in and the real Capability are its
+ * Adapters. A call arrives checked and normalized: names valid, bytes as `Uint8Array`, defaults
+ * filled in.
+ */
+/** What a Bucket holds now: its Objects and their bytes, a copy counted as its own. */
+interface Usage {
+  readonly objects: number;
+  readonly bytes: number;
+}
+/**
+ * Calls made on a Bucket: `writes` put, copy, delete and the steps of an upload, a call for each
+ * Object; `reads` get, head and list, a call for each Object read or page listed.
+ */
+interface Operations {
+  readonly reads: number;
+  readonly writes: number;
+}
+interface StorageEngine {
+  put(bucket: string, key: string, body: Uint8Array, options: EnginePut): Promise<StoredObject>;
+  /**
+   * With no range and a `limit`, an Object larger than `limit` bytes returns its first `limit` bytes,
+   * as though that range had been asked for: a client that cannot carry it whole reads on by range.
+   */
+  get(bucket: string, key: string, range?: Range, limit?: number): Promise<ObjectRead | null>;
+  head(bucket: string, key: string): Promise<StoredObject | null>;
+  delete(bucket: string, key: string): Promise<void>;
+  list(bucket: string, options: EngineList): Promise<Listing>;
+  copy(bucket: string, from: string, to: string, options: {
+    readonly ifNoneMatch?: "*";
+  }): Promise<StoredObject>;
+  createUpload(bucket: string, key: string, options: Omit<EnginePut, "ifMatch">): Promise<{
+    readonly uploadId: string;
+  }>;
+  uploadPart(bucket: string, key: string, uploadId: string, partNumber: number, body: Uint8Array): Promise<Part>;
+  completeUpload(bucket: string, key: string, uploadId: string, parts: ReadonlyArray<Pick<Part, "partNumber" | "etag">>): Promise<StoredObject>;
+  abortUpload(bucket: string, key: string, uploadId: string): Promise<void>;
+  /** What the Bucket stores, for metering. A Bucket never written to stores nothing. */
+  usage(bucket: string): Promise<Usage>;
+  /** The calls made on the Bucket in the hours from `from` up to `to` (milliseconds), for metering. */
+  operations(bucket: string, from: number, to: number): Promise<Operations>;
+  /**
+   * The streaming forms of `get`, `put` and `uploadPart`, for bodies too large to hold: an engine that
+   * holds bodies whole, such as the Stand-in, leaves them out and callers fall back to the whole forms.
+   * `sha256`, when given, is the hex hash the body must have; one that does not is `invalid` and stored
+   * nowhere. A streamed part's etag is unique to that upload of it, not its bytes' hash.
+   */
+  stream?(bucket: string, key: string, range?: Range): Promise<ObjectStream | null>;
+  putStream?(bucket: string, key: string, body: ReadableStream<Uint8Array>, size: number, options: EnginePut & {
+    readonly sha256?: string;
+  }): Promise<StoredObject>;
+  uploadPartStream?(bucket: string, key: string, uploadId: string, partNumber: number, body: ReadableStream<Uint8Array>, size: number, sha256?: string): Promise<Part>;
+}
+/**
+ * The streaming methods of `engine` an engine wrapping it passes on, with each Bucket named as `read`
+ * (for `stream`) and `write` (for the rest) turn it; none where `engine` has none.
+ */
+declare function streamsOf(engine: StorageEngine, read: (bucket: string) => string, write: (bucket: string) => string): Pick<StorageEngine, "stream" | "putStream" | "uploadPartStream">;
+/** An Object read as a stream: its description and the bytes asked for, `range.length` of them or its whole size. */
+interface ObjectStream extends StoredObject {
+  readonly body: ReadableStream<Uint8Array>;
+  readonly range?: {
+    readonly offset: number;
+    readonly length: number;
+  };
+}
+interface EnginePut {
+  readonly contentType: string;
+  readonly metadata: Readonly<Record<string, string>>;
+  readonly ifNoneMatch?: "*";
+  readonly ifMatch?: string;
+}
+interface EngineList {
+  readonly prefix: string;
+  readonly delimiter?: string;
+  readonly after?: string;
+  readonly limit: number;
+}
+/** Storage over `engine`. */
+declare function storage(engine: StorageEngine): Storage;
+//#endregion
+export { storage as _, ListOptions as a, StorageErrorCode as b, ObjectStream as c, PutOptions as d, Range as f, Usage as g, StoredObject as h, EnginePut as i, Operations as l, StorageEngine as m, Bucket as n, Listing as o, Storage as p, EngineList as r, ObjectRead as s, Body as t, Part as u, streamsOf as v, StorageErrorReason as x, StorageError as y };

package/index.d.mts

@@ -0,0 +1,2 @@
+import { _ as storage, a as ListOptions, b as StorageErrorCode, c as ObjectStream, d as PutOptions, f as Range, g as Usage, h as StoredObject, i as EnginePut, l as Operations, m as StorageEngine, n as Bucket, o as Listing, p as Storage, r as EngineList, s as ObjectRead, t as Body, u as Part, v as streamsOf, x as StorageErrorReason, y as StorageError } from "./index-sgdyoA2P.mjs";
+export { Body, Bucket, EngineList, EnginePut, ListOptions, Listing, ObjectRead, ObjectStream, Operations, Part, PutOptions, Range, Storage, StorageEngine, StorageError, type StorageErrorCode, type StorageErrorReason, StoredObject, Usage, storage, streamsOf };

package/index.mjs

@@ -0,0 +1,137 @@
+import { a as checkMetadata, c as checkRange, d as invalid, h as StorageError, i as checkListLimit, l as checkUploadId, n as checkBucketName, o as checkPartNumber, r as checkKey, s as checkParts } from "./names-DfCBKupJ.mjs";
+//#region src/index.ts
+/**
+* The SDK: the one package your project's code imports to use Midsummer's products. This entry is
+* storage: your team's files, kept in buckets.
+*
+* In your deployment's server, the environment's storage arrives as `context.storage`. A bucket is
+* named by the name the environment binds it under (`midsummer env binding set`), so `avatars` can
+* be one bucket in production and another in Preview:
+*
+*   import { storage } from "@midsummer-ai/sdk"
+*   import { remote } from "@midsummer-ai/sdk/wire"
+*
+*   export default {
+*     async fetch(request: Request, context: { storage: { send(frame: Uint8Array): Promise<Uint8Array> } }) {
+*       const avatars = storage(remote(context.storage)).bucket("avatars")
+*       await avatars.put("ada.png", new Uint8Array(await request.arrayBuffer()), { contentType: "image/png" })
+*       const page = await avatars.list({ prefix: "2026/", delimiter: "/" })
+*       return Response.json(page)
+*     },
+*   }
+*
+* Code that runs outside Midsummer connects with a storage key (`midsummer storage key create`):
+*
+*   import { storage } from "@midsummer-ai/sdk"
+*   import { client } from "@midsummer-ai/sdk/client"
+*
+*   const files = storage(client("https://api.midsummer.new", { key, secret }))
+*
+* In tests, `standIn` from `@midsummer-ai/sdk/stand-in` keeps files in memory. All three pass the same
+* tests, in `@midsummer-ai/sdk/contract`, and only what those tests check is guaranteed.
+*
+* Bucket names and keys are checked before a request is sent. Every failure is a `StorageError`,
+* and its `code` shows which kind. Reading a key with nothing stored returns `null`, not an error.
+*/
+/**
+* The streaming methods of `engine` an engine wrapping it passes on, with each Bucket named as `read`
+* (for `stream`) and `write` (for the rest) turn it; none where `engine` has none.
+*/
+function streamsOf(engine, read, write) {
+	const { stream, putStream, uploadPartStream } = engine;
+	return {
+		...stream ? { stream: (bucket, key, range) => stream.call(engine, read(bucket), key, range) } : {},
+		...putStream ? { putStream: (bucket, key, body, size, options) => putStream.call(engine, write(bucket), key, body, size, options) } : {},
+		...uploadPartStream ? { uploadPartStream: (bucket, key, uploadId, partNumber, body, size, sha256) => uploadPartStream.call(engine, write(bucket), key, uploadId, partNumber, body, size, sha256) } : {}
+	};
+}
+/** Storage over `engine`. */
+function storage(engine) {
+	return { bucket(name) {
+		checkBucketName(name);
+		return {
+			name,
+			async put(key, body, options = {}) {
+				checkKey(key);
+				const metadata = options.metadata ?? {};
+				checkMetadata(metadata);
+				if (options.ifMatch !== void 0 && !/^[0-9a-f]{64}$/.test(options.ifMatch)) invalid("ifMatch is not an etag");
+				return engine.put(name, key, body instanceof Blob ? await bytesOfBlob(body) : bytesOf(body), {
+					contentType: options.contentType ?? "application/octet-stream",
+					metadata,
+					...options.ifNoneMatch ? { ifNoneMatch: options.ifNoneMatch } : {},
+					...options.ifMatch !== void 0 ? { ifMatch: options.ifMatch } : {}
+				});
+			},
+			async get(key, options = {}) {
+				checkKey(key);
+				if (options.range) checkRange(options.range);
+				return engine.get(name, key, options.range);
+			},
+			async head(key) {
+				checkKey(key);
+				return engine.head(name, key);
+			},
+			async delete(key) {
+				checkKey(key);
+				return engine.delete(name, key);
+			},
+			async list(options = {}) {
+				const limit = options.limit ?? 1e3;
+				checkListLimit(limit);
+				if (options.delimiter === "") invalid("the delimiter is empty");
+				return engine.list(name, {
+					prefix: options.prefix ?? "",
+					limit,
+					...options.delimiter !== void 0 ? { delimiter: options.delimiter } : {},
+					...options.after !== void 0 ? { after: options.after } : {}
+				});
+			},
+			async copy(from, to, options = {}) {
+				checkKey(from);
+				checkKey(to);
+				return engine.copy(name, from, to, options.ifNoneMatch ? { ifNoneMatch: options.ifNoneMatch } : {});
+			},
+			async createUpload(key, options = {}) {
+				checkKey(key);
+				const metadata = options.metadata ?? {};
+				checkMetadata(metadata);
+				return engine.createUpload(name, key, {
+					contentType: options.contentType ?? "application/octet-stream",
+					metadata,
+					...options.ifNoneMatch ? { ifNoneMatch: options.ifNoneMatch } : {}
+				});
+			},
+			async uploadPart(key, uploadId, partNumber, body) {
+				checkKey(key);
+				checkUploadId(uploadId);
+				checkPartNumber(partNumber);
+				return engine.uploadPart(name, key, uploadId, partNumber, body instanceof Blob ? await bytesOfBlob(body) : bytesOf(body));
+			},
+			async completeUpload(key, uploadId, parts) {
+				checkKey(key);
+				checkUploadId(uploadId);
+				checkParts(parts);
+				return engine.completeUpload(name, key, uploadId, parts.map((p) => ({
+					partNumber: p.partNumber,
+					etag: p.etag
+				})));
+			},
+			async abortUpload(key, uploadId) {
+				checkKey(key);
+				checkUploadId(uploadId);
+				return engine.abortUpload(name, key, uploadId);
+			}
+		};
+	} };
+}
+function bytesOf(body) {
+	if (typeof body === "string") return new TextEncoder().encode(body);
+	if (body instanceof Uint8Array) return body;
+	return new Uint8Array(body);
+}
+async function bytesOfBlob(body) {
+	return new Uint8Array(await body.arrayBuffer());
+}
+//#endregion
+export { StorageError, storage, streamsOf };

package/names-DfCBKupJ.mjs

@@ -0,0 +1,115 @@
+//#region src/errors.ts
+const storageErrorCodes = [
+	"invalid",
+	"not_found",
+	"conflict",
+	"forbidden",
+	"quota",
+	"unavailable"
+];
+const storageErrorReasons = [
+	"range",
+	"upload",
+	"part",
+	"part-order",
+	"part-too-small"
+];
+var StorageError = class extends Error {
+	code;
+	reason;
+	constructor(code, why, reason) {
+		super(why);
+		this.code = code;
+		this.reason = reason;
+		this.name = "StorageError";
+	}
+};
+//#endregion
+//#region src/names.ts
+function invalid(why) {
+	throw new StorageError("invalid", why);
+}
+function checkBucketName(name) {
+	if (!/^[a-z0-9](?:[a-z0-9-]{1,61})[a-z0-9]$/.test(name)) invalid(`"${name}" is not a Bucket name: 3 to 63 lowercase letters, digits and hyphens, starting and ending with a letter or digit`);
+}
+const encoder = new TextEncoder();
+function checkKey(key) {
+	const bytes = encoder.encode(key).length;
+	if (bytes === 0) invalid("the key is empty");
+	if (bytes > 1024) invalid(`the key is ${bytes} bytes; at most 1,024`);
+}
+function checkMetadata(metadata) {
+	let bytes = 0;
+	for (const [name, value] of Object.entries(metadata)) {
+		if (!/^[a-z0-9][a-z0-9-]{0,127}$/.test(name)) invalid(`"${name}" is not a metadata name: lowercase letters, digits and hyphens`);
+		if (!/^[\x20-\x7e]*$/.test(value)) invalid(`metadata "${name}" is not printable ASCII`);
+		bytes += name.length + value.length;
+	}
+	if (bytes > 2048) invalid(`metadata is ${bytes} bytes; at most 2,048`);
+}
+const count = (n) => Number.isSafeInteger(n);
+function checkRange(range) {
+	if ("suffix" in range) {
+		if (!count(range.suffix) || range.suffix < 1) invalid("a suffix range is a whole number of bytes, at least 1");
+		return;
+	}
+	if (!count(range.offset) || range.offset < 0) invalid("a range offset is a whole number of bytes, at least 0");
+	if (range.length !== void 0 && (!count(range.length) || range.length < 1)) invalid("a range length is a whole number of bytes, at least 1");
+}
+/** Where `range` falls in an Object of `size` bytes: cut at the end; `invalid` if it starts at or past it. */
+function resolveRange(range, size) {
+	if ("suffix" in range) {
+		if (size === 0) invalid("the Object is empty");
+		const length = Math.min(range.suffix, size);
+		return {
+			offset: size - length,
+			length
+		};
+	}
+	if (range.offset >= size) throw new StorageError("invalid", `the range starts at byte ${range.offset}; the Object has ${size}`, "range");
+	const end = range.length === void 0 ? size : Math.min(range.offset + range.length, size);
+	return {
+		offset: range.offset,
+		length: end - range.offset
+	};
+}
+/** Every part of an upload but the last is at least this many bytes. */
+const MIN_PART = 5 << 20;
+function checkPartNumber(partNumber) {
+	if (!count(partNumber) || partNumber < 1 || partNumber > 1e4) invalid("a part number is 1 to 10,000");
+}
+function checkUploadId(uploadId) {
+	if (!/^[A-Za-z0-9._-]{1,256}$/.test(uploadId)) invalid("that is not an upload id");
+}
+/** The parts to complete: 1 to 10,000 of them, each named once with an etag, in ascending part number. */
+function checkParts(parts) {
+	if (parts.length < 1 || parts.length > 1e4) invalid("an upload completes with 1 to 10,000 parts");
+	parts.forEach((part, i) => {
+		checkPartNumber(part.partNumber);
+		if (!/^[0-9a-f]{64}$/.test(part.etag)) throw new StorageError("invalid", `part ${part.partNumber}'s etag is not a SHA-256`, "part");
+		if (i > 0 && part.partNumber <= parts[i - 1].partNumber) throw new StorageError("invalid", "the parts are not in ascending part number", "part-order");
+	});
+}
+function checkListLimit(limit) {
+	if (!count(limit) || limit < 1 || limit > 1e3) invalid("a listing's limit is 1 to 1,000");
+}
+/** Keys compare in UTF-8 byte order, the order listings promise; JavaScript's own order is UTF-16. */
+function compareKeys(a, b) {
+	const x = encoder.encode(a), y = encoder.encode(b);
+	for (let i = 0; i < Math.min(x.length, y.length); i += 1) if (x[i] !== y[i]) return x[i] - y[i];
+	return x.length - y.length;
+}
+async function sha256(bytes) {
+	const digest = await crypto.subtle.digest("SHA-256", bytes);
+	return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* Refuses parts whose sizes an upload cannot be stored in: every part but the last the size of the
+* first, and the last no larger. Uploads are stored part for part, and parts of one size are what
+* that storage takes.
+*/
+function sameSizes(sizes, named) {
+	for (let i = 1; i < sizes.length; i += 1) if (i < sizes.length - 1 ? sizes[i] !== sizes[0] : sizes[i] > sizes[0]) throw new StorageError("invalid", `part ${named[i].partNumber} is ${sizes[i]} bytes: every part but the last must be ${sizes[0]} bytes, as the first is, and the last no larger`, "part");
+}
+//#endregion
+export { storageErrorReasons as _, checkMetadata as a, checkRange as c, invalid as d, resolveRange as f, storageErrorCodes as g, StorageError as h, checkListLimit as i, checkUploadId as l, sha256 as m, checkBucketName as n, checkPartNumber as o, sameSizes as p, checkKey as r, checkParts as s, MIN_PART as t, compareKeys as u };