Version: 🚧 Canary

🔧 Composition Utilities

The Nodeblocks SDK provides essential utilities for composing handlers, handling asynchronous operations, and building complex business logic pipelines. These utilities enable you to build complex, error-safe pipelines by combining simple functions in predictable ways.

🎯 Overview

Composition utilities provide the building blocks for robust and maintainable business logic. They handle function composition and error propagation, allowing you to chain operations safely and efficiently.

Key Features

Function Composition: Combine multiple functions into single pipelines
Error-Safe Operations: Automatic error propagation and handling
Async Support: Seamless handling of asynchronous operations
Type Safety: Full TypeScript support with proper typing

🔗 Basic Composition

For conceptual background on composition, currying, and Result types, see Functional Programming ».

`compose`

Combines multiple functions into a single pipeline. In the SDK, compose is an alias for Ramda's pipe — functions run left to right (not standard Ramda compose, which runs right to left):

import { primitives } from '@nodeblocks/backend-sdk';

const { compose } = primitives;

const processUser = compose(
  validateUser,   // 1. runs first
  saveUser,       // 2. runs second
  formatResponse  // 3. runs last
);

// Equivalent to: formatResponse(saveUser(validateUser(input)))

`lift`

In route handler chains, lift adapts the terminator step. It awaits the Promise from the previous composed step, then passes the unwrapped value to its function — typically orThrow, which maps block errors to HTTP status codes and formats the response:

import { primitives, blocks } from '@nodeblocks/backend-sdk';

const { compose, flatMapAsync, lift, applyPayloadArgs, orThrow } = primitives;
const { getProductById, normalizeProduct, ProductNotFoundBlockError } = blocks;

// lift wraps orThrow — the standard terminator pattern
const handler = compose(
  applyPayloadArgs(getProductById, [
    ['context', 'db', 'products'],
    ['params', 'requestParams', 'productId'],
  ], 'product'),
  flatMapAsync(
    applyPayloadArgs(normalizeProduct, [['context', 'data', 'product']], 'normalizedProduct')
  ),
  lift(
    orThrow(
      [[ProductNotFoundBlockError, 404]],
      [['context', 'data', 'normalizedProduct']]
    )
  )
);

lift does not lift plain functions into the Result functor. It bridges the async Promise between composed handler steps and the synchronous terminator.

`mergeData`

Merges data into the payload context for use by subsequent handlers in a composition pipeline.

import { ok } from 'neverthrow';
import { handlers, primitives } from '@nodeblocks/backend-sdk';

const { mergeData } = handlers;
const { compose, flatMapAsync, lift, orThrow } = primitives;

const enrichUserData = async (payload: RouteHandlerPayload) => {
  const profile = await profileService.getProfile(payload.context.data.userId);
  return ok(mergeData(payload, { profile }));
};

const getUserHandler = compose(
  fetchUserFromDb,
  flatMapAsync(enrichUserData), // profile is now available in payload.context.data
  lift(orThrow([[UserNotFoundError, 404]], [['context', 'data', 'profile']]))
);

Parameters:

payload: The current payload object
data: Object containing data to merge into payload.context.data

Returns: Updated payload object with merged data

Note: mergeData returns a payload, not a Result. Handlers used with flatMapAsync must wrap the return in ok() (or err() on failure).

Usage Examples:

import { ok } from 'neverthrow';

// Merge single value (inside a flatMapAsync handler)
return ok(mergeData(payload, { userId: '123' }));

// Merge multiple values
return ok(mergeData(payload, {
  user: userData,
  profile: profileData,
  settings: settingsData,
}));

// Merge in async handlers
const createUser = async (payload: RouteHandlerPayload) => {
  const user = await db.users.create(payload.params.requestBody);
  return ok(mergeData(payload, { user }));
};

`applyPayloadArgs`

Extracts arguments from payload and applies them to a pure function, enabling seamless integration of pure business logic into route handlers.

Purpose: Bridges pure functions with route payload context by extracting specific paths and applying them as function arguments

Handler Process:

Input: RouteHandlerPayload with context, params, and body data
Process: Extracts specified paths from payload and applies them to pure function (async or sync)
Output: Result<RouteHandlerPayload, Error> with function result merged into payload
Errors: Propagates errors when function returns Result.err

Parameters:

