true-myth

What is true-myth?

The true-myth npm package provides a set of utilities for working with types that represent the presence or absence of a value (Option) and the success or failure of an operation (Result). It is inspired by functional programming concepts and aims to make error handling and value management more robust and expressive.

What are true-myth's main functionalities?

Option

The Option type represents a value that may or may not be present. It can be either Some (containing a value) or None (containing no value). The match method allows for pattern matching on the Option type.

const { Option } = require('true-myth');

const someValue = Option.of(42);
const noneValue = Option.none();

someValue.match({
  Some: (value) => console.log(`Got a value: ${value}`),
  None: () => console.log('Got nothing')
});

noneValue.match({
  Some: (value) => console.log(`Got a value: ${value}`),
  None: () => console.log('Got nothing')
});

Result

The Result type represents the outcome of an operation that can either succeed (Ok) or fail (Err). The match method allows for pattern matching on the Result type.

const { Result } = require('true-myth');

const successResult = Result.ok('Success!');
const failureResult = Result.err('Failure!');

successResult.match({
  Ok: (value) => console.log(`Operation succeeded with value: ${value}`),
  Err: (error) => console.log(`Operation failed with error: ${error}`)
});

failureResult.match({
  Ok: (value) => console.log(`Operation succeeded with value: ${value}`),
  Err: (error) => console.log(`Operation failed with error: ${error}`)
});

Chaining and Transformations

Both Option and Result types support chaining and transformations using methods like map. This allows for functional-style transformations of the contained values.

const { Option, Result } = require('true-myth');

const someValue = Option.of(42);
const transformedValue = someValue.map(value => value * 2);

transformedValue.match({
  Some: (value) => console.log(`Transformed value: ${value}`),
  None: () => console.log('Got nothing')
});

const successResult = Result.ok(42);
const transformedResult = successResult.map(value => value * 2);

transformedResult.match({
  Ok: (value) => console.log(`Transformed result: ${value}`),
  Err: (error) => console.log(`Operation failed with error: ${error}`)
});

Other packages similar to true-myth

folktale

Folktale is a suite of libraries for generic functional programming in JavaScript. It provides similar types like Maybe (equivalent to Option) and Result, along with a broader set of functional programming utilities. Folktale is more comprehensive and includes additional features like data validation and asynchronous control flow.

monet

Monet is a library that brings functional programming concepts to JavaScript. It includes types like Maybe and Either, which are similar to Option and Result in true-myth. Monet also provides a rich set of combinators and utilities for functional programming, making it a more feature-rich alternative.

fp-ts

fp-ts is a library for typed functional programming in TypeScript. It provides a wide range of functional programming utilities, including Option and Either types. fp-ts is highly type-safe and integrates well with TypeScript's type system, making it a strong choice for TypeScript projects.

README

True Myth

True Myth provides safe, idiomatic null, error, and async code handling in TypeScript, with Maybe, Result, and Task types that are really nice.

README • API docs • Source • Intro blog post

Overview

True Myth provides standard, type-safe wrappers and helper functions to help you with three extremely common cases in programming:

• not having a value
• having a result where you need to deal with either success or failure
• having an asynchronous operation which may fail

You could implement all of these yourself – it's not hard! – but it's much easier to just have one extremely well-tested library you can use everywhere to solve this problem once and for all.

See the docs for setup, guides, and API docs!

Contents

• Requirements
• Compatibility
• Basic bundle size info

Requirements

• Node 20+
• TS 5.3+
• tsconfig.json:
  • moduleResolution: use "Node16" or later
  • strict: true
• package.json
  • type: "module" (or else use import() to import True Myth into a commonJS build)

For details on using a pure ES modules package in TypeScript, see the TypeScript handbook's guide.

Compatibility

This project follows the current draft of the Semantic Versioning for TypeScript Types specification.

• Currently supported TypeScript versions: 5.3, 5.4, 5.5, 5.6, 5.7, and 5.8
• Compiler support policy: simple majors
• Public API: all published, documented types not in a -private module and not marked as @internal or @private are public

Basic bundle size info

Size of the ESM build without tree-shaking (yes, these are in bytes: this is a pretty small library!):

file	size (B)	terser1 (B)	terser and brotli2 (B)
-private/utils.js	888	321	166
index.js	646	273	108
maybe.js	18683	3553	889
result.js	14111	3258	812
task/delay.js	3901	649	259
task.js	51219	7254	1997
test-support.js	473	142	89
toolbelt.js	3739	890	277
unit.js	656	58	57
total3	94316	16398	4654

Notes:

• The unmodified size includes comments.
• Thus, running through Terser gets us a much more realistic size: about 16.4KB to parse.
• The total size across the wire of the whole library will be ~4.7KB.
• This is all tree-shakeable to a significant degree. If your production bundle does not import or use anything from true-myth/test-support, you will not pay for it. However, some parts of the library do depend directly on other parts: for example, toolbelt uses exports from result and maybe, and Task makes extensive use of Result under the hood.

Inspiration

The design of True Myth draws heavily on prior art; essentially nothing of this is original – perhaps excepting the choice to make Maybe.of handle null and undefined in constructing the types. In particular, however, True Myth draws particular inspiration from:

• Rust's Option and Result types and their associated methods
• Folktale's Maybe and Result implementations
• Elm's Maybe and Result types and their associated functions

Footnotes

• Using terser 5.37.0 with --compress --mangle --mangle-props. ↩

• Generated by running gzip -kq11 on the result of the terser invocation. ↩

• This is just the sum of the previous lines. Real-world bundle size is a function of what you actually use, how your bundler handles tree-shaking, and how the results of bundling compresses. Notice that sufficiently small files can end up larger after compression; this stops being an issue once part of a bundle. ↩

Changelog

9.0.1 (2025-05-21)

Fixes an assignability bug with the PromiseLike interface and continues cleaning up some docs. This one comes entirely from external contributors—thanks, folks!

:bug: Bug Fix

• #1051 Task: align with PromiseLike interface (@auvred)

:memo: Documentation

• #1052 Remove "Why do I need this?" reference (@viniciuskneves)
• #1029 docs/build: add TS 5.8 to matrix (@chriskrycho)
• #1028 docs: clarify public API (@chriskrycho)

:house: Internal

• #1030 build: check build script in CI (@chriskrycho)

Committers: 3

• Chris Krycho (@chriskrycho)
• Vinicius Kiatkoski Neves (@viniciuskneves)
• @auvred