@vpmedia/simplify 1.54.0 → 1.55.0

package/src/util/object.test.js

@@ -0,0 +1,205 @@
+import { getObjValueByPath, setObjValueByPath, purgeObject, deepMerge } from './object.js';
+
+describe('deepMerge', () => {
+  test('should override deep properties correctly', () => {
+    const defaultObj = { a: { b: 1, c: 2 }, d: 3 };
+    const overrideObj = { a: { b: 42 } };
+    const expectedResult = { a: { b: 42, c: 2 }, d: 3 };
+
+    expect(deepMerge({ ...defaultObj }, overrideObj)).toEqual(expectedResult);
+  });
+
+  test('should not modify the original target object', () => {
+    const target = { x: { y: 10 } };
+    const source = { x: { y: 20 } };
+    const copy = { ...target };
+
+    deepMerge(target, source);
+    expect(target).toEqual(copy);
+  });
+
+  test('should handle non-object values correctly', () => {
+    expect(deepMerge(null, { a: 1 })).toEqual({ a: 1 });
+    expect(deepMerge({ a: 1 }, null)).toEqual({ a: 1 });
+  });
+
+  test('should handle arrays correctly', () => {
+    const target = { arr: [1, 2] };
+    const source = { arr: [3, 4] };
+
+    expect(deepMerge(target, source)).toEqual({ arr: [3, 4] });
+  });
+
+  test('should handle nested arrays correctly', () => {
+    const target = { obj: { arr: [1, 2] } };
+    const source = { obj: { arr: [3, 4] } };
+
+    expect(deepMerge(target, source)).toEqual({ obj: { arr: [3, 4] } });
+  });
+
+  test('should handle string values', () => {
+    const target = { str: 'hello' };
+    const source = { str: 'world' };
+
+    expect(deepMerge(target, source)).toEqual({ str: 'world' });
+  });
+
+  test('should handle number values', () => {
+    const target = { num: 42 };
+    const source = { num: 100 };
+
+    expect(deepMerge(target, source)).toEqual({ num: 100 });
+  });
+
+  test('should handle boolean values', () => {
+    const target = { bool: true };
+    const source = { bool: false };
+
+    expect(deepMerge(target, source)).toEqual({ bool: false });
+  });
+
+  test('should handle undefined values', () => {
+    const target = { undef: undefined };
+    const source = { undef: 'value' };
+
+    expect(deepMerge(target, source)).toEqual({ undef: 'value' });
+  });
+
+  test('should handle null values', () => {
+    const target = { nullVal: null };
+    const source = { nullVal: 'value' };
+
+    expect(deepMerge(target, source)).toEqual({ nullVal: 'value' });
+  });
+
+  test('should handle mixed property types', () => {
+    const target = {
+      str: 'hello',
+      num: 42,
+      arr: [1, 2],
+      obj: { nested: 'value' },
+    };
+    const source = {
+      str: 'world',
+      num: 100,
+      arr: [3, 4],
+      obj: { nested: 'newValue' },
+    };
+
+    expect(deepMerge(target, source)).toEqual({
+      str: 'world',
+      num: 100,
+      arr: [3, 4],
+      obj: { nested: 'newValue' },
+    });
+  });
+
+  test('should handle constructor and __proto__ protection', () => {
+    const target = { a: 1 };
+    const source = { b: 2 };
+
+    expect(deepMerge(target, source)).toEqual({ a: 1, b: 2 });
+  });
+});
+
+test('Purges object of null and undefined values', () => {
+  const a = { k: 'v' };
+  expect(a.k).toBe('v');
+  purgeObject(a);
+  expect(a.k).toBe(null);
+});
+
+describe('getObjValueByPath', () => {
+  test('Gets object value by path', () => {
+    const source = { a: { b: { c: 'd' } } };
+    expect(getObjValueByPath(source, 'a.b.c')).toBe('d');
+  });
+
+  test('Returns null when object is null or undefined', () => {
+    expect(getObjValueByPath(null, 'a.b.c')).toBeNull();
+    expect(getObjValueByPath(undefined, 'a.b.c')).toBeNull();
+  });
+
+  test('Returns null when path is empty or null', () => {
+    expect(getObjValueByPath({ a: 'b' }, '')).toBeNull();
+    expect(getObjValueByPath({ a: 'b' }, null)).toBeNull();
+  });
+
+  test('Returns null when property does not exist', () => {
+    const source = { a: { b: 'c' } };
+    expect(getObjValueByPath(source, 'a.b.c')).toBeNull();
+  });
+
+  test('Returns null when property is undefined', () => {
+    const source = { a: { b: undefined } };
+    expect(getObjValueByPath(source, 'a.b')).toBeNull();
+  });
+
+  test('Handles single-level paths correctly', () => {
+    const source = { a: 'value' };
+    expect(getObjValueByPath(source, 'a')).toBe('value');
+  });
+
+  test('Handles nested paths correctly', () => {
+    const source = {
+      level1: {
+        level2: {
+          level3: 'deepValue',
+        },
+      },
+    };
+    expect(getObjValueByPath(source, 'level1.level2.level3')).toBe('deepValue');
+  });
+
+  test('Handles arrays in paths', () => {
+    const source = {
+      items: [{ name: 'item1' }, { name: 'item2' }],
+    };
+    expect(getObjValueByPath(source, 'items.0.name')).toBe('item1');
+  });
+});
+
+describe('setObjValueByPath', () => {
+  test('Sets object value by path', () => {
+    const source = { a: { b: { c: 'd' } } };
+    expect(getObjValueByPath(source, 'a.b.c')).toBe('d');
+    setObjValueByPath(source, 'a.b.c', 'newValue');
+    expect(getObjValueByPath(source, 'a.b.c')).toBe('newValue');
+  });
+
+  test('Handles null or undefined object', () => {
+    // Should not throw error
+    setObjValueByPath(null, 'a.b.c', 'value');
+    setObjValueByPath(undefined, 'a.b.c', 'value');
+  });
+
+  test('Handles null or undefined path', () => {
+    const source = { a: 'b' };
+    // Should not throw error
+    setObjValueByPath(source, null, 'value');
+    setObjValueByPath(source, undefined, 'value');
+  });
+
+  test('Sets value at root level', () => {
+    const source = { a: 'oldValue' };
+    setObjValueByPath(source, 'a', 'newValue');
+    expect(source.a).toBe('newValue');
+  });
+
+  test('Creates new nested properties', () => {
+    const source = { a: { b: 'existing' } };
+    setObjValueByPath(source, 'a.c.d', 'newNestedValue');
+    expect(getObjValueByPath(source, 'a.c.d')).toBe('newNestedValue');
+  });
+
+  test('Handles array paths', () => {
+    const source = { items: [{ name: 'item1' }] };
+    setObjValueByPath(source, 'items.0.name', 'updatedItem');
+    expect(getObjValueByPath(source, 'items.0.name')).toBe('updatedItem');
+  });
+
+  test('Throws error for __proto__ path', () => {
+    const source = { a: 'b' };
+    expect(() => setObjValueByPath(source, '__proto__.test', 'value')).toThrow(SyntaxError);
+  });
+});

