tapimo 0.0.0 → 0.0.2

package/src/internal/Value.ts

@@ -0,0 +1,114 @@
+import { Hex } from 'ox'
+
+/** Coerce a TIDX numeric column (bigint / number / string) to a JS number. */
+export function toNumber(value: unknown) {
+  if (typeof value === 'bigint') return Number(value)
+  if (typeof value === 'number') return value
+  if (typeof value === 'string') return Number(value)
+  return undefined
+}
+
+/**
+ * Coerce a TIDX text column (address / hash / topic / hex data) to a string.
+ * TIDX already returns these columns as strings; this narrows the `unknown`
+ * row value without an unsafe `String(...)` on a possible object. Returns
+ * undefined for null/non-string values.
+ */
+export function toText(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined
+}
+
+/**
+ * Coerce a TIDX numeric column (bigint / number / string) to a non-negative
+ * decimal integer string, preserving precision for values beyond
+ * `Number.MAX_SAFE_INTEGER` (e.g. token balances). Returns undefined when the
+ * value cannot be interpreted as a non-negative integer.
+ */
+export function toIntegerString(value: unknown) {
+  if (typeof value === 'bigint') return value >= 0n ? value.toString() : undefined
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || value < 0 || !Number.isInteger(value)) return undefined
+    // Route through BigInt so large integers serialize as plain decimals rather
+    // than exponential notation (e.g. `1e+21`).
+    return BigInt(value).toString()
+  }
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    return /^\d+$/.test(trimmed) ? trimmed : undefined
+  }
+  return undefined
+}
+
+/**
+ * Coerce a TIDX numeric column (bigint / number / decimal string) to a minimal
+ * `0x`-prefixed hex quantity (`0x0` for zero), matching the JSON-RPC wire
+ * format. Returns undefined when the value is null/undefined or cannot be
+ * interpreted as a non-negative integer.
+ */
+export function toHex(value: unknown): Hex.Hex | undefined {
+  let big: bigint
+  if (typeof value === 'bigint') big = value
+  else if (typeof value === 'number') {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) return undefined
+    big = BigInt(value)
+  } else if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (!/^\d+$/.test(trimmed)) return undefined
+    big = BigInt(trimmed)
+  } else return undefined
+  if (big < 0n) return undefined
+  return Hex.fromNumber(big)
+}
+
+/**
+ * Parse a `0x`-prefixed hex quantity into a non-negative decimal integer string,
+ * preserving precision beyond `Number.MAX_SAFE_INTEGER`. Returns undefined when
+ * the value is not a valid hex quantity.
+ */
+export function fromHex(value: unknown): string | undefined {
+  if (typeof value !== 'string' || !/^0x[0-9a-fA-F]+$/.test(value)) return undefined
+  return BigInt(value).toString()
+}
+
+/**
+ * Parse a `0x`-prefixed hex quantity into a JS number. Returns undefined when
+ * the value is not a valid hex quantity.
+ */
+export function hexToNumber(value: unknown): number | undefined {
+  const decimal = fromHex(value)
+  return decimal === undefined ? undefined : Number(decimal)
+}
+
+/**
+ * Convert a `0x`-prefixed hex Unix-seconds timestamp into an ISO 8601 datetime
+ * string. Returns undefined when the value is not a valid hex quantity.
+ */
+export function hexSecondsToIso(value: unknown): string | undefined {
+  const seconds = hexToNumber(value)
+  return seconds === undefined ? undefined : new Date(seconds * 1000).toISOString()
+}
+
+/**
+ * Coerce a TIDX timestamp column (Date / epoch seconds / epoch ms / ISO string)
+ * to an ISO 8601 datetime string. Returns undefined when the value cannot be
+ * interpreted as a timestamp.
+ */
+export function toIsoDateTime(value: unknown) {
+  if (value instanceof Date) return value.toISOString()
+  // TIDX can surface timestamps as either decoded date strings or numeric
+  // epochs depending on the query engine and transport codec.
+  if (typeof value === 'number')
+    return new Date(value > 1_000_000_000_000 ? value : value * 1000).toISOString()
+  if (typeof value !== 'string') return undefined
+
+  // ClickHouse formats `DateTime`/`DateTime64` as `YYYY-MM-DD HH:MM:SS[.sss]`
+  // (UTC), which V8's Date parser treats as *local* time. Normalize to a
+  // strict ISO 8601 UTC string so both engines hit the same `new Date(...)`
+  // path.
+  const normalized = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(\.\d+)?$/.test(value)
+    ? `${value.replace(' ', 'T')}Z`
+    : value
+  const date = new Date(normalized)
+  if (Number.isNaN(date.getTime())) return undefined
+  return date.toISOString()
+}

package/src/internal/VerifiedTokens.test.ts

