@travetto/runtime 5.0.0-rc.10

package/src/console.ts

@@ -0,0 +1,137 @@
+import util from 'node:util';
+import debug from 'debug';
+
+import { RuntimeIndex } from './manifest-index';
+
+export type ConsoleEvent = {
+  /** Time of event */
+  timestamp: Date;
+  /** The level of the console event */
+  level: 'info' | 'warn' | 'debug' | 'error';
+  /** The line number the console event was triggered from */
+  line: number;
+  /** The module name for the source file */
+  module: string;
+  /** The module path  for the source file*/
+  modulePath: string;
+  /** The computed scope for the console. statement.  */
+  scope?: string;
+  /** Arguments passed to the console call*/
+  args: unknown[];
+};
+
+export interface ConsoleListener {
+  log(ev: ConsoleEvent): void;
+}
+
+const DEBUG_OG = { formatArgs: debug.formatArgs, log: debug.log };
+
+/**
+ * Provides a general abstraction against the console.* methods to allow for easier capture and redirection.
+ *
+ * The transpiler will replace all console.* calls in the typescript files for the framework and those provided by the user.
+ * Any console.log statements elsewhere will not be affected.
+ */
+class $ConsoleManager implements ConsoleListener {
+
+  /**
+   * The current listener
+   */
+  #listener: ConsoleListener;
+
+  /**
+   * List of logging filters
+   */
+  #filters: Partial<Record<ConsoleEvent['level'], (x: ConsoleEvent) => boolean>> = {};
+
+  constructor(listener: ConsoleListener) {
+    this.set(listener);
+    this.enhanceDebug(true);
+    this.debug(false);
+    util.inspect.defaultOptions.depth = Math.max(util.inspect.defaultOptions.depth ?? 0, 4);
+  }
+
+  /**
+   * Add exclusion
+   * @private
+   */
+  filter(level: ConsoleEvent['level'], filter?: boolean | ((ctx: ConsoleEvent) => boolean)): void {
+    if (filter !== undefined) {
+      if (typeof filter === 'boolean') {
+        const v = filter;
+        filter = (): boolean => v;
+      }
+      this.#filters[level] = filter;
+    } else {
+      delete this.#filters[level];
+    }
+  }
+
+  /**
+   * 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);
+        args.push(debug.humanize(this.diff));
+      };
+      debug.log = (modulePath, ...args: string[]): void => this.log({
+        level: 'debug', module: '@npm:debug', modulePath,
+        args: [util.format(...args)], line: 0, timestamp: new Date()
+      });
+    } else {
+      debug.formatArgs = DEBUG_OG.formatArgs;
+      debug.log = DEBUG_OG.log;
+    }
+  }
+
+  /**
+   * Set logging debug level
+   */
+  debug(value: false | string): void {
+    if (value !== false) {
+      const active = RuntimeIndex.getModuleList('workspace', value);
+      active.add('@npm:debug');
+      this.filter('debug', ctx => active.has(ctx.module));
+    } else {
+      this.filter('debug', () => false);
+    }
+  }
+
+  /**
+   * Handle direct call in lieu of the console.* commands
+   */
+  log(ev: ConsoleEvent & { import?: [string, string] }): void {
+    const outEv = {
+      ...ev,
+      timestamp: new Date(),
+      module: ev.module ?? ev.import?.[0],
+      modulePath: ev.modulePath ?? ev.import?.[1]
+    };
+
+    if (this.#filters[outEv.level] && !this.#filters[outEv.level]!(outEv)) {
+      return; // Do nothing
+    } else {
+      return this.#listener.log(outEv);
+    }
+  }
+
+  /**
+   * Set a new console listener
+   */
+  set(cons: ConsoleListener): void {
+    this.#listener = cons;
+  }
+
+  /**
+   * Get the listener
+   */
+  get(): ConsoleListener {
+    return this.#listener;
+  }
+}
+
+export const ConsoleManager = new $ConsoleManager({ log(ev): void { console![ev.level](...ev.args); } });
+export const log = ConsoleManager.log.bind(ConsoleManager);

package/src/context.ts

