@kairos-es/read 0.0.0

package/dist/cjs/runProjection.js

@@ -0,0 +1,117 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.runProjection = exports.projectionLayer = void 0;
+var _effect = require("effect");
+var _ProjectionRunner = require("./ProjectionRunner.js");
+/**
+ * Start the daemon maintaining `readModel`, forked into the caller's `Scope`.
+ *
+ * The returned effect is INFALLIBLE (`E = never`): starting a projection cannot
+ * fail, because everything that can go wrong once it is running is the
+ * supervisor's business and lives on the fibre's error channel.
+ *
+ * ## What can go wrong BEFORE the fork is a programming error, and those are defects
+ *
+ * Which wirings are refused on the READ SIDE'S rules, why each one is a wiring
+ * nothing at runtime would ever notice, and the order they are judged in are all
+ * `projectionWiringFault`'s — one gate over five rules, whose only relation to this
+ * function is that it is the one place they can be applied before anything exists to
+ * be wrong. The gate judges a SET of materialisations, and this function supplies a
+ * SINGLETON: the two PER-ENTRY rungs judge that one wiring, the two that are
+ * functions of the shared query and slice record judge it once and would do so
+ * whatever N was, and the collision rung is a property of the set and is vacuous over
+ * one entry, having no sibling to be paired with. That is also why nothing here carries
+ * an entry index — the gate names one only where there is a set to index into.
+ * A further refusal is the CODEC's and fires just below the gate; `prepareProjection`
+ * owns that ordering for both entry points, and the gate's doc says why the rule
+ * stays in the codec. This function keeps the two claims that are its own.
+ *
+ * The verdict is a DEFECT rather than a value on the error channel, because no
+ * application can handle its own mis-wiring: the only repair is to change the
+ * wiring, and a channel value would ask every caller to write a handler for a
+ * mistake that has already been made by the time the program runs. `Effect.die`
+ * with an `Error` is the same classification the store gives a mis-built query
+ * through `assertServableQuery`, which is one of the rules.
+ *
+ * And it lands on THIS effect before the `forkScoped` at the foot of `buildAndFork`:
+ * the gate is consulted while the daemon is still being
+ * assembled, so a rejected wiring has read no checkpoint, opened no subscription
+ * and left no half-started fibre behind. That is what makes the defect safe to
+ * raise rather than merely early, and every construction case in this package
+ * asserts the stored checkpoint is still `ORIGIN` afterwards to keep it true.
+ *
+ * The preamble on the message is written HERE, once, naming the projection and the
+ * partition — the gate returns the sentence about the RULE, and this function knows
+ * WHO broke it. The single `Effect.die` that joins them is `prepareProjection`'s,
+ * which is why there is one for both entry points rather than one per rule.
+ */
+const runProjection = (readModel, options) => _effect.Effect.gen(function* () {
+  // ## RESOLVE — every value the gate has to judge, and every figure that runs
+  //
+  // `resolveProjection` is a pure function shared with `runProjections`, so the
+  // defaults, the key and the view's durability are read in ONE place for both
+  // callers: the figure that was judged cannot differ from the figure that runs.
+  const view = readModel.store;
+  const resolved = (0, _ProjectionRunner.resolveProjection)(view, options);
+  // ## PREPARE — the log's durability, the merged query, the gate, the decode
+  //
+  // The shared middle, and the same call `runProjections` makes: it reads
+  // `EventLogDurability` from context, composes the query, consults the gate and
+  // only then builds the decode stage — an order `prepareProjection` owns on behalf
+  // of both entry points, and whose reasons are on it rather than restated here.
+  //
+  // The entry list is a SINGLETON, over which the collision rung has no pair to
+  // find. Its `cursorIdentity` is what that rung compares by reference — the BOUND
+  // view here, which `runProjections` could not use and does not, since a lone
+  // entry can only ever be compared with itself and the choice is therefore free at
+  // this arity.
+  //
+  // The preamble is this function's own half of the defect message and the only
+  // half it writes: the gate returns the sentence about the RULE, and this names
+  // the projection and the partition whose wiring broke it. No entry index, because
+  // there is no set to index into.
+  const prepared = yield* (0, _ProjectionRunner.prepareProjection)(readModel.slices, [{
+    ...resolved,
+    cursorIdentity: view
+  }], `runProjection: invalid wiring for projection ` + `'${resolved.key.projection}' (partition ` + `'${resolved.key.partition}')`);
+  // ## BUILD AND FORK — the pipeline, the read side's own rules now satisfied
+  return yield* (0, _ProjectionRunner.buildAndFork)(resolved, {
+    query: prepared.query,
+    decode: prepared.decode,
+    apply: readModel.apply,
+    options
+  });
+});
+/**
+ * `runProjection` as a `Layer` whose own scope owns the daemon.
+ *
+ * It provides NOTHING (`ROut = never`): a projection is a background process, not
+ * a service, and nothing should be able to depend on it as one — a read model is
+ * queried through its view store, never through the runner. What the `Layer` buys
+ * is lifecycle: dropped into an application's layer graph, the daemon starts when
+ * the graph is built and is interrupted when it is released, alongside the store
+ * layers it reads from, with no bespoke startup or shutdown code.
+ *
+ * Discarding the runner discards its fibre too, which is correct and has one
+ * consequence worth wiring for: under this `Layer` — the recommended shape — a
+ * `ProjectionStalled` has no fibre to be awaited on, so it reaches the outside
+ * world only through the supervisor's `Effect.logError` and through `onStalled`.
+ * That hook is the reason a stall need not be a log line somebody happens to grep
+ * for; pass one in `options` if a stalled projection should fail a health check,
+ * exit non-zero, or page.
+ *
+ * `Layer.scopedDiscard` discharges the `Scope` the fork needs; the store, its
+ * `EventLogDurability` declaration, the `Serializer`, the slices' requirements and
+ * the read model's own `R` stay on the layer's inputs, so they are satisfied the
+ * same way every other layer's are. `EventLogDurability` being an INPUT is what
+ * makes the wiring read correctly: the declaration is provided once, alongside the
+ * `DcbEventStore` layer it describes, and every projection layer in the graph is
+ * then satisfied from that one declaration.
+ */
+exports.runProjection = runProjection;
+const projectionLayer = (readModel, options) => _effect.Layer.scopedDiscard(runProjection(readModel, options));
+exports.projectionLayer = projectionLayer;
+//# sourceMappingURL=runProjection.js.map

