ts-rules-composer 1.0.1 → 1.0.2

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.cts CHANGED
@@ -1,7 +1,4 @@
1
- type Prettify<T> = {
2
- [K in keyof T]: T[K];
3
- } & {};
4
-
1
+ type Prettify<T> = { [K in keyof T]: T[K]; } & {};
5
2
  /**
6
3
  * Configuration options for error handling behavior in rule combinators
7
4
  * @template TError - The type of the error that will be caught and transformed (when safe)
@@ -33,13 +30,12 @@ type Prettify<T> = {
33
30
  * });
34
31
  */
35
32
  type RuleSafetyOptions<TError = unknown> = {
36
- errorHandlingMode?: "safe" | "unsafe";
37
- errorTransform?: (error: unknown) => TError;
33
+ errorHandlingMode?: "safe" | "unsafe";
34
+ errorTransform?: (error: unknown) => TError;
38
35
  };
39
-
40
36
  /**
41
37
  * Options for rule composition functions.
42
- * @property cloneContext - Whether to clone the context for each rule
38
+ * @property cloneContext - Whether to clone the context once per composed invocation
43
39
  * @property cloneStrategy - Which strategy to use when cloning the context
44
40
  * @property errorHandling - Determines how the combinator handles thrown errors
45
41
  * - "safe": (default) Catches errors and converts them to failed RuleResults
@@ -61,10 +57,9 @@ type RuleSafetyOptions<TError = unknown> = {
61
57
  * - Circular references fail silently in JSON clone mode
62
58
  */
63
59
  type CompositionOptions<TError = string> = Prettify<{
64
- cloneContext?: boolean;
65
- cloneStrategy?: "shallow" | "json" | "structured";
60
+ cloneContext?: boolean;
61
+ cloneStrategy?: "shallow" | "json" | "structured";
66
62
  } & RuleSafetyOptions<TError>>;
67
-
68
63
  /**
69
64
  * Represents the result of a rule evaluation.
70
65
  * @template TError - The type of the error (defaults to string)
@@ -79,12 +74,11 @@ type CompositionOptions<TError = string> = Prettify<{
79
74
  * };
80
75
  */
81
76
  type RuleResult<TError = string> = {
82
- readonly status: "passed";
77
+ readonly status: "passed";
83
78
  } | {
84
- readonly status: "failed";
85
- readonly error: TError;
79
+ readonly status: "failed";
80
+ readonly error: TError;
86
81
  };
87
-
88
82
  /**
89
83
  * Configuration options for debug functionality.
90
84
  * @template TInput - The type of the input to validate
@@ -96,43 +90,24 @@ type RuleResult<TError = string> = {
96
90
  * @property onError - Called when rule throws
97
91
  */
98
92
  type DebugOptions<TInput, TError, TContext> = {
99
- /** Unique identifier for the rule */
100
- name?: string;
101
- /** Called before rule execution */
102
- onStart?: (input: TInput, context?: TContext) => void;
103
- /** Called after rule completes */
104
- onEnd?: (input: TInput, result: RuleResult<TError>, context?: TContext, meta?: {
105
- ruleName: string;
106
- duration: number;
107
- startTime: number;
108
- }) => void;
109
- /** Called when rule throws */
110
- onError?: (error: unknown, input: TInput, context?: TContext, duration?: number) => void;
93
+ /** Unique identifier for the rule */
94
+ name?: string;
95
+ /** Called before rule execution */
96
+ onStart?: (input: TInput, context?: TContext) => void;
97
+ /** Called after rule completes */
98
+ onEnd?: (input: TInput, result: RuleResult<TError>, context?: TContext, meta?: {
99
+ ruleName: string;
100
+ duration: number;
101
+ startTime: number;
102
+ }) => void;
103
+ /** Called when rule throws */
104
+ onError?: (error: unknown, input: TInput, context?: TContext, duration?: number) => void;
111
105
  };
112
-
113
- /**
114
- * A function that validates an input and returns a RuleResult.
115
- * @template TInput - The type of the input to validate
116
- * @template TError - The type of the error (defaults to string)
117
- * @template TContext - The type of the context object (optional)
118
- * @param input - The input value to validate
119
- * @param context - Optional context object that can be used during validation
120
- * @returns Either a Promise of RuleResult or RuleResult directly
121
- * @example
122
- * const isEven: Rule<number> = (input) => {
123
- * return input % 2 === 0
124
- * ? { status: "passed" }
125
- * : { status: "failed", error: "Number must be even" };
126
- * };
127
- */
128
- type Rule<TInput, TError = string, TContext = unknown> = (input: TInput, context?: TContext) => Promise<RuleResult<TError>> | RuleResult<TError>;
129
-
130
106
  /**
131
107
  * A predicate function that evaluates an input and returns a boolean result.
132
108
  * Can be synchronous or asynchronous.
133
109
  */
