purify

name

purify

description

Master the Purify library for practical functional programming in TypeScript with algebraic data types (Maybe, Either, EitherAsync, MaybeAsync), composable error handling, data transformations, Codec for runtime type safety, List operations, Tuple utilities, and functional patterns. Use when working with Purify's Maybe/Either types, async error handling with EitherAsync/MaybeAsync, runtime validation with Codecs, or building practical functional TypeScript applications with cleaner syntax than fp-ts.

Purify Mastery

Purify is a practical functional library for TypeScript focusing on ergonomics and real-world usability, offering algebraic data types and tools for composable error handling and data transformations.

Installation and Setup

npm install purify-ts

import { Maybe, Either, EitherAsync, MaybeAsync } from 'purify-ts';
import { Codec, string, number } from 'purify-ts/Codec';
import { List } from 'purify-ts/List';
import { Tuple } from 'purify-ts/Tuple';

Philosophy

Purify focuses on:

• Practicality: Easier learning curve than fp-ts
• Ergonomics: Cleaner syntax, method chaining
• Real-world use cases: Built for production TypeScript
• Type safety: Leverages TypeScript's type system
• Async-first: First-class async support with EitherAsync/MaybeAsync

Maybe Type

Represents optional values safely.

Construction

import { Maybe, Just, Nothing } from 'purify-ts';

// Create Maybe values
const just = Just(42);              // Just(42)
const nothing = Nothing;             // Nothing
const fromNullable = Maybe.fromNullable(maybeValue);
const fromPredicate = Maybe.fromPredicate(
  (n: number) => n > 0,
  5
); // Just(5)

// fromFalsy - treats falsy values as Nothing
Maybe.fromFalsy(0);        // Nothing
Maybe.fromFalsy('hello');  // Just('hello')
Maybe.fromFalsy('');       // Nothing

Core Operations

// map - transform the value
Just(5)
  .map(n => n * 2);  // Just(10)

Nothing
  .map(n => n * 2);  // Nothing

// chain (flatMap) - sequence operations
Just(5)
  .chain(n => n > 0 ? Just(n * 2) : Nothing);  // Just(10)

// Method chaining for readability
Just(5)
  .map(n => n * 2)
  .chain(n => Just(n + 1))
  .map(n => n.toString());  // Just("11")

// orDefault - extract with default
Just(5).orDefault(0);      // 5
Nothing.orDefault(0);       // 0

// caseOf - pattern matching
Just().({
  :  ,
  :  
}); 


()
  .( n > );  

()
  .( n > );  



  .(());  


( n * )
  .(());  

Utility Methods

// isJust and isNothing
const maybe = Just(5);
if (maybe.isJust()) {
  // TypeScript knows this is Just
  const value = maybe.extract();  // Safe to extract
}

// extract - unsafe! Throws if Nothing
Just(5).extract();  // 5
// Nothing.extract();  // Throws error!

// toEither - convert to Either
Just(5).toEither('error');  // Right(5)
Nothing.toEither('error');   // Left('error')

// ifJust and ifNothing - side effects
Just(5).ifJust(n => console.log(n));  // Logs 5
Nothing.ifNothing(() => console.log('Empty'));

// sequence - convert array of Maybe to Maybe of array
Maybe.sequence([Just(1), Just(2), Just(3)]);  
.([(), , ()]);  


.([(), , ()]);  


.(
   n >  ? (n * ) : ,
  [, -, , -, ]
);  


.( .(jsonString));

Practical Examples

// Safe array access
const head = <A>(arr: A[]): Maybe<A> =>
  Maybe.fromNullable(arr[0]);

// Safe property access
const getProp = <T, K extends keyof T>(obj: T, key: K): Maybe<T[K]> =>
  Maybe.fromNullable(obj[key]);

// Chaining optional operations
type User = { name: string; address?: { city?: string } };

const getCity = (user: User): Maybe<string> =>
  Maybe.fromNullable(user.address)
    .chain(addr => Maybe.fromNullable(addr.city));

// Safe parsing
const parseNumber = (s: string): Maybe<number> =>
  Maybe.encase(() => {
    const n = parseFloat(s);
    if (isNaN(n)) throw new ();
     n;
  });


 extractUserEmail = (: ): <> =>
  .(data)
    .(  d ===  ? (d  ) : )
    .( .(obj.))
    .( .(user.))
    .(  email ===  && email.());

