@magic/deep 0.1.15 → 0.1.17

package/README.md

@@ -23,11 +23,13 @@ Work with deeply nested objects and arrays.
 [snyk-url]: https://snyk.io/test/github/magic/deep
 
 ##### install
+
 ```bash
 npm i --save --save-exact @magic/deep
 ```
 
 ##### import
+
 ```javascript
 // single function
 import { equal, flatten, loop, merge } from '@magic/deep'
@@ -39,27 +41,29 @@ import deep from '@magic/deep'
 Currently implemented:
 
 ##### deep.equal
+
 ```javascript
 // test equality
 deep.equal(['shallow', ['deep']], ['shallow', ['deep']])
 // true
 
 // alias
-deep.equals, deep.eq
+// deep.equals, deep.eq
 ```
 
 ##### deep.different
+
 ```javascript
 // test difference
 deep.different(['shallow', ['deep']], ['shallow', ['deep']])
 // false
 
 // alias
-deep.diff
+// deep.diff
 ```
 
-
 ##### deep.flatten
+
 ```javascript
 // flatten a deeply nested array
 deep.flatten(['shallow', ['deep']])
@@ -67,6 +71,7 @@ deep.flatten(['shallow', ['deep']])
 ```
 
 ##### deep.loop
+
 ```javascript
 // apply function add
 const add = e => e + 1
@@ -82,11 +87,12 @@ deep.loop(items, add)
 ```
 
 ##### deep.merge
+
 ```javascript
 // merge objects and arrays, with infinite recursion if needed.
 // this can be slow...
 
-deep.merge({ obj1Key: { val: 1 } }, { obj2Key: { val: 2 } } )
+deep.merge({ obj1Key: { val: 1 } }, { obj2Key: { val: 2 } })
 
 // { obj1Key: { val: 1}, obj2Key: { val: 2 } }
 
