@forklaunch/common 0.2.9 → 0.2.11

package/lib/index.d.mts

@@ -57,6 +57,40 @@ declare function isTrue(value: true): true;
  */
 declare function noop(): void;
 
+/**
+ * Safely stringifies any JavaScript value, handling special cases like:
+ * - Circular references
+ * - Error objects
+ * - BigInt
+ * - Functions
+ * - Symbols
+ * - Special number values (NaN, Infinity)
+ * - Built-in objects (Date, RegExp)
+ * - Collections (Map, Set)
+ * - TypedArrays and ArrayBuffers
+ *
+ * @param arg - The value to stringify
+ * @returns A string representation of the value
+ *
+ * @example
+ * ```typescript
+ * // Handle circular references
+ * const circular = { a: 1 };
+ * circular.self = circular;
+ * safeStringify(circular); // '{"a":1,"self":"[Circular Reference]"}'
+ *
+ * // Handle Error objects
+ * safeStringify(new Error("test")); // '{"name":"Error","message":"test","stack":"..."}'
+ *
+ * // Handle special types
+ * safeStringify(BigInt(123)); // "123n"
+ * safeStringify(Symbol("test")); // "Symbol(test)"
+ * safeStringify(() => {}); // "[Function: anonymous]"
+ * safeStringify(new Map([["key", "value"]])); // '{"__type":"Map","value":[["key","value"]]}'
+ * ```
+ */
+declare function safeStringify(arg: unknown): string;
+
 /**
  * Recursively sorts the keys of an object and its nested objects alphabetically.
  * This is useful for consistent object serialization and comparison.
@@ -204,4 +238,4 @@ type Prettify<T> = {
  */
 type RemoveTrailingSlash<T extends string> = T extends `${infer Route}/` ? Route : T;
 
-export { type Flatten, type FlattenKeys, type FlattenValues, type IdDto, type IdsDto, type InstanceTypeRecord, type MakePropertyOptionalIfChildrenOptional, type Prettify, type RecordTimingDto, type RemoveTrailingSlash, type ReturnTypeRecord, extractArgumentNames, isNever, isRecord, isTrue, noop, sortObjectKeys, stripUndefinedProperties };
+export { type Flatten, type FlattenKeys, type FlattenValues, type IdDto, type IdsDto, type InstanceTypeRecord, type MakePropertyOptionalIfChildrenOptional, type Prettify, type RecordTimingDto, type RemoveTrailingSlash, type ReturnTypeRecord, extractArgumentNames, isNever, isRecord, isTrue, noop, safeStringify, sortObjectKeys, stripUndefinedProperties };

package/lib/index.d.ts

@@ -57,6 +57,40 @@ declare function isTrue(value: true): true;
  */
 declare function noop(): void;
 
+/**
+ * Safely stringifies any JavaScript value, handling special cases like:
+ * - Circular references
+ * - Error objects
+ * - BigInt
+ * - Functions
+ * - Symbols
+ * - Special number values (NaN, Infinity)
+ * - Built-in objects (Date, RegExp)
+ * - Collections (Map, Set)
+ * - TypedArrays and ArrayBuffers
+ *
+ * @param arg - The value to stringify
+ * @returns A string representation of the value
+ *
+ * @example
+ * ```typescript
+ * // Handle circular references
+ * const circular = { a: 1 };
+ * circular.self = circular;
+ * safeStringify(circular); // '{"a":1,"self":"[Circular Reference]"}'
+ *
+ * // Handle Error objects
+ * safeStringify(new Error("test")); // '{"name":"Error","message":"test","stack":"..."}'
+ *
+ * // Handle special types
+ * safeStringify(BigInt(123)); // "123n"
+ * safeStringify(Symbol("test")); // "Symbol(test)"
+ * safeStringify(() => {}); // "[Function: anonymous]"
+ * safeStringify(new Map([["key", "value"]])); // '{"__type":"Map","value":[["key","value"]]}'
+ * ```
+ */
+declare function safeStringify(arg: unknown): string;
+
 /**
  * Recursively sorts the keys of an object and its nested objects alphabetically.
  * This is useful for consistent object serialization and comparison.
@@ -204,4 +238,4 @@ type Prettify<T> = {
  */
 type RemoveTrailingSlash<T extends string> = T extends `${infer Route}/` ? Route : T;
 
-export { type Flatten, type FlattenKeys, type FlattenValues, type IdDto, type IdsDto, type InstanceTypeRecord, type MakePropertyOptionalIfChildrenOptional, type Prettify, type RecordTimingDto, type RemoveTrailingSlash, type ReturnTypeRecord, extractArgumentNames, isNever, isRecord, isTrue, noop, sortObjectKeys, stripUndefinedProperties };
+export { type Flatten, type FlattenKeys, type FlattenValues, type IdDto, type IdsDto, type InstanceTypeRecord, type MakePropertyOptionalIfChildrenOptional, type Prettify, type RecordTimingDto, type RemoveTrailingSlash, type ReturnTypeRecord, extractArgumentNames, isNever, isRecord, isTrue, noop, safeStringify, sortObjectKeys, stripUndefinedProperties };

package/lib/index.js

@@ -25,6 +25,7 @@ __export(index_exports, {
   isRecord: () => isRecord,
   isTrue: () => isTrue,
   noop: () => noop,
+  safeStringify: () => safeStringify,
   sortObjectKeys: () => sortObjectKeys,
   stripUndefinedProperties: () => stripUndefinedProperties
 });
