@design-edito/tools 0.4.5 → 0.4.11

package/agnostic/objects/record-map/index.test.js

@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest';
+import { recordMap } from './index.js';
+describe('recordMap', () => {
+    it('maps values using the mapper function', () => {
+        const record = { a: 1, b: 2, c: 3 };
+        const result = recordMap(record, val => val * 2);
+        expect(result).toEqual({ a: 2, b: 4, c: 6 });
+    });
+    it('preserves keys while transforming values', () => {
+        const record = { x: 'hello', y: 'world' };
+        const result = recordMap(record, val => val.toUpperCase());
+        expect(result).toEqual({ x: 'HELLO', y: 'WORLD' });
+    });
+    it('provides both value and key to mapper function', () => {
+        const record = { a: 1, b: 2 };
+        const result = recordMap(record, (val, key) => `${key}:${val}`);
+        expect(result).toEqual({ a: 'a:1', b: 'b:2' });
+    });
+    it('handles empty records', () => {
+        const record = {};
+        const result = recordMap(record, val => val);
+        expect(result).toEqual({});
+    });
+    it('handles records with different value types', () => {
+        const record = { num: 5, str: 'test', bool: true };
+        const result = recordMap(record, val => String(val));
+        expect(result).toEqual({ num: '5', str: 'test', bool: 'true' });
+    });
+    it('handles mapper that changes value type', () => {
+        const record = { a: 1, b: 2, c: 3 };
+        const result = recordMap(record, val => val > 2);
+        expect(result).toEqual({ a: false, b: false, c: true });
+    });
+    it('handles mapper that returns objects', () => {
+        const record = { a: 1, b: 2 };
+        const result = recordMap(record, val => ({ value: val }));
+        expect(result).toEqual({ a: { value: 1 }, b: { value: 2 } });
+    });
+    it('handles mapper that returns arrays', () => {
+        const record = { a: 1, b: 2 };
+        const result = recordMap(record, val => [val, val * 2]);
+        expect(result).toEqual({ a: [1, 2], b: [2, 4] });
+    });
+    it('only processes own properties', () => {
+        const parent = { inherited: 'value' };
+        const record = Object.create(parent);
+        record.own = 'ownValue';
+        const result = recordMap(record, val => val.toUpperCase());
+        expect(result).toEqual({ own: 'OWNVALUE' });
+    });
+    it('handles numeric string keys', () => {
+        const record = { '0': 'zero', '1': 'one', '2': 'two' };
+        const result = recordMap(record, val => val.toUpperCase());
+        expect(result).toEqual({ '0': 'ZERO', '1': 'ONE', '2': 'TWO' });
+    });
+});

package/agnostic/objects/sort-keys/index.js

