@fgv/ts-utils 5.1.0-4 → 5.1.0-40

package/lib/packlets/collections/validatingConvertingCollector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatingConvertingCollector.js","sourceRoot":"","sources":["../../../src/packlets/collections/validatingConvertingCollector.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,kCAAgD;AAEhD,+DAA4D;AAC5D,iFAA8E;AA8B9E;;;;;GAKG;AACH,MAAa,6BAIX,SAAQ,yCAAgC;IASxC;;;;OAIG;IACH,YAAmB,MAAoE;;QACrF,KAAK,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QACnC,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,IAAI,2DAA4B,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;QACvG,KAAK,MAAM,KAAK,IAAI,MAAA,MAAM,CAAC,OAAO,mCAAI,EAAE,EAAE,CAAC;YACzC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAC9C,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,yBAAyB,CAKrC,MAAoE;QAEpE,OAAO,IAAA,oBAAa,EAAC,GAAG,EAAE,CAAC,IAAI,6BAA6B,CAAC,MAAM,CAAC,CAAC,CAAC;IACxE,CAAC;IAED;;;;OAIG;IACI,UAAU;QACf,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAnDD,sEAmDC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { captureResult, Result } from '../base';\nimport { CollectibleFactory, CollectibleKey, ICollectible } from './collectible';\nimport { ConvertingCollector } from './convertingCollector';\nimport { ConvertingCollectorValidator } from './convertingCollectorValidator';\nimport { KeyValueEntry } from './common';\nimport { KeyValueConverters } from './keyValueConverters';\nimport { IReadOnlyValidatingCollector } from './validatingCollector';\n\n/**\n * Parameters for constructing a {@link Collections.ValidatingConvertingCollector | ValidatingConvertingCollector}.\n * @public\n */\nexport interface IValidatingConvertingCollectorConstructorParams<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>,\n  TSRC = TITEM\n> {\n  /**\n   * {@inheritDoc Collections.IConvertingCollectorConstructorParams.factory}\n   */\n  factory: CollectibleFactory<TITEM, TSRC>;\n\n  /**\n   * {@inheritDoc Collections.IConvertingCollectorValidatorCreateParams.converters}\n   */\n  converters: KeyValueConverters<CollectibleKey<TITEM>, TSRC>;\n\n  /**\n   * {@inheritDoc Collections.IConvertingCollectorConstructorParams.entries}\n   */\n  entries?: KeyValueEntry<CollectibleKey<TITEM>, TSRC>[];\n}\n\n/**\n * A {@link Collections.ConvertingCollector | ConvertingCollector} with a\n * {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator}\n * property that enables validated use of the underlying map with weakly-typed keys and values.\n * @public\n */\nexport class ValidatingConvertingCollector<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>,\n  TSRC = TITEM\n> extends ConvertingCollector<TITEM, TSRC> {\n  /**\n   * A {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator} which validates keys and values\n   * before inserting them into this collector.\n   */\n  public readonly validating: ConvertingCollectorValidator<TITEM, TSRC>;\n\n  protected readonly _converters: KeyValueConverters<CollectibleKey<TITEM>, TSRC>;\n\n  /**\n   * Constructs a new {@link Collections.ValidatingConvertingCollector | ValidatingConvertingCollector}\n   * from the supplied {@link Collections.IValidatingConvertingCollectorConstructorParams | parameters}.\n   * @param params - Required parameters for constructing the collector.\n   */\n  public constructor(params: IValidatingConvertingCollectorConstructorParams<TITEM, TSRC>) {\n    super({ factory: params.factory });\n    this._converters = params.converters;\n    this.validating = new ConvertingCollectorValidator({ collector: this, converters: params.converters });\n    for (const entry of params.entries ?? []) {\n      this.getOrAdd(entry[0], entry[1]).orThrow();\n    }\n  }\n\n  /**\n   * Creates a new {@link Collections.ValidatingConvertingCollector | ValidatingConvertingCollector} instance from\n   * the supplied {@link Collections.IValidatingConvertingCollectorConstructorParams | parameters}.\n   * @param params - Required parameters for constructing the collector.\n   * @returns {@link Success} with the new collector if successful, {@link Failure} otherwise.\n   */\n  public static createValidatingCollector<\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    TITEM extends ICollectible<any, any>,\n    TSRC = TITEM\n  >(\n    params: IValidatingConvertingCollectorConstructorParams<TITEM, TSRC>\n  ): Result<ValidatingConvertingCollector<TITEM, TSRC>> {\n    return captureResult(() => new ValidatingConvertingCollector(params));\n  }\n\n  /**\n   * Gets a read-only version of this collector as a\n   * {@link Collections.IReadOnlyValidatingResultMap | read-only map}.\n   * @returns\n   */\n  public toReadOnly(): IReadOnlyValidatingCollector<TITEM> {\n    return this;\n  }\n}\n"]}

package/lib/packlets/collections/validatingConvertingResultMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatingConvertingResultMap.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/validatingConvertingResultMap.ts"],"names":[],"mappings":"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"}

package/lib/packlets/collections/validatingConvertingResultMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatingConvertingResultMap.js","sourceRoot":"","sources":["../../../src/packlets/collections/validatingConvertingResultMap.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,kCAAgD;AAGhD,+EAGuC;AACvC,+DAA4D;AAE5D,6DAAkE;AAwBlE;;;;;GAKG;AACH,MAAa,qCAIX,SAAQ,yDAA8C;IAWtD;;;OAGG;IACH,YAAmB,MAAkF;QACnG,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,IAAI,+CAA0B,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC5E,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAU,MAAM,CAC3B,MAAkF;QAElF,OAAO,IAAA,oBAAa,EAAC,GAAG,EAAE,CAAC,IAAI,qCAAqC,CAAC,MAAM,CAAC,CAAC,CAAC;IAChF,CAAC;CACF;AAnCD,sFAmCC;AA6BD;;;;;;;GAOG;AACH,MAAa,6BAKX,SAAQ,yCAA+C;IAWvD;;;OAGG;IACH,YAAmB,MAAmF;QACpG,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,IAAI,+CAA0B,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC5E,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAU,MAAM,CAM3B,MAAmF;QAEnF,OAAO,IAAA,oBAAa,EAAC,GAAG,EAAE,CAAC,IAAI,6BAA6B,CAAC,MAAM,CAAC,CAAC,CAAC;IACxE,CAAC;CACF;AAzCD,sEAyCC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { captureResult, Result } from '../base';\nimport { KeyValueConverters } from './keyValueConverters';\nimport { IReadOnlyResultMap } from './readonlyResultMap';\nimport {\n  ReadOnlyConvertingResultMap,\n  ConvertingResultMapValueConverter\n} from './readOnlyConvertingResultMap';\nimport { ConvertingResultMap } from './convertingResultMap';\nimport { IResultMap } from './resultMap';\nimport { ReadOnlyResultMapValidator } from './resultMapValidator';\n\n/**\n * Parameters for constructing a\n * {@link Collections.ValidatingReadOnlyConvertingResultMap | ValidatingReadOnlyConvertingResultMap}.\n * @public\n */\nexport interface IValidatingReadOnlyConvertingResultMapConstructorParams<TK extends string, TSRC, TTARGET> {\n  /**\n   * The inner map containing source values.\n   */\n  inner: IReadOnlyResultMap<TK, TSRC>;\n\n  /**\n   * The converter function to transform source values to target values.\n   */\n  converter: ConvertingResultMapValueConverter<TK, TSRC, TTARGET>;\n\n  /**\n   * The key-value converters for validating weakly-typed access.\n   */\n  converters: KeyValueConverters<TK, TTARGET>;\n}\n\n/**\n * A read-only result map that wraps an inner {@link Collections.IReadOnlyResultMap | IReadOnlyResultMap}\n * of source type and returns lazily-converted, cached values of a target type, with a\n * {@link Collections.ReadOnlyResultMapValidator | validating} property for weakly-typed access.\n * @public\n */\nexport class ValidatingReadOnlyConvertingResultMap<\n  TK extends string,\n  TSRC,\n  TTARGET\n> extends ReadOnlyConvertingResultMap<TK, TSRC, TTARGET> {\n  /**\n   * A validator for weakly-typed access to the map.\n   */\n  public readonly validating: ReadOnlyResultMapValidator<TK, TTARGET>;\n\n  /**\n   * The key-value converters used for validation.\n   */\n  protected readonly _converters: KeyValueConverters<TK, TTARGET>;\n\n  /**\n   * Constructs a new {@link Collections.ValidatingReadOnlyConvertingResultMap | ValidatingReadOnlyConvertingResultMap}.\n   * @param params - Parameters for constructing the map.\n   */\n  public constructor(params: IValidatingReadOnlyConvertingResultMapConstructorParams<TK, TSRC, TTARGET>) {\n    super({ inner: params.inner, converter: params.converter });\n    this._converters = params.converters;\n    this.validating = new ReadOnlyResultMapValidator(this, params.converters);\n  }\n\n  /**\n   * Creates a new {@link Collections.ValidatingReadOnlyConvertingResultMap | ValidatingReadOnlyConvertingResultMap}.\n   * @param params - Parameters for constructing the map.\n   * @returns `Success` with the new map, or `Failure` with error details if an error occurred.\n   */\n  public static override create<TK extends string, TSRC, TTARGET>(\n    params: IValidatingReadOnlyConvertingResultMapConstructorParams<TK, TSRC, TTARGET>\n  ): Result<ValidatingReadOnlyConvertingResultMap<TK, TSRC, TTARGET>> {\n    return captureResult(() => new ValidatingReadOnlyConvertingResultMap(params));\n  }\n}\n\n/**\n * Parameters for constructing a\n * {@link Collections.ValidatingConvertingResultMap | ValidatingConvertingResultMap}.\n * @public\n */\nexport interface IValidatingConvertingResultMapConstructorParams<\n  TK extends string,\n  TSRC,\n  TTARGET,\n  TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>\n> {\n  /**\n   * The inner map containing source values.\n   */\n  inner: TSRCMAP;\n\n  /**\n   * The converter function to transform source values to target values.\n   */\n  converter: ConvertingResultMapValueConverter<TK, TSRC, TTARGET>;\n\n  /**\n   * The key-value converters for validating weakly-typed access.\n   */\n  converters: KeyValueConverters<TK, TTARGET>;\n}\n\n/**\n * A result map that wraps an inner {@link Collections.IResultMap | IResultMap} of source type\n * and returns lazily-converted, cached values of a target type, with a\n * {@link Collections.ReadOnlyResultMapValidator | validating} property for weakly-typed access\n * and a {@link Collections.CacheInvalidatingResultMapWrapper | source} property for mutable access\n * to the underlying source map.\n * @public\n */\nexport class ValidatingConvertingResultMap<\n  TK extends string,\n  TSRC,\n  TTARGET,\n  TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>\n> extends ConvertingResultMap<TK, TSRC, TTARGET, TSRCMAP> {\n  /**\n   * A validator for weakly-typed access to the map.\n   */\n  public readonly validating: ReadOnlyResultMapValidator<TK, TTARGET>;\n\n  /**\n   * The key-value converters used for validation.\n   */\n  protected readonly _converters: KeyValueConverters<TK, TTARGET>;\n\n  /**\n   * Constructs a new {@link Collections.ValidatingConvertingResultMap | ValidatingConvertingResultMap}.\n   * @param params - Parameters for constructing the map.\n   */\n  public constructor(params: IValidatingConvertingResultMapConstructorParams<TK, TSRC, TTARGET, TSRCMAP>) {\n    super({ inner: params.inner, converter: params.converter });\n    this._converters = params.converters;\n    this.validating = new ReadOnlyResultMapValidator(this, params.converters);\n  }\n\n  /**\n   * Creates a new {@link Collections.ValidatingConvertingResultMap | ValidatingConvertingResultMap}.\n   * @param params - Parameters for constructing the map.\n   * @returns `Success` with the new map, or `Failure` with error details if an error occurred.\n   */\n  public static override create<\n    TK extends string,\n    TSRC,\n    TTARGET,\n    TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>\n  >(\n    params: IValidatingConvertingResultMapConstructorParams<TK, TSRC, TTARGET, TSRCMAP>\n  ): Result<ValidatingConvertingResultMap<TK, TSRC, TTARGET, TSRCMAP>> {\n    return captureResult(() => new ValidatingConvertingResultMap(params));\n  }\n}\n"]}

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