134
110
  type Predicate<TInput, TContext> = (input: TInput, context?: TContext) => boolean | Promise<boolean>;
135
-
136
111
  /**
137
112
  * Represents the result of a predicate evaluation.
138
113
  * @template TError - The type of the error (defaults to string)
@@ -151,19 +126,33 @@ type Predicate<TInput, TContext> = (input: TInput, context?: TContext) => boolea
151
126
  * };
152
127
  */
153
128
  type PredicateResult<TError = string> = {
154
- readonly status: "passed";
155
- value: boolean;
129
+ readonly status: "passed";
130
+ value: boolean;
156
131
  } | {
157
- readonly status: "failed";
158
- readonly error: TError;
132
+ readonly status: "failed";
133
+ readonly error: TError;
159
134
  };
160
-
161
135
  /**
162
136
  * A predicate function that evaluates an input and returns a PredicateResult.
163
137
  * Can be synchronous or asynchronous.
164
138
  */
165
139
  type PredicateSafe<TInput, TError, TContext> = (input: TInput, context?: TContext) => PredicateResult<TError> | Promise<PredicateResult<TError>>;
166
-
140
+ /**
141
+ * A function that validates an input and returns a RuleResult.
142
+ * @template TInput - The type of the input to validate
143
+ * @template TError - The type of the error (defaults to string)
144
+ * @template TContext - The type of the context object (optional)
145
+ * @param input - The input value to validate
146
+ * @param context - Optional context object that can be used during validation
147
+ * @returns Either a Promise of RuleResult or RuleResult directly
148
+ * @example
149
+ * const isEven: Rule<number> = (input) => {
150
+ * return input % 2 === 0
151
+ * ? { status: "passed" }
152
+ * : { status: "failed", error: "Number must be even" };
153
+ * };
154
+ */
155
+ type Rule<TInput, TError = string, TContext = unknown> = (input: TInput, context?: TContext) => Promise<RuleResult<TError>> | RuleResult<TError>;
167
156
  /**
168
157
  * Composes multiple rules into a single rule that runs them all and collects all errors.
169
158
  * @template TInput - The type of the input to validate
@@ -171,7 +160,7 @@ type PredicateSafe<TInput, TError, TContext> = (input: TInput, context?: TContex
171
160
  * @template TContext - The type of the context object (optional)
172
161
  * @param rules - Array of rules to compose
173
162
  * @param options - Configuration options
174
- * @param options.cloneContext - Whether to clone the context for each rule (default: false)
163
+ * @param options.cloneContext - Whether to clone the context once per composed invocation (default: false)
175
164
  * @param options.cloneStrategy -Which strategy to use when cloning the context
176
165
  * @param options.errorHandlingMode - Determines how errors are handled:
177
166
  * - 'safe': (default) Converts thrown errors to validation failures
@@ -197,8 +186,7 @@ type PredicateSafe<TInput, TError, TContext> = (input: TInput, context?: TContex
197
186
  * 2. Uses structuredClone if available and options.structuredClone = true
198
187
  * 3. Falls back to JSON clone otherwise
199
188
  */
200
- declare const every: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: CompositionOptions<TError>) => Rule<TInput, TError[], TContext>;
201
-
189
+ export declare const every: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: CompositionOptions<TError>) => Rule<TInput, TError[], TContext>;
202
190
  /**
203
191
  * Configuration options for error handling behavior in rule combinators
204
192
  * @template TError - The type of the error that will be caught and transformed (when safe)
@@ -224,11 +212,9 @@ declare const every: <TInput, TError = string, TContext = unknown>(rules: Rule<T
224
212
  * );
225
213
  */
226
214
  type PredicateSafetyOptions<TError = unknown> = {
227
- predicateErrorTransform?: (error: unknown) => TError;
215
+ predicateErrorTransform?: (error: unknown) => TError;
228
216
  };
229
-
230
217
  type SafetyOptions<TError = unknown> = Prettify<RuleSafetyOptions<TError> & PredicateSafetyOptions<TError>>;
231
-
232
218
  /**
233
219
  * Conditionally executes one of two rules based on a predicate
234
220
  * @template TInput - The type of the input to validate
@@ -257,8 +243,7 @@ type SafetyOptions<TError = unknown> = Prettify<RuleSafetyOptions<TError> & Pred
257
243
  * validateAdultAccount
258
244
  * );
259
245
  */
260
- declare const ifElse: <TInput, TError = string, TContext = unknown>(predicate: Predicate<TInput, TContext>, ifRule: Rule<TInput, TError, TContext>, elseRule?: Rule<TInput, TError, TContext>, options?: SafetyOptions<TError>) => Rule<TInput, TError, TContext>;
261
-
246
+ export declare const ifElse: <TInput, TError = string, TContext = unknown>(predicate: Predicate<TInput, TContext>, ifRule: Rule<TInput, TError, TContext>, elseRule?: Rule<TInput, TError, TContext>, options?: SafetyOptions<TError>) => Rule<TInput, TError, TContext>;
262
247
  /**
263
248
  * Pattern-matching combinator that selects a rule based on a key extracted from input.
264
249
  * @template TInput - The type of the input to validate
@@ -317,8 +302,7 @@ declare const ifElse: <TInput, TError = string, TContext = unknown>(predicate: P
317
302
  * - All case rules must have compatible input/context types
318
303
  * - For conditional branching (true/false), consider using `branch` instead
319
304
  */
