@fgv/ts-json-base 5.0.1-9 → 5.0.1

package/dist/packlets/json-file/jsonLike.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2024 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.
+ */
+/**
+ * @public
+ */
+export const DefaultJsonLike = JSON;
+//# sourceMappingURL=jsonLike.js.map

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

@@ -0,0 +1,116 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { mapResults, succeed } from '@fgv/ts-utils';
+import { DefaultJsonLike } from './jsonLike';
+/**
+ * Helper class to work with JSON files using FileTree API (web-compatible).
+ * @public
+ */
+export class JsonTreeHelper {
+    /**
+     * Construct a new JsonTreeHelper.
+     * @param json - Optional {@link JsonFile.IJsonLike | IJsonLike} used to process strings
+     * and JSON values.
+     */
+    constructor(json) {
+        this.json = json !== null && json !== void 0 ? json : DefaultJsonLike;
+    }
+    /**
+     * Read type-safe JSON from a file in a FileTree.
+     * @param fileTree - The FileTree to read from
+     * @param filePath - Path of the file to read within the tree
+     * @returns `Success` with a {@link JsonValue | JsonValue} or `Failure`
+     * with a message if an error occurs.
+     */
+    readJsonFromTree(fileTree, filePath) {
+        return fileTree.getFile(filePath).onSuccess((file) => {
+            // Now getContents() returns JsonCompatibleType<unknown> which is assignable to JsonValue!
+            return file.getContents();
+        });
+    }
+    /**
+     * Read a JSON file from a FileTree and apply a supplied converter or validator.
+     * @param fileTree - The FileTree to read from
+     * @param filePath - Path of the file to read within the tree
+     * @param cv - Converter or validator used to process the file.
+     * @param context - Optional context for the converter/validator
+     * @returns `Success` with a result of type `<T>`, or `Failure`
+     * with a message if an error occurs.
+     */
+    convertJsonFromTree(fileTree, filePath, cv, context) {
+        return this.readJsonFromTree(fileTree, filePath).onSuccess((json) => {
+            return cv.convert(json, context);
+        });
+    }
+    /**
+     * Reads all JSON files from a directory in a FileTree and applies a converter or validator.
+     * @param fileTree - The FileTree to read from
+     * @param dirPath - The path of the directory within the tree
+     * @param cv - Converter or validator to apply to each JSON file
+     * @param filePattern - Optional regex pattern to filter files (defaults to .json files)
+     * @param context - Optional context for the converter/validator
+     * @returns Array of items with filename and converted content
+     */
+    convertJsonDirectoryFromTree(fileTree, dirPath, cv, filePattern, context) {
+        const pattern = filePattern !== null && filePattern !== void 0 ? filePattern : /\.json$/;
+        return fileTree.getDirectory(dirPath).onSuccess((dir) => {
+            return dir.getChildren().onSuccess((children) => {
+                const results = children
+                    .filter((child) => child.type === 'file' && pattern.test(child.name))
+                    .map((file) => {
+                    return this.convertJsonFromTree(fileTree, file.absolutePath, cv, context).onSuccess((item) => {
+                        return succeed({
+                            filename: file.name,
+                            item
+                        });
+                    });
+                });
+                return mapResults(results);
+            });
+        });
+    }
+    /**
+     * Reads and converts all JSON files from a directory in a FileTree,
+     * returning a Map indexed by file base name.
+     * @param fileTree - The FileTree to read from
+     * @param dirPath - The path of the directory within the tree
+     * @param cv - Converter or validator to apply to each JSON file
+     * @param filePattern - Optional regex pattern to filter files
+     * @param context - Optional context for the converter/validator
+     * @returns Map of basename to converted content
+     */
+    convertJsonDirectoryToMapFromTree(fileTree, dirPath, cv, filePattern, context) {
+        return this.convertJsonDirectoryFromTree(fileTree, dirPath, cv, filePattern, context).onSuccess((items) => {
+            const map = new Map();
+            for (const item of items) {
+                const basename = item.filename.replace(/\.json$/, '');
+                map.set(basename, item.item);
+            }
+            return succeed(map);
+        });
+    }
+}
+/**
+ * @public
+ */
+export const DefaultJsonTreeHelper = new JsonTreeHelper();
+//# sourceMappingURL=jsonTreeHelper.js.map

