tapimo 0.11.0 → 0.12.0

package/src/internal/Response.test.ts

@@ -1,4 +1,5 @@
 import { Hono } from 'hono'
+import { Tidx } from 'tidx.ts'
 
 import * as Response from './Response.js'
 
@@ -25,4 +26,98 @@ describe('upstream', () => {
     `)
     expect(captured).toBe(cause)
   })
+
+  test('returns a query error when a positional page times out', async () => {
+    const app = new Hono()
+    const cause = new Tidx.FetchRequestError(
+      'Request timeout',
+      new globalThis.Response(null, { status: 408 }),
+    )
+    let captured: Error | undefined
+
+    app.use(async (c, next) => {
+      await next()
+      captured = c.error
+    })
+    app.get('/', (c) => Response.upstream(c, cause, { page: 2 }))
+
+    const response = await app.request('/')
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "query_invalid",
+          "message": "The requested page timed out. Use cursor pagination for deep traversal.",
+        },
+      }
+    `)
+    expect(captured).toBe(cause)
+  })
+
+  test('returns a query error when a positional page is rejected', async () => {
+    const app = new Hono()
+    const cause = new Tidx.FetchRequestError(
+      'Query rejected',
+      new globalThis.Response(null, { status: 422 }),
+    )
+    let captured: Error | undefined
+
+    app.use(async (c, next) => {
+      await next()
+      captured = c.error
+    })
+    app.get('/', (c) => Response.upstream(c, cause, { page: 584 }))
+
+    const response = await app.request('/')
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "query_invalid",
+          "message": "The requested page was rejected. Use cursor pagination for deep traversal.",
+        },
+      }
+    `)
+    expect(captured).toBe(cause)
+  })
+
+  test('keeps timeouts without a deep positional page as upstream errors', async () => {
+    const app = new Hono()
+    const cause = new Tidx.FetchRequestError(
+      'Request timeout',
+      new globalThis.Response(null, { status: 408 }),
+    )
+    app.get('/', (c) => Response.upstream(c, cause, { page: undefined }))
+
+    const response = await app.request('/')
+    expect(response.status).toMatchInlineSnapshot(`502`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "upstream_error",
+          "message": "Upstream service could not complete the request",
+        },
+      }
+    `)
+  })
+
+  test('keeps query rejections without a deep positional page as upstream errors', async () => {
+    const app = new Hono()
+    const cause = new Tidx.FetchRequestError(
+      'Query rejected',
+      new globalThis.Response(null, { status: 422 }),
+    )
+    app.get('/', (c) => Response.upstream(c, cause, { page: undefined }))
+
+    const response = await app.request('/')
+    expect(response.status).toMatchInlineSnapshot(`502`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "upstream_error",
+          "message": "Upstream service could not complete the request",
+        },
+      }
+    `)
+  })
 })

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

package/src/internal/Schema.test.ts

@@ -1,3 +1,5 @@
+import * as z from 'zod/mini'
+
 import * as Schema from './Schema.js'
 
 describe('ChainId', () => {
@@ -51,6 +53,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

@@ -191,6 +191,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 +386,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 +443,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,3 +1,4 @@
+import { HonoRequest } from 'hono/request'
 import { Store } from 'tapimo'
 import * as TestStore from '../../test/Store.js'
 
@@ -754,6 +755,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()
@@ -836,6 +849,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 +1010,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 +1106,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)
+  }
+}

package/src/internal/Store.ts

@@ -575,26 +575,62 @@ export declare namespace durableObject {
   }
 }
 
+/** Associates request cache directives with a store used by request handlers. */
+export function withRequest(store: Store, request: withRequest.Request): Store {
+  const source = requestStores.get(store)?.store ?? store
+  const scoped = {
+    delete: source.delete.bind(source),
+    ...(source.deleteIf ? { deleteIf: source.deleteIf.bind(source) } : {}),
+    get: source.get.bind(source),
+    ...(source.increment ? { increment: source.increment.bind(source) } : {}),
+    list: source.list.bind(source),
+    put: source.put.bind(source),
+    ...(source.swap ? { swap: source.swap.bind(source) } : {}),
+    type: source.type,
+  }
+  requestStores.set(scoped, { request, store: source })
+  return scoped
+}
+
+export declare namespace withRequest {
+  /** Request surface needed to read cache directives. */
+  type Request = {
+    /** Reads one request header. */
+    header(name: string): string | undefined
+  }
+}
+
 /**
- * Wraps an async producer with store-backed caching. Returns the cached value if
- * present and valid; otherwise runs `fetch`, stores the JSON-encoded result
- * under `key` with `ttl` milliseconds, and returns it. Undefined results are
- * returned without being cached.
+ * Returns a cached value when present. Otherwise, runs `fetch` and stores its
+ * result unless undefined or rejected by `shouldCache`.
  */
 export async function memoize<value>(
   fetch: () => Promise<value>,
-  options: memoize.Options,
+  options: memoize.Options<value>,
 ): Promise<value> {
-  const { key, store, ttl } = options
-
-  const raw = await store.get(key)
-  // Old cache entries used ambiguous untagged bigint strings. Refresh them
-  // instead of guessing whether a matching string was originally a bigint.
-  if (raw?.startsWith(jsonCodecPrefix)) {
-    try {
-      return jsonDecode(raw) as value
-    } catch {
-      // Corrupt entries are treated as misses so the next call refreshes.
+  const scoped = requestStores.get(options.store)
+  const { key, ttl } = options
+  const request = scoped?.request
+  const store = scoped?.store ?? options.store
+
+  // Request cache directives follow the same semantics as the response cache:
+  // no-cache refreshes the entry, while no-store bypasses it entirely.
+  const cacheControl = request?.header('cache-control')
+  const directives = (cacheControl ?? request?.header('pragma') ?? '').toLowerCase()
+  const noStore = directives.includes('no-store')
+  const noCache = noStore || directives.includes('no-cache')
+  if (noStore) return fetch()
+
+  if (!noCache) {
+    const raw = await store.get(key)
+    // Old cache entries used ambiguous untagged bigint strings. Refresh them
+    // instead of guessing whether a matching string was originally a bigint.
+    if (raw?.startsWith(jsonCodecPrefix)) {
+      try {
+        return jsonDecode(raw) as value
+      } catch {
+        // Corrupt entries are treated as misses so the next call refreshes.
+      }
     }
   }
 
@@ -606,8 +642,9 @@ export async function memoize<value>(
   // boundary; this only prevents a local cold-key stampede while the first
   // fetch is still in flight.
   const flight = (async () => {
+    if (noCache) await store.delete(key)
     const value = await fetch()
-    if (value === undefined) return value
+    if (value === undefined || options.shouldCache?.(value) === false) return value
     await store.put(key, jsonEncode(value), { ttl })
     return value
   })()
@@ -622,9 +659,11 @@ export async function memoize<value>(
 
 export declare namespace memoize {
   /** Options for {@link memoize}. */
-  type Options = {
+  type Options<value = unknown> = {
     /** Cache key. Callers are responsible for namespacing/versioning. */
     key: string
+    /** Returns whether a fetched value should be stored. Single-flight callers still share it. */
+    shouldCache?: ((value: value) => boolean) | undefined
     /** Store used to persist cache entries. */
     store: Store
     /** Time-to-live in milliseconds. */
@@ -632,6 +671,7 @@ export declare namespace memoize {
   }
 }
 
+const requestStores = new WeakMap<Store, { request: withRequest.Request; store: Store }>()
 const flights = new WeakMap<Store, Map<string, Promise<unknown>>>()
 
 function flightsFor(store: Store) {

package/src/internal/Tidx.test.ts

@@ -59,10 +59,16 @@ describe('providerFailure', () => {
 
   test('classifies timeout and rate-limit statuses', () => {
     expect([
+      Tidx.providerFailure(appError('query timed out')),
       Tidx.providerFailure(appError('secret upstream detail', 408)),
       Tidx.providerFailure(appError('secret upstream detail', 429)),
     ]).toMatchInlineSnapshot(`
       [
+        {
+          "failure": "timeout",
+          "id": "tidx",
+          "operation": "query",
+        },
         {
           "failure": "timeout",
           "id": "tidx",
@@ -135,6 +141,19 @@ describe('isQueryRejection', () => {
   })
 })
 
+describe('isQueryTimeout', () => {
+  test('matches explicit indexer query timeout failures only', () => {
+    expect([
+      Tidx.isQueryTimeout(appError('Request timeout', 408)),
+      Tidx.isQueryTimeout(appError('query timed out')),
+      Tidx.isQueryTimeout(appError('error sending request for url (...)')),
+      Tidx.isQueryTimeout(appError('db error')),
+      Tidx.isQueryTimeout(appError('Request timeout', 429)),
+      Tidx.isQueryTimeout(new DOMException('query timed out', 'TimeoutError')),
+    ]).toEqual([true, true, true, false, false, false])
+  })
+})
+
 describe('escape', () => {
   test('doubles quotes for ANSI string literals, leaving backslashes alone', () => {
     expect(Tidx.escape('USD')).toMatchInlineSnapshot(`"USD"`)

package/src/internal/Tidx.ts

@@ -142,8 +142,10 @@ const transientRetryDelay = 250
  * dropped at the server's execution cap — typically a cold object-storage
  * cache read that warms across attempts, so retrying genuinely helps.
  */
-const transientErrorPattern =
-  /db error|timeout|timed out|connection reset|connection refused|error sending request/i
+const transientErrorPattern = /db error|connection reset|connection refused/i
+
+/** Indexer failures caused by the query execution deadline. */
+const queryTimeoutPattern = /timeout|timed out|error sending request/i
 
 /**
  * Escapes a free-form string for safe embedding inside a single-quoted SQL
@@ -239,8 +241,11 @@ export function providerFailure(cause: unknown): Log.ProviderFailure {
     return { ...base, failure: 'timeout' }
 
   const status = Errors.getStatus(cause)
+  if (isQueryTimeout(cause))
+    return status === 408
+      ? { ...base, failure: 'timeout', status }
+      : { ...base, failure: 'timeout' }
   if (status !== undefined && status >= 200 && status < 300) return { ...base, failure: 'payload' }
-  if (status === 408) return { ...base, failure: 'timeout', status }
   if (status === 422) return { ...base, failure: 'query', status }
   if (status === 429) return { ...base, failure: 'rate_limit', status }
   if (status !== undefined) return { ...base, failure: 'http', status }
@@ -270,6 +275,13 @@ export function isQueryRejection(cause: unknown): boolean {
   return status === 400 || status === 422
 }
 
+/** Whether a failed TIDX request exhausted its query execution deadline. */
+export function isQueryTimeout(cause: unknown): boolean {
+  if (!(cause instanceof Tidx.FetchRequestError)) return false
+  if (cause.status === 408) return true
+  return cause.status >= 200 && cause.status < 300 && queryTimeoutPattern.test(cause.message)
+}
+
 /**
  * True for deterministic indexer failures a retry cannot fix: a
  * `FetchRequestError` outside {@link isTransientError}'s transient classes,
@@ -294,7 +306,7 @@ export function isDeterministicError(error: unknown): boolean {
  */
 function isTransientError(error: unknown): boolean {
   if (!(error instanceof Tidx.FetchRequestError)) return false
-  if (error.status === 408 || error.status === 429 || error.status >= 500) return true
+  if (isQueryTimeout(error) || error.status === 429 || error.status >= 500) return true
   return error.status >= 200 && error.status < 300 && transientErrorPattern.test(error.message)
 }