whenNot

whenNot() adds a guard in the pattern matching pipeline. When predicate returns false, the associated function is executed and its result is wrapped in a PatternResult. With a type guard, the branch is automatically typed with the excluded shape.

Interactive example

Syntax

Curried signatures

// Type Guard
function whenNot<
	GenericInput extends AnyValue, 
	GenericInputValue extends Exclude<GenericInput, PatternResult>, 
	GenericInputPatternResult extends Extract<GenericInput, PatternResult>, 
	GenericPredicatedInput extends GenericInputValue, 
	GenericOutput extends AnyValue
>(
	predicate: (input: GenericInputValue) => input is GenericPredicatedInput, 
	theFunction: (predicatedInput: Exclude<GenericInputValue, GenericPredicatedInput>) => GenericOutput
): (
	input: (GenericInput | GenericInputPatternResult | GenericInputValue)
) => (
	GenericInputPatternResult
	| Exclude<BreakGenericLink<GenericInputValue>, Exclude<GenericInputValue, GenericPredicatedInput>>
	| PatternResult<GenericOutput>
);

// Boolean
export declare function whenNot<
	GenericInput extends AnyValue, 
	GenericInputValue extends Exclude<GenericInput, PatternResult>, 
	GenericInputPatternResult extends Extract<GenericInput, PatternResult>, 
	GenericOutput extends AnyValue
>(
	predicate: (input: GenericInputValue) => boolean, 
	theFunction: (predicatedInput: GenericInputValue) => GenericOutput
): (
	input: (GenericInput | GenericInputPatternResult | GenericInputValue)
) => (GenericInputPatternResult | GenericInputValue | PatternResult<GenericOutput>);

Classic signatures

// Type Guard
function whenNot<
	GenericInput extends AnyValue, 
	GenericInputValue extends Exclude<GenericInput, PatternResult>, 
	GenericInputPatternResult extends Extract<GenericInput, PatternResult>, 
	GenericPredicatedInput extends GenericInputValue, 
	GenericOutput extends AnyValue
>(
	input: (GenericInput | GenericInputPatternResult | GenericInputValue), 
	predicate: (input: GenericInputValue) => input is GenericPredicatedInput, 
	theFunction: (predicatedInput: Exclude<GenericInputValue, GenericPredicatedInput>) => GenericOutput
): (
	GenericInputPatternResult
	| Exclude<GenericInputValue, Exclude<GenericInputValue, GenericPredicatedInput>>
	| PatternResult<GenericOutput>
);

// Boolean
function whenNot<
	GenericInput extends AnyValue, 
	GenericInputValue extends Exclude<GenericInput, PatternResult>, 
	GenericInputPatternResult extends Extract<GenericInput, PatternResult>, 
	GenericOutput extends AnyValue
>(
	input: (GenericInput | GenericInputPatternResult | GenericInputValue), 
	predicate: (input: GenericInputValue) => boolean, 
	theFunction: (predicatedInput: GenericInputValue) => GenericOutput
): (GenericInputPatternResult | GenericInputValue | PatternResult<GenericOutput>);

(a second overload exists with a simple boolean predicate).

Parameters

• input (optional): value to test immediately. Otherwise, whenNot returns a function for your pipe.
• predicate: guard function. Can be a type guard (value is ...) to statically reduce the union, or a simple boolean.
• theFunction: transformation to execute when the guard is not satisfied.

Return value

A PatternResult<Output> if the condition is not met, otherwise the original value (or what remains after previous guards). This result is ready to be passed to another when, whenNot, match, otherwise or exhaustive.

Best practices

• Declare your guards (type PaidInvoice = Extract<Invoice, { status: "paid" }>;) then reference them in predicate to keep readable typing.
• whenNot are evaluated in order: place the most specific cases before the generic ones.
• Combine whenNot with match in a builder to interleave rules based on predicates rather than structural patterns.

See also

• when
• match
• otherwise
• exhaustive