@peisar/peisar-wasm32-wasi 0.2.22 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peisar/peisar-wasm32-wasi",
-  "version": "0.2.22",
+  "version": "0.3.01",
   "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,6 @@ try {
 }
 export default __napiModule.exports
 export const Peisar = __napiModule.exports.Peisar
-export const EmphasisLevel = __napiModule.exports.EmphasisLevel
-export const TableCellAlignment = __napiModule.exports.TableCellAlignment
-export const TaskState = __napiModule.exports.TaskState
+export const PeisarCache = __napiModule.exports.PeisarCache
+export const frontmatter = __napiModule.exports.frontmatter
+export const yamlParser = __napiModule.exports.yamlParser

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.cjs","exports":["Peisar","PeisarCache","frontmatter","yamlParser"],"managedRootEntries":["browser.js","index.cjs","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,13 @@ 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.EmphasisLevel = __napiModule.exports.EmphasisLevel
-module.exports.TableCellAlignment = __napiModule.exports.TableCellAlignment
-module.exports.TaskState = __napiModule.exports.TaskState
+module.exports.PeisarCache = __napiModule.exports.PeisarCache
+module.exports.frontmatter = __napiModule.exports.frontmatter
+module.exports.yamlParser = __napiModule.exports.yamlParser

package/peisar.wasi.d.cts

@@ -1,5 +1,7 @@
-/* auto-generated by NAPI-RS */
-/* eslint-disable */
+export type PeisarEmphasisLevel = "Italic" | "Bold";
+export type PeisarTableCellAlignment = "Default" | "Left" | "Center" | "Right";
+export type PeisarTableCellAlignments = PeisarTableCellAlignment[];
+export type PeisarTaskState = "Unchecked" | "Checked";
 
 /** The WASI flavor this loader instantiates. */
 export declare const __napiBindingTarget: 'wasm32-wasi'
@@ -65,6 +67,73 @@ export declare class Peisar {
   get astJson(): string
 }
 
+/**
+ * In-memory cache of the Markdown and asset files under a directory tree.
+ *
+ * The cache maps absolute source paths to [`CachedContent`] entries, is
+ * mirrored to a `.peisar_cache` directory on disk, and — after
+ * [`PeisarCache::start_watching`] — tracks the source directories with a
+ * recursive file watcher.
+ *
+ * Rust consumers read the cache with [`PeisarCache::get`] and
+ * [`PeisarCache::all`]; JavaScript consumers use the N-API methods below
+ * (`getText`, `getBinary`, `listFiles`, `markdownFiles`, `assetFiles`, …).
+ */
+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
+  /**
+   * JS: `cache.startWatchingJs()` — start watching the entry (and
+   * assets) directories recursively; 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.
+   *
+   * Rust consumers do not need this: dropping the [`PeisarCache`] stops
+   * the watcher, closes the persistence channel, and joins the worker.
+   */
+  dispose(): void
+}
+
 /**
  * Options that control how Markdown is parsed.
  *
@@ -149,13 +218,13 @@ export type Block =
  * Synchronous block-visitor callback. Receives a `Block`, returns
  * `VisitControlJs` (or `undefined` for no changes).
  */
-export type BlockCallback = (arg: [Block]) => VisitControlJs | null
+export type BlockCallback = (arg: [Block]) => VisitorControl | null
 
 /**
  * Synchronous block parser hook. Receives a [`BlockParseContext`], returns
  * a [`BlockParseResultJs`] (or `undefined` to decline).
  */
-export type BlockParseCallback = (arg: [BlockParseContext]) => BlockParseResultJs | null
+export type BlockParseCallback = (arg: [BlockParseContext]) => BlockParseResult | null
 
 /**
  * Context passed to block parser hooks.
@@ -178,13 +247,35 @@ export interface BlockParseContext {
  * All fields are optional; omitting `block` (or returning `undefined`)
  * declines the position so the next hook / built-in parser handles it.
  */
-export interface BlockParseResultJs {
+export interface BlockParseResult {
   /** The parsed block node. */
   block?: Block
   /** Number of source lines consumed (must be at least `1`). */
   consumed?: number
 }
 
+/**
+ * A file-change event delivered to change callbacks
+ * (see [`PeisarCache::on_change`]).
+ */
+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 and textual
+ * assets) 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.
  *
