maraj 1.0.7 → 1.1.0

package/README.md

@@ -1,134 +1,121 @@
 
 # Maraj
 
-A lightweight alternative for creating **immutable updates of objects and arrays.**
+A lightweight alternative for creating **immutable updates of objects and arrays** such as Immer or ImmutableJS.
 
-**4 times faster** than the commonly used alternatives like Immer or ImmutableJS.
+**4 times faster** and **over 10 times lighter**.
 
-Only **600 bytes** gziped with 5 common utilities that you will most likelly need in every project.
+Only **400 bytes** gziped and additional **300 bytes** for 4 common utilities that you will most likelly need in every project.
 
 Features:
 - Can accept multiple updates while mantaining the order of execution.
 - Easy syntax for conditional updates.
 - Functional updates.
 
+Vitest: https://www.npmjs.com/package/maraj-test
+
 ## Creating an Immutable Update
 
 The **createImmutableUpdate** function has two arguments:
-1. The **original object** we want to update non-destructively
-2. An **update object** with key-value pairs representing the updates we want to make
-
-The **updateObject** has the following syntax:
+1. The **Original object**.
+2. An **Update object** (key-value pairs representing the updates we want to make)
 
-It can accept multiple key-value pairs and the order of execution will be preserved.
+The **Update Object** has the following syntax:
+```js
+{
+    'my.path.separated.by.dots': 'The new value',
+    'another.path': 'new value',
+    'myArray.0.name': 'new name in object inside array at index 0',
+    [false && 'path.conditionalUpdate']: true
+}
+```
+Multiple key-value pairs that mantains the order of execution.
 
-- **Key:** path name of the fiels, separated by commas (same syntax you use to access object/array properties)
+- **Keys:** path name of the fiels, separated by dots.
     - For arrays just use its index value
-    - Can accept conditional statements. (If the key is falsy, undefined or null it will not update the new value into the new object.)
+    - Can accept conditional statements. (If the key = false or undefined or null it will skip that field update.)
 
-- **Value:** can be any type, including a function, where its argument will be the current value and its return value has to be the new value to be updated
+- **Value:** new value, any type. If its a function it ll be called with the current value in that field.
 
 
 ## Example
 
 ```js
-import createImmutableUpdate from 'maraj'
-
-const person = {
-    name: 'Lukasz',
-    country: 'Spain',
-    additionalInfo:{
-        info1: null,
-        info2: null,
-        info3: null,
-        info4: null
-    }
-    projects: [
-        {
-            title: 'portfolio',
-            languages: ['esp','eng'],
-            description: 'lorem ipsum',
-            available: false,
-            data:{
-                createdAt: '01-01-2000',
-                size: 20000
-            }
-        },
-        {
-            title: 'asia',
-            languages: ['esp','eng'],
-            description: 'lorem ipsum',
-            available: true,
-            data:{
-                createdAt: '01-01-2000',
-                size: 40000
-            }
-        },
-        {
-            title: 'pos',
-            languages: ['esp','eng'],
-            description: 'lorem ipsum',
-            available: false,
-            data:{
-                createdAt: '01-01-2000',
-                size: 100000
-            }
-        }
+import createImmutableUpdate, { spread } from "maraj";
+
+const data = {
+    person: { name: "Lukasz", works: ["soum", "fi"] },
+    works: [
+        { title: "soum", size: 90, available: true, info: ["info1"] },
+        { title: "fi", size: 30, available: false, info: ["infoA"] },
     ]
 }
 
-const newUpdatedObject = createImmutableUpdate(person,{
-    'name': 'maraj', //normal update
-    'projects.0.title': 'website', //nested update
-    'projects.1.available': true, //nested update
-    'projects.1.available': (currentValue) => !currentValue, //functional update
-    'projects': (currentValue) => currentValue.filter(project => project.available), //functional update
-    [condition && 'additionalInfo.info1']: 'some info' //conditional update, only if the key is not false/undefined/null
+const newUpdatedObject = createImmutableUpdate(data, {
+    "age": 28, //add new values
+    "person.name": "Lucas", //update values
+    "person.works.1": "gs", //nested array update
+    "works.1.available": (currentValue) => (!currentValue), //functional update
+    [false && "works.0.size"]: 120, //conditional field update
+    "person.works": spread("portfolio") //common utilities
 })
+
+/** Does not make a deep copy and "falsy" fields are ignored */
+newUpdatedObject.works[0] === data.works[0] //true
+
+/** New Updated Object 
+{
+    person: { name: "Lucas", works: ["soum", "gs", "portfolio"], age: 28 },
+    works: [
+        { title: "soum", size: 90, available: true, info: ["info1"] },
+        { title: "fi", size: 30, available: true, info: ["infoA"] },
+    ]
+}
+*/
 ```
 
 ## Other Utilities
 
 ### spread
 
