feat(88): add more matching

.commands/test-lint.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+set -e
+
+ARGUMENTS="$@"
+
+# scripts
+eslint --quiet $ARGUMENTS scripts/
+# tests
+eslint --quiet $ARGUMENTS tests/
+eslint --quiet $ARGUMENTS integration/
+# documentation
+eslint --quiet $ARGUMENTS docs/

.gitignore

@@ -1,4 +1,5 @@
 node_modules
 dist
 coverage
-cache
+cache
+.temp

docs/en/v1/api/clean/index.md

@@ -69,6 +69,12 @@ Declares an aggregate of linked business actions that must run in order.
 ### [equal](/en/v1/api/clean/primitives/operators/equal)
 Compares two wrapped primitives (or a primitive and a raw value) with a type guard.
 
+### [matchWithString](/en/v1/api/clean/primitives/operators/matchWithString)
+Performs exhaustive matching with raw string keys and passes the narrowed original Clean primitive.
+
+### [matchWithNumber](/en/v1/api/clean/primitives/operators/matchWithNumber)
+Performs exhaustive matching with raw number keys and passes the narrowed original Clean primitive.
+
 ### [add](/en/v1/api/clean/primitives/operators/add)
 Adds two `Number` (supports the curried version).
 

docs/en/v1/api/clean/primitives/index.md

