maraj 2.4.0 → 2.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.d.mts +39 -17
  2. package/dist/index.d.ts +39 -17
  3. package/package.json +1 -1
package/dist/index.d.mts CHANGED
@@ -3,47 +3,55 @@
3
3
  * UTILITIES
4
4
  * --------------------------------------------
5
5
  */
6
+ /** Primitives and browser native objects. */
6
7
  type PrimitivesAndNativeObjects = null | undefined | string | number | boolean | symbol | bigint | Date | FileList | File;
8
+ /** Index literal type to improve DX at managing updates. */
7
9
  type LiteralIndex = '${number}';
10
+ /** Array indexes type. */
8
11
  type ArrayIndexes = `${number}` | LiteralIndex;
12
+ /** To check if a ReadonlyArray is a tuple or not. */
9
13
  type IsTuple<T extends ReadonlyArray<any>> = number extends T['length'] ? false : true;
10
14
  /**
11
15
  * --------------------------------------------
12
16
  * DOT PATH IMPLEMENTATION
13
17
  * --------------------------------------------
14
18
  */
15
- type ArrayPaths<TInnerType, TAllowedTypes> = TInnerType extends TAllowedTypes ? TInnerType extends PrimitivesAndNativeObjects ? `${ArrayIndexes}` : `${ArrayIndexes}` | `${ArrayIndexes}.${Flatten<TInnerType, TAllowedTypes>}` : `${ArrayIndexes}.${Flatten<TInnerType, TAllowedTypes>}`;
19
+ /** Dot-paths of an array. */
20
+ type ArrayPaths<TInnerType, TAllowedTypes> = TInnerType extends TAllowedTypes ? TInnerType extends PrimitivesAndNativeObjects ? `${ArrayIndexes}` : `${ArrayIndexes}` | `${ArrayIndexes}.${DotPaths<TInnerType, TAllowedTypes>}` : `${ArrayIndexes}.${DotPaths<TInnerType, TAllowedTypes>}`;
21
+ /** Dot-paths of an object. */
16
22
  type ObjectPaths<T, TAllowedTypes> = {
17
- [Key in keyof T & string]: T[Key] extends TAllowedTypes ? T[Key] extends PrimitivesAndNativeObjects ? `${Key}` : `${Key}` | `${Key}.${Flatten<T[Key], TAllowedTypes>}` : `${Key}.${Flatten<T[Key], TAllowedTypes>}`;
23
+ [Key in keyof T & string]: T[Key] extends TAllowedTypes ? T[Key] extends PrimitivesAndNativeObjects ? `${Key}` : `${Key}` | `${Key}.${DotPaths<T[Key], TAllowedTypes>}` : `${Key}.${DotPaths<T[Key], TAllowedTypes>}`;
18
24
  }[keyof T & string];
25
+ /** Dot-paths of a tuple. */
19
26
  type TuplePaths<T, TAllowedTypes> = ObjectPaths<Omit<T, keyof any[]>, TAllowedTypes>;
20
- type Flatten<T, TAllowedTypes> = T extends ReadonlyArray<infer U> ? IsTuple<T> extends true ? TuplePaths<T, TAllowedTypes> : ArrayPaths<U, TAllowedTypes> : T extends PrimitivesAndNativeObjects ? never : ObjectPaths<T, TAllowedTypes>;
21
- type DotPaths<T, TAllowedTypes = any> = Flatten<T, TAllowedTypes>;
22
- /**
23
- * --------------------------------------------
24
- * TO KNOW IF A PATH IS INDEXING ARRAY OR NOT
25
- * --------------------------------------------
26
- */
27
+ /** Literal union of all posible dot-paths which satisfy provided types as second argument (default: any). */
28
+ type DotPaths<T, TAllowedTypes = any> = T extends ReadonlyArray<infer U> ? IsTuple<T> extends true ? TuplePaths<T, TAllowedTypes> : ArrayPaths<U, TAllowedTypes> : T extends PrimitivesAndNativeObjects ? never : ObjectPaths<T, TAllowedTypes>;
27
29
  /**
28
30
  * --------------------------------------------
29
31
  * VALUE OF A NESTED PROPERTY PROVIDING A DOT PATH
30
32
  * --------------------------------------------
31
33
  */