-Spreads its argument into the key provided in the **createImmutableUpdate.**
-
-Works with objects(updates its keys) and arrays(adds new values to the array)
+**For Objects and Arrays: Spreads** its argument into the key provided in the createImmutableUpdate.
+**For the rest: Sets** its argument into the key provided in the createImmutableUpdate.
 
 ```js
 import {spread} from 'maraj'
 
-const newUpdatedObject = createImmutableUpdate(person,{
-    'additionalInfo.info1': spread({info1: 'new Info'}), //same as (newValue) => (value) => ({...value, ...newValue})
-    'projects': spread({title: 'new project'}) //same as (newValueToAdd) => (value) => ([...value, ...newValueToAdd])
+const newUpdatedObject = createImmutableUpdate(data,{
+    'person': spread({info1: 'new Info'}), //same as (newValue) => (value) => ({...value, ...newValue})
+    'works': spread({title: 'new project', size: 20}) //same as (newValueToAdd) => (value) => ([...value, ...newValueToAdd])
+    'person.works': spread("portfolio") //same as (newValue) => (value) => (newValue)
 })
 ```
 
 ### remove
 
-Removes the key of an object or the index of an array in the key provided in the **createImmutableUpdate.**
+Removes the **key of an object** or the **index of an array** in the key provided in the **createImmutableUpdate.**
 
 ```js
 import {remove} from 'maraj'
 
 const newUpdatedObject = createImmutableUpdate(person,{
-    'additionalInfo': remove('info1'), // returns new value (in this case "additionalInfo") without the provided key ("info1")
-    'projects': remove(1) // returns new array (in this case "projects") without the provided index (1)
+    'person': remove('works'), // returns new value (in this case "person") without the provided key ("works")
+    'works': remove(1) // returns new array (in this case "works") without the provided index (1)
 })
 ```
 
 ### createSelectorFromStringPath
 
-Creates a store selector from provided string path.
+**Creates a store selector** from provided string path.
 
 Usefull in cases like getting data from Redux, Zustand, and so on. stores.
 
 ```js
 import {createSelectorFromStringPath} from 'maraj'
 
-const stringPath = 'projects.1.data.size'
+const stringPath = 'works.1.size'
 
-const storeSelector = createSelectorFromStringPath(stringPath) // will behave as (store) => store[projects][1][data][size]
+const storeSelector = createSelectorFromStringPath(stringPath) // will behave as (store) => store[works][1][size]
 ```
 
 ### splitPath
@@ -137,4 +124,15 @@ Usefull when you want to spread multiple values into objects dynamically
 
 Splits string path (example:'projects.1.data.size' ) into two:
 - id: the last key in the path (in this case 'size')
-- remainingPath: the remaining path (in this case 'projects.1.data')
+- remainingPath: the remaining path (in this case 'projects.1.data')
+
+
+```js
+import {splitPath} from 'maraj'
+
+const stringPath = 'works.1.size'
+
+const { id, remainingPath } = splitPath(stringPath)
+// id = 'size'
+// remainingPath = 'works.1'
+```

package/maraj.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file maraj.js is the root file for this example app
+ * @author Lukasz Maraj
+ * @see <a href="https://lukaszmaraj.com">Lukasz Maraj</a>
+ */
+/**
+ * Returns a new updated state (new object/array)
+ * @param {object} state - object or array to update immutably
+ * @param {object} update - update object
+ * @returns - new updated state
+ */
+declare const createImmutableUpdate: (state: any, update?: {}) => any;
+export default createImmutableUpdate;
+/**
+ * Spreads if its an object or array to the target, if its not then it sets its value
+ * @param {*} update - any
+ * @returns - updated value; spreaded if object/array, overwritted for the rest of the cases
+ */
+export declare const spread: (update: any) => (value: any) => any;
+/**
+ * Removes properties or indexes; skips the ones dont exist
+ * @param {string | number | string[] | number[]} keys - properties or indexes to be removed
+ * @returns - new updated value
+ */
+export declare const remove: (keys: string | number | string[] | number[]) => (value: any) => any;
+/**
+ * Creates a selector with a string path
+ * @param {string} path - path, ex: 'login.form.username.value'
+ * @returns - store selector
+ */
+export declare const createSelectorFromStringPath: (path: string) => (state: any) => any;
+/**
+ * Splits string path into ID and RemainingPath
+ * @param {string} path - Path separated by dots
+ * @returns {id: string, remainingPath: string} - {id: string, remainingPath: string | ''}
+ */
+export declare const splitPath: (path: string) => {
+    id: string;
+    remainingPath: string;
+};

