tapimo 0.4.1 → 0.4.4

package/src/internal/Store.ts

@@ -1,9 +1,52 @@
 import { Json } from 'ox'
 
+/** Key-to-value map used by typed stores. */
+export type StoreItemMap = Record<string, unknown>
+
+/** Result of an atomic store update. */
+export type Change<value, result> =
+  | {
+      /** Leaves the value unchanged. */
+      op: 'noop'
+      /** Value returned by the update. */
+      result: result
+    }
+  | {
+      /** Replaces the stored value. */
+      op: 'set'
+      /** Value returned by the update. */
+      result: result
+      /** New stored value. */
+      value: value
+    }
+  | {
+      /** Deletes the stored value. */
+      op: 'delete'
+      /** Value returned by the update. */
+      result: result
+    }
+
+/** Typed store with atomic read-modify-write support. */
+export type AtomicStore<itemMap extends StoreItemMap = StoreItemMap> = {
+  /** Deletes a key. */
+  delete<key extends keyof itemMap & string>(key: key): Promise<void>
+  /** Gets a typed value. */
+  get<key extends keyof itemMap & string>(key: key): Promise<itemMap[key] | null>
+  /** Writes a typed value. */
+  put<key extends keyof itemMap & string>(key: key, value: itemMap[key]): Promise<void>
+  /** Atomically updates a typed value. */
+  update<key extends keyof itemMap & string, result>(
+    key: key,
+    fn: (current: itemMap[key] | null) => Change<itemMap[key], result>,
+  ): Promise<result>
+}
+
 /** Minimal string store contract used by Tempo API internals. */
 export type Store = {
   /** Deletes a key. */
   delete(key: string): Promise<void>
+  /** Deletes a key only when its value matches `expected`. */
+  deleteIf?: ((key: string, expected: null | string) => Promise<boolean>) | undefined
   /** Gets a string value. Returns `null` for missing or expired keys. */
   get(key: string): Promise<null | string>
   /**
@@ -77,6 +120,9 @@ export namespace Store {
  */
 export type State = Store & { type: 'state' }
 
+/** Authoritative string state that also supports typed atomic operations. */
+export type AtomicState<itemMap extends StoreItemMap = StoreItemMap> = AtomicStore<itemMap> & State
+
 /**
  * Wraps store operations into a {@link Store}, defaulting to an authoritative
  * {@link State} store. Omit `type` for the common authoritative case; pass
@@ -136,7 +182,7 @@ export async function update(
   fn: (current: null | string) => string,
   options: update.Options = {},
 ): Promise<string> {
-  const { attempts = 8, ...put } = options
+  const { attempts = updateAttempts, ...put } = options
 
   if (!store.swap) {
     const next = fn(await store.get(key))
@@ -152,6 +198,8 @@ export async function update(
   throw new UpdateContentionError(key, attempts)
 }
 
+const updateAttempts = 8
+
 export declare namespace update {
   /** Options for {@link update}. */
   type Options = Store.PutOptions & {
@@ -187,6 +235,11 @@ export function memory(options: memory.Options = {}): State {
     async delete(key) {
       cells.delete(key)
     },
+    async deleteIf(key, expected) {
+      if ((read(key)?.value ?? null) !== expected) return false
+      cells.delete(key)
+      return true
+    },
     async get(key) {
       return read(key)?.value ?? null
     },
@@ -347,21 +400,26 @@ export declare namespace cloudflareKv {
   }
 }
 
-export function durableObject(storage: durableObject.Storage): State
+/** Creates typed atomic state over namespace RPC, or raw object storage state. */
+export function durableObject(namespace: durableObject.Namespace): durableObject.ReturnValue
 export function durableObject(
   namespace: durableObject.Namespace,
   options: durableObject.Options,
-): State
-/** Creates a store backed by Cloudflare Durable Object storage or namespace RPC. */
+): durableObject.ReturnValue
+export function durableObject<const itemMap extends StoreItemMap>(
+  namespace: durableObject.Namespace,
+): AtomicState<itemMap>
+export function durableObject<const itemMap extends StoreItemMap>(
+  namespace: durableObject.Namespace,
+  options: durableObject.Options,
+): AtomicState<itemMap>
+export function durableObject(storage: durableObject.Storage): State
 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)
-  }
+  options: durableObject.Options = {},
+): durableObject.ReturnValue | State {
+  if (durableObjectNamespace(target))
+    return durableObjectStub(target, options.name ?? ((key) => key))
   return durableObjectStorage(target)
 }
 
