ts-rules-composer 1.0.1 → 1.0.3

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,31 +1,29 @@
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)
8
5
  *
9
- * @property errorHandling - Determines how the combinator handles thrown errors
6
+ * @property errorHandlingMode - Determines how the combinator handles thrown errors
10
7
  * - "safe": (default) Catches errors and converts them to failed RuleResults
11
8
  * - "unsafe": Lets errors propagate normally (for performance-critical cases)
12
9
  *
13
10
  * @property errorTransform - Optional custom error transformation function
14
- * Only used when errorHandling="safe". Allows customizing how thrown errors
15
- * are converted to the rule's error type.
11
+ * Allows customizing how thrown errors are converted to the rule's error
12
+ * type. Only valid when errorHandlingMode is "safe" (or omitted); combining
13
+ * it with "unsafe" is a compile error because the transform would never run.
16
14
  *
17
15
  * @example
18
16
  * // Basic usage with default safe handling
19
- * const rule = every([rule1, rule2], { errorHandling: "safe" });
17
+ * const rule = every([rule1, rule2], { errorHandlingMode: "safe" });
20
18
  *
21
19
  * @example
22
20
  * // Unsafe mode for performance
23
- * const rule = every([rule1, rule2], { errorHandling: "unsafe" });
21
+ * const rule = every([rule1, rule2], { errorHandlingMode: "unsafe" });
24
22
  *
25
23
  * @example
26
24
  * // Custom error transformation