@@ -1,12 +1,16 @@
-// src/agnostic/objects/sort-keys/index.ts
-function sortKeys(obj, sorter = (a, b) => String(a).localeCompare(String(b))) {
-  const out = {};
-  const keys = Object.keys(obj);
-  for (const key of keys.sort(sorter)) {
-    out[key] = obj[key];
-  }
-  return out;
+/**
+ * Returns a new object with the keys sorted according to the provided sorter.
+ *
+ * @template T - The type of the input object.
+ * @param {T} obj - The object whose keys should be sorted.
+ * @param {(a: keyof T, b: keyof T) => number} [sorter] - Optional function used to compare keys for sorting. Defaults to alphabetical order.
+ * @returns {{ [K in keyof T]: T[K] }} A new object with the same keys and values as the input, but sorted by key.
+ */
+export function sortKeys(obj, sorter = (a, b) => String(a).localeCompare(String(b))) {
+    const out = {};
+    const keys = Object.keys(obj);
+    for (const key of keys.sort(sorter)) {
+        out[key] = obj[key];
+    }
+    return out;
 }
-export {
-  sortKeys
-};

package/agnostic/objects/sort-keys/index.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+import { sortKeys } from './index.js';
+describe('sortKeys', () => {
+    it('returns a new object with keys sorted alphabetically by default', () => {
+        const inp = { b: 2, a: 1, c: 3 };
+        const out = sortKeys(inp);
+        expect(Object.keys(out)).toEqual(['a', 'b', 'c']);
+        expect(out).toEqual({ a: 1, b: 2, c: 3 });
+    });
+    it('preserves the value types for each key', () => {
+        const inp = { b: 'str', a: 42 };
+        const out = sortKeys(inp, (a, b) => a.localeCompare(b));
+        expect(out.a).toBe(42);
+        expect(out.b).toBe('str');
+    });
+    it('does not modify the original object', () => {
+        const inp = { b: 2, a: 1 };
+        const copy = { ...inp };
+        sortKeys(inp, (a, b) => a.localeCompare(b));
+        expect(inp).toEqual(copy);
+    });
+    it('works with custom sorter', () => {
+        const inp = { a: 1, b: 2, c: 3 };
+        const out = sortKeys(inp, (a, b) => b.localeCompare(a)); // reverse
+        expect(Object.keys(out)).toEqual(['c', 'b', 'a']);
+    });
+    it('works with single-key objects', () => {
+        const inp = { only: 1 };
+        const out = sortKeys(inp, (a, b) => a.localeCompare(b));
+        expect(out).toEqual({ only: 1 });
+    });
+    it('works with empty objects', () => {
+        const inp = {};
+        const out = sortKeys(inp, (a, b) => a.localeCompare(b));
+        expect(out).toEqual({});
+    });
+});

package/agnostic/objects/validation/index.js

@@ -1,9 +1,22 @@
-// src/agnostic/objects/validation/index.ts
-function fromPartial(obj, partial) {
-  return Object.entries(partial).every(([key, val]) => {
-    return obj[key] === val;
-  });
+// [WIP]
+// Has all keys from
+// Has extra keys from
+// Has same keys from
+// Has equal properties than (maybe option for not just shallow equivalence?)
+// Has extra properties than
+// Has same properties than
+/**
+ * Checks if an object contains all the key-value pairs from a partial object.
+ *
+ * Performs a shallow equality check for each property in `partial`.
+ *
+ * @template T - The type of the full object.
+ * @param {T} obj - The object to validate.
+ * @param {Partial<T>} partial - The partial object with key-value pairs to check.
+ * @returns {boolean} `true` if all entries in `partial` match those in `obj`, otherwise `false`.
+ */
+export function fromPartial(obj, partial) {
+    return Object.entries(partial).every(([key, val]) => {
+        return obj[key] === val;
+    });
 }
-export {
-  fromPartial
-};

package/agnostic/objects/validation/index.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { fromPartial } from './index.js';
+describe('fromPartial', () => {
+    it('returns true when all partial entries match', () => {
+        const obj = { a: 1, b: 2, c: 3 };
+        const partial = { a: 1, b: 2 };
+        expect(fromPartial(obj, partial)).toBe(true);
+    });
+    it('returns true when partial is empty', () => {
+        const obj = { a: 1, b: 2 };
+        const partial = {};
+        expect(fromPartial(obj, partial)).toBe(true);
+    });
+    it('returns false when any partial entry does not match', () => {
+        const obj = { a: 1, b: 2, c: 3 };
+        const partial = { a: 1, b: 3 };
+        expect(fromPartial(obj, partial)).toBe(false);
+    });
+    it('returns false when partial has key not in object', () => {
+        const obj = { a: 1, b: 2 };
+        const partial = { a: 1, c: 3 };
+        expect(fromPartial(obj, partial)).toBe(false);
+    });
+    it('handles string values', () => {
+        const obj = { name: 'John', age: 30 };
+        const partial = { name: 'John' };
+        expect(fromPartial(obj, partial)).toBe(true);
+    });
+    it('handles boolean values', () => {
+        const obj = { active: true, verified: false };
+        const partial = { active: true };
+        expect(fromPartial(obj, partial)).toBe(true);
+    });
+    it('handles null values', () => {
+        const obj = { a: null, b: 2 };
+        const partial = { a: null };
+        expect(fromPartial(obj, partial)).toBe(true);
+    });
+    it('handles undefined values', () => {
+        const obj = { a: undefined, b: 2 };
+        const partial = { a: undefined };
+        expect(fromPartial(obj, partial)).toBe(true);
+    });
+    it('performs shallow equality check', () => {
+        const obj = { nested: { a: 1 } };
+        const partial = { nested: { a: 1 } };
+        // Shallow check: objects are compared by reference
+        expect(fromPartial(obj, partial)).toBe(false);
+    });
+    it('handles arrays with shallow equality', () => {
+        const obj = { items: [1, 2, 3] };
+        const partial = { items: [1, 2, 3] };
+        // Shallow check: arrays are compared by reference
+        expect(fromPartial(obj, partial)).toBe(false);
+    });
+    it('handles arrays with same reference', () => {
+        const items = [1, 2, 3];
+        const obj = { items };
+        const partial = { items };
+        expect(fromPartial(obj, partial)).toBe(true);
+    });
+    it('handles multiple matching entries', () => {
+        const obj = { a: 1, b: 2, c: 3, d: 4, e: 5 };
+        const partial = { a: 1, c: 3, e: 5 };
+        expect(fromPartial(obj, partial)).toBe(true);
+    });
+    it('handles objects with no matching entries', () => {
+        const obj = { a: 1, b: 2 };
+        const partial = { a: 2, b: 1 };
+        expect(fromPartial(obj, partial)).toBe(false);
+    });
+});

package/agnostic/optim/memoize/index.js

@@ -1,17 +1,25 @@
-// src/agnostic/optim/memoize/index.ts
-function memoize(toMemoizeFunc) {
-  let cachedArgs;
-  let cachedResult;
-  const memoizedFunc = (...args) => {
-    const argsMatch = cachedArgs !== void 0 && args.length === cachedArgs.length && args.every((arg, i) => arg === cachedArgs?.[i]);
-    if (argsMatch && cachedResult !== void 0) return cachedResult.value;
-    const result = toMemoizeFunc(...args);
-    cachedArgs = args;
-    cachedResult = { value: result };
-    return result;
-  };
-  return memoizedFunc;
+/**
+ * Creates a memoized version of a function, caching the result for repeated calls with the same arguments.
+ *
+ * Only performs shallow equality checks on arguments (strict equality `===`).
+ *
+ * @template T - The type of the function to memoize.
+ * @param {T} toMemoizeFunc - The function to memoize.
+ * @returns {T} A memoized version of the input function.
+ */
+export function memoize(toMemoizeFunc) {
+    let cachedArgs;
+    let cachedResult;
+    const memoizedFunc = (...args) => {
+        const argsMatch = cachedArgs !== undefined
+            && args.length === cachedArgs.length
+            && args.every((arg, i) => arg === cachedArgs?.[i]);
+        if (argsMatch && cachedResult !== undefined)
+            return cachedResult.value;
+        const result = toMemoizeFunc(...args);
+        cachedArgs = args;
+        cachedResult = { value: result };
+        return result;
+    };
+    return memoizedFunc;
 }
-export {
-  memoize
-};

package/agnostic/optim/memoize/index.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { memoize } from './index.js';
+describe('memoize', () => {
+    it('returns the same result for identical arguments without re-calling the wrapped function', () => {
+        let callCount = 0;
+        const fn = (...args) => {
+            callCount += 1;
+            return args.reduce((sum, n) => sum + n, 0);
+        };
+        const mem = memoize(fn);
+        const r1 = mem(1, 2, 3);
+        const r2 = mem(1, 2, 3);
+        expect(r1).toBe(6);
+        expect(r2).toBe(6);
+        expect(callCount).toBe(1);
+    });
+    it('recomputes when arguments change (shallow equality)', () => {
+        let callCount = 0;
+        const fn = (obj) => {
+            callCount += 1;
+            return obj.v * 2;
+        };
+        const mem = memoize(fn);
+        const r1 = mem({ v: 2 });
+        const r2 = mem({ v: 2 });
+        expect(r1).toBe(4);
+        expect(r2).toBe(4);
+        expect(callCount).toBe(2);
+    });
+});

package/agnostic/optim/throttle-debounce/index.js

@@ -1,112 +1,130 @@
-// src/agnostic/optim/throttle-debounce/index.ts
-function throttle(toThrottleFunc, delayMs) {
-  let currentDelayMs = delayMs;
-  let lastArgs = [];
-  let lastExecutedOn = 0;
-  let lastReturnValue;
-  let nextExecutionTimeout = null;
-  function scheduleNextCall() {
-    if (nextExecutionTimeout !== null) {
-      clearTimeout(nextExecutionTimeout);
-      nextExecutionTimeout = null;
+/**
+ * Returns a throttled version of the function passed as an argument
+ * @param toThrottleFunc - The function that has to be throttled
+ * @param delayMs - The throttle delay in ms
+ */
+export function throttle(toThrottleFunc, delayMs) {
+    let currentDelayMs = delayMs;
+    let lastArgs = [];
+    let lastExecutedOn = 0;
+    let lastReturnValue;
+    let nextExecutionTimeout = null;
+    /** Schedules a next call according to the delay */
+    function scheduleNextCall() {
+        if (nextExecutionTimeout !== null) {
+            clearTimeout(nextExecutionTimeout);
+            nextExecutionTimeout = null;
+        }
+        const now = Date.now();
+        const nextExecutionTimestamp = lastExecutedOn + currentDelayMs;
+        const msTillNextExecution = nextExecutionTimestamp - now;
+        nextExecutionTimeout = setTimeout(() => {
+            nextExecutionTimeout = null;
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            const returnValue = toThrottleFunc(...lastArgs);
+            lastReturnValue = returnValue;
+            lastExecutedOn = now;
+        }, msTillNextExecution) ?? null;
     }
-    const now = Date.now();
-    const nextExecutionTimestamp = lastExecutedOn + currentDelayMs;
-    const msTillNextExecution = nextExecutionTimestamp - now;
-    nextExecutionTimeout = setTimeout(() => {
-      nextExecutionTimeout = null;
-      const returnValue = toThrottleFunc(...lastArgs);
-      lastReturnValue = returnValue;
-      lastExecutedOn = now;
-    }, msTillNextExecution) ?? null;
-  }
-  function throttled(...args) {
-    const now = Date.now();
-    lastArgs = args;
-    if (now - lastExecutedOn >= delayMs) {
-      const returnValue = toThrottleFunc(...lastArgs);
-      lastReturnValue = returnValue;
-      lastExecutedOn = now;
-      return {
-        returnValue: lastReturnValue,
-        lastExecutedOn,
-        delayMs: currentDelayMs,
-        isCached: false
-      };
+    /** The throttled function */
+    function throttled(...args) {
+        const now = Date.now();
+        lastArgs = args;
+        if (now - lastExecutedOn >= delayMs) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            const returnValue = toThrottleFunc(...lastArgs);
+            lastReturnValue = returnValue;
+            lastExecutedOn = now;
+            return {
+                returnValue: lastReturnValue,
+                lastExecutedOn,
+                delayMs: currentDelayMs,
+                isCached: false
+            };
+        }
+        if (nextExecutionTimeout === null)
+            scheduleNextCall();
+        return {
+            returnValue: lastReturnValue,
+            lastExecutedOn,
+            delayMs: currentDelayMs,
+            isCached: true
+        };
+    }
+    /** Changes the throttle delay */
+    function setDelay(delayMs) {
+        currentDelayMs = delayMs;
+        if (nextExecutionTimeout !== null)
+            scheduleNextCall();
     }
-    if (nextExecutionTimeout === null) scheduleNextCall();
     return {
-      returnValue: lastReturnValue,
-      lastExecutedOn,
-      delayMs: currentDelayMs,
-      isCached: true
+        throttled,
+        setDelay
     };
-  }
-  function setDelay(delayMs2) {
-    currentDelayMs = delayMs2;
-    if (nextExecutionTimeout !== null) scheduleNextCall();
-  }
-  return {
-    throttled,
-    setDelay
-  };
 }
-function debounce(toDebounceFunc, delayMs) {
-  let currentDelayMs = delayMs;
-  let lastArgs = [];
-  let lastCalledOn = 0;
-  let lastExecutedOn = 0;
-  let lastReturnValue;
-  let nextExecutionTimeout = null;
-  function scheduleNextCall() {
-    if (nextExecutionTimeout !== null) {
-      clearTimeout(nextExecutionTimeout);
-      nextExecutionTimeout = null;
+/**
+ * Returns a debounced version of the function passed as an argument
+ * @param toDebounceFunc - The function that has to be debounced
+ * @param delayMs - The debounce delay in ms
+ */
+export function debounce(toDebounceFunc, delayMs) {
+    let currentDelayMs = delayMs;
+    let lastArgs = [];
+    let lastCalledOn = 0;
+    let lastExecutedOn = 0;
+    let lastReturnValue;
+    let nextExecutionTimeout = null;
+    /** Schedules a next call according to the delay */
+    function scheduleNextCall() {
+        if (nextExecutionTimeout !== null) {
+            clearTimeout(nextExecutionTimeout);
+            nextExecutionTimeout = null;
+        }
+        const now = Date.now();
+        const nextExecutionTimestamp = lastCalledOn + currentDelayMs;
+        const msTillNextExecution = nextExecutionTimestamp - now;
+        nextExecutionTimeout = setTimeout(() => {
+            nextExecutionTimeout = null;
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            const returnValue = toDebounceFunc(...lastArgs);
+            lastReturnValue = returnValue;
+            lastExecutedOn = now;
+        }, msTillNextExecution) ?? null;
+    }
+    /** The debounced function */
+    function debounced(...args) {
+        const now = Date.now();
+        lastArgs = args;
+        if (now - lastCalledOn >= currentDelayMs) {
+            lastCalledOn = now;
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            const returnValue = toDebounceFunc(...lastArgs);
+            lastReturnValue = returnValue;
+            lastExecutedOn = now;
+            return {
+                returnValue: lastReturnValue,
+                lastExecutedOn,
+                delayMs: currentDelayMs,
+                isCached: false
+            };
+        }
+        lastCalledOn = now;
+        scheduleNextCall();
+        return {
+            returnValue: lastReturnValue,
+            lastExecutedOn,
+            delayMs: currentDelayMs,
+            isCached: true
+        };
     }
-    const now = Date.now();
-    const nextExecutionTimestamp = lastCalledOn + currentDelayMs;
-    const msTillNextExecution = nextExecutionTimestamp - now;
-    nextExecutionTimeout = setTimeout(() => {
-      nextExecutionTimeout = null;
-      const returnValue = toDebounceFunc(...lastArgs);
-      lastReturnValue = returnValue;
-      lastExecutedOn = now;
-    }, msTillNextExecution) ?? null;
-  }
-  function debounced(...args) {
-    const now = Date.now();
-    lastArgs = args;
-    if (now - lastCalledOn >= currentDelayMs) {
-      lastCalledOn = now;
-      const returnValue = toDebounceFunc(...lastArgs);
-      lastReturnValue = returnValue;
-      lastExecutedOn = now;
-      return {
-        returnValue: lastReturnValue,
-        lastExecutedOn,
-        delayMs: currentDelayMs,
-        isCached: false
-      };
+    /** Changes the debounce delay */
+    function setDelay(delayMs) {
+        currentDelayMs = delayMs;
+        if (nextExecutionTimeout !== null)
+            scheduleNextCall();
     }
-    lastCalledOn = now;
-    scheduleNextCall();
     return {
-      returnValue: lastReturnValue,
-      lastExecutedOn,
-      delayMs: currentDelayMs,
-      isCached: true
+        debounced,
+        setDelay
     };
-  }
-  function setDelay(delayMs2) {
-    currentDelayMs = delayMs2;
-    if (nextExecutionTimeout !== null) scheduleNextCall();
-  }
-  return {
-    debounced,
-    setDelay
-  };
 }
-export {
-  debounce,
-  throttle
-};

package/agnostic/optim/throttle-debounce/index.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect, vi } from 'vitest';
+import { throttle, debounce } from './index.js';
+describe('throttle', () => {
+    it('calls the wrapped function immediately and then throttles subsequent calls', async () => {
+        vi.useFakeTimers();
+        const fn = vi.fn((x) => x * 2);
+        const { throttled } = throttle(fn, 100);
+        const first = throttled(1);
+        const second = throttled(2);
+        expect(first.isCached).toBe(false);
+        expect(first.returnValue).toBe(2);
+        expect(second.isCached).toBe(true);
+        expect(fn).toHaveBeenCalledTimes(1);
+        // Fast-forward past the throttle delay to trigger the scheduled call
+        vi.advanceTimersByTime(100);
+        expect(fn).toHaveBeenCalledTimes(2);
+        vi.useRealTimers();
+    });
+});
+describe('debounce', () => {
+    it('fires immediately on first call, then debounces subsequent calls and uses latest arguments', async () => {
+        vi.useFakeTimers();
+        const fn = vi.fn((x) => x * 3);
+        const { debounced } = debounce(fn, 100);
+        // First call executes immediately (leading edge)
+        debounced(1);
+        expect(fn).toHaveBeenCalledTimes(1);
+        expect(fn).toHaveBeenLastCalledWith(1);
+        // Subsequent rapid calls within the debounce window are deferred
+        debounced(2);
+        debounced(3);
+        expect(fn).toHaveBeenCalledTimes(1);
+        // After the delay, the deferred call should run once with the latest args
+        vi.advanceTimersByTime(100);
+        expect(fn).toHaveBeenCalledTimes(2);
+        expect(fn).toHaveBeenLastCalledWith(3);
+        // After an inactivity window, a new call should again execute immediately
+        vi.advanceTimersByTime(200);
+        debounced(4);
+        expect(fn).toHaveBeenCalledTimes(3);
+        expect(fn).toHaveBeenLastCalledWith(4);
+        vi.useRealTimers();
+    });
+});

package/agnostic/optim/throttle-debounce/types.js

@@ -0,0 +1 @@
+export {};

package/agnostic/random/hex-char/index.js

@@ -1,11 +1,9 @@
-// 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;
+/** List of hex chars (0-9a-f) */
+export const hexChars = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'];
+/** Generates a random hexadecimal char (0-9a-f) */
+export function randomHexChar() {
+    const nbr = Math.floor(Math.random() * 16);
+    const char = hexChars[nbr];
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    return char;
 }
-export {
-  hexChars,
-  randomHexChar
-};

package/agnostic/random/hex-char/index.test.js

@@ -0,0 +1,20 @@
+import { describe, it, expect } from 'vitest';
+import { hexChars, randomHexChar } from './index.js';
+describe('hexChars', () => {
+    it('contains 16 hexadecimal characters', () => {
+        expect(hexChars.length).toBe(16);
+        expect(hexChars[0]).toBe('0');
+        expect(hexChars[15]).toBe('f');
+    });
+});
+describe('randomHexChar', () => {
+    it('returns a single hexadecimal character from hexChars', () => {
+        const char = randomHexChar();
+        expect(char.length).toBe(1);
+        expect(hexChars.includes(char)).toBe(true);
+    });
+    it('always returns characters from the allowed set over multiple calls', () => {
+        const results = Array.from({ length: 32 }, () => randomHexChar());
+        expect(results.every(c => hexChars.includes(c))).toBe(true);
+    });
+});

package/agnostic/random/index.d.ts

@@ -1,3 +1,3 @@
+export * as random from './random/index.js'
 export * as hexChar from './hex-char/index.js'
 export * as uuid from './uuid/index.js'
-export * as random from './random/index.js'

package/agnostic/random/index.js

@@ -1,3 +1,3 @@
+export * as random from './random/index.js'
 export * as hexChar from './hex-char/index.js'
 export * as uuid from './uuid/index.js'
-export * as random from './random/index.js'