@takosjp/yurucommu-core 3.4.5 → 4.1.0

package/src/backend/runtime/cloudflare.ts

@@ -11,16 +11,15 @@ import type {
   MessageBatch,
   Queue,
   R2Bucket,
-  R2Object,
 } from "@cloudflare/workers-types";
 import { getDb } from "../../db/index.ts";
 import type {
   IKeyValueStore,
-  IObjectStorage,
+  ObjectStore,
+  ObjectStoreBody,
+  ObjectStoreObject,
+  ObjectStorePutOptions,
   IStaticAssets,
-  ListObjectsResult,
-  ObjectMetadata,
-  StorageObject,
 } from "./types.ts";
 import type {
   IQueueBatch,
@@ -33,76 +32,39 @@ import type {
 /**
  * Cloudflare R2 Storage Adapter
  */
-class CloudflareStorage implements IObjectStorage {
+class CloudflareStorage implements ObjectStore {
   constructor(private bucket: R2Bucket) {}
 
   async put(
     key: string,
-    value: Blob | ReadableStream | ArrayBuffer | string,
-    options?: {
-      httpMetadata?: ObjectMetadata["httpMetadata"];
-      customMetadata?: Record<string, string>;
-    },
+    value: ObjectStoreBody,
+    options?: ObjectStorePutOptions,
   ): Promise<void> {
     await this.bucket.put(key, value as Parameters<R2Bucket["put"]>[1], {
-      httpMetadata: options?.httpMetadata,
-      customMetadata: options?.customMetadata,
+      httpMetadata:
+        options?.contentType === undefined
+          ? undefined
+          : { contentType: options.contentType },
     });
   }
 
-  async get(key: string): Promise<StorageObject | null> {
+  async get(key: string): Promise<ObjectStoreObject | null> {
     const obj = await this.bucket.get(key);
     if (!obj) return null;
 
     return {
       key,
       body: obj.body as unknown as ReadableStream,
-      bodyUsed: obj.bodyUsed,
-      httpEtag: obj.httpEtag,
-      arrayBuffer: () => obj.arrayBuffer(),
-      text: () => obj.text(),
-      json: <T>() => obj.json<T>(),
-      httpMetadata: obj.httpMetadata,
-      customMetadata: obj.customMetadata,
-    };
-  }
-
-  async delete(key: string | string[]): Promise<void> {
-    await this.bucket.delete(key);
-  }
-
-  async list(options?: {
-    prefix?: string;
-    limit?: number;
-    cursor?: string;
-    delimiter?: string;
-  }): Promise<ListObjectsResult> {
-    const result = await this.bucket.list(options);
-    return {
-      objects: result.objects.map((obj: R2Object) => ({
-        key: obj.key,
-        size: obj.size,
-        uploaded: obj.uploaded,
-        etag: obj.etag,
-        httpMetadata: obj.httpMetadata,
-      })),
-      truncated: result.truncated,
-      cursor: result.truncated ? result.cursor : undefined,
-      delimitedPrefixes: result.delimitedPrefixes,
+      contentType: obj.httpMetadata?.contentType,
+      etag: obj.httpEtag,
+      byteLength: obj.size,
     };
   }
 
-  async head(key: string): Promise<ObjectMetadata | null> {
-    const obj = await this.bucket.head(key);
-    if (!obj) return null;
-
-    return {
-      contentType: obj.httpMetadata?.contentType,
-      contentLength: obj.size,
-      etag: obj.etag,
-      httpMetadata: obj.httpMetadata,
-      customMetadata: obj.customMetadata,
-    };
+  async delete(key: string | readonly string[]): Promise<void> {
+    await this.bucket.delete(
+      typeof key === "string" ? key : ([...key] as string[]),
+    );
   }
 }
 
@@ -241,7 +203,7 @@ export function wrapCloudflareBindings<
   "DB" | "MEDIA" | "KV" | "ASSETS" | "DELIVERY_QUEUE" | "DELIVERY_DLQ"
 > & {
   DB_INSTANCE: ReturnType<typeof getDb>;
-  MEDIA?: IObjectStorage;
+  MEDIA?: ObjectStore;
   KV: IKeyValueStore;
   ASSETS?: IStaticAssets;
   DELIVERY_QUEUE?: IQueueProducer<unknown>;

package/src/backend/runtime/edge-facades.ts

@@ -0,0 +1,336 @@
+/**
+ * The portable binding facades a Takoserver-hosted Worker receives.
+ *
+ * A Worker Version published through Takoform onto a Takoserver Host does not
+ * get Cloudflare's native `KVNamespace` / `D1Database` / `Queue` / `R2Bucket`
+ * objects. The Host's generated entrypoint replaces `env` with an object whose
+ * bindings are the exact facades named by the Interface the Version declared —
+ * `edge.kv@1.0.0`, `edge.sql@1.0.0`, `edge.queue@1.0.0`, `edge.objects@1.0.0`.
+ * The managed Cloudflare backend and the self-host backend project the SAME
+ * facade: same methods, same option keys, same error names. Takoserver's
+ * ADR 0005 states this explicitly for object storage, and its self-host wrapper
+ * repeats it for KV and SQL.
+ *
+ * This module is a TYPE MIRROR of that contract plus the structural probes the
+ * lane selector uses. It deliberately contains no behaviour: the adapters that
+ * map a facade onto this repo's runtime ports live in `edge-kv.ts`,
+ * `edge-sql.ts`, `edge-queue.ts`, and `edge-objects.ts`.
+ *
+ * Source of truth (read, do not re-derive from memory):
+ *   takoserver `src/providers/cloudflare-managed-worker-wrapper.ts`
+ *     — `projectEnv`, `createKvAdapter`, `createSqlAdapter`,
+ *       `createQueueAdapter`, `createEdgeObjectsR2Adapter`
+ *   takoserver `src/providers/selfhost-worker-wrapper.ts`
+ *     — `projectEnv`, `createKvAdapter`, `createSqlAdapter`
+ *
+ * Every method rejects with an `Error` whose `name` is the portable error code
+ * (`invalid_key`, `invalid_value`, `value_too_large`, `metadata_too_large`,
+ * `invalid_cursor`, `invalid_argument`, `sql_error`, `numeric_out_of_range`,
+ * `busy`, `not_found`, `precondition_failed`, `range_not_satisfiable`,
+ * `invalid_body`, `message_too_large`, `batch_too_large`, `invalid_part`,
+ * `already_settled`, `backend_unavailable`). The adapters let those propagate
+ * unchanged so a caller sees the Host's own vocabulary.
+ */
+
+/** Limits the facades enforce. Mirrored so the adapters can fail before the
+ *  round-trip instead of surfacing an opaque `invalid_*` from the Host. */
+export const EDGE_KV_MAX_KEY_BYTES = 467;
+export const EDGE_KV_MAX_VALUE_BYTES = 26214400;
+/** `expirationTtlSeconds` is rejected outside this range by both backends. */
+export const EDGE_KV_MIN_EXPIRATION_TTL_SECONDS = 60;
+export const EDGE_KV_MAX_EXPIRATION_TTL_SECONDS = 315360000;
+export const EDGE_KV_MAX_LIST_LIMIT = 1000;
+export const EDGE_SQL_MAX_STATEMENTS = 100;
+export const EDGE_SQL_MAX_PARAMETERS = 100;
+export const EDGE_SQL_MAX_ROWS = 10000;
+export const EDGE_SQL_MAX_COLUMNS = 100;
+export const EDGE_QUEUE_MAX_MESSAGES = 100;
+
+/** A byte string on the wire. The facades never hand out raw `Uint8Array`. */
+export interface EdgeEncodedBytes {
+  readonly encoding: "base64";
+  readonly data: string;
+}
+
+/** Exactly what `edge.sql` accepts as a bound parameter and returns in a row. */
+export type EdgeSqlValue = null | number | string | EdgeEncodedBytes;
+
+export interface EdgeSqlStatement {
+  readonly sql: string;
+  readonly params?: readonly EdgeSqlValue[];
+}
+
+/**
+ * One statement's result. `rows` are RECORDS keyed by result-column name, not
+ * positional arrays — the single most consequential difference from D1, and the
+ * reason the lane has to rewrite the projection list (`sqlite-proxy-rows.ts`)
+ * before it can hand anything to Drizzle.
+ */
+export interface EdgeSqlResult {
+  readonly rows: readonly Readonly<Record<string, EdgeSqlValue>>[];
+  readonly rowsWritten: number;
+}
+
+/** `edge.sql@1.0.0`. */
+export interface EdgeSqlBinding {
+  execute(
+    sql: string,
+    params?: readonly EdgeSqlValue[],
+  ): Promise<EdgeSqlResult>;
+  /** `execute` restricted to statements that write nothing. */
+  query(sql: string, params?: readonly EdgeSqlValue[]): Promise<EdgeSqlResult>;
+  /** All-or-none. 1..100 statements, ordered, one Host round trip. */
+  transaction(
+    statements: readonly EdgeSqlStatement[],
+  ): Promise<readonly EdgeSqlResult[]>;
+}
+
+export interface EdgeKvPutOptions {
+  readonly expirationTtlSeconds?: number;
+  /** String values only; the Host projects a record of strings. */
+  readonly metadata?: Record<string, string>;
+}
+
+export interface EdgeKvListOptions {
+  readonly prefix?: string;
+  readonly cursor?: string;
+  readonly limit?: number;
+}
+
+/**
+ * A listed key carries its NAME ONLY. Neither backend returns the expiration or
+ * the metadata it stored, so `IKeyValueStore.list` reports those as absent on
+ * this lane.
+ */
+export interface EdgeKvListResult {
+  readonly keys: readonly { readonly name: string }[];
+  readonly listComplete: boolean;
+  readonly cursor?: string;
+}
+
+/** `edge.kv@1.0.0`. Values are always bytes; there is no `type` option. */
+export interface EdgeKvBinding {
+  get(key: string): Promise<ArrayBuffer | null>;
+  getWithMetadata(key: string): Promise<{
+    readonly value: ArrayBuffer;
+    readonly metadata?: Record<string, string>;
+  } | null>;
+  put(
+    key: string,
+    value: string | ArrayBuffer | ArrayBufferView,
+    options?: EdgeKvPutOptions,
+  ): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(options?: EdgeKvListOptions): Promise<EdgeKvListResult>;
+}
+
+export interface EdgeQueueSendOptions {
+  readonly delaySeconds?: number;
+}
+
+export interface EdgeQueueBatchItem {
+  readonly body: string | ArrayBuffer | ArrayBufferView;
+  readonly delaySeconds?: number;
+}
+
+/**
+ * `edge.queue@1.0.0` producer. Bodies are BYTES — there is no structured-clone
+ * path, so a JavaScript object has to be serialized by the caller. `send`
+ * returns the Host's acceptance id, which is not a provider dedupe id.
+ */
+export interface EdgeQueueBinding {
+  send(
+    body: string | ArrayBuffer | ArrayBufferView,
+    options?: EdgeQueueSendOptions,
+  ): Promise<string>;
+  sendBatch(
+    messages: readonly EdgeQueueBatchItem[],
+  ): Promise<readonly string[]>;
+}
+
+/** One message as the Host hands it to a declared `queue` handler. */
+export interface EdgeQueueMessage {
+  readonly id: string;
+  readonly timestampMillis: number;
+  readonly attempts: number;
+  readonly body: EdgeEncodedBytes;
+  acknowledge(): void;
+  /** `delaySeconds`, when given, must be >= 1. */
+  retry(options?: { readonly delaySeconds?: number }): void;
+}
+
+export interface EdgeQueueBatch {
+  readonly batchId: string;
+  readonly queue: string;
+  readonly messages: readonly EdgeQueueMessage[];
+  acknowledgeAll(): void;
+  retryAll(options?: { readonly delaySeconds?: number }): void;
+}
+
+export interface EdgeObjectMetadata {
+  readonly etag: string;
+  readonly size: number;
+  readonly contentType?: string;
+  readonly uploadedAtMillis?: number;
+}
+
+export interface EdgeObjectBody extends EdgeObjectMetadata {
+  readonly body: ReadableStream;
+  readonly partial: boolean;
+  readonly range?: { readonly offset: number; readonly length: number };
+}
+
+export interface EdgeObjectListResult {
+  readonly objects: readonly (EdgeObjectMetadata & { readonly key: string })[];
+  readonly prefixes: readonly string[];
+  readonly truncated: boolean;
+  readonly cursor?: string;
+}
+
+/**
+ * `edge.objects@1.0.0`. Note the fixed arities — the Host counts
+ * `arguments.length`, so `get(key)` with one argument is a type error and the
+ * adapter must pass `undefined` explicitly. There is no `customMetadata`, and a
+ * streaming `put` requires `contentLength`.
+ */
+export interface EdgeObjectsBinding {
+  head(key: string): Promise<EdgeObjectMetadata | null>;
+  get(
+    key: string,
+    options:
+      undefined | { readonly range?: { offset: number; length?: number } },
+  ): Promise<EdgeObjectBody | null>;
+  put(
+    key: string,
+    body: string | ArrayBuffer | ArrayBufferView | ReadableStream,
+    options:
+      | undefined
+      | {
+          readonly contentLength?: number;
+          readonly contentType?: string;
+        },
+  ): Promise<{ readonly etag: string; readonly size: number }>;
+  delete(key: string): Promise<void>;
+  list(
+    options:
+      | undefined
+      | {
+          readonly prefix?: string;
+          readonly delimiter?: string;
+          readonly cursor?: string;
+          readonly limit?: number;
+        },
+  ): Promise<EdgeObjectListResult>;
+}
+
+function hasMethods(value: unknown, names: readonly string[]): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as Record<string, unknown>;
+  for (const name of names) {
+    if (typeof record[name] !== "function") return false;
+  }
+  return true;
+}
+
+/**
+ * Structural probes.
+ *
+ * Only SOME bindings can be told apart by shape, and the difference matters:
+ *
+ *   decisive   `DB`     — `execute`/`query`/`transaction` (facade) against
+ *                         `prepare`/`batch` (D1). Disjoint method sets.
+ *   decisive   `MEDIA`  — R2 carries the multipart helpers the facade omits.
+ *   decisive   a queue *batch* — `acknowledgeAll` (facade) against `ackAll`
+ *                         (Cloudflare `MessageBatch`).
+ *   AMBIGUOUS  `KV`     — `edge.kv` and `KVNamespace` expose the same five
+ *                         method names.
+ *   AMBIGUOUS  a queue *producer* — both are `send`/`sendBatch`.
+ *
+ * That is why the lane is a DECLARED variable rather than something sniffed:
+ * two of the five bindings cannot be identified at all. The declaration is then
+ * cross-checked against the decisive bindings, so a Worker whose var and whose
+ * bindings disagree refuses to start instead of calling `kv.get(key, {type})`
+ * on a facade that would silently treat the options object as nothing.
+ */
+export function isEdgeSqlBinding(value: unknown): value is EdgeSqlBinding {
+  return (
+    hasMethods(value, ["execute", "query", "transaction"]) &&
+    typeof (value as Record<string, unknown>).prepare !== "function"
+  );
+}
+
+/** Cloudflare's `D1Database` is the `prepare`/`batch`/`exec` shape. */
+export function isNativeD1Database(value: unknown): boolean {
+  return (
+    hasMethods(value, ["prepare", "batch"]) &&
+    typeof (value as Record<string, unknown>).execute !== "function"
+  );
+}
+
+export function isEdgeQueueBatch(value: unknown): value is EdgeQueueBatch {
+  return (
+    hasMethods(value, ["acknowledgeAll", "retryAll"]) &&
+    Array.isArray((value as Record<string, unknown>).messages)
+  );
+}
+
+export function isEdgeObjectsBinding(
+  value: unknown,
+): value is EdgeObjectsBinding {
+  return (
+    hasMethods(value, ["head", "get", "put", "delete", "list"]) &&
+    // R2 exposes multipart helpers on the binding itself; the facade does not
+    // give a bucket-shaped object those names.
+    typeof (value as Record<string, unknown>).createMultipartUpload !==
+      "function" &&
+    // Arity is part of the facade's contract and is asserted rather than
+    // assumed: the Host checks `arguments.length`, so `get` and `list` take
+    // their options slot even when it is `undefined`. Anything bucket-shaped
+    // whose `get` takes one argument is some other adapter, not this facade.
+    (value as { get: (...args: unknown[]) => unknown }).get.length === 2
+  );
+}
+
+/** Cloudflare's `R2Bucket`. */
+export function isNativeR2Bucket(value: unknown): boolean {
+  return hasMethods(value, [
+    "head",
+    "get",
+    "put",
+    "delete",
+    "list",
+    "createMultipartUpload",
+  ]);
+}
+
+/** Decode one `{encoding:"base64"}` value into bytes. */
+export function decodeEdgeBytes(value: EdgeEncodedBytes): Uint8Array {
+  const binary = atob(value.data);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+/** Encode bytes into the facade's wire value. */
+export function encodeEdgeBytes(bytes: Uint8Array): EdgeEncodedBytes {
+  let binary = "";
+  // Chunked so a large blob does not blow the argument limit of `apply`.
+  const CHUNK = 0x8000;
+  for (let index = 0; index < bytes.length; index += CHUNK) {
+    binary += String.fromCharCode(
+      ...bytes.subarray(index, Math.min(index + CHUNK, bytes.length)),
+    );
+  }
+  return { encoding: "base64", data: btoa(binary) };
+}
+
+export function isEdgeEncodedBytes(value: unknown): value is EdgeEncodedBytes {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as EdgeEncodedBytes).encoding === "base64" &&
+    typeof (value as EdgeEncodedBytes).data === "string"
+  );
+}

package/src/backend/runtime/edge-kv.ts

@@ -0,0 +1,204 @@
+/**
+ * `edge.kv@1.0.0` → {@link IKeyValueStore}.
+ *
+ * The app's port and the facade disagree in three places, and each disagreement
+ * is resolved here rather than at the call sites:
+ *
+ *  - READS. `IKeyValueStore.get` selects `text` / `json` / `arrayBuffer`; the
+ *    facade always returns bytes. The decode happens here.
+ *  - EXPIRY. The port carries Cloudflare's pair (`expirationTtl` relative,
+ *    `expiration` absolute); the facade accepts only `expirationTtlSeconds`. An
+ *    absolute instant is converted against the current clock.
+ *  - LISTING. The facade returns `{name}` only and calls the flag
+ *    `listComplete`; the port expects `list_complete` and optional
+ *    `expiration` / `metadata`. Those two fields are ABSENT on this lane — the
+ *    Host does not return them — so nothing may be inferred from their absence.
+ */
+
+import type { IKeyValueStore } from "./types.ts";
+import {
+  EDGE_KV_MAX_EXPIRATION_TTL_SECONDS,
+  EDGE_KV_MIN_EXPIRATION_TTL_SECONDS,
+  type EdgeKvBinding,
+  type EdgeKvPutOptions,
+} from "./edge-facades.ts";
+import { nowSeconds, readStream } from "./shared.ts";
+
+/** A put option the facade cannot express. */
+export class EdgeKeyValueOptionError extends TypeError {
+  constructor(message: string) {
+    super(message);
+    this.name = "EdgeKeyValueOptionError";
+  }
+}
+
+/** A stored value could not be read back in the requested shape. */
+export class EdgeKeyValueValueError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "EdgeKeyValueValueError";
+  }
+}
+
+/**
+ * Resolve the port's expiry pair into the single value `edge.kv` takes.
+ *
+ * `expiration` is an absolute UNIX second; the facade has no equivalent, so it
+ * becomes the remaining seconds from now. Both backends reject a TTL under 60
+ * seconds (as does Cloudflare KV itself), so a shorter one is refused here with
+ * a message that names the caller's own value instead of surfacing the Host's
+ * bare `invalid_value`.
+ */
+export function resolveEdgeKvExpirationTtl(
+  options?: { readonly expirationTtl?: number; readonly expiration?: number },
+  now: () => number = nowSeconds,
+): number | undefined {
+  const ttl =
+    options?.expirationTtl !== undefined
+      ? options.expirationTtl
+      : options?.expiration !== undefined
+        ? Math.ceil(options.expiration - now())
+        : undefined;
+  if (ttl === undefined) return undefined;
+  const seconds = Math.ceil(ttl);
+  if (!Number.isSafeInteger(seconds)) {
+    throw new EdgeKeyValueOptionError(
+      `edge.kv: expiration resolves to ${ttl}, which is not a whole number of seconds`,
+    );
+  }
+  if (seconds < EDGE_KV_MIN_EXPIRATION_TTL_SECONDS) {
+    throw new EdgeKeyValueOptionError(
+      `edge.kv: expiration resolves to ${seconds}s, under the ` +
+        `${EDGE_KV_MIN_EXPIRATION_TTL_SECONDS}s floor both Takoserver and ` +
+        `Cloudflare KV enforce; store a longer-lived entry or carry the ` +
+        `deadline inside the value`,
+    );
+  }
+  if (seconds > EDGE_KV_MAX_EXPIRATION_TTL_SECONDS) {
+    throw new EdgeKeyValueOptionError(
+      `edge.kv: expiration resolves to ${seconds}s, over the ` +
+        `${EDGE_KV_MAX_EXPIRATION_TTL_SECONDS}s ceiling`,
+    );
+  }
+  return seconds;
+}
+
+/**
+ * The facade stores a record of STRINGS. The port's `Record<string, unknown>`
+ * is therefore only usable when every value already is one; anything else is
+ * refused rather than stringified, because a silent `String(value)` would round
+ * -trip differently on the two lanes.
+ */
+function projectMetadata(
+  metadata: Record<string, unknown> | undefined,
+): Record<string, string> | undefined {
+  if (metadata === undefined) return undefined;
+  const projected: Record<string, string> = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (typeof value !== "string") {
+      throw new EdgeKeyValueOptionError(
+        `edge.kv: metadata."${key}" is ${typeof value}; the facade stores ` +
+          `string values only`,
+      );
+    }
+    projected[key] = value;
+  }
+  return projected;
+}
+
+async function toBytes(
+  value: string | ArrayBuffer | ReadableStream,
+): Promise<string | ArrayBuffer | Uint8Array> {
+  if (typeof value === "string" || value instanceof ArrayBuffer) return value;
+  return await readStream(value as ReadableStream<Uint8Array>);
+}
+
+export class EdgeKeyValueStore implements IKeyValueStore {
+  constructor(
+    private readonly kv: EdgeKvBinding,
+    private readonly now: () => number = nowSeconds,
+  ) {}
+
+  get(key: string, options?: { type?: "text" }): Promise<string | null>;
+  get<T = unknown>(key: string, options: { type: "json" }): Promise<T | null>;
+  get(
+    key: string,
+    options: { type: "arrayBuffer" },
+  ): Promise<ArrayBuffer | null>;
+  async get(
+    key: string,
+    options?: { type?: "text" | "json" | "arrayBuffer" },
+  ): Promise<string | ArrayBuffer | unknown | null> {
+    const value = await this.kv.get(key);
+    if (value === null) return null;
+    const type = options?.type ?? "text";
+    if (type === "arrayBuffer") return value;
+    const text = new TextDecoder().decode(value);
+    if (type === "json") {
+      // A present-but-unparseable entry is a fault, not a miss: reporting it as
+      // `null` would be indistinguishable from "no such key" and would silently
+      // reset whatever state the entry held. The other lanes in this repo
+      // (MemoryKV, the managed runtime) both raise here too.
+      try {
+        return JSON.parse(text) as unknown;
+      } catch (error) {
+        throw new EdgeKeyValueValueError(
+          `edge.kv: "${key}" is present but is not JSON: ${String(error)}`,
+        );
+      }
+    }
+    return text;
+  }
+
+  async put(
+    key: string,
+    value: string | ArrayBuffer | ReadableStream,
+    options?: {
+      expirationTtl?: number;
+      expiration?: number;
+      metadata?: Record<string, unknown>;
+    },
+  ): Promise<void> {
+    const expirationTtlSeconds = resolveEdgeKvExpirationTtl(options, this.now);
+    const metadata = projectMetadata(options?.metadata);
+    const put: EdgeKvPutOptions = {
+      ...(expirationTtlSeconds === undefined ? {} : { expirationTtlSeconds }),
+      ...(metadata === undefined ? {} : { metadata }),
+    };
+    await this.kv.put(key, await toBytes(value), put);
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.kv.delete(key);
+  }
+
+  async list(options?: {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+  }): Promise<{
+    keys: Array<{ name: string; expiration?: number; metadata?: unknown }>;
+    list_complete: boolean;
+    cursor?: string;
+  }> {
+    const result = await this.kv.list({
+      ...(options?.prefix === undefined ? {} : { prefix: options.prefix }),
+      ...(options?.cursor === undefined ? {} : { cursor: options.cursor }),
+      ...(options?.limit === undefined ? {} : { limit: options.limit }),
+    });
+    return {
+      keys: result.keys.map((entry) => ({ name: entry.name })),
+      list_complete: result.listComplete,
+      // The facade omits the cursor once the listing is complete; the port
+      // says the same thing with `undefined`.
+      cursor: result.listComplete ? undefined : result.cursor,
+    };
+  }
+}
+
+export function wrapEdgeKv(
+  kv: EdgeKvBinding,
+  now?: () => number,
+): IKeyValueStore {
+  return new EdgeKeyValueStore(kv, now);
+}