@travetto/runtime 5.0.0-rc.10

package/src/function.ts

@@ -0,0 +1,61 @@
+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
+ * @param `file` Filename
+ * @param `hash` Hash of class contents
+ * @param `line` Line number in source
+ * @param `methods` Methods and their hashes
+ * @param `abstract` Is the class abstract
+ * @param `synthetic` Is this code generated at build time
+ * @private
+ */
+export function registerFunction(
+  fn: Function, [pkg, pth]: [string, string], tag: FunctionMetadataTag,
+  methods?: Record<string, FunctionMetadataTag>, abstract?: boolean, synthetic?: boolean
+): void {
+  const modulePath = pth.replace(/[.][cm]?[tj]sx?$/, '');
+
+  const metadata: FunctionMetadata = {
+    id: (fn.name ? `${pkg}:${modulePath}￮${fn.name}` : `${pkg}:${modulePath}`),
+    import: `${pkg}/${pth}`,
+    module: pkg,
+    modulePath,
+    ...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;
+}
+
+/**
+ * Read metadata
+ */
+export function describeFunction(fn: Function): FunctionMetadata;
+export function describeFunction(fn?: Function): FunctionMetadata | undefined {
+  const _fn: (Function & { [METADATA]?: FunctionMetadata }) | undefined = fn;
+  return _fn?.[METADATA];
+}

package/src/global.d.ts

@@ -0,0 +1,20 @@
+import { BlobMeta } from './types';
+
+// https://github.com/microsoft/TypeScript/issues/59012
+declare const write: unique symbol;
+declare global {
+  interface WritableStreamDefaultWriter<W = any> {
+    [write]?: (a: W) => void;
+  }
+  interface Function {
+    Ⲑid: string;
+  }
+
+  interface Blob {
+    readonly meta?: Readonly<BlobMeta>;
+  }
+
+  interface File {
+    readonly meta?: Readonly<BlobMeta>;
+  }
+}

package/src/manifest-index.ts

@@ -0,0 +1,4 @@
+import { ManifestIndex } from '@travetto/manifest';
+
+/** Runtime manifest index */
+export const RuntimeIndex = new ManifestIndex();

package/src/queue.ts

@@ -0,0 +1,64 @@
+import { Util } from './util';
+
+/**
+ * An asynchronous queue
+ */
+export class AsyncQueue<X> implements AsyncIterator<X>, AsyncIterable<X> {
+
+  #queue: X[] = [];
+  #done = false;
+  #ready = Util.resolvablePromise();
+
+  /**
+   * Initial set of items
+   */
+  constructor(initial: Iterable<X> = [], signal?: AbortSignal) {
+    this.#queue.push(...initial);
+    signal?.addEventListener('abort', () => this.close());
+    if (signal?.aborted) {
+      this.close();
+    }
+  }
+
+  // Allow for iteration
+  [Symbol.asyncIterator](): AsyncIterator<X> {
+    return this;
+  }
+
+  /**
+   * Wait for next event to fire
+   */
+  async next(): Promise<IteratorResult<X>> {
+    while (!this.#done && !this.#queue.length) {
+      await this.#ready.promise;
+      this.#ready = Util.resolvablePromise();
+    }
+    return { value: (this.#queue.length ? this.#queue.shift() : undefined)!, done: this.#done };
+  }
+
+  /**
+   * Queue next event to fire
+   * @param {boolean} immediate Determines if item(s) should be append or prepended to the queue
+   */
+  add(item: X, immediate = false): void {
+    this.#queue[immediate ? 'unshift' : 'push'](item);
+    this.#ready.resolve();
+  }
+
+  /**
+   * Close the iterator
+   */
+  close(): void {
+    this.#done = true;
+    this.#ready.resolve();
+  }
+
+  /**
+   * Throw an error from the queue, rejecting and terminating immediately
+   */
+  async throw(e?: Error): Promise<IteratorResult<X>> {
+    this.#done = true;
+    this.#ready.reject(e);
+    return { value: undefined, done: this.#done };
+  }
+}

package/src/resources.ts

@@ -0,0 +1,28 @@
+import { Runtime } from './context';
+import { Env } from './env';
+import { FileLoader } from './file-loader';
+
+/**
+ * Environment aware file loader
+ */
+class $RuntimeResources extends FileLoader {
+  #computed: string[];
+  #env: string;
+  #mod: string;
+
+  constructor() {
+    super([]);
+  }
+
+  override get searchPaths(): readonly string[] {
+    if (!this.#computed || this.#env !== Env.TRV_RESOURCES.val || this.#mod !== Env.TRV_MODULE.val) {
+      this.#env = Env.TRV_RESOURCES.val!;
+      this.#mod = Env.TRV_MODULE.val!;
+      this.#computed = Runtime.resourcePaths();
+    }
+    return this.#computed;
+  }
+}
+
+/** Runtime resources */
+export const RuntimeResources = new $RuntimeResources();

package/src/shutdown.ts

@@ -0,0 +1,65 @@
+import { Env } from './env';
+import { Util } from './util';
+import { TimeUtil } from './time';
+
+/**
+ * Shutdown manager, allowing for listening for graceful shutdowns
+ */
+export class ShutdownManager {
+
+  static #registered = false;
+  static #handlers: { name?: string, handler: () => Promise<void> }[] = [];
+
+  /**
+   * On Shutdown requested
+   * @param name name to log for
+   * @param handler synchronous or asynchronous handler
+   */
+  static onGracefulShutdown(handler: () => Promise<void>, name?: string | { constructor: { Ⲑid: string } }): () => 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 });
+    return () => {
+      const idx = this.#handlers.findIndex(x => x.handler === handler);
+      if (idx >= 0) {
+        this.#handlers.splice(idx, 1);
+      }
+    };
+  }
+
+  /**
+   * Wait for graceful shutdown to run and complete
+   */
+  static async gracefulShutdown(code: number | string | undefined = process.exitCode): Promise<void> {
+    if (code !== undefined) {
+      process.exitCode = code;
+    }
+
+    if (this.#handlers.length) {
+      console.debug('Graceful shutdown: started');
+
+      const items = this.#handlers.splice(0, this.#handlers.length);
+      const handlers = Promise.all(items.map(({ name, handler }) => {
+        if (name) {
+          console.debug('Stopping', { name });
+        }
+        return handler().catch(err => {
+          console.error('Error shutting down', { name, err });
+        });
+      }));
+
+      await Promise.race([
+        Util.nonBlockingTimeout(TimeUtil.fromValue(Env.TRV_SHUTDOWN_WAIT.val) ?? 2000), // Wait 2s and then force finish
+        handlers,
+      ]);
+
+      console.debug('Graceful shutdown: completed');
+    }
+    if (code !== undefined) {
+      process.exit();
+    }
+  }
+}

package/src/time.ts

@@ -0,0 +1,100 @@
+const MIN = 1000 * 60;
+const DAY = 24 * MIN * 60;
+const TIME_UNITS = {
+  y: DAY * 365,
+  M: DAY * 30,
+  w: DAY * 7,
+  d: DAY,
+  h: MIN * 60,
+  m: MIN,
+  s: 1000,
+  ms: 1
+};
+
+export type TimeSpan = `${number}${keyof typeof TIME_UNITS}`;
+export type TimeUnit = keyof typeof TIME_UNITS;
+
+export class TimeUtil {
+
+  static #timePattern = new RegExp(`^(?<amount>-?[0-9.]+)(?<unit>${Object.keys(TIME_UNITS).join('|')})$`);
+
+  /**
+   * 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);
+  }
+
+  /**
+   * 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 {
+    if (amount instanceof Date) {
+      return amount.getTime();
+    } else if (typeof amount === 'string') {
+      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;
+      }
+      amount = amountStr.includes('.') ? parseFloat(amountStr) : parseInt(amountStr, 10);
+    }
+    return amount * TIME_UNITS[unit ?? 'ms'];
+  }
+
+  /**
+   * Returns the time converted to seconds
+   * @param date The date to convert
+   */
+  static asSeconds(date: Date | number | TimeSpan, unit?: TimeUnit): number {
+    return Math.trunc(this.asMillis(date, unit) / 1000);
+  }
+
+  /**
+   * Returns the time converted to a Date
+   * @param date The date to convert
+   */
+  static asDate(date: Date | number | TimeSpan, unit?: TimeUnit): Date {
+    return new Date(this.asMillis(date, unit));
+  }
+
+  /**
+   * Resolve time or span to possible time
+   */
+  static fromValue(value: Date | number | string | undefined): number | undefined {
+    if (value === undefined) {
+      return value;
+    }
+    const val = (typeof value === 'string' && /\d+[a-z]$/i.test(value)) ?
+      (this.isTimeSpan(value) ? this.asMillis(value) : undefined) :
+      (typeof value === 'string' ? parseInt(value, 10) :
+        (value instanceof Date ? value.getTime() : value));
+    return Number.isNaN(val) ? undefined : val;
+  }
+
+  /**
+   * 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 {
+    return new Date(Date.now() + this.asMillis(amount, unit));
+  }
+
+  /**
+   * Returns a pretty timestamp
+   * @param time Time in milliseconds
+   */
+  static asClock(time: number): string {
+    const s = Math.trunc(time / 1000);
+    return [
+      s > 3600 ? `${Math.trunc(s / 3600).toString().padStart(2, '0')}h` : '',
+      s > 60 ? `${Math.trunc((s % 3600) / 60).toString().padStart(2, '0')}m` : '',
+      `${(s % 60).toString().padStart(2, '0')}s`
+    ].filter(x => !!x).slice(0, 2).join(' ');
+  }
+}

package/src/trv.d.ts

@@ -0,0 +1,64 @@
+import type { ManifestModuleRole } from '@travetto/manifest';
+
+import type { TimeSpan } from './time';
+
+type Role = Exclude<ManifestModuleRole, 'std' | 'compile'>;
+
+
+declare global {
+  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',
+    /**
+     * Should break on first line of a method when using the @DebugBreak decorator
+     * @default false
+     */
+    TRV_DEBUG_BREAK: boolean;
+  }
+}

