@travetto/runtime 5.0.0-rc.9 → 5.0.1

package/README.md

@@ -34,7 +34,6 @@ While running any code within the framework, there are common patterns/goals for
 ```typescript
 class $Runtime {
   constructor(idx: ManifestIndex, resourceOverrides?: Record<string, string>);
-  get #moduleAliases(): Record<string, string>;
   /** Get env name, with support for the default env */
   get env(): string | undefined;
   /** Are we in development mode */
@@ -260,7 +259,7 @@ The [FileLoader](https://github.com/travetto/travetto/tree/main/module/runtime/s
 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#L19) includes:
+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.
@@ -353,4 +352,4 @@ export function registerShutdownHandler() {
 ```
 
 ## 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.
+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

@@ -1,5 +1,6 @@
 /// <reference path="./src/trv.d.ts" />
 /// <reference path="./src/global.d.ts" />
+export * from './src/binary';
 export * from './src/console';
 export * from './src/context';
 export * from './src/debug';
@@ -9,6 +10,7 @@ export * from './src/env';
 export * from './src/file-loader';
 export * from './src/function';
 export * from './src/manifest-index';
+export * from './src/queue';
 export * from './src/resources';
 export * from './src/shutdown';
 export * from './src/time';

package/package.json

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

package/src/binary.ts

@@ -0,0 +1,133 @@
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import { PassThrough, Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { ReadableStream } from 'node:stream/web';
+import { text as toText, arrayBuffer as toBuffer } from 'node:stream/consumers';
+
+import { BinaryInput, BlobMeta } from './types';
+import { AppError } from './error';
+import { Util } from './util';
+
+const BlobMetaⲐ = Symbol.for('@travetto/runtime:blob-meta');
+
+/**
+ * Common functions for dealing with binary data/streams
+ */
+export class BinaryUtil {
+
+  /**
+   * Generate a proper sha512 hash from a src value
+   * @param src The seed value to build the hash from
+   * @param len The optional length of the hash to generate
+   */
+  static hash(src: string, len: number = -1): string {
+    const hash = crypto.createHash('sha512');
+    hash.update(src);
+    const ret = hash.digest('hex');
+    return len > 0 ? ret.substring(0, len) : ret;
+  }
+
+  /**
+   * Compute hash from an input blob, buffer or readable stream.
+   */
+  static async hashInput(input: BinaryInput): Promise<string> {
+    const hash = crypto.createHash('sha256').setEncoding('hex');
+    if (Buffer.isBuffer(input)) {
+      hash.write(input);
+    } else if (input instanceof Blob) {
+      await pipeline(Readable.fromWeb(input.stream()), hash);
+    } else {
+      await pipeline(input, hash);
+    }
+    return hash.digest('hex').toString();
+  }
+
+  /**
+   * Write file and copy over when ready
+   */
+  static async bufferedFileWrite(file: string, content: string, checkHash = false): Promise<void> {
+    if (checkHash) {
+      const current = await fs.readFile(file, 'utf8').catch(() => '');
+      if (this.hash(current) === this.hash(content)) {
+        return;
+      }
+    }
+
+    const temp = path.resolve(os.tmpdir(), `${process.hrtime()[1]}.${path.basename(file)}`);
+    await fs.writeFile(temp, content, 'utf8');
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.copyFile(temp, file);
+    await fs.rm(temp, { force: true });
+  }
+
+  /**
+   * Make a blob, and assign metadata
+   */
+  static readableBlob(input: () => (Readable | Promise<Readable>), metadata: Omit<BlobMeta, 'filename'> & { filename: string }): File;
+  static readableBlob(input: () => (Readable | Promise<Readable>), metadata?: BlobMeta): Blob;
+  static readableBlob(input: () => (Readable | Promise<Readable>), metadata: BlobMeta = {}): Blob | File {
+    const go = (): Readable => {
+      const stream = new PassThrough();
+      Promise.resolve(input()).then(v => v.pipe(stream), (err) => stream.destroy(err));
+      return stream;
+    };
+
+    const size = metadata.range ? (metadata.range.end - metadata.range.start) + 1 : metadata.size;
+    const out: Blob = metadata.filename ?
+      new File([], path.basename(metadata.filename), { type: metadata.contentType }) :
+      new Blob([], { type: metadata.contentType });
+
+    return Object.defineProperties(out, {
+      size: { value: size },
+      stream: { value: () => ReadableStream.from(go()) },
+      arrayBuffer: { value: () => toBuffer(go()) },
+      text: { value: () => toText(go()) },
+      bytes: { value: () => toBuffer(go()).then(v => new Uint8Array(v)) },
+      [BlobMetaⲐ]: { value: metadata }
+    });
+  }
+
+  /**
+   * Get blob metadata
+   */
+  static getBlobMeta(blob: Blob): BlobMeta | undefined {
+    const withMeta: Blob & { [BlobMetaⲐ]?: BlobMeta } = blob;
+    return withMeta[BlobMetaⲐ];
+  }
+
+  /**
+   * Write limiter
+   * @returns
+   */
+  static limitWrite(maxSize: number): Transform {
+    let read = 0;
+    return new Transform({
+      transform(chunk, encoding, callback): void {
+        read += (Buffer.isBuffer(chunk) || typeof chunk === 'string') ? chunk.length : (chunk instanceof Uint8Array ? chunk.byteLength : 0);
+        if (read > maxSize) {
+          callback(new AppError('File size exceeded', 'data', { read, size: maxSize }));
+        } else {
+          callback(null, chunk);
+        }
+      },
+    });
+  }
+
+  /**
+   * Get a hashed location/path for a blob
+   */
+  static hashedBlobLocation(meta: BlobMeta): string {
+    const hash = meta.hash ?? Util.uuid();
+
+    let parts = hash.match(/(.{1,4})/g)!.slice();
+    if (parts.length > 4) {
+      parts = [...parts.slice(0, 4), parts.slice(4).join('')];
+    }
+
+    const ext = path.extname(meta.filename ?? '') || '.bin';
+    return `${parts.join('/')}${ext}`;
+  }
+}

package/src/global.d.ts

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

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/types.ts

@@ -1,3 +1,6 @@
+import { Readable } from 'node:stream';
+import { ReadableStream } from 'node:stream/web';
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type Any = any;
 
@@ -7,6 +10,8 @@ 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>>;
@@ -40,3 +45,32 @@ export function classConstruct<T>(cls: Class<T>, args: unknown[] = []): ClassIns
   const cons: { new(..._args: Any[]): T } = castTo(cls);
   return castTo(new cons(...args));
 }
