remark-mdat/dist/lib/mdat/rules.d.ts

A remark plugin implementing the Markdown Autophagic Template (MDAT) system.

import type { JsonValue, Merge, MergeDeep, SetOptional, Simplify } from 'type-fest';
import { type Root } from 'mdast';
import { z } from 'zod';
export type SimplifyDeep<T> = Simplify<MergeDeep<T, T>>;
/**
 * Strict normalized rules used internally.
 * Rules normalized to a form with async content functions and other default metadata
 * Simplifies processing elsewhere, while retaining flexibility for rule authors
 */
export type NormalizedRule = {
    /**
     * The order in which the rule should be applied during processing
     * Helpful if a rule depends on the presence of content generated by another rule
     * Defaults to 0.
     */
    applicationOrder: number;
    /**
     * The function that generates the expanded Markdown string.
     * For 'compound' rules, this can be an array of rules (without keywords).
     */
    content: ((options: JsonValue, tree: Root) => Promise<string>) | NormalizedRule[];
    /**
     * The expected order of the keyword in the document relative to other expander comments.
     * Used for validation purposes.
     * Leave undefined to order skip validation.
     * Defaults to undefined, which means order is not enforced.
     */
    order: number | undefined;
    /**
     * Whether the presence of the keyword comment in the document is required.
     * Used for validation purposes.
     * Defaults to false.
     */
    required: boolean;
};
export type Rule = 
/**
 * Function that returns the Markdown string to expand at the comment site.
 */
((options: JsonValue, tree: Root) => Promise<string> | string)
/**
 * Compound rules may be defined an array of rules, without keywords.
 * Can be defined at the top level, if no validation metadata is required, or as the 'content' value
 * of a rule object with validation metadata.
 */
 | Rule[]
/**
 * The Markdown string to expand at the comment site.
 */
 | SetOptional<Merge<NormalizedRule, {
    /**
     * Gets content to expand into the comment.
     * Can be a simple string for direct replacement, a function that returns a string, or an async function that returns a string.
     *
     * If a function is provided, it will be passed the following arguments:
     * @param options
     * JSON value of options parsed immediately after the comment keyword in the comment, e.g.:
     * `<!-- keyword({something: true}) -->` or
     * `<!-- keyword {something: true}-->`
     * Sets options to {something: true}
     * @param tree
     * Markdown (mdast) abstract syntax tree containing the entire parsed document. Useful for expanders that need the entire document context, such as when generating a table of contents. Do not mutate the AST, instead return a new string.
     * @returns A string with the generated content. The string will be parsed as Markdown and inserted into the document at the comment's location.
     */
    content: ((options: JsonValue, tree: Root) => Promise<string> | string) | Rule[] | string;
}>, 'applicationOrder' | 'order' | 'required'> | string;
/**
 * Rules are record objects whose keys match strings inside a Markdown comment, and values explain what should be expanded at the comment site.
 *
 * The record value may be a string, or an object containing additional metadata, possibly with a function to invoke to generate content.
 * @example
 * Most basic rule:
 * ```ts
 * { basic: 'content' }
 * ```
 *
 * Rule with dynamic content:
 * ```ts
 * { basic: () => `${new Date().toISOString()}` }
 * ```
 *
 * Rule with metadata:
 * ```ts
 * { basic-meta: { required: true, content: 'content'} }
 * ```
 *
 * Rule with dynamic content and metadata:
 * { basic-date: { required: true, content: () => `${new Date().toISOString()}` } }
 */
export type Rules = SimplifyDeep<Record<string, Rule>>;
export type NormalizedRules = SimplifyDeep<Record<string, NormalizedRule>>;
export declare function normalizeRules(rules: Rules): NormalizedRules;
export declare function validateRules(rules: Rules): void;
export declare const rulesSchema: z.ZodRecord<z.ZodString, z.ZodType<any, z.ZodTypeDef, any>>;
/**
 * Compound rule helpers, used in both "expand" and "check" utilities
 */
export declare function getRuleContent(rule: NormalizedRule, options: JsonValue, tree: Root, check?: boolean): Promise<string>;
/**
 * Returns the rule value from a single-rule record.
 * Useful when aliasing rules or invoking them programmatically.
 *
 * Throws if there are no entries or more than one entry.
 */
export declare function getSoleRule<T extends NormalizedRules | Rules>(rules: T): T[keyof T];
/**
 * Returns the rule key from a single-rule record.
 * Useful for comment placeholder validation.
 *
 * Throws if there are no entries or more than one entry.
 */
export declare function getSoleRuleKey<T extends NormalizedRules | Rules>(rules: T): keyof T;