ts-data-forge 1.0.0 → 1.0.2

package/dist/others/unknown-to-string.d.mts

@@ -0,0 +1,180 @@
+import { Result } from '../functional/index.mjs';
+/**
+ * Converts an unknown value to its string representation in a type-safe manner.
+ *
+ * This function handles all JavaScript types and provides consistent string conversion
+ * with proper error handling for edge cases like circular references. Unlike naive
+ * toString() calls, this function never throws and handles all value types gracefully.
+ *
+ * **Type conversion rules:**
+ * - Strings: returned as-is
+ * - Numbers, booleans, bigints: converted via toString()
+ * - Symbols: converted to their description string
+ * - Functions: converted to their string representation
+ * - null: returns "null" (not "null" from JSON)
+ * - undefined: returns "undefined"
+ * - Objects: JSON stringified (with optional pretty printing)
+ *
+ * @param value - The unknown value to convert to string
+ * @param options - Optional configuration for the conversion
+ * @param options.prettyPrintObject - If true, objects are formatted with 2-space indentation
+ * @returns A Result containing either the string representation or an Error for failures
+ *
+ * @example Basic type conversions
+ * ```typescript
+ * // Primitive types
+ * unknownToString('hello');        // Ok('hello')
+ * unknownToString(123);            // Ok('123')
+ * unknownToString(true);           // Ok('true')
+ * unknownToString(null);           // Ok('null')
+ * unknownToString(undefined);      // Ok('undefined')
+ * unknownToString(Symbol('test')); // Ok('Symbol(test)')
+ * unknownToString(123n);           // Ok('123')
+ *
+ * // Function conversion
+ * const fn = () => 'test';
+ * unknownToString(fn); // Ok('() => 'test'')
+ * ```
+ *
+ * @example Object stringification
+ * ```typescript
+ * // Simple object
+ * const obj = { a: 1, b: 'hello', c: [1, 2, 3] };
+ * const result = unknownToString(obj);
+ * if (Result.isOk(result)) {
+ *   console.log(result.value); // '{"a":1,"b":"hello","c":[1,2,3]}'
+ * }
+ *
+ * // Pretty printing
+ * const prettyResult = unknownToString(obj, { prettyPrintObject: true });
+ * if (Result.isOk(prettyResult)) {
+ *   console.log(prettyResult.value);
+ *   // {
+ *   //   "a": 1,
+ *   //   "b": "hello",
+ *   //   "c": [
+ *   //     1,
+ *   //     2,
+ *   //     3
+ *   //   ]
+ *   // }
+ * }
+ * ```
+ *
+ * @example Error handling for circular references
+ * ```typescript
+ * // Circular reference
+ * const circular: any = { name: 'parent' };
+ * circular.self = circular;
+ *
+ * const result = unknownToString(circular);
+ * if (Result.isErr(result)) {
+ *   console.log(result.value.message);
+ *   // "Converting circular structure to JSON"
+ * }
+ *
+ * // Handle with custom serialization
+ * const safeStringify = (value: unknown): string => {
+ *   const result = unknownToString(value);
+ *   return Result.isOk(result)
+ *     ? result.value
+ *     : `[Error: ${result.value.message}]`;
+ * };
+ * ```
+ *
+ * @example Logging and debugging utilities
+ * ```typescript
+ * // Type-safe logger
+ * class Logger {
+ *   log(message: string, data?: unknown): void {
+ *     const timestamp = new Date().toISOString();
+ *     const dataStr = data !== undefined
+ *       ? unknownToString(data, { prettyPrintObject: true })
+ *       : Result.ok('');
+ *
+ *     if (Result.isOk(dataStr)) {
+ *       console.log(`[${timestamp}] ${message}`, dataStr.value);
+ *     } else {
+ *       console.log(`[${timestamp}] ${message} [Unstringifiable data]`);
+ *     }
+ *   }
+ * }
+ *
+ * const logger = new Logger();
+ * logger.log('User data:', { id: 123, name: 'John' });
+ * ```
+ *
+ * @example API response formatting
+ * ```typescript
+ * // Safe error response formatting
+ * function formatErrorResponse(error: unknown): string {
+ *   const result = unknownToString(error, { prettyPrintObject: true });
+ *
+ *   if (Result.isOk(result)) {
+ *     return JSON.stringify({
+ *       success: false,
+ *       error: result.value
+ *     });
+ *   }
+ *
+ *   // Fallback for unstringifiable errors
+ *   return JSON.stringify({
+ *     success: false,
+ *     error: 'An unknown error occurred'
+ *   });
+ * }
+ *
+ * try {
+ *   // some operation
+ * } catch (error) {
+ *   const response = formatErrorResponse(error);
+ *   res.status(500).send(response);
+ * }
+ * ```
+ *
+ * @example Working with special objects
+ * ```typescript
+ * // Date objects
+ * unknownToString(new Date('2023-01-01'));
+ * // Ok('"2023-01-01T00:00:00.000Z"') - JSON stringified
+ *
+ * // Regular expressions
+ * unknownToString(/test/gi);
+ * // Ok('{}') - RegExp has no enumerable properties
+ *
+ * // Arrays
+ * unknownToString([1, 'two', { three: 3 }]);
+ * // Ok('[1,"two",{"three":3}]')
+ *
+ * // Map and Set (converted to empty objects by JSON.stringify)
+ * unknownToString(new Map([['a', 1]])); // Ok('{}')
+ * unknownToString(new Set([1, 2, 3]));   // Ok('{}')
+ * ```
+ *
+ * @example Integration with Result type
+ * ```typescript
+ * import { Result, pipe } from '../functional';
+ *
+ * // Chain with other Result operations
+ * function processUserInput(input: unknown): Result<string, Error> {
+ *   return pipe(input)
+ *     .map(val => unknownToString(val))
+ *     .map(Result.flatten) // Flatten Result<Result<string, Error>, never>
+ *     .map(str => Result.map(str, s => s.trim()))
+ *     .map(Result.flatten)
+ *     .map(str => Result.flatMap(str, s =>
+ *       s.length > 0
+ *         ? Result.ok(s)
+ *         : Result.err(new Error('Empty string'))
+ *     ))
+ *     .value;
+ * }
+ * ```
+ *
+ * @see Result - For error handling pattern used by this function
+ * @see JSON.stringify - Underlying serialization for objects
+ */
+export declare const unknownToString: (value: unknown, options?: Partial<Readonly<{
+    prettyPrintObject: boolean;
+}>>) => Result<string, Error>;
+//# sourceMappingURL=unknown-to-string.d.mts.map