package/dist/cjs/runProjection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runProjection.js","names":["_effect","require","_ProjectionRunner","runProjection","readModel","options","Effect","gen","view","store","resolved","resolveProjection","prepared","prepareProjection","slices","cursorIdentity","key","projection","partition","buildAndFork","query","decode","apply","exports","projectionLayer","Layer","scopedDiscard"],"sources":["../../src/runProjection.ts"],"sourcesContent":[null],"mappings":";;;;;;AAuCA,IAAAA,OAAA,GAAAC,OAAA;AAEA,IAAAC,iBAAA,GAAAD,OAAA;AA6FA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CO,MAAME,aAAa,GAAGA,CAC3BC,SAA6B,EAC7BC,OAAiC,KAWjCC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB;EACA;EACA;EACA;EACA;EACA,MAAMC,IAAI,GAAGJ,SAAS,CAACK,KAAK;EAC5B,MAAMC,QAAQ,GAAG,IAAAC,mCAAiB,EAACH,IAAI,EAAEH,OAAO,CAAC;EAEjD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,MAAMO,QAAQ,GAAG,OAAO,IAAAC,mCAAiB,EACvCT,SAAS,CAACU,MAAM,EAChB,CAAC;IAAE,GAAGJ,QAAQ;IAAEK,cAAc,EAAEP;EAAI,CAAE,CAAC,EACvC,+CAA+C,GAC7C,IAAIE,QAAQ,CAACM,GAAG,CAACC,UAAU,eAAe,GAC1C,IAAIP,QAAQ,CAACM,GAAG,CAACE,SAAS,IAAI,CACjC;EAED;EACA,OAAO,OAAO,IAAAC,8BAAY,EAACT,QAAQ,EAAE;IACnCU,KAAK,EAAER,QAAQ,CAACQ,KAAK;IACrBC,MAAM,EAAET,QAAQ,CAACS,MAAM;IACvBC,KAAK,EAAElB,SAAS,CAACkB,KAAK;IACtBjB;GACD,CAAC;AACJ,CAAC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;AAAAkB,OAAA,CAAApB,aAAA,GAAAA,aAAA;AA0BO,MAAMqB,eAAe,GAAGA,CAK7BpB,SAA6B,EAC7BC,OAAiC,KAK9BoB,aAAK,CAACC,aAAa,CAACvB,aAAa,CAACC,SAAS,EAAEC,OAAO,CAAC,CAAC;AAAAkB,OAAA,CAAAC,eAAA,GAAAA,eAAA","ignoreList":[]}