package/maraj.js

@@ -0,0 +1,99 @@
+/**
+ * @file maraj.js is the root file for this example app
+ * @author Lukasz Maraj
+ * @see <a href="https://lukaszmaraj.com">Lukasz Maraj</a>
+ */
+
+
+/**
+ * Returns a new updated state (new object/array)
+ * @param {object} state - object or array to update immutably
+ * @param {object} update - update object
+ * @returns - new updated state
+ */
+const createImmutableUpdate = (state, update = {}) => {
+    if (state?.constructor !== Object && !Array.isArray(state)) return state
+    const newState = Array.isArray(state) ? [...state] : { ...state }
+    const visited = {}
+    for (const [path, value] of Object.entries(update)) {
+        if (!path || path === 'false' || path === 'undefined' || path === 'null') continue
+        let keys = path.split(".")
+        let lastkey = keys.pop()
+        let tracker = visited
+        let current = newState
+        for (let key of keys) {
+            if (typeof current[key] !== 'object') throw new Error(`Destructure "${key}" in "${path}" with value: ${current[key]}`)
+            if (!tracker[key]) {
+                current[key] = Array.isArray(current[key]) ? [...current[key]] : { ...current[key] }
+                tracker[key] = {}
+            }
+            current = current[key]
+            tracker = tracker[key]
+        }
+        delete tracker[lastkey]
+        current[lastkey] = typeof value === 'function' ? value(current[lastkey]) : value
+    }
+    return newState
+}
+export default createImmutableUpdate
+
+
+/**
+ * Spreads if its an object or array to the target, if its not then it sets its value
+ * @param {*} update - any
+ * @returns - updated value; spreaded if object/array, overwritted for the rest of the cases
+ */
+export const spread = (update) => (value) => {
+    if (value?.constructor === Object && update?.constructor === Object) return { ...value, ...update }
+    if (Array.isArray(value) && Array.isArray(update)) return [...value, ...update]
+    return update
+}
+
+
+/**
+ * Removes properties or indexes; skips the ones dont exist
+ * @param {string | number | string[] | number[]} keys - properties or indexes to be removed
+ * @returns - new updated value
+ */
+export const remove = (keys) => (value) => {
+    if (typeof value !== 'object') return value
+    if (typeof keys !== 'object' || keys === null) keys = [keys]
+    if (Array.isArray(value)) {
+        const values = keys.map(key => value[key])
+        return value.filter(v => (!values.includes(v) || (values.splice(values.indexOf(v), 1) && false)))
+    }
+    const update = { ...value }
+    keys.forEach(key => delete update[key])
+    return update
+}
+
+
+/**
+ * Creates a selector with a string path
+ * @param {string} path - path, ex: 'login.form.username.value'
+ * @returns - store selector
+ */
+export const createSelectorFromStringPath = (path) => (state) => {
+    if (typeof path !== 'string') throw new Error('Path should be string')
+    if (!path) return state
+    return path.split(".").reduce((current, key) => {
+        if (current?.hasOwnProperty(key)) return current[key]
+        throw new Error(`Key "${key}" doesnt exist in "${path}"`)
+    }, state)
+}
+
+
+/**
+ * Splits string path into ID and RemainingPath
+ * @param {string} path - Path separated by dots
+ * @returns {id: string, remainingPath: string} - {id: string, remainingPath: string | ''}
+ */
+// splits a string id path
+export const splitPath = (path) => {
+    if (typeof path !== 'string') throw new Error(`Provided path is not a string ${path}`)
+    const lastDot = path.lastIndexOf(".") + 1
+    return {
+        id: path.slice(lastDot),
+        remainingPath: lastDot ? path.slice(0, lastDot - 1) : ''
+    }
+}

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "maraj",
-  "version": "1.0.7",
-  "description": "A lightweight 600 bytes gzipped alternative for immutable updates while dealing with objects and arrays",
-  "main": "index.js",
+  "version": "1.1.0",
+  "description": "A lightweight 500 bytes gzipped alternative for immutable updates while dealing with objects and arrays",
+  "main": "maraj.js",
+  "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "vitest"
   },
   "author": "Lukasz Maraj",
