@buoy-gg/shared-ui 1.7.2

package/lib/commonjs/utils/safeStringify.js

@@ -0,0 +1,229 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.safeStringify = safeStringify;
+/**
+ * Safely stringifies objects with circular references by:
+ * 1. Pre-processing to detect and temporarily replace circular references
+ * 2. Handling special JS types that JSON.stringify can't serialize
+ * 3. Restoring original object structure after stringification
+ * 4. Inspired by fast-safe-stringify with additional type handling
+ */
+
+const CIRCULAR_REPLACE_NODE = "[Circular]";
+const LIMIT_REPLACE_NODE = "[...]";
+
+/**
+ * Safely stringifies objects with circular references and special JavaScript types
+ * 
+ * This function provides comprehensive JSON serialization that handles:
+ * - Circular references (replaced with "[Circular]")
+ * - Special JavaScript types (Date, RegExp, Error, Map, Set, etc.)
+ * - Non-serializable values (undefined, functions, symbols, BigInt)
+ * - Depth and edge limits to prevent infinite recursion
+ * - Restoration of original object structure after processing
+ * 
+ * @param obj - The object/value to stringify
+ * @param space - Number of spaces for pretty-printing (optional)
+ * @param options - Configuration options for limits
+ * @param options.depthLimit - Maximum depth to traverse (default: unlimited)
+ * @param options.edgesLimit - Maximum edges per object (default: unlimited)
+ * 
+ * @returns JSON string representation of the object
+ * 
+ * @example
+ * ```typescript
+ * const obj = { name: "test" };
+ * obj.self = obj; // circular reference
+ * 
+ * const result = safeStringify(obj, 2);
+ * // Returns: '{\n  "name": "test",\n  "self": "[Circular]"\n}'
+ * 
+ * // With limits
+ * const limited = safeStringify(deepObject, 2, { depthLimit: 5 });
+ * ```
+ * 
+ * @performance Uses pre-processing approach to handle circular references efficiently
+ * @performance Includes object restoration to maintain original structure integrity
+ * @performance Optimized for arrays and objects with separate handling paths
+ */
+function safeStringify(obj, space, options = {}) {
+  const {
+    depthLimit = Number.MAX_SAFE_INTEGER,
+    edgesLimit = Number.MAX_SAFE_INTEGER
+  } = options;
+  const arr = []; // Store original values to restore after stringification
+
+  // Pre-process the object to handle circular references and depth limits
+  function decirc(val, k, edgeIndex, stack, parent, depth) {
+    depth += 1;
+    if (typeof val === "object" && val !== null) {
+      // Check for circular references
+      for (let i = 0; i < stack.length; i++) {
+        if (stack[i] === val) {
+          setReplace(CIRCULAR_REPLACE_NODE, val, k, parent);
+          return;
+        }
+      }
+
+      // Check depth limit
+      if (depth > depthLimit) {
+        setReplace(LIMIT_REPLACE_NODE, val, k, parent);
+        return;
+      }
+
+      // Check edges limit
+      if (edgeIndex + 1 > edgesLimit) {
+        setReplace(LIMIT_REPLACE_NODE, val, k, parent);
+        return;
+      }
+      stack.push(val);
+
+      // Optimize for Arrays
+      if (Array.isArray(val)) {
+        const arrayParent = val;
+        for (let i = 0; i < val.length; i++) {
+          decirc(val[i], i, i, stack, arrayParent, depth);
+        }
+      } else if (val instanceof Map || val instanceof Set || val instanceof RegExp || val instanceof Date || val instanceof Error) {
+        // Skip special objects
+        stack.pop();
+        return;
+      } else {
+        const objParent = val;
+        const keys = Object.keys(objParent);
+        for (let i = 0; i < keys.length; i++) {
+          const key = keys[i];
+          decirc(objParent[key], key, i, stack, objParent, depth);
+        }
+      }
+      stack.pop();
+    }
+  }
+  function setReplace(replace, val, k, parent) {
+    if (!parent) return;
+    const propertyDescriptor = Object.getOwnPropertyDescriptor(parent, k);
+    if (propertyDescriptor?.get !== undefined) {
+      if (propertyDescriptor.configurable) {
+        Object.defineProperty(parent, k, {
+          value: replace
+        });
+        arr.push([parent, k, val, propertyDescriptor]);
+      } else {
+        // Handle non-configurable getters - skip for now
+        return;
+      }
+    } else {
+      parent[k] = replace;
+      arr.push([parent, k, val]);
+    }
+  }
+
+  // Custom replacer for special types
+  const replacer = (key, value) => {
+    // Handle primitives that JSON.stringify can't handle
+    if (typeof value === "bigint") return `${value.toString()}n`;
+    if (typeof value === "symbol") return value.toString();
+    if (typeof value === "undefined") return "undefined";
+    if (typeof value === "function") {
+      return `[Function: ${value.name || "anonymous"}]`;
+    }
+
+    // Handle special number values
+    if (typeof value === "number") {
+      if (value === Infinity) return "Infinity";
+      if (value === -Infinity) return "-Infinity";
+      if (Number.isNaN(value)) return "NaN";
+    }
+
+    // Handle special objects
+    if (value instanceof Error) {
+      const errorObj = {
+        name: value.name,
+        message: value.message,
+        stack: value.stack
+      };
+      // Include custom properties
+      Object.getOwnPropertyNames(value).forEach(prop => {
+        if (!["name", "message", "stack"].includes(prop)) {
+          try {
+            const propValue = value[prop];
+            if (propValue !== undefined) {
+              errorObj[prop] = propValue;
+            }
+          } catch {
+            // Skip properties that can't be accessed
+          }
+        }
+      });
+      return errorObj;
+    }
+    if (value instanceof Date) return value.toISOString();
+    if (value instanceof RegExp) return value.toString();
+
+    // Handle Map objects
+    if (value instanceof Map) {
+      try {
+        const entries = Array.from(value.entries()).map(([mapKey, val]) => [String(mapKey), val]);
+        return {
+          __type: "Map",
+          entries: entries
+        };
+      } catch {
+        // Handle cases where Map iteration fails
+        return {
+          __type: "Map",
+          entries: "[Map iteration failed]"
+        };
+      }
+    }
+
+    // Handle Set objects
+    if (value instanceof Set) {
+      try {
+        return {
+          __type: "Set",
+          values: Array.from(value)
+        };
+      } catch {
+        return {
+          __type: "Set",
+          values: "[Set iteration failed]"
+        };
+      }
+    }
+    return value;
+  };
+
+  // Pre-process to handle circular references
+  try {
+    decirc(obj, "", 0, [], null, 0);
+
+    // Stringify with custom replacer
+    const result = JSON.stringify(obj, replacer, space);
+    return result;
+  } catch {
+    // Fallback for complex circular references
+    return JSON.stringify("[unable to serialize, circular reference is too complex to analyze]");
+  } finally {
+    // Restore original object structure
+    while (arr.length !== 0) {
+      const part = arr.pop();
+      if (part && part.length === 4) {
+        // Restore property descriptor
+        const [targetObj, key,, descriptor] = part;
+        if (targetObj && typeof targetObj === "object" && descriptor) {
+          Object.defineProperty(targetObj, key, descriptor);
+        }
+      } else if (part) {
+        // Restore simple property
+        const [targetObj, key, value] = part;
+        if (targetObj && typeof targetObj === "object" && (typeof key === "string" || typeof key === "number")) {
+          targetObj[key] = value;
+        }
+      }
+    }
+  }
+}

