functionalscript 0.4.3 → 0.5.0

package/text/sgr/module.f.js

@@ -1,8 +1,33 @@
+// Co control codes
+// https://en.wikipedia.org/wiki/ANSI_escape_code#C0_control_codes
+export const backspace = '\x08';
 /**
+ * Control Sequence Introducer (CSI) escape sequence.
+ * https://en.wikipedia.org/wiki/ANSI_escape_code#Control_Sequence_Introducer_commands
+ *
+ * @param end - The final character that indicates the type of sequence.
+ * @returns A function that takes a code (number or string) and returns the complete ANSI escape sequence.
+ */
+export const csi = (end) => code => `\x1b[${code.toString()}${end}`;
+/**
+ * Specialization of CSI for Select Graphic Rendition (SGR) sequences.
  * https://en.wikipedia.org/wiki/ANSI_escape_code#SGR
  */
-export const sgr = (c) => `\x1b[${c.toString()}m`;
+export const sgr = csi('m');
 export const reset = sgr(0);
 export const bold = sgr(1);
 export const fgRed = sgr(31);
 export const fgGreen = sgr(32);
+const { max } = Math;
+const replace = (old) => (text) => {
+    const len = old.length;
+    const suffixLength = max(0, len - text.length);
+    return backspace.repeat(len) + text + " ".repeat(suffixLength) + backspace.repeat(suffixLength);
+};
+export const createConsoleText = (stdout) => {
+    const f = (old) => (text) => {
+        stdout.write(replace(old)(text));
+        return f(text);
+    };
+    return f('');
+};

package/text/sgr/test.f.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (() => void)[];
+export default _default;

package/text/sgr/test.f.js

@@ -0,0 +1,8 @@
+import { fgRed } from "./module.f.js";
+export default [
+    () => {
+        if (fgRed !== '\x1b[31m') {
+            throw new Error('Test failed: sgr(0)');
+        }
+    }
+];

package/text/utf16/module.f.d.ts

@@ -1,14 +1,130 @@
 import { type List, type Thunk } from '../../types/list/module.f.ts';
+/**
+ * Represent an unsigned UTF16, used to store one word UTF-16 (code unit).
+ */
 export type U16 = number;
 /**
  * [0, 0x10_FFFF]: 16+5 = 21 bits
  *
  * 121_0000_0000: 16+16+9 = 41 bits
  */
+/**
+ * Represent an Unicode code point.
+ * Has range: from 0x0000 to 0x10_FFFF (21 bits).
+ */
 export type CodePoint = number;
+/**
+ * Converts a UTF-16 sequence to its corresponding Unicode code points.
+ *
+ * This function handles:
+ * 1. Single U16 values in the Basic Multilingual Plane (BMP) [0x0000–0xFFFF].
+ * 2. Surrogate pairs representing code points in the Supplementary Plane [0x10000–0x10FFFF].
+ * 3. Invalid input sequences by applying an error mask to the resulting code point.
+ *
+ * @param utf16 - A list of UTF-16 code units (U16) to convert.
+ * @returns A list of Unicode code points. Each code point corresponds to one or more U16
+ *          values in the input. Invalid sequences are marked with the `errorMask`.
+ * @example
+ *
+ * ```ts
+ * const exampleUtf16: List<U16> = [
+ *     0x0041,       // 'A' (BMP, single U16)
+ *     0xD83D, 0xDE00, // 😀 (Emoji, surrogate pair)
+ *     0xD800,       // Unpaired high surrogate
+ *     0xDC00,       // Unpaired low surrogate
+ * ]
+ *
+ * const codePoints = toCodePointList(exampleUtf16)
+ * codePoints.forEach((codePoint) => {
+ *     if (codePoint & errorMask) {
+ *         console.log(`Invalid sequence detected: ${codePoint.toString(16).toUpperCase()}`)
+ *     } else {
+ *         console.log(`Code Point: U+${codePoint.toString(16).toUpperCase()}`)
+ *     }
+ * })
+ * ```
+ */
 export declare const fromCodePointList: (input: List<CodePoint>) => Thunk<U16>;