320
- declare const match: <TInput, TError = string, TContext = unknown, TKey extends string | number | symbol = string>(accessor: (input: TInput, context?: TContext) => TKey | Promise<TKey>, cases: Record<TKey, Rule<TInput, TError, TContext>>, defaultCase?: Rule<TInput, TError, TContext> | TError, options?: RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>;
321
-
305
+ export declare const match: <TInput, TError = string, TContext = unknown, TKey extends string | number | symbol = string>(accessor: (input: TInput, context?: TContext) => TKey | Promise<TKey>, cases: Record<TKey, Rule<TInput, TError, TContext>>, defaultCase?: Rule<TInput, TError, TContext> | TError, options?: RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>;
322
306
  /**
323
307
  * Inverts the logic of a rule - passes when original fails and vice versa.
324
308
  * @template TInput - The type of the input to validate
@@ -337,8 +321,7 @@ declare const match: <TInput, TError = string, TContext = unknown, TKey extends
337
321
  * - The original rule's error is discarded when it fails
338
322
  * - Always uses the provided error when original passes
339
323
  */
340
- declare const not: <TInput, TError = string>(rule: Rule<TInput, TError>, error: TError, options?: RuleSafetyOptions<TError>) => Rule<TInput, TError>;
341
-
324
+ export declare const not: <TInput, TError = string>(rule: Rule<TInput, TError>, error: TError, options?: RuleSafetyOptions<TError>) => Rule<TInput, TError>;
342
325
  /**
343
326
  * Creates a rule that passes if any of the provided rules pass (short-circuiting).
344
327
  * @template TInput - The type of the input to validate
@@ -361,8 +344,7 @@ declare const not: <TInput, TError = string>(rule: Rule<TInput, TError>, error:
361
344
  * - Rules are executed in sequence until one passes
362
345
  * - Returns all errors if all rules fail
363
346
  */
364
- declare const oneOf: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: RuleSafetyOptions<TError>) => Rule<TInput, TError[], TContext>;
365
-
347
+ export declare const oneOf: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: RuleSafetyOptions<TError>) => Rule<TInput, TError[], TContext>;
366
348
  /**
367
349
  * Executes a rule only if the predicate returns false.
368
350
  * @template TInput - The type of the input to validate
@@ -386,8 +368,7 @@ declare const oneOf: <TInput, TError = string, TContext = unknown>(rules: Rule<T
386
368
  * - Opposite behavior of `when`
387
369
  * - Automatically passes when predicate is true
388
370
  */
389
- declare const unless: <TInput, TError = string, TContext = unknown>(predicate: Predicate<TInput, TContext>, rule: Rule<TInput, TError, TContext>, options?: SafetyOptions<TError>) => Rule<TInput, TError, TContext>;
390
-
371
+ export declare const unless: <TInput, TError = string, TContext = unknown>(predicate: Predicate<TInput, TContext>, rule: Rule<TInput, TError, TContext>, options?: SafetyOptions<TError>) => Rule<TInput, TError, TContext>;
391
372
  /**
392
373
  * Conditionally executes a rule based on a predicate.
393
374
  * Similar to branch but without an else case.
@@ -411,8 +392,7 @@ declare const unless: <TInput, TError = string, TContext = unknown>(predicate: P
411
392
  * - The predicate can be async
412
393
  * - If predicate returns false, the rule automatically passes
413
394
  */
414
- declare const when: <TInput, TError = string, TContext = unknown>(predicate: Predicate<TInput, TContext>, rule: Rule<TInput, TError, TContext>, options?: SafetyOptions<TError>) => Rule<TInput, TError, TContext>;
415
-
395
+ export declare const when: <TInput, TError = string, TContext = unknown>(predicate: Predicate<TInput, TContext>, rule: Rule<TInput, TError, TContext>, options?: SafetyOptions<TError>) => Rule<TInput, TError, TContext>;
416
396
  /**
417
397
  * Creates a rule that falls back to an alternative rule if the main rule fails.
418
398
  * @template TInput - Input type
@@ -434,10 +414,9 @@ declare const when: <TInput, TError = string, TContext = unknown>(predicate: Pre
434
414
  * { onlyFallbackOn: err => err.code !== 'FATAL' }
435
415
  * );
436
416
  */