package/lib/commonjs/utils/time/formatRelativeTime.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.formatRelativeTime = formatRelativeTime;
+/**
+ * Formats a timestamp as relative time (e.g., "1s ago", "5m ago", "2h ago")
+ * @param timestamp - The timestamp to format (Date object or number in milliseconds)
+ * @param currentTime - Current time in milliseconds (defaults to Date.now())
+ * @returns Formatted relative time string
+ */
+function formatRelativeTime(timestamp, currentTime = Date.now()) {
+  const timestampMs = timestamp instanceof Date ? timestamp.getTime() : timestamp;
+  const seconds = Math.floor((currentTime - timestampMs) / 1000);
+
+  // Handle edge cases
+  if (seconds < 0) {
+    return "just now";
+  }
+  if (seconds < 60) {
+    return seconds === 0 ? "just now" : `${seconds}s ago`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) {
+    return `${minutes}m ago`;
+  }
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) {
+    return `${hours}h ago`;
+  }
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}

package/lib/commonjs/utils/time/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "formatRelativeTime", {
+  enumerable: true,
+  get: function () {
+    return _formatRelativeTime.formatRelativeTime;
+  }
+});
+var _formatRelativeTime = require("./formatRelativeTime.js");

package/lib/commonjs/utils/typeHelpers.js

