tapimo 0.0.0 → 0.0.2

package/dist/internal/Cache.d.ts

@@ -0,0 +1,74 @@
+import type { Context, Env, MiddlewareHandler } from 'hono';
+import type * as z from 'zod/mini';
+/**
+ * Named `Cache-Control` policies, tiered by how volatile each resource is. The
+ * `max-age` bounds how stale a shared (edge) hit can be; `stale-while-revalidate`
+ * lets clients/CDNs serve a slightly older copy while refreshing in the
+ * background. Handlers may override per response via `Cache.setPolicy` (e.g. a
+ * mined transaction is `immutable`, a pending one is `noStore`).
+ */
+export declare const policies: {
+    /**
+     * Publicly shareable binary assets (token logos). `public` because the bytes
+     * carry no per-principal data and the edge layer strips per-request headers.
+     * Deliberately NOT `immutable`: these live at a stable URL
+     * (`/tokens/:token/logo`) whose underlying R2 icon can be replaced in place
+     * (admin upload), so a long `max-age` is paired with `stale-while-revalidate`
+     * to revalidate rather than pin a replaced logo for a year. Use a versioned/
+     * content-addressed URL if true `immutable` forever-caching is needed.
+     */
+    readonly asset: 'public, max-age=86400, stale-while-revalidate=604800';
+    /** Fallback for routes that do not specify a policy. */
+    readonly default: 'private, max-age=30, stale-while-revalidate=300';
+    /** Newest-first feeds (transactions, receipts, transfers): refresh quickly. */
+    readonly feed: 'private, max-age=10, stale-while-revalidate=30';
+    /** Immutable resources (mined transactions and receipts): cache aggressively. */
+    readonly immutable: 'private, max-age=86400, stale-while-revalidate=604800';
+    /** Token metadata and indexed listings: change slowly. */
+    readonly metadata: 'private, max-age=60, stale-while-revalidate=300';
+    /** Transient or uncacheable responses (pending transactions). */
+    readonly noStore: 'no-store';
+    /** Slow-changing curated data (verified tokens). */
+    readonly stable: 'private, max-age=300, stale-while-revalidate=3600';
+    /** Current-state pages (holders, balances): moderately volatile. */
+    readonly state: 'private, max-age=30, stale-while-revalidate=120';
+};
+/**
+ * Overrides the cache policy for the current response, taking precedence over
+ * the route's default `Cache.response` policy. Lets a handler vary caching by
+ * outcome — e.g. cache a mined transaction as `immutable` but a pending one as
+ * `noStore`. Must be called before the handler returns.
+ */
+export declare function setPolicy<environment extends Env>(c: Context<environment>, cacheControl: string): void;
+/** Hono response-cache helpers. */
+export declare function response<environment extends Env>(options: response.Options<environment>): MiddlewareHandler<environment>;
+export declare namespace response {
+    /** Options for response caching. */
+    type Options<environment extends Env> = {
+        /** Cache-control value returned to clients. */
+        cacheControl?: string | undefined;
+        /** Cache name passed to Hono's cache middleware. */
+        name: string;
+        /** Cache key generator. */
+        key: (c: Context<environment>) => Promise<string> | string;
+        /** Vary headers used for the response and cache key. */
+        vary?: readonly string[] | undefined;
+    };
+}
+export declare namespace response {
+    /** Per-request headers that must not be stored in shared response caches. */
+    const preservedHeaders: string[];
+}
+/**
+ * Builds a cache key from the request URL after parsing query params through
+ * the given Zod schema. Defaults from the schema are baked into the key so
+ * cached entries collide regardless of param ordering, casing, or omitted
+ * defaults. Resolves an optional `chainId` query parameter against the app's
+ * default chain id when the caller did not provide one.
+ */
+export declare function urlKey<environment extends {
+    Variables: {
+        chainId: number;
+    };
+}, schema extends z.ZodMiniType>(c: Context<environment>, schema: schema): string;
+//# sourceMappingURL=Cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../src/internal/Cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAG3D,OAAO,KAAK,KAAK,CAAC,MAAM,UAAU,CAAA;AAIlC;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ;IACnB;;;;;;;;OAQG;aACH,KAAK,EAAE,sDAAsD;IAC7D,wDAAwD;aACxD,OAAO,EAAE,iDAAiD;IAC1D,+EAA+E;aAC/E,IAAI,EAAE,gDAAgD;IACtD,iFAAiF;aACjF,SAAS,EAAE,uDAAuD;IAClE,0DAA0D;aAC1D,QAAQ,EAAE,iDAAiD;IAC3D,iEAAiE;aACjE,OAAO,EAAE,UAAU;IACnB,oDAAoD;aACpD,MAAM,EAAE,mDAAmD;IAC3D,oEAAoE;aACpE,KAAK,EAAE,iDAAiD;CAChD,CAAA;AAEV;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,WAAW,SAAS,GAAG,EAC/C,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,EACvB,YAAY,EAAE,MAAM,GACnB,IAAI,CAEN;AAED,mCAAmC;AACnC,wBAAgB,QAAQ,CAAC,WAAW,SAAS,GAAG,EAC9C,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,GACrC,iBAAiB,CAAC,WAAW,CAAC,CAoGhC;AAED,MAAM,CAAC,OAAO,WAAW,QAAQ,CAAC;IAChC,oCAAoC;IACpC,KAAK,OAAO,CAAC,WAAW,SAAS,GAAG,IAAI;QACtC,+CAA+C;QAC/C,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QACjC,oDAAoD;QACpD,IAAI,EAAE,MAAM,CAAA;QACZ,2BAA2B;QAC3B,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;QAC1D,wDAAwD;QACxD,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;KACrC,CAAA;CACF;AAED,yBAAiB,QAAQ,CAAC;IACxB,6EAA6E;IACtE,MAAM,gBAAgB,UAAgE,CAAA;CAC9F;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,WAAW,SAAS;IAAE,SAAS,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EACtD,MAAM,SAAS,CAAC,CAAC,WAAW,EAC5B,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAUjD"}