package/dist/packlets/validators/index.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2020 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.
+ */
+export * from './validators';
+//# sourceMappingURL=index.js.map

package/dist/packlets/validators/validators.js

@@ -0,0 +1,179 @@
+/*
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { Validation, fail } from '@fgv/ts-utils';
+import { isJsonArray, isJsonObject } from '../json';
+/**
+ * An in-place validator which validates that a supplied `unknown` value is
+ * a valid {@link JsonPrimitive | JsonPrimitive}.
+ * @public
+ */
+export const jsonPrimitive = new Validation.Base.GenericValidator({
+    validator: (from, ctx, self) => {
+        if (from === null) {
+            return true;
+        }
+        switch (typeof from) {
+            case 'boolean':
+            case 'string':
+                return true;
+            case 'number':
+                if (!Number.isNaN(from)) {
+                    return true;
+                }
+                break;
+        }
+        if (from === undefined && (ctx === null || ctx === void 0 ? void 0 : ctx.ignoreUndefinedProperties) === true) {
+            return true;
+        }
+        return fail(`"${String(from)}": invalid JSON primitive.`);
+    }
+});
+/**
+ * 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
+ */
+export const jsonObject = new Validation.Base.GenericValidator({
+    validator: (from, ctx, self) => {
+        if (!isJsonObject(from)) {
+            return fail('invalid JSON object.');
+        }
+        const errors = [];
+        for (const [name, value] of Object.entries(from)) {
+            jsonValue.validate(value, ctx).onFailure((m) => {
+                errors.push(`${name}: ${m}`);
+                return fail(m);
+            });
+        }
+        if (errors.length > 0) {
+            return fail(`invalid JSON object:\n${errors.join('\n')}`);
+        }
+        return true;
+    }
+});
+/**
+ * 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
+ */
+export const jsonArray = new Validation.Base.GenericValidator({
+    validator: (from, ctx, self) => {
+        if (!isJsonArray(from)) {
+            return fail('not an array');
+        }
+        const errors = [];
+        for (let i = 0; i < from.length; i++) {
+            const value = from[i];
+            jsonValue.validate(value, ctx).onFailure((m) => {
+                errors.push(`${i}: ${m}`);
+                return fail(m);
+            });
+        }
+        if (errors.length > 0) {
+            return fail(`array contains non-json elements:\n${errors.join('\n')}`);
+        }
+        return true;
+    }
+});
+/**
+ * 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
+ */
+export const jsonValue = new Validation.Base.GenericValidator({
+    validator: (from, ctx, self) => {
+        if (isJsonArray(from)) {
+            const result = jsonArray.validate(from, ctx);
+            return result.success === true ? true : result;
+        }
+        else if (isJsonObject(from)) {
+            const result = jsonObject.validate(from, ctx);
+            return result.success === true ? true : result;
+        }
+        const result = jsonPrimitive.validate(from, ctx);
+        return result.success === true ? true : result;
+    }
+});
+/**
+ * A {@link Validation.Classes.StringValidator | StringValidator} which validates a string in place.
+ * Accepts {@link Validators.IJsonValidatorContext | IJsonValidatorContext} but ignores it.
+ * @public
+ */
+export const string = new Validation.Classes.StringValidator();
+/**
+ * A {@link Validation.Classes.NumberValidator | NumberValidator} which validates a number in place.
+ * Accepts {@link Validators.IJsonValidatorContext | IJsonValidatorContext} but ignores it.
+ * @public
+ */
+export const number = new Validation.Classes.NumberValidator();
+/**
+ * A {@link Validation.Classes.BooleanValidator | BooleanValidator} which validates a boolean in place.
+ * Accepts {@link Validators.IJsonValidatorContext | IJsonValidatorContext} but ignores it.
+ * @public
+ */
+export const boolean = new Validation.Classes.BooleanValidator();
+/**
+ * Helper to create a validator for a literal value.
+ * Accepts {@link Validators.IJsonValidatorContext | IJsonValidatorContext} but ignores it.
+ * Mirrors the behavior of `@fgv/ts-utils`.
+ * @public
+ */
+export function literal(value) {
+    return new Validation.Base.GenericValidator({
+        validator: (from) => {
+            return from === value ? true : fail(`Expected literal ${String(value)}, found ${JSON.stringify(from)}`);
+        }
+    });
+}
+/**
+ * Helper function to create a {@link Validator | Validator} which validates `unknown` to one of a set of
+ * supplied enumerated values. Anything else fails.
+ *
+ * @remarks
+ * This JSON variant accepts an {@link Validators.IJsonValidatorContext | IJsonValidatorContext} OR
+ * a `ReadonlyArray<T>` as its validation context. If the context is an array, it is used to override the
+ * allowed values for that validation; otherwise, the original `values` supplied at creation time are used.
+ *
+ * @param values - Array of allowed values.
+ * @param message - Optional custom failure message.
+ * @returns A new {@link Validator | Validator} returning `<T>`.
+ * @public
+ */
+export function enumeratedValue(values, message) {
+    return new Validation.Base.GenericValidator({
+        validator: (from, context) => {
+            const effectiveValues = Array.isArray(context) ? context : values;
+            const index = effectiveValues.indexOf(from);
+            if (index >= 0) {
+                return true;
+            }
+            return fail(message !== null && message !== void 0 ? message : `Invalid enumerated value ${JSON.stringify(from)}`);
+        }
+    });
+}
+//# sourceMappingURL=validators.js.map