package/dist/cjs/runProjections.js

@@ -0,0 +1,144 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.runProjections = void 0;
+var _effect = require("effect");
+var _ProjectionRunner = require("./ProjectionRunner.js");
+var _ProjectionStore = require("./ProjectionStore.js");
+/**
+ * Start one daemon per materialisation, all forked into the caller's `Scope`.
+ *
+ * The returned effect is INFALLIBLE for the reason `runProjection`'s is: starting a
+ * projection cannot fail, because everything that can go wrong once one is running
+ * belongs to its own supervisor and lives on its own fibre's error channel. The
+ * runners come back in ENTRY ORDER, so `runners[i]` is `materialisations[i]`'s.
+ *
+ * Each runner carries the store THIS call bound for its entry, so `runners[i].store`
+ * is that materialisation's cursor and a caller observing one re-derives no binding
+ * it never wrote. It is also what tells the N handles apart: under one `ProjectionId`
+ * the keys are equal wherever no entry named a partition, so a runner carrying only a
+ * key could not name which of the N views it maintains.
+ *
+ * ## N = 1 is legal and carries nothing inert
+ *
+ * One entry is `runProjection` with the `forKey` binding done for you, and every
+ * field means the same thing it means at N = 3. The two run the identical phases —
+ * one `resolveProjection`, one `prepareProjection`, one `buildAndFork` — rather than
+ * merely offering the same surface, so there is no threshold at which a caller should
+ * switch functions: a read model that grows a second materialisation adds an entry.
+ *
+ * ## Every rule is judged before ANY entry is forked
+ *
+ * The construction gate takes the whole call — the shared log, query and slice
+ * record, plus the N resolved wirings — and this call reaches it ONCE, through
+ * `prepareProjection`, above the `Effect.forEach` below. So a call refused for ANY
+ * reason has forked NOTHING,
+ * not even the entries that were sound: not the collision, which is a property of
+ * the set, and not a degenerate `batchWindow` or an R2 violation on the last entry
+ * either. Half a call running is a worse state than none of it, and the pairing of N
+ * materialisations is one wiring decision.
+ *
+ * Two consequences of the gate judging a SET are worth stating rather than leaving
+ * to be met.
+ *
+ * A per-entry rung names its ENTRY. The gate prefixes its verdict with
+ * `materialisations[i]` where there is more than one entry, in the vocabulary the
+ * collision sentence already uses; this function's preamble names the PROJECTION and
+ * no partition, because under one `ProjectionId` the N keys are equal wherever no
+ * entry named a partition, so a partition never discriminated them.
+ *
+ * And the order is over RULES, not over entries. Where two entries break two
+ * DIFFERENT rules the earlier RULE wins whatever entry it is in — entry 0's
+ * degenerate `batchWindow` beside entry 1's illegal durability pairing reports entry
+ * 1's R2 fault, because R2 is the wider mistake wherever it sits. The gate's module
+ * doc argues that, and it is why the rules are judged rule-major rather than by
+ * walking the entries.
+ */
+const runProjections = spec => _effect.Effect.gen(function* () {
+  // ## RESOLVE — everything the gate has to judge, and every figure that runs
+  //
+  // Each entry's key and its five defaulted figures, through the same pure
+  // `resolveProjection` a single wiring goes through. Resolved here and carried,
+  // rather than derived twice: the gate below judges these values and the pipelines
+  // further down run from these same values, so what was checked cannot differ from
+  // what runs.
+  //
+  // Built as an EXPLICIT literal rather than by spreading the `Materialisation`,
+  // so every field on an entry has exactly one meaning and nothing dead rides
+  // along. A spread would carry the caller's `store` and `partition` into a record
+  // that already holds the BOUND view (from the resolve step) and the UNBOUND port
+  // under `cursorIdentity` — two names for one reference, one name for a different
+  // one, and a `partition` nothing downstream reads because `key` has absorbed it.
+  // That is a near-miss of the very hazard `cursorIdentity` was renamed to close.
+  //
+  // `cursorIdentity` is the UNBOUND port here, which is the last surface at which
+  // sameness is askable — `forKey` returns a fresh literal per call and does not
+  // expose what it closed over, so two bound views are never equal even over one
+  // store. `runProjection` passes its bound view instead, which is free at an arity
+  // where the rung cannot fire. `MaterialisationWiring`'s doc owns that argument.
+  const entries = _effect.Array.map(spec.materialisations, materialisation => {
+    const key = (0, _ProjectionStore.checkpointKey)(spec.projection, materialisation.partition);
+    return {
+      ...(0, _ProjectionRunner.resolveProjection)((0, _ProjectionStore.forKey)(materialisation.store, key), materialisation.options),
+      cursorIdentity: materialisation.store,
+      apply: materialisation.apply,
+      options: materialisation.options
+    };
+  });
+  // ## PREPARE — the log's durability, the merged query, the gate, the decode
+  //
+  // The shared middle, and the same call `runProjection` makes with a singleton.
+  // It reads the LOG's half of R2 from context — once for the call, because it IS
+  // one fact about one log — composes the ONE query the N subscriptions share,
+  // judges all five rungs over the whole entry list, and only then builds the ONE
+  // decode stage the N pipelines share. All of it above the `Effect.forEach` below,
+  // so a refused call has forked nothing.
+  //
+  // The order of the last two steps is `prepareProjection`'s to own, and it is why
+  // `decodeSlices` is not simply hoisted beside the composition: a record wrong in
+  // the codec's way AND in one of the gate's must meet the gate's sentence.
+  //
+  // The preamble is this function's own half of the defect message: the PROJECTION
+  // and no partition, because under one `ProjectionId` the N keys are equal wherever
+  // no entry named one, so a partition never discriminated them. The gate prefixes
+  // the entry index itself, where there is a set to index into.
+  const prepared = yield* (0, _ProjectionRunner.prepareProjection)(spec.slices, entries, `runProjections: invalid wiring for projection '${spec.projection}'`);
+  // ## FORK — one runner per entry, SEQUENTIALLY
+  //
+  // No `concurrency` option, deliberately. `buildAndFork` returns as soon as its
+  // daemon is forked into this scope, so it does no waiting for a concurrent pass
+  // to overlap: concurrency would buy nothing and would cost the returned ORDER,
+  // which is what lets a caller pair a runner with the entry it maintains. The
+  // daemons themselves run concurrently regardless — that is what forking them is.
+  //
+  // A runner naming its own bound cursor does not make that order redundant. The
+  // entry hands over an UNBOUND port and `forKey` deliberately does not expose what
+  // it closed over, so nothing a caller still holds can be compared against
+  // `runners[i].store` to recover which entry it came from. The order is the only
+  // statement of that pairing, and it is why this fold stays sequential.
+  //
+  // Each entry reaches the SAME build step a single wiring reaches, with the same
+  // shared query and the same shared decode stage, so the N pipelines differ in
+  // nothing but their store, their `apply` and their tuning.
+  return yield* _effect.Effect.forEach(entries, entry => (0, _ProjectionRunner.buildAndFork)(entry, {
+    query: prepared.query,
+    decode: prepared.decode,
+    // THE one assertion in this function, and the reason the requirement
+    // channel declared above is checked rather than wished for. Inside the
+    // body an entry is known only by its constraint, so this `apply` reads as
+    // `Effect<void, unknown, unknown>`; naming the alias the return type
+    // already names is what carries the entries' real requirement through
+    // `buildAndFork`, where a wildcard bound would instead absorb the lot and
+    // leave every member of that union unverified. It is narrow on purpose —
+    // `entry.apply` alone, to one expression written in one other place —
+    // and it cannot be dropped: without it the module does not compile.
+    // `MaterialisationAny` owns the mechanic, `MaterialisedProjection` what
+    // the compiler is being asked to take on trust.
+    apply: entry.apply,
+    options: entry.options
+  }));
+});
+exports.runProjections = runProjections;
+//# sourceMappingURL=runProjections.js.map

