@kairos-es/read 0.0.0

package/src/testing.ts

@@ -0,0 +1,290 @@
+/**
+ * Test-support for the READ side, shared across every kairos-es suite — and
+ * across a consumer's own suites — via the published `@kairos-es/read/testing`
+ * subpath.
+ *
+ * ## Why the read side needs a testing surface at all
+ *
+ * A projection is a DAEMON. Every assertion about a read model is therefore an
+ * assertion about a forked fibre that has not necessarily finished, so the very
+ * first thing anybody writing a read-model test has to invent is "run this
+ * projection until it has consumed the log, THEN look at the view". There is no
+ * other way to phrase it: `runProjection` returns as soon as the daemon is
+ * forked, on purpose, because starting a projection is not the same event as a
+ * projection having caught up.
+ *
+ * Left uninvented, that gap is filled by a sleep — and a sleep is the one answer
+ * that is wrong in both directions at once. Too short and the suite is flaky on a
+ * loaded machine; too long and every case pays for the worst machine anybody runs
+ * it on. So the answer here is to POLL THE OBSERVABLE STATE: re-read the stored
+ * checkpoint until it reaches the position under test, under a generous ceiling
+ * whose only job is to turn a genuine hang into a failed assertion NAMING the
+ * position that was never reached, rather than an undiagnosable framework
+ * timeout. A slow machine then takes longer; it does not fail.
+ *
+ * That reasoning was written out three times in this repo — in `read`'s own
+ * runner suite, in `read-postgres`'s live-log cases and in the worked example —
+ * with three slightly different timeout strings, which is the usual evidence that
+ * a library is missing a surface rather than that its tests are untidy. It is
+ * written once here, and everything else imports it.
+ *
+ * ## Why a published SUBPATH rather than a package
+ *
+ * `@kairos-es/core/testing` is the precedent and the test this module has to
+ * pass: a subpath shares its package's dependency surface, so it may exist only
+ * if it adds NO peer to that surface. Nothing below imports anything
+ * `@kairos-es/read` does not already peer (`effect`, `@kairos-es/core`,
+ * `@kairos-es/codec`), and in particular nothing here imports a test FRAMEWORK.
+ * There is no `expect`, no `it`, no `@effect/vitest`: what a caller gets is plain
+ * `Effect`s (and one pure function, `lastPosition`) run under whatever runner it
+ * already has. That is what keeps `@kairos-es/read`'s published peer set
+ * unchanged, and it is why this is not `@kairos-es/testing`, which peers
+ * `@effect/vitest` because a Given/When/Then surface genuinely needs one.
+ *
+ * ## The boundary against `@kairos-es/projection-store-contract-tests`
+ *
+ * That package publishes `keyFor` / `position` / `storedPosition` /
+ * `advanceCheckpoint`, and the overlap is apparent rather than real. Those are
+ * tools for proving the MULTI-KEY PORT: they brand raw strings and bigints into
+ * the port's domain types and perform the setup moves a guard case needs, they
+ * are addressed to somebody implementing a `ProjectionStore` BACKEND, and the
+ * package is private and unpublished. This module is addressed to somebody
+ * running a READ MODEL — an application author, or one of this repo's own suites
+ * — and every export that observes a view takes the `KeyedProjectionStore` a read
+ * model is actually handed, never a `(store, key)` pair. (`lastPosition` takes no
+ * store at all: it derives a convergence TARGET from what `append` returned, which
+ * is not an observation of a view.) Same domain, different surface, different
+ * publication status. Neither imports the other: `read` cannot depend on a suite
+ * that already depends on `read`.
+ *
+ * ## Platform-neutral, like the rest of the package
+ *
+ * No `node:*`, no `Date`, no host RNG. The poll interval and the ceiling are
+ * Effect `Duration`s scheduled through the `Clock`, so a caller who can drive the
+ * clock still can.
+ */
+import type {
+  RequirementOf,
+  Serializer,
+  SliceProjection,
+} from '@kairos-es/codec'
+import type { DcbEventStore, Position } from '@kairos-es/core'
+import { Array as Arr, type Duration, Effect, Option, type Scope } from 'effect'
+import type { EventLogDurability } from './EventLogDurability'
+import type {
+  ProjectionRunner,
+  ProjectionRunnerOptions,
+} from './ProjectionRunner'
+import type { KeyedProjectionStore } from './ProjectionStore'
+import { type ReadModel, runProjection } from './runProjection'
+
+/**
+ * How often the waiting fibre re-reads the checkpoint. Small, because the wait
+ * ends on the FIRST read that has got there and a coarse interval would add its
+ * own latency to every case; not zero, because each read is a real store
+ * operation (a SQL round trip on a durable backend).
+ */
+const DEFAULT_POLL_INTERVAL: Duration.DurationInput = '2 millis'
+
+/**
+ * The ceiling on convergence. Deliberately far larger than any well-behaved case
+ * needs: it exists to turn a genuine hang into a FAILED assertion naming the
+ * position that was never reached, not to police how fast a runner is on a loaded
+ * machine. Backends whose live tail has its own poll interval — Postgres wakes on
+ * NOTIFY but GUARANTEES delivery by polling — should raise it to several of those
+ * intervals rather than lower it.
+ */
+const DEFAULT_TIMEOUT: Duration.DurationInput = '10 seconds'
+
+/**
+ * How a convergence wait is paced and bounded.
+ *
+ * Both figures are per-DEPLOYMENT judgements rather than contract, in the same
+ * sense the runner's own tuning is: an in-memory log converges in microseconds
+ * and a containerised Postgres does not, so the defaults suit the former and the
+ * latter says so at its call site.
+ */
+export interface AwaitCheckpointOptions {
+  /** How often to re-read the stored checkpoint. Default `'2 millis'`. */
+  readonly pollInterval?: Duration.DurationInput
+
+  /**
+   * How long to wait before treating the projection as hung. Default
+   * `'10 seconds'`. Exceeding it is a DEFECT, not a failure — see
+   * `awaitCheckpoint`.
+   */
+  readonly timeout?: Duration.DurationInput
+}
+
+/**
+ * The stored checkpoint of a read model's bound view store, right now.
+ *
+ * `orDie` because a `ProjectionStoreError` means the test's own fixture cannot
+ * read its own checkpoint. The port puts that on the ERROR channel for the
+ * runner's supervisor, which has to tell retry-with-backoff from give-up
+ * (ADR-0007) — but a test has no supervisor and nothing to retry, so surfacing it
+ * as a defect keeps a broken fixture clearly distinct from the case's own
+ * assertion failing, and keeps every signature here `E = never` so a case never
+ * has to widen its own error channel to look at a view.
+ */
+export const storedCheckpoint = (
+  store: KeyedProjectionStore,
+): Effect.Effect<Position> => Effect.orDie(store.readCheckpoint)
+
+/**
+ * Wait until the stored checkpoint has reached `target`, then return it.
+ *
+ * The read side's answer to "has the projection caught up yet?", and the reason
+ * a read-model test needs no sleep: it polls the OBSERVABLE state, so it ends the
+ * instant the runner has actually got there and no sooner. Comparison is `>=`
+ * rather than `===` and that is load-bearing — positions are strictly increasing
+ * but NOT gapless, so a target derived from an append may be overshot by a batch
+ * that carried later events too, and an equality test would then wait for a
+ * position the log will never store.
+ *
+ * A KEYED store rather than a `(store, key)` pair, matching the shape the package
+ * settled on everywhere else: a read model's materialisation carries
+ * `forKey(store, key)` INSTEAD of a key field, so "one materialisation, one key" is
+ * structural rather than conventional, and the same argument applies to observing
+ * one. There is no key to transpose, the timeout message names `store.key` and
+ * therefore cannot name a key the poll did not use, and `readModel.store` is
+ * already exactly the right argument. A caller holding the multi-key port writes
+ * `forKey(store, key)`, which is the library's own one-line adapter and is
+ * `store.readCheckpoint(key)` with a `suspend` around it — so a suite deliberately
+ * observing through the RAW port (as `read-postgres`' live-log cases do, to keep
+ * "the façade wrote where the port reads" an observation rather than an assumption)
+ * loses nothing.
+ *
+ * A read model materialised N ways (`runProjections`) is N of these observations,
+ * one per store, and there is deliberately no plural helper for it. Under one
+ * `ProjectionId` and the default partition the N keys are IDENTICAL — a key names a
+ * cursor within a store — so the STORE is what distinguishes the materialisations,
+ * and each runner carries its own: `awaitCheckpoint(runners[i].store, target)` is
+ * already the per-entry observation, over the very binding the call made. So a plural
+ * helper would take nothing a caller does not already hold, and the N waits are one
+ * `Effect.all` over the runners it was handed — concurrently, since waiting on them
+ * in turn would prove only that each converges once the others have.
+ *
+ * Exceeding the timeout is a DEFECT, so this stays `E = never` and a case need
+ * not thread a timeout error it has no intention of handling. It is the right
+ * classification anyway: a projection that never converged is a broken test or a
+ * broken library, never an outcome to assert on.
+ */
+export const awaitCheckpoint = (
+  store: KeyedProjectionStore,
+  target: Position,
+  options?: AwaitCheckpointOptions,
+): Effect.Effect<Position> =>
+  Effect.repeat(
+    Effect.zipRight(
+      Effect.sleep(options?.pollInterval ?? DEFAULT_POLL_INTERVAL),
+      storedCheckpoint(store),
+    ),
+    { until: (stored) => stored >= target },
+  ).pipe(
+    Effect.timeoutFail({
+      duration: options?.timeout ?? DEFAULT_TIMEOUT,
+      onTimeout: () =>
+        new Error(
+          `awaitCheckpoint: the checkpoint for projection ` +
+            `'${store.key.projection}' (partition '${store.key.partition}') ` +
+            `never reached position ${target}`,
+        ),
+    }),
+    Effect.orDie,
+  )
+
+/**
+ * Everything `runProjectionUntil` takes: the runner's own tuning plus the wait's.
+ *
+ * ONE FLAT object, for the reason `ProjectionRunnerOptions` is itself flat —
+ * `{ ...OPTIONS, oneField }` is the dominant override idiom in this repo, and a
+ * spread is shallow, so a nested shape would silently drop a whole group's
+ * siblings. The two halves stay distinct TYPES, which is where the distinction
+ * belongs; the field names are disjoint, so nothing is ambiguous at a call site.
+ */
+export interface RunProjectionUntilOptions
+  extends ProjectionRunnerOptions,
+    AwaitCheckpointOptions {}
+
+/**
+ * Start the projection maintaining `readModel` and wait until its checkpoint has
+ * reached `target` — "run this until it has consumed the log", as one call.
+ *
+ * This is the surface the read side was missing. `runProjection` returns once the
+ * daemon is FORKED, which is the only honest thing it can do, so every read-model
+ * test is otherwise a two-step dance the author has to know to write; this pairs
+ * the two steps so that a case's next line can assert on the view.
+ *
+ * It returns the `ProjectionRunner` rather than swallowing it, because everything
+ * a case might do next needs the handle: `Fiber.poll` it (is the daemon still
+ * up?), `Fiber.interrupt` it early, or await it. The scope is still the teardown
+ * mechanism — this forks into the CALLER's `Scope`, exactly as `runProjection`
+ * does, so closing that scope interrupts the daemon and waits for it.
+ *
+ * ## What it deliberately is NOT
+ *
+ * A TEST helper, not a production freshness API. It reports nothing about lag, it
+ * cannot enumerate checkpoints, and no consumer should reach for it to make a
+ * request wait for its own write to be projected — a read model is eventually
+ * consistent by construction and a `waitUntilProcessed` on the hot path would be
+ * a way to pretend otherwise. That is why it lives behind `/testing` and not on
+ * the package's main entry. Where a request genuinely must see its own write, the
+ * honest answer is not to wait on a MAINTAINED materialisation at all: fold the log
+ * at query time with `modelAtHead` from `@kairos-es/codec`, which is consistent as
+ * of the `head` its read returned and therefore never behind a checkpoint.
+ *
+ * It also does not race the daemon's fibre against the wait. A projection that
+ * gives up fails `ProjectionStalled`, and it would be possible to surface that
+ * here instead of timing out — but the daemon's failure and the convergence
+ * ceiling are two independent clocks, and a helper whose diagnosis depended on
+ * which fired first is a worse instrument than one that always says the same
+ * thing. A case that wants the stall itself has the fibre returned above, and
+ * `onStalled` besides.
+ */
+export const runProjectionUntil = <
+  T extends Record<string, SliceProjection>,
+  E,
+  R,
+>(
+  readModel: ReadModel<T, E, R>,
+  target: Position,
+  options?: RunProjectionUntilOptions,
+): Effect.Effect<
+  ProjectionRunner,
+  never,
+  | Scope.Scope
+  | DcbEventStore
+  | EventLogDurability
+  | Serializer
+  | RequirementOf<T>
+  | R
+> =>
+  Effect.tap(runProjection(readModel, options), () =>
+    // The read model's OWN bound store, so the cursor being waited on is
+    // necessarily the cursor the runner advances. A `store` parameter here would
+    // reintroduce exactly the pair `KeyedProjectionStore` exists to abolish.
+    awaitCheckpoint(readModel.store, target, options),
+  )
+
+/**
+ * The LAST position of a sequence — the convergence target, derived from what
+ * `append` actually reported.
+ *
+ * The companion to the two waits above, and the reason it is a helper rather than
+ * `positions[positions.length - 1]`: a fixture that appended nothing would
+ * otherwise yield `undefined`, and a wait for `undefined` is either a type error
+ * at best or a vacuous assertion at worst. Failing loudly at the point the
+ * fixture is wrong is worth four lines.
+ *
+ * Targets are built this way — from the positions the log HANDED OUT — rather
+ * than from a literal `1n..Nn`, because positions are strictly increasing and NOT
+ * gapless: a rolled-back append burns an id, and a tag-narrowed subscription
+ * never delivers the positions it does not match. Nothing here does arithmetic on
+ * a position.
+ */
+export const lastPosition = (positions: ReadonlyArray<Position>): Position =>
+  Option.getOrThrowWith(
+    Arr.last(positions),
+    () => new Error('test fixture: no events were appended'),
+  )

package/testing/package.json

@@ -0,0 +1,6 @@
+{
+  "sideEffects": [],
+  "main": "../dist/cjs/testing.js",
+  "module": "../dist/esm/testing.js",
+  "types": "../dist/dts/testing.d.ts"
+}