tapimo 0.0.0 → 0.0.2

package/dist/internal/Store.js

@@ -0,0 +1,291 @@
+/**
+ * Wraps store operations into a {@link Store}, defaulting to an authoritative
+ * {@link State} store. Omit `type` for the common authoritative case; pass
+ * `type: 'cache'` to opt into a cache-kind store (non-enumerable, lossy — e.g.
+ * the Web Cache).
+ */
+export function from(store) {
+    // Default the discriminant so only cache-kind stores have to opt in.
+    return { ...store, type: store.type ?? 'state' };
+}
+/**
+ * Increments an integer counter on a store and returns the new value. A
+ * missing or expired key restarts at `1`; `ttl` applies like {@link Store.put}.
+ *
+ * Uses the store's native {@link Store.increment} when implemented (atomic
+ * where the backend executes it in one place — in-memory, inside a Durable
+ * Object). Otherwise falls back to a get + put read-modify-write, which
+ * costs two round trips on remote stores and can race under concurrency —
+ * fine for dev/in-process backends, not for enforced distributed counters.
+ */
+export async function increment(store, key, options = {}) {
+    if (store.increment)
+        return store.increment(key, options);
+    const count = Number((await store.get(key)) ?? 0) + 1;
+    await store.put(key, String(count), options);
+    return count;
+}
+/** Creates an in-memory store with TTL support. */
+export function memory(options = {}) {
+    const cells = new Map((options.entries ?? []).map(([key, value]) => [key, { expiresAt: undefined, value }]));
+    function read(key) {
+        const cell = cells.get(key);
+        if (!cell)
+            return null;
+        if (cell.expiresAt !== undefined && cell.expiresAt <= Date.now()) {
+            cells.delete(key);
+            return null;
+        }
+        return cell;
+    }
+    return from({
+        async delete(key) {
+            cells.delete(key);
+        },
+        async get(key) {
+            return read(key)?.value ?? null;
+        },
+        // Native increment: the read-modify-write is synchronous, so concurrent
+        // consumers cannot interleave between the read and the write.
+        async increment(key, options = {}) {
+            const count = Number(read(key)?.value ?? 0) + 1;
+            const expiresAt = options.ttl === undefined ? undefined : Date.now() + options.ttl;
+            cells.set(key, { expiresAt, value: String(count) });
+            return count;
+        },
+        async list(options = {}) {
+            const keys = Array.from(cells.keys())
+                .filter((key) => (!options.prefix || key.startsWith(options.prefix)) && read(key))
+                .sort()
+                .map((name) => ({ name }));
+            return { keys };
+        },
+        async put(key, value, options = {}) {
+            const expiresAt = options.ttl === undefined ? undefined : Date.now() + options.ttl;
+            cells.set(key, { expiresAt, value });
+        },
+    });
+}
+/**
+ * Creates a store backed by a Web Cache API instance (e.g. Cloudflare's
+ * colo-local `caches.default`). Values are stored as cache entries keyed by a
+ * synthetic URL, with `ttl` mapped to `Cache-Control: max-age`. The Web Cache
+ * cannot enumerate keys, so `list` returns no keys — use this for caching
+ * (get/put/delete) only, e.g. the origin read cache and edge response cache.
+ */
+export function cache(webCache) {
+    const request = (key) => new Request(`https://tempo-api.cache/${encodeURIComponent(key)}`);
+    return from({
+        async delete(key) {
+            await webCache.delete(request(key));
+        },
+        async get(key) {
+            const hit = await webCache.match(request(key));
+            return hit ? hit.text() : null;
+        },
+        async list() {
+            return { keys: [] };
+        },
+        async put(key, value, options = {}) {
+            // The Web Cache only persists responses with a positive freshness lifetime.
+            const seconds = Math.max(1, Math.ceil((options.ttl ?? 0) / 1_000));
+            const headers = new Headers({ 'Cache-Control': `max-age=${seconds}` });
+            await webCache.put(request(key), new Response(value, { headers }));
+        },
+        type: 'cache',
+    });
+}
+/** Creates a store backed by a Cloudflare Workers KV namespace. */
+export function cloudflareKv(namespace) {
+    return from({
+        async delete(key) {
+            await namespace.delete(key);
+        },
+        async get(key) {
+            return namespace.get(key);
+        },
+        async list(options = {}) {
+            const result = await namespace.list(options.prefix === undefined ? undefined : { prefix: options.prefix });
+            return { keys: result.keys.map(({ name }) => ({ name })) };
+        },
+        async put(key, value, options = {}) {
+            const expirationTtl = cloudflareKvExpirationTtl(options.ttl);
+            if (expirationTtl === 0) {
+                await namespace.delete(key);
+                return;
+            }
+            await namespace.put(key, value, expirationTtl === undefined ? undefined : { expirationTtl });
+        },
+    });
+}
+/** Creates a store backed by Cloudflare Durable Object storage or namespace RPC. */
+export function durableObject(target, options) {
+    if (durableObjectNamespace(target)) {
+        const name = options?.name;
+        if (name === undefined)
+            throw new TypeError('Durable Object name is required');
+        return durableObjectStub(target, name);
+    }
+    return durableObjectStorage(target);
+}
+function durableObjectStorage(storage) {
+    return from({
+        async delete(key) {
+            await storage.delete(key);
+        },
+        async get(key) {
+            return (await durableObjectRead(storage, key, await storage.get(key)))?.value ?? null;
+        },
+        async list(options = {}) {
+            const values = await storage.list(options);
+            const keys = [];
+            for (const [key, value] of values) {
+                if (await durableObjectRead(storage, key, value))
+                    keys.push({ name: key });
+            }
+            return { keys };
+        },
+        async put(key, value, options = {}) {
+            if (options.ttl !== undefined && options.ttl <= 0) {
+                await storage.delete(key);
+                return;
+            }
+            await storage.put(key, durableObjectValue(value, options));
+        },
+    });
+}
+/**
+ * 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.
+ */
+export async function memoize(fetch, options) {
+    const { key, store, ttl } = options;
+    const raw = await store.get(key);
+    if (raw) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            // Corrupt entries are treated as misses so the next call refreshes.
+        }
+    }
+    const flights = flightsFor(store);
+    const existing = flights.get(key);
+    if (existing)
+        return existing;
+    // 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();
+        await store.put(key, JSON.stringify(value), { ttl });
+        return value;
+    })();
+    flights.set(key, flight);
+    try {
+        return await flight;
+    }
+    finally {
+        flights.delete(key);
+    }
+}
+const flights = new WeakMap();
+function flightsFor(store) {
+    let inFlight = flights.get(store);
+    if (!inFlight) {
+        inFlight = new Map();
+        flights.set(store, inFlight);
+    }
+    return inFlight;
+}
+function durableObjectNamespace(target) {
+    return typeof target === 'object' && target !== null && 'getByName' in target;
+}
+function durableObjectStub(namespace, name) {
+    // Durable Object stubs are request-scoped I/O objects in Workers, so
+    // resolve the stub inside each store operation instead of caching it.
+    const stub = (key) => namespace.getByName(typeof name === 'function' ? name(key) : name);
+    return from({
+        async delete(key) {
+            await durableObjectRetry(() => stub(key).delete(key));
+        },
+        async get(key) {
+            return durableObjectRetry(() => stub(key).get(key));
+        },
+        // Native RPC increment: the read-modify-write runs inside the object
+        // (one round trip, atomic) instead of the get + put fallback (two).
+        async increment(key, options) {
+            return durableObjectRetry(() => stub(key).increment(key, options));
+        },
+        async list(options) {
+            // A sharded store scatters keys across objects, so no single object can
+            // enumerate them.
+            if (typeof name === 'function')
+                throw new TypeError('cannot list a sharded Durable Object store');
+            return durableObjectRetry(() => stub('').list(options));
+        },
+        async put(key, value, options) {
+            await durableObjectRetry(() => stub(key).put(key, value, options));
+        },
+    });
+}
+/**
+ * Runs a Durable Object stub call, retrying once when workerd marks the error
+ * retryable (transient transport failures, e.g. "Network connection lost.")
+ * and not overloaded. Callers pass a thunk so the retry resolves a fresh
+ * stub: a stub that threw is disconnected.
+ */
+async function durableObjectRetry(call) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        const { overloaded, retryable } = (error ?? {});
+        if (retryable !== true || overloaded === true)
+            throw error;
+        return call();
+    }
+}
+function cloudflareKvExpirationTtl(ttl) {
+    if (ttl === undefined)
+        return undefined;
+    if (ttl <= 0)
+        return 0;
+    // Workers KV expects TTLs in seconds and rejects values under 60 seconds.
+    const seconds = Math.ceil(ttl / 1_000);
+    if (seconds < 60)
+        throw new RangeError('Cloudflare KV expirationTtl must be at least 60 seconds');
+    return seconds;
+}
+const durableObjectValueType = 'cadent:store:v1';
+function durableObjectValue(value, options) {
+    if (options.ttl === undefined)
+        return value;
+    // Durable Object storage does not expose per-key TTL in the current Worker
+    // API, so this adapter stores expirations in-band and evicts lazily on read.
+    return { expiresAt: Date.now() + options.ttl, type: durableObjectValueType, value };
+}
+async function durableObjectRead(storage, key, value) {
+    if (typeof value === 'string')
+        return { value };
+    if (!isDurableObjectValue(value))
+        return null;
+    if (value.expiresAt !== undefined && value.expiresAt <= Date.now()) {
+        await storage.delete(key);
+        return null;
+    }
+    return value;
+}
+function isDurableObjectValue(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    return ('type' in value &&
+        value.type === durableObjectValueType &&
+        'value' in value &&
+        typeof value.value === 'string' &&
+        (!('expiresAt' in value) ||
+            value.expiresAt === undefined ||
+            typeof value.expiresAt === 'number'));
+}
+//# sourceMappingURL=Store.js.map