package/dist/internal/Cache.js

@@ -0,0 +1,215 @@
+import { cache as hono_cache } from 'hono/cache';
+import { etag as hono_etag, RETAINED_304_HEADERS } from 'hono/etag';
+import * as EdgeCache from './EdgeCache.js';
+/**
+ * Named `Cache-Control` policies, tiered by how volatile each resource is. The
+ * `max-age` bounds how stale a shared (edge) hit can be; `stale-while-revalidate`
+ * lets clients/CDNs serve a slightly older copy while refreshing in the
+ * background. Handlers may override per response via `Cache.setPolicy` (e.g. a
+ * mined transaction is `immutable`, a pending one is `noStore`).
+ */
+export const policies = {
+    /**
+     * Publicly shareable binary assets (token logos). `public` because the bytes
+     * carry no per-principal data and the edge layer strips per-request headers.
+     * Deliberately NOT `immutable`: these live at a stable URL
+     * (`/tokens/:token/logo`) whose underlying R2 icon can be replaced in place
+     * (admin upload), so a long `max-age` is paired with `stale-while-revalidate`
+     * to revalidate rather than pin a replaced logo for a year. Use a versioned/
+     * content-addressed URL if true `immutable` forever-caching is needed.
+     */
+    asset: 'public, max-age=86400, stale-while-revalidate=604800',
+    /** Fallback for routes that do not specify a policy. */
+    default: 'private, max-age=30, stale-while-revalidate=300',
+    /** Newest-first feeds (transactions, receipts, transfers): refresh quickly. */
+    feed: 'private, max-age=10, stale-while-revalidate=30',
+    /** Immutable resources (mined transactions and receipts): cache aggressively. */
+    immutable: 'private, max-age=86400, stale-while-revalidate=604800',
+    /** Token metadata and indexed listings: change slowly. */
+    metadata: 'private, max-age=60, stale-while-revalidate=300',
+    /** Transient or uncacheable responses (pending transactions). */
+    noStore: 'no-store',
+    /** Slow-changing curated data (verified tokens). */
+    stable: 'private, max-age=300, stale-while-revalidate=3600',
+    /** Current-state pages (holders, balances): moderately volatile. */
+    state: 'private, max-age=30, stale-while-revalidate=120',
+};
+/**
+ * Overrides the cache policy for the current response, taking precedence over
+ * the route's default `Cache.response` policy. Lets a handler vary caching by
+ * outcome — e.g. cache a mined transaction as `immutable` but a pending one as
+ * `noStore`. Must be called before the handler returns.
+ */
+export function setPolicy(c, cacheControl) {
+    c.set('cacheControl', cacheControl);
+}
+/** Hono response-cache helpers. */
+export function response(options) {
+    const defaultCacheControl = options.cacheControl ?? policies.default;
+    const vary = options.vary ?? ['Accept-Encoding', 'Authorization', 'Tempo-API-Key'];
+    // hono/cache suffixes its key with `::<directive>=<value>` for every
+    // configured vary directive (trimmed, lowercased, deduped). Mirror that
+    // normalization so the `no-cache` purge below deletes exactly the entry the
+    // wrapped middleware reads — drift here would make refreshes silently miss.
+    const varyKeyDirectives = [
+        ...new Set(vary.map((name) => name.trim().toLowerCase()).filter(Boolean)),
+    ];
+    const cache = hono_cache({
+        cacheName: options.name,
+        keyGenerator: options.key,
+        onCacheNotAvailable: false,
+        vary: [...vary],
+        wait: true,
+    });
+    const etag = hono_etag();
+    return async (c, next) => {
+        const values = response.preservedHeaders.map((name) => [name, c.res.headers.get(name)]);
+        // Honor the standard request `Cache-Control` directives (plus the HTTP/1.0
+        // `Pragma: no-cache` fallback, used only when `Cache-Control` is absent),
+        // mirroring `EdgeCache.middleware`: a refresh that bypasses the edge layer
+        // must also bypass this inner response cache, or the caller is served the
+        // inner stored copy and the "refresh" never reaches the handler.
+        // `no-cache` purges the stored entry so the wrapped hono/cache misses and
+        // re-stores the fresh response; `no-store` skips reads and writes entirely
+        // while leaving the stored entry untouched.
+        const directives = (c.req.header('Cache-Control') ?? c.req.header('Pragma') ?? '').toLowerCase();
+        const noStore = directives.includes('no-store');
+        const noCache = noStore || directives.includes('no-cache');
+        const caches = globalThis.caches;
+        if (noCache && !noStore && caches) {
+            let key = await options.key(c);
+            for (const name of varyKeyDirectives)
+                key += `::${name}=${encodeURIComponent(c.req.raw.headers.get(name) ?? '')}`;
+            await (await caches.open(options.name)).delete(key);
+        }
+        // Run ETag inside Hono's cache miss path so fresh responses are hashed
+        // once before storage. Cached hits bypass Hono's ETag middleware, so this
+        // wrapper handles conditional requests from the stored ETag below.
+        const handler = async () => {
+            await etag(c, async () => {
+                await next();
+                // Rate-limit headers are per request and would be stale if stored with
+                // the shared cached body.
+                for (const name of response.preservedHeaders)
+                    c.res.headers.delete(name);
+            });
+            // Stamp the resolved policy's shared form onto 2xx responses BEFORE
+            // hono/cache stores them: the explicit `s-maxage` bounds the stored
+            // entry's lifetime to the policy (instead of the platform cache's
+            // default TTL), and a policy resolved to `noStore` (e.g. a pending
+            // transaction via `setPolicy`) becomes `no-store`, which hono/cache
+            // refuses to store. Client-facing headers are applied after storage
+            // below; non-2xx responses keep their own headers (`Response.error`
+            // marks envelopes `no-store`).
+            if (c.res.status >= 200 && c.res.status < 300) {
+                const policy = edgeCachePolicy(c.get('cacheControl') ?? defaultCacheControl);
+                c.res.headers.set('Cache-Control', policy ? EdgeCache.cacheControl(policy) : 'no-store');
+            }
+        };
+        const result = noStore ? await handler() : await cache(c, handler);
+        // A handler may override the policy per response (see `setPolicy`); fall back
+        // to the route default. Publishing the derived policy is what marks the
+        // response as eligible for the shared edge cache (see `EdgeCache.middleware`),
+        // so `noStore` responses are never persisted there. The edge layer reads this
+        // after the whole chain runs, so setting it here (post-handler) is in time.
+        const cacheControl = c.get('cacheControl') ?? defaultCacheControl;
+        c.set('edgeCache', edgeCachePolicy(cacheControl));
+        let res = result instanceof Response ? new Response(result.body, result) : c.res;
+        if (result instanceof Response &&
+            etagMatches(res.headers.get('ETag'), c.req.header('If-None-Match')))
+            res = notModified(res);
+        // Apply private client cache headers after Hono cache storage; the stored
+        // copy carries the shared `public, s-maxage` form stamped above, while the
+        // client receives the policy's private form. Error responses keep their
+        // own `Cache-Control` (`no-store` from `Response.error` or the app-level
+        // safety net) instead of inheriting the route policy.
+        if ((res.status >= 200 && res.status < 300) || res.status === 304)
+            setCacheHeaders(res.headers, { cacheControl, vary });
+        for (const [name, value] of values)
+            if (value)
+                res.headers.set(name, value);
+        if (result instanceof Response)
+            return res;
+        return undefined;
+    };
+}
+(function (response) {
+    /** Per-request headers that must not be stored in shared response caches. */
+    response.preservedHeaders = ['RateLimit-Limit', 'RateLimit-Remaining', 'RateLimit-Reset'];
+})(response || (response = {}));
+/**
+ * Builds a cache key from the request URL after parsing query params through
+ * the given Zod schema. Defaults from the schema are baked into the key so
+ * cached entries collide regardless of param ordering, casing, or omitted
+ * defaults. Resolves an optional `chainId` query parameter against the app's
+ * default chain id when the caller did not provide one.
+ */
+export function urlKey(c, schema) {
+    const url = new URL(c.req.url);
+    const query = schema.parse(Object.fromEntries(url.searchParams));
+    url.search = '';
+    if (query['chainId'] === undefined)
+        url.searchParams.set('chainId', String(c.get('chainId')));
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined)
+            continue;
+        url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+}
+function etagMatches(etag, ifNoneMatch) {
+    if (!etag || !ifNoneMatch)
+        return false;
+    return ifNoneMatch.split(/,\s*/).some((tag) => stripWeak(tag) === stripWeak(etag));
+}
+function notModified(response) {
+    const headers = new Headers();
+    for (const name of RETAINED_304_HEADERS) {
+        const value = response.headers.get(name);
+        if (value)
+            headers.set(name, value);
+    }
+    return new Response(null, {
+        headers,
+        status: 304,
+        statusText: 'Not Modified',
+    });
+}
+function setCacheHeaders(headers, options) {
+    headers.set('Cache-Control', options.cacheControl);
+    const vary = new Map((headers.get('Vary') ?? '')
+        .split(',')
+        .map((value) => value.trim())
+        .filter(Boolean)
+        .map((value) => [value.toLowerCase(), value]));
+    for (const value of options.vary)
+        vary.set(value.toLowerCase(), value);
+    headers.set('Vary', Array.from(vary.values()).join(', '));
+}
+function stripWeak(etag) {
+    return etag.replace(/^W\//, '');
+}
+// Derive the shared-cache policy from a route's client `Cache-Control`. A
+// positive `s-maxage`/`max-age` (and no `no-store`/`no-cache`) is what makes a
+// route eligible for the anonymous edge cache; the `private` directive only
+// scopes the client copy and is intentionally ignored here.
+function edgeCachePolicy(cacheControl) {
+    const directives = new Map(cacheControl
+        .split(',')
+        .map((part) => part.trim().toLowerCase())
+        .filter(Boolean)
+        .map((part) => part.split('=')));
+    if (directives.has('no-store') || directives.has('no-cache'))
+        return undefined;
+    const maxAge = Number(directives.get('s-maxage') ?? directives.get('max-age'));
+    if (!Number.isFinite(maxAge) || maxAge <= 0)
+        return undefined;
+    const staleWhileRevalidate = Number(directives.get('stale-while-revalidate'));
+    return {
+        maxAge,
+        staleWhileRevalidate: Number.isFinite(staleWhileRevalidate) && staleWhileRevalidate > 0
+            ? staleWhileRevalidate
+            : undefined,
+    };
+}
+//# sourceMappingURL=Cache.js.map

package/dist/internal/Cache.js.map

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

package/dist/internal/Cursor.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Opaque keyset-pagination cursor: a positional tuple encoding the sort-key of
+ * the last returned row (e.g. `[block, index]` for an append-only feed, or
+ * `[balance, address]` for a balance ranking). Pages are anchored to this
+ * position rather than a numeric offset, so rows arriving at the head of a feed
+ * cannot shift items across page boundaries (the duplicate/skip hazard of offset
+ * pagination over a live feed).
+ *
+ * The token is opaque on purpose: callers must treat it as a blob and pass back
+ * the `nextCursor` from the previous page verbatim. Because cursor values are
+ * inlined into upstream SQL, every field is validated on decode against its
+ * declared `Field` kind and re-serialized into a safe SQL literal via `literal`,
+ * so a malformed or forged cursor degrades to "start from the head" rather than
+ * reaching the query.
+ */
+export type Cursor = (string | number)[];
+/** The kind of a cursor field, determining its validation and SQL literal form. */
+export type Field = 'int' | 'uint' | 'address' | 'timestamp';
+/** Encodes a positional tuple as an opaque, URL-safe token. */
+export declare function encode(values: Cursor): string;
+/**
+ * Splits a keyset query result (fetched with one extra row, `LIMIT n + 1`) into
+ * a page. Returns the page `rows` (capped at `limit`), whether `hasMore` rows
+ * follow, and the `nextCursor` anchoring the next page below the last row.
+ *
+ * `key` derives the next-page cursor tuple from the last row of the page,
+ * returning `undefined` when the row's sort-key can't be extracted (then
+ * `nextCursor` is `null`). Callers build their typed `data` from `rows`.
+ */
+export declare function paginate<row>(options: {
+    /** The raw query result, fetched with one extra row (`LIMIT limit + 1`). */
+    rows: readonly row[];
+    /** The requested page size. */
+    limit: number;
+    /** Derives the next-page cursor tuple from the last row of the page. */
+    key: (row: row) => Cursor | undefined;
+}): {
+    hasMore: boolean;
+    nextCursor: string | null;
+    rows: row[];
+};
+/**
+ * Decodes a cursor token, validating arity and each field against `fields`.
+ * Returns `undefined` for anything malformed/forged so a bad cursor falls back
+ * to the head page instead of erroring (or reaching SQL).
+ */
+export declare function decode(token: string, fields: readonly Field[]): Cursor | undefined;
+/**
+ * Renders a (decode-validated) cursor value as a safe SQL literal: integers and
+ * uint256 decimals are inlined bare; addresses are lowercased and quoted;
+ * timestamps are quoted. Only ever call with values returned from `decode`.
+ */
+export declare function literal(value: string | number, field: Field): string;
+/**
+ * Builds a strict lexicographic keyset predicate for the given ORDER BY columns
+ * and direction. Columns carry pre-rendered `literal`s.
+ *
+ * When every column sorts the same way, this emits a row-value (tuple)
+ * comparison, e.g. for `ORDER BY a DESC, b DESC` after `(va, vb)`:
+ * `((a, b) < (va, vb))`. This single-predicate form is the only one the
+ * indexer's signature-decoded queries accept (they reject the equivalent
+ * `OR`-expansion), and standard Postgres / ClickHouse support it too.
+ *
+ * When directions are mixed (e.g. a ranking `ORDER BY balance DESC, addr ASC`),
+ * a tuple comparison can't express it, so it falls back to the `OR` expansion:
+ * `((a < va) OR (a = va AND b > vb))`. Mixed-direction keysets only run against
+ * ClickHouse, which accepts the `OR` form.
+ *
+ * Multi-column keysets additionally AND a redundant non-strict bound on the
+ * first column (`a <= va`): neither the tuple nor the `OR` form alone lets the
+ * ClickHouse planner prune the primary-key range, so without the bare bound a
+ * deep cursor page scans from the tip (see the Q1 notes in `activities.ts`).
+ */
+export declare function keyset(columns: readonly {
+    name: string;
+    literal: string;
+    order: 'asc' | 'desc';
+}[]): string;
+//# sourceMappingURL=Cursor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Cursor.d.ts","sourceRoot":"","sources":["../../src/internal/Cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;AAExC,mFAAmF;AACnF,MAAM,MAAM,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,CAAA;AAE5D,+DAA+D;AAC/D,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE;IACrC,4EAA4E;IAC5E,IAAI,EAAE,SAAS,GAAG,EAAE,CAAA;IACpB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,GAAG,SAAS,CAAA;CACtC,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,CAO/D;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,MAAM,GAAG,SAAS,CASlF;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,CAUpE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAA;CAAE,EAAE,GAC3E,MAAM,CAsBR"}

package/dist/internal/Cursor.js

@@ -0,0 +1,116 @@
+/** Encodes a positional tuple as an opaque, URL-safe token. */
+export function encode(values) {
+    return base64UrlEncode(JSON.stringify(values));
+}
+/**
+ * Splits a keyset query result (fetched with one extra row, `LIMIT n + 1`) into
+ * a page. Returns the page `rows` (capped at `limit`), whether `hasMore` rows
+ * follow, and the `nextCursor` anchoring the next page below the last row.
+ *
+ * `key` derives the next-page cursor tuple from the last row of the page,
+ * returning `undefined` when the row's sort-key can't be extracted (then
+ * `nextCursor` is `null`). Callers build their typed `data` from `rows`.
+ */
+export function paginate(options) {
+    const { rows, limit, key } = options;
+    const pageRows = rows.slice(0, limit);
+    const hasMore = rows.length > limit;
+    const last = pageRows.at(-1);
+    const tuple = hasMore && last !== undefined ? key(last) : undefined;
+    return { hasMore, nextCursor: tuple ? encode(tuple) : null, rows: pageRows };
+}
+/**
+ * Decodes a cursor token, validating arity and each field against `fields`.
+ * Returns `undefined` for anything malformed/forged so a bad cursor falls back
+ * to the head page instead of erroring (or reaching SQL).
+ */
+export function decode(token, fields) {
+    try {
+        const parsed = JSON.parse(base64UrlDecode(token));
+        if (!Array.isArray(parsed) || parsed.length !== fields.length)
+            return undefined;
+        for (let i = 0; i < fields.length; i++)
+            if (!isValid(parsed[i], fields[i]))
+                return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Renders a (decode-validated) cursor value as a safe SQL literal: integers and
+ * uint256 decimals are inlined bare; addresses are lowercased and quoted;
+ * timestamps are quoted. Only ever call with values returned from `decode`.
+ */
+export function literal(value, field) {
+    switch (field) {
+        case 'int':
+        case 'uint':
+            return String(value);
+        case 'address':
+            return `'${String(value).toLowerCase()}'`;
+        case 'timestamp':
+            return `'${String(value)}'`;
+    }
+}
+/**
+ * Builds a strict lexicographic keyset predicate for the given ORDER BY columns
+ * and direction. Columns carry pre-rendered `literal`s.
+ *
+ * When every column sorts the same way, this emits a row-value (tuple)
+ * comparison, e.g. for `ORDER BY a DESC, b DESC` after `(va, vb)`:
+ * `((a, b) < (va, vb))`. This single-predicate form is the only one the
+ * indexer's signature-decoded queries accept (they reject the equivalent
+ * `OR`-expansion), and standard Postgres / ClickHouse support it too.
+ *
+ * When directions are mixed (e.g. a ranking `ORDER BY balance DESC, addr ASC`),
+ * a tuple comparison can't express it, so it falls back to the `OR` expansion:
+ * `((a < va) OR (a = va AND b > vb))`. Mixed-direction keysets only run against
+ * ClickHouse, which accepts the `OR` form.
+ *
+ * Multi-column keysets additionally AND a redundant non-strict bound on the
+ * first column (`a <= va`): neither the tuple nor the `OR` form alone lets the
+ * ClickHouse planner prune the primary-key range, so without the bare bound a
+ * deep cursor page scans from the tip (see the Q1 notes in `activities.ts`).
+ */
+export function keyset(columns) {
+    const first = columns[0];
+    const bound = columns.length > 1
+        ? `${first.name} ${first.order === 'asc' ? '>=' : '<='} ${first.literal} AND `
+        : '';
+    const uniform = columns.every((column) => column.order === first.order);
+    if (uniform) {
+        const op = first.order === 'asc' ? '>' : '<';
+        const names = columns.map((column) => column.name).join(', ');
+        const literals = columns.map((column) => column.literal).join(', ');
+        return `(${bound}(${names}) ${op} (${literals}))`;
+    }
+    const clauses = [];
+    for (let i = 0; i < columns.length; i++) {
+        const parts = columns.slice(0, i).map((column) => `${column.name} = ${column.literal}`);
+        const op = columns[i].order === 'asc' ? '>' : '<';
+        parts.push(`${columns[i].name} ${op} ${columns[i].literal}`);
+        clauses.push(`(${parts.join(' AND ')})`);
+    }
+    return `(${bound}(${clauses.join(' OR ')}))`;
+}
+function isValid(value, field) {
+    switch (field) {
+        case 'int':
+            return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+        case 'uint':
+            return typeof value === 'string' && /^\d+$/.test(value);
+        case 'address':
+            return typeof value === 'string' && /^0x[0-9a-fA-F]{40}$/.test(value);
+        case 'timestamp':
+            return typeof value === 'string' && !Number.isNaN(Date.parse(value));
+    }
+}
+function base64UrlEncode(value) {
+    return btoa(value).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}
+function base64UrlDecode(value) {
+    return atob(value.replaceAll('-', '+').replaceAll('_', '/'));
+}
+//# sourceMappingURL=Cursor.js.map

package/dist/internal/Cursor.js.map

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

package/dist/internal/EdgeCache.d.ts

@@ -0,0 +1,59 @@
+import type { Env, MiddlewareHandler } from 'hono';
+import type * as Store from './Store.js';
+/**
+ * Per-request edge-cache policy published by `Cache.response` for routes that
+ * opted into response caching. Its presence is what marks a response as safe to
+ * persist in the shared edge cache.
+ */
+export type Policy = {
+    /** Shared max-age / s-maxage in seconds for the stored response. */
+    maxAge: number;
+    /** Stale-while-revalidate window in seconds, if any. */
+    staleWhileRevalidate?: number | undefined;
+};
+/** Hono variables published by the edge-cache layer. */
+export type Variables = {
+    /** Edge-cache policy for the current route, set by `Cache.response`. */
+    edgeCache?: Policy | undefined;
+    /** `'hit'` when the edge cache served the response without reaching the origin handlers. */
+    edgeCacheStatus?: 'hit' | undefined;
+};
+/**
+ * Serves GET responses from the edge cache store BEFORE auth and rate-limiting
+ * run, so cache hits skip the per-request store round-trips that dominate
+ * latency — for every caller, authenticated or not. Place this ahead of the
+ * auth middleware.
+ *
+ * Only 2xx responses from routes that opted into caching (via `Cache.response`,
+ * which publishes the `edgeCache` policy) are stored, and the policy is only
+ * published for routes whose responses are public and URL-keyed (no per-principal
+ * data), so a single shared entry is safe to serve to all callers. The trade-off
+ * is that cache hits bypass origin metering: they are not counted against
+ * rate-limit quotas.
+ *
+ * The cache is a plain `Store.Store` — the same store the origin read cache uses
+ * — holding the response serialized to a string under a URL key. It is a no-op
+ * when no store is supplied.
+ *
+ * Standard request `Cache-Control` directives let a caller invalidate without an
+ * out-of-band purge: `no-cache` forces a refresh (skip the stored hit, re-fetch,
+ * overwrite the entry) and `no-store` bypasses the cache entirely. Both fall
+ * through to the origin and are metered normally. The store is colo-local, so a
+ * refresh only affects the data center serving that request.
+ */
+export declare function middleware<environment extends Env>(options?: middleware.Options): MiddlewareHandler<environment>;
+export declare namespace middleware {
+    /** Options for the edge-cache middleware. */
+    type Options = {
+        /** Store backing the edge cache. The layer is a no-op when omitted. */
+        store?: Store.Store | undefined;
+    };
+}
+/**
+ * Builds the shared-cache `Cache-Control` value for a stored copy: `public`
+ * with `max-age`/`s-maxage` bound to the policy plus an optional
+ * `stale-while-revalidate` window. Used for this layer's stored copies and by
+ * `Cache.response` to bound the inner response cache's entry lifetime.
+ */
+export declare function cacheControl(policy: Policy): string;
+//# sourceMappingURL=EdgeCache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EdgeCache.d.ts","sourceRoot":"","sources":["../../src/internal/EdgeCache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAGlD,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC;;;;GAIG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAA;IACd,wDAAwD;IACxD,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1C,CAAA;AAED,wDAAwD;AACxD,MAAM,MAAM,SAAS,GAAG;IACtB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,4FAA4F;IAC5F,eAAe,CAAC,EAAE,KAAK,GAAG,SAAS,CAAA;CACpC,CAAA;AAmBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,UAAU,CAAC,WAAW,SAAS,GAAG,EAChD,OAAO,GAAE,UAAU,CAAC,OAAY,GAC/B,iBAAiB,CAAC,WAAW,CAAC,CA+ChC;AAED,MAAM,CAAC,OAAO,WAAW,UAAU,CAAC;IAClC,6CAA6C;IAC7C,KAAK,OAAO,GAAG;QACb,uEAAuE;QACvE,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,GAAG,SAAS,CAAA;KAChC,CAAA;CACF;AA0FD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,UAK1C"}