@sproutboat/wire 0.14.6 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @sproutboat/wire
 
+## 0.15.0
+
+### Minor Changes
+
+- 9b15539: KV matches workerd from compatibility date `2026-10-25`:
+  
+  - `get`, `getWithMetadata`, `put`, `delete` and `list` return Promises, and errors reject them.
+  - `get(key, type)` takes `"text"`, `"json"`, `"arrayBuffer"` and `"stream"`, and `get([keys])` returns a `Map`.
+  - `getWithMetadata(key, type)` returns `{ value, metadata, cacheStatus }`.
+  - `put(key, value, { expiration, expirationTtl, metadata })` takes strings, bytes and `ReadableStream`s, and stores the metadata.
+  - `list({ prefix, limit, cursor })` returns `{ keys: [{ name, expiration?, metadata? }], list_complete, cursor?, cacheStatus }` and pages at up to 1,000 keys.
+  - Keys, values, expirations, metadata and list limits fail with KV's own errors. For example: `Key name cannot be empty.`, `KV PUT failed: 414 UTF-8 encoded length of 513 exceeds key length limit of 512.`, `KV PUT failed: 400 Invalid expiration_ttl of 30. Expiration TTL must be at least 60.`, and `KV PUT failed: 413 Metadata length of 1110 exceeds limit of 1024.`
+  
+  Earlier dates keep the synchronous shim. Two changes apply at every date:
+  
+  - **A `list()` prefix now matches exactly.** It used SQL `LIKE`, so it ignored case and read `_` and `%` as wildcards. For example, the prefix `a_` also listed `ab`, and `a` also listed `AB`.
+  - **Both transports store KV metadata in a new column.** It's added to existing stores when they open.
+
+### Patch Changes
+
+- Updated dependencies [9b15539]
+- Updated dependencies [1c36119]
+- Updated dependencies [3cad1f0]
+  - @sproutboat/runtime@0.26.0
+
 ## 0.14.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/wire",
-  "version": "0.14.6",
+  "version": "0.15.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -23,6 +23,6 @@
   },
   "dependencies": {
     "@sproutboat/assets": "^0.3.0",
-    "@sproutboat/runtime": "^0.25.0"
+    "@sproutboat/runtime": "^0.26.0"
   }
 }

package/src/broker.test.ts

@@ -114,7 +114,7 @@ test("#233: a KV value put as bytes is flagged binary and survives an existing s
   const bytes = Array.from({ length: 256 }, (_, i) => String.fromCharCode(i)).join("");
   await b.dispatch({ op: "kv.put", ns: "CACHE", key: "bin", value: bytes, binary: true });
   await b.dispatch({ op: "kv.put", ns: "CACHE", key: "txt", value: "café" });
-  expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "bin" })).toEqual({ ok: true, found: true, value: bytes, binary: true });
+  expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "bin" })).toMatchObject({ ok: true, found: true, value: bytes, binary: true });
   expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "txt" })).toMatchObject({ value: "café", binary: false });
   // Overwriting a binary value with text clears the flag.
   await b.dispatch({ op: "kv.put", ns: "CACHE", key: "bin", value: "now text" });
@@ -126,12 +126,36 @@ test("KV put / get / list / delete, scoped to a bound namespace", async () => {
   expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "k" })).toEqual({ ok: true, found: false, value: null });
   await b.dispatch({ op: "kv.put", ns: "CACHE", key: "k", value: "v" });
   await b.dispatch({ op: "kv.put", ns: "CACHE", key: "k2", value: "v2" });
-  expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "k" })).toEqual({ ok: true, found: true, value: "v", binary: false });
-  expect(await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "k" })).toEqual({ ok: true, keys: ["k", "k2"] });
+  expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "k" })).toMatchObject({ ok: true, found: true, value: "v", binary: false });
+  expect(await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "k" })).toMatchObject({ ok: true, keys: ["k", "k2"] });
   await b.dispatch({ op: "kv.delete", ns: "CACHE", key: "k" });
   expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "k" })).toMatchObject({ found: false });
 });
 