+/**
+ * Converts a list of UTF-16 code units to a list of Unicode code points (CodePoint).
+ * This function processes each UTF-16 code unit, decoding them into their corresponding Unicode code points.
+ * The input list of `U16` values may represent characters in the Basic Multilingual Plane (BMP) or supplementary planes,
+ * with surrogate pairs handled correctly. The function also handles EOF (`null`).
+ * @param input - A list of UTF-16 code units (`U16`), possibly containing surrogate pairs.
+ * @returns A list of Unicode code points (`CodePoint`), one for each valid code unit or surrogate pair.
+ *
+ * @example
+ *
+ * ```ts
+ * const utf16List: List<U16> = [0x0041, 0xD83D, 0xDE00] // 'A' and 😀 (surrogate pair)
+ * const codePoints = toCodePointList(utf16List)
+ * ```
+ */
 export declare const toCodePointList: (input: List<U16>) => List<CodePoint>;
+/**
+ * Converts a string to a list of UTF-16 code units (U16).
+ *
+ * This function processes each character in the input string and converts it to its corresponding UTF-16 code unit(s).
+ * Characters in the Basic Multilingual Plane (BMP) will produce a single `U16`, while supplementary plane characters
+ * (those requiring surrogate pairs) will produce two `U16` values.
+ * @param s - The input string to convert to UTF-16 code units.
+ * @returns A list of UTF-16 code units (`U16`) representing the string.
+ *
+ * @example
+ *
+ * ```js
+ * const inputString = "Hello, 😀"
+ * const utf16List = stringToList(inputString)
+ * ```
+ */
 export declare const stringToList: (s: string) => List<U16>;
+/**
+ * Converts a string to a list of Unicode code points (CodePoint).
+ * This function first converts the string to a list of UTF-16 code units (U16) using `stringToList`,
+ * then it converts the UTF-16 code units to Unicode code points using `toCodePointList`. This is useful for handling
+ * Unicode characters, including supplementary characters represented by surrogate pairs in UTF-16.
+ *
+ * @param input - The input string to convert.
+ * @returns A list of Unicode code points (`CodePoint`) corresponding to the characters in the string.
+ *
+ * @example
+ *
+ * ```js
+ * const inputString = "Hello, 😀"
+ * const codePoints = stringToCodePointList(inputString)
+ * ```
+ */
 export declare const stringToCodePointList: (input: string) => List<CodePoint>;
+/**
+ * Converts a list of UTF-16 code units (U16) to a string.
+ * This function takes a list of `U16` values (UTF-16 code units) and reconstructs the original string by mapping
+ * each code unit back to its character using `String.fromCharCode`. The resulting characters are concatenated
+ * to form the final string.
+ *
+ * @param input - A list of UTF-16 code units (`U16`).
+ * @returns A string representing the characters encoded by the input UTF-16 code units.
+ *
+ * @example
+ *
+ * ```ts
+ * const utf16List: List<U16> = [0x0041, 0x0042, 0x0043] // 'ABC'
+ * const outputString = listToString(utf16List)
+ * ```
+ */
 export declare const listToString: (input: List<U16>) => string;
+/**
+ * Converts a list of Unicode code points (CodePoint) to a string.
+ * This function first converts the list of Unicode code points to a list of UTF-16 code units using `fromCodePointList`,
+ * then it uses `listToString` to reconstruct the string from the UTF-16 code units.
+ *
+ * @param input - A list of Unicode code points (`CodePoint`).
+ * @returns A string representing the characters encoded by the input code points.
+ *
+ * @example
+ *
+ * ```ts
+ * const codePoints: List<CodePoint> = [0x48, 0x65, 0x6C, 0x6C, 0x6F]
+ * const outputString = codePointListToString(codePoints)
+ * ```
+ */
 export declare const codePointListToString: (input: List<CodePoint>) => string;