func: Pure function to execute with extracted arguments (supports both async and sync). Can use Result types.
funcArgs: Array of paths to extract from payload (direct keys or nested paths)
key: Optional property name to store the function result in payload.context.data[key] (via mergeData)

Returns: AsyncRouteHandler that applies pure function with payload-extracted arguments

Usage Examples:

import { primitives } from '@nodeblocks/backend-sdk';

const { applyPayloadArgs } = primitives;

// Used in route composition with async function:
const updateRoute = withRoute({
  handler: compose(
    applyPayloadArgs(updateIdentityPure, [
      ['params', 'requestParams', 'identityId'],
      ['params', 'requestBody'],
      ['context', 'db', 'identities']
    ], 'identityId')
  )
});

// Use flatMapAsync when combining:
const updateRoute = withRoute({
  handler: compose(
    applyPayloadArgs(updateItem, [
      ['params', 'requestParams', 'itemId'],
      ['params', 'requestBody'],
      ['context', 'db', 'items']
    ], 'itemId'),
    flatMapAsync(
      applyPayloadArgs(
        getItemById,
        [
          ['context', 'data', 'itemId'],
          ['context', 'db', 'items'],
        ],
        'item'
      )
    ),
    flatMapAsync(
      applyPayloadArgs(
        getOtherItemById,
        [
          ['context', 'data', 'itemId'],
          ['context', 'db', 'otherItems'],
        ],
        'item'
      )
    ),
    lift(
      orThrow([[ItemNotFoundError, 404]], [['context', 'data', 'item']])
    )
  )
});

// Works with sync functions too:
applyPayloadArgs(someSyncFunction, [
  ['params', 'requestParams', 'id'],
  ['body']
], 'result')

// Handles Result types automatically:
applyPayloadArgs((x: number, y: number) => ok(x + y), [
  ['params', 'requestParams', 'x'],
  ['context', 'data', 'y']
], 'result')

`orThrow`

Terminator function that handles Result success/error cases with custom error mapping and optional success data extraction.

Purpose: Provides controlled error handling and response formatting for composition pipelines

Response Formatting:

Input: Result containing RouteHandlerPayload or Error
Process: Maps specific error types to HTTP status codes or custom errors, optionally extracts data from success payload
Output: With successMap, returns the extracted success value and optional status code; without it, returns the original RouteHandlerPayload. Throws mapped errors with appropriate status codes on failure.
Errors: Throws NodeblocksError with status code or custom error instances

Parameters:

errorMap: Array of [CustomError, HttpStatusCode | Error] tuples for error mapping
successMap: Optional [ObjectPath, HttpStatusCode] tuple for success data extraction

Returns: Function that processes Result, extracts success data when configured, or throws a mapped error

Usage Examples:

import { primitives } from '@nodeblocks/backend-sdk';

const { compose, lift, orThrow } = primitives;

// Used in route composition with error mapping:
const createUserRoute = withRoute({
  handler: compose(
    createUserHandler,
    lift(orThrow([
      [ValidationError, 400],
      [DuplicateError, 409],
      [DatabaseError, 500]
    ]))
  )
});

// With success data extraction:
const getUserRoute = withRoute({
  handler: compose(
    getUserHandler,
    lift(orThrow(
      [[UserNotFoundError, 404]],
      [['context', 'data', 'user'], 200]
    ))
  )
});

🔎 Helpers

`match`

Predicate utility that checks a nested path via Ramda's pathSatisfies.

import { primitives } from '@nodeblocks/backend-sdk';

const { match } = primitives;

// Curried usage (2 args): returns a predicate that expects the object later
const isPositiveLimit = match(
  (x: unknown) => Number(x) > 0,
  ['params', 'requestQuery', 'limit']
);
// later, supply the object
const ok = isPositiveLimit(payload); // boolean

// Direct usage (3 args): pass the object immediately
const okImmediate = match(
  (x: unknown) => Number(x) > 0,
  ['params', 'requestQuery', 'limit'],
  payload
); // boolean

`ifElse`

Functional conditional that selects one of two functions based on a predicate.

import { primitives } from '@nodeblocks/backend-sdk';

const { ifElse } = primitives;

const normalizeName = ifElse(
  (x: any) => !!x.nickname,
  (x: any) => x.nickname,
  (x: any) => `${x.firstName} ${x.lastName}`
);

