@peisar/peisar-wasm32-wasi 0.2.22 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peisar/peisar-wasm32-wasi",
-  "version": "0.2.22",
+  "version": "0.3.0",
   "main": "peisar.wasi.cjs",
   "files": [
     "peisar.wasm32-wasi.wasm",
@@ -30,8 +30,8 @@
   "browser": "peisar.wasi-browser.js",
   "type": "module",
   "dependencies": {
-    "@napi-rs/wasm-runtime": "~1.2.4",
-    "@emnapi/core": "2.0.0-alpha.5",
-    "@emnapi/runtime": "2.0.0-alpha.5"
+    "@napi-rs/wasm-runtime": "~1.2.5",
+    "@emnapi/core": "2.0.0-alpha.6",
+    "@emnapi/runtime": "2.0.0-alpha.6"
   }
 }

package/peisar.wasi-browser.js

@@ -1441,6 +1441,7 @@ try {
 }
 export default __napiModule.exports
 export const Peisar = __napiModule.exports.Peisar
+export const PeisarCache = __napiModule.exports.PeisarCache
 export const EmphasisLevel = __napiModule.exports.EmphasisLevel
 export const TableCellAlignment = __napiModule.exports.TableCellAlignment
 export const TaskState = __napiModule.exports.TaskState

package/peisar.wasi.cjs

@@ -1,4 +1,4 @@
-// napi-rs-artifact-metadata:{"version":2,"rootEntry":"index.js","exports":["Peisar","EmphasisLevel","TableCellAlignment","TaskState"],"managedRootEntries":["browser.js","index.js","peisar.wasm","peisar.debug.wasm"]}
+// napi-rs-artifact-metadata:{"version":2,"rootEntry":"index.js","exports":["Peisar","PeisarCache","EmphasisLevel","TableCellAlignment","TaskState"],"managedRootEntries":["browser.js","index.js","peisar.wasm","peisar.debug.wasm"]}
 /* eslint-disable */
 /* auto-generated by NAPI-RS */
 
@@ -222,6 +222,34 @@ function __hasWasiThreadCrashed() {
 }
 
 let __wasiThreadCrashDisposePromise
