functionalscript 0.43.1 → 0.44.0

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

@@ -1,40 +0,0 @@
-/**
- * Indented text `Block` rendering and UTF-8 helpers: `flat` flattens a nested
- * block into prefixed lines, while `utf8`/`utf8ToString` convert between
- * strings and MSB-first UTF-8 bit vectors.
- *
- * @module
- */
-import { type Vec } from '../types/bit_vec/module.f.ts';
-import { type List } from '../types/list/module.f.ts';
-import { type Nullable } from '../types/nullable/module.f.ts';
-export type Block = ItemThunk | ItemArray;
-type ItemArray = readonly Item[];
-type ItemThunk = () => List<Item>;
-export type Item = string | ItemArray | ItemThunk;
-export declare const flat: (indent: string) => (text: Block) => List<string>;
-export type Utf8 = Vec;
-/**
- * Converts a string to an UTF-8, represented as an MSB first bit vector,
- * returning `null` instead of throwing if the result would exceed
- * `maxLength`.
- *
- * @param s The input string to be converted.
- * @returns The resulting UTF-8 bit vector, MSB first, or `null` on overflow.
- */
-export declare const tryUtf8: (s: string) => Nullable<Utf8>;
-/**
- * Converts a string to an UTF-8, represented as an MSB first bit vector.
- *
- * @param s The input string to be converted.
- * @returns The resulting UTF-8 bit vector, MSB first.
- */
-export declare const utf8: import("../types/function/module.f.ts").Func<string, Vec>;
-/**
- * Converts a UTF-8 bit vector with MSB first encoding to a string.
- *
- * @param msbV - The UTF-8 bit vector with MSB first encoding.
- * @returns The resulting string.
- */
-export declare const utf8ToString: (msbV: Utf8) => string;
-export {};

package/fjs/text/module.f.js

@@ -1,43 +0,0 @@
-/**
- * Indented text `Block` rendering and UTF-8 helpers: `flat` flattens a nested
- * block into prefixed lines, while `utf8`/`utf8ToString` convert between
- * strings and MSB-first UTF-8 bit vectors.
- *
- * @module
- */
-import { msb, tryU8ListToVec, u8List } from '../types/bit_vec/module.f.js';
-import { flatMap } from '../types/list/module.f.js';
-import { fromCodePointList, toCodePointList } from './utf8/module.f.js';
-import { stringToCodePointList, codePointListToString } from './utf16/module.f.js';
-import { mapUnwrap } from '../types/nullable/module.f.js';
-export const flat = (indent) => {
-    const f = (prefix) => {
-        const g = (item) => typeof (item) === 'string' ? [`${prefix}${item}`] : f(`${prefix}${indent}`)(item);
-        return flatMap(g);
-    };
-    return f('');
-};
-const tryU8ListToVecMsb = tryU8ListToVec(msb);
-/**
- * Converts a string to an UTF-8, represented as an MSB first bit vector,
- * returning `null` instead of throwing if the result would exceed
- * `maxLength`.
- *
- * @param s The input string to be converted.
- * @returns The resulting UTF-8 bit vector, MSB first, or `null` on overflow.
- */
-export const tryUtf8 = (s) => tryU8ListToVecMsb(fromCodePointList(stringToCodePointList(s)));
-/**
- * Converts a string to an UTF-8, represented as an MSB first bit vector.
- *
- * @param s The input string to be converted.
- * @returns The resulting UTF-8 bit vector, MSB first.
- */
-export const utf8 = mapUnwrap(tryUtf8);
-/**
- * Converts a UTF-8 bit vector with MSB first encoding to a string.
- *
- * @param msbV - The UTF-8 bit vector with MSB first encoding.
- * @returns The resulting string.
- */
-export const utf8ToString = (msbV) => codePointListToString(toCodePointList(u8List(msb)(msbV)));

package/fjs/text/proof.f.js

