@pcg/dynamic-components 1.0.0-alpha.0

package/src/paths/array-ops.ts

@@ -0,0 +1,124 @@
+import { isIndex, isObject } from '@/assertions/index.js';
+import { generateKeyBetween } from '@/dynamic-components/fractional-indexing.js';
+
+import { getIndexByArrayKey, isArrayKey } from './array-keys.js';
+import { getFromPath, setInPath } from './basic-ops.js';
+import { NestedRecord } from './types.js';
+
+/**
+ * Pushes a value into a nested array in an object using a path.
+ * @param {NestedRecord} object - The object to push the value into.
+ * @param {(string | number)[]} path - The path to the array in the object.
+ * @param {unknown} value - The value to push.
+ * @example
+ * let obj = { items: ['John'] };
+ * pushInPath(obj, ['items'], 'Jane');  // obj is now { items: ['John', 'Jane'] }
+ */
+export const pushInPath = (object: NestedRecord, path: (string | number)[], value: unknown) => {
+  const array = getFromPath(object, path);
+  if (!Array.isArray(array)) {
+    setInPath(object, path, [value]);
+  } else {
+    array.push(value);
+  }
+};
+
+/**
+ * Inserts values into a nested array in an object at a specified index or key using a path.
+ * @param {NestedRecord} object - The object to insert the values into.
+ * @param {(string | number)[]} path - The path to the array in the object.
+ * @param {string | number} keyOrIndex - The index or key at which to insert the values.
+ * @param {unknown[]} values - The values to insert.
+ * @example
+ * let obj = { items: ['John', 'Jane'] };
+ * insertInPath(obj, ['items'], 1, ['Joe']);  // obj is now { items: ['John', 'Joe', 'Jane'] }
+ */
+export const insertInPath = (object: NestedRecord, path: (string | number)[], keyOrIndex: string | number, values: unknown[]) => {
+  const array = getFromPath(object, path) as unknown[];
+
+  if (Array.isArray(array)) {
+    if (isIndex(keyOrIndex)) {
+      array.splice(keyOrIndex, 0, ...values);
+    } else if (isArrayKey(keyOrIndex)) {
+      const index = getIndexByArrayKey(array, keyOrIndex);
+      array.splice(index, 0, ...values);
+    }
+  }
+};
+
+/**
+ * Removes a value from a nested array in an object at a specified index or array key using a path.
+ * @param {NestedRecord} object - The object to remove the value from.
+ * @param {(string | number)[]} path - The path to the array in the object.
+ * @param {string | number} key - The index or key at which to remove the value.
+ * @example
+ * let obj = { items: ['John', 'Joe', 'Jane'] };
+ * pullFromPath(obj, ['items'], 1);  // obj is now { items: ['John', 'Jane'] }
+ */
+export const pullFromPath = (object: NestedRecord, path: (string | number)[], key: string | number) => {
+  const array = getFromPath(object, path) as unknown[];
+
+  if (Array.isArray(array)) {
+    if (isIndex(key)) {
+      array.splice(key, 1);
+    } else if (isArrayKey(key)) {
+      const index = getIndexByArrayKey(array, key);
+      array.splice(index, 1);
+    }
+  }
+};
+
+const printPosition = (array: { position?: string }[]) => array.map((it) => isObject(it) ? it.position ?? 'no-position' : 'not-object');
+
+/**
+ * Moves an item to a new position relative to another item in the array or object at the specified path.
+ *
+ * @example
+ * moveInYPath(values, ['components'], 'a0', 'b1', 'after');
+ */
+export const moveInPath = (
+  object: NestedRecord,
+  path: (string | number)[],
+  oldPosition: string,
+  relativePosition: string,
+  insert: 'before' | 'after',
+) => {
+  const array = getFromPath(object, path);
+  if (!Array.isArray(array)) {
+    throw new Error(`Can't move. Target item is not array in path ${JSON.stringify(path)}`);
+  }
+
+  const item = array.find((it) => isObject(it) && it.position === oldPosition);
+  const relativeItemIndex = array.findIndex((it) => isObject(it) && it.position === relativePosition);
+
+  if (!isObject(item)) {
+    throw new Error(`Can't move. Item in position ${oldPosition} not found. ${printPosition(array)}`);
+  }
+
+  if (relativeItemIndex === -1) {
+    throw new Error(`Can't move. Relative item in position ${relativePosition} not found. ${printPosition(array)}`);
+  }
+
+  const relativeItem = array[relativeItemIndex];
+  if (!isObject(relativeItem)) {
+    throw new Error(`Can't move. Relative item in position ${relativePosition} must be an object. ${printPosition(array)}`);
+  }
+
+  if (insert === 'before') {
+    const left = array[relativeItemIndex - 1];
+    const leftPosition = isObject(left) ? left.position as string ?? null : null;
+
+    const newPosition = generateKeyBetween(leftPosition, relativeItem.position as string);
+    item.position = newPosition;
+
+    return newPosition;
+  }
+
+  const right = array[relativeItemIndex + 1];
+  const rightPosition = isObject(right) ? right.position as string ?? null : null;
+
+  const newPosition = generateKeyBetween(relativeItem.position as string, rightPosition);
+  item.position = newPosition;
+
+  return newPosition;
+};

