@travetto/manifest 3.0.3 → 3.1.0-rc.1

package/README.md

@@ -36,7 +36,7 @@ During the compilation process, it is helpful to know how the output content dif
 ## Class and Function Metadata
 For the framework to work properly, metadata needs to be collected about files, classes and functions to uniquely identify them, with support for detecting changes during live reloads.  To achieve this, every `class` is decorated with an additional field of `Ⲑid`.  `Ⲑid` represents a computed id that is tied to the file/class combination. 
 
-`Ⲑid` is used heavily throughout the framework for determining which classes are owned by the framework, and being able to lookup the needed data from the [RootIndex](https://github.com/travetto/travetto/tree/main/module/manifest/src/root-index.ts#L12) using the `getFunctionMetadata` method.
+`Ⲑid` is used heavily throughout the framework for determining which classes are owned by the framework, and being able to lookup the needed data from the [RootIndex](https://github.com/travetto/travetto/tree/main/module/manifest/src/root-index.ts#L11) using the `getFunctionMetadata` method.
 
 **Code: Test Class**
 ```typescript
@@ -90,17 +90,27 @@ By default, all paths within the framework are assumed to be in a POSIX style, a
 ## File Watching
 The module also leverages [fetch](https://www.npmjs.com/package/@parcel/watcher), to expose a single function of `watchFolders`. Only the [Compiler](https://github.com/travetto/travetto/tree/main/module/compiler#readme "The compiler infrastructure for the Travetto framework") module packages [fetch](https://www.npmjs.com/package/@parcel/watcher) as a direct dependency.  This means, that in production, by default all watch operations will fail with a missing dependency.
 
-**Code: Watch Folder Signature**
+**Code: Watch Configuration**
 ```typescript
-export type WatchEvent = { action: 'create' | 'update' | 'delete', file: string };
-export type WatchEventFilter = (ev: WatchEvent) => boolean;
+export type WatchEvent = { action: 'create' | 'update' | 'delete', file: string, folder: string };
 
-export type WatchEventListener = (ev: WatchEvent, folder: string) => void;
-export type WatchConfig = {
+export type WatchFolder = {
   /**
-   * Predicate for filtering events
+   * Source folder
    */
-  filter?: WatchEventFilter;
+  src: string;
+  /**
+   * Target folder name, useful for deconstructing
+   */
+  target?: string;
+  /**
+   * Filter events
+   */
+  filter?: (ev: WatchEvent) => boolean;
+  /**
+   * Only look at immediate folder
+   */
+  immediate?: boolean;
   /**
    * List of top level folders to ignore
    */
@@ -113,27 +123,21 @@ export type WatchConfig = {
    * Include files that start with '.'
    */
   includeHidden?: boolean;
-  /**
-   * Should watching prevent normal exiting, until watch is removed?
-   */
-  persistent?: boolean;
 };
 
-/**
- * Watch files for a given folder
- * @param folder
- * @param onEvent
- * @param options
- */
-export async function watchFolderImmediate(
-  folder: string,
-  onEvent: WatchEventListener,
-  options: WatchConfig = {}
-): Promise<() => Promise<void>> {
+export type WatchStream = AsyncIterable<WatchEvent> & { close: () => Promise<void> };
 ```
 
 This method allows for watching one or more folders, and registering a callback that will fire every time a file changes, and which of the registered folders it was triggered within. The return of the `watchFolders` is a cleanup method, that when invoked will remove and stop all watching behavior.
 
+**Code: Watch Configuration**
+```typescript
+export function watchFolders(
+  folders: string[] | WatchFolder[],
+  config: Omit<WatchFolder, 'src' | 'target'> = {}
+): WatchStream {
+```
+
 ## Anatomy of a Manifest
 
 **Code: Manifest for @travetto/manifest**
@@ -149,6 +153,9 @@ This method allows for watching one or more folders, and registering a callback
   "toolFolder": ".trv_build",
   "compilerFolder": ".trv_compiler",
   "packageManager": "npm",
+  "version": "3.1.0-rc.0",
+  "description": "Support for project indexing, manifesting, along with file watching",
+  "frameworkVersion": "3.1.0-rc.0",
   "modules": {
     "@travetto/manifest": {
       "main": true,
@@ -238,19 +245,19 @@ The modules represent all of the [Travetto](https://travetto.dev)-aware dependen
 
 ### Module Files
 The module files are a simple categorization of files into a predetermined set of folders:
-   *  $root - All uncategorized files at the module root
-   *  $index - __index__.ts, index.ts files at the root of the project
-   *  $package - The [Package JSON](https://docs.npmjs.com/cli/v9/configuring-npm/package-json) for the project
-   *  src - Code that should be automatically loaded at runtime. All .ts files under the src/ folder
-   *  test - Code that contains test files. All .ts files under the test/ folder
-   *  test/fixtures - Test resource files, pertains to the main module only. Located under test/fixtures/
-   *  resources - Packaged resource, meant to pertain to the main module only. Files, under resources/
-   *  support - All .ts files under the support/ folder
-   *  support/resources - Packaged resource files, meant to be included by other modules, under support/resources/
-   *  support/fixtures - Test resources meant to shared across modules.  Under support/fixtures/
-   *  doc - Documentation files. All .ts files under the doc/ folder
-   *  $transformer - All .ts files under the pattern support/transform*.  These are used during compilation and never at runtime
-   *  bin - Entry point .js files.  All .js files under the bin/ folder
+   *  `$root` - All uncategorized files at the module root
+   *  `$index` - `__index__.ts`, `index.ts` files at the root of the project
+   *  `$package` - The [Package JSON](https://docs.npmjs.com/cli/v9/configuring-npm/package-json) for the project
+   *  `src` - Code that should be automatically loaded at runtime. All .ts files under the `src/` folder
+   *  `test` - Code that contains test files. All .ts files under the `test/` folder
+   *  `test/fixtures` - Test resource files, pertains to the main module only. Located under `test/fixtures/`
+   *  `resources` - Packaged resource, meant to pertain to the main module only. Files, under `resources/`
+   *  `support` - All .ts files under the `support/` folder
+   *  `support/resources` - Packaged resource files, meant to be included by other modules, under `support/resources/`
+   *  `support/fixtures` - Test resources meant to shared across modules.  Under `support/fixtures/`
+   *  `doc` - Documentation files. `DOC.tsx` and All .ts/.tsx files under the `doc/` folder
+   *  `$transformer` - All .ts files under the pattern `support/transform*`.  These are used during compilation and never at runtime
+   *  `bin` - Entry point .js files.  All .js files under the `bin/` folder
 Within each file there is a pattern of either a 3 or 4 element array:
 
 **Code: Sample file**

package/bin/context.js

@@ -23,20 +23,27 @@ async function $getPkg(inputFolder) {
 const WS_ROOT = {};
 
 /**
- * Get module name from a given file
- * @param {string} file
- * @return {Promise<string|void>}
+ * Get module root for a given folder
+ * @param {string} dir
+ * @return {Promise<string>}
  */
-async function $getModuleFromFile(file) {
-  let dir = path.dirname(file);
+async function $getModuleRoot(dir) {
   let prev;
   while (dir !== prev && !(await fs.stat(path.resolve(dir, 'package.json')).catch(() => false))) {
     prev = dir;
     dir = path.dirname(dir);
   }
-  try {
-    return (await $getPkg(dir)).name;
-  } catch { }
+  return dir;
+}
+
+
+/**
+ * Get module name from a given file
+ * @param {string} file
+ * @return {Promise<string|void>}
+ */
+async function $getModuleFromFile(file) {
+  return $getPkg(await $getModuleRoot(path.dirname(file))).then(v => v.name, () => { });
 }
 
 /**
@@ -74,6 +81,7 @@ async function $getWorkspaceRoot(base = process.cwd()) {
  */
 export async function getManifestContext(folder) {
   const workspacePath = path.resolve(await $getWorkspaceRoot(folder));
+  const req = createRequire(`${workspacePath}/node_modules`);
 
   // If manifest specified via env var, and is a package name
   if (!folder && process.env.TRV_MODULE) {
@@ -81,7 +89,6 @@ export async function getManifestContext(folder) {
     if (/[.](t|j)s$/.test(process.env.TRV_MODULE)) {
       process.env.TRV_MODULE = await $getModuleFromFile(process.env.TRV_MODULE) ?? process.env.TRV_MODULE;
     }
-    const req = createRequire(`${workspacePath}/node_modules`);
     try {
       folder = path.dirname(req.resolve(`${process.env.TRV_MODULE}/package.json`));
     } catch {
@@ -94,8 +101,8 @@ export async function getManifestContext(folder) {
     }
   }
 
-  const mainPath = path.resolve(folder ?? '.');
-  const { name: mainModule, workspaces, travetto } = (await $getPkg(mainPath));
+  const mainPath = await $getModuleRoot(path.resolve(folder ?? '.'));
+  const { name: mainModule, workspaces, travetto, version, description } = (await $getPkg(mainPath));
   const monoRepo = workspacePath !== mainPath || !!workspaces;
   const outputFolder = travetto?.outputFolder ?? '.trv_output';
 
@@ -104,6 +111,8 @@ export async function getManifestContext(folder) {
   /** @type {'yarn'|'npm'} */
   const packageManager = await fs.stat(path.resolve(workspacePath, 'yarn.lock')).then(() => 'yarn', () => 'npm');
 
+  const { version: frameworkVersion } = JSON.parse(await fs.readFile(req.resolve('@travetto/manifest/package.json'), 'utf8'));
+
   const res = {
     moduleType,
     mainModule: mainModule ?? 'untitled', // When root package.json is missing a name
@@ -113,7 +122,10 @@ export async function getManifestContext(folder) {
     outputFolder,
     toolFolder: '.trv_build',
     compilerFolder: '.trv_compiler',
-    packageManager
+    packageManager,
+    version,
+    description,
+    frameworkVersion
   };
   return res;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/manifest",
-  "version": "3.0.3",
+  "version": "3.1.0-rc.1",
   "description": "Support for project indexing, manifesting, along with file watching",
   "keywords": [
     "path",

package/src/dependencies.ts

@@ -39,9 +39,12 @@ export class ModuleDependencyVisitor implements PackageVisitor<ModuleDep> {
       .map(x => new RegExp(`^${x.replace(/[*]/g, '.*?')}$`));
   }
 
-  constructor(public ctx: ManifestContext) { }
+  constructor(public ctx: ManifestContext) {
+    this.#mainSourcePath = path.resolve(this.ctx.workspacePath, this.ctx.mainFolder);
+  }
 
   #mainPatterns: RegExp[] = [];
+  #mainSourcePath: string;
 
   /**
    * Initialize visitor, and provide global dependencies
@@ -76,7 +79,7 @@ export class ModuleDependencyVisitor implements PackageVisitor<ModuleDep> {
    * Is valid dependency for searching
    */
   valid(req: PackageVisitReq<ModuleDep>): boolean {
-    return req.sourcePath === path.cwd() || (
+    return req.sourcePath === this.#mainSourcePath || (
       req.rel !== 'peer' &&
       (!!req.pkg.travetto || req.pkg.private === true || !req.sourcePath.includes('node_modules') || req.rel === 'global')
     );

package/src/manifest-index.ts

@@ -261,7 +261,7 @@ export class ManifestIndex {
     return name ? this.getModule(name) : undefined;
   }
   /**
-   * Build module list from an expression list (e.g. `@travetto/app,-@travetto/log)
+   * Build module list from an expression list (e.g. `@travetto/rest,-@travetto/log)
    */
   getModuleList(mode: 'local' | 'all', exprList: string = ''): Set<string> {
     const allMods = Object.keys(this.#manifest.modules);

package/src/package.ts

@@ -3,16 +3,24 @@ import fs from 'fs/promises';
 import { createRequire } from 'module';
 import { execSync } from 'child_process';
 
-import { ManifestContext, Package, PackageDigest, PackageRel, PackageVisitor, PackageVisitReq, PackageWorkspaceEntry } from './types';
+import { ManifestContext, Package, PackageRel, PackageVisitor, PackageVisitReq, PackageWorkspaceEntry } from './types';
 import { path } from './path';
 
+/**
+ * Utilities for querying, traversing and reading package.json files.
+ */
 export class PackageUtil {
 
   static #req = createRequire(path.resolve('node_modules'));
-  static #framework: Package;
   static #cache: Record<string, Package> = {};
   static #workspaces: Record<string, PackageWorkspaceEntry[]> = {};
 
+  static #exec<T>(cwd: string, cmd: string): Promise<T> {
+    const env = { PATH: process.env.PATH, NODE_PATH: process.env.NODE_PATH };
+    const text = execSync(cmd, { cwd, encoding: 'utf8', env, stdio: ['pipe', 'pipe'] }).toString().trim();
+    return JSON.parse(text);
+  }
+
   /**
    * Clear out cached package file reads
    */
@@ -108,18 +116,6 @@ export class PackageUtil {
     return this.readPackage(this.resolvePackagePath(moduleName));
   }
 
-  /**
-   * Write package
-   */
-  static async writePackageIfChanged(modulePath: string, pkg: Package): Promise<void> {
-    const final = JSON.stringify(pkg, null, 2);
-    const target = path.resolve(modulePath, 'package.json');
-    const current = (await fs.readFile(target, 'utf8').catch(() => '')).trim();
-    if (final !== current) {
-      await fs.writeFile(target, `${final}\n`, 'utf8');
-    }
-  }
-
   /**
    * Visit packages with ability to track duplicates
    */
@@ -158,21 +154,6 @@ export class PackageUtil {
     return (await visitor.complete?.(out)) ?? out;
   }
 
-  /**
-   * Get version of manifest package
-   */
-  static getFrameworkVersion(): string {
-    return (this.#framework ??= this.importPackage('@travetto/manifest')).version;
-  }
-
-  /**
-   * Produce simple digest of
-   */
-  static digest(pkg: Package): PackageDigest {
-    const { main, name, author, license, version } = pkg;
-    return { name, main, author, license, version, framework: this.getFrameworkVersion() };
-  }
-
   /**
    * Find workspace values from rootPath
    */
@@ -186,15 +167,13 @@ export class PackageUtil {
         let out: PackageWorkspaceEntry[];
         switch (ctx.packageManager) {
           case 'npm': {
-            const text = execSync('npm query .workspace', { cwd: rootPath, encoding: 'utf8', env: { PATH: process.env.PATH, NODE_PATH: process.env.NODE_PATH } });
-            out = JSON.parse(text)
-              .map((d: { location: string, name: string }) => ({ sourcePath: d.location, name: d.name }));
+            const res = await this.#exec<{ location: string, name: string }[]>(rootPath, 'npm query .workspace');
+            out = res.map(d => ({ sourcePath: d.location, name: d.name }));
             break;
           }
           case 'yarn': {
-            const text = execSync('yarn -s workspaces info', { cwd: rootPath, encoding: 'utf8', env: { PATH: process.env.PATH, NODE_PATH: process.env.NODE_PATH } });
-            out = Object.entries<{ location: string }>(JSON.parse(text))
-              .map(([name, { location }]) => ({ sourcePath: location, name }));
+            const res = await this.#exec<Record<string, { location: string }>>(rootPath, 'npm query .workspace');
+            out = Object.entries(res).map(([name, { location }]) => ({ sourcePath: location, name }));
             break;
           }
         }
@@ -206,34 +185,4 @@ export class PackageUtil {
     }
     return this.#workspaces[rootPath];
   }
-
-  /**
-   * Sync versions across a series of folders
-   */
-  static async syncVersions(folders: string[], versionMapping: Record<string, string> = {}): Promise<void> {
-    const packages = folders.map(folder => {
-      const pkg = this.readPackage(folder, true);
-      versionMapping[pkg.name] = `^${pkg.version}`;
-      return { folder, pkg };
-    });
-
-    for (const { pkg } of packages) {
-      for (const group of [
-        pkg.dependencies ?? {},
-        pkg.devDependencies ?? {},
-        pkg.optionalDependencies ?? {},
-        pkg.peerDependencies ?? {}
-      ]) {
-        for (const [mod, ver] of Object.entries(versionMapping)) {
-          if (mod in group && !/^[*]|(file:.*)$/.test(group[mod])) {
-            group[mod] = ver;
-          }
-        }
-      }
-    }
-
-    for (const { folder, pkg } of packages) {
-      await this.writePackageIfChanged(folder, pkg);
-    }
-  }
 }

package/src/root-index.ts

@@ -1,7 +1,6 @@
 import { path } from './path';
 import { IndexedModule, ManifestIndex } from './manifest-index';
-import { FunctionMetadata, Package, PackageDigest } from './types';
-import { PackageUtil } from './package';
+import { FunctionMetadata, ManifestContext, Package } from './types';
 
 const METADATA = Symbol.for('@travetto/manifest:metadata');
 type Metadated = { [METADATA]: FunctionMetadata };
@@ -11,7 +10,6 @@ type Metadated = { [METADATA]: FunctionMetadata };
  */
 class $RootIndex extends ManifestIndex {
 
-  #config: Package | undefined;
   #metadata = new Map<string, FunctionMetadata>();
 
   /**
@@ -20,7 +18,6 @@ class $RootIndex extends ManifestIndex {
    */
   reinitForModule(module: string): void {
     this.init(`${this.outputRoot}/node_modules/${module}`);
-    this.#config = undefined;
   }
 
   /**
@@ -49,32 +46,28 @@ class $RootIndex extends ManifestIndex {
   }
 
   /**
-   * Get main module for manifest
+   * Get main module name
    */
-  get mainModule(): IndexedModule {
-    return this.getModule(this.mainPackage.name)!;
+  get mainModuleName(): string {
+    return this.manifest.mainModule;
   }
 
   /**
-   * Get main package for manifest
+   * Get main module for manifest
    */
-  get mainPackage(): Package {
-    if (!this.#config) {
-      const { outputPath } = this.getModule(this.manifest.mainModule)!;
-      this.#config = {
-        ...{
-          name: 'untitled',
-          description: 'A Travetto application',
-          version: '0.0.0',
-        },
-        ...PackageUtil.readPackage(outputPath)
-      };
-    }
-    return this.#config;
+  get mainModule(): IndexedModule {
+    return this.getModule(this.mainModuleName)!;
   }
 
-  mainDigest(): PackageDigest {
-    return PackageUtil.digest(this.mainPackage);
+  /**
+   * Digest manifest
+   */
+  manifestDigest(): Pick<ManifestContext, 'mainModule' | 'frameworkVersion' | 'version'> {
+    return {
+      mainModule: this.manifest.mainModule,
+      frameworkVersion: this.manifest.frameworkVersion,
+      version: this.manifest.version,
+    };
   }
 
   /**

package/src/types.ts

@@ -35,6 +35,9 @@ export type ManifestContext = {
   monoRepo?: boolean;
   moduleType: 'module' | 'commonjs';
   packageManager: 'yarn' | 'npm';
+  frameworkVersion: string;
+  description: string;
+  version: string;
 };
 
 export type ManifestRoot = ManifestContext & {
@@ -86,9 +89,6 @@ export type Package = {
   publishConfig?: { access?: 'restricted' | 'public' };
 };
 
-export type PackageDigestField = 'name' | 'main' | 'author' | 'license' | 'version';
-export type PackageDigest = Pick<Package, PackageDigestField> & { framework: string };
-
 type OrProm<T> = T | Promise<T>;
 
 export type PackageVisitReq<T> = { pkg: Package, rel: PackageRel, sourcePath: string, parent?: T };

package/src/util.ts

@@ -76,6 +76,7 @@ export class ManifestUtil {
       file = path.resolve(file, MANIFEST_FILE);
     }
     const manifest: ManifestRoot = JSON.parse(readFileSync(file, 'utf8'));
+    // Support packaged environments, by allowing empty outputFolder
     if (!manifest.outputFolder) {
       manifest.outputFolder = path.cwd();
       manifest.workspacePath = path.cwd();

package/src/watch.ts

@@ -1,5 +1,6 @@
 import { watch, Stats } from 'fs';
 import fs from 'fs/promises';
+
 import { path } from './path';
 
 async function getWatcher(): Promise<typeof import('@parcel/watcher')> {
@@ -11,15 +12,25 @@ async function getWatcher(): Promise<typeof import('@parcel/watcher')> {
   }
 }
 
-export type WatchEvent = { action: 'create' | 'update' | 'delete', file: string };
-export type WatchEventFilter = (ev: WatchEvent) => boolean;
+export type WatchEvent = { action: 'create' | 'update' | 'delete', file: string, folder: string };
 
-export type WatchEventListener = (ev: WatchEvent, folder: string) => void;
-export type WatchConfig = {
+export type WatchFolder = {
+  /**
+   * Source folder
+   */
+  src: string;
+  /**
+   * Target folder name, useful for deconstructing
+   */
+  target?: string;
+  /**
+   * Filter events
+   */
+  filter?: (ev: WatchEvent) => boolean;
   /**
-   * Predicate for filtering events
+   * Only look at immediate folder
    */
-  filter?: WatchEventFilter;
+  immediate?: boolean;
   /**
    * List of top level folders to ignore
    */
@@ -32,25 +43,66 @@ export type WatchConfig = {
    * Include files that start with '.'
    */
   includeHidden?: boolean;
-  /**
-   * Should watching prevent normal exiting, until watch is removed?
-   */
-  persistent?: boolean;
 };
 
+export type WatchStream = AsyncIterable<WatchEvent> & { close: () => Promise<void> };
+
+const DEDUPE_THRESHOLD = 50;
+
+class Queue<X> implements AsyncIterator<X>, AsyncIterable<X> {
+  #queue: X[] = [];
+  #done = false;
+  #ready: Promise<void>;
+  #fire: (() => void);
+  #onClose: (() => (void | Promise<void>))[] = [];
+  #recentKeys = new Map<string, number>();
+
+  constructor() {
+    this.#ready = new Promise(r => this.#fire = r);
+  }
+
+  // Allow for iteration
+  [Symbol.asyncIterator](): AsyncIterator<X> { return this; }
+
+  async next(): Promise<IteratorResult<X>> {
+    while (!this.#done && !this.#queue.length) {
+      this.#recentKeys = new Map([...this.#recentKeys.entries()] // Cull before waiting
+        .filter(([, time]) => (Date.now() - time) < DEDUPE_THRESHOLD));
+      await this.#ready;
+      this.#ready = new Promise(r => this.#fire = r);
+    }
+    return { value: this.#queue.shift()!, done: this.#done };
+  }
+
+  add(item: X | X[]): void {
+    const now = Date.now();
+    for (const value of Array.isArray(item) ? item : [item]) {
+      const key = JSON.stringify(value);
+      if ((now - (this.#recentKeys.get(key) ?? 0)) > DEDUPE_THRESHOLD) {
+        this.#queue.push(value);
+        this.#recentKeys.set(key, now);
+        this.#fire();
+      }
+    }
+  }
+
+  registerOnClose(handler: () => (void | Promise<void>)): void {
+    this.#onClose.push(handler);
+  }
+
+  async close(): Promise<void> {
+    this.#done = true;
+    this.#fire();
+    await Promise.all(this.#onClose.map(x => x()));
+  }
+}
+
 /**
- * Watch files for a given folder
- * @param folder
- * @param onEvent
- * @param options
+ * Watch immediate files for a given folder
  */
-export async function watchFolderImmediate(
-  folder: string,
-  onEvent: WatchEventListener,
-  options: WatchConfig = {}
-): Promise<() => Promise<void>> {
-  const watchPath = path.resolve(folder);
-  const watcher = watch(watchPath, { persistent: options.persistent, encoding: 'utf8' });
+async function watchFolderImmediate(queue: Queue<WatchEvent>, options: WatchFolder): Promise<void> {
+  const watchPath = path.resolve(options.src);
+  const watcher = watch(watchPath, { persistent: true, encoding: 'utf8' });
   const lastStats: Record<string, Stats | undefined> = {};
   const invalidFilter = (el: string): boolean =>
     (el === '.' || el === '..' || (!options.includeHidden && el.startsWith('.')) || !!options.ignore?.includes(el));
@@ -62,6 +114,9 @@ export async function watchFolderImmediate(
     const file = path.resolve(watchPath, el);
     lastStats[file] = await fs.stat(file);
   }
+
+  const target = options.target ?? options.src;
+
   watcher.on('change', async (type: string, file: string): Promise<void> => {
     if (invalidFilter(file)) {
       return;
@@ -78,69 +133,73 @@ export async function watchFolderImmediate(
     }
     let ev: WatchEvent;
     if (prevStat && !stat) {
-      ev = { action: 'delete', file };
+      ev = { action: 'delete', file, folder: target };
     } else if (!prevStat && stat) {
-      ev = { action: 'create', file };
+      ev = { action: 'create', file, folder: target };
     } else {
-      ev = { action: 'update', file };
+      ev = { action: 'update', file, folder: target };
     }
     if (!options.filter || options.filter(ev)) {
-      onEvent(ev, folder);
+      queue.add(ev);
     }
   });
-  process.on('exit', () => watcher.close());
-  return async () => watcher.close();
+
+  queue.registerOnClose(() => watcher.close());
 }
 
 /**
- * Leverages @parcel/watcher to watch a series of folders
- * @param folders
- * @param onEvent
- * @param options
+ * Watch recursive files for a given folder
  */
-export async function watchFolders(
-  folders: string[] | [folder: string, targetFolder: string][] | (readonly [folder: string, targetFolder: string])[],
-  onEvent: WatchEventListener,
-  config: WatchConfig = {}
-): Promise<() => Promise<void>> {
+async function watchFolderRecursive(queue: Queue<WatchEvent>, options: WatchFolder): Promise<void> {
   const lib = await getWatcher();
-  const createMissing = config.createMissing ?? false;
-  const validFolders = new Set(folders.map(x => typeof x === 'string' ? x : x[0]));
-
-  const subs = await Promise.all(folders.map(async value => {
-    const folder = typeof value === 'string' ? value : value[0];
-    const targetFolder = typeof value === 'string' ? value : value[1];
-
-    if (await fs.stat(folder).then(() => true, () => createMissing)) {
-      await fs.mkdir(folder, { recursive: true });
-      const ignore = (await fs.readdir(folder)).filter(x => x.startsWith('.') && x.length > 2);
-      return lib.subscribe(folder, (err, events) => {
-        for (const ev of events) {
-          const finalEv = { action: ev.type, file: path.toPosix(ev.path) };
-          if (ev.type === 'delete' && validFolders.has(finalEv.file)) {
-            return process.exit(0); // Exit when watched folder is removed
-          }
-          const isHidden = !config.includeHidden && finalEv.file.replace(targetFolder, '').includes('/.');
-          const matches = !isHidden && (!config.filter || config.filter(finalEv));
-          if (matches) {
-            onEvent(finalEv, targetFolder);
+  const target = options.target ?? options.src;
+
+  if (await fs.stat(options.src).then(() => true, () => options.createMissing)) {
+    await fs.mkdir(options.src, { recursive: true });
+    const ignore = (await fs.readdir(options.src)).filter(x => x.startsWith('.') && x.length > 2);
+    const cleanup = await lib.subscribe(options.src, async (err, events) => {
+      for (const ev of events) {
+        const finalEv = { action: ev.type, file: path.toPosix(ev.path), folder: target };
+        if (ev.type !== 'delete') {
+          const stats = await fs.stat(finalEv.file);
+          if ((stats.ctimeMs - Date.now()) < DEDUPE_THRESHOLD) {
+            ev.type = 'create'; // Force create on newly stated files
           }
         }
-      }, { ignore: [...ignore, ...config.ignore ?? []] });
-    }
-  }));
-
-  // Allow for multiple calls
-  let finalProm: Promise<void> | undefined;
-  const remove = (): Promise<void> => finalProm ??= Promise.all(subs.map(x => x?.unsubscribe())).then(() => { });
 
-  // Cleanup on intent to exit
-  if (!config.persistent) {
-    process.on('SIGUSR2', remove);
+        if (ev.type === 'delete' && finalEv.file === options.src) {
+          return queue.close();
+        }
+        const isHidden = !options.includeHidden && finalEv.file.replace(target, '').includes('/.');
+        const matches = !isHidden && (!options.filter || options.filter(finalEv));
+        if (matches) {
+          queue.add(finalEv);
+        }
+      }
+    }, { ignore: [...ignore, ...options.ignore ?? []] });
+    queue.registerOnClose(() => cleanup.unsubscribe());
   }
+}
 
-  // Cleanup on exit
-  process.on('exit', remove);
-
-  return remove;
+/**
+ * Watch a series of folders
+ * @param folders
+ * @param onEvent
+ * @param options
+ */
+export function watchFolders(
+  folders: string[] | WatchFolder[],
+  config: Omit<WatchFolder, 'src' | 'target'> = {}
+): WatchStream {
+  const queue = new Queue<WatchEvent>();
+  for (const folder of folders) {
+    if (typeof folder === 'string') {
+      watchFolderRecursive(queue, { ...config, src: folder });
+    } else if (!folder.immediate) {
+      watchFolderRecursive(queue, { ...config, ...folder });
+    } else {
+      watchFolderImmediate(queue, { ...config, ...folder });
+    }
+  }
+  return queue;
 }