package/text/utf16/module.f.js

@@ -2,13 +2,67 @@ import { map, flat, stateScan, reduce, flatMap, empty, } from "../../types/list/
 import { concat } from "../../types/function/operator/module.f.js";
 import { contains } from "../../types/range/module.f.js";
 import { fn } from "../../types/function/module.f.js";
+/**
+ * Ranges of code points for the lower (Low) and higher (High) parts of the BMP (Basic Multilingual Plane) plane.
+ */
 const lowBmp = contains([0x0000, 0xd7ff]);
 const highBmp = contains([0xe000, 0xffff]);
+/**
+ * Checks whether the code point is in the BMP range.
+ * BMP is the main multi-plane Unicode plane that covers code points 0x0000 - 0xFFFF, except for the range of surrogates.
+ */
 const isBmpCodePoint = (codePoint) => lowBmp(codePoint) || highBmp(codePoint);
+/**
+ * Checks whether the 16-bit word (U16) is a surrogate of the high part.
+ * Range: 0xD800 - 0xDBFF.
+ */
 const isHighSurrogate = contains([0xd800, 0xdbff]);
+/**
+ * Checks whether the 16-bit word (U16) is a substitute for the low part.
+ * Range: 0xDC00 – 0xDFFF.
+ */
 const isLowSurrogate = contains([0xdc00, 0xdfff]);
+/**
+ * Mask of mistakes. Used to indicate invalid code points or coding errors
+ */
 const errorMask = 0b1000_0000_0000_0000_0000_0000_0000_0000;
+/**
+ * Checks whether the code point belongs to the additional (Supplementary) plane of Unicode.
+ * Additional planes include code points from 0x010000 to 0x10FFFF.
+ */
 const isSupplementaryPlane = contains([0x01_0000, 0x10_ffff]);
