@design-edito/tools 0.4.4 → 0.4.6

package/agnostic/strings/matches/index.js

@@ -1,11 +1,38 @@
-import {
-  matches,
-  matchesEvery,
-  matchesSome
-} from "../../../chunks/chunk-R3AWQXMY.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  matches,
-  matchesEvery,
-  matchesSome
-};
+/**
+ * Checks whether a string matches a single matcher.
+ *
+ * @param input - The string to test.
+ * @param matcher - The matcher to test against.
+ * @returns `true` if the input matches, otherwise `false`.
+ */
+export function matches(input, matcher) {
+    if (typeof matcher === 'string')
+        return input === matcher;
+    if (typeof matcher === 'function')
+        return matcher(input);
+    return input.match(matcher) !== null;
+}
+/**
+ * Checks whether a string matches at least one matcher in a list (or a single matcher).
+ *
+ * @param input - The string to test.
+ * @param matchers - A matcher or array of matchers.
+ * @returns `true` if the input matches at least one matcher, otherwise `false`.
+ */
+export function matchesSome(input, matchers) {
+    if (!Array.isArray(matchers))
+        return matches(input, matchers);
+    return matchers.some(matcher => matches(input, matcher));
+}
+/**
+ * Checks whether a string matches every matcher in a list (or a single matcher).
+ *
+ * @param input - The string to test.
+ * @param matchers - A matcher or array of matchers.
+ * @returns `true` if the input matches all matchers, otherwise `false`.
+ */
+export function matchesEvery(input, matchers) {
+    if (!Array.isArray(matchers))
+        return matches(input, matchers);
+    return matchers.every(matcher => matches(input, matcher));
+}

package/agnostic/strings/normalize-indent/index.js