27
25
  * const rule = every([rule1, rule2], {
28
- * errorHandling: "safe",
26
+ * errorHandlingMode: "safe",
29
27
  * errorTransform: (err) => ({
30
28
  * code: 500,
31
29
  * message: String(err)
@@ -33,21 +31,23 @@ type Prettify<T> = {
33
31
  * });
34
32
  */
35
33
  type RuleSafetyOptions<TError = unknown> = {
36
- errorHandlingMode?: "safe" | "unsafe";
37
- errorTransform?: (error: unknown) => TError;
34
+ errorHandlingMode?: "safe";
35
+ errorTransform?: (error: unknown) => TError;
36
+ } | {
37
+ errorHandlingMode: "unsafe";
38
+ errorTransform?: never;
38
39
  };
39
-
40
40
  /**
41
41
  * Options for rule composition functions.
42
- * @property cloneContext - Whether to clone the context for each rule
42
+ * @property cloneContext - Whether to clone the context once per composed invocation
43
43
  * @property cloneStrategy - Which strategy to use when cloning the context
44
- * @property errorHandling - Determines how the combinator handles thrown errors
44
+ * @property errorHandlingMode - Determines how the combinator handles thrown errors
45
45
  * - "safe": (default) Catches errors and converts them to failed RuleResults
46
46
  * - "unsafe": Lets errors propagate normally (for performance-critical cases)
47
47
  *
48
48
  * @property errorTransform - Optional custom error transformation function
49
- * Only used when errorHandling="safe". Allows customizing how thrown errors
50
- * are converted to the rule's error type.
49
+ * Allows customizing how thrown errors are converted to the rule's error
50
+ * type. Only valid when errorHandlingMode is "safe" (or omitted).
51
51
  *
52
52
  *
53
53
  * @warn
@@ -61,10 +61,9 @@ type RuleSafetyOptions<TError = unknown> = {
61
61
  * - Circular references fail silently in JSON clone mode
62
62
  */
63
63
  type CompositionOptions<TError = string> = Prettify<{
64
- cloneContext?: boolean;
65
- cloneStrategy?: "shallow" | "json" | "structured";
64
+ cloneContext?: boolean;
65
+ cloneStrategy?: "shallow" | "json" | "structured";
66
66
  } & RuleSafetyOptions<TError>>;
67
-
68
67
  /**
69
68
  * Represents the result of a rule evaluation.
70
69
  * @template TError - The type of the error (defaults to string)
@@ -79,12 +78,11 @@ type CompositionOptions<TError = string> = Prettify<{
79
78
  * };
80
79
  */
81
80
  type RuleResult<TError = string> = {
82
- readonly status: "passed";
81
+ readonly status: "passed";
83
82
  } | {
84
- readonly status: "failed";
85
- readonly error: TError;
83
+ readonly status: "failed";
84
+ readonly error: TError;
86
85
  };
87
-
88
86
  /**
89
87
  * Configuration options for debug functionality.
90
88
  * @template TInput - The type of the input to validate
@@ -96,43 +94,24 @@ type RuleResult<TError = string> = {
96
94
  * @property onError - Called when rule throws
97
95
  */
98
96
  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;
97
+ /** Unique identifier for the rule */
98
+ name?: string;
99
+ /** Called before rule execution */
100
+ onStart?: (input: TInput, context?: TContext) => void;
101
+ /** Called after rule completes */
102
+ onEnd?: (input: TInput, result: RuleResult<TError>, context?: TContext, meta?: {
103
+ ruleName: string;
104
+ duration: number;
105
+ startTime: number;
106
+ }) => void;
107
+ /** Called when rule throws */
108
+ onError?: (error: unknown, input: TInput, context?: TContext, duration?: number) => void;
111
109
  };
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
110
  /**
131
111
  * A predicate function that evaluates an input and returns a boolean result.
132
112
  * Can be synchronous or asynchronous.
133
113
  */
134
114
  type Predicate<TInput, TContext> = (input: TInput, context?: TContext) => boolean | Promise<boolean>;
135
-
136
115
  /**
137
116
  * Represents the result of a predicate evaluation.
138
117
  * @template TError - The type of the error (defaults to string)
@@ -151,19 +130,33 @@ type Predicate<TInput, TContext> = (input: TInput, context?: TContext) => boolea
151
130
  * };
152
131
  */
153
132
  type PredicateResult<TError = string> = {
154
- readonly status: "passed";
155
- value: boolean;
133
+ readonly status: "passed";
134
+ value: boolean;
156
135
  } | {
157
- readonly status: "failed";
158
- readonly error: TError;
136
+ readonly status: "failed";
137
+ readonly error: TError;
159
138
  };
160
-
161
139
  /**
162
140
  * A predicate function that evaluates an input and returns a PredicateResult.
163
141
  * Can be synchronous or asynchronous.
164
142
  */
165
143
  type PredicateSafe<TInput, TError, TContext> = (input: TInput, context?: TContext) => PredicateResult<TError> | Promise<PredicateResult<TError>>;
166
-
144
+ /**
145
+ * A function that validates an input and returns a RuleResult.
146
+ * @template TInput - The type of the input to validate
147
+ * @template TError - The type of the error (defaults to string)
148
+ * @template TContext - The type of the context object (optional)
149
+ * @param input - The input value to validate
150
+ * @param context - Optional context object that can be used during validation
151
+ * @returns Either a Promise of RuleResult or RuleResult directly
152
+ * @example
153
+ * const isEven: Rule<number> = (input) => {
154
+ * return input % 2 === 0
155
+ * ? { status: "passed" }
156
+ * : { status: "failed", error: "Number must be even" };
157
+ * };
158
+ */
159
+ type Rule<TInput, TError = string, TContext = unknown> = (input: TInput, context?: TContext) => Promise<RuleResult<TError>> | RuleResult<TError>;
167
160
  /**
168
161
  * Composes multiple rules into a single rule that runs them all and collects all errors.
169
162
  * @template TInput - The type of the input to validate
@@ -171,7 +164,7 @@ type PredicateSafe<TInput, TError, TContext> = (input: TInput, context?: TContex
171
164
  * @template TContext - The type of the context object (optional)
172
165
  * @param rules - Array of rules to compose
173
166
  * @param options - Configuration options
174
- * @param options.cloneContext - Whether to clone the context for each rule (default: false)
167
+ * @param options.cloneContext - Whether to clone the context once per composed invocation (default: false)
175
168
  * @param options.cloneStrategy -Which strategy to use when cloning the context
176
169
  * @param options.errorHandlingMode - Determines how errors are handled:
177
170
  * - 'safe': (default) Converts thrown errors to validation failures
@@ -197,16 +190,15 @@ type PredicateSafe<TInput, TError, TContext> = (input: TInput, context?: TContex
197
190
  * 2. Uses structuredClone if available and options.structuredClone = true
198
191
  * 3. Falls back to JSON clone otherwise
199
192
  */
200
- declare const every: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: CompositionOptions<TError>) => Rule<TInput, TError[], TContext>;
201
-
193
+ export declare const every: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: CompositionOptions<TError>) => Rule<TInput, TError[], TContext>;
202
194
  /**
203
195
  * Configuration options for error handling behavior in rule combinators
204
196
  * @template TError - The type of the error that will be caught and transformed (when safe)
205
197
  *
206
198
  *
207
199
  * @property predicateErrorTransform - Optional custom error transformation function
208
- * Only used when errorHandling="safe". Allows customizing how thrown errors
209
- * are converted to the rule's error type.
200
+ * Allows customizing how thrown errors are converted to the rule's error
201
+ * type. Only valid when errorHandlingMode is "safe" (or omitted).
210
202
  *
211
203
  *
212
204
  * @example
@@ -224,11 +216,9 @@ declare const every: <TInput, TError = string, TContext = unknown>(rules: Rule<T
224
216
  * );
225
217
  */