@@ -0,0 +1,122 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+import { type ManifestIndex, type ManifestContext, ManifestModuleUtil } from '@travetto/manifest';
+
+import { Env } from './env';
+import { RuntimeIndex } from './manifest-index';
+import { describeFunction } from './function';
+
+/** Constrained version of {@type ManifestContext} */
+class $Runtime {
+
+  #idx: ManifestIndex;
+  #resourceOverrides?: Record<string, string>;
+
+  constructor(idx: ManifestIndex, resourceOverrides?: Record<string, string>) {
+    this.#idx = idx;
+    this.#resourceOverrides = resourceOverrides;
+  }
+
+  get #moduleAliases(): Record<string, string> {
+    return {
+      '@': this.#idx.mainModule.sourcePath,
+      '@@': this.#idx.manifest.workspace.path,
+    };
+  }
+
+  /** Get env name, with support for the default env */
+  get env(): string | undefined {
+    return Env.TRV_ENV.val || (!this.production ? this.#idx.manifest.workspace.defaultEnv : undefined);
+  }
+
+  /** Are we in development mode */
+  get production(): boolean {
+    return process.env.NODE_ENV === 'production';
+  }
+
+  /** Is the app in dynamic mode? */
+  get dynamic(): boolean {
+    return Env.TRV_DYNAMIC.isTrue;
+  }
+
+  /** Get debug value */
+  get debug(): false | string {
+    const val = Env.DEBUG.val ?? '';
+    return (!val && this.production) || Env.DEBUG.isFalse ? false : val;
+  }
+
+  /** Manifest main */
+  get main(): ManifestContext['main'] {
+    return this.#idx.manifest.main;
+  }
+
+  /** Manifest workspace */
+  get workspace(): ManifestContext['workspace'] {
+    return this.#idx.manifest.workspace;
+  }
+
+  /** Are we running from a mono-root? */
+  get monoRoot(): boolean {
+    return !!this.workspace.mono && !this.main.folder;
+  }
+
+  /** Main source path */
+  get mainSourcePath(): string {
+    return this.#idx.mainModule.sourcePath;
+  }
+
+  /** Produce a workspace relative path */
+  workspaceRelative(...rel: string[]): string {
+    return path.resolve(this.workspace.path, ...rel);
+  }
+
+  /** Strip off the workspace path from a file */
+  stripWorkspacePath(full: string): string {
+    return full === this.workspace.path ? '' : full.replace(`${this.workspace.path}/`, '');
+  }
+
+  /** Produce a workspace path for tooling, with '@' being replaced by node_module/name folder */
+  toolPath(...rel: string[]): string {
+    rel = rel.flatMap(x => x === '@' ? ['node_modules', this.#idx.manifest.main.name] : [x]);
+    return path.resolve(this.workspace.path, this.#idx.manifest.build.toolFolder, ...rel);
+  }
+
+  /** Resolve single module path */
+  modulePath(modulePath: string): string {
+    const [base, sub] = (this.#resourceOverrides?.[modulePath] ?? modulePath)
+      .replace(/^([^#]*)(#|$)/g, (_, v, r) => `${this.#moduleAliases[v] ?? v}${r}`)
+      .split('#');
+    return path.resolve(this.#idx.getModule(base)?.sourcePath ?? base, sub ?? '.');
+  }
+
+  /** Resolve resource paths */
+  resourcePaths(paths: string[] = []): string[] {
+    return [...new Set([...paths, ...Env.TRV_RESOURCES.list ?? [], '@#resources', '@@#resources'].map(v => this.modulePath(v)))];
+  }
+
+  /** Get source for function */
+  getSourceFile(fn: Function): string {
+    return this.#idx.getFromImport(this.getImport(fn))?.sourceFile!;
+  }
+
+  /** Get import for function */
+  getImport(fn: Function): string {
+    return describeFunction(fn).import;
+  }
+
+  /** Import from a given path */
+  importFrom<T = unknown>(imp?: string): Promise<T> {
+    const file = path.resolve(this.#idx.mainModule.sourcePath, imp!);
+    if (existsSync(file)) {
+      imp = this.#idx.getFromSource(file)?.import;
+    }
+    if (!imp) {
+      throw new Error(`Unable to find ${imp}, not in the manifest`);
+    }
+    imp = ManifestModuleUtil.withOutputExtension(imp);
+    return import(imp);
+  }
+}
+
+export const Runtime = new $Runtime(RuntimeIndex, Env.TRV_RESOURCE_OVERRIDES.object);

package/src/debug.ts

@@ -0,0 +1,18 @@
+import { Env } from './env';
+import { ClassInstance } from './types';
+
+/**
+ * The `@DebugBreak` indicates that a function inserts an optional debugger keyword to stop on entry
+ * @augments `@travetto/runtime:DebugBreak`
+ */
+export function DebugBreak(): MethodDecorator {
+  return (inst: ClassInstance, prop: string | symbol, descriptor: PropertyDescriptor) => descriptor;
+
+}
+
+/**
+ * Determine if we should invoke the debugger
+ */
+export function tryDebugger(): boolean {
+  return Env.TRV_DEBUG_BREAK.isTrue;
+}

package/src/env.ts

@@ -0,0 +1,109 @@
+import { castKey, castTo } from './types';
+
+const IS_TRUE = /^(true|yes|on|1)$/i;
+const IS_FALSE = /^(false|no|off|0)$/i;
+
+export class EnvProp<T> {
+  constructor(public readonly key: string) { }
+
+  /** Set value according to prop type */
+  set(val: T | undefined | null): void {
+    if (val === undefined || val === null) {
+      delete process.env[this.key];
+    } else {
+      process.env[this.key] = Array.isArray(val) ? `${val.join(',')}` : `${val}`;
+    }
+  }
+
+  /** Remove value */
+  clear(): void {
+    this.set(null);
+  }
+
+  /** Export value */
+  export(val: T | undefined): Record<string, string> {
+    let out: string;
+    if (val === undefined || val === '' || val === null) {
+      out = '';
+    } else if (Array.isArray(val)) {
+      out = val.join(',');
+    } else if (typeof val === 'object') {
+      out = Object.entries(val).map(([k, v]) => `${k}=${v}`).join(',');
+    } else {
+      out = `${val}`;
+    }
+    return { [this.key]: out };
+  }
+
+  /** Read value as string */
+  get val(): string | undefined { return process.env[this.key] || undefined; }
+
+  /** Read value as list */
+  get list(): string[] | undefined {
+    const val = this.val;
+    return (val === undefined || val === '') ?
+      undefined : val.split(/[, ]+/g).map(x => x.trim()).filter(x => !!x);
+  }
+
+  /** Read value as object */
+  get object(): Record<string, string> | undefined {
+    const items = this.list;
+    return items ? Object.fromEntries(items.map(x => x.split(/[:=]/g))) : undefined;
+  }
+
+  /** Add values to list */
+  add(...items: string[]): void {
+    process.env[this.key] = [... new Set([...this.list ?? [], ...items])].join(',');
+  }
+
+  /** Read value as int  */
+  get int(): number | undefined {
+    const vi = parseInt(this.val ?? '', 10);
+    return Number.isNaN(vi) ? undefined : vi;
+  }
+
+  /** Read value as boolean */
+  get bool(): boolean | undefined {
+    const val = this.val;
+    return (val === undefined || val === '') ? undefined : IS_TRUE.test(val);
+  }
+
+  /** Determine if the underlying value is truthy */
+  get isTrue(): boolean {
+    return IS_TRUE.test(this.val ?? '');
+  }
+
+  /** Determine if the underlying value is falsy */
+  get isFalse(): boolean {
+    return IS_FALSE.test(this.val ?? '');
+  }
+
+  /** Determine if the underlying value is set */
+  get isSet(): boolean {
+    const val = this.val;
+    return val !== undefined && val !== '';
+  }
+}
+
+type AllType = {
+  [K in keyof TravettoEnv]: Pick<EnvProp<TravettoEnv[K]>, 'key' | 'export' | 'val' | 'set' | 'clear' | 'isSet' |
+    (TravettoEnv[K] extends unknown[] ? 'list' | 'add' : never) |
+    (Extract<TravettoEnv[K], object> extends never ? never : 'object') |
+    (Extract<TravettoEnv[K], number> extends never ? never : 'int') |
+    (Extract<TravettoEnv[K], boolean> extends never ? never : 'bool' | 'isTrue' | 'isFalse')
+  >
+};
+
+function delegate<T extends object>(base: T): AllType & T {
+  return new Proxy(castTo(base), {
+    get(target, prop): unknown {
+      return typeof prop !== 'string' ? undefined :
+        (prop in base ? base[castKey(prop)] :
+          target[castKey<typeof target>(prop)] ??= castTo(new EnvProp(prop))
+        );
+    }
+  });
+}
+
+/** Basic utils for reading known environment variables */
+export const Env = delegate({});

package/src/error.ts

@@ -0,0 +1,66 @@
+import { castTo } from './types';
+
+export type ErrorCategory =
+  'general' |
+  'notfound' |
+  'data' |
+  'permissions' |
+  'authentication' |
+  'timeout' |
+  'unavailable';
+
+/**
+ * Framework error class, with the aim of being extensible
+ */
+export class AppError<T = unknown> extends Error {
+
+  /** Convert from JSON object */
+  static fromJSON(e: unknown): AppError | undefined {
+    if (!!e && typeof e === 'object' &&
+      ('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')
+    ) {
+      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;
+    }
+  }
+
+  type: string;
+  at = new Date();
+  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
+
+  ) {
+    super(message);
+    this.type = this.constructor.name;
+    this.details = details!;
+  }
+
+  /**
+   * The format of the JSON output
+   */
+  toJSON(): { message: string, category: string, type: string, at: string, details?: Record<string, unknown> } {
+    return {
+      message: this.message,
+      category: this.category,
+      type: this.type,
+      at: this.at.toISOString(),
+      details: castTo(this.details),
+    };
+  }
+}

package/src/exec.ts

@@ -0,0 +1,156 @@
+import { ChildProcess } from 'node:child_process';
+import { Readable } from 'node:stream';
+import { createInterface } from 'node:readline/promises';
+import { castTo } from './types';
+
+const MINUTE = (1000 * 60);
+
+const RESULT = Symbol.for('@travetto/runtime:exec-result');
+
+interface ExecutionBaseResult {
+  /**
+   * Exit code
+   */
+  code: number;
+  /**
+   * Execution result message, should be inline with code
+   */
+  message?: string;
+  /**
+   * Whether or not the execution completed successfully
+   */
+  valid: boolean;
+}
+
+/**
+ * Result of an execution
+ */
+export interface ExecutionResult<T extends string | Buffer = string | Buffer> extends ExecutionBaseResult {
+  /**
+   * Stdout
+   */
+  stdout: T;
+  /**
+   * Stderr
+   */
+  stderr: T;
+}
+
+/**
+ * Standard utilities for managing executions
+ */
+export class ExecUtil {
+
+  static RESTART_EXIT_CODE = 200;
+
+  /**
+   * Run with automatic restart support
+   * @param run The factory to produce the next running process
+   * @param maxRetriesPerMinute The number of times to allow a retry within a minute
+   */
+  static async withRestart(run: () => ChildProcess, maxRetriesPerMinute?: number): Promise<ExecutionResult> {
+    const maxRetries = maxRetriesPerMinute ?? 5;
+    const restarts: number[] = [];
+
+    for (; ;) {
+      const proc = run();
+
+      const toKill = (): void => { proc.kill('SIGKILL'); };
+      const toMessage = (v: unknown): void => { proc.send?.(v!); };
+
+      // Proxy kill requests
+      process.on('message', toMessage);
+      process.on('SIGINT', toKill);
+      proc.on('message', v => process.send?.(v));
+
+      const result = await this.getResult(proc, { catch: true });
+      if (result.code !== this.RESTART_EXIT_CODE) {
+        return result;
+      } else {
+        process.off('SIGINT', toKill);
+        process.off('message', toMessage);
+        restarts.unshift(Date.now());
+        if (restarts.length === maxRetries) {
+          if ((restarts[0] - restarts[maxRetries - 1]) <= MINUTE) {
+            console.error(`Bailing, due to ${maxRetries} restarts in under a minute`);
+            return result;
+          }
+          restarts.pop(); // Keep list short
+        }
+        console.error('Restarting...', { pid: process.pid });
+      }
+    }
+  }
+
+  /**
+   * Take a child process, and some additional options, and produce a promise that
+   * represents the entire execution.  On successful completion the promise will resolve, and
+   * on failed completion the promise will reject.
+   *
+   * @param proc The process to enhance
+   * @param options The options to use to enhance the process
+   */
+  static getResult(proc: ChildProcess): Promise<ExecutionResult<string>>;
+  static getResult(proc: ChildProcess, options: { catch?: boolean, binary?: false }): Promise<ExecutionResult<string>>;
+  static getResult(proc: ChildProcess, options: { catch?: boolean, binary: true }): Promise<ExecutionResult<Buffer>>;
+  static getResult<T extends string | Buffer>(proc: ChildProcess, options: { catch?: boolean, binary?: boolean } = {}): Promise<ExecutionResult<T>> {
+    const _proc: ChildProcess & { [RESULT]?: Promise<ExecutionResult> } = proc;
+    const res = _proc[RESULT] ??= new Promise<ExecutionResult>(resolve => {
+      const stdout: Buffer[] = [];
+      const stderr: Buffer[] = [];
+      let done = false;
+      const finish = (result: ExecutionBaseResult): void => {
+        if (done) {
+          return;
+        }
+        done = true;
+
+        const buffers = {
+          stdout: Buffer.concat(stdout),
+          stderr: Buffer.concat(stderr),
+        };
+
+        const final = {
+          stdout: options.binary ? buffers.stdout : buffers.stdout.toString('utf8'),
+          stderr: options.binary ? buffers.stderr : buffers.stderr.toString('utf8'),
+          ...result
+        };
+
+        resolve(!final.valid ?
+          { ...final, message: `${final.message || final.stderr || final.stdout || 'failed'}` } :
+          final
+        );
+      };
+
+      proc.stdout?.on('data', (d: string | Buffer) => stdout.push(Buffer.from(d)));
+      proc.stderr?.on('data', (d: string | Buffer) => stderr.push(Buffer.from(d)));
+
+      proc.on('error', (err: Error) =>
+        finish({ code: 1, message: err.message, valid: false }));
+
+      proc.on('close', (code: number) =>
+        finish({ code, valid: code === null || code === 0 }));
+
+      if (proc.exitCode !== null) { // We are already done
+        finish({ code: proc.exitCode, valid: proc.exitCode === 0 });
+      }
+    });
+
+    return castTo(options.catch ? res : res.then(v => {
+      if (v.valid) {
+        return v;
+      } else {
+        throw new Error(v.message);
+      }
+    }));
+  }
+
+  /**
+   * 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);
+    }
+  }
+}

package/src/file-loader.ts

@@ -0,0 +1,59 @@
+import { createReadStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { AppError } from './error';
+
+/**
+ * File loader that will search for files across the provided search paths
+ */
+export class FileLoader {
+
+  #searchPaths: readonly string[];
+
+  constructor(paths: string[]) {
+    this.#searchPaths = [...new Set(paths)]; // Dedupe
+  }
+
+  /**
+   * The paths that will be searched on resolve
+   */
+  get searchPaths(): readonly string[] {
+    return this.#searchPaths;
+  }
+
+  /**
+   * Return the absolute path for the given relative path
+   * @param relativePath The path to resolve
+   */
+  async resolve(relativePath: string): Promise<string> {
+    for (const sub of this.searchPaths) {
+      const resolved = path.join(sub, relativePath);
+      if (await fs.stat(resolved).catch(() => false)) {
+        return resolved;
+      }
+    }
+    throw new AppError(`Unable to find: ${relativePath}, searched=${this.searchPaths.join(',')}`, 'notfound');
+  }
+
+  /**
+   * Read a file, 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> {
+    const file = await this.resolve(relativePath);
+    return fs.readFile(file, binary ? undefined : 'utf8');
+  }
+
+  /**
+   * Read a file as a stream
+   * @param relativePath The path to read
+   */
+  async readStream(relativePath: string, binary = true): Promise<Readable> {
+    const file = await this.resolve(relativePath);
+    return createReadStream(file, { encoding: binary ? undefined : 'utf8' });
+  }
+}