Either Type

Represents computations that can fail.

Construction

import { Either, Left, Right } from 'purify-ts';

// Create Either values
const right = Right(42);              // Right(42)
const left = Left('error');           // Left('error')
const fromPredicate = Either.fromPredicate(
  (n: number) => n > 0,
  n => `${n} is not positive`,
  5
); // Right(5)

// encase - wrap throwing function
Either.encase(() => JSON.parse(jsonString));  // Either<Error, unknown>

Core Operations

// map - transform right value
Right(5)
  .map(n => n * 2);  // Right(10)

Left('error')
  .map(n => n * 2);  // Left('error')

// mapLeft - transform left value
Left('error')
  .mapLeft(e => e.toUpperCase());  // Left('ERROR')

// chain (flatMap) - sequence Either operations
Right(5)
  .chain(n => n > 0 ? Right(n * 2) : Left('negative'));  // Right(10)

// Method chaining
Right(5)
  .map(n => n * 2)
  .chain(n => Right(n + 1))
  .map(n => n.toString());  // Right("11")

// caseOf - pattern matching
Right().({
  :  ,
  :  
}); 


().();     
().(); 


().( ());


().();  
().();  


<, >().(
   e.(),
   n * 
);  


()
  .(());  

Error Handling Patterns

// try-catch wrapping
const safeParse = (json: string): Either<Error, unknown> =>
  Either.encase(() => JSON.parse(json));

// Validation
const validateEmail = (email: string): Either<string, string> =>
  email.includes('@')
    ? Right(email)
    : Left('Invalid email');

const validateAge = (age: number): Either<string, number> =>
  age >= 18
    ? Right(age)
    : Left('Must be 18 or older');

// Chain validations
const validateUser = (email: string, age: number): Either<string, User> =>
  validateEmail(email)
    .chain(validEmail =>
      validateAge(age).map(validAge => ({
        : validEmail,
        : validAge
      }))
    );


.([
  (),
  ().( )
]);  


 eithers = [(), (), ()];
.(eithers);   
.(eithers);  


 either = ();
 (either.()) {
   value = either.();  
}


().();  



().();  



().();  
().();  


().( .(n));
().( .(e));

Practical Examples

// API response handling
type ApiError = { message: string; code: number };

const parseApiResponse = <T>(
  response: Response
): Either<ApiError, T> =>
  response.ok
    ? Either.encase(() => response.json())
        .mapLeft(e => ({ 
          message: 'Parse error', 
          code: 500 
        }))
    : Left({ message: 'Request failed', code: response.status });

// Form validation with error accumulation
type ValidationError = { field: string; message: string };

const validateForm = (
  email: string,
  age: number,
  name: string
): Either<ValidationError[], User> => {
  const errors: ValidationError[] = [];
  
  if (!email.includes()) {
    errors.({ : , :  });
  }
   (age < ) {
    errors.({ : , :  });
  }
   (name. === ) {
    errors.({ : , :  });
  }
  
   errors. > 
    ? (errors)
    : ({ email, age, name });
};


 processUser = (: ): <, > =>
  (data)
    .(validateUser)
    .(normalizeUser)
    .(saveUser)
    .(formatResponse);

EitherAsync Type

Async operations with error handling.

Construction

import { EitherAsync } from 'purify-ts';

// Create EitherAsync
const fetchUser = (id: number): EitherAsync<Error, User> =>
  EitherAsync(async ({ liftEither, throwE }) => {
    try {
      const response = await fetch(`/api/users/${id}`);
      if (!response.ok) {
        return throwE(new Error('Not found'));
      }
      return response.json();
    } catch (error) {
      return throwE(error as Error);
    }
  });

// From Promise
const fromPromise = EitherAsync.fromPromise(
  async () => fetch('/api/data').then(r => r.json())
);

// liftEither - convert Either to EitherAsync
const eitherAsync = EitherAsync.liftEither(
  validateData(data)
);

Core Operations

// map - transform success value
fetchUser(1)
  .map(user => user.name);  // EitherAsync<Error, string>

