satteri 0.9.0 → 0.9.1

package/README.md

@@ -182,9 +182,25 @@ const { html, data } = markdownToHtml("# A\n\n# B", { mdastPlugins: [collectHead
 console.log(data?.headings); // ["A", "B"]
 ```
 
-The bag lives entirely on the JS side, so any value is allowed, including functions, class instances, and `Map`/`Set`. References are preserved across plugins and across the mdast→hast boundary. A fresh, empty bag is created for every compile.
+The bag lives entirely on the JS side, so any value is allowed, including functions, class instances, and `Map`/`Set`. References are preserved across plugins and across the mdast→hast boundary. A fresh, empty bag is created for every compile unless you seed one with the `data` option.
 
-By default keys are typed as `unknown`. To give a key a type, augment the `DataMap` interface, much like `vfile`'s `DataMap`:
+To seed data into the bag before plugins run, pass an object to the `data` option. The same object is available in all plugins and returned as `result.data` after compilation, so you can pre-populate it with values or methods that plugins can read and update.
+
+```ts
+const data = { title: "Hello" };
+const rewriteTitle = defineMdastPlugin({
+  name: "rewrite-title",
+  heading(_node, ctx) {
+    ctx.data.title = "Updated";
+  },
+});
+
+const result = markdownToHtml("# A", { mdastPlugins: [rewriteTitle], data });
+console.log(result.data === data); // true, the seeded object is returned
+console.log(data.title); // "Updated"
+```
+
+By default keys are typed as `unknown`. To give a key a type, augment the `DataMap` interface:
 
 ```ts
 declare module "satteri" {
@@ -334,6 +350,7 @@ interface CompileOptions {
   hastPlugins?: HastPluginDefinition[];
   features?: Features;
   fileURL?: URL;
+  data?: Data;
 }
 
 // mdxToJs accepts MdxCompileOptions, which extends CompileOptions
@@ -344,6 +361,8 @@ interface MdxCompileOptions extends CompileOptions {
 
 `fileURL` is the `URL` of the document being processed, surfaced to plugins as `ctx.fileURL` (a `URL`, or `undefined` when omitted). Pass a file URL such as Astro's `fileURL`, or convert a filesystem path with Node's `pathToFileURL`; read it back with `fileURLToPath(ctx.fileURL)`.
 
+`data` seeds the document-level data bag before plugins run, surfaced as `ctx.data` and returned as `result.data`. See [Sharing data between plugins](#sharing-data-between-plugins).
+
 `Features` controls the Markdown extensions Sätteri's parser recognizes: `gfm`, `frontmatter`, `math`, `directive`, `smartPunctuation`, etc. `gfm`, `math`, and `smartPunctuation` also accept granular options. For example, `math: { singleDollarTextMath: false }` keeps single `$` as literal text. See the [Features reference](https://satteri.dev/docs/features/) for the full list.
 
 ## License

package/dist/compile.d.ts

@@ -130,6 +130,14 @@ export interface CompileOptions {
      * `pathToFileURL` before passing it.
      */
     fileURL?: URL;
+    /**
+     * Initial document-level data bag, seeding `ctx.data` before any plugin runs.
+     * It is the same object plugins mutate and the caller reads back as
+     * `result.data`, so values flow both into and out of a compile. Defaults to a
+     * fresh empty object. Used by reference and mutated in place, so pass a
+     * throwaway object per compile rather than a shared one.
+     */
+    data?: Data;
 }
 /**
  * MDX-only compile options.
@@ -200,7 +208,7 @@ export interface MarkdownToHtmlResult {
     html: string;
     /** Frontmatter block at the start of the document, or `null` if none. */
     frontmatter: Frontmatter | null;
-    /** Document-level data bag populated by plugins via `ctx.data`. Empty `{}` if untouched. */
+    /** Document-level data bag shared with plugins via `ctx.data`; the seeded `data` option if provided, else a fresh `{}`. */
     data: Data;
 }
 /** Result of {@link mdxToJs}. */
@@ -209,7 +217,7 @@ export interface MdxToJsResult {
     code: string;
     /** Frontmatter block at the start of the document, or `null` if none. */
     frontmatter: Frontmatter | null;
-    /** Document-level data bag populated by plugins via `ctx.data`. Empty `{}` if untouched. */
+    /** Document-level data bag shared with plugins via `ctx.data`; the seeded `data` option if provided, else a fresh `{}`. */
     data: Data;
 }
 type AnyFn = (...args: any[]) => unknown;

package/dist/compile.js

@@ -75,11 +75,12 @@ function featuresToNative(features) {
     }
     return { features: result, convertOptions };
 }
-/** Drop a handle after bumping its epoch: the arena dies with the handle, so a
- *  child stub retained past the pipeline must hit the designed retention error,
- *  not a cryptic RangeError from snapshotting the freed arena. */
-function disposeHandle(handle) {
-    markHandleMutated(handle);
+/** Free a handle's arena. A plugin's visitor can hand child stubs to user code;
+ *  pass `invalidateStubs` so the epoch bump makes any stub retained past this
+ *  point hit the designed retention error instead of snapshotting the freed arena. */
+function releaseHandle(handle, invalidateStubs) {
+    if (invalidateStubs)
+        markHandleMutated(handle);
     dropHandle(handle);
 }
 function warnDroppedTransforms(plugin, dropped, kind) {
@@ -190,9 +191,9 @@ function mdxOptionsToNative(opts) {
     return result;
 }
 export function markdownToHtml(source, options = {}) {
-    const { mdastPlugins = [], hastPlugins = [], features, fileURL } = options;
+    const { mdastPlugins = [], hastPlugins = [], features, fileURL, data = {} } = options;
+    const hastMayHaveStubs = hastPlugins.length > 0;
     const { features: nativeFeatures, convertOptions: nativeConvertOptions } = featuresToNative(features);
-    const data = {};
     const result = createHastHandleFromMdast(source, mdastPlugins, false, fileURL, nativeFeatures, nativeConvertOptions, data);
     const renderAndDrop = (h, frontmatter) => {
         try {
@@ -200,7 +201,7 @@ export function markdownToHtml(source, options = {}) {
             return { html, frontmatter, data };
         }
         finally {
-            disposeHandle(h);
+            releaseHandle(h, hastMayHaveStubs);
         }
     };
     const runHastThenRender = (r) => {
@@ -209,12 +210,12 @@ export function markdownToHtml(source, options = {}) {
             hastResult = runHastPluginsOnHandle(r.hastHandle, hastPlugins, source, fileURL, data);
         }
         catch (err) {
-            disposeHandle(r.hastHandle);
+            releaseHandle(r.hastHandle, hastMayHaveStubs);
             throw err;
         }
         if (hastResult instanceof Promise) {
             return hastResult.then(() => renderAndDrop(r.hastHandle, r.frontmatter), (err) => {
-                disposeHandle(r.hastHandle);
+                releaseHandle(r.hastHandle, hastMayHaveStubs);
                 throw err;
             });
         }
@@ -225,10 +226,10 @@ export function markdownToHtml(source, options = {}) {
     return runHastThenRender(result);
 }
 export function mdxToJs(source, options = {}) {
-    const { mdastPlugins = [], hastPlugins = [], features, fileURL, ...mdxFields } = options;
+    const { mdastPlugins = [], hastPlugins = [], features, fileURL, data = {}, ...mdxFields } = options;
+    const hastMayHaveStubs = hastPlugins.length > 0;
     const mdxOptions = mdxOptionsToNative(mdxFields);
     const { features: nativeFeatures, convertOptions: nativeConvertOptions } = featuresToNative(features);
-    const data = {};
     const result = createHastHandleFromMdast(source, mdastPlugins, true, fileURL, nativeFeatures, nativeConvertOptions, data);
     const compileAndDrop = (h, frontmatter) => {
         try {
@@ -236,7 +237,7 @@ export function mdxToJs(source, options = {}) {
             return { code, frontmatter, data };
         }
         finally {
-            disposeHandle(h);
+            releaseHandle(h, hastMayHaveStubs);
         }
     };
     const runHastThenCompile = (r) => {
@@ -245,12 +246,12 @@ export function mdxToJs(source, options = {}) {
             hastResult = runHastPluginsOnHandle(r.hastHandle, hastPlugins, source, fileURL, data);
         }
         catch (err) {
-            disposeHandle(r.hastHandle);
+            releaseHandle(r.hastHandle, hastMayHaveStubs);
             throw err;
         }
         if (hastResult instanceof Promise) {
             return hastResult.then(() => compileAndDrop(r.hastHandle, r.frontmatter), (err) => {
-                disposeHandle(r.hastHandle);
+                releaseHandle(r.hastHandle, hastMayHaveStubs);
                 throw err;
             });
         }
@@ -295,19 +296,20 @@ nativeConvertOptions, data) {
     const mdastHandle = mdx
         ? createMdxMdastHandle(source, nativeFeatures)
         : createMdastHandle(source, nativeFeatures);
-    // finally{dispose} is intentional: convertMdastToHastHandle empties the arena
+    const mdastMayHaveStubs = mdastPlugins.length > 0;
+    // finally{release} is intentional: convertMdastToHastHandle empties the arena
     // on success, but if any step here throws the handle would otherwise leak.
     const finalize = (r) => {
         try {
             const frontmatter = readFrontmatter(r.handle);
-            // The conversion empties the mdast arena; bump the epoch so a stub
-            // retained past the mdast pass fails with the retention error.
-            markHandleMutated(r.handle);
+            // convert empties the mdast arena, so invalidate any stub held past this point.
+            if (mdastMayHaveStubs)
+                markHandleMutated(r.handle);
             const hastHandle = convertMdastToHastHandle(r.handle, nativeConvertOptions);
             return { hastHandle, frontmatter };
         }
         finally {
-            disposeHandle(r.handle);
+            releaseHandle(r.handle, mdastMayHaveStubs);
         }
     };
     try {
@@ -317,14 +319,14 @@ nativeConvertOptions, data) {
         const mdastResult = runMdastPluginsOnHandle(mdastHandle, mdastPlugins, fileURL, data);
         if (mdastResult instanceof Promise) {
             return mdastResult.then(finalize, (err) => {
-                disposeHandle(mdastHandle);
+                releaseHandle(mdastHandle, mdastMayHaveStubs);
                 throw err;
             });
         }
         return finalize(mdastResult);
     }
     catch (err) {
-        disposeHandle(mdastHandle);
+        releaseHandle(mdastHandle, mdastMayHaveStubs);
         throw err;
     }
 }
@@ -336,7 +338,7 @@ export function markdownToMdast(source, options = {}) {
         return materializeMdastTree(new MdastReader(serializeHandle(handle)));
     }
     finally {
-        disposeHandle(handle);
+        releaseHandle(handle, true);
     }
 }
 /** Parse MDX source into a materialized mdast tree. */
@@ -346,7 +348,7 @@ export function mdxToMdast(source, options = {}) {
         return materializeMdastTree(new MdastReader(serializeHandle(handle)));
     }
     finally {
-        disposeHandle(handle);
+        releaseHandle(handle, true);
     }
 }
 /** Convert Markdown source to a materialized hast tree. */
@@ -357,7 +359,7 @@ export function markdownToHast(source, options = {}) {
         return materializeHastTree(new HastReader(serializeHandle(handle)));
     }
     finally {
-        disposeHandle(handle);
+        releaseHandle(handle, true);
     }
 }
 /** Convert MDX source to a materialized hast tree. */
@@ -368,6 +370,6 @@ export function mdxToHast(source, options = {}) {
         return materializeHastTree(new HastReader(serializeHandle(handle)));
     }
     finally {
-        disposeHandle(handle);
+        releaseHandle(handle, true);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "satteri",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "High-performance Markdown and MDX processing",
   "repository": {
     "type": "git",
@@ -80,11 +80,11 @@
     ]
   },
   "optionalDependencies": {
-    "@bruits/satteri-linux-x64-gnu": "0.9.0",
-    "@bruits/satteri-darwin-x64": "0.9.0",
-    "@bruits/satteri-darwin-arm64": "0.9.0",
-    "@bruits/satteri-win32-x64-msvc": "0.9.0",
-    "@bruits/satteri-wasm32-wasi": "0.9.0"
+    "@bruits/satteri-linux-x64-gnu": "0.9.1",
+    "@bruits/satteri-darwin-x64": "0.9.1",
+    "@bruits/satteri-darwin-arm64": "0.9.1",
+    "@bruits/satteri-win32-x64-msvc": "0.9.1",
+    "@bruits/satteri-wasm32-wasi": "0.9.1"
   },
   "scripts": {
     "build:binary:wasm": "napi build --manifest-path ../../crates/satteri-napi-binding/Cargo.toml --output-dir . --platform --release --esm --strip --target wasm32-wasip1-threads",