@rimbu/deep 2.0.3 → 2.0.5

package/dist/bun/patch.mts

@@ -1,263 +0,0 @@
-import {
-  type IsAnyFunc,
-  type IsArray,
-  isPlainObj,
-  type IsPlainObj,
-} from '@rimbu/base';
-
-import type { Protected } from './internal.mts';
-import type { Tuple } from './tuple.mts';
-
-/**
- * A type to determine the allowed input type for the `patch` function.
- * @typeparam T - the input type to be patched
- */
-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, 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>;
-
-  /**
-   * 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 WithResult<T, P, R, S> = S | Patch.Func<T, P, R, S>;
-
-  /**
-   * 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 Func<T, P, R, S> = (
-    current: Protected<T>,
-    parent: Protected<P>,
-    root: Protected<R>
-  ) => Protected<S>;
-
-  /**
-   * 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 Tup<T, C, R> = {
-    [K in Tuple.KeysOf<T>]?: Patch.Entry<T[K & keyof T], C[K & keyof C], T, R>;
-  } & NotIterable;
-
-  /**
-   * Utility type to exclude Iterable types.
-   */
-  export type NotIterable = {
-    [Symbol.iterator]?: never;
-  };
-
-  /**
-   * 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>[];
-
-  /**
-   * 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 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 }] }] )
- * // => { a: 1, b: { c: false, d: 'a' } }
- * patch(input, [{ a: (v) => v + 1, b: [{ d: 'q' }] }] )
- * // => { a: 2, b: { c: true, d: 'q' } }
- * ```
- */
-export function patch<T, TE extends T = T, TT = T>(
-  value: T,
-  patchItem: Patch<TE, T & TT>
-): T {
-  return patchEntry(value, value, value, patchItem as Patch<T>);
-}
-
-function patchEntry<T, C, P, R>(
-  value: T,
-  parent: P,
-  root: R,
-  patchItem: Patch.Entry<T, C, P, R>
-): T {
-  if (Object.is(value, patchItem)) {
-    // patching a value with itself never changes the value
-    return value;
-  }
-
-  if (typeof value === 'function') {
-    // function input, directly return patch
-    return patchItem as T;
-  }
-
-  if (typeof patchItem === 'function') {
-    // function patch always needs to be resolved first
-    const item = patchItem(value, parent, root);
-
-    return patchEntry(value, parent, root, item);
-  }
-
-  if (isPlainObj(value)) {
-    // value is plain object
-    return patchPlainObj(value, root, patchItem as any);
-  }
-
-  if (Array.isArray(value)) {
-    // value is tuple or array
-    return patchArr(value, root, patchItem as any);
-  }
-
-  // value is primitive type or complex object
-
-  return patchItem as T;
-}
-
-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
-
-    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;
-
-    // keep current updated result as parent
-    const parent = { ...result };
-
-    // 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,
-        parent,
-        currentRoot,
-        (entry as any)[key]
-      );
-
-      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 patchArr<T extends any[], C, R>(
-  value: T,
-  root: R,
-  patchItem: T | Patch.Tup<T, C, R>
-): T {
-  if (Array.isArray(patchItem)) {
-    // value is a normal array
-    // patch is a complete replacement of current array
-
-    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,
-      (patchItem as any)[index]
-    );
-
-    if (!Object.is(newValue, currentValue)) {
-      // if value changed, set it in result and mark change
-      anyChange = true;
-      result[numIndex] = newValue;
-    }
-  }
-
-  if (anyChange) {
-    // something changed, return new value
-    return result;
-  }
-
-  // nothing changed, return old value
-  return value;
-}

package/dist/bun/path.mts

