tapimo 0.0.0 → 0.0.2

package/src/internal/Store.ts

@@ -0,0 +1,526 @@
+/** Minimal string store contract used by Tempo API internals. */
+export type Store = {
+  /** Deletes a key. */
+  delete(key: string): Promise<void>
+  /** Gets a string value. Returns `null` for missing or expired keys. */
+  get(key: string): Promise<null | string>
+  /**
+   * Optional native counter: increments an integer value and returns the new
+   * count. A missing or expired key restarts at `1`; `ttl` applies like
+   * {@link Store.put}. Implement when the backend can execute the
+   * read-modify-write in one place (in-memory, inside a Durable Object);
+   * consumers go through the {@link increment} helper, which falls back to a
+   * get + put when this is absent.
+   */
+  increment?: ((key: string, options?: Store.PutOptions) => Promise<number>) | undefined
+  /** Lists keys. */
+  list(options?: {
+    /** Restrict results to keys with this prefix. */
+    prefix?: string | undefined
+  }): Promise<{
+    /** Matching keys. */
+    keys: readonly {
+      /** Key name. */
+      name: string
+    }[]
+  }>
+  /** Writes a string value, optionally with a time-to-live. */
+  put(key: string, value: string, options?: Store.PutOptions): Promise<void>
+  /**
+   * Store kind discriminant. `'state'` marks an authoritative, enumerable
+   * store ({@link State}); `'cache'` marks a cache (e.g. the Web Cache,
+   * which cannot enumerate keys and silently drops entries).
+   */
+  type: Store.Type
+}
+
+export namespace Store {
+  /** Store kind: `'state'` (authoritative, enumerable) or `'cache'` (a cache). */
+  export type Type = 'state' | 'cache'
+
+  /** Options for writing a value to a store. */
+  export type PutOptions = {
+    /**
+     * Time-to-live in milliseconds. After this duration the key is treated as
+     * absent. Production backends should map this to native expiration
+     * (Redis `PEXPIRE`, Cloudflare `expirationTtl`, etc.).
+     */
+    ttl?: number | undefined
+  }
+}
+
+/**
+ * An authoritative, enumerable {@link Store} for stateful features (webhook
+ * subscriptions, rate-limit counters, …). Discriminated by `type: 'state'` so
+ * stateful features can require it at the type level and reject cache adapters
+ * like the Web Cache ({@link cache}, `type: 'cache'`), which cannot enumerate
+ * keys and silently drops entries on eviction. `memory`, `cloudflareKv`, and
+ * `durableObject` produce it.
+ */
+export type State = Store & { type: 'state' }
+
+/**
+ * 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<const store extends from.Input>(store: store): from.Output<store> {
+  // Default the discriminant so only cache-kind stores have to opt in.
+  return { ...store, type: store.type ?? 'state' } as never
+}
+
+export declare namespace from {
+  /** Store operations with an optional kind discriminant (defaults to `'state'`). */
+  type Input = Omit<Store, 'type'> & {
+    /** Store kind; defaults to `'state'`. Pass `'cache'` for a cache-kind store. */
+    type?: Store.Type | undefined
+  }
+
+  /** Resolved store kind: {@link State} unless `type: 'cache'` is provided. */
+  type Output<store extends Input> = store extends { type: 'cache' } ? Store : 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: Store,
+  key: string,
+  options: Store.PutOptions = {},
+): Promise<number> {
+  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: memory.Options = {}): State {
+  // Track value + optional expiration in one cell so `get` can lazily evict
+  // expired entries without a background sweeper.
+  type Cell = { expiresAt: number | undefined; value: string }
+  const cells = new Map<string, Cell>(
+    (options.entries ?? []).map(([key, value]) => [key, { expiresAt: undefined, value }]),
+  )
+
+  function read(key: string) {
+    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 })
+    },
+  })
+}
+
+export declare namespace memory {
+  /** Options for creating an in-memory store. */
+  type Options = {
+    /** Initial entries. */
+    entries?: readonly (readonly [string, string])[] | undefined
+  }
+}
+
+/**
+ * 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: cache.Cache): Store {
+  const request = (key: string) => 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',
+  })
+}
+
+export declare namespace cache {
+  /** Minimal Web Cache API surface used by this adapter. */
+  type Cache = {
+    /** Deletes a cache entry. */
+    delete(request: Request | string): Promise<boolean>
+    /** Looks up a cache entry. */
+    match(request: Request | string): Promise<Response | undefined>
+    /** Stores a cache entry. */
+    put(request: Request | string, response: Response): Promise<void>
+  }
+}
+
+/** Creates a store backed by a Cloudflare Workers KV namespace. */
+export function cloudflareKv(namespace: cloudflareKv.Namespace): State {
+  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 })
+    },
+  })
+}
+
+export declare namespace cloudflareKv {
+  /** Minimal Cloudflare Workers KV namespace shape used by this adapter. */
+  type Namespace = {
+    /** Deletes a key. */
+    delete(key: string): Promise<void>
+    /** Gets a text value. */
+    get(key: string): Promise<null | string>
+    /** Lists keys. */
+    list(options?: {
+      /** Restrict results to keys with this prefix. */
+      prefix?: string | null | undefined
+    }): Promise<{
+      /** Matching keys. */
+      keys: readonly {
+        /** Key name. */
+        name: string
+      }[]
+    }>
+    /** Writes a text value. */
+    put(
+      key: string,
+      value: string,
+      options?: {
+        /** Native Cloudflare KV TTL in seconds. */
+        expirationTtl?: number | undefined
+      },
+    ): Promise<void>
+  }
+}
+
+export function durableObject(storage: durableObject.Storage): State
+export function durableObject(
+  namespace: durableObject.Namespace,
+  options: durableObject.Options,
+): State
+/** Creates a store backed by Cloudflare Durable Object storage or namespace RPC. */
+export function durableObject(
+  target: durableObject.Namespace | durableObject.Storage,
+  options?: durableObject.Options,
+): State {
+  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: durableObject.Storage): State {
+  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<unknown>(options)
+      const keys: { name: string }[] = []
+
+      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))
+    },
+  })
+}
+
+export declare namespace durableObject {
+  /** Minimal Durable Object namespace shape used by this adapter. */
+  type Namespace = {
+    /** Gets the Durable Object stub for a stable object name. */
+    getByName(name: string): Stub
+  }
+
+  /** Options for creating a store from a Durable Object namespace. */
+  type Options = {
+    /**
+     * Durable Object name. A static string pins one object holding every key
+     * (enumerable via `list`). A resolver function shards keys across objects
+     * (`name(key)` per operation) so each key's object is created near the
+     * traffic that uses it — sharded stores cannot `list`.
+     */
+    name: string | ((key: string) => string)
+  }
+
+  /** Minimal Cloudflare Durable Object storage shape used by this adapter. */
+  type Storage = {
+    /** Deletes a key. */
+    delete(key: string): Promise<unknown>
+    /** Gets a stored value. */
+    get<value = unknown>(key: string): Promise<undefined | value>
+    /** Lists stored values. */
+    list<value = unknown>(options?: {
+      /** Restrict results to keys with this prefix. */
+      prefix?: string | undefined
+    }): Promise<Map<string, value>>
+    /** Writes a stored value. */
+    put<value>(key: string, value: value): Promise<void>
+  }
+
+  /**
+   * Minimal Durable Object RPC stub shape used by this adapter — just the store
+   * operations (no `type` discriminant, which an RPC stub doesn't carry).
+   * `increment` is required: the stub mirrors the `tapimo/cloudflare`
+   * `DurableObject` class, whose RPC surface implements it.
+   */
+  type Stub = Omit<Store, 'increment' | 'type'> & {
+    /** Atomically increments an integer counter inside the object. */
+    increment(key: string, options?: Store.PutOptions): Promise<number>
+  }
+}
+
+/**
+ * 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<value>(
+  fetch: () => Promise<value>,
+  options: memoize.Options,
+): Promise<value> {
+  const { key, store, ttl } = options
+
+  const raw = await store.get(key)
+  if (raw) {
+    try {
+      return JSON.parse(raw) as value
+    } 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 as Promise<value>
+
+  // Coalesce concurrent misses for this process. The store remains the cache
+  // boundary; this only prevents a local cold-key stampede while the first
+  // fetch is still in flight.
+  const flight = (async () => {
+    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)
+  }
+}
+
+export declare namespace memoize {
+  /** Options for {@link memoize}. */
+  type Options = {
+    /** Cache key. Callers are responsible for namespacing/versioning. */
+    key: string
+    /** Store used to persist cache entries. */
+    store: Store
+    /** Time-to-live in milliseconds. */
+    ttl: number
+  }
+}
+
+const flights = new WeakMap<Store, Map<string, Promise<unknown>>>()
+
+function flightsFor(store: Store) {
+  let inFlight = flights.get(store)
+  if (!inFlight) {
+    inFlight = new Map()
+    flights.set(store, inFlight)
+  }
+  return inFlight
+}
+
+function durableObjectNamespace(
+  target: durableObject.Namespace | durableObject.Storage,
+): target is durableObject.Namespace {
+  return typeof target === 'object' && target !== null && 'getByName' in target
+}
+
+function durableObjectStub(
+  namespace: durableObject.Namespace,
+  name: string | ((key: string) => string),
+): State {
+  // 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: string) => 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<value>(call: () => Promise<value>): Promise<value> {
+  try {
+    return await call()
+  } catch (error) {
+    const { overloaded, retryable } = (error ?? {}) as {
+      overloaded?: boolean | undefined
+      retryable?: boolean | undefined
+    }
+    if (retryable !== true || overloaded === true) throw error
+    return call()
+  }
+}
+
+function cloudflareKvExpirationTtl(ttl: number | undefined) {
+  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'
+
+type DurableObjectValue = {
+  expiresAt?: number | undefined
+  type: typeof durableObjectValueType
+  value: string
+}
+
+function durableObjectValue(value: string, options: Store.PutOptions): DurableObjectValue | string {
+  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: durableObject.Storage,
+  key: string,
+  value: unknown,
+): Promise<DurableObjectValue | { value: string } | null> {
+  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: unknown): value is DurableObjectValue {
+  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')
+  )
+}

package/src/internal/Tidx.local.test.ts

@@ -0,0 +1,33 @@
+import * as TestApp from '../../test/App.js'
+import * as Runtime from '../../test/runtime.js'
+import * as Indexer from '../apps/indexer.js'
+
+describe('local TIDX runtime', () => {
+  test.runIf(Runtime.get().mode === 'localnet')(
+    'proxies queries to a disposable TIDX',
+    async () => {
+      const runtime = Runtime.get()
+      const client = TestApp.client()
+      const response = await client.v1.indexer.query.$get(
+        { query: { chainId: String(runtime.chainId), sql: 'select 1 as value' } },
+        TestApp.auth,
+      )
+      const body = await TestApp.json(response, Indexer.schema.Response)
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(body.ok).toMatchInlineSnapshot(`true`)
+      expect(body.columns).toMatchInlineSnapshot(`
+      [
+        "value",
+      ]
+    `)
+      expect(body.rows).toMatchInlineSnapshot(`
+      [
+        [
+          1,
+        ],
+      ]
+    `)
+    },
+  )
+})