437
- declare const withFallback: <TInput, TError, TContext>(mainRule: Rule<TInput, TError, TContext>, fallbackRule: Rule<TInput, TError, TContext>, options?: RuleSafetyOptions<TError> & {
438
- onlyFallbackOn?: (error: TError) => boolean;
417
+ export declare const withFallback: <TInput, TError, TContext>(mainRule: Rule<TInput, TError, TContext>, fallbackRule: Rule<TInput, TError, TContext>, options?: RuleSafetyOptions<TError> & {
418
+ onlyFallbackOn?: (error: TError) => boolean;
439
419
  }) => Rule<TInput, TError, TContext>;
440
-
441
420
  /**
442
421
  * Injects a dependency into a rule creation function, returning a configured rule.
443
422
  * @template TInput - The type of the input to validate
@@ -454,8 +433,7 @@ declare const withFallback: <TInput, TError, TContext>(mainRule: Rule<TInput, TE
454
433
  * @caveats
455
434
  * - The dependency is injected at rule creation time, not execution time
456
435
  */
457
- declare const inject: <TInput, TError, TDep>(dependency: TDep, rule: (dep: TDep) => Rule<TInput, TError>) => Rule<TInput, TError>;
458
-
436
+ export declare const inject: <TInput, TError, TDep>(dependency: TDep, rule: (dep: TDep) => Rule<TInput, TError>) => Rule<TInput, TError>;
459
437
  /**
460
438
  * Transforms the error of a rule using a mapping function.
461
439
  * @template TInput - The type of the input to validate
@@ -479,8 +457,7 @@ declare const inject: <TInput, TError, TDep>(dependency: TDep, rule: (dep: TDep)
479
457
  * - Only transforms failed results, passes successful results through unchanged
480
458
  * - The transform function is not called for successful results
481
459
  */
482
- declare const mapError: <TInput, TError, TNewError>(rule: Rule<TInput, TError>, transform: (error: TError) => TNewError) => Rule<TInput, TNewError>;
483
-
460
+ export declare const mapError: <TInput, TError, TNewError>(rule: Rule<TInput, TError>, transform: (error: TError) => TNewError) => Rule<TInput, TNewError>;
484
461
  /**
485
462
  * Creates a standalone tap effect for use in composition pipelines
486
463
  * @template TInput - Input type
@@ -494,32 +471,7 @@ declare const mapError: <TInput, TError, TNewError>(rule: Rule<TInput, TError>,
494
471
  * validateInput
495
472
  * ])
496
473
  */
497
- declare const tap: <TInput, TError = string, TContext = unknown>(effect: (input: TInput, context?: TContext) => Promise<void> | void) => Rule<TInput, TError, TContext>;
498
-
499
- /**
500
- * Creates a rule wrapper that performs side effects without modifying the result.
501
- * @template TInput - The type of the input to validate
502
- * @template TError - The type of the error (defaults to string)
503
- * @template TContext - The type of the context object (optional)
504
- * @param effect - Side effect function receiving input, result and context
505
- * @param options - Configuration for error handling safety
506
- * @param options.errorHandlingMode - Determines how errors are handled:
507
- * - 'safe': (default) Converts thrown errors to validation failures
508
- * - 'unsafe': Lets errors propagate (use only in performance-critical paths)
509
- * @param options.errorTransform - Custom transformation for caught errors
510
- * @returns A function that wraps a rule with the tap effect
511
- * @example
512
- * const withLogging = tap((input, result) => {
513
- * console.log(`Validation result for ${input}:`, result);
514
- * });
515
- *
516
- * const rule = withLogging(validateInput);
517
- * @caveats
518
- * - Errors in the effect are caught and logged but don't affect rule execution
519
- * - Doesn't modify the rule's result
520
- */
521
- declare const withTap: <TInput, TError = string, TContext = unknown>(effect: (input: TInput, result: RuleResult<TError>, context?: TContext) => Promise<void> | void, options?: RuleSafetyOptions<TError>) => ((rule: Rule<TInput, TError, TContext>) => Rule<TInput, TError, TContext>);
522
-
474
+ export declare const tap: <TInput, TError = string, TContext = unknown>(effect: (input: TInput, context?: TContext) => Promise<void> | void) => Rule<TInput, TError, TContext>;
523
475
  /**
524
476
  * Creates a rule that extracts a value using a getter function and validates it.
525
477
  * @template TInput - The type of the input object
@@ -560,8 +512,7 @@ declare const withTap: <TInput, TError = string, TContext = unknown>(effect: (in
560
512
  * - Defaults are applied before rule execution (the rule sees the default value)
561
513
  * - Default values aren't type-checked against potentially undefined returns
562
514
  */
563
- declare function validateField<TInput, TValue, TError = string, TContext = unknown>(getter: (input: TInput) => TValue | undefined, rule: Rule<TValue, TError, TContext>, defaultValue?: TValue, options?: RuleSafetyOptions<TError>): Rule<TInput, TError, TContext>;
564
-
515
+ export declare function validateField<TInput, TValue, TError = string, TContext = unknown>(getter: (input: TInput) => TValue | undefined, rule: Rule<TValue, TError, TContext>, defaultValue?: TValue, options?: RuleSafetyOptions<TError>): Rule<TInput, TError, TContext>;
565
516
  /**
566
517
  * Wraps a rule with debugging capabilities.
567
518
  * @template TInput - The type of the input to validate
@@ -586,8 +537,7 @@ declare function validateField<TInput, TValue, TError = string, TContext = unkno
586
537
  * - Debug callbacks are executed synchronously and may impact performance
587
538
  * - Errors in callbacks will propagate and potentially mask rule errors
588
539
  */
589
- declare const withDebug: <TInput, TError, TContext>(rule: Rule<TInput, TError, TContext>, options: DebugOptions<TInput, TError, TContext> | string) => Rule<TInput, TError, TContext>;
590
-
540
+ export declare const withDebug: <TInput, TError, TContext>(rule: Rule<TInput, TError, TContext>, options: DebugOptions<TInput, TError, TContext> | string) => Rule<TInput, TError, TContext>;
591
541
  /**
592
542
  * Creates a memoized version of a rule that caches results based on input keys.
593
543
  * @template TInput - The type of the input to validate
@@ -616,12 +566,11 @@ declare const withDebug: <TInput, TError, TContext>(rule: Rule<TInput, TError, T
616
566
  * - Successful results obey TTL rules
617
567
  * - Cache is shared across rule instances
618
568
  */
619
- declare const withMemoize: <TInput, TError = string, TContext = unknown>(rule: Rule<TInput, TError, TContext>, keyFn: (input: TInput) => string, options?: {
620
- ttl?: number;
621
- maxSize?: number;
569
+ export declare const withMemoize: <TInput, TError = string, TContext = unknown>(rule: Rule<TInput, TError, TContext>, keyFn: (input: TInput) => string, options?: {
570
+ ttl?: number;
571
+ maxSize?: number;
622
572
  } & RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>;
623
-
624
- type RetryStrategy = "fixed" | "linear" | "exponential" | ((attempt: number) => number);
573
+ export type RetryStrategy = "fixed" | "linear" | "exponential" | ((attempt: number) => number);
625
574
  /**
626
575
  * Wraps a rule with retry logic for handling transient failures.
627
576
  * @template TInput - The type of the input to validate
@@ -643,13 +592,12 @@ type RetryStrategy = "fixed" | "linear" | "exponential" | ((attempt: number) =>
643
592
  * - Only retries on failed RuleResults, not on thrown exceptions
644
593
  * - The final error will be "MAX_RETRIES_EXCEEDED" if all attempts fail
645
594
  */
646
- declare const withRetry: <TInput, TError = string, TContext = unknown>(rule: Rule<TInput, TError, TContext>, options?: {
647
- attempts?: number;
648
- delayMs?: number;
649
- retryStrategy?: RetryStrategy;
650
- shouldRetry?: (error: TError | unknown, attempt: number) => boolean;
595
+ export declare const withRetry: <TInput, TError = string, TContext = unknown>(rule: Rule<TInput, TError, TContext>, options?: {
596
+ attempts?: number;
597
+ delayMs?: number;
598
+ retryStrategy?: RetryStrategy;
599
+ shouldRetry?: (error: TError | unknown, attempt: number) => boolean;
651
600
  }) => Rule<TInput, TError | "MAX_RETRIES_EXCEEDED", TContext>;
652
-
653
601
  /**
654
602
  * Wraps a rule to catch errors and convert them to failed RuleResults
655
603
  * @template TInput - The input type
@@ -673,8 +621,7 @@ declare const withRetry: <TInput, TError = string, TContext = unknown>(rule: Rul
673
621
  * - Generic parameters must be explicitly set for custom error types
674
622
  * - Doesn't verify error types match TError at runtime
675
623
  */
676
- declare const withSafeError: <TInput, TError = string, TContext = unknown>(rule: Rule<TInput, TError, TContext>, errorTransform?: (error: unknown) => TError) => Rule<TInput, TError, TContext>;
677
-
624
+ export declare const withSafeError: <TInput, TError = string, TContext = unknown>(rule: Rule<TInput, TError, TContext>, errorTransform?: (error: unknown) => TError) => Rule<TInput, TError, TContext>;
678
625
  /**
679
626
  * Wraps a predicate function with error handling and type safety.
680
627
  * @template TInput - The input type
@@ -702,8 +649,30 @@ declare const withSafeError: <TInput, TError = string, TContext = unknown>(rule:
702
649
  * - Returns failed result for Promise rejections (transformed via errorTransform)
703
650
  * - Returns failed result for thrown non-Error values (like `throw "string"`)
704
651
  */
705
- declare const withSafePredicate: <TInput, TError = string, TContext = unknown>(predicate: Predicate<TInput, TContext>, errorTransform?: (error: unknown) => TError) => PredicateSafe<TInput, TError, TContext>;
706
-
652
+ export declare const withSafePredicate: <TInput, TError = string, TContext = unknown>(predicate: Predicate<TInput, TContext>, errorTransform?: (error: unknown) => TError) => PredicateSafe<TInput, TError, TContext>;
653
+ /**
654
+ * Creates a rule wrapper that performs side effects without modifying the result.
655
+ * @template TInput - The type of the input to validate
656
+ * @template TError - The type of the error (defaults to string)
657
+ * @template TContext - The type of the context object (optional)
658
+ * @param effect - Side effect function receiving input, result and context
659
+ * @param options - Configuration for error handling safety
660
+ * @param options.errorHandlingMode - Determines how errors are handled:
661
+ * - 'safe': (default) Converts thrown errors to validation failures
662
+ * - 'unsafe': Lets errors propagate (use only in performance-critical paths)
663
+ * @param options.errorTransform - Custom transformation for caught errors
664
+ * @returns A function that wraps a rule with the tap effect
665
+ * @example
666
+ * const withLogging = tap((input, result) => {
667
+ * console.log(`Validation result for ${input}:`, result);
668
+ * });
669
+ *
670
+ * const rule = withLogging(validateInput);
671
+ * @caveats
672
+ * - Errors in the effect are caught and logged but don't affect rule execution
673
+ * - Doesn't modify the rule's result
674
+ */
675
+ export declare const withTap: <TInput, TError = string, TContext = unknown>(effect: (input: TInput, result: RuleResult<TError>, context?: TContext) => Promise<void> | void, options?: RuleSafetyOptions<TError>) => ((rule: Rule<TInput, TError, TContext>) => Rule<TInput, TError, TContext>);
707
676
  /**
708
677
  * Wraps a rule with timeout functionality.
709
678
  * @template TInput - The type of the input to validate
@@ -728,8 +697,7 @@ declare const withSafePredicate: <TInput, TError = string, TContext = unknown>(p
728
697
  * - The original rule's execution isn't aborted when timeout occurs
729
698
  * - Only fails if the rule doesn't complete before timeout, not if it fails before timeout
730
699
  */
731
- declare const withTimeout: <TInput, TError, TContext>(rule: Rule<TInput, TError, TContext>, timeoutMs: number, timeoutError: TError, options?: RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>;
732
-
700
+ export declare const withTimeout: <TInput, TError, TContext>(rule: Rule<TInput, TError, TContext>, timeoutMs: number, timeoutError: TError, options?: RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>;
733
701
  /**
734
702
  * Composes multiple rules into a single rule that runs them in right-to-left order (fail-fast).
735
703
  * Stops at the first failure and returns the error.
@@ -739,7 +707,7 @@ declare const withTimeout: <TInput, TError, TContext>(rule: Rule<TInput, TError,
739
707
  * @template TContext - The type of the context object (optional)
740
708
  * @param rules - Array of rules to compose
741
709
  * @param options - Configuration options
742
- * @param options.cloneContext - Whether to clone the context for each rule (default: false)
710
+ * @param options.cloneContext - Whether to clone the context once per composed invocation (default: false)
743
711
  * @param options.errorHandlingMode - Determines how errors are handled:
744
712
  * - 'safe': (default) Converts thrown errors to validation failures
745
713
  * - 'unsafe': Lets errors propagate (use only in performance-critical paths)
@@ -763,8 +731,36 @@ declare const withTimeout: <TInput, TError, TContext>(rule: Rule<TInput, TError,
763
731
  * 2. Uses structuredClone if available and options.structuredClone = true
764
732
  * 3. Falls back to JSON clone otherwise
765
733
  */
766
- declare const composeRules: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: CompositionOptions) => Rule<TInput, TError, TContext>;
767
-
734
+ export declare const composeRules: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: CompositionOptions<TError>) => Rule<TInput, TError, TContext>;
735
+ /**
736
+ * Pipes a value through a series of functions (left-to-right composition).
737
+ * @template A - The input type
738
+ * @template B - The output type after first function
739
+ * @param value - The initial value
740
+ * @param fns - Functions to apply sequentially
741
+ * @returns The result of applying all functions to the initial value
742
+ * @example
743
+ * const result = pipe(
744
+ * 5,
745
+ * (x) => x * 2,
746
+ * (x) => x + 3,
747
+ * (x) => `Result: ${x}`
748
+ * ); // "Result: 13"
749
+ * @caveats
750
+ * - Currently supports up to 10 functions with proper type inference
751
+ * - For more functions, type information will be lost
752
+ */
753
+ export declare function pipe<A>(value: A): A;
754
+ export declare function pipe<A, B>(value: A, fn1: (arg: A) => B): B;
755
+ export declare function pipe<A, B, C>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C): C;
756
+ export declare function pipe<A, B, C, D>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D): D;
757
+ export declare function pipe<A, B, C, D, E>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E): E;
758
+ export declare function pipe<A, B, C, D, E, F>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F): F;
759
+ export declare function pipe<A, B, C, D, E, F, G>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G): G;
760
+ export declare function pipe<A, B, C, D, E, F, G, H>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G, fn7: (arg: G) => H): H;
761
+ export declare function pipe<A, B, C, D, E, F, G, H, I>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G, fn7: (arg: G) => H, fn8: (arg: H) => I): I;
762
+ export declare function pipe<A, B, C, D, E, F, G, H, I, J>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G, fn7: (arg: G) => H, fn8: (arg: H) => I, fn9: (arg: I) => J): J;
763
+ export declare function pipe<A, B, C, D, E, F, G, H, I, J, K>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G, fn7: (arg: G) => H, fn8: (arg: H) => I, fn9: (arg: I) => J, fn10: (arg: J) => K): K;
768
764
  /**
769
765
  * Pipes multiple rules into a single rule that runs them sequentially (fail-fast).
770
766
  * Stops at the first failure and returns the error.
@@ -773,7 +769,7 @@ declare const composeRules: <TInput, TError = string, TContext = unknown>(rules:
773
769
  * @template TContext - The type of the context object (optional)
774
770
  * @param rules - Array of rules to compose
775
771
  * @param options - Configuration options
776
- * @param options.cloneContext - Whether to clone the context for each rule (default: false)
772
+ * @param options.cloneContext - Whether to clone the context once per composed invocation (default: false)
777
773
  * @param options.errorHandlingMode - Determines how errors are handled:
778
774
  * - 'safe': (default) Converts thrown errors to validation failures
779
775
  * - 'unsafe': Lets errors propagate (use only in performance-critical paths)
@@ -795,38 +791,7 @@ declare const composeRules: <TInput, TError = string, TContext = unknown>(rules:
795
791
  * 2. Uses structuredClone if available and options.structuredClone = true
796
792
  * 3. Falls back to JSON clone otherwise
797
793
  */