34
+ /** Nested type implementation. */
32
35
  type NestedType<TObject, TPath> = TPath extends '' ? TObject : TPath extends keyof TObject ? TObject[TPath] : TPath extends LiteralIndex ? never : TPath extends `${number}` ? TObject extends ReadonlyArray<infer U> ? U : never : TPath extends `${infer K}.${infer R}` ? K extends keyof TObject ? NestedType<TObject[K], R> : K extends LiteralIndex ? never : K extends `${number}` ? TObject extends ReadonlyArray<infer U> ? NestedType<U, R> : never : never : never;
36
+ /** Value of a nested property of a given dot-path. */
33
37
  type ValueInDotPath<TObject, TPath extends DotPaths<TObject> | ''> = NestedType<TObject, TPath>;
34
38
  /**
35
39
  * --------------------------------------------
36
40
  * RETURNED VALUE OF A NESTED PROPERTY PROVIDING A DOT PATH
37
41
  * --------------------------------------------
38
42
  */
43
+ /** Returned nested type implementation. */
39
44
  type ReturnedNestedValue<TObject, TPath> = TPath extends '' ? TObject : TPath extends keyof TObject ? TObject[TPath] : TPath extends LiteralIndex ? never : TPath extends `${number}` ? TObject extends ReadonlyArray<infer U> ? (U | undefined) : never : TPath extends `${infer K}.${infer R}` ? K extends keyof TObject ? ReturnedNestedValue<TObject[K], R> : K extends LiteralIndex ? never : K extends `${number}` ? TObject extends ReadonlyArray<infer U> ? (ReturnedNestedValue<U, R> | undefined) : never : never : never;
45
+ /** Value of a RETURNED nested property of a given dot-path (so when accessing arrays can be undefined). */
40
46
  type ReturnedValueInDotPath<TObject, TPath extends DotPaths<TObject> | ''> = ReturnedNestedValue<TObject, TPath>;
41
47
  /**
42
48
  * --------------------------------------------
43
49
  * UPDATE OBJECT WITH DOT PATH IMPLEMENTATION
44
50
  * --------------------------------------------
45
51
  */
52
+ /** Value of a dot-path update object, can be the value or a function. */
46
53
  type DotPathUpdateValue<TObject, TPath extends DotPaths<TObject>> = ValueInDotPath<TObject, TPath> | ((fieldValue: ValueInDotPath<TObject, TPath>, fullObject: TObject) => ValueInDotPath<TObject, TPath>);
54
+ /** Dot-path update object, used to give updates to the updateImmutably function. */
47
55
  type DotPathUpdateObject<TObject> = {
48
56
  [TPath in DotPaths<TObject>]?: ValueInDotPath<TObject, TPath> | ((fieldValue: ValueInDotPath<TObject, TPath>, fullObject: TObject) => ValueInDotPath<TObject, TPath>);
49
57
  };