package/dist/others/unknown-to-string.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-to-string.d.mts","sourceRoot":"","sources":["../../src/others/unknown-to-string.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8KG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,OAAO,EACd,UAAU,OAAO,CAAC,QAAQ,CAAC;IAAE,iBAAiB,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,KAC1D,MAAM,CAAC,MAAM,EAAE,KAAK,CAiCtB,CAAC"}

package/dist/others/unknown-to-string.mjs

@@ -0,0 +1,211 @@
+import { isNonNullish } from '../guard/is-type.mjs';
+import '../functional/optional.mjs';
+import { Result } from '../functional/result.mjs';
+
+/**
+ * Converts an unknown value to its string representation in a type-safe manner.
+ *
+ * This function handles all JavaScript types and provides consistent string conversion
+ * with proper error handling for edge cases like circular references. Unlike naive
+ * toString() calls, this function never throws and handles all value types gracefully.
+ *
+ * **Type conversion rules:**
+ * - Strings: returned as-is
+ * - Numbers, booleans, bigints: converted via toString()
+ * - Symbols: converted to their description string
+ * - Functions: converted to their string representation
+ * - null: returns "null" (not "null" from JSON)
+ * - undefined: returns "undefined"
+ * - Objects: JSON stringified (with optional pretty printing)
+ *
+ * @param value - The unknown value to convert to string
+ * @param options - Optional configuration for the conversion
+ * @param options.prettyPrintObject - If true, objects are formatted with 2-space indentation
+ * @returns A Result containing either the string representation or an Error for failures
+ *
+ * @example Basic type conversions
+ * ```typescript
+ * // Primitive types
+ * unknownToString('hello');        // Ok('hello')
+ * unknownToString(123);            // Ok('123')
+ * unknownToString(true);           // Ok('true')
+ * unknownToString(null);           // Ok('null')
+ * unknownToString(undefined);      // Ok('undefined')
+ * unknownToString(Symbol('test')); // Ok('Symbol(test)')
+ * unknownToString(123n);           // Ok('123')
+ *
+ * // Function conversion
+ * const fn = () => 'test';
+ * unknownToString(fn); // Ok('() => 'test'')
+ * ```
+ *
+ * @example Object stringification
+ * ```typescript
+ * // Simple object
+ * const obj = { a: 1, b: 'hello', c: [1, 2, 3] };
+ * const result = unknownToString(obj);
+ * if (Result.isOk(result)) {
+ *   console.log(result.value); // '{"a":1,"b":"hello","c":[1,2,3]}'
+ * }
+ *
+ * // Pretty printing
+ * const prettyResult = unknownToString(obj, { prettyPrintObject: true });
+ * if (Result.isOk(prettyResult)) {
+ *   console.log(prettyResult.value);
+ *   // {
+ *   //   "a": 1,
+ *   //   "b": "hello",
+ *   //   "c": [
+ *   //     1,
+ *   //     2,
+ *   //     3
+ *   //   ]
+ *   // }
+ * }
+ * ```
+ *
+ * @example Error handling for circular references
+ * ```typescript
+ * // Circular reference
+ * const circular: any = { name: 'parent' };
+ * circular.self = circular;
+ *
+ * const result = unknownToString(circular);
+ * if (Result.isErr(result)) {
+ *   console.log(result.value.message);
+ *   // "Converting circular structure to JSON"
+ * }
+ *
+ * // Handle with custom serialization
+ * const safeStringify = (value: unknown): string => {
+ *   const result = unknownToString(value);
+ *   return Result.isOk(result)
+ *     ? result.value
+ *     : `[Error: ${result.value.message}]`;
+ * };
+ * ```
+ *
+ * @example Logging and debugging utilities
+ * ```typescript
+ * // Type-safe logger
+ * class Logger {
+ *   log(message: string, data?: unknown): void {
+ *     const timestamp = new Date().toISOString();
+ *     const dataStr = data !== undefined
+ *       ? unknownToString(data, { prettyPrintObject: true })
+ *       : Result.ok('');
+ *
+ *     if (Result.isOk(dataStr)) {
+ *       console.log(`[${timestamp}] ${message}`, dataStr.value);
+ *     } else {
+ *       console.log(`[${timestamp}] ${message} [Unstringifiable data]`);
+ *     }
+ *   }
+ * }
+ *
+ * const logger = new Logger();
+ * logger.log('User data:', { id: 123, name: 'John' });
+ * ```
+ *
+ * @example API response formatting
+ * ```typescript
+ * // Safe error response formatting
+ * function formatErrorResponse(error: unknown): string {
+ *   const result = unknownToString(error, { prettyPrintObject: true });
+ *
+ *   if (Result.isOk(result)) {
+ *     return JSON.stringify({
+ *       success: false,
+ *       error: result.value
+ *     });
+ *   }
+ *
+ *   // Fallback for unstringifiable errors
+ *   return JSON.stringify({
+ *     success: false,
+ *     error: 'An unknown error occurred'
+ *   });
+ * }
+ *
+ * try {
+ *   // some operation
+ * } catch (error) {
+ *   const response = formatErrorResponse(error);
+ *   res.status(500).send(response);
+ * }
+ * ```
+ *
+ * @example Working with special objects
+ * ```typescript
+ * // Date objects
+ * unknownToString(new Date('2023-01-01'));
+ * // Ok('"2023-01-01T00:00:00.000Z"') - JSON stringified
+ *
+ * // Regular expressions
+ * unknownToString(/test/gi);
+ * // Ok('{}') - RegExp has no enumerable properties
+ *
+ * // Arrays
+ * unknownToString([1, 'two', { three: 3 }]);
+ * // Ok('[1,"two",{"three":3}]')
+ *
+ * // Map and Set (converted to empty objects by JSON.stringify)
+ * unknownToString(new Map([['a', 1]])); // Ok('{}')
+ * unknownToString(new Set([1, 2, 3]));   // Ok('{}')
+ * ```
+ *
+ * @example Integration with Result type
+ * ```typescript
+ * import { Result, pipe } from '../functional';
+ *
+ * // Chain with other Result operations
+ * function processUserInput(input: unknown): Result<string, Error> {
+ *   return pipe(input)
+ *     .map(val => unknownToString(val))
+ *     .map(Result.flatten) // Flatten Result<Result<string, Error>, never>
+ *     .map(str => Result.map(str, s => s.trim()))
+ *     .map(Result.flatten)
+ *     .map(str => Result.flatMap(str, s =>
+ *       s.length > 0
+ *         ? Result.ok(s)
+ *         : Result.err(new Error('Empty string'))
+ *     ))
+ *     .value;
+ * }
+ * ```
+ *
+ * @see Result - For error handling pattern used by this function
+ * @see JSON.stringify - Underlying serialization for objects
+ */
+const unknownToString = (value, options) => {
+    switch (typeof value) {
+        case 'string':
+            return Result.ok(value);
+        case 'number':
+        case 'bigint':
+        case 'boolean':
+        case 'symbol':
+        case 'function':
+            return Result.ok(value.toString());
+        case 'object':
+            if (!isNonNullish(value)) {
+                return Result.ok('null');
+            }
+            try {
+                const stringified = options?.prettyPrintObject === true
+                    ? JSON.stringify(value, undefined, 2)
+                    : JSON.stringify(value);
+                return Result.ok(stringified);
+            }
+            catch (error) {
+                return Result.err(error instanceof Error
+                    ? error
+                    : new Error('Failed to stringify object'));
+            }
+        case 'undefined':
+            return Result.ok('undefined');
+    }
+};
+
+export { unknownToString };
+//# sourceMappingURL=unknown-to-string.mjs.map