package/src/types.ts

@@ -0,0 +1,73 @@
+import { Readable } from 'node:stream';
+import { ReadableStream } from 'node:stream/web';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Any = 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 BinaryInput = Blob | Buffer | Readable | ReadableStream;
+
+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]>));
+};
+
+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 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));
+}
+
+/**
+ * Range of bytes, inclusive
+ */
+export type ByteRange = { start: number, end?: number };
+
+export interface BlobMeta {
+  /** Size of blob */
+  size?: number;
+  /** Mime type of the content */
+  contentType?: string;
+  /** Hash of blob contents */
+  hash?: string;
+  /** The original base filename of the file */
+  filename?: string;
+  /** Filenames title, optional for elements like images, audio, videos */
+  title?: string;
+  /** Content encoding */
+  contentEncoding?: string;
+  /** Content language */
+  contentLanguage?: string;
+  /** Cache control */
+  cacheControl?: string;
+  /** Byte range for blob */
+  range?: Required<ByteRange>;
+}

package/src/util.ts

@@ -0,0 +1,134 @@
+import crypto from 'node:crypto';
+import timers from 'node:timers/promises';
+
+import { castTo } from './types';
+
+type PromiseWithResolvers<T> = {
+  resolve: (v: T) => void;
+  reject: (err?: unknown) => void;
+  promise: Promise<T>;
+};
+
+type MapFn<T, U> = (val: T, i: number) => U | Promise<U>;
+
+/**
+ * Grab bag of common utilities
+ */
+export class Util {
+
+  static #match<T, K extends unknown[]>(
+    rules: { value: T, positive: boolean }[],
+    compare: (rule: T, ...compareInput: K) => boolean,
+    unmatchedValue: boolean,
+    ...input: K
+  ): boolean {
+    for (const rule of rules) {
+      if (compare(rule.value, ...input)) {
+        return rule.positive;
+      }
+    }
+    return unmatchedValue;
+  }
+
+  static #allowDenyRuleInput<T>(
+    rule: (string | T | [value: T, positive: boolean] | [value: T]),
+    convert: (inputRule: string) => T
+  ): { value: T, positive: boolean } {
+    return typeof rule === 'string' ?
+      { value: convert(rule.replace(/^!/, '')), positive: !rule.startsWith('!') } :
+      Array.isArray(rule) ?
+        { value: rule[0], positive: rule[1] ?? true } :
+        { value: rule, positive: true };
+  }
+
+  /**
+   * Generate a random UUID
+   * @param len The length of the uuid to generate
+   */
+  static uuid(len: number = 32): string {
+    const bytes = crypto.randomBytes(Math.ceil(len / 2));
+    // eslint-disable-next-line no-bitwise
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    // eslint-disable-next-line no-bitwise
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    return bytes.toString('hex').substring(0, len);
+  }
+
+  /**
+   * Produce a promise that is externally resolvable
+   */
+  static resolvablePromise<T = void>(): PromiseWithResolvers<T> {
+    let ops: Pick<PromiseWithResolvers<T>, 'reject' | 'resolve'>;
+    const prom = new Promise<T>((resolve, reject) => ops = { resolve, reject });
+    return { ...ops!, promise: prom };
+  }
+
+  /**
+   * Map an async iterable with various mapping functions
+   */
+  static mapAsyncItr<T, U, V, W>(source: AsyncIterable<T>, fn1: MapFn<T, U>, fn2: MapFn<U, V>, fn3: MapFn<V, W>): AsyncIterable<W>;
+  static mapAsyncItr<T, U, V>(source: AsyncIterable<T>, fn1: MapFn<T, U>, fn2: MapFn<U, V>): AsyncIterable<V>;
+  static mapAsyncItr<T, U>(source: AsyncIterable<T>, fn: MapFn<T, U>): AsyncIterable<U>;
+  static async * mapAsyncItr<T>(source: AsyncIterable<T>, ...fns: MapFn<unknown, unknown>[]): AsyncIterable<unknown> {
+    let idx = -1;
+    for await (const el of source) {
+      if (el !== undefined) {
+        idx += 1;
+        let m = el;
+        for (const fn of fns) {
+          m = castTo(await fn(m, idx));
+        }
+        yield m;
+      }
+    }
+  }
+
+  /**
+   * Non-blocking timeout
+   */
+  static nonBlockingTimeout(time: number): Promise<void> {
+    return timers.setTimeout(time, undefined, { ref: false }).catch(() => { });
+  }
+
+  /**
+   * Blocking timeout
+   */
+  static blockingTimeout(time: number): Promise<void> {
+    return timers.setTimeout(time, undefined, { ref: true }).catch(() => { });
+  }
+
+  /**
+   * Queue new macro task
+   */
+  static queueMacroTask(): Promise<void> {
+    return timers.setImmediate(undefined);
+  }
+
+  /**
+   * Simple check against allow/deny rules
+   * @param rules
+   */
+  static allowDeny<T, K extends unknown[]>(
+    rules: string | (string | T | [value: T, positive: boolean])[],
+    convert: (rule: string) => T,
+    compare: (rule: T, ...compareInput: K) => boolean,
+    cacheKey?: (...keyInput: K) => string
+  ): (...input: K) => boolean {
+
+    const rawRules = (Array.isArray(rules) ? rules : rules.split(/\s*,\s*/g));
+    const convertedRules = rawRules.map(rule => this.#allowDenyRuleInput(rule, convert));
+    const unmatchedValue = !convertedRules.some(r => r.positive);
+
+    if (convertedRules.length) {
+      if (cacheKey) {
+        const cache: Record<string, boolean> = {};
+        return (...input: K) =>
+          cache[cacheKey(...input)] ??= this.#match(convertedRules, compare, unmatchedValue, ...input);
+      } else {
+        return (...input: K) => this.#match(convertedRules, compare, unmatchedValue, ...input);
+      }
+    } else {
+      return () => true;
+    }
+  }
+}

