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

package/README.md

@@ -61,12 +61,14 @@ class $Runtime {
   /** Resolve resource paths */
   resourcePaths(paths: string[] = []): string[];
   /** Get source for function */
-  getSource(fn: Function): string;
+  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
@@ -118,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;
   }
 ```
 
@@ -245,7 +252,7 @@ The primary access patterns for resources, is to directly request a file, and to
 
 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.
+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:

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.3",
+  "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

@@ -93,8 +93,13 @@ class $Runtime {
   }
 
   /** Get source for function */
-  getSource(fn: Function): string {
-    return this.#idx.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;
   }
 }
 

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/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),