package/dist/cjs/runProjections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runProjections.js","names":["_effect","require","_ProjectionRunner","_ProjectionStore","runProjections","spec","Effect","gen","entries","Arr","map","materialisations","materialisation","key","checkpointKey","projection","partition","resolveProjection","forKey","store","options","cursorIdentity","apply","prepared","prepareProjection","slices","forEach","entry","buildAndFork","query","decode","exports"],"sources":["../../src/runProjections.ts"],"sourcesContent":[null],"mappings":";;;;;;AA8FA,IAAAA,OAAA,GAAAC,OAAA;AAEA,IAAAC,iBAAA,GAAAD,OAAA;AAOA,IAAAE,gBAAA,GAAAF,OAAA;AAuWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDO,MAAMG,cAAc,GAIzBC,IAAmC,IAWnCC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,MAAMC,OAAO,GAAGC,aAAG,CAACC,GAAG,CAACL,IAAI,CAACM,gBAAgB,EAAGC,eAAe,IAAI;IACjE,MAAMC,GAAG,GAAG,IAAAC,8BAAa,EAACT,IAAI,CAACU,UAAU,EAAEH,eAAe,CAACI,SAAS,CAAC;IACrE,OAAO;MACL,GAAG,IAAAC,mCAAiB,EAClB,IAAAC,uBAAM,EAACN,eAAe,CAACO,KAAK,EAAEN,GAAG,CAAC,EAClCD,eAAe,CAACQ,OAAO,CACxB;MACDC,cAAc,EAAET,eAAe,CAACO,KAAK;MACrCG,KAAK,EAAEV,eAAe,CAACU,KAAK;MAC5BF,OAAO,EAAER,eAAe,CAACQ;KAC1B;EACH,CAAC,CAAC;EAEF;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,MAAMG,QAAQ,GAAG,OAAO,IAAAC,mCAAiB,EACvCnB,IAAI,CAACoB,MAAM,EACXjB,OAAO,EACP,kDAAkDH,IAAI,CAACU,UAAU,GAAG,CACrE;EAED;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,OAAO,OAAOT,cAAM,CAACoB,OAAO,CAAClB,OAAO,EAAGmB,KAAK,IAC1C,IAAAC,8BAAY,EAACD,KAAK,EAAE;IAClBE,KAAK,EAAEN,QAAQ,CAACM,KAAK;IACrBC,MAAM,EAAEP,QAAQ,CAACO,MAAM;IACvB;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACAR,KAAK,EAAEK,KAAK,CAACL,KAEgD;IAC7DF,OAAO,EAAEO,KAAK,CAACP;GAChB,CAAC,CACH;AACH,CAAC,CAAC;AAAAW,OAAA,CAAA3B,cAAA,GAAAA,cAAA","ignoreList":[]}