yini-parser 1.0.1-beta → 1.1.0-beta

package/dist/core/objectBuilder.js

@@ -1,185 +1,148 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.constructFinalObject = void 0;
+exports.astToObject = void 0;
 const env_1 = require("../config/env");
 const print_1 = require("../utils/print");
 /**
- * Construct the final result of a JavaScript Object.
+ * Construct the final JavaScript Object.
+ * Transforms the AST to the plain JS object.
+ *
+ * - Keys are used exactly as-is.
+ * - Order of properties matches the AST traversal order.
+ *
+ * @note All `tag` fields MUST be ignored.
  */
-const constructFinalObject = (syntaxTreeC, errorHandler) => {
+const astToObject = (ast, errorHandler) => {
     (0, print_1.debugPrint)('-> constructFinalObject(..)');
-    const bulder = new Builder(syntaxTreeC, errorHandler);
-    if ((0, env_1.isDebug)()) {
-        console.log('Argument, syntaxTreeC:');
-        (0, print_1.printObject)(syntaxTreeC);
+    // return sectionChildrenToObject(ast.root)
+    const out = {};
+    for (const child of ast.root.children) {
+        define(out, child.sectionName, sectionToObject(child));
     }
-    const jsObject = bulder.doCheckAndBuild();
-    (0, print_1.debugPrint)('<- About to leave constructFinalObject(..)');
-    if ((0, env_1.isDebug)()) {
-        console.log('Returning, jsObject:');
-        (0, print_1.printObject)(syntaxTreeC);
-    }
-    return jsObject;
+    return out;
 };
-exports.constructFinalObject = constructFinalObject;
-class Builder {
-    constructor(syntaxTreeC, errorHandler) {
-        (0, print_1.debugPrint)('-> Builder: constructor(..)');
-        this.syntaxTreeC = syntaxTreeC;
-        this.errorHandler = errorHandler;
-    }
-    doCheckAndBuild() {
-        (0, print_1.debugPrint)('-> Builder: doCheckAndBuild(..)');
-        if (!this.syntaxTreeC) {
-            // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-            this.errorHandler.pushOrBail(null, 'Fatal-Error', 'SyntaxTreeC is undefined', 'This is most likely caused by an internal error somewhere. The process cannot recover fully from this, sorry.');
-        }
-        const fullSubTreeList = this.buildFullSubTrees(this.syntaxTreeC);
-        const jsObject = this.buildObjectFromList(fullSubTreeList);
-        return jsObject;
-    }
-    buildFullSubTrees(syntaxTreeC) {
-        (0, print_1.debugPrint)('-> Builder: buildFullSubTrees(..)');
-        (0, env_1.isDebug)() && console.log();
-        const fullSubTreeList = []; // List of FULL sub-trees.
-        // Current Working Full Sub-Tree (starting at level 1).
-        let workingFullSubTree = syntaxTreeC._syntaxTree[0]; // (!) Any tree MUST START at level 1.
-        (0, print_1.debugPrint)(`Setted new workingFullSubTree, from syntaxTreeC._syntaxTree[0]`);
-        const len = syntaxTreeC._syntaxTree.length;
-        for (let i = 1; i < len; i++) {
-            const currentChainC = syntaxTreeC._syntaxTree[i];
-            const level = currentChainC.originLevel;
-            const nestingIndex = level - 1; // For debugging purposes.
-            const chain = currentChainC.chain; // For debugging purposes.
-            (0, print_1.debugPrint)(`Got new chain from syntaxTreeC._syntaxTree[${i}] to be mounted onto parent...`);
-            (0, print_1.debugPrint)('* level: ' + level + ' (i=' + i + '), chain: ' + chain);
-            if (level === 1) {
-                (0, print_1.debugPrint)('HIT - Detected that currentChain starts with level 1');
-                fullSubTreeList.push(workingFullSubTree);
-                (0, print_1.debugPrint)('The workingFullSubTree is finished, pushed it to the list.');
-                workingFullSubTree = syntaxTreeC._syntaxTree[i]; // (!) The tree MUST START at level 1.
-                (0, print_1.debugPrint)(`Setted new workingFullSubTree, from syntaxTreeC._syntaxTree[${i}]`);
-            }
-            else {
-                (0, print_1.debugPrint)('About to mount currentChain onto workingFullSubTree at correct level...');
-                workingFullSubTree = this.mountChainOntoLevel(currentChainC, workingFullSubTree);
-            }
-            (0, print_1.debugPrint)();
-        }
-        fullSubTreeList.push(workingFullSubTree);
-        if ((0, env_1.isDebug)()) {
-            console.log();
-            console.log('--- fullSubTreeList: (list of FULL sub-trees.) -------');
-            (0, print_1.printObject)(fullSubTreeList);
-            console.log();
-        }
-        return fullSubTreeList;
+exports.astToObject = astToObject;
+/** Convert only the children of a section into an object keyed by sectionName. */
+// function sectionChildrenToObject(
+//     section: YiniSection,
+// ): Record<string, unknown> {
+//     const out: Record<string, unknown> = {}
+//     for (const child of section.children) {
+//         out[child.sectionName] = sectionToObject(child)
+//     }
+//     return out
+// }
+/** Convert a section (its members + nested sections) to a plain object. */
+// function sectionToObject(node: YiniSection): Record<string, unknown> {
+//     const obj: Record<string, unknown> = {}
+//     // Members → properties
+//     for (const [key, val] of node.members.entries()) {
+//         obj[key] = literalToJS(val)
+//     }
+//     // Nested sections → nested objects keyed by sectionName
+//     for (const child of node.children) {
+//         obj[child.sectionName] = sectionToObject(child)
+//     }
+//     return obj
+// }
+/**
+ * Convert a section (members + nested sections) to a plain
+ * object, preserving order.
+ */
+const sectionToObject = (node) => {
+    const obj = {};
+    // 1) Members (Map preserves insertion order).
+    for (const [key, val] of node.members) {
+        define(obj, key, literalToJS(val));
     }
-    mountChainOntoLevel(chainC, workingSubTree) {
-        (0, print_1.debugPrint)('-> Builder: mountChainOntoLevel(..)');
-        if ((0, env_1.isDebug)()) {
-            (0, print_1.printObject)(chainC);
-        }
-        if (chainC.originLevel > 1) {
-            // NOP
-        }
-        else {
-            // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-            this.errorHandler.pushOrBail(null, 'Fatal-Error', 'Internal-Error: Detected incorrect chain in mountChainOntoLevel(..), start section has level: ' +
-                chainC.originLevel, 'The (chain) must start with a section level higher than 1', '' + (0, print_1.printObject)(chainC));
-        }
-        if (workingSubTree.originLevel != 1) {
-            // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-            this.errorHandler.pushOrBail(null, 'Fatal-Error', 'Internal-Error: Detected incorrect full sub-tree in mountChainOntoLevel(..), start section has level: ' +
-                chainC.originLevel, 'A full sub-tree (chain) must start with a section at level 1', '' + (0, print_1.printObject)(chainC));
-        }
-        const chain = chainC.chain;
-        const targetLevel = chainC.originLevel;
-        if ((0, env_1.isDebug)()) {
-            (0, print_1.debugPrint)('Target level = ' + targetLevel);
-            (0, print_1.debugPrint)(`The chain to mount: (onto level: ${targetLevel})`);
-            (0, print_1.printObject)(chain);
-            (0, print_1.debugPrint)('--- workingFullSubTree: -------');
-            (0, print_1.debugPrint)('Before mounting onto workingSubTree.chain:');
-            (0, print_1.printObject)(workingSubTree.chain);
-        }
-        (0, print_1.debugPrint)('Mount currentChain onto workingFullSubTree.');
-        workingSubTree.chain = mountObjectAtLevel(workingSubTree.chain, chain, targetLevel, this.errorHandler);
-        if ((0, env_1.isDebug)()) {
-            (0, print_1.debugPrint)('After mounting onto workingSubTree.chain:');
-            (0, print_1.printObject)(workingSubTree.chain);
-            (0, print_1.debugPrint)('----------');
-        }
-        (0, print_1.debugPrint)('<- Builder: mountChainOntoLevel(..)');
-        return workingSubTree;
+    // 2) Nested sections (array order preserved).
+    for (const child of node.children) {
+        define(obj, child.sectionName, sectionToObject(child));
     }
-    // Contruct the final JS object from the list of full sub-trees.
-    buildObjectFromList(fullSubTreeList) {
-        (0, print_1.debugPrint)('-> Builder: buildObjectFromList(..)');
-        const jsObject = {};
-        for (const chainC of fullSubTreeList) {
-            if (chainC.originLevel === 1) {
+    return obj;
+};
+/**
+ * Convert a literal to plain JS, ignoring both `tag` and `type`.
+ * - Scalars: return primitive value
+ * - List:    return array (item order preserved)
+ * - Object:  return plain object; iterate keys in creation order
+ *
+ * @note All `tag` fields MUST be ignored.
+ */
+const literalToJS = (v) => {
+    const IS_LOCAL_DEBUG = false;
+    (0, print_1.debugPrint)('In literalToJS(..)');
+    // if (!v) {
+    //     // NOTE: Only in lenient-mode, if parsing a
+    //     // member (key = value), but the value is invalid
+    //     // key will get undefined
+    //     return undefined
+    // }
+    switch (v.type) {
+        case 'String':
+        case 'Number':
+        case 'Boolean':
+        case 'Null':
+            return v.value;
+        case 'Undefined':
+            return undefined;
+        case 'List': {
+            if (IS_LOCAL_DEBUG) {
+                (0, print_1.debugPrint)("case 'List':");
                 if ((0, env_1.isDebug)()) {
-                    console.log('About to assign chainC.chain:');
-                    console.log(chainC.chain);
+                    console.log('input:');
+                    (0, print_1.printObject)(v);
                 }
-                Object.assign(jsObject, chainC.chain);
+            }
+            const out = v.elems.map((elem) => {
+                const ret = literalToJS(elem);
+                if (IS_LOCAL_DEBUG) {
+                    if ((0, env_1.isDebug)()) {
+                        console.log(`elem:`);
+                        (0, print_1.printObject)(elem);
+                    }
+                }
+                return ret;
+            });
+            if (IS_LOCAL_DEBUG) {
                 if ((0, env_1.isDebug)()) {
-                    console.log('After, jsObject:');
-                    console.log(jsObject);
+                    console.log('Returning:');
+                    (0, print_1.printObject)(out);
                 }
             }
-            else {
-                // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-                this.errorHandler.pushOrBail(null, 'Fatal-Error', 'Internal-Error: Detected incorrect full sub-tree in buildObjectFromList(..), start section has level: ' +
-                    chainC.originLevel, 'A full sub-tree (chain) must start with a section at level 1', '' + (0, print_1.printObject)(chainC));
+            return out;
+        }
+        case 'Object': {
+            const out = {};
+            // for (const key of Object.keys(v.entries)) {
+            //     const entry = v.entries[key]
+            //     if (isScalar(entry)) {
+            //         // Scalar entries in object-literals: value
+            //         // out[key] = { type: entry.type, value: entry.value }
+            //         out[key] = entry.value
+            //     } else if (entry.type === 'List') {
+            //         out[key] = entry.elems.map(literalToJS)
+            //     } else {
+            //         out[key] = literalToJS(entry) // nested object-literal
+            //     }
+            // }
+            // Object.keys preserves property insertion order for plain objects
+            for (const k of Object.keys(v.entries)) {
+                define(out, k, literalToJS(v.entries[k]));
             }
+            return out;
         }
-        return jsObject;
     }
-}
+};
 /**
- * Mounts objectDest onto the first object at the given depth (level is
- * 1-based) in objectSrc.
- * @return Returns a new object without mutating input objects.
+ * Helper function, defines a property to preserve explicit insertion
+ * order and enumerability.
  */
-const mountObjectAtLevel = (objectSrc, objectDest, level, errorHandler) => {
-    // Deep copy to avoid mutating the input.
-    const result = JSON.parse(JSON.stringify(objectSrc));
-    let current = result;
-    let currentLevel = 1;
-    // Traverse down the first object path until the desired level.
-    while (currentLevel < level) {
-        // Get all keys in current object.
-        const keys = Object.keys(current);
-        // Find first key where value is a plain object (not array).
-        const nextKey = keys.find((key) => current[key] &&
-            typeof current[key] === 'object' &&
-            !Array.isArray(current[key]));
-        if (!nextKey) {
-            // Could not reach the specified depth.
-            return result;
-        }
-        current = current[nextKey];
-        currentLevel++;
-    }
-    (0, print_1.debugPrint)('--------');
-    (0, print_1.debugPrint)('   current = ' + (0, print_1.toPrettyJSON)(current));
-    const [firstKey] = Object.keys(objectDest);
-    (0, print_1.debugPrint)('objectDest = ' + firstKey);
-    if (Object.prototype.hasOwnProperty.call(current, firstKey)) {
-        //@todo Add metadata with line number, onto chainC, so can use line number in error reporting
-        (0, print_1.debugPrint)(`(!) sectionName already exist, name: "${firstKey}", in: `);
-        (0, print_1.debugPrint)((0, print_1.toPrettyJSON)(current));
-        // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-        errorHandler.pushOrBail(null, 'Syntax-Error', 'Section name already exists', 'Cannot redefine section name: "' +
-            firstKey +
-            '" at level ' +
-            currentLevel +
-            '.');
-        return current;
-    }
-    // Mount objectDest onto the object at the required level.
-    Object.assign(current, objectDest);
-    return result;
+const define = (obj, key, value) => {
+    Object.defineProperty(obj, key, {
+        value,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+    });
 };

package/dist/core/types.d.ts

@@ -1,59 +1,249 @@
-export type TPersistThreshold = '0-Ignore-Errors' | '1-Abort-on-Errors' | '2-Abort-Even-on-Warnings';
-export type TIssueType = 'Fatal-Error' | 'Internal-Error' | 'Syntax-Error' | 'Syntax-Warning' | 'Notice' | 'Info';
+/**
+ * @note
+ *   The use of null vs undefined
+ *   ----------------------------
+ *   The convention here (in this file) is:
+ *   - undefined is used where a value is missing, or does not apply.
+ *   - null is used where a value is missing or has not yet been computed.
+ */
 export type TJSObject = any;
+export type TSourceType = 'File' | 'Inline';
+export type TSubjectType = 'None/Ignore' | TSourceType;
 export type TBailSensitivityLevel = 0 | 1 | 2;
-export interface IParseMainOptions {
+export type TPreferredFailLevel = 'auto' | 0 | 1 | 2;
+export type TPersistThreshold = '0-Ignore-Errors' | '1-Abort-on-Errors' | '2-Abort-Even-on-Warnings';
+/**
+ * Only for returned meta data to user.
+ * NOTE: Only use lower case snake_case for keys.
+ */
+export type TFailLevelKey = 'ignore_errors' | 'abort_on_errors' | 'abort_on_warnings';
+/**
+ * Scalar literal, a single, indivisible piece of data:
+ * string, number, boolean, and null.
+ * @property {string | undefined} [tag]
+ *           Its contents may change at any time and should not
+ *           be relied upon for any significant purpose.
+ * @note Undefined is included here despite that JSON cannot represent
+ *       it (undefined), but JS objects can (it's sometimes useful in
+ *       debugging etc), it will later get stripped if converted into JSON.
+ */
+export type TScalarValue = {
+    type: 'String';
+    value: string;
+    tag: string | undefined;
+} | {
+    type: 'Number';
+    value: number;
+    tag: string | undefined;
+} | {
+    type: 'Boolean';
+    value: boolean;
+    tag: string | undefined;
+} | {
+    type: 'Null';
+    value: null;
+    tag: string | undefined;
+} | {
+    type: 'Undefined';
+    value: undefined;
+    tag: string | undefined;
+};
+/** Any literal value in YINI: scalar, list, or object. */
+export type TValueLiteral = TScalarValue | TListValue | TObjectValue;
+/**
+ * @property {string | undefined} [tag]
+ *           Debugging only. Its contents may change at any time and
+ *           must not be relied upon for any functional purpose.
+ */
+export type TListValue = {
+    type: 'List';
+    elems: readonly TValueLiteral[];
+    tag: string | undefined;
+};
+/**
+ * @property {string | undefined} [tag]
+ *           Debugging only. Its contents may change at any time and
+ *           must not be relied upon for any functional purpose.
+ */
+export type TObjectValue = {
+    type: 'Object';
+    entries: Readonly<Record<string, TValueLiteral>>;
+    tag: string | undefined;
+};
+export type TSectionHeaderType = undefined | 'Classic-Header-Marker' | 'Numeric-Header-Marker';
+export type TIssueType = 'Fatal-Error' | 'Internal-Error' | 'Syntax-Error' | 'Syntax-Warning' | 'Notice' | 'Info';
+interface IMetaBaseInfo {
+    sourceType: TSourceType;
+    fileName: string | undefined;
+}
+/**
+ * Internal runtime info / meta data.
+ * @note Used for internal diagnostics, bookkeeping, state, etc.
+ */
+export interface IRuntimeInfo extends IMetaBaseInfo {
+    lineCount: number | null;
+    fileByteSize: number | null;
+    timeIoMs: number | null;
+    preferredBailSensitivity: null | TPreferredFailLevel;
+    sha256: string | null;
+}
+export interface IParseCoreOptions {
     isStrict: boolean;
-    bailSensitivityLevel: TBailSensitivityLevel;
+    bailSensitivity: TBailSensitivityLevel;
     isIncludeMeta: boolean;
     isWithDiagnostics: boolean;
     isWithTiming: boolean;
+    isKeepUndefinedInMeta: boolean;
+    isRequireDocTerminator: boolean;
 }
-export interface IParseMetaData {
-    strictMode: boolean;
-    hasTerminal: boolean;
-    sections: null | number;
-    members: null | number;
-    keysParsed: null | number;
-    sectionChains: null | number;
+/**
+ * User-facing options, these are external and should be more user friendly,
+ * and shorter, parameter names than the (more descriptive) internal
+ * engine option names.
+ *
+ * @note These parameters are emphasizes a bit more than the other options,
+ *       therefor these are kept a bit shorter for usability-purposes.
+ * @note These are the same as in the "simple positional API" function in
+ *       the YINI class.
+ */
+interface IPrimaryUserParams {
+    strictMode?: boolean;
+    failLevel?: TPreferredFailLevel;
+    includeMetaData?: boolean;
+}
+export interface IAllUserOptions extends IPrimaryUserParams {
+    includeDiagnostics?: boolean;
+    includeTiming?: boolean;
+    preserveUndefinedInMeta?: boolean;
+    requireDocTerminator?: boolean;
+}
+export interface IYiniAST extends IMetaBaseInfo {
+    root: IYiniSection;
+    isStrict: boolean;
+    terminatorSeen: boolean;
+    yiniMarkerSeen: boolean;
+    maxDepth: number | null;
+    numOfSections: number;
+    numOfMembers: number;
+    sectionNamePaths: string[] | null;
+}
+export interface IYiniSection {
+    sectionName: string;
+    level: number;
+    members: Map<string, TValueLiteral>;
+    children: IYiniSection[];
+}
+export interface IBuildOptions {
+    mode?: 'lenient' | 'strict';
+    onDuplicateKey?: 'error' | 'warn' | 'keep-first' | 'overwrite';
+}
+export interface IIssuePayload {
+    line: number | undefined;
+    column: number | undefined;
+    typeKey: string;
+    message: string;
+    advice: string | undefined;
+    hint: string | undefined;
+}
+/**
+ * @note NOTE: USE NO TYPES here (or neither in nested structures), they
+ *       should only be strings (and content MUST be transformed from the
+ *       types to lower snake case)
+ *
+ *       *** DUE TO make easier for tooling ***
+ *
+ * @note UPDATE 'metaSchemaVersion' on any edits to the meta structure.
+ */
+export interface IResultMetaData {
+    parserVersion: string;
+    mode: 'lenient' | 'strict';
+    orderPreserved: boolean;
+    totalErrors: number;
+    totalWarnings: number;
+    totalMessages: number;
+    runStartedAt: string;
+    runFinishedAt: string;
+    durationMs: number;
+    source: {
+        sourceType: string;
+        fileName: undefined | string;
+        hasDocumentTerminator: boolean;
+        hasYiniMarker: boolean;
+        byteSize: null | number;
+        lineCount: null | number;
+        sha256: null | string;
+    };
+    structure: {
+        maxDepth: null | number;
+        sectionCount: null | number;
+        memberCount: null | number;
+        keysParsedCount: null | number;
+        sectionNamePaths: string[] | null;
+    };
+    metaSchemaVersion: '1.0.0';
     diagnostics?: {
-        bailSensitivityLevel: TBailSensitivityLevel;
-        errors: null | number;
-        warnings: null | number;
-        infoAndNotices: null | number;
-        envs: {
+        failLevel: {
+            preferredLevel: null | 'auto' | 0 | 1 | 2;
+            levelUsed: TBailSensitivityLevel;
+            levelKey: TFailLevelKey;
+            levelLabel: TPersistThreshold;
+            levelDescription: string | null;
+        };
+        errors: {
+            errorCount: number;
+            payload: IIssuePayload[];
+        };
+        warnings: {
+            warningCount: number;
+            payload: IIssuePayload[];
+        };
+        notices: {
+            noticeCount: number;
+            payload: IIssuePayload[];
+        };
+        infos: {
+            infoCount: number;
+            payload: IIssuePayload[];
+        };
+        environment: {
             NODE_ENV: undefined | string;
             APP_ENV: undefined | string;
-            libNodeEnv: undefined | string;
-            libAppEnv: undefined | string;
-        };
-        libFlags: {
-            isDev: boolean;
-            isDebug: boolean;
+            lib: {
+                nodeEnv: undefined | string;
+                appEnv: undefined | string;
+                flags: {
+                    isDev: boolean;
+                    isDebug: boolean;
+                };
+            };
         };
+        optionsUsed: IAllUserOptions;
     };
     timing?: {
-        totalMs: null | number;
-        phase1Ms: null | number;
-        phase2Ms: null | number;
-        phase3Ms: null | number;
+        total: null | {
+            timeMs: number;
+            name: string;
+        };
+        phase0: undefined | {
+            timeMs: number;
+            name: string;
+        };
+        phase1: null | {
+            timeMs: number;
+            name: string;
+        };
+        phase2: null | {
+            timeMs: number;
+            name: string;
+        };
+        phase3: null | {
+            timeMs: number;
+            name: string;
+        };
+        phase4: null | {
+            timeMs: number;
+            name: string;
+        };
     };
 }
-export type TSyntaxTreeContainer = {
-    _syntaxTree: TSyntaxTree;
-    _hasTerminal: boolean;
-    _meta_numOfSections: number;
-    _meta_numOfMembers: number;
-    _meta_numOfChains: number;
-};
-export type TSyntaxTree = IChainContainer[];
-export type TSectionHeaderType = undefined | 'Classic-Header-Marker' | 'Numeric-Header-Marker';
-export interface IChainContainer {
-    originLevel: number;
-    chain: any;
-}
-export interface ISectionResult {
-    level: number;
-    name: string;
-    members: any;
-}
+export {};

package/dist/core/types.js

@@ -1,36 +1,10 @@
 "use strict";
-/*
-    A Full Nested Linear Branch - (in tree data structures):
-    - A branch in a tree where each section has at most one nested section at each level (never more at each level).
-    - Forms a straight path: each section (node) has exactly one nested section, and this continues through multiple levels—like a linked chain.
-    - If a section has a nested section, the nesting must form a direct sequence. For example: Section level 3 → Section level 4 → Section level 5, and so on.
-    - Can be any branch within a tree (not just the root), or even the whole tree in some cases.
-    - Each section includes its own members at that level.
-    - Represents a single path from the starting section to the last (deepest) nested section.
-    - In other words, it’s a branch that forms a continuous, unbranched sequence of nested sections.
-    
-    Example:
-    "
-^ Section1
-sValue = 1
-    ^^ Section11
-    sValue = 11
-    bValue = OFF
-^ Section2
-sValue = 2
-        "
-
-    Has two Nested Linear Branches:
-    1:
-    ^ Section1
-    sValue = 1
-        ^^ Section11
-        sValue = 11
-        bValue = OFF
-    
-    2:
-    ^ Section2
-    sValue = 2
-    
+/**
+ * @note
+ *   The use of null vs undefined
+ *   ----------------------------
+ *   The convention here (in this file) is:
+ *   - undefined is used where a value is missing, or does not apply.
+ *   - null is used where a value is missing or has not yet been computed.
  */
 Object.defineProperty(exports, "__esModule", { value: true });