legal-markdown-js
Version:
Node.js implementation of LegalMarkdown for processing legal documents with markdown and YAML - Complete feature parity with Ruby version
169 lines • 5.46 kB
TypeScript
/**
* Branded types for differentiating content formats
*
* This module provides type-safe wrappers for string content to prevent
* accidentally mixing Markdown, HTML, and plain text formats. Using branded
* types allows TypeScript to catch format mismatches at compile time.
*
* @example
* ```typescript
* // Type-safe conversion
* const markdown = asMarkdown('# Title\n\nContent');
* const html = await generateHtml(markdown); // ✅ Type-safe
*
* // This will cause a TypeScript error:
* const html = '<h1>Title</h1>';
* await generateHtml(html); // ❌ Type error: HTML cannot be passed as Markdown
* ```
*
* @module types/content-formats
*/
/**
* Branded type for Markdown-formatted content
*
* This type ensures that strings known to contain Markdown formatting
* cannot be accidentally used where HTML or plain text is expected.
*/
declare const markdownBrand: unique symbol;
export type MarkdownString = string & {
readonly [markdownBrand]: true;
};
/**
* Branded type for HTML-formatted content
*
* This type ensures that strings known to contain HTML markup
* cannot be accidentally used where Markdown or plain text is expected.
*/
declare const htmlBrand: unique symbol;
export type HtmlString = string & {
readonly [htmlBrand]: true;
};
/**
* Branded type for plain text content (no formatting)
*
* This type represents unformatted text without Markdown or HTML markup.
*/
declare const plainTextBrand: unique symbol;
export type PlainTextString = string & {
readonly [plainTextBrand]: true;
};
/**
* Type guard to check if content appears to be HTML
*
* Performs a heuristic check for HTML tags in the content.
* This is not foolproof but catches most common cases.
*
* @param content - The content to check
* @returns true if content appears to contain HTML tags
*
* @example
* ```typescript
* isHtml('<h1>Title</h1>'); // true
* isHtml('# Title'); // false
* isHtml('Plain text'); // false
* ```
*/
export declare function isHtml(content: string): boolean;
/**
* Type guard to check if content appears to be Markdown
*
* A simple heuristic: if it's not HTML, we assume it's Markdown or plain text.
* More sophisticated detection could check for Markdown syntax patterns.
*
* @param content - The content to check
* @returns true if content does not appear to be HTML
*
* @example
* ```typescript
* isMarkdown('# Title'); // true
* isMarkdown('Plain text'); // true
* isMarkdown('<h1>Title</h1>'); // false
* ```
*/
export declare function isMarkdown(content: string): boolean;
/**
* Converts a string to MarkdownString type
*
* This is a type assertion that should be used when you know the content
* is Markdown. For safety, consider validating with isMarkdown() first.
*
* @param content - The content to convert
* @returns The same content typed as MarkdownString
*
* @example
* ```typescript
* const markdown = asMarkdown('# Title\n\nContent');
* await generateHtml(markdown); // Type-safe
* ```
*/
export declare function asMarkdown(content: string): MarkdownString;
/**
* Converts a string to HtmlString type
*
* This is a type assertion that should be used when you know the content
* is HTML. For safety, consider validating with isHtml() first.
*
* @param content - The content to convert
* @returns The same content typed as HtmlString
*
* @example
* ```typescript
* const html = asHtml('<h1>Title</h1>');
* await renderHtml(html); // Type-safe
* ```
*/
export declare function asHtml(content: string): HtmlString;
/**
* Converts a string to PlainTextString type
*
* This is a type assertion that should be used when you know the content
* is plain text without formatting.
*
* @param content - The content to convert
* @returns The same content typed as PlainTextString
*
* @example
* ```typescript
* const plain = asPlainText('Just plain text');
* console.log(plain);
* ```
*/
export declare function asPlainText(content: string): PlainTextString;
/**
* Safely converts any string to MarkdownString after validation
*
* Throws an error if the content appears to be HTML instead of Markdown.
* Use this when you want runtime validation in addition to type safety.
*
* @param content - The content to validate and convert
* @param source - Optional description of where this content came from (for error messages)
* @returns The content typed as MarkdownString
* @throws {Error} If content appears to be HTML
*
* @example
* ```typescript
* const markdown = toMarkdown('# Title'); // ✅ OK
* const invalid = toMarkdown('<h1>Title</h1>'); // ❌ Throws error
* ```
*/
export declare function toMarkdown(content: string, source?: string): MarkdownString;
/**
* Safely converts any string to HtmlString after validation
*
* Validates that the content appears to contain HTML markup.
* Use this when you want runtime validation in addition to type safety.
*
* @param content - The content to validate and convert
* @param source - Optional description of where this content came from (for error messages)
* @returns The content typed as HtmlString
* @throws {Error} If content does not appear to be HTML
*
* @example
* ```typescript
* const html = toHtml('<h1>Title</h1>'); // ✅ OK
* const invalid = toHtml('# Title'); // ❌ Throws error
* ```
*/
export declare function toHtml(content: string, source?: string): HtmlString;
export {};
//# sourceMappingURL=content-formats.d.ts.map