@@ -370,6 +428,13 @@ function durableObjectStorage(storage: durableObject.Storage): State {
     async delete(key) {
       await storage.delete(key)
     },
+    // Storage input gates prevent writes between comparison and deletion.
+    async deleteIf(key, expected) {
+      const current = (await durableObjectRead(storage, key, await storage.get(key)))?.value ?? null
+      if (current !== expected) return false
+      await storage.delete(key)
+      return true
+    },
     async get(key) {
       return (await durableObjectRead(storage, key, await storage.get(key)))?.value ?? null
     },
@@ -408,6 +473,19 @@ function durableObjectStorage(storage: durableObject.Storage): State {
 }
 
 export declare namespace durableObject {
+  /** Durable Object state assignable to any typed item map. */
+  type ReturnValue = State & {
+    /** Gets a contextually typed value. */
+    get<value = unknown>(key: string): Promise<value | null>
+    /** Writes a typed value. */
+    put<value>(key: string, value: value, options?: Store.PutOptions): Promise<void>
+    /** Atomically updates a contextually typed value. */
+    update<value, result>(
+      key: string,
+      fn: (current: value | null) => Change<value, result>,
+    ): Promise<result>
+  }
+
   /** Minimal Durable Object namespace shape used by this adapter. */
   type Namespace = {
     /** Gets the Durable Object stub for a stable object name. */
@@ -416,13 +494,8 @@ export declare namespace durableObject {
 
   /** 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)
+    /** Static pins all keys; a resolver shards them; omission shards by key. */
+    name?: string | ((key: string) => string) | undefined
   }
 
   /** Minimal Cloudflare Durable Object storage shape used by this adapter. */
@@ -440,14 +513,10 @@ export declare namespace durableObject {
     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` and `swap` are required: the stub mirrors the
-   * `tapimo/cloudflare` `DurableObject` class, whose RPC surface implements
-   * them.
-   */
-  type Stub = Omit<Store, 'increment' | 'swap' | 'type'> & {
+  /** RPC store operations used by the namespace adapter. */
+  type Stub = Omit<Store, 'deleteIf' | 'increment' | 'swap' | 'type'> & {
+    /** Atomically deletes a matching value inside the object. */
+    deleteIf(key: string, expected: null | string): Promise<boolean>
     /** Atomically increments an integer counter inside the object. */
     increment(key: string, options?: Store.PutOptions): Promise<number>
     /** Atomically compares-and-swaps a value inside the object. */
@@ -533,40 +602,58 @@ function durableObjectNamespace(
 function durableObjectStub(
   namespace: durableObject.Namespace,
   name: string | ((key: string) => string),
-): State {
+): durableObject.ReturnValue {
   // 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) {
+  return {
+    async delete(key: string) {
       await durableObjectRetry(() => stub(key).delete(key))
     },
-    async get(key) {
-      return durableObjectRetry(() => stub(key).get(key))
+    async deleteIf(key: string, expected: null | string) {
+      const encoded = expected === null ? null : durableObjectEncode(expected)
+      return stub(key).deleteIf(key, encoded)
+    },
+    async get(key: string) {
+      return durableObjectDecode(await 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) {
+    async increment(key: string, options?: Store.PutOptions) {
       return durableObjectRetry(() => stub(key).increment(key, options))
     },
-    async list(options) {
+    async list(options?: Parameters<Store['list']>[0]) {
       // 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))
+    async put(key: string, value: unknown, options?: Store.PutOptions) {
+      await durableObjectRetry(() => stub(key).put(key, durableObjectEncode(value), options))
     },
-    // Native RPC swap: the compare-and-write runs inside the object. A lost
-    // response retried after a successful write compares stale and returns
-    // false, which optimistic callers already handle as contention.
-    async swap(key, expected, next, options) {
-      return durableObjectRetry(() => stub(key).swap(key, expected, next, options))
+    async swap(key: string, expected: null | string, next: string, options?: Store.PutOptions) {
+      const encoded = expected === null ? null : durableObjectEncode(expected)
+      return stub(key).swap(key, encoded, durableObjectEncode(next), options)
     },
-  })
+    type: 'state' as const,
+    async update<result>(key: string, fn: (current: unknown) => Change<unknown, result>) {
+      for (let attempt = 0; attempt < updateAttempts; attempt++) {
+        const current = await durableObjectRetry(() => stub(key).get(key))
+        const change = fn(durableObjectDecode(current))
+        if (change.op === 'noop') return change.result
+
+        // Retrying an ambiguous CAS can apply the transform twice.
+        const changed =
+          change.op === 'set'
+            ? await stub(key).swap(key, current, durableObjectEncode(change.value))
+            : await stub(key).deleteIf(key, current)
+        if (changed) return change.result
+      }
+      throw new UpdateContentionError(key, updateAttempts)
+    },
+  } as durableObject.ReturnValue
 }
 
 /**
@@ -588,6 +675,26 @@ async function durableObjectRetry<value>(call: () => Promise<value>): Promise<va
   }
 }
 
+const durableObjectCodecRoot = 'tempo-api:store:json:'
+const durableObjectCodecVersion = 'v1'
+const durableObjectCodecPrefix = `${durableObjectCodecRoot}${durableObjectCodecVersion}:`
+
+function durableObjectEncode(value: unknown): string {
+  if (typeof value === 'string' && !value.startsWith(durableObjectCodecRoot)) return value
+  const encoded = Json.stringify(value)
+  if (encoded === undefined) throw new TypeError('Durable Object store value is not serializable')
+  return `${durableObjectCodecPrefix}${encoded}`
+}
+
+function durableObjectDecode(value: null | string): unknown {
+  if (value === null || !value.startsWith(durableObjectCodecRoot)) return value
+  if (!value.startsWith(durableObjectCodecPrefix)) {
+    const [version] = value.slice(durableObjectCodecRoot.length).split(':')
+    throw new DurableObjectCodecError(version)
+  }
+  return Json.parse(value.slice(durableObjectCodecPrefix.length))
+}
+
 function cloudflareKvExpirationTtl(ttl: number | undefined) {
   if (ttl === undefined) return undefined
   if (ttl <= 0) return 0
@@ -649,3 +756,12 @@ export class UpdateContentionError extends Error {
     super(`Store update on "${key}" lost ${attempts} compare-and-swap attempts.`)
   }
 }
+
+/** Thrown when Durable Object state uses an unsupported codec. */
+export class DurableObjectCodecError extends Error {
+  override name = 'Store.DurableObjectCodecError'
+
+  constructor(version: unknown) {
+    super(`Unsupported Durable Object store codec version: ${String(version)}`)
+  }
+}

package/src/internal/index.test.ts

@@ -0,0 +1,34 @@
+import * as Internal from './index.js'
+
+test('exports internal modules', () => {
+  expect(Object.keys(Internal)).toMatchInlineSnapshot(`
+    [
+      "Auth",
+      "Cache",
+      "Cursor",
+      "EdgeCache",
+      "Errors",
+      "Fees",
+      "FundingRoutes",
+      "Id",
+      "Log",
+      "MetricSink",
+      "Mpp",
+      "OpenApi",
+      "Path",
+      "RateLimit",
+      "Response",
+      "RpcSchema",
+      "Schema",
+      "Store",
+      "Tidx",
+      "Timing",
+      "Ttl",
+      "Value",
+      "VerifiedTokens",
+      "Viem",
+      "WebhookDestination",
+      "Webhooks",
+    ]
+  `)
+})

package/src/internal/index.ts

@@ -0,0 +1,26 @@
+export * as Auth from './Auth.js'
+export * as Cache from './Cache.js'
+export * as Cursor from './Cursor.js'
+export * as EdgeCache from './EdgeCache.js'
+export * as Errors from './Errors.js'
+export * as Fees from './Fees.js'
+export * as FundingRoutes from './FundingRoutes.js'
+export * as Id from './Id.js'
+export * as Log from './Log.js'
+export * as MetricSink from './MetricSink.js'
+export * as Mpp from './Mpp.js'
+export * as OpenApi from './OpenApi.js'
+export * as Path from './Path.js'
+export * as RateLimit from './RateLimit.js'
+export * as Response from './Response.js'
+export * as RpcSchema from './RpcSchema.js'
+export * as Schema from './Schema.js'
+export * as Store from './Store.js'
+export * as Tidx from './Tidx.js'
+export * as Timing from './Timing.js'
+export * as Ttl from './Ttl.js'
+export * as Value from './Value.js'
+export * as VerifiedTokens from './VerifiedTokens.js'
+export * as Viem from './Viem.js'
+export * as WebhookDestination from './WebhookDestination.js'
+export * as Webhooks from './Webhooks.js'