@deessejs/fp

Lightweight, type-safe functional programming utilities for TypeScript. Result, Maybe, Try, Unit, and friends — ESM-only, no runtime dependencies, designed for first-class interoperability with @deessejs/errors.

Sibling projects: @deessejs/errors provides error types that integrate natively with @deessejs/fp's Result and Try. Install them together to get a complete error-handling story without glue code. Used internally at deessejs.com.

What's included

Why this stack

• Simple by default. No over-engineering, no fancy type gymnastics. Just the primitives you need to write cleaner code.
• ESM-only. Modern packaging, no CJS shim, no module/main duplication.
• Zero runtime dependencies. The only peer dep is @deessejs/errors, which is opt-in. The library itself is dependency-free.
• TypeScript 6 first-class. Strict types, no any leakages, full inference. JSDoc where types alone are not enough.
• Lockfile-clean pnpm workspaces. A single pnpm install rebuilds, lints, types, and tests the whole monorepo.
• Real testing. Vitest, with coverage and integration tests against @deessejs/errors.

Quick start

Prerequisites

• Node.js 22.14.0+ (engines.node enforced)
• pnpm 10+ for development (corepack enable if not installed)
• TypeScript 6+ for consumers (the package emits dist/*.d.ts)

Install

# Install @deessejs/fp with its optional sibling, @deessejs/errors.
# See https://github.com/deessejs/errors
npm install @deessejs/fp @deessejs/errors

@deessejs/errors is optional — install it if you want Result<T, E> to carry typed errors instead of strings.

Usage

import { ok, err, some, none, maybe, pipe } from '@deessejs/fp';

// Result: represent values that may have failed
const divide = (a: number, b: number) => (b === 0 ? err('Division by zero') : ok(a / b));

const result = divide(10, 2);
result.match({
  ok: (value) => console.log(`Result: ${value}`),
  err: (error) => console.error(`Error: ${error}`),
});

// Maybe: represent optional values
const user = { name: 'Alice', address: { city: 'Paris' } };
const city = maybe(user.address?.city)
  .map((c) => c.toUpperCase())
  .getOrElse('Unknown');

// pipe: compose functions without glue
const trim = (s: string) => s.trim();
const uppercase = (s: string) => s.toUpperCase();
const processed = pipe('  hello  ', trim, uppercase);

Engine compatibility

ESM-only. Consumers using a CJS resolver need to use dynamic import() or migrate to ESM.

Available commands

Workspace (root)

Package: @deessejs/fp

App: web

Compatibility

Peer dependencies

Engines

Project structure

.
├── packages/
│   └── fp/                # The library — @deessejs/fp on npm
│       ├── src/           # Source code (ESM)
│       ├── dist/          # Build output (gitignored)
│       ├── vitest.config.ts
│       └── tsconfig.build.json
├── apps/
│   └── web/               # Documentation site (Next.js + Fumadocs)
├── docs/
│   ├── internal/          # Engineering plans, runbooks
│   │   ├── product/
│   │   └── versions/
│   └── AGENTS.md          # Agent guidance (CLAUDE.md redirects here)
├── pnpm-workspace.yaml
├── turbo.json             # Turborepo pipelines
├── .changeset/            # Changesets for versioning
└── README.md

Publishing

Releases are fully automated via Changesets + npm Trusted Publishing (OIDC). No long-lived NPM_TOKEN is required.

For the full pipeline design, see docs/engineering/plans/release-pipeline.md.

Architecture notes

• ESM-only. The package exports ES modules. Consumers using legacy CJS resolvers must use dynamic import().
• Strict types. Result.match requires both branches; Maybe.getOrElse requires a fallback. No partial type escapes.
• Composition over inheritance. All primitives compose via pipe and flow. No class hierarchy, no extends.
• Zero-runtime abstractions. No decorators, no reflection, no proxy traps. The library is straightforward to read in DevTools and node --prof.
• Smoke-tested before publish. The release workflow runs a dynamic ESM import of the built artifact and verifies that key exports are present. A broken build fails the publish step before reaching npm.
• @deessejs/errors is opt-in. The peer dep stays optional so consumers can adopt @deessejs/fp in isolation. Once @deessejs/errors is added, every err(error) call accepts a typed error.
• One source of truth for auth-style errors. The apps/app/proxy.ts (in the broader deessejs monorepo, not in this repo) enforces email verification at the proxy level. @deessejs/errors errors are caught and translated to HTTP responses centrally.

Contributing

Open an issue to discuss larger changes. For typos, broken links, and small fixes, PRs are welcome.

Before submitting a PR:

1. Run pnpm --filter @deessejs/fp test:run and pnpm --filter @deessejs/fp lint.
2. Add a .changeset/<topic>.md if the change is user-facing (patch / minor / major).
3. Update docs/internal/product/README.md if the API surface changes.

License

MIT. See the LICENSE file for details.

Support

• Issues: github.com/deessejs/fp/issues
• Discussions: github.com/deessejs/fp/discussions
• Email: [email protected]
• Documentation: fp.deessejs.com