@@ -0,0 +1,333 @@
+import type { Context } from 'hono'
+
+import type * as App from '../App.js'
+import * as Store from './Store.js'
+import * as VerifiedTokens from './VerifiedTokens.js'
+
+// Seeds a store with the documented head + versioned blob layout for a
+// chain so `read`/`snapshot` can load it.
+async function seed(
+  store: Store.State,
+  chainId: number,
+  version: string,
+  list: readonly VerifiedTokens.Token[],
+) {
+  const updatedAt = '2024-01-01T00:00:00.000Z'
+  await store.put(
+    `verified-token:v1:${chainId}:snapshot:${version}`,
+    JSON.stringify({ chainId, schema: 1, tokens: list, updatedAt, version }),
+  )
+  await store.put(
+    `verified-token:v1:${chainId}:head`,
+    JSON.stringify({ chainId, count: list.length, schema: 1, updatedAt, version }),
+  )
+}
+
+// Store wrapper that counts `get` calls per key prefix so tests can assert the
+// hot path does zero (fresh) or head-only (soft-stale) I/O.
+function counting(store: Store.State) {
+  const counts = { head: 0, snapshot: 0 }
+  return {
+    counts,
+    store: Store.from({
+      ...store,
+      get(key: string) {
+        if (key.endsWith(':head')) counts.head++
+        else if (key.includes(':snapshot:')) counts.snapshot++
+        return store.get(key)
+      },
+    }),
+  }
+}
+
+// Minimal context that returns a verified-tokens feature config (or none).
+function context(config?: App.create.VerifiedTokens): Context<App.Environment> {
+  return {
+    get: (key: string) => (key === 'verifiedTokens' ? config : undefined),
+  } as unknown as Context<App.Environment>
+}
+
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0))
+
+const tokens: readonly VerifiedTokens.Token[] = [
+  { address: '0xAAA0000000000000000000000000000000000001', currency: 'USD', decimals: 6, name: 'Alpha USD', symbol: 'aUSD' }, // prettier-ignore
+  { address: '0xBBB0000000000000000000000000000000000002', currency: 'EUR', decimals: 2, name: 'Beta EUR', symbol: 'bEUR' }, // prettier-ignore
+  { address: '0xCCC0000000000000000000000000000000000003', currency: 'usd', decimals: 6, name: 'Gamma USD', symbol: 'cUSD' }, // prettier-ignore
+]
+
+describe('compile', () => {
+  const snapshot = VerifiedTokens.compile({
+    chainId: 4217,
+    tokens,
+    updatedAt: '2024-01-01T00:00:00.000Z',
+    version: 'test',
+  })
+
+  test('preserves list order', () => {
+    expect(snapshot.list.map((token) => token.symbol)).toMatchInlineSnapshot(`
+      [
+        "aUSD",
+        "bEUR",
+        "cUSD",
+      ]
+    `)
+  })
+
+  test('indexes by lowercased address', () => {
+    expect(snapshot.byAddress.has('0xaaa0000000000000000000000000000000000001')).toBe(true)
+    // Lookups normalize, so the original mixed-case key is not present verbatim.
+    expect(snapshot.byAddress.has('0xAAA0000000000000000000000000000000000001')).toBe(false)
+  })
+
+  test('indexes by lowercased symbol', () => {
+    expect(snapshot.bySymbol.get('ausd')?.address).toBe(
+      '0xAAA0000000000000000000000000000000000001',
+    )
+  })
+
+  test('groups by lowercased currency, preserving order', () => {
+    expect(snapshot.byCurrency.get('usd')?.map((token) => token.symbol)).toMatchInlineSnapshot(`
+      [
+        "aUSD",
+        "cUSD",
+      ]
+    `)
+    expect(snapshot.byCurrency.get('eur')?.map((token) => token.symbol)).toMatchInlineSnapshot(`
+      [
+        "bEUR",
+      ]
+    `)
+  })
+
+  test('derives sorted, distinct (case-sensitive) currencies', () => {
+    expect(snapshot.currencies).toMatchInlineSnapshot(`
+      [
+        "EUR",
+        "USD",
+        "usd",
+      ]
+    `)
+  })
+})
+
+describe('read', () => {
+  test('returns null when the chain has no head', async () => {
+    expect(await VerifiedTokens.read(Store.memory(), 4217)).toBe(null)
+  })
+
+  test('compiles the snapshot the head points at', async () => {
+    const store = Store.memory()
+    await seed(store, 4217, 'v1', tokens)
+    const snapshot = await VerifiedTokens.read(store, 4217)
+    expect(snapshot?.version).toBe('v1')
+    expect(snapshot?.list.map((token) => token.symbol)).toMatchInlineSnapshot(`
+      [
+        "aUSD",
+        "bEUR",
+        "cUSD",
+      ]
+    `)
+  })
+
+  test('throws when the head points at a missing snapshot blob', async () => {
+    const store = Store.memory()
+    await store.put(
+      'verified-token:v1:4217:head',
+      JSON.stringify({
+        chainId: 4217,
+        count: 0,
+        schema: 1,
+        updatedAt: '2024-01-01T00:00:00.000Z',
+        version: 'ghost',
+      }),
+    )
+    await expect(VerifiedTokens.read(store, 4217)).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[VerifiedTokens.TornStateError: verified-token head for chain 4217 points at missing snapshot version "ghost".]`,
+    )
+  })
+})
+
+describe('snapshot', () => {
+  // Minimal context stub: `Timing.time` only reads the optional `serverTiming`.
+  const unconfigured = { get: () => undefined } as unknown as Context<App.Environment>
+
+  test('serves an empty snapshot when the feature is unconfigured', async () => {
+    const snapshot = await VerifiedTokens.snapshot(unconfigured, 4217)
+    expect(snapshot.version).toBe('empty')
+    expect(snapshot.list).toEqual([])
+  })
+
+  // The following cases run in order and share the module-level per-isolate cache
+  // for chain 42431: cold load → fresh → soft-stale unchanged → soft-stale changed.
+  test('cold-loads from the store when a head exists', async () => {
+    const store = Store.memory()
+    await seed(store, 42431, 'v1', tokens)
+    const snapshot = await VerifiedTokens.snapshot(context({ store }), 42431)
+    expect(snapshot.version).toBe('v1')
+    expect(snapshot.byAddress.size).toBe(tokens.length)
+  })
+
+  test('serves fresh lookups with zero store I/O', async () => {
+    const { counts, store } = counting(Store.memory())
+    const snapshot = await VerifiedTokens.snapshot(context({ refreshMs: 60_000, store }), 42431)
+    expect(snapshot.version).toBe('v1')
+    expect(counts).toEqual({ head: 0, snapshot: 0 })
+  })
+
+  test('soft-stale reads only the head when the version is unchanged', async () => {
+    const base = Store.memory()
+    await seed(base, 42431, 'v1', tokens)
+    const { counts, store } = counting(base)
+    // refreshMs 0 forces the soft-stale path; the current snapshot is returned
+    // immediately and the head-only refresh runs in the background.
+    const snapshot = await VerifiedTokens.snapshot(context({ refreshMs: 0, store }), 42431)
+    expect(snapshot.version).toBe('v1')
+    await flush()
+    expect(counts).toEqual({ head: 1, snapshot: 0 })
+  })
+
+  test('soft-stale recompiles when the version changed', async () => {
+    const store = Store.memory()
+    await seed(store, 42431, 'v2', tokens.slice(0, 1))
+    // Stale call returns the existing v1 immediately, refreshes to v2 in background.
+    const stale = await VerifiedTokens.snapshot(context({ refreshMs: 0, store }), 42431)
+    expect(stale.version).toBe('v1')
+    await flush()
+    // Next call sees the refreshed cell (fresh window) and returns v2.
+    const fresh = await VerifiedTokens.snapshot(context({ refreshMs: 60_000, store }), 42431)
+    expect(fresh.version).toBe('v2')
+    expect(fresh.list.map((token) => token.symbol)).toEqual(['aUSD'])
+  })
+
+  test('cold-loads an empty snapshot when the store has no head', async () => {
+    // Chain 4217 has no configured cell yet and an empty store → empty snapshot.
+    const snapshot = await VerifiedTokens.snapshot(context({ store: Store.memory() }), 4217)
+    expect(snapshot.version).toBe('empty')
+    expect(snapshot.list).toEqual([])
+  })
+})
+
+const newToken = {
+  address: '0xDDD0000000000000000000000000000000000004',
+  currency: 'GBP',
+  decimals: 8,
+  name: 'Delta GBP',
+  symbol: 'dGBP',
+} satisfies VerifiedTokens.Token
+
+describe('replace', () => {
+  test('publishes the list and round-trips through read', async () => {
+    const store = Store.memory()
+    const { snapshot } = await VerifiedTokens.replace(store, 42431, tokens)
+    const read = await VerifiedTokens.read(store, 42431)
+    expect(read?.version).toBe(snapshot.version)
+    expect(read?.list.map((token) => token.symbol)).toEqual(['aUSD', 'bEUR', 'cUSD'])
+    // Addresses are normalized to lowercase on write.
+    expect(read?.list[0]?.address).toBe('0xaaa0000000000000000000000000000000000001')
+  })
+
+  test('advances the head version on each publish', async () => {
+    const store = Store.memory()
+    const first = await VerifiedTokens.replace(store, 42431, tokens)
+    const second = await VerifiedTokens.replace(store, 42431, tokens.slice(0, 1))
+    expect(second.snapshot.version > first.snapshot.version).toBe(true)
+  })
+
+  test('rejects a duplicate address in the input', async () => {
+    const store = Store.memory()
+    await expect(
+      VerifiedTokens.replace(store, 42431, [tokens[0]!, tokens[0]!]),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[VerifiedTokens.DuplicateAddressError: verified token 0xaaa0000000000000000000000000000000000001 already exists on chain 42431.]`,
+    )
+  })
+})
+
+describe('create', () => {
+  test('appends a token preserving order', async () => {
+    const store = Store.memory()
+    await VerifiedTokens.replace(store, 42431, tokens)
+    const { snapshot, token } = await VerifiedTokens.create(store, { ...newToken, chainId: 42431 })
+    expect(token.address).toBe('0xddd0000000000000000000000000000000000004')
+    expect(snapshot.list.map((t) => t.symbol)).toEqual(['aUSD', 'bEUR', 'cUSD', 'dGBP'])
+  })
+
+  test('rejects a duplicate address', async () => {
+    const store = Store.memory()
+    await VerifiedTokens.replace(store, 42431, tokens)
+    await expect(
+      VerifiedTokens.create(store, { ...tokens[0]!, chainId: 42431 }),
+    ).rejects.toThrowError(VerifiedTokens.DuplicateAddressError)
+  })
+
+  test('rejects a case-insensitive duplicate symbol', async () => {
+    const store = Store.memory()
+    await VerifiedTokens.replace(store, 42431, tokens)
+    await expect(
+      VerifiedTokens.create(store, { ...newToken, chainId: 42431, symbol: 'AUSD' }),
+    ).rejects.toThrowError(VerifiedTokens.DuplicateSymbolError)
+  })
+})
+
+describe('patch', () => {
+  test('edits fields in place, preserving order', async () => {
+    const store = Store.memory()
+    await VerifiedTokens.replace(store, 42431, tokens)
+    const { snapshot, token } = await VerifiedTokens.patch(store, 42431, tokens[1]!.address, {
+      name: 'Beta Euro',
+    })
+    expect(token.name).toBe('Beta Euro')
+    // Unchanged fields are preserved; order is preserved.
+    expect(token.symbol).toBe('bEUR')
+    expect(snapshot.list.map((t) => t.symbol)).toEqual(['aUSD', 'bEUR', 'cUSD'])
+  })
+
+  test('throws NotFoundError for an unknown address', async () => {
+    const store = Store.memory()
+    await VerifiedTokens.replace(store, 42431, tokens)
+    await expect(
+      VerifiedTokens.patch(store, 42431, newToken.address, { name: 'x' }),
+    ).rejects.toThrowError(VerifiedTokens.NotFoundError)
+  })
+
+  test('rejects an If-Match version mismatch', async () => {
+    const store = Store.memory()
+    await VerifiedTokens.replace(store, 42431, tokens)
+    await expect(
+      VerifiedTokens.patch(store, 42431, tokens[0]!.address, { name: 'x' }, { ifMatch: 'stale' }),
+    ).rejects.toThrowError(VerifiedTokens.VersionMismatchError)
+  })
+})
+
+describe('remove', () => {
+  test('removes a token and publishes', async () => {
+    const store = Store.memory()
+    await VerifiedTokens.replace(store, 42431, tokens)
+    const { snapshot } = await VerifiedTokens.remove(store, 42431, tokens[0]!.address)
+    expect(snapshot.list.map((t) => t.symbol)).toEqual(['bEUR', 'cUSD'])
+    expect(snapshot.byAddress.has(tokens[0]!.address.toLowerCase())).toBe(false)
+  })
+
+  test('throws NotFoundError for an unknown address', async () => {
+    const store = Store.memory()
+    await VerifiedTokens.replace(store, 42431, tokens)
+    await expect(VerifiedTokens.remove(store, 42431, newToken.address)).rejects.toThrowError(
+      VerifiedTokens.NotFoundError,
+    )
+  })
+})
+
+describe('prime', () => {
+  test('gives read-your-write for the priming isolate', async () => {
+    const primed = VerifiedTokens.compile({
+      chainId: 42431,
+      tokens: tokens.slice(0, 2),
+      updatedAt: '2024-02-02T00:00:00.000Z',
+      version: 'primed',
+    })
+    VerifiedTokens.prime(42431, primed)
+    // Within the fresh window the primed snapshot is served with no store read.
+    const snapshot = await VerifiedTokens.snapshot(context({ refreshMs: 60_000, store: Store.memory() }), 42431) // prettier-ignore
+    expect(snapshot).toBe(primed)
+  })
+})