@cosmicdrift/kumiko-framework 0.158.2 → 0.160.0

package/src/engine/types/projection.ts

@@ -1,165 +1,2 @@
-import type { DbRunner } from "../../db/connection";
-import type { TableColumns } from "../../db/dialect";
-import type { StoredEvent } from "../../event-store/event-store";
-import type { MultiStreamApplyContext } from "../../pipeline/multi-stream-apply-context";
-import type { RunIn } from "./config";
-import type { EntityDefinition } from "./fields";
-
-// Drizzle pgTable shape — projections hand their table through to apply() so
-// user code writes upserts/updates directly instead of going through a
-// framework-managed state reducer. Using Drizzle's own `PgTableWithColumns<any>`
-// (re-exported as TableColumns) keeps typing honest: drizzle's typed paths work
-// inside apply(), but the column union is erased so framework code doesn't need
-// to know the schema shape of every user table.
-// biome-ignore lint/suspicious/noExplicitAny: Drizzle's PgTable generic needs a concrete row shape; we erase it on purpose because the framework does not know user-defined column types.
-export type ProjectionTable = TableColumns<any>;
-
-// Single-stream projection apply: runs inline in the write-TX of the event
-// it projects. Gets the event, the TX-scoped DbRunner, and the projection's
-// own `table` (already erased to ProjectionTable). Write through THAT table —
-// it is the only ES-blessed write into a managed projection outside the
-// executor, and it is reachable only here (an arbitrary handler has no such
-// arg), so the write-brand cannot be bypassed by closing over the branded
-// table constant. Inline projections must not spawn further events (no ctx)
-// because they run inside the command's transaction and the framework
-// guarantees a single commit boundary per command.
-//
-// Generic über payload-shape. Default = Record<string, unknown> behält
-// rückwärtskompatibles Verhalten; Konkrete Apply-Handler annotieren
-// `SingleStreamApplyFn<MyPayload>` für typed event.payload-Access. Der
-// `table`-Param ist additiv — 2-arg-Applies (event, tx) bleiben gültig.
-export type SingleStreamApplyFn<TPayload = Record<string, unknown>> = (
-  event: StoredEvent<TPayload>,
-  tx: DbRunner,
-  table: ProjectionTable,
-) => Promise<void>;
-
-// Multi-stream projection apply: runs asynchronously via the event-dispatcher
-// with its own cursor. Gets the event, tx, and a ctx surface for emitting
-// follow-up events (saga / process-manager pattern). ctx.appendEvent +
-// ctx.loadAggregate are the Marten-equivalent of IProjectionSession — write
-// cross-aggregate reactions here, not in single-stream projections.
-export type MultiStreamApplyFn<TPayload = Record<string, unknown>> = (
-  event: StoredEvent<TPayload>,
-  tx: DbRunner,
-  ctx: MultiStreamApplyContext,
-) => Promise<void>;
-
-export type ProjectionDefinition = {
-  readonly name: string;
-  // One or more entity names whose events feed this projection. Event-types
-  // are matched in `apply` (e.g. "unit.created") — `source` is only used to
-  // index projections so the executor doesn't scan all projections on every
-  // write.
-  readonly source: string | readonly string[];
-  // Additional aggregate-types whose events the rebuild replay must include
-  // beyond `source`. Fed by r.extendEntityProjection — an extension can react
-  // to events on foreign streams (e.g. "field-definition") while `source`
-  // keeps meaning "the owning entity" for consumers like soft-delete-cleanup.
-  readonly extraSources?: readonly string[];
-  // Drizzle-table the projection materializes into. User owns the schema —
-  // framework just guarantees the TX and event delivery.
-  readonly table: ProjectionTable;
-  // Optional: the EntityDefinition the table was built from, for projections
-  // without an r.entity registration — lets boot-time GDPR guards see
-  // pii/tenantOwned fields that feature.entities (r.entity-only) would miss.
-  readonly entity?: EntityDefinition;
-  // Keyed by fully-qualified event type ("<aggregate>.<verb>", e.g. "unit.created").
-  // Missing keys are silently skipped — a projection declares only the events it
-  // cares about.
-  readonly apply: Readonly<Record<string, SingleStreamApplyFn>>;
-  // Auto-registered projection (one per r.entity) that exists ONLY to
-  // make rebuildProjection work for entity-tables. Live writes go through
-  // the EventStoreExecutor directly — firing the implicit apply inline
-  // would double-write into the same table. The inline-projection-runner
-  // skips entries with this flag; rebuildProjection treats them
-  // identically to explicit projections.
-  readonly isImplicit?: boolean;
-};
-
-// Extension merged into an entity's implicit projection at registry build.
-// Lets a bundled feature that writes into the HOST entity's table via events
-// (custom-fields pattern) hook those event types into the entity's rebuild
-// replay — without it, a rebuild resets everything the extension wrote.
-// Live delivery stays with the extension's own MSP: implicit projections are
-// skipped by the inline runner, so the apply here runs ONLY during rebuild.
-export type EntityProjectionExtension = {
-  // Aggregate-types beyond the entity's own stream whose events the rebuild
-  // must scan (e.g. "field-definition"). Omit when all extension events are
-  // appended on the host entity's stream.
-  readonly sources?: readonly string[];
-  // Keyed by fully-qualified event type. Must not collide with the entity's
-  // built-in lifecycle applies (<entity>.created/updated/...) or another
-  // extension — collisions fail at boot.
-  readonly apply: Readonly<Record<string, SingleStreamApplyFn>>;
-};
-
-// Per-lifecycle error policy for a MultiStreamProjection. Mirrors Marten's
-// Projections.Errors / Projections.RebuildErrors split — a projection can
-// be lenient during steady-state delivery but strict during rebuild (or
-// vice versa).
-export type MspErrorPolicy = {
-  // When the apply handler throws: log the error, advance the cursor past
-  // the offending event, and keep delivering. Default false — current
-  // strict behaviour: retry up to maxAttempts, then mark the consumer
-  // status="dead" and pause delivery. Use for best-effort sinks
-  // (notifications, webhooks) where a single bad event should not stall
-  // the whole consumer.
-  readonly skipApplyErrors?: boolean;
-};
-
-export type MspErrorMode = {
-  // Applied during steady-state dispatcher delivery.
-  readonly continuous?: MspErrorPolicy;
-  // Applied during rebuildProjection() / backfill passes. When omitted,
-  // rebuild inherits continuous — explicit override common for "strict
-  // during rebuild, lenient in production" patterns.
-  readonly rebuild?: MspErrorPolicy;
-};
-
-// Marten-style MultiStreamProjection: aggregates events from many streams
-// into one cross-cutting read-model. Unlike ProjectionDefinition (single-
-// source, inline in the write-TX), an MSP is ASYNC — the event-dispatcher
-// picks events off the log via its own cursor. Handlers MUST be idempotent
-// because the dispatcher guarantees at-least-once delivery.
-//
-// Use for Sagas / process managers, customer-centric views that span
-// multiple aggregate types, cross-feature aggregations, audit logs. With
-// `table` omitted, the MSP becomes a pure side-effect consumer — sending
-// notifications, posting webhooks, updating an external system. Marten's
-// equivalent of a subscription / event listener, without a separate API.
-export type MultiStreamProjectionDefinition = {
-  readonly name: string;
-  // Optional: omit for side-effect-only handlers (notifications, external
-  // system sync). When present, setupTestStack auto-pushes the table.
-  readonly table?: ProjectionTable;
-  // Keyed by fully-qualified event type. Unlike a single-stream projection,
-  // there is no source-entity hint — the MSP declares the event types it
-  // cares about directly. Extract the identity/grouping key inside the
-  // apply handler from the event payload.
-  readonly apply: Readonly<Record<string, MultiStreamApplyFn>>;
-  // How the dispatcher handles apply-throws. Default strict (retry + dead).
-  readonly errorMode?: MspErrorMode;
-  // Which deploy-lane runs this MSP's dispatcher. Default "worker". MSPs
-  // share a single consumer-row per MSP name with SKIP LOCKED, so "both"
-  // is safe semantically (API + Worker race for each event; exactly one
-  // wins). Use "api" for MSPs that need in-process state on the API
-  // (rare); use "both" only when genuinely load-balancing is helpful.
-  readonly runIn?: RunIn;
-  // Delivery semantics across multi-instance deploys:
-  //   "shared"       (default) — one cursor across all dispatcher instances,
-  //                   SKIP LOCKED serialises; each event delivered exactly
-  //                   once globally. The right choice for side-effects with
-  //                   any downstream state: notifications, external APIs,
-  //                   projection tables, audit rows.
-  //   "per-instance" — one cursor PER dispatcher instance, so every process
-  //                   delivers every event. Required for push-to-local-
-  //                   subscribers (SSE, in-memory caches): a split-deploy
-  //                   where API instance B emits an event that API instance
-  //                   A's clients also need to see. Handler MUST be
-  //                   side-effect-free relative to the DB — it only reaches
-  //                   in-process structures — otherwise each instance
-  //                   writes duplicate rows. Misuse = duplicated side
-  //                   effects, not a safety property.
-  readonly delivery?: "shared" | "per-instance";
-};
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/projection";

