writr 5.0.4 → 6.0.0

package/dist/writr.js

@@ -94,7 +94,7 @@ var WritrCache = class {
   }
 };
 
-// src/writr.ts
+// src/types.ts
 var WritrHooks = /* @__PURE__ */ ((WritrHooks2) => {
   WritrHooks2["beforeRender"] = "beforeRender";
   WritrHooks2["afterRender"] = "afterRender";
@@ -103,11 +103,362 @@ var WritrHooks = /* @__PURE__ */ ((WritrHooks2) => {
   WritrHooks2["loadFromFile"] = "loadFromFile";
   return WritrHooks2;
 })(WritrHooks || {});
+
+// src/writr-ai.ts
+import { generateText, Output } from "ai";
+import { z } from "zod";
+
+// src/writr-ai-cache.ts
+import { CacheableMemory as CacheableMemory2 } from "cacheable";
+import { Hashery as Hashery2 } from "hashery";
+var WritrAICache = class {
+  _store = new CacheableMemory2();
+  _hashStore = new CacheableMemory2();
+  _hash = new Hashery2();
+  get store() {
+    return this._store;
+  }
+  get hashStore() {
+    return this._hashStore;
+  }
+  get(key, context) {
+    const hash = this.hash(key, context);
+    return this._store.get(hash);
+  }
+  set(key, context, value) {
+    const hash = this.hash(key, context);
+    this._store.set(hash, value);
+  }
+  hash(key, context) {
+    const content = { key, context };
+    const cacheKey = JSON.stringify(content);
+    const result = this._hashStore.get(cacheKey);
+    if (result) {
+      return result;
+    }
+    const hash = this._hash.toHashSync(content);
+    this._hashStore.set(cacheKey, hash);
+    return hash;
+  }
+  clear() {
+    this._store.clear();
+    this._hashStore.clear();
+  }
+};
+
+// src/writr-ai.ts
+var AVERAGE_WORDS_PER_MINUTE = 200;
+var WritrAI = class {
+  /**
+   * Creates a new WritrAI instance bound to a specific Writr document.
+   *
+   * @param writr - The base Writr instance this AI helper operates on.
+   * @param options - The AI model and optional cache/prompt settings.
+   */
+  constructor(writr, options) {
+    this.writr = writr;
+    this.model = options.model;
+    this.prompts = options.prompts ?? {};
+    this.cache = options.cache ? new WritrAICache() : void 0;
+  }
+  /**
+   * The AI SDK model used for all generation requests.
+   */
+  model;
+  /**
+   * The prompt templates used by this WritrAI instance.
+   */
+  prompts;
+  /**
+   * Optional in-memory cache for generated AI results.
+   */
+  cache;
+  /**
+   * Generates metadata for the current markdown document.
+   *
+   * @param options - Controls which metadata fields should be generated.
+   * @returns A metadata object for the current document.
+   */
+  async getMetadata(options) {
+    const cacheKey = `metadata:${JSON.stringify(options ?? {})}`;
+    const cached = this.cache?.get(cacheKey, this.writr.content);
+    if (cached) {
+      return cached;
+    }
+    const fields = this.resolveMetadataFields(options);
+    const result = {};
+    if (fields.includes("wordCount")) {
+      result.wordCount = this.computeWordCount();
+    }
+    if (fields.includes("readingTime")) {
+      result.readingTime = this.computeReadingTime();
+    }
+    const aiFields = fields.filter(
+      (f) => f !== "wordCount" && f !== "readingTime"
+    );
+    if (aiFields.length > 0) {
+      const schema = this.buildMetadataSchema(aiFields);
+      const prompt = this.prompts.metadata ?? "Analyze the following markdown document and generate metadata for it. Be concise and accurate.";
+      const { output } = await generateText({
+        model: this.model,
+        output: Output.object({ schema }),
+        prompt: `${prompt}
+
+---
+
+${this.writr.content}`
+      });
+      Object.assign(result, output);
+    }
+    this.cache?.set(cacheKey, this.writr.content, result);
+    return result;
+  }
+  /**
+   * Generates SEO metadata for the current markdown document.
+   *
+   * @param options - Controls which SEO fields should be generated.
+   * @returns An SEO metadata object for the current document.
+   */
+  async getSEO(options) {
+    const cacheKey = `seo:${JSON.stringify(options ?? {})}`;
+    const cached = this.cache?.get(cacheKey, this.writr.content);
+    if (cached) {
+      return cached;
+    }
+    const fields = this.resolveSEOFields(options);
+    const schema = this.buildSEOSchema(fields);
+    const prompt = this.prompts.seo ?? "Analyze the following markdown document and generate SEO metadata for it. Be concise and accurate.";
+    const { output } = await generateText({
+      model: this.model,
+      output: Output.object({ schema }),
+      prompt: `${prompt}
+
+---
+
+${this.writr.content}`
+    });
+    const result = output;
+    this.cache?.set(cacheKey, this.writr.content, result);
+    return result;
+  }
+  /**
+   * Generates a translated version of the current document.
+   *
+   * @param options - Translation settings including target locale.
+   * @returns A new translated Writr instance.
+   */
+  async getTranslation(options) {
+    const cacheKey = `translation:${JSON.stringify(options)}`;
+    const cached = this.cache?.get(cacheKey, this.writr.content);
+    if (cached) {
+      return new Writr(cached);
+    }
+    const fromClause = options.from ? ` from ${options.from}` : "";
+    const frontMatterClause = options.translateFrontMatter ? " Also translate any string values in the YAML frontmatter." : " Preserve the YAML frontmatter exactly as-is without translating it.";
+    const prompt = this.prompts.translation ?? `Translate the following markdown document${fromClause} to ${options.to}.${frontMatterClause} Preserve all markdown formatting, links, code blocks, and structure. Return only the translated markdown document with no additional commentary.`;
+    let { text } = await generateText({
+      model: this.model,
+      prompt: `${prompt}
+
+---
+
+${this.writr.content}`
+    });
+    text = this.stripCodeFence(text);
+    this.cache?.set(cacheKey, this.writr.content, text);
+    return new Writr(text);
+  }
+  /**
+   * Generates metadata and applies it to the document frontmatter.
+   *
+   * @param options - Controls generation, overwrite behavior, and field mapping.
+   * @returns A result object describing what metadata was generated and applied.
+   */
+  async applyMetadata(options) {
+    const generated = await this.getMetadata(options?.generate);
+    const frontMatter = { ...this.writr.frontMatter };
+    const fieldMap = options?.fieldMap ?? {};
+    const overwrite = options?.overwrite;
+    const applied = [];
+    const overwritten = [];
+    const skipped = [];
+    const overwriteSet = Array.isArray(overwrite) ? new Set(overwrite) : void 0;
+    for (const key of Object.keys(generated)) {
+      const value = generated[key];
+      if (value === void 0) {
+        continue;
+      }
+      const frontMatterKey = fieldMap[key] ?? key;
+      const exists = frontMatterKey in frontMatter;
+      if (!exists) {
+        frontMatter[frontMatterKey] = value;
+        applied.push(key);
+      } else if (overwrite === true || overwriteSet?.has(key)) {
+        frontMatter[frontMatterKey] = value;
+        overwritten.push(key);
+      } else {
+        skipped.push(key);
+      }
+    }
+    this.writr.frontMatter = frontMatter;
+    return {
+      writr: this.writr,
+      generated,
+      applied,
+      overwritten,
+      skipped
+    };
+  }
+  resolveMetadataFields(options) {
+    const allFields = [
+      "title",
+      "tags",
+      "keywords",
+      "description",
+      "preview",
+      "summary",
+      "category",
+      "topic",
+      "audience",
+      "difficulty",
+      "readingTime",
+      "wordCount"
+    ];
+    if (!options) {
+      return allFields;
+    }
+    return allFields.filter(
+      (field) => options[field] === true
+    );
+  }
+  resolveSEOFields(options) {
+    const allFields = ["slug", "canonical", "openGraph"];
+    if (!options) {
+      return allFields;
+    }
+    return allFields.filter(
+      (field) => options[field] === true
+    );
+  }
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic schema construction
+  buildMetadataSchema(fields) {
+    const fieldSet = new Set(fields);
+    const entries = [];
+    if (fieldSet.has("title")) {
+      entries.push([
+        "title",
+        z.string().describe("The best-fit title for the document")
+      ]);
+    }
+    if (fieldSet.has("tags")) {
+      entries.push([
+        "tags",
+        z.array(z.string()).describe("Human-friendly labels for organizing the document")
+      ]);
+    }
+    if (fieldSet.has("keywords")) {
+      entries.push([
+        "keywords",
+        z.array(z.string()).describe("Search-oriented terms related to the document")
+      ]);
+    }
+    if (fieldSet.has("description")) {
+      entries.push([
+        "description",
+        z.string().describe("A concise meta-style description of the document")
+      ]);
+    }
+    if (fieldSet.has("preview")) {
+      entries.push([
+        "preview",
+        z.string().describe("A short teaser or preview of the content")
+      ]);
+    }
+    if (fieldSet.has("summary")) {
+      entries.push([
+        "summary",
+        z.string().describe("A slightly longer overview of the document")
+      ]);
+    }
+    if (fieldSet.has("category")) {
+      entries.push([
+        "category",
+        z.string().describe('A broad grouping such as "docs", "guide", or "blog"')
+      ]);
+    }
+    if (fieldSet.has("topic")) {
+      entries.push([
+        "topic",
+        z.string().describe("The primary subject the document is about")
+      ]);
+    }
+    if (fieldSet.has("audience")) {
+      entries.push([
+        "audience",
+        z.string().describe(
+          'The intended audience such as "developers" or "beginners"'
+        )
+      ]);
+    }
+    if (fieldSet.has("difficulty")) {
+      entries.push([
+        "difficulty",
+        z.enum(["beginner", "intermediate", "advanced"]).describe(
+          "The estimated skill level required to understand the document"
+        )
+      ]);
+    }
+    return z.object(Object.fromEntries(entries));
+  }
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic schema construction
+  buildSEOSchema(fields) {
+    const fieldSet = new Set(fields);
+    const entries = [];
+    if (fieldSet.has("slug")) {
+      entries.push([
+        "slug",
+        z.string().describe("A URL-safe identifier for the document")
+      ]);
+    }
+    if (fieldSet.has("canonical")) {
+      entries.push([
+        "canonical",
+        z.string().describe("The preferred canonical URL for the document")
+      ]);
+    }
+    if (fieldSet.has("openGraph")) {
+      entries.push([
+        "openGraph",
+        z.object({
+          title: z.string().describe("The social sharing title"),
+          description: z.string().describe("The social sharing description"),
+          image: z.string().describe("The image URL for social sharing").nullable()
+        }).describe("Open Graph metadata")
+      ]);
+    }
+    return z.object(Object.fromEntries(entries));
+  }
+  computeWordCount() {
+    const text = this.writr.body;
+    const words = text.replace(/```[\s\S]*?```/g, "").replace(/`[^`]*`/g, "").replace(/[#*_[\]()>~|-]/g, " ").split(/\s+/).filter((word) => word.length > 0);
+    return words.length;
+  }
+  computeReadingTime() {
+    const wordCount = this.computeWordCount();
+    return Math.max(1, Math.ceil(wordCount / AVERAGE_WORDS_PER_MINUTE));
+  }
+  stripCodeFence(text) {
+    const trimmed = text.trim();
+    const match = /^```\w*\n([\s\S]*?)```$/.exec(trimmed);
+    return match ? match[1].trim() : text;
+  }
+};
+
+// src/writr.ts
 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(rehypeStringify);
   // Stringify HTML
   _options = {
-    throwErrors: false,
     renderOptions: {
       emoji: true,
       toc: true,
@@ -121,6 +472,7 @@ var Writr = class extends Hookified {
   };
   _content = "";
   _cache = new WritrCache();
+  _ai;
   /**
    * Initialize Writr. Accepts a string or options object.
    * @param {string | WritrOptions} [arguments1] If you send in a string, it will be used as the markdown content. If you send in an object, it will be used as the options.
@@ -130,7 +482,13 @@ var Writr = class extends Hookified {
    * const writr = new Writr('Hello, world!', {caching: false});
    */
   constructor(arguments1, arguments2) {
-    super();
+    const options = typeof arguments1 === "object" ? arguments1 : arguments2;
+    super({
+      throwOnEmitError: options?.throwOnEmitError,
+      throwOnHookError: options?.throwOnHookError,
+      throwOnEmptyListeners: options?.throwOnEmptyListeners,
+      eventLogger: options?.eventLogger
+    });
     if (typeof arguments1 === "string") {
       this._content = arguments1;
     } else if (arguments1) {
@@ -145,6 +503,9 @@ var Writr = class extends Hookified {
         this.engine = this.createProcessor(this._options.renderOptions);
       }
     }
+    if (this._options.ai) {
+      this._ai = new WritrAI(this, this._options.ai);
+    }
   }
   /**
    * Get the options.
@@ -153,6 +514,13 @@ var Writr = class extends Hookified {
   get options() {
     return this._options;
   }
+  /**
+   * Get the WritrAI instance if AI options were provided.
+   * @type {WritrAI | undefined}
+   */
+  get ai() {
+    return this._ai;
+  }
   /**
    * Get the Content. This is the markdown content and front matter if it exists.
    * @type {WritrOptions}
@@ -290,8 +658,8 @@ ${yamlString}---
       return resultData.result;
     } catch (error) {
       this.emit("error", error);
-      throw new Error(`Failed to render markdown: ${error.message}`);
     }
+    return "";
   }
   /**
    * Render the markdown content to HTML synchronously.
@@ -333,8 +701,8 @@ ${yamlString}---
       return resultData.result;
     } catch (error) {
       this.emit("error", error);
-      throw new Error(`Failed to render markdown: ${error.message}`);
     }
+    return "";
   }
   /**
    * Validate the markdown content by attempting to render it.
@@ -363,7 +731,6 @@ ${yamlString}---
       }
       return { valid: true };
     } catch (error) {
-      this.emit("error", error);
       if (content !== void 0) {
         this._content = originalContent;
       }
@@ -423,9 +790,6 @@ ${yamlString}---
       await writeFile(data.filePath, data.content);
     } catch (error) {
       this.emit("error", error);
-      if (this._options.throwErrors) {
-        throw error;
-      }
     }
   }
   /**
@@ -446,9 +810,6 @@ ${yamlString}---
       fs.writeFileSync(data.filePath, data.content);
     } catch (error) {
       this.emit("error", error);
-      if (this._options.throwErrors) {
-        throw error;
-      }
     }
   }
   /**
@@ -463,8 +824,8 @@ ${yamlString}---
       return parse(html, reactParseOptions);
     } catch (error) {
       this.emit("error", error);
-      throw new Error(`Failed to render React: ${error.message}`);
     }
+    return "";
   }
   /**
    * Render the markdown content to React synchronously.
@@ -478,8 +839,8 @@ ${yamlString}---
       return parse(html, reactParseOptions);
     } catch (error) {
       this.emit("error", error);
-      throw new Error(`Failed to render React: ${error.message}`);
     }
+    return "";
   }
   /**
    * Load markdown content from a file.
@@ -497,9 +858,6 @@ ${yamlString}---
       this._content = data.content;
     } catch (error) {
       this.emit("error", error);
-      if (this._options.throwErrors) {
-        throw error;
-      }
     }
   }
   /**
@@ -517,9 +875,6 @@ ${yamlString}---
       this._content = data.content;
     } catch (error) {
       this.emit("error", error);
-      if (this._options.throwErrors) {
-        throw error;
-      }
     }
   }
   /**
@@ -540,9 +895,6 @@ ${yamlString}---
       await writeFile(data.filePath, data.content);
     } catch (error) {
       this.emit("error", error);
-      if (this._options.throwErrors) {
-        throw error;
-      }
     }
   }
   /**
@@ -562,19 +914,19 @@ ${yamlString}---
       fs.writeFileSync(data.filePath, data.content);
     } catch (error) {
       this.emit("error", error);
-      if (this._options.throwErrors) {
-        throw error;
-      }
     }
   }
   mergeOptions(current, options) {
-    if (options.throwErrors !== void 0) {
-      current.throwErrors = options.throwErrors;
+    if (options.throwOnEmitError !== void 0) {
+      this.throwOnEmitError = options.throwOnEmitError;
     }
     if (options.renderOptions) {
       current.renderOptions ??= {};
       this.mergeRenderOptions(current.renderOptions, options.renderOptions);
     }
+    if (options.ai) {
+      current.ai = options.ai;
+    }
     return current;
   }
   isCacheEnabled(options) {
@@ -642,6 +994,8 @@ ${yamlString}---
 };
 export {
   Writr,
+  WritrAI,
+  WritrAICache,
   WritrHooks
 };
 /* v8 ignore next -- @preserve */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "writr",
-  "version": "5.0.4",
+  "version": "6.0.0",
   "description": "Markdown Rendering Simplified",
   "type": "module",
   "main": "./dist/writr.js",
@@ -49,9 +49,10 @@
     "markdown-to-react"
   ],
   "dependencies": {
-    "cacheable": "^2.3.1",
+    "ai": "^6.0.116",
+    "cacheable": "^2.3.3",
     "hashery": "^1.5.0",
-    "hookified": "^1.15.1",
+    "hookified": "^2.1.0",
     "html-react-parser": "^5.2.17",
     "js-yaml": "^4.1.1",
     "react": "^19.2.4",
@@ -61,31 +62,36 @@
     "rehype-stringify": "^10.0.1",
     "remark-emoji": "^5.0.2",
     "remark-gfm": "^4.0.1",
-    "remark-github-blockquote-alert": "^2.0.1",
+    "remark-github-blockquote-alert": "^2.1.0",
     "remark-math": "^6.0.0",
     "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
     "remark-toc": "^9.0.0",
-    "unified": "^11.0.5"
+    "unified": "^11.0.5",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.4",
+    "@ai-sdk/anthropic": "^3.0.58",
+    "@ai-sdk/google": "^3.0.43",
+    "@ai-sdk/openai": "^3.0.41",
+    "@biomejs/biome": "^2.4.7",
     "@monstermann/tinybench-pretty-printer": "^0.3.0",
     "@types/js-yaml": "^4.0.9",
     "@types/markdown-it": "^14.1.2",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.5.0",
     "@types/react": "^19.2.14",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "^4.1.0",
     "docula": "^0.40.0",
+    "dotenv": "^17.3.1",
     "markdown-it": "^14.1.1",
-    "marked": "^17.0.3",
+    "marked": "^17.0.4",
     "rimraf": "^6.1.3",
     "tinybench": "^6.0.0",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   },
   "files": [
     "dist",
@@ -99,6 +105,7 @@
     "benchmark": "tsx benchmark/benchmark-minimal.ts && tsx benchmark/benchmark-standard.ts",
     "test": "pnpm lint && vitest run --coverage",
     "test:ci": "biome check --error-on-warnings && vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
     "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"
   }