@homer0/object-utils 1.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Leonardo Apiwan (@homer0)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,228 @@
+# 🧰 Object utils
+
+A small collection of utility methods to work with objects. It relies on [`extend`](https://www.npmjs.com/package/extend) for deep merge and copy.
+
+## 🍿 Usage
+
+> If you are wondering why I built this, go to the [Motivation](#motivation) section.
+
+- ⚙️ [Functions](#%EF%B8%8F-functions)
+- 🤘 [Development](#-development)
+
+### ⚙️ Functions
+
+- [`merge`](#merge)
+- [`copy`](#copy)
+- [`get`](#get)
+- [`set`](#set)
+- [`extract`](#extract)
+- [`remove`](#remove)
+- [`flat`](#flat)
+- [`unflat`](#unflat)
+- [`formatKeys`](#formatKeys)
+
+#### `merge`
+
+Makes a deep merge of a list of objects.
+
+```js
+import { merge } from '@homer0/object-utils';
+
+const objA = { a: 'first' };
+const objB = { b: 'second' };
+
+console.log(merge(objA, objB));
+// Will output { a: 'first', b: 'second' }
+```
+
+#### `copy`
+
+Makes a deep copy of an object.
+
+```js
+import { copy } from '@homer0/object-utils';
+
+const objA = { a: 'first' };
+const objB = copy(objA);
+objA.b = 'second';
+
+console.log(objB);
+// Will output { a: 'first' }
+```
+
+### `get`
+
+Reads a property from an object using a path:
+
+```js
+import { get } from '@homer0/object-utils';
+
+const obj = {
+  propOne: {
+    propOneSub: 'Charito!',
+  },
+  propTwo: '!!!',
+};
+
+console.log(
+  get({
+    target: obj,
+    path: 'propOne.propOneSub',
+  }),
+);
+// Will output 'Charito!'
+```
+
+#### `set`
+
+Sets a property on an object using a path. If the path doesn't exist, it will be created.
+
+```js
+import { set } from '@homer0/object-utils';
+
+const target = {};
+
+console.log(
+  set({
+    target,
+    path: 'some.prop.path',
+    value: 'some-value',
+  }),
+);
+// Will output { some: { prop: { path: 'some-value' } } }
+```
+
+#### `extract`
+
+Extracts a property or properties from an object in order to create a new one.
+
+```js
+import { extract } from '@homer0/object-utils';
+
+const target = {
+  name: {
+    first: 'Pilar',
+  },
+  age: 2,
+  address: {
+    planet: 'earth',
+    something: 'else',
+  },
+};
+
+console.log(
+  set({
+    target: obj,
+    paths: [{ name: 'name.first' }, 'age', 'address.planet'],
+  }),
+);
+// Will output { name: 'Pilar', age: 2, address: { planet: 'earth' } }
+```
+
+#### `remove`
+
+Deletes a property of an object using a path. If by removing a property of a sub object, the object has no more keys, it also removes it.
+
+```js
+import { remove } from '@homer0/object-utils';
+
+const target = {
+  propOne: {
+    propOneSub: 'Charito!',
+  },
+  propTwo: '!!!',
+};
+
+console.log(
+  remove({
+    target,
+    path: 'propOne.propOneSub',
+  }),
+);
+// Will output { propTwo: '!!!' }
+```
+
+#### `flat`
+
+Flattens an object properties into a single level dictionary.
+
+```js
+import { flat } from '@homer0/object-utils';
+
+const target = {
+  propOne: {
+    propOneSub: 'Charito!',
+  },
+  propTwo: '!!!',
+};
+
+console.log(flat({ target }));
+// Will output { 'propOne.propOneSub': 'Charito!', propTwo: '!!!' }
+```
+
+#### `unflat`
+
+This method does the exact opposite from `flat`: It takes an already flatten object and restores its structure.
+
+```js
+import { unflat } from '@homer0/object-utils';
+
+const target = {
+  'propOne.propOneSub': 'Charito!
+  propTwo: '!!!',
+};
+
+console.log(unflat({ target }));
+// Will output { propOne: { propOneSub: 'Charito!' }, 'propTwo': '!!!' }
+```
+
+#### `formatKeys`
+
+Formats all the keys on an object using a way similar to `.replace(regexp, ...)` but that also works recursively and with _"object paths"_.
+
+```js
+import { formatKeys } from '@homer0/object-utils';
+
+const target = {
+  prop_one: 'Charito!',
+};
+
+console.log(
+  formatKeys({
+    target,
+    // Find all the keys with snake case.
+    search: /([a-z])_([a-z])/g,
+    // Using the same .replace style callback, replace it with lower camel case.
+    replace: (_, firstLetter, secondLetter) => {
+      const newSecondLetter = secondLetter.toUpperCase();
+      return `${firstLetter}${newSecondLetter}`;
+    },
+  }),
+);
+```
+
+There are also a few "shorthand implementations" of `formatKeys`:
+
+- `lowerCamelToSnakeKeys(...)`
+- `lowerCamelToDashKeys(...)`
+- `snakeToLowerCamelKeys(...)`
+- `snakeToDashKeys(...)`
+- `dashToLowerCamelKeys(...)`
+- `dashToSnakeKeys(...)`
+
+### 🤘 Development
+
+As this project is part of the `packages` monorepo, it requires Yarn, and some of the tooling, like ESLint and Husky, are installed on the root's `package.json`.
+
+#### Yarn tasks
+
+| Task    | Description          |
+| ------- | -------------------- |
+| `test`  | Runs the unit tests. |
+| `build` | Bundles the project. |
+
+## Motivation
+
+This used to be part of the [`wootils`](https://www.npmjs.com/package/wootils) package, my personal lib of utilities, but I decided to extract them into individual packages, as part of the `packages` monorepo, and take the oportunity to migrate them to TypeScript.
+
+What I like most about this library is that it's VERY small, and it only has one single dependency.

package/dist/esm/index.js

@@ -0,0 +1,363 @@
+// src/fns/merge.ts
+import extend from "extend";
+var merge = (...targets) => {
+  const [firstTarget] = targets;
+  const base = Array.isArray(firstTarget) ? [] : {};
+  return extend(true, base, ...targets);
+};
+
+// src/fns/copy.ts
+var copy = (target) => merge(target);
+
+// src/fns/formatKeys.ts
+var formatKeys = (options) => {
+  const {
+    target,
+    search,
+    replace,
+    include = [],
+    exclude = [],
+    pathDelimiter = "."
+  } = options;
+  const useTarget = target;
+  const keys = Object.keys(target);
+  const hasChildrenByKey = {};
+  keys.forEach((key) => {
+    const value = useTarget[key];
+    hasChildrenByKey[key] = !!(value && typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value));
+  });
+  const escapedPathDelimiter = pathDelimiter.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, "\\$&");
+  const cleanPathStartExpression = new RegExp(`^${escapedPathDelimiter}`, "i");
+  const cleanPathEndExpression = new RegExp(`${escapedPathDelimiter}$`, "i");
+  const subIncludeByKey = {};
+  let keysToFormat;
+  if (include.length) {
+    keysToFormat = include.map((includePath) => {
+      const useIncludePath = includePath.replace(cleanPathStartExpression, "").replace(cleanPathEndExpression, "");
+      let key;
+      if (useIncludePath.includes(pathDelimiter)) {
+        const pathParts = useIncludePath.split(pathDelimiter);
+        const pathKey = pathParts.shift();
+        key = "";
+        if (!subIncludeByKey[pathKey]) {
+          subIncludeByKey[pathKey] = [];
+        }
+        subIncludeByKey[pathKey].push(pathParts.join(pathDelimiter));
+      } else {
+        key = useIncludePath;
+      }
+      return key;
+    }).filter((key) => key);
+  } else {
+    keysToFormat = keys;
+  }
+  const subExcludeByKey = {};
+  if (exclude.length) {
+    const keysToRemove = [];
+    exclude.forEach((excludePath) => {
+      const useExcludePath = excludePath.replace(cleanPathStartExpression, "").replace(cleanPathEndExpression, "");
+      if (useExcludePath.includes(pathDelimiter)) {
+        const pathParts = useExcludePath.split(pathDelimiter);
+        const pathKey = pathParts.shift();
+        if (!subExcludeByKey[pathKey]) {
+          subExcludeByKey[pathKey] = [];
+        }
+        subExcludeByKey[pathKey].push(pathParts.join(pathDelimiter));
+      } else {
+        hasChildrenByKey[useExcludePath] = false;
+        keysToRemove.push(useExcludePath);
+      }
+    });
+    keysToFormat = keysToFormat.filter((key) => key && !keysToRemove.includes(key));
+  }
+  return keys.reduce((newObj, key) => {
+    let newKey;
+    let newValue;
+    const value = useTarget[key];
+    if (keysToFormat.includes(key)) {
+      newKey = key.replace(search, replace);
+    } else {
+      newKey = key;
+    }
+    if (hasChildrenByKey[key]) {
+      newValue = formatKeys({
+        target: value,
+        search,
+        replace,
+        include: subIncludeByKey[key] || [],
+        exclude: subExcludeByKey[key] || [],
+        pathDelimiter
+      });
+    } else {
+      newValue = value;
+    }
+    return { ...newObj, [newKey]: newValue };
+  }, {});
+};
+
+// src/fns/dashToLowerCamelKeys.ts
+var dashToLowerCamelKeys = (options) => formatKeys({
+  ...options,
+  search: /([a-z])-([a-z])/g,
+  replace: (_, firstLetter, secondLetter) => {
+    const newSecondLetter = secondLetter.toUpperCase();
+    return `${firstLetter}${newSecondLetter}`;
+  }
+});
+
+// src/fns/dashToSnakeKeys.ts
+var dashToSnakeKeys = (options) => formatKeys({
+  ...options,
+  search: /([a-z])-([a-z])/g,
+  replace: (_, firstLetter, secondLetter) => `${firstLetter}_${secondLetter}`
+});
+
+// src/fns/get.ts
+var get = (options) => {
+  const { target, path, pathDelimiter = ".", failWithError = false } = options;
+  const useTarget = target;
+  const parts = path.split(pathDelimiter);
+  const first = parts.shift();
+  let currentElement = useTarget[first];
+  if (typeof currentElement === "undefined") {
+    if (failWithError) {
+      throw new Error(`There's nothing on '${path}'`);
+    }
+    return void 0;
+  }
+  if (!parts.length) {
+    return currentElement;
+  }
+  let currentPath = first;
+  parts.some((currentPart) => {
+    let breakLoop = false;
+    currentPath += `${pathDelimiter}${currentPart}`;
+    currentElement = currentElement[currentPart];
+    if (typeof currentElement === "undefined") {
+      if (failWithError) {
+        throw new Error(`There's nothing on '${currentPath}'`);
+      } else {
+        breakLoop = true;
+      }
+    }
+    return breakLoop;
+  });
+  return currentElement;
+};
+
+// src/fns/set.ts
+var set = (options) => {
+  const { target, path, value, pathDelimiter = ".", failWithError = false } = options;
+  const result = copy(target);
+  if (!path.includes(pathDelimiter)) {
+    result[path] = value;
+    return result;
+  }
+  const parts = path.split(pathDelimiter);
+  const last = parts.pop();
+  let currentElement = result;
+  let currentPath = "";
+  let foundInvalid = false;
+  parts.forEach((part) => {
+    currentPath += `${pathDelimiter}${part}`;
+    const element = currentElement[part];
+    const elementType = typeof element;
+    if (elementType === "undefined") {
+      currentElement[part] = {};
+      currentElement = currentElement[part];
+    } else if (elementType === "object") {
+      currentElement = currentElement[part];
+    } else {
+      const errorPath = currentPath.substring(pathDelimiter.length);
+      if (failWithError) {
+        throw new Error(`There's already an element of type '${elementType}' on '${errorPath}'`);
+      } else {
+        foundInvalid = true;
+      }
+    }
+  });
+  if (foundInvalid)
+    return void 0;
+  if (result && last) {
+    currentElement[last] = value;
+  }
+  return result;
+};
+
+// src/fns/extract.ts
+var extract = (options) => {
+  const { target, paths, pathDelimiter = ".", failWithError = false } = options;
+  const copied = copy(target);
+  let result = {};
+  let failed = false;
+  (Array.isArray(paths) ? paths : [paths]).reduce((acc, objPath) => {
+    let destPath;
+    let originPath;
+    if (typeof objPath === "string") {
+      destPath = objPath;
+      originPath = objPath;
+    } else {
+      const [firstKey] = Object.keys(objPath);
+      destPath = firstKey;
+      originPath = objPath[destPath];
+    }
+    acc.push({
+      origin: originPath,
+      customDest: destPath.includes(pathDelimiter),
+      dest: destPath
+    });
+    return acc;
+  }, []).some((pathInfo) => {
+    let breakLoop = false;
+    const value = get({
+      target: copied,
+      path: pathInfo.origin,
+      pathDelimiter,
+      failWithError
+    });
+    if (typeof value !== "undefined") {
+      if (pathInfo.customDest) {
+        const withCustomProp = set({
+          target: result,
+          path: pathInfo.dest,
+          value,
+          pathDelimiter,
+          failWithError
+        });
+        if (typeof withCustomProp === "undefined") {
+          breakLoop = true;
+          failed = true;
+        } else {
+          result = withCustomProp;
+        }
+      } else {
+        result[pathInfo.dest] = value;
+      }
+    }
+    return breakLoop;
+  });
+  if (failed)
+    return void 0;
+  return result;
+};
+
+// src/fns/flat.ts
+var flat = (options) => {
+  const { target, shouldFlatten, pathDelimiter = ".", prefix = "" } = options;
+  const useTarget = target;
+  let result = {};
+  const namePrefix = prefix ? `${prefix}${pathDelimiter}` : "";
+  Object.keys(useTarget).forEach((key) => {
+    const name = `${namePrefix}${key}`;
+    const value = useTarget[key];
+    const valueType = typeof value;
+    const isObject = valueType === "object" && value !== null;
+    if (isObject && (!shouldFlatten || shouldFlatten(key, value))) {
+      result = merge(result, flat({ target: value, pathDelimiter, prefix: name, shouldFlatten }));
+    } else {
+      result[name] = isObject ? copy(value) : value;
+    }
+  });
+  return result;
+};
+
+// src/fns/lowerCamelToDashKeys.ts
+var lowerCamelToDashKeys = (options) => formatKeys({
+  ...options,
+  search: /([a-z])([A-Z])/g,
+  replace: (_, firstLetter, secondLetter) => {
+    const newSecondLetter = secondLetter.toLowerCase();
+    return `${firstLetter}-${newSecondLetter}`;
+  }
+});
+
+// src/fns/lowerCamelToSnakeKeys.ts
+var lowerCamelToSnakeKeys = (options) => formatKeys({
+  ...options,
+  search: /([a-z])([A-Z])/g,
+  replace: (_, firstLetter, secondLetter) => {
+    const newSecondLetter = secondLetter.toLowerCase();
+    return `${firstLetter}_${newSecondLetter}`;
+  }
+});
+
+// src/fns/remove.ts
+var remove = (options) => {
+  const {
+    target,
+    path,
+    pathDelimiter = ".",
+    cleanEmptyProperties = true,
+    failWithError = false
+  } = options;
+  const parts = path.split(pathDelimiter);
+  const last = parts.pop();
+  const result = copy(target);
+  if (!parts.length) {
+    delete result[last];
+    return result;
+  }
+  const parentPath = parts.join(pathDelimiter);
+  const parentObj = get({
+    target: result,
+    path: parentPath,
+    pathDelimiter,
+    failWithError
+  });
+  if (typeof parentObj === "undefined") {
+    return void 0;
+  }
+  delete parentObj[last];
+  if (cleanEmptyProperties && !Object.keys(parentObj).length) {
+    return remove({
+      target: result,
+      path: parentPath,
+      pathDelimiter,
+      failWithError,
+      cleanEmptyProperties
+    });
+  }
+  return result;
+};
+
+// src/fns/snakeToDashKeys.ts
+var snakeToDashKeys = (options) => formatKeys({
+  ...options,
+  search: /([a-z])_([a-z])/g,
+  replace: (_, firstLetter, secondLetter) => `${firstLetter}-${secondLetter}`
+});
+
+// src/fns/snakeToLowerCamelKeys.ts
+var snakeToLowerCamelKeys = (options) => formatKeys({
+  ...options,
+  search: /([a-z])_([a-z])/g,
+  replace: (_, firstLetter, secondLetter) => {
+    const newSecondLetter = secondLetter.toUpperCase();
+    return `${firstLetter}${newSecondLetter}`;
+  }
+});
+
+// src/fns/unflat.ts
+var unflat = (options) => {
+  const { target, pathDelimiter = "." } = options;
+  const useTarget = target;
+  return Object.keys(useTarget).reduce((current, key) => set({ target: current, path: key, value: useTarget[key], pathDelimiter }), {});
+};
+export {
+  copy,
+  dashToLowerCamelKeys,
+  dashToSnakeKeys,
+  extract,
+  flat,
+  formatKeys,
+  get,
+  lowerCamelToDashKeys,
+  lowerCamelToSnakeKeys,
+  merge,
+  remove,
+  set,
+  snakeToDashKeys,
+  snakeToLowerCamelKeys,
+  unflat
+};
+//# sourceMappingURL=index.js.map