@travetto/runtime 5.0.0-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 ArcSine Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,304 @@
+<!-- This file was generated by @travetto/doc and should not be modified directly -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/runtime/DOC.tsx and execute "npx trv doc" to rebuild -->
+# Runtime
+
+## Runtime for travetto applications.
+
+**Install: @travetto/runtime**
+```bash
+npm install @travetto/runtime
+
+# or
+
+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
+   *  Console Management
+   *  Resource Access
+   *  Standard Error Support
+   *  Common Utilities
+   *  Time Utilities
+   *  Process Execution
+   *  Shutdown Management
+   *  Path behavior
+
+## 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`
+
+**Code: Base Known Environment Flags**
+```typescript
+interface TravettoEnv {
+    /** 
+     * The node environment we are running in
+     * @default development
+     */
+    NODE_ENV: 'development' | 'production';
+    /** 
+     * Outputs all console.debug messages, defaults to `local` in dev, and `off` in prod. 
+     */
+    DEBUG: boolean | string;
+    /** 
+     * Environment to deploy, defaults to `NODE_ENV` if not `TRV_ENV` is not specified.  
+     */
+    TRV_ENV: string;
+    /** 
+     * Special role to run as, used to access additional files from the manifest during runtime.  
+     */
+    TRV_ROLE: Role;
+    /** 
+     * Whether or not to run the program in dynamic mode, allowing for real-time updates  
+     */
+    TRV_DYNAMIC: boolean;
+    /** 
+     * The folders to use for resource lookup
+     */
+    TRV_RESOURCES: string[];
+    /** 
+     * Resource path overrides
+     * @private
+     */
+    TRV_RESOURCE_OVERRIDES: Record<string, string>;
+    /** 
+     * The max time to wait for shutdown to finish after initial SIGINT, 
+     * @default 2s
+     */
+    TRV_SHUTDOWN_WAIT: TimeSpan | number;
+    /**
+     * The desired runtime module 
+     */
+    TRV_MODULE: string;
+    /**
+     * The location of the manifest file
+     * @default undefined
+     */
+    TRV_MANIFEST: string;
+    /**
+     * trvc log level
+     */
+    TRV_BUILD: 'none' | 'info' | 'debug' | 'error' | 'warn'
+  }
+```
+
+### 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.
+
+**Code: EnvProp Shape**
+```typescript
+export class EnvProp<T> {
+  constructor(public readonly key: string) { }
+  /** Remove value */
+  clear(): void;
+  /** Export value */
+  export(val: T | undefined): Record<string, string>;
+  /** Read value as string */
+  get val(): string | undefined;
+  /** Read value as list */
+  get list(): string[] | undefined;
+  /** Read value as object */
+  get object(): Record<string, string> | undefined;
+  /** Add values to list */
+  add(...items: string[]): void;
+  /** Read value as int  */
+  get int(): number | undefined;
+  /** Read value as boolean */
+  get bool(): boolean | undefined;
+  /** Determine if the underlying value is truthy */
+  get isTrue(): boolean;
+  /** Determine if the underlying value is falsy */
+  get isFalse(): boolean;
+  /** Determine if the underlying value is set */
+  get isSet(): boolean;
+}
+```
+
+## 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). 
+
+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:
+   *  `general` - General purpose errors
+   *  `system` - Synonym for `general`
+   *  `data` - Data format, content, etc are incorrect. Generally correlated to bad input.
+   *  `permission` - Operation failed due to lack of permissions
+   *  `auth` - Operation failed due to lack of authentication
+   *  `missing` - Resource was not found when requested
+   *  `timeout` - Operation did not finish in a timely manner
+   *  `unavailable` - Resource was unresponsive
+
+## Console Management
+This module provides logging functionality, built upon [console](https://nodejs.org/api/console.html) operations. 
+
+The supported operations are:
+   *  `console.error` which logs at the `ERROR` level
+   *  `console.warn` which logs at the `WARN` level
+   *  `console.info` which logs at the `INFO` level
+   *  `console.debug` which logs at the `DEBUG` level
+   *  `console.log` which logs at the `INFO` level
+
+**Note**: All other console methods are excluded, specifically `trace`, `inspect`, `dir`, `time`/`timeEnd`
+
+## 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:
+
+**Code: Sample logging at various levels**
+```typescript
+export function work() {
+  console.debug('Start Work');
+
+  try {
+    1 / 0;
+  } catch (err) {
+    console.error('Divide by zero', { error: err });
+  }
+  console.debug('End Work');
+}
+```
+
+**Code: Sample After Transpilation**
+```javascript
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.work = work;
+const tslib_1 = require("tslib");
+const ᚕ_c = tslib_1.__importStar(require("@travetto/runtime/src/console.js"));
+var ᚕm = ["@travetto/runtime", "doc/transpile"];
+function work() {
+    ᚕ_c.log({ level: "debug", import: ᚕm, line: 2, scope: "work", args: ['Start Work'] });
+    try {
+        1 / 0;
+    }
+    catch (err) {
+        ᚕ_c.log({ level: "error", import: ᚕm, line: 7, scope: "work", args: ['Divide by zero', { error: err }] });
+    }
+    ᚕ_c.log({ level: "debug", import: ᚕm, line: 9, scope: "work", args: ['End Work'] });
+}
+```
+
+### 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**
+```bash
+
+# Debug
+$ DEBUG=-@travetto/model npx trv run app
+$ DEBUG=-@travetto/registry npx trv run app
+$ DEBUG=@travetto/rest npx trv run app
+$ DEBUG=@travetto/*,-@travetto/model npx trv run app
+```
+
+Additionally, the logging framework will merge [debug](https://www.npmjs.com/package/debug) into the output stream, and supports the standard usage
+
+**Terminal: Sample environment flags for standard usage**
+```bash
+
+# Debug
+$ DEBUG=express:*,@travetto/rest npx trv run rest
+```
+
+## 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.
+   *  `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.
+   *  `resolvablePromise()` produces a `Promise` instance with the `resolve` and `reject` methods attached to the instance.  This is extremely useful for integrating promises into async iterations, or any other situation in which the promise creation and the execution flow don't always match up.
+
+**Code: Sample makeTemplate Usage**
+```typescript
+const tpl = makeTemplate((name: 'age'|'name', val) => `**${name}: ${val}**`); 
+tpl`{{age:20}} {{name: 'bob'}}</>;
+// produces
+'**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.
+
+**Code: Time Utilities**
+```typescript
+export class TimeUtil {
+  /**
+   * Test to see if a string is valid for relative time
+   * @param val
+   */
+  static isTimeSpan(val: string): val is TimeSpan;
+  /**
+   * Returns time units convert to ms
+   * @param amount Number of units to extend
+   * @param unit Time unit to extend ('ms', 's', 'm', 'h', 'd', 'w', 'y')
+   */
+  static asMillis(amount: Date | number | TimeSpan, unit?: TimeUnit): number;
+  /**
+   * Returns the time converted to seconds
+   * @param date The date to convert
+   */
+  static asSeconds(date: Date | number | TimeSpan, unit?: TimeUnit): number;
+  /**
+   * Returns the time converted to a Date
+   * @param date The date to convert
+   */
+  static asDate(date: Date | number | TimeSpan, unit?: TimeUnit): Date;
+  /**
+   * Resolve time or span to possible time
+   */
+  static fromValue(value: Date | number | string | undefined): number | undefined;
+  /**
+   * Returns a new date with `amount` units into the future
+   * @param amount Number of units to extend
+   * @param unit Time unit to extend ('ms', 's', 'm', 'h', 'd', 'w', 'y')
+   */
+  static fromNow(amount: number | TimeSpan, unit: TimeUnit = 'ms'): Date;
+  /**
+   * Returns a pretty timestamp
+   * @param time Time in milliseconds
+   */
+  static asClock(time: number): string;
+}
+```
+
+## 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.
+
+A simple example would be:
+
+**Code: Running a directory listing via ls**
+```typescript
+import { spawn } from 'node:child_process';
+import { ExecUtil } from '@travetto/runtime';
+
+export async function executeListing() {
+  const final = await ExecUtil.getResult(spawn('ls'));
+  console.log('Listing', { lines: final.stdout.split('\n') });
+}
+```
+
+## Shutdown Management
+Another key lifecycle is the process of shutting down. The framework provides centralized functionality for running operations on graceful shutdown. Primarily used by the framework for cleanup operations, this provides a clean interface for registering shutdown handlers. The code intercepts `SIGTERM` and `SIGUSR2`, with a default threshold of 2 seconds. These events will start the shutdown process, but also clear out the pending queue. If a kill signal is sent again, it will complete immediately. 
+
+As a registered shutdown handler, you can do.
+
+**Code: Registering a shutdown handler**
+```typescript
+import { ShutdownManager } from '@travetto/runtime';
+
+export function registerShutdownHandler() {
+  ShutdownManager.onGracefulShutdown(async () => {
+    // Do important work, the framework will wait until all async
+    //   operations are completed before finishing shutdown
+  });
+}
+```
+
+## Path Behavior
+To ensure consistency in path usage throughout the framework, imports pointing at $`node:path` and $`path` are rewritten at compile time.  These imports are pointing towards [Manifest](https://github.com/travetto/travetto/tree/main/module/manifest#readme "Support for project indexing, manifesting, along with file watching")'s `path`  implementation.  This allows for seamless import/usage patterns with the reliability needed for cross platform support.

package/__index__.ts

@@ -0,0 +1,16 @@
+/// <reference path="./src/trv.d.ts" />
+/// <reference path="./src/global.d.ts" />
+export * from './src/console';
+export * from './src/context';
+export * from './src/error';
+export * from './src/exec';
+export * from './src/env';
+export * from './src/file-loader';
+export * from './src/function';
+export * from './src/manifest-index';
+export * from './src/resources';
+export * from './src/shutdown';
+export * from './src/time';
+export * from './src/types';
+export * from './src/watch';
+export * from './src/util';

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@travetto/runtime",
+  "version": "5.0.0-rc.2",
+  "description": "Runtime for travetto applications.",
+  "keywords": [
+    "console-manager",
+    "runtime",
+    "travetto",
+    "typescript"
+  ],
+  "homepage": "https://travetto.io",
+  "license": "MIT",
+  "author": {
+    "email": "travetto.framework@gmail.com",
+    "name": "Travetto Framework"
+  },
+  "files": [
+    "__index__.ts",
+    "src",
+    "support"
+  ],
+  "main": "__index__.ts",
+  "repository": {
+    "url": "https://github.com/travetto/travetto.git",
+    "directory": "module/runtime"
+  },
+  "dependencies": {
+    "@travetto/manifest": "^5.0.0-rc.2",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^20.14.10",
+    "debug": "^4.3.5"
+  },
+  "peerDependencies": {
+    "@travetto/transformer": "^5.0.0-rc.2"
+  },
+  "peerDependenciesMeta": {
+    "@travetto/transformer": {
+      "optional": true
+    }
+  },
+  "travetto": {
+    "displayName": "Runtime"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

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,100 @@
+import path from 'node:path';
+
+import { type 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 = {
+  /** Get env name, with support for the default env */
+  get name(): string | undefined {
+    return Env.TRV_ENV.val || (!prod() ? RuntimeIndex.manifest.workspace.defaultEnv : undefined);
+  },
+
+  /** Are we in development mode */
+  get production(): boolean {
+    return prod();
+  },
+
+  /** 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;
+  },
+
+  /** Manifest main */
+  get main(): ManifestContext['main'] {
+    return RuntimeIndex.manifest.main;
+  },
+
+  /** Manifest workspace */
+  get workspace(): ManifestContext['workspace'] {
+    return RuntimeIndex.manifest.workspace;
+  },
+
+  /** Are we running from a mono-root? */
+  get monoRoot(): boolean {
+    return !!RuntimeIndex.manifest.workspace.mono && !RuntimeIndex.manifest.main.folder;
+  },
+
+  /** Main source path */
+  get mainSourcePath(): string {
+    return RuntimeIndex.mainModule.sourcePath;
+  },
+
+  /** Produce a workspace relative path */
+  workspaceRelative(...rel: string[]): string {
+    return path.resolve(RuntimeIndex.manifest.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}/`, '');
+  },
+
+  /** 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);
+  },
+
+  /** Resolve single module path */
+  modulePath(modulePath: string): string {
+    const [base, sub] = (OVERRIDES[modulePath] ?? modulePath)
+      .replace(/^([^#]*)(#|$)/g, (_, v, r) => `${MODULE_ALIASES[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))];
+  },
+
+  /** Resolve resource paths */
+  resourcePaths(paths: string[] = []): string[] {
+    return this.modulePaths([...paths, ...Env.TRV_RESOURCES.list ?? [], '@#resources', '@@#resources']);
+  },
+
+  /** Get source for function */
+  getSource(fn: Function): string {
+    return RuntimeIndex.getFromImport(describeFunction(fn).import)?.sourceFile!;
+  }
+};