// mapLeft - transform error
fetchUser(1)
  .mapLeft(error => ({ 
    message: error.message, 
    code: 500 
  }));

// chain (flatMap) - sequence async operations
fetchUser(1)
  .chain(user => fetchPosts(user.id));  // EitherAsync<Error, Post[]>

// Method chaining
fetchUser(1)
  .map(user => user.id)
  .chain(fetchPosts)
  .map(posts => posts.length);  // EitherAsync<Error, number>

// run - execute and get Promise<Either>
await fetchUser(1).run();  // Promise<Either<Error, User>>

// caseOf - pattern matching (async)
await fetchUser(1)
  .()
  .( either.({
    :  .(error),
    :  .(user)
  }));


<, >( ({ liftEither, fromPromise, throwE }) => {
  
   validated =  ((data));
  
  
   result =  (());
  
  
   (condition) {
     ( ());
  }
  
   result;
});

Practical Examples

// Fetch with validation
const fetchValidatedUser = (id: number): EitherAsync<Error, User> =>
  EitherAsync(async ({ liftEither, throwE }) => {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) {
      return throwE(new Error(`HTTP ${response.status}`));
    }
    
    const data = await response.json();
    const validated = await liftEither(validateUser(data));
    return validated;
  });

// Parallel requests
const fetchUserData = (id: number): EitherAsync<Error, UserData> =>
  EitherAsync.liftEither(
    Either.sequence([
      Right(fetchUser(id)),
      Right(fetchPosts(id)),
      Right(fetchComments(id))
    ])
  ).chain(async ([userAsync, postsAsync, commentsAsync]) => {
     [user, posts, comments] =  .([
      userAsync.(),
      postsAsync.(),
      commentsAsync.()
    ]);
    
     .([user, posts, comments])
      .( ({ : u, : p, : c }));
  });


 fetchWithRetry = <T>(
  : <, T>,
  :  = 
): <, T> =>
  ( ({ throwE }) => {
     :  |  = ;
    
     ( i = ; i < retries; i++) {
       result =  fetch.();
       (result.()) {
         result.();
      }
      lastError = result.();
        ( (resolve,  * (i + )));
    }
    
     (lastError!);
  });


 createUserTransaction = (
  : 
): <, > =>
  ( ({ liftEither, throwE }) => {
    
     validated =  ((userData));
    
    
     user =  (
       (validated).()
    );
    
    
     emailResult =  (user.).();
     (emailResult.()) {
      
       (user.).();
       ( ());
    }
    
     user;
  });

MaybeAsync Type

Async operations that may not return a value.

Construction and Usage

import { MaybeAsync } from 'purify-ts';

// Create MaybeAsync
const findUser = (id: number): MaybeAsync<User> =>
  MaybeAsync(async ({ liftMaybe }) => {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) return liftMaybe(Nothing);
    
    const data = await response.json();
    return liftMaybe(Maybe.fromNullable(data));
  });

// map and chain
findUser(1)
  .map(user => user.name)
  .chain(name => findUserByName(name));

// run - execute and get Promise<Maybe>
await findUser(1).run();  // Promise<Maybe<User>>

// toEitherAsync - convert to EitherAsync
findUser(1)
  .toEitherAsync(new ());  


 getCachedValue = <T>(: ): <T> =>
  ( ({ liftMaybe }) => {
     value =  cache.(key);
     (.(value));
  });

 getOrFetch = <T>(
  : ,
  :  <T>
): <T> =>
  getCachedValue<T>(key)
    .(( () => {
       value =  ();
       cache.(key, value);
       value;
    }));

Codec - Runtime Type Validation

Type-safe encoding/decoding with runtime validation.

Basic Codecs

import { Codec, string, number, boolean, nullType } from 'purify-ts/Codec';
import { Left, Right } from 'purify-ts';

// Primitive codecs
string.decode('hello');     // Right('hello')
string.decode(123);         // Left('Expected a string')

number.decode(42);          // Right(42)
boolean.decode(true);       // Right(true)
nullType.decode(null);      // Right(null)

// Custom primitive codec
const positiveNumber = Codec.custom<number>({
  decode: (input) =>
    typeof input === 'number' && input > 0
      ? Right(input)
      : Left('Expected positive number'),
  encode: (input) => input
});

