Functype Feature Matrix

This matrix shows which interfaces are supported by each data structure in the functype library.

Legend

✓ Full support
◐ Partial support (custom implementation)
✗ Not supported
← Inherited from parent interface

Core Interfaces

Data Structure	Functor	Applicative	Monad	AsyncMonad	Foldable	Matchable	Serializable	Traversable	Extractable	Unsafe	Pipe	Collection	ContainerOps	CollectionOps
Option	✓	✓	✓	✓	✓	✓	✓	✓	✓	←	✓	✗	✓	✗
Either<L,R>	✓	✓	✓	✓	✓	✗	✓	✗	✓	←	✗	✗	◐	✗
Try	✓	✓	✓	✓	✓	✗	✓	✗	✓	←	✓	✗	◐	✗
IO<R,E,A>	✓	✓	✓	✓	✓	✓	✗	✗	✗	✗	✓	✗	✗	✗
Http	✗	✗	✗	✗	✗	✗	✗	✗	✗	✗	✗	✗	✗	✗
TaskOutcome	✓	✓	✓	✓	✓	✗	✓	✓	✓	←	✓	✗	✓	✗
List	✓	✓	✓	✓	✓	✗	✓	✓	✗	✗	✓	✓	✓	✓
Set	✓	✓	✓	✓	✓	✗	✓	✓	✗	✗	✓	✓	✓	✓
Obj	◐	◐	◐	◐	✓	✓	✓	◐	✓	←	✓	✗	✓	✗
Map<K,V>	◐	✗	✗	✗	✓	✗	✓	◐	✗	✗	✓	✓	✗	✗
Lazy	✓	✓	✓	✓	✓	✗	✓	✓	✓	←	✓	✗	✓	✗
Stack	✗	✗	✗	✗	✓	✓	✓	✓	✗	✗	✓	✗	✗	✗
LazyList	◐	✗	◐	✗	✓	✗	✓	✗	✗	✗	✓	✗	✗	✗
Tuple<T[]>	◐	✗	◐	✗	✓	✗	✓	✗	✗	✗	✓	✗	✗	✗

Variance (0.6.0+)

Data Structure	Variance	Notes
Option	`<out T>`	covariant
Either<L,R>	`<out L, out R>`	covariant in both
Try	`<out T>`	covariant
List	`<out A>`	covariant. `contains`/`remove`/`indexOf` accept `unknown`; `add`/`prepend`/`concat` widen to `A \| B`; `reduce` guarded by `Widen<A, B>`
Set	`<out A>`	covariant. Same patterns as List
LazyList	`<out A>`	covariant. `concat<B>` widens
Lazy	`<out T>`	covariant
Identity	`<out T>`	covariant. `isSame` accepts `Identity<unknown>`
Tuple<T[]>	`<out T>`	covariant
Map<K,V>	`<K, out V>`	V covariant; K invariant (Scala Map[K, +V] precedent — equality-sensitive keys)
TaskOutcome	`<out T>`	covariant. `recover<U>` / `recoverWith<U>` widen to `Ok<T \| U>`
Stack	structural covariant	intersection type alias can’t carry `<out>`; subtyping works structurally
Obj	invariant (by design)	T is a record type; `keyof T` is contravariant, so widening loses key fidelity
Ref	invariant (by design)	mutable cell; `set(A)` writes A, widening would be unsound
IO<R,E,A>	`<in out R, out E, out A>`	E and A covariant; R invariant. `IO<R, never, A>` widens to `IO<R, AnyError, A>` without a cast. ZIO-style `<in R>` still deferred.

All base typeclasses (Traversable, Extractable, Functor, Applicative, Monad, AsyncMonad, ContainerOps, CollectionOps, Foldable, Serializable, Pipe, Matchable, Promisable, Doable, Reshapeable) declared <out T> / <out A>.

Traversable.reduce / reduceRight are guarded by Widen<A, B> (src/typeclass/variance.ts), TypeScript’s equivalent of Scala’s [B >: A] lower-bound constraint. See variance-guide.md for the full contributor reference.

Collections (List, Set, LazyList, Stack, Map, Obj) keep Traversable. Sum types (Either, Try) extend the lighter FunctypeSum base with no collection-style methods.

Additional Properties

