@travetto/runtime 7.1.4 → 8.0.0-alpha.1

package/src/codec.ts

@@ -0,0 +1,105 @@
+import { createInterface } from 'node:readline/promises';
+
+import { BinaryUtil, type BinaryArray, type BinaryType } from './binary.ts';
+import { RuntimeError } from './error.ts';
+import { castTo, type Any } from './types.ts';
+
+type TextInput = string | BinaryArray;
+
+const UTF8_DECODER = new TextDecoder('utf8');
+const UTF8_ENCODER = new TextEncoder();
+
+/**
+ * Utilities for encoding and decoding common formats
+ */
+export class CodecUtil {
+
+  /** Generate buffer from hex string  */
+  static fromHexString(value: string): BinaryArray {
+    try {
+      return Uint8Array.fromHex(value);
+    } catch (err) {
+      if (err instanceof SyntaxError) {
+        throw new RuntimeError('Invalid hex string', { cause: err });
+      }
+      throw err;
+    }
+  }
+
+  /** Convert hex bytes to string  */
+  static toHexString(value: BinaryArray): string {
+    return BinaryUtil.binaryArrayToUint8Array(value).toHex();
+  }
+
+  /** Return buffer from base64 string  */
+  static fromBase64String(value: string): BinaryArray {
+    try {
+      return Uint8Array.fromBase64(value);
+    } catch (err) {
+      if (err instanceof SyntaxError) {
+        throw new RuntimeError('Invalid base64 string', { cause: err });
+      }
+      throw err;
+    }
+  }
+
+  /** Convert value to base64 string  */
+  static toBase64String(value: BinaryArray): string {
+    return BinaryUtil.binaryArrayToUint8Array(value).toBase64();
+  }
+
+  /** Return buffer from utf8 string  */
+  static fromUTF8String(value: string): BinaryArray {
+    return UTF8_ENCODER.encode(value);
+  }
+
+  /** Return utf8 string from bytes  */
+  static toUTF8String(value: BinaryArray): string {
+    return UTF8_DECODER.decode(BinaryUtil.binaryArrayToUint8Array(value));
+  }
+
+  /** Convert utf8 value to base64 value string  */
+  static utf8ToBase64(value: TextInput): string {
+    return this.toBase64String(typeof value === 'string' ? this.fromUTF8String(value) : value);
+  }
+
+  /** Convert base64 value to utf8 string  */
+  static base64ToUTF8(value: TextInput): string {
+    const result = this.toUTF8String(typeof value === 'string' ? this.fromBase64String(value) : value);
+    return result;
+  }
+
+  /** Convert url encoded base64 value to utf8 string  */
+  static urlEncodedBase64ToUTF8(value: TextInput): string {
+    const result = this.base64ToUTF8(value);
+    return result.startsWith('%') ? decodeURIComponent(result) : result;
+  }
+
+  /** Detect encoding of a binary type, if possible  */
+  static detectEncoding(input: BinaryType): string | undefined {
+    if (input && typeof input === 'object' && 'readableEncoding' in input && typeof input.readableEncoding === 'string') {
+      return input.readableEncoding;
+    }
+  }
+
+  /** Consume lines  */
+  static async readLines(stream: BinaryType, handler: (input: string) => unknown | Promise<unknown>): Promise<void> {
+    for await (const item of createInterface(BinaryUtil.toReadable(stream))) {
+      await handler(item);
+    }
+  }
+
+  /** Read chunk as utf8 if not a binary array */
+  static readUtf8Chunk(chunk: Any): BinaryArray {
+    return BinaryUtil.isBinaryArray(chunk) ? chunk : this.fromUTF8String(typeof chunk === 'string' ? chunk : `${chunk}`);
+  }
+
+  /** Read chunk, default to toString if type is unknown  */
+  static readChunk(chunk: Any, encoding?: string | null): BinaryArray {
+    if (!encoding) {
+      return this.readUtf8Chunk(chunk);
+    }
+    return BinaryUtil.isBinaryArray(chunk) ? chunk :
+      Buffer.from(typeof chunk === 'string' ? chunk : `${chunk}`, castTo(encoding ?? 'utf8'));
+  }
+}

