tapimo 0.10.0 → 0.10.1

package/src/internal/MetricSink.ts

@@ -51,6 +51,21 @@ export type WebhookEvent =
       /** Identifies durable coordinator progress. */
       type: 'webhook:head-progress'
     }
+  | {
+      /** Tempo chain whose listener was checked. */
+      chainId: number
+      /** Heads refused in a row by the monotonic guard; zero on a delivering listener. */
+      skippedHeads: number
+      /** Identifies heads received and discarded rather than heads not received. */
+      type: 'webhook:head-skipped'
+    }
+  | {
+      chainId: number
+      /** Blocks the probed chain head leads the listener's newest observation. */
+      lagBlocks: number
+      /** Identifies the out-of-band listener head probe. */
+      type: 'webhook:listener-head-lag'
+    }
   | {
       /** Tempo chain whose recovery poke was dequeued. */
       chainId: number
@@ -145,6 +160,22 @@ export type WebhookEvent =
       type: 'webhook:enqueue'
     }
   | {
+      /** Atomic ledger claim outcome. */
+      outcome: 'attempting' | 'claimed' | 'missing' | 'scheduled' | 'terminal'
+      /** Identifies a delivery-obligation claim. */
+      type: 'webhook:delivery-job-claim'
+    }
+  | {
+      /** Obligations represented by this outcome. */
+      count: number
+      /** Whether staging created or found the obligation. */
+      outcome: 'created' | 'existing'
+      /** Identifies obligation staging ahead of Queue handoff. */
+      type: 'webhook:delivery-job-ensure'
+    }
+  | {
+      /** Delivery attempt ordinal: the ledger claim count on the queue path. */
+      attempt: number
       envelope: Webhooks.Envelope
       /** Cloudflare Queue delivery attempt, absent outside the Queue path. */
       queueAttempt?: number | undefined
@@ -340,6 +371,16 @@ export function webhooks(backend: Metrics): WebhookSink {
             chain_id: String(event.chainId),
           })
           return
+        case 'webhook:head-skipped':
+          backend.gauge('webhook_head_skipped_count', event.skippedHeads, {
+            chain_id: String(event.chainId),
+          })
+          return
+        case 'webhook:listener-head-lag':
+          backend.gauge('webhook_listener_head_lag_blocks', event.lagBlocks, {
+            chain_id: String(event.chainId),
+          })
+          return
         case 'webhook:poll-failure':
           backend.count('webhook_poll_failure_count', 1, {
             chain_id: String(event.chainId),
@@ -456,6 +497,16 @@ export function webhooks(backend: Metrics): WebhookSink {
           })
           return
         }
