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

package/dist/packlets/json/common.js

@@ -0,0 +1,145 @@
+/*
+ * 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.
+ */
+import { captureResult, fail, succeed } from '@fgv/ts-utils';
+/**
+ * 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 function isJsonPrimitive(from) {
+    return typeof from === 'boolean' || typeof from === 'number' || typeof from === 'string' || from === null;
+}
+/**
+ * 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
+ * with no symbol keys, `false` otherwise.
+ * @public
+ */
+export function isJsonObject(from) {
+    return (typeof from === 'object' &&
+        from !== null &&
+        !Array.isArray(from) &&
+        !(from instanceof RegExp) &&
+        !(from instanceof Date) &&
+        !(from instanceof Map) &&
+        !(from instanceof Set) &&
+        !(from instanceof Error) &&
+        Object.getOwnPropertySymbols(from).length === 0);
+}
+/**
+ * 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 function isJsonArray(from) {
+    return typeof from === 'object' && Array.isArray(from);
+}
+/**
+ * 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 function classifyJsonValue(from) {
+    if (isJsonPrimitive(from)) {
+        return succeed('primitive');
+    }
+    else if (isJsonObject(from)) {
+        return succeed('object');
+    }
+    else if (isJsonArray(from)) {
+        return succeed('array');
+    }
+    return fail(`Invalid JSON: ${from}`);
+}
+/**
+ * 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 function pickJsonValue(src, path) {
+    let result = src;
+    for (const part of path.split('.')) {
+        if (result && isJsonObject(result)) {
+            result = result[part];
+            if (result === undefined) {
+                return fail(`${path}: child '${part}' does not exist`);
+            }
+        }
+        else {
+            return fail(`${path}: child '${part}' does not exist`);
+        }
+    }
+    return succeed(result);
+}
+/**
+ * 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 function pickJsonObject(src, path) {
+    return pickJsonValue(src, path).onSuccess((v) => {
+        if (!isJsonObject(v)) {
+            return fail(`${path}: not an object`);
+        }
+        return succeed(v);
+    });
+}
+/**
+ * "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 function sanitizeJson(from) {
+    return captureResult(() => JSON.parse(JSON.stringify(from)));
+}
+/**
+ * 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 function sanitizeJsonObject(from) {
+    return captureResult(() => JSON.parse(JSON.stringify(from)));
+}
+//# sourceMappingURL=common.js.map

package/dist/packlets/json/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 './common';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,23 @@
+/*
+ * 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.
+ */
+export {};
+//# sourceMappingURL=common.js.map

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

