@sparted/shared-library 1.0.7 → 1.0.8-alpha.0

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

@@ -0,0 +1,50 @@
+import { ManipulationConfig, LinkedListItem } from './type';
+
+import {
+  findPreviousId,
+  assertItemCompatibility,
+  assertPresence,
+  assertNewNodePosition,
+} from './linked-list-utils';
+
+export const insertLinkedList = <T extends LinkedListItem>(item: T, config: ManipulationConfig<T>) => {
+  const { format, list, factory } = config;
+
+  assertItemCompatibility(item, format);
+  assertPresence(item.nextId, list.items);
+  assertPresence(item.previousId, list.items);
+
+  const hasPrevious = item.previousId !== undefined;
+
+  const previousId = hasPrevious
+    ? item.previousId!
+    : findPreviousId(item.nextId, list);
+
+  assertNewNodePosition(item, {
+    previousId,
+    list,
+  });
+
+  const newHeadId = item.nextId === list.headId ? item.id : list.headId;
+  const newItems = {
+    ...list.items,
+    ...(previousId ? {
+      [previousId]: {
+        ...list.items[previousId],
+        nextId: item.id,
+      },
+    } : {}),
+    ...(hasPrevious && item.nextId ? {
+      [item.nextId]: {
+        ...list.items[item.nextId],
+        ...(hasPrevious ? { previousId: item.id } : {}),
+      },
+    } : {}),
+    [item.id]: item,
+  };
+
+  return factory({
+    headId: newHeadId,
+    items: newItems,
+  });
+};

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

@@ -0,0 +1,143 @@
+import { runWhile } from '../fp';
+import { LinkedListFormat, LinkedListItem, SimpleLinkedList } from './type';
+
+export type WalkConfig<T extends LinkedListItem, Result> = {
+  startId: string | null,
+  items: Record<string, T>,
+  initValue: Result,
+};
+
+type WalkCallbackResult<R> = {
+  result: R,
+  control?: {
+    stop?: boolean,
+  },
+};
+
+export type WalkCallback<Item, Result> = (accumulator: Result, current: Item) => WalkCallbackResult<Result>;
+
+type RunWhileValue<T> = {
+  currentId: string | null,
+  accumulator: T,
+  control: WalkCallbackResult<any>['control'],
+};
+
+export const walkListItemRecord = <T extends LinkedListItem, Result>(
+  callback: WalkCallback<T, Result>,
+  config: WalkConfig<T, Result>,
+) => {
+  const { items, startId, initValue } = config;
+  const visited = new Set();
+  const totalNodes = Object.keys(items).length;
+
+  const { result } = runWhile({
+    iterationLimit: totalNodes + 1,
+    initialValue: {
+      currentId: startId,
+      accumulator: initValue,
+      control: {
+        stop: false,
+      },
+    } as RunWhileValue<Result>,
+    predicate: ({ control, currentId }) => {
+      const stop = control?.stop;
+      const forcedStop = stop === undefined ? false : stop;
+
+      /**
+       * Stop early or when the end is reached
+       */
+      return !forcedStop && currentId !== null;
+    },
+    callback: (current) => {
+      if (visited.has(current.currentId)) {
+        throw new Error('Infinite loop found');
+      }
+
+      visited.add(current.currentId);
+
+      const currentItem = items[current.currentId!];
+
+      if (!currentItem) {
+        throw new Error('Cul de sac detected');
+      }
+
+      const { result: currentResult, control } = callback(current.accumulator, currentItem);
+
+      return {
+        accumulator: currentResult,
+        currentId: currentItem.nextId,
+        control,
+      };
+    },
+  });
+
+  return result.accumulator;
+};
+
+export const findPreviousId = <T extends LinkedListItem>(id: string | null, list: SimpleLinkedList<T>) => {
+  if (id === list.headId) {
+    return null;
+  }
+
+  return walkListItemRecord(
+    (acc, current) => {
+      if (current.nextId === id) {
+        return {
+          result: current.id,
+          control: {
+            stop: true,
+          },
+        };
+      }
+
+      return {
+        result: acc,
+      };
+    },
+    {
+      initValue: null as null | string,
+      startId: list.headId,
+      items: list.items,
+    },
+  );
+};
+
+export const assertItemCompatibility = <T extends LinkedListItem>(item: T, format: LinkedListFormat | null) => {
+  /**
+   * An empty linked list won't have any format yet, it will be
+   * determined by the first item inserted in the list.
+   */
+  if (format === null) {
+    return;
+  }
+
+  const incompatibleWithDoubleLinks = item.previousId === undefined && format === 'double';
+  const incompatibleWithSingleLink = item.previousId !== undefined && format === 'single';
+
+  if (incompatibleWithDoubleLinks || incompatibleWithSingleLink) {
+    throw new Error(`Node is incompatible with the list (id: ${item.id})`);
+  }
+};
+
+export const assertPresence = (id: string | null | undefined, items: Record<string, unknown>) => {
+  if (id && !items[id]) {
+    throw new Error(`Node not found in the list (id: ${id})`);
+  }
+};
+
+type PositionAssertionConfig = {
+  previousId: string | null,
+  list: SimpleLinkedList<LinkedListItem>,
+};
+
+export const assertNewNodePosition = <T extends LinkedListItem>(item: T, config: PositionAssertionConfig) => {
+  const { previousId, list } = config;
+
+  const insertionMiddleError = previousId && list.items[previousId].nextId !== item.nextId;
+  const insertionTailError = previousId && item.nextId === null && list.items[previousId].nextId !== null;
+  const insertionHeadError = previousId === null && item.nextId !== list.headId;
+
+  if (insertionMiddleError || insertionTailError || insertionHeadError) {
+    throw new Error(`Invalid position for given node (id: ${item.id})`);
+  }
+};

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