+/**
+ * Converts a Unicode code point to its corresponding UTF-16 representation.
+ *
+ * This function handles:
+ * 1. Code points in the Basic Multilingual Plane (BMP) [0x0000–0xFFFF],
+ *    which map directly to a single 16-bit value (U16).
+ * 2. Supplementary Plane code points [0x10000–0x10FFFF],
+ *    which are represented as surrogate pairs in UTF-16.
+ *
+ * @param codePoint - A valid Unicode code point.
+ * @returns A list of 16-bit unsigned integers (U16) representing the UTF-16 encoding
+ *          of the input code point. If the code point is in the BMP range, a single U16
+ *          value is returned. For code points in the supplementary planes, two U16
+ *          values (a high and a low surrogate) are returned.
+ * @example
+ *
+ * ```ts
+ * const exampleCodePoints: List<CodePoint> = [
+ *     0x0041,       // 'A' (BMP, single U16)
+ *     0x1F600,      // 😀 (Emoji, supplementary plane, surrogate pair)
+ *     0xD7FF,       // Last code point in the low BMP range
+ *     0xE000,       // First code point in the high BMP range
+ *     0x10FFFF,     // Maximum valid code point in Unicode
+ *     0x110000,     // Invalid code point (outside Unicode range)
+ * ]
+ * exampleCodePoints.forEach((codePoint) => {
+ *     const utf16Result = codePointToUtf16(codePoint)
+ *     console.log(`Code Point: U+${codePoint.toString(16).toUpperCase()}`)
+ *     console.log(`UTF-16: ${utf16Result.map(u16 => u16.toString(16).toUpperCase()).join(' ')}`)
+ * })
+ * ```
+ */
 const codePointToUtf16 = (codePoint) => {
     if (isBmpCodePoint(codePoint)) {
         return [codePoint];
@@ -21,8 +75,92 @@ const codePointToUtf16 = (codePoint) => {
     }
     return [codePoint & 0xffff];
 };
+/**
+ * Converts a UTF-16 sequence to its corresponding Unicode code points.
+ *
+ * This function handles:
+ * 1. Single U16 values in the Basic Multilingual Plane (BMP) [0x0000–0xFFFF].
+ * 2. Surrogate pairs representing code points in the Supplementary Plane [0x10000–0x10FFFF].
+ * 3. Invalid input sequences by applying an error mask to the resulting code point.
+ *
+ * @param utf16 - A list of UTF-16 code units (U16) to convert.
+ * @returns A list of Unicode code points. Each code point corresponds to one or more U16
+ *          values in the input. Invalid sequences are marked with the `errorMask`.
+ * @example
+ *
+ * ```ts
+ * const exampleUtf16: List<U16> = [
+ *     0x0041,       // 'A' (BMP, single U16)
+ *     0xD83D, 0xDE00, // 😀 (Emoji, surrogate pair)
+ *     0xD800,       // Unpaired high surrogate
+ *     0xDC00,       // Unpaired low surrogate
+ * ]
+ *
+ * const codePoints = toCodePointList(exampleUtf16)
+ * codePoints.forEach((codePoint) => {
+ *     if (codePoint & errorMask) {
+ *         console.log(`Invalid sequence detected: ${codePoint.toString(16).toUpperCase()}`)
+ *     } else {
+ *         console.log(`Code Point: U+${codePoint.toString(16).toUpperCase()}`)
+ *     }
+ * })
+ * ```
+ */
 export const fromCodePointList = flatMap(codePointToUtf16);
+/**
+ * Validates whether a given 16-bit unsigned integer (U16) falls within the valid range for UTF-16 code units.
+ *
+ * UTF-16 uses 16-bit code units to encode characters. The valid range for these code units is [0x0000, 0xFFFF].
+ * This function is used to verify that a number is within this range.
+ *
+ * @param i - A 16-bit unsigned integer (U16) to validate.
+ * @returns A boolean value indicating whether the input is a valid UTF-16 code unit.
+ *
+ * @example
+ *
+ * ```ts
+ * const validU16 = u16(0x0041)  // true: U+0041 ('A')
+ * const invalidU16 = u16(0x110000)  // false: Value is outside the valid range
+ * const edgeCaseLow = u16(0x0000)  // true: Minimum valid value for UTF-16
+ * const edgeCaseHigh = u16(0xFFFF)  // true: Maximum valid value for UTF-16
+ * ```
+ */
 const u16 = contains([0x0000, 0xFFFF]);
+/**
+ * A stateful operation that converts a UTF-16 word (U16) to a list of Unicode code points (CodePoint),
+ * while maintaining the state of surrogate pair decoding.
+ *
+ * This operation processes UTF-16 code units and decodes them into Unicode code points. It handles:
+ * 1. BMP code points (single U16).
+ * 2. Surrogate pairs (two U16s representing a single code point in the supplementary planes).
+ * 3. Invalid or malformed code units.
+ *
+ * It also manages the internal state, which is necessary to handle surrogate pairs. If the state is null,
+ * it expects a valid BMP code point or a high surrogate. If the state is not null, it processes a low surrogate
+ * and combines the pair into a single supplementary code point.
+ *
+ * @param state - The current state of the UTF-16 decoding operation.
+ *               This can be either `null` (no state) or the previous high surrogate value.
+ * @param word - The current UTF-16 word (U16) to process.
+ * @returns A tuple where the first element is a list of decoded Unicode code points (`CodePoint`), and
+ *          the second element is the updated state. If the word is invalid, an error code `0xffffffff` is returned.
+ *
+ * @example
+ *
+ * ```ts
+ * const state: Utf16State = null;
+ * const word: U16 = 0xD83D;  // High surrogate for 😀 emoji
+ * const [decodedCodePoints, newState] = utf16ByteToCodePointOp(state)(word);
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const state: Utf16State = 0xD83D;  // High surrogate already stored
+ * const word: U16 = 0xDC00;  // Low surrogate for 😀 emoji
+ * const [decodedCodePoints, newState] = utf16ByteToCodePointOp(state)(word);
+ * ```
+ */
 const utf16ByteToCodePointOp = state => word => {
     if (!u16(word)) {
         return [[0xffffffff], state];
@@ -49,10 +187,110 @@ const utf16ByteToCodePointOp = state => word => {
     }
     return [[state | errorMask, word | errorMask], null];
 };
+/**
+ * Handles the EOF (end-of-file) condition during UTF-16 decoding.
+ *
+ * If there is no pending state (`state === null`), it simply returns an empty list
+ * of code points, indicating no further input to process. If there is a pending state,
+ * it is treated as an unpaired surrogate, and the `errorMask` is applied to flag
+ * the invalid sequence.
+ *
+ * @param state - The current UTF-16 decoding state. This can be:
+ *   - `null`: No pending surrogate to process.
+ *   - A high surrogate (0xD800–0xDBFF) left from an earlier input, waiting for a low surrogate.
+ * @returns A tuple:
+ *   - The first element is a list of code points. If there’s a pending state, it is returned
+ *     with the `errorMask` applied.
+ *   - The second element is the next state, which will always be `null` because EOF means no
+ *     further processing.
+ *
+ * @example
+ *
+ * ```js
+ * const eofState = utf16EofToCodePointOp(0xD800) // Unpaired high surrogate
+ * const validState = utf16EofToCodePointOp(null) // No pending state
+ * ```
+ */
 const utf16EofToCodePointOp = (state) => [state === null ? empty : [state | errorMask], null];
+/**
+ * A stateful scan operation that processes UTF-16 input (word or EOF).
+ * This function determines whether to handle a UTF-16 word or an end-of-file (EOF)
+ * signal during decoding:
+ * 1. If the input is `null` (EOF), it calls `utf16EofToCodePointOp` to process
+ *    any remaining state.
+ * 2. If the input is a valid UTF-16 word, it calls `utf16ByteToCodePointOp` to
+ *    process the word and update the state accordingly.
+ * @param state - The current state in the UTF-16 decoding process:
+ *   - `null`: No pending surrogate.
+ *   - A high surrogate waiting for a low surrogate.
+ * @param input - The current UTF-16 word to process, or `null` to signal EOF.
+ * @returns A tuple:
+ *   - A list of decoded code points (if any).
+ *   - The updated decoding state.
+ *
+ * @example
+ *
+ * ```ts
+ * // Example 1: Process a valid UTF-16 word
+ * const input1 = 0x0041 // 'A' (BMP code point)
+ * const result1 = utf16ByteOrEofToCodePointOp(null)(input1)
+ * console.log(result1) // [[0x0041], null]
+ * // Example 2: Process a high surrogate, followed by EOF
+ * const input2 = 0xD83D // High surrogate
+ * const result2 = utf16ByteOrEofToCodePointOp(null)(input2)
+ * console.log(result2) // [[], 0xD83D] (waiting for a low surrogate)
+ * const eofResult = utf16ByteOrEofToCodePointOp(0xD83D)(null)
+ * console.log(eofResult) // [[0xD83D | errorMask], null] (unpaired high surrogate)
+ * // Example 3: Handle EOF with no pending state
+ * const eofResult2 = utf16ByteOrEofToCodePointOp(null)(null)
+ * ```
+ */
 const utf16ByteOrEofToCodePointOp = state => input => input === null ? utf16EofToCodePointOp(state) : utf16ByteToCodePointOp(state)(input);
+/**
+ * Represents an end-of-file (EOF) indicator in a list of UTF-16 code units.
+ *
+ * This list contains a single element, `null`, which is used to signal the end
+ * of input during UTF-16 decoding operations.
+ * @example
+ *
+ * ```ts
+ * const input = [...utf16Data, ...eofList]
+ * // Ensures the EOF is handled during processing.
+ * ```
+ */
 const eofList = [null];
+/**
+ * Converts a list of UTF-16 code units to a list of Unicode code points (CodePoint).
+ * This function processes each UTF-16 code unit, decoding them into their corresponding Unicode code points.
+ * The input list of `U16` values may represent characters in the Basic Multilingual Plane (BMP) or supplementary planes,
+ * with surrogate pairs handled correctly. The function also handles EOF (`null`).
+ * @param input - A list of UTF-16 code units (`U16`), possibly containing surrogate pairs.
+ * @returns A list of Unicode code points (`CodePoint`), one for each valid code unit or surrogate pair.
+ *
+ * @example
+ *
+ * ```ts
+ * const utf16List: List<U16> = [0x0041, 0xD83D, 0xDE00] // 'A' and 😀 (surrogate pair)
+ * const codePoints = toCodePointList(utf16List)
+ * ```
+ */
 export const toCodePointList = (input) => flat(stateScan(utf16ByteOrEofToCodePointOp)(null)(flat([input, eofList])));
+/**
+ * Converts a string to a list of UTF-16 code units (U16).
+ *
+ * This function processes each character in the input string and converts it to its corresponding UTF-16 code unit(s).
+ * Characters in the Basic Multilingual Plane (BMP) will produce a single `U16`, while supplementary plane characters
+ * (those requiring surrogate pairs) will produce two `U16` values.
+ * @param s - The input string to convert to UTF-16 code units.
+ * @returns A list of UTF-16 code units (`U16`) representing the string.
+ *
+ * @example
+ *
+ * ```js
+ * const inputString = "Hello, 😀"
+ * const utf16List = stringToList(inputString)
+ * ```
+ */
 export const stringToList = (s) => {
     const at = (i) => {
         const first = s.charCodeAt(i);
@@ -60,8 +298,55 @@ export const stringToList = (s) => {
     };
     return at(0);
 };
+/**
+ * Converts a string to a list of Unicode code points (CodePoint).
+ * This function first converts the string to a list of UTF-16 code units (U16) using `stringToList`,
+ * then it converts the UTF-16 code units to Unicode code points using `toCodePointList`. This is useful for handling
+ * Unicode characters, including supplementary characters represented by surrogate pairs in UTF-16.
+ *
+ * @param input - The input string to convert.
+ * @returns A list of Unicode code points (`CodePoint`) corresponding to the characters in the string.
+ *
+ * @example
+ *
+ * ```js
+ * const inputString = "Hello, 😀"
+ * const codePoints = stringToCodePointList(inputString)
+ * ```
+ */
 export const stringToCodePointList = (input) => toCodePointList(stringToList(input));
+/**
+ * Converts a list of UTF-16 code units (U16) to a string.
+ * This function takes a list of `U16` values (UTF-16 code units) and reconstructs the original string by mapping
+ * each code unit back to its character using `String.fromCharCode`. The resulting characters are concatenated
+ * to form the final string.
+ *
+ * @param input - A list of UTF-16 code units (`U16`).
+ * @returns A string representing the characters encoded by the input UTF-16 code units.
+ *
+ * @example
+ *
+ * ```ts
+ * const utf16List: List<U16> = [0x0041, 0x0042, 0x0043] // 'ABC'
+ * const outputString = listToString(utf16List)
+ * ```
+ */
 export const listToString = fn(map(String.fromCharCode))
     .then(reduce(concat)(''))
     .result;
+/**
+ * Converts a list of Unicode code points (CodePoint) to a string.
+ * This function first converts the list of Unicode code points to a list of UTF-16 code units using `fromCodePointList`,
+ * then it uses `listToString` to reconstruct the string from the UTF-16 code units.
+ *
+ * @param input - A list of Unicode code points (`CodePoint`).
+ * @returns A string representing the characters encoded by the input code points.
+ *
+ * @example
+ *
+ * ```ts
+ * const codePoints: List<CodePoint> = [0x48, 0x65, 0x6C, 0x6C, 0x6F]
+ * const outputString = codePointListToString(codePoints)
+ * ```
+ */
 export const codePointListToString = (input) => listToString(fromCodePointList(input));

package/text/utf16/test.f.d.ts

@@ -2,5 +2,9 @@ declare const _default: {
     toCodePointList: (() => void)[];
     fromCodePointList: (() => void)[];
     string: (() => void)[];
+    stringToList: (() => void)[];
+    listToString: (() => void)[];
+    stringToCodePointList: (() => void)[];
+    codePointListToString: (() => void)[];
 };
 export default _default;

package/text/utf16/test.f.js

@@ -146,5 +146,33 @@ export default {
                 throw result;
             }
         }
+    ],
+    stringToList: [
+        () => {
+            const inputString = "Hello, i like js";
+            const utf16List = stringToList(inputString);
+        },
+        () => {
+            const inputString = "😇🤬🫥😑🫠";
+            const utf16List = stringToList(inputString);
+        }
+    ],
+    listToString: [
+        () => {
+            const utf16List = [0x0041, 0x0042, 0x0043];
+            const outputString = listToString(utf16List);
+        }
+    ],
+    stringToCodePointList: [
+        () => {
+            const inputString = "Hello, 😀";
+            const codePoints = stringToCodePointList(inputString);
+        }
+    ],
+    codePointListToString: [
+        () => {
+            const codePoints = [0x48, 0x65, 0x6C, 0x6C, 0x6F];
+            const outputString = codePointListToString(codePoints);
+        }
     ]
 };