@@ -1,44 +0,0 @@
-import { assertEq, assertNotNullish } from '../asserts/module.f.js';
-import { flat, utf8, utf8ToString, tryUtf8 } from './module.f.js';
-import { join } from '../types/string/module.f.js';
-import { empty, maxLengthBytes } from '../types/bit_vec/module.f.js';
-const overflowStr = 'a'.repeat(Number(maxLengthBytes) + 1);
-export const proof = {
-    block: () => {
-        const text = [
-            'a',
-            'b',
-            () => [
-                'c',
-                () => ['d'],
-            ],
-            'e',
-        ];
-        const result = join('\n')(flat(':')(text));
-        assertEq(result, 'a\nb\n:c\n::d\ne');
-    },
-    encoding: () => {
-        const v = utf8('Hello world!');
-        const r = utf8ToString(v);
-        assertEq(r, 'Hello world!');
-    },
-    tryUtf8RoundTrip: () => {
-        const v = assertNotNullish(tryUtf8('Hello world!'));
-        assertEq(v, utf8('Hello world!'));
-        assertEq(utf8ToString(v), 'Hello world!');
-    },
-    tryUtf8Empty: () => {
-        assertEq(tryUtf8(''), empty);
-    },
-    tryUtf8Overflow: {
-        // One byte past `maxLengthBytes`; `tryUtf8` should report `null`
-        // instead of building an oversized `bigint`, and the throwing `utf8`
-        // wrapper should raise on the same input.
-        try: () => {
-            assertEq(tryUtf8(overflowStr), null);
-        },
-        throw: () => {
-            utf8(overflowStr);
-        },
-    },
-};

package/fjs/text/sgr/module.f.d.ts

@@ -1,53 +0,0 @@
-/**
- * ANSI Control Sequence Introducer (CSI) and Select Graphic Rendition (SGR)
- * helpers for writing formatted terminal output and TTY-aware console streams.
- *
- * @module
- */
-import { type Write, type WriteConsoles, type NodeProgramOptions } from '../../effects/node/module.f.ts';
-import { type Effect } from '../../effects/module.f.ts';
-export declare const backspace: string;
-type End = 'm';
-type Csi = (code: number | string) => string;
-/**
- * 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 declare const csi: (end: End) => Csi;
-/**
- * Specialization of CSI for Select Graphic Rendition (SGR) sequences.
- * https://en.wikipedia.org/wiki/ANSI_escape_code#SGR
- */
-export declare const sgr: Csi;
-/** Resets all SGR styles to terminal defaults. */
-export declare const reset: string;
-/** Enables bold/intense text rendering when supported by the terminal. */
-export declare const bold: string;
-/** Applies red foreground color to subsequent text. */
-export declare const fgRed: string;
-/** Applies green foreground color to subsequent text. */
-export declare const fgGreen: string;
-export type Stdout = {
-    /** Writes a string to the output stream. */
-    readonly write: (s: string) => void;
-};
-/** Stateful writer that updates previously printed text in-place. */
-export type WriteText = (text: string) => WriteText;
-/**
- * Creates a stateful text writer that rewrites the previous value using backspaces.
- *
- * @param stdout - Destination output stream.
- * @returns A recursive writer that replaces prior text on each call.
- */
-export declare const createConsoleText: (stdout: Stdout) => WriteText;
-export type CsiConsole = (s: string) => void;
-/**
- * Effect-based TTY-aware write. Strips ANSI SGR sequences when the target
- * stream is not a TTY, then encodes to UTF-8 and emits a `Write` effect.
- * Does NOT append `\n` — callers are responsible for line termination.
- */
-export declare const csiWrite: ({ std }: NodeProgramOptions) => (stream: WriteConsoles) => (s: string) => Effect<Write, void>;
-export {};

package/fjs/text/sgr/module.f.js

