tapimo 0.12.0 → 0.13.0

package/src/internal/Store.test.ts

@@ -1,6 +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 = {
@@ -808,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

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>
 
@@ -576,7 +578,11 @@ export declare namespace durableObject {
 }
 
 /** Associates request cache directives with a store used by request handlers. */
-export function withRequest(store: Store, request: withRequest.Request): Store {
+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),
@@ -588,13 +594,18 @@ export function withRequest(store: Store, request: withRequest.Request): Store {
     ...(source.swap ? { swap: source.swap.bind(source) } : {}),
     type: source.type,
   }
-  requestStores.set(scoped, { request, store: source })
+  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. */
-  type Request = {
+  export type Request = {
     /** Reads one request header. */
     header(name: string): string | undefined
   }
@@ -602,16 +613,19 @@ export declare namespace withRequest {
 
 /**
  * Returns a cached value when present. Otherwise, runs `fetch` and stores its
- * result unless undefined or rejected by `shouldCache`.
+ * 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>,
+  fetch: (signal?: AbortSignal) => Promise<value>,
   options: memoize.Options<value>,
 ): Promise<value> {
   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.
@@ -619,7 +633,11 @@ export async function memoize<value>(
   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 (noStore)
+    return Timeout.run((signal) => fetch(signal), {
+      error: new MemoizeTimeoutError(flightTimeout),
+      timeout: flightTimeout,
+    })
 
   if (!noCache) {
     const raw = await store.get(key)
@@ -641,25 +659,77 @@ 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 () => {
-    if (noCache) await store.delete(key)
-    const value = await fetch()
+  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
-    await store.put(key, jsonEncode(value), { ttl })
+    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<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. */
@@ -671,7 +741,14 @@ export declare namespace memoize {
   }
 }
 
-const requestStores = new WeakMap<Store, { request: withRequest.Request; store: Store }>()
+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) {
@@ -869,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

@@ -231,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. */
@@ -184,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

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

package/src/internal/funding/Action.test.ts

@@ -132,7 +132,47 @@ describe('validateEvmCalls', () => {
         sourceTokenAddress: sourceToken,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Action.InvalidActionError: Stablecoin funding calls must not carry native value.]`,
+      `[Funding.Action.InvalidActionError: Native value must match a validated provider fee.]`,
     )
   })
+
+  test('accepts an exact provider-validated native value', () => {
+    Action.validateEvmCalls({
+      action: {
+        calls: [approveCall(1_000_000n), { ...depositCall, value: '0x10' }],
+        type: 'evm:calls',
+      },
+      nativeValues: [{ to: spender, value: '0x10' }],
+      sourceAmount: '1000000',
+      sourceTokenAddress: sourceToken,
+    })
+  })
+
+  test('rejects malformed native value allowances', () => {
+    expect(() =>
+      Action.validateEvmCalls({
+        action: { calls: [approveCall(1_000_000n), depositCall], type: 'evm:calls' },
+        nativeValues: [{ to: spender, value: '10' }],
+        sourceAmount: '1000000',
+        sourceTokenAddress: sourceToken,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Action.InvalidActionError: Malformed native value allowance.]`,
+    )
+  })
+
+  test('rejects native values outside the exact provider allowance', () => {
+    for (const call of [
+      { ...depositCall, to: `0x${'99'.repeat(20)}`, value: '0x10' },
+      { ...depositCall, value: '0x11' },
+    ])
+      expect(() =>
+        Action.validateEvmCalls({
+          action: { calls: [approveCall(1_000_000n), call], type: 'evm:calls' },
+          nativeValues: [{ to: spender, value: '0x10' }],
+          sourceAmount: '1000000',
+          sourceTokenAddress: sourceToken,
+        }),
+      ).toThrow(Action.InvalidActionError)
+  })
 })