Registry

Patterns and utilities for handling registration of metadata and functionality for run-time use

Install: @travetto/registry

npm install @travetto/registry

# or

yarn add @travetto/registry

This module is the backbone for all "discovered" and "registered" behaviors within the framework. This is primarily used for building modules within the framework and not directly useful for application development.

Flows

Registration, within the framework flows throw two main use cases:

Initial Flows

The primary flow occurs on initialization of the application. At that point, the module will:

1. Initialize RootRegistry and will automatically register/load all relevant files
2. As files are imported, decorators within the files will record various metadata relevant to the respective registries
3. When all files are processed, the RootRegistry is finished, and it will signal to anything waiting on registered data that its free to use it. This flow ensures all files are loaded and processed before application starts. A sample registry could like:

Code: Sample Registry

import { Class } from '@travetto/base';
import { MetadataRegistry } from '@travetto/registry';

interface Group {
  class: Class;
  name: string;
}

interface Child {
  name: string;
  method: Function;
}

function isComplete(o: Partial<Group>): o is Group {
  return !!o;
}

export class SampleRegistry extends MetadataRegistry<Group, Child> {
  /**
   * Finalize class after all metadata is collected
   */
  onInstallFinalize<T>(cls: Class<T>): Group {
    const pending: Partial<Group> = this.getOrCreatePending(cls);
    if (isComplete(pending)) {
      return pending;
    } else {
      throw new Error('Invalid Group');
    }
  }

  /**
   * Create scaffolding on first encounter of a class
   */
  createPending(cls: Class): Partial<Group> {
    return {
      class: cls,
      name: cls.name
    };
  }
}

The registry is a MetadataRegistry that similar to the Schema's Schema registry and Dependency Injection's Dependency registry.

Live Flow

At runtime, the registry is designed to listen for changes and to propagate the changes as necessary. In many cases the same file is handled by multiple registries.

As the DynamicFileLoader notifies that a file has been changed, the RootRegistry will pick it up, and process it accordingly.

Supporting Metadata

As mentioned in Manifest's readme, the framework produces hashes of methods, classes, and functions, to allow for detecting changes to individual parts of the codebase. During the live flow, various registries will inspect this information to determine if action should be taken.

Code: Sample Class Diffing

#handleFileChanges(file: string, classes: Class[] = []): void {
    const next = new Map<string, Class>(classes.map(cls => [cls.Ⲑid, cls] as const));

    let prev = new Map<string, Class>();
    if (this.#classes.has(file)) {
      prev = new Map(this.#classes.get(file)!.entries());
    }

    const keys = new Set([...Array.from(prev.keys()), ...Array.from(next.keys())]);

    if (!this.#classes.has(file)) {
      this.#classes.set(file, new Map());
    }

    let changes = 0;

    /**
     * Determine delta based on the various classes (if being added, removed or updated)
     */
    for (const k of keys) {
      if (!next.has(k)) {
        changes += 1;
        this.emit({ type: 'removing', prev: prev.get(k)! });
        this.#classes.get(file)!.delete(k);
      } else {
        this.#classes.get(file)!.set(k, next.get(k)!);
        if (!prev.has(k)) {
          changes += 1;
          this.emit({ type: 'added', curr: next.get(k)! });
        } else {
          const prevMeta = RuntimeIndex.getFunctionMetadataFromClass(prev.get(k));
          const nextMeta = RuntimeIndex.getFunctionMetadataFromClass(next.get(k));
          if (prevMeta?.hash !== nextMeta?.hash) {
            changes += 1;
            this.emit({ type: 'changed', curr: next.get(k)!, prev: prev.get(k) });
          }
        }
      }
    }
    if (!changes) {
      this.#emitter.emit('unchanged-file', file);
    }
  }