composable-functions

In composable-functions, context is a mechanism used to ensure the safety and propagation of constant values across a sequence of compositions. Instead of manually passing a shared dependency (like an authenticated user or a configuration object) through every single function in a chain, you use a Composable that accepts a context object as its second argument.

A Composable with context follows this type signature: Composable<(input: I, context: C) => O>

This is particularly useful for scenarios like authorization, where an identity or permission set must be available to every step of a process without being explicitly returned and re-passed by each intermediate function.

A Composable is a function that returns a Promise<Result<T>>. The Result<T> type represents either a success (containing the value of type T) or a failure (containing a list of Error objects).

You can create a Composable by wrapping a plain function with the composable method, or by using combinators like pipe which work with both plain functions and existing Composables.

import { composable, pipe } from 'composable-functions'

// Creating a primitive composable
const add = composable((a: number, b: number) => a + b)
// ^? Composable<(a: number, b: number) => number>

// Composing with a plain function
const toString = (a: unknown) => `${a}`
const addAndReturnString = pipe(add, toString)
// ^? Composable<(a: number, b: number) => string>

The Result type has been simplified. Instead of separate keys for different error types, all errors are represented as instances of Error within an array. This preserves stack traces and allows for standard exception handling.

To differentiate between error types, use instanceof with specific error classes like InputError or ContextError (formerly environment errors).

Old ErrorResult structure:

{
  "success": false,
  "errors": [{ "message": "Something went wrong" }],
  "inputErrors": [{ "message": "Required", "path": ["name"] }],
  "environemntErrors": [{ "message": "Unauthorized", "path": ["user"] }]
}

New Failure structure:

{
  "success": false,
  "errors": [
    new Error('Something went wrong'),
    new InputError('Required', ['name']),
    new ContextError('Unauthorized', ['user']),
  ],
}

In sequential compositions, the 'context' (the second argument) is not automatically passed to subsequent functions. To ensure the context is forwarded through the chain, use the combinators in the withContext namespace.

• withContext.pipe: Similar to pipe, but forwards the context to every function in the chain.
• withContext.sequence: Similar to sequence, but forwards the context to every function in the chain.
• withContext.branch: Similar to branch, but forwards the context to the next composable.

import { withContext } from 'composable-functions'

const a = (val: number, ctx: { user: User }) => val
const b = (val: number, ctx: { user: User }) => val && ctx.user.admin

// Context is passed to both a and b
const d = withContext.pipe(a, b)
const result = await d(1, { user: { admin: true } })

You can use pipe to compose functions into a single execution chain. When a function in the chain throws an error, the resulting Composable returns a Result object indicating failure instead of throwing an exception.

Results follow this shape:

• Success: { success: true, data: T, errors: [] }
• Failure: { success: false, errors: Error[] }

import { composable, pipe } from 'composable-functions'

const faultyAdd = (a: number, b: number) => {
  if (a === 1) throw new Error('a is 1')
  return a + b
}
const show = (a: number) => String(a)
const addAndShow = pipe(faultyAdd, show)

const result = await addAndShow(2, 2)
/*
result = {
  success: true,
  data: "4",
  errors: []
}
*/

const failedResult = await addAndShow(1, 2)
/*
failedResult = {
  success: false,
  errors: [<Error object>]
}
*/

The Result type returned by a composable only contains the data property if the operation was successful. To maintain type safety and avoid TypeScript errors, you must first check the success property before accessing data.

const result = await getUser('123')
if (!result.success) return notFound()

return result.data
// result.data is now typed as User

If you are migrating from domain-functions, note that DomainFunction<T> is now equivalent to Composable<(input?: unknown, context?: unknown) => T> (also known as ComposableWithSchema<T>).

Key Changes:

• Type Safety: Arguments are now part of the type signature to allow better type-checking during composition.
• Schemas: You no longer need to define schemas for every function, though you can still use applySchema for optional runtime validation.
• Context: The old environment is now called context.
• Result Type: The error structure has changed from a complex object with inputErrors and environmentErrors keys to a unified Failure type containing an array of Error instances.
• Incremental Migration: Both libraries can coexist, allowing you to migrate module by module.

In composable-functions, parallel combinators (like all and collect) automatically forward arguments to every function. However, for sequential compositions, you must use the combinators in the withContext namespace to ensure the context is preserved through the chain.

Warning: Using pipe, sequence, or branch outside of the withContext namespace will cause the context to be lost during composition.

import { withContext } from 'composable-functions'

// Correct way to preserve context in a sequence:
const result = withContext.pipe(fn1, fn2)(input, ctx)

// Also available:
// withContext.sequence
// withContext.branch

To use the library in your project, install it using npm:

npm i composable-functions

To use this library in a Deno environment, import the functions directly from deno.land/x. Replace standard Node.js imports with the following URL:

import { composable } from "https://deno.land/x/composable_functions/mod.ts";