@@ -77,6 +78,86 @@ function isTrue(value) {
 function noop() {
 }
 
+// src/safeStringify.ts
+function safeStringify(arg) {
+  if (typeof arg === "string") {
+    return arg;
+  }
+  if (arg == null) {
+    return String(arg);
+  }
+  const seen = /* @__PURE__ */ new WeakSet();
+  const replacer = (key, value) => {
+    if (value && typeof value === "object") {
+      if (seen.has(value)) {
+        return "[Circular Reference]";
+      }
+      seen.add(value);
+    }
+    if (value instanceof Error) {
+      return {
+        name: value.name,
+        message: value.message,
+        stack: value.stack,
+        cause: value.cause
+      };
+    }
+    if (typeof value === "bigint") {
+      return value.toString() + "n";
+    }
+    if (typeof value === "function") {
+      return `[Function: ${value.name || "anonymous"}]`;
+    }
+    if (typeof value === "symbol") {
+      return value.toString();
+    }
+    if (typeof value === "number") {
+      if (Number.isNaN(value)) return "NaN";
+      if (value === Infinity) return "Infinity";
+      if (value === -Infinity) return "-Infinity";
+    }
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    if (value instanceof RegExp) {
+      return value.toString();
+    }
+    if (value instanceof Map) {
+      return {
+        __type: "Map",
+        value: Array.from(value.entries())
+      };
+    }
+    if (value instanceof Set) {
+      return {
+        __type: "Set",
+        value: Array.from(value.values())
+      };
+    }
+    if (ArrayBuffer.isView(value)) {
+      return {
+        __type: value.constructor.name,
+        value: Array.from(value)
+      };
+    }
+    if (value instanceof ArrayBuffer) {
+      return {
+        __type: "ArrayBuffer",
+        value: Array.from(new Uint8Array(value))
+      };
+    }
+    return value;
+  };
+  try {
+    return JSON.stringify(arg, replacer);
+  } catch (error) {
+    if (error instanceof Error) {
+      return `[Unserializable: ${error.message}]`;
+    }
+    return "[Unserializable: Unknown error]";
+  }
+}
+
 // src/sortObjectKeys.ts
 function sortObjectKeys(obj) {
   if (typeof obj !== "object" || obj === null) {
@@ -105,6 +186,7 @@ function stripUndefinedProperties(obj) {
   isRecord,
   isTrue,
   noop,
+  safeStringify,
   sortObjectKeys,
   stripUndefinedProperties
 });

package/lib/index.mjs

@@ -45,6 +45,86 @@ function isTrue(value) {
 function noop() {
 }
 
+// src/safeStringify.ts
+function safeStringify(arg) {
+  if (typeof arg === "string") {
+    return arg;
+  }
+  if (arg == null) {
+    return String(arg);
+  }
+  const seen = /* @__PURE__ */ new WeakSet();
+  const replacer = (key, value) => {
+    if (value && typeof value === "object") {
+      if (seen.has(value)) {
+        return "[Circular Reference]";
+      }
+      seen.add(value);
+    }
+    if (value instanceof Error) {
+      return {
+        name: value.name,
+        message: value.message,
+        stack: value.stack,
+        cause: value.cause
+      };
+    }
+    if (typeof value === "bigint") {
+      return value.toString() + "n";
+    }
+    if (typeof value === "function") {
+      return `[Function: ${value.name || "anonymous"}]`;
+    }
+    if (typeof value === "symbol") {
+      return value.toString();
+    }
+    if (typeof value === "number") {
+      if (Number.isNaN(value)) return "NaN";
+      if (value === Infinity) return "Infinity";
+      if (value === -Infinity) return "-Infinity";
+    }
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    if (value instanceof RegExp) {
+      return value.toString();
+    }
+    if (value instanceof Map) {
+      return {
+        __type: "Map",
+        value: Array.from(value.entries())
+      };
+    }
+    if (value instanceof Set) {
+      return {
+        __type: "Set",
+        value: Array.from(value.values())
+      };
+    }
+    if (ArrayBuffer.isView(value)) {
+      return {
+        __type: value.constructor.name,
+        value: Array.from(value)
+      };
+    }
+    if (value instanceof ArrayBuffer) {
+      return {
+        __type: "ArrayBuffer",
+        value: Array.from(new Uint8Array(value))
+      };
+    }
+    return value;
+  };
+  try {
+    return JSON.stringify(arg, replacer);
+  } catch (error) {
+    if (error instanceof Error) {
+      return `[Unserializable: ${error.message}]`;
+    }
+    return "[Unserializable: Unknown error]";
+  }
+}
+
 // src/sortObjectKeys.ts
 function sortObjectKeys(obj) {
   if (typeof obj !== "object" || obj === null) {
@@ -72,6 +152,7 @@ export {
   isRecord,
   isTrue,
   noop,
+  safeStringify,
   sortObjectKeys,
   stripUndefinedProperties
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forklaunch/common",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "Common package for base types, interfaces, implementations.",
   "homepage": "https://github.com/forklaunch/forklaunch-js#readme",
   "bugs": {
@@ -28,12 +28,12 @@
     "lib/**"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.24.0",
+    "@eslint/js": "^9.25.0",
     "depcheck": "^1.4.7",
-    "eslint": "^9.24.0",
+    "eslint": "^9.25.0",
     "globals": "^16.0.0",
     "tsup": "^8.4.0",
-    "typedoc": "^0.28.2",
+    "typedoc": "^0.28.3",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.30.1",
     "vitest": "^3.1.1"