tapimo 0.11.0 → 0.13.0

package/src/internal/Store.ts

@@ -1,5 +1,7 @@
 import { Json } from 'ox'
 
+import * as Timeout from './Timeout.js'
+
 /** Key-to-value map used by typed stores. */
 export type StoreItemMap = Record<string, unknown>
 
@@ -575,26 +577,78 @@ export declare namespace durableObject {
   }
 }
 
+/** Associates request cache directives with a store used by request handlers. */
+export function withRequest(
+  store: Store,
+  request: withRequest.Request,
+  options: withRequest.Options = {},
+): 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, waitUntil: options.waitUntil })
+  return scoped
+}
+
+export declare namespace withRequest {
+  /** Request-scoped cache behavior. */
+  export type Options = {
+    /** Keeps asynchronous cache persistence alive after the response returns. */
+    waitUntil?: ((promise: Promise<unknown>) => void) | undefined
+  }
+  /** Request surface needed to read cache directives. */
+  export 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`. Cache persistence is
+ * best-effort and never delays the fetched value.
  */
 export async function memoize<value>(
-  fetch: () => Promise<value>,
-  options: memoize.Options,
+  fetch: (signal?: AbortSignal) => Promise<value>,
+  options: memoize.Options<value>,
 ): Promise<value> {
-  const { key, store, ttl } = options
+  const scoped = requestStores.get(options.store)
+  const { key, ttl } = options
+  const flightTimeout = options.flightTimeout ?? Timeout.duration
+  const request = scoped?.request
+  const store = scoped?.store ?? options.store
+  const waitUntil = scoped?.waitUntil
+
+  // 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 Timeout.run((signal) => fetch(signal), {
+      error: new MemoizeTimeoutError(flightTimeout),
+      timeout: flightTimeout,
+    })
 
-  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.
+  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.
+      }
     }
   }
 
@@ -605,26 +659,81 @@ export async function memoize<value>(
   // Coalesce concurrent misses for this process. The store remains the cache
   // boundary; this only prevents a local cold-key stampede while the first
   // fetch is still in flight.
-  const flight = (async () => {
-    const value = await fetch()
-    if (value === undefined) return value
-    await store.put(key, jsonEncode(value), { ttl })
+  let mutating = noCache
+  let settled = false
+  const work = async (signal?: AbortSignal) => {
+    if (noCache) {
+      try {
+        await store.delete(key)
+      } finally {
+        mutating = false
+      }
+    }
+    signal?.throwIfAborted()
+    mutating = false
+    const value = await fetch(signal)
+    signal?.throwIfAborted()
+    if (value === undefined || options.shouldCache?.(value) === false) return value
+    mutating = true
+    if (store.type === 'cache') {
+      // A lossy cache write cannot turn a successful origin read into an error.
+      const persist = Promise.resolve()
+        .then(() => store.put(key, jsonEncode(value), { ttl }))
+        .catch(() => {})
+      if (waitUntil)
+        try {
+          waitUntil(persist)
+          mutating = false
+          return value
+        } catch {}
+      try {
+        await persist
+      } finally {
+        mutating = false
+      }
+      return value
+    }
+    try {
+      await store.put(key, jsonEncode(value), { ttl })
+    } finally {
+      mutating = false
+    }
     return value
-  })()
-  flights.set(key, flight)
-
-  try {
-    return await flight
-  } finally {
-    flights.delete(key)
   }
+  let flight!: Promise<value>
+  const release = () => {
+    // A canceled fetch cannot mutate the cache after its next abort check.
+    // Non-cancelable cache mutations retain ownership until they settle.
+    if ((settled || !mutating) && flights.get(key) === flight) flights.delete(key)
+  }
+  flight = Timeout.run(
+    async (signal) => {
+      signal.addEventListener('abort', release, { once: true })
+      try {
+        return await work(signal)
+      } finally {
+        settled = true
+        release()
+      }
+    },
+    {
+      error: new MemoizeTimeoutError(flightTimeout),
+      timeout: flightTimeout,
+    },
+  )
+  flights.set(key, flight)
+  return flight
 }
 
 export declare namespace memoize {
   /** Options for {@link memoize}. */
-  type Options = {
+  type Options<value = unknown> = {
+    /** Maximum shared cache-miss flight duration in milliseconds. Defaults to 15 seconds. */
+    flightTimeout?: number | undefined
     /** 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 +741,14 @@ export declare namespace memoize {
   }
 }
 
+const requestStores = new WeakMap<
+  Store,
+  {
+    request: withRequest.Request
+    store: Store
+    waitUntil?: ((promise: Promise<unknown>) => void) | undefined
+  }
+>()
 const flights = new WeakMap<Store, Map<string, Promise<unknown>>>()
 
 function flightsFor(store: Store) {
@@ -829,6 +946,15 @@ function isDurableObjectValue(value: unknown): value is DurableObjectValue {
   )
 }
 
+/** Thrown when a shared memoized cache-miss flight exceeds its configured deadline. */
+export class MemoizeTimeoutError extends Error {
+  override name = 'Store.MemoizeTimeoutError'
+
+  constructor(timeout: number) {
+    super(`Memoized cache-miss flight timed out after ${timeout}ms.`)
+  }
+}
+
 /** Thrown when {@link update} exhausts its compare-and-swap attempts. */
 export class UpdateContentionError extends Error {
   override name = 'Store.UpdateContentionError'

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"`)
@@ -212,7 +231,8 @@ describe('withTransientRetry', () => {
 
     await client.fetch({ chainId: 42431, query: 'SELECT 1' })
 
-    expect(fetch.mock.calls[0]![0]).toMatchInlineSnapshot(`
+    const { signal: _signal, ...options } = fetch.mock.calls[0]![0]
+    expect(options).toMatchInlineSnapshot(`
       {
         "chainId": 42431,
         "query": "SELECT 1",

package/src/internal/Tidx.ts

@@ -5,6 +5,7 @@ import type * as Auth from './Auth.js'
 import * as Credential from './Credential.js'
 import * as Errors from './Errors.js'
 import type * as Log from './Log.js'
+import * as Timeout from './Timeout.js'
 import * as Viem from './Viem.js'
 
 /** Default Tempo indexer (TIDX) base URLs. */
@@ -142,8 +143,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
@@ -182,17 +185,21 @@ export function withTransientRetry(client: Client): Client {
   return {
     ...client,
     fetch: async (options) => {
+      const signal = Timeout.signal({ signal: options.signal })
       let lastError: unknown
       for (let attempt = 0; attempt <= transientRetryCount; attempt++) {
         try {
           // `retryCount: 1` caps the inner client at a single HTTP attempt so
           // the combined budget stays this wrapper's alone.
-          return await fetch({ ...options, retryCount: 1 })
+          return await fetch({ ...options, retryCount: 1, signal })
         } catch (error) {
           if (!isTransientError(error)) throw error
           lastError = error
           if (attempt < transientRetryCount)
-            await new Promise((resolve) => setTimeout(resolve, transientRetryDelay * 2 ** attempt))
+            await Timeout.wait({
+              milliseconds: transientRetryDelay * 2 ** attempt,
+              signal,
+            })
         }
       }
       throw lastError
@@ -239,8 +246,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 +280,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 +311,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)
 }
 

package/src/internal/Timeout.test.ts

@@ -0,0 +1,35 @@
+import * as Timeout from './Timeout.js'
+
+describe('duration', () => {
+  test('uses a 15 second default', () => {
+    expect(Timeout.duration).toBe(15_000)
+  })
+})
+
+describe('signal', () => {
+  test('preserves a caller signal and otherwise creates a deadline', () => {
+    const caller = new AbortController().signal
+
+    expect(Timeout.signal({ signal: caller })).toBe(caller)
+    expect(Timeout.signal()).toBeInstanceOf(AbortSignal)
+  })
+})
+
+describe('wait', () => {
+  test('rejects with the abort reason and clears its timer', async () => {
+    vi.useFakeTimers()
+    try {
+      const controller = new AbortController()
+      const reason = new DOMException('deadline exceeded', 'TimeoutError')
+      const waiting = Timeout.wait({ milliseconds: 1_000, signal: controller.signal })
+      const rejection = expect(waiting).rejects.toBe(reason)
+
+      controller.abort(reason)
+
+      await rejection
+      expect(vi.getTimerCount()).toBe(0)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})

package/src/internal/Timeout.ts

@@ -0,0 +1,73 @@
+/** Default maximum duration for API dependency work. */
+export const duration = 15_000
+
+/** Returns a caller signal or a signal carrying the default deadline. */
+export function signal(options: signal.Options = {}): AbortSignal {
+  return options.signal ?? AbortSignal.timeout(options.timeout ?? duration)
+}
+
+export declare namespace signal {
+  /** Options for {@link signal}. */
+  type Options = {
+    /** Existing caller signal. */
+    signal?: AbortSignal | null | undefined
+    /** Default maximum duration in milliseconds. */
+    timeout?: number | undefined
+  }
+}
+
+/** Waits for a duration, rejecting immediately when `signal` aborts. */
+export function wait(options: wait.Options): Promise<void> {
+  options.signal.throwIfAborted()
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timer)
+      reject(options.signal.reason)
+    }
+    const timer = setTimeout(() => {
+      options.signal.removeEventListener('abort', abort)
+      resolve()
+    }, options.milliseconds)
+    options.signal.addEventListener('abort', abort, { once: true })
+  })
+}
+
+export declare namespace wait {
+  /** Options for {@link wait}. */
+  type Options = {
+    /** Duration to wait in milliseconds. */
+    milliseconds: number
+    /** Signal that cancels the wait. */
+    signal: AbortSignal
+  }
+}
+
+/** Runs asynchronous work under a hard deadline and aborts cooperative work. */
+export function run<value>(
+  work: (signal: AbortSignal) => Promise<value>,
+  options: run.Options = {},
+): Promise<value> {
+  const timeout = options.timeout ?? duration
+  const controller = new AbortController()
+  const timeoutError = new DOMException(`Timed out after ${timeout}ms.`, 'TimeoutError')
+  const error = options.error ?? timeoutError
+  const timer = setTimeout(() => controller.abort(timeoutError), timeout)
+  const operation = Promise.resolve().then(() => work(controller.signal))
+
+  return Promise.race([
+    operation,
+    new Promise<never>((_, reject) => {
+      controller.signal.addEventListener('abort', () => reject(error), { once: true })
+    }),
+  ]).finally(() => clearTimeout(timer))
+}
+
+export declare namespace run {
+  /** Options for {@link run}. */
+  type Options = {
+    /** Error returned to the caller when the deadline expires. */
+    error?: Error | undefined
+    /** Maximum duration in milliseconds. */
+    timeout?: number | undefined
+  }
+}

package/src/internal/Timing.ts

@@ -2,6 +2,8 @@ import type { Context, MiddlewareHandler } from 'hono'
 
 /** Hono variables used to collect Server-Timing metrics. */
 export type Variables = {
+  /** Operations that have started but not finished. */
+  activeTimings?: Active[] | undefined
   /** Metrics emitted in the `Server-Timing` response header. */
   serverTiming?: Metric[] | undefined
 }
@@ -19,12 +21,22 @@ export type Metric = {
   name: string
 }
 
+/** One operation that has started but not finished. */
+export type Active = {
+  /** Metric name. */
+  name: string
+  /** Monotonic start time. */
+  start: number
+}
+
 /** Adds a `Server-Timing` header with total request duration. */
 export function middleware<
   environment extends Environment = Environment,
 >(): MiddlewareHandler<environment> {
   return async (c, next) => {
+    const active: Active[] = []
     const metrics: Metric[] = []
+    c.set('activeTimings', active)
     c.set('serverTiming', metrics)
 
     const start = performance.now()
@@ -44,9 +56,13 @@ export async function time<environment extends Environment, value>(
   fn: () => Promise<value> | value,
 ) {
   const start = performance.now()
+  const active = { name, start }
+  c.get('activeTimings')?.push(active)
   try {
     return await fn()
   } finally {
+    const activeTimings = c.get('activeTimings')
+    if (activeTimings) activeTimings.splice(activeTimings.indexOf(active), 1)
     c.get('serverTiming')?.push({ duration: performance.now() - start, name })
   }
 }

package/src/internal/WebhookDestination.ts

@@ -176,6 +176,9 @@ export async function send(options: send.Options): Promise<Result> {
       signal: controller.signal,
     })
     const durationMs = clock() - start
+    // The body is never read; an unreleased stream holds its buffer and
+    // connection in the isolate until GC, which stacks up during drains.
+    response.body?.cancel().catch(() => {})
     if (
       options.rejectRedirects &&
       (response.status === 0 || (response.status >= 300 && response.status < 400))