package/types/monoid/module.f.d.ts

@@ -1,4 +1,4 @@
-import type { Reduce } from "../function/operator/module.f.ts";
+import type { Reduce } from '../function/operator/module.f.ts';
 /**
  * Represents a monoid, an algebraic structure with a binary operation
  * and an identity (neutral) element.
@@ -52,6 +52,8 @@ export type Monoid<T> = {
  * @returns A function that takes an element `a` and a repetition count `n`,
  * and returns the result of applying the operation `n` times.
  *
+ * See also {@link https://en.wikipedia.org/wiki/Exponentiation_by_squaring}.
+ *
  * @example
  *
  * ```ts

package/types/monoid/module.f.js

@@ -7,6 +7,8 @@
  * @returns A function that takes an element `a` and a repetition count `n`,
  * and returns the result of applying the operation `n` times.
  *
+ * See also {@link https://en.wikipedia.org/wiki/Exponentiation_by_squaring}.
+ *
  * @example
  *
  * ```ts

package/types/object/module.f.d.ts

@@ -8,3 +8,21 @@ export declare const at: (name: string) => <T>(object: Map<T>) => T | null;
 export declare const sort: <T>(e: List<Entry<T>>) => List<Entry<T>>;
 export declare const fromEntries: <T>(e: List<Entry<T>>) => Map<T>;
 export declare const fromMap: <T>(m: BtMap<T>) => Map<T>;
+/**
+ * A set of objects with a single key.
+ *
+ * See also
+ * https://stackoverflow.com/questions/57571664/typescript-type-for-an-object-with-only-one-key-no-union-type-allowed-as-a-key
+ */
+export type OneKey<K extends string, V> = {
+    [P in K]: (Record<P, V> & Partial<Record<Exclude<K, P>, never>>) extends infer O ? {
+        [Q in keyof O]: O[Q];
+    } : never;
+}[K];
+/**
+ * https://stackoverflow.com/questions/61112584/typing-a-single-record-entry
+ */
+export type NotUnion<T, U = T> = T extends unknown ? [
+    U
+] extends [T] ? T : never : never;
+export type SingleProperty<T extends Record<string, never>> = keyof T extends NotUnion<keyof T> ? T : never;