226
218
  type PredicateSafetyOptions<TError = unknown> = {
227
- predicateErrorTransform?: (error: unknown) => TError;
219
+ predicateErrorTransform?: (error: unknown) => TError;
228
220
  };
229
-
230
221
  type SafetyOptions<TError = unknown> = Prettify<RuleSafetyOptions<TError> & PredicateSafetyOptions<TError>>;
231
-
232
222
  /**
233
223
  * Conditionally executes one of two rules based on a predicate
234
224
  * @template TInput - The type of the input to validate
@@ -257,8 +247,7 @@ type SafetyOptions<TError = unknown> = Prettify<RuleSafetyOptions<TError> & Pred
257
247
  * validateAdultAccount
258
248
  * );
259
249
  */
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
-
250
+ 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
251
  /**
263
252
  * Pattern-matching combinator that selects a rule based on a key extracted from input.
264
253
  * @template TInput - The type of the input to validate
@@ -317,8 +306,7 @@ declare const ifElse: <TInput, TError = string, TContext = unknown>(predicate: P
317
306
  * - All case rules must have compatible input/context types
318
307
  * - For conditional branching (true/false), consider using `branch` instead
319
308
  */
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
-
309
+ 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
310
  /**
323
311
  * Inverts the logic of a rule - passes when original fails and vice versa.
324
312
  * @template TInput - The type of the input to validate
@@ -337,8 +325,7 @@ declare const match: <TInput, TError = string, TContext = unknown, TKey extends
337
325
  * - The original rule's error is discarded when it fails
338
326
  * - Always uses the provided error when original passes
339
327
  */
340
- declare const not: <TInput, TError = string>(rule: Rule<TInput, TError>, error: TError, options?: RuleSafetyOptions<TError>) => Rule<TInput, TError>;
341
-
328
+ export declare const not: <TInput, TError = string>(rule: Rule<TInput, TError>, error: TError, options?: RuleSafetyOptions<TError>) => Rule<TInput, TError>;
342
329
  /**
343
330
  * Creates a rule that passes if any of the provided rules pass (short-circuiting).
344
331
  * @template TInput - The type of the input to validate
@@ -361,8 +348,7 @@ declare const not: <TInput, TError = string>(rule: Rule<TInput, TError>, error:
361
348
  * - Rules are executed in sequence until one passes
362
349
  * - Returns all errors if all rules fail
363
350
  */
364
- declare const oneOf: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: RuleSafetyOptions<TError>) => Rule<TInput, TError[], TContext>;
365
-
351
+ export declare const oneOf: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: RuleSafetyOptions<TError>) => Rule<TInput, TError[], TContext>;
366
352
  /**
367
353
  * Executes a rule only if the predicate returns false.
368
354
  * @template TInput - The type of the input to validate
@@ -386,8 +372,7 @@ declare const oneOf: <TInput, TError = string, TContext = unknown>(rules: Rule<T
386
372
  * - Opposite behavior of `when`
387
373
  * - Automatically passes when predicate is true
388
374
  */
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
-
375
+ 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
376
  /**
392
377
  * Conditionally executes a rule based on a predicate.
393
378
  * Similar to branch but without an else case.
@@ -411,8 +396,7 @@ declare const unless: <TInput, TError = string, TContext = unknown>(predicate: P
411
396
  * - The predicate can be async
412
397
  * - If predicate returns false, the rule automatically passes
413
398
  */
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
-
399
+ 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
400
  /**
417
401
  * Creates a rule that falls back to an alternative rule if the main rule fails.
418
402
  * @template TInput - Input type
@@ -434,10 +418,9 @@ declare const when: <TInput, TError = string, TContext = unknown>(predicate: Pre
434
418
  * { onlyFallbackOn: err => err.code !== 'FATAL' }
435
419
  * );
436
420
  */
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;
421
+ export declare const withFallback: <TInput, TError, TContext>(mainRule: Rule<TInput, TError, TContext>, fallbackRule: Rule<TInput, TError, TContext>, options?: RuleSafetyOptions<TError> & {
422
+ onlyFallbackOn?: (error: TError) => boolean;
439
423
  }) => Rule<TInput, TError, TContext>;
