docs: annotate public api

Author: acrazing

src/config.ts

@@ -3,16 +3,31 @@
  * @since 2017-08-19 15:56:14
  */
 
-function createMap<T>(keys: string, value: T): Record<string, T> {
-  return keys.split(',').reduce((pre, now) => {
-    pre[now] = value;
-    return pre;
-  }, Object.create(null));
-}
-
-export const selfCloseTags = createMap<true>(
-  'area,base,br,col,embed,hr,img,input,link,meta,param,source,track,wbr,!doctype,,!,!--',
-  true,
-);
+/**
+ * HTML tags that do not require closing tags.
+ */
+export const selfCloseTags = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+  '!doctype',
+  '',
+  '!',
+  '!--',
+]);
 
-export const noNestedTags = createMap<true>('li,option,select,textarea', true);
+/**
+ * Tags that implicitly close a previous tag of the same name.
+ */
+export const noNestedTags = new Set(['li', 'option', 'select', 'textarea']);

src/parse.ts

@@ -16,10 +16,13 @@ interface IContext {
   tag: ITag;
 }
 
+/**
+ * Options that control AST construction.
+ */
 export interface ParseOptions {
-  // create tag's attributes map
-  // if true, will set ITag.attributeMap property
-  // as a `Record<string, IAttribute>`
+  /**
+   * Populate each tag node with an attribute lookup map.
+   */
   setAttributeMap: boolean;
 }
 
