tapimo 0.0.2 → 0.1.0

package/src/internal/Store.ts

@@ -1,3 +1,5 @@
+import { Json } from 'ox'
+
 /** Minimal string store contract used by Tempo API internals. */
 export type Store = {
   /** Deletes a key. */
@@ -26,6 +28,22 @@ export type Store = {
   }>
   /** Writes a string value, optionally with a time-to-live. */
   put(key: string, value: string, options?: Store.PutOptions): Promise<void>
+  /**
+   * Optional atomic compare-and-swap: writes `next` only when the current
+   * value equals `expected` (`null` = only-if-absent) and reports whether the
+   * write happened. Implement when the backend can execute the compare and
+   * write in one place (in-memory, inside a Durable Object); consumers go
+   * through the {@link update} helper, which falls back to a get + put when
+   * this is absent.
+   */
+  swap?:
+    | ((
+        key: string,
+        expected: null | string,
+        next: string,
+        options?: Store.PutOptions,
+      ) => Promise<boolean>)
+    | undefined
   /**
    * Store kind discriminant. `'state'` marks an authoritative, enumerable
    * store ({@link State}); `'cache'` marks a cache (e.g. the Web Cache,
@@ -102,6 +120,50 @@ export async function increment(
   return count
 }
 
+/**
+ * Atomically transforms a value on a store: reads the current value, applies
+ * `fn`, and writes the result, returning the written value.
+ *
+ * Uses the store's native {@link Store.swap} compare-and-swap when implemented,
+ * re-running `fn` on contention (optimistic concurrency, bounded by
+ * `attempts`). Otherwise falls back to a get + put read-modify-write, which
+ * can lose concurrent writes — fine for dev/in-process backends, not for
+ * contended distributed state.
+ */
+export async function update(
+  store: Store,
+  key: string,
+  fn: (current: null | string) => string,
+  options: update.Options = {},
+): Promise<string> {
+  const { attempts = 8, ...put } = options
+
+  if (!store.swap) {
+    const next = fn(await store.get(key))
+    await store.put(key, next, put)
+    return next
+  }
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    const current = await store.get(key)
+    const next = fn(current)
+    if (await store.swap(key, current, next, put)) return next
+  }
+  throw new UpdateContentionError(key, attempts)
+}
+
+export declare namespace update {
+  /** Options for {@link update}. */
+  type Options = Store.PutOptions & {
+    /**
+     * Maximum compare-and-swap attempts before failing with
+     * {@link UpdateContentionError}.
+     * @default 8
+     */
+    attempts?: number | undefined
+  }
+}
+
 /** Creates an in-memory store with TTL support. */
 export function memory(options: memory.Options = {}): State {
   // Track value + optional expiration in one cell so `get` can lazily evict
@@ -148,6 +210,14 @@ export function memory(options: memory.Options = {}): State {
       const expiresAt = options.ttl === undefined ? undefined : Date.now() + options.ttl
       cells.set(key, { expiresAt, value })
     },
+    // Native swap: the compare and write are synchronous, so concurrent
+    // consumers cannot interleave between them.
+    async swap(key, expected, next, options = {}) {
+      if ((read(key)?.value ?? null) !== expected) return false
+      const expiresAt = options.ttl === undefined ? undefined : Date.now() + options.ttl
+      cells.set(key, { expiresAt, value: next })
+      return true
+    },
   })
 }
 
@@ -302,6 +372,19 @@ function durableObjectStorage(storage: durableObject.Storage): State {
 
       await storage.put(key, durableObjectValue(value, options))
     },
+    // Native swap: the object is single-threaded and its input gate holds
+    // other events while storage operations are in flight, so the compare and
+    // write cannot interleave with another request.
+    async swap(key, expected, next, options = {}) {
+      const current = (await durableObjectRead(storage, key, await storage.get(key)))?.value ?? null
+      if (current !== expected) return false
+      if (options.ttl !== undefined && options.ttl <= 0) {
+        await storage.delete(key)
+        return true
+      }
+      await storage.put(key, durableObjectValue(next, options))
+      return true
+    },
   })
 }
 