package/types/object/module.f.js

@@ -3,7 +3,7 @@ import { entries as mapEntries, fromEntries as mapFromEntries } from "../map/mod
 const { getOwnPropertyDescriptor, fromEntries: objectFromEntries } = Object;
 export const at = name => object => {
     const r = getOwnPropertyDescriptor(object, name);
-    return r === void 0 ? null : r.value;
+    return r === undefined ? null : r.value;
 };
 export const sort = e => mapEntries(mapFromEntries(e));
 export const fromEntries = e => objectFromEntries(iterable(e));

package/bnf/tag/module.f.d.ts

@@ -1,30 +0,0 @@
-import { type Array2 } from '../../types/array/module.f.ts';
-export type Range = bigint;
-export type Sequence = readonly Rule[];
-export type Or = {
-    readonly [k in string]: Rule;
-};
-export type DataRule = Or | Sequence | Range | string;
-export type LazyRule = () => DataRule;
-export type Rule = DataRule | LazyRule;
-export declare const rangeEncode: (a: number, b: number) => Range;
-export declare const oneEncode: (a: number) => Range;
-export declare const rangeDecode: (r: bigint) => Array2<number>;
-export declare const str: (s: string) => readonly Range[] | Range;
-export declare const set: (s: string) => Or;
-export declare const range: (ab: string) => Range;
-export type None = readonly [];
-export declare const none: None;
-export type Option<S> = {
-    none: None;
-    some: S;
-};
-export declare const option: <S extends Rule>(some: S) => Option<S>;
-export type Repeat0<T> = () => Option<readonly [T, Repeat0<T>]>;
-export declare const repeat0: <T extends Rule>(some: T) => Repeat0<T>;
-export type Repeat1<T> = readonly [T, Repeat0<T>];
-export declare const repeat1: <T extends Rule>(some: T) => Repeat1<T>;
-export type Join1<T, S> = readonly [T, Repeat0<readonly [S, T]>];
-export declare const join1: <T extends Rule, S extends Rule>(some: T, separator: S) => Join1<T, S>;
-export type Join0<T, S> = Option<readonly [T, Repeat0<readonly [S, T]>]>;
-export declare const join0: <T extends Rule, S extends Rule>(some: T, separator: S) => Rule;

