@rimbu/deep 0.11.2 → 0.12.0

package/dist/types/path.d.ts

@@ -1,53 +1,196 @@
-import type { Update } from '@rimbu/common';
-import type { IsPlainObj, PlainObj } from '@rimbu/base';
-/**
- * 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<{ a: { b: { c : 5 }}}> = 'a.b'
- * ```
- */
-export declare type Path<T> = IsPlainObj<T> extends true ? {
-    [K in string & keyof T]: `${K}` | `${K}.${Path<T[K]>}`;
-}[string & keyof T] : never;
+import type { IsAnyFunc, IsArray, IsPlainObj } from '@rimbu/base';
+import { Patch } from './internal';
+import type { Tuple } from './tuple';
 export declare namespace Path {
     /**
-     * The result type when selecting from object type T a path with type P.
+     * A string representing a path into an (nested) object of type T.
      * @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 }
+     * const p: Path.Get<{ a: { b: { c : 5 } } }> = 'a.b'
      * ```
      */
-    type Result<T, P extends Path<T> = Path<T>> = T extends Record<string, unknown> ? P extends `${infer Head}.${infer Rest}` ? Head extends keyof T ? Path.Result<T[Head], Rest & Path<T[Head]>> : never : P extends `${infer K}` ? T[K] : never : never;
+    type Get<T> = Path.Internal.Generic<T, false, false, true>;
     /**
-     * Returns the value resulting from selecting the given `path` in the given `source` object.
+     * A string representing a path into an (nested) object of type T.
      * @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
-     * console.log(Path.get({ a: { b: { c: 5 } } }), 'a.b')
-     * // => { c: 5 }
-     * console.log(Path.get({ a: { b: { c: 5 } } }), 'a.b.c')
-     * // => 5
+     * const p: Path.Set<{ a: { b: { c : 5 } } }> = 'a.b'
      * ```
      */
-    function get<T, P extends Path<T> = Path<T>>(source: T & PlainObj<T>, path: P): Path.Result<T, P>;
+    type Set<T> = Path.Internal.Generic<T, true, false, true>;
+    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
+         */
+        type Generic<T, Write extends boolean, Maybe extends boolean, First extends boolean = false> = `${IsAnyFunc<T> extends true ? '' : // 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
+         */
+        type NonEmpty<T, Write extends boolean, Maybe extends boolean, First extends boolean> = Path.Internal.IsOptional<T> extends true ? Write extends false ? Path.Internal.Generic<Exclude<T, undefined | null>, Write, true> : never : `${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
+         * @typeparam First - if true this is the root call
+         */
+        type NonOptional<T, Write extends boolean, Maybe extends boolean> = Tuple.IsTuple<T> extends true ? Path.Internal.Tup<T, Write, Maybe> : T extends readonly any[] ? Write extends false ? Path.Internal.Arr<T> : never : IsPlainObj<T> extends true ? Path.Internal.Obj<T, Write, Maybe> : 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
+         */
+        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
+         */
+        type Arr<T extends readonly any[]> = `[${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
+         */
+        type Obj<T, Write extends boolean, Maybe extends boolean> = {
+            [K in keyof T]: `${K & string}${Path.Internal.Generic<T[K], Write, Write extends true ? false : Path.Internal.IsOptional<T[K], true, Maybe>>}`;
+        }[keyof T];
+        /**
+         * Determines the allowed path part seperator 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
+         */
+        type Separator<First extends boolean, Maybe extends boolean, IsArray extends boolean> = Maybe extends true ? First extends true ? never : '?.' : First extends true ? '' : IsArray extends true ? '' : '.';
+        /**
+         * 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
+         */
+        type IsOptional<T, True = true, False = false> = undefined extends T ? True : null extends T ? True : 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
+         */
+        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.
+         * @typeparma A - the input string array
+         * @typeparam T - the string value to optionally add
+         */
+        type AppendIfNotEmpty<A extends string[], T extends string> = T extends '' ? A : [
+            ...A,
+            T
+        ];
+    }
     /**
-     * Sets the value at the given path in the source to the given value.
-     * @param source - the object to update
-     * @param path - the path in the object to update
-     * @param value - the new value to set at the given position
+     * 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
-     * console.log(Path.update({ a: { b: { c: 5 } } }, 'a.b.c', v => v + 5)
-     * // => { a: { b: { c: 6 } } }
+     * let r!: Path.Result<{ a: { b: { c: number } } }, 'a.b'>;
+     * // => type of r: { c: number }
      * ```
      */
-    function update<T, P extends Path<T> = Path<T>>(source: T & PlainObj<T>, path: P, value: Update<Path.Result<T, P>>): T;
+    type Result<T, P extends string> = Path.Result.For<T, Path.Result.Tokenize<P>, false>;
+    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
+         */
+        type For<T, Tokens, Maybe extends boolean = Path.Internal.IsOptional<T>> = Tokens extends [] ? Path.Internal.MaybeValue<T, Maybe> : Path.Internal.IsOptional<T> extends true ? Path.Result.For<Exclude<T, undefined | null>, Tokens, Maybe> : Tokens extends ['?.', infer Key, ...infer Rest] ? Path.Result.For<Path.Result.Part<T, Key, Maybe>, Rest, true> : Tokens extends ['.', infer Key, ...infer Rest] ? Path.Result.For<Path.Result.Part<T, Key, false>, Rest, Maybe> : Tokens extends [infer Key, ...infer Rest] ? 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
+         */
+        type Part<T, K, Maybe extends boolean> = IsArray<T> extends true ? Path.Internal.MaybeValue<T[K & keyof T], Tuple.IsTuple<T> extends true ? Maybe : true> : 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
+         */
+        type Tokenize<P extends string, Token extends string = '', Res extends string[] = []> = P extends '' ? Path.Internal.AppendIfNotEmpty<Res, Token> : P extends `[${infer Index}]${infer Rest}` ? Tokenize<Rest, '', [
+            ...Path.Internal.AppendIfNotEmpty<Res, Token>,
+            Index
+        ]> : P extends `?.${infer Rest}` ? Tokenize<Rest, '', [
+            ...Path.Internal.AppendIfNotEmpty<Res, Token>,
+            '?.'
+        ]> : P extends `.${infer Rest}` ? Tokenize<Rest, '', [...Path.Internal.AppendIfNotEmpty<Res, Token>, '.']> : P extends `${infer First}${infer Rest}` ? Tokenize<Rest, `${Token}${First}`, Res> : never;
+    }
+    /**
+     * Regular expression used to split a path string into tokens.
+     */
+    const stringSplitRegex: RegExp;
+    /**
+     * The allowed values of a split path.
+     */
+    type StringSplit = (string | number | undefined)[];
+    /**
+     * Return the given `path` string split into an array of subpaths.
+     * @param path - the input string path
+     */
+    function stringSplit(path: string): Path.StringSplit;
 }