Data Structure	Typeable	Valuable	Iterable	PromiseLike	Do-notation	Reshapeable	Promisable
Option	✓	✗	✗	✗	✓	✓	✓
Either<L,R>	✓	✗	✗	✓	✓	✓	✓
Try	✓	✗	✗	✗	✓	✓	✓
IO<R,E,A>	✗	✗	✓	✗	✓	✗	✗
Http	✗	✗	✗	✗	✗	✗	✗
List	✓	✗	✓	✗	✓	✓	✗
Set	✓	✗	✓	✗	✗	✗	✗
Obj	✓	✗	✗	✗	✓	✓	✓
Map<K,V>	✓	✗	✓	✗	✗	✗	✗
Lazy	✓	✗	✗	✗	✗	✗	✗
Stack	✓	✓	✗	✗	✗	✗	✗
LazyList	✓	✗	✓	✗	✗	✗	✗
Tuple<T[]>	✓	✓	✓	✗	✗	✗	✗
TaskOutcome	✓	✗	✗	✗	✓	✗	✓

Companion Methods

All types follow the Companion pattern (inspired by Scala), combining constructor functions with static utility methods. Each type provides:

Common Creation Methods

Data Structure	of	from	pure	empty	none	left	right	success	failure
Option	✓	✓	✗	✗	✓	✗	✗	✗	✗
Either<L,R>	✗	✗	✗	✗	✗	✓	✓	✗	✗
Try	✓	✗	✗	✗	✗	✗	✗	✓	✓
IO<R,E,A>	✗	✓	✗	✗	✗	✗	✗	✓	✓
Http	✗	✗	✗	✗	✗	✗	✗	✗	✗
List	✓	✗	✗	✓	✗	✗	✗	✗	✗
Set	✓	✗	✗	✓	✗	✗	✗	✗	✗
Obj	✓	✗	✗	✓	✗	✗	✗	✗	✗
Map<K,V>	✓	✗	✗	✓	✗	✗	✗	✗	✗
Lazy	✓	✗	✗	✗	✗	✗	✗	✗	✗
Stack	✗	✗	✗	✓	✗	✗	✗	✗	✗
LazyList	✓	✗	✗	✓	✗	✗	✗	✗	✗
Tuple<T[]>	✓	✗	✗	✗	✗	✗	✗	✗	✗
Identity	✓	✗	✓	✗	✗	✗	✗	✗	✗
Ref	✓	✗	✗	✗	✗	✗	✗	✗	✗

Collection creation - multiple options available:

// List creation
List([1, 2, 3]) // from array
List.of(1, 2, 3) // variadic factory
List.empty<number>() // typed empty list

// Set creation
Set([1, 2, 3]) // from array
Set.of(1, 2, 3) // variadic factory
Set.empty<number>() // typed empty set

// Map creation
Map([
  ["a", 1],
  ["b", 2],
]) // from key-value pairs
Map.of<string, number>(["a", 1], ["b", 2]) // variadic factory
Map.empty<string, number>() // typed empty map

Http Methods

// Http — fetch wrapper returning IO<never, HttpError, HttpResponse<unknown>> by default
// Provide a validate function to get typed responses (BYOV: bring your own validator)
Http.get(url, opts?)          // GET → HttpResponse<unknown>
Http.get(url, { validate })   // GET → HttpResponse<T> (T inferred from validate)
Http.post(url, opts?)         // POST with auto JSON body serialization
Http.put(url, opts?)          // PUT
Http.patch(url, opts?)        // PATCH
Http.delete(url, opts?)       // DELETE
Http.request(fullOpts)        // Full control
Http.client(config)           // Create configured client with baseUrl, defaultHeaders, custom fetch, beforeRequest (effectful request transformer)

// Example with validator (works with Zod, TypeBox, Valibot, or manual validators)
Http.get("/api/users", { validate: (data) => z.array(UserSchema).parse(data) })
Http.post("/api/users", { body: { name: "Alice" }, validate: (data) => UserSchema.parse(data) })

// HttpError — three-variant ADT
HttpError.networkError(url, method, cause)
HttpError.httpStatusError(url, method, status, statusText, body)
HttpError.decodeError(url, method, body, cause)
HttpError.match(error, { NetworkError, HttpStatusError, DecodeError })
HttpError.isNetworkError(e) / .isHttpStatusError(e) / .isDecodeError(e)

Validation & Typed Errors

