Skip to content
Skills Library
Programming · Building & coding

functype-developer

/functype-developer

Assist contributors working on the functype library codebase. Use this skill when creating new data structures, implementing functional interfaces (Functor, Monad, Foldable), adding tests, debugging library internals, or understanding functype's Scala-inspired architecture patterns including the Base pattern, HKT system, and Companion utilities.

Repository
functype ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
2
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/new-type-template.sh, scripts/validate.sh

What it does and when to use it

Assist contributors working on the functype library codebase. Use this skill when creating new data structures, implementing functional interfaces (Functor, Monad, Foldable), adding tests, debugging library internals, or understanding functype's Scala-inspired architecture patterns including the Base pattern, HKT system, and Companion utilities.

Original author description

Assist contributors working on the functype library codebase. Use this skill when creating new data structures, implementing functional interfaces (Functor, Monad, Foldable), adding tests, debugging library internals, or understanding functype's Scala-inspired architecture patterns including the Base pattern, HKT system, and Companion utilities.

How it works

  1. Overview
  2. When to Use This Skill
  3. Development Workflow
  4. Core Architecture
  5. Creating a New Data Structure
  6. Testing Patterns
  7. Code Style Guidelines
  8. Common Development Tasks
  9. Debugging Tips
  10. Variance (covariance — <out T>)
Original SKILL.md headings · 596 lines, 1,797 words
SKILL.md preview
---
name: functype-developer
description: Assist contributors working on the functype library codebase. Use this skill when creating new data structures, implementing functional interfaces (Functor, Monad, Foldable), adding tests, debugging library internals, or understanding functype's Scala-inspired architecture patterns including the Base pattern, HKT system, and Companion utilities.
---

# Functype Library Developer

## Overview

Guide for contributing to the functype TypeScript library. This skill provides architectural patterns, development workflows, and tooling for implementing new functional data structures following functype's Scala-inspired design.

## When to Use This Skill

Trigger this skill when:

- Creating new data structures or types
- Adding methods to existing data structures
- Implementing functional interfaces (Functor, Monad, Foldable, etc.)
- Adding or fixing tests
- Understanding library architecture
- Debugging functional type implementations
- Following the Base pattern and type class system
- Working with the Feature Matrix

## Development Workflow

### Prerequisites

- **Node.js**: ≥ 18.0.0
- **pnpm**: 10.12.1
- **TypeScript**: Strict mode enabled

### Essential Commands

```bash
# Install dependencies
pnpm install

# Development (build with watch)
pnpm dev

# Before committing (MUST PASS)
pnpm validate

# Run tests
pnpm test

# Run specific test file
pnpm vitest run test/specific.spec.ts

# Check types without building
pnpm compile
```

### Pre-Commit Checklist

**Always run before committing:**

```bash
pnpm validate
```

This runs:

1. **Format**: Prettier formatting
2. **Lint**: ESLint checks
3. **Test**: All Vitest tests
4. **Build**: Production build

## Core Architecture

### Scala-Inspired Constructor Pattern

All types follow this pattern:

```typescript
// Constructor function returns object with methods
const option = Option(value) // Constructor
option.map((x) => x + 1) // Instance methods
Option.none() // Companion methods
```

**NOT class-based:**

```typescript
// ❌ Don't do this
class Option<T> {
  constructor(value: T) { ... }
}

// ✅ Do this
export function Option<T>(value: T | null | undefined): OptionType<T> {
  return value == null ? none() : some(value)
}
```

### Naming and API Shape

Scala is where the design started, not the spec. Before naming a method or choosing its shape, check what native ES, Effect, fp-ts, Immutable.js, Scala, Haskell and Rust call it. Prefer the name most of them share, or the one that fits functype's own existing contracts. For example, `Map.has(key)` follows native, Effect and Immutable.js, not Scala's `contains(key)`.

### Base Pattern

Use the `Base` function to add common functionality to all types:

```typescript
import { Base } from "@/core/base"

export function Option<T>(value: T | null | undefined): OptionType<T> {
  if (value == null) {
    return Base("None", {
      // methods here
      map: <B>(f: (val: T) => B) => Option.none<B>(),
      // ...
    })
  }

  return Base("Some", {
    // methods here
    map: <B>(f: (val: T) => B) => Option(f(value)),
    // ...
  })
}
```

