@fgv/ts-res 5.0.1-9 → 5.0.2-0

package/dist/packlets/runtime/resource-tree/common.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+export {};
+//# sourceMappingURL=common.js.map

package/dist/packlets/runtime/resource-tree/index.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+export * from './common';
+export * from './resourceTreeChildren';
+export * from './resourceTreeChildrenValidator';
+export * from './readOnlyResourceTree';
+//# sourceMappingURL=index.js.map

package/dist/packlets/runtime/resource-tree/readOnlyResourceTree.js

@@ -0,0 +1,216 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { MessageAggregator, captureResult, mapResults, succeed } from '@fgv/ts-utils';
+import { Helpers } from '../../common';
+import { ReadOnlyResourceTreeChildren } from './resourceTreeChildren';
+// Type guards
+/**
+ * Type guard to determine if an init object represents a branch or root with children.
+ * @param init - The initialization object to test
+ * @returns True if the init object has children property
+ * @public
+ */
+export function isResourceTreeRootOrNodeInit(init) {
+    return 'children' in init;
+}
+/**
+ * Type guard to determine if an init object represents a leaf node with a resource.
+ * @param init - The initialization object to test
+ * @returns True if the init object has a resource but no children
+ * @public
+ */
+export function isResourceTreeLeafInit(init) {
+    return 'resource' in init && !('children' in init);
+}
+/**
+ * Implementation of a read-only resource tree leaf node that contains a resource value.
+ * Leaf nodes represent the actual resources in the tree and cannot have children.
+ * @public
+ */
+export class ReadOnlyResourceTreeLeaf {
+    get isRoot() {
+        return false;
+    }
+    get isBranch() {
+        return false;
+    }
+    get isLeaf() {
+        return true;
+    }
+    /**
+     * Creates a new leaf node. Use the static create method instead.
+     * @param name - The name of this node (last segment of the path)
+     * @param parentPath - The path to the parent node (undefined for root-level nodes)
+     * @param resource - The resource value stored in this leaf
+     */
+    constructor(name, parentPath, resource) {
+        this.name = name;
+        this.id = Helpers.joinResourceIds(parentPath, name).orThrow();
+        this.resource = resource;
+    }
+    /**
+     * Creates a new ReadOnlyResourceTreeLeaf instance.
+     * @param name - The name of this node (last segment of the path)
+     * @param parentPath - The path to the parent node (undefined for root-level nodes)
+     * @param resource - The resource value to store in this leaf
+     * @returns Result containing the new leaf node or failure if construction fails
+     */
+    static create(name, parentPath, resource) {
+        return captureResult(() => new ReadOnlyResourceTreeLeaf(name, parentPath, resource));
+    }
+}
+/**
+ * Implementation of a read-only resource tree branch node that contains child nodes.
+ * Branch nodes organize other nodes in a hierarchical structure and may optionally contain a resource value.
+ * @public
+ */
+export class ReadOnlyResourceTreeBranch {
+    get isRoot() {
+        return false;
+    }
+    get isBranch() {
+        return true;
+    }
+    get isLeaf() {
+        return false;
+    }
+    /**
+     * Creates a new branch node. Use the static create method instead.
+     * @param name - The name of this node (last segment of the path)
+     * @param parentPath - The path to the parent node (undefined for root-level nodes)
+     * @param init - Initialization data containing child nodes
+     */
+    constructor(name, parentPath, init) {
+        this.name = name;
+        this.id = Helpers.joinResourceIds(parentPath, name).orThrow();
+        const children = mapResults(Array.from(Object.entries(init.children)).map(([childName, childInit]) => {
+            if (isResourceTreeLeafInit(childInit)) {
+                return ReadOnlyResourceTreeLeaf.create(childName, this.id, childInit.resource);
+            }
+            return ReadOnlyResourceTreeBranch.create(childName, this.id, childInit);
+        })).orThrow();
+        this.children = new ReadOnlyResourceTreeChildren(this.id, children.map((c) => [c.name, c]));
+    }
+    /**
+     * Creates a new ReadOnlyResourceTreeBranch instance.
+     * @param childName - The name of this node (last segment of the path)
+     * @param path - The path to the parent node (undefined for root-level nodes)
+     * @param childInit - Initialization data containing child nodes
+     * @returns Result containing the new branch node or failure if construction fails
+     */
+    static create(childName, path, childInit) {
+        return captureResult(() => new ReadOnlyResourceTreeBranch(childName, path, childInit));
+    }
+}
+/**
+ * Implementation of a read-only resource tree root that organizes resources hierarchically.
+ * The root provides the entry point for tree navigation and resource access by ResourceId paths.
+ * @public
+ */
+export class ReadOnlyResourceTreeRoot {
+    get isRoot() {
+        return true;
+    }
+    get isBranch() {
+        return false;
+    }
+    get isLeaf() {
+        return false;
+    }
+    /**
+     * Creates a new root node. Use the static create method instead.
+     * @param init - Initialization data containing child nodes
+     */
+    constructor(init) {
+        const children = mapResults(Array.from(Object.entries(init.children)).map(([childName, childInit]) => {
+            if (isResourceTreeLeafInit(childInit)) {
+                return ReadOnlyResourceTreeLeaf.create(childName, undefined, childInit.resource);
+            }
+            return ReadOnlyResourceTreeBranch.create(childName, undefined, childInit);
+        })).orThrow();
+        this.children = new ReadOnlyResourceTreeChildren(undefined, children.map((c) => [c.name, c]));
+    }
+    /**
+     * Creates a new ReadOnlyResourceTreeRoot from either resources or initialization data.
+     * @param init - Either an array of [ResourceId, resource] pairs or tree initialization structure
+     * @returns Result containing the new root or failure if construction fails
+     */
+    static create(init) {
+        if (Array.isArray(init)) {
+            return ReadOnlyResourceTreeRoot.createResourceTreeInit(init).onSuccess((treeInit) => captureResult(() => new ReadOnlyResourceTreeRoot(treeInit)));
+        }
+        return captureResult(() => new ReadOnlyResourceTreeRoot(init));
+    }
+    /**
+     * Converts an array of resources into tree initialization data.
+     * Validates that resource paths do not conflict - if a path has child resources,
+     * it cannot itself be a resource (e.g., if 'app.messages.welcome' exists, then 'app' cannot be a resource).
+     * @param resources - Array of [ResourceId, resource] pairs to convert
+     * @returns Result containing the initialization structure or failure if validation fails
+     */
+    static createResourceTreeInit(resources) {
+        const errors = new MessageAggregator();
+        const root = { children: {} };
+        for (const [id, resource] of resources) {
+            Helpers.splitResourceId(id)
+                .onSuccess((pathComponents) => {
+                let currentNode = root;
+                const resourceName = pathComponents.pop();
+                for (const nodeName of pathComponents) {
+                    if (isResourceTreeRootOrNodeInit(currentNode)) {
+                        if (!(nodeName in currentNode.children)) {
+                            currentNode.children[nodeName] = { children: {} };
+                        }
+                        if (isResourceTreeLeafInit(currentNode.children[nodeName])) {
+                            errors.addMessage(`${id}: Expected a branch but found a leaf at ${nodeName}.`);
+                        }
+                        else {
+                            currentNode = currentNode.children[nodeName];
+                        }
+                    } /* c8 ignore next 4 - defense in depth, not reachable without chicanery */
+                    else if (isResourceTreeLeafInit(currentNode)) {
+                        errors.addMessage(`${id}: Expected a branch but found a leaf.`);
+                        break;
+                    } /* c8 ignore next 3 - defense in depth, not reachable without chicanery */
+                    else {
+                        errors.addMessage(`${id}: Unexpected structure in resource tree`);
+                    }
+                }
+                if (isResourceTreeRootOrNodeInit(currentNode)) {
+                    if (resourceName in currentNode.children) {
+                        errors.addMessage(`${id}: Duplicate resource at path.`);
+                    }
+                    else {
+                        currentNode.children[resourceName] = { resource };
+                    } /* c8 ignore next 3 - defense in depth, not reachable without chicanery */
+                }
+                else {
+                    errors.addMessage(`${id}: Expected a branch but found a leaf.`);
+                }
+                return succeed(currentNode.children[resourceName]);
+            })
+                .aggregateError(errors);
+        }
+        return errors.returnOrReport(succeed(root));
+    }
+}
+//# sourceMappingURL=readOnlyResourceTree.js.map