@@ -52,10 +60,13 @@ type DotPathUpdateObject<TObject> = {
52
60
  * REQUIRED OR OPTIONAL KEYS
53
61
  * --------------------------------------------
54
62
  */
63
+ /** All types instead of undefined. */
55
64
  type NonPartialKeys = null | object;
65
+ /** Returns only the optional keys of an object. */
56
66
  type RetrieveOptionalKeys<T> = {
57
67
  [K in keyof T & string]: T[K] extends NonPartialKeys ? never : K;
58
68
  }[keyof T & string];
69
+ /** Returns only the required keys of an object. */
59
70
  type RetrieveRequiredKeys<T> = {
60
71
  [K in keyof T & string]: T[K] extends NonPartialKeys ? K : never;
61
72
  }[keyof T & string];
@@ -63,13 +74,18 @@ type RetrieveRequiredKeys<T> = {
63
74
  type Remove = <T extends object>(value: T, keys: T extends any[] ? (number | `${number}` | (number | `${number}`)[]) : (RetrieveOptionalKeys<T> | (RetrieveOptionalKeys<T>)[])) => T;
64
75
  /**
65
76
  * Removes properties or indexes, order doesn't matter.
77
+ * @param value Object/array from where to remove keys/indexes shallowly.
78
+ * @param keys Keys to remove.
79
+ * @returns New object/array without the provided keys/indexes.
66
80
  */
67
81
  declare const remove: Remove;
68
82
 
69
83
  type Select = <TObject, TPath extends DotPaths<TObject> | ''>(state: TObject, path: TPath) => ReturnedValueInDotPath<TObject, TPath>;
70
84
  /**
71
- * Returns the value from a given dot path of an object/array.
72
- * Returns undefined if the provided path doesnt exist.
85
+ * Returns the value from a given dot path of an object/array or undefined if doesn't exist.
86
+ * @param state State from which retrieve the value.
87
+ * @param path Path indicating the value to extract.
88
+ * @returns Value of the provided path or undefined.
73
89
  */
74
90
  declare const select: Select;
75
91
 
@@ -77,21 +93,27 @@ type PathWithoutLastKey = string;
77
93
  type LastKey = string;
78
94
  type SplitDotPathAtLastKey = <T extends string>(dotPath: T) => [PathWithoutLastKey, LastKey];
79
95
  /**
80
- * Splits string dotPath into ID and RemainingPath
81
- */
96
+ * Splits a dot path string into its last key and its remaining keys ('' if none).
97
+ * @param dotPath A dot path.
98
+ * @returns [pathWithoutLastKey, lastKey] or ['', lastKey].
99
+ */
82
100
  declare const splitPathAtLastKey: SplitDotPathAtLastKey;
83
101
 
84
102
  type Set = <T>(newValue: T) => (value: T) => T;
85
103
  /**
86
- * Allows to set strongly typed values (removing inacurate "undefined" inference) in nested values inside arrays
104
+ * Allows to set strongly typed values (removing inacurate "undefined" inference) in nested values inside arrays.
105
+ * @param newValue New value.
106
+ * @returns The same value.
87
107
  */
88
108
  declare const set: Set;
89
109
 
90
110
  type UpdateImmutably = <T extends object>(state: T, updates: DotPathUpdateObject<T>, addNonExistentPropsAndIndexes?: true) => T;
91
111
  /**
92
- * Creates a new updated object/array applying the changes provided in the update object.
93
- * It doesnt modify the original input.
94
- * If any of the paths doesnt exists it returns
112
+ * Creates a new object applying immutable updates using dot-path syntax.
113
+ * @param state Original State Object.
114
+ * @param updates Dot Path Update Object.
115
+ * @param addNonExistentPropsAndIndexes If it should or not create non-existent fields.
116
+ * @returns New Updated Object.
95
117
  */
96
118
  declare const updateImmutably: UpdateImmutably;
97
119
 
package/dist/index.d.ts CHANGED
@@ -3,47 +3,55 @@
3
3
  * UTILITIES
4
4
  * --------------------------------------------
5
5
  */
6
+ /** Primitives and browser native objects. */
6
7
  type PrimitivesAndNativeObjects = null | undefined | string | number | boolean | symbol | bigint | Date | FileList | File;
8
+ /** Index literal type to improve DX at managing updates. */
7
9
  type LiteralIndex = '${number}';
10
+ /** Array indexes type. */
8
11
  type ArrayIndexes = `${number}` | LiteralIndex;
12
+ /** To check if a ReadonlyArray is a tuple or not. */
9
13
  type IsTuple<T extends ReadonlyArray<any>> = number extends T['length'] ? false : true;
10
14
  /**
11
15
  * --------------------------------------------
12
16
  * DOT PATH IMPLEMENTATION
13
17
  * --------------------------------------------
14
18
  */
15
- type ArrayPaths<TInnerType, TAllowedTypes> = TInnerType extends TAllowedTypes ? TInnerType extends PrimitivesAndNativeObjects ? `${ArrayIndexes}` : `${ArrayIndexes}` | `${ArrayIndexes}.${Flatten<TInnerType, TAllowedTypes>}` : `${ArrayIndexes}.${Flatten<TInnerType, TAllowedTypes>}`;
19
+ /** Dot-paths of an array. */
20
+ type ArrayPaths<TInnerType, TAllowedTypes> = TInnerType extends TAllowedTypes ? TInnerType extends PrimitivesAndNativeObjects ? `${ArrayIndexes}` : `${ArrayIndexes}` | `${ArrayIndexes}.${DotPaths<TInnerType, TAllowedTypes>}` : `${ArrayIndexes}.${DotPaths<TInnerType, TAllowedTypes>}`;
21
+ /** Dot-paths of an object. */
16
22
  type ObjectPaths<T, TAllowedTypes> = {
17
- [Key in keyof T & string]: T[Key] extends TAllowedTypes ? T[Key] extends PrimitivesAndNativeObjects ? `${Key}` : `${Key}` | `${Key}.${Flatten<T[Key], TAllowedTypes>}` : `${Key}.${Flatten<T[Key], TAllowedTypes>}`;
23
+ [Key in keyof T & string]: T[Key] extends TAllowedTypes ? T[Key] extends PrimitivesAndNativeObjects ? `${Key}` : `${Key}` | `${Key}.${DotPaths<T[Key], TAllowedTypes>}` : `${Key}.${DotPaths<T[Key], TAllowedTypes>}`;
18
24
  }[keyof T & string];
25
+ /** Dot-paths of a tuple. */
19
26
  type TuplePaths<T, TAllowedTypes> = ObjectPaths<Omit<T, keyof any[]>, TAllowedTypes>;
20
- type Flatten<T, TAllowedTypes> = T extends ReadonlyArray<infer U> ? IsTuple<T> extends true ? TuplePaths<T, TAllowedTypes> : ArrayPaths<U, TAllowedTypes> : T extends PrimitivesAndNativeObjects ? never : ObjectPaths<T, TAllowedTypes>;
21
- type DotPaths<T, TAllowedTypes = any> = Flatten<T, TAllowedTypes>;
22
- /**
23
- * --------------------------------------------
24
- * TO KNOW IF A PATH IS INDEXING ARRAY OR NOT
25
- * --------------------------------------------
26
- */
27
+ /** Literal union of all posible dot-paths which satisfy provided types as second argument (default: any). */
28
+ type DotPaths<T, TAllowedTypes = any> = T extends ReadonlyArray<infer U> ? IsTuple<T> extends true ? TuplePaths<T, TAllowedTypes> : ArrayPaths<U, TAllowedTypes> : T extends PrimitivesAndNativeObjects ? never : ObjectPaths<T, TAllowedTypes>;
27
29
  /**
28
30
  * --------------------------------------------
29
31
  * VALUE OF A NESTED PROPERTY PROVIDING A DOT PATH
30
32
  * --------------------------------------------
31
33
  */
34
+ /** Nested type implementation. */
32
35
  type NestedType<TObject, TPath> = TPath extends '' ? TObject : TPath extends keyof TObject ? TObject[TPath] : TPath extends LiteralIndex ? never : TPath extends `${number}` ? TObject extends ReadonlyArray<infer U> ? U : never : TPath extends `${infer K}.${infer R}` ? K extends keyof TObject ? NestedType<TObject[K], R> : K extends LiteralIndex ? never : K extends `${number}` ? TObject extends ReadonlyArray<infer U> ? NestedType<U, R> : never : never : never;
36
+ /** Value of a nested property of a given dot-path. */
33
37
  type ValueInDotPath<TObject, TPath extends DotPaths<TObject> | ''> = NestedType<TObject, TPath>;
34
38
  /**
35
39
  * --------------------------------------------
36
40
  * RETURNED VALUE OF A NESTED PROPERTY PROVIDING A DOT PATH
37
41
  * --------------------------------------------
38
42
  */
43
+ /** Returned nested type implementation. */
39
44
  type ReturnedNestedValue<TObject, TPath> = TPath extends '' ? TObject : TPath extends keyof TObject ? TObject[TPath] : TPath extends LiteralIndex ? never : TPath extends `${number}` ? TObject extends ReadonlyArray<infer U> ? (U | undefined) : never : TPath extends `${infer K}.${infer R}` ? K extends keyof TObject ? ReturnedNestedValue<TObject[K], R> : K extends LiteralIndex ? never : K extends `${number}` ? TObject extends ReadonlyArray<infer U> ? (ReturnedNestedValue<U, R> | undefined) : never : never : never;
45
+ /** Value of a RETURNED nested property of a given dot-path (so when accessing arrays can be undefined). */
40
46
  type ReturnedValueInDotPath<TObject, TPath extends DotPaths<TObject> | ''> = ReturnedNestedValue<TObject, TPath>;
41
47
  /**
42
48
  * --------------------------------------------
43
49
  * UPDATE OBJECT WITH DOT PATH IMPLEMENTATION
44
50
  * --------------------------------------------
45
51
  */
52
+ /** Value of a dot-path update object, can be the value or a function. */
46
53
  type DotPathUpdateValue<TObject, TPath extends DotPaths<TObject>> = ValueInDotPath<TObject, TPath> | ((fieldValue: ValueInDotPath<TObject, TPath>, fullObject: TObject) => ValueInDotPath<TObject, TPath>);
54
+ /** Dot-path update object, used to give updates to the updateImmutably function. */
47
55
  type DotPathUpdateObject<TObject> = {
48
56
  [TPath in DotPaths<TObject>]?: ValueInDotPath<TObject, TPath> | ((fieldValue: ValueInDotPath<TObject, TPath>, fullObject: TObject) => ValueInDotPath<TObject, TPath>);
49
57
  };
@@ -52,10 +60,13 @@ type DotPathUpdateObject<TObject> = {
52
60
  * REQUIRED OR OPTIONAL KEYS
53
61
  * --------------------------------------------
54
62
  */
63
+ /** All types instead of undefined. */
55
64
  type NonPartialKeys = null | object;
65
+ /** Returns only the optional keys of an object. */
56
66
  type RetrieveOptionalKeys<T> = {
57
67
  [K in keyof T & string]: T[K] extends NonPartialKeys ? never : K;
58
68
  }[keyof T & string];
69
+ /** Returns only the required keys of an object. */
59
70
  type RetrieveRequiredKeys<T> = {
60
71
  [K in keyof T & string]: T[K] extends NonPartialKeys ? K : never;
61
72
  }[keyof T & string];
@@ -63,13 +74,18 @@ type RetrieveRequiredKeys<T> = {
63
74
  type Remove = <T extends object>(value: T, keys: T extends any[] ? (number | `${number}` | (number | `${number}`)[]) : (RetrieveOptionalKeys<T> | (RetrieveOptionalKeys<T>)[])) => T;
64
75
  /**
65
76
  * Removes properties or indexes, order doesn't matter.
77
+ * @param value Object/array from where to remove keys/indexes shallowly.
78
+ * @param keys Keys to remove.
79
+ * @returns New object/array without the provided keys/indexes.
66
80
  */
67
81
  declare const remove: Remove;
68
82
 
69
83
  type Select = <TObject, TPath extends DotPaths<TObject> | ''>(state: TObject, path: TPath) => ReturnedValueInDotPath<TObject, TPath>;
70
84
  /**
71
- * Returns the value from a given dot path of an object/array.
72
- * Returns undefined if the provided path doesnt exist.
85
+ * Returns the value from a given dot path of an object/array or undefined if doesn't exist.
86
+ * @param state State from which retrieve the value.
87
+ * @param path Path indicating the value to extract.
88
+ * @returns Value of the provided path or undefined.
73
89
  */
74
90
  declare const select: Select;
75
91
 
@@ -77,21 +93,27 @@ type PathWithoutLastKey = string;
77
93
  type LastKey = string;
78
94
  type SplitDotPathAtLastKey = <T extends string>(dotPath: T) => [PathWithoutLastKey, LastKey];
79
95
  /**
80
- * Splits string dotPath into ID and RemainingPath
81
- */
96
+ * Splits a dot path string into its last key and its remaining keys ('' if none).
97
+ * @param dotPath A dot path.
98
+ * @returns [pathWithoutLastKey, lastKey] or ['', lastKey].
99
+ */
82
100
  declare const splitPathAtLastKey: SplitDotPathAtLastKey;
83
101
 
84
102
  type Set = <T>(newValue: T) => (value: T) => T;
85
103
  /**
86
- * Allows to set strongly typed values (removing inacurate "undefined" inference) in nested values inside arrays
104
+ * Allows to set strongly typed values (removing inacurate "undefined" inference) in nested values inside arrays.
105
+ * @param newValue New value.
106
+ * @returns The same value.
87
107
  */
88
108
  declare const set: Set;
89
109
 
90
110
  type UpdateImmutably = <T extends object>(state: T, updates: DotPathUpdateObject<T>, addNonExistentPropsAndIndexes?: true) => T;
91
111
  /**
92
- * Creates a new updated object/array applying the changes provided in the update object.
93
- * It doesnt modify the original input.
94
- * If any of the paths doesnt exists it returns
112
+ * Creates a new object applying immutable updates using dot-path syntax.
113
+ * @param state Original State Object.
114
+ * @param updates Dot Path Update Object.
115
+ * @param addNonExistentPropsAndIndexes If it should or not create non-existent fields.
116
+ * @returns New Updated Object.
95
117
  */
96
118
  declare const updateImmutably: UpdateImmutably;
97
119
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "maraj",
3
- "version": "2.4.0",
3
+ "version": "2.4.1",
4
4
  "description": "A lightweight 500 bytes gzipped alternative for immutable updates while dealing with objects and arrays",
5
5
  "keywords": [
6
6
  "shallow",