@decohere/flux 0.0.1-dev.125 → 0.0.1-dev.127

package/README.md

@@ -140,7 +140,7 @@ On a watched change that reaches a served entry, Flux invalidates that subgraph,
 
 Saves less than the window apart (250ms by default) become one reboot. Saves further apart each reboot, and a save during a reboot folds into one follow-up reboot. Whatever the timing, the app ends up on the last save; a reboot in between may fail (an import not yet updated) and logs the error.
 
-The window adds its length to every reload, including a single save. Measured on a rename across six files (#484):
+The window adds its length to every reload, including a single save. Measured on a rename across six files:
 
 | Gap between saves | Reboots at 250ms | Reboots at 2000ms |
 |---|---|---|
@@ -217,7 +217,7 @@ Logs name skipped libraries and deferred packages (script + cwd). Child processe
 
 ## Compile cache
 
-Flux keeps the code it compiles on disk, so starting again compiles only what changed (#514). On a cold start with nothing changed, it reads every file from the cache instead of compiling it (`pnpm bench flux-load`, `flux.load.cold-cached`).
+Flux keeps the code it compiles on disk, so starting again compiles only what changed. On a cold start with nothing changed, it reads every file from the cache instead of compiling it (`pnpm bench flux-load`, `flux.load.cold-cached`).
 
 - **Where:** `<workspace>/node_modules/.cache/decohere/flux`. When the workspace has no `node_modules`, it's under `$XDG_CACHE_HOME/decohere`, then the OS temp directory.
 - **Settings:** `DECOHERE_CACHE_DIR=<dir>` moves the cache; `DECOHERE_CACHE=0` turns it off.
@@ -240,7 +240,7 @@ Only source files (`.ts`) that a served entry imports trigger a reboot.
 
 **Memory grows over a long session.** Each reboot imports changed modules under a new `?version=` URL, and Node's ES module cache never releases the old versions. That's fine for a working day; if a session runs for days with thousands of reboots, restart it.
 
-Flux uses **Forge’s compiler**, with one SWC config per project built once per run. SWC leaves imports as written; Flux's resolve hook maps each one to its TypeScript source: `@scope/pkg` and `@scope/pkg/sub` through the the workspace package aliases (and tsconfig `paths`), `./file.js` and `./file` to `file.ts` or `file.tsx`, `./file.mjs` to `file.mts`, `./file.cjs` to `file.cts` (which runs as CommonJS), and `./dir` to `dir/index.ts`. Doing it in one place, instead of in SWC (`jsc.paths`, `resolveFully`) and again in the hook, made loading about 20% faster once Node and SWC are warm (`pnpm bench flux-load`, #513). Before Node imports an entry, Flux compiles it and the files it imports, following their imports out from the entry, in parallel on SWC's thread pool (#661). The load hook is synchronous and would otherwise compile one file at a time; files the app never imports, such as tests, are not compiled. A file that fails to compile there is compiled again when Node loads it, and that load fails with the file's name, as before. That is a debug rule so you can edit a library and hit HMR without a pre-build or `node_modules` workspace symlink. Release still resolves through real `node_modules` (published `exports` / `main`).
+Flux uses **Forge’s compiler**, with one SWC config per project built once per run. SWC leaves imports as written; Flux's resolve hook maps each one to its TypeScript source: `@scope/pkg` and `@scope/pkg/sub` through the the workspace package aliases (and tsconfig `paths`), `./file.js` and `./file` to `file.ts` or `file.tsx`, `./file.mjs` to `file.mts`, `./file.cjs` to `file.cts` (which runs as CommonJS), and `./dir` to `dir/index.ts`. Doing it in one place, instead of in SWC (`jsc.paths`, `resolveFully`) and again in the hook, made loading about 20% faster once Node and SWC are warm (`pnpm bench flux-load`). Before Node imports an entry, Flux compiles it and the files it imports, following their imports out from the entry, in parallel on SWC's thread pool. The load hook is synchronous and would otherwise compile one file at a time; files the app never imports, such as tests, are not compiled. A file that fails to compile there is compiled again when Node loads it, and that load fails with the file's name, as before. That is a debug rule so you can edit a library and hit HMR without a pre-build or `node_modules` workspace symlink. Release still resolves through real `node_modules` (published `exports` / `main`).
 
 Why aliases, and a tree of where a symlink misses `src/index.ts`: [Forge — debug path aliases](../forge/README.md#debug-path-aliases-not-node_modules-links).
 

package/commonjs/src/flux.module.js

@@ -27,7 +27,7 @@ class FluxModule extends _cli.ModuleManifest {
         builder.registerSingleton(_deferredscriptrunner.DeferredScriptRunner);
     }
     createWorkspace(options) {
-        // Same workspace as `flux.run` / `flux.serve` and forge (#516).
+        // Same workspace as `flux.run` / `flux.serve` and forge.
         return (0, _forge.createWorkspace)(options);
     }
 }

package/commonjs/src/hot-reload-server.js

@@ -325,7 +325,7 @@ class HotReloadServer extends _nodeevents.EventEmitter {
     /**
 	 * A failed boot (e.g. importing a file that doesn't exist yet) may have recorded no
 	 * dependency edges, so the graph can't tell whether this save fixes it. Any source
-	 * add or change retries failed entries (#512).
+	 * add or change retries failed entries.
 	 */ retryFailedEntries(fullPath) {
         const failed = [
             ...this.entries.values()
@@ -369,7 +369,7 @@ class HotReloadServer extends _nodeevents.EventEmitter {
     // ── Dependency graph ─────────────────────────────────────────────────────
     /**
 	 * Every module that imports `moduleId`, directly or transitively. Visits each module
-	 * once: import graphs share modules (diamonds) and may legally contain cycles (#515).
+	 * once: import graphs share modules (diamonds) and may legally contain cycles.
 	 */ getDependencyGraph(moduleId) {
         if (this.isSelf(moduleId)) return [];
         const found = new Set();

package/commonjs/src/source-module-loader.js

@@ -83,7 +83,7 @@ class SourceModuleLoader {
     transpileCache = new Map();
     /** Bumped when a file's cached code is dropped, so an up-front compile already running can't put it back. */ transpileVersions = new Map();
     /** The source files each entry's walk reached, so a reboot only walks out from what changed. */ reachedFrom = new Map();
-    /** Compiled code on disk across runs (#514); null when caching is off. */ diskCache = null;
+    /** Compiled code on disk across runs; null when caching is off. */ diskCache = null;
     /** Up-front compiles in flight, shared by entries booting at the same time. */ compilingAhead = new Map();
     /** SWC options per project, built on first use and kept until the next `configure()`. */ swcConfigs = new Map();
     commonJsConfigs = new Map();
@@ -128,7 +128,7 @@ class SourceModuleLoader {
         if (this.hooksRegistered) return;
         this.hooksRegistered = true;
         // Compiled code carries inline source maps; Node only applies them to stack traces when
-        // this is on. Without it, errors point at compiled line numbers (#506).
+        // this is on. Without it, errors point at compiled line numbers.
         process.setSourceMapsEnabled(true);
         (0, _nodemodule.registerHooks)({
             resolve: (specifier, context, next)=>{
@@ -194,7 +194,7 @@ class SourceModuleLoader {
         return new Map(entries.flat());
     }
     /**
-	 * Compiles the entry and the source files it imports, before Node imports it (#661). The load
+	 * Compiles the entry and the source files it imports, before Node imports it. The load
 	 * hook is synchronous, so it would compile one file at a time on the main thread; async SWC
 	 * runs on the thread pool. Walks out from the entry, compiling each file's imports in parallel,
 	 * so files the app never imports (tests, other apps) are not compiled. A reboot walks out only
@@ -259,7 +259,7 @@ class SourceModuleLoader {
     loadTs(url) {
         if (!url.startsWith("file:")) return null;
         // fileURLToPath, not URL.pathname: decodes %20 and gives Windows paths, so files
-        // whose path has a space still match the workspace's package list (#511).
+        // whose path has a space still match the workspace's package list.
         const cleanPath = (0, _nodeurl.fileURLToPath)(url);
         const fileInfo = this.fileInfoMap.get(cleanPath);
         if (fileInfo == null) return null;
@@ -277,7 +277,7 @@ class SourceModuleLoader {
         };
     }
     /**
-	 * Compiles a file for the load hook, through the disk cache (#514). Throws, naming the file,
+	 * Compiles a file for the load hook, through the disk cache. Throws, naming the file,
 	 * when it can't be read or doesn't compile.
 	 */ compileSync(fullPath, project) {
         const file = new _io.FileEx({
@@ -308,7 +308,7 @@ class SourceModuleLoader {
 	 * Compiles a file ahead, through the disk cache; undefined when it doesn't compile, which the
 	 * load hook then reports (see {@link compileAhead}). The source and the cache entry are read
 	 * synchronously: for small files that is far cheaper than a trip through libuv's thread pool,
-	 * which async SWC needs for the compiles that miss (#514).
+	 * which async SWC needs for the compiles that miss.
 	 */ async compileAsync(fullPath, project) {
         const file = new _io.FileEx({
             fullPath
@@ -332,13 +332,13 @@ class SourceModuleLoader {
     }
     /**
 	 * The project's SWC options, built once: rebuilding them for every file was about a quarter
-	 * of load time (#513). Import specifiers are left as written, without `jsc.paths` or
+	 * of load time. Import specifiers are left as written, without `jsc.paths` or
 	 * `resolveFully`: the resolve hook maps them to source files (aliases, `.js` to `.ts`,
 	 * directory indexes), so SWC does not resolve them a second time against the disk.
 	 */ swcConfigFor(project, fullPath) {
         const config = this.esModuleConfigFor(project);
         if (!_workspace.sourceExtensions.isCommonJs(fullPath)) return config;
-        // `.cts` is CommonJS: Node loads it with `require` semantics, so SWC emits CommonJS (#518).
+        // `.cts` is CommonJS: Node loads it with `require` semantics, so SWC emits CommonJS.
         // Kept per project, like the ES module options, so the disk cache hashes them once.
         const cached = this.commonJsConfigs.get(project);
         if (cached != null) return cached;

package/commonjs/src/static-imports.js

@@ -12,7 +12,7 @@ Object.defineProperty(exports, "staticImports", {
  * The module specifiers a compiled ES module names in `import … from`, `export … from`, bare
  * `import "x"` and literal `import("x")`.
  *
- * Only a hint for compiling ahead (#661): a specifier it misses is compiled when Node loads it,
+ * Only a hint for compiling ahead: a specifier it misses is compiled when Node loads it,
  * and one it finds by mistake (an import written inside a string) costs one extra compile. So a
  * scan of SWC's output is enough; it never decides what runs.
  */ const STATIC = /\b(?:import|export)\s*(?:[\w$*{},\s]+?\s*from\s*)?["']([^"'\n]+)["']/g;

package/es6/src/flux.module.js

@@ -17,7 +17,7 @@ export class FluxModule extends ModuleManifest {
         builder.registerSingleton(DeferredScriptRunner);
     }
     createWorkspace(options) {
-        // Same workspace as `flux.run` / `flux.serve` and forge (#516).
+        // Same workspace as `flux.run` / `flux.serve` and forge.
         return createWorkspace(options);
     }
 }

package/es6/src/hot-reload-server.js

@@ -293,7 +293,7 @@ export class HotReloadServer extends EventEmitter {
     /**
 	 * A failed boot (e.g. importing a file that doesn't exist yet) may have recorded no
 	 * dependency edges, so the graph can't tell whether this save fixes it. Any source
-	 * add or change retries failed entries (#512).
+	 * add or change retries failed entries.
 	 */ retryFailedEntries(fullPath) {
         const failed = [
             ...this.entries.values()
@@ -337,7 +337,7 @@ export class HotReloadServer extends EventEmitter {
     // ── Dependency graph ─────────────────────────────────────────────────────
     /**
 	 * Every module that imports `moduleId`, directly or transitively. Visits each module
-	 * once: import graphs share modules (diamonds) and may legally contain cycles (#515).
+	 * once: import graphs share modules (diamonds) and may legally contain cycles.
 	 */ getDependencyGraph(moduleId) {
         if (this.isSelf(moduleId)) return [];
         const found = new Set();

package/es6/src/rewrite-serve-specifier.js

@@ -5,7 +5,7 @@ import { packageAliases, sourceExtensions } from "@decohere/workspace";
  * Map a resolve-hook specifier to a versioned watched `.ts` file URL.
  * Covers relative `.js` / `.ts` / extensionless imports, directory imports (`./models` is
  * `./models/index.ts`), and bare workspace package names and subpaths. Flux compiles without
- * SWC's own path resolution, so this is the only place imports are mapped to sources (#513).
+ * SWC's own path resolution, so this is the only place imports are mapped to sources.
  */ export function rewriteServeSpecifier(options) {
     const { specifier, parentUrl, isWatchedTs, resolveBare, versionFileUrl } = options;
     const relativeTs = resolveRelativeWatchedTs(specifier, parentUrl, isWatchedTs);

package/es6/src/source-module-loader.js

@@ -27,7 +27,7 @@ export class SourceModuleLoader {
     transpileCache = new Map();
     /** Bumped when a file's cached code is dropped, so an up-front compile already running can't put it back. */ transpileVersions = new Map();
     /** The source files each entry's walk reached, so a reboot only walks out from what changed. */ reachedFrom = new Map();
-    /** Compiled code on disk across runs (#514); null when caching is off. */ diskCache = null;
+    /** Compiled code on disk across runs; null when caching is off. */ diskCache = null;
     /** Up-front compiles in flight, shared by entries booting at the same time. */ compilingAhead = new Map();
     /** SWC options per project, built on first use and kept until the next `configure()`. */ swcConfigs = new Map();
     commonJsConfigs = new Map();
@@ -72,7 +72,7 @@ export class SourceModuleLoader {
         if (this.hooksRegistered) return;
         this.hooksRegistered = true;
         // Compiled code carries inline source maps; Node only applies them to stack traces when
-        // this is on. Without it, errors point at compiled line numbers (#506).
+        // this is on. Without it, errors point at compiled line numbers.
         process.setSourceMapsEnabled(true);
         registerHooks({
             resolve: (specifier, context, next)=>{
@@ -138,7 +138,7 @@ export class SourceModuleLoader {
         return new Map(entries.flat());
     }
     /**
-	 * Compiles the entry and the source files it imports, before Node imports it (#661). The load
+	 * Compiles the entry and the source files it imports, before Node imports it. The load
 	 * hook is synchronous, so it would compile one file at a time on the main thread; async SWC
 	 * runs on the thread pool. Walks out from the entry, compiling each file's imports in parallel,
 	 * so files the app never imports (tests, other apps) are not compiled. A reboot walks out only
@@ -203,7 +203,7 @@ export class SourceModuleLoader {
     loadTs(url) {
         if (!url.startsWith("file:")) return null;
         // fileURLToPath, not URL.pathname: decodes %20 and gives Windows paths, so files
-        // whose path has a space still match the workspace's package list (#511).
+        // whose path has a space still match the workspace's package list.
         const cleanPath = fileURLToPath(url);
         const fileInfo = this.fileInfoMap.get(cleanPath);
         if (fileInfo == null) return null;
@@ -221,7 +221,7 @@ export class SourceModuleLoader {
         };
     }
     /**
-	 * Compiles a file for the load hook, through the disk cache (#514). Throws, naming the file,
+	 * Compiles a file for the load hook, through the disk cache. Throws, naming the file,
 	 * when it can't be read or doesn't compile.
 	 */ compileSync(fullPath, project) {
         const file = new FileEx({
@@ -252,7 +252,7 @@ export class SourceModuleLoader {
 	 * Compiles a file ahead, through the disk cache; undefined when it doesn't compile, which the
 	 * load hook then reports (see {@link compileAhead}). The source and the cache entry are read
 	 * synchronously: for small files that is far cheaper than a trip through libuv's thread pool,
-	 * which async SWC needs for the compiles that miss (#514).
+	 * which async SWC needs for the compiles that miss.
 	 */ async compileAsync(fullPath, project) {
         const file = new FileEx({
             fullPath
@@ -276,13 +276,13 @@ export class SourceModuleLoader {
     }
     /**
 	 * The project's SWC options, built once: rebuilding them for every file was about a quarter
-	 * of load time (#513). Import specifiers are left as written, without `jsc.paths` or
+	 * of load time. Import specifiers are left as written, without `jsc.paths` or
 	 * `resolveFully`: the resolve hook maps them to source files (aliases, `.js` to `.ts`,
 	 * directory indexes), so SWC does not resolve them a second time against the disk.
 	 */ swcConfigFor(project, fullPath) {
         const config = this.esModuleConfigFor(project);
         if (!sourceExtensions.isCommonJs(fullPath)) return config;
-        // `.cts` is CommonJS: Node loads it with `require` semantics, so SWC emits CommonJS (#518).
+        // `.cts` is CommonJS: Node loads it with `require` semantics, so SWC emits CommonJS.
         // Kept per project, like the ES module options, so the disk cache hashes them once.
         const cached = this.commonJsConfigs.get(project);
         if (cached != null) return cached;

package/es6/src/static-imports.js

@@ -2,7 +2,7 @@
  * The module specifiers a compiled ES module names in `import … from`, `export … from`, bare
  * `import "x"` and literal `import("x")`.
  *
- * Only a hint for compiling ahead (#661): a specifier it misses is compiled when Node loads it,
+ * Only a hint for compiling ahead: a specifier it misses is compiled when Node loads it,
  * and one it finds by mistake (an import written inside a string) costs one extra compile. So a
  * scan of SWC's output is enough; it never decides what runs.
  */ const STATIC = /\b(?:import|export)\s*(?:[\w$*{},\s]+?\s*from\s*)?["']([^"'\n]+)["']/g;

package/es6/src/transpile-disk-cache.js

@@ -8,7 +8,7 @@ import { scribe } from "@decohere/scribe";
 /** Pruning runs at most this often, recorded by the mtime of a marker file. */ const PRUNE_EVERY_MS = 24 * 60 * 60 * 1000;
 const PRUNE_MARKER = ".last-prune";
 /**
- * Compiled code on disk, so a cold start doesn't compile files that haven't changed (#514).
+ * Compiled code on disk, so a cold start doesn't compile files that haven't changed.
  * Content-addressed: the key hashes the file's path and source, the SWC options it compiles
  * with, SWC's version and this cache's format, so any change to those is a miss, never a stale
  * hit. Entries are written to a temp file and renamed into place, so a process reading an entry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/flux",
-  "version": "0.0.1-dev.125",
+  "version": "0.0.1-dev.127",
   "description": "Hot module reload server for Node.js ESM applications",
   "keywords": [
     "typescript",
@@ -34,12 +34,12 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/core": "0.0.1-dev.125",
-    "@decohere/crucible": "0.0.1-dev.125",
-    "@decohere/devkit": "0.0.1-dev.125",
-    "@decohere/forge": "0.0.1-dev.125",
-    "@decohere/scribe": "0.0.1-dev.125",
-    "@decohere/workspace": "0.0.1-dev.125",
+    "@decohere/core": "0.0.1-dev.127",
+    "@decohere/crucible": "0.0.1-dev.127",
+    "@decohere/devkit": "0.0.1-dev.127",
+    "@decohere/forge": "0.0.1-dev.127",
+    "@decohere/scribe": "0.0.1-dev.127",
+    "@decohere/workspace": "0.0.1-dev.127",
     "commander": "^13.1.0",
     "rxjs": "^7.8.2"
   },

package/types/src/hot-reload-server.d.ts

@@ -29,7 +29,7 @@ export interface HotReloadServerOptions {
     /**
      * Quiet window in milliseconds after the last affecting save before a reboot.
      * Defaults to {@link DEFAULT_REBOOT_DEBOUNCE_MS}. Every reload waits this long, so a larger
-     * window only pays off for saves known to come at a steady pace inside it (#484).
+     * window only pays off for saves known to come at a steady pace inside it.
      */
     rebootDebounceMs?: number;
 }
@@ -74,13 +74,13 @@ export declare class HotReloadServer extends EventEmitter<HotReloadServerEvents>
     /**
      * A failed boot (e.g. importing a file that doesn't exist yet) may have recorded no
      * dependency edges, so the graph can't tell whether this save fixes it. Any source
-     * add or change retries failed entries (#512).
+     * add or change retries failed entries.
      */
     private retryFailedEntries;
     private reloadIfAffected;
     /**
      * Every module that imports `moduleId`, directly or transitively. Visits each module
-     * once: import graphs share modules (diamonds) and may legally contain cycles (#515).
+     * once: import graphs share modules (diamonds) and may legally contain cycles.
      */
     private getDependencyGraph;
     private trackDependency;

package/types/src/rewrite-serve-specifier.d.ts

@@ -9,6 +9,6 @@ export type RewriteServeSpecifierOptions = {
  * Map a resolve-hook specifier to a versioned watched `.ts` file URL.
  * Covers relative `.js` / `.ts` / extensionless imports, directory imports (`./models` is
  * `./models/index.ts`), and bare workspace package names and subpaths. Flux compiles without
- * SWC's own path resolution, so this is the only place imports are mapped to sources (#513).
+ * SWC's own path resolution, so this is the only place imports are mapped to sources.
  */
 export declare function rewriteServeSpecifier(options: RewriteServeSpecifierOptions): string | null;

package/types/src/source-module-loader.d.ts

@@ -34,7 +34,7 @@ export declare class SourceModuleLoader {
     private transpileVersions;
     /** The source files each entry's walk reached, so a reboot only walks out from what changed. */
     private reachedFrom;
-    /** Compiled code on disk across runs (#514); null when caching is off. */
+    /** Compiled code on disk across runs; null when caching is off. */
     private diskCache;
     /** Up-front compiles in flight, shared by entries booting at the same time. */
     private compilingAhead;
@@ -56,7 +56,7 @@ export declare class SourceModuleLoader {
     dispose(): void;
     private buildFileInfoMap;
     /**
-     * Compiles the entry and the source files it imports, before Node imports it (#661). The load
+     * Compiles the entry and the source files it imports, before Node imports it. The load
      * hook is synchronous, so it would compile one file at a time on the main thread; async SWC
      * runs on the thread pool. Walks out from the entry, compiling each file's imports in parallel,
      * so files the app never imports (tests, other apps) are not compiled. A reboot walks out only
@@ -74,7 +74,7 @@ export declare class SourceModuleLoader {
     private sourcePathOf;
     private loadTs;
     /**
-     * Compiles a file for the load hook, through the disk cache (#514). Throws, naming the file,
+     * Compiles a file for the load hook, through the disk cache. Throws, naming the file,
      * when it can't be read or doesn't compile.
      */
     private compileSync;
@@ -82,12 +82,12 @@ export declare class SourceModuleLoader {
      * Compiles a file ahead, through the disk cache; undefined when it doesn't compile, which the
      * load hook then reports (see {@link compileAhead}). The source and the cache entry are read
      * synchronously: for small files that is far cheaper than a trip through libuv's thread pool,
-     * which async SWC needs for the compiles that miss (#514).
+     * which async SWC needs for the compiles that miss.
      */
     private compileAsync;
     /**
      * The project's SWC options, built once: rebuilding them for every file was about a quarter
-     * of load time (#513). Import specifiers are left as written, without `jsc.paths` or
+     * of load time. Import specifiers are left as written, without `jsc.paths` or
      * `resolveFully`: the resolve hook maps them to source files (aliases, `.js` to `.ts`,
      * directory indexes), so SWC does not resolve them a second time against the disk.
      */

package/types/src/transpile-disk-cache.d.ts

@@ -1,5 +1,5 @@
 /**
- * Compiled code on disk, so a cold start doesn't compile files that haven't changed (#514).
+ * Compiled code on disk, so a cold start doesn't compile files that haven't changed.
  * Content-addressed: the key hashes the file's path and source, the SWC options it compiles
  * with, SWC's version and this cache's format, so any change to those is a miss, never a stale
  * hit. Entries are written to a temp file and renamed into place, so a process reading an entry