@walkeros/core 4.7.2 → 4.8.0-next-1791496487198

package/dist/index.d.mts

@@ -105,15 +105,24 @@ interface Rule<Settings = unknown> {
      */
     remove?: string[];
 }
+/**
+ * A deep partial of T as `mergeMappingRule` applies it: every object key is
+ * optional and a `null` clears the inherited key (JSON merge-patch delete);
+ * arrays and functions replace as a whole.
+ */
+type Patch<T> = T extends readonly unknown[] ? T : T extends (...args: never[]) => unknown ? T : T extends object ? {
+    [K in keyof T]?: Patch<T[K]> | null;
+} : T;
 /**
  * A partial Rule used by `Rule.extend`. Every field is optional, and a
- * `null` value clears the inherited field (JSON merge-patch delete). The
- * control fields `extend` and `remove` are excluded: a patch models only
- * direct rule fields, matching what the runtime patch schema accepts.
+ * `null` at any object key clears the inherited key, for example
+ * `{ data: { map: { tax: null } } }`. The control fields `extend` and
+ * `remove` are excluded: a patch models only direct rule fields, matching
+ * what the runtime patch schema accepts.
  */
 type RulePatchFields<Settings = unknown> = Omit<Rule<Settings>, 'extend' | 'remove'>;
 type RulePatch<Settings = unknown> = {
-    [K in keyof RulePatchFields<Settings>]?: RulePatchFields<Settings>[K] | null;
+    [K in keyof RulePatchFields<Settings>]?: Patch<RulePatchFields<Settings>[K]> | null;
 };
 interface Result$2 {
     eventMapping?: Rule;
@@ -154,6 +163,13 @@ interface Context$6 {
     logger: Instance$3;
     consent?: Consent;
 }
+/**
+ * Context for `getMappingValue`. The collector is required; the other
+ * Context fields are optional. `event` and `consent` override what is
+ * inferred from the value and the collector; the logger always comes from
+ * the collector.
+ */
+type ValueContext = Pick<Context$6, 'collector'> & Partial<Omit<Context$6, 'collector'>>;
 type Fn$4 = (value: unknown, context: Context$6) => PromiseOrValue<Property | unknown>;
 type Condition = (value: unknown, context: Context$6) => PromiseOrValue<boolean>;
 type Validate = (value: unknown, context: Context$6) => PromiseOrValue<boolean>;
@@ -172,10 +188,11 @@ type mapping_Rules<T = Rule> = Rules<T>;
 type mapping_Validate = Validate;
 type mapping_Value = Value;
 type mapping_ValueConfig = ValueConfig;
+type mapping_ValueContext = ValueContext;
 type mapping_ValueType = ValueType;
 type mapping_Values = Values;
 declare namespace mapping {
-  export type { mapping_Condition as Condition, Config$7 as Config, Context$6 as Context, Data$1 as Data, Fn$4 as Fn, mapping_Loop as Loop, mapping_Map as Map, Policy$1 as Policy, Result$2 as Result, mapping_Root as Root, mapping_Rule as Rule, mapping_RulePatch as RulePatch, mapping_Rules as Rules, mapping_Validate as Validate, mapping_Value as Value, mapping_ValueConfig as ValueConfig, mapping_ValueType as ValueType, mapping_Values as Values };
+  export type { mapping_Condition as Condition, Config$7 as Config, Context$6 as Context, Data$1 as Data, Fn$4 as Fn, mapping_Loop as Loop, mapping_Map as Map, Policy$1 as Policy, Result$2 as Result, mapping_Root as Root, mapping_Rule as Rule, mapping_RulePatch as RulePatch, mapping_Rules as Rules, mapping_Validate as Validate, mapping_Value as Value, mapping_ValueConfig as ValueConfig, mapping_ValueContext as ValueContext, mapping_ValueType as ValueType, mapping_Values as Values };
 }
 
 interface BaseCacheRule {
@@ -3440,7 +3457,12 @@ interface Event {
 interface Consent {
     [name: string]: boolean;
 }
-interface User extends Properties {
+/**
+ * Declared (named) fields of an event User. Index-free like `SourceFields`, so
+ * the drift guard can compare `keyof UserFields` against
+ * `keyof z.infer<typeof UserFieldsSchema>`.
+ */
+interface UserFields {
     id?: string;
     device?: string;
     session?: string;
@@ -3463,6 +3485,9 @@ interface User extends Properties {
     screenSize?: string;
     ip?: string;
     internal?: boolean;
+    optout?: boolean;
+}
+interface User extends Properties, UserFields {
 }
 type SourcePlatform = 'web' | 'server' | 'app' | 'ios' | 'android' | 'terminal' | string;
 /**
@@ -3554,8 +3579,9 @@ type walkeros_SourceFields = SourceFields;
 type walkeros_SourceMap = SourceMap;
 type walkeros_SourcePlatform = SourcePlatform;
 type walkeros_User = User;
+type walkeros_UserFields = UserFields;
 declare namespace walkeros {
-  export type { walkeros_ActionHandler as ActionHandler, walkeros_AnyFunction as AnyFunction, walkeros_AnyObject as AnyObject, walkeros_Consent as Consent, walkeros_ConsentHandler as ConsentHandler, walkeros_DeepPartial as DeepPartial, walkeros_DeepPartialEvent as DeepPartialEvent, walkeros_Elb as Elb, walkeros_Entities as Entities, walkeros_Entity as Entity, walkeros_Event as Event, walkeros_Events as Events, walkeros_OrderedProperties as OrderedProperties, walkeros_PartialEvent as PartialEvent, walkeros_PromiseOrValue as PromiseOrValue, walkeros_Properties as Properties, walkeros_Property as Property, walkeros_PropertyType as PropertyType, walkeros_SingleOrArray as SingleOrArray, walkeros_Source as Source, walkeros_SourceFields as SourceFields, walkeros_SourceMap as SourceMap, walkeros_SourcePlatform as SourcePlatform, walkeros_User as User };
+  export type { walkeros_ActionHandler as ActionHandler, walkeros_AnyFunction as AnyFunction, walkeros_AnyObject as AnyObject, walkeros_Consent as Consent, walkeros_ConsentHandler as ConsentHandler, walkeros_DeepPartial as DeepPartial, walkeros_DeepPartialEvent as DeepPartialEvent, walkeros_Elb as Elb, walkeros_Entities as Entities, walkeros_Entity as Entity, walkeros_Event as Event, walkeros_Events as Events, walkeros_OrderedProperties as OrderedProperties, walkeros_PartialEvent as PartialEvent, walkeros_PromiseOrValue as PromiseOrValue, walkeros_Properties as Properties, walkeros_Property as Property, walkeros_PropertyType as PropertyType, walkeros_SingleOrArray as SingleOrArray, walkeros_Source as Source, walkeros_SourceFields as SourceFields, walkeros_SourceMap as SourceMap, walkeros_SourcePlatform as SourcePlatform, walkeros_User as User, walkeros_UserFields as UserFields };
 }
 
 /**
@@ -4513,12 +4539,12 @@ declare function getMappingEvent(event: DeepPartialEvent | PartialEvent | Event,
 /**
  * Gets a value from a mapping.
  *
- * @param value The value to get the mapping from.
- * @param data The mapping data.
- * @param options The mapping options.
- * @returns The mapped value.
+ * @param value The source to resolve the mapping against, usually an event.
+ * @param data The mapping data: a key path, a value config, or a list of them.
+ * @param context The collector (required), plus an optional event and consent.
+ * @returns The mapped value, or undefined when the value is undefined.
  */
-declare function getMappingValue(value: DeepPartialEvent | unknown | undefined, data?: Data$1, context?: Partial<Context$6>): Promise<Property | undefined>;
+declare function getMappingValue(value: DeepPartialEvent | unknown | undefined, data: Data$1 | undefined, context: ValueContext): Promise<Property | undefined>;
 /**
  * Processes an event through mapping configuration.
  *

package/dist/index.d.ts

@@ -105,15 +105,24 @@ interface Rule<Settings = unknown> {
      */
     remove?: string[];
 }
+/**
+ * A deep partial of T as `mergeMappingRule` applies it: every object key is
+ * optional and a `null` clears the inherited key (JSON merge-patch delete);
+ * arrays and functions replace as a whole.
+ */
+type Patch<T> = T extends readonly unknown[] ? T : T extends (...args: never[]) => unknown ? T : T extends object ? {
+    [K in keyof T]?: Patch<T[K]> | null;
+} : T;
 /**
  * A partial Rule used by `Rule.extend`. Every field is optional, and a
- * `null` value clears the inherited field (JSON merge-patch delete). The
- * control fields `extend` and `remove` are excluded: a patch models only
- * direct rule fields, matching what the runtime patch schema accepts.
+ * `null` at any object key clears the inherited key, for example
+ * `{ data: { map: { tax: null } } }`. The control fields `extend` and
+ * `remove` are excluded: a patch models only direct rule fields, matching
+ * what the runtime patch schema accepts.
  */
 type RulePatchFields<Settings = unknown> = Omit<Rule<Settings>, 'extend' | 'remove'>;
 type RulePatch<Settings = unknown> = {
-    [K in keyof RulePatchFields<Settings>]?: RulePatchFields<Settings>[K] | null;
+    [K in keyof RulePatchFields<Settings>]?: Patch<RulePatchFields<Settings>[K]> | null;
 };
 interface Result$2 {
     eventMapping?: Rule;
@@ -154,6 +163,13 @@ interface Context$6 {
     logger: Instance$3;
     consent?: Consent;
 }
+/**
+ * Context for `getMappingValue`. The collector is required; the other
+ * Context fields are optional. `event` and `consent` override what is
+ * inferred from the value and the collector; the logger always comes from
+ * the collector.
+ */
+type ValueContext = Pick<Context$6, 'collector'> & Partial<Omit<Context$6, 'collector'>>;
 type Fn$4 = (value: unknown, context: Context$6) => PromiseOrValue<Property | unknown>;
 type Condition = (value: unknown, context: Context$6) => PromiseOrValue<boolean>;
 type Validate = (value: unknown, context: Context$6) => PromiseOrValue<boolean>;
@@ -172,10 +188,11 @@ type mapping_Rules<T = Rule> = Rules<T>;
 type mapping_Validate = Validate;
 type mapping_Value = Value;
 type mapping_ValueConfig = ValueConfig;
+type mapping_ValueContext = ValueContext;
 type mapping_ValueType = ValueType;
 type mapping_Values = Values;
 declare namespace mapping {
-  export type { mapping_Condition as Condition, Config$7 as Config, Context$6 as Context, Data$1 as Data, Fn$4 as Fn, mapping_Loop as Loop, mapping_Map as Map, Policy$1 as Policy, Result$2 as Result, mapping_Root as Root, mapping_Rule as Rule, mapping_RulePatch as RulePatch, mapping_Rules as Rules, mapping_Validate as Validate, mapping_Value as Value, mapping_ValueConfig as ValueConfig, mapping_ValueType as ValueType, mapping_Values as Values };
+  export type { mapping_Condition as Condition, Config$7 as Config, Context$6 as Context, Data$1 as Data, Fn$4 as Fn, mapping_Loop as Loop, mapping_Map as Map, Policy$1 as Policy, Result$2 as Result, mapping_Root as Root, mapping_Rule as Rule, mapping_RulePatch as RulePatch, mapping_Rules as Rules, mapping_Validate as Validate, mapping_Value as Value, mapping_ValueConfig as ValueConfig, mapping_ValueContext as ValueContext, mapping_ValueType as ValueType, mapping_Values as Values };
 }
 
 interface BaseCacheRule {
@@ -3440,7 +3457,12 @@ interface Event {
 interface Consent {
     [name: string]: boolean;
 }
-interface User extends Properties {
+/**
+ * Declared (named) fields of an event User. Index-free like `SourceFields`, so
+ * the drift guard can compare `keyof UserFields` against
+ * `keyof z.infer<typeof UserFieldsSchema>`.
+ */
+interface UserFields {
     id?: string;
     device?: string;
     session?: string;
@@ -3463,6 +3485,9 @@ interface User extends Properties {
     screenSize?: string;
     ip?: string;
     internal?: boolean;
+    optout?: boolean;
+}
+interface User extends Properties, UserFields {
 }
 type SourcePlatform = 'web' | 'server' | 'app' | 'ios' | 'android' | 'terminal' | string;
 /**
@@ -3554,8 +3579,9 @@ type walkeros_SourceFields = SourceFields;
 type walkeros_SourceMap = SourceMap;
 type walkeros_SourcePlatform = SourcePlatform;
 type walkeros_User = User;
+type walkeros_UserFields = UserFields;
 declare namespace walkeros {
-  export type { walkeros_ActionHandler as ActionHandler, walkeros_AnyFunction as AnyFunction, walkeros_AnyObject as AnyObject, walkeros_Consent as Consent, walkeros_ConsentHandler as ConsentHandler, walkeros_DeepPartial as DeepPartial, walkeros_DeepPartialEvent as DeepPartialEvent, walkeros_Elb as Elb, walkeros_Entities as Entities, walkeros_Entity as Entity, walkeros_Event as Event, walkeros_Events as Events, walkeros_OrderedProperties as OrderedProperties, walkeros_PartialEvent as PartialEvent, walkeros_PromiseOrValue as PromiseOrValue, walkeros_Properties as Properties, walkeros_Property as Property, walkeros_PropertyType as PropertyType, walkeros_SingleOrArray as SingleOrArray, walkeros_Source as Source, walkeros_SourceFields as SourceFields, walkeros_SourceMap as SourceMap, walkeros_SourcePlatform as SourcePlatform, walkeros_User as User };
+  export type { walkeros_ActionHandler as ActionHandler, walkeros_AnyFunction as AnyFunction, walkeros_AnyObject as AnyObject, walkeros_Consent as Consent, walkeros_ConsentHandler as ConsentHandler, walkeros_DeepPartial as DeepPartial, walkeros_DeepPartialEvent as DeepPartialEvent, walkeros_Elb as Elb, walkeros_Entities as Entities, walkeros_Entity as Entity, walkeros_Event as Event, walkeros_Events as Events, walkeros_OrderedProperties as OrderedProperties, walkeros_PartialEvent as PartialEvent, walkeros_PromiseOrValue as PromiseOrValue, walkeros_Properties as Properties, walkeros_Property as Property, walkeros_PropertyType as PropertyType, walkeros_SingleOrArray as SingleOrArray, walkeros_Source as Source, walkeros_SourceFields as SourceFields, walkeros_SourceMap as SourceMap, walkeros_SourcePlatform as SourcePlatform, walkeros_User as User, walkeros_UserFields as UserFields };
 }
 
 /**
@@ -4513,12 +4539,12 @@ declare function getMappingEvent(event: DeepPartialEvent | PartialEvent | Event,
 /**
  * Gets a value from a mapping.
  *
- * @param value The value to get the mapping from.
- * @param data The mapping data.
- * @param options The mapping options.
- * @returns The mapped value.
+ * @param value The source to resolve the mapping against, usually an event.
+ * @param data The mapping data: a key path, a value config, or a list of them.
+ * @param context The collector (required), plus an optional event and consent.
+ * @returns The mapped value, or undefined when the value is undefined.
  */
-declare function getMappingValue(value: DeepPartialEvent | unknown | undefined, data?: Data$1, context?: Partial<Context$6>): Promise<Property | undefined>;
+declare function getMappingValue(value: DeepPartialEvent | unknown | undefined, data: Data$1 | undefined, context: ValueContext): Promise<Property | undefined>;
 /**
  * Processes an event through mapping configuration.
  *