@fluixi/utils 1.0.0-alpha.100

package/dist/lib/object/utils.cjs

@@ -0,0 +1,326 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/object/utils.ts
+var utils_exports = {};
+__export(utils_exports, {
+  isClass: () => isClass,
+  isEmptyObject: () => isEmptyObject,
+  isObject: () => isObject,
+  isPlainObject: () => isPlainObject,
+  toJSONString: () => toJSONString,
+  traverseStructure: () => traverseStructure
+});
+module.exports = __toCommonJS(utils_exports);
+var isObject = (value) => {
+  if (value == null) return false;
+  if (Array.isArray(value)) return false;
+  if (typeof value === "function") return false;
+  if (value instanceof Date) return false;
+  if (value instanceof RegExp) return false;
+  if (value instanceof Map) return false;
+  if (value instanceof Set) return false;
+  if (value instanceof Error) return false;
+  return typeof value === "object";
+};
+function isPlainObject(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+function isClass(obj) {
+  return typeof obj === "function" && /^class\s/.test(Function.prototype.toString.call(obj));
+}
+var isEmptyObject = (value) => {
+  if (!isObject(value)) return false;
+  return Object.keys(value).length === 0;
+};
+var traverseStructure = (current, segments, depth, maxDepth) => {
+  if (depth > maxDepth) return void 0;
+  if (segments.length === 0) return current;
+  const segment = segments[0];
+  const remaining = segments.slice(1);
+  if (segment.type === "descendant") {
+    const result = traverseStructure(current, remaining, depth + 1, maxDepth);
+    if (result !== void 0) {
+      return result;
+    }
+    if (current && typeof current === "object") {
+      if (Array.isArray(current)) {
+        const arrResult = [];
+        for (let i = 0; i < current.length; i++) {
+          const itemResult = traverseStructure(
+            current[i],
+            segments,
+            depth + 1,
+            maxDepth
+          );
+          if (itemResult !== void 0) {
+            arrResult[i] = itemResult;
+          }
+        }
+        return arrResult.length > 0 ? arrResult : void 0;
+      } else {
+        const objResult = {};
+        for (const key in current) {
+          if (current.hasOwnProperty(key)) {
+            const itemResult = traverseStructure(
+              current[key],
+              segments,
+              depth + 1,
+              maxDepth
+            );
+            if (itemResult !== void 0) {
+              objResult[key] = itemResult;
+            }
+          }
+        }
+        return Object.keys(objResult).length > 0 ? objResult : void 0;
+      }
+    }
+    return void 0;
+  }
+  switch (segment.type) {
+    case "property":
+      if (isObject(current) && segment.value && String(segment.value) in current) {
+        const next = current[String(segment.value)];
+        const result = traverseStructure(next, remaining, depth + 1, maxDepth);
+        if (result !== void 0) {
+          return { [String(segment.value)]: result };
+        }
+      }
+      break;
+    case "index":
+      if (Array.isArray(current)) {
+        const index = segment.value;
+        if (index >= 0 && index < current.length) {
+          const result = traverseStructure(
+            current[index],
+            remaining,
+            depth + 1,
+            maxDepth
+          );
+          if (result !== void 0) {
+            const arr = new Array(current.length).filter(
+              (a) => a !== void 0
+            );
+            arr[index] = result;
+            return arr;
+          }
+        }
+      } else if (current && typeof current === "object") {
+        const key = String(segment.value);
+        if (key in current) {
+          const result = traverseStructure(
+            current[key],
+            remaining,
+            depth + 1,
+            maxDepth
+          );
+          if (result !== void 0) {
+            return { [key]: result };
+          }
+        }
+      }
+      break;
+    case "wildcard":
+      if (current && typeof current === "object") {
+        if (Array.isArray(current)) {
+          const arrResult = [];
+          let hasResults = false;
+          for (let i = 0; i < current.length; i++) {
+            const result = traverseStructure(
+              current[i],
+              remaining,
+              depth + 1,
+              maxDepth
+            );
+            if (result !== void 0) {
+              arrResult[i] = result;
+              hasResults = true;
+            }
+          }
+          return hasResults ? arrResult : void 0;
+        } else {
+          const objResult = {};
+          let hasResults = false;
+          for (const key in current) {
+            if (current.hasOwnProperty(key)) {
+              const result = traverseStructure(
+                current[key],
+                remaining,
+                depth + 1,
+                maxDepth
+              );
+              if (result !== void 0) {
+                objResult[key] = result;
+                hasResults = true;
+              }
+            }
+          }
+          return hasResults ? objResult : void 0;
+        }
+      }
+      break;
+    case "slice":
+      if (Array.isArray(current)) {
+        const [start, end] = segment.value;
+        const actualStart = Math.max(0, start);
+        const actualEnd = Math.min(
+          current.length,
+          end === Infinity ? current.length : end
+        );
+        const arrResult = [];
+        let hasResults = false;
+        for (let i = actualStart; i < actualEnd; i++) {
+          const result = traverseStructure(
+            current[i],
+            remaining,
+            depth + 1,
+            maxDepth
+          );
+          if (result !== void 0) {
+            arrResult[i] = result;
+            hasResults = true;
+          }
+        }
+        return hasResults ? arrResult : void 0;
+      }
+      break;
+    case "union":
+      if (Array.isArray(current)) {
+        const indices = segment.value;
+        const arrResult = [];
+        let hasResults = false;
+        for (const index of indices) {
+          if (index >= 0 && index < current.length) {
+            const result = traverseStructure(
+              current[index],
+              remaining,
+              depth + 1,
+              maxDepth
+            );
+            if (result !== void 0) {
+              arrResult[index] = result;
+              hasResults = true;
+            }
+          }
+        }
+        return hasResults ? arrResult : void 0;
+      }
+      break;
+    case "filter":
+      if (Array.isArray(current)) {
+        const filterFn = segment.value;
+        const arrResult = [];
+        let hasResults = false;
+        for (let i = 0; i < current.length; i++) {
+          if (filterFn(current[i])) {
+            const result = traverseStructure(
+              current[i],
+              remaining,
+              depth + 1,
+              maxDepth
+            );
+            if (result !== void 0) {
+              arrResult[i] = result;
+              hasResults = true;
+            }
+          }
+        }
+        return hasResults ? arrResult : void 0;
+      }
+      break;
+  }
+  return void 0;
+};
+function toJSONString(value, space = 0) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  const gap = (n) => space ? " ".repeat(n) : "";
+  const nl = (n) => space ? `
+${" ".repeat(n)}` : "";
+  const esc = (s) => s.replace(/[\u0000-\u001F"\\]/g, (c) => {
+    switch (c) {
+      case '"':
+        return '\\"';
+      case "\\":
+        return "\\\\";
+      case "\b":
+        return "\\b";
+      case "\f":
+        return "\\f";
+      case "\n":
+        return "\\n";
+      case "\r":
+        return "\\r";
+      case "	":
+        return "\\t";
+      default:
+        const code = c.charCodeAt(0).toString(16).padStart(4, "0");
+        return `\\u${code}`;
+    }
+  });
+  const ser = (v, indent) => {
+    if (v === null) return "null";
+    const t = typeof v;
+    if (t === "number") return Number.isFinite(v) ? String(v) : "null";
+    if (t === "boolean") return v ? "true" : "false";
+    if (t === "string") {
+    }
+    if (t === "bigint") return `"${String(v)}"`;
+    if (t === "function" || t === "undefined" || t === "symbol")
+      return void 0;
+    if (Array.isArray(v)) {
+      if (seen.has(v))
+        throw new TypeError("Converting circular structure to JSON");
+      seen.add(v);
+      const next = indent + space;
+      const parts = v.map((x) => {
+        const s = ser(x, next);
+        return s === void 0 ? "null" : s;
+      });
+      seen.delete(v);
+      if (!space) return `[${parts.join(",")}]`;
+      return `[${nl(next)}${parts.join(`,${nl(next)}`)}${nl(indent)}]`;
+    }
+    if (t === "object") {
+      if (seen.has(v))
+        throw new TypeError("Converting circular structure to JSON");
+      seen.add(v);
+      const keys = Object.keys(v);
+      const next = indent + space;
+      const parts = [];
+      for (const k of keys) {
+        const s = ser(v[k], next);
+        if (s !== void 0) {
+          if (!space) parts.push(`"${esc(k)}":${s}`);
+          else parts.push(`${gap(next)}"${esc(k)}": ${s}`);
+        }
+      }
+      seen.delete(v);
+      if (!space) return `{${parts.join(",")}}`;
+      return `{
+${parts.join(",\n")}
+${gap(indent)}}`;
+    }
+    return void 0;
+  };
+  const out = ser(value, 0);
+  return out === void 0 ? void 0 : out;
+}

