kernel.nix

Source: /nix/store/mls72plk3raskl1r5afh3cl9ik3rn969-source/nix/kernel.nix

Module Description

Core kernel primitives for the NFX effect system

Combinators

adapt

The fundamental combinator - everything else builds on this.

adapt is the core primitive that enables all effect transformations. It simultaneously handles:

1. Contravariant mapping of context requirements (what the effect needs)
2. Covariant mapping of continuations (what happens given the result)

Type Signature

Fx<S,V> -> (T -> S) -> (T -> S -> V -> Fx<T,U>) -> Fx<T,U>

Parameters

• e: The effect to transform
• cmap: Context mapper T -> S - extracts inner requirement from outer context
• fmap: Continuation (T, S, V) -> Fx<T,U> - transforms the result

How It Works

1. Creates a pending effect expecting context T
2. Applies cmap to get the inner context S
3. If effect is immediate, applies fmap to produce final result
4. If effect is pending, recursively adapts the continuation

Example

# Double the result of an effect
adapt (pure 21) (s: s) (_t: _s: v: immediate {} (v * 2))

See Also

• map - Simpler value transformation (built on adapt)
• contraMap - Simpler context transformation (built on adapt)

immediate

Creates an immediate (already resolved) effect.

An immediate effect is the terminal case of the Fx type - it carries both a state and a value, meaning it needs no further context to produce its result. This is one of two fundamental constructors for the Fx algebraic data type.

Type Signature

state -> value -> Fx<state, value>

Parameters

• state: The current state/context that was used to produce the value
• value: The computed result

Example

immediate {} 42  # Effect holding value 42 with empty state
immediate { count = 1; } "done"  # Effect with state and string value

See Also

• pending - The other Fx constructor for suspended computations
• runFx - Evaluates an effect to extract its value

pending

Creates a pending (suspended) effect awaiting context.

A pending effect wraps an “ability” - a function that will be called given context to produce the next step of computation. This is the mechanism by which effects express their requirements: the ability requests something from the context.

Type Signature

(context -> Fx<S, V>) -> Fx<S, V>

Parameters

• ability: A function context -> Fx<S, V> that consumes context and produces the next computation step

Example

# Effect that reads a number from context and doubles it
pending (n: immediate n (n * 2))

# Effect requesting an attribute from context
pending (ctx: immediate ctx ctx.username)

See Also

• immediate - The terminal case, already has its value
• adapt - The fundamental combinator for transforming effects

runFx

Evaluates an effect to extract its final value.

This is the interpreter that runs an effect computation. It only works when all context requirements have been satisfied (state is unit/empty). The function loops until reaching an immediate result, feeding empty context {} to any pending abilities.

Type Signature

Fx<{}, V> -> V

Parameters

• e: An effect with no remaining context requirements

Returns

The final computed value

Example

runFx (pure 42)  # => 42
runFx (provide 10 (pending (n: immediate n (n * 2))))  # => 20

Notes

Before calling runFx, all context requirements must be satisfied using provide or similar combinators. Calling runFx on an effect that still has requirements will fail when the ability tries to access missing context.

See Also

• provide - Satisfies context requirements before evaluation
• pure - Creates an effect ready for immediate evaluation

Generated from /nix/store/mls72plk3raskl1r5afh3cl9ik3rn969-source/nix/kernel.nix