440
-
441
424
  /**
442
425
  * Injects a dependency into a rule creation function, returning a configured rule.
443
426
  * @template TInput - The type of the input to validate
@@ -454,8 +437,7 @@ declare const withFallback: <TInput, TError, TContext>(mainRule: Rule<TInput, TE
454
437
  * @caveats
455
438
  * - The dependency is injected at rule creation time, not execution time
456
439
  */
457
- declare const inject: <TInput, TError, TDep>(dependency: TDep, rule: (dep: TDep) => Rule<TInput, TError>) => Rule<TInput, TError>;
458
-
440
+ export declare const inject: <TInput, TError, TDep>(dependency: TDep, rule: (dep: TDep) => Rule<TInput, TError>) => Rule<TInput, TError>;
459
441
  /**
460
442
  * Transforms the error of a rule using a mapping function.
461
443
  * @template TInput - The type of the input to validate
@@ -479,8 +461,7 @@ declare const inject: <TInput, TError, TDep>(dependency: TDep, rule: (dep: TDep)
479
461
  * - Only transforms failed results, passes successful results through unchanged
480
462
  * - The transform function is not called for successful results
481
463
  */
482
- declare const mapError: <TInput, TError, TNewError>(rule: Rule<TInput, TError>, transform: (error: TError) => TNewError) => Rule<TInput, TNewError>;
483
-
464
+ export declare const mapError: <TInput, TError, TNewError>(rule: Rule<TInput, TError>, transform: (error: TError) => TNewError) => Rule<TInput, TNewError>;
484
465
  /**
485
466
  * Creates a standalone tap effect for use in composition pipelines
486
467
  * @template TInput - Input type
@@ -494,32 +475,7 @@ declare const mapError: <TInput, TError, TNewError>(rule: Rule<TInput, TError>,
494
475
  * validateInput
495
476
  * ])
496
477
  */
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
-
478
+ export declare const tap: <TInput, TError = string, TContext = unknown>(effect: (input: TInput, context?: TContext) => Promise<void> | void) => Rule<TInput, TError, TContext>;
523
479
  /**
524
480
  * Creates a rule that extracts a value using a getter function and validates it.
525
481
  * @template TInput - The type of the input object
@@ -560,8 +516,7 @@ declare const withTap: <TInput, TError = string, TContext = unknown>(effect: (in
560
516
  * - Defaults are applied before rule execution (the rule sees the default value)
561
517
  * - Default values aren't type-checked against potentially undefined returns
562
518
  */
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
-
519
+ 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
520
  /**
566
521
  * Wraps a rule with debugging capabilities.
567
522
  * @template TInput - The type of the input to validate
@@ -586,8 +541,7 @@ declare function validateField<TInput, TValue, TError = string, TContext = unkno
586
541
  * - Debug callbacks are executed synchronously and may impact performance
587
542
  * - Errors in callbacks will propagate and potentially mask rule errors
588
543
  */
