@owlmeans/error 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OwlMeans Common — Fullstack typescript framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,390 @@
+# @owlmeans/error
+
+A fully typed error system for seamless error handling between backend and frontend, allowing errors to be marshaled/unmarshaled while preserving type information across network boundaries.
+
+## Overview
+
+The `@owlmeans/error` package provides a robust error handling system that enables type-safe error propagation between server and client applications. The core concept revolves around the `ResilientError` class, which can be:
+
+- **Marshaled** (serialized) on the server side
+- **Transmitted** over the network as regular Error objects  
+- **Unmarshaled** (deserialized) on the client side back to the same typed error class
+
+This ensures that error handling remains consistent and type-safe across the entire application stack.
+
+## Installation
+
+```bash
+npm install @owlmeans/error
+```
+
+## Core Concepts
+
+### ResilientError Class
+
+The `ResilientError` class is the foundation of the error system. It extends the standard JavaScript `Error` class and provides additional functionality for marshaling, unmarshaling, and type conversion.
+
+### Error Conversion System
+
+The package includes a flexible converter system that allows registration of custom error types and their conversion logic through the `Converter` interface.
+
+### Marshaling & Unmarshaling
+
+- **Marshaling**: Converting a ResilientError into a transferable format
+- **Unmarshaling**: Reconstructing a ResilientError from its marshaled form
+
+## API Reference
+
+### ResilientError Class
+
+#### Properties
+
+- `type: string` - The error type identifier
+- `oiriginalStack?: string` - The original stack trace when the error was created
+
+#### Static Properties
+
+- `separator: string` - The separator used in marshaled error messages (default: `'|||'`)
+- `typeName: string` - The default type name for ResilientError instances (default: `'ResilientError'`)
+- `converters: Converter[]` - Array of registered error converters
+
+#### Static Methods
+
+##### `registerErrorClass(resilientErrorClass, errorClass?)`
+
+Registers a custom error class with the converter system.
+
+**Parameters:**
+- `resilientErrorClass: ResilientErrorConstructor` - The ResilientError subclass to register
+- `errorClass?: ErrorConstructor` - Optional native Error class to convert from
+
+**Returns:** `Converter` - The created converter instance
+
+**Example:**
+```typescript
+class CustomError extends ResilientError {
+  static typeName = 'CustomError'
+}
+
+ResilientError.registerErrorClass(CustomError, TypeError)
+```
+
+##### `ensure(err, throwOnUnknown?)`
+
+Ensures an error is converted to a ResilientError instance.
+
+**Parameters:**
+- `err: Error | string` - The error to convert
+- `throwOnUnknown?: boolean` - Whether to throw on unknown error types (default: false)
+
+**Returns:** `ResilientError` - The converted error
+
+**Example:**
+```typescript
+const resilientError = ResilientError.ensure(new Error('Something went wrong'))
+const typedError = ResilientError.ensure('Error message')
+```
+
+##### `marshal(err)`
+
+Marshals an error for network transmission.
+
+**Parameters:**
+- `err: Error` - The error to marshal
+
+**Returns:** `Error` - A marshaled error object
+
+**Example:**
+```typescript
+const original = new ResilientError('CustomError', 'Something failed')
+const marshaled = ResilientError.marshal(original)
+// marshaled.message contains: "CustomError|||Something failed|||[stack trace]"
+```
+
+#### Instance Methods
+
+##### `marshal()`
+
+Marshals the current error instance.
+
+**Returns:** `Error` - A marshaled error object
+
+**Example:**
+```typescript
+const error = new ResilientError('MyError', 'Description')
+const marshaled = error.marshal()
+```
+
+##### `finalizeUnmarshal()`
+
+Called after unmarshaling to perform any post-processing. Override in subclasses for custom behavior.
+
+**Returns:** `void`
+
+#### Constructor
+
+```typescript
+constructor(type: string, message: string, stack?: string)
+constructor(message: string, stack?: string)
+```
+
+**Parameters:**
+- `type: string` - The error type identifier
+- `message: string` - The error message
+- `stack?: string` - Optional stack trace
+
+**Example:**
+```typescript
+const error1 = new ResilientError('ValidationError', 'Invalid input')
+const error2 = new ResilientError('Network error') // uses default type
+```
+
+### Helper Functions
+
+#### `enuserError<T>(err, throwOnUnknown?)`
+
+Convenience function that ensures an error is a ResilientError instance.
+
+**Parameters:**
+- `err: Error | string` - The error to ensure
+- `throwOnUnknown?: boolean` - Whether to throw on unknown error types
+
+**Returns:** `T extends ResilientError` - The ensured error
+
+**Example:**
+```typescript
+import { enuserError } from '@owlmeans/error'
+
+const resilientError = enuserError(new Error('Something went wrong'))
+const typedError = enuserError<MyCustomError>(someError)
+```
+
+#### `marshalError(err)`
+
+Convenience function that marshals an error after ensuring it's a ResilientError.
+
+**Parameters:**
+- `err: Error | string` - The error to marshal
+
+**Returns:** `Error` - The marshaled error
+
+**Example:**
+```typescript
+import { marshalError } from '@owlmeans/error'
+
+const marshaled = marshalError(new Error('Server error'))
+```
+
+### Utility Functions
+
+#### `createErrorConverter(resilientErrorClass, errorClass?)`
+
+Creates a converter for transforming native errors to ResilientError instances.
+
+**Parameters:**
+- `resilientErrorClass: ResilientErrorConstructor` - The target ResilientError class
+- `errorClass?: ErrorConstructor` - Optional source Error class to match against
+
+**Returns:** `Converter` - The created converter
+
+**Example:**
+```typescript
+import { createErrorConverter } from '@owlmeans/error'
+
+const converter = createErrorConverter(MyResilientError, TypeError)
+ResilientError.converters.push(converter)
+```
+
+#### `unmarshal<T>(errorClass)`
+
+Creates an unmarshaling function for a specific error class.
+
+**Parameters:**
+- `errorClass: ResilientErrorConstructor` - The error class to unmarshal to
+
+**Returns:** `(err: Error) => T` - Function that unmarshals errors to the specified type
+
+**Example:**
+```typescript
+import { unmarshal } from '@owlmeans/error'
+
+const unmarshalMyError = unmarshal(MyResilientError)
+const restored = unmarshalMyError(marshaledError)
+```
+
+### Type Definitions
+
+#### `ValueOrError<T>`
+
+A utility type that represents either a value or a ResilientError.
+
+```typescript
+type ValueOrError<T> = T | ResilientError
+```
+
+**Example:**
+```typescript
+function processData(): ValueOrError<string> {
+  if (someCondition) {
+    return "success"
+  }
+  return new ResilientError('ProcessingError', 'Failed to process')
+}
+```
+
+#### `Converter`
+
+Interface for error conversion logic.
+
+```typescript
+interface Converter {
+  match: (err: Error) => boolean
+  convert: (err: Error) => ResilientError
+  isMarshaled: (err: Error) => boolean
+  unmarshal: (err: Error) => ResilientError
+}
+```
+
+**Methods:**
+- `match(err)` - Determines if the converter can handle the error
+- `convert(err)` - Converts the error to a ResilientError
+- `isMarshaled(err)` - Checks if the error is in marshaled form
+- `unmarshal(err)` - Unmarshals the error back to ResilientError
+
+#### `ResilientErrorConstructor<T>`
+
+Constructor interface for ResilientError classes.
+
+```typescript
+interface ResilientErrorConstructor<T extends ResilientError = ResilientError> {
+  new (type: string, message: string, stack?: string): T
+  new (message: string, stack?: string): T
+  typeName: string
+}
+```
+
+### Constants
+
+#### `SEPARATOR`
+
+The default separator used in marshaled error messages.
+
+```typescript
+const SEPARATOR = '|||'
+```
+
+#### `RESILENT_ERROR`
+
+The default type name for ResilientError instances.
+
+```typescript
+const RESILENT_ERROR = 'ResilientError'
+```
+
+## Usage Examples
+
+### Basic Error Handling
+
+```typescript
+import { ResilientError, enuserError } from '@owlmeans/error'
+
+// Create a resilient error
+const error = new ResilientError('ValidationError', 'Invalid email format')
+
+// Ensure any error is resilient
+const resilientError = enuserError(new Error('Something went wrong'))
+```
+
+### Custom Error Types
+
+```typescript
+import { ResilientError } from '@owlmeans/error'
+
+class ValidationError extends ResilientError {
+  static typeName = 'ValidationError'
+  
+  constructor(field: string, message: string) {
+    super(ValidationError.typeName, `${field}: ${message}`)
+  }
+}
+
+// Register the custom error type
+ResilientError.registerErrorClass(ValidationError)
+```
+
+### Network Error Transmission
+
+```typescript
+import { ResilientError, marshalError, enuserError } from '@owlmeans/error'
+
+// Server side - marshal error for transmission
+function handleServerError(error: Error) {
+  const marshaled = marshalError(error)
+  return { error: marshaled.message }
+}
+
+// Client side - unmarshal received error
+function handleClientError(errorMessage: string) {
+  const error = new Error(errorMessage)
+  const resilientError = enuserError(error)
+  return resilientError
+}
+```
+
+### Error Conversion System
+
+```typescript
+import { ResilientError, createErrorConverter } from '@owlmeans/error'
+
+class NetworkError extends ResilientError {
+  static typeName = 'NetworkError'
+}
+
+// Register converter for fetch errors
+const converter = createErrorConverter(NetworkError, TypeError)
+ResilientError.converters.push(converter)
+
+// Now TypeError instances will be automatically converted
+const converted = ResilientError.ensure(new TypeError('Network failure'))
+// converted will be a NetworkError instance
+```
+
+### Working with ValueOrError
+
+```typescript
+import { ValueOrError, ResilientError } from '@owlmeans/error'
+
+function fetchUserData(id: string): ValueOrError<User> {
+  try {
+    // Simulate API call
+    return { id, name: 'John Doe' }
+  } catch (error) {
+    return new ResilientError('FetchError', 'Failed to fetch user')
+  }
+}
+
+const result = fetchUserData('123')
+if (result instanceof ResilientError) {
+  console.error('Error:', result.message)
+} else {
+  console.log('User:', result.name)
+}
+```
+
+## Best Practices
+
+1. **Define Custom Error Types**: Create specific error classes for different error categories
+2. **Register Error Classes**: Use `registerErrorClass()` to enable automatic conversion
+3. **Use Helper Functions**: Leverage `enuserError()` and `marshalError()` for common operations
+4. **Implement finalizeUnmarshal()**: Override in custom error classes for post-processing
+5. **Type Safety**: Use `ValueOrError<T>` type for functions that may return errors
+
+## Integration with OwlMeans Common
+
+This package integrates with the broader OwlMeans Common library ecosystem, following the established patterns for:
+- **Types**: Error-related type definitions
+- **Helpers**: Utility functions for error handling
+- **Service**: Domain-specific error handling logic
+- **i18n**: Internationalization support for error messages
+
+The error system is designed to work seamlessly across different OwlMeans packages including server, client, and web implementations.

