@fgv/ts-utils 5.0.2 → 5.1.0-0

package/lib/packlets/validation/classes.js

@@ -21,12 +21,14 @@
  * SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TypeGuardValidator = exports.StringValidator = exports.OneOfValidator = exports.ObjectValidator = exports.NumberValidator = exports.BooleanValidator = exports.ArrayValidator = void 0;
+exports.TypeGuardValidator = exports.StringValidator = exports.OneOfValidator = exports.ObjectValidator = exports.NumberValidator = exports.CompositeIdValidator = exports.BooleanValidator = exports.ArrayValidator = void 0;
 /* c8 ignore start */
 var array_1 = require("./array");
 Object.defineProperty(exports, "ArrayValidator", { enumerable: true, get: function () { return array_1.ArrayValidator; } });
 var boolean_1 = require("./boolean");
 Object.defineProperty(exports, "BooleanValidator", { enumerable: true, get: function () { return boolean_1.BooleanValidator; } });
+var compositeId_1 = require("./compositeId");
+Object.defineProperty(exports, "CompositeIdValidator", { enumerable: true, get: function () { return compositeId_1.CompositeIdValidator; } });
 var number_1 = require("./number");
 Object.defineProperty(exports, "NumberValidator", { enumerable: true, get: function () { return number_1.NumberValidator; } });
 var object_1 = require("./object");

package/lib/packlets/validation/compositeId.d.ts

@@ -0,0 +1,29 @@
+import { Failure } from '../base';
+import { Validator } from './validator';
+import { ValidatorBase, ValidatorBaseConstructorParams } from './validatorBase';
+/**
+ * Parameters used to construct a {@link Validation.Classes.StringValidator | StringValidator}.
+ * @public
+ */
+export interface CompositeIdValidatorConstructorParams<T extends string = string, TCOLLECTIONID extends string = string, TITEMID extends string = string, TC = unknown> extends ValidatorBaseConstructorParams<T, TC> {
+    readonly collectionId: Validator<TCOLLECTIONID, TC>;
+    readonly separator: string;
+    readonly itemId: Validator<TITEMID, TC>;
+}
+/**
+ * An in-place {@link Validation.Validator | Validator} for a strongly-typed composite ID.
+ * @public
+ */
+export declare class CompositeIdValidator<T extends string = string, TCOLLECTIONID extends string = string, TITEMID extends string = string, TC = unknown> extends ValidatorBase<T, TC> {
+    protected readonly _collectionIdValidator: Validator<TCOLLECTIONID, TC>;
+    protected readonly _itemIdValidator: Validator<TITEMID, TC>;
+    protected readonly _separator: string;
+    /**
+     * Constructs a new {@link Validation.Classes.StringValidator | StringValidator}.
+     * @param params - Optional {@link Validation.Classes.StringValidatorConstructorParams | init params}
+     * for the new {@link Validation.Classes.StringValidator | StringValidator}.
+     */
+    constructor(params: CompositeIdValidatorConstructorParams<T, TCOLLECTIONID, TITEMID, TC>);
+    protected _validate(value: unknown, context?: TC): boolean | Failure<T>;
+}
+//# sourceMappingURL=compositeId.d.ts.map

package/lib/packlets/validation/compositeId.js

@@ -0,0 +1,64 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompositeIdValidator = void 0;
+const base_1 = require("../base");
+const validatorBase_1 = require("./validatorBase");
+/**
+ * An in-place {@link Validation.Validator | Validator} for a strongly-typed composite ID.
+ * @public
+ */
+class CompositeIdValidator extends validatorBase_1.ValidatorBase {
+    /**
+     * Constructs a new {@link Validation.Classes.StringValidator | StringValidator}.
+     * @param params - Optional {@link Validation.Classes.StringValidatorConstructorParams | init params}
+     * for the new {@link Validation.Classes.StringValidator | StringValidator}.
+     */
+    constructor(params) {
+        /* c8 ignore next */
+        super(Object.assign({}, params));
+        const { collectionId, separator, itemId } = params;
+        this._collectionIdValidator = collectionId.withFormattedError((value, err) => `${value}: invalid composite collection ID (${err}).`);
+        this._itemIdValidator = itemId.withFormattedError((value, err) => `${value}: invalid composite item ID (${err}).`);
+        this._separator = separator;
+    }
+    _validate(value, context) {
+        if (typeof value !== 'string') {
+            return (0, base_1.fail)(`${value}: invalid non-string composite ID.`);
+        }
+        const parts = value.split(this._separator);
+        if (parts.length < 2) {
+            return (0, base_1.fail)(`${value}: invalid composite ID - separator '${this._separator}' not found.`);
+        }
+        else if (parts.length > 2) {
+            return (0, base_1.fail)(`${value}: invalid composite ID - multiple separators '${this._separator}.' found.`);
+        }
+        const [collectionId, itemId] = parts;
+        const result = this._collectionIdValidator
+            .validate(collectionId, context)
+            .onSuccess(() => this._itemIdValidator.validate(itemId, context));
+        return result.isSuccess() ? true : base_1.Failure.with(`${value}: invalid composite ID - ${result.message}`);
+    }
+}
+exports.CompositeIdValidator = CompositeIdValidator;
+//# sourceMappingURL=compositeId.js.map