@@ -0,0 +1,90 @@
+/*
+ * 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 { Conversion, Converters } from '@fgv/ts-utils';
+/**
+ * A helper function to create a {@link JsonCompatible.ArrayConverter | JSON-compatible ArrayConverter<T, TC>}
+ * 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 JsonCompatible.ArrayConverter | JSON-compatible ArrayConverter<T, TC>} which returns `JsonCompatibleType<T>[]`.
+ * @public
+ */
+export function arrayOf(converter, onError = 'failOnError') {
+    return Converters.arrayOf(converter, onError);
+}
+/**
+ * A helper function to create a {@link JsonCompatible.RecordConverter | JSON-compatible RecordConverter<T, TC, TK>}
+ * 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 `Converters.KeyedConverterOptions` 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 `Converters.KeyedConverterOptions<TK, TC>` which
+ * supplies a key converter and/or error-handling options.
+ * @returns A {@link JsonCompatible.RecordConverter | JSON-compatible RecordConverter<T, TC, TK>} which
+ * converts a supplied `unknown` value to a valid record of {@link JsonCompatibleType | JsonCompatible} values.
+ * @public
+ */
+export function recordOf(converter, options) {
+    return Converters.recordOf(converter, options !== null && options !== void 0 ? options : { onError: 'fail' });
+}
+/**
+ * A helper function to create a {@link JsonCompatible.ObjectConverter | JSON-compatible ObjectConverter<T, TC>} 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 {@link JsonCompatible.ObjectConverter | JSON-compatible ObjectConverter<T, TC>} which
+ * converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @public
+ */
+export function object(properties, options) {
+    return new Conversion.ObjectConverter(properties, options);
+}
+/**
+ * A helper function to create a {@link JsonCompatible.ObjectConverter | JSON-compatible ObjectConverter<T, TC>} 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 {@link JsonCompatible.ObjectConverter | JSON-compatible ObjectConverter<T, TC>} which
+ * converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @public
+ */
+export function strictObject(properties, options) {
+    const objectOptions = Object.assign(Object.assign({}, options), { strict: true });
+    return new Conversion.ObjectConverter(properties, objectOptions);
+}
+/**
+ * A helper function to create a {@link JsonCompatible.Converter | JSON-compatible Converter<T, TC>} 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 {@link JsonCompatible.Converter | JSON-compatible Converter<T, TC>} which
+ * converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
+ * @public
+ */
+export function discriminatedObject(discriminatorProp, converters) {
+    return Converters.discriminatedObject(discriminatorProp, converters);
+}
+//# sourceMappingURL=converters.js.map

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

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+export * from './common';
+import * as Converters from './converters';
+import * as Validators from './validators';
+export { Converters, Validators };
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,54 @@
+/*
+ * 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 { 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 validator to use.
+ * @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 function arrayOf(validateElement, params) {
+    return Validators.arrayOf(validateElement, params !== null && params !== void 0 ? params : {});
+}
+/**
+ * A helper function to create a {@link JsonCompatible.RecordValidator | JSON-compatible RecordValidator<T, TC, TK>} which validates a supplied `unknown` value
+ * to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @param validateElement - The element validator to use.
+ * @param options - The options to use for the validation.
+ * @returns A `Validation.Validator<Record<TK, JsonCompatibleType<T>>, TC>` which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
+ * @public
+ */
+export function recordOf(validateElement, options) {
+    return 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
+ */
+export function object(properties, params) {
+    return Validators.object(properties, params !== null && params !== void 0 ? params : {});
+}
+//# sourceMappingURL=validators.js.map

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

@@ -0,0 +1,74 @@
+/*
+ * 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.
+ */
+import { DefaultJsonFsHelper, JsonFsHelper } from './jsonFsHelper';
+import { DefaultJsonLike } from './jsonLike';
+/**
+ * {@inheritdoc JsonFile.JsonFsHelper.readJsonFileSync}
+ * @public
+ */
+export function readJsonFileSync(srcPath) {
+    return DefaultJsonFsHelper.readJsonFileSync(srcPath);
+}
+/**
+ * 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
+ */
+export function convertJsonFileSync(srcPath, converter) {
+    return DefaultJsonFsHelper.convertJsonFileSync(srcPath, converter);
+}
+/**
+ * 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
+ */
+export function convertJsonDirectorySync(srcPath, options) {
+    return DefaultJsonFsHelper.convertJsonDirectorySync(srcPath, options);
+}
+/**
+ * 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
+ */
+export function convertJsonDirectoryToMapSync(srcPath, options) {
+    return DefaultJsonFsHelper.convertJsonDirectoryToMapSync(srcPath, options);
+}
+const CompatJsonFsHelper = new JsonFsHelper({
+    json: DefaultJsonLike,
+    allowUndefinedWrite: true // for compatibility
+});
+/**
+ * {@inheritDoc JsonFile.JsonFsHelper.writeJsonFileSync}
+ * @public
+ */
+export function writeJsonFileSync(srcPath, value) {
+    return CompatJsonFsHelper.writeJsonFileSync(srcPath, value);
+}
+//# sourceMappingURL=file.js.map

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

@@ -0,0 +1,30 @@
+/*
+ * 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.
+ */
+// Browser-safe JSON file exports - excludes Node.js filesystem dependencies
+// Export browser-safe core functionality
+export * from './jsonLike';
+// Export FileTree-based helper (web-compatible)
+export * from './jsonTreeHelper';
+// Exclude:
+// - file.ts (wraps jsonFsHelper - requires Node.js fs/path)
+// - jsonFsHelper (requires Node.js fs/path)
+//# sourceMappingURL=index.browser.js.map

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

@@ -0,0 +1,30 @@
+/*
+ * 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 core JSON functionality (no filesystem deps)
+export * from './file';
+export * from './jsonLike';
+// Export FileTree-based helper (web-compatible)
+export * from './jsonTreeHelper';
+// Export filesystem helpers separately for tree-shaking
+// Web apps that don't import JsonFsHelper won't bundle fs/path
+export * from './jsonFsHelper';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,166 @@
+/*
+ * 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.
+ */
+import { captureResult, fail, mapResults, succeed } from '@fgv/ts-utils';
+import fs from 'fs';
+import path from 'path';
+import { DefaultJsonLike } from './jsonLike';
+/**
+ * Function to transform the name of some entity, given only a previous name. This
+ * default implementation always returns `Success` with the value that was passed in.
+ * @param n - The name to be transformed.
+ * @returns - `Success` with the string that was passed in.
+ * @public
+ */
+const defaultNameTransformer = (n) => succeed(n);
+/**
+ * Default configuration for {@link JsonFile.JsonFsHelper | JsonFsHelper}.
+ * @public
+ */
+export const DefaultJsonFsHelperConfig = {
+    json: DefaultJsonLike,
+    allowUndefinedWrite: false,
+    defaultFiles: [/.*.json/]
+};
+/**
+ * Helper class to simplify common filesystem operations involving JSON (or JSON-like)
+ * files.
+ * @public
+ */
+export class JsonFsHelper {
+    /**
+     * Construct a new {@link JsonFile.JsonFsHelper | JsonFsHelper}.
+     * @param json - Optional {@link JsonFile.IJsonLike | IJsonLike} used to process strings
+     * and JSON values.
+     */
+    constructor(init) {
+        this.config = Object.assign(Object.assign({}, DefaultJsonFsHelperConfig), (init !== null && init !== void 0 ? init : {}));
+    }
+    /**
+     * 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) {
+        return captureResult(() => {
+            const fullPath = path.resolve(srcPath);
+            const body = fs.readFileSync(fullPath, 'utf8').toString();
+            return this.config.json.parse(body);
+        });
+    }
+    /**
+     * 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(srcPath, cv, context) {
+        return this.readJsonFileSync(srcPath).onSuccess((json) => {
+            return cv.convert(json, context);
+        });
+    }
+    /**
+     * 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(srcPath, options, context) {
+        return captureResult(() => {
+            const fullPath = path.resolve(srcPath);
+            if (!fs.statSync(fullPath).isDirectory()) {
+                throw new Error(`${fullPath}: Not a directory`);
+            }
+            const files = fs.readdirSync(fullPath, { withFileTypes: true });
+            const results = files
+                .map((fi) => {
+                if (fi.isFile() && this._pathMatchesOptions(options, fi.name)) {
+                    const filePath = path.resolve(fullPath, fi.name);
+                    return this.convertJsonFileSync(filePath, options.converter, context)
+                        .onSuccess((payload) => {
+                        return succeed({
+                            filename: fi.name,
+                            item: payload
+                        });
+                    })
+                        .onFailure((message) => {
+                        return fail(`${fi.name}: ${message}`);
+                    });
+                }
+                return undefined;
+            })
+                .filter((r) => r !== undefined);
+            return mapResults(results).orThrow();
+        });
+    }
+    /**
+     * 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(srcPath, options, context) {
+        return this.convertJsonDirectorySync(srcPath, options, context).onSuccess((items) => {
+            var _a;
+            const transformName = (_a = options.transformName) !== null && _a !== void 0 ? _a : defaultNameTransformer;
+            return mapResults(items.map((item) => {
+                const basename = path.basename(item.filename, '.json');
+                return transformName(basename, item.item).onSuccess((name) => {
+                    return succeed([name, item.item]);
+                });
+            })).onSuccess((items) => {
+                return succeed(new Map(items));
+            });
+        });
+    }
+    /**
+     * 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, value) {
+        return captureResult(() => {
+            const fullPath = path.resolve(srcPath);
+            const stringified = this.config.json.stringify(value, undefined, 2);
+            /* c8 ignore next 3 */
+            if (stringified === undefined && this.config.allowUndefinedWrite !== true) {
+                throw new Error(`Could not stringify ${value}`);
+            }
+            fs.writeFileSync(fullPath, stringified);
+            return true;
+        });
+    }
+    _pathMatchesOptions(options, path) {
+        var _a;
+        /* c8 ignore next 1 */
+        const match = (_a = options.files) !== null && _a !== void 0 ? _a : this.config.defaultFiles;
+        return match.some((m) => m.exec(path));
+    }
+}
+/**
+ * @public
+ */
+export const DefaultJsonFsHelper = new JsonFsHelper();
+//# sourceMappingURL=jsonFsHelper.js.map