writr 4.5.1 → 5.0.1

package/README.md

@@ -56,7 +56,18 @@ plugins and working with the processor directly.
   - [`.loadFromFileSync(filePath: string)`](#loadfromfilesyncfilepath-string)
   - [`.saveToFile(filePath: string)`](#savetofilefilepath-string)
   - [`.saveToFileSync(filePath: string)`](#savetofilesyncfilepath-string)
+- [Caching On Render](#caching-on-render)
+- [GitHub Flavored Markdown (GFM)](#github-flavored-markdown-gfm)
+  - [GFM Features](#gfm-features)
+  - [Using GFM](#using-gfm)
+  - [Disabling GFM](#disabling-gfm)
 - [Hooks](#hooks)
+- [Emitters](#emitters)
+  - [Error Events](#error-events)
+  - [Listening to Error Events](#listening-to-error-events)
+  - [Methods that Emit Errors](#methods-that-emit-errors)
+  - [Error Event Examples](#error-event-examples)
+  - [Event Emitter Methods](#event-emitter-methods)
 - [ESM and Node Version Support](#esm-and-node-version-support)
 - [Code of Conduct and Contributing](#code-of-conduct-and-contributing)
 - [License](#license)
@@ -413,6 +424,117 @@ writr.cache.store.lruSize = 100;
 writr.cache.store.ttl = '5m'; // setting it to 5 minutes
 ```
 
+# GitHub Flavored Markdown (GFM)
+
+Writr includes full support for [GitHub Flavored Markdown](https://github.github.com/gfm/) (GFM) through the `remark-gfm` and `remark-github-blockquote-alert` plugins. GFM is enabled by default and adds several powerful features to standard Markdown.
+
+## GFM Features
+
+When GFM is enabled (which it is by default), you get access to the following features:
+
+### Tables
+
+Create tables using pipes and hyphens:
+
+```markdown
+| Feature | Supported |
+|---------|-----------|
+| Tables  | Yes       |
+| Alerts  | Yes       |
+```
+
+### Strikethrough
+
+Use `~~` to create strikethrough text:
+
+```markdown
+~~This text is crossed out~~
+```
+
+### Task Lists
+
+Create interactive checkboxes:
+
+```markdown
+- [x] Completed task
+- [ ] Incomplete task
+- [ ] Another task
+```
+
+### Autolinks
+
+URLs are automatically converted to clickable links:
+
+```markdown
+https://github.com
+```
+
+### GitHub Blockquote Alerts
+
+GitHub-style alerts are supported to emphasize critical information. These are blockquote-based admonitions that render with special styling:
+
+```markdown
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+```
+
+## Using GFM
+
+GFM is enabled by default. Here's an example:
+
+```javascript
+import { Writr } from 'writr';
+
+const markdown = `
+# Task List Example
+
+- [x] Learn Writr basics
+- [ ] Master GFM features
+
+> [!NOTE]
+> GitHub Flavored Markdown is enabled by default!
+
+| Feature | Status |
+|---------|--------|
+| GFM     | ✓      |
+`;
+
+const writr = new Writr(markdown);
+const html = await writr.render(); // Renders with full GFM support
+```
+
+## Disabling GFM
+
+If you need to disable GFM features, you can set `gfm: false` in the render options:
+
+```javascript
+import { Writr } from 'writr';
+
+const writr = new Writr('~~strikethrough~~ text');
+
+// Disable GFM
+const html = await writr.render({ gfm: false });
+// Output: <p>~~strikethrough~~ text</p>
+
+// With GFM enabled (default)
+const htmlWithGfm = await writr.render({ gfm: true });
+// Output: <p><del>strikethrough</del> text</p>
+```
+
+Note: When GFM is disabled, GitHub blockquote alerts will not be processed and will render as regular blockquotes.
+
 # Hooks
 
 Hooks are a way to add additional parsing to the render pipeline. You can add hooks to the the Writr instance. Here is an example of adding a hook to the instance of Writr:
@@ -476,6 +598,135 @@ export type loadFromFileData = {
 
 This is called when you call `loadFromFile`, `loadFromFileSync`.
 
+# Emitters
+
+Writr extends the [Hookified](https://github.com/jaredwray/hookified) class, which provides event emitter capabilities. This means you can listen to events emitted by Writr during its lifecycle, particularly error events.
+
+## Error Events
+
+Writr emits an `error` event whenever an error occurs in any of its methods. This provides a centralized way to handle errors without wrapping every method call in a try/catch block.
+
+### Listening to Error Events
+
+You can listen to error events using the `.on()` method:
+
+```javascript
+import { Writr } from 'writr';
+
+const writr = new Writr('# Hello World');
+
+// Listen for any errors
+writr.on('error', (error) => {
+  console.error('An error occurred:', error.message);
+  // Handle the error appropriately
+  // Log to error tracking service, display to user, etc.
+});
+
+// Now when any error occurs, your listener will be notified
+try {
+  await writr.render();
+} catch (error) {
+  // Error is also thrown, so you can handle it here too
+}
+```
+
+### Methods that Emit Errors
+
+The following methods emit error events when they fail:
+
+**Rendering Methods:**
+- `render()` - Emits error before throwing when markdown rendering fails
+- `renderSync()` - Emits error before throwing when markdown rendering fails
+- `renderReact()` - Emits error before throwing when React rendering fails
+- `renderReactSync()` - Emits error before throwing when React rendering fails
+
+**Validation Methods:**
+- `validate()` - Emits error when validation fails (returns error in result object)
+- `validateSync()` - Emits error when validation fails (returns error in result object)
+
+**File Operations:**
+- `renderToFile()` - Emits error when file writing fails (does not throw if `throwErrors: false`)
+- `renderToFileSync()` - Emits error when file writing fails (does not throw if `throwErrors: false`)
+- `loadFromFile()` - Emits error when file reading fails (does not throw if `throwErrors: false`)
+- `loadFromFileSync()` - Emits error when file reading fails (does not throw if `throwErrors: false`)
+- `saveToFile()` - Emits error when file writing fails (does not throw if `throwErrors: false`)
+- `saveToFileSync()` - Emits error when file writing fails (does not throw if `throwErrors: false`)
+
+**Front Matter Operations:**
+- `frontMatter` getter - Emits error when YAML parsing fails
+- `frontMatter` setter - Emits error when YAML serialization fails
+
+### Error Event Examples
+
+**Example 1: Global Error Handler**
+
+```javascript
+import { Writr } from 'writr';
+
+const writr = new Writr();
+
+// Set up a global error handler
+writr.on('error', (error) => {
+  // Log to your monitoring service
+  console.error('Writr error:', error);
+
+  // Send to error tracking (e.g., Sentry, Rollbar)
+  // errorTracker.captureException(error);
+});
+
+// All errors will be emitted to the listener above
+await writr.loadFromFile('./content.md');
+const html = await writr.render();
+```
+
+**Example 2: Validation with Error Listening**
+
+```javascript
+import { Writr } from 'writr';
+
+const writr = new Writr('# My Content');
+let lastError = null;
+
+writr.on('error', (error) => {
+  lastError = error;
+});
+
+const result = await writr.validate();
+
+if (!result.valid) {
+  console.log('Validation failed');
+  console.log('Error details:', lastError);
+  // result.error is also available
+}
+```
+
+**Example 3: File Operations Without Try/Catch**
+
+```javascript
+import { Writr } from 'writr';
+
+const writr = new Writr('# Content', { throwErrors: false });
+
+writr.on('error', (error) => {
+  console.error('File operation failed:', error.message);
+  // Handle gracefully - maybe use default content
+});
+
+// Won't throw, but will emit error event if file doesn't exist
+await writr.loadFromFile('./maybe-missing.md');
+```
+
+### Event Emitter Methods
+
+Since Writr extends Hookified, you have access to standard event emitter methods:
+
+- `writr.on(event, handler)` - Add an event listener
+- `writr.once(event, handler)` - Add a one-time event listener
+- `writr.off(event, handler)` - Remove an event listener
+- `writr.emit(event, data)` - Emit an event (used internally)
+
+For more information about event handling capabilities, see the [Hookified documentation](https://github.com/jaredwray/hookified).
+
 # ESM and Node Version Support
 
 This package is ESM only and tested on the current lts version and its previous. Please don't open issues for questions regarding CommonJS / ESM or previous Nodejs versions.

package/dist/writr.d.ts

@@ -16,6 +16,13 @@ declare class WritrCache {
     set(markdown: string, value: string, options?: RenderOptions): void;
     clear(): void;
     hash(markdown: string, options?: RenderOptions): string;
+    /**
+     * Sanitizes render options to only include serializable properties for caching.
+     * This prevents issues with structuredClone when options contain Promises, functions, or circular references.
+     * @param {RenderOptions} [options] The render options to sanitize
+     * @returns {RenderOptions | undefined} A new object with only the known RenderOptions properties
+     */
+    private sanitizeOptions;
 }
 
 /**
@@ -37,8 +44,8 @@ type WritrOptions = {
  * @property {boolean} [highlight] - Code highlighting (default: true)
  * @property {boolean} [gfm] - Github flavor markdown (default: true)
  * @property {boolean} [math] - Math support (default: true)
- * @property {boolean} [mdx] - MDX support (default: true)
- * @property {boolean} [caching] - Caching (default: false)
+ * @property {boolean} [mdx] - MDX support (default: false)
+ * @property {boolean} [caching] - Caching (default: true)
  */
 type RenderOptions = {
     emoji?: boolean;
@@ -208,9 +215,9 @@ declare class Writr extends Hookified {
      * @returns {void}
      */
     saveToFileSync(filePath: string): void;
+    mergeOptions(current: WritrOptions, options: WritrOptions): WritrOptions;
     private isCacheEnabled;
     private createProcessor;
-    private mergeOptions;
     private mergeRenderOptions;
 }
 

package/dist/writr.js

@@ -10,6 +10,7 @@ import rehypeSlug from "rehype-slug";
 import rehypeStringify from "rehype-stringify";
 import remarkEmoji from "remark-emoji";
 import remarkGfm from "remark-gfm";
+import remarkGithubBlockquoteAlert from "remark-github-blockquote-alert";
 import remarkMath from "remark-math";
 import remarkMDX from "remark-mdx";
 import remarkParse from "remark-parse";
@@ -18,11 +19,12 @@ import remarkToc from "remark-toc";
 import { unified } from "unified";
 
 // src/writr-cache.ts
-import { Cacheable, CacheableMemory } from "cacheable";
+import { CacheableMemory } from "cacheable";
+import { Hashery } from "hashery";
 var WritrCache = class {
   _store = new CacheableMemory();
   _hashStore = new CacheableMemory();
-  _hash = new Cacheable();
+  _hash = new Hashery();
   get store() {
     return this._store;
   }
@@ -42,15 +44,53 @@ var WritrCache = class {
     this._hashStore.clear();
   }
   hash(markdown, options) {
-    const content = { markdown, options };
+    const sanitizedOptions = this.sanitizeOptions(options);
+    const content = { markdown, options: sanitizedOptions };
     const key = JSON.stringify(content);
-    let result = this._hashStore.get(key);
+    const result = this._hashStore.get(key);
     if (result) {
       return result;
     }
-    result = this._hash.hash(content);
-    this._hashStore.set(key, result);
-    return result;
+    const hash = this._hash.toHashSync(content);
+    this._hashStore.set(key, hash);
+    return hash;
+  }
+  /**
+   * Sanitizes render options to only include serializable properties for caching.
+   * This prevents issues with structuredClone when options contain Promises, functions, or circular references.
+   * @param {RenderOptions} [options] The render options to sanitize
+   * @returns {RenderOptions | undefined} A new object with only the known RenderOptions properties
+   */
+  sanitizeOptions(options) {
+    if (!options) {
+      return void 0;
+    }
+    const sanitized = {};
+    if (options.emoji !== void 0) {
+      sanitized.emoji = options.emoji;
+    }
+    if (options.toc !== void 0) {
+      sanitized.toc = options.toc;
+    }
+    if (options.slug !== void 0) {
+      sanitized.slug = options.slug;
+    }
+    if (options.highlight !== void 0) {
+      sanitized.highlight = options.highlight;
+    }
+    if (options.gfm !== void 0) {
+      sanitized.gfm = options.gfm;
+    }
+    if (options.math !== void 0) {
+      sanitized.math = options.math;
+    }
+    if (options.mdx !== void 0) {
+      sanitized.mdx = options.mdx;
+    }
+    if (options.caching !== void 0) {
+      sanitized.caching = options.caching;
+    }
+    return sanitized;
   }
 };
 
@@ -64,7 +104,7 @@ var WritrHooks = /* @__PURE__ */ ((WritrHooks2) => {
   return WritrHooks2;
 })(WritrHooks || {});
 var Writr = class extends Hookified {
-  engine = unified().use(remarkParse).use(remarkGfm).use(remarkToc).use(remarkEmoji).use(remarkRehype).use(rehypeSlug).use(remarkMath).use(rehypeKatex).use(rehypeHighlight).use(remarkMDX).use(rehypeStringify);
+  engine = unified().use(remarkParse).use(remarkGfm).use(remarkToc).use(remarkEmoji).use(remarkRehype).use(rehypeSlug).use(remarkMath).use(rehypeKatex).use(rehypeHighlight).use(rehypeStringify);
   // Stringify HTML
   _options = {
     throwErrors: false,
@@ -75,8 +115,8 @@ var Writr = class extends Hookified {
       highlight: true,
       gfm: true,
       math: true,
-      mdx: true,
-      caching: false
+      mdx: false,
+      caching: true
     }
   };
   _content = "";
@@ -191,12 +231,16 @@ var Writr = class extends Hookified {
    */
   // biome-ignore lint/suspicious/noExplicitAny: expected
   set frontMatter(data) {
-    const frontMatter = this.frontMatterRaw;
-    const yamlString = yaml.dump(data);
-    const newFrontMatter = `---
+    try {
+      const frontMatter = this.frontMatterRaw;
+      const yamlString = yaml.dump(data);
+      const newFrontMatter = `---
 ${yamlString}---
 `;
-    this._content = this._content.replace(frontMatter, newFrontMatter);
+      this._content = this._content.replace(frontMatter, newFrontMatter);
+    } catch (error) {
+      this.emit("error", error);
+    }
   }
   /**
    * Get the front matter value for a key.
@@ -245,6 +289,7 @@ ${yamlString}---
       await this.hook("afterRender" /* afterRender */, resultData);
       return resultData.result;
     } catch (error) {
+      this.emit("error", error);
       throw new Error(`Failed to render markdown: ${error.message}`);
     }
   }
@@ -287,6 +332,7 @@ ${yamlString}---
       this.hook("afterRender" /* afterRender */, resultData);
       return resultData.result;
     } catch (error) {
+      this.emit("error", error);
       throw new Error(`Failed to render markdown: ${error.message}`);
     }
   }
@@ -317,6 +363,7 @@ ${yamlString}---
       }
       return { valid: true };
     } catch (error) {
+      this.emit("error", error);
       if (content !== void 0) {
         this._content = originalContent;
       }
@@ -350,6 +397,7 @@ ${yamlString}---
       }
       return { valid: true };
     } catch (error) {
+      this.emit("error", error);
       if (content !== void 0) {
         this._content = originalContent;
       }
@@ -410,8 +458,13 @@ ${yamlString}---
    * @returns {Promise<string | React.JSX.Element | React.JSX.Element[]>} The rendered React content.
    */
   async renderReact(options, reactParseOptions) {
-    const html = await this.render(options);
-    return parse(html, reactParseOptions);
+    try {
+      const html = await this.render(options);
+      return parse(html, reactParseOptions);
+    } catch (error) {
+      this.emit("error", error);
+      throw new Error(`Failed to render React: ${error.message}`);
+    }
   }
   /**
    * Render the markdown content to React synchronously.
@@ -420,8 +473,13 @@ ${yamlString}---
    * @returns {string | React.JSX.Element | React.JSX.Element[]} The rendered React content.
    */
   renderReactSync(options, reactParseOptions) {
-    const html = this.renderSync(options);
-    return parse(html, reactParseOptions);
+    try {
+      const html = this.renderSync(options);
+      return parse(html, reactParseOptions);
+    } catch (error) {
+      this.emit("error", error);
+      throw new Error(`Failed to render React: ${error.message}`);
+    }
   }
   /**
    * Load markdown content from a file.
@@ -509,6 +567,16 @@ ${yamlString}---
       }
     }
   }
+  mergeOptions(current, options) {
+    if (options.throwErrors !== void 0) {
+      current.throwErrors = options.throwErrors;
+    }
+    if (options.renderOptions) {
+      current.renderOptions ??= {};
+      this.mergeRenderOptions(current.renderOptions, options.renderOptions);
+    }
+    return current;
+  }
   isCacheEnabled(options) {
     if (options?.caching !== void 0) {
       return options.caching;
@@ -520,6 +588,7 @@ ${yamlString}---
     const processor = unified().use(remarkParse);
     if (options.gfm) {
       processor.use(remarkGfm);
+      processor.use(remarkGithubBlockquoteAlert);
     }
     if (options.toc) {
       processor.use(remarkToc, { heading: "toc|table of contents" });
@@ -543,16 +612,6 @@ ${yamlString}---
     processor.use(rehypeStringify);
     return processor;
   }
-  mergeOptions(current, options) {
-    if (options.throwErrors !== void 0) {
-      current.throwErrors = options.throwErrors;
-    }
-    if (options.renderOptions) {
-      current.renderOptions ??= {};
-      this.mergeRenderOptions(current.renderOptions, options.renderOptions);
-    }
-    return current;
-  }
   mergeRenderOptions(current, options) {
     if (options.emoji !== void 0) {
       current.emoji = options.emoji;
@@ -585,3 +644,4 @@ export {
   Writr,
   WritrHooks
 };
+/* v8 ignore next -- @preserve */

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "writr",
-  "version": "4.5.1",
+  "version": "5.0.1",
   "description": "Markdown Rendering Simplified",
   "type": "module",
   "main": "./dist/writr.js",
   "types": "./dist/writr.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/writr.d.ts",
       "import": "./dist/writr.js"
     }
   },
-  "repository": "https://github.com/jaredwray/writr.git",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jaredwray/writr.git"
+  },
   "author": "Jared Wray <me@jaredwray.com>",
   "engines": {
     "node": ">=20"
@@ -44,28 +48,20 @@
     "react-markdown",
     "markdown-to-react"
   ],
-  "scripts": {
-    "clean": "rimraf ./dist ./coverage ./node_modules ./pnpm-lock.yaml ./site/README.md ./site/dist",
-    "build": "rimraf ./dist && tsup src/writr.ts --format esm --dts --clean",
-    "prepare": "pnpm build",
-    "lint": "biome check --write --error-on-warnings",
-    "test": "pnpm lint && vitest run --coverage",
-    "test:ci": "biome check --error-on-warnings && vitest run --coverage",
-    "website:build": "rimraf ./site/README.md ./site/dist && npx docula build -s ./site -o ./site/dist",
-    "website:serve": "rimraf ./site/README.md ./site/dist && npx docula serve -s ./site -o ./site/dist"
-  },
   "dependencies": {
-    "cacheable": "^2.0.2",
-    "hookified": "^1.12.1",
-    "html-react-parser": "^5.2.6",
-    "js-yaml": "^4.1.0",
-    "react": "^19.1.1",
+    "cacheable": "^2.2.0",
+    "hashery": "^1.2.0",
+    "hookified": "^1.13.0",
+    "html-react-parser": "^5.2.10",
+    "js-yaml": "^4.1.1",
+    "react": "^19.2.0",
     "rehype-highlight": "^7.0.2",
     "rehype-katex": "^7.0.1",
     "rehype-slug": "^6.0.0",
     "rehype-stringify": "^10.0.1",
     "remark-emoji": "^5.0.2",
     "remark-gfm": "^4.0.1",
+    "remark-github-blockquote-alert": "^2.0.0",
     "remark-math": "^6.0.0",
     "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",
@@ -74,27 +70,29 @@
     "unified": "^11.0.5"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.2.4",
+    "@biomejs/biome": "^2.3.7",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^24.5.2",
-    "@types/react": "^19.1.13",
-    "@vitest/coverage-v8": "^3.2.4",
-    "docula": "^0.30.0",
-    "rimraf": "^6.0.1",
-    "ts-node": "^10.9.2",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4",
-    "webpack": "^5.101.3"
-  },
-  "xo": {
-    "ignores": [
-      "docula.config.*"
-    ]
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@vitest/coverage-v8": "^4.0.14",
+    "docula": "^0.31.1",
+    "rimraf": "^6.1.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.14"
   },
   "files": [
     "dist",
     "README.md",
     "LICENSE"
-  ]
-}
+  ],
+  "scripts": {
+    "clean": "rimraf ./dist ./coverage ./node_modules ./pnpm-lock.yaml ./site/README.md ./site/dist",
+    "build": "rimraf ./dist && tsup src/writr.ts --format esm --dts --clean",
+    "lint": "biome check --write --error-on-warnings",
+    "test": "pnpm lint && vitest run --coverage",
+    "test:ci": "biome check --error-on-warnings && vitest run --coverage",
+    "website:build": "rimraf ./site/README.md ./site/dist && npx docula build -s ./site -o ./site/dist",
+    "website:serve": "rimraf ./site/README.md ./site/dist && npx docula serve -s ./site -o ./site/dist"
+  }
+}