@@ -204,12 +295,14 @@ export interface Document {
   linkReferences: Array<LinkReferenceDefinition>
 }
 
-/** Emphasis strength. */
-export declare const enum EmphasisLevel {
-  /** `*italic*` / `_italic_` */
-  Italic = 0,
-  /** `**bold**` / `__bold__` */
-  Bold = 1,
+export declare function frontmatter(content: string): FrontmatterResult
+
+/** The Markdown body and YAML metadata parsed from a front-matter document. */
+export interface FrontmatterResult {
+  /** Markdown source after the leading YAML front matter is removed. */
+  pureMarkdownContent: string
+  /** Deserialized YAML front matter, or `null` when no front matter exists. */
+  yamlData?: Record<string, any>
 }
 
 /** Inline-level nodes. */
@@ -218,7 +311,7 @@ export type Inline =
     value: string; /** Source span. */
   pos: Span }
   | { type: 'Emphasis'; /** Emphasis level (italic or bold). */
-    level: EmphasisLevel; /** Nested inline content. */
+    level: PeisarEmphasisLevel; /** Nested inline content. */
     children: Array<Inline>; /** Source span. */
   pos: Span }
   | { type: 'Code'; /** The code text. */
@@ -256,13 +349,13 @@ export type Inline =
  * Synchronous inline-visitor callback. Receives an `Inline`, returns
  * `InlineVisitControlJs` (or `undefined` for no changes).
  */
-export type InlineCallback = (arg: [Inline]) => InlineVisitControlJs | null
+export type InlineCallback = (arg: [Inline]) => InlineVisitorControl | null
 
 /**
  * Synchronous inline parser hook. Receives an [`InlineParseContext`],
  * returns an [`InlineParseResultJs`] (or `undefined` to decline).
  */
-export type InlineParseCallback = (arg: [InlineParseContext]) => InlineParseResultJs | null
+export type InlineParseCallback = (arg: [InlineParseContext]) => InlineParseResult | null
 
 /**
  * Context passed to inline parser hooks.
@@ -282,7 +375,7 @@ export interface InlineParseContext {
  * All fields are optional; omitting `inline` (or returning `undefined`)
  * declines the position so the next hook / built-in parser handles it.
  */
-export interface InlineParseResultJs {
+export interface InlineParseResult {
   /** The parsed inline node. */
   inline?: Inline
   /** Number of characters consumed (`0` or missing declines). */
@@ -295,7 +388,7 @@ export interface InlineParseResultJs {
  * Returned from the JS `visitInline` callback.  All fields are optional;
  * omitting a field means "no change" for that operation.
  */
-export interface InlineVisitControlJs {
+export interface InlineVisitorControl {
   /** Nodes to insert before the current node. */
   insertBefore?: Array<Inline>
   /** Nodes to insert after the current node. */
@@ -325,39 +418,12 @@ export interface ListItem {
   /** Nested block content of the item. */
   children: Array<Block>
   /** GFM task-list state: `None` = not a task, `Some` = checked / unchecked. */
-  task?: TaskState
+  task?: PeisarTaskState
   /** Span of the item in the *sub-document* of its enclosing list. */
   pos: Span
 }
 
-/**
- * JavaScript object shape for a parser hook pair.
- *
- * ```js
- * const myParser = {
- *   parseBlock(ctx) {
- *     if (!ctx.line.startsWith(':::')) return;         // decline
- *     const name = ctx.line.slice(3).trim();
- *     return {
- *       block: { type: 'HtmlBlock', html: `<div data-name="${name}"></div>`, pos: { start: {}, end: {} } },
- *       consumed: 1,
- *     };
- *   },
- *   parseInline(ctx) {
- *     if (!ctx.rest.startsWith('@@')) return;          // decline
- *     const end = ctx.rest.indexOf(' ', 2);
- *     const name = end === -1 ? ctx.rest.slice(2) : ctx.rest.slice(2, end);
- *     return {
- *       inline: { type: 'HtmlInline', html: `<span data-name="${name}"></span>`, pos: { start: {}, end: {} } },
- *       consumed: name.length + 2,
- *     };
- *   },
- * };
- * document.useParser(myParser);
- * ```
- *
- * Either property may be omitted / `null` to skip that phase.
- */
+/** Either property may be omitted / `null` to skip that phase. */
 export interface Parser {
   /** Optional JS block parser hook (JS: `parseBlock`). */
   parseBlock?: BlockParseCallback
@@ -365,14 +431,6 @@ export interface Parser {
   parseInline?: InlineParseCallback
 }
 
-/** The Markdown body and YAML metadata parsed from a front-matter document. */
-export interface ParseResult {
-  /** Markdown source after the leading YAML front matter is removed. */
-  pureMarkdownContent: string
-  /** Deserialized YAML front matter, or `null` when no front matter exists. */
-  yamlData?: Record<string, any>
-}
-
 /**
  * JavaScript options for Markdown parsing and HTML rendering.
  *
@@ -507,7 +565,7 @@ export interface Table {
   /** Body rows. */
   rows: Array<TableRow>
   /** Column alignment specifications (one per column). */
-  alignments: Array<TableCellAlignment>
+  alignments: PeisarTableCellAlignments
 }
 
 /** A single table cell. */
@@ -516,30 +574,33 @@ export interface TableCell {
   children: Array<Inline>
 }
 
-/** Column alignment for table cells. */
-export declare const enum TableCellAlignment {
-  /** `:---` or `---` — default (left) */
-  Default = 0,
-  /** `:---` */
-  Left = 1,
-  /** `:---:` */
-  Center = 2,
-  /** `---:` */
-  Right = 3,
-}
-
 /** A single table row (header or body). */
 export interface TableRow {
   /** The cells in this row. */
   cells: Array<TableCell>
 }
 
-/** GFM task-list checkbox state. */
-export declare const enum TaskState {
-  /** `[ ]` — unchecked */
-  Unchecked = 0,
-  /** `[x]` / `[X]` — checked */
-  Checked = 1,
+/**
+ * JavaScript object shape for a visitor callback pair.
+ *
+ * On the JS side it is a plain object with two optional
+ * function properties:
+ *
+ * ```js
+ * const myPlugin = {
+ *   visitBlock(block)  { return { recurse: true }; },
+ *   visitInline(inline) { return {}; },
+ * };
+ * ast.addVisitor(myPlugin);
+ * ```
+ *
+ * Either property may be omitted / `null` to skip that node kind.
+ */
+export interface Visitor {
+  /** Optional JS callback for block nodes (JS: `visitBlock`). */
+  visitBlock?: BlockCallback
+  /** Optional JS callback for inline nodes (JS: `visitInline`). */
+  visitInline?: InlineCallback
 }
 
 /**
@@ -548,7 +609,7 @@ export declare const enum TaskState {
  * Returned from the JS `visitBlock` callback.  All fields are optional;
  * omitting a field means "no change" for that operation.
  */
-export interface VisitControlJs {
+export interface VisitorControl {
   /** Nodes to insert before the current node. */
   insertBefore?: Array<Block>
   /** Nodes to insert after the current node. */
@@ -562,24 +623,13 @@ export interface VisitControlJs {
 }
 
 /**
- * JavaScript object shape for a visitor callback pair.
+ * Parses a YAML document into a JSON-compatible value.
  *
- * On the JS side it is a plain object with two optional
- * function properties:
+ * When consumed from Node.js, the result is exposed as a JavaScript object
+ * with the TypeScript type `Record<string, any>`.
  *
- * ```js
- * const myPlugin = {
- *   visitBlock(block)  { return { recurse: true }; },
- *   visitInline(inline) { return {}; },
- * };
- * ast.addVisitor(myPlugin);
- * ```
+ * # Panics
  *
- * Either property may be omitted / `null` to skip that node kind.
+ * Panics when `yaml_str` is not valid YAML.
  */
-export interface Visitor {
-  /** Optional JS callback for block nodes (JS: `visitBlock`). */
-  visitBlock?: BlockCallback
-  /** Optional JS callback for inline nodes (JS: `visitInline`). */
-  visitInline?: InlineCallback
-}
+export declare function yamlParser(yamlStr: string): Record<string, any>