package/bnf/tag/module.f.js

@@ -1,37 +0,0 @@
-import { stringToCodePointList } from "../../text/utf16/module.f.js";
-import { isArray2 } from "../../types/array/module.f.js";
-import { map, toArray } from "../../types/list/module.f.js";
-//
-const { fromEntries } = Object;
-const { fromCodePoint } = String;
-const offset = 24n;
-const mask = (1n << offset) - 1n;
-export const rangeEncode = (a, b) => (BigInt(a) << offset) | BigInt(b);
-export const oneEncode = (a) => rangeEncode(a, a);
-export const rangeDecode = (r) => [Number(r >> offset), Number(r & mask)];
-const mapOneEncode = map(oneEncode);
-export const str = (s) => {
-    const x = toArray(mapOneEncode(stringToCodePointList(s)));
-    return x.length === 1 ? x[0] : x;
-};
-const mapEntry = map((v) => [fromCodePoint(v), oneEncode(v)]);
-export const set = (s) => fromEntries(toArray(mapEntry(stringToCodePointList(s))));
-export const range = (ab) => {
-    const a = toArray(stringToCodePointList(ab));
-    if (!isArray2(a)) {
-        throw `Invalid range ${ab}.`;
-    }
-    return rangeEncode(...a);
-};
-export const none = [];
-export const option = (some) => ({
-    none,
-    some,
-});
-export const repeat0 = (some) => {
-    const f = () => option([some, f]);
-    return f;
-};
-export const repeat1 = (some) => [some, repeat0(some)];
-export const join1 = (some, separator) => [some, repeat0([separator, some])];
-export const join0 = (some, separator) => option(join1(some, separator));