@travetto/runtime 6.0.0 → 7.0.0-rc.0

package/README.md

@@ -168,7 +168,7 @@ 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#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 [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative api for Web Applications with support for the dependency injection.") 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 [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative support for creating Web Applications") module and HTTP status codes). 
 
 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
@@ -278,7 +278,7 @@ tpl`{{age:20}} {{name: 'bob'}}</>;
 ```
 
 ## Time Utilities
-[TimeUtil](https://github.com/travetto/travetto/tree/main/module/runtime/src/time.ts#L17) contains general helper methods, created to assist with time-based inputs via environment variables, command line interfaces, and other string-heavy based input.
+[TimeUtil](https://github.com/travetto/travetto/tree/main/module/runtime/src/time.ts#L19) contains general helper methods, created to assist with time-based inputs via environment variables, command line interfaces, and other string-heavy based input.
 
 **Code: Time Utilities**
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/runtime",
-  "version": "6.0.0",
+  "version": "7.0.0-rc.0",
   "description": "Runtime for travetto applications.",
   "keywords": [
     "console-manager",
@@ -25,12 +25,12 @@
     "directory": "module/runtime"
   },
   "dependencies": {
-    "@travetto/manifest": "^6.0.0",
+    "@travetto/manifest": "^7.0.0-rc.0",
     "@types/debug": "^4.1.12",
-    "debug": "^4.4.0"
+    "debug": "^4.4.3"
   },
   "peerDependencies": {
-    "@travetto/transformer": "^6.0.0"
+    "@travetto/transformer": "^7.0.0-rc.0"
   },
   "peerDependenciesMeta": {
     "@travetto/transformer": {

package/src/debug.ts

@@ -6,7 +6,7 @@ import { ClassInstance } from './types.ts';
  * @augments `@travetto/runtime:DebugBreak`
  */
 export function DebugBreak(): MethodDecorator {
-  return (inst: ClassInstance, prop: string | symbol, descriptor: PropertyDescriptor) => descriptor;
+  return (instance: ClassInstance, property: string | symbol, descriptor: PropertyDescriptor) => descriptor;
 
 }
 

package/src/exec.ts

@@ -51,28 +51,37 @@ export class ExecUtil {
    */
   static async withRestart(
     run: () => ChildProcess,
-    maxRetriesPerMinute?: number,
-    killSignal: 'SIGINT' | 'SIGTERM' = 'SIGINT'
+    config?: { maxRetriesPerMinute?: number, relayInterrupt?: boolean }
   ): Promise<ExecutionResult> {
-    const maxRetries = maxRetriesPerMinute ?? 5;
+    const maxRetries = config?.maxRetriesPerMinute ?? 5;
+    const relayInterrupt = config?.relayInterrupt ?? false;
+
     const restarts: number[] = [];
 
+    if (!relayInterrupt) {
+      process.removeAllListeners('SIGINT'); // Remove any existing listeners
+      process.on('SIGINT', () => { }); // Prevents SIGINT from killing parent process, the child will handle
+    }
+
     for (; ;) {
       const proc = run();
-
-      const toKill = (): void => { proc.kill(killSignal); };
+      const interrupt = (): void => { proc.kill('SIGINT'); };
       const toMessage = (v: unknown): void => { proc.send?.(v!); };
 
       // Proxy kill requests
       process.on('message', toMessage);
-      process.on('SIGINT', toKill);
+      if (relayInterrupt) {
+        process.on('SIGINT', interrupt);
+      }
       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);
+        if (relayInterrupt) {
+          process.off('SIGINT', interrupt);
+        }
         process.off('message', toMessage);
         restarts.unshift(Date.now());
         if (restarts.length === maxRetries) {

package/src/function.ts

@@ -6,7 +6,7 @@ export type FunctionMetadata = FunctionMetadataTag & {
   import: string;
   module: string;
   modulePath: string;
-  methods?: Record<string, FunctionMetadataTag>;
+  methods?: Record<string | symbol, FunctionMetadataTag>;
   class?: boolean;
   abstract?: boolean;
 };
@@ -36,7 +36,10 @@ export function registerFunction(
     import: `${pkg}/${pth}`,
     module: pkg,
     modulePath,
-    ...tag, methods, abstract, class: abstract !== undefined
+    ...tag,
+    methods,
+    abstract,
+    class: methods !== undefined
   };
   pending.add(fn);
   Object.defineProperties(fn, { Ⲑid: { value: metadata.id }, [MetadataSymbol]: { value: metadata } });

package/src/shutdown.ts

@@ -8,20 +8,37 @@ import { TimeUtil } from './time.ts';
 export class ShutdownManager {
 
   static #registered = false;
-  static #handlers: { name?: string, handler: () => (void | Promise<void>) }[] = [];
+  static #handlers: { scope?: string, handler: () => (void | Promise<void>) }[] = [];
+  static #pending: (PromiseWithResolvers<void> & { time: number }) | undefined;
+
+  static #ensureExitListeners(): void {
+    if (this.#registered) {
+      return;
+    }
+    this.#registered = true;
+    const cleanup = (signal: string): void => {
+      if (this.#pending && (Date.now() - this.#pending.time) > 500) {
+        console.warn('Shutdown already in progress, exiting immediately', { signal });
+        process.exit(0); // Quit immediately
+      }
+      this.gracefulShutdown(signal).then(() => process.exit(0));
+    };
+    if (process.stdout.isTTY) {
+      process.on('SIGINT', () => process.stdout.write('\n')); // Ensure we get a newline on ctrl-c
+    }
+    process.on('SIGUSR2', cleanup);
+    process.on('SIGTERM', cleanup);
+    process.on('SIGINT', cleanup);
+  }
 
   /**
    * On Shutdown requested
-   * @param name name to log for
+   * @param source The source of the shutdown request, for logging purposes
    * @param handler synchronous or asynchronous handler
    */
-  static onGracefulShutdown(handler: () => (void | Promise<void>), name?: string | { constructor: Function }): () => void {
-    if (!this.#registered) {
-      this.#registered = true;
-      const done = (): void => { this.gracefulShutdown(0); };
-      process.on('SIGUSR2', done).on('SIGTERM', done).on('SIGINT', done);
-    }
-    this.#handlers.push({ handler, name: typeof name === 'string' ? name : name?.constructor?.Ⲑid });
+  static onGracefulShutdown(handler: () => (void | Promise<void>), scope?: string): () => void {
+    this.#ensureExitListeners();
+    this.#handlers.push({ handler, scope });
     return () => {
       const idx = this.#handlers.findIndex(x => x.handler === handler);
       if (idx >= 0) {
@@ -33,37 +50,45 @@ export class ShutdownManager {
   /**
    * Wait for graceful shutdown to run and complete
    */
-  static async gracefulShutdown(code: number | string | undefined = process.exitCode): Promise<void> {
-    await Util.queueMacroTask(); // Force the event loop to wait one cycle
-
-    if (code !== undefined) {
-      process.exitCode = code;
+  static async gracefulShutdown(source: string): Promise<void> {
+    if (this.#pending) {
+      return this.#pending.promise;
+    } else if (!this.#handlers.length) {
+      return;
     }
 
-    if (this.#handlers.length) {
-      console.debug('Graceful shutdown: started');
+    this.#pending = { ...Promise.withResolvers<void>(), time: Date.now() };
 
-      const items = this.#handlers.splice(0, this.#handlers.length);
-      const handlers = Promise.all(items.map(async ({ name, handler }) => {
-        if (name) {
-          console.debug('Stopping', { name });
-        }
-        try {
-          return await handler();
-        } catch (err) {
-          console.error('Error shutting down', { name, err });
+    await Util.queueMacroTask(); // Force the event loop to wait one cycle
+
+    const timeout = TimeUtil.fromValue(Env.TRV_SHUTDOWN_WAIT.val) ?? 2000;
+    const items = this.#handlers.splice(0, this.#handlers.length);
+    console.debug('Graceful shutdown: started', { source, timeout, count: items.length });
+    const handlers = Promise.all(items.map(async ({ scope, handler }) => {
+      if (scope) {
+        console.debug('Stopping', { scope });
+      }
+      try {
+        await handler();
+        if (scope) {
+          console.debug('Stopped', { scope });
         }
-      }));
+      } catch (err) {
+        console.error('Error stopping', { err, scope });
+      }
+    }));
 
-      await Promise.race([
-        Util.nonBlockingTimeout(TimeUtil.fromValue(Env.TRV_SHUTDOWN_WAIT.val) ?? 2000), // Wait 2s and then force finish
-        handlers,
-      ]);
+    const winner = await Promise.race([
+      Util.nonBlockingTimeout(timeout).then(() => this), // Wait N seconds and then give up if not done
+      handlers,
+    ]);
 
+    if (winner !== this) {
       console.debug('Graceful shutdown: completed');
+    } else {
+      console.debug('Graceful shutdown: timed-out', { timeout });
     }
-    if (code !== undefined) {
-      process.exit();
-    }
+
+    this.#pending.resolve();
   }
 }

package/src/time.ts

@@ -14,16 +14,16 @@ const TIME_UNITS = {
 export type TimeSpan = `${number}${keyof typeof TIME_UNITS}`;
 export type TimeUnit = keyof typeof TIME_UNITS;
 
-export class TimeUtil {
+const TIME_PATTERN = new RegExp(`^(?<amount>-?[0-9.]+)(?<unit>${Object.keys(TIME_UNITS).join('|')})$`);
 
-  static #timePattern = new RegExp(`^(?<amount>-?[0-9.]+)(?<unit>${Object.keys(TIME_UNITS).join('|')})$`);
+export class TimeUtil {
 
   /**
    * Test to see if a string is valid for relative time
    * @param val
    */
   static isTimeSpan(val: string): val is TimeSpan {
-    return this.#timePattern.test(val);
+    return TIME_PATTERN.test(val);
   }
 
   /**
@@ -35,7 +35,7 @@ export class TimeUtil {
     if (amount instanceof Date) {
       return amount.getTime();
     } else if (typeof amount === 'string') {
-      const groups: { amount?: string, unit?: TimeUnit } = amount.match(this.#timePattern)?.groups ?? {};
+      const groups: { amount?: string, unit?: TimeUnit } = amount.match(TIME_PATTERN)?.groups ?? {};
       const amountStr = groups.amount ?? `${amount}`;
       unit = groups.unit ?? unit ?? 'ms';
       if (!TIME_UNITS[unit]) {

package/src/types.ts

@@ -24,12 +24,24 @@ export type DeepPartial<T> = {
     (T[P] extends Any[] ? (DeepPartial<T[P][number]> | null | undefined)[] : DeepPartial<T[P]>));
 };
 
+type ValidPrimitiveFields<T, Z = undefined> = {
+  [K in keyof T]:
+  (T[K] extends (Primitive | Z | undefined) ? K :
+    (T[K] extends (Function | undefined) ? never :
+      K))
+}[keyof T];
+
+export type RetainPrimitiveFields<T, Z = undefined> = Pick<T, ValidPrimitiveFields<T, Z>>;
+
 export const TypedObject: {
   keys<T = unknown, K extends keyof T = keyof T & string>(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;
 
+export const safeAssign = <T extends {}, U extends {}>(target: T, ...sources: U[]): T & U =>
+  Object.assign(target, ...sources);
+
 export function castTo<T>(input: unknown): T {
   // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
   return input as T;
@@ -53,6 +65,26 @@ export function toConcrete<T extends unknown>(): Class<T> {
   return arguments[0];
 }
 
+export function getAllEntries<V>(obj: Record<string | symbol, V>): [string | symbol, V][] {
+  return [
+    ...Object.keys(obj),
+    ...Object.getOwnPropertySymbols(obj)
+  ].map(k => [k, obj[k]] as const);
+}
+
+/**
+ * Find parent class for a given class object
+ */
+export function getParentClass(cls: Class): Class | undefined {
+  const parent: Class = Object.getPrototypeOf(cls);
+  return parent.name && parent !== Object ? parent : undefined;
+}
+
+/**
+ * Get the class from an instance or class
+ */
+export const getClass = <T = unknown>(x: ClassInstance | Class): Class<T> => 'Ⲑid' in x ? castTo(x) : asConstructable<T>(x).constructor;
+
 /**
  * Range of bytes, inclusive
  */

package/src/util.ts

@@ -195,4 +195,28 @@ export class Util {
       }
     });
   }
+
+  /**
+   * Retry an operation, with a custom conflict handler
+   * @param op The operation to retry
+   * @param isHandledConflict Function to determine if the error is a handled conflict
+   * @param maxTries Maximum number of retries
+   */
+  static async acquireWithRetry<T>(
+    op: () => T | Promise<T>,
+    prepareRetry: (err: unknown, count: number) => (void | undefined | boolean | Promise<(void | undefined | boolean)>),
+    maxTries = 5,
+  ): Promise<T> {
+    for (let i = 0; i < maxTries; i++) {
+      try {
+        return await op();
+      } catch (err) {
+        if (i === maxTries - 1 || await prepareRetry(err, i) === false) {
+          throw err; // Stop retrying if we reached max tries or prepareRetry returns false
+        }
+      }
+    }
+
+    throw new AppError(`Operation failed after ${maxTries} attempts`);
+  }
 }

package/src/watch.ts

@@ -17,7 +17,7 @@ export async function* watchCompiler(cfg?: { restartOnExit?: boolean, signal?: A
   });
 
   const ctrl = new AbortController();
-  const remove = ShutdownManager.onGracefulShutdown(async () => ctrl.abort(), watchCompiler);
+  const remove = ShutdownManager.onGracefulShutdown(async () => ctrl.abort());
 
   await client.waitForState(['compile-end', 'watch-start'], undefined, ctrl.signal);
 
@@ -33,6 +33,7 @@ export async function* watchCompiler(cfg?: { restartOnExit?: boolean, signal?: A
 
   if (cfg?.restartOnExit) {
     // We are done, request restart
-    await ShutdownManager.gracefulShutdown(ExecUtil.RESTART_EXIT_CODE);
+    await ShutdownManager.gracefulShutdown('@travetto/runtime:watchCompiler');
+    process.exit(ExecUtil.RESTART_EXIT_CODE);
   }
 }

package/support/transformer.console-log.ts

@@ -1,6 +1,9 @@
 import ts from 'typescript';
 
-import { TransformerState, OnCall, LiteralUtil, OnClass, AfterClass, OnMethod, AfterMethod, AfterFunction, OnFunction } from '@travetto/transformer';
+import {
+  TransformerState, OnCall, LiteralUtil, OnClass, AfterClass, OnMethod, AfterMethod,
+  AfterFunction, OnFunction, OnStaticMethod, AfterStaticMethod
+} from '@travetto/transformer';
 
 const CONSOLE_IMPORT = '@travetto/runtime/src/console.ts';
 
@@ -39,6 +42,8 @@ export class ConsoleLogTransformer {
     return node;
   }
 
+
+  @OnStaticMethod()
   @OnMethod()
   static startMethodForLog(state: CustomState, node: ts.MethodDeclaration): typeof node {
     this.initState(state);
@@ -50,6 +55,7 @@ export class ConsoleLogTransformer {
     return node;
   }
 
+  @AfterStaticMethod()
   @AfterMethod()
   static leaveMethodForLog(state: CustomState, node: ts.MethodDeclaration): typeof node {
     state.scope.pop();

package/support/transformer.dynamic-import.ts

@@ -8,7 +8,7 @@ import { OnCall, TransformerState } from '@travetto/transformer';
 export class DynamicImportTransformer {
 
   @OnCall()
-  static onLogCall(state: TransformerState, node: ts.CallExpression): typeof node | ts.Identifier {
+  static onCall(state: TransformerState, node: ts.CallExpression): typeof node | ts.Identifier {
     if (
       ts.isCallExpression(node) &&
       node.expression.kind === ts.SyntaxKind.ImportKeyword &&