package/src/paths/basic-ops.ts

@@ -0,0 +1,181 @@
+// Paths is an array with keys and indexes that represent a path to a value in a deep object.
+// For example, for the object { items: [{ name: 'John' }]} the path to the first item name is ['items', 0, 'name'].
+
+import {
+  isContainerValue, isIndex, isNullOrUndefined, isObject,
+} from '@/assertions/index.js';
+
+import { getIndexByArrayKey, isArrayKey } from './array-keys.js';
+import { NestedRecord } from './types.js';
+
+/**
+ * Gets a nested property value from an object using a path.
+ * @param {NestedRecord | undefined} object - The object to get the value from.
+ * @param {(string | number)[]} path - The path to the value in the object.
+ * @returns {TValue | undefined} Returns the value at the specified path in the object.
+ * @example
+ * getFromPath({ items: [{ name: 'John' }] }, ['items', 0, 'name']);  // Returns 'John'
+ */
+export const getFromPath = <TValue = unknown>(object: NestedRecord | undefined, path: (string | number)[]): TValue | undefined => {
+  if (!object) {
+    return;
+  }
+
+  if (path.length === 0) {
+    return object as TValue;
+  }
+
+  const resolvedValue = path
+    .reduce((acc, propKey) => {
+      const key = isArrayKey(propKey) ? getIndexByArrayKey(acc, propKey) : propKey;
+
+      if (isContainerValue(acc) && key in acc) {
+        return acc[key];
+      }
+
+      return;
+    }, object as unknown);
+
+  return resolvedValue as TValue | undefined;
+};
+
+/**
+ * Sets a nested property value in a path, creates the path properties if they don't exist.
+ * @param {NestedRecord} object - The object to set the value in.
+ * @param {(string | number)[]} path - The path to the value in the object.
+ * @param {unknown} value - The value to set.
+ * @example
+ * let obj = { items: [{ name: 'John' }] };
+ * setInPath(obj, ['items', 0, 'name'], 'Jane');  // obj is now { items: [{ name: 'Jane' }] }
+ */
+export const setInPath = (object: NestedRecord, path: (string | number)[], value: unknown): void => {
+  let acc = object;
+  for (const [i, rawKey] of path.entries()) {
+    const key = isArrayKey(rawKey) ? getIndexByArrayKey(acc, rawKey) : rawKey;
+
+    if (Array.isArray(acc)) {
+      const index = Number(key);
+
+      // Last key, set it
+      if (i === path.length - 1) {
+        acc[index] = value;
+
+        return;
+      }
+
+      // Key does not exist, create a container for it
+      if (!(index in acc) || isNullOrUndefined(acc[index])) {
+        const nextRawKey = path[i + 1];
+        const nextKey = isArrayKey(nextRawKey) ? getIndexByArrayKey(acc, nextRawKey) : nextRawKey;
+        // container can be either an object or an array depending on the next key if it exists
+        acc[index] = isIndex(nextKey) ? [] : {
+        };
+      }
+
+      acc = acc[index] as Record<string, unknown>;
+    } else {
+      // Last key, set it
+      if (i === path.length - 1) {
+        acc[key] = value;
+
+        return;
+      }
+
+      // Key does not exist, create a container for it
+      if (!(key in acc) || isNullOrUndefined(acc[key])) {
+        const nextRawKey = path[i + 1];
+        const nextKey = isArrayKey(nextRawKey) ? getIndexByArrayKey(acc, nextRawKey) : nextRawKey;
+        // container can be either an object or an array depending on the next key if it exists
+        acc[key] = isIndex(nextKey) ? [] : {
+        };
+      }
+
+      acc = acc[key] as Record<string, unknown>;
+    }
+  }
+};
+
+const unset = (object: Record<string, unknown> | unknown[], key: string | number) => {
+  if (Array.isArray(object) && isIndex(key)) {
+    object.splice(Number(key), 1);
+
+    return;
+  }
+
+  if (isObject(object)) {
+    delete object[key];
+  }
+};
+
+/**
+ * Removes a nested property from an object using a path.
+ * @param {NestedRecord} object - The object to remove the value from.
+ * @param {(string | number)[]} path - The path to the value in the object.
+ * @example
+ * let obj = { items: [{ name: 'John' }] };
+ * unsetPath(obj, ['items', 0, 'name']);  // obj is now { items: [{}] }
+ */
+export const unsetPath = (object: NestedRecord, path: (string | number)[]): void => {
+  let acc = object;
+  for (const [i, rawKey] of path.entries()) {
+    const key = isArrayKey(rawKey) ? getIndexByArrayKey(acc, rawKey) : rawKey;
+
+    // Last key, unset it
+    if (i === path.length - 1) {
+      unset(acc, key);
+      break;
+    }
+
+    if (Array.isArray(acc)) {
+      const index = Number(key);
+
+      // Key does not exist, exit
+      if (!(key in acc) || isNullOrUndefined(acc[index])) {
+        break;
+      }
+
+      acc = acc[index] as Record<string, unknown>;
+    } else {
+      // Key does not exist, exit
+      if (!(key in acc) || isNullOrUndefined(acc[key])) {
+        break;
+      }
+
+      acc = acc[key] as Record<string, unknown>;
+    }
+  }
+};
+
+/** Checks if a nested property exists in an object using a path.
+ * @param {NestedRecord | undefined} object - The object to check the value in.
+ * @param {(string | number)[]} path - The path to the value in the object.
+ * @returns {boolean} Returns true if the value exists at the specified path, false otherwise.
+ * @example
+ * existsInPath({ items: [{ name: 'John' }] }, ['items', 0, 'name']);  // Returns true
+ * existsInPath({ items: [{ name: 'John' }] }, ['items', 1, 'name']);  // Returns false
+ */
+export const existsInPath = (object: NestedRecord | undefined, path: (string | number)[]): boolean => {
+  return getFromPath(object, path) !== undefined;
+};
+
+/** * Compares two paths for equality.
+ * @param {(string | number)[]} pathA - The first path to compare.
+ * @param {(string | number)[]} pathB - The second path to compare.
+ * @returns {boolean} Returns true if the paths are equal, false otherwise.
+ * @example
+ * isSamePath(['items', 0, 'name'], ['items', 0, 'name']);  // Returns true
+ * isSamePath(['items', 0, 'name'], ['items', 1, 'name']);  // Returns false
+ */
+export const isSamePath = (pathA: (string | number)[], pathB: (string | number)[]): boolean => {
+  if (pathA.length !== pathB.length) {
+    return false;
+  }
+
+  for (let i = 0; i < pathA.length; i++) {
+    if (pathA[i] !== pathB[i]) {
+      return false;
+    }
+  }
+
+  return true;
+};