+// Raised by the crash disposal right before it terminates the workers. See
+// `__wasiSetImmediate`.
+let __wasiReentryClosed = false
+
+/**
+ * emnapi's `features.setImmediate` for this binding's context. emnapi defers
+ * its calls back into wasm through it: `_emnapi_set_immediate` (libuv handle
+ * closes, threadsafe-function finalizers), threadsafe-function dispatch
+ * (`async-send`) and the finalizer queue. One queued before a crash disposal
+ * terminates the workers still runs after it, and a worker terminated while it
+ * held a lock in the wasm heap (napi's heap-sync allocator lock spins and never
+ * gives up) leaves that call spinning on this thread for good. The binding is
+ * unusable after a crash disposal, so those calls are dropped.
+ *
+ * Known residual, still able to enter wasm after a crash disposal because emnapi
+ * offers no hook for them: the `FinalizationRegistry` callbacks that free
+ * external memory when GC collects a value (`_free`, the shared-buffer meta
+ * release), threadsafe-function dispatch of `async-send` type 1 and
+ * `_emnapi_next_tick` (both `Promise.resolve().then`), and every deferred
+ * call under emnapi 1.x, whose `createContext` ignores `features`.
+ */
+function __wasiSetImmediate(callback) {
+  return setImmediate(function () {
+    if (!__wasiReentryClosed) {
+      callback()
+    }
+  })
+}
 
 /**
  * Stores the first error a pool worker reported, with the worker's id. Called
@@ -371,6 +399,8 @@ function __disposeWasiBindingAfterThreadCrash() {
     return __wasiThreadCrashDisposePromise
   }
   __releaseEmnapiWaitingRequestHandle()
+  // No call into wasm after this: see `__wasiSetImmediate`.
+  __wasiReentryClosed = true
   let workerResult
   try {
     workerResult = __terminateWasiWorkers()
@@ -455,6 +485,130 @@ function __rollbackWasiInitializationAfterThreadCrash() {
   return [crashError]
 }
 
+const __wasiThreadPoolReconcileSymbol = Symbol.for('napi.rs.wasi.reconcileThreadPool')
+
+/**
+ * Takes a Worker out of emnapi's reuse pool, if it is still there. emnapi
+ * terminates a pooled Worker that failed to load but (up to
+ * @emnapi/wasi-threads 2.1.0) leaves it in the pool, where the next thread
+ * spawn would pop it. A newer emnapi removes it itself, so this is a no-op
+ * then.
+ */
+function __removeWasiPoolWorker(manager, worker) {
+  const index = manager.unusedWorkers.indexOf(worker)
+  if (index !== -1) {
+    manager.unusedWorkers.splice(index, 1)
+  }
+}
+
+/**
+ * Takes a Worker the thread manager just terminated out of `__wasiWorkers`
+ * once it has exited, not before. `terminateWorker` only starts Node's
+ * asynchronous `worker.terminate()` and drops its promise, so a disposal that
+ * begins before the exit has to find this Worker in the set and wait for it
+ * like any other. A second `terminate()` settles when the Worker has exited,
+ * the way `__terminateWasiWorkers` waits.
+ */
+function __untrackWasiWorkerOnExit(worker) {
+  const terminated = worker.terminate()
+  if (__isThenable(terminated)) {
+    Promise.resolve(terminated).then(
+      () => {
+        __wasiWorkers.delete(worker)
+      },
+      // Left tracked: disposal terminates it again and reports the error.
+      () => {},
+    )
+  } else {
+    __wasiWorkers.delete(worker)
+  }
+}
+
+/**
+ * Matches emnapi's idle reuse pool to the addon's configured MultiThread worker
+ * count, which the addon exports as `napi_wasm_runtime_pool_workers`
+ * (napi-async-runtime; 0 under CurrentThread). `reuseWorker: true` starts the
+ * pool empty, so without this every pool thread the first async call spawns
+ * boots a Worker and loads the wasm into it first. Here each missing Worker is
+ * created and starts loading now; a spawn later pops one that is already
+ * booting. Idle Workers above the count are terminated, last in first out,
+ * the way a spawn takes them. A Worker a spawn already took is not in the pool
+ * and is left alone.
+ *
+ * Runs once after a successful load and, when the loader wraps it, after every
+ * successful `configureAsyncRuntime`. Also reachable as
+ * binding[Symbol.for('napi.rs.wasi.reconcileThreadPool')]().
+ * It never throws and never waits on a Worker: a Worker whose load fails is
+ * dropped from the pool when its load rejects. Nothing at all happens after a
+ * thread crash, once disposal started, or for an addon without the export.
+ */
+function __reconcileWasiThreadPool() {
+  try {
+    if (__wasiDisposed || __wasiDisposePromise || __hasWasiThreadCrashed()) {
+      return
+    }
+    const read = __napiInstance?.exports?.napi_wasm_runtime_pool_workers
+    if (typeof read !== 'function') {
+      return
+    }
+    const count = read() >>> 0
+    const manager = __getWasiThreadManager()
+    if (
+      !manager ||
+      !Array.isArray(manager.unusedWorkers) ||
+      typeof manager.allocateUnusedWorker !== 'function' ||
+      typeof manager.loadWasmModuleToWorker !== 'function'
+    ) {
+      return
+    }
+    // Both loops are bounded by the difference they start from, so a manager
+    // that does not update `unusedWorkers` the way emnapi does cannot spin.
+    for (let excess = manager.unusedWorkers.length - count; excess > 0; excess--) {
+      const worker = manager.unusedWorkers[manager.unusedWorkers.length - 1]
+      manager.terminateWorker(worker)
+      __removeWasiPoolWorker(manager, worker)
+      __untrackWasiWorkerOnExit(worker)
+      // Compatibility with @emnapi/wasi-threads 2.1.0 and older:
+      // `terminateWorker` installs a reporter that logs every emnapi message
+      // still queued on the port, so a Worker that finished loading just
+      // before it was terminated prints 'received "loaded" command from
+      // terminated worker'. Nothing listens for that Worker any more, and a
+      // newer emnapi ignores the late 'loaded' itself, so this is harmless
+      // there. `__terminateWasiWorkers` does the same.
+      worker.onmessage = undefined
+    }
+    for (let missing = count - manager.unusedWorkers.length; missing > 0; missing--) {
+      let worker
+      try {
+        // Through `onCreateWorker`: tracked in `__wasiWorkers`, unref'd, and
+        // handed the crash flags like any pool Worker.
+        worker = manager.allocateUnusedWorker()
+        manager
+          .loadWasmModuleToWorker(worker)
+          .then(undefined, () => __removeWasiPoolWorker(manager, worker))
+      } catch {
+        if (worker !== undefined) {
+          __removeWasiPoolWorker(manager, worker)
+          try {
+            manager.terminateWorker(worker)
+            __untrackWasiWorkerOnExit(worker)
+          } catch {}
+        }
+        return
+      }
+    }
+  } catch {}
+}
+
+function __publishWasiThreadPoolReconcile(exports) {
+  Object.defineProperty(exports, __wasiThreadPoolReconcileSymbol, {
+    configurable: false,
+    enumerable: false,
+    value: __reconcileWasiThreadPool,
+    writable: false,
+  })
+}
+
 const __cwd = process.cwd()
 const __rootDir = __nodePath.parse(__cwd).root
 const __hostRoot =
@@ -2011,7 +2165,7 @@ try {
   const __finishAutoDestroyCapture = __captureEmnapiAutoDestroyListener()
   try {
     __emnapiContext = __wrapEmnapiContextDestroyForSettlement(
-      __emnapiCreateContext({ autoDestroy: false }),
+      __emnapiCreateContext({ autoDestroy: false, features: { setImmediate: __wasiSetImmediate } }),
       __prepareWasmEnvCleanup,
       __isPreparingWasmEnvCleanup,
     )
@@ -2108,6 +2262,7 @@ try {
     },
   }))
   __publishWasiDispose(__napiModule.exports)