package/build/consts.d.ts

@@ -0,0 +1,3 @@
+export declare const SEPARATOR = "|||";
+export declare const RESILENT_ERROR = "ResilientError";
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,SAAS,QAAQ,CAAA;AAE9B,eAAO,MAAM,cAAc,mBAAmB,CAAA"}

package/build/consts.js

@@ -0,0 +1,3 @@
+export const SEPARATOR = '|||';
+export const RESILENT_ERROR = 'ResilientError';
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,CAAA;AAE9B,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAA"}

package/build/helper.d.ts

@@ -0,0 +1,4 @@
+import { ResilientError } from './resilient.js';
+export declare const enuserError: <T extends ResilientError = ResilientError>(err: Error | string, throwOnUnknown?: boolean) => T;
+export declare const marshalError: (err: Error | string) => Error;
+//# sourceMappingURL=helper.d.ts.map

package/build/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE/C,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,cAAc,wBAAwB,KAAK,GAAG,MAAM,mBAAmB,OAAO,KAAG,CACtE,CAAA;AAEjD,eAAO,MAAM,YAAY,QAAS,KAAK,GAAG,MAAM,KAAG,KACC,CAAA"}

package/build/helper.js

@@ -0,0 +1,4 @@
+import { ResilientError } from './resilient.js';
+export const enuserError = (err, throwOnUnknown) => ResilientError.ensure(err, throwOnUnknown);
+export const marshalError = (err) => ResilientError.marshal(ResilientError.ensure(err));
+//# sourceMappingURL=helper.js.map

