@sparted/shared-library 1.9.3 → 1.9.5

package/src/linked-list/type.ts

@@ -0,0 +1,38 @@
+export type LinkedListItem = {
+  id: string,
+  nextId: string | null,
+  previousId?: string | null,
+};
+
+export type SimpleLinkedList<T extends LinkedListItem> = {
+  headId: string | null,
+  items: {
+    [id: string]: T,
+  },
+};
+
+export type ReduceCallback<Item, Result> = (accumulator: Result, current: Item) => Result;
+export type ItemPredicate<Item> = (item: Item) => boolean;
+export type LinkedListFormat = 'double' | 'single';
+export type ManipulationConfig<T extends LinkedListItem> = {
+  format: LinkedListFormat | null,
+  list: SimpleLinkedList<T>,
+  factory: (list: SimpleLinkedList<T>) => LinkedList<T>,
+};
+
+export type LinkedList<T extends LinkedListItem> = {
+  readonly head: T | null,
+  readonly items: {
+    [id: string]: T,
+  },
+  readonly size: number,
+  readonly format: LinkedListFormat | null,
+  readonly reduce: <Result>(cb: ReduceCallback<T, Result>, init: Result) => Result,
+  readonly find: (predicate: ItemPredicate<T>) => T | null,
+  readonly while: (predicate: ItemPredicate<T>, startId?: string) => string[],
+  readonly remove: (id: string) => LinkedList<T>,
+  readonly insert: (item: T) => LinkedList<T>,
+  readonly get: (id: string) => T | null,
+  readonly update: (item: T) => LinkedList<T>,
+  readonly applyDiff: (before: T | null, after: T | null) => LinkedList<T>,
+};

package/src/linked-list/update-linked-list.ts