+test("KV metadata, expiration and paged list (the shim from 2026-10-25); the prefix matches exactly", async () => {
+  const b = make({ bindings: { kv: ["CACHE"] } });
+  const at = Math.floor(Date.now() / 1000) + 3600;
+  await b.dispatch({ op: "kv.put", ns: "CACHE", key: "a", value: "1", metadata: '{"t":1}' });
+  await b.dispatch({ op: "kv.put", ns: "CACHE", key: "b", value: "2", expiration: at });
+  await b.dispatch({ op: "kv.put", ns: "CACHE", key: "c", value: "3" });
+  await b.dispatch({ op: "kv.put", ns: "CACHE", key: "a_x", value: "4" });
+  await b.dispatch({ op: "kv.put", ns: "CACHE", key: "AB", value: "5" });
+  expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "a" })).toMatchObject({ metadata: '{"t":1}', expiration: null });
+  expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "b" })).toMatchObject({ metadata: null, expiration: at });
+  // LIKE matched "ab" for "a_" and "AB" for "a"; the prefix is now exact and case-sensitive.
+  expect((await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "a_" })).keys).toEqual(["a_x"]);
+  expect((await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "a" })).keys).toEqual(["a", "a_x"]);
+  const first = await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "", limit: 2, cursor: "" });
+  expect(first).toMatchObject({ keys: ["AB", "a"], list_complete: false, cursor: "a" });
+  expect(first.entries).toEqual([
+    { name: "AB", expiration: null, metadata: null },
+    { name: "a", expiration: null, metadata: '{"t":1}' },
+  ]);
+  const rest = await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "", limit: 2, cursor: "a" });
+  expect(rest).toMatchObject({ keys: ["a_x", "b"], list_complete: false, cursor: "b" });
+  expect(await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "", limit: 2, cursor: "b" })).toMatchObject({ keys: ["c"], list_complete: true, cursor: "" });
+});
+
 test("KV expirationTtl under 60 seconds is rejected, matching CF", async () => {
   const b = make({ bindings: { kv: ["CACHE"] } });
   await expect(b.dispatch({ op: "kv.put", ns: "CACHE", key: "k", value: "v", expirationTtl: 59 })).rejects.toThrow(
@@ -149,7 +173,7 @@ test("a key past its expiration reads as absent and is omitted from list", async
     found: false,
     value: null,
   });
-  expect(await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "" })).toEqual({ ok: true, keys: ["fresh"] });
+  expect(await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "" })).toMatchObject({ ok: true, keys: ["fresh"] });
 });
 
 test("an unbound KV namespace is rejected", async () => {
@@ -883,7 +907,7 @@ test("resource-backed KV persists across brokers and is shared by id", async ()
       resourceDir,
       bindings: { kv: ["SHORTENER"], resources: { SHORTENER: { kind: "kv", id: kvId } } },
     });
-    expect(await second.dispatch({ op: "kv.get", ns: "SHORTENER", key: "a" })).toEqual({
+    expect(await second.dispatch({ op: "kv.get", ns: "SHORTENER", key: "a" })).toMatchObject({
       ok: true,
       found: true,
       binary: false,

package/src/broker.ts

@@ -301,6 +301,8 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     // #233 — 1 when the value was put as bytes (stored one char per byte), so get()
     // can hand back exact bytes or decoded text depending on the requested type.
     if (!kvColumns.some((column) => column.name === "binary")) conn.exec("ALTER TABLE kv ADD COLUMN binary INTEGER NOT NULL DEFAULT 0");
+    // A key's metadata (put(key, value, { metadata })), as JSON text.
+    if (!kvColumns.some((column) => column.name === "metadata")) conn.exec("ALTER TABLE kv ADD COLUMN metadata TEXT");
     // #56 — no `body` column: an object's bytes live in their own file under
     // `r2Dir` (or an in-memory map for `:memory:`), never in the SQLite row.
     // Doubling every object through SQLite's own page cache on top of the
@@ -521,29 +523,31 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   };
 
   type KvStmts = {
-    get: Statement<{ value: string; expires_at: number | null; binary: number }, [string, string]>;
-    put: Statement<unknown, [string, string, string, number | null, number]>;
+    get: Statement<{ value: string; expires_at: number | null; binary: number; metadata: string | null }, [string, string]>;
+    put: Statement<unknown, [string, string, string, number | null, number, string | null]>;
     del: Statement<unknown, [string, string]>;
-    list: Statement<{ key: string }, [string, string, number]>;
+    list: Statement<{ key: string; expires_at: number | null; metadata: string | null }, [string, string, string, number, number]>;
   };
   const kvStmtCache = new Map<Database, KvStmts>();
   const kvStmts = (store: Database): KvStmts => {
     let stmts = kvStmtCache.get(store);
     if (!stmts) {
       stmts = {
-        get: store.query<{ value: string; expires_at: number | null; binary: number }, [string, string]>(
-          "SELECT value, expires_at, binary FROM kv WHERE ns = ? AND key = ?",
+        get: store.query<{ value: string; expires_at: number | null; binary: number; metadata: string | null }, [string, string]>(
+          "SELECT value, expires_at, binary, metadata FROM kv WHERE ns = ? AND key = ?",
         ),
         put: store.query(
-          "INSERT INTO kv (ns, key, value, expires_at, binary) VALUES (?1, ?2, ?3, ?4, ?5) " +
-            "ON CONFLICT (ns, key) DO UPDATE SET value = ?3, expires_at = ?4, binary = ?5",
+          "INSERT INTO kv (ns, key, value, expires_at, binary, metadata) VALUES (?1, ?2, ?3, ?4, ?5, ?6) " +
+            "ON CONFLICT (ns, key) DO UPDATE SET value = ?3, expires_at = ?4, binary = ?5, metadata = ?6",
         ),
         del: store.query("DELETE FROM kv WHERE ns = ? AND key = ?"),
         // #58 — an expired row is filtered out here; a periodic sweep to hard-delete
         // it is a separate concern (ponytail: rows accumulate until touched by a
         // get/list/put on the same key/prefix, add a cron sweep if that matters).
-        list: store.query<{ key: string }, [string, string, number]>(
-          "SELECT key FROM kv WHERE ns = ? AND key LIKE ? || '%' AND (expires_at IS NULL OR expires_at > ?) ORDER BY key LIMIT 1000",
+        // The prefix matches exactly: LIKE ignored case and read "_" and "%" as wildcards.
+        list: store.query<{ key: string; expires_at: number | null; metadata: string | null }, [string, string, string, number, number]>(
+          "SELECT key, expires_at, metadata FROM kv WHERE ns = ?1 AND substr(key, 1, length(?2)) = ?2 AND key > ?3 " +
+            "AND (expires_at IS NULL OR expires_at > ?4) ORDER BY key LIMIT ?5",
         ),
       };
       kvStmtCache.set(store, stmts);
@@ -1285,11 +1289,25 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
           stmts.del.run(part, str(msg.key));
           return { ok: true, found: false, value: null };
         }
-        return { ok: true, found: true, value: row.value, binary: row.binary === 1 };
+        return {
+          ok: true,
+          found: true,
+          value: row.value,
+          binary: row.binary === 1,
+          metadata: row.metadata,
+          expiration: row.expires_at == null ? null : Math.floor(row.expires_at / 1000),
+        };
       }
       case "kv.put": {
         const { store, part } = storeFor("kv", requireKv(msg.ns));
-        kvStmts(store).put.run(part, str(msg.key), str(msg.value), kvExpiresAt(msg), msg.binary === true ? 1 : 0);
+        kvStmts(store).put.run(
+          part,
+          str(msg.key),
+          str(msg.value),
+          kvExpiresAt(msg),
+          msg.binary === true ? 1 : 0,
+          msg.metadata == null ? null : str(msg.metadata),
+        );
         return { ok: true };
       }
       case "kv.delete": {
@@ -1299,11 +1317,23 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       }
       case "kv.list": {
         const { store, part } = storeFor("kv", requireKv(msg.ns));
+        // With a limit (the shim from 2026-10-25): a page after the cursor (the previous page's
+        // last key), with expirations and metadata. Without one: up to 1,000 keys, as before.
+        const paged = isNumber(msg.limit);
+        const limit = paged ? Math.max(0, Math.floor(Number(msg.limit))) : 1000;
+        const rows = kvStmts(store).list.all(part, str(msg.prefix), paged ? str(msg.cursor) : "", Date.now(), paged ? limit + 1 : limit);
+        const page = rows.slice(0, limit);
+        const complete = !paged || rows.length <= limit;
         return {
           ok: true,
-          keys: kvStmts(store)
-            .list.all(part, str(msg.prefix), Date.now())
-            .map((r) => r.key),
+          keys: page.map((r) => r.key),
+          entries: page.map((r) => ({
+            name: r.key,
+            expiration: r.expires_at == null ? null : Math.floor(r.expires_at / 1000),
+            metadata: r.metadata,
+          })),
+          list_complete: complete,
+          cursor: complete ? "" : (page[page.length - 1]?.key ?? ""),
         };
       }
       case "cache.match": {