package/src/paths/constants.ts

@@ -0,0 +1 @@
+export const PATH_REGEXP = /\.|\[(\d+)\]/;

package/src/paths/index.ts

@@ -0,0 +1,7 @@
+export * from './array-keys.js';
+export * from './array-ops.js';
+export * from './basic-ops.js';
+export * from './constants.js';
+export * from './tools.js';
+export * from './types.js';
+

package/src/paths/tools.ts

@@ -0,0 +1,42 @@
+import { isString } from '@/assertions/index.js';
+
+/**
+ * Joins a path with additional items.
+ * @param {(string | number)[]} path - The initial path.
+ * @param {...(string | number)[]} items - The items to add to the path.
+ * @returns {(string | number)[]} Returns the joined path.
+ * @throws {Error} If `path` is not an array or if any of `items` are not a string or an integer.
+ * @example
+ * joinPath(['items', 'id:xxx'], 'name');  // Returns ['items', 'id:xxx', 'name']
+ */
+export const joinPath = (path: (string | number)[], ...items: (string | number)[]) => {
+  if (!Array.isArray(path)) {
+    throw new Error(`path must be array: ${path}`);
+  }
+
+  for (const item of items) {
+    if (!isString(item) && !Number.isInteger(item)) {
+      throw new Error(`Invalid path item: ${item}`);
+    }
+  }
+
+  return path.concat(items);
+};
+
+/**
+ * Compares two fractional-based position strings for sorting.
+ * @param {string} aPosition - The first fractional-based position string.
+ * @param {string} bPosition - The second fractional-based position string.
+ * @returns {number} Returns -1 if `aPosition` comes before `bPosition`, 1 if `aPosition` comes after `bPosition`, or 0 if they are equal.
+ * @example
+ * sortByPosition('a1', 'a2');  // Returns -1
+ */
+export const sortByPosition = (aPosition: string, bPosition: string) => {
+  if (aPosition < bPosition) {
+    return -1;
+  } else if (aPosition > bPosition) {
+    return 1;
+  }
+
+  return 0;
+};

