functional-code_skill

Overview

This skill guides writing pure, functional JavaScript code that emphasizes immutability, explicit dependencies, and testability. It includes an automated auditor to scan code for functional-programming violations and generates clear, actionable refactoring suggestions. The goal is to separate pure business logic from I/O, make errors explicit as values, and promote declarative data transformations.

How this skill works

The skill inspects JavaScript/TypeScript source for common FP anti-patterns: mutating array/object methods, hidden I/O in core logic, imperative loops, thrown validation errors, and hidden globals. It produces a structured report with severity levels, code snippets of the violation, suggested fixes (e.g., spread instead of push), and rationale. You can run targeted audits, export JSON for automation, and integrate the auditor into CI or workflow pipelines to enforce FP rules continuously.

When to use it

• Creating new functions or business logic to keep them pure and testable
• Refactoring existing code to remove mutation and hidden side effects
• Implementing data transformations using map/filter/reduce instead of loops
• Handling errors in APIs or edge functions by returning Result/Either values
• Separating pure logic from I/O using the Functional Core / Imperative Shell pattern
• Auditing a codebase for FP violations and generating prioritized refactoring tasks

Best practices

• Keep pure functions deterministic: same inputs → same outputs, no hidden globals
• Never mutate inputs; return new objects/arrays using spread, filter, map
• Push all I/O to the shell layer; core logic must be side-effect free
• Return errors as Result/Either types for expected failures; reserve throw for unexpected bugs
• Pass dependencies explicitly (dependency injection) so functions remain testable
• Prefer declarative higher-order functions and small composable utilities

Example use cases

• Audit pricing calculators to replace push/sort mutations with immutable patterns
• Refactor an HTTP handler to extract a pure merge/validate core and a thin I/O shell
• Convert validation that throws into functions returning Result/Either for predictable flows
• Transform imperative data processing loops into map/filter/reduce pipelines
• Integrate the auditor in a pre-commit or CI job to prevent new FP regressions