package/dist/others/unknown-to-string.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-to-string.mjs","sources":["../../src/others/unknown-to-string.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8KG;MACU,eAAe,GAAG,CAC7B,KAAc,EACd,OAA2D,KAClC;IACzB,QAAQ,OAAO,KAAK;AAClB,QAAA,KAAK,QAAQ;AACX,YAAA,OAAO,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC;AAEzB,QAAA,KAAK,QAAQ;AACb,QAAA,KAAK,QAAQ;AACb,QAAA,KAAK,SAAS;AACd,QAAA,KAAK,QAAQ;AACb,QAAA,KAAK,UAAU;YACb,OAAO,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;AAEpC,QAAA,KAAK,QAAQ;AACX,YAAA,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE;AACxB,gBAAA,OAAO,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC;;AAE1B,YAAA,IAAI;AACF,gBAAA,MAAM,WAAW,GACf,OAAO,EAAE,iBAAiB,KAAK;sBAC3B,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC;AACpC,sBAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;AAC3B,gBAAA,OAAO,MAAM,CAAC,EAAE,CAAC,WAAW,CAAC;;YAC7B,OAAO,KAAK,EAAE;AACd,gBAAA,OAAO,MAAM,CAAC,GAAG,CACf,KAAK,YAAY;AACf,sBAAE;AACF,sBAAE,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAC5C;;AAGL,QAAA,KAAK,WAAW;AACd,YAAA,OAAO,MAAM,CAAC,EAAE,CAAC,WAAW,CAAC;;AAEnC;;;;"}