+        case 'webhook:delivery-job-claim': {
+          backend.count('webhook_delivery_job_claim_count', 1, { outcome: event.outcome })
+          return
+        }
+        case 'webhook:delivery-job-ensure': {
+          backend.count('webhook_delivery_job_ensure_count', event.count, {
+            outcome: event.outcome,
+          })
+          return
+        }
         case 'webhook:delivery': {
           const { envelope, result, subscription, timings } = event
           const queueTags =
@@ -463,7 +514,11 @@ export function webhooks(backend: Metrics): WebhookSink {
               ? {}
               : {
                   queue_attempt_bucket: attemptBucket(event.queueAttempt),
-                  queue_disposition: WebhookDestination.isRetryable(result) ? 'retried' : 'acked',
+                  // Retryable results ack the message and schedule a ledger
+                  // retry; the Queue transport never redelivers them.
+                  queue_disposition: WebhookDestination.isRetryable(result)
+                    ? 'scheduled_retry'
+                    : 'acked',
                 }
           const tags = {
             chain_id: String(envelope.chainId),
@@ -473,7 +528,7 @@ export function webhooks(backend: Metrics): WebhookSink {
           const outcome = result.ok ? 'succeeded' : 'failed'
           backend.count('webhook_delivery_attempt_count', 1, {
             ...tags,
-            attempt_bucket: attemptBucket(subscription.failureCount + 1),
+            attempt_bucket: attemptBucket(event.attempt),
             outcome,
             ...queueTags,
             status_class: statusClass(result),
@@ -495,6 +550,9 @@ export function webhooks(backend: Metrics): WebhookSink {
           if (timings?.endToEndMs !== undefined)
             backend.histogram('webhook_delivery_end_to_end_ms', timings.endToEndMs, {
               ...tags,
+              // Unlimited-horizon ledger retries emit hour-plus samples;
+              // the bucket keeps first-attempt percentiles interpretable.
+              attempt_bucket: attemptBucket(event.attempt),
               outcome,
             })
           if (timings?.eventToEnvelopeMs !== undefined)

package/src/internal/RateLimit.test.ts

@@ -1,13 +1,14 @@
 import { RateLimit, Store } from 'tapimo'
 
 describe('memory', () => {
-  test('tracks fixed-window quota in a store', async () => {
+  test('tracks fixed-minute quota in a store', async () => {
     const store = RateLimit.memory({
       now: () => new Date('2026-05-25T00:00:30.000Z'),
     })
-    const first = await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
-    const second = await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
-    const third = await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+    const limit = { limit: 2, period: 'minute' } as const
+    const first = await store.consume({ key: 'public:anonymous', limit })
+    const second = await store.consume({ key: 'public:anonymous', limit })
+    const third = await store.consume({ key: 'public:anonymous', limit })
 
     expect(first).toMatchInlineSnapshot(`
       {
@@ -35,25 +36,26 @@ describe('memory', () => {
     `)
   })
 
-  test('restarts the count when the next window opens', async () => {
-    // The window reset rides on counter expiry (the key is stable, not
-    // bucket-suffixed), so the store clock and the consume clock must agree.
+  test('restarts the count when the next second opens', async () => {
+    // The window reset rides on counter expiry, so the store clock and the
+    // consume clock must agree.
     vi.useFakeTimers()
     try {
-      vi.setSystemTime(new Date('2026-05-25T00:00:30.000Z'))
+      vi.setSystemTime(new Date('2026-05-25T00:00:30.250Z'))
       const store = RateLimit.memory()
-      await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
-      await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+      const limit = { limit: 2, period: 'second' } as const
+      await store.consume({ key: 'public:anonymous', limit })
+      await store.consume({ key: 'public:anonymous', limit })
 
-      vi.setSystemTime(new Date('2026-05-25T00:01:00.001Z'))
-      const next = await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+      vi.setSystemTime(new Date('2026-05-25T00:00:31.001Z'))
+      const next = await store.consume({ key: 'public:anonymous', limit })
 
       expect(next).toMatchInlineSnapshot(`
         {
           "allowed": true,
           "limit": 2,
           "remaining": 1,
-          "reset": 1779667320,
+          "reset": 1779667232,
         }
       `)
     } finally {
@@ -72,19 +74,22 @@ describe('memory', () => {
       },
     })
     const store = RateLimit.memory({
-      // 30s into the minute, so 30s of the window remains.
-      now: () => new Date('2026-05-25T00:00:30.000Z'),
+      // 250ms into the second, so 750ms of the window remains.
+      now: () => new Date('2026-05-25T00:00:30.250Z'),
       store: recording,
     })
 
-    await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+    await store.consume({
+      key: 'public:anonymous',
+      limit: { limit: 2, period: 'second' },
+    })
 
     expect(increments).toMatchInlineSnapshot(`
       [
         {
-          "key": "ratelimit:public:anonymous",
+          "key": "ratelimit:second:1779667230:public:anonymous",
           "options": {
-            "ttl": 30000,
+            "ttl": 750,
           },
         },
       ]

package/src/internal/RateLimit.ts

@@ -6,9 +6,15 @@ import * as Store from './Store.js'
 export namespace schema {
   /** A rate-limit policy; the source of truth for {@link Limit}. */
   export const Limit = z.object({
-    perMinute: z
+    limit: z
       .number()
-      .check(z.int(), z.nonnegative(), z.describe('Number of requests allowed per minute.')),
+      .check(z.int(), z.nonnegative(), z.describe('Number of requests allowed per period.')),
+    period: z
+      .union([z.literal('minute'), z.literal('second')])
+      .check(
+        z.describe('Fixed window used to enforce the request limit.'),
+        z.meta({ examples: ['minute'] }),
+      ),
   })
 }
 
@@ -49,11 +55,8 @@ export namespace RateLimitStore {
  * Each consume is a single `Store.increment`, so a backend with a native
  * counter (e.g. a Durable Object) is one atomic round trip; backends without
  * one fall back to get + put, acceptable for dev/in-process stores only.
- * The storage key is stable per quota key — the
- * window lives in the TTL: the counter expires exactly at the end of the
- * current minute, so the next window's first hit restarts at 1 and idle keys
- * hold no storage. The sub-minute TTL rules out Cloudflare KV as a backend,
- * which is unsuitable for enforced counters anyway.
+ * The storage key includes the fixed-window bucket, so backend latency cannot
+ * carry a previous count into a later window.
  */
 export function memory(options: memory.Options = {}): RateLimitStore {
   const store = options.store ?? Store.memory()
@@ -62,19 +65,24 @@ export function memory(options: memory.Options = {}): RateLimitStore {
   return {
     async consume(options) {
       const time = now().getTime()
-      const bucket = Math.floor(time / 60_000)
-      // Every increment within a window recomputes the TTL against the same
-      // window end, so the counter's absolute expiry never moves under load.
-      const count = await Store.increment(store, `ratelimit:${options.key}`, {
-        ttl: (bucket + 1) * 60_000 - time,
-      })
-      const limit = options.limit.perMinute
+      const window = options.limit.period === 'second' ? 1_000 : 60_000
+      const bucket = Math.floor(time / window)
+      // The bucket isolates window counts if the backing store applies the TTL
+      // after the next window starts.
+      const count = await Store.increment(
+        store,
+        `ratelimit:${options.limit.period}:${bucket}:${options.key}`,
+        {
+          ttl: (bucket + 1) * window - time,
+        },
+      )
+      const limit = options.limit.limit
 
       return {
         allowed: count <= limit,
         limit,
         remaining: Math.max(limit - count, 0),
-        reset: Math.ceil(((bucket + 1) * 60_000) / 1_000),
+        reset: Math.ceil(((bucket + 1) * window) / 1_000),
       }
     },
   }

package/src/internal/Store.test.ts

@@ -389,6 +389,39 @@ describe('durableObject', () => {
     `)
   })
 
+  test('preserves bigint values and collision-shaped strings', async () => {
+    const { namespace } = TestStore.durableObjectNamespace()
+    const store = Store.durableObject<{
+      value: { bigint: bigint; legacyMarker: string; valueMarker: string }
+    }>(namespace)
+    const value = {
+      bigint: 42n,
+      legacyMarker: '123#__bigint',
+      valueMarker: 'tempo-api:store:value:bigint:123',
+    }
+
+    await store.put('value', value)
+    await store.update('value', (current) => ({
+      op: 'set',
+      result: undefined,
+      value: { ...current!, bigint: current!.bigint + 1n },
+    }))
+
+    expect(await store.get('value')).toEqual({ ...value, bigint: 43n })
+  })
+
+  test('reads typed values written with the legacy codec', async () => {
+    const { getState, namespace } = TestStore.durableObjectNamespace()
+    await getState('channel').put('channel', 'tempo-api:store:json:v1:{"spent":"42#__bigint"}')
+    const store = Store.durableObject<TypedItems>(namespace)
+
+    expect(await store.get('channel')).toMatchInlineSnapshot(`
+      {
+        "spent": 42n,
+      }
+    `)
+  })
+
   test('keeps typed updates linearizable', async () => {
     const { namespace } = TestStore.durableObjectNamespace()
     const storeA = Store.durableObject<TypedItems>(namespace)
@@ -439,11 +472,11 @@ describe('durableObject', () => {
 
   test('rejects typed values written with an unknown codec version', async () => {
     const { getState, namespace } = TestStore.durableObjectNamespace()
-    await getState('channel').put('channel', 'tempo-api:store:json:v2:{}')
+    await getState('channel').put('channel', 'tempo-api:store:json:v3:{}')
     const store = Store.durableObject<TypedItems>(namespace)
 
     await expect(store.get('channel')).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[Store.DurableObjectCodecError: Unsupported Durable Object store codec version: v2]`,
+      `[Store.DurableObjectCodecError: Unsupported Durable Object store codec version: v3]`,
     )
   })
 
@@ -744,11 +777,9 @@ describe('memoize', () => {
     const values = await Promise.all(requests)
 
     expect(calls).toMatchInlineSnapshot(`1`)
-    expect(JSON.parse((await store.get('memo:test')) ?? 'null')).toMatchInlineSnapshot(`
-      {
-        "value": "fresh",
-      }
-    `)
+    expect(await store.get('memo:test')).toMatchInlineSnapshot(
+      `"tempo-api:store:json:v2:{"value":"fresh"}"`,
+    )
     expect(values).toMatchInlineSnapshot(`
       [
         {
@@ -805,8 +836,65 @@ describe('memoize', () => {
     `)
   })
 
+  test('preserves bigint values and collision-shaped strings on cache hits', async () => {
+    const store = Store.memory()
+    let calls = 0
+    const fetch = async () => {
+      calls += 1
+      return {
+        bigint: 42n,
+        legacyMarker: '123#__bigint',
+        valueMarker: 'tempo-api:store:value:bigint:123',
+      }
+    }
+
+    const first = await Store.memoize(fetch, { key: 'memo:test', store, ttl: 60_000 })
+    const second = await Store.memoize(fetch, { key: 'memo:test', store, ttl: 60_000 })
+
+    expect(first).toEqual(second)
+    expect(second).toEqual({
+      bigint: 42n,
+      legacyMarker: '123#__bigint',
+      valueMarker: 'tempo-api:store:value:bigint:123',
+    })
+    expect(calls).toBe(1)
+  })
+
+  test('does not cache undefined results', async () => {
+    const store = Store.memory()
+    let calls = 0
+    const fetch = async () => {
+      calls += 1
+      return undefined
+    }
+
+    const first = await Store.memoize(fetch, { key: 'memo:test', store, ttl: 60_000 })
+    const second = await Store.memoize(fetch, { key: 'memo:test', store, ttl: 60_000 })
+
+    expect(first).toBeUndefined()
+    expect(second).toBeUndefined()
+    expect(await store.get('memo:test')).toBeNull()
+    expect(calls).toBe(2)
+  })
+
+  test('refreshes legacy untagged cache entries', async () => {
+    const store = Store.memory({ entries: [['memo:test', '{"value":"123#__bigint"}']] })
+    let calls = 0
+
+    const value = await Store.memoize(
+      async () => {
+        calls += 1
+        return { value: '123#__bigint' }
+      },
+      { key: 'memo:test', store, ttl: 60_000 },
+    )
+
+    expect(value).toEqual({ value: '123#__bigint' })
+    expect(calls).toBe(1)
+  })
+
   test('refreshes corrupt cache entries', async () => {
-    const store = Store.memory({ entries: [['memo:test', 'not-json']] })
+    const store = Store.memory({ entries: [['memo:test', 'tempo-api:store:json:v2:not-json']] })
 
     const value = await Store.memoize(async () => ({ value: 'fresh' }), {
       key: 'memo:test',
@@ -819,11 +907,9 @@ describe('memoize', () => {
         "value": "fresh",
       }
     `)
-    expect(JSON.parse((await store.get('memo:test')) ?? 'null')).toMatchInlineSnapshot(`
-      {
-        "value": "fresh",
-      }
-    `)
+    expect(await store.get('memo:test')).toMatchInlineSnapshot(
+      `"tempo-api:store:json:v2:{"value":"fresh"}"`,
+    )
   })
 })
 

package/src/internal/Store.ts

@@ -578,7 +578,8 @@ export declare namespace durableObject {
 /**
  * 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.
+ * under `key` with `ttl` milliseconds, and returns it. Undefined results are
+ * returned without being cached.
  */
 export async function memoize<value>(
   fetch: () => Promise<value>,
@@ -587,9 +588,11 @@ export async function memoize<value>(
   const { key, store, ttl } = options
 
   const raw = await store.get(key)
-  if (raw) {
+  // Old cache entries used ambiguous untagged bigint strings. Refresh them
+  // instead of guessing whether a matching string was originally a bigint.
+  if (raw?.startsWith(jsonCodecPrefix)) {
     try {
-      return Json.parse(raw) as value
+      return jsonDecode(raw) as value
     } catch {
       // Corrupt entries are treated as misses so the next call refreshes.
     }
@@ -604,7 +607,8 @@ export async function memoize<value>(
   // fetch is still in flight.
   const flight = (async () => {
     const value = await fetch()
-    await store.put(key, Json.stringify(value), { ttl })
+    if (value === undefined) return value
+    await store.put(key, jsonEncode(value), { ttl })
     return value
   })()
   flights.set(key, flight)
@@ -721,24 +725,55 @@ async function durableObjectRetry<value>(call: () => Promise<value>): Promise<va
   }
 }
 
-const durableObjectCodecRoot = 'tempo-api:store:json:'
-const durableObjectCodecVersion = 'v1'
-const durableObjectCodecPrefix = `${durableObjectCodecRoot}${durableObjectCodecVersion}:`
+const jsonCodecRoot = 'tempo-api:store:json:'
+const jsonCodecVersion = 'v2'
+const jsonCodecPrefix = `${jsonCodecRoot}${jsonCodecVersion}:`
+const jsonValuePrefix = 'tempo-api:store:value:'
+const legacyDurableObjectCodecPrefix = `${jsonCodecRoot}v1:`
+
+function jsonEncode(value: unknown): string {
+  const encoded = JSON.stringify(value, (_key, item) => {
+    if (typeof item === 'bigint') return `${jsonValuePrefix}bigint:${item}`
+    if (typeof item === 'string' && item.startsWith(jsonValuePrefix))
+      return `${jsonValuePrefix}string:${item}`
+    return item
+  })
+  if (encoded === undefined) throw new TypeError('Store value is not serializable')
+  return `${jsonCodecPrefix}${encoded}`
+}
+
+function jsonDecode(value: string): unknown {
+  return JSON.parse(value.slice(jsonCodecPrefix.length), (_key, item) => {
+    if (typeof item !== 'string' || !item.startsWith(jsonValuePrefix)) return item
+    if (item.startsWith(`${jsonValuePrefix}string:`))
+      return item.slice(`${jsonValuePrefix}string:`.length)
+    if (item.startsWith(`${jsonValuePrefix}bigint:`)) {
+      const bigint = item.slice(`${jsonValuePrefix}bigint:`.length)
+      if (!/^-?\d+$/.test(bigint)) throw new TypeError('Store bigint is malformed')
+      return BigInt(bigint)
+    }
+    throw new TypeError('Store value tag is unsupported')
+  })
+}
 
 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}`
+  if (typeof value === 'string' && !value.startsWith(jsonCodecRoot)) return value
+  try {
+    return jsonEncode(value)
+  } catch (cause) {
+    throw new TypeError('Durable Object store value is not serializable', {
+      cause,
+    })
+  }
 }
 
 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))
+  if (value === null || !value.startsWith(jsonCodecRoot)) return value
+  if (value.startsWith(jsonCodecPrefix)) return jsonDecode(value)
+  if (value.startsWith(legacyDurableObjectCodecPrefix))
+    return Json.parse(value.slice(legacyDurableObjectCodecPrefix.length))
+  const [version] = value.slice(jsonCodecRoot.length).split(':')
+  throw new DurableObjectCodecError(version)
 }
 
 function cloudflareKvExpirationTtl(ttl: number | undefined) {

package/src/internal/Tidx.test.ts

@@ -330,9 +330,9 @@ describe('resolve', () => {
   test('passes Zone metadata to the resolver', () => {
     expect(
       Tidx.resolve(({ zone }) => ({ baseUrl: zone ? 'http://tidx:8080' : undefined }), {
-        chainId: Zones.zoneModerato.id,
+        chainId: Zones.zoneModeratoInternal.id,
         principal: null,
-        zone: Zones.zoneModerato,
+        zone: Zones.zoneModeratoInternal,
       }),
     ).toMatchInlineSnapshot(`
       {
@@ -469,7 +469,7 @@ describe('getClient', () => {
     )
     try {
       const client = Tidx.getClient({
-        chainId: Zones.zoneModerato.id,
+        chainId: Zones.zoneModeratoInternal.id,
         tidx: {
           baseUrl: 'https://internal.indexer',
           zoneHeaders: {
@@ -477,7 +477,7 @@ describe('getClient', () => {
             'CF-Access-Client-Secret': 'client-secret',
           },
         },
-        zone: Zones.zoneModerato,
+        zone: Zones.zoneModeratoInternal,
       })
       await client.fetch({ query: 'select 1' })
 

package/src/internal/Value.test.ts

@@ -1,5 +1,30 @@
 import * as Value from './Value.js'
 
+describe('blockToIso', () => {
+  test('prefers the millisecond timestamp on a raw header', () => {
+    expect(
+      Value.blockToIso({ timestamp: '0x6a7b5571', timestampMillis: '0x19ff1c5c312' }),
+    ).toMatchInlineSnapshot(`"2026-08-11T17:01:37.426Z"`)
+  })
+
+  test('falls back to whole seconds when the millisecond timestamp is absent', () => {
+    expect(Value.blockToIso({ timestamp: '0x6a7b5571' })).toMatchInlineSnapshot(
+      `"2026-08-11T17:01:37.000Z"`,
+    )
+  })
+
+  test('reads a viem-formatted header', () => {
+    expect(
+      Value.blockToIso({ timestamp: 1_786_467_697n, timestampMillis: '0x19ff1c5c312' }),
+    ).toMatchInlineSnapshot(`"2026-08-11T17:01:37.426Z"`)
+  })
+
+  test('returns undefined without a usable timestamp', () => {
+    expect(Value.blockToIso(undefined)).toMatchInlineSnapshot(`undefined`)
+    expect(Value.blockToIso({ timestamp: null })).toMatchInlineSnapshot(`undefined`)
+  })
+})
+
 describe('tokenAmount', () => {
   test('renders a self-contained token quantity', () => {
     expect(

package/src/internal/Value.ts

@@ -111,6 +111,35 @@ export function hexSecondsToIso(value: unknown): string | undefined {
   return seconds === undefined ? undefined : new Date(seconds * 1000).toISOString()
 }
 
+/**
+ * Read a block's timestamp as epoch milliseconds, preferring Tempo's
+ * `timestampMillis` over the second-granularity `timestamp`. Accepts hex
+ * quantities (raw RPC) and bigint/number (viem-formatted).
+ */
+function blockToMillis(block: unknown): number | undefined {
+  if (typeof block !== 'object' || block === null) return undefined
+  const { timestamp, timestampMillis } = block as {
+    timestamp?: unknown
+    timestampMillis?: unknown
+  }
+  const millis = quantity(timestampMillis)
+  if (millis !== undefined) return millis
+  const seconds = quantity(timestamp)
+  return seconds === undefined ? undefined : seconds * 1_000
+}
+
+/** Convert a block's timestamp to an ISO 8601 datetime string, preserving milliseconds. */
+export function blockToIso(block: unknown): string | undefined {
+  const millis = blockToMillis(block)
+  return millis === undefined ? undefined : new Date(millis).toISOString()
+}
+
+/** Narrows a quantity that may arrive hex-encoded (raw RPC) or decoded (viem). */
+function quantity(value: unknown): number | undefined {
+  const number = toNumber(value)
+  return number === undefined || !Number.isFinite(number) ? undefined : number
+}
+
 /**
  * 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