@travetto/registry 3.0.0-rc.9 → 3.0.0

package/README.md

@@ -6,6 +6,10 @@
 **Install: @travetto/registry**
 ```bash
 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.
@@ -39,12 +43,21 @@ interface Child {
   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 {
-    return this.getOrCreatePending(cls) as Group;
+    const pending: Partial<Group> = this.getOrCreatePending(cls);
+    if (isComplete(pending)) {
+      return pending;
+    } else {
+      throw new Error('Invalid Group');
+    }
   }
 
   /**
@@ -68,7 +81,51 @@ As the [DynamicFileLoader](https://github.com/travetto/travetto/tree/main/module
 
 ## Supporting Metadata
 
-For the registries to work properly, metadata needs to be collected about files and classes to uniquely identify them, especially across file reloads for the live flow.  To achieve this, every `class` is decorated with additional fields.  The data that is added is:
+As mentioned in [Manifest](https://github.com/travetto/travetto/tree/main/module/manifest#readme "Support for project indexing, manifesting, along with file watching")'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.  
 
-   
-   *  `Ⲑid` represents a computed id that is tied to the file/class combination;
+**Code: Sample Class Diffing**
+```typescript
+#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 = RootIndex.getFunctionMetadataFromClass(prev.get(k));
+          const nextMeta = RootIndex.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);
+    }
+  }
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/registry",
-  "version": "3.0.0-rc.9",
+  "version": "3.0.0",
   "description": "Patterns and utilities for handling registration of metadata and functionality for run-time use",
   "keywords": [
     "ast-transformations",
@@ -27,10 +27,10 @@
     "directory": "module/registry"
   },
   "dependencies": {
-    "@travetto/base": "^3.0.0-rc.7"
+    "@travetto/base": "^3.0.0"
   },
   "peerDependencies": {
-    "@travetto/transformer": "^3.0.0-rc.9"
+    "@travetto/transformer": "^3.0.0"
   },
   "peerDependenciesMeta": {
     "@travetto/transformer": {

package/src/service/root.ts

@@ -19,6 +19,14 @@ class $RootRegistry extends Registry {
     await super.onEvent(e); // Process event, and
     this.emit(e); // Send to children
   }
+
+  /**
+   * Registers a listener to be notified when a file changes, but no
+   * classes are modified
+   */
+  onNonClassChanges(handler: (file: string) => void): void {
+    this.parent(ClassSource)!.onNonClassChanges(handler);
+  }
 }
 
 export const RootRegistry = new $RootRegistry();

package/src/source/class-source.ts

@@ -1,7 +1,7 @@
 import { EventEmitter } from 'events';
 
-import { RootIndex } from '@travetto/manifest';
-import { Class, FileWatchEvent, GlobalEnv } from '@travetto/base';
+import { WatchEvent, RootIndex } from '@travetto/manifest';
+import { Class, GlobalEnv } from '@travetto/base';
 import { DynamicFileLoader } from '@travetto/base/src/internal/file-loader';
 
 import { ChangeSource, ChangeEvent, ChangeHandler } from '../types';
@@ -51,32 +51,40 @@ export class ClassSource implements ChangeSource<Class> {
       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 = RootIndex.getFunctionMetadataFromClass(prev.get(k));
           const nextMeta = RootIndex.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);
+    }
   }
 
   /**
    * Handle when a file watch event happens
    */
-  async onLoadEvent(ev: FileWatchEvent): Promise<void> {
+  async onLoadEvent(ev: WatchEvent): Promise<void> {
     console.debug('Pending changes', { changes: PendingRegister.ordered.map(([, x]) => x.map(y => y.Ⲑid)) });
     for (const [file, classes] of PendingRegister.flush()) {
       this.#handleFileChanges(file, classes);
@@ -116,4 +124,11 @@ export class ClassSource implements ChangeSource<Class> {
   on(callback: ChangeHandler<Class>): void {
     this.#emitter.on('change', callback);
   }
+
+  /**
+   * Add callback for when a file is changed, but emits no class changes
+   */
+  onNonClassChanges(callback: (file: string) => void): void {
+    this.#emitter.on('unchanged-file', callback);
+  }
 }

package/src/source/method-source.ts

@@ -37,19 +37,19 @@ export class MethodSource implements ChangeSource<[Class, Function]> {
      * Go through each method, comparing hashes.  To see added/removed and changed
      */
     for (const k of Object.keys(next)) {
-      if (!prev[k]) {
+      if (!prev[k] || !e.prev) {
         this.emit({ type: 'added', curr: [e.curr!, e.curr!.prototype[k]] });
-      } else if (next[k].hash !== prev[k].hash) {
+      } else if (next[k].hash !== prev[k].hash && e.curr) {
         // FIXME: Why is e.prev undefined sometimes?
-        this.emit({ type: 'changed', curr: [e.curr!, e.curr!.prototype[k]], prev: [e.prev!, e.prev!.prototype[k]] });
+        this.emit({ type: 'changed', curr: [e.curr, e.curr.prototype[k]], prev: [e.prev, e.prev.prototype[k]] });
       } else {
         // Method Unchanged
       }
     }
 
     for (const k of Object.keys(prev)) {
-      if (!next[k]) {
-        this.emit({ type: 'removing', prev: [e.prev!, e.prev!.prototype[k]] });
+      if (!next[k] && e.prev) {
+        this.emit({ type: 'removing', prev: [e.prev, e.prev.prototype[k]] });
       }
     }
   }