tapimo 0.11.0 → 0.13.0

package/src/internal/Response.ts

@@ -1,6 +1,8 @@
 import type { Context } from 'hono'
 import type * as z from 'zod/mini'
 
+import * as Tidx from './Tidx.js'
+
 /** Creates a JSON error response. */
 export function error<const status extends error.Status, const code extends string>(
   c: Context,
@@ -39,14 +41,34 @@ export function unsupportedChainId(c: Context, chainId: number, supported: Itera
 }
 
 /**
- * Maps an unexpected upstream failure to a stable 502 JSON error envelope.
+ * Maps upstream failures to 502, except TIDX query failures after the first positional page return 400.
  * Preserves `Error` causes for reporting and rethrows non-`Error` causes.
  */
-export function upstream(c: Context, cause: unknown) {
+export function upstream(c: Context, cause: unknown): upstream.Response
+export function upstream(
+  c: Context,
+  cause: unknown,
+  options: upstream.Options,
+): upstream.PageResponse
+export function upstream(c: Context, cause: unknown, options?: upstream.Options) {
   if (cause instanceof Error) {
     // Preserve the original error for error-reporting middleware without
     // exposing provider URLs, payloads, or credentials in the response.
     c.error = cause
+    if (options?.page !== undefined && options.page > 1) {
+      if (Tidx.isQueryTimeout(cause))
+        return error(c, {
+          code: 'query_invalid',
+          message: 'The requested page timed out. Use cursor pagination for deep traversal.',
+          status: 400,
+        })
+      if (Tidx.isQueryRejection(cause))
+        return error(c, {
+          code: 'query_invalid',
+          message: 'The requested page was rejected. Use cursor pagination for deep traversal.',
+          status: 400,
+        })
+    }
     return error(c, {
       code: 'upstream_error',
       message: 'Upstream service could not complete the request',
@@ -56,6 +78,22 @@ export function upstream(c: Context, cause: unknown) {
   throw cause
 }
 
+export declare namespace upstream {
+  /** Pagination context for classifying a deep-page query failure. */
+  type Options = {
+    /** Validated positional page number, when requested. */
+    page: number | undefined
+  }
+
+  /** Upstream response for routes that support positional pagination. */
+  type PageResponse =
+    | ReturnType<typeof error<400, 'query_invalid'>>
+    | ReturnType<typeof error<502, 'upstream_error'>>
+
+  /** Default upstream error response. */
+  type Response = ReturnType<typeof error<502, 'upstream_error'>>
+}
+
 /**
  * Validates `value` against `schema`. Returns the parsed value on success or
  * throws a generic upstream error so the public response body never leaks Zod
@@ -104,7 +142,7 @@ export declare namespace error {
   }
 
   /** HTTP status code accepted by the public error helper. */
-  type Status = 400 | 401 | 403 | 404 | 409 | 412 | 413 | 415 | 429 | 500 | 501 | 502 | 503
+  type Status = 400 | 401 | 403 | 404 | 409 | 412 | 413 | 415 | 429 | 500 | 501 | 502 | 503 | 504
 
   /** Options for creating a JSON error response. */
   type Options<status extends Status = Status, code extends string = string> = {

package/src/internal/Schema.test.ts

@@ -1,9 +1,13 @@
+import * as z from 'zod/mini'
+
 import * as Schema from './Schema.js'
 
 describe('ChainId', () => {
   test('resolves aliases to their chain id', () => {
     expect(Schema.ChainId.parse('mainnet')).toMatchInlineSnapshot(`4217`)
     expect(Schema.ChainId.parse('testnet')).toMatchInlineSnapshot(`42431`)
+    expect(Schema.ChainId.parse('1424310001')).toMatchInlineSnapshot(`1424310003`)
+    expect(Schema.ChainId.parse(1_424_310_001)).toMatchInlineSnapshot(`1424310003`)
   })
 
   test('accepts numeric chain ids as numbers or strings', () => {
@@ -51,6 +55,20 @@ describe('Limit', () => {
   })
 })
 
+describe('pageChecks', () => {
+  const Query = z
+    .object({ cursor: Schema.Cursor, limit: Schema.Limit, page: Schema.Page })
+    .check(...Schema.pageChecks())
+
+  test('accepts positional pages through the 500-row window', () => {
+    expect(Query.safeParse({ limit: '10', page: '50' }).success).toMatchInlineSnapshot(`true`)
+  })
+
+  test('rejects deeper positional pages', () => {
+    expect(Query.safeParse({ limit: '10', page: '51' }).success).toMatchInlineSnapshot(`false`)
+  })
+})
+
 describe('timestampBound', () => {
   test('normalizes RFC 3339 offsets to UTC', () => {
     const bound = Schema.timestampBound('swaps', 'from')

package/src/internal/Schema.ts

@@ -90,12 +90,19 @@ export function tokenAddress(example: core_Hex.Hex) {
     )
 }
 
-/** Maps human-readable chain aliases to their Tempo chain id. */
+/** Maps caller-facing chain aliases to their current Tempo chain id. */
 export const chainIdAlias = {
+  // TODO: Remove this alias after clients migrate to chain 1424310003.
+  1_424_310_001: 1_424_310_003,
   mainnet: 4217,
   testnet: 42431,
 } as const
 
+/** Resolves a numeric chain id through the caller-facing alias map. */
+export function resolveChainId(chainId: number): number {
+  return chainIdAlias[chainId as keyof typeof chainIdAlias] ?? chainId
+}
+
 /**
  * Tempo chain id. Accepts a chain alias (`mainnet`/`testnet`) or any positive
  * integer chain id (a number or numeric string), normalizing all forms to a
@@ -110,7 +117,10 @@ export const ChainId = z
         z.enum(['mainnet', 'testnet']),
         z.transform((alias) => chainIdAlias[alias]),
       ),
-      z.coerce.number(),
+      z.pipe(
+        z.coerce.number(),
+        z.transform((chainId) => resolveChainId(chainId)),
+      ),
     ]),
     z.number().check(z.int(), z.positive()),
   )
@@ -191,6 +201,8 @@ export const ErrorDetail = z
   })
   .check(z.describe('A single problem with the request.'))
 
+z.globalRegistry.add(ErrorDetail, { ...z.globalRegistry.get(ErrorDetail), ref: 'ErrorDetail' })
+
 /**
  * Builds the global error envelope, optionally enumerating `error.code` to a
  * fixed set of machine-readable codes. Pass the codes a given status can return
@@ -384,12 +396,10 @@ export const Cursor = z
 
 /**
  * Maximum page window (`page × limit` rows) accepted by positional pagination.
- * Mirrors the indexer's own 10k row ceiling, and the bounded-window convention
- * of comparable APIs (Elasticsearch `max_result_window`, Zendesk's 100-page
- * cap): shallow page-numbered access is served positionally, deep traversal
- * must use cursors.
+ * Stays below the indexer's own 10k row ceiling so large offsets do not reach
+ * the indexer. Deeper traversal must use cursors.
  */
-export const maxPageWindow = 10_000
+export const maxPageWindow = 500
 
 /**
  * Page-number query parameter (1-indexed) shared by list endpoints that
@@ -443,8 +453,8 @@ export const NextCursor = z
  * count is computed by a capped subquery (`… LIMIT countCap`) so it can't blow
  * the indexer's execution budget on the 10⁹-plus row tables; when the bound is
  * hit the count is a lower bound, signalled by `Meta.totalCountCapped`. Mirrors the
- * indexer's own 10k row ceiling (see {@link maxPageWindow}) and the capped-count
- * conventions of comparable APIs (Stripe Search's 10k `total_count`,
+ * indexer's own 10k row ceiling and the capped-count conventions of comparable
+ * APIs (Stripe Search's 10k `total_count`,
  * Elasticsearch `track_total_hits`, Shopify's `Count.precision`).
  */
 export const countCap = 10_000

package/src/internal/Store.test.ts

@@ -1,5 +1,7 @@
+import { HonoRequest } from 'hono/request'
 import { Store } from 'tapimo'
 import * as TestStore from '../../test/Store.js'
+import * as Timeout from './Timeout.js'
 
 describe('from', () => {
   const ops = {
@@ -754,6 +756,18 @@ describe('durableObject', () => {
   })
 })
 
+describe('withRequest', () => {
+  test('preserves the source store contract', async () => {
+    const source = new ReceiverStore()
+    const store = Store.withRequest(source, new HonoRequest(new Request('https://api.tempo.xyz')))
+
+    await store.put('value', 'stored')
+
+    expect(store.type).toMatchInlineSnapshot(`"cache"`)
+    expect(await source.get('value')).toMatchInlineSnapshot(`"stored"`)
+  })
+})
+
 describe('memoize', () => {
   test('coalesces concurrent cache misses for the same key', async () => {
     const store = Store.memory()
@@ -795,6 +809,183 @@ describe('memoize', () => {
     `)
   })
 
+  test('hands cache persistence to waitUntil without retaining the resolved flight', async () => {
+    const pending = deferred<void>()
+    const waited: Promise<unknown>[] = []
+    const source = Store.memory()
+    const store = Store.withRequest(
+      Store.from({
+        ...source,
+        put: () => pending.promise,
+        type: 'cache',
+      }),
+      new HonoRequest(new Request('https://api.tempo.xyz')),
+      { waitUntil: (promise) => void waited.push(promise) },
+    )
+    let calls = 0
+    const options = { key: 'memo:stalled-write', store, ttl: 60_000 }
+
+    const first = await Store.memoize(async () => ({ value: ++calls }), options)
+    const second = await Store.memoize(async () => ({ value: ++calls }), options)
+
+    expect(first).toEqual({ value: 1 })
+    expect(second).toEqual({ value: 2 })
+    expect(calls).toBe(2)
+    expect(waited).toHaveLength(2)
+
+    pending.resolve()
+    await Promise.all(waited)
+  })
+
+  test('ignores cache persistence failures without waitUntil', async () => {
+    const store = Store.from({
+      ...Store.memory(),
+      async put() {
+        throw new Error('cache unavailable')
+      },
+      type: 'cache',
+    })
+
+    await expect(
+      Store.memoize(async () => ({ value: 'fresh' }), {
+        key: 'memo:failed-write',
+        store,
+        ttl: 60_000,
+      }),
+    ).resolves.toEqual({ value: 'fresh' })
+  })
+
+  test('releases a no-cache flight after deletion fails', async () => {
+    let deletes = 0
+    let fetches = 0
+    const source = Store.from({
+      ...Store.memory(),
+      async delete() {
+        if (++deletes === 1) throw new Error('cache unavailable')
+      },
+    })
+    const store = Store.withRequest(
+      source,
+      new HonoRequest(
+        new Request('https://api.tempo.xyz', { headers: { 'cache-control': 'no-cache' } }),
+      ),
+    )
+    const options = { key: 'memo:failed-delete', store, ttl: 60_000 }
+
+    await expect(Store.memoize(async () => ({ value: ++fetches }), options)).rejects.toThrow(
+      'cache unavailable',
+    )
+    await expect(Store.memoize(async () => ({ value: ++fetches }), options)).resolves.toEqual({
+      value: 1,
+    })
+    expect(deletes).toBe(2)
+  })
+
+  test('times out and evicts a stalled cache-miss flight', async () => {
+    vi.useFakeTimers()
+    try {
+      const store = Store.memory()
+      const stalled = deferred<{ value: string }>()
+      let calls = 0
+      let leaderSignal: AbortSignal | undefined
+      const options = {
+        flightTimeout: 100,
+        key: 'memo:test',
+        store,
+        ttl: 60_000,
+      }
+      const leader = Store.memoize(async (signal) => {
+        calls += 1
+        leaderSignal = signal
+        return stalled.promise
+      }, options)
+      await vi.advanceTimersByTimeAsync(0)
+      const follower = Store.memoize(async () => {
+        calls += 1
+        return { value: 'unexpected' }
+      }, options)
+      const failures = Promise.all([
+        expect(leader).rejects.toBeInstanceOf(Store.MemoizeTimeoutError),
+        expect(follower).rejects.toBeInstanceOf(Store.MemoizeTimeoutError),
+      ])
+
+      await vi.advanceTimersByTimeAsync(100)
+      await failures
+
+      expect(calls).toBe(1)
+      expect(leaderSignal?.aborted).toBe(true)
+      expect(leaderSignal?.reason).toMatchObject({ name: 'TimeoutError' })
+
+      const recovered = await Store.memoize(async () => {
+        calls += 1
+        return { value: 'fresh' }
+      }, options)
+      stalled.resolve({ value: 'stale' })
+      await stalled.promise
+      await Promise.resolve()
+
+      expect(recovered).toEqual({ value: 'fresh' })
+      expect(calls).toBe(2)
+      expect(await store.get('memo:test')).toBe('tempo-api:store:json:v2:{"value":"fresh"}')
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  test('retains a timed-out flight until a cache mutation settles', async () => {
+    vi.useFakeTimers()
+    try {
+      const source = Store.memory()
+      const store = Store.withRequest(
+        source,
+        new HonoRequest(
+          new Request('https://api.tempo.xyz', {
+            headers: { 'cache-control': 'no-cache' },
+          }),
+        ),
+      )
+      let calls = 0
+      const options = { flightTimeout: 100, key: 'memo:mutation', store, ttl: 60_000 }
+      const leader = Store.memoize(async () => ({ value: ++calls }), options)
+      const leaderFailure = expect(leader).rejects.toBeInstanceOf(Store.MemoizeTimeoutError)
+
+      // The first microtask enters the real in-memory store's async delete.
+      await Promise.resolve()
+      vi.advanceTimersByTime(100)
+      const followerFailure = expect(
+        Store.memoize(async () => ({ value: ++calls }), options),
+      ).rejects.toBeInstanceOf(Store.MemoizeTimeoutError)
+
+      await Promise.all([leaderFailure, followerFailure])
+      expect(calls).toBe(0)
+      await expect(Store.memoize(async () => ({ value: ++calls }), options)).resolves.toEqual({
+        value: 1,
+      })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  test('defaults cache-miss flights to the API deadline', async () => {
+    vi.useFakeTimers()
+    try {
+      const store = Store.memory()
+      const stalled = deferred<{ value: string }>()
+      const failure = expect(
+        Store.memoize(() => stalled.promise, {
+          key: 'memo:default-timeout',
+          store,
+          ttl: 60_000,
+        }),
+      ).rejects.toBeInstanceOf(Store.MemoizeTimeoutError)
+
+      await vi.advanceTimersByTimeAsync(Timeout.duration)
+      await failure
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   test('returns cached JSON values until the entry expires', async () => {
     const store = Store.memory()
     let calls = 0
@@ -836,6 +1027,126 @@ describe('memoize', () => {
     `)
   })
 
+  test('refreshes the entry when request headers send no-cache', async () => {
+    const store = Store.memory()
+    let calls = 0
+    const fetch = async () => ({ value: ++calls })
+
+    await Store.memoize(fetch, { key: 'memo:test', store, ttl: 60_000 })
+    const refreshed = await Store.memoize(fetch, {
+      key: 'memo:test',
+      store: Store.withRequest(
+        store,
+        new HonoRequest(
+          new Request('https://api.tempo.xyz', {
+            headers: { 'cache-control': 'no-cache' },
+          }),
+        ),
+      ),
+      ttl: 60_000,
+    })
+    const after = await Store.memoize(fetch, { key: 'memo:test', store, ttl: 60_000 })
+
+    expect(calls).toMatchInlineSnapshot(`2`)
+    expect(refreshed).toMatchInlineSnapshot(`
+      {
+        "value": 2,
+      }
+    `)
+    expect(after).toEqual(refreshed)
+  })
+
+  test('propagates no-cache through nested memoizers', async () => {
+    const source = Store.memory()
+    let calls = 0
+    const fetch = async () => ({ value: ++calls })
+
+    await Store.memoize(fetch, { key: 'memo:inner', store: source, ttl: 60_000 })
+    const store = Store.withRequest(
+      source,
+      new HonoRequest(
+        new Request('https://api.tempo.xyz', {
+          headers: { 'cache-control': 'no-cache' },
+        }),
+      ),
+    )
+    const value = await Store.memoize(
+      () => Store.memoize(fetch, { key: 'memo:inner', store, ttl: 60_000 }),
+      { key: 'memo:outer', store, ttl: 60_000 },
+    )
+
+    expect(calls).toMatchInlineSnapshot(`2`)
+    expect(value).toMatchInlineSnapshot(`
+      {
+        "value": 2,
+      }
+    `)
+  })
+
+  test('bypasses without replacing the entry when request headers send no-store', async () => {
+    const store = Store.memory()
+    let calls = 0
+    const fetch = async () => ({ value: ++calls })
+
+    const first = await Store.memoize(fetch, { key: 'memo:test', store, ttl: 60_000 })
+    const bypassed = await Store.memoize(fetch, {
+      key: 'memo:test',
+      store: Store.withRequest(
+        store,
+        new HonoRequest(
+          new Request('https://api.tempo.xyz', {
+            headers: { 'cache-control': 'no-store' },
+          }),
+        ),
+      ),
+      ttl: 60_000,
+    })
+    const after = await Store.memoize(fetch, { key: 'memo:test', store, ttl: 60_000 })
+
+    expect(calls).toMatchInlineSnapshot(`2`)
+    expect(bypassed).toMatchInlineSnapshot(`
+      {
+        "value": 2,
+      }
+    `)
+    expect(after).toEqual(first)
+  })
+
+  test('honors Pragma no-cache only without Cache-Control', async () => {
+    const store = Store.memory()
+    let calls = 0
+    const fetch = async () => ({ value: ++calls })
+
+    await Store.memoize(fetch, { key: 'memo:test', store, ttl: 60_000 })
+    await Store.memoize(fetch, {
+      key: 'memo:test',
+      store: Store.withRequest(
+        store,
+        new HonoRequest(new Request('https://api.tempo.xyz', { headers: { pragma: 'no-cache' } })),
+      ),
+      ttl: 60_000,
+    })
+    const cached = await Store.memoize(fetch, {
+      key: 'memo:test',
+      store: Store.withRequest(
+        store,
+        new HonoRequest(
+          new Request('https://api.tempo.xyz', {
+            headers: { 'cache-control': 'max-age=0', pragma: 'no-cache' },
+          }),
+        ),
+      ),
+      ttl: 60_000,
+    })
+
+    expect(calls).toMatchInlineSnapshot(`2`)
+    expect(cached).toMatchInlineSnapshot(`
+      {
+        "value": 2,
+      }
+    `)
+  })
+
   test('preserves bigint values and collision-shaped strings on cache hits', async () => {
     const store = Store.memory()
     let calls = 0
@@ -877,6 +1188,34 @@ describe('memoize', () => {
     expect(calls).toBe(2)
   })
 
+  test('coalesces values excluded by the cache predicate without storing them', async () => {
+    const store = Store.memory()
+    const pending = deferred<void>()
+    let calls = 0
+    const fetch = async () => {
+      calls += 1
+      await pending.promise
+      return { cacheable: false, value: 'fresh' }
+    }
+    const options = {
+      key: 'memo:test',
+      shouldCache: (value: Awaited<ReturnType<typeof fetch>>) => value.cacheable,
+      store,
+      ttl: 60_000,
+    }
+    const requests = [Store.memoize(fetch, options), Store.memoize(fetch, options)]
+
+    await Promise.resolve()
+    pending.resolve()
+
+    expect(await Promise.all(requests)).toStrictEqual([
+      { cacheable: false, value: 'fresh' },
+      { cacheable: false, value: 'fresh' },
+    ])
+    expect(await store.get('memo:test')).toBeNull()
+    expect(calls).toBe(1)
+  })
+
   test('refreshes legacy untagged cache entries', async () => {
     const store = Store.memory({ entries: [['memo:test', '{"value":"123#__bigint"}']] })
     let calls = 0
@@ -945,3 +1284,28 @@ function durableObjectStorage(): Store.durableObject.Storage & { cells: Map<stri
     },
   }
 }
+
+class ReceiverStore implements Store.Store {
+  #cells = new Map<string, string>()
+  type = 'cache' as const
+
+  async delete(key: string) {
+    this.#cells.delete(key)
+  }
+
+  async get(key: string) {
+    return this.#cells.get(key) ?? null
+  }
+
+  async list(options: { prefix?: string | undefined } = {}) {
+    return {
+      keys: [...this.#cells.keys()]
+        .filter((key) => options.prefix === undefined || key.startsWith(options.prefix))
+        .map((name) => ({ name })),
+    }
+  }
+
+  async put(key: string, value: string) {
+    this.#cells.set(key, value)
+  }
+}