@design-edito/tools 0.4.5 → 0.4.11

package/agnostic/random/random/index.js

@@ -1,16 +1,19 @@
-// src/agnostic/random/random/index.ts
-function random(bound1 = 1, bound2) {
-  const min = bound2 === void 0 ? 0 : bound1;
-  const max = bound2 ?? bound1;
-  if (min === max || min > max) return void 0;
-  const range = max - min;
-  return Math.random() * range + min;
+export function random(bound1 = 1, bound2) {
+    const min = bound2 === undefined ? 0 : bound1;
+    const max = bound2 ?? bound1;
+    if (min === max || min > max)
+        return undefined;
+    const range = max - min;
+    return (Math.random() * range) + min;
 }
-function randomInt(...args) {
-  const rand = random(...args);
-  return rand !== void 0 ? Math.floor(rand) : void 0;
+/**
+ * Generates a random integer within a range.
+ *
+ * @param {number} [bound1=1] - The lower bound if `bound2` is provided, otherwise the upper bound (min is 0).
+ * @param {number} [bound2] - Optional upper bound. If omitted, the range is `[0, bound1)`.
+ * @returns {number | undefined} A random integer in `[min, max)`, or `undefined` if bounds are invalid.
+ */
+export function randomInt(...args) {
+    const rand = random(...args);
+    return rand !== undefined ? Math.floor(rand) : undefined;
 }
-export {
-  random,
-  randomInt
-};

package/agnostic/random/random/index.test.js

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { random, randomInt } from './index.js';
+describe('random', () => {
+    it('generates a number in [0, 1) by default', () => {
+        const value = random();
+        expect(typeof value === 'number' || value === undefined).toBe(true);
+        if (value !== undefined) {
+            expect(value).toBeGreaterThanOrEqual(0);
+            expect(value).toBeLessThan(1);
+        }
+    });
+    it('supports a single upper-bound argument [0, bound)', () => {
+        const bound = 10;
+        const value = random(bound);
+        expect(typeof value === 'number' || value === undefined).toBe(true);
+        if (value !== undefined) {
+            expect(value).toBeGreaterThanOrEqual(0);
+            expect(value).toBeLessThan(bound);
+        }
+    });
+    it('supports explicit min/max bounds [min, max)', () => {
+        const min = 5;
+        const max = 10;
+        const value = random(min, max);
+        expect(typeof value === 'number' || value === undefined).toBe(true);
+        if (value !== undefined) {
+            expect(value).toBeGreaterThanOrEqual(min);
+            expect(value).toBeLessThan(max);
+        }
+    });
+    it('returns undefined when min === max', () => {
+        expect(random(5, 5)).toBeUndefined();
+    });
+    it('returns undefined when min > max', () => {
+        expect(random(10, 5)).toBeUndefined();
+    });
+});
+describe('randomInt', () => {
+    it('generates an integer in [0, 1) by default (always 0 when defined)', () => {
+        const value = randomInt();
+        expect(typeof value === 'number' || value === undefined).toBe(true);
+        if (value !== undefined) {
+            expect(Number.isInteger(value)).toBe(true);
+            expect(value).toBeGreaterThanOrEqual(0);
+            expect(value).toBeLessThan(1);
+        }
+    });
+    it('generates an integer within [0, bound)', () => {
+        const bound = 10;
+        const value = randomInt(bound);
+        expect(typeof value === 'number' || value === undefined).toBe(true);
+        if (value !== undefined) {
+            expect(Number.isInteger(value)).toBe(true);
+            expect(value).toBeGreaterThanOrEqual(0);
+            expect(value).toBeLessThan(bound);
+        }
+    });
+    it('generates an integer within [min, max)', () => {
+        const min = 3;
+        const max = 7;
+        const value = randomInt(min, max);
+        expect(typeof value === 'number' || value === undefined).toBe(true);
+        if (value !== undefined) {
+            expect(Number.isInteger(value)).toBe(true);
+            expect(value).toBeGreaterThanOrEqual(min);
+            expect(value).toBeLessThan(max);
+        }
+    });
+    it('returns undefined when bounds are invalid', () => {
+        expect(randomInt(5, 5)).toBeUndefined();
+        expect(randomInt(10, 5)).toBeUndefined();
+    });
+});

package/agnostic/random/uuid/index.js

@@ -1,23 +1,31 @@
-// src/agnostic/random/hex-char/index.ts
-var hexChars = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "a", "b", "c", "d", "e", "f"];
-function randomHexChar() {
-  const nbr = Math.floor(Math.random() * 16);
-  const char = hexChars[nbr];
-  return char;
+import { randomHexChar } from '../hex-char/index.js';
+/**
+ * Generates a random hexadecimal string of given length.
+ *
+ * @param {number} [length=4] - Number of hex characters.
+ * @returns {string} Random hexadecimal string.
+ */
+export function randomHash(length = 4) {
+    return new Array(length)
+        .fill(null)
+        .map(randomHexChar)
+        .join('');
 }
-
-// src/agnostic/random/uuid/index.ts
-function randomHash(length = 4) {
-  return new Array(length).fill(null).map(randomHexChar).join("");
+/**
+ * Generates a random hexadecimal string following a pattern.
+ *
+ * @param {number[]} pattern - Array of segment lengths.
+ * @param {string} [joiner='-'] - String used to join the segments.
+ * @returns {string} Random hexadecimal string with segments joined by `joiner`.
+ */
+export function randomHashPattern(pattern, joiner = '-') {
+    return pattern.map(randomHash).join(joiner);
 }
-function randomHashPattern(pattern, joiner = "-") {
-  return pattern.map(randomHash).join(joiner);
+/**
+ * Generates a random UUID-like string (version 4 style, not RFC-compliant).
+ *
+ * @returns {string} Random UUID-like string.
+ */
+export function randomUUID() {
+    return randomHashPattern([8, 4, 4, 4, 12]);
 }
-function randomUUID() {
-  return randomHashPattern([8, 4, 4, 4, 12]);
-}
-export {
-  randomHash,
-  randomHashPattern,
-  randomUUID
-};

package/agnostic/random/uuid/index.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { randomHash, randomHashPattern, randomUUID } from './index.js';
+import { hexChars } from '../hex-char/index.js';
+const isHexString = (value) => value.split('').every(char => hexChars.includes(char));
+describe('randomHash', () => {
+    it('generates a 4-character hexadecimal string by default', () => {
+        const hash = randomHash();
+        expect(hash.length).toBe(4);
+        expect(isHexString(hash)).toBe(true);
+    });
+    it('generates a hexadecimal string of the requested length', () => {
+        const length = 8;
+        const hash = randomHash(length);
+        expect(hash.length).toBe(length);
+        expect(isHexString(hash)).toBe(true);
+    });
+});
+describe('randomHashPattern', () => {
+    it('generates segments of the requested lengths joined by default "-"', () => {
+        const pattern = [2, 3, 4];
+        const hash = randomHashPattern(pattern);
+        const parts = hash.split('-');
+        expect(parts.length).toBe(pattern.length);
+        parts.forEach((part, index) => {
+            expect(part.length).toBe(pattern[index]);
+            expect(isHexString(part)).toBe(true);
+        });
+    });
+    it('supports a custom joiner', () => {
+        const pattern = [1, 1, 1];
+        const joiner = ':';
+        const hash = randomHashPattern(pattern, joiner);
+        expect(hash.split(joiner).length).toBe(pattern.length);
+    });
+});
+describe('randomUUID', () => {
+    it('generates a UUID-like hexadecimal string with expected pattern', () => {
+        const uuid = randomUUID();
+        const parts = uuid.split('-');
+        expect(parts.map(p => p.length)).toEqual([8, 4, 4, 4, 12]);
+        parts.forEach(part => {
+            expect(isHexString(part)).toBe(true);
+        });
+    });
+});

package/agnostic/regexps/index.js

@@ -1,98 +1,140 @@
-// src/agnostic/regexps/index.ts
-function mergeFlags(...flagStrs) {
-  const flagsSet = /* @__PURE__ */ new Set();
-  flagStrs.forEach(
-    (flagStr) => flagStr.split("").forEach((char) => flagsSet.add(char))
-  );
-  return Array.from(flagsSet.values()).join("");
+/**
+ * Merges multiple flag strings into a single string containing each flag only once.
+ *
+ * @param {...string[]} flagStrs - Flag strings to merge.
+ * @returns {string} Merged flags string.
+ */
+export function mergeFlags(...flagStrs) {
+    const flagsSet = new Set();
+    flagStrs.forEach(flagStr => flagStr
+        .split('')
+        .forEach(char => flagsSet.add(char)));
+    return Array.from(flagsSet.values()).join('');
 }
-function setFlags(regexp, flags) {
-  const mergedFlags = mergeFlags(regexp.flags, flags);
-  return new RegExp(`${regexp.source}`, mergedFlags);
+/**
+ * Returns a new RegExp with combined flags.
+ *
+ * @param {RegExp} regexp - The original regular expression.
+ * @param {string} flags - Flags to add.
+ * @returns {RegExp} New regular expression with combined flags.
+ */
+export function setFlags(regexp, flags) {
+    const mergedFlags = mergeFlags(regexp.flags, flags);
+    return new RegExp(`${regexp.source}`, mergedFlags);
 }
-function fromStart(regexp, flags = "g") {
-  const mergedFlags = mergeFlags(regexp.flags, flags);
-  return new RegExp(`^(${regexp.source})`, mergedFlags);
+/**
+ * Anchors a RegExp to the start of a string.
+ *
+ * @param {RegExp} regexp - The original regular expression.
+ * @param {string} [flags='g'] - Optional flags to apply.
+ * @returns {RegExp} Anchored RegExp.
+ */
+export function fromStart(regexp, flags = 'g') {
+    const mergedFlags = mergeFlags(regexp.flags, flags);
+    return new RegExp(`^(${regexp.source})`, mergedFlags);
 }
-function toEnd(regexp, flags = "g") {
-  const mergedFlags = mergeFlags(regexp.flags, flags);
-  return new RegExp(`(${regexp.source})$`, mergedFlags);
+/**
+ * Anchors a RegExp to the end of a string.
+ *
+ * @param {RegExp} regexp - The original regular expression.
+ * @param {string} [flags='g'] - Optional flags to apply.
+ * @returns {RegExp} Anchored RegExp.
+ */
+export function toEnd(regexp, flags = 'g') {
+    const mergedFlags = mergeFlags(regexp.flags, flags);
+    return new RegExp(`(${regexp.source})$`, mergedFlags);
 }
-function fromStartToEnd(regexp, flags = "g") {
-  const mergedFlags = mergeFlags(regexp.flags, flags);
-  return fromStart(toEnd(regexp, mergedFlags), mergedFlags);
+/**
+ * Anchors a RegExp to match the entire string.
+ *
+ * @param {RegExp} regexp - The original regular expression.
+ * @param {string} [flags='g'] - Optional flags to apply.
+ * @returns {RegExp} Anchored RegExp.
+ */
+export function fromStartToEnd(regexp, flags = 'g') {
+    const mergedFlags = mergeFlags(regexp.flags, flags);
+    return fromStart(toEnd(regexp, mergedFlags), mergedFlags);
 }
-function stringStartsWith(string, regexp, returnMatches = false, flags = "g") {
-  const actualRegexp = fromStart(regexp, flags);
-  return returnMatches ? string.match(actualRegexp) : actualRegexp.test(string);
+export function stringStartsWith(string, regexp, returnMatches = false, flags = 'g') {
+    const actualRegexp = fromStart(regexp, flags);
+    return returnMatches ? string.match(actualRegexp) : actualRegexp.test(string);
 }
-function stringEndsWith(string, regexp, returnMatches = false, flags = "g") {
-  const actualRegexp = toEnd(regexp, flags);
-  return returnMatches ? string.match(actualRegexp) : actualRegexp.test(string);
+export function stringEndsWith(string, regexp, returnMatches = false, flags = 'g') {
+    const actualRegexp = toEnd(regexp, flags);
+    return returnMatches ? string.match(actualRegexp) : actualRegexp.test(string);
 }
-function stringIs(string, regexp, returnMatches = false, flags = "g") {
-  const actualRegexp = fromStartToEnd(regexp, flags);
-  return returnMatches ? string.match(actualRegexp) : actualRegexp.test(string);
+export function stringIs(string, regexp, returnMatches = false, flags = 'g') {
+    const actualRegexp = fromStartToEnd(regexp, flags);
+    return returnMatches ? string.match(actualRegexp) : actualRegexp.test(string);
 }
-function fromStrings(strings) {
-  const rootsMap = stringsToRootsMap(strings);
-  const source = sourceFromRootsMap(rootsMap, false);
-  const regexp = new RegExp(source);
-  return regexp;
+/**
+ * Creates a RegExp that matches any of the provided strings.
+ *
+ * @param {string[]} strings - Strings to match.
+ * @returns {RegExp} Regular expression matching all strings.
+ */
+export function fromStrings(strings) {
+    const rootsMap = stringsToRootsMap(strings);
+    const source = sourceFromRootsMap(rootsMap, false);
+    const regexp = new RegExp(source);
+    return regexp;
 }
-function escape(string) {
-  let result = "";
-  for (const ch of string) {
-    if (ch === "\n") {
-      result += "\\n";
-    } else if (/\s/.test(ch)) {
-      result += "\\s";
-    } else if (/[.*+?^${}()|[\]\\]/.test(ch)) {
-      result += "\\" + ch;
-    } else {
-      result += ch;
+/**
+ * Escapes special RegExp characters in a string.
+ * - Newlines are turned into `\\n`
+ * - Other whitespace characters are normalized to `\\s`
+ * - RegExp special characters (including backslash) are escaped
+ *
+ * @param {string} string - String to escape.
+ * @returns {string} Escaped string.
+ */
+export function escape(string) {
+    let result = '';
+    for (const ch of string) {
+        if (ch === '\n') {
+            result += '\\n';
+        }
+        else if (/\s/.test(ch)) {
+            result += '\\s'; // any other whitespace (space, tab, etc.)
+        }
+        else if (/[.*+?^${}()|[\]\\]/.test(ch)) {
+            result += '\\' + ch; // regex special chars (including backslash)
+        }
+        else {
+            result += ch;
+        }
     }
-  }
-  return result;
+    return result;
 }
-function stringsToRootsMap(strings, rootsMap = /* @__PURE__ */ new Map()) {
-  const lengthSorted = strings.sort((strA, strB) => strA.length - strB.length);
-  lengthSorted.forEach((string) => {
-    const [firstChar, ...lastChars] = string.split("");
-    const isWordEnd = lastChars.length === 0;
-    if (firstChar === void 0) return;
-    const roots = Array.from(rootsMap.keys());
-    const foundRoot = roots.find((root) => new RegExp(`^(${escape(root)})`).test(string));
-    const subRootsMap = foundRoot !== void 0 ? rootsMap.get(foundRoot)?.subRootsMap : void 0;
-    if (foundRoot === void 0 || subRootsMap === void 0) {
-      const subRootsMap2 = /* @__PURE__ */ new Map();
-      stringsToRootsMap([lastChars.join("")], subRootsMap2);
-      return rootsMap.set(firstChar, { subRootsMap: subRootsMap2, isWordEnd });
-    }
-    stringsToRootsMap([lastChars.join("")], subRootsMap);
-  });
-  return rootsMap;
+function stringsToRootsMap(strings, rootsMap = new Map()) {
+    const lengthSorted = strings.sort((strA, strB) => strA.length - strB.length);
+    lengthSorted.forEach(string => {
+        const [firstChar, ...lastChars] = string.split('');
+        const isWordEnd = lastChars.length === 0;
+        if (firstChar === undefined)
+            return;
+        const roots = Array.from(rootsMap.keys());
+        const foundRoot = roots.find(root => new RegExp(`^(${escape(root)})`).test(string));
+        const subRootsMap = foundRoot !== undefined
+            ? rootsMap.get(foundRoot)?.subRootsMap
+            : undefined;
+        if (foundRoot === undefined || subRootsMap === undefined) {
+            const subRootsMap = new Map();
+            stringsToRootsMap([lastChars.join('')], subRootsMap);
+            return rootsMap.set(firstChar, { subRootsMap, isWordEnd });
+        }
+        stringsToRootsMap([lastChars.join('')], subRootsMap);
+    });
+    return rootsMap;
 }
 function sourceFromRootsMap(rootsMap, isOptional) {
-  const rootsMapEntries = Array.from(rootsMap.entries());
-  if (rootsMapEntries.length === 0) return "";
-  const regexpBody = rootsMapEntries.map(([root, rootData]) => {
-    return `${escape(root)}${sourceFromRootsMap(
-      rootData.subRootsMap,
-      rootData.isWordEnd
-    )}`;
-  }).join("|");
-  return isOptional ? `(${regexpBody})?` : `(${regexpBody})`;
+    const rootsMapEntries = Array.from(rootsMap.entries());
+    if (rootsMapEntries.length === 0)
+        return '';
+    const regexpBody = rootsMapEntries.map(([root, rootData]) => {
+        return `${escape(root)}${sourceFromRootsMap(rootData.subRootsMap, rootData.isWordEnd)}`;
+    }).join('|');
+    return isOptional
+        ? `(${regexpBody})?`
+        : `(${regexpBody})`;
 }
-export {
-  escape,
-  fromStart,
-  fromStartToEnd,
-  fromStrings,
-  mergeFlags,
-  setFlags,
-  stringEndsWith,
-  stringIs,
-  stringStartsWith,
-  toEnd
-};

package/agnostic/regexps/index.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import { mergeFlags, setFlags, fromStart, toEnd, fromStartToEnd, stringStartsWith, stringEndsWith, stringIs, fromStrings, escape } from './index.js';
+describe('mergeFlags', () => {
+    it('merges flags without duplicates', () => {
+        expect(mergeFlags('g', 'g')).toBe('g');
+        const merged = mergeFlags('g', 'i', 'm');
+        expect(merged.length).toBe(3);
+        expect(merged.includes('g')).toBe(true);
+        expect(merged.includes('i')).toBe(true);
+        expect(merged.includes('m')).toBe(true);
+    });
+});
+describe('setFlags', () => {
+    it('adds new flags to existing regexp flags', () => {
+        const regexp = /abc/g;
+        const withFlags = setFlags(regexp, 'i');
+        expect(withFlags.flags.includes('g')).toBe(true);
+        expect(withFlags.flags.includes('i')).toBe(true);
+    });
+});
+describe('fromStart / toEnd / fromStartToEnd', () => {
+    it('anchors regexps at the start', () => {
+        const re = fromStart(/abc/);
+        expect('abcdef'.match(re)).not.toBeNull();
+        expect('zabc'.match(re)).toBeNull();
+    });
+    it('anchors regexps at the end', () => {
+        const re = toEnd(/abc/);
+        expect('zabc'.match(re)).not.toBeNull();
+        expect('abczz'.match(re)).toBeNull();
+    });
+    it('anchors regexps at both start and end', () => {
+        const re = fromStartToEnd(/abc/);
+        expect('abc'.match(re)).not.toBeNull();
+        expect('zabc'.match(re)).toBeNull();
+        expect('abczz'.match(re)).toBeNull();
+    });
+});
+describe('stringStartsWith', () => {
+    it('returns a boolean by default', () => {
+        const ok = stringStartsWith('foobar', /foo/);
+        const ko = stringStartsWith('barfoo', /foo/);
+        expect(ok).toBe(true);
+        expect(ko).toBe(false);
+    });
+    it('can return matches when requested', () => {
+        const result = stringStartsWith('foobar', /foo/, true);
+        if (result !== null) {
+            expect(result[0]).toBe('foo');
+        }
+    });
+});
+describe('stringEndsWith', () => {
+    it('returns a boolean by default', () => {
+        const ok = stringEndsWith('foobar', /bar/);
+        const ko = stringEndsWith('barfoo', /bar/);
+        expect(ok).toBe(true);
+        expect(ko).toBe(false);
+    });
+    it('can return matches when requested', () => {
+        const result = stringEndsWith('foobar', /bar/, true);
+        if (result !== null) {
+            expect(result[0]).toBe('bar');
+        }
+    });
+});
+describe('stringIs', () => {
+    it('checks for a full-string match', () => {
+        const ok = stringIs('foo', /foo/);
+        const ko1 = stringIs('foobar', /foo/);
+        const ko2 = stringIs('barfoo', /foo/);
+        expect(ok).toBe(true);
+        expect(ko1).toBe(false);
+        expect(ko2).toBe(false);
+    });
+    it('can return matches when requested', () => {
+        const result = stringIs('foo', /foo/, true);
+        if (result !== null) {
+            expect(result[0]).toBe('foo');
+        }
+    });
+});
+describe('fromStrings', () => {
+    it('creates a regexp matching any of the provided strings', () => {
+        const strings = ['cat', 'car', 'dog'];
+        const re = fromStrings(strings);
+        expect('cat'.match(re)).not.toBeNull();
+        expect('car'.match(re)).not.toBeNull();
+        expect('dog'.match(re)).not.toBeNull();
+        expect('cow'.match(re)).toBeNull();
+    });
+});
+describe('escape', () => {
+    it('escapes regexp special characters', () => {
+        const input = 'a.b*c+d?^$()|[]{}\\';
+        const escaped = escape(input);
+        expect(new RegExp(escaped).test(input)).toBe(true);
+        expect(escaped).toContain('\\.');
+        expect(escaped).toContain('\\*');
+        expect(escaped).toContain('\\?');
+    });
+    it('escapes whitespace and newlines', () => {
+        const input = 'a b\nc';
+        const escaped = escape(input);
+        expect(escaped.includes('\\s')).toBe(true);
+        expect(escaped.includes('\\n')).toBe(true);
+    });
+});

package/agnostic/sanitization/file-name/index.js

@@ -1,9 +1,25 @@
-// src/agnostic/sanitization/file-name/index.ts
-function sanitizeFileName(input, maxLength = 255) {
-  input = input.normalize("NFKC").replace(/[<>:"/\\|?*\x00-\x1F]/g, "").trim().replace(/\s+/g, " ").replace(/\.+/g, ".").replace(/^\.+|\.+$/g, "");
-  if (input.length > maxLength) return null;
-  return input.length > 0 ? input : null;
+/**
+ * Sanitizes a single file name by removing invalid characters and normalizing Unicode.
+ *
+ * - Removes characters forbidden in Windows and Unix file systems.
+ * - Replaces multiple spaces with a single space.
+ * - Replaces multiple dots with a single dot and removes leading/trailing dots.
+ * - Normalizes Unicode to NFKC form to prevent homoglyph attacks.
+ *
+ * @param {string} input - The file name to sanitize.
+ * @param {number} [maxLength=255] - Maximum allowed length of the sanitized file name.
+ * @returns {string | null} Sanitized file name, or null if empty or exceeds maxLength.
+ */
+export function sanitizeFileName(input, maxLength = 255) {
+    input = input
+        .normalize('NFKC') // Normalize Unicode to avoid homoglyph attacks
+        // eslint-disable-next-line no-control-regex
+        .replace(/[<>:"/\\|?*\x00-\x1F]/g, '') // Remove invalid characters (e.g., Windows and Unix forbidden characters)
+        .trim() // Trim whitespace
+        .replace(/\s+/g, ' ') // Replace multiple spaces with a single space
+        .replace(/\.+/g, '.') // Replace multiple dots with a single dot
+        .replace(/^\.+|\.+$/g, ''); // Remove leading/trailing dots
+    if (input.length > maxLength)
+        return null;
+    return input.length > 0 ? input : null;
 }
-export {
-  sanitizeFileName
-};

package/agnostic/sanitization/file-name/index.test.js

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { sanitizeFileName } from './index.js';
+describe('sanitizeFileName', () => {
+    it('removes invalid characters and trims/condenses spaces', () => {
+        const input = '  in*va|lid:file?name  ';
+        const result = sanitizeFileName(input);
+        expect(result).toBe('invalidfilename');
+    });
+    it('normalizes multiple dots and strips leading/trailing dots', () => {
+        const input = '...my...file...name...';
+        const result = sanitizeFileName(input);
+        expect(result).toBe('my.file.name');
+    });
+    it('returns null when the result is empty', () => {
+        const result = sanitizeFileName(' <>:"/\\\\|?*');
+        expect(result).toBeNull();
+    });
+    it('returns null when exceeding max length', () => {
+        const long = 'a'.repeat(10);
+        const result = sanitizeFileName(long, 5);
+        expect(result).toBeNull();
+    });
+});