@@ -96,6 +96,18 @@ function is(
 ### [equal](/en/v1/api/clean/primitives/operators/equal)
 Compares two wrapped primitives (or a primitive and a raw value) with a type guard.
 
+### [matchWithString](/en/v1/api/clean/primitives/operators/matchWithString)
+Performs exhaustive matching with raw string keys and passes the narrowed original Clean primitive.
+
+### [matchWithStringOtherwise](/en/v1/api/clean/primitives/operators/matchWithStringOtherwise)
+Partially matches raw string keys and passes remaining wrapped values to a typed fallback.
+
+### [matchWithNumber](/en/v1/api/clean/primitives/operators/matchWithNumber)
+Performs exhaustive matching with raw number keys and passes the narrowed original Clean primitive.
+
+### [matchWithNumberOtherwise](/en/v1/api/clean/primitives/operators/matchWithNumberOtherwise)
+Partially matches raw number keys and passes remaining wrapped values to a typed fallback.
+
 ### [add](/en/v1/api/clean/primitives/operators/add)
 Adds two `Number` (supports the curried version).
 

docs/en/v1/api/clean/primitives/operators/add.md

@@ -1,8 +1,8 @@
 ---
 outline: [2, 3]
 prev:
-  text: "equal"
-  link: "/en/v1/api/clean/primitives/operators/equal"
+  text: "matchWithNumberOtherwise"
+  link: "/en/v1/api/clean/primitives/operators/matchWithNumberOtherwise"
 next:
   text: "subtract"
   link: "/en/v1/api/clean/primitives/operators/subtract"

docs/en/v1/api/clean/primitives/operators/equal.md

@@ -1,8 +1,8 @@
 ---
 outline: [2, 3]
 next:
-  text: "add"
-  link: "/en/v1/api/clean/primitives/operators/add"
+  text: "matchWithString"
+  link: "/en/v1/api/clean/primitives/operators/matchWithString"
 ---
 
 # equal

docs/en/v1/api/clean/primitives/operators/matchWithNumber.md

@@ -0,0 +1,59 @@
+---
+outline: [2, 3]
+description: "matchWithNumber() performs exhaustive pattern matching on a Clean number primitive value and passes the correctly narrowed original primitive to each branch."
+prev:
+  text: "matchWithStringOtherwise"
+  link: "/en/v1/api/clean/primitives/operators/matchWithStringOtherwise"
+next:
+  text: "matchWithNumberOtherwise"
+  link: "/en/v1/api/clean/primitives/operators/matchWithNumberOtherwise"
+---
+
+# matchWithNumber
+
+`matchWithNumber()` performs exhaustive pattern matching on the value of a Clean number primitive. Every possible value must have a processing branch.
+
+A Clean primitive is a wrapped object, so it cannot be used directly as a matcher key. The keys are therefore raw `number` values. When a key matches, its callback receives the original Clean primitive narrowed to that value, preserving its `Primitive`, `ConstrainedType`, or `NewType` information.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/clean/primitives/operators/matchWithNumber/tryout.doc.ts"
+  majorVersion="v1"
+  height="565px"
+/>
+
+## Syntax
+
+### Classic signature
+
+```typescript
+function matchWithNumber<Input extends Primitive<number>, Matcher>(
+  input: Input,
+  matcher: Matcher
+): ReturnType<Matcher[keyof Matcher]>
+```
+
+### Curried signature
+
+```typescript
+function matchWithNumber<Input extends Primitive<number>, Matcher>(
+  matcher: Matcher
+): (input: Input) => ReturnType<Matcher[keyof Matcher]>
+```
+
+## Parameters
+
+- `input`: a Clean primitive containing a `number`, including constrained values and new types.
+- `matcher`: an exhaustive object indexed by the possible raw `number` values. A broad `Primitive<number>` requires an indexed `Record<number, handler>`.
+
+Every key must have exactly one handler. TypeScript rejects a missing key or a key outside the input union. The selected handler receives the original Clean object narrowed with `Primitive<MatchingValue>`.
+
+## Return value
+
+The selected handler result, typed as the union of every handler return type.
+
+## See also
+
+- [`matchWithString`](/en/v1/api/clean/primitives/operators/matchWithString) - String primitive equivalent.
+- [`equal`](/en/v1/api/clean/primitives/operators/equal) - Compares wrapped primitive values.

docs/en/v1/api/clean/primitives/operators/matchWithNumberOtherwise.md

@@ -0,0 +1,58 @@
+---
+outline: [2, 3]
+description: "matchWithNumberOtherwise() partially matches a Clean number primitive while preserving the narrowed original primitive in handlers and otherwise."
+prev:
+  text: "matchWithNumber"
+  link: "/en/v1/api/clean/primitives/operators/matchWithNumber"
+next:
+  text: "add"
+  link: "/en/v1/api/clean/primitives/operators/add"
+---
+
+# matchWithNumberOtherwise
+
+`matchWithNumberOtherwise()` handles selected values of a Clean number primitive. Raw number values form the matcher keys. Missing cases are sent to `otherwise`, which receives the original primitive narrowed to the remaining values.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/clean/primitives/operators/matchWithNumberOtherwise/tryout.doc.ts"
+  majorVersion="v1"
+  height="565px"
+/>
+
+## Syntax
+
+### Classic signature
+
+```typescript
+function matchWithNumberOtherwise<Input extends Primitive<number>, Matcher, Output>(
+  input: Input,
+  matcher: Matcher,
+  otherwise: (value: UnhandledPrimitive) => Output
+): MatcherResult | Output
+```
+
+### Curried signature
+
+```typescript
+function matchWithNumberOtherwise<Input extends Primitive<number>, Matcher, Output>(
+  matcher: Matcher,
+  otherwise: (value: UnhandledPrimitive) => Output
+): (input: Input) => MatcherResult | Output
+```
+
+## Parameters
+
+- `input`: a Clean number primitive with literal values.
+- `matcher`: a partial object indexed by raw values from the primitive. Unknown keys are rejected.
+- `otherwise`: receives the original `Primitive`, `ConstrainedType`, or `NewType`, narrowed to values without a handler.
+
+## Return value
+
+The selected handler result, or the `otherwise` result for an unhandled wrapped value.
+
+## See also
+
+- [`matchWithNumber`](/en/v1/api/clean/primitives/operators/matchWithNumber) - Exhaustive primitive matching.
+- [`matchWithStringOtherwise`](/en/v1/api/clean/primitives/operators/matchWithStringOtherwise) - String primitive equivalent.

docs/en/v1/api/clean/primitives/operators/matchWithString.md

@@ -0,0 +1,59 @@
+---
+outline: [2, 3]
+description: "matchWithString() performs exhaustive pattern matching on a Clean string primitive value and passes the correctly narrowed original primitive to each branch."
+prev:
+  text: "equal"
+  link: "/en/v1/api/clean/primitives/operators/equal"
+next:
+  text: "matchWithStringOtherwise"
+  link: "/en/v1/api/clean/primitives/operators/matchWithStringOtherwise"
+---
+
+# matchWithString
+
+`matchWithString()` performs exhaustive pattern matching on the value of a Clean string primitive. Every possible value must have a processing branch.
+
+A Clean primitive is a wrapped object, so it cannot be used directly as a matcher key. The keys are therefore raw `string` values. When a key matches, its callback receives the original Clean primitive narrowed to that value, preserving its `Primitive`, `ConstrainedType`, or `NewType` information.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/clean/primitives/operators/matchWithString/tryout.doc.ts"
+  majorVersion="v1"
+  height="544px"
+/>
+
+## Syntax
+
+### Classic signature
+
+```typescript
+function matchWithString<Input extends Primitive<string>, Matcher>(
+  input: Input,
+  matcher: Matcher
+): ReturnType<Matcher[keyof Matcher]>
+```
+
+### Curried signature
+
+```typescript
+function matchWithString<Input extends Primitive<string>, Matcher>(
+  matcher: Matcher
+): (input: Input) => ReturnType<Matcher[keyof Matcher]>
+```
+
+## Parameters
+
+- `input`: a Clean primitive containing a `string`, including constrained values and new types.
+- `matcher`: an exhaustive object indexed by the possible raw `string` values. A broad `Primitive<string>` requires an indexed `Record<string, handler>`.
+
+Every key must have exactly one handler. TypeScript rejects a missing key or a key outside the input union. The selected handler receives the original Clean object narrowed with `Primitive<MatchingValue>`.
+
+## Return value
+
+The selected handler result, typed as the union of every handler return type.
+
+## See also
+
+- [`matchWithNumber`](/en/v1/api/clean/primitives/operators/matchWithNumber) - Numeric primitive equivalent.
+- [`equal`](/en/v1/api/clean/primitives/operators/equal) - Compares wrapped primitive values.

docs/en/v1/api/clean/primitives/operators/matchWithStringOtherwise.md

@@ -0,0 +1,58 @@
+---
+outline: [2, 3]
+description: "matchWithStringOtherwise() partially matches a Clean string primitive while preserving the narrowed original primitive in handlers and otherwise."
+prev:
+  text: "matchWithString"
+  link: "/en/v1/api/clean/primitives/operators/matchWithString"
+next:
+  text: "matchWithNumber"
+  link: "/en/v1/api/clean/primitives/operators/matchWithNumber"
+---
+
+# matchWithStringOtherwise
+
+`matchWithStringOtherwise()` handles selected values of a Clean string primitive. Raw string values form the matcher keys. Missing cases are sent to `otherwise`, which receives the original primitive narrowed to the remaining values.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/clean/primitives/operators/matchWithStringOtherwise/tryout.doc.ts"
+  majorVersion="v1"
+  height="565px"
+/>
+
+## Syntax
+
+### Classic signature
+
+```typescript
+function matchWithStringOtherwise<Input extends Primitive<string>, Matcher, Output>(
+  input: Input,
+  matcher: Matcher,
+  otherwise: (value: UnhandledPrimitive) => Output
+): MatcherResult | Output
+```
+
+### Curried signature
+
+```typescript
+function matchWithStringOtherwise<Input extends Primitive<string>, Matcher, Output>(
+  matcher: Matcher,
+  otherwise: (value: UnhandledPrimitive) => Output
+): (input: Input) => MatcherResult | Output
+```
+
+## Parameters
+
+- `input`: a Clean string primitive with literal values.
+- `matcher`: a partial object indexed by raw values from the primitive. Unknown keys are rejected.
+- `otherwise`: receives the original `Primitive`, `ConstrainedType`, or `NewType`, narrowed to values without a handler.
+
+## Return value
+
+The selected handler result, or the `otherwise` result for an unhandled wrapped value.
+
+## See also
+
+- [`matchWithString`](/en/v1/api/clean/primitives/operators/matchWithString) - Exhaustive primitive matching.
+- [`matchWithNumberOtherwise`](/en/v1/api/clean/primitives/operators/matchWithNumberOtherwise) - Number primitive equivalent.

docs/en/v1/api/common/asyncInnerPipe.md

@@ -5,8 +5,8 @@ prev:
   text: "asyncPipe"
   link: "/en/v1/api/common/asyncPipe"
 next:
-  text: "forward"
-  link: "/en/v1/api/common/forward"
+  text: "prepareAsyncPipe"
+  link: "/en/v1/api/common/prepareAsyncPipe"
 ---
 
 # asyncInnerPipe

docs/en/v1/api/common/asyncPipe.md

@@ -2,8 +2,8 @@
 outline: [2, 3]
 description: "The asyncPipe() method chains asynchronous functions (promises or FutureEither) in series. Each step waits for the previous one to resolve and the last value is returned in a promise."
 prev:
-  text: "innerPipe"
-  link: "/en/v1/api/common/innerPipe"
+  text: "preparePipe"
+  link: "/en/v1/api/common/preparePipe"
 next:
   text: "asyncInnerPipe"
   link: "/en/v1/api/common/asyncInnerPipe"

docs/en/v1/api/common/forward.md

@@ -2,8 +2,8 @@
 outline: [2, 3]
 description: "The forward() function returns the passed argument without modifying it. Useful to standardize an API that expects a function, or to improve readability in a pipeline."
 prev:
-  text: "asyncInnerPipe"
-  link: "/en/v1/api/common/asyncInnerPipe"
+  text: "prepareAsyncPipe"
+  link: "/en/v1/api/common/prepareAsyncPipe"
 next:
   text: "forwardLog"
   link: "/en/v1/api/common/forwardLog"

docs/en/v1/api/common/index.md

@@ -32,12 +32,18 @@ Composes synchronous functions by chaining a single input.
 ### [innerPipe](/en/v1/api/common/innerPipe)
 Prepares a reusable pipe that returns a function to apply later.
 
+### [preparePipe](/en/v1/api/common/preparePipe)
+Declares reusable synchronous steps with contextual input-to-output inference.
+
 ### [asyncPipe](/en/v1/api/common/asyncPipe)
 Composes promises or `FutureEither` sequentially and returns a `Promise`.
 
 ### [asyncInnerPipe](/en/v1/api/common/asyncInnerPipe)
 Curried version of `asyncPipe` that returns a function ready to accept a value (sync or async).
 
+### [prepareAsyncPipe](/en/v1/api/common/prepareAsyncPipe)
+Declares reusable maybe-promise steps with contextual input-to-output inference.
+
 ### [forward](/en/v1/api/common/forward)
 Convenient identity function in a chain to pass the value through unchanged.
 

docs/en/v1/api/common/innerPipe.md

@@ -5,8 +5,8 @@ prev:
   text: "pipe"
   link: "/en/v1/api/common/pipe"
 next:
-  text: "asyncPipe"
-  link: "/en/v1/api/common/asyncPipe"
+  text: "preparePipe"
+  link: "/en/v1/api/common/preparePipe"
 ---
 
 # innerPipe