package/dist/lib/object/utils.d.ts

@@ -0,0 +1,165 @@
+import { ClassType } from '@fluixi/utils/primitive';
+import { RecordObject, SelectorSegment } from './types.js';
+/**
+ * Checks if a value is an object (not array, function, date, etc.)
+ *
+ * This function determines if a value is a plain JavaScript object by excluding
+ * arrays, functions, and built-in object types like Date, RegExp, Map, etc.
+ *
+ * @param value - The value to check
+ * @returns `true` if value is a plain object; `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isObject({});              // true
+ * isObject({ key: 'value' }); // true
+ *
+ * isObject([]);              // false
+ * isObject(null);            // false
+ * isObject(undefined);       // false
+ * isObject(new Date());      // false
+ * isObject(() => {});        // false
+ * isObject(new Map());       // false
+ * ```
+ *
+ * @category Type Checking
+ * @see isPlainObject - For stricter object type checking
+ */
+export declare const isObject: (value: unknown) => value is RecordObject;
+/**
+ * Checks if a value is a plain object (only Object.prototype or null in prototype chain)
+ *
+ * Unlike {@link isObject}, this function performs a stricter check to ensure the value
+ * is a "plain" object - created via object literal `{}` or `Object.create(null)`.
+ * This excludes objects created with custom constructors.
+ *
+ * @template T - The expected object type
+ * @param v - The value to check
+ * @returns `true` if value is a plain object; `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isPlainObject({});                   // true
+ * isPlainObject(Object.create(null));  // true
+ *
+ * class Custom {}
+ * isPlainObject(new Custom());         // false
+ * isPlainObject([]);                   // false
+ * isPlainObject(null);                 // false
+ * ```
+ *
+ * @category Type Checking
+ */
+export declare function isPlainObject<T extends Record<string, any> = Record<string, any>>(v: unknown): v is T;
+/**
+ * Checks if a value is a class constructor
+ *
+ * This function determines if a value is a class constructor by checking
+ * if it's a function and if its string representation starts with the "class" keyword.
+ *
+ * @param obj - The value to check
+ * @returns `true` if value is a class constructor; `false` otherwise
+ *
+ * @example
+ * ```ts
+ * class Example {}
+ * isClass(Example);           // true
+ *
+ * function regularFn() {}
+ * isClass(regularFn);         // false
+ *
+ * const arrowFn = () => {};
+ * isClass(arrowFn);           // false
+ * ```
+ *
+ * @category Type Checking
+ */
+export declare function isClass(obj: unknown): obj is ClassType;
+/**
+ * Checks if a value is an empty object
+ *
+ * This function determines if a value is an object with no enumerable properties.
+ * It first checks if the value is an object using {@link isObject} and then
+ * checks if it has any enumerable properties.
+ *
+ * @param value - The value to check
+ * @returns `true` if value is an object with no properties; `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isEmptyObject({});               // true
+ * isEmptyObject(Object.create(null)); // true
+ *
+ * isEmptyObject({a: 1});           // false
+ * isEmptyObject(null);             // false
+ * isEmptyObject([]);               // false (arrays are not objects in this context)
+ * ```
+ *
+ * @category Type Checking
+ * @see isObject - Used internally for type checking
+ */
+export declare const isEmptyObject: (value: unknown) => boolean;
+/**
+ * Traverses an object structure based on selector segments
+ *
+ * This advanced utility function traverses a data structure (object or array) based on
+ * a series of selector segments. It preserves the structure of the original data while
+ * navigating through it. The function supports various selector types including property access,
+ * array indexing, wildcards, slices, unions, filters, and recursive descent.
+ *
+ * @param current - The current object/array being traversed
+ * @param segments - An array of selector segments that define the traversal path
+ * @param depth - The current traversal depth (for recursion limits)
+ * @param maxDepth - The maximum depth to traverse (prevents infinite recursion)
+ * @returns The traversed structure or undefined if no match found
+ *
+ * @example
+ * ```ts
+ * // Access nested property with a simple path
+ * const data = { users: [{ name: 'Alice', age: 30 }] };
+ * const segments = [
+ *   { type: 'property', value: 'users' },
+ *   { type: 'index', value: 0 },
+ *   { type: 'property', value: 'name' }
+ * ];
+ * traverseStructure(data, segments, 0, 10); // { users: [{ name: 'Alice' }] }
+ * ```
+ *
+ * @internal
+ * @category Object Traversal
+ */
+export declare const traverseStructure: (current: any, segments: SelectorSegment[], depth: number, maxDepth: number) => any;
+/**
+ * Converts a value to a JSON string with improved handling of special cases
+ *
+ * This function converts a JavaScript value to a JSON string, similar to `JSON.stringify`,
+ * but with improved handling of circular references and special character escaping.
+ *
+ * @param value - The value to convert to a JSON string
+ * @param space - The number of spaces to use for indentation (0 for no formatting)
+ * @returns The JSON string representation of the value or undefined for unsupported types
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * toJSONString({ name: 'Alice', age: 30 });
+ * // '{"name":"Alice","age":30}'
+ *
+ * // With formatting
+ * toJSONString({ name: 'Alice', age: 30 }, 2);
+ * // '{
+ * //   "name": "Alice",
+ * //   "age": 30
+ * // }'
+ *
+ * // Handles circular references safely
+ * const circular = { self: null };
+ * circular.self = circular;
+ * toJSONString(circular); // throws TypeError (circular structure)
+ * ```
+ *
+ * @throws {TypeError} When encountering circular references
+ * @category Serialization
+ */
+export declare function toJSONString(value: any, space?: number): string | undefined;
+//# sourceMappingURL=utils.d.ts.map

package/dist/lib/object/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/lib/object/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAa,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,YAUlD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACnD,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,CAAC,CAIpB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,SAAS,CAKtD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,OAG9C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,iBAAiB,GAC5B,SAAS,GAAG,EACZ,UAAU,eAAe,EAAE,EAC3B,OAAO,MAAM,EACb,UAAU,MAAM,KACf,GA+NF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,SAAI,sBAuFjD"}