@@ -1,63 +0,0 @@
-/**
- * ANSI Control Sequence Introducer (CSI) and Select Graphic Rendition (SGR)
- * helpers for writing formatted terminal output and TTY-aware console streams.
- *
- * @module
- */
-// C0 control codes
-// https://en.wikipedia.org/wiki/ANSI_escape_code#C0_control_codes
-import { write } from '../../effects/node/module.f.js';
-import {} from '../../effects/module.f.js';
-import { utf8 } from "../module.f.js";
-export const backspace = '\x08';
-const begin = '\x1b[';
-/**
- * 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 => `${begin}${code.toString()}${end}`;
-/**
- * Specialization of CSI for Select Graphic Rendition (SGR) sequences.
- * https://en.wikipedia.org/wiki/ANSI_escape_code#SGR
- */
-export const sgr = csi('m');
-/** Resets all SGR styles to terminal defaults. */
-export const reset = sgr(0);
-/** Enables bold/intense text rendering when supported by the terminal. */
-export const bold = sgr(1);
-/** Applies red foreground color to subsequent text. */
-export const fgRed = sgr(31);
-/** Applies green foreground color to subsequent text. */
-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);
-};
-/**
- * Creates a stateful text writer that rewrites the previous value using backspaces.
- *
- * @param stdout - Destination output stream.
- * @returns A recursive writer that replaces prior text on each call.
- */
-export const createConsoleText = (stdout) => {
-    const f = (old) => (text) => {
-        stdout.write(replace(old)(text));
-        return f(text);
-    };
-    return f('');
-};
-const str = (isTTY) => (s) => isTTY ? s : s.replace(/\x1b\[[0-9;]*m/g, '');
-/**
- * Effect-based TTY-aware write. Strips ANSI SGR sequences when the target
- * stream is not a TTY, then encodes to UTF-8 and emits a `Write` effect.
- * Does NOT append `\n` — callers are responsible for line termination.
- */
-export const csiWrite = ({ std }) => (stream) => {
-    const toStr = str(std[stream].isTTY);
-    return (s) => write(stream, utf8(toStr(s)));
-};

package/fjs/text/sgr/proof.f.js

@@ -1,33 +0,0 @@
-import { fgRed, reset, createConsoleText, backspace, csiWrite } from './module.f.js';
-import { virtual, emptyState, defaultNodeProgramOptions } from '../../effects/node/virtual/module.f.js';
-import { assert, assertEq } from '../../asserts/module.f.js';
-const makeOptions = (isTTY) => ({ ...defaultNodeProgramOptions, std: { stdout: { isTTY }, stderr: { isTTY } } });
-export const proof = [
-    () => {
-        assertEq(fgRed, '\x1b[31m', new Error('Test failed: sgr(0)'));
-    },
-    () => {
-        const output = [];
-        const stdout = { write: (s) => { output.push(s); } };
-        const writer1 = createConsoleText(stdout);
-        const writer2 = writer1('hello');
-        assert(output[0] === 'hello');
-        // replacing 'hello' (len=5) with 'hi' (len=2): suffixLength=3
-        writer2('hi');
-        const expected = backspace.repeat(5) + 'hi' + ' '.repeat(3) + backspace.repeat(3);
-        assertEq(output[1], expected);
-    },
-    () => {
-        // csiWrite with isTTY=false strips ANSI SGR sequences
-        const writeFn = csiWrite(makeOptions(false))('stdout');
-        const [state] = virtual(emptyState)(writeFn(fgRed + 'hello' + reset));
-        assertEq(state.stdout, 'hello', ['expected ANSI stripped', state.stdout]);
-    },
-    () => {
-        // csiWrite with isTTY=true preserves ANSI SGR sequences
-        const writeFn = csiWrite(makeOptions(true))('stdout');
-        const [state] = virtual(emptyState)(writeFn(fgRed + 'hello' + reset));
-        const expected = fgRed + 'hello' + reset;
-        assertEq(state.stdout, expected, ['expected ANSI preserved', state.stdout]);
-    },
-];

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

@@ -1,161 +0,0 @@
-/**
- * UTF-16 utilities: convert between strings, UTF-16 code units, and Unicode
- * code points, including surrogate-pair encoding/decoding via streaming
- * `stateScan` operations.
- *
- * @module
- */
-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;
-/**
- * Converts a single Unicode code point to a string — the scalar counterpart of
- * {@link codePointListToString}, for callers that hold one code point rather
- * than a list of them and would otherwise wrap it in a single-element list.
- *
- * Input outside the assignable range — a surrogate, a value above
- * `0x10FFFF`, or a negative one — is truncated to its low 16 bits and encoded
- * as that code unit, rather than rejected. This matches
- * {@link codePointListToString}, which reports malformed input through the
- * decoder's `errorMask` on the way *in* rather than through a failure on the
- * way out.
- *
- * @param codePoint - A Unicode code point (`CodePoint`).
- * @returns The one- or two-code-unit string encoding it.
- *
- * @example
- *
- * ```ts
- * codePointToString(0x48)      // 'H'
- * codePointToString(0x1F600)   // the 😀 surrogate pair
- * codePointToString(0x110000)  // '\u0000' — out of range, low 16 bits kept
- * ```
- */
-export declare const codePointToString: (codePoint: CodePoint) => string;