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.
- Author
- jordanburke ↗
- Repository
- functype ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 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
- Overview
- When to Use This Skill
- Development Workflow
- Core Architecture
- Creating a New Data Structure
- Testing Patterns
- Code Style Guidelines
- Common Development Tasks
- Debugging Tips
- Variance (covariance — <out T>)
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,…