package/build/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE/C,MAAM,CAAC,MAAM,WAAW,GAAG,CAA4C,GAAmB,EAAE,cAAwB,EAAK,EAAE,CACzH,cAAc,CAAC,MAAM,CAAC,GAAG,EAAE,cAAc,CAAM,CAAA;AAEjD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,GAAmB,EAAS,EAAE,CACzD,cAAc,CAAC,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA"}

package/build/i18n/en.json

@@ -0,0 +1,4 @@
+{
+    "minLength": "The value is too short",
+    "maxLength": "The value is too long"
+}

package/build/i18n.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=i18n.d.ts.map

package/build/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":""}

package/build/i18n.js

@@ -0,0 +1,4 @@
+import { addI18nLib } from '@owlmeans/i18n';
+import en from './i18n/en.json' with { type: 'json' };
+addI18nLib('en', 'errors', en);
+//# sourceMappingURL=i18n.js.map

package/build/i18n.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAE3C,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AAErD,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,6 @@
+export * from './resilient.js';
+export * from './helper.js';
+export * from './consts.js';
+export * from './types.js';
+export * from './i18n.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA"}

package/build/index.js

@@ -0,0 +1,6 @@
+export * from './resilient.js';
+export * from './helper.js';
+export * from './consts.js';
+export * from './types.js';
+export * from './i18n.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA"}