589
- declare const withDebug: <TInput, TError, TContext>(rule: Rule<TInput, TError, TContext>, options: DebugOptions<TInput, TError, TContext> | string) => Rule<TInput, TError, TContext>;
590
-
544
+ export declare const withDebug: <TInput, TError, TContext>(rule: Rule<TInput, TError, TContext>, options: DebugOptions<TInput, TError, TContext> | string) => Rule<TInput, TError, TContext>;
591
545
  /**
592
546
  * Creates a memoized version of a rule that caches results based on input keys.
593
547
  * @template TInput - The type of the input to validate
@@ -614,14 +568,14 @@ declare const withDebug: <TInput, TError, TContext>(rule: Rule<TInput, TError, T
614
568
  * - Cache cleanup happens during rule execution
615
569
  * - Rejected promises are automatically evicted from cache
616
570
  * - Successful results obey TTL rules
617
- * - Cache is shared across rule instances
571
+ * - Each call to withMemoize creates its own cache; it is not shared across memoized rules
572
+ * - Entries are evicted oldest-inserted first (FIFO) once maxSize is reached; hits do not refresh recency
618
573
  */
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;
574
+ export declare const withMemoize: <TInput, TError = string, TContext = unknown>(rule: Rule<TInput, TError, TContext>, keyFn: (input: TInput) => string, options?: {
575
+ ttl?: number;
576
+ maxSize?: number;
622
577
  } & RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>;
623
-
624
- type RetryStrategy = "fixed" | "linear" | "exponential" | ((attempt: number) => number);
578
+ export type RetryStrategy = "fixed" | "linear" | "exponential" | ((attempt: number) => number);
625
579
  /**
626
580
  * Wraps a rule with retry logic for handling transient failures.
627
581
  * @template TInput - The type of the input to validate
@@ -643,13 +597,12 @@ type RetryStrategy = "fixed" | "linear" | "exponential" | ((attempt: number) =>
643
597
  * - Only retries on failed RuleResults, not on thrown exceptions
644
598
  * - The final error will be "MAX_RETRIES_EXCEEDED" if all attempts fail
645
599
  */
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;
600
+ export declare const withRetry: <TInput, TError = string, TContext = unknown>(rule: Rule<TInput, TError, TContext>, options?: {
601
+ attempts?: number;
602
+ delayMs?: number;
603
+ retryStrategy?: RetryStrategy;
604
+ shouldRetry?: (error: TError | unknown, attempt: number) => boolean;
651
605
  }) => Rule<TInput, TError | "MAX_RETRIES_EXCEEDED", TContext>;
652
-
653
606
  /**
654
607
  * Wraps a rule to catch errors and convert them to failed RuleResults
655
608
  * @template TInput - The input type
@@ -673,8 +626,7 @@ declare const withRetry: <TInput, TError = string, TContext = unknown>(rule: Rul
673
626
  * - Generic parameters must be explicitly set for custom error types
674
627
  * - Doesn't verify error types match TError at runtime
675
628
  */
676
- declare const withSafeError: <TInput, TError = string, TContext = unknown>(rule: Rule<TInput, TError, TContext>, errorTransform?: (error: unknown) => TError) => Rule<TInput, TError, TContext>;
677
-
629
+ export declare const withSafeError: <TInput, TError = string, TContext = unknown>(rule: Rule<TInput, TError, TContext>, errorTransform?: (error: unknown) => TError) => Rule<TInput, TError, TContext>;
678
630
  /**
679
631
  * Wraps a predicate function with error handling and type safety.
680
632
  * @template TInput - The input type
@@ -702,8 +654,30 @@ declare const withSafeError: <TInput, TError = string, TContext = unknown>(rule:
702
654
  * - Returns failed result for Promise rejections (transformed via errorTransform)
703
655
  * - Returns failed result for thrown non-Error values (like `throw "string"`)
704
656
  */
705
- declare const withSafePredicate: <TInput, TError = string, TContext = unknown>(predicate: Predicate<TInput, TContext>, errorTransform?: (error: unknown) => TError) => PredicateSafe<TInput, TError, TContext>;
706
-
657
+ export declare const withSafePredicate: <TInput, TError = string, TContext = unknown>(predicate: Predicate<TInput, TContext>, errorTransform?: (error: unknown) => TError) => PredicateSafe<TInput, TError, TContext>;
658
+ /**
659
+ * Creates a rule wrapper that performs side effects without modifying the result.
660
+ * @template TInput - The type of the input to validate
661
+ * @template TError - The type of the error (defaults to string)
662
+ * @template TContext - The type of the context object (optional)
663
+ * @param effect - Side effect function receiving input, result and context
664
+ * @param options - Configuration for error handling safety
665
+ * @param options.errorHandlingMode - Determines how errors are handled:
666
+ * - 'safe': (default) Converts thrown errors to validation failures
667
+ * - 'unsafe': Lets errors propagate (use only in performance-critical paths)
668
+ * @param options.errorTransform - Custom transformation for caught errors
669
+ * @returns A function that wraps a rule with the tap effect
670
+ * @example
671
+ * const withLogging = tap((input, result) => {
672
+ * console.log(`Validation result for ${input}:`, result);
673
+ * });
674
+ *
675
+ * const rule = withLogging(validateInput);
676
+ * @caveats
677
+ * - Errors in the effect are caught and logged but don't affect rule execution
678
+ * - Doesn't modify the rule's result
679
+ */
680
+ 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
681
  /**
708
682
  * Wraps a rule with timeout functionality.
709
683
  * @template TInput - The type of the input to validate
@@ -728,8 +702,7 @@ declare const withSafePredicate: <TInput, TError = string, TContext = unknown>(p
728
702
  * - The original rule's execution isn't aborted when timeout occurs
729
703
  * - Only fails if the rule doesn't complete before timeout, not if it fails before timeout
730
704
  */
731
- declare const withTimeout: <TInput, TError, TContext>(rule: Rule<TInput, TError, TContext>, timeoutMs: number, timeoutError: TError, options?: RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>;
732
-
705
+ export declare const withTimeout: <TInput, TError, TContext>(rule: Rule<TInput, TError, TContext>, timeoutMs: number, timeoutError: TError, options?: RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>;
733
706
  /**
734
707
  * Composes multiple rules into a single rule that runs them in right-to-left order (fail-fast).
735
708
  * Stops at the first failure and returns the error.
@@ -739,7 +712,7 @@ declare const withTimeout: <TInput, TError, TContext>(rule: Rule<TInput, TError,
739
712
  * @template TContext - The type of the context object (optional)
740
713
  * @param rules - Array of rules to compose
741
714
  * @param options - Configuration options
742
- * @param options.cloneContext - Whether to clone the context for each rule (default: false)
715
+ * @param options.cloneContext - Whether to clone the context once per composed invocation (default: false)
743
716
  * @param options.errorHandlingMode - Determines how errors are handled:
744
717
  * - 'safe': (default) Converts thrown errors to validation failures
745
718
  * - 'unsafe': Lets errors propagate (use only in performance-critical paths)
@@ -763,8 +736,36 @@ declare const withTimeout: <TInput, TError, TContext>(rule: Rule<TInput, TError,
763
736
  * 2. Uses structuredClone if available and options.structuredClone = true
764
737
  * 3. Falls back to JSON clone otherwise
765
738
  */
766
- declare const composeRules: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: CompositionOptions) => Rule<TInput, TError, TContext>;
767
-
739
+ export declare const composeRules: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: CompositionOptions<TError>) => Rule<TInput, TError, TContext>;
740
+ /**
741
+ * Pipes a value through a series of functions (left-to-right composition).
742
+ * @template A - The input type
743
+ * @template B - The output type after first function
744
+ * @param value - The initial value
745
+ * @param fns - Functions to apply sequentially
746
+ * @returns The result of applying all functions to the initial value
747
+ * @example
748
+ * const result = pipe(
749
+ * 5,
750
+ * (x) => x * 2,
751
+ * (x) => x + 3,
752
+ * (x) => `Result: ${x}`
753
+ * ); // "Result: 13"
754
+ * @caveats
755
+ * - Currently supports up to 10 functions with proper type inference
756
+ * - For more functions, type information will be lost
757
+ */
758
+ export declare function pipe<A>(value: A): A;
759
+ export declare function pipe<A, B>(value: A, fn1: (arg: A) => B): B;
760
+ export declare function pipe<A, B, C>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C): C;
761
+ export declare function pipe<A, B, C, D>(value: A, fn1: (arg: A) => B, fn2: (arg: B) => C, fn3: (arg: C) => D): D;
762
+ 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;
763
+ 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;
764
+ 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;
765
+ 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;
766
+ 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;
767
+ 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;
768
+ 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
769
  /**
769
770
  * Pipes multiple rules into a single rule that runs them sequentially (fail-fast).
770
771
  * Stops at the first failure and returns the error.
@@ -773,7 +774,7 @@ declare const composeRules: <TInput, TError = string, TContext = unknown>(rules:
773
774
  * @template TContext - The type of the context object (optional)
774
775
  * @param rules - Array of rules to compose
775
776
  * @param options - Configuration options
776
- * @param options.cloneContext - Whether to clone the context for each rule (default: false)
777
+ * @param options.cloneContext - Whether to clone the context once per composed invocation (default: false)
777
778
  * @param options.errorHandlingMode - Determines how errors are handled:
778
779
  * - 'safe': (default) Converts thrown errors to validation failures
779
780
  * - 'unsafe': Lets errors propagate (use only in performance-critical paths)
@@ -795,38 +796,7 @@ declare const composeRules: <TInput, TError = string, TContext = unknown>(rules:
795
796
  * 2. Uses structuredClone if available and options.structuredClone = true
796
797
  * 3. Falls back to JSON clone otherwise
797
798
  */
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
-
799
+ export declare const pipeRules: <TInput, TError = string, TContext = unknown>(rules: Rule<TInput, TError, TContext>[], options?: CompositionOptions<TError>) => Rule<TInput, TError, TContext>;
830
800
  /**
831
801
  * Type guard to check if context exists and is of type T.
832
802
  * @template T - The expected context type
@@ -837,8 +807,7 @@ declare function pipe<A, B, C, D, E, F, G, H, I, J, K>(value: A, fn1: (arg: A) =
837
807
  * // context is now typed as AdminContext
838
808
  * }
839
809
  */
