shelving/util/functionmodule

Core type definitions and small utilities for working with functions. This file is the source of the AnyCaller type that threads through the whole library to produce accurate stack traces, and provides BLACKHOLE() and PASSTHROUGH() — two no-op sentinels used throughout as safe default callbacks.

Things to know:

  • BLACKHOLE is a stable function reference (not recreated on every call), so it is safe to compare with === and to use as a default prop value without triggering re-renders.
  • AnyCaller is used as the last parameter of many util functions so errors show the correct call site in the stack trace — pass myFunction itself when wrapping another helper.

Usage

Checking and asserting functions

ts
import { isFunction, assertFunction } from "shelving/util";

isFunction(() => {});   // true
isFunction("hello");    // false

assertFunction(callback); // throws RequiredError if not a function

No-op sentinels

ts
import { BLACKHOLE, PASSTHROUGH } from "shelving/util";

// Safe default for event handlers that do nothing.
<Button onClick={BLACKHOLE} />

// Identity transform — useful as a default mapping function.
const transform = options.map ?? PASSTHROUGH;
const result = transform(value); // returns value unchanged

Callback types

ts
import type { Callback, ValueCallback, ErrorCallback } from "shelving/util";

const onDone: Callback = () => console.log("done");
const onValue: ValueCallback<string> = (v) => console.log(v);
const onError: ErrorCallback = (err) => console.error(err);

Functions

Go

isFunction()function

Is a value a function?

isFunction(value: unknown): value is AnyFunction
Go

assertFunction()function

Assert that a value is a function.

assertFunction(value: unknown): asserts value is AnyFunction
Go

PASSTHROUGH()function

Function that just passes through the first argument.

PASSTHROUGH(value: T): T
Go

BLACKHOLE()function

Function that does nothing with its arguments and always returns void.

BLACKHOLE(..._unused: Arguments): void | undefined

Types

Go

Argumentstype

Readonly unknown array that is being used as a set of arguments to a function.

readonly unknown[]
Go

UnknownFunctiontype

Unknown function.

(...args: unknown[]) => unknown
Go

AnyFunctiontype

Any function (purposefully as wide as possible for use with extends X or is X statements).

(...args: any) => any
Go

AnyCallertype

Any calling function or constructor, usually referring to something that can call in the current scope that can appear in a stack trace.

AnyFunction | AnyConstructor
Go

Callbacktype

A callback is a function that is called when something happens, optionally with multiple values.

(...args: A) => void
Go

ValueCallbacktype

A callback is a function that is called when something happens with a value.

(value: T) => void
Go

ErrorCallbacktype

Function that is called when something errors.

(reason: unknown) => void