Structured errors, nominal types, and time primitives.
Structured, immutable error constructors with discriminant tags.
import { ErrType } from '@igorjs/pure-fx'
// Define error kinds
const NotFound = ErrType('NotFound'); // code: 'NOT_FOUND' (auto-derived)
const Forbidden = ErrType('Forbidden'); // code: 'FORBIDDEN'
const DbError = ErrType('DbError', 'DB_ERR'); // explicit code
// Create instances (frozen, immutable)
const err = NotFound('User not found', { userId: 'u_123' });
err.tag; // 'NotFound'
err.code; // 'NOT_FOUND'
err.message; // 'User not found'
err.metadata; // { userId: 'u_123' }
err.timestamp; // Date.now()
err.stack; // stack trace
// Cause chains (Error.cause convention)
const inner = DbError('connection refused');
const outer = NotFound('user lookup failed', { cause: inner });
outer.cause; // the DbError instance
outer.toString(); // "NotFound(NOT_FOUND): user lookup failed [caused by: DbError(DB_ERR): connection refused]"
// Type guards
NotFound.is(err); // true, narrows type
Forbidden.is(err); // false
ErrType.is(err); // true (any ErrType)
// Convert to Result
err.toResult(); // Err(err)
// Serialize
err.toJSON(); // { tag, code, message, metadata, timestamp, cause }Branded types that prevent mixing structurally identical values.
import type { Type } from '@igorjs/pure-fx'
type UserId = Type<'UserId', string>;
type OrderId = Type<'OrderId', string>;
const userId = 'u_123' as UserId;
const orderId = 'o_456' as OrderId;
// These are both strings, but TypeScript prevents mixing:
function getUser(id: UserId) { /* ... */ }
getUser(userId); // OK
getUser(orderId); // TYPE ERRORType<...> is type-level-only. TypeDef adds runtime validation: each
branded type owns its schema and a uniform parse/new/validate/is/
unsafe surface.
import { TypeDef, Schema } from '@igorjs/pure-fx'
class UserId extends TypeDef('UserId', Schema.uuid) {}
UserId.parse(input); // Result<Type<'UserId', string>, SchemaError>
UserId.is(input); // input is Type<'UserId', string>
UserId.tag; // 'UserId'
// Validation with error accumulation:
UserId.validate(input); // Validation<Type<'UserId', string>, SchemaError>
// Dev-mode-checked passthrough (zero cost in production):
const u = UserId.unsafe(knownGoodString);Extract the branded value type with TypeDef.Infer:
type UserIdValue = TypeDef.Infer<typeof UserId>;
// = Type<'UserId', string>TypeDef classes are validators, not data carriers: new UserId() throws.
Seven JS-native primitives ship branded, with a uniform static surface so you can extend them directly:
| Type | Backs | Notes |
|---|---|---|
Str |
string |
any string |
Num |
number |
rejects NaN, allows Infinity |
Int |
number |
Number.isInteger(value) must hold |
UInt |
number |
non-negative integer |
Bool |
boolean |
strict, no coercion |
Bytes |
Uint8Array |
accepts Node Buffer, rejects ArrayBuffer |
Nil |
null |
strictly the literal null |
import { Str, Int, UInt, Bool, Bytes, Nil } from '@igorjs/pure-fx'
class Username extends Str {}
class Score extends Int {}
Username.parse('alice'); // Result<Type<'Str', string>, SchemaError>
Score.parse(42);Nine generic factories build new branded types from existing ones. Vec,
Dict, Pair, Tuple, Either return deep-frozen native snapshots;
Struct, ListOf, MapOf return pure-fx Immutable
collections (functional API + copy-on-write produce). Reference-keyed
composers are cached so Vec(X) === Vec(X) holds (Tuple/Struct take
unbounded shapes and are not cached — hold them in a const/class).
| Composer | Validates | Returns |
|---|---|---|
Vec(T) |
T[] |
frozen readonly T[] branded |
Pair(A, B) |
[A, B] |
frozen readonly [A, B] branded |
Tuple(...T) |
n-tuple | frozen readonly [...T] branded |
Dict(K, V) |
string-keyed record | frozen Readonly<Record<K, V>> branded |
ListOf(T) |
T[] |
ImmutableList<T> branded |
MapOf(K, V) |
string-keyed record | ImmutableHashMap<K, V> branded |
Struct({...}) |
named heterogeneous object | ImmutableRecord<{...}> branded |
Maybe(T) |
{tag:'Some',value:T} | {tag:'None'} | null | undefined |
Option<T> branded |
Either(L, R) |
{tag:'Left',value:L} | {tag:'Right',value:R} |
tagged sum branded |
Vec/Dict are lightweight snapshots (a branded frozen array/object) — use
plain indexing/property access. ListOf/MapOf are the collection variants:
access their parsed values through the collection API (.at(i), .get(key),
.size, .produce(...)). Struct is the heterogeneous counterpart to Dict/
MapOf: each field has its own TypeDef.
import { TypeDef, Schema, Struct } from '@igorjs/pure-fx'
class UserId extends TypeDef('UserId', Schema.uuid) {}
class Email extends TypeDef('Email', Schema.email) {}
class User extends Struct({ id: UserId, email: Email }) {}
const r = User.parse({ id: '550e8400-e29b-41d4-a716-446655440000', email: 'a@b.com' });
if (r.isOk) {
r.value.id; // Type<'UserId', string>
r.value.email; // Type<'Email', string>
// r.value is an ImmutableRecord — assignment throws
}import { TypeDef, Schema, Vec, Pair, Dict, Maybe, Either } from '@igorjs/pure-fx'
class Email extends TypeDef('Email', Schema.email) {}
class Latitude extends TypeDef('Latitude', Schema.number.refine(n => n >= -90 && n <= 90, 'lat')) {}
class Longitude extends TypeDef('Longitude', Schema.number.refine(n => n >= -180 && n <= 180, 'lng')) {}
class Emails extends Vec(Email) {}
class GeoPoint extends Pair(Latitude, Longitude) {}
class Headers extends Dict(Str, Str) {}
class MaybeEmail extends Maybe(Email) {}The catalogue is deliberately minimal. Application types are one-line user-side definitions:
import { TypeDef, Schema } from '@igorjs/pure-fx'
class Email extends TypeDef('Email', Schema.email) {}
class Uuid extends TypeDef('Uuid', Schema.uuid) {}
class HttpUrl extends TypeDef('HttpUrl', Schema.url) {}
class Port extends TypeDef(
'Port',
Schema.int.refine(n => n >= 1 && n <= 65535, 'port'),
) {}
class Money extends TypeDef('Money', Schema.object({
amount: Schema.string.refine(s => /^-?\d+(\.\d+)?$/.test(s), 'decimal'),
currency: Schema.string.refine(s => s.length === 3, 'iso 4217'),
})) {}Then compose freely:
class Wallet extends Dict(Str, Money) {}
class Failure extends Either(HttpError, NetworkError) {}A Temporal-aware instant primitive. DateTime is a TypeDef you can extend;
parsing yields a DateTimeValue — an immutable instant stored as epoch
nanoseconds (bigint).
import { DateTime, DateTimeValue } from '@igorjs/pure-fx'
class CreatedAt extends DateTime {}
// Parse accepts an ISO string, epoch millis, a Date, a Temporal.Instant /
// ZonedDateTime, or an existing DateTimeValue:
const r = CreatedAt.parse('2026-05-22T10:00:00.000Z');
// Result<Type<'DateTime', DateTimeValue>, SchemaError>
if (r.isOk) {
r.value.epochNanos; // bigint (full nanosecond precision)
r.value.toDate(); // Date (millisecond precision)
r.value.toISO(); // '2026-05-22T10:00:00.000Z'
r.value.toEpochMillis(); // 1747908000000
r.value.toTemporal(); // Option<Temporal.Instant> (Some when available)
}
// Convenience constructors return branded values directly:
DateTime.now();
DateTime.fromEpochMillis(1_700_000_000_000);
DateTime.fromDate(new Date());DateTimeValue is comparable: equals(other), compare(other) (-1 | 0 | 1),
and the typeclass instances DateTimeValue.eq / DateTimeValue.ord (ordered by
instant).
Zero-dependency Temporal interop. pure-fx bundles no polyfill and declares no
dependency. globalThis.Temporal is feature-detected at runtime: when present,
toTemporal() returns Some(Temporal.Instant) with full nanosecond precision;
when absent (older runtimes), it returns None and everything else continues to
work via Date/bigint. Date-based conversions (toDate, toISO,
fromISO, fromDate, fromEpochMillis) are millisecond-precision; full
nanosecond fidelity is preserved in epochNanos and through Temporal values.
DateTimeValue implements the Immutable protocol
(Immutable.is(dt) === true). Modifiers are copy-on-write — they always return a
new value, never mutating in place:
const later = dt.plus(Duration.hours(1)); // new DateTimeValue
const reset = dt.withEpochMillis(0); // new DateTimeValue
dt.toMutable(); // a fresh Date (interop)Static constructors: now, fromEpochMillis, fromEpochNanos, fromDate,
fromISO, fromTemporal
Instance: epochNanos, toEpochMillis, toDate, toISO, toJSON,
toMutable, toTemporal, equals, compare
Copy-on-write modifiers: plus(Duration), minus(Duration),
withEpochMillis, withEpochNanos
Typeclass instances: eq, ord
Typed time values in milliseconds with conversions.
import { Duration } from '@igorjs/pure-fx'
const d = Duration.seconds(90); // 90000 (milliseconds)
Duration.toSeconds(d); // 90
Duration.toMinutes(d); // 1.5
Duration.minutes(5); // 300000
Duration.hours(1); // 3600000
Duration.days(7); // 604800000
Duration.toHours(Duration.minutes(90)); // 1.5
// Arithmetic
const total = Duration.add(Duration.minutes(5), Duration.seconds(30));
Duration.toSeconds(total); // 330
Duration.subtract(Duration.hours(1), Duration.minutes(15));
Duration.multiply(Duration.seconds(10), 3);
// Predicates and formatting
Duration.isZero(Duration.zero); // true
Duration.isPositive(Duration.seconds(1)); // true
Duration.format(Duration.add(Duration.hours(2), Duration.minutes(30)));
// "2h 30m"
// Typeclass instances
Duration.eq.equals(Duration.seconds(1), Duration.milliseconds(1000)); // true
Duration.ord.compare(Duration.seconds(1), Duration.seconds(2)); // -1
// Used in APIs that accept Duration:
Stream.interval(Duration.seconds(1));
Retry.exponential({ base: Duration.milliseconds(100) });Factories: milliseconds, seconds, minutes, hours, days
Conversions: toMilliseconds, toSeconds, toMinutes, toHours
Arithmetic: add, subtract, multiply
Predicates: isZero, isPositive
Other: format, zero, eq, ord
Cron expression parser with field validation.
import { Cron } from '@igorjs/pure-fx'
const expr = Cron.parse('*/5 * * * *');
// Result<CronExpression, SchemaError>
// Next occurrence after a given date
if (expr.isOk) {
const next = Cron.next(expr.value); // Option<Date>
const nextAfter = Cron.next(expr.value, new Date('2025-01-01'));
// Check if a date matches the schedule
Cron.matches(expr.value, new Date()); // boolean
}Static: parse, next, matches