Reference

Package name: @xwiki/cristal-fn-utils.

The utility library provides several function utilities and types to simplify some common operations.

API

/**
 * Ensure a statement is unreachable
 *
 * @param value - the error value printed when this method is reached
 *
 * @since 18.0.0RC1
 * @beta
 */
function assertUnreachable(value: never): never;

/**
 * Assert that a value is in an array, and fix its type
 *
 * @since 18.0.0RC1
 * @beta
 *
 * @param array - the array to check
 * @param value - the value expected in the array
 * @param message - a message displayed in case the value is not found in the array
 *
 * @returns Whether the value is in the provided array, with the correct type
 */
function assertInArray<T, U extends T>(
  value: T,
  array: U[],
  message: string,
): U;

/**
 * Get a function's output or `null` if it thrown an error
 *
 * @since 18.0.0RC1
 * @beta
 *
 * @param func - The function to try
 *
 * @returns The function's output, or `null` if it thrown an error
 */
function tryFallible<T>(func: () => T): T | null;

/**
 * Get a function's output or the thrown error
 * Will construct a new Error object if the thrown value is not an instance of the Error class
 *
 * @since 18.0.0RC1
 * @beta
 *
 * @param func - The function to try
 *
 * @returns The function's output, the thrown error if it's an instance of the `Error` class, or a constructed `Error` instance
 */
// eslint-disable-next-line max-statements
function tryFallibleOrError<T>(func: () => T): T | Error;

/**
 * Get a funcion's promise's output or the thrown error
 * Will construct a new Error object if the thrown value is not an instance of the Error class
 *
 * @since 18.0.0RC1
 * @beta
 *
 * @param func - The function to try
 *
 * @returns The promise's output, the thrown/resolved error if it's an instance of the `Error` class, or a constructed `Error` instance
 */
// eslint-disable-next-line max-statements
async function tryFalliblePromiseOrError<T>(
  func: () => Promise<T>,
): Promise<T | Error>;

/**
 * Provide a type for expressions type inference
 *
 * This is actually an identity function - the provided value is returned as is, with no other operation.
 *
 * @since 18.0.0RC1
 * @beta
 *
 * @param value - The value to return
 * @returns - The provided value
 *
 * @example `[1].concat("Hello")` // Type error
 * @example `provideTypeInference<number | string>([1].concat("Hello"))` // Works
 */
function provideTypeInference<T>(value: T): T;

/**
 * Filter and map an array's values
 *
 * Combines both `.filter` and `.map` with the additional benefit of conditional type predicates
 *
 * @since 18.0.0RC1
 * @beta
 *
 * @example `filterMap([1, 2, 3], value => value >= 2 ? value.toString() : null) // ['2', '3']`
 *
 * @param array - The array to map
 * @param filterMap - The function performing the mapping and filtering. Returning `null` or `undefined` corresponds to filter values out.
 *
 * @returns The filtered and mapped array
 */
function filterMap<T, U>(
  array: T[],
  filterMap: (value: T, index: number) => U | null | undefined,
): U[];

/**
 * Get correctly-typed object entries, functionally equivalent to `Object.entries`
 *
 * Fixes builtin `Object.entries` which types the returned object values as `any`
 *
 * @param obj - The object to get the entries of
 *
 * @returns - The correctly-typed object's entries
 *
 * @since 18.0.0RC1
 * @beta
 */
function objectEntries<O extends Record<string, unknown>>(
  obj: O,
): Array<[keyof O & string, O[keyof O]]>;


/**
 * Produce an HTML string representing an element
 *
 * @param tagName - The element's tag name
 * @param attrs - The element's attributes
 * @param content - The element's inner HTML content
 *
 * @returns - The string representation of the HTML element
 *
 * @since 18.0.0RC1
 * @beta
 */
function produceHtmlEl(
  tagName: string,
  attrs: Record<string, string | undefined>,
  innerHTML: string | false,
): string;

/**
 * Escape HTML-specific characters in a string
 *
 * @param str - The string to escape
 *
 * @returns - The HTML-safe string
 *
 * @since 18.0.0RC1
 * @beta
 */
function escapeHtml(str: string): string;

/**
 * Generic tree structure type.
 * @since 18.0.0RC1
 * @beta
 */
type TreeNode<T> = T & {
  children?: TreeNode<T>[];
};