tapimo 0.10.2 → 0.12.0

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)
 }