@inglorious/utils 3.8.0 → 4.0.0

package/src/data-structures/object.js

@@ -1,320 +0,0 @@
-import { v } from "../v.js"
-import { isArray } from "./array.js"
-
-const INITIAL_LEVEL = 0
-const LAST_KEY_OFFSET = 1
-const NEXT_KEY_OFFSET = 1
-const NEXT_LEVEL = 2
-
-/**
- * Creates a deep clone of a given value using the structured clone algorithm.
- * This is a modern and efficient way to deep-clone objects.
- *
- * Note: `structuredClone` has some limitations. It cannot clone functions,
- * DOM nodes, property descriptors, getters, setters, or certain other
- * non-serializable objects. It will throw a `DataCloneError` in such cases.
- *
- * For more details, see:
- * https://developer.mozilla.org/en-US/docs/Web/API/structuredClone
- *
- * This is similar to Lodash's `_.cloneDeep`.
- *
- * @template T
- * @param {T} obj - The value to clone.
- * @returns {T} A deep clone of the input value.
- */
-export function clone(obj) {
-  return deserialize(serialize(obj))
-}
-
-/**
- * Deserializes an object, converting plain object representations back into
- * their original types, such as vector-like objects. This is the inverse
- * operation of `serialize`.
- *
- * - Recursively deserializes nested objects.
- * - Converts objects with a `_type: "vector"` property and `coords` array
- *   back into a vector-like object using the `v` factory function.
- * - Copies all other property values as-is.
- *
- * @param {string} str - The JSON string to deserialize.
- * @returns {Object} The deserialized object.
- */
-export function deserialize(str) {
-  const data = JSON.parse(str)
-
-  return revive(data)
-
-  function revive(value) {
-    if (isArray(value)) {
-      return value.map(revive)
-    }
-    if (isObject(value)) {
-      if (value._type === "vector" && value.coords) {
-        return v(...value.coords)
-      }
-
-      const deserialized = {}
-      for (const key in value) {
-        if (Object.prototype.hasOwnProperty.call(value, key)) {
-          deserialized[key] = revive(value[key])
-        }
-      }
-      return deserialized
-    }
-    return value
-  }
-}
-
-/**
- * Filters the properties of an object based on a callback function.
- *
- * @param {Object} obj - The object to filter.
- * @param {Function} callback - A function that determines whether a property should be included.
- *                              Receives (key, value, obj) as arguments.
- * @returns {Object} A new object with the filtered properties.
- */
-export function filter(obj, callback) {
-  return Object.fromEntries(
-    Object.entries(obj).filter(([key, value], obj) =>
-      callback(key, value, obj),
-    ),
-  )
-}
-
-/**
- * Finds the first property in an object that satisfies the callback function.
- *
- * @param {Object} obj - The object to search.
- * @param {Function} callback - A function that determines whether a property matches.
- *                              Receives (key, value, obj) as arguments.
- * @returns {Object} An object containing the first matching property, or an empty object if none match.
- */
-export function find(obj, callback) {
-  return Object.fromEntries([
-    Object.entries(obj).find(([key, value], obj) => callback(key, value, obj)),
-  ])
-}
-
-/**
- * Gets the value at a specified path of an object. If the resolved value is
- * `undefined`, the `defaultValue` is returned in its place. This function
- * supports dot-notation for nested properties and numbers for array indices.
- *
- * This is similar to Lodash's `_.get`.
- *
- * @example
- * const object = { 'a': [{ 'b': { 'c': 3 } }] };
- * get(object, 'a.0.b.c');
- * // => 3
- *
- * get(object, 'a.0.d', 'default');
- * // => 'default'
- *
- * @param {Object} obj - The object to query.
- * @param {string} path - The path of the property to retrieve.
- * @param {*} [defaultValue=undefined] - The value returned for `undefined` resolved values.
- * @returns {*} Returns the resolved value, else the `defaultValue`.
- */
-export function get(obj, path, defaultValue = undefined) {
-  if (!path) return defaultValue
-
-  const keys = path.split(".")
-  let result = obj
-
-  for (const key of keys) {
-    if (result == null || typeof result !== "object") {
-      return defaultValue
-    }
-    result = result[key]
-  }
-
-  return result !== undefined ? result : defaultValue
-}
-
-/**
- * Checks if a value is a plain object.
- *
- * @param {*} value - The value to check.
- * @returns {boolean} True if the value is a plain object, false otherwise.
- */
-export function isObject(value) {
-  return value != null && value.constructor === Object
-}
-
-/**
- * Maps the properties of an object using a callback function.
- *
- * @param {Object} obj - The object to map.
- * @param {Function} callback - A function that transforms each property.
- *                              Receives (key, value, obj) as arguments.
- * @returns {Object} A new object with the mapped properties.
- */
-export function map(obj, callback) {
-  return Object.entries(obj).reduce((acc, [key, value]) => {
-    acc[key] = callback(key, value, obj)
-    return acc
-  }, {})
-}
-
-/**
- * A utility function inspired by Immer's `produce` API. It provides a convenient
- * way to work with immutable data structures by allowing "mutations" on a
- * temporary draft.
- *
- * **Important:** Unlike Immer, which uses structural sharing via proxies for
- * high performance, this implementation performs a full deep clone of the base
- * state on every call using `deserialize(serialize())`. This can be
- * inefficient for large or complex states. It is intended for simple use cases
- * where the convenience of the API outweighs the performance cost.
- *
- * The recipe function receives a draft copy of the state. It can either
- * mutate the draft and return nothing (`undefined`), or it can return a
- * completely new value, which will become the next state.
- *
- * Can be called in two ways:
- * - **Standard:** `produce(baseState, recipe, ...args)`
- * - **Curried:** `produce(recipe)` returns a new function `(baseState, ...args) => newState`
- *
- * @template T
- * @param {T|function(T, ...*): (T|void)} baseState The initial state, or a recipe for currying.
- * @param {function(T, ...*): (T|void)} [recipe] The recipe function.
- * @param {...*} args Additional arguments to pass to the recipe.
- * @returns {T | function(T, ...*): T} A new state, or a producer function if curried.
- */
-export function produce(baseState, recipe, ...args) {
-  if (typeof baseState === "function" && recipe === undefined) {
-    const recipeFn = baseState
-    return (state, ...recipeArgs) => produce(state, recipeFn, ...recipeArgs)
-  }
-
-  const draft = clone(baseState)
-  const result = recipe(draft, ...args)
-  return result === undefined ? draft : result
-}
-
-/**
- * Serializes an object, converting special types like vectors into a plain
- * object representation. This is useful for processes like saving state to a
- * file or sending it over a network.
- *
- * - Recursively serializes nested objects.
- * - Converts objects with a `__isVector__` property into a serializable
- *   format: `{ _type: "vector", coords: [...] }`.
- * - Copies all other property values as-is.
- *
- * @param {Object} obj - The object to serialize.
- * @returns {string} The serialized JSON string.
- */
-export function serialize(obj) {
-  function replacer(key, value) {
-    // Handle top-level vector
-    if (value?.__isVector__) {
-      return {
-        _type: "vector",
-        coords: Array.from(value),
-      }
-    }
-
-    if (isObject(value)) {
-      const serialized = {}
-
-      for (const k in value) {
-        if (Object.prototype.hasOwnProperty.call(value, k)) {
-          serialized[k] = replacer(undefined, value[k])
-        }
-      }
-
-      return serialized
-    }
-
-    return value
-  }
-
-  return JSON.stringify(obj, replacer)
-}
-
-/**
- * Sets the value at a specified path of an object. If a portion of the path
- * doesn't exist, it's created. Arrays are created for missing index properties
- * while objects are created for all other missing properties. This function
- * mutates the object.
- *
- * This is similar to Lodash's `_.set`.
- *
- * @example
- * const object = { 'a': [{ 'b': { 'c': 3 } }] };
- * set(object, 'a.0.b.d', 4);
- * // object is now { 'a': [{ 'b': { 'c': 3, 'd': 4 } }] }
- *
- * set(object, 'x.0.y', 5);
- * // object is now { 'a': [...], 'x': [{ 'y': 5 }] }
- *
- * @param {Object} obj - The object to modify.
- * @param {string} path - The path of the property to set.
- * @param {*} value - The value to set.
- * @returns {Object} Returns the modified object.
- */
-export function set(obj, path, value) {
-  if (!path) return obj
-
-  const keys = path.split(".")
-  let current = obj
-
-  for (let i = 0; i < keys.length - LAST_KEY_OFFSET; i++) {
-    const key = keys[i]
-    const nextKey = keys[i + NEXT_KEY_OFFSET]
-
-    // Create missing intermediate objects
-    if (!(key in current) || typeof current[key] !== "object") {
-      // Create array if next key is a number, object otherwise
-      current[key] = /^\d+$/.test(nextKey) ? [] : {}
-    }
-
-    current = current[key]
-  }
-
-  current[keys[keys.length - LAST_KEY_OFFSET]] = value
-  return obj
-}
-
-/**
- * Converts an object or array to a formatted string representation.
- *
- * @param {*} obj - The object or array to convert.
- * @param {number} [indentationLevel=INITIAL_LEVEL] - The current indentation level (used for nested structures).
- * @returns {string} A string representation of the input object or array.
- */
-export function toString(obj, indentationLevel = INITIAL_LEVEL) {
-  if (Array.isArray(obj)) {
-    return `[
-${obj
-  .map(
-    (item) =>
-      " ".repeat(indentationLevel + NEXT_LEVEL) +
-      toString(item, indentationLevel + NEXT_LEVEL),
-  )
-  .join(",\n")}
-${" ".repeat(indentationLevel)}]`
-  }
-
-  if (typeof obj === "object" && obj != null) {
-    return `{
-${Object.entries(obj)
-  .map(
-    ([key, value]) =>
-      `${" ".repeat(indentationLevel + NEXT_LEVEL)}${key}: ${toString(
-        value,
-        indentationLevel + NEXT_LEVEL,
-      )}`,
-  )
-  .join(",\n")}
-${" ".repeat(indentationLevel)}}`
-  }
-
-  if (typeof obj === "string") {
-    return `"${obj}"`
-  }
-
-  return obj
-}

