A small, focused TypeScript library for safer code through functional patterns. Inspired by folktale,

folklore

Folklore provides two essential types for writing more reliable TypeScript: Maybe for handling optional values and Result for managing errors without exceptions.

Installation

JSR (recommended for Deno/modern setups):

# Deno
deno add jsr:@folklore/folklore

# npm (via JSR)
npx jsr add @folklore/folklore

npm:

npm install folklore

Quick Start

Maybe - Safe Optional Values

Handle nullable values without null checks:

import { Maybe } from 'folklore'

function findUser(id: string): Maybe<User> {
  const user = database.get(id)
  return Maybe.FromNullable(user)
}

const greeting = findUser('123')
  .map((user) => user.name)
  .map((name) => `Hello, ${name}!`)
  .getOrElse('Hello, stranger!')

Result - Error Handling Without Exceptions

Manage errors explicitly in your type system:

import { Result } from 'folklore'

function parseConfig(json: string): Result<Config> {
  return Result.Try(() => JSON.parse(json))
    .chain((data) => validateConfig(data))
}

const config = parseConfig(input)
  .matchWith({
    Ok: (cfg) => console.log('Loaded config:', cfg),
    Error: (err) => console.error('Failed to load config:', err),
  })

// Or with async operations
const response = await Result.FromPromise(fetch('/api/data'))
  .then((result) => result.map((res) => res.json()))

API

The library includes comprehensive JSDoc documentation - your editor’s IntelliSense will show you examples and usage guidance for every method. See #13: A Retelling, not a reimplementation for more details on API decisions.

Status & Contributing

Folklore is used in production on several large/critical TypeScript projects and is well-tested.

If you’re interested in contributing, please open an issue to discuss your idea first. I am very open to anything docs/stability/project related.

License

folklore is provided under the Mozilla Public License 2.0.

A copy of the MPLv2 is included license.md file for convenience.