@vpmedia/simplify 1.74.0 → 1.75.0

package/src/util/object.test.ts

@@ -0,0 +1,203 @@
+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: string | null } = { 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', () => {
+    setObjValueByPath(null, 'a.b.c', 'value');
+    setObjValueByPath(undefined, 'a.b.c', 'value');
+  });
+
+  test('Handles null or undefined path', () => {
+    const source = { a: 'b' };
+    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: Record<string, unknown> = { 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/{object.js → object.ts}

@@ -1,10 +1,11 @@
 const PROHIBITED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 
+type AnyRecord = Record<string, any>;
+
 /**
  * Purges object properties to free up memory.
- * @param {object} target - The target object.
  */
-export const purgeObject = (target) => {
+export const purgeObject = (target: AnyRecord | null | undefined): void => {
   if (!target) {
     return;
   }
@@ -15,11 +16,8 @@ export const purgeObject = (target) => {
 
 /**
  * Merge two objects.
- * @param {object} target - Target merge object.
- * @param {object} source - Source merge object.
- * @returns {object} Merged result object.
  */
-export const deepMerge = (target, source) => {
+export const deepMerge = (target: AnyRecord | null, source: AnyRecord | null): AnyRecord | null => {
   if (typeof target !== 'object' || target === null) {
     return source;
   }
@@ -45,24 +43,19 @@ export const deepMerge = (target, source) => {
 
 /**
  * Returns the sum value of an array of objects field.
- * @param {object[]} arr - The list of input objects.
- * @param {string} prop - The object property key.
- * @returns {number} The sum value.
  */
-export const getObjArrayPropSum = (arr, prop) => arr.reduce((accumulator, object) => accumulator + object[prop], 0);
+export const getObjArrayPropSum = (arr: AnyRecord[], prop: string): number =>
+  arr.reduce((accumulator, object) => accumulator + (object[prop] as number), 0);
 
 /**
  * Get object value by path.
- * @param {object} obj - The source object to get the value from.
- * @param {string} path - The path to the property in dot notation (e.g. 'a.b.c').
- * @returns {object | null} The value at the specified path or null if not found.
  */
-export const getObjValueByPath = (obj, path) => {
+export const getObjValueByPath = (obj: AnyRecord | null | undefined, path: string | null | undefined): unknown => {
   if (!obj || !path) {
     return null;
   }
   const keyParts = path.split('.');
-  const [nextKey] = keyParts;
+  const nextKey = keyParts[0]!;
   if (keyParts.length === 1) {
     return obj[nextKey] === undefined ? null : obj[nextKey];
   }
@@ -74,24 +67,24 @@ export const getObjValueByPath = (obj, path) => {
 
 /**
  * Set object value by path.
- * @param {object} obj - The source object to set the value in.
- * @param {string} path - The path to the property in dot notation (e.g. 'a.b.c').
- * @param {object | null | undefined} value - The value to set at the specified path.
  * @throws {SyntaxError} Error when illegal path value has been provided.
  */
-export const setObjValueByPath = (obj, path, value) => {
+export const setObjValueByPath = (
+  obj: AnyRecord | null | undefined,
+  path: string | null | undefined,
+  value: unknown
+): void => {
   if (!obj || !path) {
     return;
   }
   const keyParts = path.split('.');
-  const [nextKey] = keyParts;
+  const nextKey = keyParts[0]!;
   if (PROHIBITED_KEYS.has(nextKey)) {
     throw new SyntaxError(`Security violation error. Cannot use "${nextKey}" as parameter.`);
   }
   if (keyParts.length === 1) {
     obj[nextKey] = value;
   } else {
-    // Create the nested object if it doesn't exist
     if (obj[nextKey] === undefined || obj[nextKey] === null) {
       obj[nextKey] = {};
     }

package/src/util/query.test.ts

@@ -0,0 +1,71 @@
+/**
+ * @vitest-environment-options { "url": "https://localhost/app/?language=en&token=123-456-öüó%24D" }
+ */
+
+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');
+  });
+
+  test('Handles valid url parameter sanitized', () => {
+    expect(getURLParam('language')).toBe('en');
+    expect(getURLParam('token')).toBe('123-456-D');
+  });
+
+  test('Handles valid url parameter unsanitized', () => {
+    expect(getURLParam('token', null, false)).toBe('123-456-öüó$D');
+  });
+});
+
+describe('sanitizeURLParam', () => {
+  test('Sanitizes URL parameter correctly', () => {
+    expect(sanitizeURLParam('abc<>-123[]{}-()A_BC')).toBe('abc-123-A_BC');
+  });
+
+  test('Handles null input', () => {
+    expect(sanitizeURLParam(null)).toBe(null);
+  });
+
+  test('Handles empty string', () => {
+    expect(sanitizeURLParam('')).toBe('');
+  });
+
+  test('Handles valid characters', () => {
+    expect(sanitizeURLParam('abc123')).toBe('abc123');
+    expect(sanitizeURLParam('test-parameter')).toBe('test-parameter');
+    expect(sanitizeURLParam('test_parameter')).toBe('test_parameter');
+  });
+
+  test('Handles special characters', () => {
+    expect(sanitizeURLParam('test@#$%')).toBe('test');
+    expect(sanitizeURLParam('test!@#$%^&*()')).toBe('test');
+  });
+
+  test('Handles unicode characters', () => {
+    expect(sanitizeURLParam('test_äöü')).toBe('test_');
+  });
+
+  test('Handles edge cases with various special characters', () => {
+    expect(sanitizeURLParam('test!!!@@@')).toBe('test');
+    expect(sanitizeURLParam('test_param-123')).toBe('test_param-123');
+    expect(sanitizeURLParam('test param')).toBe('testparam');
+  });
+
+  test('Handles very long parameter names', () => {
+    const longParam = 'a'.repeat(1000);
+    expect(typeof sanitizeURLParam(longParam)).toBe('string');
+  });
+});

package/src/util/query.ts

@@ -0,0 +1,35 @@
+const urlSearchParams = new URLSearchParams(globalThis.location?.search);
+
+/**
+ * Sanitizes URL parameters allowing only alpha-numeric characters and dash.
+ */
+export function sanitizeURLParam(input: string): string;
+export function sanitizeURLParam(input: null | undefined): null | undefined;
+export function sanitizeURLParam(input: string | null | undefined): string | null | undefined;
+export function sanitizeURLParam(input: string | null | undefined): string | null | undefined {
+  if (!input) {
+    return input;
+  }
+  return input.replaceAll(/[^\w-]/giu, '');
+}
+
+/**
+ * Get a URL parameter value.
+ */
+export function getURLParam<T = null>(
+  key: string | null | undefined,
+  defaultValue?: T,
+  isSanitize?: boolean
+): string | T {
+  if (!key) {
+    return (defaultValue ?? null) as T;
+  }
+  const paramValue = urlSearchParams.get(key);
+  if (paramValue === null || paramValue === undefined) {
+    return (defaultValue ?? null) as T;
+  }
+  if (isSanitize !== false) {
+    return sanitizeURLParam(paramValue) as string;
+  }
+  return paramValue;
+}

package/src/util/state.test.ts

@@ -0,0 +1,47 @@
+import { serverDataToState } from './state.js';
+
+describe('state', () => {
+  test('serverDataToState() recursive', () => {
+    const state = serverDataToState(
+      {
+        my_array: [{ key_a: 'value1' }],
+        my_data: { key_a: 'value1' },
+        my_list: [1, 2, 3],
+        my_null: null,
+        my_number: 1000,
+        my_string: 'a',
+        my_var: 'test',
+      },
+      true
+    );
+    expect(state.myArray[0].keyA).toBe('value1');
+    expect(state.myData.keyA).toBe('value1');
+    expect(state.myList[0]).toBe(1);
+    expect(state.myNull).toBe(null);
+    expect(state.myNumber).toBe(1000);
+    expect(state.myString).toBe('a');
+    expect(state.myVar).toBe('test');
+  });
+
+  test('serverDataToState() non-recursive', () => {
+    const state = serverDataToState(
+      {
+        my_array: [{ key_a: 'value1' }],
+        my_data: { key_a: 'value1' },
+        my_list: [1, 2, 3],
+        my_null: null,
+        my_number: 1000,
+        my_string: 'a',
+        my_var: 'test',
+      },
+      false
+    );
+    expect(state.myArray[0].key_a).toBe('value1');
+    expect(state.myData.key_a).toBe('value1');
+    expect(state.myList[0]).toBe(1);
+    expect(state.myNull).toBe(null);
+    expect(state.myNumber).toBe(1000);
+    expect(state.myString).toBe('a');
+    expect(state.myVar).toBe('test');
+  });
+});

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

@@ -2,17 +2,14 @@ import { underscoreToCamelCase } from './string.js';
 
 /**
  * Maps server data to client data.
- * @param {object} data - The server input data.
- * @param {boolean} isRecursive - Use recursive serialization.
- * @returns {object} The output data.
  */
-export const serverDataToState = (data, isRecursive = false) => {
+export const serverDataToState = (data: unknown, isRecursive = false): any => {
   if (Array.isArray(data)) {
     return data.map((entry) => serverDataToState(entry, isRecursive));
   }
 
   if (data !== null && typeof data === 'object') {
-    const result = {};
+    const result: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(data)) {
       const clientKey = underscoreToCamelCase(key);
       result[clientKey] = isRecursive ? serverDataToState(value, isRecursive) : value;
@@ -20,5 +17,5 @@ export const serverDataToState = (data, isRecursive = false) => {
     return result;
   }
 
-  return data; // Return primitives as-is
+  return data;
 };

package/src/util/string.test.ts

@@ -0,0 +1,64 @@
+import {
+  underscoreToCamelCase,
+  capitalize,
+  addLeadingZero,
+  getTypeFromValue,
+  getDisplayValue,
+  saveAsFile,
+} from './string.js';
+
+describe('string', () => {
+  test('addLeadingZero', () => {
+    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);
+  });
+
+  test('capitalize', () => {
+    expect(capitalize('test')).toBe('Test');
+    expect(capitalize('TEST')).toBe('Test');
+    expect(capitalize('tEST')).toBe('Test');
+    expect(capitalize(null)).toBe(null);
+    expect(capitalize('')).toBe('');
+    expect(capitalize('   ')).toBe('   ');
+    expect(capitalize('a')).toBe('A');
+    expect(capitalize('A')).toBe('A');
+    expect(capitalize('test123')).toBe('Test123');
+  });
+
+  test('underscoreToCamelCase', () => {
+    expect(underscoreToCamelCase('test')).toBe('test');
+    expect(underscoreToCamelCase('test_variable')).toBe('testVariable');
+    expect(underscoreToCamelCase('test_variable_name')).toBe('testVariableName');
+  });
+
+  test('getTypeFromValue', () => {
+    expect(getTypeFromValue('test')).toBe('string');
+    expect(getTypeFromValue(() => null)).toBe('function');
+    expect(getTypeFromValue([])).toBe('array');
+    expect(getTypeFromValue({})).toBe('object');
+    expect(getTypeFromValue(new Date())).toBe('date');
+    expect(getTypeFromValue(null)).toBe('null');
+    expect(getTypeFromValue(true)).toBe('boolean');
+    expect(getTypeFromValue(undefined)).toBe('undefined');
+  });
+
+  test('getDisplayValue', () => {
+    expect(getDisplayValue('test')).toBe('"test"');
+    expect(getDisplayValue(() => null)).toBe('() => null');
+    expect(getDisplayValue([])).toBe('[]');
+    expect(getDisplayValue({})).toBe('{}');
+    expect(getDisplayValue(new Date())).not.toBe(null);
+    expect(getDisplayValue(null)).toBe('null');
+    expect(getDisplayValue(true)).toBe('true');
+    expect(getDisplayValue(undefined)).toBe('undefined');
+  });
+
+  test('saveAsFile', () => {
+    expect(() => saveAsFile('test.txt', 'test content')).not.toThrowError(Error);
+  });
+});

package/src/util/string.ts

@@ -0,0 +1,65 @@
+/**
+ * Add leading zeros to a value to ensure it has a minimum width.
+ */
+export const addLeadingZero = (value: number | string | null | undefined, size = 2): string | null => {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  let str = value.toString();
+  while (str.length < size) {
+    str = `0${str}`;
+  }
+  return str;
+};
+
+/**
+ * Capitalize a string.
+ */
+export const capitalize = (value: string | null | undefined): string | null => {
+  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.
+ */
+export const underscoreToCamelCase = (value: string): string =>
+  value.replaceAll(/(_\w)/gu, (m) => m[1]!.toUpperCase());
+
+/**
+ * Saves text file.
+ */
+export const saveAsFile = (filename: string, text: string): void => {
+  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();
+};
+
+/**
+ * Get type from value in human readable format.
+ */
+export const getTypeFromValue = (value: unknown): string =>
+  Object.prototype.toString.call(value).slice(8, -1).toLowerCase();
+
+/**
+ * Get value in human readable format.
+ */
+export const getDisplayValue = (value: unknown): string => {
+  if (typeof value === 'string') {
+    return `"${value}"`;
+  }
+  if (typeof value === 'object') {
+    return JSON.stringify(value);
+  }
+  return String(value);
+};

package/src/util/uuid.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { randomUUIDFallback, uuidv4 } from './uuid.js';
+
+const uuidV4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+
+describe('UUID functions', () => {
+  let originalRandomUUID: typeof crypto.randomUUID;
+
+  beforeEach(() => {
+    originalRandomUUID = crypto.randomUUID;
+  });
+
+  afterEach(() => {
+    crypto.randomUUID = originalRandomUUID;
+  });
+
+  it('randomUUIDFallback generates a valid UUID v4', () => {
+    const uuid = randomUUIDFallback();
+    expect(uuid).toMatch(uuidV4Regex);
+  });
+
+  it('uuidv4 returns a valid UUID v4', () => {
+    const uuid = uuidv4();
+    expect(uuid).toMatch(uuidV4Regex);
+  });
+
+  it('uuidv4 uses crypto.randomUUID if available', () => {
+    crypto.randomUUID = vi.fn(() => 'mock-uuid' as `${string}-${string}-${string}-${string}-${string}`);
+    const uuid = uuidv4();
+    expect(uuid).toBe('mock-uuid');
+    expect(crypto.randomUUID).toHaveBeenCalled();
+  });
+
+  it('randomUUIDFallback fallback works if crypto.randomUUID not available', () => {
+    // @ts-expect-error - allow deleting non-optional property for test
+    delete crypto.randomUUID;
+    const uuid = randomUUIDFallback();
+    expect(uuid).toMatch(uuidV4Regex);
+  });
+
+  it('randomUUIDFallback does not generate duplicates', () => {
+    const uuidMap = new Map<string, boolean>();
+    const numSamples = 1000;
+    for (let i = 0; i < numSamples; i += 1) {
+      const uuid = randomUUIDFallback();
+      if (uuidMap.has(uuid)) {
+        throw new Error('Duplicate UUIDv4 found');
+      }
+      uuidMap.set(uuid, true);
+    }
+    expect(uuidMap.size).toBe(numSamples);
+  });
+});

package/src/util/uuid.ts

@@ -0,0 +1,31 @@
+/**
+ * Convert a byte (0–255) to a 2-character hex string.
+ */
+export const byteToHex = (byte: number): string => (byte >>> 4).toString(16) + (byte & 0b1111).toString(16);
+
+/**
+ * UUIDv4 fallback generator (RFC 4122 compliant).
+ */
+export const randomUUIDFallback = (): string => {
+  const bytes: number[] | Uint8Array = crypto.getRandomValues
+    ? crypto.getRandomValues(new Uint8Array(16))
+    : Array.from({ length: 16 }, () => Math.floor(Math.random() * 256));
+
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+
+  let uuid = '';
+  for (let index = 0; index < bytes.length; index += 1) {
+    if (index === 4 || index === 6 || index === 8 || index === 10) {
+      uuid += '-';
+    }
+    uuid += byteToHex(bytes[index]!);
+  }
+  return uuid;
+};
+
+/**
+ * Crypto UUIDv4 wrapper with fallback.
+ */
+export const uuidv4 = (): string =>
+  typeof crypto.randomUUID === 'function' ? crypto.randomUUID() : randomUUIDFallback();