package/src/watch.ts

@@ -0,0 +1,38 @@
+import { RuntimeIndex } from './manifest-index';
+import { ExecUtil } from './exec';
+import { ShutdownManager } from './shutdown';
+import { Util } from './util';
+
+export type WatchEvent = { file: string, action: 'create' | 'update' | 'delete', output: string, module: string, time: number };
+
+export async function* watchCompiler(cfg?: { restartOnExit?: boolean, signal?: AbortSignal }): AsyncIterable<WatchEvent> {
+  // Load at runtime
+  const { CompilerClient } = await import('@travetto/compiler/support/server/client');
+
+  const client = new CompilerClient(RuntimeIndex.manifest, {
+    warn(message, ...args): void { console.error('warn', message, ...args); },
+    debug(message, ...args): void { console.error('debug', message, ...args); },
+    error(message, ...args): void { console.error('error', message, ...args); },
+    info(message, ...args): void { console.error('info', message, ...args); },
+  });
+
+  const ctrl = new AbortController();
+  const remove = ShutdownManager.onGracefulShutdown(async () => ctrl.abort(), watchCompiler);
+
+  await client.waitForState(['compile-end', 'watch-start'], undefined, ctrl.signal);
+
+  if (!await client.isWatching()) { // If we get here, without a watch
+    while (!await client.isWatching()) { // Wait until watch starts
+      await Util.nonBlockingTimeout(1000 * 60);
+    }
+  } else {
+    yield* client.fetchEvents('change', { signal: ctrl.signal, enforceIteration: true });
+  }
+
+  remove();
+
+  if (cfg?.restartOnExit) {
+    // We are done, request restart
+    await ShutdownManager.gracefulShutdown(ExecUtil.RESTART_EXIT_CODE);
+  }
+}