@rimbu/deep 0.11.2 → 0.12.0

package/src/patch.ts

@@ -1,257 +1,254 @@
-import {
-  RimbuError,
-  type AnyFunc,
-  isPlainObj,
-  type PlainObj,
-} from '@rimbu/base';
+import { IsAnyFunc, IsArray, isPlainObj, IsPlainObj } from '@rimbu/base';
 
 import type { Protected } from './internal';
+import type { Tuple } from './tuple';
 
 /**
  * A type to determine the allowed input type for the `patch` function.
  * @typeparam T - the input type to be patched
  */
-export type Patch<T> = Patch.Entry<T, T>;
+export type Patch<T, C = T> = Patch.Entry<T, C, T, T>;
 
 export namespace Patch {
   /**
    * The entry type for a (nested) patch. Can be either a patch object or a function accepting the nested patch function and returning a patch object.
    * @typeparam T - the input value type
+   * @typeparam C - a utility type
+   * @typeparam P - the parent type
    * @typeparam R - the root object type
    */
-  export type Entry<T, R> =
-    | Patch.Obj<T, R>
-    | ((patchNested: Patch.Nested) => Patch.Obj<T, R>);
+  export type Entry<T, C, P, R> = IsAnyFunc<T> extends true
+    ? T
+    : IsPlainObj<T> extends true
+    ? Patch.WithResult<T, P, R, Patch.Obj<T, C, R>>
+    : Tuple.IsTuple<T> extends true
+    ? Patch.WithResult<T, P, R, T | Patch.Tup<T, C, R>>
+    : IsArray<T> extends true
+    ? Patch.WithResult<T, P, R, T>
+    : Patch.WithResult<T, P, R, T>;
 
   /**
-   * The object patch type, allows the user to specify keys in T that should be patched, and each given key contains either a new value or a nested patch, or a function receiving
-   * the current value, the parent object, and the root object, and returning a new value or a nested patch.
-   * @typeparam T - the input value type
-   * @typeparam R - the root object type
+   * Either result type S, or a patch function with the value type, the parent type, and the root type.
+   * @typeparam T - the value type
+   * @typeparam P - the parent type
+   * @typeparam R - the root type
+   * @typeparam S - the result type
    */
-  export type Obj<T, R> = {
-    [K in keyof T]?:
-      | (T[K] extends AnyFunc ? never : ObjItem<T[K], R>)
-      | ((
-          cur: Protected<T[K]>,
-          parent: Protected<T>,
-          root: Protected<R>
-        ) => ObjItem<T[K], R>);
-  };
+  export type WithResult<T, P, R, S> = S | Patch.Func<T, P, R, S>;
 
   /**
-   * A patch object can have as update either a new value or a nested patch object
-   * @typeparam T - the input value type
-   * @typeparam R - the root object type
+   * A function patch type that is a function taking the current value, the parent and root values,
+   * and returns a return value.
+   * @typeparam T - the value type
+   * @typeparam P - the parent type
+   * @typeparam R - the root type
+   * @typeparam S - the result type
    */
-  export type ObjItem<T, R> = T | NestedObj<T, R>;
+  export type Func<T, P, R, S> = (
+    current: Protected<T>,
+    parent: Protected<P>,
+    root: Protected<R>
+  ) => Protected<S>;
 
   /**
-   * The function type to create a nested Patch object.
+   * A type defining the allowed patch values for tuples.
+   * @typeparam T - the input tuple type
+   * @typeparam C - a utility type
+   * @typeparam R - the root type
    */
-  export type Nested = typeof patchNested;
+  export type Tup<T, C, R> = {
+    [K in Tuple.KeysOf<T>]?: Patch.Entry<T[K & keyof T], C[K & keyof C], T, R>;
+  } & NotIterable;
 
   /**
-   * Returns a function that patches a given `value` with the given `patchItems`.
-   * @typeparam T - the patch value type
-   * @typeparam Q - the input value type
-   * @param patchItems - a number of `Patch` objects that patch a given value of type T.
-   * @example
-   * ```ts
-   * const items = [{ a: 1, b: 'a' }, { a: 2, b: 'b' }]
-   * items.map(Patch.create({ a: v => v + 1 }))
-   * // => [{ a: 2, b: 'a' }, { a: 3, b: 'b' }]
-   * ```
+   * Utility type to exclude Iterable types.
    */
-  export function create<T, Q extends T = T>(
-    ...patchItems: Patch<T & Q>[]
-  ): (value: Q & PlainObj<Q>) => Q {
-    return (value) => patch<Q>(value, ...patchItems);
-  }
-}
+  export type NotIterable = {
+    [Symbol.iterator]?: never;
+  };
 
-class NestedObj<T, R, Q extends T = T> {
-  constructor(readonly patchDataItems: Patch.Obj<Q, R>[]) {}
-}
+  /**
+   * A type defining the allowed patch values for objects.
+   * @typeparam T - the input value type
+   * @typeparam C - a utility type
+   * @typeparam R - the root object type
+   */
+  export type Obj<T, C, R> = T | Patch.ObjProps<T, C, R>[];
 
