tapimo 0.0.0 → 0.0.2

package/src/internal/Tidx.test.ts

@@ -0,0 +1,294 @@
+import { Tidx as TidxClient } from 'tidx.ts'
+
+import type * as Auth from './Auth.js'
+import * as Tidx from './Tidx.js'
+import type * as Viem from './Viem.js'
+
+/** Anonymous (public) request principal. */
+const publicPrincipal: Auth.Principal = { id: 'pub', type: 'public' }
+/** Authenticated API-key request principal. */
+const apiKeyPrincipal: Auth.Principal = {
+  apiKey: {} as never,
+  environment: 'production',
+  id: 'key_test',
+  orgId: 'org_test',
+  type: 'api_key',
+}
+
+/** Builds a `FetchRequestError` as the indexer surfaces it at a given status. */
+function appError(message: string, status = 200) {
+  return new TidxClient.FetchRequestError(message, new Response(null, { status }))
+}
+
+/** Minimal client whose `fetch` is a controllable mock. */
+function fakeClient(fetch: Tidx.Client['fetch']): Tidx.Client {
+  return { fetch } as never
+}
+
+describe('escape', () => {
+  test('doubles quotes for ANSI string literals, leaving backslashes alone', () => {
+    expect(Tidx.escape('USD')).toMatchInlineSnapshot(`"USD"`)
+    expect(Tidx.escape("US' OR '1'='1")).toMatchInlineSnapshot(`"US'' OR ''1''=''1"`)
+    expect(Tidx.escape('back\\slash')).toMatchInlineSnapshot(`"back\\slash"`)
+    expect(Tidx.escape("\\'")).toMatchInlineSnapshot(`"\\''"`)
+  })
+})
+
+describe('withTransientRetry', () => {
+  test('retries a transient `db error` and resolves once it succeeds', async () => {
+    vi.useFakeTimers()
+    try {
+      const result = { hasMore: false, rows: [] } as never
+      const fetch = vi
+        .fn()
+        .mockRejectedValueOnce(appError('db error'))
+        .mockRejectedValueOnce(appError('db error'))
+        .mockResolvedValueOnce(result)
+      const client = Tidx.withTransientRetry(fakeClient(fetch))
+
+      const promise = client.fetch({ chainId: 42431, query: 'SELECT 1' })
+      await vi.runAllTimersAsync()
+      await expect(promise).resolves.toBe(result)
+      expect(fetch).toHaveBeenCalledTimes(3)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  test('retries a dropped ClickHouse Cloud connection', async () => {
+    vi.useFakeTimers()
+    try {
+      const result = { hasMore: false, rows: [] } as never
+      const fetch = vi
+        .fn()
+        .mockRejectedValueOnce(
+          appError('ClickHouse HTTP request failed: error sending request for url (…)'),
+        )
+        .mockResolvedValueOnce(result)
+      const client = Tidx.withTransientRetry(fakeClient(fetch))
+
+      const promise = client.fetch({ chainId: 42431, query: 'SELECT 1' })
+      await vi.runAllTimersAsync()
+      await expect(promise).resolves.toBe(result)
+      expect(fetch).toHaveBeenCalledTimes(2)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  test('retries HTTP-level transient failures under the shared budget', async () => {
+    vi.useFakeTimers()
+    try {
+      const result = { hasMore: false, rows: [] } as never
+      const fetch = vi
+        .fn()
+        .mockRejectedValueOnce(appError('bad gateway', 502))
+        .mockRejectedValueOnce(appError('too many requests', 429))
+        .mockResolvedValueOnce(result)
+      const client = Tidx.withTransientRetry(fakeClient(fetch))
+
+      const promise = client.fetch({ chainId: 42431, query: 'SELECT 1' })
+      await vi.runAllTimersAsync()
+      await expect(promise).resolves.toBe(result)
+      expect(fetch).toHaveBeenCalledTimes(3)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  test('disables the inner client retries so the budget is not multiplied', async () => {
+    const fetch = vi.fn().mockResolvedValue({ hasMore: false, rows: [] } as never)
+    const client = Tidx.withTransientRetry(fakeClient(fetch))
+
+    await client.fetch({ chainId: 42431, query: 'SELECT 1' })
+
+    expect(fetch.mock.calls[0]![0]).toMatchInlineSnapshot(`
+      {
+        "chainId": 42431,
+        "query": "SELECT 1",
+        "retryCount": 1,
+      }
+    `)
+  })
+
+  test('does not retry a deterministic application error', async () => {
+    const fetch = vi.fn().mockRejectedValue(appError('syntax error near "SELCT"'))
+    const client = Tidx.withTransientRetry(fakeClient(fetch))
+
+    await expect(client.fetch({ chainId: 42431, query: 'SELCT 1' })).rejects.toThrow('syntax error')
+    expect(fetch).toHaveBeenCalledTimes(1)
+  })
+
+  test('does not retry an HTTP 422 `db error` (deterministic query-shape failure)', async () => {
+    const fetch = vi.fn().mockRejectedValue(appError('db error', 422))
+    const client = Tidx.withTransientRetry(fakeClient(fetch))
+
+    await expect(client.fetch({ chainId: 42431, query: 'SELECT 1' })).rejects.toThrow('db error')
+    expect(fetch).toHaveBeenCalledTimes(1)
+  })
+
+  test('gives up after exhausting retries on persistent `db error`', async () => {
+    vi.useFakeTimers()
+    try {
+      const fetch = vi.fn().mockRejectedValue(appError('db error'))
+      const client = Tidx.withTransientRetry(fakeClient(fetch))
+
+      const promise = client.fetch({ chainId: 42431, query: 'SELECT 1' })
+      const assertion = expect(promise).rejects.toThrow('db error')
+      await vi.runAllTimersAsync()
+      await assertion
+      // First attempt plus four retries.
+      expect(fetch).toHaveBeenCalledTimes(5)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})
+
+describe('resolve', () => {
+  test('defaults to the per-chain indexer URL', () => {
+    expect(Tidx.resolve(undefined, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://indexer.tempo.xyz",
+        "basicAuth": undefined,
+      }
+    `)
+    expect(Tidx.resolve(undefined, { chainId: 42431, principal: null })).toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://indexer.testnet.tempo.xyz",
+        "basicAuth": undefined,
+      }
+    `)
+  })
+
+  test('uses a static base URL override', () => {
+    expect(Tidx.resolve({ baseUrl: 'https://indexer.test' }, { chainId: 4217, principal: null }))
+      .toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://indexer.test",
+        "basicAuth": undefined,
+      }
+    `)
+  })
+
+  test('uses a base URL resolver override', () => {
+    expect(
+      Tidx.resolve(
+        { baseUrl: (chainId) => `https://${chainId}.indexer.test` },
+        { chainId: 42431, principal: null },
+      ),
+    ).toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://42431.indexer.test",
+        "basicAuth": undefined,
+      }
+    `)
+  })
+
+  test('the static form ignores the principal', () => {
+    const tidx = { baseUrl: 'https://internal.indexer', basicAuth: 'user:pass' }
+    expect(Tidx.resolve(tidx, { chainId: 4217, principal: publicPrincipal }))
+      .toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://internal.indexer",
+        "basicAuth": "user:pass",
+      }
+    `)
+    expect(Tidx.resolve(tidx, { chainId: 4217, principal: apiKeyPrincipal }))
+      .toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://internal.indexer",
+        "basicAuth": "user:pass",
+      }
+    `)
+  })
+
+  test('the resolver form routes anonymous callers to a separate upstream', () => {
+    const tidx = ({ principal }: Viem.resolve.Context) =>
+      principal?.type === 'public'
+        ? { baseUrl: 'https://indexer.tempo.xyz' }
+        : { baseUrl: 'https://internal.indexer', basicAuth: 'user:pass' }
+    expect(Tidx.resolve(tidx, { chainId: 4217, principal: publicPrincipal }))
+      .toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://indexer.tempo.xyz",
+        "basicAuth": undefined,
+      }
+    `)
+    expect(Tidx.resolve(tidx, { chainId: 4217, principal: apiKeyPrincipal }))
+      .toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://internal.indexer",
+        "basicAuth": "user:pass",
+      }
+    `)
+    // A null principal (trusted poller) takes the non-public branch.
+    expect(Tidx.resolve(tidx, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://internal.indexer",
+        "basicAuth": "user:pass",
+      }
+    `)
+  })
+
+  test('a resolver that omits baseUrl falls back to the built-in public host', () => {
+    const tidx = () => ({})
+    expect(Tidx.resolve(tidx, { chainId: 42431, principal: publicPrincipal }))
+      .toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://indexer.testnet.tempo.xyz",
+        "basicAuth": undefined,
+      }
+    `)
+  })
+})
+
+describe('createGetClient', () => {
+  test('memoizes one client per resolved upstream', () => {
+    const getTidx = Tidx.createGetClient({
+      tidx: ({ principal }) =>
+        principal?.type === 'public'
+          ? { baseUrl: 'https://indexer.tempo.xyz' }
+          : { baseUrl: 'https://internal.indexer', basicAuth: 'user:pass' },
+    })
+    // Callers resolving to the same upstream share a client; distinct upstreams
+    // (and chain ids) get distinct clients.
+    expect(getTidx(4217, apiKeyPrincipal)).toBe(getTidx(4217, apiKeyPrincipal))
+    expect(getTidx(4217, publicPrincipal)).toBe(getTidx(4217, publicPrincipal))
+    expect(getTidx(4217, publicPrincipal)).not.toBe(getTidx(4217, apiKeyPrincipal))
+    expect(getTidx(4217, apiKeyPrincipal)).not.toBe(getTidx(42431, apiKeyPrincipal))
+  })
+
+  test('shares a client across principals when the resolver ignores them', () => {
+    const getTidx = Tidx.createGetClient()
+    // With no resolver the upstream is identical for every caller, so the key
+    // (resolved output) collapses and all principals share one client.
+    expect(getTidx(4217, publicPrincipal)).toBe(getTidx(4217, apiKeyPrincipal))
+    expect(getTidx(4217, null)).toBe(getTidx(4217, publicPrincipal))
+  })
+
+  test('consults the resolver on every call but builds one client per upstream', () => {
+    const seen: (string | undefined)[] = []
+    const getTidx = Tidx.createGetClient({
+      tidx: ({ principal }) => {
+        const config =
+          principal?.type === 'public'
+            ? { baseUrl: 'https://indexer.tempo.xyz' }
+            : { baseUrl: 'https://internal.indexer', basicAuth: 'user:pass' }
+        seen.push(principal?.type)
+        return config
+      },
+    })
+    const first = getTidx(4217, apiKeyPrincipal)
+    const second = getTidx(4217, apiKeyPrincipal)
+    getTidx(4217, publicPrincipal)
+    // The resolver is consulted on every call (it derives the cache key from its
+    // resolved output) — including the repeat that hits the cache — so a
+    // per-request principal is always honored.
+    expect(seen).toContain('api_key')
+    expect(seen).toContain('public')
+    expect(seen.length).toBeGreaterThanOrEqual(3)
+    // …but the client itself (the costly construction) is built once per upstream.
+    expect(first).toBe(second)
+  })
+})

package/src/internal/Tidx.ts

@@ -0,0 +1,238 @@
+import { Tidx } from 'tidx.ts'
+
+import type * as Auth from './Auth.js'
+import * as Viem from './Viem.js'
+
+/** Default Tempo indexer (TIDX) base URLs. */
+export const url: Record<number, string> = {
+  4217: 'https://indexer.tempo.xyz',
+  42431: 'https://indexer.testnet.tempo.xyz',
+}
+
+/** TIDX query client. */
+export type Client = Tidx.Tidx
+
+/** Gets a TIDX query client for a Tempo chain id and request principal. */
+export type GetClient = (chainId?: Viem.ChainId, principal?: Auth.Principal | null) => Client
+
+/**
+ * Resolves a TIDX base URL for a Tempo chain id. May return `undefined` to fall
+ * back to the built-in {@link url} map (e.g. for a chain the resolver doesn't
+ * serve).
+ */
+export type UrlResolver = (chainId: Viem.ChainId) => string | undefined
+
+/**
+ * Resolves the effective TIDX config for a single request.
+ *
+ * Accepts either a static config object or a per-request resolver function that
+ * receives a {@link Viem.resolve.Context} (`chainId` plus the request
+ * `principal`), so callers can route traffic per caller — e.g. send anonymous
+ * (`principal.type === 'public'`) traffic to a separate, no-auth indexer. A
+ * missing `baseUrl` falls back to the built-in public host map ({@link url}); a
+ * missing `basicAuth` means no Basic auth is sent.
+ */
+export function resolve(
+  tidx: getClient.Tidx | undefined,
+  context: Viem.resolve.Context,
+): resolve.Resolved {
+  const config = typeof tidx === 'function' ? tidx(context) : tidx
+  return {
+    baseUrl:
+      (typeof config?.baseUrl === 'function' ? config.baseUrl(context.chainId) : config?.baseUrl) ??
+      url[context.chainId],
+    basicAuth: config?.basicAuth,
+  }
+}
+
+export declare namespace resolve {
+  /** Resolved TIDX config for a single request. */
+  type Resolved = {
+    /**
+     * Resolved TIDX base URL, or `undefined` when neither a configured `tidx`
+     * nor the built-in {@link url} map covers the chain (e.g. an unconfigured
+     * localnet). A `undefined` base URL falls through to the TIDX client default.
+     */
+    baseUrl: string | undefined
+    /** Basic auth credentials, or undefined to send no Basic auth. */
+    basicAuth?: string | undefined
+  }
+}
+
+export function getClient(options: getClient.Options): Client {
+  const { chainId = Viem.defaultChainId, principal = null, tidx } = options
+  const { baseUrl, basicAuth } = resolve(tidx, { chainId, principal })
+  return withTransientRetry(Tidx.create({ baseUrl, basicAuth, chainId }))
+}
+
+/**
+ * Builds a memoized {@link GetClient} that constructs one TIDX client per
+ * resolved upstream and reuses it. Clients are stateless HTTP transports, so
+ * reusing them avoids per-call construction cost. The cache key is the resolved
+ * output (`baseUrl` + `basicAuth` + `chainId`), not the principal, so a resolver
+ * `tidx` may branch on any principal field while client cardinality stays
+ * bounded by the number of distinct upstreams — callers that resolve to the same
+ * upstream share a client. Shared by `App.create` (per-request reads) and
+ * `Webhooks.createPoller` (the scheduled poller) so the resolver logic lives in
+ * one place.
+ */
+export function createGetClient(options: createGetClient.Options = {}): GetClient {
+  const { defaultChainId = Viem.defaultChainId, tidx } = options
+  const clients = new Map<string, Client>()
+
+  return (chainId = defaultChainId, principal = null) => {
+    // Resolve to derive the cache key; `getClient` re-resolves to build the
+    // client on a miss. `resolve` is pure and cheap, so the extra call is free.
+    const { baseUrl, basicAuth } = resolve(tidx, { chainId, principal })
+    const cacheKey = `${baseUrl}|${basicAuth ?? ''}|${chainId}`
+    const existing = clients.get(cacheKey)
+    if (existing) return existing
+
+    const client = getClient({ chainId, principal, tidx })
+    clients.set(cacheKey, client)
+    return client
+  }
+}
+
+/**
+ * Number of additional `fetch` attempts for transient application-level
+ * indexer errors. The first attempt plus this many retries.
+ *
+ * Combined with {@link transientRetryDelay} this gives a ~3.75s backoff window
+ * (250 + 500 + 1000 + 2000ms over five attempts). The heaviest reads — e.g.
+ * the unfiltered global swap scan — can momentarily trip the indexer's `db
+ * error` under concurrent load, and a ~1s window was too short to ride those
+ * bursts out, surfacing them to callers as a 502.
+ */
+const transientRetryCount = 4
+
+/** Base backoff (ms) between transient-error retries; doubles each attempt. */
+const transientRetryDelay = 250
+
+/**
+ * Application-level indexer failures that are transient and safe to retry on
+ * an idempotent read. The indexer surfaces transient ClickHouse failures (a
+ * busy/contended planner, a query-execution hiccup) as the literal message
+ * `db error`; timeouts and connection resets are likewise non-deterministic.
+ * `error sending request` is how TIDX reports a ClickHouse Cloud connection
+ * 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
+
+/**
+ * Escapes a free-form string for safe embedding inside a single-quoted SQL
+ * string literal sent to the indexer. TIDX parses every query with an ANSI
+ * SQL parser before re-rendering it for the engine, and ANSI strings have
+ * exactly one special character inside `'…'`: the quote itself, escaped by
+ * doubling (`''`). Backslash escaping (`\'`) is **rejected** with a parse
+ * error, and a backslash is an ordinary character on both engines (verified
+ * against the deployed indexer on `postgres` and `clickhouse`).
+ *
+ * Most interpolated values (addresses, hashes, ISO timestamps) are already
+ * schema-constrained to charsets that cannot contain a quote; reach for this
+ * whenever a query must interpolate genuinely free-form user input (e.g. the
+ * token `currency` filter).
+ */
+export function escape(value: string) {
+  return value.replaceAll("'", "''")
+}
+
+/**
+ * Wraps a TIDX client so `fetch` retries transient errors under **one**
+ * shared budget ({@link transientRetryCount} retries with backoff).
+ *
+ * Two transient failure modes are covered: HTTP-level failures (408/429/5xx)
+ * and the indexer's transient ClickHouse errors, which arrive as **HTTP 200**
+ * with an `{ ok: false, error: 'db error' }` body (a `FetchRequestError`
+ * whose `status` is 200). The raw `tidx.ts` client would retry the HTTP-level
+ * mode itself (5 attempts), which stacked multiplicatively under this wrapper
+ * — one flapping query shape could cost ~25 upstream executions — so the
+ * wrapper disables the client-level retries (`retryCount: 1`) and owns the
+ * whole budget: at most {@link transientRetryCount} + 1 upstream executions.
+ * Deterministic errors (e.g. a malformed query) fall through immediately.
+ */
+export function withTransientRetry(client: Client): Client {
+  const fetch = client.fetch.bind(client)
+  return {
+    ...client,
+    fetch: async (options) => {
+      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 })
+        } catch (error) {
+          if (!isTransientError(error)) throw error
+          lastError = error
+          if (attempt < transientRetryCount)
+            await new Promise((resolve) => setTimeout(resolve, transientRetryDelay * 2 ** attempt))
+        }
+      }
+      throw lastError
+    },
+  }
+}
+
+/**
+ * True for transient indexer errors: an HTTP-level transient failure
+ * (408/429/5xx), or a `FetchRequestError` that came back on a **2xx** HTTP
+ * response whose message matches a known transient failure.
+ *
+ * The 2xx gate on the message pattern matters. The indexer reports two
+ * different `db error`s: a transient ClickHouse hiccup arrives on an HTTP 200
+ * with `{ ok: false, error: 'db error' }` (worth retrying), whereas an HTTP
+ * 422 `db error` means the planner cannot execute that query shape at all — a
+ * deterministic failure that will never succeed on retry. Retrying the latter
+ * would just burn the backoff budget before failing anyway, so 4xx statuses
+ * other than 408/429 are excluded.
+ */
+function isTransientError(error: unknown): boolean {
+  if (!(error instanceof Tidx.FetchRequestError)) return false
+  if (error.status === 408 || error.status === 429 || error.status >= 500) return true
+  return error.status >= 200 && error.status < 300 && transientErrorPattern.test(error.message)
+}
+
+export declare namespace getClient {
+  /** Options for getting a TIDX query client. */
+  type Options = {
+    /** Tempo chain id. */
+    chainId?: Viem.ChainId | undefined
+    /** Request principal, or `null`/omitted for a trusted non-request caller. */
+    principal?: Auth.Principal | null | undefined
+    /** TIDX query client options. */
+    tidx?: Tidx | undefined
+  }
+
+  /**
+   * TIDX query client options: either a static config, or a per-request
+   * resolver function that receives a {@link Viem.resolve.Context} and returns
+   * the config to use (e.g. routing anonymous callers to a public, no-auth
+   * indexer).
+   */
+  type Tidx =
+    | {
+        /** Resolves the TIDX base URL for a Tempo chain id, or a static base URL. */
+        baseUrl?: UrlResolver | string | undefined
+        /** Basic auth credentials for TIDX requests. */
+        basicAuth?: string | undefined
+      }
+    | ((context: Viem.resolve.Context) => {
+        /** TIDX base URL to use; falls back to the built-in public host when omitted. */
+        baseUrl?: string | undefined
+        /** Basic auth credentials for TIDX requests, or undefined for none. */
+        basicAuth?: string | undefined
+      })
+}
+
+export declare namespace createGetClient {
+  /** Options for building a memoized TIDX client resolver. */
+  type Options = {
+    /** Tempo chain id used when a caller omits one. */
+    defaultChainId?: Viem.ChainId | undefined
+    /** TIDX query client options applied to every constructed client. */
+    tidx?: getClient.Tidx | undefined
+  }
+}

package/src/internal/Timing.test.ts

@@ -0,0 +1,22 @@
+import { Hono } from 'hono'
+import * as Timing from './Timing.js'
+
+describe('middleware', () => {
+  test('emits request and operation server timings', async () => {
+    const app = new Hono<{ Variables: Timing.Variables }>()
+
+    app.use('*', Timing.middleware())
+    app.get('/', async (c) => {
+      await Timing.time(c, 'example.work', () => Promise.resolve())
+      return c.text('ok')
+    })
+
+    const response = await app.request('/')
+    const timing = response.headers.get('server-timing')
+
+    expect(response.status).toMatchInlineSnapshot(`200`)
+    expect(response.headers.get('content-type')).toMatchInlineSnapshot(`"text/plain;charset=UTF-8"`)
+    expect(timing?.includes('example.work;dur=')).toMatchInlineSnapshot(`true`)
+    expect(timing?.includes('request;dur=')).toMatchInlineSnapshot(`true`)
+  })
+})

package/src/internal/Timing.ts

@@ -0,0 +1,62 @@
+import type { Context, MiddlewareHandler } from 'hono'
+
+/** Hono variables used to collect Server-Timing metrics. */
+export type Variables = {
+  /** Metrics emitted in the `Server-Timing` response header. */
+  serverTiming?: Metric[] | undefined
+}
+
+/** Hono environment shape used by timing helpers. */
+export type Environment = {
+  Variables: Variables
+}
+
+/** One Server-Timing metric. */
+export type Metric = {
+  /** Metric duration in milliseconds. */
+  duration: number
+  /** Metric name. */
+  name: string
+}
+
+/** Adds a `Server-Timing` header with total request duration. */
+export function middleware<
+  environment extends Environment = Environment,
+>(): MiddlewareHandler<environment> {
+  return async (c, next) => {
+    const metrics: Metric[] = []
+    c.set('serverTiming', metrics)
+
+    const start = performance.now()
+    await next()
+    metrics.push({ duration: performance.now() - start, name: 'request' })
+
+    const value = format(metrics)
+    const existing = c.res.headers.get('Server-Timing')
+    c.res.headers.set('Server-Timing', existing ? `${existing}, ${value}` : value)
+  }
+}
+
+/** Measures one async operation and adds it to the current request timings. */
+export async function time<environment extends Environment, value>(
+  c: Context<environment>,
+  name: string,
+  fn: () => Promise<value> | value,
+) {
+  const start = performance.now()
+  try {
+    return await fn()
+  } finally {
+    c.get('serverTiming')?.push({ duration: performance.now() - start, name })
+  }
+}
+
+function format(metrics: readonly Metric[]) {
+  return metrics
+    .map((metric) => `${name(metric.name)};dur=${metric.duration.toFixed(1)}`)
+    .join(', ')
+}
+
+function name(value: string) {
+  return value.replace(/[^A-Za-z0-9_.*-]/g, '_')
+}

package/src/internal/Ttl.test.ts

@@ -0,0 +1,18 @@
+import * as Ttl from './Ttl.js'
+
+describe('Ttl', () => {
+  test('converts common durations to milliseconds', () => {
+    expect(Ttl.millisecond(1)).toMatchInlineSnapshot(`1`)
+    expect(Ttl.milliseconds(2)).toMatchInlineSnapshot(`2`)
+    expect(Ttl.second(1)).toMatchInlineSnapshot(`1000`)
+    expect(Ttl.seconds(2)).toMatchInlineSnapshot(`2000`)
+    expect(Ttl.minute(1)).toMatchInlineSnapshot(`60000`)
+    expect(Ttl.minutes(2)).toMatchInlineSnapshot(`120000`)
+    expect(Ttl.hour(1)).toMatchInlineSnapshot(`3600000`)
+    expect(Ttl.hours(2)).toMatchInlineSnapshot(`7200000`)
+    expect(Ttl.day(1)).toMatchInlineSnapshot(`86400000`)
+    expect(Ttl.days(2)).toMatchInlineSnapshot(`172800000`)
+    expect(Ttl.week(1)).toMatchInlineSnapshot(`604800000`)
+    expect(Ttl.weeks(2)).toMatchInlineSnapshot(`1209600000`)
+  })
+})

package/src/internal/Ttl.ts

@@ -0,0 +1,59 @@
+/** Returns milliseconds from milliseconds. */
+export function milliseconds(value: number) {
+  return value
+}
+
+/** Returns milliseconds from seconds. */
+export function seconds(value: number) {
+  return value * 1_000
+}
+
+/** Returns milliseconds from minutes. */
+export function minutes(value: number) {
+  return seconds(value) * 60
+}
+
+/** Returns milliseconds from hours. */
+export function hours(value: number) {
+  return minutes(value) * 60
+}
+
+/** Returns milliseconds from days. */
+export function days(value: number) {
+  return hours(value) * 24
+}
+
+/** Returns milliseconds from weeks. */
+export function weeks(value: number) {
+  return days(value) * 7
+}
+
+/** Returns milliseconds from milliseconds. */
+export function millisecond(value: number) {
+  return milliseconds(value)
+}
+
+/** Returns milliseconds from seconds. */
+export function second(value: number) {
+  return seconds(value)
+}
+
+/** Returns milliseconds from minutes. */
+export function minute(value: number) {
+  return minutes(value)
+}
+
+/** Returns milliseconds from hours. */
+export function hour(value: number) {
+  return hours(value)
+}
+
+/** Returns milliseconds from days. */
+export function day(value: number) {
+  return days(value)
+}
+
+/** Returns milliseconds from weeks. */
+export function week(value: number) {
+  return weeks(value)
+}