@fgv/ts-utils 5.0.2 → 5.1.0-0

package/lib/packlets/collections/aggregatedResultMap.js

@@ -0,0 +1,728 @@
+"use strict";
+/*
+ * Copyright (c) 2026 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AggregatedResultMap = exports.AggregatedResultMapBase = exports.AggregatedResultMapValidator = void 0;
+const base_1 = require("../base");
+const conversion_1 = require("../conversion");
+const validation_1 = require("../validation");
+const keyValueConverters_1 = require("./keyValueConverters");
+const validatingResultMap_1 = require("./validatingResultMap");
+/**
+ * A validator for weakly-typed access to an {@link AggregatedResultMap | aggregated result map}.
+ * @public
+ */
+class AggregatedResultMapValidator {
+    /**
+     * Constructs a new {@link AggregatedResultMapValidator | aggregated result map validator}.
+     * @param map - The {@link AggregatedResultMap | aggregated result map} being validated.
+     * @param converters - The key-value converters for weakly-typed access.
+     */
+    constructor(map, converters) {
+        this._map = map;
+        this.converters = converters;
+    }
+    /** {@inheritDoc Collections.ResultMapValidator.map} */
+    get map() {
+        return this._map;
+    }
+    /** {@inheritDoc Collections.ResultMapValidator.get} */
+    get(key) {
+        return this.converters.convertKey(key).onSuccess((k) => {
+            return this._map.get(k);
+        });
+    }
+    /** {@inheritDoc Collections.ResultMapValidator.has} */
+    has(key) {
+        const result = this.converters.convertKey(key);
+        if (result.isFailure()) {
+            return false;
+        }
+        return this._map.has(result.value);
+    }
+    /** {@inheritDoc Collections.ResultMapValidator.add} */
+    add(key, value) {
+        return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {
+            return this._map.add(vk, vv);
+        });
+    }
+    /** {@inheritDoc Collections.ResultMapValidator.set} */
+    set(key, value) {
+        return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {
+            return this._map.set(vk, vv);
+        });
+    }
+    /** {@inheritDoc Collections.ResultMapValidator.update} */
+    update(key, value) {
+        return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {
+            return this._map.update(vk, vv);
+        });
+    }
+    /** {@inheritDoc Collections.ResultMapValidator.delete} */
+    delete(key) {
+        return this.converters.convertKey(key).onSuccess((k) => {
+            return this._map.delete(k);
+        });
+    }
+}
+exports.AggregatedResultMapValidator = AggregatedResultMapValidator;
+/**
+ * Type guard to check if an {@link AggregatedResultMapEntry | aggregated result map entry} is mutable.
+ */
+function isMutableEntry(entry) {
+    return entry.isMutable === true;
+}
+/**
+ * Base class for an aggregated result map that wraps a collection of {@link ValidatingResultMap} instances,
+ * keyed by collection ID. Items are accessed via composite IDs that combine the collection ID
+ * and item ID with a delimiter.
+ * @remarks Consumers should inherit from this class or use {@link AggregatedResultMap | AggregatedResultMap}
+ * for fully generic.
+ * @public
+ */
+class AggregatedResultMapBase {
+    /**
+     * Protected constructor for derived classes.
+     * Use the {@link AggregatedResultMap.create | create static method} for safe construction with error handling.
+     * @param params - {@link IAggregatedResultMapConstructorParams | Parameters} for constructing the map.
+     * @throws If initialization fails (e.g., invalid collections).
+     * @public
+     */
+    constructor(params) {
+        var _a, _b, _c;
+        this._compositeIdValidator =
+            (_a = params.compositeIdValidator) !== null && _a !== void 0 ? _a : AggregatedResultMapBase._compositeIdValidator(params);
+        this._collectionIdConverter = params.collectionIdConverter;
+        this._itemIdConverter = params.itemIdConverter;
+        this._itemConverter = params.itemConverter;
+        this._metadataConverter = params.metadataConverter;
+        this._delimiter = (_b = params.separator) !== null && _b !== void 0 ? _b : '.';
+        // Build child key-value converters for item ID/value pairs
+        this._childKvConverters = new keyValueConverters_1.KeyValueConverters({
+            key: params.itemIdConverter,
+            value: params.itemConverter
+        });
+        // Build composite ID converter for parsing composite IDs
+        this._compositeIdConverter = conversion_1.Converters.compositeId(params.collectionIdConverter, this._delimiter, params.itemIdConverter);
+        // Build key-value converters for composite ID/item pairs
+        this._kvConverters = new keyValueConverters_1.KeyValueConverters({
+            key: this._compositeIdValidator,
+            value: params.itemConverter
+        });
+        // Build entry converter for collection entries
+        const entryConverter = AggregatedResultMapBase._entryConverter(params.collectionIdConverter, this._childKvConverters, params.metadataConverter);
+        // Build key-value converters for the collections map
+        this._collectionKvConverters = new keyValueConverters_1.KeyValueConverters({
+            key: params.collectionIdConverter,
+            value: entryConverter
+        });
+        // Convert all input collections to [id, entry] pairs for ValidatingResultMap
+        const initCollections = (_c = params.collections) !== null && _c !== void 0 ? _c : [];
+        const initEntries = initCollections.map((entry) => {
+            return [entry.id, entry];
+        });
+        // Build the inner ValidatingResultMap - throws on error
+        this._collections = new validatingResultMap_1.ValidatingResultMap({
+            converters: this._collectionKvConverters,
+            entries: initEntries
+        });
+        // Build the validator
+        this._validating = new AggregatedResultMapValidator(this, this._kvConverters);
+    }
+    // ==================== IReadOnlyValidatingResultMap implementation ====================
+    /**
+     * A validator for weakly-typed access to the map.
+     */
+    get validating() {
+        return this._validating;
+    }
+    /**
+     * The total number of items across all collections.
+     */
+    get size() {
+        let total = 0;
+        for (const entry of Array.from(this._collections.values())) {
+            total += entry.items.size;
+        }
+        return total;
+    }
+    /**
+     * Gets an item by its composite ID.
+     * @param key - The composite ID of the item.
+     * @returns `Success` with the item if found, `Failure` otherwise.
+     */
+    get(key) {
+        return this._splitAndLookup(key).onSuccess(({ entry, itemId }) => {
+            return entry.items.get(itemId);
+        });
+    }
+    /**
+     * Checks if an item exists by its composite ID.
+     * @param key - The composite ID of the item.
+     * @returns `true` if the item exists, `false` otherwise.
+     */
+    has(key) {
+        const result = this._splitAndLookup(key);
+        if (result.isFailure()) {
+            return false;
+        }
+        return result.value.entry.items.has(result.value.itemId);
+    }
+    /**
+     * Iterates over all entries in all collections.
+     */
+    *entries() {
+        for (const collectionEntry of Array.from(this._collections.values())) {
+            for (const [itemId, item] of Array.from(collectionEntry.items.entries())) {
+                // Validate the composite ID through the converter
+                const compositeId = this._compositeIdValidator
+                    .convert(`${collectionEntry.id}${this._delimiter}${itemId}`)
+                    .orThrow();
+                yield [compositeId, item];
+            }
+        }
+    }
+    /**
+     * Iterates over all composite keys.
+     */
+    *keys() {
+        for (const [key] of Array.from(this.entries())) {
+            yield key;
+        }
+    }
+    /**
+     * Iterates over all values.
+     */
+    *values() {
+        for (const collectionEntry of Array.from(this._collections.values())) {
+            for (const value of Array.from(collectionEntry.items.values())) {
+                yield value;
+            }
+        }
+    }
+    /**
+     * Calls a callback for each entry.
+     * @param cb - The callback to call.
+     * @param thisArg - Optional `this` argument for the callback.
+     */
+    forEach(cb, thisArg) {
+        for (const [key, value] of Array.from(this.entries())) {
+            cb.call(thisArg, value, key, this);
+        }
+    }
+    /**
+     * Gets an iterator over the map entries.
+     */
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+    // ==================== Mutating methods ====================
+    /**
+     * Sets an item by its composite ID. Creates the collection if it doesn't exist and is mutable.
+     * @param key - The composite ID of the item.
+     * @param value - The value to set.
+     * @returns `Success` with the value if set, `Failure` otherwise.
+     */
+    set(key, value) {
+        return this._splitCompositeId(key).onSuccess(({ collectionId, itemId }) => {
+            return this._getOrCreateMutableCollection(collectionId).onSuccess((collection) => {
+                return collection.set(itemId, value);
+            });
+        });
+    }
+    /**
+     * Adds an item by its composite ID. Fails if the item already exists.
+     * @param key - The composite ID of the item.
+     * @param value - The value to add.
+     * @returns `Success` with the value if added, `Failure` otherwise.
+     */
+    add(key, value) {
+        return this._splitCompositeId(key).onSuccess(({ collectionId, itemId }) => {
+            return this._getOrCreateMutableCollection(collectionId).onSuccess((collection) => {
+                return collection.add(itemId, value);
+            });
+        });
+    }
+    /**
+     * Updates an existing item by its composite ID. Fails if the item doesn't exist.
+     * @param key - The composite ID of the item.
+     * @param value - The new value.
+     * @returns `Success` with the value if updated, `Failure` otherwise.
+     */
+    update(key, value) {
+        return this._splitAndLookupMutable(key).onSuccess(({ entry, itemId }) => {
+            return entry.items.update(itemId, value);
+        });
+    }
+    /**
+     * Deletes an item by its composite ID.
+     * @param key - The composite ID of the item.
+     * @returns `Success` with the deleted value, `Failure` otherwise.
+     */
+    delete(key) {
+        return this._splitAndLookupMutable(key).onSuccess(({ entry, itemId }) => {
+            return entry.items.delete(itemId);
+        });
+    }
+    getOrAdd(key, valueOrFactory) {
+        return this._splitCompositeId(key).onSuccess(({ collectionId, itemId }) => {
+            return this._getOrCreateMutableCollection(collectionId).onSuccess((collection) => {
+                // Use type guard to check if valueOrFactory is a factory function
+                if (this._isFactory(valueOrFactory)) {
+                    return collection.getOrAdd(itemId, () => valueOrFactory(key));
+                }
+                return collection.getOrAdd(itemId, valueOrFactory);
+            });
+        });
+    }
+    /**
+     * Clears all items from all mutable collections.
+     * Immutable collections are not affected.
+     */
+    clear() {
+        for (const entry of Array.from(this._collections.values())) {
+            if (isMutableEntry(entry)) {
+                entry.items.clear();
+            }
+        }
+    }
+    /**
+     * Returns a read-only view of this map.
+     */
+    toReadOnly() {
+        return this;
+    }
+    // ==================== Convenience methods for split IDs ====================
+    /**
+     * Composes a collection ID and item ID into a composite ID.
+     * @param collectionId - The collection ID.
+     * @param itemId - The item ID.
+     * @returns `Success` with the composite ID if valid, `Failure` otherwise.
+     */
+    composeId(collectionId, itemId) {
+        const rawId = `${collectionId}${this._delimiter}${itemId}`;
+        return this._compositeIdValidator.convert(rawId);
+    }
+    /**
+     * Adds an item using separate collection and item IDs.
+     * @param collectionId - The collection ID.
+     * @param itemId - The item ID.
+     * @param value - The value to add.
+     * @returns `Success` with the composite ID if added, `Failure` otherwise.
+     */
+    addToCollection(collectionId, itemId, value) {
+        return this._getOrCreateMutableCollection(collectionId).onSuccess((collection) => {
+            return collection.add(itemId, value).onSuccess(() => {
+                return this.composeId(collectionId, itemId).withDetail('invalid-key', 'added');
+            });
+        });
+    }
+    /**
+     * Sets an item using separate collection and item IDs.
+     * @param collectionId - The collection ID.
+     * @param itemId - The item ID.
+     * @param value - The value to set.
+     * @returns `Success` with the composite ID if set, `Failure` otherwise.
+     */
+    setInCollection(collectionId, itemId, value) {
+        return this._getOrCreateMutableCollection(collectionId).onSuccess((collection) => {
+            return collection.set(itemId, value).onSuccess((_, detail) => {
+                return this.composeId(collectionId, itemId).withDetail('invalid-key', detail);
+            });
+        });
+    }
+    /**
+     * Updates an item using separate collection and item IDs.
+     * @param collectionId - The collection ID.
+     * @param itemId - The item ID.
+     * @param value - The new value.
+     * @returns `Success` with the composite ID if updated, `Failure` otherwise.
+     */
+    updateInCollection(collectionId, itemId, value) {
+        return this._getMutableCollection(collectionId).onSuccess((collection) => {
+            return collection.update(itemId, value).onSuccess(() => {
+                return this.composeId(collectionId, itemId).withDetail('invalid-key', 'updated');
+            });
+        });
+    }
+    /**
+     * Deletes an item using separate collection and item IDs.
+     * @param collectionId - The collection ID.
+     * @param itemId - The item ID.
+     * @returns `Success` with the composite ID if deleted, `Failure` otherwise.
+     */
+    deleteFromCollection(collectionId, itemId) {
+        return this._getMutableCollection(collectionId).onSuccess((collection) => {
+            return collection.delete(itemId).onSuccess(() => {
+                return this.composeId(collectionId, itemId).withDetail('invalid-key', 'deleted');
+            });
+        });
+    }
+    // ==================== Collection-level methods ====================
+    /**
+     * Provides read-only access to the underlying collections map.
+     * Use `collections.has(id)` and `collections.get(id)` to check existence and retrieve collections.
+     */
+    get collections() {
+        return this._collections;
+    }
+    /**
+     * The number of collections.
+     */
+    get collectionCount() {
+        return this._collections.size;
+    }
+    /**
+     * Gets the metadata for a specific collection.
+     * @param collectionId - The collection ID.
+     * @returns `Success` with the metadata if found, `Failure` otherwise.
+     */
+    getCollectionMetadata(collectionId) {
+        return this._collections.get(collectionId).asResult.onSuccess((entry) => {
+            return (0, base_1.succeed)(entry.metadata);
+        });
+    }
+    /**
+     * Sets the metadata for a mutable collection.
+     * @param collectionId - The collection ID.
+     * @param metadata - The metadata to set.
+     * @returns `Success` if set, `Failure` otherwise.
+     */
+    setCollectionMetadata(collectionId, metadata) {
+        return this._collections.get(collectionId).asResult.onSuccess((entry) => {
+            if (!isMutableEntry(entry)) {
+                return (0, base_1.fail)(`Cannot modify metadata of immutable collection '${collectionId}'`);
+            }
+            entry.metadata = metadata;
+            return (0, base_1.succeed)(metadata);
+        });
+    }
+    /**
+     * Adds a new collection from a pre-built entry object.
+     * @param entry - The collection entry to add (JSON with items/entries, or pre-instantiated).
+     * @returns `Success` with the entry if added, `Failure` otherwise.
+     */
+    addCollectionEntry(entry) {
+        return AggregatedResultMapBase._entryConverter(this._collectionIdConverter, this._childKvConverters, this._metadataConverter)
+            .convert(entry)
+            .withFailureDetail('invalid-value')
+            .onSuccess((c) => this._collections.add(c.id, c));
+    }
+    /**
+     * Adds a new collection with the specified ID and optional initial entries.
+     * @param collectionId - The collection ID as a string (will be validated).
+     * @param items - Optional initial entries for the collection.
+     * @param options - Optional settings (isImmutable defaults to false).
+     * @returns `Success` with the validated collection ID if added, `Failure` otherwise.
+     */
+    addCollectionWithItems(collectionId, items, options) {
+        const isMutable = (options === null || options === void 0 ? void 0 : options.isImmutable) !== true;
+        const entries = items ? Array.from(items) : [];
+        return this._collectionIdConverter
+            .convert(collectionId)
+            .onSuccess((id) => this.addCollectionEntry({ isMutable, id, entries, metadata: options === null || options === void 0 ? void 0 : options.metadata }).asResult.onSuccess(() => base_1.Success.with(id)));
+    }
+    // ==================== Protected helpers ====================
+    /**
+     * Deletes a collection from the internal collections map.
+     * This is a protected method for use by derived classes that need to implement
+     * collection deletion functionality.
+     *
+     * @param collectionId - The collection ID to delete.
+     * @returns `Success` with the deleted entry if found, `Failure` otherwise.
+     * @remarks
+     * - Does NOT check if the collection is mutable - callers should validate this first.
+     * - Use `collections.get(id)` to check if a collection exists and its mutability before calling.
+     */
+    _deleteCollection(collectionId) {
+        // ValidatingResultMap extends ResultMap which has delete method
+        return this._collections.delete(collectionId);
+    }
+    // ==================== Private helpers ====================
+    /**
+     * Type guard to check if a value is a factory function.
+     */
+    _isFactory(valueOrFactory) {
+        return typeof valueOrFactory === 'function';
+    }
+    _splitCompositeId(key) {
+        return this._compositeIdConverter.convert(key).withDetail('invalid-key', 'success');
+    }
+    _splitAndLookup(key) {
+        return this._splitCompositeId(key).onSuccess(({ collectionId, itemId }) => {
+            return this._collections.get(collectionId).onSuccess((entry) => {
+                return (0, base_1.succeedWithDetail)({ entry, itemId }, 'success');
+            });
+        });
+    }
+    _splitAndLookupMutable(key) {
+        return this._splitAndLookup(key).onSuccess(({ entry, itemId }) => {
+            if (!isMutableEntry(entry)) {
+                return (0, base_1.failWithDetail)(`Cannot modify immutable collection '${entry.id}'`, 'failure');
+            }
+            return (0, base_1.succeedWithDetail)({ entry, itemId }, 'success');
+        });
+    }
+    /**
+     * Gets an existing mutable collection by ID.
+     * Returns failure if the collection doesn't exist or is immutable.
+     */
+    _getMutableCollection(collectionId) {
+        return this._collections.get(collectionId).onSuccess((entry) => {
+            if (!isMutableEntry(entry)) {
+                return (0, base_1.failWithDetail)(`Cannot modify immutable collection '${collectionId}'`, 'failure');
+            }
+            return (0, base_1.succeedWithDetail)(entry.items, 'exists');
+        });
+    }
+    /**
+     * Gets an existing mutable collection or creates a new one.
+     */
+    _getOrCreateMutableCollection(collectionId) {
+        const existing = this._collections.get(collectionId);
+        if (existing.isSuccess()) {
+            if (!isMutableEntry(existing.value)) {
+                return (0, base_1.failWithDetail)(`Cannot modify immutable collection '${collectionId}'`, 'failure');
+            }
+            return (0, base_1.succeedWithDetail)(existing.value.items, 'exists');
+        }
+        // Create a new mutable collection
+        const newItems = new validatingResultMap_1.ValidatingResultMap({
+            converters: this._childKvConverters
+        });
+        const newEntry = {
+            isMutable: true,
+            id: collectionId,
+            items: newItems
+        };
+        return this._collections.add(collectionId, newEntry).onSuccess(() => {
+            return (0, base_1.succeedWithDetail)(newItems, 'added');
+        });
+    }
+    // ==================== Static converter factories ====================
+    /**
+     * Constructs a composite id validator using other converters/validators and separator supplied in params.
+     * @param params - Constructor params.
+     * @returns The composite ID validator.
+     */
+    static _compositeIdValidator(params) {
+        var _a;
+        return validation_1.Validators.compositeId({
+            collectionId: conversion_1.Converters.asValidator(params.collectionIdConverter),
+            separator: (_a = params.separator) !== null && _a !== void 0 ? _a : '.',
+            itemId: conversion_1.Converters.asValidator(params.itemIdConverter)
+        });
+    }
+    /**
+     * Converts metadata from source, failing fast if metadata is present but no converter is configured.
+     * @param sourceMetadata - The metadata from the source (may be undefined).
+     * @param metadataConverter - Optional converter for metadata.
+     * @returns Success with converted metadata (or undefined), or Failure if metadata is present but disallowed.
+     */
+    static _convertMetadata(sourceMetadata, metadataConverter) {
+        if (sourceMetadata === undefined) {
+            return (0, base_1.succeed)(undefined);
+        }
+        if (!metadataConverter) {
+            return (0, base_1.fail)('metadata is not allowed when no metadataConverter is configured');
+        }
+        return metadataConverter.convert(sourceMetadata);
+    }
+    /**
+     * Extracts metadata from a source object if present.
+     */
+    static _extractSourceMetadata(from) {
+        return typeof from === 'object' && from !== null && 'metadata' in from ? from.metadata : undefined;
+    }
+    /**
+     * Creates a converter for pre-instantiated mutable entries.
+     * These are entries that already have a ValidatingResultMap as their items property.
+     */
+    static _instantiatedMutableConverter(collectionIdConverter, metadataConverter) {
+        const baseConverter = conversion_1.Converters.strictObject({
+            isMutable: conversion_1.Converters.literal(true),
+            id: collectionIdConverter,
+            items: conversion_1.Converters.isA('ValidatingResultMap', (t) => t instanceof validatingResultMap_1.ValidatingResultMap)
+        });
+        return conversion_1.Converters.generic((from) => {
+            return baseConverter.convert(from).onSuccess((base) => {
+                const sourceMetadata = AggregatedResultMapBase._extractSourceMetadata(from);
+                return AggregatedResultMapBase._convertMetadata(sourceMetadata, metadataConverter).onSuccess((metadata) => {
+                    const entry = {
+                        isMutable: true,
+                        id: base.id,
+                        items: base.items,
+                        metadata
+                    };
+                    return (0, base_1.succeed)(entry);
+                });
+            });
+        });
+    }
+    /**
+     * Creates a converter for pre-instantiated read-only entries.
+     * These are entries that already have an IReadOnlyValidatingResultMap as their items property.
+     */
+    static _instantiatedReadonlyConverter(collectionIdConverter, metadataConverter) {
+        const baseConverter = conversion_1.Converters.strictObject({
+            isMutable: conversion_1.Converters.literal(false),
+            id: collectionIdConverter,
+            items: conversion_1.Converters.isA('IReadOnlyValidatingResultMap', (t) => t instanceof validatingResultMap_1.ValidatingResultMap)
+        });
+        return conversion_1.Converters.generic((from) => {
+            return baseConverter.convert(from).onSuccess((base) => {
+                const sourceMetadata = AggregatedResultMapBase._extractSourceMetadata(from);
+                return AggregatedResultMapBase._convertMetadata(sourceMetadata, metadataConverter).onSuccess((metadata) => {
+                    const entry = {
+                        isMutable: false,
+                        id: base.id,
+                        items: base.items,
+                        metadata
+                    };
+                    return (0, base_1.succeed)(entry);
+                });
+            });
+        });
+    }
+    /**
+     * Creates a converter for JSON entries with an entries array.
+     * Converts the entries array to a ValidatingResultMap.
+     */
+    static _jsonWithEntriesConverter(collectionIdConverter, childKvConverters, metadataConverter) {
+        const entriesArrayConverter = conversion_1.Converters.isA('entries array', (t) => Array.isArray(t) && t.every((item) => Array.isArray(item) && item.length === 2));
+        const baseConverter = conversion_1.Converters.object({
+            isMutable: conversion_1.Converters.boolean,
+            id: collectionIdConverter,
+            entries: entriesArrayConverter
+        });
+        return conversion_1.Converters.generic((from) => {
+            return baseConverter.convert(from).onSuccess((json) => {
+                const sourceMetadata = AggregatedResultMapBase._extractSourceMetadata(from);
+                return childKvConverters.convertEntries(json.entries).onSuccess((convertedEntries) => {
+                    const items = new validatingResultMap_1.ValidatingResultMap({
+                        converters: childKvConverters,
+                        entries: convertedEntries
+                    });
+                    return AggregatedResultMapBase._convertMetadata(sourceMetadata, metadataConverter).onSuccess((metadata) => {
+                        if (json.isMutable) {
+                            return (0, base_1.succeed)({
+                                isMutable: true,
+                                id: json.id,
+                                items,
+                                metadata
+                            });
+                        }
+                        return (0, base_1.succeed)({
+                            isMutable: false,
+                            id: json.id,
+                            items: items.toReadOnly(),
+                            metadata
+                        });
+                    });
+                });
+            });
+        });
+    }
+    /**
+     * Creates a converter for JSON entries with an items object.
+     * Converts the items object to a ValidatingResultMap.
+     */
+    static _jsonWithItemsConverter(collectionIdConverter, childKvConverters, metadataConverter) {
+        const baseConverter = conversion_1.Converters.object({
+            isMutable: conversion_1.Converters.boolean,
+            id: collectionIdConverter,
+            items: conversion_1.Converters.generic((from) => {
+                if (typeof from === 'object' && from !== null && !Array.isArray(from)) {
+                    return (0, base_1.succeed)(from);
+                }
+                return (0, base_1.fail)('expected an object');
+            })
+        });
+        return conversion_1.Converters.generic((from) => {
+            return baseConverter.convert(from).onSuccess((json) => {
+                const sourceMetadata = AggregatedResultMapBase._extractSourceMetadata(from);
+                const entries = Object.entries(json.items);
+                return childKvConverters.convertEntries(entries).onSuccess((convertedEntries) => {
+                    const items = new validatingResultMap_1.ValidatingResultMap({
+                        converters: childKvConverters,
+                        entries: convertedEntries
+                    });
+                    return AggregatedResultMapBase._convertMetadata(sourceMetadata, metadataConverter).onSuccess((metadata) => {
+                        if (json.isMutable) {
+                            return (0, base_1.succeed)({
+                                isMutable: true,
+                                id: json.id,
+                                items,
+                                metadata
+                            });
+                        }
+                        return (0, base_1.succeed)({
+                            isMutable: false,
+                            id: json.id,
+                            items: items.toReadOnly(),
+                            metadata
+                        });
+                    });
+                });
+            });
+        });
+    }
+    /**
+     * Creates a unified entry converter that handles all entry formats.
+     * Tries each format in order: instantiated mutable, instantiated readonly,
+     * JSON with entries array, JSON with items object.
+     */
+    static _entryConverter(collectionIdConverter, childKvConverters, metadataConverter) {
+        return conversion_1.Converters.oneOf([
+            AggregatedResultMapBase._instantiatedMutableConverter(collectionIdConverter, metadataConverter),
+            AggregatedResultMapBase._instantiatedReadonlyConverter(collectionIdConverter, metadataConverter),
+            AggregatedResultMapBase._jsonWithEntriesConverter(collectionIdConverter, childKvConverters, metadataConverter),
+            AggregatedResultMapBase._jsonWithItemsConverter(collectionIdConverter, childKvConverters, metadataConverter)
+        ]);
+    }
+}
+exports.AggregatedResultMapBase = AggregatedResultMapBase;
+/**
+ * An aggregated result map that wraps a collection of {@link ValidatingResultMap | ValidatingResultMap} instances,
+ * keyed by collection ID. Items are accessed via composite IDs that combine the collection ID
+ * and item ID with a delimiter.
+ * @public
+ */
+class AggregatedResultMap extends AggregatedResultMapBase {
+    /**
+     * Constructs a new {@link AggregatedResultMap | AggregatedResultMap}.
+     * @param params -
+     */
+    constructor(params) {
+        super(params);
+    }
+    /**
+     * Creates a new {@link AggregatedResultMap | AggregatedResultMap}.
+     * @param params - Parameters for constructing the map.
+     * @returns `Success` with the new map if successful, `Failure` otherwise.
+     */
+    static create(params) {
+        return (0, base_1.captureResult)(() => new AggregatedResultMap(params));
+    }
+}
+exports.AggregatedResultMap = AggregatedResultMap;
+//# sourceMappingURL=aggregatedResultMap.js.map