-/**
- * Returns a nested patch object based on the given `patchDataItems` that work on a subpart
- * of a larger object to be patched.
- * @typeparam T - the input value type
- * @typeparam R - the root object type
- * @typeparam Q - the patch type
- * @param patchDataItems - a number of `Patch` objects to be applied to the subpart of the object
- * @example
- * ```ts
- * patch({ a: 1, b: { c: true, d: 'a' } }, { b: patchNested({ d: 'b' }) })
- * // => { a: 1, b: { c: true, d: 'b' } }
- * ```
- */
-export function patchNested<T, R, Q extends T = T>(
-  ...patchDataItems: Patch.Obj<Q, R>[]
-): NestedObj<T, R, Q> {
-  return new NestedObj(patchDataItems);
+  /**
+   * A type defining the allowed patch values for object properties.
+   * @typeparam T - the input value type
+   * @typeparam C - a utility type
+   * @typeparam R - the root object type
+   */
+  export type ObjProps<T, C, R> = {
+    [K in keyof C]?: K extends keyof T ? Patch.Entry<T[K], C[K], T, R> : never;
+  };
 }
 
 /**
  * Returns an immutably updated version of the given `value` where the given `patchItems` have been
  * applied to the result.
+ * The Rimbu patch notation is as follows:
+ * - if the target is a simple value or array, the patch can be the same type or a function returning the same type
+ * - if the target is a tuple (array of fixed length), the patch be the same type or an object containing numeric keys with patches indicating the tuple index to patch
+ * - if the target is an object, the patch can be the same type, or an array containing partial keys with their patches for the object
+ * @typeparam T - the type of the value to patch
+ * @typeparam TE - a utility type
+ * @typeparam TT - a utility type
  * @param value - the input value to patch
- * @param patchItems - the `Patch` objects to apply to the input value
+ * @param patchItem - the `Patch` value to apply to the input value
  * @example
  * ```ts
  * const input = { a: 1, b: { c: true, d: 'a' } }
- * patch(input, { a: 2 })  // => { a: 2, b: { c: true, d: 'a' } }
- * patch(input: ($) => ({ b: $({ c: v => !v }) }) )
+ * patch(input, [{ a: 2 }])  // => { a: 2, b: { c: true, d: 'a' } }
+ * patch(input, [{ b: [{ c: (v) => !v }] }] )
  * // => { a: 1, b: { c: false, d: 'a' } }
- * patch(input: ($) => ({ a: v => v + 1, b: $({ d: 'q' }) }) )
+ * patch(input: [{ a: (v) => v + 1, b: [{ d: 'q' }] }] )
  * // => { a: 2, b: { c: true, d: 'q' } }
  * ```
  */