@@ -10,7 +10,8 @@ import { IReadOnlyResultMapValidator, ResultMapValidator } from './resultMapVali
  */
 export interface IReadOnlyValidatingResultMap<TK extends string = string, TV = unknown> extends IReadOnlyResultMap<TK, TV> {
     /**
-     * {@inheritDoc Collections.ValidatingResultMap.validating}
+     * A {@link Collections.ResultMapValidator | ResultMapValidator} which validates keys and values
+     * before inserting them into this collection.
      */
     readonly validating: IReadOnlyResultMapValidator<TK, TV>;
 }

package/lib/packlets/collections/validatingResultMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatingResultMap.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/validatingResultMap.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAiB,MAAM,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,2BAA2B,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEvF;;;GAGG;AACH,MAAM,WAAW,4BAA4B,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,OAAO,CACpF,SAAQ,kBAAkB,CAAC,EAAE,EAAE,EAAE,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,2BAA2B,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;CAC1D;AAED;;;GAGG;AACH,MAAM,WAAW,qCAAqC,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,OAAO;IAC7F,OAAO,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,UAAU,EAAE,kBAAkB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;CACxC;AAED;;;;GAIG;AACH,qBAAa,mBAAmB,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,OAAO,CACvE,SAAQ,SAAS,CAAC,EAAE,EAAE,EAAE,CACxB,YAAW,4BAA4B,CAAC,EAAE,EAAE,EAAE,CAAC;IAE/C;;;OAGG;IACH,SAAgB,UAAU,EAAE,kBAAkB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAEvD;;;OAGG;gBACgB,MAAM,EAAE,qCAAqC,CAAC,EAAE,EAAE,EAAE,CAAC;IAMxE;;;;;OAKG;WACW,yBAAyB,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,OAAO,EAC9E,MAAM,EAAE,qCAAqC,CAAC,EAAE,EAAE,EAAE,CAAC,GACpD,MAAM,CAAC,mBAAmB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAItC;;OAEG;IACI,UAAU,IAAI,4BAA4B,CAAC,EAAE,EAAE,EAAE,CAAC;CAG1D"}

package/lib/packlets/collections/validatingResultMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatingResultMap.js","sourceRoot":"","sources":["../../../src/packlets/collections/validatingResultMap.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,kCAAgD;AAIhD,2CAAwC;AACxC,6DAAuF;AAwBvF;;;;GAIG;AACH,MAAa,mBACX,SAAQ,qBAAiB;IASzB;;;OAGG;IACH,YAAmB,MAAqD;;QACtE,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,MAAA,MAAM,CAAC,OAAO,mCAAI,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QACxF,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,IAAI,uCAAkB,CAAS,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IACjG,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,yBAAyB,CACrC,MAAqD;QAErD,OAAO,IAAA,oBAAa,EAAC,GAAG,EAAE,CAAC,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED;;OAEG;IACI,UAAU;QACf,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAtCD,kDAsCC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { captureResult, Result } from '../base';\nimport { KeyValueEntry } from './common';\nimport { KeyValueConverters } from './keyValueConverters';\nimport { IReadOnlyResultMap } from './readonlyResultMap';\nimport { ResultMap } from './resultMap';\nimport { IReadOnlyResultMapValidator, ResultMapValidator } from './resultMapValidator';\n\n/**\n * A read-only interface exposing non-mutating methods of a {@link Collections.ValidatingResultMap | ValidatingResultMap}.\n * @public\n */\nexport interface IReadOnlyValidatingResultMap<TK extends string = string, TV = unknown>\n  extends IReadOnlyResultMap<TK, TV> {\n  /**\n   * A {@link Collections.ResultMapValidator | ResultMapValidator} which validates keys and values\n   * before inserting them into this collection.\n   */\n  readonly validating: IReadOnlyResultMapValidator<TK, TV>;\n}\n\n/**\n * Parameters for constructing a {@link Collections.ResultMap | ResultMap}.\n * @public\n */\nexport interface IValidatingResultMapConstructorParams<TK extends string = string, TV = unknown> {\n  entries?: Iterable<KeyValueEntry<string, unknown>>;\n  converters: KeyValueConverters<TK, TV>;\n}\n\n/**\n * A {@link Collections.ResultMap | ResultMap} with a {@link Collections.ResultMapValidator | validator}\n * property that enables validated use of the underlying map with weakly-typed keys and values.\n * @public\n */\nexport class ValidatingResultMap<TK extends string = string, TV = unknown>\n  extends ResultMap<TK, TV>\n  implements IReadOnlyValidatingResultMap<TK, TV>\n{\n  /**\n   * A {@link Collections.ResultMapValidator | ResultMapValidator} which validates keys and values\n   * before inserting them into this collection.\n   */\n  public readonly validating: ResultMapValidator<TK, TV>;\n\n  /**\n   * Constructs a new {@link Collections.ValidatingResultMap | ValidatingResultMap}.\n   * @param params - Required parameters for constructing the map.\n   */\n  public constructor(params: IValidatingResultMapConstructorParams<TK, TV>) {\n    const entries = params.converters.convertEntries([...(params.entries ?? [])]).orThrow();\n    super({ entries });\n    this.validating = new ResultMapValidator<TK, TV>({ map: this, converters: params.converters });\n  }\n\n  /**\n   * Creates a new {@link Collections.ValidatingResultMap | ValidatingResultMap} instance.\n   * @param params - Required parameters for constructing the map.\n   * @returns `Success` with the new map if successful, `Failure` otherwise.\n   * @public\n   */\n  public static createValidatingResultMap<TK extends string = string, TV = unknown>(\n    params: IValidatingResultMapConstructorParams<TK, TV>\n  ): Result<ValidatingResultMap<TK, TV>> {\n    return captureResult(() => new ValidatingResultMap(params));\n  }\n\n  /**\n   * Gets a read-only version of this map.\n   */\n  public toReadOnly(): IReadOnlyValidatingResultMap<TK, TV> {\n    return this;\n  }\n}\n"]}

package/lib/packlets/conversion/advancedConverters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advancedConverters.d.ts","sourceRoot":"","sources":["../../../src/packlets/conversion/advancedConverters.ts"],"names":[],"mappings":"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"}