@@ -59,7 +62,7 @@ function pushNode(_node: ITag | IText) {
   } else if (
     _node.type === SyntaxKind.Tag &&
     _node.name === tagChain.tag.name &&
-    noNestedTags[_node.name]
+    noNestedTags.has(_node.name)
   ) {
     tagChain = tagChain.parent;
     pushNode(_node);
@@ -185,7 +188,7 @@ function parseOpenTag() {
     if (token.type === TokenKind.OpenTagEnd) {
       tag.end = tag.open.end = token.end + 1;
       tag.open.value = buffer.substring(tag.open.start, tag.open.end);
-      if (token.value === '' && !selfCloseTags[tag.name]) {
+      if (token.value === '' && !selfCloseTags.has(tag.name)) {
         tag.body = [];
         pushTagChain(tag);
       } else {
@@ -258,6 +261,9 @@ function parseCloseTag() {
   tagChain = _context;
 }
 
+/**
+ * Parse an HTML string into an AST.
+ */
 export function parse(input: string, options?: ParseOptions): INode[] {
   init(input, {
     setAttributeMap: false,

src/safeHtml.ts

@@ -8,13 +8,31 @@ import { parse } from './parse';
 import { SyntaxKind } from './types';
 import type { INode } from './types';
 
+/**
+ * Options used to sanitize and stringify HTML.
+ */
 export interface SafeHtmlOptions {
+  /**
+   * Tag names allowed in the sanitized output.
+   */
   allowedTags: string[];
+  /**
+   * Attribute names allowed on every allowed tag.
+   */
   allowedAttrs: string[];
+  /**
+   * Attribute names allowed only for specific tags.
+   */
   tagAllowedAttrs: Record<string, string[]>;
+  /**
+   * URL pattern allowed for href and src attributes.
+   */
   allowedUrl: RegExp;
 }
 
+/**
+ * Default safe HTML allowlist.
+ */
 export const safeHtmlDefaultOptions: SafeHtmlOptions = {
   allowedTags: [
     'a',
@@ -106,6 +124,9 @@ export const safeHtmlDefaultOptions: SafeHtmlOptions = {
   allowedUrl: /^(?:mailto|tel|https?|ftp|[^:]*[^a-z0-9.+-][^:]*):|^[^:]*$/i,
 };
 
+/**
+ * Sanitize an HTML string using the configured allowlist.
+ */
 export function safeHtml(input: string, options: Partial<SafeHtmlOptions> = {}): string {
   const config: SafeHtmlOptions = {
     ...safeHtmlDefaultOptions,
@@ -128,7 +149,7 @@ function stringify(ast: INode[], config: SafeHtmlOptions, input: string): string
       if (config.allowedTags.indexOf(node.name) === -1) {
         return '';
       }
-      if (selfCloseTags[node.name]) {
+      if (selfCloseTags.has(node.name)) {
         if (node.body !== void 0) {
           throw new Error(`self closed tag "${node.name}" should not have body`);
         }

src/tokenize.ts

@@ -21,22 +21,67 @@ const enum State {
   ClosingTag,
 }
 
+/**
+ * Token kinds emitted by tokenize.
+ */
 export const enum TokenKind {
+  /**
+   * Raw text outside tag syntax.
+   */
   Literal,
-  OpenTag, // trim leading '<'
-  OpenTagEnd, // trim tailing '>', only could be '/' or ''
-  CloseTag, // trim leading '</' and tailing '>'
-  Whitespace, // the whitespace between attributes
+  /**
+   * Opening tag name without the leading <.
+   */
+  OpenTag,
+  /**
+   * Opening tag end marker without the trailing >; value is / or empty.
+   */
+  OpenTagEnd,
+  /**
+   * Closing tag name without the leading </ or trailing >.
+   */
+  CloseTag,
+  /**
+   * Whitespace between attributes.
+   */
+  Whitespace,
+  /**
+   * Attribute value assignment marker.
+   */
   AttrValueEq,
+  /**
+   * Unquoted attribute value.
+   */
   AttrValueNq,
+  /**
+   * Single-quoted attribute value.
+   */
   AttrValueSq,
+  /**
+   * Double-quoted attribute value.
+   */
   AttrValueDq,
 }
 
+/**
+ * Token emitted by the HTML tokenizer.
+ */
 export interface IToken {
+  /**
+   * Zero-based start offset in the source string.
+   */
   start: number;
+  /**
+   * Zero-based end offset in the source string.
+   */
   end: number;
+  /**
+   * Raw token value after token-specific trimming.
+   */
   value: string;
+  /**
+   * Token category.
+   */
   type: TokenKind;
 }
 
@@ -115,6 +160,9 @@ function init(input: string) {
   offset = 0;
 }
 
+/**
+ * Convert an HTML string into a flat token stream.
+ */
 export function tokenize(input: string): IToken[] {
   init(input);
   while (index < bufSize) {

src/types.ts

@@ -3,53 +3,115 @@
  * @since 2017-08-18 15:17:51
  */
 
+/**
+ * Node kinds returned by the parser.
+ */
 export enum SyntaxKind {
+  /**
+   * Plain text content.
+   */
   Text = 'Text',
+  /**
+   * HTML tag node.
+   */
   Tag = 'Tag',
 }
 
+/**
+ * Common source range shared by every AST node.
+ */
 export interface IBaseNode {
+  /**
+   * Zero-based start offset in the source string.
+   */
   start: number;
+  /**
+   * Zero-based end offset in the source string.
+   */
   end: number;
 }
 
+/**
+ * Text node in the parsed AST.
+ */
 export interface IText extends IBaseNode {
+  /**
+   * Discriminator for text nodes.
+   */
   type: SyntaxKind.Text;
+  /**
+   * Original text content.
+   */
   value: string;
 }
 
+/**
+ * Parsed attribute value, with quote information preserved.
+ */
 export interface IAttributeValue extends IBaseNode {
+  /**
+   * Attribute value without surrounding quotes.
+   */
   value: string;
+  /**
+   * Quote character used by the source value, or undefined for unquoted values.
+   */
   quote: "'" | '"' | undefined;
 }
 
+/**
+ * Parsed tag attribute.
+ */
 export interface IAttribute extends IBaseNode {
+  /**
+   * Attribute name token.
+   */
   name: IText;
+  /**
+   * Attribute value, if the source provided one.
+   */
   value: IAttributeValue | undefined;
 }
 
+/**
+ * Tag node in the parsed AST.
+ */
 export interface ITag extends IBaseNode {
+  /**
+   * Discriminator for tag nodes.
+   */
   type: SyntaxKind.Tag;
-  // original open tag, <Div id="id">
+  /**
+   * Original opening tag text, such as <Div id="id">.
+   */
   open: IText;
-  // lower case tag name, div
+  /**
+   * Lowercase tag name, such as div.
+   */
   name: string;
-  // original case tag name, Div
+  /**
+   * Tag name with original casing, such as Div.
+   */
   rawName: string;
+  /**
+   * Attributes in source order.
+   */
   attributes: IAttribute[];
-  // the attribute map, if `options.setAttributeMap` is `true`
-  // this will be a Record, key is the attribute name literal,
-  // value is the attribute self.
+  /**
+   * Attribute lookup map when ParseOptions.setAttributeMap is true.
+   */
   attributeMap: Record<string, IAttribute> | undefined;
-  body:
-    | Array<ITag | IText> // with close tag
-    | undefined // self closed
-    | null; // EOF before open tag end
-  // original close tag, </DIV >
-  close:
-    | IText // with close tag
-    | undefined // self closed
-    | null; // EOF before end or without close tag
+  /**
+   * Child nodes for paired tags, undefined for self-closed tags, or null when the opening tag is incomplete.
+   */
+  body: Array<ITag | IText> | undefined | null;
+  /**
+   * Original closing tag text, undefined for self-closed tags, or null when missing.
+   */
+  close: IText | undefined | null;
 }
 
+/**
+ * Any node returned by parse.
+ */
 export type INode = IText | ITag;

src/utils.ts

@@ -3,6 +3,9 @@
  * @since 2017-08-20 21:41:39
  */
 
+/**
+ * Build cumulative line ending offsets for source position lookup.
+ */
 export function getLineRanges(input: string) {
   return input.split('\n').reduce(
     (arr, line) => {
@@ -13,6 +16,9 @@ export function getLineRanges(input: string) {
   );
 }
 
+/**
+ * Convert a source offset to one-based line and column coordinates.
+ */
 export function getPosition(ranges: number[], offset: number): [number, number] {
   let line = NaN;
   let column = NaN;