maraj 2.4.0 → 2.5.0

package/README.md

@@ -28,16 +28,17 @@ originalValue.files[1] === updatedValue.files[1] // true
 
 ### Limitations
 
-- If "addNonExistentPropsAndIndexes" is enabled, numbers will always create an array if the array/object doesnt exist beforehand.
+- If "addNonExistentPropsAndIndexes" is enabled (3rd parameter in the updateImmutably function), **numbers** will **always** create an **array** if the array/object doesnt exist beforehand.
 
 ```ts
 const updatedValue = updateImmutably({}, {
    'files.1.name': 'new name',
 }, true)
 // updatedValue = { files: [<empty>, { name: 'new name' }] }
+// the "files" prop is an array.
 ```
 
-- The type "UpdateDotObject" using computed properties ( [key] ) will always throw a ts error even if the typing is correct. [Playground simple explanation](https://www.typescriptlang.org/play?ts=5.3.2#code/LAKALgngDgpgBAGQJYGcxwLxwOQENtwA+cABgCQDeAdgK4C2ARjAE4C+JooksiqYASjADGAe2YATTHApwA2gGk4SKrzQBdAPwAuOItacQoqmjhDmMXGBiDREqQB4AKnBgAPK1XEpVYAHwAKAGsYCB1HAEpMX2lQODijE3MhHWQ0GzFJLApYuNyAejy4AD0wbxZmMR0UZSF4ADcAFgA6AGYmgFYldAB3JAAbPrgwAAsK7rhcFXKxCfQhYeFA5QBzUxE6KBorSWCIb0nJOtw+mhhvGmqqVasNvst4PqQrZmOyupgVJAAzIYWh6BWSm8tiSYByuTkuzUOl24P0IFy5jANGYKiSoFYQA)
+- The type "UpdateDotPathObject" (the type used as second parameter in the updateImmutably function) if used to create new update objects using computed properties { [key]: value } will always throw a ts error even if the typing is correct. [Playground simple explanation](https://www.typescriptlang.org/play?ts=5.3.2#code/LAKALgngDgpgBAGQJYGcxwLxwOQENtwA+cABgCQDeAdgK4C2ARjAE4C+JooksiqYASjADGAe2YATTHApwA2gGk4SKrzQBdAPwAuOItacQoqmjhDmMXGBiDREqQB4AKnBgAPK1XEpVYAHwAKAGsYCB1HAEpMX2lQODijE3MhHWQ0GzFJLApYuNyAejy4AD0wbxZmMR0UZSF4ADcAFgA6AGYmgFYldAB3JAAbPrgwAAsK7rhcFXKxCfQhYeFA5QBzUxE6KBorSWCIb0nJOtw+mhhvGmqqVasNvst4PqQrZmOyupgVJAAzIYWh6BWSm8tiSYByuTkuzUOl24P0IFy5jANGYKiSoFYQA)
 
 ```ts
 const updateFieldStore = <TPath extends DotPaths<Store>>(

package/dist/index.d.mts

@@ -1,49 +1,77 @@
+/** Index literal type to improve DX at managing updates. */
+declare const LITERAL_INDEX = "${number}";
+type LiteralIndex = typeof LITERAL_INDEX;
+type UpdateImmutably = <T extends object>(state: T, updates: DotPathUpdateObject<T>) => T;
+/**
+ * Creates a new object applying strict immutable updates using dot-path syntax. Can't add new props or indexes.
+ * @param state Original State Object.
+ * @param updates Dot Path Update Object.
+ * @param addNonExistentPropsAndIndexes If it should or not create non-existent fields.
+ * @returns New Updated Object.
+ */
+declare const updateImmutably: UpdateImmutably;
+type ModifyImmutably = <T extends object>(state: T, updates: DotPathUpdateObject<T> | Record<string, any>) => T;
+/**
+ * Creates a new object applying immutable modifications using dot-path syntax. It will add non-existent props or indexes if provided.
+ * @param state Original State Object.
+ * @param updates Dot Path Update Object.
+ * @param addNonExistentPropsAndIndexes If it should or not create non-existent fields.
+ * @returns New Updated Object.
+ */
+declare const modifyImmutably: ModifyImmutably;
+
 /**
  * --------------------------------------------
  *  UTILITIES
  * --------------------------------------------
  */
+/** Primitives and browser native objects. */
 type PrimitivesAndNativeObjects = null | undefined | string | number | boolean | symbol | bigint | Date | FileList | File;
-type LiteralIndex = '${number}';
-type ArrayIndexes = `${number}` | LiteralIndex;
+/** Array indexes type. */
+type ArrayIndexes = number | LiteralIndex;
+/** To check if a ReadonlyArray is a tuple or not. */
 type IsTuple<T extends ReadonlyArray<any>> = number extends T['length'] ? false : true;
 /**
  * --------------------------------------------
  *  DOT PATH IMPLEMENTATION
  * --------------------------------------------
  */
-type ArrayPaths<TInnerType, TAllowedTypes> = TInnerType extends TAllowedTypes ? TInnerType extends PrimitivesAndNativeObjects ? `${ArrayIndexes}` : `${ArrayIndexes}` | `${ArrayIndexes}.${Flatten<TInnerType, TAllowedTypes>}` : `${ArrayIndexes}.${Flatten<TInnerType, TAllowedTypes>}`;
+/** Dot-paths of an array. */
+type ArrayPaths<TInnerType, TAllowedTypes> = TInnerType extends TAllowedTypes ? TInnerType extends PrimitivesAndNativeObjects ? `${ArrayIndexes}` : `${ArrayIndexes}` | `${ArrayIndexes}.${DotPaths<TInnerType, TAllowedTypes>}` : `${ArrayIndexes}.${DotPaths<TInnerType, TAllowedTypes>}`;
+/** Dot-paths of an object. */
 type ObjectPaths<T, TAllowedTypes> = {
-    [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>}`;
+    [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>}`;
 }[keyof T & string];
+/** Dot-paths of a tuple. */
 type TuplePaths<T, TAllowedTypes> = ObjectPaths<Omit<T, keyof any[]>, TAllowedTypes>;
-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>;
-type DotPaths<T, TAllowedTypes = any> = Flatten<T, TAllowedTypes>;
-/**
- * --------------------------------------------
- *  TO KNOW IF A PATH IS INDEXING ARRAY OR NOT
- * --------------------------------------------
- */
+/** Literal union of all posible dot-paths which satisfy provided types as second argument (default: any). */
+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>;
 /**
  * --------------------------------------------
  *  VALUE OF A NESTED PROPERTY PROVIDING A DOT PATH
  * --------------------------------------------
  */
+/** Nested type implementation. */
 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;
+/** Value of a nested property of a given dot-path. */
 type ValueInDotPath<TObject, TPath extends DotPaths<TObject> | ''> = NestedType<TObject, TPath>;
 /**
  * --------------------------------------------
  *  RETURNED VALUE OF A NESTED PROPERTY PROVIDING A DOT PATH
  * --------------------------------------------
  */
+/** Returned nested type implementation. */
 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;
+/** Value of a RETURNED nested property of a given dot-path (so when accessing arrays can be undefined). */
 type ReturnedValueInDotPath<TObject, TPath extends DotPaths<TObject> | ''> = ReturnedNestedValue<TObject, TPath>;
 /**
  * --------------------------------------------
  *  UPDATE OBJECT WITH DOT PATH IMPLEMENTATION
  * --------------------------------------------
  */
+/** Value of a dot-path update object, can be the value or a function. */
 type DotPathUpdateValue<TObject, TPath extends DotPaths<TObject>> = ValueInDotPath<TObject, TPath> | ((fieldValue: ValueInDotPath<TObject, TPath>, fullObject: TObject) => ValueInDotPath<TObject, TPath>);
+/** Dot-path update object, used to give updates to the updateImmutably function. */
 type DotPathUpdateObject<TObject> = {
     [TPath in DotPaths<TObject>]?: ValueInDotPath<TObject, TPath> | ((fieldValue: ValueInDotPath<TObject, TPath>, fullObject: TObject) => ValueInDotPath<TObject, TPath>);
 };
@@ -52,24 +80,30 @@ type DotPathUpdateObject<TObject> = {
  *  REQUIRED OR OPTIONAL KEYS
  * --------------------------------------------
  */
-type NonPartialKeys = null | object;
-type RetrieveOptionalKeys<T> = {
-    [K in keyof T & string]: T[K] extends NonPartialKeys ? never : K;
-}[keyof T & string];
-type RetrieveRequiredKeys<T> = {
-    [K in keyof T & string]: T[K] extends NonPartialKeys ? K : never;
-}[keyof T & string];
+/** Returns only the optional keys of an object. */
+type OptionalKeys<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
+}[keyof T];
+/** Returns only the required keys of an object. */
+type RequiredKeys<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
 
-type Remove = <T extends object>(value: T, keys: T extends any[] ? (number | `${number}` | (number | `${number}`)[]) : (RetrieveOptionalKeys<T> | (RetrieveOptionalKeys<T>)[])) => T;
+type Remove = <T extends object>(value: T, keys: T extends any[] ? (number | `${number}` | (number | `${number}`)[]) : OptionalKeys<T> | (OptionalKeys<T>)[]) => T;
 /**
  * Removes properties or indexes, order doesn't matter.
+ * @param value Object/array from where to remove keys/indexes shallowly.
+ * @param keys Keys to remove.
+ * @returns New object/array without the provided keys/indexes.
  */
 declare const remove: Remove;
 
 type Select = <TObject, TPath extends DotPaths<TObject> | ''>(state: TObject, path: TPath) => ReturnedValueInDotPath<TObject, TPath>;
 /**
- * Returns the value from a given dot path of an object/array.
- * Returns undefined if the provided path doesnt exist.
+ * Returns the value from a given dot path of an object/array or undefined if doesn't exist.
+ * @param state State from which retrieve the value.
+ * @param path Path indicating the value to extract.
+ * @returns Value of the provided path or undefined.
  */
 declare const select: Select;
 
@@ -77,22 +111,24 @@ type PathWithoutLastKey = string;
 type LastKey = string;
 type SplitDotPathAtLastKey = <T extends string>(dotPath: T) => [PathWithoutLastKey, LastKey];
 /**
- * Splits string dotPath into ID and RemainingPath
-*/
+ * Splits a dot path string into its last key and its remaining keys ('' if none).
+ * @param dotPath A dot path.
+ * @returns [pathWithoutLastKey, lastKey] or ['', lastKey].
+ */
 declare const splitPathAtLastKey: SplitDotPathAtLastKey;
 
 type Set = <T>(newValue: T) => (value: T) => T;
 /**
- * Allows to set strongly typed values (removing inacurate "undefined" inference) in nested values inside arrays
+ * Allows to set strongly typed values (removing inacurate "undefined" inference) in nested values inside arrays.
+ * @param newValue New value.
+ * @returns The same value.
  */
 declare const set: Set;
 
-type UpdateImmutably = <T extends object>(state: T, updates: DotPathUpdateObject<T>, addNonExistentPropsAndIndexes?: true) => T;
-/**
- * Creates a new updated object/array applying the changes provided in the update object.
- * It doesnt modify the original input.
- * If any of the paths doesnt exists it returns
- */
-declare const updateImmutably: UpdateImmutably;
+/** Checks if any provided value is an object literal or not */
+declare const isObjectLiteral: (valueToTest: any) => boolean;
+
+declare const parseStringIndex: (v: string) => number | null;
+declare const isStringIndex: (v: string) => boolean;
 
-export { type DotPathUpdateObject, type DotPathUpdateValue, type DotPaths, type PrimitivesAndNativeObjects, type RetrieveOptionalKeys, type RetrieveRequiredKeys, type ReturnedValueInDotPath, type ValueInDotPath, remove, select, set, splitPathAtLastKey, updateImmutably };
+export { type DotPathUpdateObject, type DotPathUpdateValue, type DotPaths, type OptionalKeys, type PrimitivesAndNativeObjects, type RequiredKeys, type ReturnedValueInDotPath, type ValueInDotPath, isObjectLiteral, isStringIndex, modifyImmutably, parseStringIndex, remove, select, set, splitPathAtLastKey, updateImmutably };

package/dist/index.d.ts

@@ -1,49 +1,77 @@
+/** Index literal type to improve DX at managing updates. */
+declare const LITERAL_INDEX = "${number}";
+type LiteralIndex = typeof LITERAL_INDEX;
+type UpdateImmutably = <T extends object>(state: T, updates: DotPathUpdateObject<T>) => T;
+/**
+ * Creates a new object applying strict immutable updates using dot-path syntax. Can't add new props or indexes.
+ * @param state Original State Object.
+ * @param updates Dot Path Update Object.
+ * @param addNonExistentPropsAndIndexes If it should or not create non-existent fields.
+ * @returns New Updated Object.
+ */
+declare const updateImmutably: UpdateImmutably;
+type ModifyImmutably = <T extends object>(state: T, updates: DotPathUpdateObject<T> | Record<string, any>) => T;
+/**
+ * Creates a new object applying immutable modifications using dot-path syntax. It will add non-existent props or indexes if provided.
+ * @param state Original State Object.
+ * @param updates Dot Path Update Object.
+ * @param addNonExistentPropsAndIndexes If it should or not create non-existent fields.
+ * @returns New Updated Object.
+ */
+declare const modifyImmutably: ModifyImmutably;
+
 /**
  * --------------------------------------------
  *  UTILITIES
  * --------------------------------------------
  */
+/** Primitives and browser native objects. */
 type PrimitivesAndNativeObjects = null | undefined | string | number | boolean | symbol | bigint | Date | FileList | File;
-type LiteralIndex = '${number}';
-type ArrayIndexes = `${number}` | LiteralIndex;
+/** Array indexes type. */
+type ArrayIndexes = number | LiteralIndex;
+/** To check if a ReadonlyArray is a tuple or not. */
 type IsTuple<T extends ReadonlyArray<any>> = number extends T['length'] ? false : true;
 /**
  * --------------------------------------------
  *  DOT PATH IMPLEMENTATION
  * --------------------------------------------
  */
-type ArrayPaths<TInnerType, TAllowedTypes> = TInnerType extends TAllowedTypes ? TInnerType extends PrimitivesAndNativeObjects ? `${ArrayIndexes}` : `${ArrayIndexes}` | `${ArrayIndexes}.${Flatten<TInnerType, TAllowedTypes>}` : `${ArrayIndexes}.${Flatten<TInnerType, TAllowedTypes>}`;
+/** Dot-paths of an array. */
+type ArrayPaths<TInnerType, TAllowedTypes> = TInnerType extends TAllowedTypes ? TInnerType extends PrimitivesAndNativeObjects ? `${ArrayIndexes}` : `${ArrayIndexes}` | `${ArrayIndexes}.${DotPaths<TInnerType, TAllowedTypes>}` : `${ArrayIndexes}.${DotPaths<TInnerType, TAllowedTypes>}`;
+/** Dot-paths of an object. */
 type ObjectPaths<T, TAllowedTypes> = {
-    [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>}`;
+    [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>}`;
 }[keyof T & string];
+/** Dot-paths of a tuple. */
 type TuplePaths<T, TAllowedTypes> = ObjectPaths<Omit<T, keyof any[]>, TAllowedTypes>;
-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>;
-type DotPaths<T, TAllowedTypes = any> = Flatten<T, TAllowedTypes>;
-/**
- * --------------------------------------------
- *  TO KNOW IF A PATH IS INDEXING ARRAY OR NOT
- * --------------------------------------------
- */
+/** Literal union of all posible dot-paths which satisfy provided types as second argument (default: any). */
+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>;
 /**
  * --------------------------------------------
  *  VALUE OF A NESTED PROPERTY PROVIDING A DOT PATH
  * --------------------------------------------
  */
+/** Nested type implementation. */
 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;
+/** Value of a nested property of a given dot-path. */
 type ValueInDotPath<TObject, TPath extends DotPaths<TObject> | ''> = NestedType<TObject, TPath>;
 /**
  * --------------------------------------------
  *  RETURNED VALUE OF A NESTED PROPERTY PROVIDING A DOT PATH
  * --------------------------------------------
  */
+/** Returned nested type implementation. */
 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;
+/** Value of a RETURNED nested property of a given dot-path (so when accessing arrays can be undefined). */
 type ReturnedValueInDotPath<TObject, TPath extends DotPaths<TObject> | ''> = ReturnedNestedValue<TObject, TPath>;
 /**
  * --------------------------------------------
  *  UPDATE OBJECT WITH DOT PATH IMPLEMENTATION
  * --------------------------------------------
  */
+/** Value of a dot-path update object, can be the value or a function. */
 type DotPathUpdateValue<TObject, TPath extends DotPaths<TObject>> = ValueInDotPath<TObject, TPath> | ((fieldValue: ValueInDotPath<TObject, TPath>, fullObject: TObject) => ValueInDotPath<TObject, TPath>);
+/** Dot-path update object, used to give updates to the updateImmutably function. */
 type DotPathUpdateObject<TObject> = {
     [TPath in DotPaths<TObject>]?: ValueInDotPath<TObject, TPath> | ((fieldValue: ValueInDotPath<TObject, TPath>, fullObject: TObject) => ValueInDotPath<TObject, TPath>);
 };
@@ -52,24 +80,30 @@ type DotPathUpdateObject<TObject> = {
  *  REQUIRED OR OPTIONAL KEYS
  * --------------------------------------------
  */
-type NonPartialKeys = null | object;
-type RetrieveOptionalKeys<T> = {
-    [K in keyof T & string]: T[K] extends NonPartialKeys ? never : K;
-}[keyof T & string];
-type RetrieveRequiredKeys<T> = {
-    [K in keyof T & string]: T[K] extends NonPartialKeys ? K : never;
-}[keyof T & string];
+/** Returns only the optional keys of an object. */
+type OptionalKeys<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
+}[keyof T];
+/** Returns only the required keys of an object. */
+type RequiredKeys<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
 
-type Remove = <T extends object>(value: T, keys: T extends any[] ? (number | `${number}` | (number | `${number}`)[]) : (RetrieveOptionalKeys<T> | (RetrieveOptionalKeys<T>)[])) => T;
+type Remove = <T extends object>(value: T, keys: T extends any[] ? (number | `${number}` | (number | `${number}`)[]) : OptionalKeys<T> | (OptionalKeys<T>)[]) => T;
 /**
  * Removes properties or indexes, order doesn't matter.
+ * @param value Object/array from where to remove keys/indexes shallowly.
+ * @param keys Keys to remove.
+ * @returns New object/array without the provided keys/indexes.
  */
 declare const remove: Remove;
 
 type Select = <TObject, TPath extends DotPaths<TObject> | ''>(state: TObject, path: TPath) => ReturnedValueInDotPath<TObject, TPath>;
 /**
- * Returns the value from a given dot path of an object/array.
- * Returns undefined if the provided path doesnt exist.
+ * Returns the value from a given dot path of an object/array or undefined if doesn't exist.
+ * @param state State from which retrieve the value.
+ * @param path Path indicating the value to extract.
+ * @returns Value of the provided path or undefined.
  */
 declare const select: Select;
 
@@ -77,22 +111,24 @@ type PathWithoutLastKey = string;
 type LastKey = string;
 type SplitDotPathAtLastKey = <T extends string>(dotPath: T) => [PathWithoutLastKey, LastKey];
 /**
- * Splits string dotPath into ID and RemainingPath
-*/
+ * Splits a dot path string into its last key and its remaining keys ('' if none).
+ * @param dotPath A dot path.
+ * @returns [pathWithoutLastKey, lastKey] or ['', lastKey].
+ */
 declare const splitPathAtLastKey: SplitDotPathAtLastKey;
 
 type Set = <T>(newValue: T) => (value: T) => T;
 /**
- * Allows to set strongly typed values (removing inacurate "undefined" inference) in nested values inside arrays
+ * Allows to set strongly typed values (removing inacurate "undefined" inference) in nested values inside arrays.
+ * @param newValue New value.
+ * @returns The same value.
  */
 declare const set: Set;
 
-type UpdateImmutably = <T extends object>(state: T, updates: DotPathUpdateObject<T>, addNonExistentPropsAndIndexes?: true) => T;
-/**
- * Creates a new updated object/array applying the changes provided in the update object.
- * It doesnt modify the original input.
- * If any of the paths doesnt exists it returns
- */
-declare const updateImmutably: UpdateImmutably;
+/** Checks if any provided value is an object literal or not */
+declare const isObjectLiteral: (valueToTest: any) => boolean;
+
+declare const parseStringIndex: (v: string) => number | null;
+declare const isStringIndex: (v: string) => boolean;
 
-export { type DotPathUpdateObject, type DotPathUpdateValue, type DotPaths, type PrimitivesAndNativeObjects, type RetrieveOptionalKeys, type RetrieveRequiredKeys, type ReturnedValueInDotPath, type ValueInDotPath, remove, select, set, splitPathAtLastKey, updateImmutably };
+export { type DotPathUpdateObject, type DotPathUpdateValue, type DotPaths, type OptionalKeys, type PrimitivesAndNativeObjects, type RequiredKeys, type ReturnedValueInDotPath, type ValueInDotPath, isObjectLiteral, isStringIndex, modifyImmutably, parseStringIndex, remove, select, set, splitPathAtLastKey, updateImmutably };

package/dist/index.js

@@ -1 +1 @@
-"use strict";var f=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var j=Object.getOwnPropertyNames;var w=Object.prototype.hasOwnProperty;var D=(t,e)=>{for(var r in e)f(t,r,{get:e[r],enumerable:!0})},v=(t,e,r,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let a of j(e))!w.call(t,a)&&a!==r&&f(t,a,{get:()=>e[a],enumerable:!(o=O(e,a))||o.enumerable});return t};var I=t=>v(f({},"__esModule",{value:!0}),t);var R={};D(R,{remove:()=>b,select:()=>T,set:()=>K,splitPathAtLastKey:()=>P,updateImmutably:()=>x});module.exports=I(R);var b=(t,e)=>{if(!Array.isArray(t)&&t?.constructor!==Object)throw'Wrong type provided in "remove" function';let r=Array.isArray(e)?e:[e];if(Array.isArray(t)){let a=Symbol(),y=[...t];return r.forEach(n=>{y[n]=a}),y.filter(n=>n!==a)}let o={...t};return r.forEach(a=>delete o[a]),o};var T=(t,e)=>!e||typeof e!="string"?t:e.split(".").reduce((r,o)=>{if(r?.hasOwnProperty(o))return r[o]},t);var P=t=>{if(typeof t!="string")throw new Error(`Wrong dotPath type: ${t}`);let e=t.lastIndexOf(".")+1,r=e?t.slice(0,e-1):"",o=t.slice(e);return[r,o]};var K=t=>()=>t;var x=(t,e,r)=>{if(t?.constructor!==Object&&!Array.isArray(t))throw new Error(`${t} is not an object/array`);if(!e)return t;let o=Array.isArray(t)?[...t]:{...t},a={};for(let[y,d]of Object.entries(e)){if(!y)continue;let n=y.split("."),s=n.pop(),u=a,c=o;for(let h=0;h<n.length;h++){let i=n[h],p=c[i],A=typeof p=="object"&&(p.constructor===Object||Array.isArray(p)),m=r&&p===void 0;if(!A&&!m)throw new Error(`Invalid path provided: "${i}" is not an object/array in "${y}"`);u[i]||(m?c[i]=isNaN(n[h+1]??s)?{}:[]:c[i]=Array.isArray(p)?[...p]:{...p},u[i]={}),c=c[i],u=u[i]}let l=c;if(!r){if(Array.isArray(l)&&!(s<l.length))throw new Error(`Index ${s} doesnt exist in the path ${n.join(".")} because its value is ${s}, use spread operator for adding new indexes`);if(!l.hasOwnProperty(s))throw new Error(`Property ${s} doesnt exist in the path ${n.join(".")} because its value is ${l}`)}l[s]=typeof d=="function"?d(l[s],o):d,delete u[s]}return o};0&&(module.exports={remove,select,set,splitPathAtLastKey,updateImmutably});
+"use strict";var b=Object.defineProperty;var S=Object.getOwnPropertyDescriptor;var w=Object.getOwnPropertyNames;var E=Object.prototype.hasOwnProperty;var R=(t,e)=>{for(var r in e)b(t,r,{get:e[r],enumerable:!0})},$=(t,e,r,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of w(e))!E.call(t,n)&&n!==r&&b(t,n,{get:()=>e[n],enumerable:!(o=S(e,n))||o.enumerable});return t};var U=t=>$(b({},"__esModule",{value:!0}),t);var V={};R(V,{isObjectLiteral:()=>d,isStringIndex:()=>h,modifyImmutably:()=>D,parseStringIndex:()=>g,remove:()=>I,select:()=>T,set:()=>O,splitPathAtLastKey:()=>P,updateImmutably:()=>K});module.exports=U(V);var I=(t,e)=>{if(!Array.isArray(t)&&t?.constructor!==Object)throw'Wrong type provided in "remove" function';let r=Array.isArray(e)?e:[e];if(Array.isArray(t)){let n=Symbol(),p=[...t];return r.forEach(a=>{p[a]=n}),p.filter(a=>a!==n)}let o={...t};return r.forEach(n=>delete o[n]),o};var T=(t,e)=>!e||typeof e!="string"?t:e.split(".").reduce((r,o)=>{if(r?.hasOwnProperty(o))return r[o]},t);var P=t=>{if(typeof t!="string")throw new Error(`Wrong dotPath type: ${t}`);let e=t.lastIndexOf(".")+1,r=e?t.slice(0,e-1):"",o=t.slice(e);return[r,o]};var O=t=>()=>t;var d=t=>!!t&&Object.getPrototypeOf(t)===Object.prototype;var g=t=>{let e=parseInt(t);return e.toString()===t?e:null},h=t=>parseInt(t).toString()===t;var A="${number}",j=(t,e,r)=>{if(!d(t)&&!Array.isArray(t))throw new Error(`"${t}" is not an literalObject/array`);if(!e)return t;let o=Array.isArray(t)?[...t]:{...t},n={};for(let[p,m]of Object.entries(e)){if(!p)continue;let a=p.split(".");if(a.includes(A))throw new Error(`"${A}" inside "${p}"`);let i=a.pop(),l=n,y=o;for(let u=0;u<a.length;u++){let s=a[u],c=y[s],L=d(c)||Array.isArray(c),x=r&&c===void 0;if(!L&&!x)throw new Error(`"${s}" doesnt exist in "${a.slice(0,u+1).join(".")}"`);l[s]||(x?y[s]=h(a[u+1]??i)?[]:{}:y[s]=Array.isArray(c)?[...c]:{...c},l[s]={}),y=y[s],l=l[s]}let f=y;if(!r&&!f.hasOwnProperty(i))throw new Error(`Property/Index "${i}" doesnt exist in the path "${a.join(".")+"."+i}". Its value is: "${f}"`);f[i]=typeof m=="function"?m(f[i],o):m,delete l[i]}return o},K=(t,e)=>j(t,e,!1),D=(t,e)=>j(t,e,!0);0&&(module.exports={isObjectLiteral,isStringIndex,modifyImmutably,parseStringIndex,remove,select,set,splitPathAtLastKey,updateImmutably});

package/dist/index.mjs

@@ -1 +1 @@
-var b=(t,e)=>{if(!Array.isArray(t)&&t?.constructor!==Object)throw'Wrong type provided in "remove" function';let o=Array.isArray(e)?e:[e];if(Array.isArray(t)){let p=Symbol(),y=[...t];return o.forEach(a=>{y[a]=p}),y.filter(a=>a!==p)}let r={...t};return o.forEach(p=>delete r[p]),r};var T=(t,e)=>!e||typeof e!="string"?t:e.split(".").reduce((o,r)=>{if(o?.hasOwnProperty(r))return o[r]},t);var P=t=>{if(typeof t!="string")throw new Error(`Wrong dotPath type: ${t}`);let e=t.lastIndexOf(".")+1,o=e?t.slice(0,e-1):"",r=t.slice(e);return[o,r]};var K=t=>()=>t;var x=(t,e,o)=>{if(t?.constructor!==Object&&!Array.isArray(t))throw new Error(`${t} is not an object/array`);if(!e)return t;let r=Array.isArray(t)?[...t]:{...t},p={};for(let[y,d]of Object.entries(e)){if(!y)continue;let a=y.split("."),n=a.pop(),u=p,c=r;for(let h=0;h<a.length;h++){let s=a[h],i=c[s],m=typeof i=="object"&&(i.constructor===Object||Array.isArray(i)),f=o&&i===void 0;if(!m&&!f)throw new Error(`Invalid path provided: "${s}" is not an object/array in "${y}"`);u[s]||(f?c[s]=isNaN(a[h+1]??n)?{}:[]:c[s]=Array.isArray(i)?[...i]:{...i},u[s]={}),c=c[s],u=u[s]}let l=c;if(!o){if(Array.isArray(l)&&!(n<l.length))throw new Error(`Index ${n} doesnt exist in the path ${a.join(".")} because its value is ${n}, use spread operator for adding new indexes`);if(!l.hasOwnProperty(n))throw new Error(`Property ${n} doesnt exist in the path ${a.join(".")} because its value is ${l}`)}l[n]=typeof d=="function"?d(l[n],r):d,delete u[n]}return r};export{b as remove,T as select,K as set,P as splitPathAtLastKey,x as updateImmutably};
+var P=(t,e)=>{if(!Array.isArray(t)&&t?.constructor!==Object)throw'Wrong type provided in "remove" function';let r=Array.isArray(e)?e:[e];if(Array.isArray(t)){let i=Symbol(),p=[...t];return r.forEach(n=>{p[n]=i}),p.filter(n=>n!==i)}let o={...t};return r.forEach(i=>delete o[i]),o};var O=(t,e)=>!e||typeof e!="string"?t:e.split(".").reduce((r,o)=>{if(r?.hasOwnProperty(o))return r[o]},t);var g=t=>{if(typeof t!="string")throw new Error(`Wrong dotPath type: ${t}`);let e=t.lastIndexOf(".")+1,r=e?t.slice(0,e-1):"",o=t.slice(e);return[r,o]};var A=t=>()=>t;var f=t=>!!t&&Object.getPrototypeOf(t)===Object.prototype;var j=t=>{let e=parseInt(t);return e.toString()===t?e:null},h=t=>parseInt(t).toString()===t;var x="${number}",I=(t,e,r)=>{if(!f(t)&&!Array.isArray(t))throw new Error(`"${t}" is not an literalObject/array`);if(!e)return t;let o=Array.isArray(t)?[...t]:{...t},i={};for(let[p,d]of Object.entries(e)){if(!p)continue;let n=p.split(".");if(n.includes(x))throw new Error(`"${x}" inside "${p}"`);let s=n.pop(),l=i,y=o;for(let u=0;u<n.length;u++){let a=n[u],c=y[a],T=f(c)||Array.isArray(c),b=r&&c===void 0;if(!T&&!b)throw new Error(`"${a}" doesnt exist in "${n.slice(0,u+1).join(".")}"`);l[a]||(b?y[a]=h(n[u+1]??s)?[]:{}:y[a]=Array.isArray(c)?[...c]:{...c},l[a]={}),y=y[a],l=l[a]}let m=y;if(!r&&!m.hasOwnProperty(s))throw new Error(`Property/Index "${s}" doesnt exist in the path "${n.join(".")+"."+s}". Its value is: "${m}"`);m[s]=typeof d=="function"?d(m[s],o):d,delete l[s]}return o},K=(t,e)=>I(t,e,!1),D=(t,e)=>I(t,e,!0);export{f as isObjectLiteral,h as isStringIndex,D as modifyImmutably,j as parseStringIndex,P as remove,O as select,A as set,g as splitPathAtLastKey,K as updateImmutably};

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "maraj",
-   "version": "2.4.0",
+   "version": "2.5.0",
    "description": "A lightweight 500 bytes gzipped alternative for immutable updates while dealing with objects and arrays",
    "keywords": [
       "shallow",
@@ -23,6 +23,7 @@
       "test": "vitest run",
       "build": "tsup src/index.ts --minify --format cjs,esm --dts",
       "lint": "tsc",
+      "trace": "tsc --generateTrace trace",
       "ci": "npm run lint && npm run test && npm run build",
       "release": "npm run lint && npm run test && npm run build && changeset publish"
    },
@@ -37,6 +38,7 @@
    "devDependencies": {
       "@changesets/cli": "^2.27.1",
       "@microsoft/api-extractor": "^7.38.5",
+      "@typescript/analyze-trace": "^0.10.1",
       "tsup": "^8.0.1",
       "typescript": "^5.3.3",
       "vitest": "^0.28.4"