@travetto/runtime 5.0.0-rc.8 → 5.0.0-rc.9

package/README.md

@@ -71,7 +71,7 @@ class $Runtime {
 ```
 
 ## 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#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`
+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#L6), 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
@@ -133,7 +133,7 @@ interface TravettoEnv {
 ```
 
 ### Environment Property
-For a given [EnvProp](https://github.com/travetto/travetto/tree/main/module/runtime/src/env.ts#L4), we support the ability to access different properties as a means to better facilitate environment variable usage.
+For a given [EnvProp](https://github.com/travetto/travetto/tree/main/module/runtime/src/env.ts#L6), we support the ability to access different properties as a means to better facilitate environment variable usage.
 
 **Code: EnvProp Shape**
 ```typescript
@@ -165,9 +165,9 @@ 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#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). 
+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#L15) (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). 
 
-The [AppError](https://github.com/travetto/travetto/tree/main/module/runtime/src/error.ts#L13) takes in a message, and an optional payload and / or error classification. The currently supported error classifications are:
+The [AppError](https://github.com/travetto/travetto/tree/main/module/runtime/src/error.ts#L15) takes in a message, and an optional payload and / or error classification. The currently supported error classifications are:
    *  `general` - General purpose errors
    *  `system` - Synonym for `general`
    *  `data` - Data format, content, etc are incorrect. Generally correlated to bad input.
@@ -214,6 +214,7 @@ export function work() {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.work = work;
 const tslib_1 = require("tslib");
+const Ⲑ_function_1 = tslib_1.__importStar(require("@travetto/runtime/src/function.js"));
 const ᚕ_c = tslib_1.__importStar(require("@travetto/runtime/src/console.js"));
 var ᚕm = ["@travetto/runtime", "doc/transpile.ts"];
 function work() {
@@ -226,6 +227,7 @@ function work() {
     }
     ᚕ_c.log({ level: "debug", import: ᚕm, line: 9, scope: "work", args: ['End Work'] });
 }
+Ⲑ_function_1.registerFunction(work, ᚕm, { hash: 1030247697, lines: [1, 10, 2] });
 ```
 
 #### Filtering Debug
@@ -253,12 +255,12 @@ $ 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) 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#L15) 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.
+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.
 
 ## Common Utilities
-Common utilities used throughout the framework. Currently [Util](https://github.com/travetto/travetto/tree/main/module/runtime/src/util.ts#L18) includes:
+Common utilities used throughout the framework. Currently [Util](https://github.com/travetto/travetto/tree/main/module/runtime/src/util.ts#L19) includes:
    *  `uuid(len: number)` generates a simple uuid for use within the application.
    *  `allowDenyMatcher(rules[])` builds a matching function that leverages the rules as an allow/deny list, where order of the rules matters.  Negative rules are prefixed by '!'.
    *  `hash(text: string, size?: number)` produces a full sha512 hash.
@@ -318,7 +320,7 @@ export class TimeUtil {
 ```
 
 ## Process Execution
-[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.
+[ExecUtil](https://github.com/travetto/travetto/tree/main/module/runtime/src/exec.ts#L42) 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/runtime",
-  "version": "5.0.0-rc.8",
+  "version": "5.0.0-rc.9",
   "description": "Runtime for travetto applications.",
   "keywords": [
     "console-manager",
@@ -28,13 +28,13 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
-    "@travetto/manifest": "^5.0.0-rc.4",
+    "@travetto/manifest": "^5.0.0-rc.5",
     "@types/debug": "^4.1.12",
     "@types/node": "^22.1.0",
     "debug": "^4.3.5"
   },
   "peerDependencies": {
-    "@travetto/transformer": "^5.0.0-rc.5"
+    "@travetto/transformer": "^5.0.0-rc.6"
   },
   "peerDependenciesMeta": {
     "@travetto/transformer": {

package/src/env.ts

@@ -1,3 +1,5 @@
+import { castKey, castTo } from './types';
+
 const IS_TRUE = /^(true|yes|on|1)$/i;
 const IS_FALSE = /^(false|no|off|0)$/i;
 
@@ -26,8 +28,7 @@ export class EnvProp<T> {
     } else if (Array.isArray(val)) {
       out = val.join(',');
     } else if (typeof val === 'object') {
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      out = Object.entries(val as Record<string, string>).map(([k, v]) => `${k}=${v}`).join(',');
+      out = Object.entries(val).map(([k, v]) => `${k}=${v}`).join(',');
     } else {
       out = `${val}`;
     }
@@ -52,8 +53,7 @@ export class EnvProp<T> {
 
   /** Add values to list */
   add(...items: string[]): void {
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    this.set([... new Set([...this.list ?? [], ...items])] as T);
+    process.env[this.key] = [... new Set([...this.list ?? [], ...items])].join(',');
   }
 
   /** Read value as int  */
@@ -95,12 +95,12 @@ type AllType = {
 };
 
 function delegate<T extends object>(base: T): AllType & T {
-  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-  return new Proxy(base as AllType & T, {
+  return new Proxy(castTo(base), {
     get(target, prop): unknown {
       return typeof prop !== 'string' ? undefined :
-        // @ts-expect-error
-        (prop in base ? base[prop] : target[prop] ??= new EnvProp(prop));
+        (prop in base ? base[castKey(prop)] :
+          target[castKey<typeof target>(prop)] ??= castTo(new EnvProp(prop))
+        );
     }
   });
 }

package/src/error.ts

@@ -1,3 +1,5 @@
+import { castTo } from './types';
+
 export type ErrorCategory =
   'general' |
   'notfound' |
@@ -20,8 +22,7 @@ export class AppError<T = unknown> extends Error {
       ('type' in e && typeof e.type === 'string') &&
       ('at' in e && typeof e.at === 'number')
     ) {
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      const err = new AppError(e.message, e.category as ErrorCategory, 'details' in e ? e.details : undefined);
+      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;
@@ -59,8 +60,7 @@ export class AppError<T = unknown> extends Error {
       category: this.category,
       type: this.type,
       at: this.at.toISOString(),
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      details: this.details as Record<string, unknown>,
+      details: castTo(this.details),
     };
   }
 }

package/src/exec.ts

@@ -1,6 +1,7 @@
 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);
 
@@ -93,8 +94,8 @@ export class ExecUtil {
   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>> {
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    const res = (proc as unknown as { [RESULT]: Promise<ExecutionResult> })[RESULT] ??= new Promise<ExecutionResult>(resolve => {
+    const _proc: ChildProcess & { [RESULT]?: Promise<ExecutionResult> } = proc;
+    const res = _proc[RESULT] ??= new Promise<ExecutionResult>(resolve => {
       const stdout: Buffer[] = [];
       const stderr: Buffer[] = [];
       let done = false;
@@ -135,14 +136,13 @@ export class ExecUtil {
       }
     });
 
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    return (options.catch ? res : res.then(v => {
+    return castTo(options.catch ? res : res.then(v => {
       if (v.valid) {
         return v;
       } else {
         throw new Error(v.message);
       }
-    })) as Promise<ExecutionResult<T>>;
+    }));
   }
 
   /**

package/src/function.ts

@@ -56,6 +56,6 @@ export function flushPendingFunctions(): Function[] {
  */
 export function describeFunction(fn: Function): FunctionMetadata;
 export function describeFunction(fn?: Function): FunctionMetadata | undefined {
-  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-  return (fn as unknown as { [METADATA]: FunctionMetadata })?.[METADATA];
+  const _fn: (Function & { [METADATA]?: FunctionMetadata }) | undefined = fn;
+  return _fn?.[METADATA];
 }

package/src/time.ts

@@ -35,10 +35,9 @@ export class TimeUtil {
     if (amount instanceof Date) {
       return amount.getTime();
     } else if (typeof amount === 'string') {
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      const { groups } = (amount.match(this.#timePattern) as { groups: { amount?: string, unit?: TimeUnit } });
-      const amountStr = groups?.amount ?? `${amount}`;
-      unit = groups?.unit ?? unit ?? 'ms';
+      const groups: { amount?: string, unit?: TimeUnit } = amount.match(this.#timePattern)?.groups ?? {};
+      const amountStr = groups.amount ?? `${amount}`;
+      unit = groups.unit ?? unit ?? 'ms';
       if (!TIME_UNITS[unit]) {
         return NaN;
       }

package/src/types.ts

@@ -1,23 +1,42 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-export type Class<T = any> = abstract new (...args: any[]) => T;
-export type ConcreteClass<T = any> = new (...args: any[]) => T;
-export type ClassInstance<T = any> = T & {
-  constructor: ConcreteClass<T> & { Ⲑid: string };
-};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Any = any;
 
-export type AnyMap = {
-  [key: string]: any
+export type AnyMap = { [key: string]: Any };
+export type Class<T = Any> = abstract new (...args: Any[]) => T;
+export type ClassInstance<T = Any> = T & {
+  constructor: Class<T> & { Ⲑid: string };
 };
 
+export type TypedFunction<R = Any, V = unknown> = (this: V, ...args: Any[]) => R;
+
+export type MethodDescriptor<V = Any, R = Any> = TypedPropertyDescriptor<TypedFunction<R, V>>;
+export type AsyncMethodDescriptor<V = Any, R = Any> = TypedPropertyDescriptor<TypedFunction<Promise<R>, V>>;
+export type AsyncItrMethodDescriptor<V = Any, R = Any> = TypedPropertyDescriptor<TypedFunction<AsyncIterable<R>, V>>;
+export type ClassTDecorator<T extends Class = Class> = (target: T) => T | void;
+
 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]>));
+    (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[];
+  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 function castTo<T>(input: unknown): T {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  return input as T;
+}
+
+export const castKey = <T>(input: string | number | symbol): keyof T => castTo(input);
+export const asFull = <T>(input: Partial<T>): T => castTo(input);
+export const asConstructable = <Z = unknown>(input: Class | unknown): { constructor: Class<Z> } => castTo(input);
+
+export function classConstruct<T>(cls: Class<T>, args: unknown[] = []): ClassInstance<T> {
+  const cons: { new(..._args: Any[]): T } = castTo(cls);
+  return castTo(new cons(...args));
+}

package/src/util.ts

@@ -3,6 +3,7 @@ import timers from 'node:timers/promises';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
+import { castTo } from './types';
 
 type PromiseWithResolvers<T> = {
   resolve: (v: T) => void;
@@ -64,8 +65,7 @@ export class Util {
         idx += 1;
         let m = el;
         for (const fn of fns) {
-          // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-          m = (await fn(m, idx)) as typeof m;
+          m = castTo(await fn(m, idx));
         }
         yield m;
       }
@@ -104,7 +104,7 @@ export class Util {
   }
 
   /**
-   * Queue new macrotask
+   * Queue new macro task
    */
   static queueMacroTask(): Promise<void> {
     return timers.setImmediate(undefined);

package/support/transformer.console-log.ts

@@ -22,8 +22,7 @@ const VALID_LEVELS: Record<string, string> = {
 };
 
 /**
- * Allows for removal of debug log messages depending on whether app is running
- * in prod mode.
+ * Logging support with code-location aware messages.
  */
 export class ConsoleLogTransformer {
 

package/support/transformer.function-metadata.ts

@@ -2,7 +2,7 @@ import ts from 'typescript';
 
 import {
   TransformerState, OnMethod, OnClass, AfterClass,
-  AfterFunction, CoreUtil, SystemUtil, Import
+  CoreUtil, SystemUtil, Import, OnFunction
 } from '@travetto/transformer';
 
 import type { FunctionMetadataTag } from '../src/function';
@@ -40,7 +40,7 @@ export class RegisterTransformer {
         }
       }
       return { hash, lines: range };
-    } catch (err) {
+    } catch {
       return { hash, lines: [0, 0] };
     }
   }
@@ -118,7 +118,7 @@ export class RegisterTransformer {
   /**
    * Give proper functions a file name
    */
-  @AfterFunction()
+  @OnFunction()
   static registerFunctionMetadata(state: TransformerState & MetadataInfo, node: ts.FunctionDeclaration | ts.FunctionExpression): typeof node {
     if (!this.#valid(state)) {
       return node;

package/support/transformer.type-helpers.ts

@@ -0,0 +1,25 @@
+import ts from 'typescript';
+
+import { TransformerState, OnCall } from '@travetto/transformer';
+
+const SRC = '@travetto/runtime/src/types.ts';
+
+/**
+ * Allows for removal of type helpers at compile time
+ */
+export class TypeHelpersTransformer {
+  @OnCall()
+  static onTypeHelper(state: TransformerState, node: ts.CallExpression): ts.Node {
+    if (
+      ts.isIdentifier(node.expression) &&
+      node.arguments.length === 1 &&
+      /as(Class|Constructable|Full)|cast(To|Key)/.test(node.expression.escapedText.toString())
+    ) {
+      const type = state.resolveType(node.expression);
+      if (type.key === 'unknown' && 'importName' in type && type.importName === SRC) {
+        // return node.arguments[0];
+      }
+    }
+    return node;
+  }
+}