package/dist/packlets/runtime/resource-tree/resourceTreeChildren.js

@@ -0,0 +1,97 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { ResultMap, fail, succeed } from '@fgv/ts-utils';
+import { Helpers } from '../../common';
+import { ResourceTreeChildrenValidator } from './resourceTreeChildrenValidator';
+/**
+ * Implementation of a result-based resource tree that provides hierarchical access to resources.
+ * Extends ResultMap to provide collection-like access while adding tree-specific navigation methods.
+ * @public
+ */
+export class ReadOnlyResourceTreeChildren extends ResultMap {
+    /**
+     * Creates a new ReadOnlyResourceTreeChildren instance.
+     * @param path - The path to this tree node (undefined for root)
+     * @param entries - Array of [name, node] tuples to populate the tree
+     */
+    constructor(path, entries) {
+        super(entries);
+        this.path = path;
+        this.validating = new ResourceTreeChildrenValidator(this);
+    }
+    getResource(name) {
+        return this.get(name).onSuccess((node) => {
+            if (node.isLeaf) {
+                return succeed(node).withDetail('success');
+            }
+            /* c8 ignore next 3 - functional code tested but coverage intermittently missed */
+            return fail(`${name}: not a resource${this.path ? ` in ${this.path}` : ''}.`).withDetail('failure');
+        });
+    }
+    getBranch(name) {
+        return this.get(name).onSuccess((node) => {
+            if (node.isBranch) {
+                return succeed(node).withDetail('success');
+            }
+            /* c8 ignore next 3 - functional code tested but coverage intermittently missed */
+            return fail(`${name}: not a branch${this.path ? ` in ${this.path}` : ''}.`).withDetail('failure');
+        });
+    }
+    getById(id) {
+        return Helpers.splitResourceId(id).onSuccess((names) => {
+            let name = names.shift();
+            if (name !== undefined) {
+                let node = this.get(name).orDefault();
+                while (node) {
+                    name = names.shift();
+                    if (name === undefined) {
+                        return succeed(node);
+                    }
+                    if (node.isLeaf) {
+                        /* c8 ignore next 1 - defense in depth */
+                        return fail(`${id}: resource not found${this.path ? ` in ${this.path}` : ''}.`);
+                    }
+                    node = node.children.get(name).orDefault();
+                }
+            }
+            return fail(`${id}: resource not found${this.path ? ` in ${this.path}` : ''}.`);
+        });
+    }
+    getResourceById(id) {
+        return this.getById(id).onSuccess((node) => {
+            if (node.isLeaf) {
+                return succeed(node).withDetail('success');
+            }
+            return fail(`${id}: not a resource${this.path ? ` in ${this.path}` : ''}.`).withDetail('failure');
+        });
+    }
+    getBranchById(id) {
+        return this.getById(id).onSuccess((node) => {
+            if (node.isBranch) {
+                return succeed(node).withDetail('success');
+            }
+            /* c8 ignore next 3 - functional code tested but coverage intermittently missed */
+            return fail(`${id}: not a branch${this.path ? ` in ${this.path}` : ''}.`).withDetail('failure');
+        });
+    }
+}
+//# sourceMappingURL=resourceTreeChildren.js.map