package/build/resilient.d.ts

@@ -0,0 +1,15 @@
+import type { Converter, ResilientErrorConstructor } from './types.js';
+export declare class ResilientError extends Error {
+    static separator: string;
+    static typeName: string;
+    static converters: Converter[];
+    static registerErrorClass(resilientErrorClass: ResilientErrorConstructor, errorClass?: ErrorConstructor): Converter;
+    static ensure(err: Error | string, throwOnUnknown?: boolean): ResilientError;
+    static marshal(err: Error): Error;
+    type: string;
+    oiriginalStack?: string;
+    constructor(type: string, message: string, stack?: string);
+    marshal(): Error;
+    finalizeUnmarshal(): void;
+}
+//# sourceMappingURL=resilient.d.ts.map

package/build/resilient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilient.d.ts","sourceRoot":"","sources":["../src/resilient.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAGtE,qBAAa,cAAe,SAAQ,KAAK;IACvC,OAAc,SAAS,EAAE,MAAM,CAAY;IAE3C,OAAc,QAAQ,EAAE,MAAM,CAAiB;IAE/C,OAAc,UAAU,EAAE,SAAS,EAAE,CAAK;WAE5B,kBAAkB,CAAC,mBAAmB,EAAE,yBAAyB,EAAE,UAAU,CAAC,EAAE,gBAAgB,GAAG,SAAS;WAO5G,MAAM,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,EAAE,cAAc,CAAC,EAAE,OAAO,GAAG,cAAc;WA8BrE,OAAO,CAAC,GAAG,EAAE,KAAK,GAAG,KAAK;IAQjC,IAAI,EAAE,MAAM,CAAiB;IAE7B,cAAc,CAAC,EAAE,MAAM,CAAA;gBAElB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;IAUzD,OAAO,IAAI,KAAK;IAIhB,iBAAiB,IAAI,IAAI;CAC1B"}

package/build/resilient.js

