@fgv/ts-utils 5.0.0-22 → 5.0.0-24

package/src/packlets/collections/collector.ts

@@ -1,273 +0,0 @@
-/*
- * 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 {
-  captureResult,
-  DetailedResult,
-  failWithDetail,
-  Result,
-  fail,
-  succeed,
-  succeedWithDetail
-} from '../base';
-import { CollectibleFactoryCallback, CollectibleKey, ICollectible } from './collectible';
-import { KeyValueEntry } from './common';
-import { IReadOnlyResultMap, ResultMapForEachCb, ResultMapResultDetail } from './readonlyResultMap';
-
-/**
- * Additional success or failure details for mutating collector calls.
- * @public
- */
-export type CollectorResultDetail = ResultMapResultDetail | 'invalid-index';
-
-/**
- * A read-only interface exposing only the non-mutating methods of a {@link Collections.Collector | ICollector}.
- * @public
- */
-export interface IReadOnlyCollector<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  TITEM extends ICollectible<any, any>
-> extends IReadOnlyResultMap<CollectibleKey<TITEM>, TITEM> {
-  /**
-   * Gets the item at a specified index.
-   * @param index - The index of the item to retrieve.
-   * @returns Returns {@link Success | Success} with the item if it exists, or {@link Failure | Failure}
-   * with an error if the index is out of range.
-   */
-  getAt(index: number): Result<TITEM>;
-}
-
-/**
- * Parameters for constructing a {@link Collections.Collector | ICollector}.
- * @public
- */
-export interface ICollectorConstructorParams<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  TITEM extends ICollectible<any, any>
-> {
-  items?: TITEM[];
-}
-
-/**
- * A {@link Collections.Collector | Collector} that is a specialized collection
- * which contains items of type {@link Collections.ICollectible | ICollectible},
- * which have a unique key and a write-once index.
- *
- * Items are assigned an index sequentially as they are added to the collection.
- * Once added, items are immutable - they cannot be removed or replaced.
- * @public
- */
-export class Collector<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  TITEM extends ICollectible<any, any>
-> implements IReadOnlyCollector<TITEM>
-{
-  private readonly _byKey: Map<CollectibleKey<TITEM>, TITEM>;
-  private readonly _byIndex: TITEM[];
-
-  /**
-   * {@inheritdoc Collections.ResultMap.size}
-   */
-  public get size(): number {
-    return this._byIndex.length;
-  }
-
-  /**
-   * Constructs a new {@link Collections.Collector | Collector}.
-   * @param params - Optional {@link Collections.ICollectorConstructorParams | initialization parameters} used
-   * to construct the collector.
-   */
-  public constructor(params?: ICollectorConstructorParams<TITEM>) {
-    this._byKey = new Map<CollectibleKey<TITEM>, TITEM>();
-    this._byIndex = [];
-    for (const item of params?.items ?? []) {
-      this.add(item).orThrow();
-    }
-  }
-
-  /**
-   * Creates a new {@link Collections.Collector | Collector} instance.
-   * @param params - Optional {@link Collections.ICollectorConstructorParams | initialization parameters} used
-   * to create the collector.
-   * @returns Returns {@link Success | Success} with the new collector if it was created successfully,
-   * or {@link Failure | Failure} with an error if the collector could not be created.
-   */
-  public static createCollector<
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    TITEM extends ICollectible<any, any>
-  >(params?: ICollectorConstructorParams<TITEM>): Result<Collector<TITEM>> {
-    return captureResult(() => new Collector(params));
-  }
-
-  /**
-   * Adds an item to the collection, failing if a different item with the same key already exists. Note
-   * that adding an object that is already in the collection again will succeed without updating the collection.
-   * @param item - The item to add.
-   * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added
-   * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with
-   * an error message and appropriate detail if the item could not be added.
-   */
-  public add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail> {
-    const existing = this._byKey.get(item.key);
-    if (existing === item) {
-      return succeedWithDetail(item, 'exists');
-    } else if (existing) {
-      return failWithDetail(`${item.key}: already exists`, 'exists');
-    }
-    const indexResult = item.setIndex(this._byIndex.length);
-    if (indexResult.isFailure()) {
-      return failWithDetail(`${item.key}: ${indexResult.message}`, 'invalid-index');
-    } else if (item.index !== this._byIndex.length) {
-      return failWithDetail(`${item.key}: index mismatch - built item has ${item.index}`, 'invalid-index');
-    }
-    this._byKey.set(item.key, item);
-    this._byIndex.push(item);
-    return succeedWithDetail(item, 'added');
-  }
-
-  /**
-   * {@inheritdoc Collections.ResultMap.entries}
-   */
-  public entries(): IterableIterator<KeyValueEntry<CollectibleKey<TITEM>, TITEM>> {
-    return this._byKey.entries();
-  }
-
-  /**
-   * {@inheritdoc Collections.ResultMap.forEach}
-   */
-  public forEach(callback: ResultMapForEachCb<CollectibleKey<TITEM>, TITEM>, arg?: unknown): void {
-    for (const [key, value] of this._byKey.entries()) {
-      callback(value, key, this, arg);
-    }
-  }
-
-  /**
-   * {@inheritdoc Collections.ResultMap.get}
-   */
-  public get(key: CollectibleKey<TITEM>): DetailedResult<TITEM, ResultMapResultDetail> {
-    const item = this._byKey.get(key);
-    return item ? succeedWithDetail(item, 'exists') : failWithDetail(`${key}: not found`, 'not-found');
-  }
-
-  /**
-   * {@inheritdoc Collections.IReadOnlyCollector.getAt}
-   */
-  public getAt(index: number): Result<TITEM> {
-    if (index < 0 || index >= this._byIndex.length) {
-      return fail(`${index}: out of range.`);
-    }
-    return succeed(this._byIndex[index]);
-  }
-
-  /**
-   * Gets an existing item with a key matching that of a supplied item, or adds the supplied
-   * item to the collector if no item with that key exists.
-   * @param item - The item to get or add.
-   * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
-   * detail `exists` indicates that an existing item return and detail `added` indicates that the
-   * item was added. Returns {@link DetailedFailure | Failure} with an error and appropriate
-   * detail if the item could not be added.
-   */
-  public getOrAdd(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
-
-  /**
-   * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
-   * using a factory callback if no item with that key exists.
-   * @param key - The key of the item to add.
-   * @param callback - The factory callback to create the item.
-   * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
-   * detail `exists` indicates that an existing item return and detail `added` indicates that the
-   * item was added. Returns {@link DetailedFailure | Failure} with an error and appropriate
-   * detail if the item could not be added.
-   */
-  public getOrAdd(
-    key: CollectibleKey<TITEM>,
-    factory: CollectibleFactoryCallback<TITEM>
-  ): DetailedResult<TITEM, CollectorResultDetail>;
-
-  public getOrAdd(
-    keyOrItem: CollectibleKey<TITEM> | TITEM,
-    factory?: CollectibleFactoryCallback<TITEM>
-  ): DetailedResult<TITEM, CollectorResultDetail> {
-    const key = !this._isItem(keyOrItem) ? keyOrItem : keyOrItem.key;
-    const existing = this._byKey.get(key);
-    if (existing) {
-      return succeedWithDetail(existing, 'exists');
-    }
-
-    const itemResult = !this._isItem(keyOrItem)
-      ? factory!(keyOrItem, this._byIndex.length)
-      : succeed(keyOrItem);
-    if (itemResult.isFailure()) {
-      return failWithDetail(`${key}: ${itemResult.message}`, 'invalid-value');
-    }
-    const item = itemResult.value;
-
-    if (item.key !== key) {
-      return failWithDetail(`${key}: key mismatch - built item has ${key}`, 'invalid-key');
-    }
-
-    return itemResult.withFailureDetail<CollectorResultDetail>('invalid-index').onSuccess((item) => {
-      return this.add(item);
-    });
-  }
-
-  /**
-   * {@inheritdoc Collections.ResultMap.has}
-   */
-  public has(key: CollectibleKey<TITEM>): boolean {
-    return this._byKey.has(key);
-  }
-
-  /**
-   * {@inheritdoc Collections.ResultMap.keys}
-   */
-  public keys(): IterableIterator<CollectibleKey<TITEM>> {
-    return this._byKey.keys();
-  }
-
-  /**
-   * {@inheritdoc Collections.ResultMap.values}
-   */
-  public values(): IterableIterator<TITEM> {
-    return this._byKey.values();
-  }
-
-  /**
-   * Gets a read-only version of this collector.
-   */
-  public toReadOnly(): IReadOnlyCollector<TITEM> {
-    return this;
-  }
-
-  /**
-   * Gets an iterator over the map entries.
-   * @returns An iterator over the map entries.
-   */
-  public [Symbol.iterator](): IterableIterator<KeyValueEntry<CollectibleKey<TITEM>, TITEM>> {
-    return this._byKey[Symbol.iterator]();
-  }
-
-  protected _isItem(keyOrItem: CollectibleKey<TITEM> | TITEM): keyOrItem is TITEM {
-    return typeof keyOrItem !== 'string';
-  }
-}

package/src/packlets/collections/collectorValidator.ts

@@ -1,178 +0,0 @@
-/*
- * 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 { DetailedResult } from '../base';
-import { IReadOnlyResultMap, ResultMapResultDetail } from './readonlyResultMap';
-import { ResultMapValueFactory } from './resultMap';
-import { KeyValueConverters } from './keyValueConverters';
-import { Collector, CollectorResultDetail } from './collector';
-import { IReadOnlyResultMapValidator } from './resultMapValidator';
-import { CollectibleKey, ICollectible } from './collectible';
-
-/**
- * A read-only interface exposing non-mutating methods of a
- * {@link Collections.CollectorValidator | CollectorValidator}.
- * @public
- */
-export interface IReadOnlyCollectorValidator<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  TITEM extends ICollectible<any, any>
-> extends IReadOnlyResultMapValidator<CollectibleKey<TITEM>, TITEM> {
-  /**
-   * {@inheritdoc Collections.ConvertingCollectorValidator.map}
-   */
-  readonly map: IReadOnlyResultMap<CollectibleKey<TITEM>, TITEM>;
-
-  /**
-   * {@inheritdoc Collections.Collector.get}
-   */
-  get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
-
-  /**
-   * {@inheritdoc Collections.ResultMap.has}
-   */
-  has(key: string): boolean;
-
-  /**
-   * {@inheritdoc Collections.Collector.(getOrAdd:2)}
-   */
-  getOrAdd(
-    key: string,
-    factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>
-  ): DetailedResult<TITEM, CollectorResultDetail>;
-}
-
-/**
- * Parameters for constructing a {@link Collections.CollectorValidator | CollectorValidator}.
- * @public
- */
-export interface ICollectorValidatorCreateParams<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  TITEM extends ICollectible<any, any>
-> {
-  readonly collector: Collector<TITEM>;
-  readonly converters: KeyValueConverters<CollectibleKey<TITEM>, TITEM>;
-}
-
-/**
- * A {@link Collections.Collector | Collector} wrapper which validates weakly-typed keys
- * and values before calling the wrapped collector.
- * @public
- */
-export class CollectorValidator<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  TITEM extends ICollectible<any, any>
-> implements IReadOnlyCollectorValidator<TITEM>
-{
-  public readonly converters: KeyValueConverters<CollectibleKey<TITEM>, TITEM>;
-
-  public get map(): IReadOnlyResultMap<CollectibleKey<TITEM>, TITEM> {
-    return this._collector.toReadOnly();
-  }
-
-  protected _collector: Collector<TITEM>;
-
-  /**
-   * Constructs a new {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator}.
-   * @param params - Required parameters for constructing the collector validator.
-   */
-  public constructor(params: ICollectorValidatorCreateParams<TITEM>) {
-    this._collector = params.collector;
-    this.converters = params.converters;
-  }
-
-  /**
-   * {@inheritdoc Collections.Collector.add}
-   */
-  public add(item: unknown): DetailedResult<TITEM, CollectorResultDetail> {
-    return this._convertValue(item).onSuccess((i) => {
-      return this._collector.add(i);
-    });
-  }
-
-  /**
-   * {@inheritdoc Collections.Collector.get}
-   */
-  public get(key: string): DetailedResult<TITEM, ResultMapResultDetail> {
-    return this.converters.convertKey(key).onSuccess((k) => {
-      return this._collector.get(k);
-    });
-  }
-
-  /**
-   * {@inheritdoc Collections.Collector.(getOrAdd:2)}
-   */
-  public getOrAdd(
-    key: string,
-    factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>
-  ): DetailedResult<TITEM, CollectorResultDetail>;
-
-  /**
-   * {@inheritdoc Collections.Collector.(getOrAdd:1)}
-   * @param item - The item to add to the collector.
-   */
-  public getOrAdd(item: unknown): DetailedResult<TITEM, CollectorResultDetail>;
-
-  public getOrAdd(
-    keyOrItem: string | unknown,
-    factoryCb?: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>
-  ): DetailedResult<TITEM, CollectorResultDetail> {
-    if (factoryCb === undefined) {
-      return this._convertValue(keyOrItem).onSuccess((item) => this._collector.getOrAdd(item));
-    } else {
-      return this.converters
-        .convertKey(keyOrItem)
-        .withDetail<CollectorResultDetail>('invalid-key', 'success')
-        .onSuccess((key) => this._collector.getOrAdd(key, factoryCb));
-    }
-  }
-
-  /**
-   * {@inheritdoc Collections.ResultMap.has}
-   */
-  public has(key: string): boolean {
-    return this._collector.has(key as CollectibleKey<TITEM>);
-  }
-
-  /**
-   * {@inheritdoc Collections.Collector.toReadOnly}
-   */
-  public toReadOnly(): IReadOnlyCollectorValidator<TITEM> {
-    return this;
-  }
-
-  /**
-   * Helper to convert a value, returning a {@link DetailedResult | DetailedResult}
-   * and formatting the error message.
-   * @param value - The value to convert.
-   * @returns {@link DetailedSuccess | DetailedSuccess} with the converted value
-   * and detail `success` if conversion is successful, or
-   * {@link DetailedFailure | DetailedFailure} with the error message and detail `invalid-value`
-   * if conversion fails.
-   */
-  protected _convertValue(value: unknown): DetailedResult<TITEM, CollectorResultDetail> {
-    return this.converters
-      .convertValue(value)
-      .withErrorFormat((message) => `invalid item: ${message}`)
-      .withDetail<CollectorResultDetail>('invalid-value', 'success');
-  }
-}

package/src/packlets/collections/common.ts

@@ -1,27 +0,0 @@
-/*
- * 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.
- */
-
-/**
- * Generic key-value entry.
- * @public
- */
-export type KeyValueEntry<TK extends string = string, TV = unknown> = [TK, TV];