Receta

Practical FP recipes built on Remeda — Higher-level patterns for real-world TypeScript applications

What is Receta?

Receta (Spanish for "recipe") is a functional utility library that builds on top of Remeda. While Remeda provides low-level FP primitives (map, filter, pipe, etc.), Receta provides composed patterns that solve common real-world problems.

┌─────────────────────────────────────┐
│           Your Application          │
├─────────────────────────────────────┤
│    Receta (Patterns & Recipes)      │  ← This library
├─────────────────────────────────────┤
│    Remeda (FP Primitives)           │
├─────────────────────────────────────┤
│         TypeScript / JS             │
└─────────────────────────────────────┘

Why Receta?

TypeScript gives you compile-time safety, but runtime is still the Wild West:

// ❌ THE VANILLA NIGHTMARE
async function getUserProfile(userId: string) {
  try {
    const response = await fetch(`/api/users/${userId}`)
    if (!response.ok) throw new Error(`HTTP ${response.status}`)
    const user = await response.json()
    if (!user) throw new Error('User not found')
    return user.profile?.email || null
  } catch (error) {
    console.error(error)
    return null // 🤮 What went wrong? Who knows!
  }
}

7+ runtime failure points. Zero compile-time help. Good luck debugging production.

Receta Solution: Errors as Values + Pipe Composition

// ✅ RECETA: Type-safe, composable, self-documenting
import * as R from 'remeda'
import { Result, tryCatchAsync } from 'receta/result'
import { Option, fromNullable } from 'receta/option'

async function getUserProfile(
  userId: string
): Promise<Result<string, FetchError>> {
  return R.pipe(
    await tryCatchAsync(
      () => fetch(`/api/users/${userId}`).then(r => r.json()),
      (e): FetchError => ({ type: 'network_error', cause: e })
    ),
    Result.flatMap(user =>
      Option.toResult(
        fromNullable(user?.profile?.email),
        { type: 'email_not_found', userId }
      )
    )
  )
}

// Caller knows EXACTLY what can fail
R.pipe(
  await getUserProfile('123'),
  Result.match({
    Ok: (email) => console.log('Email:', email),
    Err: (error) => {
      if (error.type === 'network_error') showNetworkError()
      if (error.type === 'email_not_found') showEmailMissing()
    }
  })
)

Benefits:

• ✅ Compile-time exhaustiveness — TypeScript forces you to handle all error cases
• ✅ No hidden exceptions — Errors are explicit in return types
• ✅ Composable with pipe — Chain operations without nested try/catch
• ✅ Self-documenting — Function signature tells you what can fail

Installation

npm install receta remeda
# or
bun add receta remeda
# or
yarn add receta remeda

Quick Start

Result: Type-Safe Error Handling

import { Result, ok, err, tryCatch } from 'receta/result'
import * as R from 'remeda'

// Parse JSON safely
const parseJSON = <T>(str: string): Result<T, SyntaxError> =>
  tryCatch(
    () => JSON.parse(str) as T,
    (e) => e as SyntaxError
  )

// Compose with pipe
const result = R.pipe(
  '{"name": "Alice"}',
  parseJSON,
  Result.map((user: any) => user.name),
  Result.unwrapOr('Unknown')
)

console.log(result) // "Alice"

Option: No More Null/Undefined Bugs

import { Option, fromNullable } from 'receta/option'
import * as R from 'remeda'

type User = { settings?: { theme?: string } }

const getUserTheme = (user: User): string =>
  R.pipe(
    user.settings?.theme,
    fromNullable,
    Option.unwrapOr('light')
  )

getUserTheme({}) // "light"
getUserTheme({ settings: { theme: 'dark' } }) // "dark"

Async: Concurrency Control + Retry

import { mapAsync, retry } from 'receta/async'

// Fetch URLs with concurrency limit
const results = await mapAsync(
  urls,
  async (url) => fetch(url).then(r => r.json()),
  { concurrency: 5 } // Max 5 concurrent requests
)

// Retry with exponential backoff
const response = await retry(
  () => fetch('https://api.example.com/data'),
  {
    maxAttempts: 3,
    delay: 1000,
    backoff: 'exponential' // 1s, 2s, 4s
  }
)

Predicate: Composable Filters

import { where, between, oneOf, gte } from 'receta/predicate'
import * as R from 'remeda'

const products = [
  { price: 50, inStock: true, category: 'electronics', rating: 4.5 },
  { price: 150, inStock: false, category: 'books', rating: 3.8 }
]