package/src/engine/types/relations.ts

@@ -1,51 +1 @@
-import type { OnDeleteStrategy } from "../constants";
-
-// --- Relations ---
-
-export type BelongsToRelation = {
-  readonly type: "belongsTo";
-  readonly target: string;
-  readonly foreignKey: string;
-  readonly searchInclude?: readonly string[];
-  // onDelete is declared on the parent-side (hasMany / manyToMany) because
-  // that's where the "what happens to my children?" decision lives. A
-  // belongsTo node just points at a parent — the parent's onDelete drives
-  // the cleanup.
-};
-
-export type HasManyRelation = {
-  readonly type: "hasMany";
-  readonly target: string;
-  readonly foreignKey: string;
-  readonly onDelete?: OnDeleteStrategy;
-  // When true, a nested payload under this relation's key (e.g.
-  // `{ tasks: [{ ... }] }` on a `project:create` write) is auto-expanded
-  // into child writes: parent first, then one child-write per entry with
-  // the foreign key set to the parent's new id — all in the same TX.
-  // Opt-in (default false) so legacy hasMany relations that were declared
-  // purely for cascade-delete or UI-nav semantics don't silently gain a
-  // client-writable path. Children are never inferred from payload-shape
-  // alone; only relations with this flag unlock nested-write.
-  //
-  // Scope v1: depth=1, create-only, hasMany-only. Update-nested,
-  // delete-nested, and belongsTo/m2m auto-expansion are explicit future
-  // work — when they arrive, they'll take the same flag so the opt-in
-  // stays a single, consistent surface.
-  readonly nestedWrite?: boolean;
-};
-
-export type ManyToManyRelation = {
-  readonly type: "manyToMany";
-  readonly target: string;
-  readonly through: {
-    readonly table: string;
-    readonly sourceKey: string;
-    readonly targetKey: string;
-  };
-  readonly searchInclude?: readonly string[];
-  readonly onDelete?: OnDeleteStrategy;
-};
-
-export type RelationDefinition = BelongsToRelation | HasManyRelation | ManyToManyRelation;
-
-export type EntityRelations = Readonly<Record<string, RelationDefinition>>;
+export * from "@cosmicdrift/kumiko-types/relations";