+/**
+ * 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: 5 }
+ * Deep.getAt(value, 'a.b.c');
+ * // => [{ d: 5 }, { d: 5 }]
+ * Deep.getAt(value, 'a.b.c[1]');
+ * // => { d: 6 }
+ * Deep.getAt(value, 'a.b.c[1]?.d');
+ * // => 6
+ * ```
+ */
+export declare function getAt<T, P extends Path.Get<T>>(source: T, path: P): Path.Result<T, P>;
+/**
+ * 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 declare function patchAt<T, P extends Path.Set<T>, C = Path.Result<T, P>>(source: T, path: P, patchItem: Patch<Path.Result<T, P>, C>): T;

package/dist/types/protected.d.ts

@@ -12,21 +12,6 @@ import type { IsAny, IsPlainObj } from '@rimbu/base';
  */
 export declare type Protected<T> = IsAny<T> extends true ? T : T extends readonly any[] & infer A ? {
     readonly [K in keyof A]: Protected<A[K]>;
-} : T extends Map<infer K, infer V> ? Map<Protected<K>, Protected<V>> : T extends Set<infer E> ? Set<Protected<E>> : T extends Promise<infer E> ? Promise<Protected<E>> : IsPlainObj<T> extends true ? {
+} : T extends Map<infer K, infer V> ? Omit<Map<Protected<K>, Protected<V>>, 'clear' | 'delete' | 'set'> : T extends Set<infer E> ? Omit<Set<Protected<E>>, 'add' | 'clear' | 'delete'> : T extends Promise<infer E> ? Promise<Protected<E>> : IsPlainObj<T> extends true ? {
     readonly [K in keyof T]: Protected<T[K]>;
 } : T;
