Claude Code Skill

This page documents the Claude Code skill for @deessejs/fp. The skill makes functional programming patterns discoverable within Claude Code.

The skill is automatically loaded when you ask about error handling, optional values, or async operations in TypeScript.

Getting Started

The skill is located at .claude/skills/deesse-fp/SKILL.md in the repository.

Installation

The skill is already included in the repository. When you clone @deessejs/fp, the skill is automatically available in Claude Code.

Usage

You can invoke the skill in two ways:

Direct invocation:
```
/deesse-fp
```
Natural language - Claude will automatically load the skill when you ask about:
- Error handling in TypeScript
- Optional values / Maybe
- Result type patterns
- Try / AsyncResult usage

Quick Reference

Creating Values

import { ok, err, some, none, okAsync, errAsync, attempt } from "@deessejs/fp";

// Result - explicit success/failure
const success = ok(42);
const failure = err("Something went wrong");

// Maybe - optional values
const present = some("hello");
const absent = none();

// Try - wrap throwing functions
const parsed = attempt(() => JSON.parse(jsonString));

// AsyncResult - async operations
const asyncOk = okAsync(data);
const asyncErr = errAsync(new Error("failed"));

Transforming

// map - transform the success value
const doubled = ok(10).map(x => x * 2); // Ok(20)

// flatMap - chain operations returning Result
const result = ok("10")
  .flatMap(s => parseInt(s))
  .flatMap(n => divide(n, 2));

// mapErr - transform the error
const customError = err("original").mapErr(e => new Error(e));

Extracting

// getOrElse - get value or default
const value = ok(42).getOrElse(0); // 42
const defaultVal = err("oops").getOrElse(0); // 0

// getOrCompute - lazy default
const computed = err("oops").getOrCompute(() => expensiveOperation());

// match - pattern matching
const message = ok(42).match(
  (v) => `Success: ${v}`,
  (e) => `Error: ${e}`
);

// tap - side effects without changing value
ok(42).tap(v => console.log(v)); // logs 42, returns Ok(42)

Type Guards

import { isOk, isErr, isSome, isNone } from "@deessejs/fp";

if (isOk(result)) {
  console.log(result.value); // TypeScript knows it's Ok
}

if (isSome(maybe)) {
  console.log(maybe.value); // TypeScript knows it's Some
}

Common Patterns

1. Input Validation

function validateEmail(email: string): Result<Email, string> {
  if (!email.includes("@")) return err("Invalid email");
  return ok(email as Email);
}

2. Optional Configuration

function getConfig(key: string): Maybe<Config> {
  return fromNullable(config[key]);
}

const dbConfig = getConfig("database")
  .map(c => c.host)
  .getOrElse("localhost");

3. Safe JSON Parsing

const data = attempt(() => JSON.parse(userInput));
if (isErr(data)) {
  return err(`Parse error: ${data.error.message}`);
}
return ok(data.value);

4. Async API Calls

async function fetchUser(id: string): AsyncResult<User, Error> {
  const response = await fetch(`/api/users/${id}`);
  if (!response.ok) {
    return errAsync(new Error(`HTTP ${response.status}`));
  }
  return okAsync(await response.json());
}

5. Chaining Operations

const finalPrice = ok(cart)
  .flatMap(validateCart)
  .map(applyDiscount)
  .map(calculateTax)
  .getOrElse(0);

6. Error Accumulation

const errors: string[] = [];
if (!isValid(email)) errors.push("Invalid email");
if (!isValid(age)) errors.push("Invalid age");

if (errors.length > 0) return err(errors);
return ok(formData);

Error System

import { error, raise } from "@deessejs/fp";

const validationError = error({
  name: "ValidationError",
  args: { field: "email", reason: "missing @" }
});

// Add notes
const withNotes = { ...validationError, notes: ["Try adding a valid email"] };

// Use in transformations with raise
const validated = ok(input).mapErr(e => raise(validationError));

Conversions

import { toResult, toMaybeFromResult, fromNullable } from "@deessejs/fp";

// Maybe → Result
const result = toResult(maybe, () => "default error");

// Result → Maybe
const maybe = toMaybeFromResult(result);

// undefined/null → Maybe
const maybe = fromNullable(value);

When to Use Each Type

Type	Use When
Result	Explicit success/failure with typed errors
Maybe	Value might exist or not (no error context)
Try	Wrapping synchronous functions that might throw
AsyncResult	Async operations with error handling