**Base provides:**

- `Typeable` interface (type metadata)
- Standard `toString()` method
- Consistent object structure

### Type System Foundation

**Base constraint:**

```typescript
import type { Type } from "@/functor"

// Use Type instead of any
function process<T extends Type>(value: T): void {
  // ...
}
```

**Never use `any`**:

- Use `unknown` for uncertain types
- Use `Type` for generic constraints
- Use proper type definitions

### Functional Interfaces

Every container type should implement these when applicable:

**Core interfaces** (see `references/architecture.md` for details):

- `Functor` - map over values
- `Applicative` - apply wrapped functions
- `Monad` - flatMap for sequencing
- `Foldable` - extract via pattern matching
- `Traversable` - collection operations
- `Serializable` - JSON/YAML/binary serialization

**Reference the Feature Matrix:**
Check `docs/FUNCTYPE_FEATURE_MATRIX.md` to see which interfaces each type implements and what methods are required.

## Creating a New Data Structure

### Step-by-Step Guide

**1. Research existing patterns**

```bash
# Use the Explore agent to understand the codebase
# Look at Option, Either, or Try as reference implementations
```

**2. Create module structure**

```bash
mkdir -p src/mynewtype
touch src/mynewtype/index.ts
touch test/mynewtype.spec.ts
```

**3. Use the template script**

```bash
# Run the new-type-template script
./claude/skills/functype-developer/scripts/new-type-template.sh MyNewType
```

This generates:

- Basic type structure
- Required interface implementations
- Test file boilerplate

**4. Implement the type**

Follow the constructor pattern:

```typescript
// src/mynewtype/index.ts
import { Base } from "@/core/base"
import type { Functor } from "@/functor"

export type MyNewType<T> = Functor<T> & {
  // Your methods here
  getValue(): T
}

export function MyNew<T>(value: T): MyNewType<T> {
  return Base("MyNewType", {
    // Functor
    map: <B>(f: (val: T) => B): MyNewType<B> => {
      return MyNew(f(value))
    },

    // Your methods
    getValue: () => value,

    // Pipe for composition
    pipe: () => ({
      map: (f: (val: T) => any) => MyNew(value).map(f),
    }),
  })
}

// Companion methods
MyNew.empty = <T>() => MyNew<T>(null as any)
```

**5. Add exports**

Update `src/index.ts`:

```typescript
export { MyNew } from "./mynewtype"
export type { MyNewType } from "./mynewtype"
```

Update `package.json` exports:

```json
{
  "exports": {
    "./mynewtype": {
      "import": "./dist/esm/mynewtype/index.js",
      "require": "./dist/cjs/mynewtype/index.js",
      "types": "./dist/types/mynewtype/index.d.ts"
    }
  }
}
```

**6. Write comprehensive tests**

```typescript
// test/mynewtype.spec.ts
import { describe, expect, it } from "vitest"
import { MyNew } from "@/mynewtype"

describe("MyNewType", () => {
  describe("Construction", () => {
    it("should create from value", () => {
      const value = MyNew(5)
      expect(value.getValue()).toBe(5)
    })
  })

  describe("Functor", () => {
    it("should map over values", () => {
      const result = MyNew(5).map((x) => x * 2)
      expect(result.getValue()).toBe(10)
    })
  })

  // More tests...
})
```

**7. Update Feature Matrix**

Add your type to `docs/FUNCTYPE_FEATURE_MATRIX.md` showing which interfaces it implements.

**8. Validate**

```bash
pnpm validate
```

### Interface Implementation Checklist

When implementing interfaces, refer to this checklist:

**Functor:**

- [ ] `map<B>(f: (value: A) => B): Functor<B>`

**Applicative (extends Functor):**

- [ ] `ap<B>(ff: Applicative<(value: A) => B>): Applicative<B>`

**Monad (extends Applicative):**

- [ ] `flatMap<B>(f: (value: A) => Monad<B>): Monad<B>`

