@dxos/util 0.8.4-main.406dc2a → 0.8.4-main.548089c

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/util",
-  "version": "0.8.4-main.406dc2a",
+  "version": "0.8.4-main.548089c",
   "description": "Temporary bucket for misc functions, which should graduate into separate packages.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -29,15 +29,15 @@
   "dependencies": {
     "lodash.get": "^4.4.2",
     "lodash.set": "^4.3.2",
-    "@dxos/debug": "0.8.4-main.406dc2a",
-    "@dxos/invariant": "0.8.4-main.406dc2a",
-    "@dxos/keys": "0.8.4-main.406dc2a",
-    "@dxos/node-std": "0.8.4-main.406dc2a"
+    "@dxos/debug": "0.8.4-main.548089c",
+    "@dxos/invariant": "0.8.4-main.548089c",
+    "@dxos/keys": "0.8.4-main.548089c",
+    "@dxos/node-std": "0.8.4-main.548089c"
   },
   "devDependencies": {
     "@types/lodash.get": "^4.4.9",
     "@types/lodash.set": "^4.3.9",
-    "@dxos/crypto": "0.8.4-main.406dc2a"
+    "@dxos/crypto": "0.8.4-main.548089c"
   },
   "publishConfig": {
     "access": "public"

package/src/binder.ts

@@ -2,7 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-import util from 'node:util';
+import { promisify } from 'node:util';
 
 /**
  * Function binder replaces pify.
@@ -10,5 +10,5 @@ import util from 'node:util';
 // TODO(burdon): Replace pify everywhere.
 export const createBinder = (obj: any) => ({
   fn: (fn: Function) => fn.bind(obj),
-  async: (fn: Function) => util.promisify(fn.bind(obj)),
+  async: (fn: Function) => promisify(fn.bind(obj)),
 });

package/src/index.ts

@@ -40,6 +40,7 @@ export * from './remove-undefined-keys';
 export * from './safe-await';
 export * from './safe-instanceof';
 export * from './safe-parse';
+export * from './safe-stringify';
 export * from './sliding-window-summary';
 export * from './sort';
 export * from './string';

package/src/safe-stringify.ts

@@ -0,0 +1,104 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export const SKIP = Object.freeze({});
+
+export type StringifyReplacer = (key: string, value: any) => typeof SKIP | any;
+
+export function safeStringify(obj: any, filter: StringifyReplacer = defaultFilter, indent = 2) {
+  const seen = new WeakSet();
+
+  function replacer(key: string, value: any) {
+    if (typeof value === 'object' && value !== null) {
+      if (seen.has(value)) {
+        return '[Circular]';
+      }
+
+      seen.add(value);
+    }
+
+    if (filter) {
+      const v2 = filter?.(key, value);
+      if (v2 !== undefined) {
+        return v2 === SKIP ? undefined : v2;
+      }
+    }
+
+    return value;
+  }
+
+  let result = '';
+  try {
+    result = JSON.stringify(obj, replacer, indent);
+  } catch (error: any) {
+    result = `Error: ${error.message}`;
+  }
+
+  return result;
+}
+
+export type CreateReplacerProps = {
+  omit?: string[];
+  parse?: string[];
+  maxDepth?: number;
+  maxArrayLen?: number;
+  maxStringLen?: number;
+};
+
+export const createReplacer = ({
+  omit,
+  parse,
+  maxDepth,
+  maxArrayLen,
+  maxStringLen,
+}: CreateReplacerProps = {}): StringifyReplacer => {
+  let currentDepth = 0;
+  const depthMap = new WeakMap<object, number>();
+
+  return function (this: any, key: string, value: any) {
+    // Track depth.
+    if (key === '') {
+      currentDepth = 0;
+    } else if (this && typeof this === 'object') {
+      const parentDepth = depthMap.get(this) ?? 0;
+      currentDepth = parentDepth + 1;
+    }
+
+    if (typeof value === 'function') {
+      return undefined;
+    }
+
+    // Store depth for this object.
+    if (value && typeof value === 'object') {
+      depthMap.set(value, currentDepth);
+
+      // Check max depth.
+      if (maxDepth != null && currentDepth >= maxDepth) {
+        return Array.isArray(value) ? `[{ length: ${value.length} }]` : `{ keys: ${Object.keys(value).length} }`;
+      }
+    }
+
+    // Apply other filters.
+    if (omit?.includes(key)) {
+      return undefined;
+    }
+    if (parse?.includes(key) && typeof value === 'string') {
+      try {
+        return JSON.parse(value);
+      } catch {
+        return value;
+      }
+    }
+    if (maxArrayLen != null && Array.isArray(value) && value.length > maxArrayLen) {
+      return `[length: ${value.length}]`;
+    }
+    if (maxStringLen != null && typeof value === 'string' && value.length > maxStringLen) {
+      return value.slice(0, maxStringLen) + '...';
+    }
+
+    return value;
+  };
+};
+
+export const defaultFilter: StringifyReplacer = createReplacer();

package/src/types.ts

@@ -48,7 +48,6 @@ export type Falsy = false | 0 | '' | null | undefined;
  * NOTE: To filter by type:
  * items.filter((item: any): item is RangeSet<Decoration> => item instanceof RangeSet)
  */
-// TODO(burdon): Replace with Predicate.isTruthy?
 export const isTruthy = <T>(value: T): value is Exclude<T, Falsy> => !!value;
 export const isNonNullable = <T>(value: T | null | undefined): value is T => value != null;
 

package/src/unit.test.ts

@@ -19,7 +19,7 @@ describe('url', () => {
     ];
 
     tests.forEach(([input, output]) => {
-      expect(Unit.Duration(input)).toBe(output);
+      expect(Unit.Duration(input).toString(), input.toString()).toBe(output);
     });
   });
 });

