Wiki source code of Front-End Utility Library
Last modified by Manuel Leduc on 2026/02/05 17:22
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | Package name:Â ##@xwiki/cristal-fn-utils##. | ||
| 2 | |||
| 3 | The utility library provides several function utilities and types to simplify some common operations. | ||
| 4 | |||
| 5 | == API == | ||
| 6 | |||
| 7 | {{code language="typescript"}} | ||
| 8 | /** | ||
| 9 | * Ensure a statement is unreachable | ||
| 10 | * | ||
| 11 | * @param value - the error value printed when this method is reached | ||
| 12 | * | ||
| 13 | * @since 18.0.0RC1 | ||
| 14 | * @beta | ||
| 15 | */ | ||
| 16 | function assertUnreachable(value: never): never; | ||
| 17 | |||
| 18 | /** | ||
| 19 | * Assert that a value is in an array, and fix its type | ||
| 20 | * | ||
| 21 | * @since 18.0.0RC1 | ||
| 22 | * @beta | ||
| 23 | * | ||
| 24 | * @param array - the array to check | ||
| 25 | * @param value - the value expected in the array | ||
| 26 | * @param message - a message displayed in case the value is not found in the array | ||
| 27 | * | ||
| 28 | * @returns Whether the value is in the provided array, with the correct type | ||
| 29 | */ | ||
| 30 | function assertInArray<T, U extends T>( | ||
| 31 | value: T, | ||
| 32 | array: U[], | ||
| 33 | message: string, | ||
| 34 | ): U; | ||
| 35 | |||
| 36 | /** | ||
| 37 | * Get a function's output or `null` if it thrown an error | ||
| 38 | * | ||
| 39 | * @since 18.0.0RC1 | ||
| 40 | * @beta | ||
| 41 | * | ||
| 42 | * @param func - The function to try | ||
| 43 | * | ||
| 44 | * @returns The function's output, or `null` if it thrown an error | ||
| 45 | */ | ||
| 46 | function tryFallible<T>(func: () => T): T | null; | ||
| 47 | |||
| 48 | /** | ||
| 49 | * Get a function's output or the thrown error | ||
| 50 | * Will construct a new Error object if the thrown value is not an instance of the Error class | ||
| 51 | * | ||
| 52 | * @since 18.0.0RC1 | ||
| 53 | * @beta | ||
| 54 | * | ||
| 55 | * @param func - The function to try | ||
| 56 | * | ||
| 57 | * @returns The function's output, the thrown error if it's an instance of the `Error` class, or a constructed `Error` instance | ||
| 58 | */ | ||
| 59 | // eslint-disable-next-line max-statements | ||
| 60 | function tryFallibleOrError<T>(func: () => T): T | Error; | ||
| 61 | |||
| 62 | /** | ||
| 63 | * Get a funcion's promise's output or the thrown error | ||
| 64 | * Will construct a new Error object if the thrown value is not an instance of the Error class | ||
| 65 | * | ||
| 66 | * @since 18.0.0RC1 | ||
| 67 | * @beta | ||
| 68 | * | ||
| 69 | * @param func - The function to try | ||
| 70 | * | ||
| 71 | * @returns The promise's output, the thrown/resolved error if it's an instance of the `Error` class, or a constructed `Error` instance | ||
| 72 | */ | ||
| 73 | // eslint-disable-next-line max-statements | ||
| 74 | async function tryFalliblePromiseOrError<T>( | ||
| 75 | func: () => Promise<T>, | ||
| 76 | ): Promise<T | Error>; | ||
| 77 | |||
| 78 | /** | ||
| 79 | * Provide a type for expressions type inference | ||
| 80 | * | ||
| 81 | * This is actually an identity function - the provided value is returned as is, with no other operation. | ||
| 82 | * | ||
| 83 | * @since 18.0.0RC1 | ||
| 84 | * @beta | ||
| 85 | * | ||
| 86 | * @param value - The value to return | ||
| 87 | * @returns - The provided value | ||
| 88 | * | ||
| 89 | * @example `[1].concat("Hello")` // Type error | ||
| 90 | * @example `provideTypeInference<number | string>([1].concat("Hello"))` // Works | ||
| 91 | */ | ||
| 92 | function provideTypeInference<T>(value: T): T; | ||
| 93 | |||
| 94 | /** | ||
| 95 | * Filter and map an array's values | ||
| 96 | * | ||
| 97 | * Combines both `.filter` and `.map` with the additional benefit of conditional type predicates | ||
| 98 | * | ||
| 99 | * @since 18.0.0RC1 | ||
| 100 | * @beta | ||
| 101 | * | ||
| 102 | * @example `filterMap([1, 2, 3], value => value >= 2 ? value.toString() : null) // ['2', '3']` | ||
| 103 | * | ||
| 104 | * @param array - The array to map | ||
| 105 | * @param filterMap - The function performing the mapping and filtering. Returning `null` or `undefined` corresponds to filter values out. | ||
| 106 | * | ||
| 107 | * @returns The filtered and mapped array | ||
| 108 | */ | ||
| 109 | function filterMap<T, U>( | ||
| 110 | array: T[], | ||
| 111 | filterMap: (value: T, index: number) => U | null | undefined, | ||
| 112 | ): U[]; | ||
| 113 | |||
| 114 | /** | ||
| 115 | * Get correctly-typed object entries, functionally equivalent to `Object.entries` | ||
| 116 | * | ||
| 117 | * Fixes builtin `Object.entries` which types the returned object values as `any` | ||
| 118 | * | ||
| 119 | * @param obj - The object to get the entries of | ||
| 120 | * | ||
| 121 | * @returns - The correctly-typed object's entries | ||
| 122 | * | ||
| 123 | * @since 18.0.0RC1 | ||
| 124 | * @beta | ||
| 125 | */ | ||
| 126 | function objectEntries<O extends Record<string, unknown>>( | ||
| 127 | obj: O, | ||
| 128 | ): Array<[keyof O & string, O[keyof O]]>; | ||
| 129 | |||
| 130 | |||
| 131 | /** | ||
| 132 | * Produce an HTML string representing an element | ||
| 133 | * | ||
| 134 | * @param tagName - The element's tag name | ||
| 135 | * @param attrs - The element's attributes | ||
| 136 | * @param content - The element's inner HTML content | ||
| 137 | * | ||
| 138 | * @returns - The string representation of the HTML element | ||
| 139 | * | ||
| 140 | * @since 18.0.0RC1 | ||
| 141 | * @beta | ||
| 142 | */ | ||
| 143 | function produceHtmlEl( | ||
| 144 | tagName: string, | ||
| 145 | attrs: Record<string, string | undefined>, | ||
| 146 | innerHTML: string | false, | ||
| 147 | ): string; | ||
| 148 | |||
| 149 | /** | ||
| 150 | * Escape HTML-specific characters in a string | ||
| 151 | * | ||
| 152 | * @param str - The string to escape | ||
| 153 | * | ||
| 154 | * @returns - The HTML-safe string | ||
| 155 | * | ||
| 156 | * @since 18.0.0RC1 | ||
| 157 | * @beta | ||
| 158 | */ | ||
| 159 | function escapeHtml(str: string): string; | ||
| 160 | |||
| 161 | /** | ||
| 162 | * Generic tree structure type. | ||
| 163 | * @since 18.0.0RC1 | ||
| 164 | * @beta | ||
| 165 | */ | ||
| 166 | type TreeNode<T> = T & { | ||
| 167 | children?: TreeNode<T>[]; | ||
| 168 | }; | ||
| 169 | {{/code}} |