package/dist/test/fixtures/file-tree/config.json

@@ -0,0 +1 @@
+{ "name": "test", "enabled": true }

package/dist/test/fixtures/file-tree/data/items.json

@@ -0,0 +1 @@
+[1, 2, 3]

package/dist/test/fixtures/file-tree/docs/api/reference.json

@@ -0,0 +1 @@
+{ "endpoints": [] }

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

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

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

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

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

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

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

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

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

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

package/dist/test/unit/json-compatible/helpers.js

@@ -0,0 +1,32 @@
+/*
+ * 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.
+ */
+// Factory helpers for runtime sections
+export function makeUser(overrides = {}) {
+    return Object.assign({ id: 'u1', name: 'Test User', tags: ['a', 'b'], meta: { active: true, score: 10 } }, overrides);
+}
+export function makeAlpha() {
+    return { kind: 'alpha', value: 'ok' };
+}
+export function makeBeta() {
+    return { kind: 'beta', count: 3 };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/tsdoc-metadata.json

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

package/lib/packlets/json-file/index.browser.d.ts

@@ -1,4 +1,4 @@
-export * from './file';
 export * from './jsonLike';
 export * from './jsonTreeHelper';
+export type { IJsonFsDirectoryOptions, IReadDirectoryItem, ItemNameTransformFunction, IJsonFsDirectoryToMapOptions, IJsonFsHelperConfig, JsonFsHelperInitOptions } from './jsonFsHelper';
 //# sourceMappingURL=index.browser.d.ts.map

package/lib/packlets/json-file/index.browser.js

@@ -36,11 +36,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 // Browser-safe JSON file exports - excludes Node.js filesystem dependencies
-// Export core JSON functionality (no filesystem deps)
-__exportStar(require("./file"), exports);
+// Export browser-safe core functionality
 __exportStar(require("./jsonLike"), exports);
 // Export FileTree-based helper (web-compatible)
 __exportStar(require("./jsonTreeHelper"), exports);
 // Exclude:
+// - file.ts (wraps jsonFsHelper - requires Node.js fs/path)
 // - jsonFsHelper (requires Node.js fs/path)
 //# sourceMappingURL=index.browser.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-json-base",
-  "version": "5.0.1-9",
+  "version": "5.0.1",
   "description": "Typescript types and basic functions for working with json",
   "main": "lib/index.js",
   "types": "dist/ts-json-base.d.ts",
@@ -44,7 +44,6 @@
     "ts-node": "^10.9.2",
     "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",
@@ -53,11 +52,14 @@
     "@rushstack/eslint-config": "4.5.3",
     "eslint-plugin-tsdoc": "~0.4.0",
     "@types/luxon": "^3.7.1",
-    "@fgv/ts-utils": "5.0.1-9",
-    "@fgv/ts-utils-jest": "5.0.1-9"
+    "@rushstack/heft-node-rig": "2.11.4",
+    "@microsoft/api-extractor": "^7.53.3",
+    "@fgv/ts-utils": "5.0.1",
+    "@fgv/heft-dual-rig": "0.1.0",
+    "@fgv/ts-utils-jest": "5.0.1"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.0.1-9"
+    "@fgv/ts-utils": "5.0.1"
   },
   "dependencies": {
     "luxon": "^3.7.2"