package/dist/tsconfig.json

@@ -0,0 +1 @@
+{"include":["."]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-data-forge",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "private": false,
   "keywords": [
     "typescript",
@@ -35,13 +35,14 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "npm run z:node-eval -- \"import { build } from './scripts/functions/build.mjs'; build();\"",
-    "check-all": "npm run z:node-eval -- \"import { checkAll } from './scripts/cmd/check-all.mjs'; checkAll();\"",
-    "check:ext": "npm run z:node-eval -- \"import { checkExt } from './scripts/functions/check-ext.mjs'; checkExt();\"",
+    "build": "npm run z:node-esm -- ./scripts/cmd/build.mjs",
+    "check-all": "npm run z:node-esm -- ./scripts/cmd/check-all.mjs",
+    "check:ext": "npm run z:node-esm -- ./scripts/cmd/check-ext.mjs",
     "cspell": "cspell \"**\" --gitignore --gitignore-root ./ --no-progress",
-    "doc": "npm run z:node-eval -- \"import { genDocs } from './scripts/functions/gen-docs.mjs'; genDocs();\"",
-    "fmt": "prettier --write .",
-    "gi": "npm run z:node-eval -- \"import { genIndex } from './scripts/functions/gen-index.mjs'; genIndex();\"",
+    "doc": "npm run z:node-esm -- ./scripts/cmd/gen-docs.mjs",
+    "fmt": "npm run z:node-esm -- ./scripts/cmd/fmt-diff.mjs",
+    "fmt:full": "prettier --write .",
+    "gi": "npm run z:node-esm -- ./scripts/cmd/gi.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "md": "markdownlint-cli2",
@@ -54,11 +55,11 @@
     "tscw": "tsc --noEmit --watch",
     "type-check": "tsc --noEmit",
     "update-packages": "npx npm-check-updates -u --install always --reject @types/node",
-    "z:node-eval": "node --import tsx/esm --input-type=module --eval",
+    "z:node-esm": "node --import tsx/esm",
     "z:vitest": "vitest --config ./configs/vitest.config.ts"
   },
   "dependencies": {
-    "ts-type-forge": "^2.0.2"
+    "ts-type-forge": "^2.0.3"
   },
   "devDependencies": {
     "@eslint/js": "^9.29.0",
@@ -72,9 +73,9 @@
     "@semantic-release/github": "^11.0.3",
     "@semantic-release/npm": "^12.0.1",
     "@semantic-release/release-notes-generator": "^14.0.3",
-    "@types/node": "^20.19.0",
-    "@vitest/coverage-v8": "^3.2.3",
-    "@vitest/ui": "^3.2.3",
+    "@types/node": "^20.19.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
     "conventional-changelog-conventionalcommits": "^9.0.0",
     "cspell": "^9.1.1",
     "eslint": "^9.29.0",
@@ -83,14 +84,15 @@
     "prettier": "^3.5.3",
     "prettier-plugin-organize-imports": "^4.1.0",
     "prettier-plugin-packagejson": "^2.5.15",
-    "rollup": "^4.43.0",
+    "rollup": "^4.44.0",
     "semantic-release": "^24.2.5",
+    "ts-repo-utils": "^1.2.0",
     "tsx": "^4.20.3",
     "typedoc": "^0.28.5",
-    "typedoc-plugin-markdown": "^4.6.4",
+    "typedoc-plugin-markdown": "^4.7.0",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.34.0",
-    "vitest": "^3.2.3"
+    "typescript-eslint": "^8.34.1",
+    "vitest": "^3.2.4"
   },
   "peerDependencies": {
     "typescript": ">=4.8"