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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-json-base",
-  "version": "5.0.0-22",
+  "version": "5.0.0-23",
   "description": "Typescript types and basic functions for working with json",
   "main": "lib/index.js",
   "types": "dist/ts-json-base.d.ts",
@@ -39,12 +39,12 @@
     "@rushstack/eslint-patch": "~1.12.0",
     "@rushstack/eslint-config": "~4.4.0",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils": "5.0.0-22",
-    "@fgv/ts-utils-jest": "5.0.0-22",
-    "@fgv/ts-extras": "5.0.0-22"
+    "@fgv/ts-utils": "5.0.0-23",
+    "@fgv/ts-utils-jest": "5.0.0-23",
+    "@fgv/ts-extras": "5.0.0-23"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.0.0-22"
+    "@fgv/ts-utils": "5.0.0-23"
   },
   "scripts": {
     "build": "heft test --clean",

package/src/index.ts

@@ -1,28 +0,0 @@
-/*
- * 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 * as Converters from './packlets/converters';
-import * as JsonFile from './packlets/json-file';
-import * as Validators from './packlets/validators';
-
-export * from './packlets/json';
-export { Converters, JsonFile, Validators };

package/src/packlets/converters/converters.ts

@@ -1,174 +0,0 @@
-/*
- * 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 { Conversion, Converter, Result, fail, succeed } from '@fgv/ts-utils';
-import { JsonArray, JsonObject, JsonPrimitive, JsonValue, isJsonArray, isJsonObject } from '../json';
-
-/* eslint-disable no-use-before-define, @typescript-eslint/no-use-before-define */
-
-/**
- * Conversion context for JSON converters.
- * @public
- */
-export interface IJsonConverterContext {
-  ignoreUndefinedProperties?: boolean;
-}
-
-/**
- * An converter which converts a supplied `unknown` value to a valid {@link JsonPrimitive | JsonPrimitive}.
- * @public
- */
-export const jsonPrimitive: Converter<JsonPrimitive, IJsonConverterContext> = new Conversion.BaseConverter(
-  (
-    from: unknown,
-    __self: Converter<JsonPrimitive, IJsonConverterContext>,
-    ctx?: IJsonConverterContext
-  ): Result<JsonPrimitive> => {
-    if (from === null) {
-      return succeed(null);
-    }
-    switch (typeof from) {
-      case 'boolean':
-      case 'string':
-        return succeed(from);
-      case 'number':
-        if (!Number.isNaN(from)) {
-          return succeed(from);
-        }
-        break;
-    }
-    return fail(`"${String(from)}": not a valid JSON primitive.`);
-  }
-);
-
-/**
- * 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
- */
-export const jsonObject: Converter<JsonObject, IJsonConverterContext> = new Conversion.BaseConverter(
-  (
-    from: unknown,
-    __self: Converter<JsonObject, IJsonConverterContext>,
-    ctx?: IJsonConverterContext
-  ): Result<JsonObject> => {
-    if (!isJsonObject(from)) {
-      return fail('not a valid JSON object.');
-    }
-    const obj: JsonObject = {};
-    const errors: string[] = [];
-    for (const [name, value] of Object.entries(from)) {
-      if (value === undefined && ctx?.ignoreUndefinedProperties === true) {
-        // optionally ignore undefined values
-        continue;
-      }
-      jsonValue
-        .convert(value, ctx)
-        .onSuccess((v: JsonValue) => {
-          obj[name] = v;
-          return succeed(v);
-        })
-        .onFailure((m) => {
-          errors.push(`${name}: ${m}`);
-          return fail(m);
-        });
-    }
-    if (errors.length > 0) {
-      return fail(`not a valid JSON object:\n${errors.join('\n')}`);
-    }
-    return succeed(obj);
-  }
-);
-
-/**
- * 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
- */
-export const jsonArray: Converter<JsonArray, IJsonConverterContext> = new Conversion.BaseConverter(
-  (
-    from: unknown,
-    __self: Converter<JsonArray, IJsonConverterContext>,
-    ctx?: IJsonConverterContext
-  ): Result<JsonArray> => {
-    if (!isJsonArray(from)) {
-      return fail('not an array');
-    }
-    const arr: JsonValue[] = [];
-    const errors: string[] = [];
-    for (let i = 0; i < from.length; i++) {
-      const value = from[i];
-      if (value === undefined && ctx?.ignoreUndefinedProperties === true) {
-        // convert undefined to 'null' for parity with JSON.stringify
-        arr.push(null);
-        continue;
-      }
-      jsonValue
-        .convert(value, ctx)
-        .onSuccess((v) => {
-          arr.push(v);
-          return succeed(v);
-        })
-        .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 succeed(arr);
-  }
-);
-
-/**
- * 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
- */
-export const jsonValue: Converter<JsonValue, IJsonConverterContext> = new Conversion.BaseConverter<
-  JsonValue,
-  IJsonConverterContext
->(
-  (
-    from: unknown,
-    __self: Converter<JsonValue, IJsonConverterContext>,
-    ctx?: IJsonConverterContext
-  ): Result<JsonValue> => {
-    if (isJsonArray(from)) {
-      return jsonArray.convert(from, ctx);
-    } else if (isJsonObject(from)) {
-      return jsonObject.convert(from, ctx);
-    }
-    return jsonPrimitive.convert(from, ctx);
-  }
-);

package/src/packlets/converters/index.ts

@@ -1,23 +0,0 @@
-/*
- * 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 './converters';

package/src/packlets/json/common.ts

@@ -1,187 +0,0 @@
-/*
- * 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 { Result, captureResult, fail, succeed } from '@fgv/ts-utils';
-
-/* eslint-disable no-use-before-define */
-
-/**
- * Primitive (terminal) values allowed in by JSON.
- * @public
- */
-// eslint-disable-next-line @rushstack/no-new-null
-export type JsonPrimitive = boolean | number | string | null;
-
-/**
- * A {@link JsonObject | JsonObject} is a string-keyed object
- * containing only valid {@link JsonValue | JSON values}.
- * @public
- */
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export interface JsonObject {
-  [key: string]: JsonValue;
-}
-
-/**
- * A {@link JsonValue | JsonValue} is one of: a {@link JsonPrimitive | JsonPrimitive},
- * a {@link JsonObject | JsonObject} or an {@link JsonArray | JsonArray}.
- * @public
- */
-export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
-
-/**
- * A {@link JsonArray | JsonArray} is an array containing only valid {@link JsonValue | JsonValues}.
- * @public
- */
-// eslint-disable-next-line @typescript-eslint/no-empty-interface, @typescript-eslint/naming-convention
-export interface JsonArray extends Array<JsonValue> {}
-
-/**
- * Classes of {@link JsonValue | JsonValue}.
- * @public
- */
-export type JsonValueType = 'primitive' | 'object' | 'array';
-
-/**
- * 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: unknown): from is JsonPrimitive {
-  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,
- * `false` otherwise.
- * @public
- */
-export function isJsonObject(from: unknown): from is JsonObject {
-  return (
-    typeof from === 'object' &&
-    from !== null &&
-    !Array.isArray(from) &&
-    !(from instanceof RegExp) &&
-    !(from instanceof Date)
-  );
-}
-
-/**
- * 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: unknown): from is JsonArray {
-  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: unknown): Result<JsonValueType> {
-  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: JsonObject, path: string): Result<JsonValue> {
-  let result: JsonValue = 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: JsonObject, path: string): Result<JsonObject> {
-  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: unknown): Result<JsonValue> {
-  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<T>(from: T): Result<T> {
-  return captureResult(() => JSON.parse(JSON.stringify(from)));
-}

package/src/packlets/json/index.ts

@@ -1,23 +0,0 @@
-/*
- * 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';

package/src/packlets/json-file/file.ts

@@ -1,97 +0,0 @@
-/*
- * 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 { Converter, Result } from '@fgv/ts-utils';
-import { JsonValue } from '../json';
-import {
-  DefaultJsonFsHelper,
-  IJsonFsDirectoryOptions,
-  IJsonFsDirectoryToMapOptions,
-  IReadDirectoryItem,
-  JsonFsHelper
-} from './jsonFsHelper';
-import { DefaultJsonLike } from './jsonLike';
-
-/**
- * {@inheritdoc JsonFile.JsonFsHelper.readJsonFileSync}
- * @public
- */
-export function readJsonFileSync(srcPath: string): Result<JsonValue> {
-  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<T, TC = unknown>(
-  srcPath: string,
-  converter: Converter<T, TC>
-): Result<T> {
-  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<T, TC = unknown>(
-  srcPath: string,
-  options: IJsonFsDirectoryOptions<T, TC>
-): Result<IReadDirectoryItem<T>[]> {
-  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<T, TC = unknown>(
-  srcPath: string,
-  options: IJsonFsDirectoryToMapOptions<T, TC>
-): Result<Map<string, T>> {
-  return DefaultJsonFsHelper.convertJsonDirectoryToMapSync(srcPath, options);
-}
-
-const CompatJsonFsHelper: JsonFsHelper = new JsonFsHelper({
-  json: DefaultJsonLike,
-  allowUndefinedWrite: true // for compatibility
-});
-
-/**
- * {@inheritDoc JsonFile.JsonFsHelper.writeJsonFileSync}
- * @public
- */
-export function writeJsonFileSync(srcPath: string, value: JsonValue): Result<boolean> {
-  return CompatJsonFsHelper.writeJsonFileSync(srcPath, value);
-}

package/src/packlets/json-file/index.ts

@@ -1,25 +0,0 @@
-/*
- * 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 './file';
-export * from './jsonFsHelper';
-export * from './jsonLike';

package/src/packlets/json-file/jsonFsHelper.ts

@@ -1,262 +0,0 @@
-/*
- * 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 { Converter, Result, Validator, captureResult, fail, mapResults, succeed } from '@fgv/ts-utils';
-import * as fs from 'fs';
-import * as path from 'path';
-
-import { JsonValue } from '../json';
-import { DefaultJsonLike, IJsonLike } from './jsonLike';
-
-/**
- * Options for directory conversion.
- * TODO: add filtering, allowed and excluded.
- * @public
- */
-export 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[];
-}
-
-/**
- * Return value for one item in a directory conversion.
- * @public
- */
-export interface IReadDirectoryItem<T> {
-  /**
-   * Relative name of the file that was processed
-   */
-  filename: string;
-
-  /**
-   * The payload of the file.
-   */
-  item: T;
-}
-
-/**
- * Function to transform the name of a some entity, given an original name
- * and the contents of the entity.
- * @public
- */
-export type ItemNameTransformFunction<T> = (name: string, item: T) => Result<string>;
-
-/**
- * Options controlling conversion of a directory to a `Map`.
- * @public
- */
-export interface IJsonFsDirectoryToMapOptions<T, TC = unknown> extends IJsonFsDirectoryOptions<T, TC> {
-  transformName?: ItemNameTransformFunction<T>;
-}
-
-/**
- * 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: string): Result<string> => succeed(n);
-
-/**
- * Configuration for {@link JsonFile.JsonFsHelper | JsonFsHelper}.
- * @public
- */
-export interface IJsonFsHelperConfig {
-  json: IJsonLike;
-  allowUndefinedWrite: boolean;
-  defaultFiles: RegExp[];
-}
-
-/**
- * Initialization options for {@link JsonFile.JsonFsHelper | JsonFsHelper}.
- * @public
- */
-export type JsonFsHelperInitOptions = Partial<IJsonFsHelperConfig>;
-
-/**
- * Default configuration for {@link JsonFile.JsonFsHelper | JsonFsHelper}.
- * @public
- */
-export const DefaultJsonFsHelperConfig: IJsonFsHelperConfig = {
-  json: DefaultJsonLike,
-  allowUndefinedWrite: false,
-  defaultFiles: [/.*.json/]
-};
-
-/**
- * Helper class to simplify common filesystem operations involving JSON (or JSON-like)
- * files.
- * @public
- */
-export class JsonFsHelper {
-  /**
-   * Configuration for this {@link JsonFile.JsonFsHelper | JsonFsHelper}.
-   */
-  public readonly config: IJsonFsHelperConfig;
-
-  /**
-   * Construct a new {@link JsonFile.JsonFsHelper | JsonFsHelper}.
-   * @param json - Optional {@link JsonFile.IJsonLike | IJsonLike} used to process strings
-   * and JSON values.
-   */
-  public constructor(init?: JsonFsHelperInitOptions) {
-    this.config = {
-      ...DefaultJsonFsHelperConfig,
-      ...(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.
-   */
-  public readJsonFileSync(srcPath: string): Result<JsonValue> {
-    return captureResult(() => {
-      const fullPath = path.resolve(srcPath);
-      const body = fs.readFileSync(fullPath, 'utf8').toString();
-      return this.config.json.parse(body) as 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.
-   */
-  public convertJsonFileSync<T, TC = unknown>(
-    srcPath: string,
-    cv: Converter<T, TC> | Validator<T, TC>,
-    context?: TC
-  ): Result<T> {
-    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
-   */
-  public convertJsonDirectorySync<T, TC = unknown>(
-    srcPath: string,
-    options: IJsonFsDirectoryOptions<T>,
-    context?: TC
-  ): Result<IReadDirectoryItem<T>[]> {
-    return captureResult<IReadDirectoryItem<T>[]>(() => {
-      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 is Result<IReadDirectoryItem<T>> => 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.
-   */
-  public convertJsonDirectoryToMapSync<T, TC = unknown>(
-    srcPath: string,
-    options: IJsonFsDirectoryToMapOptions<T, TC>,
-    context?: unknown
-  ): Result<Map<string, T>> {
-    return this.convertJsonDirectorySync(srcPath, options, context).onSuccess((items) => {
-      const transformName = options.transformName ?? defaultNameTransformer;
-      return mapResults(
-        items.map((item) => {
-          const basename = path.basename(item.filename, '.json');
-          return transformName(basename, item.item).onSuccess((name) => {
-            return succeed<[string, T]>([name, item.item]);
-          });
-        })
-      ).onSuccess((items) => {
-        return succeed(new Map<string, T>(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.
-   */
-  public writeJsonFileSync(srcPath: string, value: JsonValue): Result<boolean> {
-    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;
-    });
-  }
-
-  protected _pathMatchesOptions<T, TC>(options: IJsonFsDirectoryOptions<T, TC>, path: string): boolean {
-    /* c8 ignore next 1 */
-    const match = options.files ?? this.config.defaultFiles;
-    return match.some((m) => m.exec(path));
-  }
-}
-
-/**
- * @public
- */
-export const DefaultJsonFsHelper: JsonFsHelper = new JsonFsHelper();

package/src/packlets/json-file/jsonLike.ts

@@ -1,56 +0,0 @@
-/*
- * 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.
- */
-
-import { JsonValue } from '../json';
-
-/**
- * @public
- */
-export type JsonReviver = (key: string, value: JsonValue) => JsonValue;
-
-/**
- * @public
- */
-export type JsonReplacerFunction = (key: string, value: JsonValue) => JsonValue;
-
-/**
- * @public
- */
-export type JsonReplacerArray = (string | number)[];
-
-/**
- * @public
- */
-export type JsonReplacer = JsonReplacerFunction | JsonReplacerArray;
-
-/**
- * @public
- */
-export interface IJsonLike {
-  parse(text: string, reviver?: JsonReviver, options?: unknown): JsonValue | undefined;
-  stringify(value: JsonValue, replacer?: JsonReplacer, space?: string | number): string | undefined;
-}
-
-/**
- * @public
- */
-export const DefaultJsonLike: IJsonLike = JSON;

package/src/packlets/validators/index.ts

@@ -1,23 +0,0 @@
-/*
- * 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';

package/src/packlets/validators/validators.ts

@@ -1,155 +0,0 @@
-/*
- * 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 { Failure, Validation, Validator, fail } from '@fgv/ts-utils';
-import { JsonArray, JsonObject, JsonPrimitive, JsonValue, isJsonArray, isJsonObject } from '../json';
-
-/* eslint-disable no-use-before-define, @typescript-eslint/no-use-before-define */
-
-/**
- * Validation context for in-place JSON validators.
- * @public
- */
-export interface IJsonValidatorContext {
-  ignoreUndefinedProperties?: boolean;
-}
-
-/**
- * An in-place validator which validates that a supplied `unknown` value is
- * a valid {@link JsonPrimitive | JsonPrimitive}.
- * @public
- */
-export const jsonPrimitive: Validator<JsonPrimitive, IJsonValidatorContext> =
-  new Validation.Base.GenericValidator({
-    validator: (
-      from: unknown,
-      ctx?: IJsonValidatorContext,
-      self?: Validator<JsonPrimitive, IJsonValidatorContext>
-    ): boolean | Failure<JsonPrimitive> => {
-      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?.ignoreUndefinedProperties === true) {
-        return true;
-      }
-      return fail(`"${String(from)}": not a valid 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: Validator<JsonObject, IJsonValidatorContext> = new Validation.Base.GenericValidator({
-  validator: (
-    from: unknown,
-    ctx?: IJsonValidatorContext,
-    self?: Validator<JsonObject, IJsonValidatorContext>
-  ) => {
-    if (!isJsonObject(from)) {
-      return fail('not a valid JSON object.');
-    }
-    const errors: string[] = [];
-    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(`not a valid 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: Validator<JsonArray, IJsonValidatorContext> = new Validation.Base.GenericValidator({
-  validator: (
-    from: unknown,
-    ctx?: IJsonValidatorContext,
-    self?: Validator<JsonArray, IJsonValidatorContext>
-  ) => {
-    if (!isJsonArray(from)) {
-      return fail('not an array');
-    }
-    const errors: string[] = [];
-    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: Validator<JsonValue, IJsonValidatorContext> = new Validation.Base.GenericValidator<
-  JsonValue,
-  IJsonValidatorContext
->({
-  validator: (
-    from: unknown,
-    ctx?: IJsonValidatorContext,
-    self?: Validator<JsonValue, IJsonValidatorContext>
-  ) => {
-    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;
-  }
-});