tapimo 0.0.0 → 0.0.2

package/src/internal/Cache.test.ts

@@ -0,0 +1,240 @@
+import { Hono } from 'hono'
+import * as Cache from './Cache.js'
+
+describe('response', () => {
+  test('preserves rate-limit headers without caching them', async () => {
+    await withCaches(async () => {
+      let calls = 0
+      const app = new Hono()
+
+      app.use('*', async (c, next) => {
+        c.header('RateLimit-Remaining', calls === 0 ? '9' : '8')
+        await next()
+      })
+      app.get('/', Cache.response({ key: (c) => c.req.url, name: 'test' }), (c) =>
+        c.json({ calls: ++calls }),
+      )
+
+      const first = await app.request('/')
+      const second = await app.request('/')
+      const third = await app.request('/', {
+        headers: { 'If-None-Match': first.headers.get('etag') ?? '' },
+      })
+
+      expect(calls).toMatchInlineSnapshot(`1`)
+      expect(await first.json()).toMatchInlineSnapshot(`
+        {
+          "calls": 1,
+        }
+      `)
+      expect(first.headers.get('cache-control')).toMatchInlineSnapshot(
+        `"private, max-age=30, stale-while-revalidate=300"`,
+      )
+      expect(etag(first)).toMatchInlineSnapshot(`"<etag>"`)
+      expect(first.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`"9"`)
+      expect(first.headers.get('vary')).toMatchInlineSnapshot(
+        `"Accept-Encoding, Authorization, Tempo-API-Key"`,
+      )
+
+      expect(await second.json()).toMatchInlineSnapshot(`
+        {
+          "calls": 1,
+        }
+      `)
+      expect(second.headers.get('cache-control')).toMatchInlineSnapshot(
+        `"private, max-age=30, stale-while-revalidate=300"`,
+      )
+      expect(second.headers.get('etag') === first.headers.get('etag')).toMatchInlineSnapshot(`true`)
+      expect(second.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`"8"`)
+      expect(second.headers.get('vary')).toMatchInlineSnapshot(
+        `"Accept-Encoding, Authorization, Tempo-API-Key"`,
+      )
+
+      expect(third.status).toMatchInlineSnapshot(`304`)
+      expect(await third.text()).toMatchInlineSnapshot(`""`)
+      expect(third.headers.get('cache-control')).toMatchInlineSnapshot(
+        `"private, max-age=30, stale-while-revalidate=300"`,
+      )
+      expect(third.headers.get('etag') === first.headers.get('etag')).toMatchInlineSnapshot(`true`)
+      expect(third.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`"8"`)
+      expect(third.headers.get('vary')).toMatchInlineSnapshot(
+        `"Accept-Encoding, Authorization, Tempo-API-Key"`,
+      )
+    })
+  })
+
+  test('stores entries with the shared policy form, not the client form', async () => {
+    await withCaches(async (stores) => {
+      const app = new Hono()
+      app.get('/', Cache.response({ key: (c) => c.req.url, name: 'test' }), (c) =>
+        c.json({ ok: true }),
+      )
+
+      await app.request('/')
+
+      const [stored] = [...(stores.get('test')?.values() ?? [])]
+      // The stored copy carries `public, s-maxage` so platform caches bound
+      // the entry's lifetime to the policy; the client copy stays private.
+      expect(stored?.headers.get('cache-control')).toMatchInlineSnapshot(
+        `"public, max-age=30, s-maxage=30, stale-while-revalidate=300"`,
+      )
+    })
+  })
+
+  test('refreshes the stored entry when the request sends `Cache-Control: no-cache`', async () => {
+    await withCaches(async () => {
+      let calls = 0
+      const app = new Hono()
+      app.get('/', Cache.response({ key: (c) => c.req.url, name: 'test' }), (c) =>
+        c.json({ calls: ++calls }),
+      )
+
+      await app.request('/')
+      // `no-cache` purges the stored entry, re-runs the handler, and stores
+      // the fresh response, so the following plain request is served the
+      // refreshed copy.
+      const refreshed = await app.request('/', { headers: { 'cache-control': 'no-cache' } })
+      const after = await app.request('/')
+
+      expect(calls).toMatchInlineSnapshot(`2`)
+      expect(await refreshed.json()).toMatchInlineSnapshot(`
+        {
+          "calls": 2,
+        }
+      `)
+      expect(await after.json()).toMatchInlineSnapshot(`
+        {
+          "calls": 2,
+        }
+      `)
+    })
+  })
+
+  test('bypasses without purging when the request sends `Cache-Control: no-store`', async () => {
+    await withCaches(async () => {
+      let calls = 0
+      const app = new Hono()
+      app.get('/', Cache.response({ key: (c) => c.req.url, name: 'test' }), (c) =>
+        c.json({ calls: ++calls }),
+      )
+
+      await app.request('/')
+      // `no-store` skips reads and writes but leaves the stored entry alone:
+      // the bypassing caller gets a fresh response while the next plain
+      // request is still served the original copy.
+      const bypassed = await app.request('/', { headers: { 'cache-control': 'no-store' } })
+      const after = await app.request('/')
+
+      expect(calls).toMatchInlineSnapshot(`2`)
+      expect(await bypassed.json()).toMatchInlineSnapshot(`
+        {
+          "calls": 2,
+        }
+      `)
+      expect(await after.json()).toMatchInlineSnapshot(`
+        {
+          "calls": 1,
+        }
+      `)
+    })
+  })
+
+  test('honors `Pragma: no-cache` when `Cache-Control` is absent', async () => {
+    await withCaches(async () => {
+      let calls = 0
+      const app = new Hono()
+      app.get('/', Cache.response({ key: (c) => c.req.url, name: 'test' }), (c) =>
+        c.json({ calls: ++calls }),
+      )
+
+      await app.request('/')
+      const refreshed = await app.request('/', { headers: { pragma: 'no-cache' } })
+
+      expect(calls).toMatchInlineSnapshot(`2`)
+      expect(await refreshed.json()).toMatchInlineSnapshot(`
+        {
+          "calls": 2,
+        }
+      `)
+    })
+  })
+
+  test('does not store responses a handler overrides to `noStore`', async () => {
+    await withCaches(async (stores) => {
+      let calls = 0
+      const app = new Hono()
+      app.get('/', Cache.response({ key: (c) => c.req.url, name: 'test' }), (c) => {
+        Cache.setPolicy(c, Cache.policies.noStore)
+        return c.json({ calls: ++calls })
+      })
+
+      const first = await app.request('/')
+      const second = await app.request('/')
+
+      // The `noStore` override must keep the response out of the inner cache
+      // (e.g. a pending transaction), so every request re-runs the handler.
+      expect(calls).toMatchInlineSnapshot(`2`)
+      expect(stores.get('test')?.size ?? 0).toMatchInlineSnapshot(`0`)
+      expect(first.headers.get('cache-control')).toMatchInlineSnapshot(`"no-store"`)
+      expect(second.headers.get('cache-control')).toMatchInlineSnapshot(`"no-store"`)
+    })
+  })
+
+  test('leaves error response `Cache-Control` alone', async () => {
+    await withCaches(async (stores) => {
+      const app = new Hono()
+      app.get('/', Cache.response({ key: (c) => c.req.url, name: 'test' }), (c) => {
+        // Mirrors `Response.error`, which marks envelopes `no-store`.
+        c.header('Cache-Control', 'no-store')
+        return c.json({ error: true }, 404)
+      })
+
+      const first = await app.request('/')
+      const second = await app.request('/')
+
+      expect(first.status).toMatchInlineSnapshot(`404`)
+      expect(first.headers.get('cache-control')).toMatchInlineSnapshot(`"no-store"`)
+      expect(second.headers.get('cache-control')).toMatchInlineSnapshot(`"no-store"`)
+      expect(stores.get('test')?.size ?? 0).toMatchInlineSnapshot(`0`)
+    })
+  })
+})
+
+function etag(response: Response) {
+  return response.headers.has('etag') ? '<etag>' : null
+}
+
+async function withCaches(fn: (stores: Map<string, Map<string, Response>>) => Promise<void>) {
+  const descriptor = Object.getOwnPropertyDescriptor(globalThis, 'caches')
+  const stores = new Map<string, Map<string, Response>>()
+  Object.defineProperty(globalThis, 'caches', {
+    configurable: true,
+    value: {
+      async open(name: string) {
+        let store = stores.get(name)
+        if (!store) {
+          store = new Map()
+          stores.set(name, store)
+        }
+        return {
+          async delete(key: string) {
+            return store.delete(key)
+          },
+          async match(key: string) {
+            return store.get(key)?.clone()
+          },
+          async put(key: string, response: Response) {
+            store.set(key, response.clone())
+          },
+        }
+      },
+    },
+  })
+
+  try {
+    await fn(stores)
+  } finally {
+    if (descriptor) Object.defineProperty(globalThis, 'caches', descriptor)
+    else delete (globalThis as { caches?: unknown }).caches
+  }
+}