@@ -1,428 +0,0 @@
-import type { IsAnyFunc, IsArray, IsPlainObj } from '@rimbu/base';
-import { Deep, type Patch } from './internal.mts';
-import type { Tuple } from './tuple.mts';
-
-export namespace Path {
-  /**
-   * A string representing a path into an (nested) object of type T.
-   * @typeparam T - the object type to select in
-   * @example
-   * ```ts
-   * const p: Path.Get<{ a: { b: { c : 5 } } }> = 'a.b'
-   * ```
-   */
-  export type Get<T> = Path.Internal.Generic<T, false, false, true>;
-
-  /**
-   * A string representing a path into an (nested) object of type T.
-   * @typeparam T - the object type to select in
-   * @example
-   * ```ts
-   * const p: Path.Set<{ a: { b: { c : 5 } } }> = 'a.b'
-   * ```
-   */
-  export type Set<T> = Path.Internal.Generic<T, true, false, true>;
-
-  export namespace Internal {
-    /**
-     * Determines the allowed paths into a value of type `T`.
-     * @typeparam T - the source type
-     * @typeparam Write - if true the path should be writable (no optional chaining)
-     * @typeparam Maybe - if true the value at the current path is optional
-     * @typeparam First - if true this is the root call
-     * @note type is mapped as template literal to prevent non-string types to leak through
-     */
-    export type Generic<
-      T,
-      Write extends boolean,
-      Maybe extends boolean,
-      First extends boolean = false,
-    > = `${IsAnyFunc<T> extends true
-      ? // functions can not be further decomposed
-        ''
-      : // empty string is always an option
-        '' | Path.Internal.NonEmpty<T, Write, Maybe, First>}`;
-
-    /**
-     * Determines the allowed non-empty paths into a value of type `T`.
-     * @typeparam T - the source type
-     * @typeparam Write - if true the path should be writable (no optional chaining)
-     * @typeparam Maybe - if true the value at the current path is optional
-     * @typeparam First - if true this is the root call
-     */
-    export type NonEmpty<
-      T,
-      Write extends boolean,
-      Maybe extends boolean,
-      First extends boolean,
-    > =
-      Path.Internal.IsOptional<T> extends true
-        ? // the value T may be null or undefined, check whether further chaining is allowed
-          Write extends false
-          ? // path is not used to write to, so optional chaining is allowed
-            Path.Internal.Generic<Exclude<T, undefined | null>, Write, true>
-          : // path can be written to, no optional chaining allowed
-            never
-        : // determine separator, and continue with non-optional value
-          `${Path.Internal.Separator<
-            First,
-            Maybe,
-            IsArray<T>
-          >}${Path.Internal.NonOptional<T, Write, Maybe>}`;
-
-    /**
-     * Determines the allowed paths into a non-optional value of type `T`.
-     * @typeparam T - the source type
-     * @typeparam Write - if true the path should be writable (no optional chaining)
-     * @typeparam Maybe - if true the value at the current path is optional
-     */
-    export type NonOptional<T, Write extends boolean, Maybe extends boolean> =
-      Tuple.IsTuple<T> extends true
-        ? // determine allowed paths for tuple
-          Path.Internal.Tup<T, Write, Maybe>
-        : T extends readonly any[]
-          ? // determine allowed paths for array
-            Write extends false
-            ? // path is not writable so arrays are allowed
-              Path.Internal.Arr<T>
-            : // path is writable, no arrays allowed
-              never
-          : IsPlainObj<T> extends true
-            ? // determine allowed paths for object
-              Path.Internal.Obj<T, Write, Maybe>
-            : // no match
-              never;
-
-    /**
-     * Determines the allowed paths for a tuple. Since tuples have fixed types, they do not
-     * need to be optional, in contrast to arrays.
-     * @typeparam T - the input tuple type
-     * @typeparam Write - if true the path should be writable (no optional chaining)
-     * @typeparam Maybe - if true the value at the current path is optional
-     */
-    export type Tup<T, Write extends boolean, Maybe extends boolean> = {
-      [K in Tuple.KeysOf<T>]: `[${K}]${Path.Internal.Generic<T[K], Write, Maybe>}`;
-    }[Tuple.KeysOf<T>];
-
-    /**
-     * Determines the allowed paths for an array.
-     * @typeparam T - the input array type
-     */
-    export type Arr<T extends readonly any[]> =
-      // first `[index]` and then the rest of the path, which cannot be Write (since optional) and must be Maybe
-      `[${number}]${Path.Internal.Generic<T[number], false, true>}`;
-
-    /**
-     * Determines the allowed paths for an object.
-     * @typeparam T - the input object type
-     * @typeparam Write - if true the path should be writable (no optional chaining)
-     * @typeparam Maybe - if true the value at the current path is optional
-     */
-    export type Obj<T, Write extends boolean, Maybe extends boolean> = {
-      [K in keyof T]: `${K & string}${Path.Internal.Generic<
-        T[K],
-        Write,
-        // If writable (not optional), Maybe is false. If value is optional, Maybe is true. Otherwise, forward current Maybe.
-        Write extends true ? false : Path.Internal.IsOptional<T[K], true, Maybe>
-      >}`;
-    }[keyof T];
-
-    /**
-     * Determines the allowed path part separator based on the input types.
-     * @typeparam First - if true, this is the first call
-     * @typeparam Maybe - if true, the value is optional
-     * @typeparam IsArray - if true, the value is an array
-     */
-    export type Separator<
-      First extends boolean,
-      Maybe extends boolean,
-      IsArray extends boolean,
-    > = Maybe extends true
-      ? First extends true
-        ? // first optional value cannot have separator
-          never
-        : // non-first optional value must have separator
-          '?.'
-      : First extends true
-        ? // first non-optional value has empty separator
-          ''
-        : IsArray extends true
-          ? // array selectors do not have separator
-            ''
-          : // normal separator
-            '.';
-
-    /**
-     * Determines whether the given type `T` is optional, that is, whether it can be null or undefined.
-     * @typeparam T - the input type
-     * @typeparam True - the value to return if `T` is optional
-     * @typeparam False - the value to return if `T` is mandatory
-     */
-    export type IsOptional<T, True = true, False = false> = undefined extends T
-      ? // is optional
-        True
-      : null extends T
-        ? // is optional
-          True
-        : // not optional
-          False;
-
-    /**
-     * Returns type `T` if `Maybe` is false, `T | undefined` otherwise.
-     * @typeparam T - the input type
-     * @typeparam Maybe - if true, the return type value should be optional
-     */
-    export type MaybeValue<T, Maybe extends boolean> = Maybe extends true
-      ? T | undefined
-      : T;
-
-    /**
-     * Utility type to only add non-empty string types to a string array.
-     * @typeparam A - the input string array
-     * @typeparam T - the string value to optionally add
-     */
-    export type AppendIfNotEmpty<
-      A extends string[],
-      T extends string,
-    > = T extends ''
-      ? // empty string, do not add
-        A
-      : // non-empty string, add to array
-        [...A, T];
-  }
-
-  /**
-   * The result type when selecting from object type T a path with type P.
-   * @typeparam T - the object type to select in
-   * @typeparam P - a Path in object type T
-   * @example
-   * ```ts
-   * let r!: Path.Result<{ a: { b: { c: number } } }, 'a.b'>;
-   * // => type of r: { c: number }
-   * ```
-   */
-  export type Result<T, P extends string> = Path.Result.For<
-    T,
-    Path.Result.Tokenize<P>,
-    false
-  >;
-
-  export namespace Result {
-    /**
-     * Determines the result type for an array of tokens representing subpaths in type `T`.
-     * @typeparam T - the current source type
-     * @typeparam Tokens - an array of elements indicating a path into the source type
-     * @typeparam Maybe - if true indicates that the path may be undefined
-     */
-    export type For<
-      T,
-      Tokens,
-      Maybe extends boolean = Path.Internal.IsOptional<T>,
-    > = Tokens extends []
-      ? // no more token
-        Path.Internal.MaybeValue<T, Maybe>
-      : Path.Internal.IsOptional<T> extends true
-        ? // T can be null or undefined, so continue with Maybe set to true
-          Path.Result.For<Exclude<T, undefined | null>, Tokens, Maybe>
-        : Tokens extends ['?.', infer Key, ...infer Rest]
-          ? // optional chaining, process first part and set Maybe to true
-            Path.Result.For<Path.Result.Part<T, Key, Maybe>, Rest, true>
-          : Tokens extends ['.', infer Key, ...infer Rest]
-            ? // normal chaining, process first part and continue
-              Path.Result.For<Path.Result.Part<T, Key, false>, Rest, Maybe>
-            : Tokens extends [infer Key, ...infer Rest]
-              ? // process first part, and continue
-                Path.Result.For<Path.Result.Part<T, Key, false>, Rest, Maybe>
-              : never;
-
-    /**
-     * Determines the result of getting the property/index `K` from type `T`, taking into
-     * account that the value may be optional.
-     * @typeparam T - the current source type
-     * @typeparam K - the key to get from the source type
-     * @typeparam Maybe - if true indicates that the path may be undefined
-     */
-    export type Part<T, K, Maybe extends boolean> =
-      IsArray<T> extends true
-        ? // for arrays, Maybe needs to be set to true to force optional chaining
-          // for tuples, Maybe should be false
-          Path.Internal.MaybeValue<
-            T[K & keyof T],
-            Tuple.IsTuple<T> extends true ? Maybe : true
-          >
-        : // Return the type at the given key, and take `Maybe` into account
-          Path.Internal.MaybeValue<T[K & keyof T], Maybe>;
-
-    /**
-     * Converts a path string into separate tokens in a string array.
-     * @typeparam P - the literal string path type
-     * @typeparam Token - the token currently being produced
-     * @typeparam Res - the resulting literal string token array
-     */
-    export type Tokenize<
-      P extends string,
-      Token extends string = '',
-      Res extends string[] = [],
-    > = P extends ''
-      ? // no more input to process, return result
-        Path.Internal.AppendIfNotEmpty<Res, Token>
-      : P extends `[${infer Index}]${infer Rest}`
-        ? // input is an array selector, append index to tokens. Continue with new token
-          Tokenize<
-            Rest,
-            '',
-            [...Path.Internal.AppendIfNotEmpty<Res, Token>, Index]
-          >
-        : P extends `?.${infer Rest}`
-          ? // optional chaining, append to tokens. Continue with new token
-            Tokenize<
-              Rest,
-              '',
-              [...Path.Internal.AppendIfNotEmpty<Res, Token>, '?.']
-            >
-          : P extends `.${infer Rest}`
-            ? // normal chaining, append to tokens. Continue with new token
-              Tokenize<
-                Rest,
-                '',
-                [...Path.Internal.AppendIfNotEmpty<Res, Token>, '.']
-              >
-            : P extends `${infer First}${infer Rest}`
-              ? // process next character
-                Tokenize<Rest, `${Token}${First}`, Res>
-              : never;
-  }
-
-  /**
-   * Regular expression used to split a path string into tokens.
-   */
-  export const stringSplitRegex = /\?\.|\.|\[|\]/g;
-
-  /**
-   * The allowed values of a split path.
-   */
-  export type StringSplit = (string | number | undefined)[];
-
-  /**
-   * Return the given `path` string split into an array of subpaths.
-   * @param path - the input string path
-   */
-  export function stringSplit(path: string): Path.StringSplit {
-    return path.split(Path.stringSplitRegex);
-  }
-}
-
-/**
- * Returns the value resulting from selecting the given `path` in the given `source` object.
- * It supports optional chaining for nullable values or values that may be undefined, and also
- * for accessing objects inside an array.
- * There is currently no support for forcing non-null (the `!` operator).
- * @typeparam T - the object type to select in
- * @typeparam P - a Path in object type T
- * @param source - the object to select in
- * @param path - the path into the object
- * @example
- * ```ts
- * const value = { a: { b: { c: [{ d: 5 }, { d: 6 }] } } }
- * Deep.getAt(value, 'a.b');
- * // => { c: [{ d: 5 }, { d: 6 }] }
- * Deep.getAt(value, 'a.b.c');
- * // => [{ d: 5 }, { d: 6 }]
- * Deep.getAt(value, 'a.b.c[1]');
- * // => { d: 6 }
- * Deep.getAt(value, 'a.b.c[1]?.d');
- * // => 6
- * ```
- */
-export function getAt<T, P extends Path.Get<T>>(
-  source: T,
-  path: P
-): Path.Result<T, P> {
-  if (path === '') {
-    // empty path always directly returns source value
-    return source as any;
-  }
-
-  const items = Path.stringSplit(path);
-
-  // start with `source` as result value
-  let result = source as any;
-
-  for (const item of items) {
-    if (undefined === item || item === '' || item === '[') {
-      // ignore irrelevant items
-      continue;
-    }
-
-    if (undefined === result || null === result) {
-      // optional chaining assumed and no value available, skip rest of path and return undefined
-      return undefined as any;
-    }
-
-    // set current result to subpath value
-    result = result[item];
-  }
-
-  return result;
-}
-
-/**
- * Patches the value at the given path in the source to the given value.
- * Because the path to update must exist in the `source` object, optional
- * chaining and array indexing is not allowed.
- * @param source - the object to update
- * @param path - the path in the object to update
- * @param patchItem - the patch for the value at the given path
- * @example
- * ```ts
- * const value = { a: { b: { c: 5 } } };
- * Deep.patchAt(value, 'a.b.c', v => v + 5);
- * // => { a: { b: { c: 6 } } }
- * ```
- */
-export function patchAt<T, P extends Path.Set<T>, C = Path.Result<T, P>>(
-  source: T,
-  path: P,
-  patchItem: Patch<Path.Result<T, P>, Path.Result<T, P> & C>
-): T {
-  if (path === '') {
-    return Deep.patch(source, patchItem as any);
-  }
-
-  const items = Path.stringSplit(path);
-
-  // creates a patch object based on the current path
-  function createPatchPart(index: number, target: any): any {
-    if (index === items.length) {
-      // processed all items, return the input `patchItem`
-      return patchItem;
-    }
-
-    const item = items[index];
-
-    if (undefined === item || item === '') {
-      // empty items can be ignored
-      return createPatchPart(index + 1, target);
-    }
-
-    if (item === '[') {
-      // next item is array index, set arrayMode to true
-      return createPatchPart(index + 1, target);
-    }
-
-    // create object with subPart as property key, and the restuls of processing next parts as value
-    const result = {
-      [item]: createPatchPart(index + 1, target[item]),
-    };
-
-    if (Array.isArray(target)) {
-      // target in source object is array/tuple, so the patch should be object
-      return result;
-    }
-
-    // target in source is not an array, so it patch should be an array
-    return [result];
-  }
-
-  return Deep.patch(source, createPatchPart(0, source));
-}