@fgv/ts-json-base 5.0.0-23 → 5.0.0-24

package/CHANGELOG.json

@@ -1,24 +1,6 @@
 {
   "name": "@fgv/ts-json-base",
   "entries": [
-    {
-      "version": "5.0.0",
-      "tag": "@fgv/ts-json-base_v5.0.0",
-      "date": "Thu, 17 Jul 2025 00:13:24 GMT",
-      "comments": {
-        "none": [
-          {
-            "comment": "add sanitizeJsonObject"
-          },
-          {
-            "comment": "upgrade dependencies"
-          },
-          {
-            "comment": "bump version"
-          }
-        ]
-      }
-    },
     {
       "version": "4.6.0",
       "tag": "@fgv/ts-json-base_v4.6.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-json-base",
-  "version": "5.0.0-23",
+  "version": "5.0.0-24",
   "description": "Typescript types and basic functions for working with json",
   "main": "lib/index.js",
   "types": "dist/ts-json-base.d.ts",
@@ -29,22 +29,22 @@
     "rimraf": "^5.0.7",
     "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
-    "typescript": "^5.8.3",
+    "typescript": "5.8.3",
     "eslint-plugin-n": "^16.6.2",
-    "@rushstack/heft-node-rig": "~2.9.3",
-    "@rushstack/heft": "~0.74.2",
-    "heft-jest": "~1.0.2",
+    "@rushstack/heft-node-rig": "2.9.4",
+    "@rushstack/heft": "0.74.3",
+    "@rushstack/heft-jest-plugin": "0.16.12",
     "@types/heft-jest": "1.0.6",
     "@microsoft/api-documenter": "^7.26.31",
     "@rushstack/eslint-patch": "~1.12.0",
-    "@rushstack/eslint-config": "~4.4.0",
+    "@rushstack/eslint-config": "4.4.0",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils": "5.0.0-23",
-    "@fgv/ts-utils-jest": "5.0.0-23",
-    "@fgv/ts-extras": "5.0.0-23"
+    "@fgv/ts-utils": "5.0.0-24",
+    "@fgv/ts-utils-jest": "5.0.0-24",
+    "@fgv/ts-extras": "5.0.0-24"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.0.0-23"
+    "@fgv/ts-utils": "5.0.0-24"
   },
   "scripts": {
     "build": "heft test --clean",

package/.vscode/launch.json

@@ -1,16 +0,0 @@
-{
-  // Use IntelliSense to learn about possible attributes.
-  // Hover to view descriptions of existing attributes.
-  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "type": "node",
-      "request": "launch",
-      "name": "Launch Program",
-      "skipFiles": ["<node_internals>/**"],
-      "program": "${workspaceFolder}/lib/index.js",
-      "outFiles": ["${workspaceFolder}/**/*.js"]
-    }
-  ]
-}

package/.vscode/settings.json

@@ -1,33 +0,0 @@
-{
-  "typescript.tsdk": "node_modules\\typescript\\lib",
-  "search.exclude": {
-    "**/boneyard": true
-  },
-  "files.exclude": {
-    "**/boneyard/**/*.ts": true
-  },
-  "cSpell.words": [
-    "badp",
-    "dflt",
-    "Eulers",
-    "fixlint",
-    "furst",
-    "luxon",
-    "multivalue",
-    "nums",
-    "oopsy",
-    "packlets",
-    "papaparse",
-    "prefixp",
-    "rtrn",
-    "rushstack",
-    "TCONV",
-    "TDEST",
-    "TELEM",
-    "templating",
-    "TSRC",
-    "TTOELEM",
-    "xyzzy"
-  ],
-  "CodeGPT.apiKey": "CodeGPT Plus Beta"
-}

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

@@ -1,458 +0,0 @@
-import { Converter } from '@fgv/ts-utils';
-import { Result } from '@fgv/ts-utils';
-import { Validator } from '@fgv/ts-utils';
-
-/**
- * Identifies whether some `unknown` value is a {@link JsonPrimitive | primitive},
- * {@link JsonObject | object} or {@link JsonArray | array}. Fails for any value
- * that cannot be converted to JSON (e.g. a function) _but_ this is a shallow test -
- * it does not test the properties of an object or elements in an array.
- * @param from - The `unknown` value to be tested
- * @public
- */
-export declare function classifyJsonValue(from: unknown): Result<JsonValueType>;
-
-declare namespace Converters {
-    export {
-        IJsonConverterContext,
-        jsonPrimitive,
-        jsonObject,
-        jsonArray,
-        jsonValue
-    }
-}
-export { Converters }
-
-/**
- * Reads all JSON files from a directory and apply a supplied converter.
- * @param srcPath - The path of the folder to be read.
- * @param options - {@link JsonFile.IJsonFsDirectoryOptions | Options} to control
- * conversion and filtering
- * @public
- */
-declare function convertJsonDirectorySync<T, TC = unknown>(srcPath: string, options: IJsonFsDirectoryOptions<T, TC>): Result<IReadDirectoryItem<T>[]>;
-
-/**
- * Reads and converts all JSON files from a directory, returning a
- * `Map<string, T>` indexed by file base name (i.e. minus the extension)
- * with an optional name transformation applied if present.
- * @param srcPath - The path of the folder to be read.
- * @param options - {@link JsonFile.IJsonFsDirectoryToMapOptions | Options} to control conversion,
- * filtering and naming.
- * @public
- */
-declare function convertJsonDirectoryToMapSync<T, TC = unknown>(srcPath: string, options: IJsonFsDirectoryToMapOptions<T, TC>): Result<Map<string, T>>;
-
-/**
- * Read a JSON file and apply a supplied converter.
- * @param srcPath - Path of the file to read.
- * @param converter - `Converter` used to convert the file contents
- * @returns `Success` with a result of type `<T>`, or `Failure`* with a message if an error occurs.
- * @public
- */
-declare function convertJsonFileSync<T, TC = unknown>(srcPath: string, converter: Converter<T, TC>): Result<T>;
-
-/**
- * @public
- */
-declare const DefaultJsonFsHelper: JsonFsHelper;
-
-/**
- * Default configuration for {@link JsonFile.JsonFsHelper | JsonFsHelper}.
- * @public
- */
-declare const DefaultJsonFsHelperConfig: IJsonFsHelperConfig;
-
-/**
- * @public
- */
-declare const DefaultJsonLike: IJsonLike;
-
-/**
- * Conversion context for JSON converters.
- * @public
- */
-declare interface IJsonConverterContext {
-    ignoreUndefinedProperties?: boolean;
-}
-
-/**
- * Options for directory conversion.
- * TODO: add filtering, allowed and excluded.
- * @public
- */
-declare interface IJsonFsDirectoryOptions<T, TC = unknown> {
-    /**
-     * The converter used to convert incoming JSON objects.
-     */
-    converter: Converter<T, TC> | Validator<T, TC>;
-    /**
-     * Filter applied to items in the directory
-     */
-    files?: RegExp[];
-}
-
-/**
- * Options controlling conversion of a directory to a `Map`.
- * @public
- */
-declare interface IJsonFsDirectoryToMapOptions<T, TC = unknown> extends IJsonFsDirectoryOptions<T, TC> {
-    transformName?: ItemNameTransformFunction<T>;
-}
-
-/**
- * Configuration for {@link JsonFile.JsonFsHelper | JsonFsHelper}.
- * @public
- */
-declare interface IJsonFsHelperConfig {
-    json: IJsonLike;
-    allowUndefinedWrite: boolean;
-    defaultFiles: RegExp[];
-}
-
-/**
- * @public
- */
-declare interface IJsonLike {
-    parse(text: string, reviver?: JsonReviver, options?: unknown): JsonValue | undefined;
-    stringify(value: JsonValue, replacer?: JsonReplacer, space?: string | number): string | undefined;
-}
-
-/**
- * Validation context for in-place JSON validators.
- * @public
- */
-declare interface IJsonValidatorContext {
-    ignoreUndefinedProperties?: boolean;
-}
-
-/**
- * Return value for one item in a directory conversion.
- * @public
- */
-declare interface IReadDirectoryItem<T> {
-    /**
-     * Relative name of the file that was processed
-     */
-    filename: string;
-    /**
-     * The payload of the file.
-     */
-    item: T;
-}
-
-/**
- * Test if an `unknown` is potentially a {@link JsonArray | JsonArray}.
- * @param from - The `unknown` to be tested.
- * @returns `true` if the supplied parameter is an array object,
- * `false` otherwise.
- * @public
- */
-export declare function isJsonArray(from: unknown): from is JsonArray;
-
-/**
- * Test if an `unknown` is potentially a {@link JsonObject | JsonObject}.
- * @param from - The `unknown` to be tested.
- * @returns `true` if the supplied parameter is a non-array, non-special object,
- * `false` otherwise.
- * @public
- */
-export declare function isJsonObject(from: unknown): from is JsonObject;
-
-/**
- * Test if an `unknown` is a {@link JsonValue | JsonValue}.
- * @param from - The `unknown` to be tested
- * @returns `true` if the supplied parameter is a valid {@link JsonPrimitive | JsonPrimitive},
- * `false` otherwise.
- * @public
- */
-export declare function isJsonPrimitive(from: unknown): from is JsonPrimitive;
-
-/**
- * Function to transform the name of a some entity, given an original name
- * and the contents of the entity.
- * @public
- */
-declare type ItemNameTransformFunction<T> = (name: string, item: T) => Result<string>;
-
-/**
- * A {@link JsonArray | JsonArray} is an array containing only valid {@link JsonValue | JsonValues}.
- * @public
- */
-export declare interface JsonArray extends Array<JsonValue> {
-}
-
-/**
- * An copying converter which converts a supplied `unknown` value to
- * a valid {@link JsonArray | JsonArray}. Fails by default if any properties or array elements
- * are `undefined` - this default behavior can be overridden by supplying an appropriate
- * {@link Converters.IJsonConverterContext | context} at runtime.
- *
- * Guaranteed to return a new array.
- * @public
- */
-declare const jsonArray: Converter<JsonArray, IJsonConverterContext>;
-
-/**
- * An in-place validator which validates that a supplied `unknown` value is
- * a valid {@link JsonArray | JsonArray}. Fails by default if any properties or array elements
- * are `undefined` - this default behavior can be overridden by supplying an appropriate
- * {@link Validators.IJsonValidatorContext | context} at runtime.
- * @public
- */
-declare const jsonArray_2: Validator<JsonArray, IJsonValidatorContext>;
-
-declare namespace JsonFile {
-    export {
-        readJsonFileSync,
-        convertJsonFileSync,
-        convertJsonDirectorySync,
-        convertJsonDirectoryToMapSync,
-        writeJsonFileSync,
-        IJsonFsDirectoryOptions,
-        IReadDirectoryItem,
-        ItemNameTransformFunction,
-        IJsonFsDirectoryToMapOptions,
-        IJsonFsHelperConfig,
-        JsonFsHelperInitOptions,
-        DefaultJsonFsHelperConfig,
-        JsonFsHelper,
-        DefaultJsonFsHelper,
-        JsonReviver,
-        JsonReplacerFunction,
-        JsonReplacerArray,
-        JsonReplacer,
-        IJsonLike,
-        DefaultJsonLike
-    }
-}
-export { JsonFile }
-
-/**
- * Helper class to simplify common filesystem operations involving JSON (or JSON-like)
- * files.
- * @public
- */
-declare class JsonFsHelper {
-    /**
-     * Configuration for this {@link JsonFile.JsonFsHelper | JsonFsHelper}.
-     */
-    readonly config: IJsonFsHelperConfig;
-    /**
-     * Construct a new {@link JsonFile.JsonFsHelper | JsonFsHelper}.
-     * @param json - Optional {@link JsonFile.IJsonLike | IJsonLike} used to process strings
-     * and JSON values.
-     */
-    constructor(init?: JsonFsHelperInitOptions);
-    /**
-     * Read type-safe JSON from a file.
-     * @param srcPath - Path of the file to read
-     * @returns `Success` with a {@link JsonValue | JsonValue} or `Failure`
-     * with a message if an error occurs.
-     */
-    readJsonFileSync(srcPath: string): Result<JsonValue>;
-    /**
-     * Read a JSON file and apply a supplied converter or validator.
-     * @param srcPath - Path of the file to read.
-     * @param cv - Converter or validator used to process the file.
-     * @returns `Success` with a result of type `<T>`, or `Failure`
-     * with a message if an error occurs.
-     */
-    convertJsonFileSync<T, TC = unknown>(srcPath: string, cv: Converter<T, TC> | Validator<T, TC>, context?: TC): Result<T>;
-    /**
-     * Reads all JSON files from a directory and apply a supplied converter or validator.
-     * @param srcPath - The path of the folder to be read.
-     * @param options - {@link JsonFile.IJsonFsDirectoryOptions | Options} to control
-     * conversion and filtering
-     */
-    convertJsonDirectorySync<T, TC = unknown>(srcPath: string, options: IJsonFsDirectoryOptions<T>, context?: TC): Result<IReadDirectoryItem<T>[]>;
-    /**
-     * Reads and converts or validates all JSON files from a directory, returning a
-     * `Map<string, T>` indexed by file base name (i.e. minus the extension)
-     * with an optional name transformation applied if present.
-     * @param srcPath - The path of the folder to be read.
-     * @param options - {@link JsonFile.IJsonFsDirectoryToMapOptions | Options} to control conversion,
-     * filtering and naming.
-     */
-    convertJsonDirectoryToMapSync<T, TC = unknown>(srcPath: string, options: IJsonFsDirectoryToMapOptions<T, TC>, context?: unknown): Result<Map<string, T>>;
-    /**
-     * Write type-safe JSON to a file.
-     * @param srcPath - Path of the file to write.
-     * @param value - The {@link JsonValue | JsonValue} to be written.
-     */
-    writeJsonFileSync(srcPath: string, value: JsonValue): Result<boolean>;
-    protected _pathMatchesOptions<T, TC>(options: IJsonFsDirectoryOptions<T, TC>, path: string): boolean;
-}
-
-/**
- * Initialization options for {@link JsonFile.JsonFsHelper | JsonFsHelper}.
- * @public
- */
-declare type JsonFsHelperInitOptions = Partial<IJsonFsHelperConfig>;
-
-/**
- * A {@link JsonObject | JsonObject} is a string-keyed object
- * containing only valid {@link JsonValue | JSON values}.
- * @public
- */
-export declare interface JsonObject {
-    [key: string]: JsonValue;
-}
-
-/**
- * An copying converter which converts a supplied `unknown` value into
- * a valid {@link JsonObject | JsonObject}. Fails by default if any properties or array elements
- * are `undefined` - this default behavior can be overridden by supplying an appropriate
- * {@link Converters.IJsonConverterContext | context} at runtime.
- *
- * Guaranteed to return a new object.
- * @public
- */
-declare const jsonObject: Converter<JsonObject, IJsonConverterContext>;
-
-/**
- * An in-place validator which validates that a supplied `unknown` value is
- * a valid {@link JsonObject | JsonObject}. Fails by default if any properties or array elements
- * are `undefined` - this default behavior can be overridden by supplying an appropriate
- * {@link Validators.IJsonValidatorContext | context} at runtime.
- * @public
- */
-declare const jsonObject_2: Validator<JsonObject, IJsonValidatorContext>;
-
-/**
- * Primitive (terminal) values allowed in by JSON.
- * @public
- */
-export declare type JsonPrimitive = boolean | number | string | null;
-
-/**
- * An converter which converts a supplied `unknown` value to a valid {@link JsonPrimitive | JsonPrimitive}.
- * @public
- */
-declare const jsonPrimitive: Converter<JsonPrimitive, IJsonConverterContext>;
-
-/**
- * An in-place validator which validates that a supplied `unknown` value is
- * a valid {@link JsonPrimitive | JsonPrimitive}.
- * @public
- */
-declare const jsonPrimitive_2: Validator<JsonPrimitive, IJsonValidatorContext>;
-
-/**
- * @public
- */
-declare type JsonReplacer = JsonReplacerFunction | JsonReplacerArray;
-
-/**
- * @public
- */
-declare type JsonReplacerArray = (string | number)[];
-
-/**
- * @public
- */
-declare type JsonReplacerFunction = (key: string, value: JsonValue) => JsonValue;
-
-/**
- * @public
- */
-declare type JsonReviver = (key: string, value: JsonValue) => JsonValue;
-
-/**
- * A {@link JsonValue | JsonValue} is one of: a {@link JsonPrimitive | JsonPrimitive},
- * a {@link JsonObject | JsonObject} or an {@link JsonArray | JsonArray}.
- * @public
- */
-export declare type JsonValue = JsonPrimitive | JsonObject | JsonArray;
-
-/**
- * An copying converter which converts a supplied `unknown` value to a
- * valid {@link JsonValue | JsonValue}. Fails by default if any properties or array elements
- * are `undefined` - this default behavior can be overridden by supplying an appropriate
- * {@link Converters.IJsonConverterContext | context} at runtime.
- * @public
- */
-declare const jsonValue: Converter<JsonValue, IJsonConverterContext>;
-
-/**
- * An in-place validator which validates that a supplied `unknown` value is
- * a valid {@link JsonValue | JsonValue}. Fails by default if any properties or array elements
- * are `undefined` - this default behavior can be overridden by supplying an appropriate
- * {@link Validators.IJsonValidatorContext | context} at runtime.
- * @public
- */
-declare const jsonValue_2: Validator<JsonValue, IJsonValidatorContext>;
-
-/**
- * Classes of {@link JsonValue | JsonValue}.
- * @public
- */
-export declare type JsonValueType = 'primitive' | 'object' | 'array';
-
-/**
- * Picks a nested {@link JsonObject | JsonObject} from a supplied
- * {@link JsonObject | JsonObject}.
- * @param src - The {@link JsonObject | object} from which the field is
- * to be picked.
- * @param path - Dot-separated path of the member to be picked.
- * @returns `Success` with the property if the path is valid and the value
- * is an object. Returns `Failure` with details if an error occurs.
- * @public
- */
-export declare function pickJsonObject(src: JsonObject, path: string): Result<JsonObject>;
-
-/**
- * Picks a nested field from a supplied {@link JsonObject | JsonObject}.
- * @param src - The {@link JsonObject | object} from which the field is to be picked.
- * @param path - Dot-separated path of the member to be picked.
- * @returns `Success` with the property if the path is valid, `Failure`
- * with an error message otherwise.
- * @public
- */
-export declare function pickJsonValue(src: JsonObject, path: string): Result<JsonValue>;
-
-/**
- * {@inheritdoc JsonFile.JsonFsHelper.readJsonFileSync}
- * @public
- */
-declare function readJsonFileSync(srcPath: string): Result<JsonValue>;
-
-/**
- * "Sanitizes" an `unknown` by stringifying and then parsing it.  Guarantees a
- * valid {@link JsonValue | JsonValue} but is not idempotent and gives no guarantees
- * about fidelity. Fails if the supplied value cannot be stringified as Json.
- * @param from - The `unknown` to be sanitized.
- * @returns `Success` with a {@link JsonValue | JsonValue} if conversion succeeds,
- * `Failure` with details if an error occurs.
- * @public
- */
-export declare function sanitizeJson(from: unknown): Result<JsonValue>;
-
-/**
- * Sanitizes some value using JSON stringification and parsing, returning an
- * returning a matching strongly-typed value.
- * @param from - The value to be sanitized.
- * @returns `Success` with a {@link JsonObject | JsonObject} if conversion succeeds,
- * `Failure` with details if an error occurs.
- * @public
- */
-export declare function sanitizeJsonObject<T>(from: T): Result<T>;
-
-declare namespace Validators {
-    export {
-        IJsonValidatorContext,
-        jsonPrimitive_2 as jsonPrimitive,
-        jsonObject_2 as jsonObject,
-        jsonArray_2 as jsonArray,
-        jsonValue_2 as jsonValue
-    }
-}
-export { Validators }
-
-/**
- * {@inheritDoc JsonFile.JsonFsHelper.writeJsonFileSync}
- * @public
- */
-declare function writeJsonFileSync(srcPath: string, value: JsonValue): Result<boolean>;
-
-export { }

package/dist/tsdoc-metadata.json

@@ -1,11 +0,0 @@
-// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
-// It should be published with your NPM package.  It should not be tracked by Git.
-{
-  "tsdocVersion": "0.12",
-  "toolPackages": [
-    {
-      "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.52.10"
-    }
-  ]
-}

package/lib/test/unit/common.test.d.ts

@@ -1,2 +0,0 @@
-import '@fgv/ts-utils-jest';
-//# sourceMappingURL=common.test.d.ts.map

package/lib/test/unit/converters.test.d.ts

@@ -1,2 +0,0 @@
-import '@fgv/ts-utils-jest';
-//# sourceMappingURL=converters.test.d.ts.map

package/lib/test/unit/data/file/bad/bad3.json

@@ -1,3 +0,0 @@
-{
-  "id": "bad3"
-}

package/lib/test/unit/data/file/bad/thing1.json

@@ -1,4 +0,0 @@
-{
-  "name": "thing1",
-  "optionalString": "thing 1 optional string"
-}

package/lib/test/unit/data/file/bad/thing2.json

@@ -1,3 +0,0 @@
-{
-  "name": "thing2"
-}

package/lib/test/unit/data/file/good/thing1.json

@@ -1,4 +0,0 @@
-{
-  "name": "thing1",
-  "optionalString": "thing 1 optional string"
-}

package/lib/test/unit/data/file/good/thing2.json

@@ -1,3 +0,0 @@
-{
-  "name": "thing2"
-}

package/lib/test/unit/file.test.d.ts

@@ -1,2 +0,0 @@
-import '@fgv/ts-utils-jest';
-//# sourceMappingURL=file.test.d.ts.map

package/lib/test/unit/jsonFsHelper.test.d.ts

@@ -1,2 +0,0 @@
-import '@fgv/ts-utils-jest';
-//# sourceMappingURL=jsonFsHelper.test.d.ts.map

package/lib/test/unit/validators.test.d.ts

@@ -1,2 +0,0 @@
-import '@fgv/ts-utils-jest';
-//# sourceMappingURL=validators.test.d.ts.map