writr 4.1.4 → 4.3.0

package/README.md

@@ -22,12 +22,15 @@
   - [`.engine`](#engine)
   - [`.render(options?: RenderOptions): Promise<string>`](#renderoptions-renderoptions-promisestring)
   - [`.renderSync(options?: RenderOptions): string`](#rendersyncoptions-renderoptions-string)
+  - [`.renderToFile(filePath: string, options?: RenderOptions)`](#rendertofilefilepath-string-options-renderoptions)
+  - [`.renderToFileSync(filePath: string, options?: RenderOptions): void`](#rendertofilesyncfilepath-string-options-renderoptions-void)
   - [`.renderReact(options?: RenderOptions, reactOptions?: HTMLReactParserOptions): Promise<React.JSX.Element />`](#renderreactoptions-renderoptions-reactoptions-htmlreactparseroptions-promise-reactjsxelement-)
   - [`.renderReactSync( options?: RenderOptions, reactOptions?: HTMLReactParserOptions): React.JSX.Element`](#renderreactsync-options-renderoptions-reactoptions-htmlreactparseroptions-reactjsxelement)
   - [`.loadFromFile(filePath: string): Promise<void>`](#loadfromfilefilepath-string-promisevoid)
   - [`.loadFromFileSync(filePath: string): void`](#loadfromfilesyncfilepath-string-void)
   - [`.saveToFile(filePath: string): Promise<void>`](#savetofilefilepath-string-promisevoid)
   - [`.saveToFileSync(filePath: string): void`](#savetofilesyncfilepath-string-void)
+- [Hooks](#hooks)
 - [Code of Conduct and Contributing](#code-of-conduct-and-contributing)
 - [License](#license)
 
@@ -45,6 +48,7 @@
 * Github Flavor Markdown (remark-gfm).
 * Emoji Support (remark-emoji).
 * MDX Support (remark-mdx).
+* Built in Hooks for adding code to render pipeline.
 
 # ESM and Node Version Support
 
@@ -81,6 +85,7 @@ An example passing in the options also via the constructor:
 ```javascript
 import { Writr, WritrOptions } from 'writr';
 const writrOptions = {
+  throwErrors: true,
   renderOptions: {
     emoji: true,
     toc: true,
@@ -105,6 +110,7 @@ By default the constructor takes in a markdown `string` or `WritrOptions` in the
 ```javascript
 import { Writr, WritrOptions } from 'writr';
 const writrOptions = {
+  throwErrors: true,
   renderOptions: {
     emoji: true,
     toc: true,
@@ -149,7 +155,23 @@ console.log(writr.body); // '# Hello World ::-):\n\n This is a test.'
 
 ## `.options`
 
-Accessing the default options for this instance of Writr.
+Accessing the default options for this instance of Writr. Here is the default settings for `WritrOptions`.
+
+```javascript
+{
+  throwErrors: false,
+  renderOptions: {
+    emoji: true,
+    toc: false,
+    slug: false,
+    highlight: false,
+    gfm: true,
+    math: false,
+    mdx: false,
+    caching: false,
+  }
+}
+```
 
 ## `.frontmatter`
 
@@ -232,6 +254,26 @@ const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
 const html = writr.renderSync(); // <h1>Hello World 🙂</h1><p>This is a test.</p>
 ```
 
+## '.renderToFile(filePath: string, options?: RenderOptions)'
+
+Rendering markdown to a file. The options are based on RenderOptions.
+
+```javascript
+import { Writr } from 'writr';
+const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
+await writr.renderToFile('path/to/file.html');
+```
+
+## '.renderToFileSync(filePath: string, options?: RenderOptions): void'
+
+Rendering markdown to a file synchronously. The options are based on RenderOptions.
+
+```javascript
+import { Writr } from 'writr';
+const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
+writr.renderToFileSync('path/to/file.html');
+```
+
 ## '.renderReact(options?: RenderOptions, reactOptions?: HTMLReactParserOptions): Promise<React.JSX.Element />'
 
 Rendering markdown to React. The options are based on RenderOptions and now HTMLReactParserOptions from `html-react-parser`.
@@ -307,9 +349,41 @@ writr.cache.store.lruSize = 100;
 writr.cache.store.ttl = '5m'; // setting it to 5 minutes
 ```
 
+# 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:
+
+```javascript
+import { Writr, WritrHooks } from 'writr';
+const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
+writr.onHook(WritrHooks.beforeRender, data => {
+  data.body = 'Hello, Universe!';
+});
+const result = await writr.render();
+console.log(result); // Hello, Universe!
+```
+
+For `beforeRender` the data object is a `renderData` object. Here is the interface for `renderData`:
+
+```typescript
+export type renderData {
+  body: string;
+  content: string;
+  options: RenderOptions;
+}
+```
+
+For `afterRender` the data object is a `resultData` object. Here is the interface for `resultData`:
+
+```typescript
+export type resultData {
+  result: string;
+}
+```
+
 # Code of Conduct and Contributing
 [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing](CONTRIBUTING.md) guidelines.
 
 # License
 
-MIT © [Jared Wray](https://jaredwray.com)
+[MIT](LICENSE) & © [Jared Wray](https://jaredwray.com)

package/dist/writr.d.ts

@@ -20,12 +20,12 @@ declare class WritrCache {
 /**
  * Writr options.
  * @typedef {Object} WritrOptions
- * @property {string} [openai] - Openai api key (default: undefined)
  * @property {RenderOptions} [renderOptions] - Default render options (default: undefined)
+ * @property {boolean} [throwErrors] - Throw error (default: false)
  */
 type WritrOptions = {
-    openai?: string;
     renderOptions?: RenderOptions;
+    throwErrors?: boolean;
 };
 /**
  * Render options.
@@ -37,7 +37,7 @@ type WritrOptions = {
  * @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: true)
+ * @property {boolean} [caching] - Caching (default: false)
  */
 type RenderOptions = {
     emoji?: boolean;
@@ -49,6 +49,14 @@ type RenderOptions = {
     mdx?: boolean;
     caching?: boolean;
 };
+declare enum WritrHooks {
+    beforeRender = "beforeRender",
+    afterRender = "afterRender",
+    beforeSaveToFile = "beforeSaveToFile",
+    afterSaveToFile = "afterSaveToFile",
+    beforeLoadFromFile = "beforeLoadFromFile",
+    afterLoadFromFile = "afterLoadFromFile"
+}
 declare class Writr extends Hookified {
     engine: unified.Processor<mdast.Root, mdast.Root, hast.Root, hast.Root, string>;
     private readonly _options;
@@ -126,6 +134,18 @@ declare class Writr extends Hookified {
      * @returns {string} The rendered HTML content.
      */
     renderSync(options?: RenderOptions): string;
+    /**
+     * Render the markdown content and save it to a file. If the directory doesn't exist it will be created.
+     * @param {string} filePath The file path to save the rendered markdown content to.
+     * @param {RenderOptions} [options] the render options.
+     */
+    renderToFile(filePath: string, options?: RenderOptions): Promise<void>;
+    /**
+     * Render the markdown content and save it to a file synchronously. If the directory doesn't exist it will be created.
+     * @param {string} filePath The file path to save the rendered markdown content to.
+     * @param {RenderOptions} [options] the render options.
+     */
+    renderToFileSync(filePath: string, options?: RenderOptions): void;
     /**
      * Render the markdown content to React.
      * @param {RenderOptions} [options] The render options.
@@ -170,4 +190,4 @@ declare class Writr extends Hookified {
     private mergeRenderOptions;
 }
 
-export { type RenderOptions, Writr, type WritrOptions };
+export { type RenderOptions, Writr, WritrHooks, type WritrOptions };

package/dist/writr.js

@@ -54,11 +54,20 @@ var WritrCache = class {
 };
 
 // src/writr.ts
+var WritrHooks = /* @__PURE__ */ ((WritrHooks2) => {
+  WritrHooks2["beforeRender"] = "beforeRender";
+  WritrHooks2["afterRender"] = "afterRender";
+  WritrHooks2["beforeSaveToFile"] = "beforeSaveToFile";
+  WritrHooks2["afterSaveToFile"] = "afterSaveToFile";
+  WritrHooks2["beforeLoadFromFile"] = "beforeLoadFromFile";
+  WritrHooks2["afterLoadFromFile"] = "afterLoadFromFile";
+  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);
   // Stringify HTML
   _options = {
-    openai: void 0,
+    throwErrors: false,
     renderOptions: {
       emoji: true,
       toc: true,
@@ -201,24 +210,33 @@ ${yamlString}---
    */
   async render(options) {
     try {
-      let result = "";
-      if (this.isCacheEnabled(options)) {
-        const cached = this._cache.get(this._content, options);
-        if (cached) {
-          return cached;
-        }
-      }
       let { engine } = this;
       if (options) {
         options = { ...this._options.renderOptions, ...options };
         engine = this.createProcessor(options);
       }
-      const file = await engine.process(this.body);
-      result = String(file);
-      if (this.isCacheEnabled(options)) {
-        this._cache.set(this._content, result, options);
+      const renderData = {
+        content: this._content,
+        body: this.body,
+        options
+      };
+      await this.hook("beforeRender" /* beforeRender */, renderData);
+      const resultData = {
+        result: ""
+      };
+      if (this.isCacheEnabled(renderData.options)) {
+        const cached = this._cache.get(renderData.content, renderData.options);
+        if (cached) {
+          return cached;
+        }
+      }
+      const file = await engine.process(renderData.body);
+      resultData.result = String(file);
+      if (this.isCacheEnabled(renderData.options)) {
+        this._cache.set(renderData.content, resultData.result, renderData.options);
       }
-      return result;
+      await this.hook("afterRender" /* afterRender */, resultData);
+      return resultData.result;
     } catch (error) {
       throw new Error(`Failed to render markdown: ${error.message}`);
     }
@@ -230,28 +248,74 @@ ${yamlString}---
    */
   renderSync(options) {
     try {
-      let result = "";
-      if (this.isCacheEnabled(options)) {
-        const cached = this._cache.get(this._content, options);
-        if (cached) {
-          return cached;
-        }
-      }
       let { engine } = this;
       if (options) {
         options = { ...this._options.renderOptions, ...options };
         engine = this.createProcessor(options);
       }
-      const file = engine.processSync(this.body);
-      result = String(file);
-      if (this.isCacheEnabled(options)) {
-        this._cache.set(this._content, result, options);
+      const renderData = {
+        content: this._content,
+        body: this.body,
+        options
+      };
+      this.hook("beforeRender" /* beforeRender */, renderData);
+      const resultData = {
+        result: ""
+      };
+      if (this.isCacheEnabled(renderData.options)) {
+        const cached = this._cache.get(renderData.content, renderData.options);
+        if (cached) {
+          return cached;
+        }
+      }
+      const file = engine.processSync(renderData.body);
+      resultData.result = String(file);
+      if (this.isCacheEnabled(renderData.options)) {
+        this._cache.set(renderData.content, resultData.result, renderData.options);
       }
-      return result;
+      this.hook("afterRender" /* afterRender */, resultData);
+      return resultData.result;
     } catch (error) {
       throw new Error(`Failed to render markdown: ${error.message}`);
     }
   }
+  /**
+   * Render the markdown content and save it to a file. If the directory doesn't exist it will be created.
+   * @param {string} filePath The file path to save the rendered markdown content to.
+   * @param {RenderOptions} [options] the render options.
+   */
+  async renderToFile(filePath, options) {
+    try {
+      const { writeFile, mkdir } = fs.promises;
+      const directoryPath = dirname(filePath);
+      const content = await this.render(options);
+      await mkdir(directoryPath, { recursive: true });
+      await writeFile(filePath, content, "utf8");
+    } catch (error) {
+      this.emit("error", error);
+      if (this._options.throwErrors) {
+        throw error;
+      }
+    }
+  }
+  /**
+   * Render the markdown content and save it to a file synchronously. If the directory doesn't exist it will be created.
+   * @param {string} filePath The file path to save the rendered markdown content to.
+   * @param {RenderOptions} [options] the render options.
+   */
+  renderToFileSync(filePath, options) {
+    try {
+      const directoryPath = dirname(filePath);
+      const content = this.renderSync(options);
+      fs.mkdirSync(directoryPath, { recursive: true });
+      fs.writeFileSync(filePath, content, "utf8");
+    } catch (error) {
+      this.emit("error", error);
+      if (this._options.throwErrors) {
+        throw error;
+      }
+    }
+  }
   /**
    * Render the markdown content to React.
    * @param {RenderOptions} [options] The render options.
@@ -295,10 +359,17 @@ ${yamlString}---
    * @returns {Promise<void>}
    */
   async saveToFile(filePath) {
-    const { writeFile, mkdir } = fs.promises;
-    const directoryPath = dirname(filePath);
-    await mkdir(directoryPath, { recursive: true });
-    await writeFile(filePath, this._content, "utf8");
+    try {
+      const { writeFile, mkdir } = fs.promises;
+      const directoryPath = dirname(filePath);
+      await mkdir(directoryPath, { recursive: true });
+      await writeFile(filePath, this._content, "utf8");
+    } catch (error) {
+      this.emit("error", error);
+      if (this._options.throwErrors) {
+        throw error;
+      }
+    }
   }
   /**
    * Save the markdown content to a file synchronously. If the directory doesn't exist it will be created.
@@ -306,9 +377,16 @@ ${yamlString}---
    * @returns {void}
    */
   saveToFileSync(filePath) {
-    const directoryPath = dirname(filePath);
-    fs.mkdirSync(directoryPath, { recursive: true });
-    fs.writeFileSync(filePath, this._content, "utf8");
+    try {
+      const directoryPath = dirname(filePath);
+      fs.mkdirSync(directoryPath, { recursive: true });
+      fs.writeFileSync(filePath, this._content, "utf8");
+    } catch (error) {
+      this.emit("error", error);
+      if (this._options.throwErrors) {
+        throw error;
+      }
+    }
   }
   isCacheEnabled(options) {
     if (options?.caching !== void 0) {
@@ -344,8 +422,8 @@ ${yamlString}---
     return processor;
   }
   mergeOptions(current, options) {
-    if (options.openai) {
-      current.openai = options.openai;
+    if (options.throwErrors !== void 0) {
+      current.throwErrors = options.throwErrors;
     }
     if (options.renderOptions) {
       current.renderOptions ??= {};
@@ -382,5 +460,6 @@ ${yamlString}---
   }
 };
 export {
-  Writr
+  Writr,
+  WritrHooks
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "writr",
-  "version": "4.1.4",
+  "version": "4.3.0",
   "description": "Markdown Rendering Simplified",
   "type": "module",
   "main": "./dist/writr.js",
@@ -53,11 +53,11 @@
     "website:serve": "rimraf ./site/README.md ./site/dist && npx docula serve -s ./site -o ./site/dist"
   },
   "dependencies": {
-    "cacheable": "^1.8.2",
-    "hookified": "^1.5.0",
-    "html-react-parser": "^5.1.18",
+    "cacheable": "^1.8.7",
+    "hookified": "^1.6.0",
+    "html-react-parser": "^5.2.2",
     "js-yaml": "^4.1.0",
-    "react": "^18.3.1",
+    "react": "^19.0.0",
     "rehype-highlight": "^7.0.1",
     "rehype-katex": "^7.0.1",
     "rehype-slug": "^6.0.0",
@@ -73,17 +73,17 @@
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^22.8.4",
-    "@types/react": "^18.3.12",
-    "@vitest/coverage-v8": "^2.1.4",
-    "docula": "^0.9.4",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.0.2",
+    "@vitest/coverage-v8": "^2.1.8",
+    "docula": "^0.9.6",
     "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",
     "tsup": "^8.3.5",
-    "typescript": "^5.6.3",
-    "vitest": "^2.1.4",
-    "webpack": "^5.95.0",
-    "xo": "^0.59.3"
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "webpack": "^5.97.1",
+    "xo": "^0.60.0"
   },
   "xo": {
     "ignores": [