const filtered = R.filter(
  products,
  where({
    price: between(10, 100),
    inStock: true,
    category: oneOf(['electronics', 'books']),
    rating: gte(4.0)
  })
)
// [{ price: 50, ... }]

Validation: Form Validation with Error Accumulation

import { validate, combine, field } from 'receta/validation'
import { isEmail, minLength } from 'receta/string'

const validateRegistration = combine({
  email: field('email', [
    validate(isEmail, 'Must be a valid email')
  ]),
  password: field('password', [
    validate(minLength(8), 'Must be at least 8 characters')
  ])
})

const result = validateRegistration({
  email: 'invalid',
  password: '123'
})
// Invalid({ email: ['Must be a valid email'], password: ['Must be at least 8 characters'] })

Core Modules

| Module | Purpose | Key Functions | |--------|---------|---------------| | result | Type-safe error handling | ok, err, tryCatch, match, unwrapOr | | option | Nullable value handling | some, none, fromNullable, unwrapOr | | async | Async utilities | mapAsync, retry, timeout, debounce, throttle | | predicate | Composable predicates | where, gt, lt, between, oneOf, and, or | | validation | Form/data validation | validate, combine, field, error accumulation | | collection | Advanced collections | nest, diff, paginate, setOps | | object | Object manipulation | flatten, unflatten, getPath, mask, deepMerge | | string | String utilities | slugify, template, truncate, isEmail, sanitize | | number | Number formatting | toCurrency, toBytes, clamp, percentage | | memo | Memoization | memoize, memoizeAsync, TTL/LRU caches | | lens | Immutable updates | prop, path, over, set, view | | compare | Comparator builders | ascending, descending, natural, compose | | function | Function combinators | ifElse, when, cond, compose, partial |

Design Principles

1. Compositional Architecture

• Functions are built from other functions, never duplicated
• Higher-level functions compose lower-level ones
• Single source of truth for each behavior

2. Remeda as Infrastructure

• Receta depends on and uses Remeda internally
• Re-exports Remeda utilities only when extending them
• Follows Remeda's data-first/data-last pattern via purry

3. Result-First Error Handling

• Default: Functions return Result<T, E>, not throw exceptions
• Errors as values for explicit, composable error handling
• Throwing functions only when absolutely necessary

4. Type Safety First

• Leverage TypeScript's type system to the fullest
• All functions fully typed — no any
• Prefer narrowing over type assertions

5. Practical Over Academic

• Solve real problems, not theoretical exercises
• API reads like intent: Result.tryCatch(() => JSON.parse(str))
• Optimize for the 90% use case, escape hatch for the 10%

6. Tree-Shakeable

• Each module can be imported independently
• No barrel files forcing bundling everything
• Side-effect free for dead code elimination

Documentation

• Why Receta? — Real-world problems and solutions
• Module Development Guide — Contributing new modules
• Module Guides:
  • Result — Error handling patterns
  • Option — Nullable value handling
  • Async — Async utilities and patterns
  • Predicate — Composable predicates
  • Validation — Form and data validation
  • Collection — Advanced collection operations
  • Object — Safe object manipulation
  • String — String utilities
  • Number — Number formatting and math
  • Memo — Memoization strategies
  • Lens — Functional lenses
  • Compare — Comparator builders
  • Function — Function combinators

Examples

Check the examples/ directory for real-world usage patterns:

• Payment processing with error handling
• API request pipelines
• Form validation
• Data transformations
• Retry strategies
• And more!

When NOT to Use Receta

Receta is overkill for:

• Prototypes/scripts — try/catch is fine for throwaway code
• Simple CRUD — If your app is 90% database queries, simpler tools suffice
• Team unfamiliar with FP — Requires buy-in and learning curve

Use Receta when:

• Reliability matters — Payment processing, auth, data pipelines
• Error handling is complex — Multiple failure modes need distinct handling
• Type safety is critical — Financial apps, healthcare, aerospace
• Composability wins — Building reusable utilities and services

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development setup
• Testing guidelines
• Commit conventions
• Pull request process

License

MIT © 2026 Khaled Maher

Acknowledgments

• Built on Remeda — the best data-first/data-last FP library for TypeScript
• Inspired by Rust's Result<T, E> and Option<T> types
• Guided by practical FP principles from Scala, Haskell, and F#

Receta: Where TypeScript meets elegance. Stop fighting runtime errors. Start composing solutions.