@@ -0,0 +1,63 @@
+import { RESILENT_ERROR, SEPARATOR } from './consts.js';
+import { createErrorConverter } from './utils.js';
+export class ResilientError extends Error {
+    static separator = SEPARATOR;
+    static typeName = RESILENT_ERROR;
+    static converters = [];
+    static registerErrorClass(resilientErrorClass, errorClass) {
+        const converter = createErrorConverter(resilientErrorClass, errorClass);
+        this.converters.push(converter);
+        return converter;
+    }
+    static ensure(err, throwOnUnknown) {
+        err = typeof err === 'string' ? new Error(err) : err;
+        if (err instanceof ResilientError) {
+            return err;
+        }
+        // We don't proceed SyntaxError - system should crash in this case
+        if (err instanceof SyntaxError) {
+            throw err;
+        }
+        // Umarshal marhalled error that is wrapepd to ordinary error
+        const unmarhaller = this.converters.toReversed().find(converter => converter.isMarshaled(err));
+        if (unmarhaller != null) {
+            return unmarhaller.unmarshal(err);
+        }
+        // Convert object of Error subtypes to ResilientError subtype
+        const converter = this.converters.find(converter => converter.match(err));
+        if (converter != null) {
+            return converter.convert(err);
+        }
+        if (throwOnUnknown === true) {
+            throw err;
+        }
+        return new ResilientError(this.typeName, err.message, err.stack);
+    }
+    static marshal(err) {
+        if (err instanceof ResilientError) {
+            return new Error([err.type, err.message, err.oiriginalStack].join(this.separator));
+        }
+        return new Error([this.typeName, err.message, err.stack].join(this.separator));
+    }
+    type = RESILENT_ERROR;
+    oiriginalStack;
+    constructor(type, message, stack) {
+        super(message);
+        this.type = type;
+        if (stack != null) {
+            this.oiriginalStack = stack;
+        }
+        else {
+            this.oiriginalStack = this.stack;
+        }
+    }
+    marshal() {
+        return ResilientError.marshal(this);
+    }
+    finalizeUnmarshal() { }
+}
+ResilientError.converters.push({
+    ...createErrorConverter(ResilientError),
+    match: () => true
+});
+//# sourceMappingURL=resilient.js.map

package/build/resilient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilient.js","sourceRoot":"","sources":["../src/resilient.ts"],"names":[],"mappings":"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"}

package/build/types.d.ts