-export function patch<T>(value: T & PlainObj<T>, ...patchItems: Patch<T>[]): T {
-  const newValue = isPlainObj(value) ? { ...value } : value;
-  const changedRef = { changed: false };
-
-  const result = processPatch(newValue, newValue, patchItems, changedRef);
-
-  if (changedRef.changed) return result;
-
-  return value;
-}
-
-/**
- * Interface providing a shared reference to a `changed` boolean.
- */
-interface ChangedRef {
-  changed: boolean;
-}
-
-function processPatch<T, R>(
+export function patch<T, TE extends T = T, TT = T>(
   value: T,
-  root: R,
-  patchDataItems: Patch.Entry<T, R>[],
-  changedRef: ChangedRef
+  patchItem: Patch<TE, TT>
 ): T {
-  let i = -1;
-  const len = patchDataItems.length;
-
-  while (++i < len) {
-    const patchItem = patchDataItems[i];
-    if (patchItem instanceof Function) {
-      const item = patchItem(patchNested);
-      if (item instanceof NestedObj) {
-        processPatch(value, root, item.patchDataItems, changedRef);
-      } else {
-        processPatchObj(value, root, item, changedRef);
-      }
-    } else {
-      processPatchObj(value, root, patchItem, changedRef);
-    }
-  }
-
-  return value;
+  return patchEntry(value, value, value, patchItem as Patch<T>);
 }
 
-function processPatchObj<T, R>(
+function patchEntry<T, C, P, R>(
   value: T,
+  parent: P,
   root: R,
-  patchData: Patch.Obj<T, R>,
-  changedRef: ChangedRef
+  patchItem: Patch.Entry<T, C, P, R>
 ): T {
-  if (undefined === value || null === value) {
+  if (Object.is(value, patchItem)) {
+    // patching a value with itself never changes the value
     return value;
   }
 
-  if (!isPlainObj(patchData)) {
-    RimbuError.throwInvalidUsageError(
-      'patch: received patch object should be a plain object'
-    );
+  if (typeof value === 'function') {
+    // function input, directly return patch
+    return patchItem as T;
   }
 
-  if (!isPlainObj(value)) {
-    RimbuError.throwInvalidUsageError(
-      'patch: received source object should be a plain object'
-    );
+  if (typeof patchItem === 'function') {
+    // function patch always needs to be resolved first
+    const item = patchItem(value, parent, root);
+
+    return patchEntry(value, parent, root, item);
   }
 
-  for (const key in patchData) {
-    const target = value[key];
+  if (isPlainObj(value)) {
+    // value is plain object
+    return patchPlainObj(value, root, patchItem as any);
+  }
 
-    // prevent prototype pollution
-    if (
-      key === '__proto__' ||
-      (key === 'constructor' && target instanceof Function)
-    ) {
-      RimbuError.throwInvalidUsageError(
-        `patch: received patch object key '${key}' which is not allowed to prevent prototype pollution`
-      );
-    }
+  if (Array.isArray(value)) {
+    // value is tuple or array
+    return patchArr(value, root, patchItem as any);
+  }
 
-    const update = patchData[key];
+  // value is primitive type or complex object
 
-    if (!(key in value) && update instanceof Function) {
-      RimbuError.throwInvalidUsageError(
-        `patch: received update function object key ${key} but the key was not present in the source object. Either explicitely set the value in the source to undefined or use a direct value.`
-      );
-    }
+  return patchItem as T;
+}
 
-    if (undefined === update) {
-      RimbuError.throwInvalidUsageError(
-        "patch: received 'undefined' as patch value. Due to type system issues we cannot prevent this through typing, but please use '() => undefined'  or '() => yourVar' instead. This value will be ignored for safety."
-      );
-    }
+function patchPlainObj<T, C, R>(
+  value: T,
+  root: R,
+  patchItem: T | Patch.Obj<T, C, R>
+): T {
+  if (!Array.isArray(patchItem)) {
+    // the patch is a complete replacement of the current value
 
-    let newValue: typeof target;
+    return patchItem as T;
+  }
+
+  // patch is an array of partial updates
+
+  // copy the input value
+  const result = { ...value };
+
+  let anyChange = false;
+
+  // loop over patches in array
+  for (const entry of patchItem) {
+    // update root if needed
+    const currentRoot = (value as any) === root ? { ...result } : root;
 
-    if (update instanceof Function) {
-      newValue = processPatchObjItem(
-        target,
-        root,
-        update(target, value, root),
-        changedRef
+    // loop over all the patch keys
+    for (const key in entry as T) {
+      // patch the value at the given key with the patch at that key
+      const currentValue = result[key];
+      const newValue = patchEntry(
+        currentValue,
+        value,
+        currentRoot,
+        (entry as any)[key]
       );
-    } else {
-      newValue = processPatchObjItem(
-        target,
-        root,
-        update as any,
-        changedRef
-      ) as any;
-    }
 
-    if (!Object.is(newValue, target)) {
-      value[key] = newValue;
-      changedRef.changed = true;
+      if (!Object.is(currentValue, newValue)) {
+        // if value changed, set it in result and mark change
+        anyChange = true;
+        result[key] = newValue;
+      }
     }
   }
 
+  if (anyChange) {
+    // something changed, return new value
+    return result;
+  }
+
+  // nothing changed, return old value
   return value;
 }
 
-function processPatchObjItem<T, R>(
+function patchArr<T extends any[], C, R>(
   value: T,
   root: R,
-  patchResult: Patch.ObjItem<T, R>,
-  superChangedRef: ChangedRef
+  patchItem: T | Patch.Tup<T, C, R>
 ): T {
-  if (patchResult instanceof NestedObj) {
-    const newValue = isPlainObj(value) ? { ...value } : value;
-    const changedRef = { changed: false };
+  if (Array.isArray(patchItem)) {
+    // value is a normal array
+    // patch is a complete replacement of current array
 
-    const result = processPatch(
-      newValue,
+    return patchItem;
+  }
+
+  // value is a tuple
+  // patch is an object containing numeric keys with function values
+  // that update the tuple at the given indices
+
+  // copy the tuple
+  const result = [...value] as T;
+  let anyChange = false;
+
+  // loop over all index keys in object
+  for (const index in patchItem) {
+    const numIndex = index as any as number;
+
+    // patch the tuple at the given index
+    const currentValue = result[numIndex];
+    const newValue = patchEntry(
+      currentValue,
+      value,
       root,
-      patchResult.patchDataItems,
-      changedRef
+      (patchItem as any)[index]
     );
 
-    if (changedRef.changed) {
-      superChangedRef.changed = true;
-      return result;
+    if (!Object.is(newValue, currentValue)) {
+      // if value changed, set it in result and mark change
+      anyChange = true;
+      result[numIndex] = newValue;
     }
+  }
 
-    return value;
+  if (anyChange) {
+    // something changed, return new value
+    return result;
   }
 
-  return patchResult;
+  // nothing changed, return old value
+  return value;
 }