840
- declare const hasContext: <T>(ctx: T | undefined) => ctx is T;
841
-
810
+ export declare const hasContext: <T>(ctx: T | undefined) => ctx is T;
842
811
  /**
843
812
  * Creates a rule that requires specific context to be present.
844
813
  * @template TInput - The type of the input to validate
@@ -859,8 +828,21 @@ declare const hasContext: <T>(ctx: T | undefined) => ctx is T;
859
828
  * - Fails immediately if context check fails
860
829
  * - Provides type safety for context requirements
861
830
  */
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>;
831
+ 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>;
832
+ /**
833
+ * const userRule = requireContextRule(
834
+ "User context required",
835
+ (input: string, ctx: { userId: string }) => {
836
+ return ctx.userId === "admin"
837
+ ? pass()
838
+ : fail("Unauthorized");
839
+ }
840
+ );
863
841
 
842
+ await userRule("action"); // fails with "User context required"
843
+ await userRule("action", { userId: "user" }); // fails with "Unauthorized"
844
+ await userRule("action", { userId: "admin" }); // passes
845
+ */
864
846
  /**
865
847
  * Creates a rule that loads context lazily before execution.
866
848
  * @template TInput - The type of the input to validate
@@ -878,8 +860,7 @@ declare const requireContextRule: <TInput, TError, TContext, TRequiredContext ex
878
860
  * - Context loading failures are converted to validation failures
879
861
  * - The loader is called for every rule execution
880
862
  */