package/src/unit.ts

@@ -2,51 +2,81 @@
 // Copyright 2025 DXOS.org
 //
 
-type Unit = {
+export type Unit = {
   symbol: string;
   quotient: number;
+  precision?: number;
 };
 
-type Format = (n: number, precision?: number) => string;
+export type UnitValue<T> = {
+  unit: Unit;
+  value: number;
+  formattedValue: T;
+  toString: () => string;
+};
+
+export type UnitFormat<T = any> = (n: number, precision?: number) => UnitValue<T>;
 
-const Formatter = (unit: Unit): Format => {
-  return (n: number, precision = 2) => {
+const createFormat = (unit: Unit): UnitFormat<string> => {
+  return (n: number, precision = unit.precision ?? 0) => {
     const value = n / unit.quotient;
-    return `${value.toFixed(precision)}${unit.symbol}`;
+    return {
+      unit,
+      value,
+      formattedValue: value.toFixed(precision),
+      toString: () => `${value.toFixed(precision)}${unit.symbol}`,
+    };
   };
 };
 
-export const Unit = {
-  // ms.
-  Hour: Formatter({ symbol: 'h', quotient: 60 * 60 * 1_000 }),
-  Minute: Formatter({ symbol: 'm', quotient: 60 * 1_000 }),
-  Second: Formatter({ symbol: 's', quotient: 1_000 }),
-  Millisecond: Formatter({ symbol: 'ms', quotient: 1 }),
+const MS_SECONDS = 1_000;
+const MS_MINUTES = 60 * MS_SECONDS;
+const MS_HOURS = 60 * MS_MINUTES;
+
+export const Unit: Record<string, UnitFormat> = {
+  // General.
+  Percent: createFormat({ symbol: '%', quotient: 1 / 100, precision: 2 }),
+  Thousand: createFormat({ symbol: 'k', quotient: 1_000, precision: 2 }),
+
+  // Bytes (note KB vs KiB).
+  Gigabyte: createFormat({ symbol: 'GB', quotient: 1_000 * 1_000 * 1_000, precision: 2 }),
+  Megabyte: createFormat({ symbol: 'MB', quotient: 1_000 * 1_000, precision: 2 }),
+  Kilobyte: createFormat({ symbol: 'KB', quotient: 1_000, precision: 2 }),
+
+  // Time.
+  Hour: createFormat({ symbol: 'h', quotient: MS_HOURS }),
+  Minute: createFormat({ symbol: 'm', quotient: MS_MINUTES }),
+  Second: createFormat({ symbol: 's', quotient: MS_SECONDS, precision: 1 }),
+  Millisecond: createFormat({ symbol: 'ms', quotient: 1 }),
   Duration: (n: number) => {
-    const hours = Math.floor(n / (60 * 60 * 1_000));
-    const minutes = Math.floor((n % (60 * 60 * 1_000)) / (60 * 1_000));
+    const hours = Math.floor(n / MS_HOURS);
+    const minutes = Math.floor((n % MS_HOURS) / MS_MINUTES);
     if (hours) {
-      return minutes ? `${hours}h ${minutes}m` : `${hours}h`;
+      const formattedValue = minutes ? `${hours}h ${minutes}m` : `${hours}h`;
+      return {
+        unit: { symbol: 'h', quotient: MS_HOURS },
+        value: hours,
+        formattedValue,
+        toString: () => formattedValue,
+      };
     }
 
-    const seconds = Math.floor((n % (60 * 1_000)) / 1_000);
     if (minutes) {
-      return seconds ? `${minutes}m ${seconds}s` : `${minutes}m`;
+      const seconds = (n - MS_MINUTES * minutes) / MS_SECONDS;
+      const formattedValue = seconds ? `${minutes}m ${seconds}s` : `${minutes}m`;
+      return {
+        unit: { symbol: 'm', quotient: MS_MINUTES },
+        value: minutes,
+        formattedValue,
+        toString: () => formattedValue,
+      };
     }
 
+    const seconds = n >= MS_SECONDS;
     if (seconds) {
-      return `${(n / 1_000).toFixed(1)}s`;
+      return Unit.Second(n);
     }
 
-    return `${n}ms`;
+    return Unit.Millisecond(n);
   },
-
-  // bytes (note KB via KiB).
-  Gigabyte: Formatter({ symbol: 'GB', quotient: 1_000 * 1_000 * 1_000 }),
-  Megabyte: Formatter({ symbol: 'MB', quotient: 1_000 * 1_000 }),
-  Kilobyte: Formatter({ symbol: 'KB', quotient: 1_000 }),
-
-  // general.
-  Thousand: Formatter({ symbol: 'k', quotient: 1_000 }),
-  Percent: Formatter({ symbol: '%', quotient: 1 / 100 }),
-};
+} as const;