-/**
- * Returns the same value wrapped in the `Protected` type.
- * @param value - the value to wrap
- * @note does not perform any runtime protection, it is only a utility to easily add the `Protected`
- * type to a value
- * @example
- * ```ts
- * const obj = Protected({ a: 1, b: { c: true, d: [1] } })
- * obj.a = 2        // compiler error: a is readonly
- * obj.b.c = false  // compiler error: c is readonly
- * obj.b.d.push(2)  // compiler error: d is a readonly array
- * (obj as any).b.d.push(2)  // will actually mutate the object
- * ```
- */
-export declare function Protected<T>(value: T): Protected<T>;

package/dist/types/selector.d.ts

@@ -0,0 +1,47 @@
+import type { IsAnyFunc, IsArray } from '@rimbu/base';
+import { Path, type Protected } from './internal';
+/**
+ * Type defining the allowed selectors on an object of type `T`.
+ * Selectors can be:
+ * - a path string into type `T`.
+ * - a function receiving a `Protected` version of type `T`, and returning an arbitrary value.
+ * - a tuple of `Selectors` for type `T`
+ * - an object where the property values are `Selectors` for type `T`.
+ * @typeparam T - the source value type.
+ */
+export declare type Selector<T> = Path.Get<T> | ((value: Protected<T>) => any) | readonly Selector<T>[] | {
+    readonly [key: string | symbol]: Selector<T>;
+};
+export declare namespace Selector {
+    /**
+     * Type defining the shape of allowed selectors, used to improve compiler checking.
+     * @typeparam SL - the selector type
+     */
+    type Shape<SL> = IsAnyFunc<SL> extends true ? SL : IsArray<SL> extends true ? readonly [...(SL extends readonly unknown[] ? SL : never)] : SL extends {
+        readonly [key: string | number | symbol]: unknown;
+    } ? {
+        readonly [K in keyof SL]: Selector.Shape<SL[K]>;
+    } : SL;
+    /**
+     * Type defining the result type of applying the SL selector type to the T value type.
+     * @typeparam T - the source value type
+     * @typeparam SL - the selector type
+     */
+    type Result<T, SL> = Selector<T> extends SL ? never : SL extends (...args: any[]) => infer R ? R : SL extends string ? Path.Result<T, SL> : {
+        readonly [K in keyof SL]: Selector.Result<T, SL[K]>;
+    };
+}
+/**
+ * Returns the result of applying the given `selector` shape to the given `source` value.
+ * @typeparam T - the patch value type
+ * @typeparam SL - the selector shape type
+ * @param source - the source value to select from
+ * @param selector - a shape indicating the selection from the source values
+ * @example
+ * ```ts
+ * const item = { a: { b:  1, c: 'a' } };
+ * Deep.select(item, { q: 'a.c', y: ['a.b', 'a.c'], z: (v) => v.a.b + 1 });
+ * // => { q: 'a', y: [1, 'a'], z: 2 }
+ * ```
+ */
+export declare function select<T, SL extends Selector<T>>(source: T, selector: Selector.Shape<SL>): Selector.Result<T, SL>;

package/dist/types/tuple.d.ts

@@ -12,6 +12,16 @@ export declare namespace Tuple {
      * A readonly array that can serve as a source for a Tuple.
      */
     type Source = readonly unknown[];
+    type IsTuple<T> = T extends {
+        length: infer L;
+    } ? 0 extends L ? false : true : false;
+    /**
+     * Returns the indices/keys that are in a tuple.
+     * @typeparam T - the input tuple type
+     */
+    type KeysOf<T> = {
+        [K in keyof T]: K;
+    }[keyof T & number];
     /**
      * Convenience method to type Tuple types
      * @param values - the values of the tuple

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimbu/deep",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Tools to use handle plain JS objects as immutable objects",
   "keywords": [
     "immutable",
@@ -57,8 +57,8 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@rimbu/base": "^0.9.4",
-    "@rimbu/common": "^0.10.2",
+    "@rimbu/base": "^0.10.0",
+    "@rimbu/common": "^0.10.3",
     "tslib": "^2.4.0"
   },
   "publishConfig": {
@@ -68,5 +68,5 @@
     "index": "src/index.ts",
     "replacer": "../../config/denoify-rimbu-replacer.js"
   },
-  "gitHead": "0d1677b4df9c1b0f1dc337eb38eea7a99ea7fc43"
+  "gitHead": "22ae1cadeb885e7fd30a23bd05c001cda3141e86"
 }