package/src/functions/function.js

@@ -1,9 +0,0 @@
-/**
- * Checks if a value is a function.
- *
- * @param {*} func - The value to check.
- * @returns {boolean} True if the value is a function, false otherwise.
- */
-export function isFunction(func) {
-  return typeof func === "function"
-}

package/src/math/quaternion.js

@@ -1,22 +0,0 @@
-/**
- * @typedef {import("../../types/math").Vector3} Vector3
- * @typedef {import("../../types/math").Quaternion} Quaternion
- */
-
-import { v } from "../v.js"
-import { cos, sin } from "./trigonometry.js"
-
-const DEFAULT_ANGLE = 0
-const HALF = 2 // Constant representing the divisor for halving an angle.
-// eslint-disable-next-line no-magic-numbers
-const Y_AXIS = v(0, 1, 0) // Default axis of rotation (Y-axis).
-
-/**
- * Computes a quaternion representing a rotation around a given axis.
- * @param {number} [angle=0] - The angle of rotation in radians. Defaults to 0.
- * @param {Vector3} [axis=Y_AXIS] - The axis of rotation as a 3D vector Defaults to the Y-axis.
- * @returns {Quaternion} The quaternion as an array [w, x, y, z].
- */
-export function quaternion(angle = DEFAULT_ANGLE, axis = Y_AXIS) {
-  return v(cos(angle / HALF), ...axis.map((coord) => coord * sin(angle / HALF)))
-}