@walkeros/collector 4.6.0 → 4.7.0-next-1790187973605

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @walkeros/collector
 
+## 4.7.0-next-1790187973605
+
+### Minor Changes
+
+- f5a1cfd: New `collector.next`: a transformer chain that runs once per event,
+  before the event is handed to the destinations. Everything it produces reaches
+  every destination, and a `stop` in it drops the event for all of them;
+  per-destination filtering stays on `destination.before`. The explorer flow map
+  draws this chain, and the MCP guidance describes it.
+- f5a1cfd: Inside an array, a transformer's own `next` now runs right after it,
+  then the array continues. `many` works in every chain field: each match
+  becomes its own copy with a derived `event.id` that finishes the rest of the
+  path. Unknown transformer ids log a warning and the chain continues.
+  `@walkeros/collector` no longer exports `walkChain` or
+  `extractTransformerNextMap`.
+- f5a1cfd: Routes can drop an event with `{ stop: true }`, optionally gated by
+  `match`, in every chain field. A route `match` now reads `{ ingest, event }`
+  and resolves only when the event reaches it, so it sees values earlier steps
+  loaded. `getNextSteps(spec, root)` now requires that root and returns
+  `NextSteps`; the new `getRouteGraph` lists every branch.
+- 2aebc53: `state` paths now resolve against `{ event, ingest }` and need an
+  `event.` or `ingest.` prefix, so a store can be keyed by request context. A
+  `get` can write into `ingest`, keeping the value off the event. An
+  unresolvable key logs a warning instead of failing silently.
+  `buildCacheContext` is renamed `createMappingRoot`.
+
+### Patch Changes
+
+- 2aebc53: A transformer whose `push` throws still stops the chain and drops the
+  event, and is now also counted in `status.failed`, so diagnostics and health
+  checks show the failure instead of only a log line.
+- Updated dependencies [57788bc]
+- Updated dependencies [f5a1cfd]
+- Updated dependencies [ef02916]
+- Updated dependencies [ef02916]
+- Updated dependencies [2aebc53]
+- Updated dependencies [f5a1cfd]
+- Updated dependencies [f5a1cfd]
+- Updated dependencies [2aebc53]
+- Updated dependencies [8f8aea6]
+- Updated dependencies [2aebc53]
+- Updated dependencies [2aebc53]
+  - @walkeros/core@4.7.0-next-1790187973605
+
+## 4.6.1
+
+### Patch Changes
+
+- @walkeros/core@4.6.1
+
 ## 4.6.0
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as _walkeros_core from '@walkeros/core';
-import { Collector, WalkerOS, Elb, Mapping, Destination, On, StepKind, Logger, Context as Context$1, BreakerState, Ingest, Source, Transformer, Simulation, CompiledCache, Store } from '@walkeros/core';
+import { Collector, WalkerOS, Elb, Mapping, Destination, On, Transformer, RespondFn, Ingest, StepKind, Logger, Context as Context$1, BreakerState, Source, ChainContinuation, Simulation, CompiledCache, Store } from '@walkeros/core';
 
 interface RunState {
     consent?: WalkerOS.Consent;
@@ -73,6 +73,38 @@ declare function processConsent(collector: Collector.Instance, data: WalkerOS.Co
     update: WalkerOS.Consent;
 };
 
+/** What `collector.next` hands to the destination fan-out. */
+interface CollectorNextResult {
+    /**
+     * Every finished copy, in order, with its own ingest; each event is
+     * completed to a full event. One copy without a fork, one per surviving
+     * fork after a `many` or a `Result[]` return, and none when the chain
+     * dropped or halted the event.
+     */
+    copies: Transformer.ChainCopy<WalkerOS.Event>[];
+    /** The respond in scope after the chain (a wrapped one if the chain set it). */
+    respond?: RespondFn;
+    /** Set when a route stop or a transformer ended every copy. */
+    dropped?: true;
+}
+/**
+ * Runs the collector's own chain (`collector.config.next`) for one completed
+ * event, through the one chain runner. Called once per event by
+ * `pushToDestinations`, before the event enters `collector.queue` and the
+ * destination fan-out, so consent replay and late-destination backfill
+ * deliver post-chain events and never run it again.
+ *
+ * A drop (route `stop` or a transformer returning `false`) on every copy
+ * emits one `collector.push` `skip` / `dropped` record and counts the event
+ * in; a `cache.stop` HIT halts delivery without a drop record, as at
+ * `source.next`.
+ */
+declare function runCollectorNext(collector: Collector.Instance, event: WalkerOS.Event, meta?: {
+    id?: string;
+    ingest?: Ingest;
+    respond?: RespondFn;
+}): Promise<CollectorNextResult>;
+
 declare function startFlow<ElbPush extends Elb.Fn = Elb.Fn>(initConfig?: Collector.InitConfig): Promise<StartFlow<ElbPush>>;
 
 /**
@@ -192,6 +224,11 @@ declare function addDestination(collector: Collector.Instance, data: Destination
 /**
  * Pushes an event to all or a subset of destinations.
  *
+ * A completed event first runs the collector's own chain
+ * (`collector.config.next`), once, and every copy it hands back is delivered.
+ * A flush call (no event) delivers what the destinations have queued and
+ * never runs the chain: queued events are already post-chain.
+ *
  * @param collector - The walkerOS collector instance.
  * @param event - The event to push.
  * @param meta - Optional metadata with id and ingest.
@@ -201,7 +238,7 @@ declare function addDestination(collector: Collector.Instance, data: Destination
 declare function pushToDestinations(collector: Collector.Instance, event?: WalkerOS.Event, meta?: {
     id?: string;
     ingest?: Ingest;
-    respond?: _walkeros_core.RespondFn;
+    respond?: RespondFn;
 }, destinations?: Collector.Destinations): Promise<Elb.PushResult>;
 declare function destinationInit<Destination extends Destination.Instance>(collector: Collector.Instance, destination: Destination, destId: string, allowed?: boolean): Promise<boolean>;
 /**
@@ -265,13 +302,21 @@ declare function commonHandleCommand(collector: Collector.Instance, action: stri
  */
 declare function prepareEvent(collector: Collector.Instance, event: WalkerOS.DeepPartialEvent): WalkerOS.PartialEvent;
 /**
- * Creates a full event from a partial event.
+ * Creates a full event from a partial event, floored with the collector's
+ * current state (globals, user, consent).
  *
  * @param collector The walkerOS collector instance.
  * @param partialEvent The partial event to transform.
  * @returns The full event.
  */
 declare function createEvent(collector: Collector.Instance, partialEvent: WalkerOS.PartialEvent, ingest?: Ingest): WalkerOS.Event;
+/**
+ * Completes an event that was already created and then edited by a chain
+ * (`collector.next`): fills only the fields that are missing, never floors
+ * globals, user or consent again, so a step that removed one keeps it
+ * removed.
+ */
+declare function completeEvent(collector: Collector.Instance, event: WalkerOS.DeepPartialEvent, ingest?: Ingest): WalkerOS.Event;
 /**
  * Enriches a partial event into a full event by applying the collector defaults
  * (`prepareEvent`) and then building the complete event (`createEvent`). This is
@@ -440,46 +485,6 @@ declare function initSource(collector: Collector.Instance, sourceId: string, sou
  */
 declare function initSources(collector: Collector.Instance, sources?: Source.InitSources): Promise<Collector.Sources>;
 
-/**
- * Extracts transformer next configuration for chain walking.
- * Maps transformer instances to their config.next values.
- *
- * This is the single source of truth for extracting chain links.
- * Used by both source.ts (pre-collector chains) and destination.ts (post-collector chains).
- *
- * @param transformers - Map of transformer instances
- * @returns Map of transformer IDs to their next configuration
- */
-declare function extractTransformerNextMap(transformers: Transformer.Transformers): Record<string, {
-    next?: string | string[];
-}>;
-/**
- * Walks a transformer chain starting from a given transformer ID.
- * Returns ordered array of transformer IDs in the chain.
- *
- * Used for on-demand chain resolution:
- * - Called from destination.ts with destination.config.before
- * - Called from source.ts with source.config.next
- *
- * @param startId - First transformer in chain, or explicit array of transformer IDs
- * @param transformers - Available transformer configs with optional `next` field
- * @returns Ordered array of transformer IDs to execute
- *
- * @example
- * // Single transformer
- * walkChain('redact', { redact: {} }) // ['redact']
- *
- * @example
- * // Chain via next
- * walkChain('a', { a: { next: 'b' }, b: { next: 'c' }, c: {} }) // ['a', 'b', 'c']
- *
- * @example
- * // Explicit array
- * walkChain(['x', 'y'], {}) // ['x', 'y']
- */
-declare function walkChain(startId: string | string[] | undefined, transformers?: Record<string, {
-    next?: string | string[];
-}>): string[];
 /**
  * Initializes a transformer if it hasn't been initialized yet.
  * Called lazily before first push.
@@ -502,16 +507,27 @@ declare function transformerInit(collector: Collector.Instance, transformer: Tra
  */
 declare function transformerPush(collector: Collector.Instance, transformer: Transformer.Instance, transformerId: string, event: WalkerOS.DeepPartialEvent, ingest?: Ingest, respond?: _walkeros_core.RespondFn): Promise<Transformer.Result | Transformer.Result[] | false | void>;
 /**
- * Runs an event through a chain of transformers.
+ * Runs an event through a chain: the one chain runner.
  *
  * @param collector - The collector instance with transformers
  * @param transformers - Map of transformer instances
- * @param chain - Ordered array of transformer IDs to execute
+ * @param start - The route to run (a chain field such as `source.next`), or
+ *   a continuation of one; `undefined` runs nothing
  * @param event - The event to process
  * @param ingest - Mutable ingest context flowing through the pipeline
- * @returns The processed event or null if chain was stopped
+ * @param respond - The respond function in scope
+ * @param chainContext - Chain path (e.g. `destination.ga4.before`), recorded
+ *   as `ingest._meta.chainPath` and keying `chainMocks`
+ * @returns Every finished copy with its own ingest (`copies`, empty when
+ *   dropped or stopped) and the respond in scope afterwards
+ */
+declare function runTransformerChain(collector: Collector.Instance, transformers: Transformer.Transformers, start: Transformer.Route | ChainContinuation | undefined, event: WalkerOS.DeepPartialEvent, ingest?: Ingest, respond?: RespondFn, chainContext?: string): Promise<Transformer.ChainResult>;
+/**
+ * Runs a transformer's `before` chain: the one implementation, used by the
+ * chain runner for every member and by the CLI simulation. A `stop` that
+ * the before route itself resolved is attributed to the transformer.
  */
-declare function runTransformerChain(collector: Collector.Instance, transformers: Transformer.Transformers, chain: string[], event: WalkerOS.DeepPartialEvent, ingest?: Ingest, respond?: _walkeros_core.RespondFn, chainContext?: string): Promise<Transformer.ChainResult>;
+declare function runTransformerBefore(collector: Collector.Instance, transformers: Transformer.Transformers, transformerId: string, event: WalkerOS.DeepPartialEvent, ingest?: Ingest, respond?: RespondFn, chainContext?: string): Promise<Transformer.ChainResult>;
 
 interface WrapResult {
     /** Env with tracked paths wrapped by recording functions */
@@ -548,4 +564,4 @@ declare function wrapEnv(env: Record<string, unknown> & {
  */
 declare function getCacheStore(compiled: CompiledCache, collector: Collector.Instance): Store.Instance | undefined;
 
-export { type BreakerConfig, code as Code, type CommandTypes, Commands, Const, type CreateCollector, DEFAULT_BREAKER_COOLDOWN_MS, DEFAULT_BREAKER_THRESHOLD, DEFAULT_DLQ_MAX, type HandleCommandFn, type RunState, type StartFlow, type StepOutcome, type StorageType, addDestination, buildReportError, bumpDropped, callDestinationOn, commonHandleCommand, createEvent, createPush, createPushResult, destinationInit, destinationPush, enrichEvent, ensureDestStatus, enterCascade, errorMeta, extractTransformerNextMap, fireCallbacks, flushSourceQueueOn, getCacheStore, initDestinations, initSource, initSources, isBreakerProbePermitted, isRequireSatisfied, isSourceStarted, isStateDelivery, isStatePresent, mergeEnvironments, on, onApply, prepareEvent, processConsent, pushToDestinations, redeliverStateAtRun, registerDestination, resolveBreakerConfig, runCollector, runTransformerChain, setMark, shouldDeliver, startFlow, transformerInit, transformerPush, walkChain, wrapEnv };
+export { type BreakerConfig, code as Code, type CollectorNextResult, type CommandTypes, Commands, Const, type CreateCollector, DEFAULT_BREAKER_COOLDOWN_MS, DEFAULT_BREAKER_THRESHOLD, DEFAULT_DLQ_MAX, type HandleCommandFn, type RunState, type StartFlow, type StepOutcome, type StorageType, addDestination, buildReportError, bumpDropped, callDestinationOn, commonHandleCommand, completeEvent, createEvent, createPush, createPushResult, destinationInit, destinationPush, enrichEvent, ensureDestStatus, enterCascade, errorMeta, fireCallbacks, flushSourceQueueOn, getCacheStore, initDestinations, initSource, initSources, isBreakerProbePermitted, isRequireSatisfied, isSourceStarted, isStateDelivery, isStatePresent, mergeEnvironments, on, onApply, prepareEvent, processConsent, pushToDestinations, redeliverStateAtRun, registerDestination, resolveBreakerConfig, runCollector, runCollectorNext, runTransformerBefore, runTransformerChain, setMark, shouldDeliver, startFlow, transformerInit, transformerPush, wrapEnv };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _walkeros_core from '@walkeros/core';
-import { Collector, WalkerOS, Elb, Mapping, Destination, On, StepKind, Logger, Context as Context$1, BreakerState, Ingest, Source, Transformer, Simulation, CompiledCache, Store } from '@walkeros/core';
+import { Collector, WalkerOS, Elb, Mapping, Destination, On, Transformer, RespondFn, Ingest, StepKind, Logger, Context as Context$1, BreakerState, Source, ChainContinuation, Simulation, CompiledCache, Store } from '@walkeros/core';
 
 interface RunState {
     consent?: WalkerOS.Consent;
@@ -73,6 +73,38 @@ declare function processConsent(collector: Collector.Instance, data: WalkerOS.Co
     update: WalkerOS.Consent;
 };
 
+/** What `collector.next` hands to the destination fan-out. */
+interface CollectorNextResult {
+    /**
+     * Every finished copy, in order, with its own ingest; each event is
+     * completed to a full event. One copy without a fork, one per surviving
+     * fork after a `many` or a `Result[]` return, and none when the chain
+     * dropped or halted the event.
+     */
+    copies: Transformer.ChainCopy<WalkerOS.Event>[];
+    /** The respond in scope after the chain (a wrapped one if the chain set it). */
+    respond?: RespondFn;
+    /** Set when a route stop or a transformer ended every copy. */
+    dropped?: true;
+}
+/**
+ * Runs the collector's own chain (`collector.config.next`) for one completed
+ * event, through the one chain runner. Called once per event by
+ * `pushToDestinations`, before the event enters `collector.queue` and the
+ * destination fan-out, so consent replay and late-destination backfill
+ * deliver post-chain events and never run it again.
+ *
+ * A drop (route `stop` or a transformer returning `false`) on every copy
+ * emits one `collector.push` `skip` / `dropped` record and counts the event
+ * in; a `cache.stop` HIT halts delivery without a drop record, as at
+ * `source.next`.
+ */
+declare function runCollectorNext(collector: Collector.Instance, event: WalkerOS.Event, meta?: {
+    id?: string;
+    ingest?: Ingest;
+    respond?: RespondFn;
+}): Promise<CollectorNextResult>;
+
 declare function startFlow<ElbPush extends Elb.Fn = Elb.Fn>(initConfig?: Collector.InitConfig): Promise<StartFlow<ElbPush>>;
 
 /**
@@ -192,6 +224,11 @@ declare function addDestination(collector: Collector.Instance, data: Destination
 /**
  * Pushes an event to all or a subset of destinations.
  *
+ * A completed event first runs the collector's own chain
+ * (`collector.config.next`), once, and every copy it hands back is delivered.
+ * A flush call (no event) delivers what the destinations have queued and
+ * never runs the chain: queued events are already post-chain.
+ *
  * @param collector - The walkerOS collector instance.
  * @param event - The event to push.
  * @param meta - Optional metadata with id and ingest.
@@ -201,7 +238,7 @@ declare function addDestination(collector: Collector.Instance, data: Destination
 declare function pushToDestinations(collector: Collector.Instance, event?: WalkerOS.Event, meta?: {
     id?: string;
     ingest?: Ingest;
-    respond?: _walkeros_core.RespondFn;
+    respond?: RespondFn;
 }, destinations?: Collector.Destinations): Promise<Elb.PushResult>;
 declare function destinationInit<Destination extends Destination.Instance>(collector: Collector.Instance, destination: Destination, destId: string, allowed?: boolean): Promise<boolean>;
 /**
@@ -265,13 +302,21 @@ declare function commonHandleCommand(collector: Collector.Instance, action: stri
  */
 declare function prepareEvent(collector: Collector.Instance, event: WalkerOS.DeepPartialEvent): WalkerOS.PartialEvent;
 /**
- * Creates a full event from a partial event.
+ * Creates a full event from a partial event, floored with the collector's
+ * current state (globals, user, consent).
  *
  * @param collector The walkerOS collector instance.
  * @param partialEvent The partial event to transform.
  * @returns The full event.
  */
 declare function createEvent(collector: Collector.Instance, partialEvent: WalkerOS.PartialEvent, ingest?: Ingest): WalkerOS.Event;
+/**
+ * Completes an event that was already created and then edited by a chain
+ * (`collector.next`): fills only the fields that are missing, never floors
+ * globals, user or consent again, so a step that removed one keeps it
+ * removed.
+ */
+declare function completeEvent(collector: Collector.Instance, event: WalkerOS.DeepPartialEvent, ingest?: Ingest): WalkerOS.Event;
 /**
  * Enriches a partial event into a full event by applying the collector defaults
  * (`prepareEvent`) and then building the complete event (`createEvent`). This is
@@ -440,46 +485,6 @@ declare function initSource(collector: Collector.Instance, sourceId: string, sou
  */
 declare function initSources(collector: Collector.Instance, sources?: Source.InitSources): Promise<Collector.Sources>;
 
-/**
- * Extracts transformer next configuration for chain walking.
- * Maps transformer instances to their config.next values.
- *
- * This is the single source of truth for extracting chain links.
- * Used by both source.ts (pre-collector chains) and destination.ts (post-collector chains).
- *
- * @param transformers - Map of transformer instances
- * @returns Map of transformer IDs to their next configuration
- */
-declare function extractTransformerNextMap(transformers: Transformer.Transformers): Record<string, {
-    next?: string | string[];
-}>;
-/**
- * Walks a transformer chain starting from a given transformer ID.
- * Returns ordered array of transformer IDs in the chain.
- *
- * Used for on-demand chain resolution:
- * - Called from destination.ts with destination.config.before
- * - Called from source.ts with source.config.next
- *
- * @param startId - First transformer in chain, or explicit array of transformer IDs
- * @param transformers - Available transformer configs with optional `next` field
- * @returns Ordered array of transformer IDs to execute
- *
- * @example
- * // Single transformer
- * walkChain('redact', { redact: {} }) // ['redact']
- *
- * @example
- * // Chain via next
- * walkChain('a', { a: { next: 'b' }, b: { next: 'c' }, c: {} }) // ['a', 'b', 'c']
- *
- * @example
- * // Explicit array
- * walkChain(['x', 'y'], {}) // ['x', 'y']
- */
-declare function walkChain(startId: string | string[] | undefined, transformers?: Record<string, {
-    next?: string | string[];
-}>): string[];
 /**
  * Initializes a transformer if it hasn't been initialized yet.
  * Called lazily before first push.
@@ -502,16 +507,27 @@ declare function transformerInit(collector: Collector.Instance, transformer: Tra
  */
 declare function transformerPush(collector: Collector.Instance, transformer: Transformer.Instance, transformerId: string, event: WalkerOS.DeepPartialEvent, ingest?: Ingest, respond?: _walkeros_core.RespondFn): Promise<Transformer.Result | Transformer.Result[] | false | void>;
 /**
- * Runs an event through a chain of transformers.
+ * Runs an event through a chain: the one chain runner.
  *
  * @param collector - The collector instance with transformers
  * @param transformers - Map of transformer instances
- * @param chain - Ordered array of transformer IDs to execute
+ * @param start - The route to run (a chain field such as `source.next`), or
+ *   a continuation of one; `undefined` runs nothing
  * @param event - The event to process
  * @param ingest - Mutable ingest context flowing through the pipeline
- * @returns The processed event or null if chain was stopped
+ * @param respond - The respond function in scope
+ * @param chainContext - Chain path (e.g. `destination.ga4.before`), recorded
+ *   as `ingest._meta.chainPath` and keying `chainMocks`
+ * @returns Every finished copy with its own ingest (`copies`, empty when
+ *   dropped or stopped) and the respond in scope afterwards
+ */
+declare function runTransformerChain(collector: Collector.Instance, transformers: Transformer.Transformers, start: Transformer.Route | ChainContinuation | undefined, event: WalkerOS.DeepPartialEvent, ingest?: Ingest, respond?: RespondFn, chainContext?: string): Promise<Transformer.ChainResult>;
+/**
+ * Runs a transformer's `before` chain: the one implementation, used by the
+ * chain runner for every member and by the CLI simulation. A `stop` that
+ * the before route itself resolved is attributed to the transformer.
  */
-declare function runTransformerChain(collector: Collector.Instance, transformers: Transformer.Transformers, chain: string[], event: WalkerOS.DeepPartialEvent, ingest?: Ingest, respond?: _walkeros_core.RespondFn, chainContext?: string): Promise<Transformer.ChainResult>;
+declare function runTransformerBefore(collector: Collector.Instance, transformers: Transformer.Transformers, transformerId: string, event: WalkerOS.DeepPartialEvent, ingest?: Ingest, respond?: RespondFn, chainContext?: string): Promise<Transformer.ChainResult>;
 
 interface WrapResult {
     /** Env with tracked paths wrapped by recording functions */
@@ -548,4 +564,4 @@ declare function wrapEnv(env: Record<string, unknown> & {
  */
 declare function getCacheStore(compiled: CompiledCache, collector: Collector.Instance): Store.Instance | undefined;
 
-export { type BreakerConfig, code as Code, type CommandTypes, Commands, Const, type CreateCollector, DEFAULT_BREAKER_COOLDOWN_MS, DEFAULT_BREAKER_THRESHOLD, DEFAULT_DLQ_MAX, type HandleCommandFn, type RunState, type StartFlow, type StepOutcome, type StorageType, addDestination, buildReportError, bumpDropped, callDestinationOn, commonHandleCommand, createEvent, createPush, createPushResult, destinationInit, destinationPush, enrichEvent, ensureDestStatus, enterCascade, errorMeta, extractTransformerNextMap, fireCallbacks, flushSourceQueueOn, getCacheStore, initDestinations, initSource, initSources, isBreakerProbePermitted, isRequireSatisfied, isSourceStarted, isStateDelivery, isStatePresent, mergeEnvironments, on, onApply, prepareEvent, processConsent, pushToDestinations, redeliverStateAtRun, registerDestination, resolveBreakerConfig, runCollector, runTransformerChain, setMark, shouldDeliver, startFlow, transformerInit, transformerPush, walkChain, wrapEnv };
+export { type BreakerConfig, code as Code, type CollectorNextResult, type CommandTypes, Commands, Const, type CreateCollector, DEFAULT_BREAKER_COOLDOWN_MS, DEFAULT_BREAKER_THRESHOLD, DEFAULT_DLQ_MAX, type HandleCommandFn, type RunState, type StartFlow, type StepOutcome, type StorageType, addDestination, buildReportError, bumpDropped, callDestinationOn, commonHandleCommand, completeEvent, createEvent, createPush, createPushResult, destinationInit, destinationPush, enrichEvent, ensureDestStatus, enterCascade, errorMeta, fireCallbacks, flushSourceQueueOn, getCacheStore, initDestinations, initSource, initSources, isBreakerProbePermitted, isRequireSatisfied, isSourceStarted, isStateDelivery, isStatePresent, mergeEnvironments, on, onApply, prepareEvent, processConsent, pushToDestinations, redeliverStateAtRun, registerDestination, resolveBreakerConfig, runCollector, runCollectorNext, runTransformerBefore, runTransformerChain, setMark, shouldDeliver, startFlow, transformerInit, transformerPush, wrapEnv };