Functions

The Functions module provides a collection of utility functions for functional programming in TypeScript. It includes common functional programming primitives, function composition utilities, and helper functions for common operations.

Function Evaluation

invoke

This function is a syntax sugar for IIFEs.

Immediately invokes a function and returns its return value.

import { invoke } from 'funkcia/functions';

declare const shape: Shape;

const humanReadableShape = invoke(() => {
  switch (shape.kind) {
    case 'CIRCLE':
      return 'Circle';
    case 'SQUARE':
      return 'Square';
    default:
      const invalidKind: never = shape.kind;
      throw new Error(`Invalid shape: ${invalidKind}`);
  }
});

lazyCompute

Lazily computes a value by invoking a function. The value is computed only once when first accessed.

import { lazyCompute } from 'funkcia/functions';

declare function expensiveComputation(target: object[]): string;
declare const userLogs: object[];

const computation = lazyCompute(() => expensiveComputation(userLogs));

const output = computation.value; // computed only when accessed
const repeatedOutput = computation.value; // cached value returned

Functional Primitives

identity

Returns the provided value unchanged.

import { identity } from 'funkcia/functions';

const output = identity(10);
// Output: 10

noop

A function that does nothing and returns nothing.

import { noop } from 'funkcia/functions';

noop(); // do nothing

Constant Functions

always

Returns a function that will always return the provided value.

import { always } from 'funkcia/functions';

const alwaysTen = always(10);

const result = alwaysTen();
// Output: 10

alwaysNull

Returns null.

export const alwaysNull: () => null = always(null);

alwaysUndefined

Returns undefined.

export const alwaysUndefined: () => undefined = always(undefined);

alwaysVoid

Returns void.

export const alwaysVoid: () => void = alwaysUndefined;

ignore

Returns never.

export const ignore: () => never = always(undefined as never);

alwaysTrue

Returns true.

import { alwaysTrue, Option } from 'funkcia/functions';

declare function findUserById(id: string): Option<User>

const isRegularUser = findUserById('user_123')
  .map(user => user.kind !== 'ADMIN')
  .unwrapOr(alwaysTrue);

alwaysFalse

Returns false.

import { alwaysFalse, Option } from 'funkcia/functions';

declare function findUserById(id: string): Option<User>

const isAdmin = findUserById('user_123')
  .map(user => user.kind === 'ADMIN')
  .unwrapOr(alwaysFalse);

Type Utilities

coerce

This operation is unsafe and can be misleading if misused. Make sure you know what you're doing and use it wisely.

Ideally, you should only use this function when you have a better understanding of your code than TypeScript, which may be unable to narrow down the type of a value.

Returns the provided value coerced to the desired type.

import { coerce, Result } from 'funkcia/functions';

//       ┌─── Result<any, SyntaxError>
//       ▼
const result = Result.try(
  () => JSON.parse('{ "name": John }'),
  error => coerce<SyntaxError>(error) // JSON.parse throws a `SyntaxError`
);

compose

Composes two or more functions into a single function, from left to right.

import { compose } from 'funkcia/functions';

declare function increment(value: number): number;
declare function double(value: number): number;
declare function stringify(value: number): string;

const compute = compose(increment, double, stringify);

const output = compute(9);
// Output: "20"

pipe

Pipes a value through a series of functions, from left to right.

import { pipe } from 'funkcia/functions';

declare function increment(value: number): number;
declare function double(value: number): number;
declare function stringify(value: number): string;

const output = pipe(9, increment, double, stringify);
// Output: "20"