writr 6.1.1 → 6.1.3

package/README.md

@@ -67,6 +67,7 @@
   - [AI Provider Configuration](#ai-provider-configuration)
   - [Metadata](#metadata)
     - [Generating Metadata](#generating-metadata)
+    - [Constraining Generated Values](#constraining-generated-values)
     - [Applying Metadata to Frontmatter](#applying-metadata-to-frontmatter)
     - [Overwrite](#overwrite)
     - [Field Mapping](#field-mapping)
@@ -867,6 +868,55 @@ const partial = await writr.ai.getMetadata({
 | `readingTime` | `number` | Estimated reading time in minutes (computed, not AI-generated). |
 | `wordCount` | `number` | Total word count of the document (computed, not AI-generated). |
 
+### Constraining Generated Values
+
+When you have a controlled vocabulary — for example a CMS taxonomy, a fixed set of categories, or an SEO keyword list — pass `allowedTags`, `allowedKeywords`, or `allowedCategories` and the AI will pick only from that list. When omitted, the AI generates freely.
+
+```typescript
+const metadata = await writr.ai.getMetadata({
+  allowedTags: ['javascript', 'typescript', 'python', 'rust'],
+  allowedKeywords: ['async', 'promises', 'callbacks'],
+  allowedCategories: ['tutorial', 'guide', 'reference', 'blog'],
+});
+
+// metadata.tags is guaranteed to be a subset of allowedTags
+// metadata.category is guaranteed to be one of allowedCategories
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `allowedTags` | `string[]` | Constrains AI-generated tags to this list. A non-empty array implicitly enables `tags`. |
+| `allowedKeywords` | `string[]` | Constrains AI-generated keywords to this list. A non-empty array implicitly enables `keywords`. |
+| `allowedCategories` | `string[]` | Constrains AI-generated category to one of these values. A non-empty array implicitly enables `category`. |
+
+**How the constraint is enforced**
+
+The constraint is applied on three reinforcing layers, so the model both *knows about* and is *prevented from violating* the list:
+
+1. **Schema enforcement (the hard guarantee).** The Zod response schema uses `z.array(z.enum(allowedTags))` for tags, `z.array(z.enum(allowedKeywords))` for keywords, and `z.enum(allowedCategories)` for category. The AI SDK's structured-output mode forces the model to return values from the enum — it literally cannot produce anything outside the list.
+2. **Prompt instruction.** A `Constraints:` block is appended to the prompt with lines like `Tags must be selected from: foo, bar, baz` and `Category must be one of: tutorial, guide, reference`, so the model also sees the list in natural language.
+3. **Schema field description.** The Zod field description is rewritten to inline the allowed values (e.g. `Human-friendly labels selected from: foo, bar, baz`), which most providers surface to the model alongside the schema.
+
+**Behavior notes**
+
+- Providing a **non-empty** `allowed*` array implicitly enables the corresponding field — you don't also need `tags: true`.
+- Setting the field explicitly to `false` disables it even when an `allowed*` list is provided.
+- An **empty** array (`allowedTags: []`) does **not** implicitly enable the field. If you want unconstrained generation, either omit the option or pair the empty array with the explicit flag (e.g. `{ tags: true, allowedTags: [] }`) — `z.enum` requires at least one value, so the empty-array path uses `z.string()` and drops the prompt constraint.
+- These also work via `applyMetadata({ generate: { allowedTags: [...] } })`.
+
+```typescript
+// Implicit enablement: tags is generated, even without `tags: true`
+const metadata = await writr.ai.getMetadata({
+  allowedTags: ['docs', 'guide', 'blog'],
+});
+
+// Explicit `false` wins: tags is not generated
+const metadata = await writr.ai.getMetadata({
+  tags: false,
+  allowedTags: ['docs', 'guide', 'blog'],
+});
+```
+
 ### Applying Metadata to Frontmatter
 
 `applyMetadata()` generates metadata and writes it into the document's frontmatter. The result tells you exactly what happened:

package/dist/writr.d.mts

@@ -0,0 +1,592 @@
+import { Hookified, HookifiedOptions } from "hookified";
+import { HTMLReactParserOptions } from "html-react-parser";
+import { Processor } from "unified";
+import { CacheableMemory } from "cacheable";
+import { LanguageModel } from "ai";
+import React from "react";
+
+//#region src/types.d.ts
+/**
+ * Writr options.
+ * @typedef {Object} WritrOptions
+ * @property {RenderOptions} [renderOptions] - Default render options (default: undefined)
+ */
+type WritrOptions = {
+  renderOptions?: RenderOptions;
+  ai?: WritrAIOptions;
+} & HookifiedOptions;
+/**
+ * Render options.
+ * @typedef {Object} RenderOptions
+ * @property {boolean} [emoji] - Emoji support (default: true)
+ * @property {boolean} [toc] - Table of contents generation (default: true)
+ * @property {boolean} [slug] - Slug generation (default: true)
+ * @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: false)
+ * @property {boolean} [rawHtml] - Raw HTML passthrough (default: false)
+ * @property {boolean} [caching] - Caching (default: true)
+ */
+type RenderOptions = {
+  emoji?: boolean;
+  toc?: boolean;
+  slug?: boolean;
+  highlight?: boolean;
+  gfm?: boolean;
+  math?: boolean;
+  mdx?: boolean;
+  rawHtml?: boolean;
+  caching?: boolean;
+};
+/**
+ * Validation result.
+ * @typedef {Object} WritrValidateResult
+ * @property {boolean} valid - Whether the markdown is valid
+ * @property {Error} [error] - Error if validation failed
+ */
+type WritrValidateResult = {
+  valid: boolean;
+  error?: Error;
+};
+declare enum WritrHooks {
+  beforeRender = "beforeRender",
+  afterRender = "afterRender",
+  saveToFile = "saveToFile",
+  renderToFile = "renderToFile",
+  loadFromFile = "loadFromFile"
+}
+/**
+ * Metadata generated for a markdown document.
+ */
+type WritrMetadata = {
+  /**
+   * The best-fit title for the document.
+   */
+  title?: string;
+  /**
+   * Human-friendly labels for organizing the document.
+   */
+  tags?: string[];
+  /**
+   * Search-oriented terms related to the document.
+   */
+  keywords?: string[];
+  /**
+   * A concise meta-style description of the document.
+   */
+  description?: string;
+  /**
+   * A short teaser or preview of the content.
+   */
+  preview?: string;
+  /**
+   * A slightly longer overview of the document.
+   */
+  summary?: string;
+  /**
+   * A broad grouping for the document such as "docs", "guide", or "blog".
+   */
+  category?: string;
+  /**
+   * The primary subject the document is about.
+   */
+  topic?: string;
+  /**
+   * The intended audience for the document.
+   */
+  audience?: string;
+  /**
+   * The estimated skill level required to understand the document.
+   */
+  difficulty?: "beginner" | "intermediate" | "advanced";
+  /**
+   * Estimated reading time in minutes.
+   */
+  readingTime?: number;
+  /**
+   * Total number of words in the document.
+   */
+  wordCount?: number;
+};
+/**
+ * Search and social metadata for a markdown document.
+ */
+type WritrSEO = {
+  /**
+   * A URL-safe identifier for the document.
+   */
+  slug?: string;
+  /**
+   * Open Graph metadata used by social platforms.
+   */
+  openGraph?: {
+    /**
+     * The social sharing title for the document.
+     */
+    title?: string;
+    /**
+     * The social sharing description for the document.
+     */
+    description?: string;
+    /**
+     * The image URL to use when the document is shared socially.
+     */
+    image?: string;
+  };
+};
+/**
+ * A valid metadata key from {@link WritrMetadata}.
+ */
+type WritrMetadataKey = keyof WritrMetadata;
+/**
+ * Custom prompt templates used by WritrAI.
+ */
+type WritrAIPrompts = {
+  /**
+   * Custom prompt template used for metadata generation.
+   */
+  metadata?: string;
+  /**
+   * Custom prompt template used for SEO generation.
+   */
+  seo?: string;
+  /**
+   * Custom prompt template used for translation.
+   */
+  translation?: string;
+};
+/**
+ * Options used to configure a {@link WritrAI} instance.
+ */
+type WritrAIOptions = {
+  /**
+   * The AI SDK model instance used for generation.
+   * Example: `openai("gpt-4.1-mini")`.
+   */
+  model: LanguageModel;
+  /**
+   * Enables the in-memory AI cache when true.
+   */
+  cache?: boolean;
+  /**
+   * Optional prompt overrides for metadata, SEO, and translation.
+   */
+  prompts?: WritrAIPrompts;
+};
+/**
+ * Controls which metadata fields should be generated.
+ * When omitted, WritrAI generates all supported metadata fields.
+ */
+type WritrGetMetadataOptions = {
+  /**
+   * Generate a title for the document.
+   */
+  title?: boolean;
+  /**
+   * Generate tags for the document.
+   */
+  tags?: boolean;
+  /**
+   * Generate keywords for the document.
+   */
+  keywords?: boolean;
+  /**
+   * Generate a meta-style description for the document.
+   */
+  description?: boolean;
+  /**
+   * Generate a short teaser or preview for the document.
+   */
+  preview?: boolean;
+  /**
+   * Generate a longer summary for the document.
+   */
+  summary?: boolean;
+  /**
+   * Generate a broad category for the document.
+   */
+  category?: boolean;
+  /**
+   * Generate the primary topic for the document.
+   */
+  topic?: boolean;
+  /**
+   * Generate the intended audience for the document.
+   */
+  audience?: boolean;
+  /**
+   * Generate a difficulty level for the document.
+   */
+  difficulty?: boolean;
+  /**
+   * Include a deterministic reading time estimate.
+   */
+  readingTime?: boolean;
+  /**
+   * Include a deterministic word count.
+   */
+  wordCount?: boolean;
+  /**
+   * When provided, constrains AI-generated tags to only values from this list.
+   * Has no effect when `tags` is explicitly `false`.
+   */
+  allowedTags?: string[];
+  /**
+   * When provided, constrains AI-generated keywords to only values from this list.
+   * Has no effect when `keywords` is explicitly `false`.
+   */
+  allowedKeywords?: string[];
+  /**
+   * When provided, constrains the AI-generated category to only values from this list.
+   * Has no effect when `category` is explicitly `false`.
+   */
+  allowedCategories?: string[];
+};
+/**
+ * Controls which SEO fields should be generated.
+ * When omitted, WritrAI generates all supported SEO fields.
+ */
+type WritrGetSEOOptions = {
+  /**
+   * Generate a URL-safe slug.
+   */
+  slug?: boolean;
+  /**
+   * Generate Open Graph metadata for the document.
+   */
+  openGraph?: boolean;
+};
+/**
+ * Options used when generating a translated document.
+ */
+type WritrTranslationOptions = {
+  /**
+   * The target language or locale to translate the document into.
+   */
+  to: string;
+  /**
+   * The source language or locale of the document when known.
+   */
+  from?: string;
+  /**
+   * When true, frontmatter string values may also be translated.
+   */
+  translateFrontMatter?: boolean;
+};
+/**
+ * Options used when applying generated metadata to frontmatter.
+ */
+type WritrApplyMetadataOptions = {
+  /**
+   * Controls overwrite behavior for existing frontmatter values.
+   *
+   * - `true` overwrites all generated fields.
+   * - `false` or `undefined` fills only missing fields.
+   * - `WritrMetadataKey[]` overwrites only the specified fields.
+   */
+  overwrite?: boolean | WritrMetadataKey[];
+  /**
+   * Maps metadata keys to custom frontmatter field names.
+   */
+  fieldMap?: Partial<Record<WritrMetadataKey, string>>;
+  /**
+   * Controls which metadata fields should be generated before applying them.
+   */
+  generate?: WritrGetMetadataOptions;
+};
+/**
+ * Result returned after metadata has been applied to frontmatter.
+ */
+type WritrApplyMetadataResult = {
+  /**
+   * The Writr instance after metadata application.
+   */
+  writr: Writr;
+  /**
+   * The full metadata object that was generated during this operation.
+   */
+  generated: WritrMetadata;
+  /**
+   * Metadata fields that were newly written because they were missing.
+   */
+  applied: WritrMetadataKey[];
+  /**
+   * Metadata fields that replaced existing frontmatter values.
+   */
+  overwritten: WritrMetadataKey[];
+  /**
+   * Metadata fields that were generated but not written because
+   * they already existed and were not allowed to be overwritten.
+   */
+  skipped: WritrMetadataKey[];
+};
+//#endregion
+//#region src/writr-cache.d.ts
+declare class WritrCache {
+  private readonly _store;
+  private readonly _hashStore;
+  private readonly _hash;
+  get store(): CacheableMemory;
+  get hashStore(): CacheableMemory;
+  get(markdown: string, options?: RenderOptions): string | undefined;
+  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;
+}
+//#endregion
+//#region src/writr-ai-cache.d.ts
+declare class WritrAICache {
+  private readonly _store;
+  private readonly _hashStore;
+  private readonly _hash;
+  get store(): CacheableMemory;
+  get hashStore(): CacheableMemory;
+  get<T>(key: string, context: string): T | undefined;
+  set<T>(key: string, context: string, value: T): void;
+  hash(key: string, context: string): string;
+  clear(): void;
+}
+//#endregion
+//#region src/writr-ai.d.ts
+/**
+ * AI companion for a {@link Writr} instance.
+ *
+ * WritrAI provides metadata generation, SEO generation,
+ * translation, and metadata application for markdown documents.
+ */
+declare class WritrAI {
+  readonly writr: Writr;
+  /**
+   * The AI SDK model used for all generation requests.
+   */
+  model: LanguageModel;
+  /**
+   * The prompt templates used by this WritrAI instance.
+   */
+  prompts: WritrAIPrompts;
+  /**
+   * Optional in-memory cache for generated AI results.
+   */
+  cache?: WritrAICache;
+  /**
+   * 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: Writr, options: WritrAIOptions);
+  /**
+   * Generates metadata for the current markdown document.
+   *
+   * Pass `allowedTags`, `allowedKeywords`, or `allowedCategories` to constrain the
+   * AI to a controlled vocabulary — values are enforced via a Zod response schema
+   * (`z.array(z.enum(...))` for tags/keywords, `z.enum(...)` for category) so the
+   * model cannot return anything outside the list. Providing a non-empty `allowed*`
+   * array also implicitly enables its corresponding field.
+   *
+   * @param options - Controls which metadata fields should be generated.
+   * @returns A metadata object for the current document.
+   *
+   * @example
+   * ```typescript
+   * const metadata = await writr.ai.getMetadata({
+   *   allowedTags: ['javascript', 'typescript', 'python'],
+   *   allowedCategories: ['tutorial', 'guide', 'blog'],
+   * });
+   * // metadata.tags ⊆ allowedTags, metadata.category ∈ allowedCategories
+   * ```
+   */
+  getMetadata(options?: WritrGetMetadataOptions): Promise<WritrMetadata>;
+  /**
+   * 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.
+   */
+  getSEO(options?: WritrGetSEOOptions): Promise<WritrSEO>;
+  /**
+   * Generates a translated version of the current document.
+   *
+   * @param options - Translation settings including target locale.
+   * @returns A new translated Writr instance.
+   */
+  getTranslation(options: WritrTranslationOptions): Promise<Writr>;
+  /**
+   * 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.
+   */
+  applyMetadata(options?: WritrApplyMetadataOptions): Promise<WritrApplyMetadataResult>;
+  private resolveMetadataFields;
+  private resolveSEOFields;
+  private buildMetadataSchema;
+  private buildSEOSchema;
+  private computeWordCount;
+  private computeReadingTime;
+  private stripCodeFence;
+}
+//#endregion
+//#region src/writr.d.ts
+declare class Writr extends Hookified {
+  engine: Processor<any, any, any, any, any>;
+  private readonly _options;
+  private _content;
+  private readonly _cache;
+  private _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.
+   * @param {WritrOptions} [arguments2] This is if you send in the content in the first argument and also want to send in options.
+   *
+   * @example
+   * const writr = new Writr('Hello, world!', {caching: false});
+   */
+  constructor(arguments1?: string | WritrOptions, arguments2?: WritrOptions);
+  /**
+   * Get the options.
+   * @type {WritrOptions}
+   */
+  get options(): WritrOptions;
+  /**
+   * Get the WritrAI instance if AI options were provided.
+   * @type {WritrAI | undefined}
+   */
+  get ai(): WritrAI | undefined;
+  /**
+   * Get the Content. This is the markdown content and front matter if it exists.
+   * @type {WritrOptions}
+   */
+  get content(): string;
+  /**
+   * Set the Content. This is the markdown content and front matter if it exists.
+   * @type {WritrOptions}
+   */
+  set content(value: string);
+  /**
+   * Get the cache.
+   * @type {WritrCache}
+   */
+  get cache(): WritrCache;
+  /**
+   * Get the front matter raw content.
+   * @type {string} The front matter content including the delimiters.
+   */
+  get frontMatterRaw(): string;
+  /**
+   * Get the body content without the front matter.
+   * @type {string} The markdown content without the front matter.
+   */
+  get body(): string;
+  /**
+   * Get the markdown content. This is an alias for the body property.
+   * @type {string} The markdown content.
+   */
+  get markdown(): string;
+  /**
+   * Get the front matter content as an object.
+   * @type {Record<string, any>} The front matter content as an object.
+   */
+  get frontMatter(): Record<string, any>;
+  /**
+   * Set the front matter content as an object.
+   * @type {Record<string, any>} The front matter content as an object.
+   */
+  set frontMatter(data: Record<string, any>);
+  /**
+   * Get the front matter value for a key.
+   * @param {string} key The key to get the value for.
+   * @returns {T} The value for the key.
+   */
+  getFrontMatterValue<T>(key: string): T;
+  /**
+   * Render the markdown content to HTML.
+   * @param {RenderOptions} [options] The render options.
+   * @returns {Promise<string>} The rendered HTML content.
+   */
+  render(options?: RenderOptions): Promise<string>;
+  /**
+   * Render the markdown content to HTML synchronously.
+   * @param {RenderOptions} [options] The render options.
+   * @returns {string} The rendered HTML content.
+   */
+  renderSync(options?: RenderOptions): string;
+  /**
+   * Validate the markdown content by attempting to render it.
+   * @param {string} [content] The markdown content to validate. If not provided, uses the current content.
+   * @param {RenderOptions} [options] The render options.
+   * @returns {Promise<WritrValidateResult>} An object with a valid boolean and optional error.
+   */
+  validate(content?: string, options?: RenderOptions): Promise<WritrValidateResult>;
+  /**
+   * Validate the markdown content by attempting to render it synchronously.
+   * @param {string} [content] The markdown content to validate. If not provided, uses the current content.
+   * @param {RenderOptions} [options] The render options.
+   * @returns {WritrValidateResult} An object with a valid boolean and optional error.
+   */
+  validateSync(content?: string, options?: RenderOptions): WritrValidateResult;
+  /**
+   * 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.
+   * @param {HTMLReactParserOptions} [reactParseOptions] The HTML React parser options.
+   * @returns {Promise<string | React.JSX.Element | React.JSX.Element[]>} The rendered React content.
+   */
+  renderReact(options?: RenderOptions, reactParseOptions?: HTMLReactParserOptions): Promise<string | React.JSX.Element | React.JSX.Element[]>;
+  /**
+   * Render the markdown content to React synchronously.
+   * @param {RenderOptions} [options] The render options.
+   * @param {HTMLReactParserOptions} [reactParseOptions] The HTML React parser options.
+   * @returns {string | React.JSX.Element | React.JSX.Element[]} The rendered React content.
+   */
+  renderReactSync(options?: RenderOptions, reactParseOptions?: HTMLReactParserOptions): string | React.JSX.Element | React.JSX.Element[];
+  /**
+   * Load markdown content from a file.
+   * @param {string} filePath The file path to load the markdown content from.
+   * @returns {Promise<void>}
+   */
+  loadFromFile(filePath: string): Promise<void>;
+  /**
+   * Load markdown content from a file synchronously.
+   * @param {string} filePath The file path to load the markdown content from.
+   * @returns {void}
+   */
+  loadFromFileSync(filePath: string): void;
+  /**
+   * Save the markdown content to a file. If the directory doesn't exist it will be created.
+   * @param {string} filePath The file path to save the markdown content to.
+   * @returns {Promise<void>}
+   */
+  saveToFile(filePath: string): Promise<void>;
+  /**
+   * Save the markdown content to a file synchronously. If the directory doesn't exist it will be created.
+   * @param {string} filePath The file path to save the markdown content to.
+   * @returns {void}
+   */
+  saveToFileSync(filePath: string): void;
+  mergeOptions(current: WritrOptions, options: WritrOptions): WritrOptions;
+  private isCacheEnabled;
+  private createProcessor;
+  private mergeRenderOptions;
+}
+//#endregion
+export { type RenderOptions, Writr, WritrAI, WritrAICache, type WritrAIOptions, type WritrAIPrompts, type WritrApplyMetadataOptions, type WritrApplyMetadataResult, type WritrGetMetadataOptions, type WritrGetSEOOptions, WritrHooks, type WritrMetadata, type WritrMetadataKey, type WritrOptions, type WritrSEO, type WritrTranslationOptions, type WritrValidateResult };