@webpieces/core-util 0.0.0-dev

package/README.md

@@ -0,0 +1,108 @@
+# @webpieces/core-util
+
+Utility functions for WebPieces applications. Works in both browser and Node.js environments.
+
+## Installation
+
+```bash
+npm install @webpieces/core-util
+```
+
+## Features
+
+### toError() - Standardized Error Handling
+
+The `toError()` function converts any thrown value into a proper Error instance.
+
+#### Usage
+
+```typescript
+import { toError } from '@webpieces/core-util';
+
+try {
+  await riskyOperation();
+} catch (err: any) {
+  const error = toError(err);
+  console.error('Operation failed:', error.message);
+  throw error;
+}
+```
+
+#### Why use toError()?
+
+JavaScript allows throwing any value, not just Errors:
+- `throw "string error"` - loses stack trace
+- `throw { code: 404 }` - not an Error instance
+- `throw null` - extremely unhelpful
+
+`toError()` ensures you always have a proper Error object with:
+- Type safety (always returns Error)
+- Stack traces preserved when available
+- Consistent error structure
+- Integration with logging/monitoring
+
+#### Enforced Pattern
+
+WebPieces projects enforce this pattern via ESLint rule `@webpieces/catch-error-pattern`:
+
+**Required:**
+```typescript
+try {
+  operation();
+} catch (err: any) {
+  const error = toError(err);
+  // Handle error...
+}
+```
+
+**Alternative (explicitly ignored errors):**
+```typescript
+try {
+  operation();
+} catch (err: any) {
+  //const error = toError(err);
+}
+```
+
+#### Nested Catch Blocks
+
+For nested catches, use numbered suffixes:
+
+```typescript
+try {
+  operation1();
+} catch (err: any) {
+  const error = toError(err);
+  try {
+    rollback();
+  } catch (err2: any) {
+    const error2 = toError(err2);
+    console.error('Rollback failed:', error2);
+  }
+}
+```
+
+#### Behavior
+
+| Input Type | Behavior | Example |
+|------------|----------|---------|
+| Error instance | Returned unchanged | `toError(new Error('msg'))` → same Error |
+| Error-like object | Converts to Error, preserves message/name/stack | `toError({message: 'msg', stack: '...'})` |
+| Object without message | Stringifies object | `toError({code: 404})` → `Error("Non-Error object thrown: {...}")` |
+| String | Wraps in Error | `toError("error")` → `Error("error")` |
+| Number | Converts to string | `toError(404)` → `Error("404")` |
+| null/undefined | Generic message | `toError(null)` → `Error("Null or undefined thrown")` |
+
+## Browser Compatibility
+
+This package has zero dependencies and works in all modern browsers and Node.js environments.
+
+## Related Packages
+
+- [@webpieces/dev-config](https://www.npmjs.com/package/@webpieces/dev-config) - Includes ESLint rule that enforces this pattern
+- [@webpieces/core-context](https://www.npmjs.com/package/@webpieces/core-context) - Request context management
+- [@webpieces/http-server](https://www.npmjs.com/package/@webpieces/http-server) - HTTP server
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@webpieces/core-util",
+  "version": "0.0.0-dev",
+  "description": "Utility functions for WebPieces - works in browser and Node.js",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "keywords": [
+    "webpieces",
+    "utilities",
+    "error-handling"
+  ],
+  "author": "Dean Hiller",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanhiller/webpieces-ts.git",
+    "directory": "packages/core/core-util"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @webpieces/core-util
+ *
+ * Utility functions for WebPieces applications.
+ * This package works in both browser and Node.js environments.
+ *
+ * @packageDocumentation
+ */
+export { toError } from './lib/errorUtils';

package/src/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * @webpieces/core-util
+ *
+ * Utility functions for WebPieces applications.
+ * This package works in both browser and Node.js environments.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toError = void 0;
+var errorUtils_1 = require("./lib/errorUtils");
+Object.defineProperty(exports, "toError", { enumerable: true, get: function () { return errorUtils_1.toError; } });
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,+CAA2C;AAAlC,qGAAA,OAAO,OAAA","sourcesContent":["/**\n * @webpieces/core-util\n *\n * Utility functions for WebPieces applications.\n * This package works in both browser and Node.js environments.\n *\n * @packageDocumentation\n */\n\nexport { toError } from './lib/errorUtils';\n"]}

package/src/lib/errorUtils.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Error handling utilities for standardized error processing
+ * All catch blocks should use toError() to ensure consistent error handling
+ *
+ * This pattern is enforced by the @webpieces/eslint-plugin-webpieces rule:
+ * `catch-error-pattern`
+ */
+/**
+ * Converts unknown error types to Error instances
+ *
+ * This function standardizes all caught errors into Error objects, ensuring:
+ * - Type safety (always returns Error)
+ * - Consistent error structure
+ * - Proper stack traces
+ * - Integration with monitoring/logging systems
+ *
+ * **WebPieces Pattern**: All catch blocks must follow this pattern:
+ * ```typescript
+ * try {
+ *     riskyOperation();
+ * } catch (err: any) {
+ *     const error = toError(err);
+ *     // Handle error...
+ * }
+ * ```
+ *
+ * Alternative (explicitly ignored errors):
+ * ```typescript
+ * try {
+ *     riskyOperation();
+ * } catch (err: any) {
+ *     //const error = toError(err);
+ * }
+ * ```
+ *
+ * @param err - Unknown error from catch block (typed as any)
+ * @returns Standardized Error instance
+ *
+ * @example
+ * ```typescript
+ * // Standard usage
+ * try {
+ *     await riskyOperation();
+ * } catch (err: any) {
+ *     const error = toError(err);
+ *     console.error('Operation failed:', error.message);
+ *     throw error;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Nested catch blocks
+ * try {
+ *     await operation1();
+ * } catch (err: any) {
+ *     const error = toError(err);
+ *     try {
+ *         await rollback();
+ *     } catch (err2: any) {
+ *         const error2 = toError(err2);
+ *         console.error('Rollback failed:', error2);
+ *     }
+ * }
+ * ```
+ */
+export declare function toError(err: any): Error;

package/src/lib/errorUtils.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Error handling utilities for standardized error processing
+ * All catch blocks should use toError() to ensure consistent error handling
+ *
+ * This pattern is enforced by the @webpieces/eslint-plugin-webpieces rule:
+ * `catch-error-pattern`
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toError = toError;
+/**
+ * Converts unknown error types to Error instances
+ *
+ * This function standardizes all caught errors into Error objects, ensuring:
+ * - Type safety (always returns Error)
+ * - Consistent error structure
+ * - Proper stack traces
+ * - Integration with monitoring/logging systems
+ *
+ * **WebPieces Pattern**: All catch blocks must follow this pattern:
+ * ```typescript
+ * try {
+ *     riskyOperation();
+ * } catch (err: any) {
+ *     const error = toError(err);
+ *     // Handle error...
+ * }
+ * ```
+ *
+ * Alternative (explicitly ignored errors):
+ * ```typescript
+ * try {
+ *     riskyOperation();
+ * } catch (err: any) {
+ *     //const error = toError(err);
+ * }
+ * ```
+ *
+ * @param err - Unknown error from catch block (typed as any)
+ * @returns Standardized Error instance
+ *
+ * @example
+ * ```typescript
+ * // Standard usage
+ * try {
+ *     await riskyOperation();
+ * } catch (err: any) {
+ *     const error = toError(err);
+ *     console.error('Operation failed:', error.message);
+ *     throw error;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Nested catch blocks
+ * try {
+ *     await operation1();
+ * } catch (err: any) {
+ *     const error = toError(err);
+ *     try {
+ *         await rollback();
+ *     } catch (err2: any) {
+ *         const error2 = toError(err2);
+ *         console.error('Rollback failed:', error2);
+ *     }
+ * }
+ * ```
+ */
+function toError(err) {
+    // If already an Error instance, return it directly
+    if (err instanceof Error) {
+        return err;
+    }
+    // If it's an object with a message property, create Error from it
+    if (err && typeof err === 'object') {
+        if ('message' in err) {
+            const error = new Error(String(err.message));
+            // Preserve stack trace if available
+            if ('stack' in err && typeof err.stack === 'string') {
+                error.stack = err.stack;
+            }
+            // Preserve error name if available
+            if ('name' in err && typeof err.name === 'string') {
+                error.name = err.name;
+            }
+            return error;
+        }
+        // For objects without message, try to stringify
+        try {
+            const message = JSON.stringify(err);
+            return new Error(`Non-Error object thrown: ${message}`);
+        }
+        catch (err) {
+            // eslint-disable-next-line @webpieces/catch-error-pattern
+            // NOTE: Intentionally not calling toError() here to prevent infinite recursion
+            // in error recovery path. This is the ONLY acceptable exception to the pattern.
+            return new Error('Non-Error object thrown (unable to stringify)');
+        }
+    }
+    // For primitives (string, number, boolean, null, undefined)
+    const message = err == null ? 'Null or undefined thrown' : String(err);
+    return new Error(message);
+}
+//# sourceMappingURL=errorUtils.js.map

package/src/lib/errorUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorUtils.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/lib/errorUtils.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AA6DH,0BAuCC;AAlGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,SAAgB,OAAO,CAAC,GAAQ;IAC9B,mDAAmD;IACnD,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,kEAAkE;IAClE,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACnC,IAAI,SAAS,IAAI,GAAG,EAAE,CAAC;YACrB,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YAE7C,oCAAoC;YACpC,IAAI,OAAO,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACpD,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;YAC1B,CAAC;YAED,mCAAmC;YACnC,IAAI,MAAM,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAClD,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;YACxB,CAAC;YAED,OAAO,KAAK,CAAC;QACf,CAAC;QAED,gDAAgD;QAChD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YACpC,OAAO,IAAI,KAAK,CAAC,4BAA4B,OAAO,EAAE,CAAC,CAAC;QAC1D,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,0DAA0D;YAC1D,+EAA+E;YAC/E,gFAAgF;YAChF,OAAO,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IAED,4DAA4D;IAC5D,MAAM,OAAO,GAAG,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACvE,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;AAC5B,CAAC","sourcesContent":["/**\n * Error handling utilities for standardized error processing\n * All catch blocks should use toError() to ensure consistent error handling\n *\n * This pattern is enforced by the @webpieces/eslint-plugin-webpieces rule:\n * `catch-error-pattern`\n */\n\n/**\n * Converts unknown error types to Error instances\n *\n * This function standardizes all caught errors into Error objects, ensuring:\n * - Type safety (always returns Error)\n * - Consistent error structure\n * - Proper stack traces\n * - Integration with monitoring/logging systems\n *\n * **WebPieces Pattern**: All catch blocks must follow this pattern:\n * ```typescript\n * try {\n *     riskyOperation();\n * } catch (err: any) {\n *     const error = toError(err);\n *     // Handle error...\n * }\n * ```\n *\n * Alternative (explicitly ignored errors):\n * ```typescript\n * try {\n *     riskyOperation();\n * } catch (err: any) {\n *     //const error = toError(err);\n * }\n * ```\n *\n * @param err - Unknown error from catch block (typed as any)\n * @returns Standardized Error instance\n *\n * @example\n * ```typescript\n * // Standard usage\n * try {\n *     await riskyOperation();\n * } catch (err: any) {\n *     const error = toError(err);\n *     console.error('Operation failed:', error.message);\n *     throw error;\n * }\n * ```\n *\n * @example\n * ```typescript\n * // Nested catch blocks\n * try {\n *     await operation1();\n * } catch (err: any) {\n *     const error = toError(err);\n *     try {\n *         await rollback();\n *     } catch (err2: any) {\n *         const error2 = toError(err2);\n *         console.error('Rollback failed:', error2);\n *     }\n * }\n * ```\n */\nexport function toError(err: any): Error {\n  // If already an Error instance, return it directly\n  if (err instanceof Error) {\n    return err;\n  }\n\n  // If it's an object with a message property, create Error from it\n  if (err && typeof err === 'object') {\n    if ('message' in err) {\n      const error = new Error(String(err.message));\n\n      // Preserve stack trace if available\n      if ('stack' in err && typeof err.stack === 'string') {\n        error.stack = err.stack;\n      }\n\n      // Preserve error name if available\n      if ('name' in err && typeof err.name === 'string') {\n        error.name = err.name;\n      }\n\n      return error;\n    }\n\n    // For objects without message, try to stringify\n    try {\n      const message = JSON.stringify(err);\n      return new Error(`Non-Error object thrown: ${message}`);\n    } catch (err: any) {\n      // eslint-disable-next-line @webpieces/catch-error-pattern\n      // NOTE: Intentionally not calling toError() here to prevent infinite recursion\n      // in error recovery path. This is the ONLY acceptable exception to the pattern.\n      return new Error('Non-Error object thrown (unable to stringify)');\n    }\n  }\n\n  // For primitives (string, number, boolean, null, undefined)\n  const message = err == null ? 'Null or undefined thrown' : String(err);\n  return new Error(message);\n}\n"]}