798
- declare const pipeRules: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: CompositionOptions) => Rule<TInput, TError, TContext>;
799
-
800
- /**
801
- * Pipes a value through a series of functions (left-to-right composition).
802
- * @template A - The input type
803
- * @template B - The output type after first function
804
- * @param value - The initial value
805
- * @param fns - Functions to apply sequentially
806
- * @returns The result of applying all functions to the initial value
807
- * @example
808
- * const result = pipe(
809
- * 5,
810
- * (x) => x * 2,
811
- * (x) => x + 3,
812
- * (x) => `Result: ${x}`
813
- * ); // "Result: 13"
814
- * @caveats
815
- * - Currently supports up to 10 functions with proper type inference
816
- * - For more functions, type information will be lost
817
- */
818
- declare function pipe<A>(value: A): A;
819
- declare function pipe<A, B>(value: A, fn1: (arg: A) => B): B;
820
- declare function pipe<A, B, C>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C): C;
821
- declare function pipe<A, B, C, D>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D): D;
822
- declare function pipe<A, B, C, D, E>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E): E;
823
- declare function pipe<A, B, C, D, E, F>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F): F;
824
- declare function pipe<A, B, C, D, E, F, G>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G): G;
825
- declare function pipe<A, B, C, D, E, F, G, H>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G, fn7: (arg: G) => H): H;
826
- declare function pipe<A, B, C, D, E, F, G, H, I>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G, fn7: (arg: G) => H, fn8: (arg: H) => I): I;
827
- declare function pipe<A, B, C, D, E, F, G, H, I, J>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G, fn7: (arg: G) => H, fn8: (arg: H) => I, fn9: (arg: I) => J): J;
828
- declare function pipe<A, B, C, D, E, F, G, H, I, J, K>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D, fn4: (arg: D) => E, fn5: (arg: E) => F, fn6: (arg: F) => G, fn7: (arg: G) => H, fn8: (arg: H) => I, fn9: (arg: I) => J, fn10: (arg: J) => K): K;
829
-
794
+ export declare const pipeRules: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: CompositionOptions<TError>) => Rule<TInput, TError, TContext>;
830
795
  /**
831
796
  * Type guard to check if context exists and is of type T.
832
797
  * @template T - The expected context type
@@ -837,8 +802,7 @@ declare function pipe<A, B, C, D, E, F, G, H, I, J, K>(value: A, fn1: (arg: A) =
837
802
  * // context is now typed as AdminContext
838
803
  * }
839
804
  */