Object Codecs

import { GetType } from 'purify-ts/Codec';

// Define codec
const UserCodec = Codec.interface({
  id: number,
  name: string,
  email: string,
  age: number
});

// Infer TypeScript type from codec
type User = GetType<typeof UserCodec>;
// type User = { id: number; name: string; email: string; age: number }

// Decode
const result = UserCodec.decode({
  id: 1,
  name: 'John',
  email: '[e-mail]',
  age: 30
});  // Right({ id: 1, name: 'John', email: '[e-mail]', age: 30 })

const invalid = UserCodec.decode({
  id: 1,
  name: 'John'
  // Missing required fields
});  // Left('Problem at key "email": missing key')

// Encode (typically identity for simple codecs)
UserCodec.encode(user);  // user as-is

Advanced Codecs

import { array, optional, oneOf, exactly, lazy } from 'purify-ts/Codec';

// Array codec
const NumberArrayCodec = array(number);
NumberArrayCodec.decode([1, 2, 3]);  // Right([1, 2, 3])

// Optional fields
const UserWithOptionalEmailCodec = Codec.interface({
  id: number,
  name: string,
  email: optional(string)
});

// Union types with oneOf
const StatusCodec = oneOf([
  exactly('pending'),
  exactly('active'),
  exactly('completed')
]);

type Status = GetType<typeof StatusCodec>;
// type Status = 'pending' | 'active' | 'completed'

// Discriminated unions
const ShapeCodec = oneOf([
  Codec.interface({
    type: exactly(),
    : 
  }),
  .({
    : (),
    : ,
    : 
  })
]);


  {
  : ;
  : [];
}

 : <> = .({
  : ,
  : ( ())
});


 { record }  ;

  = ();
.({ : , :  });  


  = .({
  : ,
  : ,
  : 
});

  = .({
  : ,
  : ,
  : 
});

Custom Validation

// Add validation to existing codec
const emailCodec = string.compose(
  Codec.custom<string>({
    decode: (email) =>
      email.includes('@')
        ? Right(email)
        : Left('Invalid email format'),
    encode: (email) => email
  })
);

// Complex validation
const PasswordCodec = string.compose(
  Codec.custom<string>({
    decode: (password) => {
      if (password.length < 8) {
        return Left('Password must be at least 8 characters');
      }
      if (!/[A-Z]/.test(password)) {
        return Left('Password must contain uppercase letter');
      }
      if (!/[0-9]/.test(password)) {
        return Left('Password must contain number');
      }
      return Right(password);
    },
    encode:  password
  })
);


  = .(
  .<>({
    : 
      s. >  ? (s) : (),
    :  s
  })
);

Practical Codec Patterns

// API response validation
const ApiResponseCodec = Codec.interface({
  data: UserCodec,
  meta: Codec.interface({
    page: number,
    total: number
  })
});

const fetchUser = async (id: number): Promise<Either<string, User>> => {
  const response = await fetch(`/api/users/${id}`);
  const data = await response.json();
  
  return ApiResponseCodec.decode(data)
    .mapLeft(error => `Validation failed: ${error}`)
    .map(result => result.data);
};

// Form data validation
const SignupFormCodec = Codec.interface({
  email: emailCodec,
  password: PasswordCodec,
  age: positiveNumber,
  terms: ()
});

 validateSignupForm = (
  : 
): <, > =>
  .(data);


  = .({
  : ([
    (),
    (),
    ()
  ]),
  : ,
  : ,
  : 
});

 env = .(process.).();



  = .<>({
  :  {
     ( input !== ) {
       ();
    }
     date =  (input);
     (date.())
      ? ()
      : (date);
  },
  :  date.()
});

  = .({
  : ,
  : ,
  : ()
});

List Type

Functional list operations.

import { List } from 'purify-ts/List';

// Create lists
const list = List.of(1, 2, 3, 4, 5);
const fromArray = List([1, 2, 3]);

// head and tail
list.head();  // Just(1)
list.tail();  // Just(List(2, 3, 4, 5))

// map and filter
list
  .map(n => n * 2)
  .filter(n => n > 5);  // List(6, 8, 10)

// reduce
list.reduce((acc, n) => acc + n, 0);  // 15