package/src/util/{getURLParam.js → query.js}

@@ -1,6 +1,16 @@
-import { sanitizeURLParam } from './sanitizeURLParam.js';
+const urlSearchParams = new URLSearchParams(globalThis.location.search);
 
-const urlSearchParams = new URLSearchParams(window.location.search);
+/**
+ * Sanitizes URL parameters allowing only alpha-numeric characters and dash.
+ * @param {string} input - The input string to be sanitized.
+ * @returns {string} The sanitized output string.
+ */
+export const sanitizeURLParam = (input) => {
+  if (!input) {
+    return input;
+  }
+  return input.replaceAll(/[^\w-]/giu, '');
+};
 
 /**
  * Get a URL parameter value.

package/src/util/{sanitizeURLParam.test.js → query.test.js}

@@ -1,4 +1,21 @@
-import { sanitizeURLParam } from './sanitizeURLParam.js';
+import { getURLParam, sanitizeURLParam } from './query.js';
+
+describe('getURLParam', () => {
+  test('Returns fallback value when parameter is not found', () => {
+    const result = getURLParam('nonexistent', 'fallback');
+    expect(result).toBe('fallback');
+  });
+
+  test('Handles null/undefined input gracefully', () => {
+    const result = getURLParam(null, 'fallback');
+    expect(result).toBe('fallback');
+  });
+
+  test('Returns default value when param is null', () => {
+    const result = getURLParam('key', 'default');
+    expect(result).toBe('default');
+  });
+});
 
 describe('sanitizeURLParam', () => {
   test('Sanitizes URL parameter correctly', () => {

package/src/util/{serverDataToState.js → state.js}

@@ -1,4 +1,4 @@
-import { underscoreToCamelCase } from './underscoreToCamelCase.js';
+import { underscoreToCamelCase } from './string.js';
 
 /**
  * Maps server data to client data.

package/src/util/{serverDataToState.test.js → state.test.js}

@@ -1,4 +1,4 @@
-import { serverDataToState } from './serverDataToState.js';
+import { serverDataToState } from './state.js';
 
 test('serverDataToState() recursive', () => {
   const state = serverDataToState(

package/src/util/string.js

@@ -0,0 +1,54 @@
+/**
+ * Add leading zeros to a value to ensure it has a minimum width.
+ * @param {number | string | null | undefined} value - The value to pad with leading zeros.
+ * @param {number} size - The minimum width of the resulting string.
+ * @returns {string | null} The value padded with leading zeros or null if the input is null/undefined.
+ */
+export const addLeadingZero = (value, size = 2) => {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  value = value.toString();
+  while (value.length < size) {
+    value = `0${value}`;
+  }
+  return value;
+};
+
+/**
+ * Capitalize a string.
+ * @param {string | null | undefined} value - The input string to capitalize.
+ * @returns {string | null} The capitalized string or null if the input is null/undefined.
+ */
+export const capitalize = (value) => {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  if (!value || value?.length === 0) {
+    return value;
+  }
+  const normValue = value.toLowerCase();
+  return normValue.charAt(0).toUpperCase() + normValue.slice(1);
+};
+
+/**
+ * Converts underscore case string to camel case.
+ * @param {string} value - The input string in underscore case.
+ * @returns {string} The output string in camel case.
+ */
+export const underscoreToCamelCase = (value) => value.replaceAll(/(_\w)/gu, (m) => m[1].toUpperCase());
+
+/**
+ * Saves text file.
+ * @param {string} filename - File name.
+ * @param {string} text - File content.
+ */
+export const saveAsFile = (filename, text) => {
+  const element = document.createElement('a');
+  element.setAttribute('href', `data:text/plain;charset=utf-8,${encodeURIComponent(text)}`);
+  element.setAttribute('download', filename);
+  element.style.display = 'none';
+  document.body.append(element);
+  element.click();
+  element.remove();
+};