package/src/paths/types.ts

@@ -0,0 +1,133 @@
+/**
+ * The NestedRecord type represents a deeply nested object structure. It can be one of the following:
+ * - A Record with string keys and unknown values
+ * - An object with string keys and NestedRecord values
+ * - An array of NestedRecords
+ * - An array of unknown values
+ *
+ * This type is useful when working with deeply nested data structures where the shape of the data is not known beforehand.
+ *
+ * @example
+ * let record: NestedRecord = {
+ *   key: "value",
+ *   nested: {
+ *     innerKey: "innerValue",
+ *     array: [
+ *       {
+ *         deepKey: "deepValue"
+ *       }
+ *     ]
+ *   },
+ * };
+ */
+export type NestedRecord = Record<string, unknown> | { [k: string]: NestedRecord } | NestedRecord[] | unknown[];
+/**
+ * Represents the payload for a set operation in a NestedRecord.
+ */
+
+export interface SetPayload<T> {
+  /**
+   * The path to the field in the NestedRecord.
+   */
+  path: (string | number)[];
+
+  /**
+   * The real path to the field in the NestedRecord, represented as an array of component (editor) IDs.
+   */
+  rpath: string[];
+
+  /**
+   * The change like input letter in text input
+   */
+  atomic?: boolean;
+
+  /**
+   * The new value for the field.
+   */
+  value: T;
+}
+
+/**
+ * Represents the payload for an unset operation in a NestedRecord.
+ */
+export interface UnsetPayload {
+  /**
+   * The path to the field in the NestedRecord.
+   */
+  path: (string | number)[];
+
+  /**
+   * The real path to the field in the NestedRecord, represented as an array of component (editor) IDs.
+   */
+  rpath: string[];
+}
+
+/**
+ * Represents the payload for a push operation in a NestedRecord.
+ */
+export interface PushPayload<T> {
+  /**
+   * The path to the field in the NestedRecord.
+   */
+  path: (string | number)[];
+
+  /**
+   * The real path to the field in the NestedRecord, represented as an array of component (editor) IDs.
+   */
+  rpath: string[];
+
+  /**
+   * The value to push into the field.
+   */
+  value: T;
+}
+
+/**
+ * Represents the payload for a pull operation in a NestedRecord.
+ */
+export interface PullPayload {
+  /**
+   * The path to the field in the NestedRecord.
+   */
+  path: (string | number)[];
+
+  /**
+   * The real path to the field in the NestedRecord, represented as an array of component (editor) IDs.
+   */
+  rpath: string[];
+
+  /**
+   * The key of the value to pull from the field.
+   */
+  key: string | number;
+}
+
+/**
+ * Represents the payload for a move operation in a NestedRecord.
+ */
+export interface MovePayload {
+  /**
+   * The path to the field in the NestedRecord.
+   */
+  path: (string | number)[];
+
+  /**
+   * The real path to the field in the NestedRecord, represented as an array of component (editor) IDs.
+   */
+  rpath: string[];
+
+  /**
+   * The old fractional position of the field
+   */
+  oldPosition: string;
+
+  /**
+   * The fractional position of the related field, rely on which the field should be moved.
+   */
+  relativePosition: string;
+
+  /**
+   * Indicates whether the field should be inserted before or after the relative position.
+   */
+  insert: 'before' | 'after';
+}

package/src/y-components/index.ts

@@ -0,0 +1,3 @@
+export * from './tools.js';
+export * from './types.js';
+