package/src/internal/Cache.ts

@@ -0,0 +1,262 @@
+import type { Context, Env, MiddlewareHandler } from 'hono'
+import { cache as hono_cache } from 'hono/cache'
+import { etag as hono_etag, RETAINED_304_HEADERS } from 'hono/etag'
+import type * as z from 'zod/mini'
+
+import * as EdgeCache from './EdgeCache.js'
+
+/**
+ * Named `Cache-Control` policies, tiered by how volatile each resource is. The
+ * `max-age` bounds how stale a shared (edge) hit can be; `stale-while-revalidate`
+ * lets clients/CDNs serve a slightly older copy while refreshing in the
+ * background. Handlers may override per response via `Cache.setPolicy` (e.g. a
+ * mined transaction is `immutable`, a pending one is `noStore`).
+ */
+export const policies = {
+  /**
+   * Publicly shareable binary assets (token logos). `public` because the bytes
+   * carry no per-principal data and the edge layer strips per-request headers.
+   * Deliberately NOT `immutable`: these live at a stable URL
+   * (`/tokens/:token/logo`) whose underlying R2 icon can be replaced in place
+   * (admin upload), so a long `max-age` is paired with `stale-while-revalidate`
+   * to revalidate rather than pin a replaced logo for a year. Use a versioned/
+   * content-addressed URL if true `immutable` forever-caching is needed.
+   */
+  asset: 'public, max-age=86400, stale-while-revalidate=604800',
+  /** Fallback for routes that do not specify a policy. */
+  default: 'private, max-age=30, stale-while-revalidate=300',
+  /** Newest-first feeds (transactions, receipts, transfers): refresh quickly. */
+  feed: 'private, max-age=10, stale-while-revalidate=30',
+  /** Immutable resources (mined transactions and receipts): cache aggressively. */
+  immutable: 'private, max-age=86400, stale-while-revalidate=604800',
+  /** Token metadata and indexed listings: change slowly. */
+  metadata: 'private, max-age=60, stale-while-revalidate=300',
+  /** Transient or uncacheable responses (pending transactions). */
+  noStore: 'no-store',
+  /** Slow-changing curated data (verified tokens). */
+  stable: 'private, max-age=300, stale-while-revalidate=3600',
+  /** Current-state pages (holders, balances): moderately volatile. */
+  state: 'private, max-age=30, stale-while-revalidate=120',
+} as const
+
+/**
+ * Overrides the cache policy for the current response, taking precedence over
+ * the route's default `Cache.response` policy. Lets a handler vary caching by
+ * outcome — e.g. cache a mined transaction as `immutable` but a pending one as
+ * `noStore`. Must be called before the handler returns.
+ */
+export function setPolicy<environment extends Env>(
+  c: Context<environment>,
+  cacheControl: string,
+): void {
+  c.set('cacheControl' as never, cacheControl as never)
+}
+
+/** Hono response-cache helpers. */
+export function response<environment extends Env>(
+  options: response.Options<environment>,
+): MiddlewareHandler<environment> {
+  const defaultCacheControl = options.cacheControl ?? policies.default
+  const vary = options.vary ?? ['Accept-Encoding', 'Authorization', 'Tempo-API-Key']
+  // hono/cache suffixes its key with `::<directive>=<value>` for every
+  // configured vary directive (trimmed, lowercased, deduped). Mirror that
+  // normalization so the `no-cache` purge below deletes exactly the entry the
+  // wrapped middleware reads — drift here would make refreshes silently miss.
+  const varyKeyDirectives = [
+    ...new Set(vary.map((name) => name.trim().toLowerCase()).filter(Boolean)),
+  ]
+  const cache = hono_cache({
+    cacheName: options.name,
+    keyGenerator: options.key,
+    onCacheNotAvailable: false,
+    vary: [...vary],
+    wait: true,
+  })
+  const etag = hono_etag()
+
+  return async (c, next) => {
+    const values = response.preservedHeaders.map((name) => [name, c.res.headers.get(name)] as const)
+
+    // Honor the standard request `Cache-Control` directives (plus the HTTP/1.0
+    // `Pragma: no-cache` fallback, used only when `Cache-Control` is absent),
+    // mirroring `EdgeCache.middleware`: a refresh that bypasses the edge layer
+    // must also bypass this inner response cache, or the caller is served the
+    // inner stored copy and the "refresh" never reaches the handler.
+    // `no-cache` purges the stored entry so the wrapped hono/cache misses and
+    // re-stores the fresh response; `no-store` skips reads and writes entirely
+    // while leaving the stored entry untouched.
+    const directives = (c.req.header('Cache-Control') ?? c.req.header('Pragma') ?? '').toLowerCase()
+    const noStore = directives.includes('no-store')
+    const noCache = noStore || directives.includes('no-cache')
+    // The Cache API global is platform-provided (Cloudflare Workers, browsers)
+    // and absent from Node's type surface, so probe it structurally — on
+    // runtimes without it the wrapped hono/cache is a no-op and there is
+    // nothing to purge.
+    type Caches = { open(name: string): Promise<{ delete(key: string): Promise<unknown> }> }
+    const caches = (globalThis as { caches?: Caches }).caches
+    if (noCache && !noStore && caches) {
+      let key = await options.key(c)
+      for (const name of varyKeyDirectives)
+        key += `::${name}=${encodeURIComponent(c.req.raw.headers.get(name) ?? '')}`
+      await (await caches.open(options.name)).delete(key)
+    }
+
+    // Run ETag inside Hono's cache miss path so fresh responses are hashed
+    // once before storage. Cached hits bypass Hono's ETag middleware, so this
+    // wrapper handles conditional requests from the stored ETag below.
+    const handler = async () => {
+      await etag(c, async () => {
+        await next()
+        // Rate-limit headers are per request and would be stale if stored with
+        // the shared cached body.
+        for (const name of response.preservedHeaders) c.res.headers.delete(name)
+      })
+      // Stamp the resolved policy's shared form onto 2xx responses BEFORE
+      // hono/cache stores them: the explicit `s-maxage` bounds the stored
+      // entry's lifetime to the policy (instead of the platform cache's
+      // default TTL), and a policy resolved to `noStore` (e.g. a pending
+      // transaction via `setPolicy`) becomes `no-store`, which hono/cache
+      // refuses to store. Client-facing headers are applied after storage
+      // below; non-2xx responses keep their own headers (`Response.error`
+      // marks envelopes `no-store`).
+      if (c.res.status >= 200 && c.res.status < 300) {
+        const policy = edgeCachePolicy(
+          (c.get('cacheControl' as never) as string | undefined) ?? defaultCacheControl,
+        )
+        c.res.headers.set('Cache-Control', policy ? EdgeCache.cacheControl(policy) : 'no-store')
+      }
+    }
+    const result = noStore ? await handler() : await cache(c, handler)
+
+    // A handler may override the policy per response (see `setPolicy`); fall back
+    // to the route default. Publishing the derived policy is what marks the
+    // response as eligible for the shared edge cache (see `EdgeCache.middleware`),
+    // so `noStore` responses are never persisted there. The edge layer reads this
+    // after the whole chain runs, so setting it here (post-handler) is in time.
+    const cacheControl =
+      (c.get('cacheControl' as never) as string | undefined) ?? defaultCacheControl
+    c.set('edgeCache' as never, edgeCachePolicy(cacheControl) as never)
+
+    let res = result instanceof Response ? new Response(result.body, result) : c.res
+    if (
+      result instanceof Response &&
+      etagMatches(res.headers.get('ETag'), c.req.header('If-None-Match'))
+    )
+      res = notModified(res)
+
+    // Apply private client cache headers after Hono cache storage; the stored
+    // copy carries the shared `public, s-maxage` form stamped above, while the
+    // client receives the policy's private form. Error responses keep their
+    // own `Cache-Control` (`no-store` from `Response.error` or the app-level
+    // safety net) instead of inheriting the route policy.
+    if ((res.status >= 200 && res.status < 300) || res.status === 304)
+      setCacheHeaders(res.headers, { cacheControl, vary })
+    for (const [name, value] of values) if (value) res.headers.set(name, value)
+    if (result instanceof Response) return res
+    return undefined
+  }
+}
+
+export declare namespace response {
+  /** Options for response caching. */
+  type Options<environment extends Env> = {
+    /** Cache-control value returned to clients. */
+    cacheControl?: string | undefined
+    /** Cache name passed to Hono's cache middleware. */
+    name: string
+    /** Cache key generator. */
+    key: (c: Context<environment>) => Promise<string> | string
+    /** Vary headers used for the response and cache key. */
+    vary?: readonly string[] | undefined
+  }
+}
+
+export namespace response {
+  /** Per-request headers that must not be stored in shared response caches. */
+  export const preservedHeaders = ['RateLimit-Limit', 'RateLimit-Remaining', 'RateLimit-Reset']
+}
+
+/**
+ * Builds a cache key from the request URL after parsing query params through
+ * the given Zod schema. Defaults from the schema are baked into the key so
+ * cached entries collide regardless of param ordering, casing, or omitted
+ * defaults. Resolves an optional `chainId` query parameter against the app's
+ * default chain id when the caller did not provide one.
+ */
+export function urlKey<
+  environment extends { Variables: { chainId: number } },
+  schema extends z.ZodMiniType,
+>(c: Context<environment>, schema: schema): string {
+  const url = new URL(c.req.url)
+  const query = schema.parse(Object.fromEntries(url.searchParams)) as Record<string, unknown>
+  url.search = ''
+  if (query['chainId'] === undefined) url.searchParams.set('chainId', String(c.get('chainId')))
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined) continue
+    url.searchParams.set(key, String(value as number | string | boolean))
+  }
+  return url.toString()
+}
+
+function etagMatches(etag: string | null, ifNoneMatch: string | undefined) {
+  if (!etag || !ifNoneMatch) return false
+  return ifNoneMatch.split(/,\s*/).some((tag) => stripWeak(tag) === stripWeak(etag))
+}
+
+function notModified(response: Response) {
+  const headers = new Headers()
+  for (const name of RETAINED_304_HEADERS) {
+    const value = response.headers.get(name)
+    if (value) headers.set(name, value)
+  }
+  return new Response(null, {
+    headers,
+    status: 304,
+    statusText: 'Not Modified',
+  })
+}
+
+function setCacheHeaders(
+  headers: Headers,
+  options: { cacheControl: string; vary: readonly string[] },
+) {
+  headers.set('Cache-Control', options.cacheControl)
+  const vary = new Map(
+    (headers.get('Vary') ?? '')
+      .split(',')
+      .map((value) => value.trim())
+      .filter(Boolean)
+      .map((value) => [value.toLowerCase(), value] as const),
+  )
+  for (const value of options.vary) vary.set(value.toLowerCase(), value)
+  headers.set('Vary', Array.from(vary.values()).join(', '))
+}
+
+function stripWeak(etag: string) {
+  return etag.replace(/^W\//, '')
+}
+
+// Derive the shared-cache policy from a route's client `Cache-Control`. A
+// positive `s-maxage`/`max-age` (and no `no-store`/`no-cache`) is what makes a
+// route eligible for the anonymous edge cache; the `private` directive only
+// scopes the client copy and is intentionally ignored here.
+function edgeCachePolicy(cacheControl: string): EdgeCache.Policy | undefined {
+  const directives = new Map(
+    cacheControl
+      .split(',')
+      .map((part) => part.trim().toLowerCase())
+      .filter(Boolean)
+      .map((part) => part.split('=') as [string, string | undefined]),
+  )
+  if (directives.has('no-store') || directives.has('no-cache')) return undefined
+  const maxAge = Number(directives.get('s-maxage') ?? directives.get('max-age'))
+  if (!Number.isFinite(maxAge) || maxAge <= 0) return undefined
+  const staleWhileRevalidate = Number(directives.get('stale-while-revalidate'))
+  return {
+    maxAge,
+    staleWhileRevalidate:
+      Number.isFinite(staleWhileRevalidate) && staleWhileRevalidate > 0
+        ? staleWhileRevalidate
+        : undefined,
+  }
+}

package/src/internal/Cursor.test.ts

@@ -0,0 +1,100 @@
+import * as Cursor from './Cursor.js'
+
+describe('Cursor', () => {
+  test('round-trips an int tuple through an opaque, URL-safe token', () => {
+    const token = Cursor.encode([123456, 7])
+    expect(token).toMatch(/^[A-Za-z0-9_-]+$/)
+    expect(Cursor.decode(token, ['int', 'int'])).toEqual([123456, 7])
+  })
+
+  test('round-trips a balance/address tuple', () => {
+    const token = Cursor.encode([
+      '1000000000000000000',
+      '0xBE058E1C4DF8A4366A387BF595B284246A93039E',
+    ])
+    expect(Cursor.decode(token, ['uint', 'address'])).toEqual([
+      '1000000000000000000',
+      '0xBE058E1C4DF8A4366A387BF595B284246A93039E',
+    ])
+  })
+
+  test('returns undefined for malformed, mis-typed, or wrong-arity tokens', () => {
+    expect(Cursor.decode('not-base64!!', ['int', 'int'])).toBeUndefined()
+    expect(Cursor.decode(btoa('{"oops":true}'), ['int', 'int'])).toBeUndefined()
+    expect(Cursor.decode(btoa('[1]'), ['int', 'int'])).toBeUndefined()
+    expect(Cursor.decode(btoa('[1,2,3]'), ['int', 'int'])).toBeUndefined()
+    expect(Cursor.decode(btoa('[1.5,2]'), ['int', 'int'])).toBeUndefined()
+    expect(Cursor.decode(btoa('[-1,2]'), ['int', 'int'])).toBeUndefined()
+    expect(Cursor.decode(btoa('["x",2]'), ['uint', 'int'])).toBeUndefined()
+    expect(Cursor.decode(btoa('["0xnotanaddress",2]'), ['address', 'int'])).toBeUndefined()
+  })
+
+  test('renders injection-safe SQL literals per field kind', () => {
+    expect(Cursor.literal(42, 'int')).toBe('42')
+    expect(Cursor.literal('1000', 'uint')).toBe('1000')
+    expect(Cursor.literal('0xAbC0000000000000000000000000000000000000', 'address')).toBe(
+      "'0xabc0000000000000000000000000000000000000'",
+    )
+    expect(Cursor.literal('2024-01-01T00:00:00Z', 'timestamp')).toBe("'2024-01-01T00:00:00Z'")
+  })
+
+  test('paginates a keyset result, deriving hasMore and nextCursor from the extra row', () => {
+    const rows = [
+      { block: 10, idx: 2 },
+      { block: 10, idx: 1 },
+      { block: 9, idx: 0 },
+    ]
+    // Fetched `limit + 1` rows, so the trailing row signals another page.
+    const page = Cursor.paginate({ rows, limit: 2, key: (row) => [row.block, row.idx] })
+    expect(page.rows).toEqual([
+      { block: 10, idx: 2 },
+      { block: 10, idx: 1 },
+    ])
+    expect(page.hasMore).toBe(true)
+    expect(Cursor.decode(page.nextCursor!, ['int', 'int'])).toEqual([10, 1])
+  })
+
+  test('paginate reports the last page with a null nextCursor', () => {
+    const rows = [{ block: 9, idx: 0 }]
+    const page = Cursor.paginate({ rows, limit: 2, key: (row) => [row.block, row.idx] })
+    expect(page.rows).toEqual(rows)
+    expect(page.hasMore).toBe(false)
+    expect(page.nextCursor).toBeNull()
+  })
+
+  test('paginate yields a null nextCursor when the last row has no sort-key', () => {
+    const rows = [{ ok: true }, { ok: true }, { ok: false }]
+    const page = Cursor.paginate({ rows, limit: 2, key: (row) => (row.ok ? [1, 2] : undefined) })
+    expect(page.hasMore).toBe(true)
+    // The boundary row (last of the page) is `{ ok: true }`, so a cursor exists.
+    expect(page.nextCursor).not.toBeNull()
+  })
+
+  test('builds a row-value tuple predicate with a prunable first-column bound', () => {
+    expect(
+      Cursor.keyset([
+        { literal: '100', name: 'block_num', order: 'desc' },
+        { literal: '3', name: 'idx', order: 'desc' },
+      ]),
+    ).toBe('(block_num <= 100 AND (block_num, idx) < (100, 3))')
+    expect(
+      Cursor.keyset([
+        { literal: '100', name: 'block_num', order: 'asc' },
+        { literal: '3', name: 'idx', order: 'asc' },
+      ]),
+    ).toBe('(block_num >= 100 AND (block_num, idx) > (100, 3))')
+  })
+
+  test('omits the redundant bound for a single-column keyset', () => {
+    expect(Cursor.keyset([{ literal: '100', name: 'num', order: 'desc' }])).toBe('((num) < (100))')
+  })
+
+  test('falls back to an OR expansion for a mixed-direction keyset', () => {
+    expect(
+      Cursor.keyset([
+        { literal: '1000', name: 'balance', order: 'desc' },
+        { literal: "'0xabc'", name: 'holder', order: 'asc' },
+      ]),
+    ).toBe("(balance <= 1000 AND ((balance < 1000) OR (balance = 1000 AND holder > '0xabc')))")
+  })
+})