@@ -0,0 +1,14 @@
+import type { ResilientError } from './resilient.js';
+export type ValueOrError<T> = T | ResilientError;
+export interface Converter {
+    match: (err: Error) => boolean;
+    convert: (err: Error) => ResilientError;
+    isMarshaled: (err: Error) => boolean;
+    unmarshal: (err: Error) => ResilientError;
+}
+export interface ResilientErrorConstructor<T extends ResilientError = ResilientError> {
+    new (type: string, message: string, stack?: string): T;
+    new (message: string, stack?: string): T;
+    typeName: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,cAAc,CAAA;AAEhD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,CAAA;IAC9B,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,cAAc,CAAA;IACvC,WAAW,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,CAAA;IACpC,SAAS,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,cAAc,CAAA;CAC1C;AAED,MAAM,WAAW,yBAAyB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc;IAClF,KAAK,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,CAAA;IACtD,KAAK,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,CAAA;IACxC,QAAQ,EAAE,MAAM,CAAA;CACjB"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/build/utils.d.ts

@@ -0,0 +1,5 @@
+import { ResilientError } from './resilient.js';
+import type { Converter, ResilientErrorConstructor } from './types.js';
+export declare const createErrorConverter: (resilientErrorClass: ResilientErrorConstructor, errorClass?: ErrorConstructor) => Converter;
+export declare const unmarshal: <T extends ResilientError = ResilientError>(errorClass: ResilientErrorConstructor) => (err: Error) => T;
+//# sourceMappingURL=utils.d.ts.map

package/build/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAEtE,eAAO,MAAM,oBAAoB,wBACV,yBAAyB,eACjC,gBAAgB,KAC5B,SAQF,CAAA;AAED,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,cAAc,+BAA+B,yBAAyB,WAClG,KAAK,KAAG,CAiBb,CAAA"}

package/build/utils.js

@@ -0,0 +1,26 @@
+import { ResilientError } from './resilient.js';
+export const createErrorConverter = (resilientErrorClass, errorClass) => {
+    return {
+        match: err => errorClass != null && err instanceof errorClass,
+        convert: err => new resilientErrorClass(err.message, err.stack),
+        isMarshaled: err => err.message.startsWith(resilientErrorClass.typeName + ResilientError.separator),
+        unmarshal: unmarshal(resilientErrorClass)
+    };
+};
+export const unmarshal = (errorClass) => (err) => {
+    if (err instanceof errorClass) {
+        return err;
+    }
+    const args = err.message.split(ResilientError.separator, 3);
+    if (args.length < 2) {
+        throw SyntaxError('Invalid marshaled error');
+    }
+    if (args[0] === errorClass.typeName) {
+        args.shift();
+    }
+    const error = new errorClass(...args);
+    error.message = args[0];
+    error.finalizeUnmarshal();
+    return error;
+};
+//# sourceMappingURL=utils.js.map

package/build/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAG/C,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,mBAA8C,EAC9C,UAA6B,EAClB,EAAE;IACb,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,UAAU,IAAI,IAAI,IAAI,GAAG,YAAY,UAAU;QAC7D,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,mBAAmB,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC;QAC/D,WAAW,EAAE,GAAG,CAAC,EAAE,CACjB,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,mBAAmB,CAAC,QAAQ,GAAG,cAAc,CAAC,SAAS,CAAC;QACjF,SAAS,EAAE,SAAS,CAAC,mBAAmB,CAAC;KAC1C,CAAA;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,CAA4C,UAAqC,EAAE,EAAE,CAC5G,CAAC,GAAU,EAAK,EAAE;IAChB,IAAI,GAAG,YAAY,UAAU,EAAE,CAAC;QAC9B,OAAO,GAAQ,CAAA;IACjB,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,SAAS,EAAE,CAAC,CAA8B,CAAA;IACxF,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,WAAW,CAAC,yBAAyB,CAAC,CAAA;IAC9C,CAAC;IAED,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,UAAU,CAAC,QAAQ,EAAE,CAAC;QACpC,IAAI,CAAC,KAAK,EAAE,CAAA;IACd,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,GAAG,IAAI,CAAC,CAAA;IACrC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;IACvB,KAAK,CAAC,iBAAiB,EAAE,CAAA;IACzB,OAAO,KAAU,CAAA;AACnB,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@owlmeans/error",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 156 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@owlmeans/i18n": "^0.1.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.7",
+    "npm-check": "^6.0.1",
+    "typescript": "^5.6.3"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,4 @@
+
+export const SEPARATOR = '|||'
+
+export const RESILENT_ERROR = 'ResilientError'

package/src/helper.ts

@@ -0,0 +1,7 @@
+import { ResilientError } from './resilient.js'
+
+export const enuserError = <T extends ResilientError = ResilientError>(err: Error | string, throwOnUnknown?: boolean): T =>
+  ResilientError.ensure(err, throwOnUnknown) as T
+
+export const marshalError = (err: Error | string): Error =>
+  ResilientError.marshal(ResilientError.ensure(err))

package/src/i18n/en.json

@@ -0,0 +1,4 @@
+{
+  "minLength": "The value is too short",
+  "maxLength": "The value is too long"
+}

package/src/i18n.ts

@@ -0,0 +1,5 @@
+import { addI18nLib } from '@owlmeans/i18n'
+
+import en from './i18n/en.json' with { type: 'json' }
+
+addI18nLib('en', 'errors', en)

package/src/index.ts

@@ -0,0 +1,6 @@
+
+export * from './resilient.js'
+export * from './helper.js'
+export * from './consts.js'
+export * from './types.js'
+export * from './i18n.js'

package/src/resilient.ts

@@ -0,0 +1,81 @@
+import { RESILENT_ERROR, SEPARATOR } from './consts.js'
+import type { Converter, ResilientErrorConstructor } from './types.js'
+import { createErrorConverter } from './utils.js'
+
+export class ResilientError extends Error {
+  public static separator: string = SEPARATOR
+
+  public static typeName: string = RESILENT_ERROR
+
+  public static converters: Converter[] = []
+
+  public static registerErrorClass(resilientErrorClass: ResilientErrorConstructor, errorClass?: ErrorConstructor): Converter {
+    const converter = createErrorConverter(resilientErrorClass, errorClass)
+    this.converters.push(converter)
+
+    return converter
+  }
+
+  public static ensure(err: Error | string, throwOnUnknown?: boolean): ResilientError {
+    err = typeof err === 'string' ? new Error(err) : err
+    if (err instanceof ResilientError) {
+      return err
+    }
+
+    // We don't proceed SyntaxError - system should crash in this case
+    if (err instanceof SyntaxError) {
+      throw err
+    }
+
+    // Umarshal marhalled error that is wrapepd to ordinary error
+    const unmarhaller = this.converters.toReversed().find(converter => converter.isMarshaled(err))
+    if (unmarhaller != null) {
+      return unmarhaller.unmarshal(err)
+    }
+
+    // Convert object of Error subtypes to ResilientError subtype
+    const converter = this.converters.find(converter => converter.match(err))
+    if (converter != null) {
+      return converter.convert(err)
+    }
+
+    if (throwOnUnknown === true) {
+      throw err
+    }
+
+    return new ResilientError(this.typeName, err.message, err.stack)
+  }
+
+  public static marshal(err: Error): Error {
+    if (err instanceof ResilientError) {
+      return new Error([err.type, err.message, err.oiriginalStack].join(this.separator))
+    }
+
+    return new Error([this.typeName, err.message, err.stack].join(this.separator))
+  }
+
+  public type: string = RESILENT_ERROR
+
+  public oiriginalStack?: string
+
+  constructor(type: string, message: string, stack?: string) {
+    super(message)
+    this.type = type
+    if (stack != null) {
+      this.oiriginalStack = stack
+    } else {
+      this.oiriginalStack = this.stack
+    }
+  }
+
+  marshal(): Error {
+    return ResilientError.marshal(this)
+  }
+
+  finalizeUnmarshal(): void { }
+}
+
+ResilientError.converters.push({
+  ...createErrorConverter(ResilientError as ResilientErrorConstructor),
+  match: () => true
+})

package/src/types.ts

@@ -0,0 +1,16 @@
+import type { ResilientError } from './resilient.js'
+
+export type ValueOrError<T> = T | ResilientError
+
+export interface Converter {
+  match: (err: Error) => boolean
+  convert: (err: Error) => ResilientError
+  isMarshaled: (err: Error) => boolean
+  unmarshal: (err: Error) => ResilientError
+}
+
+export interface ResilientErrorConstructor<T extends ResilientError = ResilientError> {
+  new (type: string, message: string, stack?: string): T
+  new (message: string, stack?: string): T
+  typeName: string
+}

package/src/utils.ts

@@ -0,0 +1,35 @@
+import { ResilientError } from './resilient.js'
+import type { Converter, ResilientErrorConstructor } from './types.js'
+
+export const createErrorConverter = (
+  resilientErrorClass: ResilientErrorConstructor,
+  errorClass?: ErrorConstructor
+): Converter => {
+  return {
+    match: err => errorClass != null && err instanceof errorClass,
+    convert: err => new resilientErrorClass(err.message, err.stack),
+    isMarshaled: err =>
+      err.message.startsWith(resilientErrorClass.typeName + ResilientError.separator),
+    unmarshal: unmarshal(resilientErrorClass)
+  }
+}
+
+export const unmarshal = <T extends ResilientError = ResilientError>(errorClass: ResilientErrorConstructor) =>
+  (err: Error): T => {
+    if (err instanceof errorClass) {
+      return err as T
+    }
+    const args = err.message.split(ResilientError.separator, 3) as [string, string, string?]
+    if (args.length < 2) {
+      throw SyntaxError('Invalid marshaled error')
+    }
+
+    if (args[0] === errorClass.typeName) {
+      args.shift()
+    }
+
+    const error = new errorClass(...args)
+    error.message = args[0]
+    error.finalizeUnmarshal()
+    return error as T
+  }

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": [
+    "../tsconfig.default.json",
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/", /* Specify the root folder within your source files. */
+    "outDir": "./build/", /* Specify an output folder for all emitted files. */
+  },
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./*.ts"
+  ]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/consts.ts","./src/helper.ts","./src/i18n.ts","./src/index.ts","./src/resilient.ts","./src/types.ts","./src/utils.ts"],"version":"5.6.3"}