@@ -341,12 +424,20 @@ export declare namespace durableObject {
   /**
    * Minimal Durable Object RPC stub shape used by this adapter — just the store
    * operations (no `type` discriminant, which an RPC stub doesn't carry).
-   * `increment` is required: the stub mirrors the `tapimo/cloudflare`
-   * `DurableObject` class, whose RPC surface implements it.
+   * `increment` and `swap` are required: the stub mirrors the
+   * `tapimo/cloudflare` `DurableObject` class, whose RPC surface implements
+   * them.
    */
-  type Stub = Omit<Store, 'increment' | 'type'> & {
+  type Stub = Omit<Store, 'increment' | 'swap' | 'type'> & {
     /** Atomically increments an integer counter inside the object. */
     increment(key: string, options?: Store.PutOptions): Promise<number>
+    /** Atomically compares-and-swaps a value inside the object. */
+    swap(
+      key: string,
+      expected: null | string,
+      next: string,
+      options?: Store.PutOptions,
+    ): Promise<boolean>
   }
 }
 
@@ -364,7 +455,7 @@ export async function memoize<value>(
   const raw = await store.get(key)
   if (raw) {
     try {
-      return JSON.parse(raw) as value
+      return Json.parse(raw) as value
     } catch {
       // Corrupt entries are treated as misses so the next call refreshes.
     }
@@ -379,7 +470,7 @@ export async function memoize<value>(
   // fetch is still in flight.
   const flight = (async () => {
     const value = await fetch()
-    await store.put(key, JSON.stringify(value), { ttl })
+    await store.put(key, Json.stringify(value), { ttl })
     return value
   })()
   flights.set(key, flight)
@@ -450,6 +541,12 @@ function durableObjectStub(
     async put(key, value, options) {
       await durableObjectRetry(() => stub(key).put(key, value, options))
     },
+    // Native RPC swap: the compare-and-write runs inside the object. A lost
+    // response retried after a successful write compares stale and returns
+    // false, which optimistic callers already handle as contention.
+    async swap(key, expected, next, options) {
+      return durableObjectRetry(() => stub(key).swap(key, expected, next, options))
+    },
   })
 }
 
@@ -482,7 +579,7 @@ function cloudflareKvExpirationTtl(ttl: number | undefined) {
   return seconds
 }
 
-const durableObjectValueType = 'cadent:store:v1'
+const durableObjectValueType = 'tempo-api:store:v1'
 
 type DurableObjectValue = {
   expiresAt?: number | undefined
@@ -524,3 +621,12 @@ function isDurableObjectValue(value: unknown): value is DurableObjectValue {
       typeof value.expiresAt === 'number')
   )
 }
+
+/** Thrown when {@link update} exhausts its compare-and-swap attempts. */
+export class UpdateContentionError extends Error {
+  override name = 'Store.UpdateContentionError'
+
+  constructor(key: string, attempts: number) {
+    super(`Store update on "${key}" lost ${attempts} compare-and-swap attempts.`)
+  }
+}

package/src/internal/VerifiedTokens.test.ts

@@ -1,49 +1,38 @@
 import type { Context } from 'hono'
 
+import * as TestApp from '../../test/App.js'
 import type * as App from '../App.js'
-import * as Store from './Store.js'
+import * as Db from '../db/Db.js'
+import * as core_VerifiedTokens from '../db/tables/verifiedTokens.js'
 import * as VerifiedTokens from './VerifiedTokens.js'
 
-// Seeds a store with the documented head + versioned blob layout for a
-// chain so `read`/`snapshot` can load it.
+// Publishes a list at an explicit version so `read`/`snapshot` can load it
+// (the write API generates monotonic versions; tests pin readable ones). Skips
+// a matching version so vitest retries on a shared db stay idempotent.
 async function seed(
-  store: Store.State,
+  db: Db.Db,
   chainId: number,
   version: string,
   list: readonly VerifiedTokens.Token[],
 ) {
-  const updatedAt = '2024-01-01T00:00:00.000Z'
-  await store.put(
-    `verified-token:v1:${chainId}:snapshot:${version}`,
-    JSON.stringify({ chainId, schema: 1, tokens: list, updatedAt, version }),
-  )
-  await store.put(
-    `verified-token:v1:${chainId}:head`,
-    JSON.stringify({ chainId, count: list.length, schema: 1, updatedAt, version }),
-  )
+  if ((await core_VerifiedTokens.head(db, chainId))?.version === version) return
+  await core_VerifiedTokens.publish(db, chainId, {
+    tokens: list,
+    updatedAt: '2024-01-01T00:00:00.000Z',
+    version,
+  })
 }
 
-// Store wrapper that counts `get` calls per key prefix so tests can assert the
-// hot path does zero (fresh) or head-only (soft-stale) I/O.
-function counting(store: Store.State) {
-  const counts = { head: 0, snapshot: 0 }
-  return {
-    counts,
-    store: Store.from({
-      ...store,
-      get(key: string) {
-        if (key.endsWith(':head')) counts.head++
-        else if (key.includes(':snapshot:')) counts.snapshot++
-        return store.get(key)
-      },
-    }),
-  }
-}
+// A database whose every query fails (nothing listens on port 1), proving a
+// code path performed zero database I/O when a test passes with it.
+const unreachable = () =>
+  Db.postgres({ connectionString: 'postgresql://postgres:postgres@127.0.0.1:1/none' })
 
-// Minimal context that returns a verified-tokens feature config (or none).
-function context(config?: App.create.VerifiedTokens): Context<App.Environment> {
+// Minimal context serving the verified-tokens feature config and the app db
+// (both the fresh and cached bindings, as `App.create` sets them).
+function context(db: Db.Db, config?: App.create.VerifiedTokens): Context<App.Environment> {
   return {
-    get: (key: string) => (key === 'verifiedTokens' ? config : undefined),
+    get: (key: string) => (key === 'verifiedTokens' ? (config ?? {}) : key === 'db' || key === 'dbCached' ? db : undefined), // prettier-ignore
   } as unknown as Context<App.Environment>
 }
 
@@ -111,14 +100,14 @@ describe('compile', () => {
 })
 
 describe('read', () => {
-  test('returns null when the chain has no head', async () => {
-    expect(await VerifiedTokens.read(Store.memory(), 4217)).toBe(null)
+  test('returns null when the chain has no list', async () => {
+    expect(await VerifiedTokens.read(TestApp.database(), 4217)).toBe(null)
   })
 
-  test('compiles the snapshot the head points at', async () => {
-    const store = Store.memory()
-    await seed(store, 4217, 'v1', tokens)
-    const snapshot = await VerifiedTokens.read(store, 4217)
+  test('compiles the latest snapshot', async () => {
+    const db = TestApp.database()
+    await seed(db, 4217, 'v1', tokens)
+    const snapshot = await VerifiedTokens.read(db, 4217)
     expect(snapshot?.version).toBe('v1')
     expect(snapshot?.list.map((token) => token.symbol)).toMatchInlineSnapshot(`
       [
@@ -129,21 +118,13 @@ describe('read', () => {
     `)
   })
 
-  test('throws when the head points at a missing snapshot blob', async () => {
-    const store = Store.memory()
-    await store.put(
-      'verified-token:v1:4217:head',
-      JSON.stringify({
-        chainId: 4217,
-        count: 0,
-        schema: 1,
-        updatedAt: '2024-01-01T00:00:00.000Z',
-        version: 'ghost',
-      }),
-    )
-    await expect(VerifiedTokens.read(store, 4217)).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[VerifiedTokens.TornStateError: verified-token head for chain 4217 points at missing snapshot version "ghost".]`,
-    )
+  test('serves the latest publish as the head', async () => {
+    const db = TestApp.database()
+    await seed(db, 4217, 'v1', tokens)
+    await seed(db, 4217, 'v2', tokens.slice(0, 1))
+    const snapshot = await VerifiedTokens.read(db, 4217)
+    expect(snapshot?.version).toBe('v2')
+    expect(snapshot?.list.map((token) => token.symbol)).toEqual(['aUSD'])
   })
 })
 
@@ -157,51 +138,54 @@ describe('snapshot', () => {
     expect(snapshot.list).toEqual([])
   })
 
-  // The following cases run in order and share the module-level per-isolate cache
-  // for chain 42431: cold load → fresh → soft-stale unchanged → soft-stale changed.
-  test('cold-loads from the store when a head exists', async () => {
-    const store = Store.memory()
-    await seed(store, 42431, 'v1', tokens)
-    const snapshot = await VerifiedTokens.snapshot(context({ store }), 42431)
+  // The following cases run in order and share the module-level per-isolate
+  // cache for chain 42431 (and one seeded db): cold load → fresh → soft-stale
+  // unchanged → soft-stale changed.
+  const db = TestApp.database()
+
+  test('cold-loads from the database when a list exists', async () => {
+    await seed(db, 42431, 'v1', tokens)
+    const snapshot = await VerifiedTokens.snapshot(context(db), 42431)
     expect(snapshot.version).toBe('v1')
     expect(snapshot.byAddress.size).toBe(tokens.length)
   })
 
-  test('serves fresh lookups with zero store I/O', async () => {
-    const { counts, store } = counting(Store.memory())
-    const snapshot = await VerifiedTokens.snapshot(context({ refreshMs: 60_000, store }), 42431)
+  test('serves fresh lookups with zero database I/O', async () => {
+    // Every query against this db fails, so a pass proves the fresh window
+    // never touched the database.
+    const snapshot = await VerifiedTokens.snapshot(
+      context(unreachable(), { refreshMs: 60_000 }),
+      42431,
+    )
     expect(snapshot.version).toBe('v1')
-    expect(counts).toEqual({ head: 0, snapshot: 0 })
   })
 
-  test('soft-stale reads only the head when the version is unchanged', async () => {
-    const base = Store.memory()
-    await seed(base, 42431, 'v1', tokens)
-    const { counts, store } = counting(base)
+  test('soft-stale keeps serving an unchanged version', async () => {
     // refreshMs 0 forces the soft-stale path; the current snapshot is returned
     // immediately and the head-only refresh runs in the background.
-    const snapshot = await VerifiedTokens.snapshot(context({ refreshMs: 0, store }), 42431)
+    const snapshot = await VerifiedTokens.snapshot(context(db, { refreshMs: 0 }), 42431)
     expect(snapshot.version).toBe('v1')
     await flush()
-    expect(counts).toEqual({ head: 1, snapshot: 0 })
   })
 
   test('soft-stale recompiles when the version changed', async () => {
-    const store = Store.memory()
-    await seed(store, 42431, 'v2', tokens.slice(0, 1))
+    await seed(db, 42431, 'v2', tokens.slice(0, 1))
     // Stale call returns the existing v1 immediately, refreshes to v2 in background.
-    const stale = await VerifiedTokens.snapshot(context({ refreshMs: 0, store }), 42431)
+    const stale = await VerifiedTokens.snapshot(context(db, { refreshMs: 0 }), 42431)
     expect(stale.version).toBe('v1')
-    await flush()
-    // Next call sees the refreshed cell (fresh window) and returns v2.
-    const fresh = await VerifiedTokens.snapshot(context({ refreshMs: 60_000, store }), 42431)
-    expect(fresh.version).toBe('v2')
+    // The refresh round-trips Postgres, so poll the (fresh-window, zero-I/O)
+    // cell until it lands rather than racing a single macrotask.
+    await vi.waitFor(async () => {
+      const fresh = await VerifiedTokens.snapshot(context(db, { refreshMs: 60_000 }), 42431)
+      expect(fresh.version).toBe('v2')
+    })
+    const fresh = await VerifiedTokens.snapshot(context(db, { refreshMs: 60_000 }), 42431)
     expect(fresh.list.map((token) => token.symbol)).toEqual(['aUSD'])
   })
 
-  test('cold-loads an empty snapshot when the store has no head', async () => {
-    // Chain 4217 has no configured cell yet and an empty store → empty snapshot.
-    const snapshot = await VerifiedTokens.snapshot(context({ store: Store.memory() }), 4217)
+  test('cold-loads an empty snapshot when the chain has no rows', async () => {
+    // Chain 4217 has no configured cell yet and an empty database → empty snapshot.
+    const snapshot = await VerifiedTokens.snapshot(context(TestApp.database()), 4217)
     expect(snapshot.version).toBe('empty')
     expect(snapshot.list).toEqual([])
   })
@@ -217,9 +201,9 @@ const newToken = {
 
 describe('replace', () => {
   test('publishes the list and round-trips through read', async () => {
-    const store = Store.memory()
-    const { snapshot } = await VerifiedTokens.replace(store, 42431, tokens)
-    const read = await VerifiedTokens.read(store, 42431)
+    const db = TestApp.database()
+    const { snapshot } = await VerifiedTokens.replace(db, 42431, tokens)
+    const read = await VerifiedTokens.read(db, 42431)
     expect(read?.version).toBe(snapshot.version)
     expect(read?.list.map((token) => token.symbol)).toEqual(['aUSD', 'bEUR', 'cUSD'])
     // Addresses are normalized to lowercase on write.
@@ -227,16 +211,16 @@ describe('replace', () => {
   })
 
   test('advances the head version on each publish', async () => {
-    const store = Store.memory()
-    const first = await VerifiedTokens.replace(store, 42431, tokens)
-    const second = await VerifiedTokens.replace(store, 42431, tokens.slice(0, 1))
+    const db = TestApp.database()
+    const first = await VerifiedTokens.replace(db, 42431, tokens)
+    const second = await VerifiedTokens.replace(db, 42431, tokens.slice(0, 1))
     expect(second.snapshot.version > first.snapshot.version).toBe(true)
   })
 
   test('rejects a duplicate address in the input', async () => {
-    const store = Store.memory()
+    const db = TestApp.database()
     await expect(
-      VerifiedTokens.replace(store, 42431, [tokens[0]!, tokens[0]!]),
+      VerifiedTokens.replace(db, 42431, [tokens[0]!, tokens[0]!]),
     ).rejects.toThrowErrorMatchingInlineSnapshot(
       `[VerifiedTokens.DuplicateAddressError: verified token 0xaaa0000000000000000000000000000000000001 already exists on chain 42431.]`,
     )
@@ -245,35 +229,35 @@ describe('replace', () => {
 
 describe('create', () => {
   test('appends a token preserving order', async () => {
-    const store = Store.memory()
-    await VerifiedTokens.replace(store, 42431, tokens)
-    const { snapshot, token } = await VerifiedTokens.create(store, { ...newToken, chainId: 42431 })
+    const db = TestApp.database()
+    await VerifiedTokens.replace(db, 42431, tokens)
+    const { snapshot, token } = await VerifiedTokens.create(db, { ...newToken, chainId: 42431 })
     expect(token.address).toBe('0xddd0000000000000000000000000000000000004')
     expect(snapshot.list.map((t) => t.symbol)).toEqual(['aUSD', 'bEUR', 'cUSD', 'dGBP'])
   })
 
   test('rejects a duplicate address', async () => {
-    const store = Store.memory()
-    await VerifiedTokens.replace(store, 42431, tokens)
-    await expect(
-      VerifiedTokens.create(store, { ...tokens[0]!, chainId: 42431 }),
-    ).rejects.toThrowError(VerifiedTokens.DuplicateAddressError)
+    const db = TestApp.database()
+    await VerifiedTokens.replace(db, 42431, tokens)
+    await expect(VerifiedTokens.create(db, { ...tokens[0]!, chainId: 42431 })).rejects.toThrowError(
+      VerifiedTokens.DuplicateAddressError,
+    )
   })
 
   test('rejects a case-insensitive duplicate symbol', async () => {
-    const store = Store.memory()
-    await VerifiedTokens.replace(store, 42431, tokens)
+    const db = TestApp.database()
+    await VerifiedTokens.replace(db, 42431, tokens)
     await expect(
-      VerifiedTokens.create(store, { ...newToken, chainId: 42431, symbol: 'AUSD' }),
+      VerifiedTokens.create(db, { ...newToken, chainId: 42431, symbol: 'AUSD' }),
     ).rejects.toThrowError(VerifiedTokens.DuplicateSymbolError)
   })
 })
 
 describe('patch', () => {
   test('edits fields in place, preserving order', async () => {
-    const store = Store.memory()
-    await VerifiedTokens.replace(store, 42431, tokens)
-    const { snapshot, token } = await VerifiedTokens.patch(store, 42431, tokens[1]!.address, {
+    const db = TestApp.database()
+    await VerifiedTokens.replace(db, 42431, tokens)
+    const { snapshot, token } = await VerifiedTokens.patch(db, 42431, tokens[1]!.address, {
       name: 'Beta Euro',
     })
     expect(token.name).toBe('Beta Euro')
@@ -283,35 +267,35 @@ describe('patch', () => {
   })
 
   test('throws NotFoundError for an unknown address', async () => {
-    const store = Store.memory()
-    await VerifiedTokens.replace(store, 42431, tokens)
+    const db = TestApp.database()
+    await VerifiedTokens.replace(db, 42431, tokens)
     await expect(
-      VerifiedTokens.patch(store, 42431, newToken.address, { name: 'x' }),
+      VerifiedTokens.patch(db, 42431, newToken.address, { name: 'x' }),
     ).rejects.toThrowError(VerifiedTokens.NotFoundError)
   })
 
   test('rejects an If-Match version mismatch', async () => {
-    const store = Store.memory()
-    await VerifiedTokens.replace(store, 42431, tokens)
+    const db = TestApp.database()
+    await VerifiedTokens.replace(db, 42431, tokens)
     await expect(
-      VerifiedTokens.patch(store, 42431, tokens[0]!.address, { name: 'x' }, { ifMatch: 'stale' }),
+      VerifiedTokens.patch(db, 42431, tokens[0]!.address, { name: 'x' }, { ifMatch: 'stale' }),
     ).rejects.toThrowError(VerifiedTokens.VersionMismatchError)
   })
 })
 
 describe('remove', () => {
   test('removes a token and publishes', async () => {
-    const store = Store.memory()
-    await VerifiedTokens.replace(store, 42431, tokens)
-    const { snapshot } = await VerifiedTokens.remove(store, 42431, tokens[0]!.address)
+    const db = TestApp.database()
+    await VerifiedTokens.replace(db, 42431, tokens)
+    const { snapshot } = await VerifiedTokens.remove(db, 42431, tokens[0]!.address)
     expect(snapshot.list.map((t) => t.symbol)).toEqual(['bEUR', 'cUSD'])
     expect(snapshot.byAddress.has(tokens[0]!.address.toLowerCase())).toBe(false)
   })
 
   test('throws NotFoundError for an unknown address', async () => {
-    const store = Store.memory()
-    await VerifiedTokens.replace(store, 42431, tokens)
-    await expect(VerifiedTokens.remove(store, 42431, newToken.address)).rejects.toThrowError(
+    const db = TestApp.database()
+    await VerifiedTokens.replace(db, 42431, tokens)
+    await expect(VerifiedTokens.remove(db, 42431, newToken.address)).rejects.toThrowError(
       VerifiedTokens.NotFoundError,
     )
   })
@@ -326,8 +310,8 @@ describe('prime', () => {
       version: 'primed',
     })
     VerifiedTokens.prime(42431, primed)
-    // Within the fresh window the primed snapshot is served with no store read.
-    const snapshot = await VerifiedTokens.snapshot(context({ refreshMs: 60_000, store: Store.memory() }), 42431) // prettier-ignore
+    // Within the fresh window the primed snapshot is served with no database read.
+    const snapshot = await VerifiedTokens.snapshot(context(unreachable(), { refreshMs: 60_000 }), 42431) // prettier-ignore
     expect(snapshot).toBe(primed)
   })
 })