@@ -0,0 +1,18 @@
+import { ReduceCallback, LinkedListItem, SimpleLinkedList } from './type';
+import { walkListItemRecord } from './linked-list-utils';
+
+export const reduceLinkedList = <Item extends LinkedListItem, Result>(
+  cb: ReduceCallback<Item, Result>,
+  initValue: Result,
+  list: SimpleLinkedList<Item>,
+): Result => {
+  const { items, headId } = list;
+
+  return walkListItemRecord((acc, current) => ({
+    result: cb(acc, current),
+  }), {
+    startId: headId,
+    items,
+    initValue,
+  });
+};

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

@@ -0,0 +1,36 @@
+import { ManipulationConfig, LinkedListItem } from './type';
+import { assertPresence, findPreviousId } from './linked-list-utils';
+
+export const removeLinkedList = <T extends LinkedListItem>(id: string, config: ManipulationConfig<T>) => {
+  const { format, list, factory } = config;
+  const { [id]: itemToDelete, ...otherItems } = list.items;
+
+  assertPresence(id, list.items);
+
+  const isDoubleLinkList = format === 'double';
+  const previousId = isDoubleLinkList
+    ? itemToDelete.previousId!
+    : findPreviousId(id, list);
+
+  const newHeadId = previousId === null ? itemToDelete.nextId : list.headId;
+  const newItems = {
+    ...otherItems,
+    ...(previousId ? {
+      [previousId]: {
+        ...otherItems[previousId],
+        nextId: itemToDelete.nextId,
+      },
+    } : {}),
+    ...(isDoubleLinkList && itemToDelete.nextId ? {
+      [itemToDelete.nextId]: {
+        ...otherItems[itemToDelete.nextId],
+        ...(isDoubleLinkList ? { previousId } : {}),
+      },
+    } : {}),
+  };
+
+  return factory({
+    headId: newHeadId,
+    items: newItems,
+  });
+};

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,29 @@
+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.
+   */
+  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__/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,4 @@
+export * from './clamp-number';
+export * from './interpolate';
+export * from './number-range';
+export * from './random-number';

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/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/index.ts

@@ -0,0 +1 @@
+export * from './merge-deep';

package/src/object/merge-deep.ts

@@ -0,0 +1,27 @@
+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) => {
+    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/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();
+  });
+});