Error-accumulating validation — functype’s “Validated” applicative role. Validation collects all field errors rather than short-circuiting on the first (unlike Either.sequence, which fails fast). Not a typeclass-grid container, so it lives here rather than in the interface matrix above (same as HttpError / DecoderError).

// FormValidation<T> — the accumulating result type
type FormValidation<T> = Either<List<TypedError<"VALIDATION_FAILED">>, T>

// TypedError — code-tagged structured error (extends Throwable)
TypedError.validation(field, value, rule)   // → TypedError<"VALIDATION_FAILED">, context { field, value, rule }
TypedError.isTypedError(v) / TypedError.hasCode(e, code)

// Validation — rule DSL + form validator
Validation.rule<T>("min:18" | "email" | "required" | "pattern:..." | "in:a,b" | ...)
Validation.combine(...validators)                 // all must pass (fail-fast per field)
Validation.custom<T>(predicate, message)          // custom per-field rule
Validation.validators.email / .url / .required / .positiveNumber / .nonEmptyString
Validation.form(schema, data)                     // → FormValidation<T>, accumulates every field error

// Validator<T> = (value: unknown) => Either<TypedError<"VALIDATION_FAILED">, T>
// form() is flat/per-field. For cross-field (lo < hi) or dynamic-key (weights.*) checks,
// hand-accumulate TypedError.validation(...) into a List and return the same FormValidation shape.

Type Guards

Static type guards for narrowing types:

Data Structure	Type Guard Methods
Option	`isSome(option)`, `isNone(option)`
Either<L,R>	`isLeft(either)`, `isRight(either)`
Try	`isSuccess(tryValue)`, `isFailure(tryValue)`

Serialization Methods

All Serializable types provide static deserialization methods:

fromJSON(json: string): T - Deserialize from JSON
fromYAML(yaml: string): T - Deserialize from YAML
fromBinary(binary: string): T - Deserialize from base64-encoded binary

Note: See docs/companion-pattern.md for complete guide on the Companion pattern.

Key Methods by Interface

Functor

map(f: (value: A) => B): Functor

Applicative (extends Functor)

ap(ff: Applicative<(value: A) => B>): Applicative

Monad (extends Applicative)

flatMap(f: (value: A) => Monad): Monad

AsyncMonad (extends Monad)

flatMapAsync(f: (value: A) => PromiseLike<AsyncMonad>): PromiseLike<AsyncMonad>

Foldable

foldLeft(z: B): (op: (b: B, a: A) => B) => B
foldRight(z: B): (op: (a: A, b: B) => B) => B

Note: fold has different semantics per type category:

Sum types (Option, Either, Try, IO, TaskOutcome): fold(onEmpty: () => B, onValue: (value: A) => B): B — pattern match
Collections (List, Set, Map, Stack, Tuple, LazyList): fold(initial: B, fn: (acc: B, a: A) => B): B — left-reduce accumulator

foldAsync (Option, Either, Try) — same shape as fold but accepts sync or async handlers and always returns Promise. Use when at least one branch performs async work to avoid T | Promise<T> unions.

Matchable

match<R>(patterns: Record<Tags, (value: A) => R>): R

Serializable

serialize(): SerializationMethods<T>
- toJSON(): string
- toYAML(): string
- toBinary(): Uint8Array

Traversable (extends AsyncMonad)

size: number
isEmpty: boolean
contains(value: A): boolean
reduce(f: (acc: B, value: A) => B, initial: B): B
reduceRight(f: (value: A, acc: B) => B, initial: B): B

Unsafe

orThrow(error?: Error): T

Extractable (extends Unsafe)

orElse(defaultValue: T): T
or(alternative: Extractable<T>): Extractable<T>
orNull(): T | null
orUndefined(): T | undefined

Pipe

pipe(f: (value: T) => U): U

Collection

toList(): List<A>
toSet(): Set<A>
toString(): string

ContainerOps

count(p: (value: A) => boolean): number
find(p: (value: A) => boolean): A | undefined
exists(p: (value: A) => boolean): boolean
forEach(f: (value: A) => void): void

CollectionOps

drop(n: number): Self
dropRight(n: number): Self
dropWhile(p: (value: A) => boolean): Self
flatten(): Self
head: A | undefined
headOption: Option<A>
take(n: number): Self
takeWhile(p: (value: A) => boolean): Self
takeRight(n: number): Self
last: A | undefined
lastOption: Option<A>
tail: Self
init: Self
toArray(): A[]

