@travetto/runtime 5.0.10 → 5.0.12

package/README.md

@@ -164,9 +164,9 @@ export class EnvProp<T> {
 ```
 
 ## Standard Error Support
-While the framework is 100 % compatible with standard `Error` instances, there are cases in which additional functionality is desired. Within the framework we use [AppError](https://github.com/travetto/travetto/tree/main/module/runtime/src/error.ts#L15) (or its derivatives) to represent framework errors. This class is available for use in your own projects. Some of the additional benefits of using this class is enhanced error reporting, as well as better integration with other modules (e.g. the [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module.") module and HTTP status codes). 
+While the framework is 100 % compatible with standard `Error` instances, there are cases in which additional functionality is desired. Within the framework we use [AppError](https://github.com/travetto/travetto/tree/main/module/runtime/src/error.ts#L26) (or its derivatives) to represent framework errors. This class is available for use in your own projects. Some of the additional benefits of using this class is enhanced error reporting, as well as better integration with other modules (e.g. the [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module.") module and HTTP status codes). 
 
-The [AppError](https://github.com/travetto/travetto/tree/main/module/runtime/src/error.ts#L15) takes in a message, and an optional payload and / or error classification. The currently supported error classifications are:
+The [AppError](https://github.com/travetto/travetto/tree/main/module/runtime/src/error.ts#L26) takes in a message, and an optional payload and / or error classification. The currently supported error classifications are:
    *  `general` - General purpose errors
    *  `system` - Synonym for `general`
    *  `data` - Data format, content, etc are incorrect. Generally correlated to bad input.
@@ -254,7 +254,7 @@ $ DEBUG=express:*,@travetto/rest npx trv run rest
 ## Resource Access
 The primary access patterns for resources, is to directly request a file, and to resolve that file either via file-system look up or leveraging the [Manifest](https://github.com/travetto/travetto/tree/main/module/manifest#readme "Support for project indexing, manifesting, along with file watching")'s data for what resources were found at manifesting time.
 
-The [FileLoader](https://github.com/travetto/travetto/tree/main/module/runtime/src/file-loader.ts#L11) allows for accessing information about the resources, and subsequently reading the file as text/binary or to access the resource as a `Readable` stream.  If a file is not found, it will throw an [AppError](https://github.com/travetto/travetto/tree/main/module/runtime/src/error.ts#L15) with a category of 'notfound'.  
+The [FileLoader](https://github.com/travetto/travetto/tree/main/module/runtime/src/file-loader.ts#L11) allows for accessing information about the resources, and subsequently reading the file as text/binary or to access the resource as a `Readable` stream.  If a file is not found, it will throw an [AppError](https://github.com/travetto/travetto/tree/main/module/runtime/src/error.ts#L26) with a category of 'notfound'.  
 
 The [FileLoader](https://github.com/travetto/travetto/tree/main/module/runtime/src/file-loader.ts#L11) also supports tying itself to [Env](https://github.com/travetto/travetto/tree/main/module/runtime/src/env.ts#L111)'s `TRV_RESOURCES` information on where to attempt to find a requested resource.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/runtime",
-  "version": "5.0.10",
+  "version": "5.0.12",
   "description": "Runtime for travetto applications.",
   "keywords": [
     "console-manager",
@@ -28,13 +28,13 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
-    "@travetto/manifest": "^5.0.7",
+    "@travetto/manifest": "^5.0.9",
     "@types/debug": "^4.1.12",
-    "@types/node": "^22.7.4",
+    "@types/node": "^22.7.9",
     "debug": "^4.3.7"
   },
   "peerDependencies": {
-    "@travetto/transformer": "^5.0.8"
+    "@travetto/transformer": "^5.0.10"
   },
   "peerDependenciesMeta": {
     "@travetto/transformer": {

package/src/binary.ts

@@ -108,7 +108,7 @@ export class BinaryUtil {
       transform(chunk, encoding, callback): void {
         read += (Buffer.isBuffer(chunk) || typeof chunk === 'string') ? chunk.length : (chunk instanceof Uint8Array ? chunk.byteLength : 0);
         if (read > maxSize) {
-          callback(new AppError('File size exceeded', 'data', { read, size: maxSize }));
+          callback(new AppError('File size exceeded', { category: 'data', details: { read, size: maxSize } }));
         } else {
           callback(null, chunk);
         }

package/src/error.ts

@@ -9,10 +9,21 @@ export type ErrorCategory =
   'timeout' |
   'unavailable';
 
+export type AppErrorOptions<T> =
+  ErrorOptions &
+  {
+    at?: Date | string | number;
+    type?: string;
+    category?: ErrorCategory;
+  } &
+  (T extends undefined ?
+    { details?: T } :
+    { details: T });
+
 /**
  * Framework error class, with the aim of being extensible
  */
-export class AppError<T = unknown> extends Error {
+export class AppError<T = Record<string, unknown> | undefined> extends Error {
 
   /** Convert from JSON object */
   static fromJSON(e: unknown): AppError | undefined {
@@ -20,47 +31,46 @@ export class AppError<T = unknown> extends Error {
       ('message' in e && typeof e.message === 'string') &&
       ('category' in e && typeof e.category === 'string') &&
       ('type' in e && typeof e.type === 'string') &&
-      ('at' in e && typeof e.at === 'number')
+      ('at' in e && typeof e.at === 'string')
     ) {
-      const err = new AppError(e.message, castTo(e.category), 'details' in e ? e.details : undefined);
-      err.at = new Date(e.at);
-      err.type = e.type;
-      return err;
+      return new AppError(e.message, castTo<AppErrorOptions<Record<string, unknown>>>(e));
     }
   }
 
   type: string;
-  at = new Date();
+  category: ErrorCategory;
+  at: string;
   details: T;
 
   /**
    * Build an app error
    *
    * @param message The error message
-   * @param category The error category, can be mapped to HTTP statuses
-   * @param details Optional error payload
    */
   constructor(
-    message: string,
-    public category: ErrorCategory = 'general',
-    details?: T
-
+    ...[message, opts]:
+      T extends undefined ? ([string] | [string, AppErrorOptions<T>]) : [string, AppErrorOptions<T>]
   ) {
-    super(message);
-    this.type = this.constructor.name;
-    this.details = details!;
+    super(message, opts?.cause ? { cause: opts.cause } : undefined);
+    this.type = opts?.type ?? this.constructor.name;
+    this.details = opts?.details!;
+    this.category = opts?.category ?? 'general';
+    this.at = new Date(opts?.at ?? Date.now()).toISOString();
   }
 
   /**
-   * The format of the JSON output
+   * Serializes an error to a basic object
    */
-  toJSON(): { message: string, category: string, type: string, at: string, details?: Record<string, unknown> } {
-    return {
-      message: this.message,
+  toJSON(): AppErrorOptions<T> & { message: string } {
+    const res: AppErrorOptions<unknown> = {
       category: this.category,
+      ...(this.cause ? { cause: `${this.cause}` } : undefined),
       type: this.type,
-      at: this.at.toISOString(),
-      details: castTo(this.details),
+      at: this.at,
+      ...(this.details ? { details: this.details } : undefined!),
     };
+
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return { message: this.message, ...res as AppErrorOptions<T> };
   }
 }

package/src/file-loader.ts

@@ -34,7 +34,7 @@ export class FileLoader {
         return resolved;
       }
     }
-    throw new AppError(`Unable to find: ${relativePath}, searched=${this.searchPaths.join(',')}`, 'notfound');
+    throw new AppError(`Unable to find: ${relativePath}, searched=${this.searchPaths.join(',')}`, { category: 'notfound' });
   }
 
   /**

package/src/types.ts

@@ -49,6 +49,8 @@ export function classConstruct<T>(cls: Class<T>, args: unknown[] = []): ClassIns
 export const hasFunction = <T>(key: keyof T) => (o: unknown): o is T =>
   typeof o === 'object' && o !== null && typeof o[castKey(key)] === 'function';
 
+export const hasToJSON = hasFunction<{ toJSON(): object }>('toJSON');
+
 /**
  * Range of bytes, inclusive
  */

package/src/util.ts

@@ -47,10 +47,12 @@ export class Util {
    */
   static uuid(len: number = 32): string {
     const bytes = crypto.randomBytes(Math.ceil(len / 2));
-    // eslint-disable-next-line no-bitwise
-    bytes[6] = (bytes[6] & 0x0f) | 0x40;
-    // eslint-disable-next-line no-bitwise
-    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    if (len === 32) { // Make valid uuid-v4
+      // eslint-disable-next-line no-bitwise
+      bytes[6] = (bytes[6] & 0x0f) | 0x40;
+      // eslint-disable-next-line no-bitwise
+      bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    }
     return bytes.toString('hex').substring(0, len);
   }