`hasValue`

Composite predicate returning true when a value is non-null and non-empty.

import { primitives } from '@nodeblocks/backend-sdk';

const { hasValue } = primitives;

hasValue('hello'); // true
hasValue('');      // false
hasValue(null);    // false
hasValue(undefined); // false
hasValue([]);      // false
hasValue({});      // false
hasValue({ a: 1 }); // true
hasValue([1, 2, 3]); // true

`either`

Ramda either re-export — logical OR for predicates. Returns a predicate that is true when either argument predicate is true.

import { utils, primitives } from '@nodeblocks/backend-sdk';

const { isCookieMode } = utils;
const { either, match } = primitives;

const isCookieAuth = either(
  match(isCookieMode, ['context', 'authMode']),
  match(isCookieMode, ['context', 'configuration', 'authMode'])
);

Used internally by whenCookieAuth to detect cookie mode from context or configuration.

`mapMatchingErrorToFalse`

Wraps a function that returns Promise<Result<T, Error>> and converts matching block errors to ok(false). Other errors propagate unchanged.

import { ok } from 'neverthrow';
import { primitives, blocks } from '@nodeblocks/backend-sdk';

const { mapMatchingErrorToFalse } = primitives;
const { checkEmailIsUniqueInIdentities, AuthenticationConflictError } = blocks;

const checkUnique = mapMatchingErrorToFalse(checkEmailIsUniqueInIdentities, [
  AuthenticationConflictError,
]);

const result = await checkUnique(identities, 'taken@example.com');
// Matching conflict: result.isOk() === true, result.value === false
// Other error: result.isErr() === true
// Success: result.isOk() === true, result.value unchanged

Parameters:

fn: Function returning Promise<Result<T, Error>>
errorTypes: Block error constructors to convert to false (via instanceof)

Returns: Wrapped function returning Promise<Result<T | boolean, Error>>

RxJS emitter helpers

These helpers are exported from primitives and are intended for filtering and tagging messages in RxJS or WebSocket pipelines.

`notFromEmitter`

Curried predicate factory. notFromEmitter(emitterId) returns a predicate that accepts object data and returns true when its emitterId is absent or differs from the supplied ID. Non-object values return false.

import { primitives } from '@nodeblocks/backend-sdk';
import { filter } from 'rxjs';

const { notFromEmitter } = primitives;

observable.pipe(filter(notFromEmitter('socket-123')));

`markAsFromEmitter`

Curried helper that returns a shallow copy of an object with the supplied emitterId field.

import { primitives } from '@nodeblocks/backend-sdk';

const { markAsFromEmitter } = primitives;
const tagged = markAsFromEmitter('socket-123')({ event: 'updated' });
// { event: 'updated', emitterId: 'socket-123' }

🔄 Error-Safe Composition

`flatMap`

Chains synchronous operations that return a Result type, enabling error-safe composition.

import { primitives } from '@nodeblocks/backend-sdk';

const { flatMap } = primitives;

const processUserData = compose(
  validateUserInput,
  flatMap(enrichUserData), // Only runs if validation succeeds
  flatMap(formatUserData)
);

`flatMapAsync`

Chains asynchronous operations that return a Result type, enabling error-safe composition.

import { primitives } from '@nodeblocks/backend-sdk';

const { flatMapAsync } = primitives;

const createAndFetchUser = compose(
  createUserInDb,
  flatMapAsync(fetchUserById), // Only runs if createUserInDb succeeds
  lift(orThrow([[UserNotFoundError, 404]], [['context', 'data', 'user']]))
);

`withSoftDelete`

Converts hard deletes into soft deletes by automatically managing a deletedAt timestamp, providing data safety and audit capabilities.

Purpose: Enables safe data deletion by marking records as deleted rather than removing them, while automatically filtering out soft-deleted records from queries

Database Operations:

