From nw
Designs APIs algebraically with monoids, semigroups, and equations. Specifies rules first to auto-generate tests, catch contradictions, and reveal missing operations before coding.
npx claudepluginhub nwave-ai/nwave --plugin nwThis skill uses the workspace's default tool permissions.
Algebraic thinking for API design. Discover the right API before implementing by specifying rules (equations) that operations must satisfy.
Designs and reviews public APIs, exported function signatures, module boundaries, types/interfaces, and code contracts to make correct usage easy and incorrect usage hard.
Guides usability in functional code design: naming conventions, pipeline-friendly APIs, lifecycle types, error naming, and feature-oriented organization.
Generates multiple radically different interface designs for modules or APIs using parallel sub-agents. Use when designing APIs, exploring options, comparing module shapes, or 'design it twice'.
Share bugs, ideas, or general feedback.
Algebraic thinking for API design. Discover the right API before implementing by specifying rules (equations) that operations must satisfy.
Cross-references: fp-principles | fp-domain-modeling | fp-usable-design
[STARTER]
Code is the wrong abstraction level for design. Starting with data structures inherits unnecessary constraints.
[STARTER]
[STARTER] -> [ADVANCED]
Recurring patterns in software. Recognizing them unlocks known rules and capabilities.
What: Type with one merge operation where grouping doesn't matter.
Rule: (a merge b) merge c = a merge (b merge c) (associativity)
When: Combining things where parenthesization shouldn't matter.
Examples: String concatenation | config merging | min/max.
What: Combinable Value with a default element inert under combination.
Rules: Associativity + default merge x = x and x merge default = x
When: Safe defaults | fold operations | "nothing happened yet" values.
Examples: (+, 0) | (*, 1) | (concat, []) | (and, true).
Design signal: If you find an associative operation, look for a default element. Finding one enables fold/reduce over collections.
What: Combinable Value where merging is also order-independent and idempotent.
When: Conflict resolution | eventually-consistent systems | CRDTs.
Example: Status tracker with seen < failed < completed uses max as merge.
What: Container type where you can transform contents without changing structure. Preserves identity and composition. When: Operations that work on data shape rather than values inside. Design signal: If most operations are agnostic to contained type, you likely have this.
What: Container where you can combine contents element-wise and fill with uniform values. When: Combining containers holding different content types.
What: Combinable Value with Default where every element has an inverse that cancels it. When: Undo operations | spatial transformations. Example: Clockwise/counter-clockwise rotation are inverses; horizontal flip is its own inverse.
[INTERMEDIATE]
Three categories, eight properties:
Clarity (communicates well):
Economy (no waste):
Safety (prevents mistakes):
[INTERMEDIATE]
Complex rules mean coarse building blocks. Split operations with many parameters into smaller, orthogonal ones. If a rule ignores some parameters, those should be separate operations.
Algebraic manipulation reveals contradictions before code is written. Requiring order-independence while returning an ordered list is a contradiction. Fix: use unordered collection.
When multiple observations share traversal logic, find one observation from which all others derive. Simplifies entire rule set.
When you have a "both" operation (parallel composition), look for its symmetric "either" counterpart. Symmetry discovers functionality not explicitly requested but inevitably needed.
[INTERMEDIATE]
Key insight: Two values are equal if no observation distinguishes them. Testing through observations allows completely different implementations to pass the same suite.
Is your domain about COMBINING things?
YES --> Algebraic thinking helps significantly
Do combinations have rules (order irrelevant, defaults, inverses)?
YES --> Known algebraic structures; use their rules directly
NO --> Rules still help, but structures are not standard
NO --> Is your domain about TRANSFORMING things?
YES --> Look for Structure-Preserving Transformation patterns
NO --> Is your API surface small and well-understood?
YES --> Algebraic thinking adds overhead; use conventional design
NO --> Rules can still clarify, even without standard structures
Rules + Property-Based Testing: Rules ARE property tests. Algebraic constructors become PBT generators. Example: empty merge x = x becomes forAll(x -> assertEquals(empty.merge(x), x)).
Rules + Domain Modeling (see fp-domain-modeling): Domain wrappers with smart constructors are algebraic rules. State machine transitions are rules about valid sequences. Example: items(addItem(cart, item)) contains item -- directly a property test.
Rules + Usable Design (see fp-usable-design): Simple algebraic rules map to simple, searchable, nameable operations -- improving navigability and learnability. Example: decomposing processOrder into validate, price, confirm gives three nameable functions instead of one opaque one.
Decomposition + Feature Organization: When algebraic decomposition splits a monolithic operation into orthogonal pieces, organize by feature domain. Example: splitting configureWidget(size, color, border) into resize, recolor, restyle lets each live in its own feature module.
-- 1. Define operations and observations
CartOps = { empty, addItem, removeItem, itemCount, totalPrice }
-- 2. Write rules
rule: itemCount(empty) == 0
rule: itemCount(addItem(cart, item)) == itemCount(cart) + 1
rule: removeItem(addItem(empty, x), x) == empty
rule: totalPrice(addItem(cart, item)) == totalPrice(cart) + item.price
-- 3. Rules become property tests
forAll(item -> assertEquals(itemCount(addItem(empty, item)), 1))
forAll(cart, item -> assertEquals(totalPrice(addItem(cart, item)), totalPrice(cart) + item.price))
-- 4. Implement naive version, run tests, then optimize