package/dist/internal/Store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Store.js","sourceRoot":"","sources":["../../src/internal/Store.ts"],"names":[],"mappings":"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"}

package/dist/internal/Tidx.d.ts

@@ -0,0 +1,120 @@
+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 declare const url: Record<number, string>;
+/** 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 declare function resolve(tidx: getClient.Tidx | undefined, context: Viem.resolve.Context): resolve.Resolved;
+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 declare function getClient(options: getClient.Options): Client;
+/**
+ * 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 declare function createGetClient(options?: createGetClient.Options): GetClient;
+/**
+ * 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 declare function escape(value: string): string;
+/**
+ * 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 declare function withTransientRetry(client: Client): Client;
+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;
+    };
+}
+//# sourceMappingURL=Tidx.d.ts.map

package/dist/internal/Tidx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tidx.d.ts","sourceRoot":"","sources":["../../src/internal/Tidx.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAE9B,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAA;AACtC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAEjC,8CAA8C;AAC9C,eAAO,MAAM,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGtC,CAAA;AAED,yBAAyB;AACzB,MAAM,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAA;AAE9B,2EAA2E;AAC3E,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,IAAI,CAAC,SAAS,GAAG,IAAI,KAAK,MAAM,CAAA;AAE7F;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,KAAK,MAAM,GAAG,SAAS,CAAA;AAEvE;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,SAAS,CAAC,IAAI,GAAG,SAAS,EAChC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,GAC5B,OAAO,CAAC,QAAQ,CAQlB;AAED,MAAM,CAAC,OAAO,WAAW,OAAO,CAAC;IAC/B,iDAAiD;IACjD,KAAK,QAAQ,GAAG;QACd;;;;WAIG;QACH,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;QAC3B,kEAAkE;QAClE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAC/B,CAAA;CACF;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,OAAO,GAAG,MAAM,CAI5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,eAAe,CAAC,OAAY,GAAG,SAAS,CAgBhF;AA6BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,UAEnC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAqBzD;AAqBD,MAAM,CAAC,OAAO,WAAW,SAAS,CAAC;IACjC,+CAA+C;IAC/C,KAAK,OAAO,GAAG;QACb,sBAAsB;QACtB,OAAO,CAAC,EAAE,IAAI,CAAC,OAAO,GAAG,SAAS,CAAA;QAClC,6EAA6E;QAC7E,SAAS,CAAC,EAAE,IAAI,CAAC,SAAS,GAAG,IAAI,GAAG,SAAS,CAAA;QAC7C,iCAAiC;QACjC,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAA;KACxB,CAAA;IAED;;;;;OAKG;IACH,KAAK,IAAI,GACL;QACE,6EAA6E;QAC7E,OAAO,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAAA;QAC1C,gDAAgD;QAChD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAC/B,GACD,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,KAAK;QAClC,iFAAiF;QACjF,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QAC5B,uEAAuE;QACvE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAC/B,CAAC,CAAA;CACP;AAED,MAAM,CAAC,OAAO,WAAW,eAAe,CAAC;IACvC,4DAA4D;IAC5D,KAAK,OAAO,GAAG;QACb,mDAAmD;QACnD,cAAc,CAAC,EAAE,IAAI,CAAC,OAAO,GAAG,SAAS,CAAA;QACzC,qEAAqE;QACrE,IAAI,CAAC,EAAE,SAAS,CAAC,IAAI,GAAG,SAAS,CAAA;KAClC,CAAA;CACF"}

package/dist/internal/Tidx.js

@@ -0,0 +1,156 @@
+import { Tidx } from 'tidx.ts';
+import * as Viem from './Viem.js';
+/** Default Tempo indexer (TIDX) base URLs. */
+export const url = {
+    4217: 'https://indexer.tempo.xyz',
+    42431: 'https://indexer.testnet.tempo.xyz',
+};
+/**
+ * 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, context) {
+    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 function getClient(options) {
+    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 = {}) {
+    const { defaultChainId = Viem.defaultChainId, tidx } = options;
+    const clients = new Map();
+    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) {
+    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) {
+    const fetch = client.fetch.bind(client);
+    return {
+        ...client,
+        fetch: async (options) => {
+            let lastError;
+            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) {
+    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);
+}
+//# sourceMappingURL=Tidx.js.map

package/dist/internal/Tidx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tidx.js","sourceRoot":"","sources":["../../src/internal/Tidx.ts"],"names":[],"mappings":"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"}

package/dist/internal/Timing.d.ts

@@ -0,0 +1,22 @@
+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 declare function middleware<environment extends Environment = Environment>(): MiddlewareHandler<environment>;
+/** Measures one async operation and adds it to the current request timings. */
+export declare function time<environment extends Environment, value>(c: Context<environment>, name: string, fn: () => Promise<value> | value): Promise<value>;
+//# sourceMappingURL=Timing.d.ts.map