// find
list.find(n => n > 3);  // Just(4)

// toArray
list.toArray();  // [1, 2, 3, 4, 5]

// cons (prepend)
list.cons(0);  // List(0, 1, 2, 3, 4, 5)

// at - safe index access
list.at();  
list.();  


list.();  
list.();  
list.();  
list.();  
list.();  
list.(.(, , ));  

Tuple Type

Fixed-size heterogeneous collections.

import { Tuple } from 'purify-ts/Tuple';

// Create tuples
const tuple = Tuple(1, 'hello', true);

// Access elements (type-safe!)
tuple.fst();  // 1
tuple.snd();  // 'hello'

// map (applies to last element)
Tuple(1, 'hello').map(s => s.toUpperCase());  // Tuple(1, 'HELLO')

// mapFirst
Tuple(1, 'hello').mapFirst(n => n * 2);  // Tuple(2, 'hello')

// bimap (map both elements)
Tuple(1, 'hello').bimap(
  n => n * 2,
  s => s.toUpperCase()
);  // Tuple(2, 'HELLO')

// swap
Tuple(1, 'hello').swap();  // Tuple('hello', 1)

// toArray
Tuple(, , ).();  


.(
   n * ,
   n + 
)();  

Function Utilities

import { identity, constant, compose } from 'purify-ts/Function';

// identity
identity(5);  // 5

// constant - always returns same value
const alwaysFive = constant(5);
alwaysFive();  // 5
alwaysFive(10);  // 5

// compose - right-to-left composition
const double = (n: number) => n * 2;
const increment = (n: number) => n + 1;
const toString = (n: number) => n.toString();

const process = compose(toString, increment, double);
process(5);  // "11"

Non-Empty Lists and Arrays

Type-safe non-empty collections.

import { NonEmptyList } from 'purify-ts/NonEmptyList';

// Must have at least one element
const nel = NonEmptyList.fromArray([1, 2, 3]);  // Just(NonEmptyList)
const empty = NonEmptyList.fromArray([]);  // Nothing

// Always safe operations (no Maybe needed)
nel.map(list => list.head());  // Just(1) - no Maybe!
nel.map(list => list.last());  // Just(3)

// Type guarantees non-emptiness
const getFirst = (nel: NonEmptyList<number>): number =>
  nel.head();  // Always safe!

Practical Patterns

API Client with Error Handling

type ApiError = 
  | { type: 'network'; message: string }
  | { type: 'validation'; errors: string[] }
  | { type: 'server'; status: number; message: string };

class ApiClient {
  constructor(private baseUrl: string) {}

  request<T>(
    path: string,
    options?: RequestInit
  ): EitherAsync<ApiError, T> {
    return EitherAsync(async ({ throwE }) => {
      try {
        const response = await fetch(`${this.baseUrl}${path}`, options);
        
        if (!response.ok) {
          return throwE({
            type: 'server',
            status: response.status,
            message: await response.text()
          });
        }
        
        return  response.();
      }  (error) {
         ({
          : ,
          : error   ? error. : 
        });
      }
    });
  }

  get<T>(: ): <, T> {
     .<T>(path);
  }

  post<T>(: , : ): <, T> {
     .<T>(path, {
      : ,
      : { :  },
      : .(body)
    });
  }
}


 api =  ();

 createUser = (: ): <, > =>
  api.<>(, userData)
    .(
      .(
        .(data).( ({
          : ,
          : [error]
        }))
      )
    );

Form Validation with Codecs

const LoginFormCodec = Codec.interface({
  email: string.compose(
    Codec.custom<string>({
      decode: (email) =>
        email.includes('@')
          ? Right(email)
          : Left('Invalid email'),
      encode: identity
    })
  ),
  password: string.compose(
    Codec.custom<string>({
      decode: (password) =>
        password.length >= 8
          ? Right(password)
          : Left('Password must be at least 8 characters'),
      encode: identity
    })
  )
});

type LoginForm = GetType<typeof LoginFormCodec>;

const validateLoginForm = (data: unknown): Either<string, LoginForm> =>
  LoginFormCodec.decode(data);

// In React component
const handleSubmit = () => {
  (data).({
    :  (error),
    :  (form)
  });
};

Async Pipeline with EitherAsync