-  "license": "ISC"
-}
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^4.9.5",
+    "vitest": "^0.28.4"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,104 @@
+{
+  "include": ["./"],
+  "compilerOptions": {
+    /* Visit https://aka.ms/tsconfig to read more about this file */
+
+    /* Projects */
+    // "incremental": true,                              /* Save .tsbuildinfo files to allow for incremental compilation of projects. */
+    // "composite": true,                                /* Enable constraints that allow a TypeScript project to be used with project references. */
+    // "tsBuildInfoFile": "./.tsbuildinfo",              /* Specify the path to .tsbuildinfo incremental compilation file. */
+    // "disableSourceOfProjectReferenceRedirect": true,  /* Disable preferring source files instead of declaration files when referencing composite projects. */
+    // "disableSolutionSearching": true,                 /* Opt a project out of multi-project reference checking when editing. */
+    // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
+
+    /* Language and Environment */
+    "target": "ES2017",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+    // "lib": [],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
+    // "jsx": "preserve",                                /* Specify what JSX code is generated. */
+    // "experimentalDecorators": true,                   /* Enable experimental support for TC39 stage 2 draft decorators. */
+    // "emitDecoratorMetadata": true,                    /* Emit design-type metadata for decorated declarations in source files. */
+    // "jsxFactory": "",                                 /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */
+    // "jsxFragmentFactory": "",                         /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
+    // "jsxImportSource": "",                            /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */
+    // "reactNamespace": "",                             /* Specify the object invoked for 'createElement'. This only applies when targeting 'react' JSX emit. */
+    // "noLib": true,                                    /* Disable including any library files, including the default lib.d.ts. */
+    // "useDefineForClassFields": true,                  /* Emit ECMAScript-standard-compliant class fields. */
+    // "moduleDetection": "auto",                        /* Control what method is used to detect module-format JS files. */
+
+    /* Modules */
+    "module": "commonjs",                                /* Specify what module code is generated. */
+    // "rootDir": "./",                                  /* Specify the root folder within your source files. */
+    // "moduleResolution": "node",                       /* Specify how TypeScript looks up a file from a given module specifier. */
+    // "baseUrl": "./",                                  /* Specify the base directory to resolve non-relative module names. */
+    // "paths": {},                                      /* Specify a set of entries that re-map imports to additional lookup locations. */
+    // "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */
+    // "typeRoots": [],                                  /* Specify multiple folders that act like './node_modules/@types'. */
+    // "types": [],                                      /* Specify type package names to be included without being referenced in a source file. */
+    // "allowUmdGlobalAccess": true,                     /* Allow accessing UMD globals from modules. */
+    // "moduleSuffixes": [],                             /* List of file name suffixes to search when resolving a module. */
+    // "resolveJsonModule": true,                        /* Enable importing .json files. */
+    // "noResolve": true,                                /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
+
+    /* JavaScript Support */
+    "allowJs": true,                                  /* Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files. */
+    // "checkJs": true,                                  /* Enable error reporting in type-checked JavaScript files. */
+    // "maxNodeModuleJsDepth": 1,                        /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
+
+    /* Emit */
+    "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
+    "declarationMap": true,                           /* Create sourcemaps for d.ts files. */
+    "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
+    // "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */
+    // "outFile": "./",                                  /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
+    "outDir": "dist",                                   /* Specify an output folder for all emitted files. */
+    // "removeComments": true,                           /* Disable emitting comments. */
+    // "noEmit": true,                                   /* Disable emitting files from a compilation. */
+    // "importHelpers": true,                            /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
+    // "importsNotUsedAsValues": "remove",               /* Specify emit/checking behavior for imports that are only used for types. */
+    // "downlevelIteration": true,                       /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
+    // "sourceRoot": "",                                 /* Specify the root path for debuggers to find the reference source code. */
+    // "mapRoot": "",                                    /* Specify the location where debugger should locate map files instead of generated locations. */
+    // "inlineSourceMap": true,                          /* Include sourcemap files inside the emitted JavaScript. */
+    // "inlineSources": true,                            /* Include source code in the sourcemaps inside the emitted JavaScript. */
+    // "emitBOM": true,                                  /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
+    // "newLine": "crlf",                                /* Set the newline character for emitting files. */
+    // "stripInternal": true,                            /* Disable emitting declarations that have '@internal' in their JSDoc comments. */
+    // "noEmitHelpers": true,                            /* Disable generating custom helper functions like '__extends' in compiled output. */
+    // "noEmitOnError": true,                            /* Disable emitting files if any type checking errors are reported. */
+    // "preserveConstEnums": true,                       /* Disable erasing 'const enum' declarations in generated code. */
+    // "declarationDir": "./",                           /* Specify the output directory for generated declaration files. */
+    // "preserveValueImports": true,                     /* Preserve unused imported values in the JavaScript output that would otherwise be removed. */
+
+    /* Interop Constraints */
+    // "isolatedModules": true,                          /* Ensure that each file can be safely transpiled without relying on other imports. */
+    // "allowSyntheticDefaultImports": true,             /* Allow 'import x from y' when a module doesn't have a default export. */
+    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
+    // "preserveSymlinks": true,                         /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
+    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
+
+    /* Type Checking */
+    "strict": true,                                      /* Enable all strict type-checking options. */
+    // "noImplicitAny": true,                            /* Enable error reporting for expressions and declarations with an implied 'any' type. */
+    // "strictNullChecks": true,                         /* When type checking, take into account 'null' and 'undefined'. */
+    // "strictFunctionTypes": true,                      /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
+    // "strictBindCallApply": true,                      /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */
+    // "strictPropertyInitialization": true,             /* Check for class properties that are declared but not set in the constructor. */
+    // "noImplicitThis": true,                           /* Enable error reporting when 'this' is given the type 'any'. */
+    // "useUnknownInCatchVariables": true,               /* Default catch clause variables as 'unknown' instead of 'any'. */
+    // "alwaysStrict": true,                             /* Ensure 'use strict' is always emitted. */
+    // "noUnusedLocals": true,                           /* Enable error reporting when local variables aren't read. */
+    // "noUnusedParameters": true,                       /* Raise an error when a function parameter isn't read. */
+    // "exactOptionalPropertyTypes": true,               /* Interpret optional property types as written, rather than adding 'undefined'. */
+    // "noImplicitReturns": true,                        /* Enable error reporting for codepaths that do not explicitly return in a function. */
+    // "noFallthroughCasesInSwitch": true,               /* Enable error reporting for fallthrough cases in switch statements. */
+    // "noUncheckedIndexedAccess": true,                 /* Add 'undefined' to a type when accessed using an index. */
+    // "noImplicitOverride": true,                       /* Ensure overriding members in derived classes are marked with an override modifier. */
+    // "noPropertyAccessFromIndexSignature": true,       /* Enforces using indexed accessors for keys declared using an indexed type. */
+    // "allowUnusedLabels": true,                        /* Disable error reporting for unused labels. */
+    // "allowUnreachableCode": true,                     /* Disable error reporting for unreachable code. */
+
+    /* Completeness */
+    // "skipDefaultLibCheck": true,                      /* Skip type checking .d.ts files that are included with TypeScript. */
+    "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
+  }
+}

