/nw-fp-principles

name: nw-fp-principles
agent: nw-functional-software-crafter
description: Core functional programming thinking patterns and type system foundations, language-agnostic
user-invocable: false

FP Principles

Core functional programming thinking patterns. Language-agnostic.

Cross-references: [fp-domain-modeling](../nw-fp-domain-modeling/SKILL.md) | [code-craftsmanship: FP Hexagonal Architecture](../nw-code-craftsmanship/SKILL.md) | [fp-algebra-driven-design](../nw-fp-algebra-driven-design/SKILL.md)

---

1. Higher-Order Functions as Problem Decomposition

[STARTER]

Three operations replace most loops:

| Operation | Purpose | Replaces | |-----------|---------|----------| | **Map** | Transform each element, preserve structure | Loop building new collection | | **Filter** | Keep elements matching condition | Loop with conditional | | **Fold** | Accumulate elements into single result | Loop with running total |

**When to use Map**: Transform every element without changing collection shape. Nested maps handle nested structures. **When to use Filter**: Select elements without changing their values. **When to use Fold**: Reduce collection to single value. Accumulator IS your state. Combining function IS your state transition. Folds make state machines explicit.

**Dependent streams**: Fold over the evolving descriptive state, not the initial state for every item. Approve then archive an invoice uses the post-approval invoice; snapshots project only the final register. Law: `prepare(s, xs ++ ys) = prepare(prepare(s, xs), ys)` on admitted transitions. When refusal forbids construction activity, load `nw-certainty-by-construction` for its readiness boundary before execution. Basis: Sandy Maguire, *Algebra-Driven Design*, Designing Algebras → Scavenger Hunt → A Unified Observation; *Thinking with Types*, Indexed Monads → Definition and Necessary Machinery.

**Decision**: "Am I transforming, selecting, or accumulating?" Pick matching operation. If none fit, compose two.

**Why**: These operations communicate intent. Map says "same shape, different values." Fold says "many inputs, one output." Loops say nothing about intent until you read every line.

---

2. Type-Driven Design

[STARTER]

Write the type signature before implementation. The type tells you what the function can and cannot do.

**Process**: 1. Declare what the function consumes and produces 2. Ask: "which type-specific operations do I actually use?" 3. Replace concrete types with type variables for everything you don't inspect 4. Add constraints only for capabilities you use (equality, ordering, display)

**Design progression**: Concrete types -> type variables -> constrained type variables. Each step increases reuse while documenting minimal assumptions.

**Why**: Function's type signature is a contract. Narrower types mean fewer possible implementations, fewer bugs.

---

3. Pattern Matching as Decision Decomposition

[STARTER]

Decompose decisions by data shape, not boolean conditions. Each clause handles one concrete case. Compiler verifies exhaustiveness.

**When to use pattern matching**: "What shape is this data?" **When to use guards/conditions**: "What property does this value have?" **When to use named bindings**: Intermediate results need a name to avoid repetition.

**Heuristic**: Prefer small extracted functions over giant match expressions. Pattern match on top-level shape, delegate to named functions for sub-decisions.

**Exhaustiveness as safety net**: When you add a new variant to a choice type, compiler flags every match that doesn't handle it.

---

4. Composition Patterns

[INTERMEDIATE]

Partial Application

Fix some arguments of a general function to create specialized version. Eliminates throwaway helper functions.

**When**: General function exists and you need specialized version for specific context.

Function Composition (Pipelines)

Chain functions where output of one feeds into next. Each function has single responsibility.

**Why**: Composition reveals architecture of computation. Pipelines read as sequence of steps, making business process visible.

Point-Free Style

Omit explicit argument when function is just a composition. Use when it reveals intent. Avoid when it obscures meaning.

---

5. Container Abstractions

[INTERMEDIATE] -> [ADVANCED]

Progressive hierarchy for working with values inside containers (nullables, lists, futures, results).

[INTERMEDIATE] Transformable Container (Functor)

**What**: Apply function to values inside container without changing structure. **Plain English**: "I have a value in a box. Transform the value without opening the box." **When**: You have nullable/optional/list/future and want to transform contents without inspecting the container. **Guarantees**: Transforming with identity does nothing. Can fuse or split transformations freely.

[INTERMEDIATE] Combinable Containers (Applicative)

**What**: Apply a function inside a container to values inside other containers. **Plain English**: "I have a function in a box AND values in boxes. Combine them." **When**: Combining independent inputs. For all-errors validation, select an error-accumulating Validation interpretation; Applicative alone does not fix failure behavior.

[INTERMEDIATE] Combinable Values (Monoid)

**What**: Combine two values of same type into one, with default element that changes nothing. **Plain English**: "I have many values. Smash them together into one." **When**: Folding/reducing collections. Combining operation must be associative, enabling parallelism. **Examples**: String concatenation with empty string | addition with zero | list append with empty list.

[ADVANCED] Chainable Operations (Monad)

**What**: Chain operations where each step produces wrapped value, next step depends on previous result. **Plain English**: "Step 1's output determines what step 2 does. Each step might fail/branch/have effects." **When**: Sequential dependent operatio