package/lib/packlets/conversion/advancedConverters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advancedConverters.js","sourceRoot":"","sources":["../../../src/packlets/conversion/advancedConverters.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AAsCH,sDAgBC;AAUD,sDA2BC;AAWD,kCAQC;AAWD,8CAoBC;AAqBD,8BAoBC;AAqED,0CA8CC;AA0BD,sBAsBC;AAvVD,kCAAsE;AAEtE,mDAAsE;AAEtE,uDAA4C;AAC5C,uDAAqE;AAuBrE;;;;;;;GAOG;AACH,SAAgB,qBAAqB,CACnC,qBAAkF,EAClF,SAAiB,EACjB,eAAgE;IAEhE,OAAO,IAAI,iCAAe,CAAkD;QAC1E,YAAY,EAAE,qBAAqB;QACnC,SAAS,EAAE,IAAA,yBAAO,EAAC,SAAS,CAAC,CAAC,QAAQ,EAAE;QACxC,MAAM,EAAE,eAAe;KACxB,CAAC,CAAC,GAAG,CAAuC,CAAC,GAAG,EAAE,EAAE;;QACnD,OAAA,cAAO,CAAC,IAAI,CAAC;YACX,YAAY,EAAE,GAAG,CAAC,YAAY;YAC9B,SAAS,EAAE,MAAA,GAAG,CAAC,SAAS,mCAAI,SAAS;YACrC,MAAM,EAAE,GAAG,CAAC,MAAM;SACnB,CAAC,CAAA;KAAA,CACH,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,qBAAqB,CACnC,qBAAkF,EAClF,SAAiB,EACjB,eAAgE;IAEhE,OAAO,IAAI,6BAAa,CACtB,CAAC,IAAa,EAAE,MAA4D,EAAE,OAAY,EAAE,EAAE;QAC5F,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,OAAO,IAAA,WAAI,EAAC,GAAG,IAAI,oCAAoC,CAAC,CAAC;QAC3D,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACpC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO,IAAA,WAAI,EAAC,GAAG,IAAI,uCAAuC,SAAS,cAAc,CAAC,CAAC;QACrF,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,OAAO,IAAA,WAAI,EAAC,GAAG,IAAI,iDAAiD,SAAS,WAAW,CAAC,CAAC;QAC5F,CAAC;QACD,OAAO,qBAAqB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,YAAY,EAAE,EAAE;YACjF,OAAO,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE;gBACrE,OAAO,IAAA,cAAO,EAAC;oBACb,YAAY;oBACZ,SAAS;oBACT,MAAM;iBACP,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CACF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,WAAW,CACzB,qBAAkF,EAClF,SAAiB,EACjB,eAAgE;IAEhE,OAAO,qBAAqB,CAAC,qBAAqB,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC,EAAE,CAChF,qBAAqB,CAAC,qBAAqB,EAAE,SAAS,EAAE,eAAe,CAAC,CACzE,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAM/B,oBAAyD,EACzD,qBAAkF,EAClF,SAAiB,EACjB,eAAgE;IAEhE,MAAM,eAAe,GAAG,qBAAqB,CAAC,qBAAqB,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC;IACjG,OAAO,IAAI,6BAAa,CAAQ,CAAC,IAAa,EAAE,MAAyB,EAAE,OAAY,EAAE,EAAE;QACzF,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,OAAO,oBAAoB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,eAAe,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,EAAE;YACtE,OAAO,oBAAoB,CAAC,OAAO,CAAC,GAAG,WAAW,CAAC,YAAY,GAAG,SAAS,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC;QACtG,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,SAAS,CAAkB,UAAkC;IAC3E,OAAO,IAAI,6BAAa,CAAC,CAAC,IAAa,EAAE,MAAM,EAAE,OAAY,EAAE,EAAE;QAC/D,+CAA+C;QAE/C,MAAM,SAAS,GAAG,EAAkC,CAAC;QACrD,MAAM,MAAM,GAAa,EAAE,CAAC;QAE5B,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpB,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBACtD,IAAI,MAAM,CAAC,SAAS,EAAE,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;oBACrD,SAAS,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;gBAChC,CAAC;qBAAM,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;oBAC9B,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAA,cAAO,EAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAA,WAAI,EAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;AACL,CAAC;AAiDD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,eAAe,CAC7B,iBAAqD,EACrD,OAAsC;IAEtC,OAAO,IAAI,6BAAa,CAAC,CAAC,IAAa,EAAE,MAAM,EAAE,OAAY,EAAE,EAAE;QAC/D,+CAA+C;QAE/C,MAAM,SAAS,GAAG,EAA0C,CAAC;QAC7D,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAoB,IAAI,GAAG,CAAC,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,CAAC,CAAC;QAEvD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACtE,KAAK,MAAM,cAAc,IAAI,iBAAiB,EAAE,CAAC;gBAC/C,IAAI,iBAAiB,CAAC,cAAc,CAAC,EAAE,CAAC;oBACtC,MAAM,MAAM,GAAG,iBAAiB,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC;oBACtD,MAAM,SAAS,GAAG,iBAAiB,CAAC,cAAc,CAAC,CAAC,SAAS,CAAC;oBAE9D,IAAI,IAAA,cAAO,EAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;wBAC1B,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;wBACxD,IAAI,MAAM,CAAC,SAAS,EAAE,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;4BACrD,SAAS,CAAC,cAAc,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;wBAC3C,CAAC;6BAAM,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;4BAC9B,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,KAAK,cAAc,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;wBACjE,CAAC;wBACD,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;oBACnB,CAAC;yBAAM,IAAI,iBAAiB,CAAC,cAAc,CAAC,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;wBAC/D,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,+CAA+C,CAAC,CAAC;oBAChF,CAAC;gBACH,CAAC;YACH,CAAC;YAED,IAAI,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,MAAK,IAAI,EAAE,CAAC;gBAC7B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;oBACvB,IAAI,IAAA,cAAO,EAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAiB,CAAC,EAAE,CAAC;wBACvD,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,wCAAwC,CAAC,CAAC;oBAC9D,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;QACzC,CAAC;QAED,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC;YACxB,CAAC,CAAC,IAAA,cAAO,EAAC,SAAS,CAAC;YACpB,CAAC,CAAC,IAAA,WAAI,EAAC,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,WAAW,EAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,QAAQ,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3G,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,KAAK,CACnB,UAAkB;IAElB,OAAO,IAAI,6BAAa,CACtB,CAAC,IAAa,EAAE,MAA8C,EAAE,OAAY,EAAE,EAAE;QAC9E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,OAAO,IAAA,WAAI,EAAC,iBAAiB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvD,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,EAAE,CAAC;YACtC,OAAO,IAAA,WAAI,EACT,4BAA4B,UAAU,CAAC,MAAM,SAAS,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAC7F,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE;YAClD,OAAO,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;QAEH,OAAO,IAAA,iBAAU,EAAC,OAAO,CAAkE,CAAC;IAC9F,CAAC,CACF,CAAC;AACJ,CAAC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { fail, isKeyOf, mapResults, succeed, Success } from '../base';\nimport { Validator } from '../validation';\nimport { BaseConverter, ConverterResultTypes } from './baseConverter';\nimport { Converter } from './converter';\nimport { literal } from './basicConverters';\nimport { FieldConverters, ObjectConverter } from './objectConverter';\n\n/**\n * Represents a composite ID constructed of two strongly-typed string IDs\n * separated by a delimiter.\n * @public\n */\nexport interface ICompositeId<TCOLLECTIONID extends string, TITEMID extends string> {\n  readonly collectionId: TCOLLECTIONID;\n  readonly separator: string;\n  readonly itemId: TITEMID;\n}\n\n/**\n * Represents a partial composite ID, where separator is optional.\n * @public\n */\nexport interface IPartialCompositeId<TCOLLECTIONID extends string, TITEMID extends string> {\n  readonly collectionId: TCOLLECTIONID;\n  readonly separator?: string;\n  readonly itemId: TITEMID;\n}\n\n/**\n * Creates an {@link ObjectConverter | ObjectConverter} for a strongly-typed {@link Converters.ICompositeId | CompositeId}.\n * @param collectionIdValidator - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.\n * @param separator - The separator string.\n * @param itemIdValidator - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.\n * @returns An {@link ObjectConverter | ObjectConverter} for the strongly-typed composite ICompositeId.\n * @public\n */\nexport function compositeIdFromObject<TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(\n  collectionIdValidator: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>,\n  separator: string,\n  itemIdValidator: Converter<TITEMID, TC> | Validator<TITEMID, TC>\n): Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC> {\n  return new ObjectConverter<IPartialCompositeId<TCOLLECTIONID, TITEMID>, TC>({\n    collectionId: collectionIdValidator,\n    separator: literal(separator).optional(),\n    itemId: itemIdValidator\n  }).map<ICompositeId<TCOLLECTIONID, TITEMID>>((obj) =>\n    Success.with({\n      collectionId: obj.collectionId,\n      separator: obj.separator ?? separator,\n      itemId: obj.itemId\n    })\n  );\n}\n\n/**\n * Converts a composite ID string into a strongly-typed {@link Converters.ICompositeId | CompositeId}.\n * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.\n * @param separator - The separator string.\n * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.\n * @returns A {@link Converter | Converter} for the strongly-typed {@link Converters.ICompositeId | CompositeId}.\n * @public\n */\nexport function compositeIdFromString<TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(\n  collectionIdConverter: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>,\n  separator: string,\n  itemIdConverter: Converter<TITEMID, TC> | Validator<TITEMID, TC>\n): Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC> {\n  return new BaseConverter<ICompositeId<TCOLLECTIONID, TITEMID>, TC>(\n    (from: unknown, __self?: Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC>, context?: TC) => {\n      if (typeof from !== 'string') {\n        return fail(`${from}: invalid non-string composite ID.`);\n      }\n      const parts = from.split(separator);\n      if (parts.length < 2) {\n        return fail(`${from}: invalid composite ID - separator '${separator}' not found.`);\n      } else if (parts.length > 2) {\n        return fail(`${from}: invalid composite ID - multiple separators '${separator}.' found.`);\n      }\n      return collectionIdConverter.convert(parts[0], context).onSuccess((collectionId) => {\n        return itemIdConverter.convert(parts[1], context).onSuccess((itemId) => {\n          return succeed({\n            collectionId,\n            separator,\n            itemId\n          });\n        });\n      });\n    }\n  );\n}\n\n/**\n * Creates a {@link Converter | Converter} for a strongly-typed {@link Converters.ICompositeId | CompositeId} from\n * either a string or an object representation.\n * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.\n * @param separator - The separator string.\n * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.\n * @returns A {@link Converter | Converter} for the strongly-typed {@link Converters.ICompositeId | CompositeId}.\n * @public\n */\nexport function compositeId<TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(\n  collectionIdConverter: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>,\n  separator: string,\n  itemIdConverter: Converter<TITEMID, TC> | Validator<TITEMID, TC>\n): Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC> {\n  return compositeIdFromObject(collectionIdConverter, separator, itemIdConverter).or(\n    compositeIdFromString(collectionIdConverter, separator, itemIdConverter)\n  );\n}\n\n/**\n * Converts a strongly-typed {@link Converters.ICompositeId | CompositeId} into a string.\n * @param compositeIdConverter - {@link Converter | Converter} or {@link Validator | Validator} that validates/converts the composite ID string.\n * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.\n * @param separator - The separator string.\n * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.\n * @returns A {@link Converter | Converter} which produces a composite ID string.\n * @public\n */\nexport function compositeIdString<\n  T extends string,\n  TCOLLECTIONID extends string,\n  TITEMID extends string,\n  TC = unknown\n>(\n  compositeIdConverter: Validator<T, TC> | Converter<T, TC>,\n  collectionIdConverter: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>,\n  separator: string,\n  itemIdConverter: Converter<TITEMID, TC> | Validator<TITEMID, TC>\n): Converter<T, TC> {\n  const objectConverter = compositeIdFromObject(collectionIdConverter, separator, itemIdConverter);\n  return new BaseConverter<T, TC>((from: unknown, __self?: Converter<T, TC>, context?: TC) => {\n    if (typeof from === 'string') {\n      return compositeIdConverter.convert(from, context);\n    }\n    return objectConverter.convert(from, context).onSuccess((compositeId) => {\n      return compositeIdConverter.convert(`${compositeId.collectionId}${separator}${compositeId.itemId}`);\n    });\n  });\n}\n\n/**\n * Helper to create a {@link Converter | Converter} which converts a source object to a new object with a\n * different shape.\n *\n * @remarks\n * On successful conversion, the resulting {@link Converter | Converter} returns {@link Success | Success} with a new\n * object, which contains the converted values under the key names specified at initialization time.\n * It returns {@link Failure | Failure} with an error message if any fields to be extracted do not exist\n * or cannot be converted.\n *\n * Fields that succeed but convert to undefined are omitted from the result object but do not\n * fail the conversion.\n *\n * @param properties - An object with key names that correspond to the target object and an\n * appropriate {@link Conversion.FieldConverters | FieldConverter} which extracts and converts\n * a single filed from the source object.\n * @returns A {@link Converter | Converter} with the specified conversion behavior.\n * @public\n */\nexport function transform<T, TC = unknown>(properties: FieldConverters<T, TC>): Converter<T, TC> {\n  return new BaseConverter((from: unknown, __self, context?: TC) => {\n    // eslint bug thinks key is used before defined\n\n    const converted = {} as { [key in keyof T]: T[key] };\n    const errors: string[] = [];\n\n    for (const key in properties) {\n      if (properties[key]) {\n        const result = properties[key].convert(from, context);\n        if (result.isSuccess() && result.value !== undefined) {\n          converted[key] = result.value;\n        } else if (result.isFailure()) {\n          errors.push(result.message);\n        }\n      }\n    }\n\n    return errors.length === 0 ? succeed(converted) : fail(errors.join('\\n'));\n  });\n}\n\n/**\n * Per-property converters and configuration for each field in the destination object of\n * a {@link Converters.transformObject} call.\n * @public\n */\nexport type FieldTransformers<TSRC, TDEST, TC = unknown> = {\n  [key in keyof TDEST]: {\n    /**\n     * The name of the property in the source object to be converted.\n     */\n    from: keyof TSRC;\n    /**\n     * The converter or validator used to convert the property.\n     */\n    converter: Converter<TDEST[key], TC> | Validator<TDEST[key], TC>;\n    /**\n     * If `true` then a missing source property is ignored.  If `false` or omitted\n     * then a missing source property causes an error.\n     */\n    optional?: boolean;\n  };\n};\n\n/**\n * Options for a {@link Converters.transformObject} call.\n * @public\n */\n\nexport interface TransformObjectOptions<TSRC> {\n  /**\n   * If `strict` is `true` then unused properties in the source object cause\n   * an error, otherwise they are ignored.\n   */\n  strict: true;\n\n  /**\n   * An optional list of source properties to be ignored when strict mode\n   * is enabled.\n   */\n  ignore?: (keyof TSRC)[];\n\n  /**\n   * An optional description of this transform to be used for error messages.\n   */\n  description?: string;\n}\n\n/**\n * Helper to create a strongly-typed {@link Converter | Converter} which converts a source object to a\n * new object with a different shape.\n *\n * @remarks\n * On successful conversion, the resulting {@link Converter | Converter} returns {@link Success | Success} with a new\n * object, which contains the converted values under the key names specified at initialization time.\n *\n * It returns {@link Failure | Failure} with an error message if any fields to be extracted do not exist\n * or cannot be converted.\n *\n * @param destinationFields - An object with key names that correspond to the target object and an\n * appropriate {@link Converters.FieldTransformers | FieldTransformers} which specifies the name\n * of the corresponding property in the source object, the converter or validator used for each source\n * property and any other configuration to guide the conversion.\n * @param options - Options which affect the transformation.\n *\n * @returns A {@link Converter | Converter} with the specified conversion behavior.\n * @public\n */\nexport function transformObject<TSRC, TDEST, TC = unknown>(\n  destinationFields: FieldTransformers<TSRC, TDEST, TC>,\n  options?: TransformObjectOptions<TSRC>\n): Converter<TDEST, TC> {\n  return new BaseConverter((from: unknown, __self, context?: TC) => {\n    // eslint bug thinks key is used before defined\n\n    const converted = {} as { [key in keyof TDEST]: TDEST[key] };\n    const errors: string[] = [];\n    const used: Set<keyof TSRC> = new Set(options?.ignore);\n\n    if (typeof from === 'object' && !Array.isArray(from) && from !== null) {\n      for (const destinationKey in destinationFields) {\n        if (destinationFields[destinationKey]) {\n          const srcKey = destinationFields[destinationKey].from;\n          const converter = destinationFields[destinationKey].converter;\n\n          if (isKeyOf(srcKey, from)) {\n            const result = converter.convert(from[srcKey], context);\n            if (result.isSuccess() && result.value !== undefined) {\n              converted[destinationKey] = result.value;\n            } else if (result.isFailure()) {\n              errors.push(`${srcKey}->${destinationKey}: ${result.message}`);\n            }\n            used.add(srcKey);\n          } else if (destinationFields[destinationKey].optional !== true) {\n            errors.push(`${String(srcKey)}: required property missing in source object.`);\n          }\n        }\n      }\n\n      if (options?.strict === true) {\n        for (const key in from) {\n          if (isKeyOf(key, from) && !used.has(key as keyof TSRC)) {\n            errors.push(`${key}: unexpected property in source object`);\n          }\n        }\n      }\n    } else {\n      errors.push('source is not an object');\n    }\n\n    return errors.length === 0\n      ? succeed(converted)\n      : fail(options?.description ? `${options.description}:\\n  ${errors.join('\\n  ')}` : errors.join('\\n'));\n  });\n}\n\n/**\n * Creates a {@link Converter | Converter} that converts an array to a strongly-typed tuple,\n * using the supplied tuple of {@link Converter | Converters} to convert each element.\n *\n * @remarks\n * The resulting {@link Converter | Converter} returns {@link Success | Success} with a tuple\n * containing the converted values if all conversions succeed. Returns {@link Failure | Failure}\n * with an error message if the source is not an array, has the wrong number of elements, or\n * any element conversion fails.\n *\n * @example\n * ```typescript\n * const converter = tuple([Converters.string, Converters.number, Converters.boolean]);\n * // Type is Converter<[string, number, boolean]>\n *\n * converter.convert(['hello', 42, true]);\n * // Returns Success with ['hello', 42, true]\n * ```\n *\n * @param converters - A tuple of {@link Converter | Converters} defining the expected types\n * for each element of the tuple.\n * @returns A {@link Converter | Converter} that returns a strongly-typed tuple.\n * @public\n */\nexport function tuple<T extends readonly Converter<unknown, TC>[], TC = unknown>(\n  converters: [...T]\n): Converter<ConverterResultTypes<T>, TC> {\n  return new BaseConverter<ConverterResultTypes<T>, TC>(\n    (from: unknown, __self: Converter<ConverterResultTypes<T>, TC>, context?: TC) => {\n      if (!Array.isArray(from)) {\n        return fail(`Not an array: ${JSON.stringify(from)}`);\n      }\n\n      if (from.length !== converters.length) {\n        return fail(\n          `Expected array of length ${converters.length}, got ${from.length}: ${JSON.stringify(from)}`\n        );\n      }\n\n      const results = converters.map((converter, index) => {\n        return converter.convert(from[index], context);\n      });\n\n      return mapResults(results) as ReturnType<Converter<ConverterResultTypes<T>, TC>['convert']>;\n    }\n  );\n}\n"]}

package/lib/packlets/conversion/baseConverter.d.ts

@@ -64,63 +64,149 @@ export declare class BaseConverter<T, TC = unknown> implements Converter<T, TC>
      */
     constructor(converter: ConverterFunc<T, TC>, defaultContext?: TC, traits?: ConverterTraits);
     /**
-     * {@inheritDoc Converter.isOptional}
+     * Indicates whether this element is explicitly optional.
      */
     get isOptional(): boolean;
     /**
-     * {@inheritDoc Converter.brand}
+     * Returns the brand for a branded type.
      */
     get brand(): string | undefined;
     /**
-     * {@inheritDoc Converter.convert}
-     */
-    convert(from: unknown, context?: TC): Result<T>;
-    /**
-     * {@inheritDoc Converter.convertOptional}
+     * Converts from `unknown` to `<T>`. For objects and arrays, is guaranteed
+     * to return a new entity, with any unrecognized properties removed.
+     * @param from - The `unknown` to be converted
+     * @param context - An optional conversion context of type `<TC>` to be used in
+     * the conversion.
+     * @param selfOverride - An optional override for the `self` reference passed to the
+     * converter function, enabling outer converters (e.g. discriminated-object) to thread
+     * themselves through to per-arm converters for recursive parsing.
+     * @returns A {@link Result} with a {@link Success} and a value on success or an
+     * {@link Failure} with a a message on failure.
+     */
+    convert(from: unknown, context?: TC, selfOverride?: Converter<T, TC>): Result<T>;
+    /**
+     * Converts from `unknown` to `<T>` or `undefined`, as appropriate.
+     *
+     * @remarks
+     * If `onError` is `failOnError`, the converter succeeds for
+     * `undefined` or any convertible value, but reports an error
+     * if it encounters a value that cannot be converted.
+     *
+     * If `onError` is `ignoreErrors` (default) then values that
+     * cannot be converted result in a successful return of `undefined`.
+     * @param from - The `unknown` to be converted
+     * @param context - An optional conversion context of type `<TC>` to be used in
+     * the conversion.
+     * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
+     * @returns A {@link Result} with a {@link Success} and a value on success or an
+     * {@link Failure} with a a message on failure.
      */
     convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined>;
     /**
-     * {@inheritDoc Converter.optional}
+     * Creates a {@link Converter} for an optional value.
+     *
+     * @remarks
+     * If `onError` is `failOnError`, the resulting converter will accept `undefined`
+     * or a convertible value, but report an error if it encounters a value that cannot be
+     * converted.
+     *
+     * If `onError` is `ignoreErrors` (default) then values that cannot be converted will
+     * result in a successful return of `undefined`.
+     *
+     * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
+     * @returns A new {@link Converter} returning `<T|undefined>`.
      */
     optional(onError?: OnError): Converter<T | undefined, TC>;
     /**
-     * {@inheritDoc Converter.map}
+     * Creates a {@link Converter} which applies a (possibly) mapping conversion to
+     * the converted value of this {@link Converter}.
+     * @param mapper - A function which maps from the the result type `<T>` of this
+     * converter to a new result type `<T2>`.
+     * @returns A new {@link Converter} returning `<T2>`.
      */
     map<T2>(mapper: (from: T, context?: TC) => Result<T2>): Converter<T2, TC>;
     /**
-     * {@inheritDoc Converter.mapConvert}
+     * Creates a {@link Converter} which applies an additional supplied
+     * converter to the result of this converter.
+     *
+     * @param mapConverter - The {@link Converter} to be applied to the
+     * converted result from this {@link Converter}.
+     * @returns A new {@link Converter} returning `<T2>`.
      */
     mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC>;
     /**
-     * {@inheritDoc Converter.mapItems}
+     * Creates a {@link Converter} which maps the individual items of a collection
+     * resulting from this {@link Converter} using the supplied map function.
+     *
+     * @remarks
+     * Fails if `from` is not an array.
+     *
+     * @param mapper - The map function to be applied to each element of the
+     * result of this {@link Converter}.
+     * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapItems<TI>(mapper: (from: unknown, context?: TC) => Result<TI>): Converter<TI[], TC>;
     /**
-     * {@inheritDoc Converter.mapConvertItems}
+     * Creates a {@link Converter} which maps the individual items of a collection
+     * resulting from this {@link Converter} using the supplied {@link Converter}.
+     *
+     * @remarks
+     * Fails if `from` is not an array.
+     *
+     * @param mapConverter - The {@link Converter} to be applied to each element of the
+     * result of this {@link Converter}.
+     * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
     /**
-     * {@inheritDoc Converter.withAction}
+     * Creates a {@link Converter | Converter} which applies a supplied action after
+     * conversion. The supplied action is always called regardless of success or failure
+     * of the base conversion and is allowed to mutate the return type.
+     * @param action - The action to be applied.
      */
     withAction<TI>(action: (result: Result<T>, context?: TC) => Result<TI>): Converter<TI, TC>;
     /**
-     * {@inheritDoc Converter.withTypeGuard}
+     * Creates a {@link Converter} which applies a supplied type guard to the conversion
+     * result.
+     * @param guard - The type guard function to apply.
+     * @param message - Optional message to be reported if the type guard fails.
+     * @returns A new {@link Converter} returning `<TI>`.
      */
     withTypeGuard<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI, TC>;
     /**
-     * {@inheritDoc Converter.withItemTypeGuard}
+     * Creates a {@link Converter} which applies a supplied type guard to each member of
+     * the conversion result from this converter.
+     *
+     * @remarks
+     * Fails if the conversion result is not an array or if any member fails the
+     * type guard.
+     * @param guard - The type guard function to apply to each element.
+     * @param message - Optional message to be reported if the type guard fails.
+     * @returns A new {@link Converter} returning `<TI>`.
      */
     withItemTypeGuard<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI[], TC>;
     /**
-     * {@inheritDoc Converter.withConstraint}
+     * Creates a {@link Converter} which applies an optional constraint to the result
+     * of this conversion. If this {@link Converter} (the base converter) succeeds, the new
+     * converter calls a supplied constraint evaluation function with the conversion, which
+     * fails the entire conversion if the constraint function returns either `false` or
+     * {@link Failure | Failure<T>}.
+     *
+     * @param constraint - Constraint evaluation function.
+     * @param options - {@link Conversion.ConstraintOptions | Options} for constraint evaluation.
+     * @returns A new {@link Converter} returning `<T>`.
      */
     withConstraint(constraint: (val: T, context?: TC) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
     /**
-     * {@inheritDoc Converter.withBrand}
+     * Returns a converter which adds a brand to the type to prevent mismatched usage
+     * of simple types.
+     * @param brand - The brand to be applied to the result value.
+     * @returns A {@link Converter} returning `Brand<T, B>`.
      */
     withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC>;
     /**
-     * {@inheritDoc Converter.withDefault}
+     * Returns a Converter which always succeeds with a default value rather than failing.
+     * @param defaultValue - The default value to use if conversion fails.
      */
     withDefault<TD = T>(defaultValue: TD): DefaultingConverter<T, TD, TC>;
     or(other: Converter<T, TC>): Converter<T, TC>;
@@ -129,7 +215,10 @@ export declare class BaseConverter<T, TC = unknown> implements Converter<T, TC>
      */
     protected _context(supplied?: TC): TC | undefined;
     /**
-     * {@inheritDoc Converter.withFormattedError}
+     * Creates a new {@link Converter} which is derived from this one but which returns an
+     * error message formatted by the supplied formatter if the conversion fails.
+     * @param formatter - The formatter to be applied.
+     * @returns A new {@link Converter} returning `<T>`.
      */
     withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T, TC>;
     /**

package/lib/packlets/conversion/baseConverter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseConverter.d.ts","sourceRoot":"","sources":["../../../src/packlets/conversion/baseConverter.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,KAAK,EAAE,MAAM,EAA6B,MAAM,SAAS,CAAC;AACnE,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,OAAO,EACR,MAAM,aAAa,CAAC;AAGrB;;;GAGG;AACH,KAAK,iBAAiB,CAAC,KAAK,IAAI,KAAK,SAAS,SAAS,CAAC,MAAM,GAAG,CAAC,GAC9D,GAAG,SAAS,KAAK,CAAC,MAAM,OAAO,CAAC,GAC9B,iBAAiB,CAAC,OAAO,CAAC,EAAE,GAC5B,GAAG,GACL,KAAK,SAAS,KAAK,CAAC,MAAM,KAAK,CAAC,GAChC,iBAAiB,CAAC,KAAK,CAAC,EAAE,GAC1B,KAAK,CAAC;AAEV;;;;;GAKG;AACH,MAAM,MAAM,KAAK,CAAC,KAAK,IAAI,KAAK,SAAS,SAAS,CAAC,MAAM,GAAG,EAAE,OAAO,CAAC,GAAG,iBAAiB,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAExG;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEvF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,SAAS,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI;KAClF,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK;CACrE,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC;AAEtG;;;GAGG;AACH,qBAAa,aAAa,CAAC,CAAC,EAAE,EAAE,GAAG,OAAO,CAAE,YAAW,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC;IACrE;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,EAAE,CAAC;IACxC;;OAEG;IACH,SAAS,CAAC,WAAW,EAAE,OAAO,CAAS;IACvC;;OAEG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqE;IAEhG;;;;;;OAMG;gBACgB,SAAS,EAAE,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,cAAc,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,eAAe;IAOjG;;OAEG;IACH,IAAW,UAAU,IAAI,OAAO,CAE/B;IAED;;OAEG;IACH,IAAW,KAAK,IAAI,MAAM,GAAG,SAAS,CAErC;IAED;;;;;;;;;;;OAWG;IACI,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,YAAY,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAIvF;;;;;;;;;;;;;;;;OAgBG;IACI,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAS7F;;;;;;;;;;;;;OAaG;IACI,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,EAAE,EAAE,CAAC;IAOhE;;;;;;OAMG;IACI,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,CAAC;IAUhF;;;;;;;OAOG;IACI,UAAU,CAAC,EAAE,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,CAAC;IAUrE;;;;;;;;;;OAUG;IACI,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;IAW7F;;;;;;;;;;OAUG;IACI,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;IAWrF;;;;;OAKG;IACI,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,CAAC;IAMjG;;;;;;OAMG;IACI,aAAa,CAAC,EAAE,EACrB,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,IAAI,IAAI,EAAE,EAClD,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,CAAC,EAAE,EAAE,EAAE,CAAC;IAWpB;;;;;;;;;;OAUG;IACI,iBAAiB,CAAC,EAAE,EACzB,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,IAAI,IAAI,EAAE,EAClD,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;IAkBtB;;;;;;;;;;OAUG;IACI,cAAc,CACnB,UAAU,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,EACzD,OAAO,CAAC,EAAE,iBAAiB,GAC1B,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC;IAkBnB;;;;;OAKG;IACI,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC;IAYxE;;;OAGG;IACI,WAAW,CAAC,EAAE,GAAG,CAAC,EAAE,YAAY,EAAE,EAAE,GAAG,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;IAIrE,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC;IAQpD;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,SAAS;IAIjD;;;;;OAKG;IACI,kBAAkB,CAAC,SAAS,EAAE,wBAAwB,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC;IAQpF;;OAEG;IACH,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe;IAQrE;;OAEG;IACH,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI;CAKxD"}

package/lib/packlets/conversion/baseConverter.js

@@ -47,25 +47,48 @@ class BaseConverter {
         this._brand = traits === null || traits === void 0 ? void 0 : traits.brand;
     }
     /**
-     * {@inheritDoc Converter.isOptional}
+     * Indicates whether this element is explicitly optional.
      */
     get isOptional() {
         return this._isOptional;
     }
     /**
-     * {@inheritDoc Converter.brand}
+     * Returns the brand for a branded type.
      */
     get brand() {
         return this._brand;
     }
     /**
-     * {@inheritDoc Converter.convert}
+     * Converts from `unknown` to `<T>`. For objects and arrays, is guaranteed
+     * to return a new entity, with any unrecognized properties removed.
+     * @param from - The `unknown` to be converted
+     * @param context - An optional conversion context of type `<TC>` to be used in
+     * the conversion.
+     * @param selfOverride - An optional override for the `self` reference passed to the
+     * converter function, enabling outer converters (e.g. discriminated-object) to thread
+     * themselves through to per-arm converters for recursive parsing.
+     * @returns A {@link Result} with a {@link Success} and a value on success or an
+     * {@link Failure} with a a message on failure.
      */
-    convert(from, context) {
-        return this._converter(from, this, context !== null && context !== void 0 ? context : this._defaultContext);
+    convert(from, context, selfOverride) {
+        return this._converter(from, selfOverride !== null && selfOverride !== void 0 ? selfOverride : this, context !== null && context !== void 0 ? context : this._defaultContext);
     }
     /**
-     * {@inheritDoc Converter.convertOptional}
+     * Converts from `unknown` to `<T>` or `undefined`, as appropriate.
+     *
+     * @remarks
+     * If `onError` is `failOnError`, the converter succeeds for
+     * `undefined` or any convertible value, but reports an error
+     * if it encounters a value that cannot be converted.
+     *
+     * If `onError` is `ignoreErrors` (default) then values that
+     * cannot be converted result in a successful return of `undefined`.
+     * @param from - The `unknown` to be converted
+     * @param context - An optional conversion context of type `<TC>` to be used in
+     * the conversion.
+     * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
+     * @returns A {@link Result} with a {@link Success} and a value on success or an
+     * {@link Failure} with a a message on failure.
      */
     convertOptional(from, context, onError) {
         const result = this._converter(from, this, this._context(context));
@@ -76,7 +99,18 @@ class BaseConverter {
         return result;
     }
     /**
-     * {@inheritDoc Converter.optional}
+     * Creates a {@link Converter} for an optional value.
+     *
+     * @remarks
+     * If `onError` is `failOnError`, the resulting converter will accept `undefined`
+     * or a convertible value, but report an error if it encounters a value that cannot be
+     * converted.
+     *
+     * If `onError` is `ignoreErrors` (default) then values that cannot be converted will
+     * result in a successful return of `undefined`.
+     *
+     * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
+     * @returns A new {@link Converter} returning `<T|undefined>`.
      */
     optional(onError) {
         return new BaseConverter((from, __self, context) => {
@@ -85,7 +119,11 @@ class BaseConverter {
         })._with(this._traits({ isOptional: true }));
     }
     /**
-     * {@inheritDoc Converter.map}
+     * Creates a {@link Converter} which applies a (possibly) mapping conversion to
+     * the converted value of this {@link Converter}.
+     * @param mapper - A function which maps from the the result type `<T>` of this
+     * converter to a new result type `<T2>`.
+     * @returns A new {@link Converter} returning `<T2>`.
      */
     map(mapper) {
         return new BaseConverter((from, __self, context) => {
@@ -97,7 +135,12 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.mapConvert}
+     * Creates a {@link Converter} which applies an additional supplied
+     * converter to the result of this converter.
+     *
+     * @param mapConverter - The {@link Converter} to be applied to the
+     * converted result from this {@link Converter}.
+     * @returns A new {@link Converter} returning `<T2>`.
      */
     mapConvert(mapConverter) {
         return new BaseConverter((from, __self, context) => {
@@ -109,7 +152,15 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.mapItems}
+     * Creates a {@link Converter} which maps the individual items of a collection
+     * resulting from this {@link Converter} using the supplied map function.
+     *
+     * @remarks
+     * Fails if `from` is not an array.
+     *
+     * @param mapper - The map function to be applied to each element of the
+     * result of this {@link Converter}.
+     * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapItems(mapper) {
         return new BaseConverter((from, __self, context) => {
@@ -122,7 +173,15 @@ class BaseConverter {
         });
     }
     /**
-     * {@inheritDoc Converter.mapConvertItems}
+     * Creates a {@link Converter} which maps the individual items of a collection
+     * resulting from this {@link Converter} using the supplied {@link Converter}.
+     *
+     * @remarks
+     * Fails if `from` is not an array.
+     *
+     * @param mapConverter - The {@link Converter} to be applied to each element of the
+     * result of this {@link Converter}.
+     * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapConvertItems(mapConverter) {
         return new BaseConverter((from, __self, context) => {
@@ -135,7 +194,10 @@ class BaseConverter {
         });
     }
     /**
-     * {@inheritDoc Converter.withAction}
+     * Creates a {@link Converter | Converter} which applies a supplied action after
+     * conversion. The supplied action is always called regardless of success or failure
+     * of the base conversion and is allowed to mutate the return type.
+     * @param action - The action to be applied.
      */
     withAction(action) {
         return new BaseConverter((from, __self, context) => {
@@ -143,7 +205,11 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.withTypeGuard}
+     * Creates a {@link Converter} which applies a supplied type guard to the conversion
+     * result.
+     * @param guard - The type guard function to apply.
+     * @param message - Optional message to be reported if the type guard fails.
+     * @returns A new {@link Converter} returning `<TI>`.
      */
     withTypeGuard(guard, message) {
         return new BaseConverter((from, __self, context) => {
@@ -156,7 +222,15 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.withItemTypeGuard}
+     * Creates a {@link Converter} which applies a supplied type guard to each member of
+     * the conversion result from this converter.
+     *
+     * @remarks
+     * Fails if the conversion result is not an array or if any member fails the
+     * type guard.
+     * @param guard - The type guard function to apply to each element.
+     * @param message - Optional message to be reported if the type guard fails.
+     * @returns A new {@link Converter} returning `<TI>`.
      */
     withItemTypeGuard(guard, message) {
         return new BaseConverter((from, __self, context) => {
@@ -174,7 +248,15 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.withConstraint}
+     * Creates a {@link Converter} which applies an optional constraint to the result
+     * of this conversion. If this {@link Converter} (the base converter) succeeds, the new
+     * converter calls a supplied constraint evaluation function with the conversion, which
+     * fails the entire conversion if the constraint function returns either `false` or
+     * {@link Failure | Failure<T>}.
+     *
+     * @param constraint - Constraint evaluation function.
+     * @param options - {@link Conversion.ConstraintOptions | Options} for constraint evaluation.
+     * @returns A new {@link Converter} returning `<T>`.
      */
     withConstraint(constraint, options) {
         return new BaseConverter((from, __self, context) => {
@@ -193,7 +275,10 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.withBrand}
+     * Returns a converter which adds a brand to the type to prevent mismatched usage
+     * of simple types.
+     * @param brand - The brand to be applied to the result value.
+     * @returns A {@link Converter} returning `Brand<T, B>`.
      */
     withBrand(brand) {
         if (this._brand) {
@@ -206,7 +291,8 @@ class BaseConverter {
         })._with(this._traits({ brand }));
     }
     /**
-     * {@inheritDoc Converter.withDefault}
+     * Returns a Converter which always succeeds with a default value rather than failing.
+     * @param defaultValue - The default value to use if conversion fails.
      */
     withDefault(defaultValue) {
         return new defaultingConverter_1.GenericDefaultingConverter(this, defaultValue);
@@ -225,7 +311,10 @@ class BaseConverter {
         return supplied !== null && supplied !== void 0 ? supplied : this._defaultContext;
     }
     /**
-     * {@inheritDoc Converter.withFormattedError}
+     * Creates a new {@link Converter} which is derived from this one but which returns an
+     * error message formatted by the supplied formatter if the conversion fails.
+     * @param formatter - The formatter to be applied.
+     * @returns A new {@link Converter} returning `<T>`.
      */
     withFormattedError(formatter) {
         return new BaseConverter((from, __self, context) => {

package/lib/packlets/conversion/baseConverter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseConverter.js","sourceRoot":"","sources":["../../../src/packlets/conversion/baseConverter.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,kCAAmE;AASnE,+DAAmE;AAmDnE;;;GAGG;AACH,MAAa,aAAa;IAgBxB;;;;;;OAMG;IACH,YAAmB,SAA+B,EAAE,cAAmB,EAAE,MAAwB;QAlBjG;;WAEG;QACO,gBAAW,GAAY,KAAK,CAAC;QAgBrC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,eAAe,GAAG,cAAc,CAAC;QACtC,IAAI,CAAC,WAAW,GAAG,CAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,UAAU,MAAK,IAAI,CAAC;QAC/C,IAAI,CAAC,MAAM,GAAG,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,IAAW,UAAU;QACnB,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,IAAW,KAAK;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;OAWG;IACI,OAAO,CAAC,IAAa,EAAE,OAAY,EAAE,YAA+B;QACzE,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,YAAY,aAAZ,YAAY,cAAZ,YAAY,GAAI,IAAI,EAAE,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,IAAI,CAAC,eAAe,CAAC,CAAC;IACtF,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACI,eAAe,CAAC,IAAa,EAAE,OAAY,EAAE,OAAiB;QACnE,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QACnE,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;YACvB,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,cAAc,CAAC;YACpC,OAAO,IAAI,KAAK,SAAS,IAAI,OAAO,KAAK,cAAc,CAAC,CAAC,CAAC,IAAA,cAAO,EAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QACxF,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;;;OAaG;IACI,QAAQ,CAAC,OAAiB;QAC/B,OAAO,IAAI,aAAa,CAAC,CAAC,IAAa,EAAE,MAAoC,EAAE,OAAY,EAAE,EAAE;YAC7F,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,aAAa,CAAC;YACnC,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;OAMG;IACI,GAAG,CAAK,MAA6C;QAC1D,OAAO,IAAI,aAAa,CAAS,CAAC,IAAa,EAAE,MAAyB,EAAE,OAAY,EAAE,EAAE;YAC1F,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YACxE,IAAI,WAAW,CAAC,SAAS,EAAE,EAAE,CAAC;gBAC5B,OAAO,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YAC3D,CAAC;YACD,OAAO,IAAA,WAAI,EAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;;;OAOG;IACI,UAAU,CAAK,YAA2B;QAC/C,OAAO,IAAI,aAAa,CAAS,CAAC,IAAa,EAAE,MAAyB,EAAE,OAAY,EAAE,EAAE;YAC1F,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YACxE,IAAI,WAAW,CAAC,SAAS,EAAE,EAAE,CAAC;gBAC5B,OAAO,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YACzE,CAAC;YACD,OAAO,IAAA,WAAI,EAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;;;;;;OAUG;IACI,QAAQ,CAAK,MAAmD;QACrE,OAAO,IAAI,aAAa,CAAW,CAAC,IAAa,EAAE,MAA2B,EAAE,OAAY,EAAE,EAAE;YAC9F,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;gBAC7E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBACzB,OAAO,IAAA,iBAAU,EAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;gBACzE,CAAC;gBACD,OAAO,IAAA,WAAI,EAAC,iCAAiC,CAAC,CAAC;YACjD,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;OAUG;IACI,eAAe,CAAK,YAAoC;QAC7D,OAAO,IAAI,aAAa,CAAW,CAAC,IAAa,EAAE,MAA2B,EAAE,OAAY,EAAE,EAAE;YAC9F,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;gBAC7E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBACzB,OAAO,IAAA,iBAAU,EAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;gBACvF,CAAC;gBACD,OAAO,IAAA,WAAI,EAAC,iCAAiC,CAAC,CAAC;YACjD,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACI,UAAU,CAAK,MAAuD;QAC3E,OAAO,IAAI,aAAa,CAAS,CAAC,IAAa,EAAE,MAAyB,EAAE,OAAY,EAAE,EAAE;YAC1F,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7F,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;;OAMG;IACI,aAAa,CAClB,KAAkD,EAClD,OAAgB;QAEhB,OAAO,IAAI,aAAa,CAAS,CAAC,IAAa,EAAE,MAAyB,EAAE,OAAY,EAAE,EAAE;YAC1F,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;gBAC7E,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,cAAc,CAAC;gBACpC,OAAO,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;oBACzC,CAAC,CAAC,IAAA,cAAO,EAAC,KAAK,CAAC;oBAChB,CAAC,CAAC,IAAA,WAAI,EAAC,GAAG,OAAO,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAClD,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;;;;;;OAUG;IACI,iBAAiB,CACtB,KAAkD,EAClD,OAAgB;QAEhB,OAAO,IAAI,aAAa,CAAW,CAAC,IAAa,EAAE,MAA2B,EAAE,OAAY,EAAE,EAAE;YAC9F,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;gBAC7E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBACzB,OAAO,IAAA,iBAAU,EACf,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;wBACd,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,cAAc,CAAC;wBACpC,OAAO,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;4BACrC,CAAC,CAAC,IAAA,cAAO,EAAC,CAAC,CAAC;4BACZ,CAAC,CAAC,IAAA,WAAI,EAAC,GAAG,OAAO,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBAClD,CAAC,CAAC,CACH,CAAC;gBACJ,CAAC;gBACD,OAAO,IAAA,WAAI,EAAC,uCAAuC,CAAC,CAAC;YACvD,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;;;;;;OAUG;IACI,cAAc,CACnB,UAAyD,EACzD,OAA2B;QAE3B,OAAO,IAAI,aAAa,CAAQ,CAAC,IAAa,EAAE,MAAwB,EAAE,OAAY,EAAE,EAAE;;YACxF,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YACnE,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;gBACvB,MAAM,gBAAgB,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;gBAC1E,IAAI,OAAO,gBAAgB,KAAK,SAAS,EAAE,CAAC;oBAC1C,OAAO,gBAAgB;wBACrB,CAAC,CAAC,MAAM;wBACR,CAAC,CAAC,IAAA,WAAI,EACF,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,WAAW,mCAAI,0BAA0B,EAAE,CAC3F,CAAC;gBACR,CAAC;gBACD,OAAO,gBAAgB,CAAC;YAC1B,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACI,SAAS,CAAmB,KAAQ;QACzC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,CAAC,MAAM,WAAW,KAAK,IAAI,CAAC,CAAC;QACrF,CAAC;QAED,OAAO,IAAI,aAAa,CAAkB,CAAC,IAAa,EAAE,MAAwB,EAAE,OAAY,EAAE,EAAE;YAClG,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE;gBACzE,OAAO,IAAA,cAAO,EAAC,CAAgB,CAAC,CAAC;YACnC,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACpC,CAAC;IAED;;;OAGG;IACI,WAAW,CAAS,YAAgB;QACzC,OAAO,IAAI,gDAA0B,CAAY,IAAI,EAAE,YAAY,CAAC,CAAC;IACvE,CAAC;IAEM,EAAE,CAAC,KAAuB;QAC/B,OAAO,IAAI,aAAa,CAAQ,CAAC,IAAa,EAAE,MAAwB,EAAE,OAAY,EAAE,EAAE;YACxF,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE;gBACxE,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YACrD,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACO,QAAQ,CAAC,QAAa;QAC9B,OAAO,QAAQ,aAAR,QAAQ,cAAR,QAAQ,GAAI,IAAI,CAAC,eAAe,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACI,kBAAkB,CAAC,SAAuC;QAC/D,OAAO,IAAI,aAAa,CAAQ,CAAC,IAAa,EAAE,MAAwB,EAAE,OAAY,EAAE,EAAE;YACxF,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE;gBAC3E,OAAO,IAAA,WAAI,EAAC,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAC5D,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;;OAEG;IACO,OAAO,CAAC,MAAiC;QACjD,uBACE,UAAU,EAAE,IAAI,CAAC,UAAU,EAC3B,KAAK,EAAE,IAAI,CAAC,KAAK,IACd,CAAC,MAAM,aAAN,MAAM,cAAN,MAAM,GAAI,EAAE,CAAC,EACjB;IACJ,CAAC;IAED;;OAEG;IACO,KAAK,CAAC,MAAgC;QAC9C,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,KAAK,IAAI,CAAC;QAC9C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AArWD,sCAqWC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\nimport { Brand, Result, fail, mapResults, succeed } from '../base';\nimport {\n  ConstraintOptions,\n  ConversionErrorFormatter,\n  Converter,\n  ConverterTraits,\n  DefaultingConverter,\n  OnError\n} from './converter';\nimport { GenericDefaultingConverter } from './defaultingConverter';\n\n/**\n * Internal helper that recursively unwraps converter and array types.\n * @internal\n */\ntype InnerInferredType<TCONV> = TCONV extends Converter<infer TTO>\n  ? TTO extends Array<infer TTOELEM>\n    ? InnerInferredType<TTOELEM>[]\n    : TTO\n  : TCONV extends Array<infer TELEM>\n  ? InnerInferredType<TELEM>[]\n  : TCONV;\n\n/**\n * Infers the type that will be returned by an instantiated converter. Works\n * for complex as well as simple types, including nested arrays.\n * @example `Infer<typeof Converters.mapOf(Converters.stringArray)>` is `Map<string, string[]>`\n * @public\n */\nexport type Infer<TCONV> = TCONV extends Converter<infer TTO, unknown> ? InnerInferredType<TTO> : never;\n\n/**\n * Deprecated name for {@link Conversion.Infer | Infer\n * } retained for compatibility.\n * @deprecated Use {@link Conversion.Infer | Infer} instead.\n * @public\n */\nexport type ConvertedToType<TCONV> = Infer<TCONV>;\n\n/**\n * Helper type to extract the result type from a {@link Converter | Converter}.\n * For simple single-level extraction. For complex nested types, use {@link Conversion.Infer | Infer}.\n * @public\n */\nexport type ConverterResultType<C> = C extends Converter<infer T, unknown> ? T : never;\n\n/**\n * Helper type to map a tuple of {@link Converter | Converters} to a tuple of their result types.\n * @public\n */\nexport type ConverterResultTypes<T extends readonly Converter<unknown, unknown>[]> = {\n  [K in keyof T]: T[K] extends Converter<infer R, unknown> ? R : never;\n};\n\n/**\n * Function signature for a converter function.\n * @public\n */\nexport type ConverterFunc<T, TC> = (from: unknown, self: Converter<T, TC>, context?: TC) => Result<T>;\n\n/**\n * Base templated wrapper to simplify creation of new {@link Converter}s.\n * @public\n */\nexport class BaseConverter<T, TC = unknown> implements Converter<T, TC> {\n  /**\n   * @internal\n   */\n  protected readonly _defaultContext?: TC;\n  /**\n   * @internal\n   */\n  protected _isOptional: boolean = false;\n  /**\n   * @internal\n   */\n  protected _brand?: string;\n\n  private readonly _converter: (from: unknown, self: Converter<T, TC>, context?: TC) => Result<T>;\n\n  /**\n   * Constructs a new {@link Converter} which uses the supplied function to perform the conversion.\n   * @param converter - The conversion function to be applied.\n   * @param defaultContext - Optional conversion context to be used by default.\n   * @param traits - Optional {@link Conversion.ConverterTraits | traits} to be assigned to the resulting\n   * converter.\n   */\n  public constructor(converter: ConverterFunc<T, TC>, defaultContext?: TC, traits?: ConverterTraits) {\n    this._converter = converter;\n    this._defaultContext = defaultContext;\n    this._isOptional = traits?.isOptional === true;\n    this._brand = traits?.brand;\n  }\n\n  /**\n   * Indicates whether this element is explicitly optional.\n   */\n  public get isOptional(): boolean {\n    return this._isOptional;\n  }\n\n  /**\n   * Returns the brand for a branded type.\n   */\n  public get brand(): string | undefined {\n    return this._brand;\n  }\n\n  /**\n   * Converts from `unknown` to `<T>`. For objects and arrays, is guaranteed\n   * to return a new entity, with any unrecognized properties removed.\n   * @param from - The `unknown` to be converted\n   * @param context - An optional conversion context of type `<TC>` to be used in\n   * the conversion.\n   * @param selfOverride - An optional override for the `self` reference passed to the\n   * converter function, enabling outer converters (e.g. discriminated-object) to thread\n   * themselves through to per-arm converters for recursive parsing.\n   * @returns A {@link Result} with a {@link Success} and a value on success or an\n   * {@link Failure} with a a message on failure.\n   */\n  public convert(from: unknown, context?: TC, selfOverride?: Converter<T, TC>): Result<T> {\n    return this._converter(from, selfOverride ?? this, context ?? this._defaultContext);\n  }\n\n  /**\n   * Converts from `unknown` to `<T>` or `undefined`, as appropriate.\n   *\n   * @remarks\n   * If `onError` is `failOnError`, the converter succeeds for\n   * `undefined` or any convertible value, but reports an error\n   * if it encounters a value that cannot be converted.\n   *\n   * If `onError` is `ignoreErrors` (default) then values that\n   * cannot be converted result in a successful return of `undefined`.\n   * @param from - The `unknown` to be converted\n   * @param context - An optional conversion context of type `<TC>` to be used in\n   * the conversion.\n   * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).\n   * @returns A {@link Result} with a {@link Success} and a value on success or an\n   * {@link Failure} with a a message on failure.\n   */\n  public convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined> {\n    const result = this._converter(from, this, this._context(context));\n    if (result.isFailure()) {\n      onError = onError ?? 'ignoreErrors';\n      return from === undefined || onError === 'ignoreErrors' ? succeed(undefined) : result;\n    }\n    return result;\n  }\n\n  /**\n   * Creates a {@link Converter} for an optional value.\n   *\n   * @remarks\n   * If `onError` is `failOnError`, the resulting converter will accept `undefined`\n   * or a convertible value, but report an error if it encounters a value that cannot be\n   * converted.\n   *\n   * If `onError` is `ignoreErrors` (default) then values that cannot be converted will\n   * result in a successful return of `undefined`.\n   *\n   * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).\n   * @returns A new {@link Converter} returning `<T|undefined>`.\n   */\n  public optional(onError?: OnError): Converter<T | undefined, TC> {\n    return new BaseConverter((from: unknown, __self: Converter<T | undefined, TC>, context?: TC) => {\n      onError = onError ?? 'failOnError';\n      return this.convertOptional(from, this._context(context), onError);\n    })._with(this._traits({ isOptional: true }));\n  }\n\n  /**\n   * Creates a {@link Converter} which applies a (possibly) mapping conversion to\n   * the converted value of this {@link Converter}.\n   * @param mapper - A function which maps from the the result type `<T>` of this\n   * converter to a new result type `<T2>`.\n   * @returns A new {@link Converter} returning `<T2>`.\n   */\n  public map<T2>(mapper: (from: T, context?: TC) => Result<T2>): Converter<T2, TC> {\n    return new BaseConverter<T2, TC>((from: unknown, __self: Converter<T2, TC>, context?: TC) => {\n      const innerResult = this._converter(from, this, this._context(context));\n      if (innerResult.isSuccess()) {\n        return mapper(innerResult.value, this._context(context));\n      }\n      return fail(innerResult.message);\n    })._with(this._traits());\n  }\n\n  /**\n   * Creates a {@link Converter} which applies an additional supplied\n   * converter to the result of this converter.\n   *\n   * @param mapConverter - The {@link Converter} to be applied to the\n   * converted result from this {@link Converter}.\n   * @returns A new {@link Converter} returning `<T2>`.\n   */\n  public mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC> {\n    return new BaseConverter<T2, TC>((from: unknown, __self: Converter<T2, TC>, context?: TC) => {\n      const innerResult = this._converter(from, this, this._context(context));\n      if (innerResult.isSuccess()) {\n        return mapConverter.convert(innerResult.value, this._context(context));\n      }\n      return fail(innerResult.message);\n    })._with(this._traits());\n  }\n\n  /**\n   * Creates a {@link Converter} which maps the individual items of a collection\n   * resulting from this {@link Converter} using the supplied map function.\n   *\n   * @remarks\n   * Fails if `from` is not an array.\n   *\n   * @param mapper - The map function to be applied to each element of the\n   * result of this {@link Converter}.\n   * @returns A new {@link Converter} returning `<TI[]>`.\n   */\n  public mapItems<TI>(mapper: (from: unknown, context?: TC) => Result<TI>): Converter<TI[], TC> {\n    return new BaseConverter<TI[], TC>((from: unknown, __self: Converter<TI[], TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((items) => {\n        if (Array.isArray(items)) {\n          return mapResults(items.map((i) => mapper(i, this._context(context))));\n        }\n        return fail('Cannot map items - not an array');\n      });\n    });\n  }\n\n  /**\n   * Creates a {@link Converter} which maps the individual items of a collection\n   * resulting from this {@link Converter} using the supplied {@link Converter}.\n   *\n   * @remarks\n   * Fails if `from` is not an array.\n   *\n   * @param mapConverter - The {@link Converter} to be applied to each element of the\n   * result of this {@link Converter}.\n   * @returns A new {@link Converter} returning `<TI[]>`.\n   */\n  public mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC> {\n    return new BaseConverter<TI[], TC>((from: unknown, __self: Converter<TI[], TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((items) => {\n        if (Array.isArray(items)) {\n          return mapResults(items.map((i) => mapConverter.convert(i, this._context(context))));\n        }\n        return fail('Cannot map items - not an array');\n      });\n    });\n  }\n\n  /**\n   * Creates a {@link Converter | Converter} which applies a supplied action after\n   * conversion. The supplied action is always called regardless of success or failure\n   * of the base conversion and is allowed to mutate the return type.\n   * @param action - The action to be applied.\n   */\n  public withAction<TI>(action: (result: Result<T>, context?: TC) => Result<TI>): Converter<TI, TC> {\n    return new BaseConverter<TI, TC>((from: unknown, __self: Converter<TI, TC>, context?: TC) => {\n      return action(this._converter(from, this, this._context(context)), this._context(context));\n    })._with(this._traits());\n  }\n\n  /**\n   * Creates a {@link Converter} which applies a supplied type guard to the conversion\n   * result.\n   * @param guard - The type guard function to apply.\n   * @param message - Optional message to be reported if the type guard fails.\n   * @returns A new {@link Converter} returning `<TI>`.\n   */\n  public withTypeGuard<TI>(\n    guard: (from: unknown, context?: TC) => from is TI,\n    message?: string\n  ): Converter<TI, TC> {\n    return new BaseConverter<TI, TC>((from: unknown, __self: Converter<TI, TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((inner) => {\n        message = message ?? 'invalid type';\n        return guard(inner, this._context(context))\n          ? succeed(inner)\n          : fail(`${message}: ${JSON.stringify(from)}`);\n      });\n    })._with(this._traits());\n  }\n\n  /**\n   * Creates a {@link Converter} which applies a supplied type guard to each member of\n   * the conversion result from this converter.\n   *\n   * @remarks\n   * Fails if the conversion result is not an array or if any member fails the\n   * type guard.\n   * @param guard - The type guard function to apply to each element.\n   * @param message - Optional message to be reported if the type guard fails.\n   * @returns A new {@link Converter} returning `<TI>`.\n   */\n  public withItemTypeGuard<TI>(\n    guard: (from: unknown, context?: TC) => from is TI,\n    message?: string\n  ): Converter<TI[], TC> {\n    return new BaseConverter<TI[], TC>((from: unknown, __self: Converter<TI[], TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((items) => {\n        if (Array.isArray(items)) {\n          return mapResults(\n            items.map((i) => {\n              message = message ?? 'invalid type';\n              return guard(i, this._context(context))\n                ? succeed(i)\n                : fail(`${message}: ${JSON.stringify(from)}`);\n            })\n          );\n        }\n        return fail('Cannot guard item type - not an array');\n      });\n    })._with(this._traits());\n  }\n\n  /**\n   * Creates a {@link Converter} which applies an optional constraint to the result\n   * of this conversion. If this {@link Converter} (the base converter) succeeds, the new\n   * converter calls a supplied constraint evaluation function with the conversion, which\n   * fails the entire conversion if the constraint function returns either `false` or\n   * {@link Failure | Failure<T>}.\n   *\n   * @param constraint - Constraint evaluation function.\n   * @param options - {@link Conversion.ConstraintOptions | Options} for constraint evaluation.\n   * @returns A new {@link Converter} returning `<T>`.\n   */\n  public withConstraint(\n    constraint: (val: T, context?: TC) => boolean | Result<T>,\n    options?: ConstraintOptions\n  ): Converter<T, TC> {\n    return new BaseConverter<T, TC>((from: unknown, __self: Converter<T, TC>, context?: TC) => {\n      const result = this._converter(from, this, this._context(context));\n      if (result.isSuccess()) {\n        const constraintResult = constraint(result.value, this._context(context));\n        if (typeof constraintResult === 'boolean') {\n          return constraintResult\n            ? result\n            : fail(\n                `\"${JSON.stringify(result.value)}\": ${options?.description ?? 'does not meet constraint'}`\n              );\n        }\n        return constraintResult;\n      }\n      return result;\n    })._with(this._traits());\n  }\n\n  /**\n   * Returns a converter which adds a brand to the type to prevent mismatched usage\n   * of simple types.\n   * @param brand - The brand to be applied to the result value.\n   * @returns A {@link Converter} returning `Brand<T, B>`.\n   */\n  public withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC> {\n    if (this._brand) {\n      throw new Error(`Cannot replace existing brand \"${this._brand}\" with \"${brand}\".`);\n    }\n\n    return new BaseConverter<Brand<T, B>, TC>((from: unknown, __self: Converter<T, TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((v) => {\n        return succeed(v as Brand<T, B>);\n      });\n    })._with(this._traits({ brand }));\n  }\n\n  /**\n   * Returns a Converter which always succeeds with a default value rather than failing.\n   * @param defaultValue - The default value to use if conversion fails.\n   */\n  public withDefault<TD = T>(defaultValue: TD): DefaultingConverter<T, TD, TC> {\n    return new GenericDefaultingConverter<T, TD, TC>(this, defaultValue);\n  }\n\n  public or(other: Converter<T, TC>): Converter<T, TC> {\n    return new BaseConverter<T, TC>((from: unknown, __self: Converter<T, TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onFailure(() => {\n        return other.convert(from, this._context(context));\n      });\n    });\n  }\n\n  /**\n   * @internal\n   */\n  protected _context(supplied?: TC): TC | undefined {\n    return supplied ?? this._defaultContext;\n  }\n\n  /**\n   * Creates a new {@link Converter} which is derived from this one but which returns an\n   * error message formatted by the supplied formatter if the conversion fails.\n   * @param formatter - The formatter to be applied.\n   * @returns A new {@link Converter} returning `<T>`.\n   */\n  public withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T, TC> {\n    return new BaseConverter<T, TC>((from: unknown, __self: Converter<T, TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onFailure((msg) => {\n        return fail(formatter(from, msg, this._context(context)));\n      });\n    })._with(this._traits());\n  }\n\n  /**\n   * @internal\n   */\n  protected _traits(traits?: Partial<ConverterTraits>): ConverterTraits {\n    return {\n      isOptional: this.isOptional,\n      brand: this.brand,\n      ...(traits ?? {})\n    };\n  }\n\n  /**\n   * @internal\n   */\n  protected _with(traits: Partial<ConverterTraits>): this {\n    this._isOptional = traits.isOptional === true;\n    this._brand = traits.brand;\n    return this;\n  }\n}\n"]}