@@ -98,56 +104,82 @@ deep.merge({ key: { val: 1, str: 'test' } }, { key: { val: 2, str: 'overwritten'
 ### Changelog
 
 #### 0.1.0
+
 use ecmascript modules instead of commonjs.
 
 #### 0.1.1
-* update readme
-* also export deep.eq alias for deep.equal
+
+- update readme
+- also export deep.eq alias for deep.equal
 
 #### 0.1.2
-* require node 13.5.0
-* use deep.equal and deep.different from @magic/types
+
+- require node 13.5.0
+- use deep.equal and deep.different from @magic/types
 
 #### 0.1.3
+
 bump required node version to 14.2.0
 
-#### 0.1.4 
+#### 0.1.4
+
 update dependencies
 
 #### 0.1.5
-* bump required node version to 14.15.4
-* update dependencies
+
+- bump required node version to 14.15.4
+- update dependencies
 
 ##### 0.1.6
-* merge now checks if o2.hasOwnProperty is a function before using it to check if we should overwrite keys of o1 or not.
 
-##### 0.1.7 
+- merge now checks if o2.hasOwnProperty is a function before using it to check if we should overwrite keys of o1 or not.
+
+##### 0.1.7
+
 update @magic/types to avoid circular dependency
 
 ##### 0.1.8
-* update dependencies
-* use @magic/types for all type comparisons
+
+- update dependencies
+- use @magic/types for all type comparisons
 
 ##### 0.1.9
+
 update dependencies
 
 ##### 0.1.10
+
 update dependencies
 
 ##### 0.1.11
+
 update dependencies
 
 ##### 0.1.12
+
 update dependencies
 
-##### 0.0.13
+##### 0.1.13
+
 update dependencies
 
-##### 0.0.14
+##### 0.1.14
+
 update dependencies
 
-##### 0.0.15
+##### 0.1.15
+
+update dependencies
+
+##### 0.1.16
+
 update dependencies
 
-##### 0.0.16 - unreleased
+##### 0.1.17
+
+- add typescript types
+- update dependencies
+
+##### 0.1.18 - unreleased
+
 ...

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@magic/deep",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "author": "Wizards & Witches",
   "description": "manipulate nested objects and arrays",
   "homepage": "https://github.com/magic/deep",
   "license": "AGPL-3.0",
-  "main": "src/index.mjs",
-  "module": "src/index.mjs",
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "module": "src/index.js",
   "type": "module",
   "scripts": {
     "start": "t",
+    "build": "tsc && npm run format",
+    "prepublishOnly": "npm run build",
     "test": "t",
     "format": "f -w",
     "format:check": "f",
@@ -30,11 +33,13 @@
     "src"
   ],
   "dependencies": {
-    "@magic/types": "0.1.22"
+    "@magic/types": "0.1.26"
   },
   "devDependencies": {
-    "@magic/format": "0.0.41",
-    "@magic/test": "0.2.12"
+    "@magic/format": "0.0.68",
+    "@magic/test": "0.2.20",
+    "@types/node": "24.5.2",
+    "typescript": "5.9.2"
   },
   "contributors": [
     {

package/src/flatten.js

@@ -0,0 +1,33 @@
+import is from '@magic/types'
+
+/**
+ * Flattens one level of an array if input is an array, otherwise returns the input as-is.
+ *
+ * @template T
+ * @param {T | T[]} flat - An array or value to flatten.
+ * @returns {T[]} The flattened value or array.
+ */
+export const shallow = flat => (is.array(flat) ? flatten(...flat) : [flat])
+
+/**
+ * Concatenates a flat array with another deep value or array.
+ *
+ * @template T
+ * @param {T[]} flat - The flat array to concatenate into.
+ * @param {T | T[]} deep - A value or array to be flattened and concatenated.
+ * @returns {T[]} The concatenated array.
+ */
+export const concat = (flat, deep) => flat.concat(shallow(deep))
+
+/**
+ * Recursively flattens one or more arrays into a single-level array.
+ *
+ * @template T
+ * @param {...(T | T[])} arr - The arrays or values to flatten.
+ * @returns {T[]} The flattened array.
+ */
+export const flatten = (...arr) =>
+  /** @type {T[]} */ (arr.reduce(/** @type {any} */ (concat), /** @type {T[]} */ ([])))
+
+/** @type {(arr: any[]) => any[]} */
+export default flatten

package/src/{index.mjs → index.js}

@@ -1,8 +1,8 @@
 import is from '@magic/types'
 
-import { loop as lo } from './loop.mjs'
-import { merge as me } from './merge.mjs'
-import { flatten as fl } from './flatten.mjs'
+import { loop as lo } from './loop.js'
+import { merge as me } from './merge.js'
+import { flatten as fl } from './flatten.js'
 
 export const equal = is.deep.equal
 export const equals = is.deep.equal

package/src/loop.js

@@ -0,0 +1,94 @@
+import is from '@magic/types'
+
+/**
+ * Recursively applies a function to items or transforms items based on conditions.
+ *
+ * @template T, R
+ * @param {((item: T) => R) | T} fn - Function to apply or the first item.
+ * @param {...any} items - Items to loop over (can be nested arrays).
+ * @returns {any} The transformed result, array of results, or undefined.
+ */
+export const loop = (fn, ...items) => {
+  // If no arguments, return undefined
+  if (!fn && items.length === 0) {
+    return undefined
+  }
+
+  // If only function provided, return undefined
+  if (is.function(fn) && items.length === 0) {
+    return undefined
+  }
+
+  let targets = items
+
+  // Check for argument swapping: if fn is not a function but we have items and one of them is a function
+  if (!is.function(fn) && items.length > 0) {
+    const functionIndex = items.findIndex(item => is.function(item))
+    if (functionIndex !== -1) {
+      // Swap: fn becomes the target, and the function becomes fn
+      const actualFn = items[functionIndex]
+      targets = [fn, ...items.slice(0, functionIndex), ...items.slice(functionIndex + 1)]
+      fn = actualFn
+    }
+  }
+
+  // Handle the case where we have multiple items but one of them is an object (options)
+  if (is.array(targets) && targets.length > 1) {
+    // Check if any item is an object (options pattern)
+    const hasOptions = targets.some(item => is.object(item) && !is.array(item))
+
+    if (hasOptions && is.function(fn)) {
+      // Apply function to each item
+      return targets.map(item => {
+        if (is.array(item)) {
+          return item.map(subItem => loop(fn, subItem))
+        }
+        return is.object(item) && !is.array(item)
+          ? item
+          : /** @type {(item: any) => any} */ (fn)(item)
+      })
+    }
+
+    if (!is.function(fn)) {
+      return [fn, ...targets]
+    }
+
+    // Apply function to multiple items
+    return targets.map(item => {
+      if (is.array(item)) {
+        return item.map(subItem => loop(fn, subItem))
+      }
+      return /** @type {(item: any) => any} */ (fn)(item)
+    })
+  }
+
+  // Single item case - if targets is an array with one element, unwrap it
+  if (is.array(targets) && targets.length === 1) {
+    targets = /** @type {any} */ (targets[0])
+  }
+
+  // If fn is not a function, return tuple
+  if (!is.function(fn)) {
+    return [fn, targets]
+  }
+
+  // If targets is null/undefined, apply function directly
+  if (!targets) {
+    return fn(targets)
+  }
+
+  // If targets has map method (is array-like), map over it
+  if (is.array(targets)) {
+    return targets.map(item => {
+      if (is.array(item)) {
+        return loop(fn, item)
+      }
+      return /** @type {(item: any) => any} */ (fn)(item)
+    })
+  }
+
+  // For non-array targets, apply function directly
+  return /** @type {(item: any) => any} */ (fn)(targets)
+}
+
+export default loop

package/src/{merge.mjs → merge.js}

@@ -1,5 +1,14 @@
 import is from '@magic/types'
 
+/**
+ * Recursively merges two values or objects.
+ *
+ * @template T
+ * @template U
+ * @param {T} o1 - First value or object.
+ * @param {U} o2 - Second value or object.
+ * @returns {any} Merged result.
+ */
 export const merge = (o1, o2) => {
   if (is.undefined(o1)) {
     return o2
@@ -8,15 +17,16 @@ export const merge = (o1, o2) => {
   }
 
   if (is.array(o1)) {
-    return o1.concat(o2)
+    return is.array(o2)
+      ? /** @type {any[]} */ (o1).concat(/** @type {any[]} */ (o2))
+      : /** @type {any[]} */ (o1).concat([o2])
   } else if (is.array(o2)) {
-    return [].concat(o1, ...o2)
+    return [o1].concat(/** @type {any[]} */ (o2))
   }
 
   if (is.mergeable(o1) && is.mergeable(o2)) {
     const keys = Object.keys({ ...o1, ...o2 })
-    const final = {}
-
+    const final = /** @type {Record<string, any>} */ ({})
     keys.forEach(key => {
       if (!is.function(o2.hasOwnProperty) || !o2.hasOwnProperty(key)) {
         final[key] = o1[key]
@@ -24,7 +34,6 @@ export const merge = (o1, o2) => {
         final[key] = merge(o1[key], o2[key])
       }
     })
-
     return final
   }
 

package/src/flatten.mjs

@@ -1,9 +0,0 @@
-import is from '@magic/types'
-
-export const shallow = flat => (is.array(flat) ? flatten(...flat) : flat)
-
-export const concat = (flat, deep) => flat.concat(shallow(deep))
-
-export const flatten = (...arr) => arr.reduce(concat, [])
-
-export default flatten

package/src/loop.mjs

@@ -1,35 +0,0 @@
-import is from '@magic/types'
-
-export const loop = (fn, ...items) => {
-  if (is.empty(items)) {
-    if (is.fn(fn)) {
-      return fn(...items)
-    }
-
-    return
-  } else if (items.length === 1) {
-    items = items[0]
-  }
-
-  if (!is.function(fn) && is.function(items)) {
-    const oldFn = fn
-    fn = items
-    items = oldFn
-  }
-
-  if (!is.function(fn)) {
-    return [fn, items]
-  }
-
-  if (!items) {
-    return fn(items)
-  }
-
-  if (!is.function(items.map)) {
-    return fn(items)
-  }
-
-  return items.map(item => loop(fn, item))
-}
-
-export default loop