@walkeros/core 3.1.1 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,3 +1,117 @@
1
+ type MatchExpression = MatchCondition | {
2
+ and: MatchExpression[];
3
+ } | {
4
+ or: MatchExpression[];
5
+ };
6
+ interface MatchCondition {
7
+ key: string;
8
+ operator: MatchOperator;
9
+ value: string;
10
+ not?: boolean;
11
+ }
12
+ type MatchOperator = 'eq' | 'contains' | 'prefix' | 'suffix' | 'regex' | 'gt' | 'lt' | 'exists';
13
+ type CompiledMatcher = (context: Record<string, unknown>) => boolean;
14
+
15
+ type matcher_CompiledMatcher = CompiledMatcher;
16
+ type matcher_MatchCondition = MatchCondition;
17
+ type matcher_MatchExpression = MatchExpression;
18
+ type matcher_MatchOperator = MatchOperator;
19
+ declare namespace matcher {
20
+ export type { matcher_CompiledMatcher as CompiledMatcher, matcher_MatchCondition as MatchCondition, matcher_MatchExpression as MatchExpression, matcher_MatchOperator as MatchOperator };
21
+ }
22
+
23
+ /**
24
+ * Shared mapping configuration interface.
25
+ * Used by both Source.Config and Destination.Config.
26
+ */
27
+ interface Config$8<T = unknown> {
28
+ consent?: Consent;
29
+ data?: Value | Values;
30
+ mapping?: Rules<Rule<T>>;
31
+ policy?: Policy$1;
32
+ }
33
+ interface Policy$1 {
34
+ [key: string]: Value;
35
+ }
36
+ interface Rules<T = Rule> {
37
+ [entity: string]: Record<string, T | Array<T>> | undefined;
38
+ }
39
+ interface Rule<Settings = unknown> {
40
+ batch?: number;
41
+ batchFn?: (destination: Instance$5, collector: Instance$6) => void;
42
+ batched?: Batch<Settings>;
43
+ condition?: Condition;
44
+ consent?: Consent;
45
+ settings?: Settings;
46
+ data?: Data$1;
47
+ ignore?: boolean;
48
+ name?: string;
49
+ policy?: Policy$1;
50
+ }
51
+ interface Result$2 {
52
+ eventMapping?: Rule;
53
+ mappingKey?: string;
54
+ }
55
+ type Data$1 = Value | Values;
56
+ type Value = ValueType | Array<ValueType>;
57
+ type Values = Array<Value>;
58
+ type ValueType = string | ValueConfig;
59
+ interface ValueConfig {
60
+ condition?: Condition;
61
+ consent?: Consent;
62
+ fn?: Fn$3;
63
+ key?: string;
64
+ loop?: Loop;
65
+ map?: Map;
66
+ set?: Value[];
67
+ validate?: Validate;
68
+ value?: PropertyType;
69
+ }
70
+ type Condition = (value: DeepPartialEvent | unknown, mapping?: Value, collector?: Instance$6) => PromiseOrValue<boolean>;
71
+ type Fn$3 = (value: DeepPartialEvent | unknown, mapping: Value, options: Options$1) => PromiseOrValue<Property | unknown>;
72
+ type Loop = [Value, Value];
73
+ type Map = {
74
+ [key: string]: Value;
75
+ };
76
+ interface Options$1 {
77
+ consent?: Consent;
78
+ collector?: Instance$6;
79
+ props?: unknown;
80
+ }
81
+ type Validate = (value?: unknown) => PromiseOrValue<boolean>;
82
+
83
+ type mapping_Condition = Condition;
84
+ type mapping_Loop = Loop;
85
+ type mapping_Map = Map;
86
+ type mapping_Rule<Settings = unknown> = Rule<Settings>;
87
+ type mapping_Rules<T = Rule> = Rules<T>;
88
+ type mapping_Validate = Validate;
89
+ type mapping_Value = Value;
90
+ type mapping_ValueConfig = ValueConfig;
91
+ type mapping_ValueType = ValueType;
92
+ type mapping_Values = Values;
93
+ declare namespace mapping {
94
+ export type { mapping_Condition as Condition, Config$8 as Config, Data$1 as Data, Fn$3 as Fn, mapping_Loop as Loop, mapping_Map as Map, Options$1 as Options, Policy$1 as Policy, Result$2 as Result, mapping_Rule as Rule, mapping_Rules as Rules, mapping_Validate as Validate, mapping_Value as Value, mapping_ValueConfig as ValueConfig, mapping_ValueType as ValueType, mapping_Values as Values };
95
+ }
96
+
97
+ interface CacheRule {
98
+ match: MatchExpression | '*';
99
+ key: string[];
100
+ ttl: number;
101
+ update?: Record<string, Value>;
102
+ }
103
+ interface Cache {
104
+ full?: boolean;
105
+ store?: string;
106
+ rules: CacheRule[];
107
+ }
108
+
109
+ type cache_Cache = Cache;
110
+ type cache_CacheRule = CacheRule;
111
+ declare namespace cache {
112
+ export type { cache_Cache as Cache, cache_CacheRule as CacheRule };
113
+ }
114
+
1
115
  /**
2
116
  * Options for responding to an HTTP request.
3
117
  * Same interface for web and server — sources implement the handler.
@@ -25,10 +139,38 @@ type RespondFn = (options?: RespondOptions) => void;
25
139
  */
26
140
  declare function createRespond(sender: (options: RespondOptions) => void): RespondFn;
27
141
 
142
+ /**
143
+ * Metadata managed by the runtime. Do not overwrite from step code.
144
+ * The _ prefix signals "runtime-managed."
145
+ */
146
+ interface IngestMeta {
147
+ /** Number of steps this data has passed through. */
148
+ hops: number;
149
+ /** Ordered list of step IDs visited. path[0] is always the source ID. */
150
+ path: string[];
151
+ /** Current chain context, e.g., "destination.ga4.before" or "source.web.next". */
152
+ chainPath?: string;
153
+ }
154
+ /**
155
+ * Mutable shared context that accumulates knowledge as data flows through the graph.
156
+ *
157
+ * Event = strict schema (analytics data).
158
+ * Ingest = wild west (pipeline context).
159
+ *
160
+ * Any step can read and write arbitrary keys. The `_meta` section is
161
+ * managed by the runtime — increment hops and append to path before each step.
162
+ */
163
+ interface Ingest {
164
+ [key: string]: unknown;
165
+ _meta: IngestMeta;
166
+ }
167
+ /** Create a fresh Ingest for a new pipeline invocation. */
168
+ declare function createIngest(sourceId: string): Ingest;
169
+
28
170
  /**
29
171
  * Core collector configuration interface
30
172
  */