**Foldable:**

- [ ] `fold<B>(onEmpty: () => B, onValue: (value: A) => B): B`
- [ ] `foldLeft<B>(z: B): (op: (b: B, a: A) => B) => B`
- [ ] `foldRight<B>(z: B): (op: (a: A, b: B) => B) => B`

See `references/architecture.md` for complete interface definitions.

## Testing Patterns

### Test Structure

Use Vitest with describe/it pattern:

```typescript
describe("TypeName", () => {
  describe("Feature Group", () => {
    it("should do specific thing", () => {
      // Arrange
      const input = createInput()

      // Act
      const result = performOperation(input)

      // Assert
      expect(result).toBe(expected)
    })
  })
})
```

### Property-Based Testing

Use fast-check for property tests:

```typescript
import { fc, test } from "@fast-check/vitest"

test.prop([fc.integer()])("should always return positive", (n) => {
  const result = Math.abs(n)
  expect(result).toBeGreaterThanOrEqual(0)
})
```

### Edge Cases to Test

Always test:

- Empty/null/undefined inputs
- Type inference correctness
- Method chaining
- Error cases
- Immutability (original unchanged)

## Code Style Guidelines

### Imports

```typescript
// Type-only imports when possible
import type { Type } from "@/functor"
import { Option } from "@/option"

// Organized with simple-import-sort (automatic)
```

### Types

```typescript
// ✅ Use Type for constraints
function process<T extends Type>(value: T): void

// ✅ Prefer types over interfaces
export type MyType<T> = {
  value: T
}

// ✅ Explicit type annotations
function transform<T>(input: T): MyType<T> {
  return { value: input }
}
```

### Naming

```typescript
// PascalCase for types
type OptionType<T> = { ... }

// camelCase for functions/variables
const someValue = Option(5)
function mapOption<T>(opt: OptionType<T>) { ... }

// Constructor functions are PascalCase
Option(value)
Either(value)
```

### Functional Style

```typescript
// ✅ Immutability
const newList = list.append(item)

// ❌ Mutation
list.push(item)

// ✅ Pure functions
function double(x: number): number {
  return x * 2
}

// ❌ Side effects
function double(x: number): number {
  console.log(x) // side effect
  return x * 2
}
```

### Pattern Matching

```typescript
// ✅ Use Cond for conditionals
import { Cond } from "@/cond"

Cond.start<string>()
  .case(x > 10, "big")
  .case(x > 5, "medium")
  .otherwise("small")

// ✅ Use Match for switches
import { Match } from "@/match"

Match(status)
  .case("success", () => handleSuccess())
  .case("error", () => handleError())
  .done()

// ❌ Avoid early returns
// Use Cond or Option instead
```

## Common Development Tasks

### Adding a Helper Method

```typescript
// Add to type definition
export type MyType<T> = {
  // existing methods...

  // New helper
  isEmpty(): boolean
}

// Implement in constructor
export function MyType<T>(value: T): MyType<T> {
  return Base("MyType", {
    // existing methods...

    isEmpty: () => value == null,
  })
}
```

### Implementing Serialization

```typescript
import { createSerializable } from "@/core/serializable"

export function MyType<T>(value: T): MyType<T> {
  return Base("MyType", {
    // other methods...

    serialize: () =>
      createSerializable({
        type: "MyType",
        value: value,
      }),
  })
}
```

### Adding Do-Notation Support

```typescript
export const MyTypeCompanion = {
  Do: <T>(gen: () => Generator<MyType<any>, T, any>): MyType<T> => {
    // Implementation here
    // See Option or Either for reference
  },
}

export const MyType = Object.assign(MyTypeConstructor, MyTypeCompanion)
```

## Debugging Tips

### TypeScript Errors

**"Type instantiation is excessively deep"**

- Check for circular type references
- Simplify nested generic types
- Use type aliases to break up complex types

**"Property 'X' does not exist on type 'Y'"**

- Ensure all interfaces are properly implemented
- Check that types are correctly exported
- Verify Base pattern includes all required methods

### Test Failures

