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

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;
-  }
-});