schema-markdown 1.2.0 → 1.2.1

package/README.md

@@ -3,91 +3,105 @@
 [![npm](https://img.shields.io/npm/v/schema-markdown)](https://www.npmjs.com/package/schema-markdown)
 [![GitHub](https://img.shields.io/github/license/craigahobbs/schema-markdown-js)](https://github.com/craigahobbs/schema-markdown-js/blob/main/LICENSE)
 
-**Schema Markdown** is a human-friendly schema definition language and schema validator. Here are
-its features at a glance:
-
-- Schema-validate JSON objects
-- Human-friendly schema definition
-- Validates member value and length contraints
-- Validation *type-massages* string member values
-- Pure JavaScript
+**schema-markdown** is a schema definition and validation library.
 
 
 ## Links
 
-- [Schema Markdown Language Reference](https://craigahobbs.github.io/schema-markdown/schema-markdown.html)
-- [Documentation on GitHub Pages](https://craigahobbs.github.io/schema-markdown-js/)
-- [Package on npm](https://www.npmjs.com/package/schema-markdown)
-- [Source code on GitHub](https://github.com/craigahobbs/schema-markdown-js)
+- [The Schema Markdown Language](https://craigahobbs.github.io/schema-markdown-js/language/)
+- [API Documentation](https://craigahobbs.github.io/schema-markdown-js/)
+- [Source code](https://github.com/craigahobbs/schema-markdown-js)
 
 
-## Usage
+## Define a Schema
 
-To schema-validate an object, first parse its *Schema Markdown* using the
-[parseSchemaMarkdown](https://craigahobbs.github.io/schema-markdown-js/module-lib_parser.parseSchemaMarkdown.html)
-function:
+Schemas are defined using the
+[Schema Markdown](https://craigahobbs.github.io/schema-markdown-js/language/)
+language which is parsed by the
+[parseSchemaMarkdown](https://craigahobbs.github.io/schema-markdown-js/module-lib_parser.html#.parseSchemaMarkdown)
+function. For example:
 
 ``` javascript
 import {parseSchemaMarkdown} from 'schema-markdown/parser.js';
-import {validateType} from 'schema-markdown/schema.js';
-
-const types = parseSchemaMarkdown(`\
-# An aggregation function
-enum Aggregation
-    Average
-    Sum
 
+export const modelTypes = parseSchemaMarkdown(`\
 # An aggregate numerical operation
-struct Operation
+struct Aggregation
+
     # The aggregation function - default is "Sum"
-    optional Aggregation aggregation
+    optional AggregationFunction aggregation
 
-    # The numbers to operate on
+    # The numbers to aggregate on
     int[len > 0] numbers
+
+# An aggregation function
+enum AggregationFunction
+    Average
+    Sum
 `);
 ```
 
-Then, validate an object using the
+
+## Validate using a Schema
+
+To validate an object using the schema, use the
 [validateType](https://craigahobbs.github.io/schema-markdown-js/module-lib_schema.html#.validateType)
-function:
+function. For example:
 
 ``` javascript
-const obj = validateType(types, 'Operation', {
-    'numbers': [1, 2, '3', 4]
-});
+import {validateType} from 'schema-markdown/schema.js';
+
+const obj = validateType(modelTypes, 'Aggregation', {'numbers': [1, 2, '3', 4]});
 console.assert(obj.numbers[2] === 3);
 ```
 
 Notice that the numerical input '3' above is *type-massaged* to the integer 3 by validation.
+
 Validation fails if the object does not match the schema:
 
 ``` javascript
 try {
-    validateType(types, 'Operation', {
-        'numbers': [1, 2, 'asdf', 4]
-    });
+    validateType(modelTypes, 'Aggregation', {'numbers': [1, 2, 'asdf', 4]});
 } catch ({message}) {
     console.assert(message === "Invalid value \"asdf\" (type 'string') for member 'numbers.2', expected type 'int'", message);
 }
 ```
 
-Validation also fails if a member contraint is violated:
+Validation also fails if a member constraint is violated:
 
 ``` javascript
 try {
-    validateType(types, 'Operation', {
-        'numbers': []
-    });
+    validateType(modelTypes, 'Aggregation', {'numbers': []});
 } catch ({message}) {
     console.assert(message === "Invalid value [] (type 'object') for member 'numbers', expected type 'array' [len > 0]", message);
 }
 ```
 
 
+## Document a Schema
+
+To document the schema, download the
+[documentation application](https://github.com/craigahobbs/schema-markdown-doc#the-schema-markdown-documentation-viewer)
+stub and save the type model as JSON:
+
+~~~
+curl -O https://craigahobbs.github.io/schema-markdown-doc/extra/index.html
+node --input-type=module \
+    -e 'import {modelTypes} from "model.js"; console.log(JSON.stringify(modelTypes))' \
+    > model.json
+~~~
+
+To host locally, start a local static web server:
+
+```
+python3 -m http.server
+```
+
+
 ## Development
 
-schema-markdown is developed using [javascript-build](https://github.com/craigahobbs/javascript-build#readme)
-and it was started using [javascript-template](https://github.com/craigahobbs/javascript-template#readme):
+This package is developed using [javascript-build](https://github.com/craigahobbs/javascript-build#readme).
+It was started using [javascript-template](https://github.com/craigahobbs/javascript-template#readme) as follows:
 
 ```
 template-specialize javascript-template/template/ schema-markdown-js/ -k package schema-markdown -k name 'Craig A. Hobbs' -k email 'craigahobbs@gmail.com' -k github 'craigahobbs' -k noapp 1

package/lib/parser.js

@@ -6,56 +6,52 @@
 import {validateTypeModelErrors} from './schemaUtil.js';
 
 
-/* eslint-disable prefer-template */
-
-
 // Built-in types
-const BUILTIN_TYPES = new Set(['bool', 'date', 'datetime', 'float', 'int', 'object', 'string', 'uuid']);
+const builtinTypes = new Set(['bool', 'date', 'datetime', 'float', 'int', 'object', 'string', 'uuid']);
 
 
 // Schema Markdown regex
-const RE_PART_ID = '(?:[A-Za-z]\\w*)';
-const RE_PART_ATTR_GROUP =
+const rPartId = '(?:[A-Za-z]\\w*)';
+const rPartAttrGroup =
       '(?:(?<nullable>nullable)' +
       '|(?<op><=|<|>|>=|==)\\s*(?<opnum>-?\\d+(?:\\.\\d+)?)' +
       '|(?<ltype>len)\\s*(?<lop><=|<|>|>=|==)\\s*(?<lopnum>\\d+))';
-const RE_PART_ATTR = RE_PART_ATTR_GROUP.replace(/\(\?<[^>]+>/g, '(?:');
-const RE_PART_ATTRS = '(?:' + RE_PART_ATTR + '(?:\\s*,\\s*' + RE_PART_ATTR + ')*)';
-const RE_ATTR_GROUP = new RegExp(RE_PART_ATTR_GROUP);
-const RE_FIND_ATTRS = new RegExp(RE_PART_ATTR + '(?:\\s*,\\s*|\\s*$)', 'g');
-const RE_LINE_CONT = /\\\s*$/;
-const RE_COMMENT = /^\s*(?:#-.*|#(?<doc>.*))?$/;
-const RE_GROUP = /^group(?:\s+"(?<group>.+?)")?\s*$/;
-const RE_ACTION = new RegExp('^action\\s+(?<id>' + RE_PART_ID + ')');
-const RE_PART_BASE_IDS = '(?:\\s*\\(\\s*(?<base_ids>' + RE_PART_ID + '(?:\\s*,\\s*' + RE_PART_ID + ')*)\\s*\\)\\s*)';
-const RE_BASE_IDS_SPLIT = /\s*,\s*/;
-const RE_DEFINITION = new RegExp('^(?<type>struct|union|enum)\\s+(?<id>' + RE_PART_ID + ')' + RE_PART_BASE_IDS + '?\\s*$');
-const RE_SECTION = new RegExp('^\\s+(?<type>path|query|input|output|errors)' + RE_PART_BASE_IDS + '?\\s*$');
-const RE_SECTION_PLAIN = /^\s+(?<type>urls)\s*$/;
-const RE_PART_TYPEDEF =
-      '(?<type>' + RE_PART_ID + ')' +
-      '(?:\\s*\\(\\s*(?<attrs>' + RE_PART_ATTRS + ')\\s*\\))?' +
+const rPartAttr = rPartAttrGroup.replace(/\(\?<[^>]+>/g, '(?:');
+const rPartAttrs = `(?:${rPartAttr}(?:\\s*,\\s*${rPartAttr})*)`;
+const rAttrGroup = new RegExp(rPartAttrGroup);
+const rFindAttrs = new RegExp(`${rPartAttr}(?:\\s*,\\s*|\\s*$)`, 'g');
+const rLineCont = /\\\s*$/;
+const rComment = /^\s*(?:#-.*|#(?<doc>.*))?$/;
+const rGroup = /^group(?:\s+"(?<group>.+?)")?\s*$/;
+const rAction = new RegExp(`^action\\s+(?<id>${rPartId})`);
+const rPartBaseIds = `(?:\\s*\\(\\s*(?<baseIds>${rPartId}(?:\\s*,\\s*${rPartId})*)\\s*\\)\\s*)`;
+const rBaseIdsSplit = /\s*,\s*/;
+const rDefinition = new RegExp(`^(?<type>struct|union|enum)\\s+(?<id>${rPartId})${rPartBaseIds}?\\s*$`);
+const rSection = new RegExp(`^\\s+(?<type>path|query|input|output|errors)${rPartBaseIds}?\\s*$`);
+const rSectionPlain = /^\s+(?<type>urls)\s*$/;
+const rPartTypedef =
+      `(?<type>${rPartId})` +
+      `(?:\\s*\\(\\s*(?<attrs>${rPartAttrs})\\s*\\))?` +
       '(?:' +
-      '(?:\\s*\\[\\s*(?<array>' + RE_PART_ATTRS + '?)\\s*\\])?' +
+      `(?:\\s*\\[\\s*(?<array>${rPartAttrs}?)\\s*\\])?` +
       '|' +
       '(?:' +
-      '\\s*:\\s*(?<dictValueType>' + RE_PART_ID + ')' +
-      '(?:\\s*\\(\\s*(?<dictValueAttrs>' + RE_PART_ATTRS + ')\\s*\\))?' +
+      `\\s*:\\s*(?<dictValueType>${rPartId})` +
+      `(?:\\s*\\(\\s*(?<dictValueAttrs>${rPartAttrs})\\s*\\))?` +
       ')?' +
-      '(?:\\s*\\{\\s*(?<dict>' + RE_PART_ATTRS + '?)\\s*\\})?' +
+      `(?:\\s*\\{\\s*(?<dict>${rPartAttrs}?)\\s*\\})?` +
       ')' +
-      '\\s+(?<id>' + RE_PART_ID + ')';
-const RE_TYPEDEF = new RegExp('^typedef\\s+' + RE_PART_TYPEDEF + '\\s*$');
-const RE_MEMBER = new RegExp('^\\s+(?<optional>optional\\s+)?' + RE_PART_TYPEDEF + '\\s*$');
-const RE_VALUE = new RegExp('^\\s+(?<id>' + RE_PART_ID + ')\\s*$');
-const RE_VALUE_QUOTED = /^\s+"(?<id>.*?)"\s*$/;
-const RE_URL = /^\s+(?<method>[A-Za-z]+|\*)(?:\s+(?<path>\/[^\s]*))?/;
-const RE_LINE_SPLIT = /\r?\n/;
+      `\\s+(?<id>${rPartId})`;
+const rTypedef = new RegExp(`^typedef\\s+${rPartTypedef}\\s*$`);
+const rMember = new RegExp(`^\\s+(?<optional>optional\\s+)?${rPartTypedef}\\s*$`);
+const rValue = new RegExp(`^\\s+(?<id>${rPartId})\\s*$`);
+const rValueQuoted = /^\s+"(?<id>.*?)"\s*$/;
+const rURL = /^\s+(?<method>[A-Za-z]+|\*)(?:\s+(?<path>\/[^\s]*))?/;
+const rLineSplit = /\r?\n/;
 
 
 /**
- * Parse Schema Markdown from an iterator of line strings (e.g an input stream). This method can
- * be called repeatedly.
+ * Parse Schema Markdown from a string or and iterator of strings
  *
  * @param {string|string[]} text - The Schema Markdown text
  * @param {Object} [options.types=''] - The [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
@@ -94,340 +90,338 @@ export function parseSchemaMarkdown(text, {types = {}, filename = '', validate =
     // Line-split all script text
     const lines = [];
     if (typeof text === 'string') {
-        lines.push(...text.split(RE_LINE_SPLIT));
+        lines.push(...text.split(rLineSplit));
     } else {
         for (const textPart of text) {
-            lines.push(...textPart.split(RE_LINE_SPLIT));
+            lines.push(...textPart.split(rLineSplit));
         }
     }
+    lines.push('');
 
     // Process each line
     const lineContinuation = [];
-    const lineGroups = [lines, ['']];
-    for (const lineGroup of lineGroups) {
-        for (const linePart of lineGroup) {
-            linenum += 1;
-
-            // Line continuation?
-            const linePartNoContinuation = linePart.replace(RE_LINE_CONT, '');
-            if (lineContinuation.length || linePartNoContinuation !== linePart) {
-                lineContinuation.push(linePartNoContinuation);
-            }
-            if (linePartNoContinuation !== linePart) {
-                continue;
-            }
-            let line;
-            if (lineContinuation.length) {
-                line = lineContinuation.join('');
-                lineContinuation.length = 0;
-            } else {
-                line = linePart;
-            }
+    for (const linePart of lines) {
+        linenum += 1;
+
+        // Line continuation?
+        const linePartNoContinuation = linePart.replace(rLineCont, '');
+        if (lineContinuation.length || linePartNoContinuation !== linePart) {
+            lineContinuation.push(linePartNoContinuation);
+        }
+        if (linePartNoContinuation !== linePart) {
+            continue;
+        }
+        let line;
+        if (lineContinuation.length) {
+            line = lineContinuation.join('');
+            lineContinuation.length = 0;
+        } else {
+            line = linePart;
+        }
 
-            // Match syntax
-            let matchName = 'comment';
-            let match = line.match(RE_COMMENT);
+        // Match syntax
+        let matchName = 'comment';
+        let match = line.match(rComment);
+        if (match === null) {
+            matchName = 'group';
+            match = line.match(rGroup);
+        }
+        if (match === null) {
+            matchName = 'action';
+            match = line.match(rAction);
+        }
+        if (match === null) {
+            matchName = 'definition';
+            match = line.match(rDefinition);
+        }
+        if (match === null && action !== null) {
+            matchName = 'section';
+            match = line.match(rSection);
+        }
+        if (match === null && action !== null) {
+            matchName = 'sectionPlain';
+            match = line.match(rSectionPlain);
+        }
+        if (match === null && userType !== null && 'enum' in userType) {
+            matchName = 'value';
+            match = line.match(rValue);
             if (match === null) {
-                matchName = 'group';
-                match = line.match(RE_GROUP);
+                match = line.match(rValueQuoted);
             }
-            if (match === null) {
-                matchName = 'action';
-                match = line.match(RE_ACTION);
+        }
+        if (match === null && userType !== null && 'struct' in userType) {
+            matchName = 'member';
+            match = line.match(rMember);
+        }
+        if (match === null && urls !== null) {
+            matchName = 'urls';
+            match = line.match(rURL);
+        }
+        if (match === null) {
+            matchName = 'typedef';
+            match = line.match(rTypedef);
+        }
+        if (match === null) {
+            matchName = null;
+        }
+
+        // Comment?
+        if (matchName === 'comment') {
+            const docString = match.groups.doc;
+            if (typeof docString !== 'undefined') {
+                doc.push(!docString.startsWith(' ') ? docString : docString.slice(1));
             }
-            if (match === null) {
-                matchName = 'definition';
-                match = line.match(RE_DEFINITION);
-            }
-            if (match === null && action !== null) {
-                matchName = 'section';
-                match = line.match(RE_SECTION);
-            }
-            if (match === null && action !== null) {
-                matchName = 'section_plain';
-                match = line.match(RE_SECTION_PLAIN);
-            }
-            if (match === null && userType !== null && 'enum' in userType) {
-                matchName = 'value';
-                match = line.match(RE_VALUE);
-                if (match === null) {
-                    match = line.match(RE_VALUE_QUOTED);
-                }
+
+        // Documentation group?
+        } else if (matchName === 'group') {
+            docGroup = match.groups.group;
+            if (typeof docGroup !== 'undefined') {
+                docGroup = docGroup.trim();
+            } else {
+                docGroup = null;
             }
-            if (match === null && userType !== null && 'struct' in userType) {
-                matchName = 'member';
-                match = line.match(RE_MEMBER);
+
+        // Action?
+        } else if (matchName === 'action') {
+            const actionId = match.groups.id;
+
+            // Action already defined?
+            if (actionId in types) {
+                addError(`Redefinition of action '${actionId}'`, filename, linenum);
             }
-            if (match === null && urls !== null) {
-                matchName = 'urls';
-                match = line.match(RE_URL);
+
+            // Clear parser state
+            urls = null;
+            userType = null;
+            const actionDoc = getDoc();
+
+            // Create the new action
+            action = {'name': actionId};
+            types[actionId] = {'action': action};
+            if (actionDoc !== null) {
+                action.doc = actionDoc;
             }
-            if (match === null) {
-                matchName = 'typedef';
-                match = line.match(RE_TYPEDEF);
+            if (docGroup !== null) {
+                action.docGroup = docGroup;
             }
-            if (match === null) {
-                matchName = null;
+
+        // Definition?
+        } else if (matchName === 'definition') {
+            const definitionString = match.groups.type;
+            const definitionId = match.groups.id;
+            const definitionBaseIds = match.groups.baseIds;
+
+            // Type already defined?
+            if (builtinTypes.has(definitionId) || definitionId in types) {
+                addError(`Redefinition of type '${definitionId}'`, filename, linenum);
             }
 
-            // Comment?
-            if (matchName === 'comment') {
-                const docString = match.groups.doc;
-                if (typeof docString !== 'undefined') {
-                    doc.push(!docString.startsWith(' ') ? docString : docString.slice(1));
+            // Clear parser state
+            action = null;
+            urls = null;
+            const definitionDoc = getDoc();
+
+            // Struct definition
+            if (definitionString === 'struct' || definitionString === 'union') {
+                // Create the new struct type
+                const struct = {'name': definitionId};
+                userType = {'struct': struct};
+                types[definitionId] = userType;
+                if (definitionDoc !== null) {
+                    struct.doc = definitionDoc;
                 }
-
-            // Documentation group?
-            } else if (matchName === 'group') {
-                docGroup = match.groups.group;
-                if (typeof docGroup !== 'undefined') {
-                    docGroup = docGroup.trim();
-                } else {
-                    docGroup = null;
+                if (docGroup !== null) {
+                    struct.docGroup = docGroup;
                 }
-
-            // Action?
-            } else if (matchName === 'action') {
-                const actionId = match.groups.id;
-
-                // Action already defined?
-                if (actionId in types) {
-                    addError(`Redefinition of action '${actionId}'`, filename, linenum);
+                if (definitionString === 'union') {
+                    struct.union = true;
+                }
+                if (typeof definitionBaseIds !== 'undefined') {
+                    struct.bases = definitionBaseIds.split(rBaseIdsSplit);
                 }
 
-                // Clear parser state
-                urls = null;
-                userType = null;
-                const actionDoc = getDoc();
-
-                // Create the new action
-                action = {'name': actionId};
-                types[actionId] = {'action': action};
-                if (actionDoc !== null) {
-                    action.doc = actionDoc;
+            // Enum definition
+            } else {
+                // definitionString == 'enum':
+                // Create the new enum type
+                const enum_ = {'name': definitionId};
+                userType = {'enum': enum_};
+                types[definitionId] = userType;
+                if (definitionDoc !== null) {
+                    enum_.doc = definitionDoc;
                 }
                 if (docGroup !== null) {
-                    action.docGroup = docGroup;
+                    enum_.docGroup = docGroup;
                 }
-
-            // Definition?
-            } else if (matchName === 'definition') {
-                const definitionString = match.groups.type;
-                const definitionId = match.groups.id;
-                const definitionBaseIds = match.groups.base_ids;
-
-                // Type already defined?
-                if (BUILTIN_TYPES.has(definitionId) || definitionId in types) {
-                    addError(`Redefinition of type '${definitionId}'`, filename, linenum);
+                if (typeof definitionBaseIds !== 'undefined') {
+                    enum_.bases = definitionBaseIds.split(rBaseIdsSplit);
                 }
+            }
 
-                // Clear parser state
-                action = null;
-                urls = null;
-                const definitionDoc = getDoc();
-
-                // Struct definition
-                if (definitionString === 'struct' || definitionString === 'union') {
-                    // Create the new struct type
-                    const struct = {'name': definitionId};
-                    userType = {'struct': struct};
-                    types[definitionId] = userType;
-                    if (definitionDoc !== null) {
-                        struct.doc = definitionDoc;
-                    }
-                    if (docGroup !== null) {
-                        struct.docGroup = docGroup;
-                    }
-                    if (definitionString === 'union') {
-                        struct.union = true;
-                    }
-                    if (typeof definitionBaseIds !== 'undefined') {
-                        struct.bases = definitionBaseIds.split(RE_BASE_IDS_SPLIT);
-                    }
-
-                // Enum definition
-                } else {
-                    // definition_string == 'enum':
-                    // Create the new enum type
-                    const enum_ = {'name': definitionId};
-                    userType = {'enum': enum_};
-                    types[definitionId] = userType;
-                    if (definitionDoc !== null) {
-                        enum_.doc = definitionDoc;
-                    }
-                    if (docGroup !== null) {
-                        enum_.docGroup = docGroup;
-                    }
-                    if (typeof definitionBaseIds !== 'undefined') {
-                        enum_.bases = definitionBaseIds.split(RE_BASE_IDS_SPLIT);
-                    }
-                }
+            // Record the definition's line number
+            filepos[definitionId] = linenum;
 
-                // Record the definition's line number
-                filepos[definitionId] = linenum;
+        // Action section?
+        } else if (matchName === 'section') {
+            const sectionString = match.groups.type;
+            const sectionBaseIds = match.groups.baseIds;
 
-            // Action section?
-            } else if (matchName === 'section') {
-                const sectionString = match.groups.type;
-                const sectionBaseIds = match.groups.base_ids;
+            // Action section redefinition?
+            if (sectionString in action) {
+                addError(`Redefinition of action ${sectionString}`, filename, linenum);
+            }
 
-                // Action section redefinition?
-                if (sectionString in action) {
-                    addError(`Redefinition of action ${sectionString}`, filename, linenum);
+            // Clear parser state
+            urls = null;
+
+            // Set the action section type
+            const sectionTypeName = `${action.name}_${sectionString}`;
+            action[sectionString] = sectionTypeName;
+            if (sectionString === 'errors') {
+                const enum_ = {'name': sectionTypeName};
+                userType = {'enum': enum_};
+                types[sectionTypeName] = userType;
+                if (typeof sectionBaseIds !== 'undefined') {
+                    enum_.bases = sectionBaseIds.split(rBaseIdsSplit);
                 }
-
-                // Clear parser state
-                urls = null;
-
-                // Set the action section type
-                const sectionTypeName = `${action.name}_${sectionString}`;
-                action[sectionString] = sectionTypeName;
-                if (sectionString === 'errors') {
-                    const enum_ = {'name': sectionTypeName};
-                    userType = {'enum': enum_};
-                    types[sectionTypeName] = userType;
-                    if (typeof sectionBaseIds !== 'undefined') {
-                        enum_.bases = sectionBaseIds.split(RE_BASE_IDS_SPLIT);
-                    }
-                } else {
-                    const struct = {'name': sectionTypeName};
-                    userType = {'struct': struct};
-                    types[sectionTypeName] = userType;
-                    if (typeof sectionBaseIds !== 'undefined') {
-                        struct.bases = sectionBaseIds.split(RE_BASE_IDS_SPLIT);
-                    }
+            } else {
+                const struct = {'name': sectionTypeName};
+                userType = {'struct': struct};
+                types[sectionTypeName] = userType;
+                if (typeof sectionBaseIds !== 'undefined') {
+                    struct.bases = sectionBaseIds.split(rBaseIdsSplit);
                 }
+            }
 
-                // Record the definition's line number
-                filepos[sectionTypeName] = linenum;
+            // Record the definition's line number
+            filepos[sectionTypeName] = linenum;
 
-            // Plain action section?
-            } else if (matchName === 'section_plain') {
-                const sectionString = match.groups.type;
+        // Plain action section?
+        } else if (matchName === 'sectionPlain') {
+            const sectionString = match.groups.type;
 
-                // Action section redefinition?
-                if (sectionString in action) {
-                    addError(`Redefinition of action ${sectionString}`, filename, linenum);
-                }
+            // Action section redefinition?
+            if (sectionString in action) {
+                addError(`Redefinition of action ${sectionString}`, filename, linenum);
+            }
 
-                // Clear parser state
-                userType = null;
+            // Clear parser state
+            userType = null;
 
-                // Update the parser state
-                urls = [];
+            // Update the parser state
+            urls = [];
 
-            // Enum value?
-            } else if (matchName === 'value') {
-                const valueString = match.groups.id;
+        // Enum value?
+        } else if (matchName === 'value') {
+            const valueString = match.groups.id;
 
-                // Add the enum value
-                const enum_ = userType.enum;
-                if (!('values' in enum_)) {
-                    enum_.values = [];
-                }
-                const enumValue = {'name': valueString};
-                enum_.values.push(enumValue);
-                const enumValueDoc = getDoc();
-                if (enumValueDoc !== null) {
-                    enumValue.doc = enumValueDoc;
-                }
+            // Add the enum value
+            const enum_ = userType.enum;
+            if (!('values' in enum_)) {
+                enum_.values = [];
+            }
+            const enumValue = {'name': valueString};
+            enum_.values.push(enumValue);
+            const enumValueDoc = getDoc();
+            if (enumValueDoc !== null) {
+                enumValue.doc = enumValueDoc;
+            }
 
-                // Record the definition's line number
-                filepos[`${enum_.name}.${valueString}`] = linenum;
+            // Record the definition's line number
+            filepos[`${enum_.name}.${valueString}`] = linenum;
 
-            // Struct member?
-            } else if (matchName === 'member') {
-                const optional = typeof match.groups.optional !== 'undefined';
-                const memberName = match.groups.id;
+        // Struct member?
+        } else if (matchName === 'member') {
+            const optional = typeof match.groups.optional !== 'undefined';
+            const memberName = match.groups.id;
 
-                // Add the member
-                const {struct} = userType;
-                if (!('members' in struct)) {
-                    struct.members = [];
-                }
-                const [memberType, memberAttr] = parseTypedef(match);
-                const memberDoc = getDoc();
-                const member = {
-                    'name': memberName,
-                    'type': memberType
-                };
-                struct.members.push(member);
-                if (memberAttr !== null) {
-                    member.attr = memberAttr;
-                }
-                if (memberDoc !== null) {
-                    member.doc = memberDoc;
-                }
-                if (optional) {
-                    member.optional = true;
-                }
+            // Add the member
+            const {struct} = userType;
+            if (!('members' in struct)) {
+                struct.members = [];
+            }
+            const [memberType, memberAttr] = parseTypedef(match);
+            const memberDoc = getDoc();
+            const member = {
+                'name': memberName,
+                'type': memberType
+            };
+            struct.members.push(member);
+            if (memberAttr !== null) {
+                member.attr = memberAttr;
+            }
+            if (memberDoc !== null) {
+                member.doc = memberDoc;
+            }
+            if (optional) {
+                member.optional = true;
+            }
 
-                // Record the definition's line number
-                filepos[`${struct.name}.${memberName}`] = linenum;
+            // Record the definition's line number
+            filepos[`${struct.name}.${memberName}`] = linenum;
 
-            // URL?
-            } else if (matchName === 'urls') {
-                const {method, path} = match.groups;
+        // URL?
+        } else if (matchName === 'urls') {
+            const {method, path} = match.groups;
 
-                // Create the action URL object
-                const actionUrl = {};
-                if (method !== '*') {
-                    actionUrl.method = method;
-                }
-                if (typeof path !== 'undefined') {
-                    actionUrl.path = path;
-                }
+            // Create the action URL object
+            const actionUrl = {};
+            if (method !== '*') {
+                actionUrl.method = method;
+            }
+            if (typeof path !== 'undefined') {
+                actionUrl.path = path;
+            }
 
-                // Duplicate URL?
-                if (urls.some((url) => url.method === actionUrl.method && url.path === actionUrl.path)) {
-                    addError(`Duplicate URL: ${method} ${'path' in actionUrl ? actionUrl.path : ''}`, filename, linenum);
-                }
+            // Duplicate URL?
+            if (urls.some((url) => url.method === actionUrl.method && url.path === actionUrl.path)) {
+                addError(`Duplicate URL: ${method} ${'path' in actionUrl ? actionUrl.path : ''}`, filename, linenum);
+            }
 
-                // Add the URL
-                if (!('urls' in action)) {
-                    action.urls = urls;
-                }
-                urls.push(actionUrl);
+            // Add the URL
+            if (!('urls' in action)) {
+                action.urls = urls;
+            }
+            urls.push(actionUrl);
 
-            // Typedef?
-            } else if (matchName === 'typedef') {
-                const definitionId = match.groups.id;
+        // Typedef?
+        } else if (matchName === 'typedef') {
+            const definitionId = match.groups.id;
 
-                // Type already defined?
-                if (BUILTIN_TYPES.has(definitionId) || definitionId in types) {
-                    addError(`Redefinition of type '${definitionId}'`, filename, linenum);
-                }
+            // Type already defined?
+            if (builtinTypes.has(definitionId) || definitionId in types) {
+                addError(`Redefinition of type '${definitionId}'`, filename, linenum);
+            }
 
-                // Clear parser state
-                action = null;
-                urls = null;
-                userType = null;
-                const typedefDoc = getDoc();
-
-                // Create the typedef
-                const [typedefType, typedefAttr] = parseTypedef(match);
-                const typedef = {
-                    'name': definitionId,
-                    'type': typedefType
-                };
-                types[definitionId] = {'typedef': typedef};
-                if (typedefAttr !== null) {
-                    typedef.attr = typedefAttr;
-                }
-                if (typedefDoc !== null) {
-                    typedef.doc = typedefDoc;
-                }
-                if (docGroup !== null) {
-                    typedef.docGroup = docGroup;
-                }
+            // Clear parser state
+            action = null;
+            urls = null;
+            userType = null;
+            const typedefDoc = getDoc();
+
+            // Create the typedef
+            const [typedefType, typedefAttr] = parseTypedef(match);
+            const typedef = {
+                'name': definitionId,
+                'type': typedefType
+            };
+            types[definitionId] = {'typedef': typedef};
+            if (typedefAttr !== null) {
+                typedef.attr = typedefAttr;
+            }
+            if (typedefDoc !== null) {
+                typedef.doc = typedefDoc;
+            }
+            if (docGroup !== null) {
+                typedef.docGroup = docGroup;
+            }
 
-                // Record the definition's line number
-                filepos[definitionId] = linenum;
+            // Record the definition's line number
+            filepos[definitionId] = linenum;
 
-            // Unrecognized line syntax
-            } else {
-                addError('Syntax error', filename, linenum);
-            }
+        // Unrecognized line syntax
+        } else {
+            addError('Syntax error', filename, linenum);
         }
     }
 
@@ -439,7 +433,9 @@ export function parseSchemaMarkdown(text, {types = {}, filename = '', validate =
             if (memberName !== null) {
                 errorLinenum = filepos[`${typeName}.${memberName}`] ?? null;
             }
-            errorLinenum ??= filepos[typeName] ?? null;
+            if (errorLinenum === null) {
+                errorLinenum = filepos[typeName] ?? null;
+            }
             if (errorLinenum === null) {
                 errorFilename = '';
                 errorLinenum = 1;
@@ -516,7 +512,7 @@ function parseTypedef(matchTypedef) {
 
 // Helper function to create a type model
 function createType(typeName) {
-    if (BUILTIN_TYPES.has(typeName)) {
+    if (builtinTypes.has(typeName)) {
         return {'builtin': typeName};
     }
     return {'user': typeName};
@@ -527,11 +523,11 @@ function createType(typeName) {
 function parseAttr(attrsString) {
     let attrs = null;
     if (typeof attrsString !== 'undefined') {
-        for (const [attrString] of attrsString.matchAll(RE_FIND_ATTRS)) {
+        for (const [attrString] of attrsString.matchAll(rFindAttrs)) {
             if (attrs === null) {
                 attrs = {};
             }
-            const matchAttr = attrString.match(RE_ATTR_GROUP);
+            const matchAttr = attrString.match(rAttrGroup);
             const attrOp = matchAttr.groups.op;
             const attrLengthOp = matchAttr.groups.lop;
 

package/lib/schema.js

@@ -10,10 +10,10 @@ import {validateTypeModelErrors} from './schemaUtil.js';
 /**
  * Get a user type's referenced type model
  *
- * @param {Object} types - The map of user type name to user type model
+ * @param {Object} types - The [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
  * @param {string} typeName - The type name
  * @param {Object} [referencedTypes=null] - Optional map of referenced user type name to user type model
- * @returns {Object}
+ * @returns {Object} The referenced [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
  */
 export function getReferencedTypes(types, typeName, referencedTypes = {}) {
     return getReferencedTypesHelper(types, {'user': typeName}, referencedTypes);
@@ -104,7 +104,7 @@ export class ValidationError extends Error {
     /**
      * Schema Markdown type model validation error constructor
      *
-     * @param {string} [memberFqn=null] - Optional fully-qualified member name
+     * @param {string} [memberFqn=null] - The fully-qualified member name
      */
     constructor(message, memberFqn = null) {
         super(message);
@@ -117,10 +117,10 @@ export class ValidationError extends Error {
  * Type-validate a value using a user type model. Container values are duplicated since some member types are
  * transformed during validation.
  *
- * @param {Object} types - The map of user type name to user type model
+ * @param {Object} types - The [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
  * @param {string} typeName - The type name
  * @param {Object} value - The value object to validate
- * @param {string} [memberFqn=null] - Optional fully-qualified member name
+ * @param {?string} [memberFqn=null] - The fully-qualified member name
  * @returns {Object} The validated, transformed value object
  * @throws [ValidationError]{@link module:lib/schema.ValidationError}
  */
@@ -448,9 +448,10 @@ function validateAttr(type, attr, value, memberFqn) {
 /**
  * Get the struct's members (inherited members first)
  *
- * @param {Object} types - The map of user type name to user type model
- * @param {Object} struct - The struct model
- * @returns {Array<Object>} The array of struct member models
+ * @param {Object} types - The [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
+ * @param {Object} struct - The [struct model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Struct'}
+ * @returns {Array<Object>} The array of
+ *     [struct member models]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='StructMember'}
  */
 export function getStructMembers(types, struct) {
     // No base structs?
@@ -480,9 +481,10 @@ export function getStructMembers(types, struct) {
 /**
  * Get the enum's values (inherited values first)
  *
- * @param {Object} types - The map of user type name to user type model
- * @param {Object} enum_ - The enum model
- * @returns {Array<Object>} The array of enum value models
+ * @param {Object} types - The [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
+ * @param {Object} enum_ - The [enum model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Enum'}
+ * @returns {Array<Object>} The array of
+ *     [enum value models]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='EnumValue'}
  */
 export function getEnumValues(types, enum_) {
     // No base enums?
@@ -512,8 +514,8 @@ export function getEnumValues(types, enum_) {
 /**
  * Validate a type model's types object
  *
- * @param {Object} types - The map of user type name to user type model
- * @returns {Object} The validated, transformed types object
+ * @param {Object} types - The [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
+ * @returns {Object} The validated [type model]{@link https://craigahobbs.github.io/schema-markdown-doc/doc/#var.vName='Types'}
  * @throws [ValidationError]{@link module:lib/schema.ValidationError}
  */
 export function validateTypeModel(types) {

package/package.json

@@ -1,8 +1,8 @@
 {
     "type": "module",
     "name": "schema-markdown",
-    "version": "1.2.0",
-    "description": "Human-friendly schema definition language and schema validator",
+    "version": "1.2.1",
+    "description": "A schema definition and validation library",
     "keywords": [
         "schema",
         "definition",