```bash
# Run specific test with verbose output
pnpm vitest run test/mytype.spec.ts --reporter=verbose

# Run tests in watch mode
pnpm test:watch

# Check test coverage
pnpm test:coverage
```

### Build Issues

```bash
# Clean and rebuild
pnpm clean && pnpm build

# Check TypeScript compilation only
pnpm compile

# Analyze bundle size
pnpm analyze:size
```

## Variance (covariance — `<out T>`)

Most functype containers are declared covariant in their type parameter(s) —
`List<out A>`, `Either<out L, out R>`, etc. When adding a new container or a
new method, follow these four rules and the variance declaration will hold:

1. **Element-query / removal** (`contains`, `indexOf`, `remove`, `has`) → accept
   `unknown`. Equality with an unrelated value is a safe `false` at runtime.
2. **Additive** (`add`, `prepend`, `concat`, `push`, `set`) → widen via
   `<B>(item: B): C<A | B>`. The return union accurately reflects runtime.
3. **Aggregation** (`reduce`, `reduceRight`) → guard with `Widen<A, B>`:
   ```ts
   import { type Widen, reduceWiden } from "@/typeclass"
   reduce: <B = A>(op: (b: Widen<A, B>, a: Widen<A, B>) => Widen<A, B>): Widen<A, B> =>
     reduceWiden<A, Widen<A, B>>(array, op)
   ```
   `Widen<A, B> = A extends B ? B : never`. Blocks `list.reduce<UnrelatedType>(...)`
   at compile time.
4. **Recovery / fallback** (`or`, `orElse`, `recover`) → widen via
   `<T2>(...): T | T2` or `C<T | T2>`.

**When to stay invariant:** mutable cells (`Ref<A>`), record types with
`keyof` dependence (`Obj<T>`), equality-sensitive keys (`Map<K, _>`). Document
the choice in JSDoc with a brief "why".

**When TS rejects `<out>`:** the compiler names the offending method. Fix it
using the rules above and re-annotate.

**Regression tests:** add `test/<path>/<type>-variance.spec.ts` patterned after
`test/either/either-variance.spec.ts` (comprehensive) or `test/list/list-variance.spec.ts`
(minimal). Type-only assertions run in milliseconds and catch silent regressions.

Full recipe: **`docs/variance-guide.md`**.

## Resources

### scripts/

- `new-type-template.sh` - Generate boilerplate for new types
- `validate.sh` - Run the full validation workflow

### references/

- `architecture.md` - Detailed architecture and patterns
- `adding-types.md` - Complete guide for adding new data structures
- `adding-methods.md` - Checklist for adding methods to existing types
- `testing-patterns.md` - Testing strategies and examples

### External Links

- **GitHub**: https://github.com/jordanburke/functype
- **Docs**: https://jordanburke.github.io/functype/
- **Feature Matrix**: `docs/FUNCTYPE_FEATURE_MATRIX.md`
- **Variance Guide**: `docs/variance-guide.md`
Files in this package (7)
  • SKILL.md 13 KB
  • references/adding-methods.md 3 KB
  • references/adding-types.md 8 KB
  • references/architecture.md 12 KB
  • references/testing-patterns.md 8 KB
  • scripts/new-type-template.sh 4 KB
  • scripts/validate.sh 1 KB

Versions

The database has no other skills named functype-developer.

Database snapshot: 13.11.2026 · package version 5960368664cd (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95functype
    Help developers use functype functional programming patterns in their TypeScript projects. Use this skill when converting imperative/OOP code to functional patterns, looking up functype APIs and methods, handling nulls with Option, managing errors with Either/Try, composing…
  • 95python-scala-functional-generics
    Guide for translating Python generic containers (covariant/contravariant), functor/monad simulations, and JSON handling to idiomatic Scala. Use this skill when converting Python Generic[T_co], Generic[T_contra], TokenFunctor, TokenMonad, or json.dumps/json.loads patterns to…
  • 100sdma
    Structured Domain Modeling Architecture (SDMA) principles. Trigger when: - Designing domain models, building ologs (ontological graphs), verifying protocol equivalence, selecting schemas, or measuring architectural entropy. - Modeling structures using Category Theory, Coalgebra,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.