@@ -1,19 +1,35 @@
-import "../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/agnostic/strings/normalize-indent/index.ts
-function normalizeIndent(input, indentLevel = 0) {
-  const indent = " ".repeat(indentLevel);
-  const lines = input.split("\n");
-  const noIndentLines = lines.map((line) => line.replace(/^\s*/igm, ""));
-  const pipeReplacedLines = noIndentLines.map((line) => {
-    const nbPipeCharsOnLineStart = line.match(/^\|+/igm)?.[0].length ?? 0;
-    const noPipeLine = line.slice(nbPipeCharsOnLineStart);
-    const replacedPipes = " ".repeat(nbPipeCharsOnLineStart);
-    return replacedPipes + noPipeLine;
-  });
-  const normalizedLines = pipeReplacedLines.map((line) => indent + line);
-  return normalizedLines.join("\n");
+/**
+ * Normalizes the indentation of a multi-line string.
+ *
+ * Removes all existing leading whitespace, replaces leading `|` characters with spaces,
+ * and applies a uniform indentation to all lines.
+ *
+ * @param input - The multi-line string to normalize.
+ * @param indentLevel - The number of spaces to prepend to each line after normalization. Defaults to `0`.
+ * @returns The input string with normalized indentation.
+ *
+ * @example
+ * const str = `
+ * |function test() {
+ * |  console.log('hi')
+ * |}`;
+ *
+ * console.log(normalizeIndent(str, 2));
+ * // Output:
+ * // "  function test() {
+ * //    console.log('hi')
+ * //  }"
+ */
+export function normalizeIndent(input, indentLevel = 0) {
+    const indent = (' ').repeat(indentLevel);
+    const lines = input.split('\n');
+    const noIndentLines = lines.map(line => line.replace(/^\s*/igm, ''));
+    const pipeReplacedLines = noIndentLines.map(line => {
+        const nbPipeCharsOnLineStart = line.match(/^\|+/igm)?.[0].length ?? 0;
+        const noPipeLine = line.slice(nbPipeCharsOnLineStart);
+        const replacedPipes = (' ').repeat(nbPipeCharsOnLineStart);
+        return replacedPipes + noPipeLine;
+    });
+    const normalizedLines = pipeReplacedLines.map(line => indent + line);
+    return normalizedLines.join('\n');
 }
-export {
-  normalizeIndent
-};

package/agnostic/strings/parse-table/index.js

@@ -1,87 +1,156 @@
-import {
-  makeFailure,
-  makeSuccess
-} from "../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/agnostic/strings/parse-table/index.ts
-var defaultLineModeOptions = {
-  mode: "line",
-  splitLines: (i) => i.split("\n"),
-  headerPos: 0,
-  splitHeaderCells: (h) => h.split("	"),
-  bodyBounds: [1, Infinity],
-  splitBodyCells: (i) => i.split("	"),
-  schema: (i) => i
+import * as Outcome from '../../misc/outcome/index.js';
+const defaultLineModeOptions = {
+    mode: 'line',
+    splitLines: i => i.split('\n'),
+    headerPos: 0,
+    splitHeaderCells: h => h.split('\t'),
+    bodyBounds: [1, Infinity],
+    splitBodyCells: i => i.split('\t'),
+    schema: i => i
 };
-var defaultColumnModeOptions = {
-  mode: "column",
-  splitLines: (i) => i.split("\n"),
-  headerPos: 0,
-  bodyBounds: [1, Infinity],
-  columns: [],
-  headerCellRefine: (h) => h,
-  bodyCellRefine: (v) => v,
-  schema: (i) => i
+const defaultColumnModeOptions = {
+    mode: 'column',
+    splitLines: i => i.split('\n'),
+    headerPos: 0,
+    bodyBounds: [1, Infinity],
+    columns: [],
+    headerCellRefine: h => h,
+    bodyCellRefine: v => v,
+    schema: i => i
 };
-function parseTable(table, _options) {
-  const inferredMode = "mode" in _options && _options.mode !== void 0 ? _options.mode : "columns" in _options ? "column" : "splitHeaderCells" in _options ? "line" : "line";
-  const options = inferredMode === "column" ? { ...defaultColumnModeOptions, ..._options, mode: "column" } : { ...defaultLineModeOptions, ..._options, mode: "line" };
-  const lines = options.splitLines(table);
-  const headLine = lines.at(options.headerPos);
-  if (headLine === void 0) return makeFailure(`Header line not found at position ${options.headerPos}`);
-  if (options.mode === "line" && "splitHeaderCells" in options) {
-    const headers = options.splitHeaderCells(headLine);
-    const [bodyStart, bodyEnd] = options.bodyBounds;
-    const bodyLines = lines.slice(bodyStart, bodyEnd);
-    const bodyLinesSplit = bodyLines.map(options.splitBodyCells);
-    const rows = [];
-    bodyLinesSplit.forEach((lineCells) => {
-      const row = {};
-      const cellCount = Math.min(lineCells.length, headers.length);
-      for (let cellPos = 0; cellPos < cellCount; cellPos++) {
-        const cellName = headers[cellPos];
-        const cellValue = lineCells[cellPos];
-        if (cellName !== void 0 && cellValue !== void 0) {
-          row[cellName] = cellValue;
-        }
-      }
-      const validated = options.schema(row);
-      if (validated !== void 0) rows.push(validated);
-    });
-    return makeSuccess(rows);
-  }
-  if (options.mode === "column" && "columns" in options) {
-    const { columns, headerCellRefine, bodyCellRefine } = options;
-    if (columns.length === 0) return makeFailure("Column mode requires at least one column position");
-    const colBounds = columns.map((colStartPos, colIndex) => {
-      const nextColStartPos = columns[colIndex + 1];
-      return [colStartPos, nextColStartPos ?? Infinity];
-    });
-    const headers = colBounds.map(([start, end]) => {
-      const rawHeader = headLine.slice(start, end);
-      return headerCellRefine(rawHeader);
-    });
-    const [bodyStart, bodyEnd] = options.bodyBounds;
-    const bodyLines = lines.slice(bodyStart, bodyEnd);
-    const rows = [];
-    bodyLines.forEach((line) => {
-      const row = {};
-      colBounds.forEach(([start, end], colIndex) => {
-        const header = headers[colIndex];
-        if (header !== void 0) {
-          const rawValue = line.slice(start, end);
-          const refinedValue = bodyCellRefine(rawValue);
-          row[header] = refinedValue;
-        }
-      });
-      const validated = options.schema(row);
-      if (validated !== void 0) rows.push(validated);
-    });
-    return makeSuccess(rows);
-  }
-  return makeFailure("Invalid parsing mode configuration");
+/**
+ * Parses a tabular string input into an array of typed objects.
+ *
+ * Supports two parsing modes:
+ * 1. **Delimiter-based** (`mode: 'line'` or when `columns` is not provided): Splits rows and cells using delimiter functions
+ * 2. **Fixed-width columns** (`mode: 'column'` or when `columns` is provided): Slices text at fixed character positions
+ *
+ * @template T - The type of objects in the resulting array, extending `Record<string, string>`.
+ * @param {string} table - The string representation of the table to parse.
+ * @param {Partial<ParseTableOptions<T>> & { schema: (obj: unknown) => T | undefined }} options - Configuration options.
+ * @param {function(unknown): T | undefined} options.schema - **Required.** Validates and transforms each row. Return `undefined` to skip invalid rows.
+ * @param {'line' | 'column'} [options.mode] - Parsing mode. If omitted, inferred from presence of `columns` property.
+ * @param {function(string): string[]} [options.splitLines] - How to split input into lines.
+ * @param {number} [options.headerPos=0] - Index of the header line.
+ * @param {[number, number]} [options.bodyBounds=[1, Infinity]] - Range of lines to parse as body rows `[start, end)`.
+ *
+ * **Delimiter-based mode options:**
+ * @param {function(string): string[]} [options.splitHeaderCells] - How to split header line into column names.
+ * @param {function(string): string[]} [options.splitBodyCells] - How to split body lines into cell values.
+ *
+ * **Fixed-width column mode options:**
+ * @param {number[]} [options.columns] - Starting positions for each column.
+ * @param {function(string): string} [options.headerCellRefine] - Clean/normalize header names.
+ * @param {function(string): string} [options.bodyCellRefine] - Clean/normalize cell values.
+ *
+ * @returns {Outcome.Either<T[], string>}
+ * - On success: `{ success: true, payload: T[] }` containing parsed rows.
+ * - On failure: `{ success: false, payload: string }` containing error message.
+ *
+ * @example
+ * // Delimiter-based parsing (TSV)
+ * const tsvTable = 'name\tage\nAlice\t30\nBob\t25';
+ * const result = parseTable(tsvTable, { schema: row => row });
+ * // result.payload = [{ name: 'Alice', age: '30' }, { name: 'Bob', age: '25' }]
+ *
+ * @example
+ * // Fixed-width column parsing
+ * const fixedTable = 'Name      Age\nAlice     30 \nBob       25 ';
+ * const result = parseTable(fixedTable, {
+ *   mode: 'column',
+ *   columns: [0, 10],
+ *   headerCellRefine: h => h.trim().toLowerCase(),
+ *   bodyCellRefine: v => v.trim(),
+ *   schema: row => row
+ * });
+ * // result.payload = [{ name: 'Alice', age: '30' }, { name: 'Bob', age: '25' }]
+ *
+ * @example
+ * // With schema validation
+ * type Person = { name: string; age: string };
+ * const validatePerson = (obj: unknown): Person | undefined => {
+ *   if (typeof obj !== 'object' || obj === null) return undefined;
+ *   const { name, age } = obj as any;
+ *   if (typeof name !== 'string' || typeof age !== 'string') return undefined;
+ *   return { name, age };
+ * };
+ * const result = parseTable(tsvTable, { schema: validatePerson });
+ */
+export function parseTable(table, _options) {
+    // Determine mode: explicit mode, presence of 'columns', or presence of 'splitHeaderCells'
+    const inferredMode = 'mode' in _options && _options.mode !== undefined
+        ? _options.mode
+        : 'columns' in _options
+            ? 'column'
+            : 'splitHeaderCells' in _options
+                ? 'line'
+                : 'line'; // default to line mode
+    const options = inferredMode === 'column'
+        ? { ...defaultColumnModeOptions, ..._options, mode: 'column' }
+        : { ...defaultLineModeOptions, ..._options, mode: 'line' };
+    const lines = options.splitLines(table);
+    const headLine = lines.at(options.headerPos);
+    if (headLine === undefined)
+        return Outcome.makeFailure(`Header line not found at position ${options.headerPos}`);
+    // Delimiter-based mode (line mode)
+    if (options.mode === 'line' && 'splitHeaderCells' in options) {
+        const headers = options.splitHeaderCells(headLine);
+        const [bodyStart, bodyEnd] = options.bodyBounds;
+        const bodyLines = lines.slice(bodyStart, bodyEnd);
+        const bodyLinesSplit = bodyLines.map(options.splitBodyCells);
+        const rows = [];
+        bodyLinesSplit.forEach(lineCells => {
+            const row = {};
+            const cellCount = Math.min(lineCells.length, headers.length);
+            for (let cellPos = 0; cellPos < cellCount; cellPos++) {
+                const cellName = headers[cellPos];
+                const cellValue = lineCells[cellPos];
+                if (cellName !== undefined
+                    && cellValue !== undefined) {
+                    row[cellName] = cellValue;
+                }
+            }
+            const validated = options.schema(row);
+            if (validated !== undefined)
+                rows.push(validated);
+        });
+        return Outcome.makeSuccess(rows);
+    }
+    // Fixed-width column mode
+    if (options.mode === 'column' && 'columns' in options) {
+        const { columns, headerCellRefine, bodyCellRefine } = options;
+        if (columns.length === 0)
+            return Outcome.makeFailure('Column mode requires at least one column position');
+        // Build column boundaries: [start, end) for each column
+        const colBounds = columns.map((colStartPos, colIndex) => {
+            const nextColStartPos = columns[colIndex + 1];
+            return [colStartPos, nextColStartPos ?? Infinity];
+        });
+        // Extract and refine headers
+        const headers = colBounds.map(([start, end]) => {
+            const rawHeader = headLine.slice(start, end);
+            return headerCellRefine(rawHeader);
+        });
+        // Parse body rows
+        const [bodyStart, bodyEnd] = options.bodyBounds;
+        const bodyLines = lines.slice(bodyStart, bodyEnd);
+        const rows = [];
+        bodyLines.forEach(line => {
+            const row = {};
+            colBounds.forEach(([start, end], colIndex) => {
+                const header = headers[colIndex];
+                if (header !== undefined) {
+                    const rawValue = line.slice(start, end);
+                    const refinedValue = bodyCellRefine(rawValue);
+                    row[header] = refinedValue;
+                }
+            });
+            const validated = options.schema(row);
+            if (validated !== undefined)
+                rows.push(validated);
+        });
+        return Outcome.makeSuccess(rows);
+    }
+    // This should never happen due to type constraints, but provides safety
+    return Outcome.makeFailure('Invalid parsing mode configuration');
 }
-export {
-  parseTable
-};

package/agnostic/strings/replace-all/index.js

@@ -1,18 +1,37 @@
-import "../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/agnostic/strings/replace-all/index.ts
-function replaceAll(input, pattern, replacer) {
-  console.warn("[DEPRECATED] Use String.replaceAll instead");
-  const found = Array.from(input.match(pattern) ?? []);
-  const foundReplaced = typeof replacer === "string" ? found.map(() => replacer) : found.map((e) => replacer(e));
-  const splitted = input.split(pattern);
-  const replaced = splitted.map((chunk, chunkPos) => {
-    const isLast = chunkPos === splitted.length - 1;
-    if (isLast) return [chunk];
-    return [chunk, foundReplaced[chunkPos] ?? ""];
-  }).flat().join("");
-  return replaced;
+// [WIP] 1/ this function seem not to work all the time
+// [WIP] 2/ this function is obsolete now that String.replaceAll is widely supported
+/**
+ * Replaces all occurrences of a pattern in a string.
+ *
+ * **Deprecated:** This function is mostly obsolete now that `String.prototype.replaceAll` is widely supported.
+ *
+ * @param input - The string to operate on.
+ * @param pattern - The string or RegExp pattern to replace.
+ * @param replacer - The replacement string or a function that returns a replacement for each match.
+ * @returns The resulting string with all matches replaced.
+ *
+ * @deprecated Use `String.prototype.replaceAll` instead.
+ *
+ * @example
+ * replaceAll('foo bar foo', 'foo', 'baz')
+ * // => 'baz bar baz'
+ *
+ * @example
+ * replaceAll('abc 123 abc', /abc/g, match => match.toUpperCase())
+ * // => 'ABC 123 ABC'
+ */
+export function replaceAll(input, pattern, replacer) {
+    console.warn('[DEPRECATED] Use String.replaceAll instead');
+    const found = Array.from(input.match(pattern) ?? []);
+    const foundReplaced = typeof replacer === 'string'
+        ? found.map(() => replacer)
+        : found.map(e => replacer(e));
+    const splitted = input.split(pattern);
+    const replaced = splitted.map((chunk, chunkPos) => {
+        const isLast = chunkPos === splitted.length - 1;
+        if (isLast)
+            return [chunk];
+        return [chunk, foundReplaced[chunkPos] ?? ''];
+    }).flat().join('');
+    return replaced;
 }
-export {
-  replaceAll
-};

package/agnostic/strings/to-alphanum/index.js

@@ -1,11 +1,24 @@
-import "../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/agnostic/strings/to-alphanum/index.ts
-function toAlphanum(string, replacer = "") {
-  const replaced = string.replace(/[^a-z0-9]/igm, replacer);
-  if (replacer.length === 0) return replaced;
-  return replaced.replace(new RegExp(`${replacer}+`, "igm"), replacer);
+/**
+ * Converts a string to an alphanumeric-only string.
+ *
+ * Non-alphanumeric characters are replaced with the provided `replacer`.
+ * Consecutive occurrences of the `replacer` are collapsed into a single instance.
+ *
+ * @param string - The input string to sanitize.
+ * @param replacer - The string to replace non-alphanumeric characters with. Defaults to empty string.
+ * @returns The sanitized alphanumeric string.
+ *
+ * @example
+ * toAlphanum("Hello, World!")
+ * // => "HelloWorld"
+ *
+ * @example
+ * toAlphanum("Hello, World!", "-")
+ * // => "Hello-World"
+ */
+export function toAlphanum(string, replacer = '') {
+    const replaced = string.replace(/[^a-z0-9]/igm, replacer);
+    if (replacer.length === 0)
+        return replaced;
+    return replaced.replace(new RegExp(`${replacer}+`, 'igm'), replacer);
 }
-export {
-  toAlphanum
-};

package/agnostic/strings/trim/index.js

@@ -1,9 +1,24 @@
-import {
-  trimEnd,
-  trimStart
-} from "../../../chunks/chunk-6XL25OZX.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  trimEnd,
-  trimStart
-};
+/**
+ * Removes all leading whitespace characters from a string.
+ *
+ * @param string - The string to trim.
+ * @returns The input string without leading whitespace.
+ *
+ * @example
+ * trimStart("   hello") // => "hello"
+ */
+export function trimStart(string) {
+    return string.replace(/^\s*/, '');
+}
+/**
+ * Removes all trailing whitespace characters from a string.
+ *
+ * @param string - The string to trim.
+ * @returns The input string without trailing whitespace.
+ *
+ * @example
+ * trimEnd("hello   ") // => "hello"
+ */
+export function trimEnd(string) {
+    return string.replace(/\s*$/, '');
+}