840
- declare const hasContext: <T>(ctx: T | undefined) => ctx is T;
841
-
805
+ export declare const hasContext: <T>(ctx: T | undefined) => ctx is T;
842
806
  /**
843
807
  * Creates a rule that requires specific context to be present.
844
808
  * @template TInput - The type of the input to validate
@@ -859,8 +823,21 @@ declare const hasContext: <T>(ctx: T | undefined) => ctx is T;
859
823
  * - Fails immediately if context check fails
860
824
  * - Provides type safety for context requirements
861
825
  */
862
- declare const requireContextRule: <TInput, TError, TContext, TRequiredContext extends TContext>(error: TError, rule: (input: TInput, context: TRequiredContext) => Promise<RuleResult<TError>> | RuleResult<TError>, contextCheck?: (context: TContext | undefined) => context is TRequiredContext) => Rule<TInput, TError, TContext>;
826
+ export declare const requireContextRule: <TInput, TError, TContext, TRequiredContext extends TContext>(error: TError, rule: (input: TInput, context: TRequiredContext) => Promise<RuleResult<TError>> | RuleResult<TError>, contextCheck?: (context: TContext | undefined) => context is TRequiredContext) => Rule<TInput, TError, TContext>;
827
+ /**
828
+ * const userRule = requireContextRule(
829
+ "User context required",
830
+ (input: string, ctx: { userId: string }) => {
831
+ return ctx.userId === "admin"
832
+ ? pass()
833
+ : fail("Unauthorized");
834
+ }
835
+ );
863
836
 
837
+ await userRule("action"); // fails with "User context required"
838
+ await userRule("action", { userId: "user" }); // fails with "Unauthorized"
839
+ await userRule("action", { userId: "admin" }); // passes
840
+ */
864
841
  /**
865
842
  * Creates a rule that loads context lazily before execution.
866
843
  * @template TInput - The type of the input to validate
@@ -878,8 +855,7 @@ declare const requireContextRule: <TInput, TError, TContext, TRequiredContext ex
878
855
  * - Context loading failures are converted to validation failures
879
856
  * - The loader is called for every rule execution
880
857
  */