@@ -0,0 +1,142 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isValidJson = exports.isPrimitive = exports.isPlainObject = exports.isJsonSerializable = exports.isEmpty = exports.getValueType = exports.getValueSize = exports.getConstructorName = void 0;
+/**
+ * Type detection and validation utilities
+ */
+
+/**
+ * Detects the type of a value with more granular type checking
+ * @param value - The value to check
+ * @returns A string representing the specific type
+ */
+const getValueType = value => {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (Array.isArray(value)) return "array";
+  const type = typeof value;
+  if (type === "object") {
+    // Check for specific object types
+    if (value instanceof Date) return "date";
+    if (value instanceof RegExp) return "regexp";
+    if (value instanceof Map) return "map";
+    if (value instanceof Set) return "set";
+    if (value instanceof Error) return "error";
+    return "object";
+  }
+  return type;
+};
+
+/**
+ * Checks if a value is a primitive type
+ * @param value - The value to check
+ * @returns True if the value is primitive
+ */
+exports.getValueType = getValueType;
+const isPrimitive = value => {
+  const type = typeof value;
+  return value === null || value === undefined || type === "string" || type === "number" || type === "boolean" || type === "bigint" || type === "symbol";
+};
+
+/**
+ * Checks if a value is a valid JSON serializable value
+ * @param value - The value to check
+ * @returns True if the value can be JSON serialized
+ */
+exports.isPrimitive = isPrimitive;
+const isJsonSerializable = value => {
+  try {
+    JSON.stringify(value);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Checks if a string represents a valid JSON value
+ * @param str - The string to test
+ * @returns True if the string is valid JSON
+ */
+exports.isJsonSerializable = isJsonSerializable;
+const isValidJson = str => {
+  try {
+    JSON.parse(str);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Safely gets the constructor name of a value
+ * @param value - The value to check
+ * @returns The constructor name or type string
+ */
+exports.isValidJson = isValidJson;
+const getConstructorName = value => {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  try {
+    return value.constructor?.name || typeof value;
+  } catch {
+    return typeof value;
+  }
+};
+
+/**
+ * Checks if a value is an empty object or array
+ * @param value - The value to check
+ * @returns True if the value is empty
+ */
+exports.getConstructorName = getConstructorName;
+const isEmpty = value => {
+  if (value === null || value === undefined) return true;
+  if (typeof value === "string") return value.length === 0;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === "object") return Object.keys(value).length === 0;
+  return false;
+};
+
+/**
+ * Gets a human-readable size description for objects and arrays
+ * @param value - The value to get size for
+ * @returns A human-readable size string
+ */
+exports.isEmpty = isEmpty;
+const getValueSize = value => {
+  if (Array.isArray(value)) {
+    const count = value.length;
+    if (count === 0) return "empty array";
+    if (count === 1) return "1 item";
+    return `${count} items`;
+  }
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value);
+    const count = keys.length;
+    if (count === 0) return "empty object";
+    if (count === 1) return "1 key";
+    return `${count} keys`;
+  }
+  if (typeof value === "string") {
+    const length = value.length;
+    if (length === 0) return "empty string";
+    if (length === 1) return "1 character";
+    return `${length} characters`;
+  }
+  return "";
+};
+
+/**
+ * Type guard to check if a value is an object (not null, not array)
+ * @param value - The value to check
+ * @returns True if value is a plain object
+ */
+exports.getValueSize = getValueSize;
+const isPlainObject = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && value.constructor === Object;
+};
+exports.isPlainObject = isPlainObject;

package/lib/commonjs/utils/valueFormatting.js