31
- interface Config$8 {
173
+ interface Config$7 {
32
174
  /** Whether to run collector automatically */
33
175
  run?: boolean;
34
176
  /** Version for event tagging */
@@ -38,12 +180,12 @@ interface Config$8 {
38
180
  /** Static session data even on a new run */
39
181
  sessionStatic: Partial<SessionData>;
40
182
  /** Logger configuration */
41
- logger?: Config$5;
183
+ logger?: Config$4;
42
184
  }
43
185
  /**
44
186
  * Initialization configuration that extends Config with initial state
45
187
  */
46
- interface InitConfig extends Partial<Config$8> {
188
+ interface InitConfig extends Partial<Config$7> {
47
189
  /** Initial consent state */
48
190
  consent?: Consent;
49
191
  /** Initial user data */
@@ -60,6 +202,8 @@ interface InitConfig extends Partial<Config$8> {
60
202
  stores?: InitStores;
61
203
  /** Initial custom properties */
62
204
  custom?: Properties;
205
+ /** Hooks for pipeline observation and interception */
206
+ hooks?: Functions;
63
207
  }
64
208
  interface SessionData extends Properties {
65
209
  isStart: boolean;
@@ -111,10 +255,12 @@ type CommandType = 'action' | 'config' | 'consent' | 'context' | 'destination' |
111
255
  */
112
256
  interface PushOptions {
113
257
  id?: string;
114
- ingest?: unknown;
258
+ ingest?: Ingest;
115
259
  respond?: RespondFn;
116
- mapping?: Config$4;
260
+ mapping?: Config$8;
117
261
  preChain?: string[];
262
+ include?: string[];
263
+ exclude?: string[];
118
264
  }
119
265
  /**
120
266
  * Push function signature - handles events only
@@ -126,9 +272,9 @@ interface PushFn$1 {
126
272
  * Command function signature - handles walker commands only
127
273
  */
128
274
  interface CommandFn {
129
- (command: 'config', config: Partial<Config$8>): Promise<PushResult>;
275
+ (command: 'config', config: Partial<Config$7>): Promise<PushResult>;
130
276
  (command: 'consent', consent: Consent): Promise<PushResult>;
131
- <T extends Types$4>(command: 'destination', destination: Init$3<T> | Instance$5<T>, config?: Config$7<T>): Promise<PushResult>;
277
+ <T extends Types$4>(command: 'destination', destination: Init$3<T> | Instance$5<T>, config?: Config$6<T>): Promise<PushResult>;
132
278
  <K extends keyof Functions>(command: 'hook', name: K, hookFn: Functions[K]): Promise<PushResult>;
133
279
  (command: 'on', type: Types$3, rules: SingleOrArray<Options>): Promise<PushResult>;
134
280
  (command: 'user', user: User): Promise<PushResult>;
@@ -144,7 +290,7 @@ interface Instance$6 {
144
290
  push: PushFn$1;
145
291
  command: CommandFn;
146
292
  allowed: boolean;
147
- config: Config$8;
293
+ config: Config$7;
148
294
  consent: Consent;
149
295
  count: number;
150
296
  custom: Properties;
@@ -180,7 +326,7 @@ type collector_SourceStatus = SourceStatus;
180
326
  type collector_Sources = Sources;
181
327
  type collector_Status = Status;
182
328
  declare namespace collector {
183
- export type { collector_CommandFn as CommandFn, collector_CommandType as CommandType, Config$8 as Config, collector_DestinationStatus as DestinationStatus, Destinations$1 as Destinations, collector_InitConfig as InitConfig, Instance$6 as Instance, PushFn$1 as PushFn, collector_PushOptions as PushOptions, collector_SessionData as SessionData, collector_SourceStatus as SourceStatus, collector_Sources as Sources, collector_Status as Status, Stores$1 as Stores, Transformers$1 as Transformers };
329
+ export type { collector_CommandFn as CommandFn, collector_CommandType as CommandType, Config$7 as Config, collector_DestinationStatus as DestinationStatus, Destinations$1 as Destinations, collector_InitConfig as InitConfig, Instance$6 as Instance, PushFn$1 as PushFn, collector_PushOptions as PushOptions, collector_SessionData as SessionData, collector_SourceStatus as SourceStatus, collector_Sources as Sources, collector_Status as Status, Stores$1 as Stores, Transformers$1 as Transformers };
184
330
  }
185
331
 
186
332
  /**
@@ -275,7 +421,7 @@ type Env$3<T extends TypesGeneric$3 = Types$4> = T['env'];
275
421
  */
276
422
  type TypesOf$3<I> = I extends Instance$5<infer T> ? T : never;
277
423
  interface Instance$5<T extends TypesGeneric$3 = Types$4> {
278
- config: Config$7<T>;
424
+ config: Config$6<T>;
279
425
  queuePush?: Events;
280
426
  queueOn?: Array<{
281
427
  type: Types$3;
@@ -289,9 +435,9 @@ interface Instance$5<T extends TypesGeneric$3 = Types$4> {
289
435
  push: PushFn<T>;
290
436
  pushBatch?: PushBatchFn<T>;
291
437
  on?: OnFn;
292
- destroy?: DestroyFn<Config$7<T>, Env$3<T>>;
438
+ destroy?: DestroyFn<Config$6<T>, Env$3<T>>;
293
439
  }
294
- interface Config$7<T extends TypesGeneric$3 = Types$4> {
440
+ interface Config$6<T extends TypesGeneric$3 = Types$4> {
295
441
  /** Required consent states to push events; queues events when not granted. */
296
442
  consent?: Consent;
297
443
  /** Implementation-specific configuration passed to the init function. */
@@ -307,28 +453,38 @@ interface Config$7<T extends TypesGeneric$3 = Types$4> {
307
453
  /** Whether to load external scripts (e.g., gtag.js); destination-specific behavior. */
308
454
  loadScript?: boolean;
309
455
  /** Logger configuration (level, handler) to override the collector's defaults. */
310
- logger?: Config$5;
456
+ logger?: Config$4;
311
457
  /** Entity-action rules to filter, rename, transform, and batch events for this destination. */
312
458
  mapping?: Rules<Rule<Mapping$1<T>>>;
313
459
  /** Pre-processing rules applied to all events before mapping; modifies events in-place. */
314
- policy?: Policy$1;
460
+ policy?: Policy;
315
461
  /** Whether to queue events when consent is not granted; defaults to true. */
316
462
  queue?: boolean;
317
463
  /** Defer destination initialization until these collector events fire (e.g., `['consent']`). */
318
464
  require?: string[];
319
465
  /** Transformer chain to run after collector processing but before this destination. */
320
- before?: string | string[];
321
- }
322
- type PartialConfig$1<T extends TypesGeneric$3 = Types$4> = Config$7<Types$4<Partial<Settings$4<T>> | Settings$4<T>, Partial<Mapping$1<T>> | Mapping$1<T>, Env$3<T>>>;
323
- interface Policy$1 {
466
+ before?: Next;
467
+ /** Transformer chain to run after destination push completes. Push response available at ingest._response. */
468
+ next?: Next;
469
+ /** Cache configuration for deduplication (step-level: skip push on HIT). */
470
+ cache?: Cache;
471
+ /** Completely skip this destination — no init, no push, no queuing. */
472
+ disabled?: boolean;
473
+ /** Return this value instead of calling push(). Uses !== undefined check to support falsy values. */
474
+ mock?: unknown;
475
+ }
476
+ type PartialConfig$1<T extends TypesGeneric$3 = Types$4> = Config$6<Types$4<Partial<Settings$4<T>> | Settings$4<T>, Partial<Mapping$1<T>> | Mapping$1<T>, Env$3<T>>>;
477
+ interface Policy {
324
478
  [key: string]: Value;
325
479
  }
326
480
  type Code$1<T extends TypesGeneric$3 = Types$4> = Instance$5<T>;
327
481
  type Init$3<T extends TypesGeneric$3 = Types$4> = {
328
482
  code: Code$1<T>;
329
- config?: Partial<Config$7<T>>;
483
+ config?: Partial<Config$6<T>>;
330
484
  env?: Partial<Env$3<T>>;
331
- before?: string | string[];
485
+ before?: Next;
486
+ next?: Next;
487
+ cache?: Cache;
332
488
  };
333
489
  interface InitDestinations {
334
490
  [key: string]: Init$3<any>;
@@ -340,19 +496,19 @@ interface Destinations {
340
496
  * Context provided to destination functions.
341
497
  * Extends base context with destination-specific properties.
342
498
  */
343
- interface Context$5<T extends TypesGeneric$3 = Types$4> extends Base<Config$7<T>, Env$3<T>> {
499
+ interface Context$5<T extends TypesGeneric$3 = Types$4> extends Base<Config$6<T>, Env$3<T>> {
344
500
  id: string;
345
- data?: Data$1;
501
+ data?: Data;
346
502
  }
347
503
  interface PushContext<T extends TypesGeneric$3 = Types$4> extends Context$5<T> {
348
- ingest?: unknown;
504
+ ingest: Ingest;
349
505
  rule?: Rule<Mapping$1<T>>;
350
506
  }
351
507
  interface PushBatchContext<T extends TypesGeneric$3 = Types$4> extends Context$5<T> {
352
- ingest?: unknown;
508
+ ingest: Ingest;
353
509
  rule?: Rule<Mapping$1<T>>;
354
510
  }
355
- type InitFn$2<T extends TypesGeneric$3 = Types$4> = (context: Context$5<T>) => PromiseOrValue<void | false | Config$7<T>>;
511
+ type InitFn$2<T extends TypesGeneric$3 = Types$4> = (context: Context$5<T>) => PromiseOrValue<void | false | Config$6<T>>;
356
512
  type PushFn<T extends TypesGeneric$3 = Types$4> = (event: Event, context: PushContext<T>) => PromiseOrValue<void | unknown>;
357
513
  type PushBatchFn<T extends TypesGeneric$3 = Types$4> = (batch: Batch<Mapping$1<T>>, context: PushBatchContext<T>) => void;
358
514
  type PushEvent<Mapping = unknown> = {
@@ -363,7 +519,7 @@ type PushEvents<Mapping = unknown> = Array<PushEvent<Mapping>>;
363
519
  interface Batch<Mapping> {
364
520
  key: string;
365
521
  events: Events;
366
- data: Array<Data$1>;
522
+ data: Array<Data>;
367
523
  mapping?: Rule<Mapping>;
368
524
  }
369
525
  interface BatchRegistry<Mapping> {
@@ -372,7 +528,7 @@ interface BatchRegistry<Mapping> {
372
528
  batchFn: () => void;
373
529
  };
374
530
  }
375
- type Data$1 = Property | undefined | Array<Property | undefined>;
531
+ type Data = Property | undefined | Array<Property | undefined>;
376
532
  interface Ref {
377
533
  type: string;
378
534
  data?: unknown;
@@ -387,8 +543,10 @@ type DLQ = Array<[Event, unknown]>;
387
543
  type destination_Batch<Mapping> = Batch<Mapping>;
388
544
  type destination_BatchRegistry<Mapping> = BatchRegistry<Mapping>;
389
545
  type destination_DLQ = DLQ;
546
+ type destination_Data = Data;
390
547
  type destination_Destinations = Destinations;
391
548
  type destination_InitDestinations = InitDestinations;
549
+ type destination_Policy = Policy;
392
550
  type destination_PushBatchContext<T extends TypesGeneric$3 = Types$4> = PushBatchContext<T>;
393
551
  type destination_PushBatchFn<T extends TypesGeneric$3 = Types$4> = PushBatchFn<T>;
394
552
  type destination_PushContext<T extends TypesGeneric$3 = Types$4> = PushContext<T>;
@@ -397,7 +555,7 @@ type destination_PushEvents<Mapping = unknown> = PushEvents<Mapping>;
397
555
  type destination_PushFn<T extends TypesGeneric$3 = Types$4> = PushFn<T>;
398
556
  type destination_Ref = Ref;
399
557
  declare namespace destination {
400
- export type { BaseEnv$3 as BaseEnv, destination_Batch as Batch, destination_BatchRegistry as BatchRegistry, Code$1 as Code, Config$7 as Config, Context$5 as Context, destination_DLQ as DLQ, Data$1 as Data, destination_Destinations as Destinations, Env$3 as Env, Init$3 as Init, destination_InitDestinations as InitDestinations, InitFn$2 as InitFn, InitSettings$3 as InitSettings, Instance$5 as Instance, Mapping$1 as Mapping, PartialConfig$1 as PartialConfig, Policy$1 as Policy, Push$1 as Push, destination_PushBatchContext as PushBatchContext, destination_PushBatchFn as PushBatchFn, destination_PushContext as PushContext, destination_PushEvent as PushEvent, destination_PushEvents as PushEvents, destination_PushFn as PushFn, destination_Ref as Ref, Settings$4 as Settings, Types$4 as Types, TypesGeneric$3 as TypesGeneric, TypesOf$3 as TypesOf };
558
+ export type { BaseEnv$3 as BaseEnv, destination_Batch as Batch, destination_BatchRegistry as BatchRegistry, Code$1 as Code, Config$6 as Config, Context$5 as Context, destination_DLQ as DLQ, destination_Data as Data, destination_Destinations as Destinations, Env$3 as Env, Init$3 as Init, destination_InitDestinations as InitDestinations, InitFn$2 as InitFn, InitSettings$3 as InitSettings, Instance$5 as Instance, Mapping$1 as Mapping, PartialConfig$1 as PartialConfig, destination_Policy as Policy, Push$1 as Push, destination_PushBatchContext as PushBatchContext, destination_PushBatchFn as PushBatchFn, destination_PushContext as PushContext, destination_PushEvent as PushEvent, destination_PushEvents as PushEvents, destination_PushFn as PushFn, destination_Ref as Ref, Settings$4 as Settings, Types$4 as Types, TypesGeneric$3 as TypesGeneric, TypesOf$3 as TypesOf };
401
559
  }
402
560
 
403
561
  interface EventFn<R = Promise<PushResult>> {
@@ -405,12 +563,12 @@ interface EventFn<R = Promise<PushResult>> {
405
563
  (event: string): R;
406
564
  (event: string, data: Properties): R;
407
565
  }
408
- interface Fn$3<R = Promise<PushResult>, Config = unknown> extends EventFn<R>, WalkerCommands<R, Config> {
566
+ interface Fn$2<R = Promise<PushResult>, Config = unknown> extends EventFn<R>, WalkerCommands<R, Config> {
409
567
  }
410
568
  interface WalkerCommands<R = Promise<PushResult>, Config = unknown> {
411
569
  (event: 'walker config', config: Partial<Config>): R;
412
570
  (event: 'walker consent', consent: Consent): R;
413
- <T extends Types$4>(event: 'walker destination', destination: Init$3<T> | Instance$5<T>, config?: Config$7<T>): R;
571
+ <T extends Types$4>(event: 'walker destination', destination: Init$3<T> | Instance$5<T>, config?: Config$6<T>): R;
414
572
  <K extends keyof Functions>(event: 'walker hook', name: K, hookFn: Functions[K]): R;
415
573
  (event: 'walker on', type: Types$3, rules: SingleOrArray<Options>): R;
416
574
  (event: 'walker user', user: User): R;
@@ -438,44 +596,9 @@ type elb_PushData<Config = unknown> = PushData<Config>;
438
596
  type elb_PushResult = PushResult;
439
597
  type elb_WalkerCommands<R = Promise<PushResult>, Config = unknown> = WalkerCommands<R, Config>;
440
598
  declare namespace elb {
441
- export type { Event$1 as Event, elb_EventFn as EventFn, Fn$3 as Fn, elb_Layer as Layer, elb_PushData as PushData, elb_PushResult as PushResult, elb_WalkerCommands as WalkerCommands };
599
+ export type { Event$1 as Event, elb_EventFn as EventFn, Fn$2 as Fn, elb_Layer as Layer, elb_PushData as PushData, elb_PushResult as PushResult, elb_WalkerCommands as WalkerCommands };
442
600
  }
443
601
 
444
- /**
445
- * Flow Configuration System
446
- *
447
- * Core types for walkerOS unified configuration.
448
- * Platform-agnostic, runtime-focused.
449
- *
450
- * The Flow system enables "one config to rule them all" - a single
451
- * walkeros.config.json file that manages multiple flows
452
- * (web_prod, web_stage, server_prod, etc.) with shared configuration,
453
- * variables, and reusable definitions.
454
- *
455
- * ## Connection Rules
456
- *
457
- * Sources use `next` to connect to transformers (pre-collector chain).
458
- * Sources cannot have `before`.
459
- *
460
- * Destinations use `before` to connect to transformers (post-collector chain).
461
- * Destinations cannot have `next`.
462
- *
463
- * Transformers use `next` to chain to other transformers. The same transformer
464
- * pool is shared by both pre-collector and post-collector chains.
465
- *
466
- * The collector is implicit — it is never referenced directly in connections.
467
- * It sits between the source chain and the destination chain automatically.
468
- *
469
- * Circular `next` references are safely handled at runtime by `walkChain()`
470
- * in the collector module (visited-set detection).
471
- *
472
- * ```
473
- * Source → [next → Transformer chain] → Collector → [before → Transformer chain] → Destination
474
- * ```
475
- *
476
- * @packageDocumentation
477
- */
478
-
479
602
  /**
480
603
  * JSON Schema object for contract entry validation.
481
604
  * Standard JSON Schema with description/examples annotations.
@@ -617,7 +740,7 @@ interface Server {
617
740
  * }
618
741
  * ```
619
742
  */
620
- interface Config$6 {
743
+ interface Config$5 {
621
744
  /**
622
745
  * Configuration schema version.
623
746
  */
@@ -968,6 +1091,18 @@ interface SourceReference {
968
1091
  * Can be an array for explicit chain control (bypasses transformer.next resolution).
969
1092
  */
970
1093
  next?: string | string[];
1094
+ /**
1095
+ * First transformer in pre-source chain (consent-exempt).
1096
+ *
1097
+ * @remarks
1098
+ * Runs before source.next chain. Consent-exempt because no analytics
1099
+ * event exists yet — these transformers handle transport-level preprocessing
1100
+ * (decode, validate, authenticate, normalize raw input).
1101
+ * Raw request data is available in context.ingest.
1102
+ */
1103
+ before?: string | string[];
1104
+ /** Cache configuration for this source. */
1105
+ cache?: Cache;
971
1106
  /**
972
1107
  * Named examples for testing and documentation.
973
1108
  * Stripped during flow resolution (not included in bundles).
@@ -1028,6 +1163,15 @@ interface TransformerReference {
1028
1163
  * Merged with default transformer environment.
1029
1164
  */
1030
1165
  env?: unknown;
1166
+ /**
1167
+ * Pre-transformer chain.
1168
+ *
1169
+ * @remarks
1170
+ * Runs before this transformer's push function.
1171
+ * Enables pre-processing or context loading before the main transform.
1172
+ * Uses the same chain resolution as source.next and destination.before.
1173
+ */
1174
+ before?: string | string[];
1031
1175
  /**
1032
1176
  * Next transformer in chain.
1033
1177
  *
@@ -1040,6 +1184,8 @@ interface TransformerReference {
1040
1184
  * are safely detected at runtime by `walkChain()`.
1041
1185
  */
1042
1186
  next?: string | string[];
1187
+ /** Cache configuration for this transformer. */
1188
+ cache?: Cache;
1043
1189
  /**
1044
1190
  * Transformer-level variables (highest priority in cascade).
1045
1191
  * Overrides flow and setup variables.
@@ -1195,6 +1341,17 @@ interface DestinationReference {
1195
1341
  * Can be an array for explicit chain control (bypasses transformer.next resolution).
1196
1342
  */
1197
1343
  before?: string | string[];
1344
+ /**
1345
+ * First transformer in post-push chain.
1346
+ *
1347
+ * @remarks
1348
+ * Runs after destination.push completes. The push response is available
1349
+ * at context.ingest._response. Consent is inherited from the destination
1350
+ * gate — no separate consent check needed.
1351
+ */
1352
+ next?: string | string[];
1353
+ /** Cache configuration for this destination. */
1354
+ cache?: Cache;
1198
1355
  /**
1199
1356
  * Named examples for testing and documentation.
1200
1357
  * Stripped during flow resolution (not included in bundles).
@@ -1221,7 +1378,7 @@ type flow_TransformerReference = TransformerReference;
1221
1378
  type flow_Variables = Variables;
1222
1379
  type flow_Web = Web;
1223
1380
  declare namespace flow {
1224
- export type { Config$6 as Config, flow_Contract as Contract, flow_ContractActions as ContractActions, flow_ContractEntry as ContractEntry, flow_ContractEvents as ContractEvents, flow_ContractSchema as ContractSchema, flow_Definitions as Definitions, flow_DestinationReference as DestinationReference, flow_InlineCode as InlineCode, flow_Packages as Packages, flow_Primitive as Primitive, flow_Server as Server, Settings$3 as Settings, flow_SourceReference as SourceReference, flow_StepExample as StepExample, flow_StepExamples as StepExamples, flow_StoreReference as StoreReference, flow_TransformerReference as TransformerReference, flow_Variables as Variables, flow_Web as Web };
1381
+ export type { Config$5 as Config, flow_Contract as Contract, flow_ContractActions as ContractActions, flow_ContractEntry as ContractEntry, flow_ContractEvents as ContractEvents, flow_ContractSchema as ContractSchema, flow_Definitions as Definitions, flow_DestinationReference as DestinationReference, flow_InlineCode as InlineCode, flow_Packages as Packages, flow_Primitive as Primitive, flow_Server as Server, Settings$3 as Settings, flow_SourceReference as SourceReference, flow_StepExample as StepExample, flow_StepExamples as StepExamples, flow_StoreReference as StoreReference, flow_TransformerReference as TransformerReference, flow_Variables as Variables, flow_Web as Web };
1225
1382
  }
1226
1383
 
1227
1384
  type AnyFunction$1<P extends unknown[] = never[], R = unknown> = (...args: P) => R;
@@ -1325,7 +1482,7 @@ interface Instance$4 {
1325
1482
  /**
1326
1483
  * Logger configuration options
1327
1484
  */
1328
- interface Config$5 {
1485
+ interface Config$4 {
1329
1486
  /**
1330
1487
  * Minimum log level to display
1331
1488
  * @default Level.ERROR
@@ -1351,7 +1508,7 @@ interface InternalConfig {
1351
1508
  /**
1352
1509
  * Logger factory function type
1353
1510
  */
1354
- type Factory = (config?: Config$5) => Instance$4;
1511
+ type Factory = (config?: Config$4) => Instance$4;
1355
1512
 
1356
1513
  type logger_DefaultHandler = DefaultHandler;
1357
1514
  type logger_ErrorContext = ErrorContext;
@@ -1364,83 +1521,7 @@ type logger_LogContext = LogContext;
1364
1521
  type logger_LogFn = LogFn;
1365
1522
  type logger_ThrowFn = ThrowFn;
1366
1523
  declare namespace logger {
1367
- export { type Config$5 as Config, type logger_DefaultHandler as DefaultHandler, type logger_ErrorContext as ErrorContext, type logger_Factory as Factory, type logger_Handler as Handler, type Instance$4 as Instance, type logger_InternalConfig as InternalConfig, logger_Level as Level, type logger_LogContext as LogContext, type logger_LogFn as LogFn, type logger_ThrowFn as ThrowFn };
1368
- }
1369
-
1370
- /**
1371
- * Shared mapping configuration interface.
1372
- * Used by both Source.Config and Destination.Config.
1373
- */
1374
- interface Config$4<T = unknown> {
1375
- consent?: Consent;
1376
- data?: Value | Values;
1377
- mapping?: Rules<Rule<T>>;
1378
- policy?: Policy;
1379
- }
1380
- interface Policy {
1381
- [key: string]: Value;
1382
- }
1383
- interface Rules<T = Rule> {
1384
- [entity: string]: Record<string, T | Array<T>> | undefined;
1385
- }
1386
- interface Rule<Settings = unknown> {
1387
- batch?: number;
1388
- batchFn?: (destination: Instance$5, collector: Instance$6) => void;
1389
- batched?: Batch<Settings>;
1390
- condition?: Condition;
1391
- consent?: Consent;
1392
- settings?: Settings;
1393
- data?: Data;
1394
- ignore?: boolean;
1395
- name?: string;
1396
- policy?: Policy;
1397
- }
1398
- interface Result$2 {
1399
- eventMapping?: Rule;
1400
- mappingKey?: string;
1401
- }
1402
- type Data = Value | Values;
1403
- type Value = ValueType | Array<ValueType>;
1404
- type Values = Array<Value>;
1405
- type ValueType = string | ValueConfig;
1406
- interface ValueConfig {
1407
- condition?: Condition;
1408
- consent?: Consent;
1409
- fn?: Fn$2;
1410
- key?: string;
1411
- loop?: Loop;
1412
- map?: Map;
1413
- set?: Value[];
1414
- validate?: Validate;
1415
- value?: PropertyType;
1416
- }
1417
- type Condition = (value: DeepPartialEvent | unknown, mapping?: Value, collector?: Instance$6) => PromiseOrValue<boolean>;
1418
- type Fn$2 = (value: DeepPartialEvent | unknown, mapping: Value, options: Options$1) => PromiseOrValue<Property | unknown>;
1419
- type Loop = [Value, Value];
1420
- type Map = {
1421
- [key: string]: Value;
1422
- };
1423
- interface Options$1 {
1424
- consent?: Consent;
1425
- collector?: Instance$6;
1426
- props?: unknown;
1427
- }
1428
- type Validate = (value?: unknown) => PromiseOrValue<boolean>;
1429
-
1430
- type mapping_Condition = Condition;
1431
- type mapping_Data = Data;
1432
- type mapping_Loop = Loop;
1433
- type mapping_Map = Map;
1434
- type mapping_Policy = Policy;
1435
- type mapping_Rule<Settings = unknown> = Rule<Settings>;
1436
- type mapping_Rules<T = Rule> = Rules<T>;
1437
- type mapping_Validate = Validate;
1438
- type mapping_Value = Value;
1439
- type mapping_ValueConfig = ValueConfig;
1440
- type mapping_ValueType = ValueType;
1441
- type mapping_Values = Values;
1442
- declare namespace mapping {
1443
- export type { mapping_Condition as Condition, Config$4 as Config, mapping_Data as Data, Fn$2 as Fn, mapping_Loop as Loop, mapping_Map as Map, Options$1 as Options, mapping_Policy as Policy, Result$2 as Result, mapping_Rule as Rule, mapping_Rules as Rules, mapping_Validate as Validate, mapping_Value as Value, mapping_ValueConfig as ValueConfig, mapping_ValueType as ValueType, mapping_Values as Values };
1524
+ export { type Config$4 as Config, type logger_DefaultHandler as DefaultHandler, type logger_ErrorContext as ErrorContext, type logger_Factory as Factory, type logger_Handler as Handler, type Instance$4 as Instance, type logger_InternalConfig as InternalConfig, logger_Level as Level, type logger_LogContext as LogContext, type logger_LogFn as LogFn, type logger_ThrowFn as ThrowFn };
1444
1525
  }
1445
1526
 
1446
1527
  type Config$3 = {
@@ -1455,7 +1536,7 @@ type Config$3 = {
1455
1536
  };
1456
1537
  type Types$3 = keyof Config$3 | (string & {});
1457
1538
  interface EventContextMap {
1458
- config: Partial<Config$8>;
1539
+ config: Partial<Config$7>;
1459
1540
  consent: Consent;
1460
1541
  custom: Properties;
1461
1542
  globals: Properties;
@@ -1522,7 +1603,11 @@ declare namespace on {
1522
1603
  export type { on_AnyEventContext as AnyEventContext, Config$3 as Config, on_ConsentConfig as ConsentConfig, on_ConsentFn as ConsentFn, Context$4 as Context, on_EventContext as EventContext, on_EventContextMap as EventContextMap, on_GenericConfig as GenericConfig, on_GenericFn as GenericFn, on_OnConfig as OnConfig, on_OnFn as OnFn, on_OnFnRuntime as OnFnRuntime, on_Options as Options, on_ReadyConfig as ReadyConfig, on_ReadyFn as ReadyFn, on_RunConfig as RunConfig, on_RunFn as RunFn, on_SessionConfig as SessionConfig, on_SessionFn as SessionFn, Types$3 as Types, on_UserConfig as UserConfig, on_UserFn as UserFn };
1523
1604
  }
1524
1605
 
1525
- type Next = string | string[];
1606
+ interface NextRule {
1607
+ match: MatchExpression | '*';
1608
+ next: Next;
1609
+ }
1610
+ type Next = string | string[] | NextRule[];
1526
1611
  /**
1527
1612
  * Base environment interface for walkerOS transformers.
1528
1613
  *
@@ -1571,9 +1656,16 @@ interface Config$2<T extends TypesGeneric$2 = Types$2> {
1571
1656
  settings?: InitSettings$2<T>;
1572
1657
  env?: Env$2<T>;
1573
1658
  id?: string;
1574
- logger?: Config$5;
1659
+ logger?: Config$4;
1660
+ before?: Next;
1575
1661
  next?: Next;
1662
+ cache?: Cache;
1576
1663
  init?: boolean;
1664
+ disabled?: boolean;
1665
+ /** Return this value instead of calling push(). Global mock for all chains. */
1666
+ mock?: unknown;
1667
+ /** Path-specific mock values keyed by chain path (e.g., "destination.ga4.before"). Takes precedence over global mock. */
1668
+ chainMocks?: Record<string, unknown>;
1577
1669
  }
1578
1670
  /**
1579
1671
  * Context provided to transformer functions.
@@ -1581,7 +1673,7 @@ interface Config$2<T extends TypesGeneric$2 = Types$2> {
1581
1673
  */
1582
1674
  interface Context$3<T extends TypesGeneric$2 = Types$2> extends Base<Config$2<T>, Env$2<T>> {
1583
1675
  id: string;
1584
- ingest?: unknown;
1676
+ ingest: Ingest;
1585
1677
  }
1586
1678
  /**
1587
1679
  * Unified result type for transformer functions.
@@ -1591,22 +1683,34 @@ interface Context$3<T extends TypesGeneric$2 = Types$2> extends Base<Config$2<T>
1591
1683
  * @field respond - Wrapped respond function for downstream transformers
1592
1684
  * @field next - Branch to a different chain (replaces BranchResult)
1593
1685
  */
1594
- interface Result$1 {
1595
- event?: DeepPartialEvent;
1686
+ interface Result$1<E = DeepPartialEvent> {
1687
+ event?: E;
1596
1688
  respond?: RespondFn;
1597
1689
  next?: Next;
1598
1690
  }
1691
+ /**
1692
+ * Result of running a transformer chain.
1693
+ * Returns the processed event (singular, fan-out array, or null if dropped)
1694
+ * alongside the potentially wrapped respond function.
1695
+ */
1696
+ interface ChainResult {
1697
+ event: DeepPartialEvent | DeepPartialEvent[] | null;
1698
+ respond?: RespondFn;
1699
+ }
1599
1700
  /**
1600
1701
  * The main transformer function.
1601
- * Uses DeepPartialEvent for consistency across pre/post collector.
1602
1702
  *
1603
- * @param event - The event to process
1604
- * @param context - Transformer context with collector, config, env, logger
1703
+ * Pre-collector transformers use default E = DeepPartialEvent.
1704
+ * Post-collector transformers can use E = Event for type-safe access.
1705
+ * A transformer written for DeepPartialEvent works in both positions
1706
+ * because Event is a subtype of DeepPartialEvent.
1707
+ *
1605
1708
  * @returns Result - structured result with event, respond, next
1709
+ * @returns Result[] - fan-out: each Result continues independently through remaining chain
1606
1710
  * @returns void - continue with current event unchanged (passthrough)
1607
1711
  * @returns false - stop chain, cancel further processing
1608
1712
  */
1609
- type Fn$1<T extends TypesGeneric$2 = Types$2> = (event: DeepPartialEvent, context: Context$3<T>) => PromiseOrValue<Result$1 | false | void>;
1713
+ type Fn$1<T extends TypesGeneric$2 = Types$2, E = DeepPartialEvent> = (event: E, context: Context$3<T>) => PromiseOrValue<Result$1<E> | Result$1<E>[] | false | void>;
1610
1714
  /**
1611
1715
  * Optional initialization function.
1612
1716
  * Called once before first push.
@@ -1640,7 +1744,9 @@ type InitTransformer<T extends TypesGeneric$2 = Types$2> = {
1640
1744
  code: Init$2<T>;
1641
1745
  config?: Partial<Config$2<T>>;
1642
1746
  env?: Partial<Env$2<T>>;
1747
+ before?: Next;
1643
1748
  next?: Next;
1749
+ cache?: Cache;
1644
1750
  };
1645
1751
  /**
1646
1752
  * Transformers configuration for collector.
@@ -1656,12 +1762,14 @@ interface Transformers {
1656
1762
  [transformerId: string]: Instance$3;
1657
1763
  }
1658
1764
 
1765
+ type transformer_ChainResult = ChainResult;
1659
1766
  type transformer_InitTransformer<T extends TypesGeneric$2 = Types$2> = InitTransformer<T>;
1660
1767
  type transformer_InitTransformers = InitTransformers;
1661
1768
  type transformer_Next = Next;
1769
+ type transformer_NextRule = NextRule;
1662
1770
  type transformer_Transformers = Transformers;
1663
1771
  declare namespace transformer {
1664
- export type { BaseEnv$2 as BaseEnv, Config$2 as Config, Context$3 as Context, Env$2 as Env, Fn$1 as Fn, Init$2 as Init, InitFn$1 as InitFn, InitSettings$2 as InitSettings, transformer_InitTransformer as InitTransformer, transformer_InitTransformers as InitTransformers, Instance$3 as Instance, transformer_Next as Next, Result$1 as Result, Settings$2 as Settings, transformer_Transformers as Transformers, Types$2 as Types, TypesGeneric$2 as TypesGeneric, TypesOf$2 as TypesOf };
1772
+ export type { BaseEnv$2 as BaseEnv, transformer_ChainResult as ChainResult, Config$2 as Config, Context$3 as Context, Env$2 as Env, Fn$1 as Fn, Init$2 as Init, InitFn$1 as InitFn, InitSettings$2 as InitSettings, transformer_InitTransformer as InitTransformer, transformer_InitTransformers as InitTransformers, Instance$3 as Instance, transformer_Next as Next, transformer_NextRule as NextRule, Result$1 as Result, Settings$2 as Settings, transformer_Transformers as Transformers, Types$2 as Types, TypesGeneric$2 as TypesGeneric, TypesOf$2 as TypesOf };
1665
1773
  }
1666
1774
 
1667
1775
  interface Context$2 {
@@ -1692,7 +1800,7 @@ interface BaseEnv$1 {
1692
1800
  push: PushFn$1;
1693
1801
  command: CommandFn;
1694
1802
  sources?: Sources;
1695
- elb: Fn$3;
1803
+ elb: Fn$2;
1696
1804
  logger: Instance$4;
1697
1805
  }
1698
1806
  /**
@@ -1705,7 +1813,7 @@ interface BaseEnv$1 {
1705
1813
  * @template E - Environment dependencies type
1706
1814
  * @template I - InitSettings configuration type (user input)
1707
1815
  */
1708
- interface Types$1<S = unknown, M = unknown, P = Fn$3, E = BaseEnv$1, I = S> {
1816
+ interface Types$1<S = unknown, M = unknown, P = Fn$2, E = BaseEnv$1, I = S> {
1709
1817
  settings: S;
1710
1818
  initSettings: I;
1711
1819
  mapping: M;
@@ -1734,7 +1842,7 @@ type Env$1<T extends TypesGeneric$1 = Types$1> = T['env'];
1734
1842
  * Inference helper: Extract Types from Instance
1735
1843
  */
1736
1844
  type TypesOf$1<I> = I extends Instance$2<infer T> ? T : never;
1737
- interface Config$1<T extends TypesGeneric$1 = Types$1> extends Config$4<Mapping<T>> {
1845
+ interface Config$1<T extends TypesGeneric$1 = Types$1> extends Config$8<Mapping<T>> {
1738
1846
  /** Implementation-specific configuration passed to the init function. */
1739
1847
  settings?: InitSettings$1<T>;
1740
1848
  /** Runtime dependencies injected by the collector (push, command, logger, etc.). */
@@ -1742,7 +1850,7 @@ interface Config$1<T extends TypesGeneric$1 = Types$1> extends Config$4<Mapping<
1742
1850
  /** Source identifier; defaults to the InitSources object key. */
1743
1851
  id?: string;
1744
1852
  /** Logger configuration (level, handler) to override the collector's defaults. */
1745
- logger?: Config$5;
1853
+ logger?: Config$4;
1746
1854
  /** Mark as primary source; its push function becomes the exported `elb` from startFlow. */
1747
1855
  primary?: boolean;
1748
1856
  /** Defer source initialization until these collector events fire (e.g., `['consent']`). */
@@ -1759,7 +1867,9 @@ interface Config$1<T extends TypesGeneric$1 = Types$1> extends Config$4<Mapping<
1759
1867
  * origin: 'req.headers.origin'
1760
1868
  * }
1761
1869
  */
1762
- ingest?: Data;
1870
+ ingest?: Data$1;
1871
+ /** Completely skip this source — no init, no event capture. */
1872
+ disabled?: boolean;
1763
1873
  }
1764
1874
  type PartialConfig<T extends TypesGeneric$1 = Types$1> = Config$1<Types$1<Partial<Settings$1<T>> | Settings$1<T>, Partial<Mapping<T>> | Mapping<T>, Push<T>, Env$1<T>>>;
1765
1875
  interface Instance$2<T extends TypesGeneric$1 = Types$1> {
@@ -1793,6 +1903,8 @@ type InitSource<T extends TypesGeneric$1 = Types$1> = {
1793
1903
  env?: Partial<Env$1<T>>;
1794
1904
  primary?: boolean;
1795
1905
  next?: Next;
1906
+ before?: Next;
1907
+ cache?: Cache;
1796
1908
  };
1797
1909
  /**
1798
1910
  * Sources configuration for collector.
@@ -1839,7 +1951,7 @@ interface Config<T extends TypesGeneric = Types> {
1839
1951
  settings?: InitSettings<T>;
1840
1952
  env?: Env<T>;
1841
1953
  id?: string;
1842
- logger?: Config$5;
1954
+ logger?: Config$4;
1843
1955
  }
1844
1956
  interface Context<T extends TypesGeneric = Types> extends Base<Config<T>, Env<T>> {
1845
1957
  id: string;
@@ -1907,7 +2019,7 @@ interface FlowHandle {
1907
2019
  /** The collector instance created by startFlow. */
1908
2020
  collector: Instance$6;
1909
2021
  /** The elb push function for direct event injection. */
1910
- elb: Fn$3;
2022
+ elb: Fn$2;
1911
2023
  }
1912
2024
  /** What createTrigger returns — a flow handle (lazy) and a trigger function. */
1913
2025
  interface Instance<TContent = unknown, TResult = unknown> {
@@ -1975,7 +2087,7 @@ declare namespace trigger {
1975
2087
  }
1976
2088
 
1977
2089
  type AnyObject<T = unknown> = Record<string, T>;
1978
- type Elb = Fn$3;
2090
+ type Elb = Fn$2;
1979
2091
  type AnyFunction = (...args: unknown[]) => unknown;
1980
2092
  type SingleOrArray<T> = T | Array<T>;
1981
2093
  type Events = Array<Event>;
@@ -2131,28 +2243,6 @@ declare namespace simulation {
2131
2243
  export type { simulation_Call as Call, simulation_Result as Result };
2132
2244
  }
2133
2245
 
2134
- type MatchExpression = MatchCondition | {
2135
- and: MatchExpression[];
2136
- } | {
2137
- or: MatchExpression[];
2138
- };
2139
- interface MatchCondition {
2140
- key: string;
2141
- operator: MatchOperator;
2142
- value: string;
2143
- not?: boolean;
2144
- }
2145
- type MatchOperator = 'eq' | 'contains' | 'prefix' | 'suffix' | 'regex' | 'gt' | 'lt' | 'exists';
2146
- type CompiledMatcher = (ingest: Record<string, unknown>) => boolean;
2147
-
2148
- type matcher_CompiledMatcher = CompiledMatcher;
2149
- type matcher_MatchCondition = MatchCondition;
2150
- type matcher_MatchExpression = MatchExpression;
2151
- type matcher_MatchOperator = MatchOperator;
2152
- declare namespace matcher {
2153
- export type { matcher_CompiledMatcher as CompiledMatcher, matcher_MatchCondition as MatchCondition, matcher_MatchExpression as MatchExpression, matcher_MatchOperator as MatchOperator };
2154
- }
2155
-
2156
2246
  interface Code {
2157
2247
  lang?: string;
2158
2248
  code: string;
@@ -2252,7 +2342,7 @@ declare function packageNameToVariable(packageName: string): string;
2252
2342
  * const prodSettings = getFlowSettings(config, 'production');
2253
2343
  * ```
2254
2344
  */
2255
- declare function getFlowSettings(config: Config$6, flowName?: string, options?: ResolveOptions): Settings$3;
2345
+ declare function getFlowSettings(config: Config$5, flowName?: string, options?: ResolveOptions): Settings$3;
2256
2346
  /**
2257
2347
  * Get platform from settings (web or server).
2258
2348
  *
@@ -2364,7 +2454,14 @@ declare function getGrantedConsent(required: Consent | undefined, state?: Consen
2364
2454
  * }));
2365
2455
  * ```
2366
2456
  */
2367
- declare function createDestination<I extends Instance$5>(baseDestination: I, config: Partial<Config$7<TypesOf$3<I>>>): I;
2457
+ declare function createDestination<I extends Instance$5>(baseDestination: I, config: Partial<Config$6<TypesOf$3<I>>>): I;
2458
+
2459
+ /**
2460
+ * Deep merges source into target, mutating target in-place.
2461
+ * Recurses into plain objects; everything else is a leaf (replaced).
2462
+ * Skips undefined source values; null overwrites.
2463
+ */
2464
+ declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Record<string, unknown>): T;
2368
2465
 
2369
2466
  /**
2370
2467
  * Creates a complete event with default values.
@@ -2526,7 +2623,7 @@ declare function isString(value: unknown): value is string;
2526
2623
  * // TODO: Consider compile-time stripping of debug logs in production builds
2527
2624
  * // e.g., if (__DEV__) { logger.debug(...) }
2528
2625
  */
2529
- declare function createLogger(config?: Config$5): Instance$4;
2626
+ declare function createLogger(config?: Config$4): Instance$4;
2530
2627
 
2531
2628
  /**
2532
2629
  * Gets the mapping for an event.
@@ -2544,7 +2641,7 @@ declare function getMappingEvent(event: DeepPartialEvent | PartialEvent | Event,
2544
2641
  * @param options The mapping options.
2545
2642
  * @returns The mapped value.
2546
2643
  */
2547
- declare function getMappingValue(value: DeepPartialEvent | unknown | undefined, data?: Data, options?: Options$1): Promise<Property | undefined>;
2644
+ declare function getMappingValue(value: DeepPartialEvent | unknown | undefined, data?: Data$1, options?: Options$1): Promise<Property | undefined>;
2548
2645
  /**
2549
2646
  * Processes an event through mapping configuration.
2550
2647
  *
@@ -2564,7 +2661,7 @@ declare function getMappingValue(value: DeepPartialEvent | unknown | undefined,
2564
2661
  * @param collector - Collector instance for context
2565
2662
  * @returns Object with transformed event, data, mapping rule, and ignore flag
2566
2663
  */
2567
- declare function processEventMapping<T extends DeepPartialEvent | Event>(event: T, config: Config$4, collector: Instance$6): Promise<{
2664
+ declare function processEventMapping<T extends DeepPartialEvent | Event>(event: T, config: Config$8, collector: Instance$6): Promise<{
2568
2665
  event: T;
2569
2666
  data?: Property;
2570
2667
  mapping?: Rule;
@@ -2638,6 +2735,36 @@ declare function mockEnv<T extends object>(env: T, interceptor: InterceptorFn):
2638
2735
  */
2639
2736
  declare function traverseEnv<T extends object>(env: T, replacer: (value: unknown, path: string[]) => unknown): T;
2640
2737
 
2738
+ /**
2739
+ * Create a mock context for testing transformers and destinations.
2740
+ *
2741
+ * Provides sensible defaults for all required fields. Override only
2742
+ * what the test cares about. When context signatures change, only
2743
+ * this factory needs updating — not every test file.
2744
+ *
2745
+ * @example
2746
+ * ```typescript
2747
+ * // Transformer test — only specify config
2748
+ * const ctx = createMockContext({ config: { settings: { strict: true } } });
2749
+ * const result = await transformer.push(event, ctx);
2750
+ *
2751
+ * // Destination test — specify config and custom env
2752
+ * const ctx = createMockContext({ config: { settings: { url } }, env: { sendWeb } });
2753
+ * await destination.push(event, ctx);
2754
+ *
2755
+ * // With custom ingest data
2756
+ * const ctx = createMockContext({ ingest: { ...createIngest('test'), path: '/api' } });
2757
+ * ```
2758
+ */
2759
+ declare function createMockContext<T extends TypesGeneric$2 = Types$2>(overrides?: Partial<Omit<Context$3<T>, 'config' | 'ingest'> & {
2760
+ config?: Config$2<T> | Config$6<TypesGeneric$3>;
2761
+ ingest?: Ingest | (Record<string, unknown> & {
2762
+ _meta: Ingest['_meta'];
2763
+ });
2764
+ data?: unknown;
2765
+ rule?: unknown;
2766
+ }>): Context$3<T> & PushContext<TypesGeneric$3>;
2767
+
2641
2768
  /**
2642
2769
  * Mock logger instance for testing
2643
2770
  * Includes all logger methods as jest.fn() plus tracking of scoped loggers
@@ -2880,7 +3007,7 @@ declare function wrapCondition(code: string): Condition;
2880
3007
  * const fn = wrapFn('const parts = value.user.email.split("@"); return parts[1].toUpperCase()');
2881
3008
  * ```
2882
3009
  */
2883
- declare function wrapFn(code: string): Fn$2;
3010
+ declare function wrapFn(code: string): Fn$3;
2884
3011
  /**
2885
3012
  * Wrap inline code string as Validate function.
2886
3013
  *
@@ -2935,6 +3062,7 @@ interface WalkerOSPackage extends WalkerOSPackageInfo {
2935
3062
  declare function fetchPackage(packageName: string, options?: {
2936
3063
  version?: string;
2937
3064
  timeout?: number;
3065
+ baseUrl?: string;
2938
3066
  }): Promise<WalkerOSPackage>;
2939
3067
  /**
2940
3068
  * @deprecated Use fetchPackage instead.
@@ -2987,6 +3115,24 @@ declare function mcpError(error: unknown, hint?: string): {
2987
3115
  */
2988
3116
  declare function compileMatcher(expr: MatchExpression | '*'): CompiledMatcher;
2989
3117
 
3118
+ interface CompiledRoute {
3119
+ match: CompiledMatcher;
3120
+ next: CompiledNext;
3121
+ }
3122
+ type CompiledNext = {
3123
+ type: 'static';
3124
+ value: string;
3125
+ } | {
3126
+ type: 'chain';
3127
+ value: string[];
3128
+ } | {
3129
+ type: 'routes';
3130
+ routes: CompiledRoute[];
3131
+ };
3132
+ declare function isRouteArray(next: Next): next is NextRule[];
3133
+ declare function compileNext(next: Next | undefined): CompiledNext | undefined;
3134
+ declare function resolveNext(compiled: CompiledNext | undefined, context?: Record<string, unknown>): string | string[] | undefined;
3135
+
2990
3136
  type PackageType = 'source' | 'destination' | 'transformer' | 'store';
2991
3137
  interface PackageSchemas {
2992
3138
  settings?: Record<string, unknown>;
@@ -2994,4 +3140,31 @@ interface PackageSchemas {
2994
3140
  }
2995
3141
  declare function mergeConfigSchema(type: PackageType, packageSchemas: PackageSchemas): Record<string, unknown>;
2996
3142
 
2997
- export { collector as Collector, Const, context as Context, destination as Destination, ENV_MARKER_PREFIX, elb as Elb, type ExampleSummary, flow as Flow, hint as Hint, hooks as Hooks, Level, lifecycle as Lifecycle, logger as Logger, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, on as On, request as Request, type ResolveOptions, type RespondFn, type RespondOptions, type SendDataValue, type SendHeaders, type SendResponse, simulation as Simulation, source as Source, type StorageType, store as Store, transformer as Transformer, trigger as Trigger, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, anonymizeIP, assign, branch, castToProperty, castValue, clone, compileMatcher, createDestination, createEvent, createLogger, createMockLogger, createRespond, debounce, fetchPackage, fetchPackageSchema, filterValues, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getOS, getOSVersion, getPlatform, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPropertyType, isSameType, isString, mcpError, mcpResult, mergeConfigSchema, mergeContractSchemas, mockEnv, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, resolveContracts, setByPath, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, walkPath, wrapCondition, wrapFn, wrapValidate };
3143
+ interface CompiledCacheRule {
3144
+ match: CompiledMatcher;
3145
+ key: string[];
3146
+ ttl: number;
3147
+ update?: CacheRule['update'];
3148
+ }
3149
+ interface CompiledCache {
3150
+ full: boolean;
3151
+ storeId?: string;
3152
+ rules: CompiledCacheRule[];
3153
+ }
3154
+ interface CacheResult {
3155
+ status: 'HIT' | 'MISS';
3156
+ key: string;
3157
+ value?: unknown;
3158
+ rule: CompiledCacheRule;
3159
+ }
3160
+ /**
3161
+ * Builds a structured context object for cache and routing operations.
3162
+ * Normalizes ingest (defaulting to {}) and optionally includes event.
3163
+ */
3164
+ declare function buildCacheContext(ingest?: unknown, event?: unknown): Record<string, unknown>;
3165
+ declare function compileCache(cache: Cache): CompiledCache;
3166
+ declare function checkCache(compiled: CompiledCache, store: Instance$1, context: Record<string, unknown>, namespace: string): CacheResult | null;
3167
+ declare function storeCache(store: Instance$1, key: string, value: unknown, ttlSeconds: number): void;
3168
+ declare function applyUpdate(value: unknown, update: Record<string, unknown> | undefined, context: Record<string, unknown>): Promise<unknown>;
3169
+
3170
+ export { cache as Cache, type CacheResult, collector as Collector, type CompiledCache, type CompiledNext, type CompiledRoute, Const, context as Context, destination as Destination, ENV_MARKER_PREFIX, elb as Elb, type ExampleSummary, flow as Flow, hint as Hint, hooks as Hooks, type Ingest, type IngestMeta, Level, lifecycle as Lifecycle, logger as Logger, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, on as On, request as Request, type ResolveOptions, type RespondFn, type RespondOptions, type SendDataValue, type SendHeaders, type SendResponse, simulation as Simulation, source as Source, type StorageType, store as Store, transformer as Transformer, trigger as Trigger, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, anonymizeIP, applyUpdate, assign, branch, buildCacheContext, castToProperty, castValue, checkCache, clone, compileCache, compileMatcher, compileNext, createDestination, createEvent, createIngest, createLogger, createMockContext, createMockLogger, createRespond, debounce, deepMerge, fetchPackage, fetchPackageSchema, filterValues, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getOS, getOSVersion, getPlatform, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPropertyType, isRouteArray, isSameType, isString, mcpError, mcpResult, mergeConfigSchema, mergeContractSchemas, mockEnv, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, resolveContracts, resolveNext, setByPath, storeCache, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, walkPath, wrapCondition, wrapFn, wrapValidate };