package/src/console.ts

@@ -79,7 +79,6 @@ class $ConsoleManager implements ConsoleListener {
    * Enable/disable enhanced debugging
    */
   enhanceDebug(active: boolean): void {
-    Error.stackTraceLimit = active ? 50 : 10;
     if (active) {
       debug.formatArgs = function (args: string[]): void {
         args.unshift(this.namespace);

package/src/context.ts

@@ -6,8 +6,8 @@ import { type ManifestIndex, type ManifestContext, ManifestModuleUtil } from '@t
 import { Env } from './env.ts';
 import { RuntimeIndex } from './manifest-index.ts';
 import { describeFunction } from './function.ts';
-import { JSONUtil } from './json.ts';
 import type { Role } from './trv';
+import { JSONUtil } from './json.ts';
 
 /** Constrained version of {@type ManifestContext} */
 class $Runtime {
@@ -119,7 +119,7 @@ class $Runtime {
       throw new Error(`Unable to find ${location}, not in the manifest`);
     } else if (location.endsWith('.json')) {
       location = this.#idx.getFromImport(location)?.sourceFile ?? location;
-      return fs.readFile(location, 'utf8').then(JSONUtil.parseSafe<T>);
+      return fs.readFile(location).then(JSONUtil.fromBinaryArray<T>);
     }
 
     if (!ManifestModuleUtil.SOURCE_EXT_REGEX.test(location)) {

package/src/error.ts

@@ -9,70 +9,33 @@ 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 });
+export type RuntimeErrorOptions<T> = Omit<Partial<RuntimeError>, 'details'> & (T extends undefined ? { details?: T } : { details: T });
 
 /**
  * Framework error class, with the aim of being extensible
  */
-export class AppError<T = Record<string, unknown> | undefined> extends Error {
+export class RuntimeError<T = Record<string, unknown> | undefined> extends Error {
 
-  static defaultCategory?: ErrorCategory;
-
-  /** Convert from JSON object */
-  static fromJSON(error: unknown): AppError | undefined {
-    if (!!error && typeof error === 'object' &&
-      ('message' in error && typeof error.message === 'string') &&
-      ('category' in error && typeof error.category === 'string') &&
-      ('type' in error && typeof error.type === 'string') &&
-      ('at' in error && typeof error.at === 'string')
-    ) {
-      return new AppError(error.message, castTo<AppErrorOptions<Record<string, unknown>>>(error));
-    }
-  }
+  static defaultCategory: ErrorCategory = 'general';
 
   type: string;
   category: ErrorCategory;
-  at: string;
+  at: Date;
   details: T;
 
   /**
-   * Build an app error
+   * Build a runtime error
    *
    * @param message The error message
    */
   constructor(
     ...[message, options]:
-      T extends undefined ? ([string] | [string, AppErrorOptions<T>]) : [string, AppErrorOptions<T>]
+      T extends undefined ? ([string] | [string, RuntimeErrorOptions<T>]) : [string, RuntimeErrorOptions<T>]
   ) {
     super(message, options?.cause ? { cause: options.cause } : undefined);
     this.type = options?.type ?? this.constructor.name;
     this.details = options?.details!;
-    this.category = options?.category ?? castTo<typeof AppError>(this.constructor).defaultCategory ?? 'general';
-    this.at = new Date(options?.at ?? Date.now()).toISOString();
-  }
-
-  /**
-   * Serializes an error to a basic object
-   */
-  toJSON(): AppErrorOptions<T> & { message: string } {
-    const options: AppErrorOptions<unknown> = {
-      category: this.category,
-      ...(this.cause ? { cause: `${this.cause}` } : undefined),
-      type: this.type,
-      at: this.at,
-      ...(this.details ? { details: this.details } : undefined!),
-    };
-
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    return { message: this.message, ...options as AppErrorOptions<T> };
+    this.category = options?.category ?? castTo<typeof RuntimeError>(this.constructor).defaultCategory ?? 'general';
+    this.at = new Date(options?.at ?? Date.now());
   }
 }

package/src/exec.ts

@@ -1,16 +1,16 @@
 import { type ChildProcess, spawn, type SpawnOptions } from 'node:child_process';
-import type { Readable } from 'node:stream';
-import { createInterface } from 'node:readline/promises';
 
 import { castTo } from './types.ts';
 import { RuntimeIndex } from './manifest-index.ts';
+import { BinaryUtil, type BinaryArray } from './binary.ts';
+import { CodecUtil } from './codec.ts';
 
 const ResultSymbol = Symbol();
 
 /**
  * Result of an execution
  */
-export interface ExecutionResult<T extends string | Buffer = string | Buffer> {
+export interface ExecutionResult<T extends string | BinaryArray = string | BinaryArray> {
   /**
    * Stdout
    */
@@ -50,12 +50,12 @@ export class ExecUtil {
    */
   static getResult(subProcess: ChildProcess): Promise<ExecutionResult<string>>;
   static getResult(subProcess: ChildProcess, options: { catch?: boolean, binary?: false }): Promise<ExecutionResult<string>>;
-  static getResult(subProcess: ChildProcess, options: { catch?: boolean, binary: true }): Promise<ExecutionResult<Buffer>>;
-  static getResult<T extends string | Buffer>(subProcess: ChildProcess, options: { catch?: boolean, binary?: boolean } = {}): Promise<ExecutionResult<T>> {
+  static getResult(subProcess: ChildProcess, options: { catch?: boolean, binary: true }): Promise<ExecutionResult<BinaryArray>>;
+  static getResult<T extends string | BinaryArray>(subProcess: ChildProcess, options: { catch?: boolean, binary?: boolean } = {}): Promise<ExecutionResult<T>> {
     const typed: ChildProcess & { [ResultSymbol]?: Promise<ExecutionResult> } = subProcess;
     const result = typed[ResultSymbol] ??= new Promise<ExecutionResult>(resolve => {
-      const stdout: Buffer[] = [];
-      const stderr: Buffer[] = [];
+      const stdout: BinaryArray[] = [];
+      const stderr: BinaryArray[] = [];
       let done = false;
       const finish = (finalResult: ExecutionBaseResult): void => {
         if (done) {
@@ -64,13 +64,13 @@ export class ExecUtil {
         done = true;
 
         const buffers = {
-          stdout: Buffer.concat(stdout),
-          stderr: Buffer.concat(stderr),
+          stdout: BinaryUtil.combineBinaryArrays(stdout),
+          stderr: BinaryUtil.combineBinaryArrays(stderr),
         };
 
         const final = {
-          stdout: options.binary ? buffers.stdout : buffers.stdout.toString('utf8'),
-          stderr: options.binary ? buffers.stderr : buffers.stderr.toString('utf8'),
+          stdout: options.binary ? buffers.stdout : buffers.stdout.toString(subProcess.stdout?.readableEncoding ?? 'utf8'),
+          stderr: options.binary ? buffers.stderr : buffers.stderr.toString(subProcess.stderr?.readableEncoding ?? 'utf8'),
           ...finalResult
         };
 
@@ -80,8 +80,8 @@ export class ExecUtil {
         );
       };
 
-      subProcess.stdout?.on('data', (data: string | Buffer) => stdout.push(Buffer.isBuffer(data) ? data : Buffer.from(data)));
-      subProcess.stderr?.on('data', (data: string | Buffer) => stderr.push(Buffer.isBuffer(data) ? data : Buffer.from(data)));
+      subProcess.stdout?.on('data', data => stdout.push(CodecUtil.readChunk(data, subProcess.stdout?.readableEncoding)));
+      subProcess.stderr?.on('data', data => stderr.push(CodecUtil.readChunk(data, subProcess.stderr?.readableEncoding)));
 
       subProcess.on('error', (error: Error) =>
         finish({ code: 1, message: error.message, valid: false }));
@@ -103,15 +103,6 @@ export class ExecUtil {
     }));
   }
 
-  /**
-   * Consume lines
-   */
-  static async readLines(stream: Readable, handler: (input: string) => unknown | Promise<unknown>): Promise<void> {
-    for await (const item of createInterface(stream)) {
-      await handler(item);
-    }
-  }
-
   /** Spawn a package command */
   static spawnPackageCommand(cmd: string, args: string[], config: SpawnOptions = {}): ChildProcess {
     return spawn(process.argv0, [RuntimeIndex.resolvePackageCommand(cmd), ...args], config);

package/src/file-loader.ts

@@ -1,10 +1,9 @@
 import { createReadStream } from 'node:fs';
-import type { Readable } from 'node:stream';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { AppError } from './error.ts';
-import { JSONUtil } from './json.ts';
+import { RuntimeError } from './error.ts';
+import { BinaryUtil, type BinaryArray, type BinaryStream } from './binary.ts';
 
 /**
  * File loader that will search for files across the provided search paths
@@ -35,42 +34,42 @@ export class FileLoader {
         return resolved;
       }
     }
-    throw new AppError(`Unable to find: ${relativePath}, searched=${this.searchPaths.join(',')}`, { category: 'notfound' });
+    throw new RuntimeError(`Unable to find: ${relativePath}, searched=${this.searchPaths.join(',')}`, { category: 'notfound' });
   }
 
   /**
-   * Read a file, after resolving the path
+   * Read a file as utf8 text, after resolving the path
    * @param relativePath The path to read
    */
-  async read(relativePath: string, binary?: false): Promise<string>;
-  async read(relativePath: string, binary: true): Promise<Buffer>;
-  async read(relativePath: string, binary = false): Promise<string | Buffer> {
+  async readText(relativePath: string): Promise<string> {
     const file = await this.resolve(relativePath);
-    return fs.readFile(file, binary ? undefined : 'utf8');
+    return fs.readFile(file, 'utf8');
   }
 
   /**
-   * Read a file as a stream
+   * Read a file as a byte array, after resolving the path
    * @param relativePath The path to read
    */
-  async readStream(relativePath: string, binary = true): Promise<Readable> {
+  async readBinaryArray(relativePath: string): Promise<BinaryArray> {
     const file = await this.resolve(relativePath);
-    return createReadStream(file, { encoding: binary ? undefined : 'utf8' });
+    return fs.readFile(file);
   }
 
   /**
-   * Read a file as a File object
+   * Read a file as a stream
    * @param relativePath The path to read
    */
-  async readFile(relativePath: string): Promise<File> {
-    return new File([await this.read(relativePath, true)], path.basename(relativePath));
+  async readBinaryStream(relativePath: string): Promise<BinaryStream> {
+    const file = await this.resolve(relativePath);
+    return createReadStream(file);
   }
 
   /**
-   * Read relative file as JSON
+   * Read a file as a File object
+   * @param relativePath The path to read
    */
-  async readJSON<T>(relativePath: string): Promise<T> {
-    const location = await this.resolve(relativePath);
-    return JSONUtil.readFile<T>(location);
+  async readFile(relativePath: string): Promise<File> {
+    const buffer = BinaryUtil.binaryArrayToBuffer(await this.readBinaryArray(relativePath));
+    return new File([buffer], path.basename(relativePath));
   }
 }

package/src/function.ts

@@ -17,8 +17,8 @@ const pending = new Set<Function>([]);
 
 /**
  * Initialize the meta data for a function/class
- * @param fn Class
- * @param `file` Filename
+ * @param input Class or function to register
+ * @param [module, relativePath] File location
  * @param `hash` Hash of class contents
  * @param `line` Line number in source
  * @param `methods` Methods and their hashes
@@ -26,48 +26,44 @@ const pending = new Set<Function>([]);
  * @private
  */
 export function registerFunction(
-  fn: Function, [pkg, pth]: [string, string], tag: FunctionMetadataTag,
+  input: Function, [module, relativePath]: [string, string], tag: FunctionMetadataTag,
   methods?: Record<string, FunctionMetadataTag>, abstract?: boolean,
 ): void {
-  const modulePath = ManifestModuleUtil.withoutSourceExtension(pth);
+  const modulePath = ManifestModuleUtil.withoutSourceExtension(relativePath);
 
   const metadata: FunctionMetadata = {
-    id: (fn.name ? `${pkg}:${modulePath}#${fn.name}` : `${pkg}:${modulePath}`),
-    import: `${pkg}/${pth}`,
-    module: pkg,
+    id: (input.name ? `${module}:${modulePath}#${input.name}` : `${module}:${modulePath}`),
+    import: `${module}/${relativePath}`,
+    module,
     modulePath,
     ...tag,
     methods,
     abstract,
     class: methods !== undefined
   };
-  pending.add(fn);
-  Object.defineProperties(fn, { Ⲑid: { value: metadata.id }, [MetadataSymbol]: { value: metadata } });
+  pending.add(input);
+  Object.defineProperties(input, { Ⲑid: { value: metadata.id }, [MetadataSymbol]: { value: metadata } });
 }
 
 /**
  * Flush all pending function registers
  */
 export function flushPendingFunctions(): Function[] {
-  const fns = [...pending];
+  const functions = [...pending];
   pending.clear();
-  return fns;
+  return functions;
 }
 
 /**
  * Read metadata
  */
-export function describeFunction(fn: Function): FunctionMetadata;
-export function describeFunction(fn?: Function): FunctionMetadata | undefined {
-  const _fn: (Function & { [MetadataSymbol]?: FunctionMetadata }) | undefined = fn;
-  return _fn?.[MetadataSymbol];
+export function describeFunction(input: Function): FunctionMetadata;
+export function describeFunction(input?: Function): FunctionMetadata | undefined {
+  const resolved: (Function & { [MetadataSymbol]?: FunctionMetadata }) | undefined = input;
+  return resolved?.[MetadataSymbol];
 }
 
 const foreignTypeRegistry = new Map<string, Function>();
 export function foreignType(id: string): Function {
-  if (!foreignTypeRegistry.has(id)) {
-    const type = class { static Ⲑid = id; };
-    foreignTypeRegistry.set(id, type);
-  }
-  return foreignTypeRegistry.get(id)!;
+  return foreignTypeRegistry.getOrInsert(id, class { static Ⲑid = id; });
 }

package/src/global.d.ts

@@ -22,6 +22,16 @@ declare global {
    */
   interface File { }
 
+  /**
+   * @concrete node:stream/web#ReadableStream
+   */
+  interface ReadableStream { }
+
+  /**
+   * @concrete node:buffer#Buffer
+   */
+  interface Buffer { }
+
   namespace NodeJS {
     /**
      * @concrete node:stream#Readable
@@ -30,9 +40,28 @@ declare global {
   }
 }
 
+declare module 'buffer' {
+  /**
+   * @concrete node:buffer#Blob
+   */
+  interface Blob { }
+
+  /**
+   * @concrete node:buffer#File
+   */
+  interface File { }
+}
+
 declare module 'stream' {
   /**
    * @concrete node:stream#Readable
    */
   interface Readable { }
+}
+
+declare module 'stream/web' {
+  /**
+   * @concrete node:stream/web#ReadableStream
+   */
+  interface ReadableStream { }
 }