package/index.js

@@ -1,49 +0,0 @@
-//creates a shallow deep copy with the only needed updated fields
-const createImmutableUpdate = (state, update = {}) => {
-    const newState = Array.isArray(state) ? [...state] : { ...state }
-    const visited = {}
-    for (const [path, value] of Object.entries(update)) {
-        if (!path || path === 'false' || path === 'undefined' || path === 'null') continue
-        let keys = path.split(".")
-        let lastkey = keys.pop()
-        let tracker = visited
-        let current = newState
-        for (let key of keys) {
-            if (typeof current[key] !== 'object') throw new Error(`Destructure "${key}" in "${path}" with value: ${current[key]}`)
-            if (!tracker[key]) {
-                current[key] = Array.isArray(current[key]) ? [...current[key]] : { ...current[key] }
-                tracker[key] = {}
-            }
-            current = current[key]
-            tracker = tracker[key]
-        }
-        delete tracker[lastkey]
-        current[lastkey] = typeof value === 'function' ? value(current[lastkey]) : value
-    }
-    return newState
-}
-export default createImmutableUpdate
-
-export const createSelectorFromStringPath = (path) => (state) => path.split(".").reduce((current, key) => current[key], state)
-
-// spread object or array, if its not object or array it just assigns its value
-export const spread = (update) => (value) => {
-    if (value?.constructor === Object && update?.constructor === Object) return { ...value, ...update }
-    if (Array.isArray(value) && Array.isArray(update)) return [...value, ...update]
-    return update
-}
-
-// a string/number/array of index or properties(key)
-export const remove = (keys) => (value) => {
-    if (typeof value !== 'object') return value
-    if (typeof keys !== 'object') keys = [keys]
-    if (Array.isArray(value)) return value.filter((v, i) => (!keys.includes(i) || (keys.splice(keys.indexOf(i), 1) && false)))
-    const update = { ...value }
-    keys.forEach(key => delete update[key])
-    return update
-}
-// splits a string id path
-export const splitPath = (path) => ({
-    remainingPath: path.slice(0, path.lastIndexOf(".") + 1),
-    id: path.slice(path.lastIndexOf(".") + 1),
-})