Reads: find, findOne, countDocuments automatically exclude soft-deleted records (where deletedAt exists)
Deletes: deleteOne, deleteMany convert to updates setting deletedAt: new Date()
Updates: updateOne, updateMany, findOneAndUpdate respect soft delete filters (won't update already deleted records)
Inserts: Unaffected, work normally

Handler Process:

Input: Any AsyncRouteHandler that uses database collections
Process: Wraps database collections with soft delete proxy that intercepts operations
Output: Handler that behaves identically but with soft delete semantics
Data Safety: Deleted records remain in database with deletedAt timestamp for audit purposes

Parameters:

handler: The async route handler to wrap with soft delete functionality

Returns: AsyncRouteHandler with soft delete semantics applied to all database operations

Usage Examples:

import { primitives } from '@nodeblocks/backend-sdk';

const { withSoftDelete } = primitives;

// Basic usage - wrap any handler for soft delete functionality
const softDeleteHandler = withSoftDelete(originalHandler);

// In route composition
const deleteUserRoute = withRoute({
  method: 'DELETE',
  path: '/users/:userId',
  handler: withSoftDelete(deleteUserHandler)
});

// Works with all database operations automatically
const userOperations = compose(
  withSoftDelete(createUserHandler),    // Inserts work normally
  withSoftDelete(findUserHandler),      // Finds exclude soft-deleted users
  withSoftDelete(updateUserHandler),    // Updates respect soft delete filters
  withSoftDelete(deleteUserHandler)     // Deletes become soft deletes
);

// Example: Soft delete marks record instead of removing
// Before: db.users.deleteOne({ id: '123' }) — permanent removal
// After:  db.users.deleteOne({ id: '123' }) — becomes updateOne with { $set: { deletedAt: new Date() } }

// Example: Queries automatically exclude soft-deleted records
// Before: db.users.find({ active: true })
// After:  db.users.find({ active: true }) — merged filter adds deletedAt: { $exists: false }

Benefits:

Data Safety: Prevents accidental permanent data loss
Audit Trail: Maintains historical records for compliance
Recovery: Soft-deleted records can be restored if needed
API Compatibility: Existing handlers work without modification
Performance: Minimal overhead, only adds deletedAt filtering

Data Recovery Example:

// To restore a soft-deleted record (bypass soft delete wrapper)
const restoreUser = async (payload: RouteHandlerPayload) => {
  const { userId } = payload.params.requestParams;
  await payload.context.db.users.updateOne(
    { id: userId },
    { $unset: { deletedAt: 1 } } // Remove the deletedAt field
  );
  return payload;
};

📝 Practical Examples

Multi-Step Data Processing (block pattern)

import { primitives, blocks } from '@nodeblocks/backend-sdk';

const { compose, flatMapAsync, lift, applyPayloadArgs, orThrow } = primitives;
const { getProductById, normalizeProduct, ProductNotFoundBlockError } = blocks;

const getProductHandler = compose(
  applyPayloadArgs(
    getProductById,
    [
      ['context', 'db', 'products'],
      ['params', 'requestParams', 'productId'],
    ],
    'product'
  ),
  flatMapAsync(
    applyPayloadArgs(normalizeProduct, [['context', 'data', 'product']], 'normalizedProduct')
  ),
  lift(
    orThrow(
      [[ProductNotFoundBlockError, 404]],
      [['context', 'data', 'normalizedProduct']]
    )
  )
);

Data Transformation Pipeline

const { compose, flatMapAsync, lift, orThrow } = primitives;

const processOrder = compose(
  applyPayloadArgs(validateOrderData, [['params', 'requestBody']], 'order'),
  flatMapAsync(applyPayloadArgs(checkInventory, [['context', 'data', 'order']], 'inventory')),
  flatMapAsync(applyPayloadArgs(createOrder, [['context', 'data', 'order']], 'createdOrder')),
  lift(orThrow([[OrderError, 500]], [['context', 'data', 'createdOrder'], 201]))
);

const createOrderRoute = withRoute({
  method: 'POST',
  path: '/orders',
  handler: processOrder,
});

Error-Safe Validation Chain

import { Result, ok, err } from 'neverthrow';
import { primitives } from '@nodeblocks/backend-sdk';

const { flatMap, flatMapAsync, lift } = primitives;

// Step 1: Validate input
const validateUserInput = (data: any): Result<ValidatedUser, ValidationError> => {
  if (!data.email || !data.name) {
    return err(new ValidationError('Missing required fields'));
  }
  return ok(data);
};

// Step 2: Check if user exists
const checkUserExists = async (user: ValidatedUser): Promise<Result<User, DatabaseError>> => {
  const existing = await db.users.findOne({ email: user.email });
  if (existing) {
    return err(new DatabaseError('User already exists'));
  }
  return ok(user);
};

// Step 3: Save user
const saveUser = async (user: ValidatedUser): Promise<Result<User, DatabaseError>> => {
  try {
    const saved = await db.users.create(user);
    return ok(saved);
  } catch (error) {
    return err(new DatabaseError('Failed to save user'));
  }
};

// Compose the error-safe pipeline
const createUserHandler = compose(
  (payload) => validateUserInput(payload.params.requestBody),
  flatMapAsync(checkUserExists),
  flatMapAsync(saveUser),
  lift(orThrow([[DatabaseError, 500]], [['context', 'data', 'user'], 201]))
);

📐️️ Best Practices

1. Keep Functions Small and Focused

// ✅ Good: Small, focused functions
const validateEmail = (email: string) => /* validation logic */;
const hashPassword = (password: string) => /* hashing logic */;
const saveUser = (user: User) => /* database logic */;

// ❌ Avoid: Large, multi-purpose functions
const createUserMegaFunction = (data: any) => {
  // validation, hashing, saving, emailing all in one function
};

2. Handle Async Operations Properly

// ✅ Good: Use flatMapAsync for async operations
const enrichDataPipeline = compose(
  fetchUserData,
  flatMapAsync(fetchUserProfile),    // Async operation
  flatMapAsync(fetchUserSettings),   // Another async operation
  lift(orThrow([[UserError, 404]], [['context', 'data', 'settings']]))  // Terminator
);

// ❌ Avoid: Mixing async/sync without proper utilities
const badPipeline = compose(
  fetchUserData,
  fetchUserProfile,  // This won't work properly in composition
  formatResponse
);

3. Compose at the Right Level

// ✅ Good: Compose related operations
const userRegistrationFlow = compose(
  validateRegistration,
  createUser,
  sendWelcomeEmail
);

// ✅ Good: Keep unrelated operations separate
const userLoginFlow = compose(
  validateCredentials,
  authenticateUser,
  generateToken
);

4. Use Result Types for Error Handling

// ✅ Good: Explicit error handling with Result types
const safeOperation = compose(
  validateInput,
  flatMapAsync(databaseOperation), // Only runs if validation succeeds
  lift(orThrow([[DatabaseError, 500]], [['context', 'data', 'result']]))
);

// ❌ Avoid: Relying on thrown exceptions in composition
const unsafeOperation = compose(
  validateInput,
  databaseOperation, // Might throw, breaking composition
  formatResponse
);

🔗 See Also

Handler Wrappers - Cross-cutting concerns like logging and pagination
Handler Component - Basic handler concepts
Route Component - Route definitions
Error Handling - Result types and error patterns
Functional Programming - Core composition concepts

🎯 Overview​

Key Features​

🔗 Basic Composition​

compose​

lift​

mergeData​

applyPayloadArgs​

orThrow​

🔎 Helpers​

match​

ifElse​

hasValue​

either​

mapMatchingErrorToFalse​

RxJS emitter helpers​

notFromEmitter​

markAsFromEmitter​

🔄 Error-Safe Composition​

flatMap​

flatMapAsync​

withSoftDelete​

📝 Practical Examples​

Multi-Step Data Processing (block pattern)​

Data Transformation Pipeline​

Error-Safe Validation Chain​

📐️️ Best Practices​

1. Keep Functions Small and Focused​

2. Handle Async Operations Properly​

3. Compose at the Right Level​

4. Use Result Types for Error Handling​

🔗 See Also​

🎯 Overview

Key Features

🔗 Basic Composition

`compose`

`lift`

`mergeData`

`applyPayloadArgs`

`orThrow`

🔎 Helpers

`match`

`ifElse`

`hasValue`

`either`

`mapMatchingErrorToFalse`

RxJS emitter helpers

`notFromEmitter`

`markAsFromEmitter`

🔄 Error-Safe Composition

`flatMap`

`flatMapAsync`

`withSoftDelete`

📝 Practical Examples

Multi-Step Data Processing (block pattern)

Data Transformation Pipeline

Error-Safe Validation Chain

📐️️ Best Practices

1. Keep Functions Small and Focused

2. Handle Async Operations Properly

3. Compose at the Right Level

4. Use Result Types for Error Handling

🔗 See Also