const processUserSignup = (
  signupData: unknown
): EitherAsync<string, User> =>
  EitherAsync.liftEither(
    SignupFormCodec.decode(signupData)
      .mapLeft(error => `Validation error: ${error}`)
  )
    .chain(form =>
      EitherAsync(async ({ liftEither, throwE }) => {
        // Check if email exists
        const exists = await checkEmailExists(form.email).run();
        if (exists.extract()) {
          return throwE('Email already registered');
        }

        // Hash password
        const hashedPassword = await hashPassword(form.password);

        // Create user
        const user = await liftEither(
          await createUser({
            ...form,
            password: hashedPassword
          }).run()
        );

        // Send welcome email
        await sendWelcomeEmail(user.).();

         user;
      })
    );


 (formData)
  .()
  .( result.({
    :  .(error),
    :  .(, user)
  }));

Caching with MaybeAsync

class Cache<T> {
  private store = new Map<string, T>();

  get(key: string): MaybeAsync<T> {
    return MaybeAsync(async ({ liftMaybe }) => {
      const value = this.store.get(key);
      return liftMaybe(Maybe.fromNullable(value));
    });
  }

  set(key: string, value: T): Promise<void> {
    this.store.set(key, value);
    return Promise.resolve();
  }

  getOrFetch<E>(
    key: string,
    fetch: () => EitherAsync<E, T>
  ): EitherAsync<E, T> {
    return this.get(key)
      .toEitherAsync(null as any)
      .alt(
        fetch().chainFirst(value =>
          .( .(key, value))
        )
      );
  }
}


 cache =  <>();

 getUser = (: ): <, > =>
  cache.(
    ,
     (id)
  );

Best Practices

1. Use method chaining: Purify's API is designed for readability through chaining
2. Leverage Codecs: Use Codecs for all external data validation
3. Prefer EitherAsync over Promise: Explicit error handling prevents surprises
4. Use caseOf for exhaustive handling: Pattern matching ensures all cases covered
5. Type-safe with GetType: Derive TypeScript types from Codecs
6. Lazy defaults with orDefaultLazy: Avoid expensive computations in happy path
7. Chain with flatMap: Avoid nested Maybe/Either with chain
8. Use NonEmptyList: When guaranteed non-empty, use type system to enforce
9. Sequence for all-or-nothing: Use Maybe.sequence and Either.sequence
10. Test with property-based testing: Algebraic laws make great properties

Comparison with fp-ts

Purify advantages:

• Cleaner, more ergonomic API
• Method chaining feels more natural
• Built-in Codec system for validation
• Easier learning curve
• Better async support with EitherAsync/MaybeAsync

fp-ts advantages:

• More comprehensive type class system
• Better for advanced FP patterns
• Larger ecosystem
• Integration with Effect-TS
• More generic abstractions

Choose Purify when:

• Team new to functional programming
• Need practical, production-ready code quickly
• Want built-in validation with Codecs
• Prefer method chaining syntax

Choose fp-ts when:

• Need advanced FP abstractions
• Building on Effect-TS ecosystem
• Team comfortable with Haskell/Scala concepts
• Need maximum type safety

Migration Tips

From Promises to EitherAsync

// Before
async function fetchUser(id: number): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  if (!response.ok) throw new Error('Not found');
  return response.json();
}

// After
function fetchUser(id: number): EitherAsync<Error, User> {
  return EitherAsync(async ({ throwE }) => {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) return throwE(new Error('Not found'));
    return response.json();
  });
}

From null/undefined to Maybe

// Before
function getFirstName(user: User | null): string | null {
  return user?.name?.split(' ')[0] ?? null;
}

// After
function getFirstName(user: User | null): Maybe<string> {
  return Maybe.fromNullable(user)
    .chain(u => Maybe.fromNullable(u.name))
    .map(name => name.split(' ')[0]);
}

From try-catch to Either

// Before
function parseJSON<T>(json: string): T {
  try {
    return JSON.parse(json);
  } catch (error) {
    throw new Error(`Parse failed: ${error}`);
  }
}

// After
function parseJSON<T>(json: string): Either<Error, T> {
  return Either.encase(() => JSON.parse(json))
    .mapLeft(error => new Error(`Parse failed: ${error}`));
}