List-specific Methods

reverse(): List<A>
indexOf(value: A): number
prepend(item: A): List<A>
distinct(): List<A>
sorted(compareFn?): List<A>
sortBy(f, compareFn?): List<A>
zip(other: List): List<[A, B]>
zipWithIndex(): List<[A, number]>
groupBy(f: (a: A) => K): Map<K, List<A>>
partition(p): [List<A>, List<A>]
span(p): [List<A>, List<A>]
slice(start, end): List<A>

Do-notation Support

Enables Scala-like for-comprehensions using JavaScript generators:

Do(function* () { ... }): Synchronous monadic comprehensions
DoAsync(async function* () { ... }): Async monadic comprehensions
$(monad): Helper for type inference with yield*

Reshapeable

Provides type conversion between monadic types:

toOption(): Option<T>
toEither<E>(leftValue: E): Either<E, T>
toList(): List<T>
toTry(): Try<T>

Promisable

Provides conversion to Promise for async interop:

toPromise(): Promise<T>

Notes

Functype<A, Tag>: Implemented by single-value containers (Option, Try, Lazy). Provides full functional programming support.
FunctypeCollection<A, Tag>: Implemented by collection containers (List, Set). Extends FunctypeBase with collection-specific operations.
Special Cases:
- Either: Implements FunctypeBase but not full Functype (no Extractable/Matchable)
- Map: Uses KVTraversable (omits map/flatMap/ap from Traversable — key-value containers can’t freely transform their type parameter)
- Obj: Immutable object wrapper using KVTraversable. Record-constrained map/flatMap (B must be a Record). Provides fluent ops: get, set, assign, merge, when, omit, pick
- Stack: Implements individual interfaces without FunctypeBase
- LazyList: Lazy evaluation with support for Foldable, Serializable, Pipe, and Typeable interfaces
- Tuple: Enhanced container with Foldable, Serializable, Pipe, Typeable, and Valuable support
Do-notation: Provides generator-based monadic comprehensions similar to Scala’s for-comprehensions. Supports Option, Either, Try, and List with automatic short-circuiting and cartesian products.
Reshapeable: Enables conversion between different monad types, allowing flexible composition in Do-notation when mixing types.
Promisable: Provides conversion to Promise for async interoperability. Supported by Option, Either, Try, and TaskOutcome.
Utility Types (not in matrix):
- Cond: Conditional expression builder
- Match: Pattern matching utility
- ValidatedBrand: Branded types with validation
- Task: Sync/async operation orchestrator returning TaskOutcome with Ok/Err constructors. Includes conversion methods: toEither(), toTry(), toOption(), fromEither(), fromTry().
- Throwable: Enhanced error type
IO<R,E,A>: Lazy, composable effect type with typed errors and dependency injection.
- R = Requirements (environment/dependencies needed to run)
- E = Error type (typed failures)
- A = Success type (value produced on success)
- Key features:
 - Lazy execution (nothing runs until explicitly executed)
 - Unified sync/async API (auto-detects Promise returns)
 - Typed errors at compile time
 - Composable via map/flatMap
 - Dependency injection via Tag/Layer/Context
 - Structured concurrency: bracket, race, timeout
 - Generator do-notation (IO.gen) and builder do-notation (IO.Do)
 - Error handling: catchTag, catchAll, retry, retryWithDelay, retryWhile, retryWithBackoff
 - Value-driven repetition: repeatUntil, repeatWhile, IO.iterate (bounded by RepeatExhausted)
 - Execution methods: run(), runOrThrow(), runSync(), runSyncOrThrow(), runExit(), runOption(), runTry()
 - Outcomes: Exit<E, A> = Success | Failure | Die | Interrupted, returned by runExit(). Failure carries a value from the declared E channel; Die carries a defect — a value that is not an E (a throwing IO.sync thunk, a throwing map/flatMap/mapError callback, or IO.die). run() returns Either, which has no branch for either a defect or an interruption, so both arrive in the Left; runExit() is what keeps them apart. Defects stay recoverable — recover/recoverWith/fold/mapError treat Die as Failure. fold’s onDie and match’s Die are optional and fall back to the failure handler.
- Testing utilities:
 - TestClock: Controlled time for testing timeouts/delays
 - TestContext: Test environment with mocked services