@datasworn-community/core 0.2.0

package/dist/esm/IdParser.js

@@ -0,0 +1,1004 @@
+import { ParseError } from './Errors.js';
+import { COLLECTION_DEPTH_MAX, COLLECTION_DEPTH_MIN, CollectionsKey, ContentsKey, GlobstarString, IdKey, PathKeySep, PrefixSep, TypeSep, WildcardString } from './IdElements/CONST.js';
+import { Pattern } from './IdElements/index.js';
+import TypeGuard from './IdElements/TypeGuard.js';
+import TypeId from './IdElements/TypeId.js';
+/**
+ * Resolves a potentially dot-separated property path to retrieve a nested value.
+ * For example, 'trigger.conditions' on { trigger: { conditions: [...] } } returns the conditions array.
+ */
+function getNestedProperty(obj, propertyPath) {
+    if (typeof obj !== 'object' || obj === null)
+        return undefined;
+    const parts = propertyPath.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (typeof current !== 'object' || current === null)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Checks if a potentially dot-separated property path exists on an object.
+ */
+function hasNestedProperty(obj, propertyPath) {
+    return getNestedProperty(obj, propertyPath) !== undefined;
+}
+/** Performs parsing, validation, and construction of Datasworn IDs, and traverses the Datasworn hierarchy to retrieve matching node(s).  */
+class IdParser {
+    static #tree = null;
+    /**  */
+    static get tree() {
+        return IdParser.#tree;
+    }
+    static set tree(value) {
+        IdParser.#tree = value;
+    }
+    #pathSegments;
+    #typeIds;
+    /**
+     * The object used for log messages.
+     * @default console
+     */
+    static logger = console;
+    get typeIds() {
+        return this.#typeIds;
+    }
+    set typeIds(value) {
+        IdParser.#validateTypeIds(value);
+        this.#typeIds = value;
+    }
+    get pathSegments() {
+        return this.#pathSegments;
+    }
+    set pathSegments(value) {
+        IdParser._validatePathSegments(this.typeIds, value);
+        this.#pathSegments = value;
+    }
+    /**
+     * This node's ancestor key on {@link Datasworn.RulesPackage}.
+     */
+    get typeBranchKey() {
+        return TypeId.getBranchKey(this.primaryTypeId);
+    }
+    constructor(options) {
+        // prepare the ID so we can throw errors with it if necessary
+        const id = IdParser.#toString(options);
+        const { typeIds, pathSegments } = options;
+        const errors = [];
+        try {
+            this.typeIds = typeIds;
+            this.pathSegments = pathSegments;
+        }
+        catch (e) {
+            errors.push(e);
+        }
+        if (errors.length > 0)
+            throw new ParseError(id, errors.join('\n'));
+    }
+    /**
+     * Returns a string representation of the ID.
+     */
+    toString() {
+        return IdParser.#toString(this);
+    }
+    toJSON() {
+        return this.toString();
+    }
+    // ID parts
+    /** The type ID of the target node. For primary IDs, this is the same as {@link IdParser.typeId}. */
+    get typeId() {
+        return this.typeIds.at(-1);
+    }
+    /** The type ID of the most recent primary node. For primary IDs, this is the same as {@link IdParser.typeId} */
+    get primaryTypeId() {
+        return this.typeIds[0];
+    }
+    get primaryPath() {
+        return this.pathSegments[0];
+    }
+    get primaryPathKeys() {
+        return this.primaryPath.split(PathKeySep);
+    }
+    /** The ID of the {@link RulesPackage} that contains this ID, or a wildcard to represent any RulesPackage. */
+    get rulesPackageId() {
+        return this.primaryPathKeys[0];
+    }
+    /** The dot-separated, fully-qualified type ID. For primary types, this is the same as {@link IdParser.typeId}  */
+    get compositeTypeId() {
+        return this.typeIds.join(TypeSep);
+    }
+    /** The dot-separated, fully-qualified path. For primary type IDs, this is the same as {@link IdParser.primaryPath}  */
+    get compositePath() {
+        return this.pathSegments.join(TypeSep);
+    }
+    /** Does this ID contain any wildcard ("*") or globstar ("**") elements? */
+    get isWildcard() {
+        return this.toString().includes(WildcardString);
+    }
+    /** Get an array of the types that are embeddable by this type. */
+    getEmbeddableTypes() {
+        return TypeId.getEmbeddableTypes(this.typeId, this instanceof EmbeddedId);
+    }
+    /**
+     * Get a Datasworn node by its ID.
+     * @throws If the ID is a wildcard ID; if no Datasworn tree is provided (either in {@link IdParser.tree} or as an argument).
+     * @returns The identified node, or `undefined` if the node doesn't exist.
+     */
+    get(tree = IdParser.tree) {
+        tree ||= IdParser.tree;
+        if (tree == null)
+            throw new Error(`No Datasworn tree found -- set the static property ${IdParser.constructor.name}#tree, or provide one as a parameter.`);
+        if (this.isWildcard)
+            throw new Error(`${this.constructor.name}#${this.get.name} expected a non-wildcard ID, but got <${this.toString()}>. If you want to get wildcard matches, use ${this.constructor.name}#${this.getMatches.name} instead.`);
+        try {
+            return this._getUnsafe(tree);
+        }
+        catch (_e) {
+            return undefined;
+        }
+    }
+    /**
+     * Get all Datasworn nodes that match this wildcard ID.
+     * @remarks Non-wildcard IDs work here too; technically they're valid as wildcard IDs.
+     * @param forEach Optional function to apply to each match. If it returns `true`, the matcher will exit early and return only the matches it has made so far.
+     * @returns A {@link Map}
+     */
+    getMatches(tree = IdParser.tree, forEach) {
+        tree ||= IdParser.tree;
+        if (tree == null)
+            throw new Error(`No Datasworn tree found -- set the static property ${IdParser.constructor.name}#tree, or provide one as a parameter.`);
+        // skip the matching process if it's not actually a wildcard ID
+        if (!this.isWildcard) {
+            const match = this.get(tree);
+            const matches = new Map();
+            if (match != null) {
+                matches.set(this.toString(), match);
+                if (typeof forEach === 'function')
+                    forEach(this.toString(), match);
+            }
+            return matches;
+        }
+        return this._getMatchesUnsafe(tree, forEach);
+    }
+    /**
+     * Can the target ID be matched with this ID?
+     * @throws If `target` is a wildcard.
+     */
+    isMatch(target) {
+        const targetIsWildcard = target.toString().includes(WildcardString);
+        if (targetIsWildcard)
+            throw new Error(`Expected a non-wildcard ID, got "${target.toString()}"`);
+        // lazy evaluation for exact matches
+        if (this.toString() === target.toString())
+            return true;
+        const that = typeof target === 'string' ? IdParser.parse(target) : target;
+        // if it's not an exact match, and this isn't a wildcard, then it logically can't be a match
+        if (!this.isWildcard)
+            return false;
+        // can never match a different type composite
+        if (this.compositeTypeId !== that.compositeTypeId)
+            return false;
+        // no more trivial matches, fall back regular expression (more computationally expensive)
+        return this.pathRegExp.test(that.compositePath);
+    }
+    /** Is this non-wildcard ID matched by at least one of the provided wildcard IDs?
+     * @throws If this instance is a wildcard ID; if it attempts a comparison with an invalid ID string
+     */
+    isMatchedBy(...wildcardIds) {
+        if (this.isWildcard)
+            throw new Error(`Matching a wildcard ID as a subset of another wildcard ID is not implemented.`);
+        for (const wildcardId of wildcardIds) {
+            // short circuit parsing if it's a trivial match
+            if (this.toString() === wildcardId.toString())
+                return true;
+            const parsed = typeof wildcardId === 'string' ? IdParser.parse(wildcardId) : wildcardId;
+            if (parsed.isMatch(this))
+                return true;
+        }
+        return false;
+    }
+    /** @internal */
+    _getPrefixRegExpSource() {
+        const src = this.typeIds.join(`\\${TypeSep}`);
+        return src;
+    }
+    #pathRegExp = null;
+    get pathRegExp() {
+        if (this.#pathRegExp == null)
+            this.#pathRegExp = RegExp(`^${this._getPathRegExpSource()}$`);
+        return this.#pathRegExp;
+    }
+    #regExp = null;
+    get regExp() {
+        if (this.#regExp == null)
+            this.#regExp = RegExp('^' +
+                this._getPrefixRegExpSource() +
+                PrefixSep +
+                this._getPathRegExpSource() +
+                '$');
+        return this.#regExp;
+    }
+    /** @internal */
+    _flush() {
+        this.#pathRegExp = null;
+        this.#regExp = null;
+    }
+    /** @internal */
+    _getPathRegExpSource() {
+        let pathPattern = '';
+        const keySep = `\\${PathKeySep}`;
+        const { min, max } = IdParser._getPathKeyCount(this.primaryTypeId);
+        /** The minimum number of path keys a single globstar ("**") may stand in for */
+        const expansionMin = Math.max(0, min - (this.primaryPathKeys.length - 1));
+        /** The maximum number of keys that a single globstar ("**") may stand in for. */
+        const expansionMax = Math.max(0, max - (this.primaryPathKeys.length - 1));
+        for (let i = 0; i < this.primaryPathKeys.length; i++) {
+            const currentKey = this.primaryPathKeys[i];
+            switch (true) {
+                // first key is always the rules package, which allows more characters
+                case i === 0:
+                    pathPattern += TypeGuard.Wildcard(currentKey)
+                        ? Pattern.RulesPackageElement.source
+                        : currentKey;
+                    break;
+                case TypeGuard.Wildcard(currentKey):
+                    if (i > 0)
+                        pathPattern += keySep;
+                    pathPattern += Pattern.DictKeyElement.source;
+                    break;
+                case TypeGuard.Globstar(currentKey):
+                    // no key separator here since it's part of the non-capturing group
+                    pathPattern += `(?:${keySep}${Pattern.DictKeyElement.source}){${expansionMin},${expansionMax}}`;
+                    break;
+                default:
+                    if (i > 0)
+                        pathPattern += keySep;
+                    pathPattern += currentKey;
+                    break;
+            }
+        }
+        return pathPattern;
+    }
+    /** Assign `_id` strings in a Datasworn node.
+     * @param node The Datasworn
+     * @param recursive Should IDs be assigned to descendant objects too? (default: true)
+     * @param index A Map used to index items by their assigned ID.
+     * @returns The mutated object.
+     */
+    assignIdsIn(node, _recursive = true, index) {
+        if (typeof node !== 'object' || node === null)
+            throw new Error(`Expected a Datasworn node object, but got ${String(node)}`);
+        if (IdKey in node && typeof node._id === 'string')
+            IdParser.logger.warn(`Can't assign <${this.toString()}>, node already has <${node._id}>`);
+        else {
+            if (index instanceof Map && index.has(this.toString()))
+                throw new Error(`Generated ID <${this.toString()}>, but it already exists in the index`);
+            // @ts-expect-error
+            node._id = this.toString();
+            if (index instanceof Map)
+                index.set(this.toString(), node);
+        }
+        return node;
+    }
+    static get(id, tree = IdParser.datasworn) {
+        const parsed = id instanceof IdParser ? id : IdParser.parse(id);
+        return parsed.get(tree);
+    }
+    static getMatches(id, tree = IdParser.datasworn, forEach) {
+        const parsed = id instanceof IdParser ? id : IdParser.parse(id);
+        return parsed.getMatches(tree, forEach);
+    }
+    static parse(id) {
+        const { typeIds, pathSegments } = IdParser.#parseOptions(id);
+        const [primaryTypeId, ...embeddedTypeIds] = typeIds;
+        const [primaryPath, ...embeddedPaths] = pathSegments;
+        const [rulesPackage, ...pathKeys] = primaryPath.split(PathKeySep);
+        const Ctor = IdParser.#getClassForPrimaryTypeId(primaryTypeId);
+        // @ts-expect-error
+        const base = new Ctor(primaryTypeId, rulesPackage, ...pathKeys);
+        if (embeddedTypeIds.length === 0)
+            return base;
+        let lastParser = base;
+        for (let i = 0; i < embeddedTypeIds.length; i++) {
+            const typeId = embeddedTypeIds[i];
+            const pathKey = embeddedPaths[i];
+            lastParser = lastParser.createEmbeddedIdChild(typeId, pathKey);
+        }
+        return lastParser;
+    }
+    /**
+     * Recursively assigns IDs to all eligibile nodes within a given {@link DataswornSource.RulesPackage}.
+     * @param rulesPackage The rules package to assign IDs to. This function mutates the object.
+     * @param index If provided, nodes that receive IDs will be indexed in the map (with their ID as the key).
+     * @returns The mutated `rulesPackage`, which now satisfies the requirements for a complete {@link Datasworn.RulesPackage}
+     */
+    static assignIdsInRulesPackage(rulesPackage, index) {
+        const errorMessages = [];
+        for (const typeId in TypeId.BranchKey) {
+            const typeBranchKey = TypeId.getBranchKey(typeId);
+            const typeBranch = rulesPackage[typeBranchKey];
+            if (typeBranch == null)
+                continue;
+            for (const dictKey in typeBranch) {
+                const node = typeBranch[dictKey];
+                if (node == null)
+                    continue;
+                try {
+                    switch (true) {
+                        case TypeGuard.CollectionType(typeId):
+                            new CollectionId(typeId, rulesPackage._id, dictKey).assignIdsIn(node, true, index);
+                            break;
+                        case TypeGuard.NonCollectableType(typeId):
+                            new NonCollectableId(typeId, rulesPackage._id, dictKey).assignIdsIn(node, true, index);
+                            break;
+                    }
+                }
+                catch (e) {
+                    const id = `${typeId}${PrefixSep}${rulesPackage._id}${PathKeySep}${dictKey}`;
+                    errorMessages.push(`Failed to create ID within <${id}>. ${String(e)}`);
+                }
+            }
+        }
+        if (errorMessages.length > 0)
+            throw new Error(errorMessages.join('\n'));
+        // @ts-expect-error
+        return rulesPackage;
+    }
+    // Static private methods
+    static #validateTypeIds(typeIds) {
+        if (!Array.isArray(typeIds) ||
+            !typeIds.every((str) => typeof str === 'string'))
+            throw new Error(`Expected an array of strings but got ${JSON.stringify(typeIds)}`);
+        const primaryTypeId = typeIds[0];
+        if (!TypeGuard.PrimaryType(primaryTypeId))
+            throw new Error(`Expected a primary type but got ${JSON.stringify(primaryTypeId)}`);
+        for (let i = 1; i < typeIds.length; i++) {
+            const embeddedTypeId = typeIds[i];
+            const parentTypeId = typeIds[i - 1];
+            const parentTypeIsEmbedded = i > 1;
+            const embeddableTypes = TypeId.getEmbeddableTypes(parentTypeId, parentTypeIsEmbedded);
+            if (!embeddableTypes.includes(embeddedTypeId)) {
+                const parentTypeIdComposite = typeIds.slice(0, i).join(TypeSep);
+                throw new Error(`Can't embed type "${embeddedTypeId}" in type "${parentTypeIdComposite}"`);
+            }
+        }
+        return true;
+    }
+    static #toString({ typeIds, pathSegments }) {
+        const leftSide = typeIds.join(TypeSep);
+        const rightSide = pathSegments.join(TypeSep);
+        return leftSide + PrefixSep + rightSide;
+    }
+    static _validatePathSegments(typeIds, pathSegments) {
+        if (!(Array.isArray(pathSegments) &&
+            pathSegments.every((str) => typeof str === 'string')))
+            throw new Error(`Expected an array of strings, but got ${JSON.stringify(pathSegments)}`);
+        if (typeIds.length !== pathSegments.length)
+            throw new Error(`The length of typeIds (${typeIds.length}) and pathSegments (${pathSegments.length}) does't match.`);
+        const [primaryTypeId, ..._embeddedTypeIds] = typeIds;
+        const errors = [];
+        const [primaryPath, ...embeddedPaths] = pathSegments;
+        try {
+            IdParser._validatePrimaryPath(primaryTypeId, primaryPath);
+        }
+        catch (e) {
+            errors.push(e);
+        }
+        // if there's no embedded paths, we're done
+        if (pathSegments.length === 1)
+            return true;
+        // TODO: make it so that a single globstar as full path matches any of its type -- even for embedded ones
+        if (TypeId.canHaveEmbed(primaryTypeId, false))
+            for (let i = 0; i < embeddedPaths.length; i++) {
+                const currentTypeIds = typeIds.slice(0, i + 1);
+                const embeddedPath = embeddedPaths[i];
+                try {
+                    EmbeddedId._validateEmbeddedPath(currentTypeIds, embeddedPath);
+                }
+                catch (e) {
+                    errors.push(e);
+                }
+            }
+        else if (embeddedPaths.length > 0) {
+            errors.push(`"${primaryTypeId}" isn't an embedding type, but received embedded paths: ${JSON.stringify(embeddedPaths)}`);
+        }
+        if (errors.length)
+            throw new Error(`Expected a valid ID path, but got ${pathSegments.join(TypeSep)}\n${errors.join('\n')}`);
+        return true;
+    }
+    static _validateEmbeddedPath(typeIds, path) {
+        const _embeddedTypeId = typeIds.at(-1);
+        const pathParts = path.split(PathKeySep);
+        for (const part of pathParts)
+            if (!(IdParser._validateDictKey(part) || IdParser._validateIndexKey(part)))
+                throw new Error(`Expected a DictKey, array index, or wildcard, but got ${JSON.stringify(part)}`);
+        return true;
+    }
+    static _validateIndexKey(value) {
+        return TypeGuard.Wildcard(value) || TypeGuard.IndexKey(value);
+    }
+    /**
+     * Parses an ID string in to an IdParser options object without attempting to validate it.
+     */
+    static #parseOptions(id) {
+        const [leftSide, rightSide] = id.split(PrefixSep);
+        const typeIds = leftSide.split(TypeSep);
+        const pathSegments = rightSide.split(TypeSep);
+        return {
+            typeIds,
+            pathSegments
+        };
+    }
+    static #getClassForPrimaryTypeId(typeId) {
+        switch (true) {
+            case TypeGuard.CollectionType(typeId):
+                // @ts-expect-error
+                return CollectionId;
+            case TypeGuard.CollectableType(typeId):
+                // @ts-expect-error
+                return CollectableId;
+            case TypeGuard.NonCollectableType(typeId):
+                // @ts-expect-error
+                return NonCollectableId;
+            default:
+                throw new Error(`Expected TypeId.AnyPrimary, but got ${JSON.stringify(typeId)}`);
+        }
+    }
+    /** @internal */
+    static _getPathKeyCount(typeId) {
+        let min, max;
+        switch (true) {
+            case TypeGuard.CollectionType(typeId):
+                // has a rulespackage
+                min = COLLECTION_DEPTH_MIN + 1;
+                max = COLLECTION_DEPTH_MAX + 1;
+                break;
+            case TypeGuard.CollectableType(typeId):
+                // has a rulespackage + its own key
+                min = COLLECTION_DEPTH_MIN + 2;
+                max = COLLECTION_DEPTH_MAX + 2;
+                break;
+            case TypeGuard.NonCollectableType(typeId):
+                // has a rulespackage
+                min = max = COLLECTION_DEPTH_MIN + 1;
+                break;
+            default:
+                throw new Error(`Expected primary TypeId but got ${String(typeId)}`);
+        }
+        return { min, max };
+    }
+    /**
+     * @throws If the typeId isn't a primary TypeId; if the path doesn't meet the minimum or maximum length for its type; or if any of the individual elements are invalid.
+     */
+    static _validatePrimaryPath(typeId, path) {
+        if (!TypeGuard.PrimaryType(typeId))
+            throw new Error(`Expected a primary TypeId, but got ${JSON.stringify(typeId)}. Valid TypeIds are: ${JSON.stringify(TypeId.Primary)}`);
+        const { min, max } = IdParser._getPathKeyCount(typeId);
+        const [rulesPackageId, ...tail] = path.split(PathKeySep);
+        const errors = [];
+        let nonGlobstarCount = 0;
+        let globstarCount = 0;
+        switch (true) {
+            case TypeGuard.Globstar(rulesPackageId):
+                globstarCount++;
+                break;
+            case TypeGuard.Wildcard(rulesPackageId):
+            case TypeGuard.RulesPackageId(rulesPackageId):
+                nonGlobstarCount++;
+                break;
+            default:
+                errors.push(`Expected RulesPackageId but got ${String(rulesPackageId)}`);
+                break;
+        }
+        for (const k of tail)
+            switch (true) {
+                case TypeGuard.Globstar(k):
+                    globstarCount++;
+                    break;
+                case TypeGuard.Wildcard(k):
+                case TypeGuard.DictKey(k):
+                    nonGlobstarCount++;
+                    break;
+                default:
+                    errors.push(`Expected DictKey but got ${String(k)}`);
+                    break;
+            }
+        if (nonGlobstarCount > max)
+            // so this error appears first
+            errors.unshift(`Path expects a maximum length of ${max}, but got ${nonGlobstarCount}`);
+        if (nonGlobstarCount < min &&
+            // if there's at least one globstar, then it'll expand to meet the minimum
+            !(globstarCount > 0))
+            errors.unshift(`Path expects a minimum length of ${min}, but got ${nonGlobstarCount}`);
+        if (errors.length > 0)
+            throw new Error(`Expected valid Primary ID path but got "${path}".\n\t${errors.join('\n\t')}`);
+        return true;
+    }
+    /** @internal */
+    static _validateDictKey(key) {
+        return TypeGuard.AnyWildcard(key) || TypeGuard.DictKey(key);
+    }
+    static _getMatchesFrom(obj, matchKey = WildcardString) {
+        switch (true) {
+            case Array.isArray(obj):
+                return IdParser.#getMatchesFromArray(obj, matchKey);
+            case obj instanceof Map:
+                return IdParser.#getMatchesFromMap(obj, matchKey);
+            case typeof obj === 'object':
+                return IdParser.#getMatchesFromRecord(obj, matchKey.toString());
+            default:
+                throw new Error(`Expected an Array, Map, or Record, but got ${String(obj)}`);
+        }
+    }
+    static #getMatchesFromArray(array, matchKey = WildcardString) {
+        if (!Array.isArray(array))
+            throw new Error(`Expected an Array, but got ${String(array)}`);
+        // special case: a wildcard matches everything, so return it as a new Map
+        if (TypeGuard.AnyWildcard(matchKey))
+            return new Map(array.entries());
+        const index = typeof matchKey === 'string' ? Number.parseInt(matchKey, 10) : matchKey;
+        if (!Number.isInteger(index))
+            throw Error(`Unable to parse an index (integer) from ${String(matchKey)}`);
+        const results = new Map();
+        const match = array[index];
+        if (match != null)
+            results.set(index, match);
+        return results;
+    }
+    static #getMatchesFromMap(map, matchKey = WildcardString) {
+        if (!(map instanceof Map))
+            throw new Error(`Expected a Map, but got ${String(map)}`);
+        // special case: a wildcard matches everything, so return it as a new Map
+        if (TypeGuard.AnyWildcard(matchKey))
+            return new Map(map);
+        const results = new Map();
+        if (map.has(matchKey))
+            results.set(matchKey, map.get(matchKey));
+        return results;
+    }
+    static #getMatchesFromRecord(record, matchKey) {
+        if (record == null || typeof record !== 'object' || Array.isArray(record))
+            throw new Error(`Expected a Record object, but got ${String(record)}`);
+        const results = new Map();
+        switch (true) {
+            case TypeGuard.AnyWildcard(matchKey):
+                for (const k in record)
+                    if (Object.hasOwn(record, k))
+                        results.set(k, record[k]);
+                break;
+            case Object.hasOwn(record, matchKey):
+                results.set(matchKey, record[matchKey]);
+                break;
+            default:
+                break;
+        }
+        return results;
+    }
+    // Static properties
+    /** An optional reference to the Datasworn tree object, shared by all subclasses. Used as the default value for several traversal methods. */
+    static datasworn = null;
+    static RulesPackagePattern = Pattern.RulesPackageElement;
+    static DictKeyPattern = Pattern.DictKeyElement;
+    static RecursiveDictKeyPattern = Pattern.RecursiveDictKeysElement;
+    /** @internal */
+    _getRulesPackage(tree) {
+        if (tree == null)
+            throw new Error(`No Datasworn tree found -- set the static property ${IdParser.constructor.name}#tree, or provide one as a parameter.`);
+        if (this.isWildcard)
+            throw new Error(`${this.constructor.name}#${this.get.name} expected a non-wildcard ID, but got <${this.toString()}>. If you want to get wildcard matches, use ${this.constructor.name}#${this.getMatches.name} instead.`);
+        if (tree instanceof Map)
+            return tree.get(this.rulesPackageId) ?? undefined;
+        return tree[this.rulesPackageId] ?? undefined;
+    }
+    /** @internal */
+    _getTypeBranch(tree) {
+        const pkg = this._getRulesPackage(tree);
+        if (pkg == null)
+            throw new Error(`Couldn't find a RulesPackage with the id "${this.rulesPackageId}"`);
+        return pkg[this.typeBranchKey];
+    }
+    /** @internal */
+    _getUnsafe(tree) {
+        const typeBranch = this._getTypeBranch(tree);
+        if (typeBranch == null)
+            throw new Error(`RulesPackage <${this.rulesPackageId}> doesn't have a "${this.typeBranchKey}" type branch.`);
+        const [_rulesPackageId, key, ..._tailKeys] = this.primaryPathKeys;
+        let result;
+        if (typeBranch instanceof Map)
+            result = typeBranch.get(key);
+        else
+            result = typeBranch[key];
+        if (result == null)
+            throw new Error(`Couldn't find key <${key}> in <${this.rulesPackageId}.${this.typeBranchKey}>`);
+        return result;
+    }
+    /** @internal */
+    _matchRulesPackages(tree = IdParser.tree) {
+        if (tree == null)
+            throw new Error(`No Datasworn tree found -- set the static property ${IdParser.constructor.name}#tree, or provide one as a parameter.`);
+        return IdParser._getMatchesFrom(tree, this.rulesPackageId);
+    }
+    /**
+     * @param forEach Optional function to apply to each match. If it returns `true`, the matcher will exit early and return whatever results it currently has.
+     * @internal
+     */
+    _getMatchesUnsafe(tree, forEach) {
+        const pkgs = this._matchRulesPackages(tree);
+        const results = new Map();
+        const [_rulesPackageId, nextKey] = this.primaryPathKeys;
+        const joiner = this instanceof EmbeddedId ? TypeSep : PathKeySep;
+        for (const [pkgId, pkg] of pkgs) {
+            // @ts-expect-error
+            const typeBranch = pkg[this.typeBranchKey];
+            if (typeBranch == null)
+                continue;
+            const matches = IdParser._getMatchesFrom(typeBranch, nextKey);
+            for (const [key, match] of matches) {
+                const path = [pkgId, key].join(joiner);
+                // computing the ID for this *position*, not the value of the _id property;
+                // this is done so that a node that overrides this position's default node retains its own ID, but still matches as intended.
+                const positionId = [this.compositeTypeId, path].join(PrefixSep);
+                results.set(positionId, match);
+                if (typeof forEach === 'function' && forEach(positionId, match))
+                    return results;
+            }
+        }
+        return results;
+    }
+}
+class EmbeddingId extends IdParser {
+    /**
+     * Create a child EmbeddedId with a given type and key.
+     */
+    createEmbeddedIdChild(embeddedTypeId, key) {
+        return new EmbeddedId(this, embeddedTypeId, key);
+    }
+    get embeddableTypes() {
+        return TypeId.getEmbeddableTypes(this.typeId, this instanceof EmbeddedId);
+    }
+    assignIdsIn(node, recursive, index) {
+        const result = super.assignIdsIn(node, recursive, index);
+        if (recursive)
+            for (const embedTypeId of this.getEmbeddableTypes()) {
+                const propertyPath = TypeId.getEmbeddedPropertyKey(embedTypeId);
+                if (typeof node !== 'object')
+                    continue;
+                // Support nested property paths like 'trigger.conditions'
+                if (!hasNestedProperty(node, propertyPath))
+                    continue;
+                const childNodes = getNestedProperty(node, propertyPath);
+                if (childNodes == null)
+                    continue;
+                if (Array.isArray(childNodes)) {
+                    this.#assignEmbeddedIdsInArray(childNodes, embedTypeId, recursive, index);
+                }
+                else if (childNodes instanceof Map) {
+                    this.#assignEmbeddedIdsInMap(childNodes, embedTypeId, recursive, index);
+                }
+                else {
+                    this.#assignEmbeddedIdsInRecord(childNodes, embedTypeId, recursive, index);
+                }
+            }
+        return result;
+    }
+    #assignEmbeddedIdsInMap(children, nextTypeId, recursive, index) {
+        children.forEach((childNode, k) => this.createEmbeddedIdChild(nextTypeId, k.toString()).assignIdsIn(childNode, recursive, index));
+    }
+    #assignEmbeddedIdsInRecord(children, nextTypeId, recursive, index) {
+        for (const k in children) {
+            if (!Object.hasOwn(children, k))
+                continue;
+            const childNode = children[k];
+            if (childNode == null)
+                continue;
+            const childParser = this.createEmbeddedIdChild(nextTypeId, k);
+            childParser.assignIdsIn(childNode, recursive, index);
+        }
+    }
+    #assignEmbeddedIdsInArray(children, nextTypeId, recursive, index) {
+        children.forEach((childNode, i) => this.createEmbeddedIdChild(nextTypeId, i.toString()).assignIdsIn(childNode, recursive, index));
+    }
+}
+class NonCollectableId extends EmbeddingId {
+    get isRecursive() {
+        return false;
+    }
+    constructor(typeId, rulesPackage, key) {
+        const pathSegment = [rulesPackage, key].join(PathKeySep);
+        super({
+            typeIds: [typeId],
+            pathSegments: [pathSegment]
+        });
+    }
+}
+class CollectableId extends EmbeddingId {
+    get isRecursive() {
+        return true;
+    }
+    get embeddableTypes() {
+        return TypeId.getEmbeddableTypes(this.primaryTypeId, false);
+    }
+    constructor(typeId, rulesPackage, ...pathKeys) {
+        const pathSegment = [rulesPackage, ...pathKeys].join(PathKeySep);
+        super({
+            typeIds: [typeId],
+            pathSegments: [pathSegment]
+        });
+    }
+    get collectionAncestorKeys() {
+        // 1st element is the RulesPackageId, which isn't counted.
+        // last element is the key of this collectable, which isn't counted.
+        return this.primaryPathKeys.slice(1, -1);
+    }
+    get recursionDepth() {
+        return this.collectionAncestorKeys.length;
+    }
+    get parentTypeId() {
+        return TypeId.getCollectionOf(this.typeId);
+    }
+    getCollectionIdParent() {
+        const ancestorKeys = this.primaryPathKeys.slice(0, -1);
+        return new CollectionId(this.parentTypeId, ...ancestorKeys);
+    }
+    /** @internal */
+    _getUnsafe(tree) {
+        const parent = this.getCollectionIdParent();
+        const parentNode = parent._getUnsafe(tree);
+        // console.log(`<${this}> got parent`, parentNode)
+        const thisKey = this.primaryPathKeys.at(-1);
+        const { contents } = parentNode;
+        let result;
+        if (contents instanceof Map)
+            result = contents.get(thisKey);
+        else if (Object.hasOwn(contents, thisKey))
+            result = contents[thisKey];
+        if (result == null)
+            throw new Error(`No result for <${this.toString()}>`);
+        return result;
+    }
+    /** @internal */
+    _getMatchesUnsafe(tree, forEach) {
+        const parentId = this.getCollectionIdParent();
+        let matches;
+        const thisKey = this.primaryPathKeys.at(-1);
+        // these aren't the targets, so they don't get forEach passed to them
+        const parentMatches = parentId._getMatchesUnsafe(tree);
+        for (const [parentIdStr, parentMatch] of parentMatches) {
+            const contents = parentMatch[ContentsKey];
+            if (contents == null)
+                continue;
+            const collectables = IdParser._getMatchesFrom(contents, thisKey);
+            for (const [currentKey, match] of collectables) {
+                const [_parentTypeId, parentPath] = parentIdStr.split(PrefixSep);
+                const currentPath = parentPath + PathKeySep + currentKey;
+                const currentId = this.compositeTypeId + PrefixSep + currentPath;
+                matches ||= new Map();
+                matches.set(currentId, match);
+                if (typeof forEach === 'function' && forEach(currentId, match))
+                    return matches;
+            }
+        }
+        return matches ?? new Map();
+    }
+}
+class CollectionId extends IdParser {
+    constructor(typeId, rulesPackage, ...pathKeys) {
+        const pathSegment = [rulesPackage, ...pathKeys].join(PathKeySep);
+        super({
+            typeIds: [typeId],
+            pathSegments: [pathSegment]
+        });
+    }
+    get isRecursive() {
+        return true;
+    }
+    get recursionDepth() {
+        // first element is the RulesPackageId, which isn't counted.
+        return this.collectionAncestorKeys.length;
+    }
+    get collectionAncestorKeys() {
+        // 1st key is the RulesPackageId, so it's omitted
+        // last key is this Collection node -- it's omitted too
+        // everything but the last key, which belongs to the node itself
+        return this.primaryPathKeys.slice(1, -1);
+    }
+    /**
+     * Create an ID representing a {@link CollectableId} child of this CollectionId, using the provided key.
+     * @example
+     * ```typescript
+     * const collection = IdParser.parse('oracle_collection:starforged/core')
+     * const collectable = collection.createCollectableIdChild('action')
+     * console.log(collectable.toString()) // 'oracle_rollable:starforged/core/action'
+     * ```
+     */
+    createCollectableIdChild(key) {
+        return new CollectableId(TypeId.getCollectableOf(this.primaryTypeId), ...this.primaryPathKeys, key);
+    }
+    /**
+     * Create an ID representing a Collection child of this CollectionId, using the provided key.
+     * @throws If a child collection ID can't be created because the maximum recursion depth has been reached.
+     * @see {@link COLLECTION_DEPTH_MAX}
+     * @example
+     * ```typescript
+     * const collection = IdParser.parse('oracle_collection:starforged/planet')
+     * const childCollection = collection.createCollectionIdChild('furnace')
+     * console.log(childCollection.toString()) // 'oracle_collection:starforged/planet/furnace'
+     * ```
+     */
+    createCollectionIdChild(key) {
+        if (this.recursionDepth >= COLLECTION_DEPTH_MAX)
+            throw new ParseError(this.toString(), `Cant't generate a child collection ID because this ID has reached the maximum recursion depth (${COLLECTION_DEPTH_MAX})`);
+        return new CollectionId(this.primaryTypeId, ...this.primaryPathKeys, key);
+    }
+    assignIdsIn(node, recursive = true, index) {
+        // run this up front so the log ordering is more intuitive
+        const base = super.assignIdsIn(node, recursive, index);
+        if (recursive) {
+            if (ContentsKey in node && node[ContentsKey] != null)
+                for (const childKey in node[ContentsKey]) {
+                    const childNode = node[ContentsKey][childKey];
+                    if (childNode == null)
+                        continue;
+                    const childParser = this.createCollectableIdChild(childKey);
+                    childParser.assignIdsIn(childNode, recursive, index);
+                }
+            if (CollectionsKey in node && node[CollectionsKey] != null)
+                for (const childKey in node[CollectionsKey]) {
+                    const childCollection = node[CollectionsKey][childKey];
+                    if (childCollection == null)
+                        continue;
+                    const childParser = this.createCollectionIdChild(childKey);
+                    childParser.assignIdsIn(childCollection, recursive, index);
+                }
+        }
+        return base;
+    }
+    /**
+     * Returns a CollectionId representing the parent collection of this ID.
+     * @throws If a parent collection ID isn't possible (because this ID doesn't have a parent collection.)
+     * @example
+     * ```typescript
+     * const collection = IdParser.parse('oracle_collection:starforged/planet/jungle/settlements')
+     * const parentCollection = collection.getCollectionIdParent()
+     * console.log(parentCollection.toString()) // 'oracle_collection:starforged/planet/jungle'
+     * ```
+     */
+    getCollectionIdParent() {
+        if (this.collectionAncestorKeys.length === 0)
+            throw new ParseError(this.toString(), `Can't generate a parent ID because this ID has no ancestors.`);
+        return new CollectionId(this.primaryTypeId, this.rulesPackageId, ...this.collectionAncestorKeys);
+    }
+    /** @internal */
+    _getUnsafe(tree) {
+        const ancestorNode = super._getUnsafe(tree);
+        const [_rulesPackage, _ancestorKey, ...keys] = this.primaryPathKeys;
+        const ancestorNodes = [ancestorNode];
+        for (const key of keys) {
+            const currentNode = ancestorNodes.at(-1);
+            if (!(CollectionsKey in currentNode))
+                throw new Error(`Couldn't find collection <${key}> in <${currentNode._id}>`);
+            const nextNode = currentNode[CollectionsKey][key];
+            if (nextNode == null)
+                throw new Error(`Expected collection <${key}> in <${currentNode._id}>, but got ${String(nextNode)}`);
+            ancestorNodes.push(nextNode);
+        }
+        return ancestorNodes.at(-1);
+    }
+    static #getPositionId(path, node) {
+        const pathStr = path.join(PathKeySep);
+        return [node.type, pathStr].join(PrefixSep);
+    }
+    /** @internal */
+    static _recurseMatches(from, currentPath, nextPath, matches = new Map(), forEach, depth = 0) {
+        // no further traversal needed
+        if (nextPath.length === 0) {
+            // from.type is fine here since collections can't be embedded.
+            const positionId = CollectionId.#getPositionId(currentPath, from);
+            if (typeof forEach === 'function')
+                forEach(positionId, from);
+            return matches.set(positionId, from);
+        }
+        if (depth > COLLECTION_DEPTH_MAX) {
+            IdParser.logger.warn(`Exceeded max collection depth (${COLLECTION_DEPTH_MAX}) @ <${CollectionId.#getPositionId(currentPath, from)}>`);
+            return matches;
+        }
+        const [keyToMatch, ...tailKeys] = nextPath;
+        const childCollections = from[CollectionsKey];
+        if (childCollections == null)
+            return matches;
+        const childMatches = IdParser._getMatchesFrom(childCollections, keyToMatch);
+        for (const [childKey, child] of childMatches) {
+            const currentChildPath = [...currentPath, childKey];
+            if (TypeGuard.Globstar(keyToMatch))
+                // recurse through children without consuming the globstar
+                for (const [matchId, match] of CollectionId._recurseMatches(child, currentChildPath, nextPath, matches, forEach, depth + 1))
+                    matches.set(matchId, match);
+            // regular key + * matches
+            for (const [matchId, match] of CollectionId._recurseMatches(child, currentChildPath, tailKeys, matches, forEach, depth + 1))
+                matches.set(matchId, match);
+        }
+        return matches;
+    }
+    /** @internal */
+    _getMatchesUnsafe(tree, forEach) {
+        const pkgs = this._matchRulesPackages(tree);
+        // defer creating this until we need it
+        let matches = new Map();
+        const [_pkgMatchKey, matchKey, ...tailKeys] = this.primaryPathKeys;
+        for (const [rulesPackageId, pkg] of pkgs) {
+            const typeBranch = pkg[this.typeBranchKey];
+            if (typeBranch == null)
+                continue;
+            const collectionMatches = IdParser._getMatchesFrom(typeBranch, matchKey);
+            for (const [collectionKey, collection] of collectionMatches) {
+                const currentCollectionPath = [rulesPackageId, collectionKey];
+                if (TypeGuard.Globstar(rulesPackageId)) {
+                    // carry forward the rules package globstar if it's present
+                    matches = new Map([
+                        ...CollectionId._recurseMatches(collection, currentCollectionPath, [GlobstarString, matchKey, ...tailKeys], matches, forEach),
+                        ...CollectionId._recurseMatches(collection, currentCollectionPath, [matchKey, ...tailKeys], matches, forEach)
+                    ]);
+                }
+                else if (TypeGuard.Globstar(matchKey)) {
+                    // carry forward current key if it's a globstar
+                    matches = new Map([
+                        ...CollectionId._recurseMatches(collection, currentCollectionPath, [matchKey, ...tailKeys], matches, forEach),
+                        ...CollectionId._recurseMatches(collection, currentCollectionPath, tailKeys, matches, forEach)
+                    ]);
+                }
+                else
+                    matches = CollectionId._recurseMatches(collection, currentCollectionPath, tailKeys, matches, forEach);
+            }
+        }
+        return matches ?? new Map();
+    }
+}
+// @ts-expect-error Complex generic type constraints
+class EmbeddedId extends EmbeddingId {
+    #parent;
+    /**
+     * Returns the embedding ID parent of this ID.
+     */
+    getEmbeddingIdParent() {
+        return this.#parent;
+    }
+    _getUnsafe(tree) {
+        const parentNode = this.#parent.get(tree);
+        const propertyPath = TypeId.getEmbeddedPropertyKey(this.typeId);
+        // Support nested property paths like 'trigger.conditions'
+        const obj = getNestedProperty(parentNode, propertyPath);
+        return obj?.[this.pathSegments.at(-1)];
+    }
+    _getPathRegExpSource() {
+        let basePath = this.#parent._getPathRegExpSource();
+        const [_primaryPathSegment, ...secondaryPathSegments] = this.pathSegments;
+        for (const segment of secondaryPathSegments) {
+            basePath += `\\${TypeSep}`;
+            const keys = segment.split(PathKeySep);
+            for (const key of keys) {
+                switch (true) {
+                    // FIXME: this doesn't account for globstars because these are always single-element path segments right now
+                    case TypeGuard.AnyWildcard(key):
+                        basePath += Pattern.DictKeyElement.source;
+                        break;
+                    default:
+                        basePath += key;
+                        break;
+                }
+            }
+        }
+        return basePath;
+    }
+    constructor(parent, typeId, key) {
+        const options = {
+            typeIds: [...parent.typeIds, typeId],
+            pathSegments: [...parent.pathSegments, key.toString()]
+        };
+        super(options);
+        this.#parent = parent;
+    }
+}
+export { CollectionId, EmbeddedId, IdParser };
+//# sourceMappingURL=IdParser.js.map