+
+export const hasFunction = <T>(key: keyof T) => (o: unknown): o is T =>
+  typeof o === 'object' && o !== null && typeof o[castKey(key)] === 'function';
+
+/**
+ * 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

@@ -1,8 +1,6 @@
 import crypto from 'node:crypto';
 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> = {
@@ -18,6 +16,31 @@ type MapFn<T, U> = (val: T, i: number) => U | Promise<U>;
  */
 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
@@ -31,18 +54,6 @@ export class Util {
     return bytes.toString('hex').substring(0, len);
   }
 
-  /**
-   * Generate a proper sha512 hash from a src value
-   * @param src The seed value to build the hash from
-   * @param len The optional length of the hash to generate
-   */
-  static hash(src: string, len: number = -1): string {
-    const hash = crypto.createHash('sha512');
-    hash.update(src);
-    const ret = hash.digest('hex');
-    return len > 0 ? ret.substring(0, len) : ret;
-  }
-
   /**
    * Produce a promise that is externally resolvable
    */
@@ -72,23 +83,6 @@ export class Util {
     }
   }
 
-  /**
-   * Write file and copy over when ready
-   */
-  static async bufferedFileWrite(file: string, content: string, checkHash = false): Promise<void> {
-    if (checkHash) {
-      const current = await fs.readFile(file, 'utf8').catch(() => '');
-      if (Util.hash(current) === Util.hash(content)) {
-        return;
-      }
-    }
-
-    const temp = path.resolve(os.tmpdir(), `${process.hrtime()[1]}.${path.basename(file)}`);
-    await fs.writeFile(temp, content, 'utf8');
-    await fs.mkdir(path.dirname(file), { recursive: true });
-    await fs.rename(temp, file);
-  }
-
   /**
    * Non-blocking timeout
    */
@@ -109,4 +103,32 @@ export class Util {
   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;
+    }
+  }
 }