package/lib/packlets/validation/field.d.ts

@@ -36,7 +36,7 @@ export declare class FieldValidator<T, TC = unknown> extends ValidatorBase<T, TC
      */
     constructor(fieldName: string, fieldValidator: Validator<T, TC>, options?: FieldValidatorOptions<TC>);
     /**
-     * {@inheritdoc Validation.ValidatorBase._validate}
+     * {@inheritDoc Validation.ValidatorBase._validate}
      */
     protected _validate(from: unknown, context?: TC, self?: Validator<T, TC>): boolean | Failure<T>;
 }

package/lib/packlets/validation/field.js

@@ -46,7 +46,7 @@ class FieldValidator extends validatorBase_1.ValidatorBase {
         this._fieldOptions = options !== null && options !== void 0 ? options : {};
     }
     /**
-     * {@inheritdoc Validation.ValidatorBase._validate}
+     * {@inheritDoc Validation.ValidatorBase._validate}
      */
     _validate(from, context, self) {
         if (typeof from === 'object' && !Array.isArray(from) && from !== null) {

package/lib/packlets/validation/genericValidator.d.ts

@@ -16,7 +16,7 @@ export interface GenericValidatorConstructorParams<T, TC> {
  */
 export declare class GenericValidator<T, TC = unknown> implements Validator<T, TC> {
     /**
-     * {@inheritdoc Validation.Validator.traits}
+     * {@inheritDoc Validation.Validator.traits}
      */
     readonly traits: ValidatorTraits;
     /**
@@ -34,45 +34,49 @@ export declare class GenericValidator<T, TC = unknown> implements Validator<T, T
      */
     constructor(params: Partial<GenericValidatorConstructorParams<T, TC>>);
     /**
-     * {@inheritdoc Validation.Validator.isOptional}
+     * {@inheritDoc Validation.Validator.isOptional}
      */
     get isOptional(): boolean;
     /**
-     * {@inheritdoc Validation.Validator.brand}
+     * {@inheritDoc Validation.Validator.brand}
      */
     get brand(): string | undefined;
     /**
-     * {@inheritdoc Validation.Validator.validate}
+     * {@inheritDoc Validation.Validator.validate}
      */
     validate(from: unknown, context?: TC): Result<T>;
     /**
-     * {@inheritdoc Validation.Validator.convert}
+     * {@inheritDoc Validation.Validator.convert}
      */
     convert(from: unknown, context?: TC): Result<T>;
     /**
-     * {@inheritdoc Validation.Validator.validateOptional}
+     * {@inheritDoc Validation.Validator.validateOptional}
      */
     validateOptional(from: unknown, context?: TC): Result<T | undefined>;
     /**
-     * {@inheritdoc Validation.Validator.guard}
+     * {@inheritDoc Validation.Validator.guard}
      */
     guard(from: unknown, context?: TC): from is T;
     /**
-     * {@inheritdoc Validation.Validator.optional}
+     * {@inheritDoc Validation.Validator.optional}
      */
     optional(): Validator<T | undefined, TC>;
     /**
-     * {@inheritdoc Validation.Validator.withConstraint}
+     * {@inheritDoc Validation.Validator.withConstraint}
      */
     withConstraint(constraint: Constraint<T>, trait?: ConstraintTrait): Validator<T, TC>;
     /**
-     * {@inheritdoc Validation.Validator.brand}
+     * {@inheritDoc Validation.Validator.brand}
      */
     withBrand<B extends string>(brand: B): Validator<Brand<T, B>, TC>;
     /**
-     * {@inheritdoc Validation.Validator.withFormattedError}
+     * {@inheritDoc Validation.Validator.withFormattedError}
      */
     withFormattedError(formatter: ValidationErrorFormatter<TC>): Validator<T, TC>;
+    /**
+     * {@inheritDoc Validation.Validator.or}
+     */
+    or(other: Validator<T, TC>): Validator<T, TC>;
     /**
      * Gets a default or explicit context.
      * @param explicitContext - Optional explicit context.

package/lib/packlets/validation/genericValidator.js

@@ -44,19 +44,19 @@ class GenericValidator {
         this.traits = new traits_1.ValidatorTraits(params.traits);
     }
     /**
-     * {@inheritdoc Validation.Validator.isOptional}
+     * {@inheritDoc Validation.Validator.isOptional}
      */
     get isOptional() {
         return this.traits.isOptional;
     }
     /**
-     * {@inheritdoc Validation.Validator.brand}
+     * {@inheritDoc Validation.Validator.brand}
      */
     get brand() {
         return this.traits.brand;
     }
     /**
-     * {@inheritdoc Validation.Validator.validate}
+     * {@inheritDoc Validation.Validator.validate}
      */
     validate(from, context) {
         const result = this._validator(from, this._context(context), this);
@@ -66,7 +66,7 @@ class GenericValidator {
         return result;
     }
     /**
-     * {@inheritdoc Validation.Validator.convert}
+     * {@inheritDoc Validation.Validator.convert}
      */
     convert(from, context) {
         const result = this._validator(from, this._context(context), this);
@@ -76,19 +76,19 @@ class GenericValidator {
         return result;
     }
     /**
-     * {@inheritdoc Validation.Validator.validateOptional}
+     * {@inheritDoc Validation.Validator.validateOptional}
      */
     validateOptional(from, context) {
         return from === undefined ? (0, base_1.succeed)(undefined) : this.validate(from, context);
     }
     /**
-     * {@inheritdoc Validation.Validator.guard}
+     * {@inheritDoc Validation.Validator.guard}
      */
     guard(from, context) {
         return this._validator(from, this._context(context), this) === true;
     }
     /**
-     * {@inheritdoc Validation.Validator.optional}
+     * {@inheritDoc Validation.Validator.optional}
      */
     optional() {
         return new GenericValidator({
@@ -99,7 +99,7 @@ class GenericValidator {
         });
     }
     /**
-     * {@inheritdoc Validation.Validator.withConstraint}
+     * {@inheritDoc Validation.Validator.withConstraint}
      */
     withConstraint(constraint, trait) {
         trait = trait !== null && trait !== void 0 ? trait : { type: 'function' };
@@ -121,7 +121,7 @@ class GenericValidator {
         });
     }
     /**
-     * {@inheritdoc Validation.Validator.brand}
+     * {@inheritDoc Validation.Validator.brand}
      */
     withBrand(brand) {
         if (this.brand) {
@@ -135,7 +135,7 @@ class GenericValidator {
         });
     }
     /**
-     * {@inheritdoc Validation.Validator.withFormattedError}
+     * {@inheritDoc Validation.Validator.withFormattedError}
      */
     withFormattedError(formatter) {
         return new GenericValidator({
@@ -150,6 +150,20 @@ class GenericValidator {
             }
         });
     }
+    /**
+     * {@inheritDoc Validation.Validator.or}
+     */
+    or(other) {
+        return new GenericValidator({
+            validator: (from, context, __self) => {
+                if (this._validator(from, this._context(context), this) === true) {
+                    return true;
+                }
+                const otherResult = other.validate(from, this._context(context));
+                return otherResult.isSuccess() ? true : otherResult;
+            }
+        });
+    }
     /**
      * Gets a default or explicit context.
      * @param explicitContext - Optional explicit context.

package/lib/packlets/validation/object.d.ts

@@ -69,10 +69,7 @@ export declare class ObjectValidator<T, TC = unknown> extends ValidatorBase<T, T
     protected readonly _allowedFields?: Set<keyof T>;
     /**
      * Constructs a new {@link Validation.Classes.ObjectValidator | ObjectValidator<T>}.
-     * @param fields - A {@link Validation.Classes.FieldValidators | FieldValidators<T>} containing
-     * a {@link Validation.Validator | Validator} for each field.
-     * @param options - An optional {@link Validation.Classes.ObjectValidatorOptions} to configure
-     * validation.
+     * @param params - Construction parameters including field validators and options.
      */
     constructor(params: ObjectValidatorConstructorParams<T, TC>);
     /**
@@ -101,13 +98,13 @@ export declare class ObjectValidator<T, TC = unknown> extends ValidatorBase<T, T
     /**
      * Creates a new {@link Validation.Classes.ObjectValidator | ObjectValidator} derived from this one but with
      * new optional properties as specified by a supplied array of `keyof T`.
-     * @param addOptionalProperties - The keys to be made optional.
+     * @param addOptionalFields - The keys to be made optional.
      * @returns A new {@link Validation.Classes.ObjectValidator | ObjectValidator} with the additional optional
      * source properties.
      */
     addPartial(addOptionalFields: (keyof T)[]): ObjectValidator<Partial<T>, TC>;
     /**
-     * {@inheritdoc Validation.ValidatorBase._validate}
+     * {@inheritDoc Validation.ValidatorBase._validate}
      * @internal
      */
     protected _validate(from: unknown, context?: TC, self?: Validator<T, TC>): boolean | Failure<T>;

package/lib/packlets/validation/object.js

@@ -36,10 +36,7 @@ const field_1 = require("./field");
 class ObjectValidator extends validatorBase_1.ValidatorBase {
     /**
      * Constructs a new {@link Validation.Classes.ObjectValidator | ObjectValidator<T>}.
-     * @param fields - A {@link Validation.Classes.FieldValidators | FieldValidators<T>} containing
-     * a {@link Validation.Validator | Validator} for each field.
-     * @param options - An optional {@link Validation.Classes.ObjectValidatorOptions} to configure
-     * validation.
+     * @param params - Construction parameters including field validators and options.
      */
     constructor(params) {
         var _a;
@@ -95,7 +92,7 @@ class ObjectValidator extends validatorBase_1.ValidatorBase {
     /**
      * Creates a new {@link Validation.Classes.ObjectValidator | ObjectValidator} derived from this one but with
      * new optional properties as specified by a supplied array of `keyof T`.
-     * @param addOptionalProperties - The keys to be made optional.
+     * @param addOptionalFields - The keys to be made optional.
      * @returns A new {@link Validation.Classes.ObjectValidator | ObjectValidator} with the additional optional
      * source properties.
      */
@@ -106,7 +103,7 @@ class ObjectValidator extends validatorBase_1.ValidatorBase {
         });
     }
     /**
-     * {@inheritdoc Validation.ValidatorBase._validate}
+     * {@inheritDoc Validation.ValidatorBase._validate}
      * @internal
      */
     _validate(from, context, self) {

package/lib/packlets/validation/traits.d.ts

@@ -44,15 +44,15 @@ export declare const defaultValidatorTraits: ValidatorTraitValues;
  */
 export declare class ValidatorTraits implements ValidatorTraitValues {
     /**
-     * {@inheritdoc Validation.ValidatorTraitValues.isOptional}
+     * {@inheritDoc Validation.ValidatorTraitValues.isOptional}
      */
     readonly isOptional: boolean;
     /**
-     * {@inheritdoc Validation.ValidatorTraitValues.brand}
+     * {@inheritDoc Validation.ValidatorTraitValues.brand}
      */
     readonly brand?: string;
     /**
-     * {@inheritdoc Validation.ValidatorTraitValues.constraints}
+     * {@inheritDoc Validation.ValidatorTraitValues.constraints}
      */
     readonly constraints: ConstraintTrait[];
     /**

package/lib/packlets/validation/validator.d.ts

@@ -111,5 +111,12 @@ export interface Validator<T, TC = unknown> {
      * @returns A new {@link Validation.Validator | Validator}.
      */
     withFormattedError(formatter: ValidationErrorFormatter<TC>): Validator<T, TC>;
+    /**
+     * Chains this validator with another of the same type, to be attempted if this
+     * validator fails.
+     * @param other - The other {@link Validation.Validator | Validator} to be attempted
+     * if this one fails.
+     */
+    or(other: Validator<T, TC>): Validator<T, TC>;
 }
 //# sourceMappingURL=validator.d.ts.map

package/lib/packlets/validation/validators.d.ts

@@ -1,4 +1,5 @@
 import { ArrayValidator, ArrayValidatorConstructorParams } from './array';
+import { CompositeIdValidator, CompositeIdValidatorConstructorParams } from './compositeId';
 import { FieldValidators, ObjectValidator, ObjectValidatorConstructorParams } from './object';
 import { TypeGuardValidator, TypeGuardValidatorConstructorParams } from './typeGuard';
 import { TypeGuardWithContext } from './common';
@@ -82,6 +83,15 @@ export declare function enumeratedValue<T extends string>(values: ReadonlyArray<
  * @public
  */
 export declare function literal<T extends string | number | boolean | symbol | null | undefined>(value: T): Validator<T>;
+/** Helper function to create a {@link Validation.Validator | Validator} which validates a
+ * strongly-typed composite ID.
+ * @param params - {@link Validation.Classes.CompositeIdValidatorConstructorParams | params}
+ * used to construct the validator.
+ * @returns A new {@link Validation.Validator | Validator} which validates the desired
+ * composite ID in place.
+ * @public
+ */
+export declare function compositeId<T extends string = string, TCOLLECTIONID extends string = string, TITEMID extends string = string, TC = unknown>(params: CompositeIdValidatorConstructorParams<T, TCOLLECTIONID, TITEMID, TC>): CompositeIdValidator<T, TCOLLECTIONID, TITEMID, TC>;
 /**
  * Helper function to create a {@link Validation.Validator | Validator} which validates one
  * of several possible validated values.

package/lib/packlets/validation/validators.js

@@ -27,11 +27,13 @@ exports.arrayOf = arrayOf;
 exports.recordOf = recordOf;
 exports.enumeratedValue = enumeratedValue;
 exports.literal = literal;
+exports.compositeId = compositeId;
 exports.oneOf = oneOf;
 exports.isA = isA;
 exports.generic = generic;
 const base_1 = require("../base");
 const array_1 = require("./array");
+const compositeId_1 = require("./compositeId");
 const object_1 = require("./object");
 const typeGuard_1 = require("./typeGuard");
 const boolean_1 = require("./boolean");
@@ -163,6 +165,17 @@ function literal(value) {
         }
     });
 }
+/** Helper function to create a {@link Validation.Validator | Validator} which validates a
+ * strongly-typed composite ID.
+ * @param params - {@link Validation.Classes.CompositeIdValidatorConstructorParams | params}
+ * used to construct the validator.
+ * @returns A new {@link Validation.Validator | Validator} which validates the desired
+ * composite ID in place.
+ * @public
+ */
+function compositeId(params) {
+    return new compositeId_1.CompositeIdValidator(params);
+}
 /**
  * Helper function to create a {@link Validation.Validator | Validator} which validates one
  * of several possible validated values.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-utils",
-  "version": "5.0.2",
+  "version": "5.1.0-0",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "module": "dist/index.js",
@@ -26,33 +26,33 @@
   "homepage": "https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils#readme",
   "devDependencies": {
     "@jest/expect-utils": "^29.7.0",
-    "@microsoft/api-documenter": "^7.27.3",
-    "@microsoft/api-extractor": "^7.53.3",
+    "@microsoft/api-documenter": "^7.28.2",
+    "@microsoft/api-extractor": "^7.55.2",
     "@types/jest": "^29.5.14",
     "@types/luxon": "^3.7.1",
     "@types/mustache": "^4.2.5",
     "@types/node": "^20.14.9",
-    "@typescript-eslint/eslint-plugin": "^8.46.2",
-    "@typescript-eslint/parser": "^8.46.2",
-    "eslint": "^9.39.0",
+    "@typescript-eslint/eslint-plugin": "^8.52.0",
+    "@typescript-eslint/parser": "^8.52.0",
+    "eslint": "^9.39.2",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-promise": "^7.2.1",
     "jest": "^29.7.0",
     "jest-extended": "^4.0.2",
     "jest-matcher-utils": "^29.7.0",
-    "rimraf": "^6.1.0",
-    "ts-jest": "^29.4.5",
+    "rimraf": "^6.1.2",
+    "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
     "typescript": "5.9.3",
     "eslint-plugin-n": "^17.23.1",
     "jest-snapshot": "~29.7.0",
-    "@rushstack/heft": "1.1.3",
-    "@rushstack/heft-node-rig": "2.11.4",
-    "@rushstack/eslint-config": "4.5.3",
+    "@rushstack/heft": "1.2.6",
+    "@rushstack/heft-node-rig": "2.11.26",
+    "@rushstack/eslint-config": "4.6.4",
     "@types/heft-jest": "1.0.6",
-    "@rushstack/heft-jest-plugin": "1.1.3",
-    "eslint-plugin-tsdoc": "~0.4.0",
+    "@rushstack/heft-jest-plugin": "1.2.6",
+    "eslint-plugin-tsdoc": "~0.5.2",
     "@fgv/heft-dual-rig": "0.1.0"
   },
   "repository": {
@@ -63,7 +63,7 @@
     "build": "heft build --clean",
     "clean": "heft clean",
     "test": "heft test --clean",
-    "build-docs": "api-documenter markdown --input-folder ./temp --output-folder docs",
+    "build-docs": "typedoc --options ./config/typedoc.json",
     "build-all": "rushx build; rushx build-docs",
     "test-handles": "jest --runInBand --detectOpenHandles",
     "clean-jest": "jest --clear-cache",