@fgv/ts-json-base 5.0.0-2 → 5.0.0-21

package/src/packlets/converters/converters.ts

@@ -0,0 +1,174 @@
+/*
+ * 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

@@ -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 './converters';

package/src/packlets/json/common.ts

@@ -0,0 +1,187 @@
+/*
+ * 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

@@ -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';

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

@@ -0,0 +1,97 @@
+/*
+ * 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

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