@@ -0,0 +1,30 @@
+import { ManipulationConfig, LinkedListItem } from './type';
+import { assertPresence } from './linked-list-utils';
+
+export const updateLinkedList = <T extends LinkedListItem>(item: T, config: ManipulationConfig<T>) => {
+  const { list, factory } = config;
+
+  assertPresence(item.id, list.items);
+
+  /**
+   * This method should not update any ids, this is why they are removed from the item.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { nextId, previousId, id, ...updatedProperties } = item;
+  const currentItem = list.items[item.id];
+
+  const newItems = {
+    ...list.items,
+    [item.id]: {
+      nextId: currentItem.nextId,
+      previousId: currentItem.previousId,
+      id: currentItem.id,
+      ...updatedProperties,
+    } as T,
+  };
+
+  return factory({
+    headId: list.headId,
+    items: newItems,
+  });
+};

package/src/linked-list/while-linked-list.ts

@@ -0,0 +1,33 @@
+import { LinkedListItem, ItemPredicate, SimpleLinkedList } from './type';
+import { walkListItemRecord } from './linked-list-utils';
+
+export const whileLinkedList = <Item extends LinkedListItem>(
+  predicate: ItemPredicate<Item>,
+  list: SimpleLinkedList<Item>,
+  startId?: string,
+): string[] => {
+  if (startId && !list.items[startId]) {
+    throw new Error('Cannot start from a node that does not exist');
+  }
+
+  return walkListItemRecord((acc, item) => {
+    const itemMatched = predicate(item);
+
+    if (itemMatched) {
+      return {
+        result: [...acc, item.id],
+      };
+    }
+
+    return {
+      result: acc,
+      control: {
+        stop: true,
+      },
+    };
+  }, {
+    initValue: [] as string[],
+    startId: startId || list.headId,
+    items: list.items,
+  });
+};

package/src/math/__tests__/clamp-number.test.ts

@@ -0,0 +1,30 @@
+import { clampNumber } from '../clamp-number';
+
+describe('clampNumber', () => {
+  it('should not return number below the min', () => {
+    const result = clampNumber(-51, {
+      min: -9,
+      max: -1,
+    });
+
+    expect(result).toStrictEqual(-9);
+  });
+
+  it('should return the same number because it is inside the range', () => {
+    const result = clampNumber(128, {
+      min: 100,
+      max: 200,
+    });
+
+    expect(result).toStrictEqual(128);
+  });
+
+  it('should not return number above the max', () => {
+    const result = clampNumber(128, {
+      min: -100,
+      max: -8,
+    });
+
+    expect(result).toStrictEqual(-8);
+  });
+});

package/src/math/__tests__/interpolate.test.ts

@@ -0,0 +1,28 @@
+import { interpolate, RangeArray } from '../interpolate';
+
+describe('interpolate', () => {
+  it('should throw if input range is x2 < x1 in input range', () => {
+    expect(
+      () => interpolate(100, [1, 0], [0, 1]),
+    ).toThrowError('interpolate: inputRange[0] should not be superior to inputRange[1]');
+  });
+
+  it('should throw if input number is not in input range', () => {
+    expect(
+      () => interpolate(100, [0, 1], [1, 0]),
+    ).toThrowError('interpolate: input number {100} is not in range of {0}-{1}');
+  });
+
+  it('should return the correct interpolated number', () => {
+    const set: { num: number, result: number, inputRange: RangeArray, outputRange: RangeArray }[] = [
+      { num: 50, inputRange: [0, 100], outputRange: [0, 1], result: 0.5 },
+      { num: 15.5, inputRange: [0, 100], outputRange: [0, 1], result: 0.155 },
+      { num: 15.5, inputRange: [0, 100], outputRange: [0, 1000], result: 155 },
+      { num: 75, inputRange: [0, 100], outputRange: [-100, 0], result: -25 },
+    ];
+
+    set.forEach(({ num, inputRange, outputRange, result }) => expect(
+      interpolate(num, inputRange, outputRange),
+    ).toStrictEqual(result));
+  });
+});

package/src/math/__tests__/median.test.ts

@@ -0,0 +1,27 @@
+import { median } from '../median';
+
+describe('median', () => {
+  it('should return the middle value if the array has an odd number of elements', () => {
+    expect(median([1, 2, 3])).toStrictEqual(2);
+  });
+
+  it('should return the average of the middle two values if the array has an even number of elements', () => {
+    expect(median([1, 2, 3, 4])).toStrictEqual(2.5);
+  });
+
+  it('should handle an empty array', () => {
+    expect(median([])).toBeNull();
+  });
+
+  it('should handle array with duplicate values', () => {
+    expect(median([4, 7, 2, 4, 9])).toStrictEqual(4);
+  });
+
+  it('should handle array with negative values', () => {
+    expect(median([-1, -5, -3, -2, -4])).toStrictEqual(-3);
+  });
+
+  it('should overwrite the default value if the array is empty', () => {
+    expect(median([], 0)).toStrictEqual(0);
+  });
+});

package/src/math/__tests__/number-range.test.ts

@@ -0,0 +1,59 @@
+import { assertNumberRange, isNumberInRange } from '../number-range';
+
+describe('assertNumberRange', () => {
+  it('should throw an error if min is above max', () => {
+    expect(
+      () => assertNumberRange({
+        min: 5,
+        max: 0,
+      }),
+    ).toThrowError('Invalid number range: min must be lower than or equal to max');
+  });
+
+  it('should not throw an error if the number range is valid', () => {
+    expect(
+      () => assertNumberRange({
+        min: 0,
+        max: 5,
+      }),
+    ).not.toThrowError();
+  });
+});
+
+describe('isNumberInRange', () => {
+  it('should throw an error if range is incorrect', () => {
+    expect(
+      () => isNumberInRange(2, {
+        min: 5,
+        max: 0,
+      }),
+    ).toThrowError('Invalid number range: min must be lower than or equal to max');
+  });
+
+  it('should return true if number is in range', () => {
+    const set = [
+      { num: 1, range: { min: 0, max: 1 } },
+      { num: 0, range: { min: 0, max: 1 } },
+      { num: 0.5, range: { min: 0, max: 1 } },
+      { num: -30, range: { min: -1000, max: 1000 } },
+    ];
+
+    set.forEach(({ num, range }) => {
+      expect(isNumberInRange(num, range)).toBeTrue();
+    });
+  });
+
+  it('should return false if number is not in range', () => {
+    const set = [
+      { num: -5, range: { min: 0, max: 1 } },
+      { num: 1.01, range: { min: 0, max: 1 } },
+      { num: 10, range: { min: 0, max: 1 } },
+      { num: -2000, range: { min: -1000, max: 1000 } },
+      { num: 2000, range: { min: -1000, max: 1000 } },
+    ];
+
+    set.forEach(({ num, range }) => {
+      expect(isNumberInRange(num, range)).toBeFalse();
+    });
+  });
+});

package/src/math/__tests__/random-number.test.ts

@@ -0,0 +1,11 @@
+import { randomNumber } from '../random-number';
+
+describe('randomNumber', () => {
+  const satisfyInRange = (min: number, max: number) => (value: number) => value >= min && value <= max;
+
+  it('should return a random number between the range', () => {
+    expect(randomNumber({ min: 98, max: 110 })).toSatisfy(satisfyInRange(98, 110));
+    expect(randomNumber({ min: -5, max: 0 })).toSatisfy(satisfyInRange(-5, 0));
+    expect(randomNumber({ min: 0, max: 10 })).toSatisfy(satisfyInRange(0, 10));
+  });
+});

package/src/math/clamp-number.ts

@@ -0,0 +1,8 @@
+import { assertNumberRange } from './number-range';
+import type { NumberRange } from './number-range';
+
+export const clampNumber = (num: number, { min, max }: NumberRange) => {
+  assertNumberRange({ min, max });
+
+  return Math.min(Math.max(num, min), max);
+};

package/src/math/index.ts

@@ -0,0 +1,5 @@
+export * from './clamp-number';
+export * from './interpolate';
+export * from './number-range';
+export * from './random-number';
+export * from './median';

package/src/math/interpolate.ts

@@ -0,0 +1,18 @@
+import { isNumberInRange } from './number-range';
+
+export type RangeArray = [number, number];
+
+export const interpolate = (num: number, inputRange: RangeArray, outputRange: RangeArray) => {
+  const [x1, x2] = inputRange;
+  const [y1, y2] = outputRange;
+
+  if (x1 > x2) {
+    throw new Error('interpolate: inputRange[0] should not be superior to inputRange[1]');
+  }
+
+  if (!isNumberInRange(num, { min: x1, max: x2 })) {
+    throw new Error(`interpolate: input number {${num}} is not in range of {${x1}}-{${x2}}`);
+  }
+
+  return y1 + ((num - x1) / (x2 - x1)) * (y2 - y1);
+};

package/src/math/median.ts

@@ -0,0 +1,21 @@
+export function median(arr: number[]): number | null;
+export function median(arr: number[], defaultValueIfEmpty: number): number;
+export function median(arr: number[], defaultValueIfEmpty?: number) {
+  if (arr.length === 0) {
+    if (typeof defaultValueIfEmpty === 'number') {
+      return defaultValueIfEmpty;
+    }
+    return null;
+  }
+
+  const sorted = [...arr].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+
+  // If the length of the array is odd, return the middle element
+  if (sorted.length % 2 === 1) {
+    return sorted[mid];
+  }
+
+  // If the length of the array is even, return the average of the middle two elements
+  return (sorted[mid - 1] + sorted[mid]) / 2;
+}

package/src/math/number-range.ts

@@ -0,0 +1,16 @@
+export type NumberRange = {
+  min: number,
+  max: number,
+};
+
+export const assertNumberRange = (range: NumberRange) => {
+  if (range.min > range.max) {
+    throw new Error('Invalid number range: min must be lower than or equal to max');
+  }
+};
+
+export const isNumberInRange = (num: number, { min, max }: NumberRange) => {
+  assertNumberRange({ min, max });
+
+  return num >= min && num <= max;
+};

package/src/math/random-number.ts

@@ -0,0 +1,10 @@
+import { assertNumberRange } from './number-range';
+import type { NumberRange } from './number-range';
+
+export const randomNumber = ({ min, max }: NumberRange) => {
+  assertNumberRange({ min, max });
+
+  return Math.floor(
+    Math.random() * (max - min) + min,
+  );
+};

package/src/object/__tests__/merge-deep.test.ts

@@ -0,0 +1,56 @@
+import { mergeDeep } from '../merge-deep';
+
+type A = {
+  a: number,
+  b: {
+    c: {
+      c1: string,
+      c2: number,
+    },
+  },
+  d:ReadonlyArray<number>,
+  e: boolean,
+};
+
+describe('mergeDeep', () => {
+  it('should return same object if no update', () => {
+    const a: A = {
+      a: 0, b: { c: { c1: 'yo', c2: 0 } }, d: [], e: false,
+    };
+    const b = {};
+
+    expect(mergeDeep(a, b)).toBe(a);
+  });
+
+  it('should leave object unchanged if update does nothing', () => {
+    const a: A = {
+      a: 0, b: { c: { c1: 'yo', c2: 0 } }, d: [], e: false,
+    };
+    const b = { a: 0 };
+
+    expect(mergeDeep(a, b)).toBe(a);
+  });
+
+  it('should do an update', () => {
+    const a: A = {
+      a: 0, b: { c: { c1: 'yo', c2: 0 } }, d: [], e: false,
+    };
+    const b = { a: 1, b: { c: { c1: 'hey' } }, d: [1, 2], e: true };
+
+    expect(mergeDeep(a, b)).toStrictEqual({ a: 1, b: { c: { c1: 'hey', c2: 0 } }, d: [1, 2], e: true });
+  });
+
+  it('should overwrite arrays', () => {
+    const a = { a: [1, 2] };
+    const b = { a: [3, 4] };
+
+    expect(mergeDeep(a, b)).toStrictEqual(b);
+  });
+
+  it('should not add new keys', () => {
+    const a = { a: 0, c: 0 };
+    const b: any = { a: 0, b: 0, c: 0 };
+
+    expect(mergeDeep(a, b)).toBe(a);
+  });
+});

package/src/object/__tests__/strip-properties-from-object.test.ts

@@ -0,0 +1,65 @@
+import { stripPropertiesFromObject } from '../strip-properties-from-object';
+
+describe('stripPropertiesFromObject', () => {
+  const obj = {
+    a: 1,
+    b: {
+      b1: 1,
+      b2: 2,
+      b3: 3,
+      b4: {
+        b41: 1,
+        b42: 2,
+        b43: 3,
+      },
+    },
+    c: 3,
+  };
+
+  it('should remove the properties from the object', () => {
+    const result = stripPropertiesFromObject(obj, ['c', 'b.b1', 'b.b4.b41']);
+
+    expect(result).toMatchObject({
+      a: 1,
+      b: {
+        b2: 2,
+        b3: 3,
+        b4: {
+          b42: 2,
+          b43: 3,
+        },
+      },
+    });
+
+    // Check if no mutation on the orignal object
+    expect(obj).toEqual({
+      a: 1,
+      b: {
+        b1: 1,
+        b2: 2,
+        b3: 3,
+        b4: {
+          b41: 1,
+          b42: 2,
+          b43: 3,
+        },
+      },
+      c: 3,
+    });
+  });
+
+  it('should ignore properties that do not exist', () => {
+    const result = stripPropertiesFromObject(obj, ['d', 'a.b', 'b.b1.b11']);
+    expect(result).toEqual(obj);
+  });
+
+  it('should not fail with empty array', () => {
+    const result = stripPropertiesFromObject(obj, []);
+    expect(result).toEqual(obj);
+  });
+
+  it('should handle empty property', () => {
+    const result = stripPropertiesFromObject(obj, ['']);
+    expect(result).toEqual(obj);
+  });
+});

package/src/object/index.ts

@@ -0,0 +1,2 @@
+export * from './merge-deep';
+export * from './strip-properties-from-object';

package/src/object/merge-deep.ts

@@ -0,0 +1,26 @@
+import type { DeepPartial, ValueType } from '../types';
+
+// https://stackoverflow.com/questions/8511281/check-if-a-value-is-an-object-in-javascript/8511350#8511350
+const isObject = (a: any) => typeof a === 'object' && a !== null;
+const isValueType = (a: any): a is ValueType => !isObject(a) || Array.isArray(a);
+
+export const mergeDeep = <T>(a: T, b: DeepPartial<T>): T => {
+  if (isValueType(a) || isValueType(b)) {
+    return b as T;
+  }
+
+  return (Object.keys(b) as (keyof T)[]).reduce((acc, key) => {
+    // @ts-ignore
+    if (!(key in a)) {
+      return acc;
+    }
+
+    if (b[key] === a[key]) {
+      return acc;
+    }
+
+    const merged = mergeDeep(a[key], b[key] as DeepPartial<T[keyof T]>);
+
+    return { ...acc, [key]: merged };
+  }, a);
+};

package/src/object/strip-properties-from-object.ts

@@ -0,0 +1,26 @@
+import structuredClone from '@ungap/structured-clone';
+
+export const stripPropertiesFromObject = <Output extends Record<any, any>, Input extends Record<any, any>>(
+  obj: Input,
+  properties: string[],
+): Output => {
+  const copy = structuredClone(obj);
+
+  properties.forEach((nestedPropertyStr) => {
+    const nestedProperties = nestedPropertyStr.split('.');
+    const propertyToRemove = nestedProperties[nestedProperties.length - 1];
+
+    const nestedObject =
+      nestedProperties.length === 1
+        ? copy
+        : nestedProperties
+            .slice(0, nestedProperties.length - 1)
+            .reduce((acc, property) => acc[property], copy);
+
+    if (nestedObject) {
+      delete nestedObject[propertyToRemove];
+    }
+  });
+
+  return copy;
+};

package/src/parsing/__tests__/parse-boolean.test.ts

@@ -0,0 +1,15 @@
+import { parseBoolean } from '../parse-boolean';
+
+describe('parseBoolean', () => {
+  it('should return true if value is "true"', () => {
+    expect(parseBoolean('true')).toStrictEqual(true);
+  });
+
+  it('should return false if value is "false"', () => {
+    expect(parseBoolean('false')).toStrictEqual(false);
+  });
+
+  it('should throw an exception if value is neither "true" nor "false"', () => {
+    expect(() => parseBoolean('value')).toThrow();
+  });
+});

package/src/parsing/__tests__/parse-enum.test.ts

@@ -0,0 +1,19 @@
+import { createEnumParser } from '../parse-enum';
+
+enum TestEnum {
+  FirstValue = 'first',
+  SecondValue = 'second',
+  ThirdValue = 'third',
+}
+
+describe('createEnumParser', () => {
+  const parseTestEnum = createEnumParser(TestEnum);
+
+  it('should return a valid enum parser', () => {
+    expect(parseTestEnum('second')).toStrictEqual(TestEnum.SecondValue);
+  });
+
+  it('should throw an error if the parsing did not work', () => {
+    expect(() => parseTestEnum('fourth')).toThrowError();
+  });
+});

package/src/parsing/__tests__/parse-number.test.ts

@@ -0,0 +1,20 @@
+import { parseNumber } from '../parse-number';
+
+describe('parseNumber', () => {
+  it('should return number 10 if value is "10', () => {
+    expect(parseNumber('10')).toStrictEqual(10);
+  });
+
+  it('should return -10 if value is "-10"', () => {
+    expect(parseNumber('-10')).toStrictEqual(-10);
+  });
+
+  it('should return 0 if value is "0"', () => {
+    expect(parseNumber('0')).toStrictEqual(0);
+  });
+
+  it('should throw an exception if value is not a number', () => {
+    expect(() => parseNumber('number')).toThrow();
+    expect(() => parseNumber('false')).toThrow();
+  });
+});

package/src/parsing/index.ts

@@ -0,0 +1,3 @@
+export * from './parse-boolean';
+export * from './parse-enum';
+export * from './parse-number';

package/src/parsing/parse-boolean.ts

@@ -0,0 +1,10 @@
+/**
+ * Parse a string to a boolean. Throw error if string is neither "true" nor "false"
+ */
+export const parseBoolean = (value: string): boolean => {
+  if (value !== 'true' && value !== 'false') {
+    throw new Error('Cannot parse value');
+  }
+
+  return value === 'true';
+};

package/src/parsing/parse-enum.ts

@@ -0,0 +1,16 @@
+import type { Primitive } from '../types';
+
+/**
+ * Factory to build enum to parse a string to an enum. Throw error if string is not an enum value
+ */
+export const createEnumParser = <E extends Record<string, Primitive>>(enumType: E) => (
+  (value: string) => {
+    const enumValues = Object.values(enumType);
+
+    if (!enumValues.includes(value as any)) {
+      throw new Error('Can\'t parse this value');
+    }
+
+    return value as unknown as E;
+  }
+);

package/src/parsing/parse-number.ts

@@ -0,0 +1,12 @@
+/**
+ * Parse a string to a number. Throw error if string is NaN
+ */
+export const parseNumber = (value: string): number => {
+  const number = parseInt(value, 10);
+
+  if (Number.isNaN(number)) {
+    throw new Error('Cannot parse value');
+  }
+
+  return number;
+};

package/src/predicates/__tests__/is-function.test.ts

@@ -0,0 +1,11 @@
+import { isFunction } from '../is-function';
+
+describe('isFunction', () => {
+  it('should return true if value is a function', () => {
+    expect(isFunction(() => {})).toBeTrue();
+  });
+
+  it('should return false if value is not a function', () => {
+    expect(isFunction('')).toBeFalse();
+  });
+});

package/src/predicates/__tests__/is-null.test.ts

@@ -0,0 +1,11 @@
+import { isNull } from '../is-null';
+
+describe('isNull', () => {
+  it('should return true if value is null', () => {
+    expect(isNull(null)).toBeTrue();
+  });
+
+  it('should return false if value is not null', () => {
+    expect(isNull('')).toBeFalse();
+  });
+});

package/src/predicates/__tests__/is-object.test.ts

@@ -0,0 +1,11 @@
+import { isObject } from '../is-object';
+
+describe('isObject', () => {
+  it('should return true if value is an object', () => {
+    expect(isObject({})).toBeTrue();
+  });
+
+  it('should return false if value is not an object', () => {
+    expect(isObject('')).toBeFalse();
+  });
+});