package/src/util/{capitalize.test.js → string.test.js}

@@ -1,4 +1,16 @@
-import { capitalize } from './capitalize.js';
+/* eslint-disable unicorn/no-useless-undefined */
+
+import { underscoreToCamelCase, capitalize, addLeadingZero } from './string.js';
+
+test('Tests add leading zero', () => {
+  expect(addLeadingZero(1)).toBe('01');
+  expect(addLeadingZero('1')).toBe('01');
+  expect(addLeadingZero(1, 3)).toBe('001');
+  expect(addLeadingZero('21')).toBe('21');
+  expect(addLeadingZero(21)).toBe('21');
+  expect(addLeadingZero(null)).toBe(null);
+  expect(addLeadingZero(undefined)).toBe(null);
+});
 
 describe('capitalize', () => {
   test('Capitalizes first letter of string', () => {
@@ -28,3 +40,9 @@ describe('capitalize', () => {
     expect(capitalize('test123')).toBe('Test123');
   });
 });
+
+test('Converts underscore to camelCase', () => {
+  expect(underscoreToCamelCase('test')).toBe('test');
+  expect(underscoreToCamelCase('test_variable')).toBe('testVariable');
+  expect(underscoreToCamelCase('test_variable_name')).toBe('testVariableName');
+});

package/src/util/validate.js

@@ -0,0 +1,272 @@
+/* eslint-disable jsdoc/reject-any-type */
+/* eslint-disable jsdoc/no-undefined-types */
+
+import { isEq, isGt, isGtOrEq, isInRange, isLe, isLeOrEq } from './number.js';
+
+/**
+ * Validates `value` as `boolean`.
+ * @param {unknown} value - Input value.
+ * @returns {value is boolean} `true` if `value` is `boolean` type.
+ */
+export const isBoolean = (value) => typeof value === 'boolean';
+
+/**
+ * Validates `value` as `function`.
+ * @param {unknown} value - Input value.
+ * @returns {value is (...args: any[]) => any} `true` if `value` is `function` type.
+ */
+export const isFunction = (value) => typeof value === 'function';
+
+/**
+ * Validates `value` as `number`.
+ * @param {unknown} value - Input value.
+ * @returns {value is number} `true` if `value` is `number` type.
+ */
+export const isNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+
+/**
+ * Validates `value` as positive `number`.
+ * @param {unknown} value - Input value.
+ * @returns {value is number} `true` if `value` is `number` type with positive value.
+ */
+export const isPositiveNumber = (value) => isNumber(value) && value > 0;
+
+/**
+ * Validates `value` as non-negative `number`.
+ * @param {unknown} value - Input value.
+ * @returns {value is number} `true` if `value` is `number` type with non-negative value.
+ */
+export const isNonNegativeNumber = (value) => isNumber(value) && value >= 0;
+
+/**
+ * Validates `value` as `integer`.
+ * @param {unknown} value - Input value.
+ * @returns {value is number} `true` if `value` is `integer` type.
+ */
+export const isInteger = (value) => isNumber(value) && Number.isInteger(value);
+
+/**
+ * Validates `value` as positive `integer`.
+ * @param {unknown} value - Input value.
+ * @returns {value is number} `true` if `value` is `integer` type with positive value.
+ */
+export const isPositiveInteger = (value) => isInteger(value) && value > 0;
+
+/**
+ * Validates `value` as non-negative `integer`.
+ * @param {unknown} value - Input value.
+ * @returns {value is number} `true` if `value` is `integer` type with non-negative value.
+ */
+export const isNonNegativeInteger = (value) => isInteger(value) && value >= 0;
+
+/**
+ * Validates `value` as `string`.
+ * @param {unknown} value - Input value.
+ * @returns {value is string} `true` if `value` is `string` type.
+ */
+export const isString = (value) => typeof value === 'string';
+
+/**
+ * Validates `value` as `array`.
+ * @template T
+ * @param {unknown} value - Input value.
+ * @returns {value is T[]} `true` if `value` is `array` type.
+ */
+export const isArray = (value) => Array.isArray(value);
+
+/**
+ * Validates `value` as `null`
+ * @param {unknown} value - Input value.
+ * @returns {value is null} `true` if `value` is `null` type.
+ */
+export const isNull = (value) => value === null;
+
+/**
+ * Validates `value` as `undefined`
+ * @param {unknown} value - Input value.
+ * @returns {value is undefined} `true` if `value` is `undefined` type.
+ */
+export const isUndefined = (value) => value === undefined;
+
+/**
+ * Validates `value` as `null` or `undefined`
+ * @param {unknown} value - Input value.
+ * @returns {value is null | undefined} `true` if `value` is `null` or `undefined` type.
+ */
+export const isNullOrUndefined = (value) => isNull(value) || isUndefined(value);
+
+/**
+ * Validates `value` as plain `object`.
+ * @param {unknown} value - Input value.
+ * @returns {value is Record<string, unknown>} `true` if `value` is `object` type.
+ */
+export const isPlainObject = (value) => Object.prototype.toString.call(value) === '[object Object]';
+
+/**
+ * Validates `value` as `type`
+ * @template T
+ * @param {unknown} value - The value to test.
+ * @param {new (...args: any[]) => T} type - A class or constructor function.
+ * @returns {value is T} `true` if `value` is an instance of `type`.
+ */
+export const isInstance = (value, type) => isFunction(type) && value instanceof type;
+
+/**
+ * Validates `value` as `enum`.
+ * @param {unknown} value - Input value.
+ * @param {unknown[] | Set<string | number> | Record<string | number, unknown>} choices - Input value.
+ * @returns {boolean} `true` if `value` is `enum` type.
+ */
+export const isEnum = (value, choices) => {
+  if (!isString(value) && !isNumber(value)) {
+    return false;
+  }
+  return (
+    (isArray(choices) && choices.includes(value)) ||
+    (isPlainObject(choices) && Object.values(choices).includes(value)) ||
+    (isInstance(choices, Set) && choices.has(value))
+  );
+};
+
+/**
+ * Type check an array of values using a validator.
+ * @template T
+ * @param {unknown} values - The value to check.
+ * @param {(value: unknown) => value is T} validator - The validator to check with.
+ * @returns {values is T[]} `true` if `values` has only `validator` checked types.
+ */
+export const isArrayOf = (values, validator) => {
+  if (!isArray(values)) {
+    return false;
+  }
+  for (const value of values) {
+    if (!validator(value)) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * Type check a plain object of values using a validator.
+ * @template T
+ * @param {Record<string | number, unknown>} record - The value to check.
+ * @param {(value: unknown) => value is T} validator - The validator to check with.
+ * @returns {record is Record<string | number, T>} `true` if `values` has only `validator` checked types.
+ */
+export const isPlainObjectOf = (record, validator) => {
+  if (!isPlainObject(record)) {
+    return false;
+  }
+  for (const value of Object.values(record)) {
+    if (!validator(value)) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * Refine a base validator with an extra condition.
+ * @template T
+ * @param {(value: unknown) => value is T} base - The base validator.
+ * @param {(value: T) => boolean} predicate - Extra condition validator.
+ * @param {string | null} name - Refined validator name.
+ * @returns {(value: unknown) => value is T} The refined validator.
+ */
+export const refineValidator = (base, predicate, name = null) => {
+  const refinedValidator = (value) => base(value) && predicate(value);
+  Object.defineProperty(refinedValidator, 'name', {
+    value: isString(name) ? name : `${base.name}Refined`,
+  });
+  // @ts-expect-error
+  return refinedValidator;
+};
+
+//
+// Refined validators
+//
+
+/**
+ * Logical OR of two validators.
+ * @template A, B
+ * @param {(value: unknown) => value is A} a - Validator A.
+ * @param {(value: unknown) => value is B} b - Validator B.
+ * @returns {(value: unknown) => value is A | B} `true` if `value` is any of the checked types.
+ */
+export const isAnyOf = (a, b) => (value) => a(value) || b(value);
+
+export const isNumberGreater = (min) => refineValidator(isNumber, (value) => isGt(value, min));
+export const isNumberGreaterOrEqual = (min) => refineValidator(isNumber, (value) => isGtOrEq(value, min));
+export const isNumberLess = (min) => refineValidator(isNumber, (value) => isLe(value, min));
+export const isNumberLessOrEqual = (min) => refineValidator(isNumber, (value) => isLeOrEq(value, min));
+export const isNumberInRange = (min, max) => refineValidator(isNumber, (value) => isInRange(value, min, max));
+export const isNumberEqual = (expected) => refineValidator(isNumber, (value) => isEq(value, expected));
+
+export const isIntegerGreater = (min) => refineValidator(isInteger, (value) => isGt(value, min));
+export const isIntegerGreaterOrEqual = (min) => refineValidator(isInteger, (value) => isGtOrEq(value, min));
+export const isIntegerLess = (min) => refineValidator(isInteger, (value) => isLe(value, min));
+export const isIntegerLessOrEqual = (min) => refineValidator(isInteger, (value) => isLeOrEq(value, min));
+export const isIntegerInRange = (min, max) => refineValidator(isInteger, (value) => isInRange(value, min, max));
+export const isIntegerEqual = (expected) => refineValidator(isNumber, (value) => isEq(value, expected));
+
+export const isStringLengthGreater = (min) => refineValidator(isString, (value) => isGt(value.length, min));
+export const isStringLengthGreaterOrEqual = (min) => refineValidator(isString, (value) => isGtOrEq(value.length, min));
+export const isStringLengthLess = (min) => refineValidator(isString, (value) => isLe(value.length, min));
+export const isStringLengthLessOrEqual = (min) => refineValidator(isString, (value) => isLeOrEq(value.length, min));
+export const isStringLengthInRange = (min, max) =>
+  refineValidator(isString, (value) => isInRange(value.length, min, max));
+export const isStringLengthEqual = (expected) => refineValidator(isString, (value) => isEq(value.length, expected));
+
+export const isArrayLengthGreater = (min) => refineValidator(isArray, (value) => isGt(value.length, min));
+export const isArrayLengthGreaterOrEqual = (min) => refineValidator(isArray, (value) => isGtOrEq(value.length, min));
+export const isArrayLengthLess = (min) => refineValidator(isArray, (value) => isLe(value.length, min));
+export const isArrayLengthLessOrEqual = (min) => refineValidator(isArray, (value) => isLeOrEq(value.length, min));
+export const isArrayLengthInRange = (min, max) =>
+  refineValidator(isArray, (value) => isInRange(value.length, min, max));
+export const isArrayLengthEqual = (expected) => refineValidator(isArray, (value) => isEq(value.length, expected));
+
+export class TypeCheckError extends TypeError {
+  /**
+   * Creates a new `TypeCheckError` instance.
+   * @param {string} message - Error message.
+   */
+  constructor(message) {
+    super(message);
+    this.name = 'TypeCheckError';
+  }
+}
+
+/**
+ * Type check a value using a validator.
+ * @template T
+ * @param {unknown} value - The value to check.
+ * @param {(value: unknown) => value is T} validator - The validator to check with.
+ * @returns {T} The type checked value.
+ * @throws {TypeCheckError}
+ */
+export const typeCheck = (value, validator) => {
+  if (!validator(value)) {
+    const name = validator.name || '<anonymous>';
+    const display = typeof value === 'string' ? `"${value}"` : Object.prototype.toString.call(value);
+    throw new TypeCheckError(`Validation failed: ${name} (${display})`);
+  }
+  return value;
+};
+
+/**
+ * Type check a value using a validator.
+ * @template T
+ * @param {unknown[]} value - The value to check.
+ * @param {(value: unknown) => value is T} validator - The validator to check the array with.
+ * @returns {T[]} The type checked value.
+ * @throws {TypeCheckError}
+ */
+export const typeCheckArray = (value, validator) => {
+  if (!isArrayOf(value, validator)) {
+    const name = validator.name || '<anonymous>';
+    const display = typeof value === 'string' ? `"${value}"` : Object.prototype.toString.call(value);
+    throw new TypeCheckError(`Validation failed: ${name} (${display})`);
+  }
+  return value;
+};