881
- declare const withLazyContext: <TInput, TError, TContext>(loader: (input: TInput) => Promise<TContext> | TContext, rule: Rule<TInput, TError, TContext>) => Rule<TInput, TError>;
882
-
858
+ export declare const withLazyContext: <TInput, TError, TContext>(loader: (input: TInput) => Promise<TContext> | TContext, rule: Rule<TInput, TError, TContext>) => Rule<TInput, TError>;
883
859
  /**
884
860
  * Creates a failed RuleResult with the provided error.
885
861
  * @template TError - The type of the error (defaults to string)
@@ -891,8 +867,7 @@ declare const withLazyContext: <TInput, TError, TContext>(loader: (input: TInput
891
867
  * // Used in rule implementations:
892
868
  * const alwaysFails: Rule<string> = () => fail("Always fails");
893
869
  */
894
- declare const fail: <TError = string>(error: TError) => RuleResult<TError>;
895
-
870
+ export declare const fail: <TError = string>(error: TError) => RuleResult<TError>;
896
871
  /**
897
872
  * Creates a successful RuleResult with "passed" status.
898
873
  * @template TError - The type of the error (defaults to string)
@@ -903,12 +878,9 @@ declare const fail: <TError = string>(error: TError) => RuleResult<TError>;
903
878
  * // Used in rule implementations:
904
879
  * const alwaysPasses: Rule<string> = () => pass();
905
880
  */