package/dist/internal/Timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Timing.d.ts","sourceRoot":"","sources":["../../src/internal/Timing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAEtD,4DAA4D;AAC5D,MAAM,MAAM,SAAS,GAAG;IACtB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;CACpC,CAAA;AAED,qDAAqD;AACrD,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,EAAE,SAAS,CAAA;CACrB,CAAA;AAED,gCAAgC;AAChC,MAAM,MAAM,MAAM,GAAG;IACnB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAA;IAChB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CACxB,WAAW,SAAS,WAAW,GAAG,WAAW,KAC1C,iBAAiB,CAAC,WAAW,CAAC,CAalC;AAED,+EAA+E;AAC/E,wBAAsB,IAAI,CAAC,WAAW,SAAS,WAAW,EAAE,KAAK,EAC/D,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,EACvB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,kBAQjC"}

package/dist/internal/Timing.js

@@ -0,0 +1,32 @@
+/** Adds a `Server-Timing` header with total request duration. */
+export function middleware() {
+    return async (c, next) => {
+        const metrics = [];
+        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(c, name, fn) {
+    const start = performance.now();
+    try {
+        return await fn();
+    }
+    finally {
+        c.get('serverTiming')?.push({ duration: performance.now() - start, name });
+    }
+}
+function format(metrics) {
+    return metrics
+        .map((metric) => `${name(metric.name)};dur=${metric.duration.toFixed(1)}`)
+        .join(', ');
+}
+function name(value) {
+    return value.replace(/[^A-Za-z0-9_.*-]/g, '_');
+}
+//# sourceMappingURL=Timing.js.map