@@ -0,0 +1,140 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.truncateText = exports.parseValue = exports.getTypeColor = exports.formatValue = exports.formatPath = exports.flattenObject = void 0;
+var _index = require("../ui/gameUI/index.js");
+/**
+ * Safely parses a value that might be a JSON string
+ * @param value - The value to parse
+ * @returns The parsed value or original value if parsing fails
+ */
+const parseValue = value => {
+  if (value === null || value === undefined) return value;
+  if (typeof value === "string") {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value;
+    }
+  }
+  return value;
+};
+
+/**
+ * Formats a value for display with appropriate type representation
+ * @param value - The value to format
+ * @returns A string representation of the value
+ */
+exports.parseValue = parseValue;
+const formatValue = value => {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (typeof value === "string") return `"${value}"`;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return String(value);
+  if (typeof value === "function") return `[Function: ${value.name || "anonymous"}]`;
+  if (typeof value === "object") {
+    if (Array.isArray(value)) {
+      return `[Array: ${value.length} items]`;
+    }
+    return `{Object: ${Object.keys(value).length} keys}`;
+  }
+  return String(value);
+};
+
+/**
+ * Gets the color for a value based on its type
+ * @param value - The value to get color for
+ * @returns The color string for the value type
+ */
+exports.formatValue = formatValue;
+const getTypeColor = value => {
+  if (value === null) return _index.gameUIColors.dataTypes.null;
+  if (value === undefined) return _index.gameUIColors.dataTypes.undefined;
+  const type = typeof value;
+  switch (type) {
+    case "string":
+      return _index.gameUIColors.dataTypes.string;
+    case "number":
+      return _index.gameUIColors.dataTypes.number;
+    case "boolean":
+      return _index.gameUIColors.dataTypes.boolean;
+    case "function":
+      return _index.gameUIColors.dataTypes.function;
+    case "object":
+      return Array.isArray(value) ? _index.gameUIColors.dataTypes.array : _index.gameUIColors.dataTypes.object;
+    default:
+      return _index.gameUIColors.primary;
+  }
+};
+
+/**
+ * Truncates text to a specified length with ellipsis
+ * @param text - The text to truncate
+ * @param maxLength - Maximum length before truncation
+ * @returns Truncated text with ellipsis if needed
+ */
+exports.getTypeColor = getTypeColor;
+const truncateText = (text, maxLength) => {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength - 3) + "...";
+};
+
+/**
+ * Flattens a nested object into a flat structure with dot notation paths
+ * @param obj - The object to flatten
+ * @param prefix - The prefix for the current level
+ * @returns A flat object with dot notation keys
+ */
+exports.truncateText = truncateText;
+const flattenObject = (obj, prefix = "") => {
+  const flattened = {};
+  if (obj === null || obj === undefined) {
+    return flattened;
+  }
+  if (typeof obj !== "object") {
+    flattened[prefix || "root"] = obj;
+    return flattened;
+  }
+  if (Array.isArray(obj)) {
+    obj.forEach((item, index) => {
+      const path = prefix ? `${prefix}[${index}]` : `[${index}]`;
+      if (typeof item === "object" && item !== null) {
+        Object.assign(flattened, flattenObject(item, path));
+      } else {
+        flattened[path] = item;
+      }
+    });
+  } else {
+    Object.keys(obj).forEach(key => {
+      const path = prefix ? `${prefix}.${key}` : key;
+      const objValue = obj[key];
+      if (typeof objValue === "object" && objValue !== null) {
+        Object.assign(flattened, flattenObject(objValue, path));
+      } else {
+        flattened[path] = objValue;
+      }
+    });
+  }
+  return flattened;
+};
+
+/**
+ * Creates a readable path from an array of segments (for diff viewers)
+ * @param pathSegments - Array of path segments
+ * @returns A readable path string
+ */
+exports.flattenObject = flattenObject;
+const formatPath = pathSegments => {
+  if (pathSegments.length === 0) return "root";
+  return pathSegments.map((segment, index) => {
+    if (typeof segment === "number") {
+      return `[${segment}]`;
+    }
+    // First segment doesn't need a dot
+    return index === 0 ? segment : `.${segment}`;
+  }).join("");
+};
+exports.formatPath = formatPath;