906
- declare const pass: <TError = string>() => RuleResult<TError>;
907
-
908
- declare const calculateDelay: (strategy: RetryStrategy | undefined, attempt: number, initialDelayMs: number) => number;
909
-
910
- declare const getNormalizedRule: <TInput, TError, TContext>(rule: Rule<TInput, TError, TContext>, opts?: RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>;
911
-
912
- declare const getNormalizedRules: <TInput, TError, TContext>(rules: Rule<TInput, TError, TContext>[], opts?: RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>[];
913
-
914
- export { type CompositionOptions, type DebugOptions, type Predicate, type PredicateResult, type PredicateSafe, type RetryStrategy, type Rule, type RuleResult, type RuleSafetyOptions, calculateDelay, composeRules, every, fail, getNormalizedRule, getNormalizedRules, hasContext, ifElse, inject, mapError, match, not, oneOf, pass, pipe, pipeRules, requireContextRule, tap, unless, validateField, when, withDebug, withFallback, withLazyContext, withMemoize, withRetry, withSafeError, withSafePredicate, withTap, withTimeout };
881
+ export declare const pass: <TError = string>() => RuleResult<TError>;
882
+ export declare const calculateDelay: (strategy: RetryStrategy | undefined, attempt: number, initialDelayMs: number) => number;
883
+ export declare const getNormalizedRule: <TInput, TError, TContext>(rule: Rule<TInput, TError, TContext>, opts?: RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>;
884
+ export declare const getNormalizedRules: <TInput, TError, TContext>(rules: Rule<TInput, TError, TContext>[], opts?: RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>[];
885
+ export type { CompositionOptions, DebugOptions, Predicate, PredicateResult, PredicateSafe, Rule, RuleResult, RuleSafetyOptions };
886
+ //# sourceMappingURL=index.d.cts.map