@travetto/runtime 5.0.0-rc.2 → 5.0.0-rc.4

package/README.md

@@ -14,19 +14,61 @@ yarn add @travetto/runtime
 ```
 
 Runtime is the foundation of all [Travetto](https://travetto.dev) applications.  It is intended to be a minimal application set, as well as support for commonly shared functionality. It has support for the following key areas:
-   *  Environment Support
    *  Runtime Context
+   *  Environment Support
+   *  Standard Error Support
    *  Console Management
    *  Resource Access
-   *  Standard Error Support
    *  Common Utilities
    *  Time Utilities
    *  Process Execution
    *  Shutdown Management
    *  Path behavior
 
+## Runtime Context
+While running any code within the framework, there are common patterns/goals for interacting with the underlying code repository.  These include:
+   *  Determining attributes of the running environment (e.g., name, debug information, production flags)
+   *  Resolving paths within the workspace (e.g. standard, tooling, resourcing, modules)
+
+**Code: Runtime Shape**
+```typescript
+class $Runtime {
+  constructor(idx: ManifestIndex, resourceOverrides?: Record<string, string>);
+  /** Get env name, with support for the default env */
+  get envName(): string | undefined;
+  /** Are we in development mode */
+  get production(): boolean;
+  /** Is the app in dynamic mode? */
+  get dynamic(): boolean;
+  /** Get debug value */
+  get debug(): false | string;
+  /** Manifest main */
+  get main(): ManifestContext['main'];
+  /** Manifest workspace */
+  get workspace(): ManifestContext['workspace'];
+  /** Are we running from a mono-root? */
+  get monoRoot(): boolean;
+  /** Main source path */
+  get mainSourcePath(): string;
+  /** Produce a workspace relative path */
+  workspaceRelative(...rel: string[]): string;
+  /** Strip off the workspace path from a file */
+  stripWorkspacePath(full: string): string;
+  /** Produce a workspace path for tooling, with '@' being replaced by node_module/name folder */
+  toolPath(...rel: string[]): string;
+  /** Resolve single module path */
+  modulePath(modulePath: string): string;
+  /** Resolve resource paths */
+  resourcePaths(paths: string[] = []): string[];
+  /** Get source for function */
+  getSourceFile(fn: Function): string;
+  /** Get import for function */
+  getImport(fn: Function): string;
+}
+```
+
 ## Environment Support
-The functionality we support for testing and retrieving environment information for known environment variables. They can be accessed directly on the [Env](https://github.com/travetto/travetto/tree/main/module/runtime/src/env.ts#L109) object, and will return a scoped [EnvProp](https://github.com/travetto/travetto/tree/main/module/runtime/src/env.ts#L4), that is compatible with the property definition.  E.g. only showing boolean related fields when the underlying flag supports `true` or `false`
+The functionality we support for testing and retrieving environment information for known environment variables. They can be accessed directly on the [Env](https://github.com/travetto/travetto/tree/main/module/runtime/src/env.ts#L108) object, and will return a scoped [EnvProp](https://github.com/travetto/travetto/tree/main/module/runtime/src/env.ts#L4), that is compatible with the property definition.  E.g. only showing boolean related fields when the underlying flag supports `true` or `false`
 
 **Code: Base Known Environment Flags**
 ```typescript
@@ -78,7 +120,12 @@ interface TravettoEnv {
     /**
      * trvc log level
      */
-    TRV_BUILD: 'none' | 'info' | 'debug' | 'error' | 'warn'
+    TRV_BUILD: 'none' | 'info' | 'debug' | 'error' | 'warn',
+    /**
+     * Should break on first line of a method when using the @DebugBreak decorator
+     * @default false
+     */
+    TRV_DEBUG_BREAK: boolean;
   }
 ```
 
@@ -114,13 +161,6 @@ export class EnvProp<T> {
 }
 ```
 
-## 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#L13) 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#L109)'s `TRV_RESOURCES` information on where to attempt to find a requested resource.
-
 ## 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#L13) (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). 
 
