@fgv/ts-utils 5.0.2 → 5.1.0-1

package/lib/packlets/collections/aggregatedResultMap.d.ts

@@ -0,0 +1,433 @@
+import { DetailedResult, Result } from '../base';
+import { Converter } from '../conversion';
+import { Validator } from '../validation';
+import { KeyValueEntry } from './common';
+import { KeyValueConverters } from './keyValueConverters';
+import { IReadOnlyResultMapValidator } from './resultMapValidator';
+import { IReadOnlyResultMap, ResultMapForEachCb, ResultMapResultDetail } from './readonlyResultMap';
+import { IResultMap, ResultMapValueFactory } from './resultMap';
+import { IReadOnlyValidatingResultMap, ValidatingResultMap } from './validatingResultMap';
+/**
+ * A read-only collection entry in an {@link AggregatedResultMap | aggregated result map}.
+ * @public
+ */
+export interface IReadonlyAggregatedResultMapEntry<TCOLLECTIONID extends string = string, TITEMID extends string = string, TITEM = unknown, TMETADATA = unknown> {
+    readonly isMutable: false;
+    readonly id: TCOLLECTIONID;
+    readonly items: IReadOnlyValidatingResultMap<TITEMID, TITEM>;
+    readonly metadata?: TMETADATA;
+}
+/**
+ * A mutable collection entry in an {@link AggregatedResultMap | aggregated result map}.
+ * @public
+ */
+export interface IMutableAggregatedResultMapEntry<TCOLLECTIONID extends string = string, TITEMID extends string = string, TITEM = unknown, TMETADATA = unknown> {
+    readonly isMutable: true;
+    readonly id: TCOLLECTIONID;
+    readonly items: ValidatingResultMap<TITEMID, TITEM>;
+    metadata?: TMETADATA;
+}
+/**
+ * A collection entry in an {@link AggregatedResultMap | aggregated result map}, either mutable or read-only.
+ * @public
+ */
+export type AggregatedResultMapEntry<TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown> = IReadonlyAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA> | IMutableAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>;
+/**
+ * JSON format for an {@link AggregatedResultMap | aggregated result map} collection entry using an entries array.
+ * @public
+ */
+export interface IAggregatedResultMapJsonEntryWithEntries<TCOLLECTIONID extends string = string> {
+    readonly isMutable: boolean;
+    readonly id: TCOLLECTIONID;
+    readonly entries: ReadonlyArray<KeyValueEntry<string, unknown>>;
+    readonly metadata?: unknown;
+}
+/**
+ * JSON format for an {@link AggregatedResultMap | aggregated result map} collection entry using a string-keyed items object.
+ * @public
+ */
+export interface IAggregatedResultMapJsonEntryWithItems<TCOLLECTIONID extends string = string> {
+    readonly isMutable: boolean;
+    readonly id: TCOLLECTIONID;
+    readonly items: Record<string, unknown>;
+    readonly metadata?: unknown;
+}
+/**
+ * JSON format for an {@link AggregatedResultMap | aggregated result map} collection entry - supports both entries array and items object.
+ * @public
+ */
+export type AggregatedResultMapJsonEntry<TCOLLECTIONID extends string = string> = IAggregatedResultMapJsonEntryWithEntries<TCOLLECTIONID> | IAggregatedResultMapJsonEntryWithItems<TCOLLECTIONID>;
+/**
+ * Any valid input format for an {@link AggregatedResultMap | aggregated result map} collection entry.
+ * @public
+ */
+export type AggregatedResultMapEntryInit<TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown> = AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA> | AggregatedResultMapJsonEntry<TCOLLECTIONID>;
+/**
+ * Options for {@link Collections.AggregatedResultMapBase.addCollectionWithItems | addCollectionWithItems}.
+ * @public
+ */
+export interface IAddCollectionWithItemsOptions<TMETADATA = unknown> {
+    /**
+     * If true, the collection will be immutable (read-only).
+     * Defaults to false (mutable).
+     */
+    readonly isImmutable?: boolean;
+    /**
+     * Optional metadata to attach to the collection.
+     */
+    readonly metadata?: TMETADATA;
+}
+/**
+ * Parameters for constructing an {@link AggregatedResultMap | aggregated result map}.
+ * @public
+ */
+export interface IAggregatedResultMapConstructorParams<TCOMPOSITEID extends string, TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown> {
+    /**
+     * Validator for composite IDs.
+     */
+    readonly compositeIdValidator?: Validator<TCOMPOSITEID, unknown>;
+    /**
+     * Converter or validator for collection IDs.
+     */
+    readonly collectionIdConverter: Converter<TCOLLECTIONID, unknown> | Validator<TCOLLECTIONID, unknown>;
+    /**
+     * Converter or validator for item IDs.
+     */
+    readonly itemIdConverter: Converter<TITEMID, unknown> | Validator<TITEMID, unknown>;
+    /**
+     * Converter or validator for individual items in each collection.
+     */
+    readonly itemConverter: Converter<TITEM, unknown> | Validator<TITEM, unknown>;
+    /**
+     * Optional converter or validator for collection metadata.  If not provided, a metadata field
+     * in the input will cause a validation failure.
+     */
+    readonly metadataConverter?: Converter<TMETADATA, unknown> | Validator<TMETADATA, unknown>;
+    /**
+     * Optional separator string for composite IDs.  Defaults to `.`.
+     */
+    readonly separator?: string;
+    /**
+     * Initial collections to populate the map.
+     * @remarks Each entry may be mutable or read-only.
+     */
+    readonly collections?: ReadonlyArray<AggregatedResultMapEntryInit<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>>;
+}
+/**
+ * A validator for weakly-typed access to an {@link AggregatedResultMap | aggregated result map}.
+ * @public
+ */
+export declare class AggregatedResultMapValidator<TCOMPOSITEID extends string, TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown> implements IReadOnlyResultMapValidator<TCOMPOSITEID, TITEM> {
+    private readonly _map;
+    /**
+     * The key-value converters used for validating weakly-typed access.
+     */
+    readonly converters: KeyValueConverters<TCOMPOSITEID, TITEM>;
+    /**
+     * 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: AggregatedResultMap<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>, converters: KeyValueConverters<TCOMPOSITEID, TITEM>);
+    /** {@inheritDoc Collections.ResultMapValidator.map} */
+    get map(): IReadOnlyValidatingResultMap<TCOMPOSITEID, TITEM>;
+    /** {@inheritDoc Collections.ResultMapValidator.get} */
+    get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
+    /** {@inheritDoc Collections.ResultMapValidator.has} */
+    has(key: string): boolean;
+    /** {@inheritDoc Collections.ResultMapValidator.add} */
+    add(key: string, value: unknown): DetailedResult<TITEM, ResultMapResultDetail>;
+    /** {@inheritDoc Collections.ResultMapValidator.set} */
+    set(key: string, value: unknown): DetailedResult<TITEM, ResultMapResultDetail>;
+    /** {@inheritDoc Collections.ResultMapValidator.update} */
+    update(key: string, value: unknown): DetailedResult<TITEM, ResultMapResultDetail>;
+    /** {@inheritDoc Collections.ResultMapValidator.delete} */
+    delete(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
+}
+/**
+ * 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
+ */
+export declare class AggregatedResultMapBase<TCOMPOSITEID extends string, TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown> implements IResultMap<TCOMPOSITEID, TITEM>, IReadOnlyValidatingResultMap<TCOMPOSITEID, TITEM> {
+    private readonly _childKvConverters;
+    private readonly _collections;
+    private readonly _collectionKvConverters;
+    private readonly _compositeIdValidator;
+    private readonly _collectionIdConverter;
+    private readonly _itemIdConverter;
+    private readonly _itemConverter;
+    private readonly _metadataConverter?;
+    private readonly _delimiter;
+    private readonly _compositeIdConverter;
+    private readonly _kvConverters;
+    private readonly _validating;
+    /**
+     * 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
+     */
+    protected constructor(params: IAggregatedResultMapConstructorParams<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>);
+    /**
+     * A validator for weakly-typed access to the map.
+     */
+    get validating(): IReadOnlyResultMapValidator<TCOMPOSITEID, TITEM>;
+    /**
+     * The total number of items across all collections.
+     */
+    get size(): number;
+    /**
+     * 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: TCOMPOSITEID): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * 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: TCOMPOSITEID): boolean;
+    /**
+     * Iterates over all entries in all collections.
+     */
+    entries(): IterableIterator<KeyValueEntry<TCOMPOSITEID, TITEM>>;
+    /**
+     * Iterates over all composite keys.
+     */
+    keys(): IterableIterator<TCOMPOSITEID>;
+    /**
+     * Iterates over all values.
+     */
+    values(): IterableIterator<TITEM>;
+    /**
+     * Calls a callback for each entry.
+     * @param cb - The callback to call.
+     * @param thisArg - Optional `this` argument for the callback.
+     */
+    forEach(cb: ResultMapForEachCb<TCOMPOSITEID, TITEM>, thisArg?: unknown): void;
+    /**
+     * Gets an iterator over the map entries.
+     */
+    [Symbol.iterator](): IterableIterator<KeyValueEntry<TCOMPOSITEID, TITEM>>;
+    /**
+     * 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: TCOMPOSITEID, value: TITEM): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * 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: TCOMPOSITEID, value: TITEM): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * 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: TCOMPOSITEID, value: TITEM): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * 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: TCOMPOSITEID): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * Gets an existing item or adds a new one.
+     * @param key - The composite ID of the item.
+     * @param value - The value to add if not found.
+     * @returns `Success` with the existing or new value.
+     */
+    getOrAdd(key: TCOMPOSITEID, value: TITEM): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * Gets an existing item or adds a new one using a factory.
+     * @param key - The composite ID of the item.
+     * @param factory - A factory function to create the value if not found. Receives the composite ID.
+     * @returns `Success` with the existing or new value.
+     */
+    getOrAdd(key: TCOMPOSITEID, factory: ResultMapValueFactory<TCOMPOSITEID, TITEM>): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * Clears all items from all mutable collections.
+     * Immutable collections are not affected.
+     */
+    clear(): void;
+    /**
+     * Returns a read-only view of this map.
+     */
+    toReadOnly(): IReadOnlyResultMap<TCOMPOSITEID, TITEM>;
+    /**
+     * 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: TCOLLECTIONID, itemId: TITEMID): Result<TCOMPOSITEID>;
+    /**
+     * 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: TCOLLECTIONID, itemId: TITEMID, value: TITEM): DetailedResult<TCOMPOSITEID, ResultMapResultDetail>;
+    /**
+     * 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: TCOLLECTIONID, itemId: TITEMID, value: TITEM): DetailedResult<TCOMPOSITEID, ResultMapResultDetail>;
+    /**
+     * 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: TCOLLECTIONID, itemId: TITEMID, value: TITEM): DetailedResult<TCOMPOSITEID, ResultMapResultDetail>;
+    /**
+     * 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: TCOLLECTIONID, itemId: TITEMID): DetailedResult<TCOMPOSITEID, ResultMapResultDetail>;
+    /**
+     * 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(): IReadOnlyValidatingResultMap<TCOLLECTIONID, AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>>;
+    /**
+     * The number of collections.
+     */
+    get collectionCount(): number;
+    /**
+     * Gets the metadata for a specific collection.
+     * @param collectionId - The collection ID.
+     * @returns `Success` with the metadata if found, `Failure` otherwise.
+     */
+    getCollectionMetadata(collectionId: TCOLLECTIONID): Result<TMETADATA | undefined>;
+    /**
+     * 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: TCOLLECTIONID, metadata: TMETADATA): Result<TMETADATA>;
+    /**
+     * 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: AggregatedResultMapEntryInit<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>): DetailedResult<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>, ResultMapResultDetail>;
+    /**
+     * 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: string, items?: Iterable<KeyValueEntry<string, unknown>>, options?: IAddCollectionWithItemsOptions<TMETADATA>): Result<TCOLLECTIONID>;
+    /**
+     * 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.
+     */
+    protected _deleteCollection(collectionId: TCOLLECTIONID): DetailedResult<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>, ResultMapResultDetail>;
+    /**
+     * Type guard to check if a value is a factory function.
+     */
+    private _isFactory;
+    private _splitCompositeId;
+    private _splitAndLookup;
+    private _splitAndLookupMutable;
+    /**
+     * Gets an existing mutable collection by ID.
+     * Returns failure if the collection doesn't exist or is immutable.
+     */
+    private _getMutableCollection;
+    /**
+     * Gets an existing mutable collection or creates a new one.
+     */
+    private _getOrCreateMutableCollection;
+    /**
+     * Constructs a composite id validator using other converters/validators and separator supplied in params.
+     * @param params - Constructor params.
+     * @returns The composite ID validator.
+     */
+    private static _compositeIdValidator;
+    /**
+     * 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.
+     */
+    private static _convertMetadata;
+    /**
+     * Extracts metadata from a source object if present.
+     */
+    private static _extractSourceMetadata;
+    /**
+     * Creates a converter for pre-instantiated mutable entries.
+     * These are entries that already have a ValidatingResultMap as their items property.
+     */
+    private static _instantiatedMutableConverter;
+    /**
+     * Creates a converter for pre-instantiated read-only entries.
+     * These are entries that already have an IReadOnlyValidatingResultMap as their items property.
+     */
+    private static _instantiatedReadonlyConverter;
+    /**
+     * Creates a converter for JSON entries with an entries array.
+     * Converts the entries array to a ValidatingResultMap.
+     */
+    private static _jsonWithEntriesConverter;
+    /**
+     * Creates a converter for JSON entries with an items object.
+     * Converts the items object to a ValidatingResultMap.
+     */
+    private static _jsonWithItemsConverter;
+    /**
+     * 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.
+     */
+    private static _entryConverter;
+}
+/**
+ * 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
+ */
+export declare class AggregatedResultMap<TCOMPOSITEID extends string, TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown> extends AggregatedResultMapBase<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA> {
+    /**
+     * Constructs a new {@link AggregatedResultMap | AggregatedResultMap}.
+     * @param params -
+     */
+    constructor(params: IAggregatedResultMapConstructorParams<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>);
+    /**
+     * 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<TCOMPOSITEID extends string, TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown>(params: IAggregatedResultMapConstructorParams<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>): Result<AggregatedResultMap<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>>;
+}
+//# sourceMappingURL=aggregatedResultMap.d.ts.map