package/dist/packlets/runtime/resource-tree/resourceTreeChildrenValidator.js

@@ -0,0 +1,161 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { Validate } from '../../common';
+import { failWithDetail } from '@fgv/ts-utils';
+/**
+ * A validator wrapper for resource tree children that validates string inputs before
+ * delegating to the underlying tree children collection.
+ *
+ * This class implements {@link Runtime.ResourceTree.IReadOnlyValidatingResourceTreeChildren | IReadOnlyValidatingResourceTreeChildren}
+ * by wrapping an {@link Runtime.ResourceTree.IReadOnlyResourceTreeChildren | IReadOnlyResourceTreeChildren} instance and
+ * providing string-based access to all tree operations. All string inputs are validated using the library's
+ * validation utilities before being passed to the underlying collection.
+ *
+ * The validator acts as a bridge between string-based external APIs and the
+ * strongly-typed internal tree operations, ensuring type safety and consistent
+ * error handling throughout the resource tree navigation.
+ *
+ * @public
+ */
+export class ResourceTreeChildrenValidator {
+    /**
+     * Creates a new validator wrapper for resource tree children.
+     * @param inner - The underlying resource tree children collection to wrap with validation
+     */
+    constructor(inner) {
+        this._inner = inner;
+    }
+    /**
+     * Gets a tree node by its string ResourceId path, validating the input.
+     * @param id - The string ResourceId path to validate and look up
+     * @returns Result containing the node if found, or failure if validation fails or not found
+     */
+    getById(id) {
+        return Validate.toResourceId(id).onSuccess((resourceId) => {
+            return this._inner.getById(resourceId);
+        });
+    }
+    /**
+     * Gets a resource node by its string name (single component), validating the input.
+     * @param name - The string ResourceName to validate and look up
+     * @returns Result containing the node if it's a resource, or failure if validation fails or not found
+     */
+    getResource(name) {
+        return Validate.toResourceName(name).onSuccess((resourceName) => {
+            return this._inner.getResource(resourceName);
+        });
+    }
+    /**
+     * Gets a branch node by its string name (single component), validating the input.
+     * @param name - The string ResourceName to validate and look up
+     * @returns Result containing the node if it's a branch, or failure if validation fails or not found
+     */
+    getBranch(name) {
+        return Validate.toResourceName(name).onSuccess((resourceName) => {
+            return this._inner.getBranch(resourceName);
+        });
+    }
+    /**
+     * Gets a resource leaf node by its string ResourceId path, validating the input.
+     * @param id - The string ResourceId path to validate and look up
+     * @returns Result containing the leaf if found and is a resource, or failure otherwise
+     */
+    getResourceById(id) {
+        return Validate.toResourceId(id).onSuccess((resourceId) => {
+            return this._inner.getResourceById(resourceId);
+        });
+    }
+    /**
+     * Gets a branch node by its string ResourceId path, validating the input.
+     * @param id - The string ResourceId path to validate and look up
+     * @returns Result containing the branch if found and has children, or failure otherwise
+     */
+    getBranchById(id) {
+        return Validate.toResourceId(id).onSuccess((resourceId) => {
+            return this._inner.getBranchById(resourceId);
+        });
+    }
+    /**
+     * The number of direct child nodes in this collection.
+     */
+    get size() {
+        return this._inner.size;
+    }
+    /**
+     * Returns an iterator of [ResourceName, node] pairs for all child nodes.
+     * @returns Map iterator for all child nodes
+     */
+    entries() {
+        return this._inner.entries();
+    }
+    /**
+     * Executes a callback function for each child node in the collection.
+     * @param cb - The callback function to execute for each child node
+     * @param arg - Optional argument to pass to the callback
+     */
+    forEach(cb, arg) {
+        for (const [key, value] of this._inner.entries()) {
+            cb(value, key, this, arg);
+        }
+    }
+    /**
+     * Gets a child node by its string key with detailed error information.
+     * @param key - The string key to look up
+     * @returns DetailedResult containing the node if found, or failure with details
+     */
+    get(key) {
+        if (Validate.isValidResourceName(key)) {
+            return this._inner.get(key);
+        }
+        return failWithDetail(`${key}: invalid resource name.`, 'invalid-key');
+    }
+    /**
+     * Checks if a child node exists at the given string key.
+     * @param key - The string key to check
+     * @returns True if a child node exists at the key, false otherwise
+     */
+    has(key) {
+        return this._inner.has(key);
+    }
+    /**
+     * Returns an iterator of ResourceName keys for all child nodes.
+     * @returns Map iterator for all child node keys
+     */
+    keys() {
+        return this._inner.keys();
+    }
+    /**
+     * Returns an iterator of child node values.
+     * @returns Map iterator for all child node values
+     */
+    values() {
+        return this._inner.values();
+    }
+    /**
+     * Returns an iterator for [ResourceName, node] pairs, enabling for...of iteration.
+     * @returns Iterable iterator for all child nodes
+     */
+    [Symbol.iterator]() {
+        return this._inner[Symbol.iterator]();
+    }
+}
+//# sourceMappingURL=resourceTreeChildrenValidator.js.map