@design-edito/tools 0.4.5 → 0.4.6

package/agnostic/misc/lorem-ipsum/index.js

@@ -1,205 +1,55 @@
-// src/agnostic/arrays/random-pick/index.ts
-function randomPick(arr, exclude = []) {
-  const filteredArr = [...arr].filter((elt) => !exclude.includes(elt));
-  const length = filteredArr.length;
-  if (length === 0) throw new Error("Array length must be at least 1 after exclusion");
-  const pos = Math.floor(Math.random() * length);
-  const found = filteredArr[pos];
-  return found;
-}
-
-// 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;
-}
-function randomInt(...args) {
-  const rand = random(...args);
-  return rand !== void 0 ? Math.floor(rand) : void 0;
-}
-
-// src/agnostic/misc/lorem-ipsum/index.ts
-var words = [
-  "a",
-  "ac",
-  "accumsan",
-  "adipiscing",
-  "aenean",
-  "aliquam",
-  "aliquet",
-  "amet",
-  "ante",
-  "arcu",
-  "at",
-  "auctor",
-  "augue",
-  "bibendum",
-  "blandit",
-  "condimentum",
-  "consectetur",
-  "consequat",
-  "convallis",
-  "cras",
-  "curabitur",
-  "cursus",
-  "dapibus",
-  "diam",
-  "dictum",
-  "dictumst",
-  "dignissim",
-  "dolor",
-  "donec",
-  "dui",
-  "duis",
-  "efficitur",
-  "egestas",
-  "eget",
-  "eleifend",
-  "elementum",
-  "elit",
-  "enim",
-  "erat",
-  "eros",
-  "est",
-  "et",
-  "eu",
-  "euismod",
-  "ex",
-  "facilisis",
-  "faucibus",
-  "felis",
-  "feugiat",
-  "finibus",
-  "fringilla",
-  "fusce",
-  "gravida",
-  "habitasse",
-  "hac",
-  "hendrerit",
-  "iaculis",
-  "id",
-  "imperdiet",
-  "in",
-  "integer",
-  "interdum",
-  "ipsum",
-  "justo",
-  "lacinia",
-  "lacus",
-  "laoreet",
-  "lectus",
-  "leo",
-  "libero",
-  "ligula",
-  "lobortis",
-  "lorem",
-  "luctus",
-  "maecenas",
-  "magna",
-  "malesuada",
-  "massa",
-  "mattis",
-  "mauris",
-  "maximus",
-  "metus",
-  "mi",
-  "molestie",
-  "mollis",
-  "morbi",
-  "nam",
-  "nec",
-  "neque",
-  "nibh",
-  "nisi",
-  "nisl",
-  "non",
-  "nulla",
-  "nullam",
-  "nunc",
-  "odio",
-  "orci",
-  "ornare",
-  "pellentesque",
-  "pharetra",
-  "phasellus",
-  "placerat",
-  "platea",
-  "porta",
-  "porttitor",
-  "posuere",
-  "praesent",
-  "pulvinar",
-  "purus",
-  "quam",
-  "quis",
-  "quisque",
-  "risus",
-  "rutrum",
-  "sagittis",
-  "sapien",
-  "sed",
-  "sem",
-  "semper",
-  "sit",
-  "sodales",
-  "sollicitudin",
-  "suscipit",
-  "suspendisse",
-  "tellus",
-  "tempor",
-  "tempus",
-  "tincidunt",
-  "tortor",
-  "tristique",
-  "turpis",
-  "ultrices",
-  "ultricies",
-  "urna",
-  "ut",
-  "vehicula",
-  "vel",
-  "velit",
-  "venenatis",
-  "vestibulum",
-  "vitae",
-  "vivamus",
-  "viverra",
-  "volutpat",
-  "vulputate"
+import { randomPick } from '../../arrays/random-pick/index.js';
+import { randomInt } from '../../random/random/index.js';
+export const words = [
+    'a', 'ac', 'accumsan', 'adipiscing', 'aenean', 'aliquam', 'aliquet', 'amet', 'ante', 'arcu', 'at', 'auctor', 'augue',
+    'bibendum', 'blandit',
+    'condimentum', 'consectetur', 'consequat', 'convallis', 'cras', 'curabitur', 'cursus',
+    'dapibus', 'diam', 'dictum', 'dictumst', 'dignissim', 'dolor', 'donec', 'dui', 'duis',
+    'efficitur', 'egestas', 'eget', 'eleifend', 'elementum', 'elit', 'enim', 'erat', 'eros', 'est', 'et', 'eu', 'euismod', 'ex',
+    'facilisis', 'faucibus', 'felis', 'feugiat', 'finibus', 'fringilla', 'fusce',
+    'gravida',
+    'habitasse', 'hac', 'hendrerit',
+    'iaculis', 'id', 'imperdiet', 'in', 'integer', 'interdum', 'ipsum',
+    'justo',
+    'lacinia', 'lacus', 'laoreet', 'lectus', 'leo', 'libero', 'ligula', 'lobortis', 'lorem', 'luctus',
+    'maecenas', 'magna', 'malesuada', 'massa', 'mattis', 'mauris', 'maximus', 'metus', 'mi', 'molestie', 'mollis', 'morbi',
+    'nam', 'nec', 'neque', 'nibh', 'nisi', 'nisl', 'non', 'nulla', 'nullam', 'nunc',
+    'odio', 'orci', 'ornare',
+    'pellentesque', 'pharetra', 'phasellus', 'placerat', 'platea', 'porta', 'porttitor', 'posuere', 'praesent', 'pulvinar', 'purus',
+    'quam', 'quis', 'quisque',
+    'risus', 'rutrum',
+    'sagittis', 'sapien', 'sed', 'sem', 'semper', 'sit', 'sodales', 'sollicitudin', 'suscipit', 'suspendisse',
+    'tellus', 'tempor', 'tempus', 'tincidunt', 'tortor', 'tristique', 'turpis',
+    'ultrices', 'ultricies', 'urna', 'ut',
+    'vehicula', 'vel', 'velit', 'venenatis', 'vestibulum', 'vitae', 'vivamus', 'viverra', 'volutpat', 'vulputate'
 ];
-var generateSentence = (wordCount) => {
-  const resultArr = [];
-  let currentWordCound = wordCount;
-  for (let i = 0; i < currentWordCound; i++) {
-    const picked = randomPick(words);
-    if (typeof picked === "string") resultArr.push(picked);
-    else {
-      currentWordCound += 1;
+export const generateSentence = (wordCount) => {
+    const resultArr = [];
+    let currentWordCound = wordCount;
+    for (let i = 0; i < currentWordCound; i++) {
+        const picked = randomPick(words);
+        if (typeof picked === 'string')
+            resultArr.push(picked);
+        else {
+            currentWordCound += 1;
+        }
     }
-  }
-  const [firstWord, ...otherWords] = resultArr;
-  if (firstWord === void 0) return "";
-  const capFirstLetter = firstWord?.charAt(0).toUpperCase();
-  const restOfFirstWord = firstWord?.slice(1);
-  const sentence = [
-    `${capFirstLetter}${restOfFirstWord}`,
-    ...otherWords
-  ].join(" ");
-  return `${sentence}.`;
+    const [firstWord, ...otherWords] = resultArr;
+    if (firstWord === undefined)
+        return '';
+    const capFirstLetter = firstWord?.charAt(0).toUpperCase();
+    const restOfFirstWord = firstWord?.slice(1);
+    const sentence = [
+        `${capFirstLetter}${restOfFirstWord}`,
+        ...otherWords
+    ].join(' ');
+    return `${sentence}.`;
 };
-var generateSentences = (sentencesCount, maxSentenceLength = 12, minSentenceLength = 4) => {
-  const sentences = [];
-  for (let i = 0; i < sentencesCount; i++) {
-    const length = randomInt(maxSentenceLength, minSentenceLength) ?? 8;
-    sentences.push(generateSentence(length));
-  }
-  return sentences;
-};
-export {
-  generateSentence,
-  generateSentences,
-  words
+export const generateSentences = (sentencesCount, maxSentenceLength = 12, minSentenceLength = 4) => {
+    const sentences = [];
+    for (let i = 0; i < sentencesCount; i++) {
+        const length = randomInt(maxSentenceLength, minSentenceLength) ?? 8;
+        sentences.push(generateSentence(length));
+    }
+    return sentences;
 };

package/agnostic/misc/lorem-ipsum/index.test.js

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest';
+import { generateSentence, generateSentences } from './index.js';
+describe('generateSentence', () => {
+    it('generates sentence with specified word count', () => {
+        const sentence = generateSentence(5);
+        const words = sentence.split(' ');
+        expect(words.length).toBe(5);
+    });
+    it('capitalizes first letter', () => {
+        const sentence = generateSentence(3);
+        expect(sentence[0]).toBe(sentence[0]?.toUpperCase());
+    });
+    it('ends with period', () => {
+        const sentence = generateSentence(3);
+        expect(sentence.endsWith('.')).toBe(true);
+    });
+    it('returns empty string for zero word count', () => {
+        const sentence = generateSentence(0);
+        expect(sentence).toBe('');
+    });
+    it('generates different sentences on multiple calls', () => {
+        const sentence1 = generateSentence(10);
+        const sentence2 = generateSentence(10);
+        // With 10 words, sentences should likely differ (not guaranteed but very likely)
+        expect(sentence1).toBeTruthy();
+        expect(sentence2).toBeTruthy();
+    });
+});
+describe('generateSentences', () => {
+    it('generates specified number of sentences', () => {
+        const sentences = generateSentences(3);
+        expect(sentences).toHaveLength(3);
+    });
+    it('generates sentences within length range', () => {
+        const sentences = generateSentences(5, 10, 4);
+        sentences.forEach(sentence => {
+            const wordCount = sentence.split(' ').length;
+            expect(wordCount).toBeGreaterThanOrEqual(4);
+            expect(wordCount).toBeLessThanOrEqual(10);
+        });
+    });
+    it('uses default max and min sentence length', () => {
+        const sentences = generateSentences(2);
+        expect(sentences).toHaveLength(2);
+        sentences.forEach(sentence => {
+            expect(sentence.endsWith('.')).toBe(true);
+        });
+    });
+});

package/agnostic/misc/normalize-extension/index.js

@@ -1,90 +1,101 @@
-// src/agnostic/misc/normalize-extension/index.ts
-var defaultAliases = {
-  // Images
-  jpeg: "jpg",
-  jpe: "jpg",
-  jfif: "jpg",
-  pjpeg: "jpg",
-  pjp: "jpg",
-  tiff: "tif",
-  svgz: "svg",
-  // Audio
-  m4a: "aac",
-  mp2: "mp3",
-  mpeg3: "mp3",
-  wave: "wav",
-  aif: "aiff",
-  aifc: "aiff",
-  opus: "ogg",
-  oga: "ogg",
-  // Video
-  m4v: "mp4",
-  mpe: "mpg",
-  mpeg: "mpg",
-  ogv: "webm",
-  mov: "qt",
-  m2ts: "ts",
-  tsx: "ts",
-  mkv: "webm",
-  // often used similarly
-  // Fonts
-  truetype: "ttf",
-  opentype: "otf",
-  svgfont: "svg",
-  eotfont: "eot",
-  // Web / Source Files
-  htm: "html",
-  xhtml: "html",
-  js: "javascript",
-  mjs: "js",
-  cjs: "js",
-  yml: "yaml",
-  text: "txt",
-  mdown: "md",
-  markdown: "md",
-  map: "json",
-  // Documents
-  doc: "docx",
-  xls: "xlsx",
-  ppt: "pptx",
-  rtf: "doc",
-  odt: "docx",
-  ods: "xlsx",
-  odp: "pptx",
-  // Archives
-  tgz: "tar.gz",
-  tbz: "tar.bz2",
-  tbz2: "tar.bz2",
-  txz: "tar.xz",
-  gz: "gzip",
-  bz2: "bzip2",
-  z: "zip",
-  // Code & Scripting
-  pyw: "py",
-  ipynb: "json",
-  "c++": "cpp",
-  "h++": "hpp",
-  cc: "cpp",
-  cxx: "cpp",
-  hxx: "hpp",
-  sh: "bash",
-  bashrc: "bash",
-  zshrc: "zsh",
-  ps1: "powershell",
-  // Configuration
-  env: "conf",
-  ini: "conf",
-  toml: "conf",
-  // Misc
-  plist: "xml",
-  xsl: "xml",
-  xslt: "xml",
-  svgx: "svg"
+/**
+ * Default mapping of file extensions to their canonical forms.
+ *
+ * Includes common image, audio, video, font, web, document, archive,
+ * code, configuration, and miscellaneous file extensions.
+ */
+const defaultAliases = {
+    // Images
+    jpeg: 'jpg',
+    jpe: 'jpg',
+    jfif: 'jpg',
+    pjpeg: 'jpg',
+    pjp: 'jpg',
+    tiff: 'tif',
+    svgz: 'svg',
+    // Audio
+    m4a: 'aac',
+    mp2: 'mp3',
+    mpeg3: 'mp3',
+    wave: 'wav',
+    aif: 'aiff',
+    aifc: 'aiff',
+    opus: 'ogg',
+    oga: 'ogg',
+    // Video
+    m4v: 'mp4',
+    mpe: 'mpg',
+    mpeg: 'mpg',
+    ogv: 'webm',
+    mov: 'qt',
+    m2ts: 'ts',
+    tsx: 'ts',
+    mkv: 'webm', // often used similarly
+    // Fonts
+    truetype: 'ttf',
+    opentype: 'otf',
+    svgfont: 'svg',
+    eotfont: 'eot',
+    // Web / Source Files
+    htm: 'html',
+    xhtml: 'html',
+    js: 'javascript',
+    mjs: 'js',
+    cjs: 'js',
+    yml: 'yaml',
+    text: 'txt',
+    mdown: 'md',
+    markdown: 'md',
+    map: 'json',
+    // Documents
+    doc: 'docx',
+    xls: 'xlsx',
+    ppt: 'pptx',
+    rtf: 'doc',
+    odt: 'docx',
+    ods: 'xlsx',
+    odp: 'pptx',
+    // Archives
+    tgz: 'tar.gz',
+    tbz: 'tar.bz2',
+    tbz2: 'tar.bz2',
+    txz: 'tar.xz',
+    gz: 'gzip',
+    bz2: 'bzip2',
+    z: 'zip',
+    // Code & Scripting
+    pyw: 'py',
+    ipynb: 'json',
+    'c++': 'cpp',
+    'h++': 'hpp',
+    cc: 'cpp',
+    cxx: 'cpp',
+    hxx: 'hpp',
+    sh: 'bash',
+    bashrc: 'bash',
+    zshrc: 'zsh',
+    ps1: 'powershell',
+    // Configuration
+    env: 'conf',
+    ini: 'conf',
+    toml: 'conf',
+    // Misc
+    plist: 'xml',
+    xsl: 'xml',
+    xslt: 'xml',
+    svgx: 'svg'
 };
-function normalizeExtension(extWithoutDot, aliasesWithoutDot = defaultAliases) {
-  const cleaned = extWithoutDot.toLowerCase().replace(/^\./, "");
-  return aliasesWithoutDot[cleaned] ?? cleaned;
+/**
+ * Normalizes a file extension to its canonical form, using an optional alias map.
+ *
+ * Converts the extension to lowercase, removes a leading dot if present,
+ * and applies alias mapping if defined.
+ *
+ * @param {string} extWithoutDot - File extension to normalize (may include or omit leading dot).
+ * @param {Record<string, string>} [aliasesWithoutDot=defaultAliases] - Optional mapping of aliases to canonical extensions.
+ * @returns {string} The normalized file extension, without leading dot.
+ */
+export function normalizeExtension(extWithoutDot, aliasesWithoutDot = defaultAliases) {
+    const cleaned = extWithoutDot.toLowerCase().replace(/^\./, '');
+    return aliasesWithoutDot[cleaned] ?? cleaned;
 }
-export {
-  normalizeExtension
-};

package/agnostic/misc/normalize-extension/index.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { normalizeExtension } from './index.js';
+describe('normalizeExtension', () => {
+    it('removes leading dot', () => {
+        expect(normalizeExtension('.jpg')).toBe('jpg');
+        expect(normalizeExtension('.png')).toBe('png');
+    });
+    it('converts to lowercase', () => {
+        expect(normalizeExtension('JPG')).toBe('jpg');
+        expect(normalizeExtension('PNG')).toBe('png');
+    });
+    it('normalizes image extensions', () => {
+        expect(normalizeExtension('jpeg')).toBe('jpg');
+        expect(normalizeExtension('tiff')).toBe('tif');
+    });
+    it('normalizes audio extensions', () => {
+        expect(normalizeExtension('m4a')).toBe('aac');
+        expect(normalizeExtension('wave')).toBe('wav');
+    });
+    it('normalizes video extensions', () => {
+        expect(normalizeExtension('m4v')).toBe('mp4');
+        expect(normalizeExtension('mpeg')).toBe('mpg');
+    });
+    it('normalizes web extensions', () => {
+        expect(normalizeExtension('htm')).toBe('html');
+        expect(normalizeExtension('yml')).toBe('yaml');
+    });
+    it('normalizes document extensions', () => {
+        expect(normalizeExtension('doc')).toBe('docx');
+        expect(normalizeExtension('xls')).toBe('xlsx');
+    });
+    it('returns extension as-is if no alias exists', () => {
+        expect(normalizeExtension('xyz')).toBe('xyz');
+        expect(normalizeExtension('unknown')).toBe('unknown');
+    });
+    it('accepts custom aliases', () => {
+        const customAliases = { 'custom': 'standard' };
+        expect(normalizeExtension('custom', customAliases)).toBe('standard');
+    });
+});

package/agnostic/misc/outcome/index.js

@@ -1,15 +1,21 @@
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
+/**
+ * Creates a success outcome with the given payload.
+ *
+ * @template Payload
+ * @param {Payload} payload - The success value.
+ * @returns {Success<Payload>} A success outcome object.
+ */
+export function makeSuccess(payload) { return { success: true, payload }; }
+/**
+ * Creates a failure outcome with the given error.
+ *
+ * @template Error
+ * @param {Error} error - The error value.
+ * @returns {Failure<Error>} A failure outcome object.
+ */
+export function makeFailure(error) { return { success: false, error }; }
+export function make(success, payloadOrError) {
+    return success
+        ? makeSuccess(payloadOrError)
+        : makeFailure(payloadOrError);
 }
-function makeFailure(error) {
-  return { success: false, error };
-}
-function make(success, payloadOrError) {
-  return success ? makeSuccess(payloadOrError) : makeFailure(payloadOrError);
-}
-export {
-  make,
-  makeFailure,
-  makeSuccess
-};

package/agnostic/misc/outcome/index.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { makeSuccess, makeFailure, make } from './index.js';
+describe('makeSuccess', () => {
+    it('creates success outcome with payload', () => {
+        const result = makeSuccess('test');
+        expect(result.success).toBe(true);
+        expect(result.payload).toBe('test');
+    });
+    it('creates success with object payload', () => {
+        const payload = { a: 1, b: 2 };
+        const result = makeSuccess(payload);
+        expect(result.success).toBe(true);
+        expect(result.payload).toEqual(payload);
+    });
+});
+describe('makeFailure', () => {
+    it('creates failure outcome with error', () => {
+        const result = makeFailure('error message');
+        expect(result.success).toBe(false);
+        expect(result.error).toBe('error message');
+    });
+    it('creates failure with Error object', () => {
+        const error = new Error('test error');
+        const result = makeFailure(error);
+        expect(result.success).toBe(false);
+        expect(result.error).toBe(error);
+    });
+});
+describe('make', () => {
+    it('creates success when first argument is true', () => {
+        const result = make(true, 'payload');
+        expect(result.success).toBe(true);
+        expect(result.payload).toBe('payload');
+    });
+    it('creates failure when first argument is false', () => {
+        const result = make(false, 'error');
+        expect(result.success).toBe(false);
+        expect(result.error).toBe('error');
+    });
+});

package/agnostic/numbers/absolute-modulo/index.js

@@ -1,7 +1,10 @@
-// src/agnostic/numbers/absolute-modulo/index.ts
-function absoluteModulo(nbr, modulo) {
-  return (nbr % modulo + modulo) % modulo;
+/**
+ * Computes the modulo of a number, always returning a non-negative result.
+ *
+ * @param {number} nbr - The number to modulo.
+ * @param {number} modulo - The modulus.
+ * @returns {number} The non-negative remainder of `nbr` modulo `modulo`.
+ */
+export function absoluteModulo(nbr, modulo) {
+    return ((nbr % modulo) + modulo) % modulo;
 }
-export {
-  absoluteModulo
-};

package/agnostic/numbers/absolute-modulo/index.test.js

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { absoluteModulo } from './index.js';
+describe('absoluteModulo', () => {
+    it('returns non-negative result for positive numbers', () => {
+        expect(absoluteModulo(10, 3)).toBe(1);
+        expect(absoluteModulo(5, 2)).toBe(1);
+    });
+    it('returns non-negative result for negative numbers', () => {
+        expect(absoluteModulo(-10, 3)).toBe(2);
+        expect(absoluteModulo(-5, 2)).toBe(1);
+    });
+    it('handles zero', () => {
+        expect(absoluteModulo(0, 5)).toBe(0);
+    });
+    it('handles numbers larger than modulo', () => {
+        expect(absoluteModulo(15, 10)).toBe(5);
+        expect(absoluteModulo(25, 10)).toBe(5);
+    });
+    it('handles numbers smaller than negative modulo', () => {
+        expect(absoluteModulo(-15, 10)).toBe(5);
+        expect(absoluteModulo(-25, 10)).toBe(5);
+    });
+});