+  __publishWasiThreadPoolReconcile(__napiModule.exports)
   // The CommonJS tail below aliases `__napiModule.exports`; a named module
   // export does not travel with it, so carry the marker on the binding itself
   // too. Three things pin the stamp to exactly this spot:
@@ -2136,8 +2291,14 @@ try {
   __runWasiInitializationRollback(rollback)
   throw rollback.error
 }
+// Preload the pool for the count the addon configured during registration.
+// See `__reconcileWasiThreadPool`.
+try {
+  __reconcileWasiThreadPool()
+} catch {}
 module.exports = __napiModule.exports
 module.exports.Peisar = __napiModule.exports.Peisar
+module.exports.PeisarCache = __napiModule.exports.PeisarCache
 module.exports.EmphasisLevel = __napiModule.exports.EmphasisLevel
 module.exports.TableCellAlignment = __napiModule.exports.TableCellAlignment
 module.exports.TaskState = __napiModule.exports.TaskState

package/peisar.wasi.d.cts

@@ -65,6 +65,68 @@ export declare class Peisar {
   get astJson(): string
 }
 
+/**
+ * In-memory cache of markdown files under a given directory.
+ * The cache maps absolute PathBuf -> raw file contents.
+ */
+export declare class PeisarCache {
+  /**
+   * Construct a new PeisarCache using the default discovery behavior.
+   *
+   * JS: `new PeisarCache(entryDir, assetsDir?)` — both plain strings.
+   */
+  constructor(entryDir: string, assetsDir?: string | undefined | null)
+  /**
+   * JS: same as the constructor, for callers that prefer a factory shape.
+   * Kept non-generic so NAPI can export it.
+   */
+  static withConfigJs(entryDir: string, assetsDir?: string | undefined | null): PeisarCache
+  /**
+   * Start watching the entry_dir recursively. The watcher will update the
+   * in-memory cache on create/modify/remove events for markdown files and
+   * assets, and persist updates to disk.
+   *
+   * The returned Result is only for watcher setup errors; runtime errors are
+   * printed to stderr by the watch callback.
+   *
+   * JS: `cache.startWatchingJs()` — errors surface as JS exceptions.
+   */
+  startWatchingJs(): void
+  /**
+   * ----------------------------------------------------------------
+   * JavaScript (NAPI) surface
+   * ----------------------------------------------------------------
+   * All JS methods take/return plain strings because `&Path`/`PathBuf`
+   * do not cross the NAPI boundary.
+   * JS: `cache.getText(absPath)` — cached text of a file, or null.
+   */
+  getText(absPath: string): string | null
+  /** JS: `cache.getBinary(absPath)` — cached bytes of a binary asset, or null. */
+  getBinary(absPath: string): Array<number> | null
+  /** JS: `cache.listFiles()` — absolute paths of everything cached. */
+  listFiles(): Array<string>
+  /** JS: `cache.markdownFiles()` — absolute paths of cached markdown files. */
+  markdownFiles(): Array<string>
+  /** JS: `cache.assetFiles()` — absolute paths of cached non-markdown files. */
+  assetFiles(): Array<string>
+  /**
+   * JS: `cache.onChange(cb)` — invoke `cb(event)` on every file change the
+   * watcher detects while watching is active. Returns a subscription id
+   * that can be passed to `offChange(id)`.
+   *
+   * The callback is wrapped in a `ThreadsafeFunction` because notify
+   * events fire on the watcher thread, not the JS main thread.
+   */
+  onChange(callback: (event: CacheChangeEvent) => void): number
+  /** JS: `cache.offChange(id)` — remove a previously registered callback. */
+  offChange(id: number): void
+  /**
+   * JS: `cache.dispose()` — stop the watcher and drop JS change callbacks.
+   * Safe to call more than once.
+   */
+  dispose(): void
+}
+
 /**
  * Options that control how Markdown is parsed.
  *
@@ -185,6 +247,25 @@ export interface BlockParseResultJs {
   consumed?: number
 }
 
+/** A file-change event delivered to JavaScript `onChange` callbacks. */
+export interface CacheChangeEvent {
+  /** Absolute path of the changed file. */
+  path: string
+  /** `"create"`, `"modify"`, `"remove"`, or `"other"`. */
+  kind: string
+  /** `true` when the file is under the markdown entry directory. */
+  isMarkdown: boolean
+}
+
+/**
+ * An entry stored in the cache: raw UTF-8 text (markdown) or raw bytes
+ * (binary assets).  Exposed to JavaScript so JS consumers can branch on
+ * the variant.
+ */
+export type CachedContent =
+  | { type: 'Text'; field0: string }
+  | { type: 'Binary'; field0: Array<number> }
+
 /**
  * A Markdown document — the root of the AST.
  *