881
- declare const withLazyContext: <TInput, TError, TContext>(loader: (input: TInput) => Promise<TContext> | TContext, rule: Rule<TInput, TError, TContext>) => Rule<TInput, TError>;
882
-
863
+ export declare const withLazyContext: <TInput, TError, TContext>(loader: (input: TInput) => Promise<TContext> | TContext, rule: Rule<TInput, TError, TContext>) => Rule<TInput, TError>;
883
864
  /**
884
865
  * Creates a failed RuleResult with the provided error.
885
866
  * @template TError - The type of the error (defaults to string)
@@ -891,8 +872,7 @@ declare const withLazyContext: <TInput, TError, TContext>(loader: (input: TInput
891
872
  * // Used in rule implementations:
892
873
  * const alwaysFails: Rule<string> = () => fail("Always fails");
893
874
  */
894
- declare const fail: <TError = string>(error: TError) => RuleResult<TError>;
895
-
875
+ export declare const fail: <TError = string>(error: TError) => RuleResult<TError>;
896
876
  /**
897
877
  * Creates a successful RuleResult with "passed" status.
898
878
  * @template TError - The type of the error (defaults to string)
@@ -903,12 +883,9 @@ declare const fail: <TError = string>(error: TError) => RuleResult<TError>;
903
883
  * // Used in rule implementations:
904
884
  * const alwaysPasses: Rule<string> = () => pass();
905
885
  */
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 };
886
+ export declare const pass: <TError = string>() => RuleResult<TError>;
887
+ export declare const calculateDelay: (strategy: RetryStrategy | undefined, attempt: number, initialDelayMs: number) => number;
888
+ export declare const getNormalizedRule: <TInput, TError, TContext>(rule: Rule<TInput, TError, TContext>, opts?: RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>;
889
+ export declare const getNormalizedRules: <TInput, TError, TContext>(rules: Rule<TInput, TError, TContext>[], opts?: RuleSafetyOptions<TError>) => Rule<TInput, TError, TContext>[];
890
+ export type { CompositionOptions, DebugOptions, Predicate, PredicateResult, PredicateSafe, Rule, RuleResult, RuleSafetyOptions };
891
+ //# sourceMappingURL=index.d.cts.map