@fgv/ts-json-base 5.0.1-2 → 5.0.1-3

package/README.md

@@ -34,7 +34,7 @@ interface JsonArray extends Array<JsonValue> { }
 
 ### JsonCompatible Type
 
-The `JsonCompatible<T>` type provides compile-time validation that a type is JSON-serializable, unlike `JsonValue` which requires an index signature. This is particularly useful for strongly-typed interfaces.
+The `JsonCompatibleType<T>` type provides compile-time validation that a type is JSON-serializable, unlike `JsonValue` which requires an index signature. This is particularly useful for strongly-typed interfaces.
 
 #### Basic Usage
 
@@ -52,7 +52,7 @@ interface UserData {
 }
 
 // ✅ This type remains unchanged because it's fully JSON-compatible
-type ValidatedUserData = JsonCompatible<UserData>;
+type ValidatedUserData = JsonCompatibleType<UserData>;
 
 // ❌ Interface with non-JSON properties
 interface UserWithMethods {
@@ -62,16 +62,16 @@ interface UserWithMethods {
 }
 
 // ❌ This type transforms 'save' to an error type
-type InvalidUserData = JsonCompatible<UserWithMethods>;
+type InvalidUserData = JsonCompatibleType<UserWithMethods>;
 // Result: { id: string; name: string; save: ['Error: Function is not JSON-compatible'] }
 ```
 
 #### The MapOf Pattern
 
-The most powerful application is using `JsonCompatible<T>` as a constraint with default type parameters:
+The most powerful application is using `JsonCompatibleType<T>` as a constraint with default type parameters:
 
 ```typescript
-class MapOf<T, TV extends JsonCompatible<T> = JsonCompatible<T>> extends Map<string, TV> {
+class MapOf<T, TV extends JsonCompatibleType<T> = JsonCompatibleType<T>> extends Map<string, TV> {
   public override set(key: string, value: TV): this {
     return super.set(key, value);
   }

package/dist/ts-json-base.d.ts

@@ -1,6 +1,31 @@
+import { Conversion } from '@fgv/ts-utils';
 import { Converter } from '@fgv/ts-utils';
+import { Converters as Converters_3 } from '@fgv/ts-utils';
+import { ObjectConverter as ObjectConverter_2 } from '@fgv/ts-utils';
 import { Result } from '@fgv/ts-utils';
+import { Validation } from '@fgv/ts-utils';
 import { Validator } from '@fgv/ts-utils';
+import { Validators as Validators_3 } from '@fgv/ts-utils';
+
+/**
+ * A helper function to create a {@link Converter | Converter} which converts a supplied `unknown` value to a valid
+ * array of {@link JsonCompatibleType | JsonCompatibleType<T>}.
+ * @param converter - {@link JsonCompatible.Converter | JSON-compatible Converter<T, TC>}
+ * or {@link JsonCompatible.Validator | JSON-compatible Validator<T>} used for each item in the source array.
+ * @param onError - The error handling option to use for the conversion.
+ * @returns A {@link Converter | Converter} which returns `JsonCompatibleType<T>[]`.
+ * @public
+ */
+declare function arrayOf<T, TC = unknown>(converter: JsonCompatible_2.Converter<T, TC> | JsonCompatible_2.Validator<T, TC>, onError?: Conversion.OnError): Converter<JsonCompatibleType<T>[], TC>;
+
+/**
+ * A helper function to create a {@link JsonCompatible.ArrayValidator | JSON-compatible ArrayValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @param validateElement - The element to validate.
+ * @param params - The parameters to use for the validation.
+ * @returns A {@link JsonCompatible.ArrayValidator | JSON-compatible ArrayValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+declare function arrayOf_2<T, TC = unknown>(validateElement: JsonCompatible_2.Validator<T, TC>, params?: Omit<Validation.Classes.ArrayValidatorConstructorParams<JsonCompatibleType<T>, TC>, 'validateElement'>): Validation.Classes.ArrayValidator<JsonCompatibleType<T>, TC>;
 
 /**
  * Identifies whether some `unknown` value is a {@link JsonPrimitive | primitive},
@@ -18,6 +43,12 @@ export declare function classifyJsonValue(from: unknown): Result<JsonValueType>;
  */
 declare type ContentTypeFactory<TCT extends string = string> = (filePath: string, provided?: string) => Result<TCT | undefined>;
 
+/**
+ * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+declare type Converter_2<T, TC = unknown> = Converter<JsonCompatibleType<T>, TC>;
+
 declare namespace Converters {
     export {
         IJsonConverterContext,
@@ -29,6 +60,16 @@ declare namespace Converters {
 }
 export { Converters }
 
+declare namespace Converters_2 {
+    export {
+        arrayOf,
+        recordOf,
+        object,
+        strictObject,
+        discriminatedObject
+    }
+}
+
 /**
  * Reads all JSON files from a directory and apply a supplied converter.
  * @param srcPath - The path of the folder to be read.
@@ -124,6 +165,15 @@ declare class DirectoryItem<TCT extends string = string> implements IFileTreeDir
     getChildren(): Result<ReadonlyArray<FileTreeItem<TCT>>>;
 }
 
+/**
+ * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @param discriminatorProp - The name of the property used to discriminate types.
+ * @param converters - The converters to use for the conversion.
+ * @returns A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @public
+ */
+declare function discriminatedObject<T, TD extends string = string, TC = unknown>(discriminatorProp: string, converters: Converters_3.DiscriminatedObjectConverters<JsonCompatibleType<T>, TD, TC>): JsonCompatible_2.Converter<T, TC>;
+
 /**
  * Class representing a file in a file tree.
  * @public
@@ -758,6 +808,35 @@ declare const jsonArray: Converter<JsonArray, IJsonConverterContext>;
  */
 declare const jsonArray_2: Validator<JsonArray, IJsonValidatorContext>;
 
+declare namespace JsonCompatible {
+    export {
+        Converters_2 as Converters,
+        Validators_2 as Validators,
+        Converter_2 as Converter,
+        Validator_2 as Validator,
+        ObjectConverter,
+        ObjectValidator
+    }
+}
+export { JsonCompatible }
+
+declare namespace JsonCompatible_2 {
+    export {
+        Converter_2 as Converter,
+        Validator_2 as Validator,
+        ObjectConverter,
+        ObjectValidator
+    }
+}
+
+/**
+ * A type that represents an array of JSON-compatible values.
+ * @param T - The type to be constrained
+ * @returns A constrained type that is compatible with JSON serialization.
+ * @public
+ */
+export declare type JsonCompatibleArray<T> = Array<JsonCompatibleType<T>>;
+
 /**
  * A constrained type that is compatible with JSON serialization.
  *
@@ -783,7 +862,7 @@ declare const jsonArray_2: Validator<JsonArray, IJsonValidatorContext>;
  *   email?: string; // Optional property can be undefined
  * }
  *
- * type UserCompatible = JsonCompatible<IUser>; // Allows undefined for email
+ * type UserCompatible = JsonCompatibleType<IUser>; // Allows undefined for email
  *
  * const user: UserCompatible = {
  *   name: "John",
@@ -797,18 +876,10 @@ declare const jsonArray_2: Validator<JsonArray, IJsonValidatorContext>;
  *
  * @public
  */
-export declare type JsonCompatible<T> = IsUnknown<T> extends true ? JsonValue : T extends JsonPrimitive | undefined ? T : T extends Array<unknown> ? JsonCompatibleArray<T[number]> : T extends Function ? ['Error: Function is not JSON-compatible'] : T extends object ? {
-    [K in keyof T]: JsonCompatible<T[K]>;
+export declare type JsonCompatibleType<T> = IsUnknown<T> extends true ? JsonValue : T extends JsonPrimitive | undefined ? T : T extends Array<unknown> ? JsonCompatibleArray<T[number]> : T extends Function ? ['Error: Function is not JSON-compatible'] : T extends object ? {
+    [K in keyof T]: JsonCompatibleType<T[K]>;
 } : ['Error: Non-JSON type'];
 
-/**
- * A type that represents an array of JSON-compatible values.
- * @param T - The type to be constrained
- * @returns A constrained type that is compatible with JSON serialization.
- * @public
- */
-export declare type JsonCompatibleArray<T> = Array<JsonCompatible<T>>;
-
 declare namespace JsonFile {
     export {
         readJsonFileSync,
@@ -1054,6 +1125,36 @@ declare const jsonValue_2: Validator<JsonValue, IJsonValidatorContext>;
  */
 export declare type JsonValueType = 'primitive' | 'object' | 'array';
 
+/**
+ * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @param properties - The properties to convert.
+ * @param options - The options to use for the conversion.
+ * @returns A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @public
+ */
+declare function object<T, TC = unknown>(properties: Conversion.FieldConverters<JsonCompatibleType<T>, TC>, options?: Conversion.ObjectConverterOptions<JsonCompatibleType<T>>): JsonCompatible_2.ObjectConverter<T, TC>;
+
+/**
+ * A helper function to create a {@link JsonCompatible.ObjectValidator | JSON-compatible ObjectValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @param properties - The properties to validate.
+ * @param params - The parameters to use for the validation.
+ * @returns A {@link JsonCompatible.ObjectValidator | JSON-compatible ObjectValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+declare function object_2<T, TC = unknown>(properties: Validation.Classes.FieldValidators<JsonCompatibleType<T>, TC>, params?: Omit<Validation.Classes.ObjectValidatorConstructorParams<JsonCompatibleType<T>, TC>, 'fields'>): JsonCompatible_2.ObjectValidator<T, TC>;
+
+/**
+ * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+declare type ObjectConverter<T, TC = unknown> = ObjectConverter_2<JsonCompatibleType<T>, TC>;
+
+/**
+ * A validator which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+declare type ObjectValidator<T, TC = unknown> = Validation.Classes.ObjectValidator<JsonCompatibleType<T>, TC>;
+
 /**
  * Picks a nested {@link JsonObject | JsonObject} from a supplied
  * {@link JsonObject | JsonObject}.
@@ -1082,6 +1183,32 @@ export declare function pickJsonValue(src: JsonObject, path: string): Result<Jso
  */
 declare function readJsonFileSync(srcPath: string): Result<JsonValue>;
 
+/**
+ * A helper function to create a {@link Converter | Converter} or which converts the `string`-keyed properties
+ * using a supplied {@link JsonCompatible.Converter | JSON-compatible Converter<T, TC>} or
+ * {@link JsonCompatible.Validator | JSON-compatible Validator<T>} to produce a
+ * `Record<TK, JsonCompatibleType<T>>`.
+ * @remarks
+ * If present, the supplied {@link Converters.KeyedConverterOptions | options} can provide a strongly-typed
+ * converter for keys and/or control the handling of elements that fail conversion.
+ * @param converter - {@link JsonCompatible.Converter | JSON-compatible Converter<T, TC>}
+ * or {@link JsonCompatible.Validator | JSON-compatible Validator<T>} used for each item in the source object.
+ * @param options - Optional {@link Converters.KeyedConverterOptions | KeyedConverterOptions<TK, TC>} which
+ * supplies a key converter and/or error-handling options.
+ * @returns A {@link Converter | Converter} which returns `Record<TK, JsonCompatibleType<T>>`.
+ * @public
+ */
+declare function recordOf<T, TC = unknown, TK extends string = string>(converter: JsonCompatible_2.Converter<T, TC> | JsonCompatible_2.Validator<T, TC>, options?: Converters_3.KeyedConverterOptions<TK, TC>): Converter<Record<TK, JsonCompatibleType<T>>, TC>;
+
+/**
+ * A helper function to create a {@link JsonCompatible.RecordValidator | JSON-compatible RecordValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @param validateElement - The element to validate.
+ * @param options - The options to use for the validation.
+ * @returns A {@link JsonCompatible.RecordValidator | JSON-compatible RecordValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+declare function recordOf_2<T, TC = unknown, TK extends string = string>(validateElement: JsonCompatible_2.Validator<T, TC>, options?: Validators_3.IRecordOfValidatorOptions<TK, TC>): Validation.Validator<Record<TK, JsonCompatibleType<T>>, TC>;
+
 /**
  * "Sanitizes" an `unknown` by stringifying and then parsing it.  Guarantees a
  * valid {@link JsonValue | JsonValue} but is not idempotent and gives no guarantees
@@ -1103,6 +1230,21 @@ export declare function sanitizeJson(from: unknown): Result<JsonValue>;
  */
 export declare function sanitizeJsonObject<T>(from: T): Result<T>;
 
+/**
+ * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @param properties - The properties to convert.
+ * @param options - The options to use for the conversion.
+ * @returns A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @public
+ */
+declare function strictObject<T, TC = unknown>(properties: Conversion.FieldConverters<JsonCompatibleType<T>, TC>, options?: Converters_3.StrictObjectConverterOptions<JsonCompatibleType<T>>): JsonCompatible_2.ObjectConverter<T, TC>;
+
+/**
+ * A validator which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+declare type Validator_2<T, TC = unknown> = Validator<JsonCompatibleType<T>, TC>;
+
 declare namespace Validators {
     export {
         IJsonValidatorContext,
@@ -1114,6 +1256,14 @@ declare namespace Validators {
 }
 export { Validators }
 
+declare namespace Validators_2 {
+    export {
+        arrayOf_2 as arrayOf,
+        recordOf_2 as recordOf,
+        object_2 as object
+    }
+}
+
 /**
  * {@inheritDoc JsonFile.JsonFsHelper.writeJsonFileSync}
  * @public

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.52.12"
+      "packageVersion": "7.53.3"
     }
   ]
 }

package/lib/index.d.ts

@@ -1,7 +1,8 @@
 import * as Converters from './packlets/converters';
 import * as FileTree from './packlets/file-tree';
+import * as JsonCompatible from './packlets/json-compatible';
 import * as JsonFile from './packlets/json-file';
 import * as Validators from './packlets/validators';
 export * from './packlets/json';
-export { Converters, FileTree, JsonFile, Validators };
+export { Converters, FileTree, JsonCompatible, JsonFile, Validators };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -57,11 +57,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Validators = exports.JsonFile = exports.FileTree = exports.Converters = void 0;
+exports.Validators = exports.JsonFile = exports.JsonCompatible = exports.FileTree = exports.Converters = void 0;
 const Converters = __importStar(require("./packlets/converters"));
 exports.Converters = Converters;
 const FileTree = __importStar(require("./packlets/file-tree"));
 exports.FileTree = FileTree;
+const JsonCompatible = __importStar(require("./packlets/json-compatible"));
+exports.JsonCompatible = JsonCompatible;
 const JsonFile = __importStar(require("./packlets/json-file"));
 exports.JsonFile = JsonFile;
 const Validators = __importStar(require("./packlets/validators"));

package/lib/packlets/json/common.d.ts

@@ -58,7 +58,7 @@ type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) :
  *   email?: string; // Optional property can be undefined
  * }
  *
- * type UserCompatible = JsonCompatible<IUser>; // Allows undefined for email
+ * type UserCompatible = JsonCompatibleType<IUser>; // Allows undefined for email
  *
  * const user: UserCompatible = {
  *   name: "John",
@@ -72,8 +72,8 @@ type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) :
  *
  * @public
  */
-export type JsonCompatible<T> = IsUnknown<T> extends true ? JsonValue : T extends JsonPrimitive | undefined ? T : T extends Array<unknown> ? JsonCompatibleArray<T[number]> : T extends Function ? ['Error: Function is not JSON-compatible'] : T extends object ? {
-    [K in keyof T]: JsonCompatible<T[K]>;
+export type JsonCompatibleType<T> = IsUnknown<T> extends true ? JsonValue : T extends JsonPrimitive | undefined ? T : T extends Array<unknown> ? JsonCompatibleArray<T[number]> : T extends Function ? ['Error: Function is not JSON-compatible'] : T extends object ? {
+    [K in keyof T]: JsonCompatibleType<T[K]>;
 } : ['Error: Non-JSON type'];
 /**
  * A type that represents an array of JSON-compatible values.
@@ -81,7 +81,7 @@ export type JsonCompatible<T> = IsUnknown<T> extends true ? JsonValue : T extend
  * @returns A constrained type that is compatible with JSON serialization.
  * @public
  */
-export type JsonCompatibleArray<T> = Array<JsonCompatible<T>>;
+export type JsonCompatibleArray<T> = Array<JsonCompatibleType<T>>;
 /**
  * Test if an `unknown` is a {@link JsonValue | JsonValue}.
  * @param from - The `unknown` to be tested

package/lib/packlets/json-compatible/common.d.ts

@@ -0,0 +1,23 @@
+import { Converter as BaseConverter, ObjectConverter as BaseObjectConverter, Validation, Validator as BaseValidator } from '@fgv/ts-utils';
+import { JsonCompatibleType } from '../json';
+/**
+ * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+export type Converter<T, TC = unknown> = BaseConverter<JsonCompatibleType<T>, TC>;
+/**
+ * A validator which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+export type Validator<T, TC = unknown> = BaseValidator<JsonCompatibleType<T>, TC>;
+/**
+ * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+export type ObjectConverter<T, TC = unknown> = BaseObjectConverter<JsonCompatibleType<T>, TC>;
+/**
+ * A validator which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+export type ObjectValidator<T, TC = unknown> = Validation.Classes.ObjectValidator<JsonCompatibleType<T>, TC>;
+//# sourceMappingURL=common.d.ts.map

package/lib/packlets/json-compatible/common.js

@@ -0,0 +1,24 @@
+"use strict";
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=common.js.map

package/lib/packlets/json-compatible/converters.d.ts

@@ -0,0 +1,54 @@
+import { Conversion, Converter, Converters } from '@fgv/ts-utils';
+import * as JsonCompatible from './common';
+import { JsonCompatibleType } from '../json';
+/**
+ * A helper function to create a {@link Converter | Converter} which converts a supplied `unknown` value to a valid
+ * array of {@link JsonCompatibleType | JsonCompatibleType<T>}.
+ * @param converter - {@link JsonCompatible.Converter | JSON-compatible Converter<T, TC>}
+ * or {@link JsonCompatible.Validator | JSON-compatible Validator<T>} used for each item in the source array.
+ * @param onError - The error handling option to use for the conversion.
+ * @returns A {@link Converter | Converter} which returns `JsonCompatibleType<T>[]`.
+ * @public
+ */
+export declare function arrayOf<T, TC = unknown>(converter: JsonCompatible.Converter<T, TC> | JsonCompatible.Validator<T, TC>, onError?: Conversion.OnError): Converter<JsonCompatibleType<T>[], TC>;
+/**
+ * A helper function to create a {@link Converter | Converter} or which converts the `string`-keyed properties
+ * using a supplied {@link JsonCompatible.Converter | JSON-compatible Converter<T, TC>} or
+ * {@link JsonCompatible.Validator | JSON-compatible Validator<T>} to produce a
+ * `Record<TK, JsonCompatibleType<T>>`.
+ * @remarks
+ * If present, the supplied {@link Converters.KeyedConverterOptions | options} can provide a strongly-typed
+ * converter for keys and/or control the handling of elements that fail conversion.
+ * @param converter - {@link JsonCompatible.Converter | JSON-compatible Converter<T, TC>}
+ * or {@link JsonCompatible.Validator | JSON-compatible Validator<T>} used for each item in the source object.
+ * @param options - Optional {@link Converters.KeyedConverterOptions | KeyedConverterOptions<TK, TC>} which
+ * supplies a key converter and/or error-handling options.
+ * @returns A {@link Converter | Converter} which returns `Record<TK, JsonCompatibleType<T>>`.
+ * @public
+ */
+export declare function recordOf<T, TC = unknown, TK extends string = string>(converter: JsonCompatible.Converter<T, TC> | JsonCompatible.Validator<T, TC>, options?: Converters.KeyedConverterOptions<TK, TC>): Converter<Record<TK, JsonCompatibleType<T>>, TC>;
+/**
+ * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @param properties - The properties to convert.
+ * @param options - The options to use for the conversion.
+ * @returns A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @public
+ */
+export declare function object<T, TC = unknown>(properties: Conversion.FieldConverters<JsonCompatibleType<T>, TC>, options?: Conversion.ObjectConverterOptions<JsonCompatibleType<T>>): JsonCompatible.ObjectConverter<T, TC>;
+/**
+ * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @param properties - The properties to convert.
+ * @param options - The options to use for the conversion.
+ * @returns A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @public
+ */
+export declare function strictObject<T, TC = unknown>(properties: Conversion.FieldConverters<JsonCompatibleType<T>, TC>, options?: Converters.StrictObjectConverterOptions<JsonCompatibleType<T>>): JsonCompatible.ObjectConverter<T, TC>;
+/**
+ * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @param discriminatorProp - The name of the property used to discriminate types.
+ * @param converters - The converters to use for the conversion.
+ * @returns A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @public
+ */
+export declare function discriminatedObject<T, TD extends string = string, TC = unknown>(discriminatorProp: string, converters: Converters.DiscriminatedObjectConverters<JsonCompatibleType<T>, TD, TC>): JsonCompatible.Converter<T, TC>;
+//# sourceMappingURL=converters.d.ts.map

package/lib/packlets/json-compatible/converters.js

@@ -0,0 +1,91 @@
+"use strict";
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.arrayOf = arrayOf;
+exports.recordOf = recordOf;
+exports.object = object;
+exports.strictObject = strictObject;
+exports.discriminatedObject = discriminatedObject;
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * A helper function to create a {@link Converter | Converter} which converts a supplied `unknown` value to a valid
+ * array of {@link JsonCompatibleType | JsonCompatibleType<T>}.
+ * @param converter - {@link JsonCompatible.Converter | JSON-compatible Converter<T, TC>}
+ * or {@link JsonCompatible.Validator | JSON-compatible Validator<T>} used for each item in the source array.
+ * @param onError - The error handling option to use for the conversion.
+ * @returns A {@link Converter | Converter} which returns `JsonCompatibleType<T>[]`.
+ * @public
+ */
+function arrayOf(converter, onError = 'failOnError') {
+    return ts_utils_1.Converters.arrayOf(converter, onError);
+}
+/**
+ * A helper function to create a {@link Converter | Converter} or which converts the `string`-keyed properties
+ * using a supplied {@link JsonCompatible.Converter | JSON-compatible Converter<T, TC>} or
+ * {@link JsonCompatible.Validator | JSON-compatible Validator<T>} to produce a
+ * `Record<TK, JsonCompatibleType<T>>`.
+ * @remarks
+ * If present, the supplied {@link Converters.KeyedConverterOptions | options} can provide a strongly-typed
+ * converter for keys and/or control the handling of elements that fail conversion.
+ * @param converter - {@link JsonCompatible.Converter | JSON-compatible Converter<T, TC>}
+ * or {@link JsonCompatible.Validator | JSON-compatible Validator<T>} used for each item in the source object.
+ * @param options - Optional {@link Converters.KeyedConverterOptions | KeyedConverterOptions<TK, TC>} which
+ * supplies a key converter and/or error-handling options.
+ * @returns A {@link Converter | Converter} which returns `Record<TK, JsonCompatibleType<T>>`.
+ * @public
+ */
+function recordOf(converter, options) {
+    return ts_utils_1.Converters.recordOf(converter, options !== null && options !== void 0 ? options : { onError: 'fail' });
+}
+/**
+ * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @param properties - The properties to convert.
+ * @param options - The options to use for the conversion.
+ * @returns A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @public
+ */
+function object(properties, options) {
+    return new ts_utils_1.Conversion.ObjectConverter(properties, options);
+}
+/**
+ * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @param properties - The properties to convert.
+ * @param options - The options to use for the conversion.
+ * @returns A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @public
+ */
+function strictObject(properties, options) {
+    const objectOptions = Object.assign(Object.assign({}, options), { strict: true });
+    return new ts_utils_1.Conversion.ObjectConverter(properties, objectOptions);
+}
+/**
+ * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @param discriminatorProp - The name of the property used to discriminate types.
+ * @param converters - The converters to use for the conversion.
+ * @returns A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @public
+ */
+function discriminatedObject(discriminatorProp, converters) {
+    return ts_utils_1.Converters.discriminatedObject(discriminatorProp, converters);
+}
+//# sourceMappingURL=converters.js.map

package/lib/packlets/json-compatible/index.d.ts

@@ -0,0 +1,5 @@
+export * from './common';
+import * as Converters from './converters';
+import * as Validators from './validators';
+export { Converters, Validators };
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/json-compatible/index.js

@@ -0,0 +1,66 @@
+"use strict";
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Validators = exports.Converters = void 0;
+__exportStar(require("./common"), exports);
+const Converters = __importStar(require("./converters"));
+exports.Converters = Converters;
+const Validators = __importStar(require("./validators"));
+exports.Validators = Validators;
+//# sourceMappingURL=index.js.map

package/lib/packlets/json-compatible/validators.d.ts

@@ -0,0 +1,28 @@
+import { JsonCompatibleType } from '../json';
+import * as JsonCompatible from './common';
+import { Validation, Validators } from '@fgv/ts-utils';
+/**
+ * A helper function to create a {@link JsonCompatible.ArrayValidator | JSON-compatible ArrayValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @param validateElement - The element to validate.
+ * @param params - The parameters to use for the validation.
+ * @returns A {@link JsonCompatible.ArrayValidator | JSON-compatible ArrayValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+export declare function arrayOf<T, TC = unknown>(validateElement: JsonCompatible.Validator<T, TC>, params?: Omit<Validation.Classes.ArrayValidatorConstructorParams<JsonCompatibleType<T>, TC>, 'validateElement'>): Validation.Classes.ArrayValidator<JsonCompatibleType<T>, TC>;
+/**
+ * A helper function to create a {@link JsonCompatible.RecordValidator | JSON-compatible RecordValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @param validateElement - The element to validate.
+ * @param options - The options to use for the validation.
+ * @returns A {@link JsonCompatible.RecordValidator | JSON-compatible RecordValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+export declare function recordOf<T, TC = unknown, TK extends string = string>(validateElement: JsonCompatible.Validator<T, TC>, options?: Validators.IRecordOfValidatorOptions<TK, TC>): Validation.Validator<Record<TK, JsonCompatibleType<T>>, TC>;
+/**
+ * A helper function to create a {@link JsonCompatible.ObjectValidator | JSON-compatible ObjectValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @param properties - The properties to validate.
+ * @param params - The parameters to use for the validation.
+ * @returns A {@link JsonCompatible.ObjectValidator | JSON-compatible ObjectValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+export declare function object<T, TC = unknown>(properties: Validation.Classes.FieldValidators<JsonCompatibleType<T>, TC>, params?: Omit<Validation.Classes.ObjectValidatorConstructorParams<JsonCompatibleType<T>, TC>, 'fields'>): JsonCompatible.ObjectValidator<T, TC>;
+//# sourceMappingURL=validators.d.ts.map

package/lib/packlets/json-compatible/validators.js

@@ -0,0 +1,58 @@
+"use strict";
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.arrayOf = arrayOf;
+exports.recordOf = recordOf;
+exports.object = object;
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * A helper function to create a {@link JsonCompatible.ArrayValidator | JSON-compatible ArrayValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @param validateElement - The element to validate.
+ * @param params - The parameters to use for the validation.
+ * @returns A {@link JsonCompatible.ArrayValidator | JSON-compatible ArrayValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+function arrayOf(validateElement, params) {
+    return ts_utils_1.Validators.arrayOf(validateElement, params !== null && params !== void 0 ? params : {});
+}
+/**
+ * A helper function to create a {@link JsonCompatible.RecordValidator | JSON-compatible RecordValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @param validateElement - The element to validate.
+ * @param options - The options to use for the validation.
+ * @returns A {@link JsonCompatible.RecordValidator | JSON-compatible RecordValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+function recordOf(validateElement, options) {
+    return ts_utils_1.Validators.recordOf(validateElement, options !== null && options !== void 0 ? options : {});
+}
+/**
+ * A helper function to create a {@link JsonCompatible.ObjectValidator | JSON-compatible ObjectValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @param properties - The properties to validate.
+ * @param params - The parameters to use for the validation.
+ * @returns A {@link JsonCompatible.ObjectValidator | JSON-compatible ObjectValidator<T, TC>} which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+function object(properties, params) {
+    return ts_utils_1.Validators.object(properties, params !== null && params !== void 0 ? params : {});
+}
+//# sourceMappingURL=validators.js.map

package/lib/packlets/json-file/jsonTreeHelper.js

@@ -46,7 +46,7 @@ class JsonTreeHelper {
      */
     readJsonFromTree(fileTree, filePath) {
         return fileTree.getFile(filePath).onSuccess((file) => {
-            // Now getContents() returns JsonCompatible<unknown> which is assignable to JsonValue!
+            // Now getContents() returns JsonCompatibleType<unknown> which is assignable to JsonValue!
             return file.getContents();
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-json-base",
-  "version": "5.0.1-2",
+  "version": "5.0.1-3",
   "description": "Typescript types and basic functions for working with json",
   "main": "lib/index.js",
   "types": "dist/ts-json-base.d.ts",
@@ -31,33 +31,33 @@
   "devDependencies": {
     "@types/jest": "^29.5.14",
     "@types/node": "^20.14.9",
-    "@typescript-eslint/eslint-plugin": "^8.42.0",
-    "@typescript-eslint/parser": "^8.42.0",
-    "eslint": "^9.35.0",
+    "@typescript-eslint/eslint-plugin": "^8.46.2",
+    "@typescript-eslint/parser": "^8.46.2",
+    "eslint": "^9.39.0",
     "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",
-    "rimraf": "^6.0.1",
-    "ts-jest": "^29.4.1",
+    "rimraf": "^6.1.0",
+    "ts-jest": "^29.4.5",
     "ts-node": "^10.9.2",
-    "typescript": "5.8.3",
-    "eslint-plugin-n": "^17.21.3",
-    "@rushstack/heft-node-rig": "2.9.5",
-    "@rushstack/heft": "0.74.4",
-    "@rushstack/heft-jest-plugin": "0.16.13",
+    "typescript": "5.9.3",
+    "eslint-plugin-n": "^17.23.1",
+    "@rushstack/heft-node-rig": "2.11.4",
+    "@rushstack/heft": "1.1.3",
+    "@rushstack/heft-jest-plugin": "1.1.3",
     "@types/heft-jest": "1.0.6",
-    "@microsoft/api-documenter": "^7.26.31",
-    "@rushstack/eslint-patch": "~1.12.0",
-    "@rushstack/eslint-config": "4.4.0",
+    "@microsoft/api-documenter": "^7.27.3",
+    "@rushstack/eslint-patch": "1.14.1",
+    "@rushstack/eslint-config": "4.5.3",
     "eslint-plugin-tsdoc": "~0.4.0",
     "@types/luxon": "^3.7.1",
-    "@fgv/ts-utils-jest": "5.0.1-2",
-    "@fgv/ts-utils": "5.0.1-2"
+    "@fgv/ts-utils": "5.0.1-3",
+    "@fgv/ts-utils-jest": "5.0.1-3"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.0.1-2"
+    "@fgv/ts-utils": "5.0.1-3"
   },
   "dependencies": {
     "luxon": "^3.7.2"