@@ -146,7 +186,7 @@ The supported operations are:
 
 **Note**: All other console methods are excluded, specifically `trace`, `inspect`, `dir`, `time`/`timeEnd`
 
-## How Logging is Instrumented
+### How Logging is Instrumented
 All of the logging instrumentation occurs at transpilation time.  All `console.*` methods are replaced with a call to a globally defined variable that delegates to the [ConsoleManager](https://github.com/travetto/travetto/tree/main/module/runtime/src/console.ts#L35).  This module, hooks into the [ConsoleManager](https://github.com/travetto/travetto/tree/main/module/runtime/src/console.ts#L35) and receives all logging events from all files compiled by the [Travetto](https://travetto.dev). 
 
 A sample of the instrumentation would be:
@@ -185,7 +225,7 @@ function work() {
 }
 ```
 
-### Filtering Debug
+#### Filtering Debug
 The `debug` messages can be filtered using the patterns from the [debug](https://www.npmjs.com/package/debug).  You can specify wild cards to only `DEBUG` specific modules, folders or files.  You can specify multiple, and you can also add negations to exclude specific packages.
 
 **Terminal: Sample environment flags**
@@ -207,6 +247,13 @@ Additionally, the logging framework will merge [debug](https://www.npmjs.com/pac
 $ 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#L13) 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#L108)'s `TRV_RESOURCES` information on where to attempt to find a requested resource.
+
 ## Common Utilities
 Common utilities used throughout the framework. Currently [Util](https://github.com/travetto/travetto/tree/main/module/runtime/src/util.ts#L17) includes:
    *  `uuid(len: number)` generates a simple uuid for use within the application.
@@ -268,7 +315,7 @@ export class TimeUtil {
 ```
 
 ## Process Execution
-[ExecUtil](https://github.com/travetto/travetto/tree/main/module/runtime/src/exec.ts#L39) exposes `getResult` as a means to wrap [child_process](https://nodejs.org/api/child_process.html)'s process object.  This wrapper allows for a promise-based resolution of the subprocess with the ability to capture the stderr/stdout.
+[ExecUtil](https://github.com/travetto/travetto/tree/main/module/runtime/src/exec.ts#L41) exposes `getResult` as a means to wrap [child_process](https://nodejs.org/api/child_process.html)'s process object.  This wrapper allows for a promise-based resolution of the subprocess with the ability to capture the stderr/stdout.
 
 A simple example would be:
 

package/__index__.ts

@@ -2,6 +2,7 @@
 /// <reference path="./src/global.d.ts" />
 export * from './src/console';
 export * from './src/context';
+export * from './src/debug';
 export * from './src/error';
 export * from './src/exec';
 export * from './src/env';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/runtime",
-  "version": "5.0.0-rc.2",
+  "version": "5.0.0-rc.4",
   "description": "Runtime for travetto applications.",
   "keywords": [
     "console-manager",
@@ -24,14 +24,17 @@
     "url": "https://github.com/travetto/travetto.git",
     "directory": "module/runtime"
   },
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "dependencies": {
     "@travetto/manifest": "^5.0.0-rc.2",
     "@types/debug": "^4.1.12",
-    "@types/node": "^20.14.10",
+    "@types/node": "^22.1.0",
     "debug": "^4.3.5"
   },
   "peerDependencies": {
-    "@travetto/transformer": "^5.0.0-rc.2"
+    "@travetto/transformer": "^5.0.0-rc.3"
   },
   "peerDependenciesMeta": {
     "@travetto/transformer": {

package/src/context.ts

@@ -1,100 +1,106 @@
 import path from 'node:path';
 
-import { type ManifestContext } from '@travetto/manifest';
+import type { ManifestIndex, ManifestContext } from '@travetto/manifest';
 
 import { Env } from './env';
 import { RuntimeIndex } from './manifest-index';
 import { describeFunction } from './function';
 
-const prod = (): boolean => process.env.NODE_ENV === 'production';
-
-const OVERRIDES = Env.TRV_RESOURCE_OVERRIDES.object ?? {};
-
-const MODULE_ALIASES: Record<string, string> = {
-  '@': RuntimeIndex.manifest.main.name,
-  '@@': RuntimeIndex.manifest.workspace.path,
-};
-
-
 /** Constrained version of {@type ManifestContext} */
-export const Runtime = {
+class $Runtime {
+
+  #idx: ManifestIndex;
+  #moduleAliases: Record<string, string>;
+  #resourceOverrides?: Record<string, string>;
+
+  constructor(idx: ManifestIndex, resourceOverrides?: Record<string, string>) {
+    this.#idx = idx;
+    this.#moduleAliases = {
+      '@': idx.manifest.main.name,
+      '@@': idx.manifest.workspace.path,
+    };
+    this.#resourceOverrides = resourceOverrides;
+  }
+
   /** Get env name, with support for the default env */
-  get name(): string | undefined {
-    return Env.TRV_ENV.val || (!prod() ? RuntimeIndex.manifest.workspace.defaultEnv : undefined);
-  },
+  get envName(): string | undefined {
+    return Env.TRV_ENV.val || (!this.production ? this.#idx.manifest.workspace.defaultEnv : undefined);
+  }
 
   /** Are we in development mode */
   get production(): boolean {
-    return prod();
-  },
+    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 && prod()) || Env.DEBUG.isFalse ? false : val;
-  },
+    return (!val && this.production) || Env.DEBUG.isFalse ? false : val;
+  }
 
   /** Manifest main */
   get main(): ManifestContext['main'] {
-    return RuntimeIndex.manifest.main;
-  },
+    return this.#idx.manifest.main;
+  }
 
   /** Manifest workspace */
   get workspace(): ManifestContext['workspace'] {
-    return RuntimeIndex.manifest.workspace;
-  },
+    return this.#idx.manifest.workspace;
+  }
 
   /** Are we running from a mono-root? */
   get monoRoot(): boolean {
-    return !!RuntimeIndex.manifest.workspace.mono && !RuntimeIndex.manifest.main.folder;
-  },
+    return !!this.workspace.mono && !this.main.folder;
+  }
 
   /** Main source path */
   get mainSourcePath(): string {
-    return RuntimeIndex.mainModule.sourcePath;
-  },
+    return this.#idx.mainModule.sourcePath;
+  }
 
   /** Produce a workspace relative path */
   workspaceRelative(...rel: string[]): string {
-    return path.resolve(RuntimeIndex.manifest.workspace.path, ...rel);
-  },
+    return path.resolve(this.workspace.path, ...rel);
+  }
 
   /** Strip off the workspace path from a file */
   stripWorkspacePath(full: string): string {
-    return full === RuntimeIndex.manifest.workspace.path ? '' : full.replace(`${RuntimeIndex.manifest.workspace.path}/`, '');
-  },
+    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', RuntimeIndex.manifest.main.name] : [x]);
-    return path.resolve(RuntimeIndex.manifest.workspace.path, RuntimeIndex.manifest.build.toolFolder, ...rel);
-  },
+    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] = (OVERRIDES[modulePath] ?? modulePath)
-      .replace(/^([^#]*)(#|$)/g, (_, v, r) => `${MODULE_ALIASES[v] ?? v}${r}`)
+    const [base, sub] = (this.#resourceOverrides?.[modulePath] ?? modulePath)
+      .replace(/^([^#]*)(#|$)/g, (_, v, r) => `${this.#moduleAliases[v] ?? v}${r}`)
       .split('#');
-    return path.resolve(RuntimeIndex.getModule(base)?.sourcePath ?? base, sub ?? '.');
-  },
-
-  /** Resolve module paths */
-  modulePaths(paths: string[]): string[] {
-    return [...new Set(paths.map(this.modulePath))];
-  },
+    return path.resolve(this.#idx.getModule(base)?.sourcePath ?? base, sub ?? '.');
+  }
 
   /** Resolve resource paths */
   resourcePaths(paths: string[] = []): string[] {
-    return this.modulePaths([...paths, ...Env.TRV_RESOURCES.list ?? [], '@#resources', '@@#resources']);
-  },
+    return [...paths, ...Env.TRV_RESOURCES.list ?? [], '@#resources', '@@#resources'].map(v => this.modulePath(v));
+  }
 
   /** Get source for function */
-  getSource(fn: Function): string {
-    return RuntimeIndex.getFromImport(describeFunction(fn).import)?.sourceFile!;
+  getSourceFile(fn: Function): string {
+    return this.#idx.getFromImport(this.getImport(fn))?.sourceFile!;
   }
-};
+
+  /** Get import for function */
+  getImport(fn: Function): string {
+    return describeFunction(fn).import;
+  }
+}
+
+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/file-loader.ts

@@ -13,7 +13,7 @@ export class FileLoader {
   #searchPaths: readonly string[];
 
   constructor(paths: string[]) {
-    this.#searchPaths = paths;
+    this.#searchPaths = [...new Set(paths)]; // Dedupe
   }
 
   /**

package/src/function.ts

@@ -1,14 +1,19 @@
-export type FunctionMetadataTag = { hash: number, lines: [number, number] };
+export type FunctionMetadataTag = { hash: number, lines: [start: number, end: number, bodyStart?: number] };
 export type FunctionMetadata = FunctionMetadataTag & {
   id: string;
   import: string;
+  module: string;
+  modulePath: string;
   methods?: Record<string, FunctionMetadataTag>;
   synthetic?: boolean;
+  class?: boolean;
   abstract?: boolean;
 };
 
 const METADATA = Symbol.for('@travetto/runtime:function-metadata');
 
+const pending = new Set<Function>([]);
+
 /**
  * Initialize the meta data for a function/class
  * @param fn Class
@@ -20,16 +25,28 @@ const METADATA = Symbol.for('@travetto/runtime:function-metadata');
  * @param `synthetic` Is this code generated at build time
  * @private
  */
-export function register(
-  fn: Function, module: [string, string], tag: FunctionMetadataTag,
+export function registerFunction(
+  fn: Function, [pkg, pth]: [string, string], tag: FunctionMetadataTag,
   methods?: Record<string, FunctionMetadataTag>, abstract?: boolean, synthetic?: boolean
 ): void {
-  let id = module.join(':');
-  if (fn.name) {
-    id = `${id}￮${fn.name}`;
-  }
-  const value = { id, import: module.join('/'), ...tag, methods, abstract, synthetic };
-  Object.defineProperties(fn, { Ⲑid: { value: id }, [METADATA]: { value } });
+  const metadata = {
+    id: fn.name ? `${pkg}:${pth}￮${fn.name}` : `${pkg}:${pth}`,
+    import: `${pkg}/${pth}`,
+    module: pkg,
+    modulePath: pth,
+    ...tag, methods, abstract, synthetic, class: abstract !== undefined
+  };
+  pending.add(fn);
+  Object.defineProperties(fn, { Ⲑid: { value: metadata.id }, [METADATA]: { value: metadata } });
+}
+
+/**
+ * Flush all pending function registers
+ */
+export function flushPendingFunctions(): Function[] {
+  const fns = [...pending];
+  pending.clear();
+  return fns;
 }
 
 /**

package/src/trv.d.ts

@@ -54,6 +54,11 @@ declare global {
     /**
      * trvc log level
      */
-    TRV_BUILD: 'none' | 'info' | 'debug' | 'error' | 'warn'
+    TRV_BUILD: 'none' | 'info' | 'debug' | 'error' | 'warn',
+    /**
+     * Should break on first line of a method when using the @DebugBreak decorator
+     * @default false
+     */
+    TRV_DEBUG_BREAK: boolean;
   }
 }

package/src/types.ts

@@ -5,8 +5,19 @@ export type ClassInstance<T = any> = T & {
   constructor: ConcreteClass<T> & { Ⲑid: string };
 };
 
+export type AnyMap = {
+  [key: string]: any
+};
+
+export type Primitive = number | bigint | boolean | string | Date;
+
+export type DeepPartial<T> = {
+  [P in keyof T]?: (T[P] extends (Primitive | undefined) ? (T[P] | undefined) :
+    (T[P] extends any[] ? (DeepPartial<T[P][number]> | null | undefined)[] : DeepPartial<T[P]>));
+};
+
 export const TypedObject: {
   keys<T = unknown, K extends keyof T = keyof T>(o: T): K[];
   fromEntries<K extends string | symbol, V>(items: ([K, V] | readonly [K, V])[]): Record<K, V>;
   entries<K extends Record<symbol | string, unknown>>(record: K): [keyof K, K[keyof K]][];
-} & ObjectConstructor = Object;
+} & ObjectConstructor = Object;

package/support/transformer.debug-method.ts

@@ -0,0 +1,41 @@
+import ts from 'typescript';
+
+import { TransformerState, OnMethod, CoreUtil } from '@travetto/transformer';
+
+const DebugⲐ = Symbol.for('@travetto/runtime:debug');
+
+/**
+ * Debug transformation state
+ */
+interface DebugState {
+  [DebugⲐ]?: ts.Expression;
+}
+
+/**
+ * Add debugger-optional statement to methods that should be debuggable
+ */
+export class DebugEntryTransformer {
+
+  @OnMethod('DebugBreak')
+  static debugOnEntry(state: TransformerState & DebugState, node: ts.MethodDeclaration): ts.MethodDeclaration {
+    if (!state[DebugⲐ]) {
+      const imp = state.importFile('@travetto/runtime/src/debug').ident;
+      state[DebugⲐ] = CoreUtil.createAccess(state.factory, imp, 'tryDebugger');
+    }
+
+    return state.factory.updateMethodDeclaration(node,
+      node.modifiers,
+      node.asteriskToken,
+      node.name,
+      node.questionToken,
+      node.typeParameters,
+      node.parameters,
+      node.type,
+      node.body ? state.factory.updateBlock(node.body, [
+        state.factory.createIfStatement(state[DebugⲐ]!,
+          state.factory.createExpressionStatement(state.factory.createIdentifier('debugger'))),
+        ...node.body.statements
+      ]) : node.body
+    );
+  }
+}

package/support/transformer.function-metadata.ts

@@ -15,6 +15,7 @@ const methods = Symbol.for(`${RUNTIME_MOD}:methods`);
 const cls = Symbol.for(`${RUNTIME_MOD}:class`);
 const fn = Symbol.for(`${RUNTIME_MOD}:function`);
 const registerImport = Symbol.for(`${RUNTIME_MOD}:registerImport`);
+const registerFn = 'registerFunction';
 
 interface MetadataInfo {
   [registerImport]?: Import;
@@ -32,6 +33,12 @@ export class RegisterTransformer {
     const hash = SystemUtil.naiveHash(node.getText());
     try {
       const range = CoreUtil.getRangeOf(state.source, node) ?? [0, 0];
+      if (ts.isMethodDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)) {
+        const bodyStart = CoreUtil.getRangeOf(state.source, node?.body?.statements[0])?.[0];
+        if (bodyStart) {
+          range.push(bodyStart);
+        }
+      }
       return { hash, lines: range };
     } catch (err) {
       return { hash, lines: [0, 0] };
@@ -80,7 +87,7 @@ export class RegisterTransformer {
     const name = node.name?.escapedText.toString() ?? '';
 
     const meta = state.factory.createCallExpression(
-      state.createAccess(state[registerImport].ident, 'register'),
+      state.createAccess(state[registerImport].ident, registerFn),
       [],
       [
         state.createIdentifier(name),
@@ -122,7 +129,7 @@ export class RegisterTransformer {
       state[registerImport] ??= state.importFile(REGISTER_IMPORT);
       const tag = this.#tag(state, node);
       const meta = state.factory.createCallExpression(
-        state.createAccess(state[registerImport].ident, 'register'),
+        state.createAccess(state[registerImport].ident, registerFn),
         [],
         [
           state.createIdentifier(node.name),