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

package/src/packlets/context/contextHelpers.ts

@@ -0,0 +1,221 @@
+/*
+ * 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, succeed } from '@fgv/ts-utils';
+import { CompositeJsonMap } from './compositeJsonMap';
+import {
+  IJsonContext,
+  IJsonReferenceMap,
+  TemplateVars,
+  VariableValue,
+  defaultExtendVars
+} from './jsonContext';
+
+/**
+ * Helper class for working with {@link IJsonContext | IJsonContext} objects.
+ * @public
+ */
+export class JsonContextHelper {
+  /**
+   * The base {@link IJsonContext | context} on which we are operating.
+   * @internal
+   */
+  protected _context?: IJsonContext;
+
+  /**
+   * Constructs a new {@link JsonContextHelper | JsonContextHelper}.
+   * @param context - The base {@link IJsonContext | IJsonContext} on
+   * which to operate.
+   */
+  public constructor(context?: IJsonContext) {
+    this._context = context;
+  }
+
+  /**
+   * Creates a new {@link IJsonContext | context}.
+   * @param context - The base {@link IJsonContext | IJsonContext} on
+   * which to operate.
+   * @returns `Success` with the new {@link IJsonContext | IJsonContext},
+   * or `Failure` with more information if an error occurs.
+   */
+  public static create(context?: IJsonContext): Result<JsonContextHelper> {
+    return captureResult(() => new JsonContextHelper(context));
+  }
+
+  /**
+   * Static helper to extend context variables for a supplied {@link IJsonContext | IJsonContext}.
+   * @param baseContext - The {@link IJsonContext | IJsonContext} to be extended, or `undefined`
+   * to start from an empty context.
+   * @param vars - Optional {@link VariableValue | variable values} to be added to the
+   * {@link IJsonContext | context}.
+   * @returns `Success` with a new {@link TemplateVars | TemplateVars} containing the variables
+   * from the base context, merged with and overridden by any that were passed in, or `Failure`
+   * with a message if an error occurs.
+   */
+  public static extendContextVars(
+    baseContext: IJsonContext | undefined,
+    vars?: VariableValue[]
+  ): Result<TemplateVars | undefined> {
+    if (vars && vars.length > 0) {
+      const extend = baseContext?.extendVars ?? defaultExtendVars;
+      return extend(baseContext?.vars ?? {}, vars);
+    }
+    return succeed(baseContext?.vars);
+  }
+
+  /**
+   * Static helper to extend context references for a supplied {@link IJsonContext | IJsonContext}.
+   * @param baseContext - The {@link IJsonContext | IJsonContext} to be extended, or `undefined`
+   * to start from an empty context.
+   * @param refs - Optional {@link IJsonReferenceMap | reference maps} to be added to the
+   * {@link IJsonContext | context}.
+   * @returns `Success` with a new {@link IJsonReferenceMap | reference map} which projects
+   * the references from the base context, merged with and overridden by any that were passed in,
+   * or `Failure` with a message if an error occurs.
+   */
+  public static extendContextRefs(
+    baseContext: IJsonContext | undefined,
+    refs?: IJsonReferenceMap[]
+  ): Result<IJsonReferenceMap | undefined> {
+    if (refs && refs.length > 0) {
+      const full = baseContext?.refs ? [...refs, baseContext.refs] : refs;
+      if (full.length > 1) {
+        return CompositeJsonMap.create(full);
+      }
+      return succeed(full[0]);
+    }
+    return succeed(baseContext?.refs);
+  }
+
+  /**
+   * Static helper to extend context variables and references for a supplied {@link IJsonContext | IJsonContext}.
+   * @param baseContext - The {@link IJsonContext | IJsonContext} to be extended, or `undefined`
+   * to start from an empty context.
+   * @param add - Optional initializer containing {@link VariableValue | variable values} and/or
+   * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.
+   * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and
+   * references from the base context, merged with and overridden by any that were passed in, or
+   * `Failure` with a message if an error occurs.
+   */
+  public static extendContext(
+    baseContext?: IJsonContext | undefined,
+    add?: { vars?: VariableValue[]; refs?: IJsonReferenceMap[] }
+  ): Result<IJsonContext | undefined> {
+    return JsonContextHelper.extendContextVars(baseContext, add?.vars || []).onSuccess((vars) => {
+      return JsonContextHelper.extendContextRefs(baseContext, add?.refs || []).onSuccess((refs) => {
+        if (!vars && !refs && !baseContext?.extendVars) {
+          return succeed(undefined);
+        }
+        const rtrn: IJsonContext = { vars, refs };
+        if (baseContext?.extendVars) {
+          rtrn.extendVars = baseContext.extendVars;
+        }
+        return succeed(rtrn);
+      });
+    });
+  }
+
+  /**
+   * Static helper to merge context variables and references for a supplied {@link IJsonContext | IJsonContext}.
+   * @param baseContext - The {@link IJsonContext | IJsonContext} into which variables and references
+   * are to be merged, or `undefined` to start from an empty context.
+   * @param add - Optional initializer containing {@link VariableValue | variable values} and/or
+   * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.
+   * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and
+   * references from the base context, merged with and overridden by any that were passed in, or
+   * `Failure` with a message if an error occurs.
+   */
+  public static mergeContext(
+    baseContext: IJsonContext | undefined,
+    add: IJsonContext | undefined
+  ): Result<IJsonContext | undefined> {
+    if (baseContext) {
+      if (add) {
+        const rtrn: IJsonContext = {
+          vars: add.vars ?? baseContext.vars,
+          refs: add.refs ?? baseContext.refs
+        };
+        if (add.hasOwnProperty('extendVars')) {
+          rtrn.extendVars = add.extendVars;
+        } else if (baseContext.hasOwnProperty('extendVars')) {
+          rtrn.extendVars = baseContext.extendVars;
+        }
+        return succeed(rtrn);
+      }
+      return succeed(baseContext);
+    }
+    return succeed(add);
+  }
+
+  /**
+   * Applies {@link JsonContextHelper.extendContextVars | extendContextVars} to the
+   * {@link IJsonContext | IJsonContext} associated with this helper.
+   * @param vars - Optional {@link VariableValue | variable values} to be added to the
+   * @returns `Success` with a new {@link TemplateVars | TemplateVars} containing the variables
+   * from the base context, merged with and overridden by any that were passed in, or `Failure`
+   * with a message if an error occurs.
+   */
+  public extendVars(vars?: VariableValue[]): Result<TemplateVars | undefined> {
+    return JsonContextHelper.extendContextVars(this._context, vars);
+  }
+
+  /**
+   * Applies {@link JsonContextHelper.extendContextRefs | extendContextRefs} to the
+   * {@link IJsonContext | IJsonContext} associated with this helper.
+   * @param refs - Optional {@link IJsonReferenceMap | reference maps} to be added to the
+   * @returns `Success` with a new {@link IJsonReferenceMap | reference map} which projects
+   * the references from the base context, merged with and overridden by any that were passed in,
+   * or `Failure` with a message if an error occurs.
+   */
+  public extendRefs(refs?: IJsonReferenceMap[]): Result<IJsonReferenceMap | undefined> {
+    return JsonContextHelper.extendContextRefs(this._context, refs);
+  }
+
+  /**
+   * Applies static `JsonContextHelper.extendContext` to the
+   * {@link IJsonContext | IJsonContext} associated with this helper.
+   * @param add - Optional initializer containing {@link VariableValue | variable values} and/or
+   * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.
+   * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and
+   * references from the base context, merged with and overridden by any that were passed in, or
+   * `Failure` with a message if an error occurs.
+   */
+  public extendContext(add?: {
+    vars?: VariableValue[];
+    refs?: IJsonReferenceMap[];
+  }): Result<IJsonContext | undefined> {
+    return JsonContextHelper.extendContext(this._context, add);
+  }
+
+  /**
+   * Applies static `JsonContextHelper.mergeContext` to the
+   * {@link IJsonContext | IJsonContext} associated with this helper.
+   * @param add - Optional initializer containing {@link VariableValue | variable values} and/or
+   * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.
+   * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and
+   * references from the base context, merged with and overridden by any that were passed in, or
+   * `Failure` with a message if an error occurs.
+   */
+  public mergeContext(merge?: IJsonContext): Result<IJsonContext | undefined> {
+    return JsonContextHelper.mergeContext(this._context, merge);
+  }
+}

package/src/packlets/context/index.ts

@@ -0,0 +1,33 @@
+/*
+ * 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.
+ */
+
+export { CompositeJsonMap } from './compositeJsonMap';
+export { JsonContextHelper } from './contextHelpers';
+export {
+  IJsonContext,
+  IJsonReferenceMap,
+  JsonReferenceMapFailureReason,
+  TemplateVars,
+  TemplateVarsExtendFunction,
+  VariableValue,
+  defaultExtendVars
+} from './jsonContext';

package/src/packlets/context/jsonContext.ts

@@ -0,0 +1,133 @@
+/*
+ * 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 { JsonObject, JsonValue } from '@fgv/ts-json-base';
+import { DetailedResult, Result, succeed } from '@fgv/ts-utils';
+
+/**
+ * Collection of variables used for template replacement in a JSON edit or
+ * conversion.
+ * @public
+ */
+export type TemplateVars = Record<string, unknown>;
+
+/**
+ * Describes one value in a {@link TemplateVars | TemplateVars} collection of
+ * variables.
+ * @public
+ */
+export type VariableValue = [string, unknown];
+
+/**
+ * Function used to create a new collection of {@link TemplateVars | TemplateVars} with
+ * one or more new or changed values.
+ * @public
+ */
+export type TemplateVarsExtendFunction = (
+  base: TemplateVars | undefined,
+  values: VariableValue[]
+) => Result<TemplateVars | undefined>;
+
+/**
+ * This default implementation of a {@link TemplateVarsExtendFunction | TemplateVarsExtendFunction}
+ * creates a new collection via inheritance from the supplied collection.
+ * @param base - The base {@link TemplateVars | variables} to be extended.
+ * @param values - The {@link VariableValue | values} to be added or overridden in the new variables.
+ * @public
+ */
+export function defaultExtendVars(
+  base: TemplateVars | undefined,
+  values: VariableValue[]
+): Result<TemplateVars | undefined> {
+  /* c8 ignore next 1 */
+  const rtrn = base ? Object.create(base) : {};
+  for (const v of values) {
+    rtrn[v[0]] = v[1];
+  }
+  return succeed(rtrn);
+}
+
+/**
+ * Failure reason for {@link IJsonReferenceMap | IJsonReferenceMap} lookup, where `'unknown'`
+ * means that the object is not present in the map and `'error'` means
+ * that an error occurred while retrieving or converting it.
+ * @public
+ */
+export type JsonReferenceMapFailureReason = 'unknown' | 'error';
+
+/**
+ * Interface for a simple map that returns named `JsonValue` values with templating,
+ * conditional logic, and external reference lookups applied using an optionally supplied context.
+ * @public
+ */
+export interface IJsonReferenceMap {
+  /**
+   * Determine if a key might be valid for this map but does not determine if key actually
+   * exists. Allows key range to be constrained.
+   * @param key - The key to be tested.
+   * @returns `true` if the key is in the valid range, `false` otherwise.
+   */
+  keyIsInRange(key: string): boolean;
+
+  /**
+   * Determines if an object with the specified key actually exists in the map.
+   * @param key - The key to be tested.
+   * @returns `true` if an object with the specified key exists, `false` otherwise.
+   */
+  has(key: string): boolean;
+
+  /**
+   * Gets a `JsonObject` specified by key.
+   * @param key - The key of the object to be retrieved.
+   * @param context - Optional {@link IJsonContext | IJsonContext} used to construct
+   * the object.
+   * @returns `Success` with the formatted JsonObject if successful. `Failure`
+   * with detail `'unknown'`  if no such object exists, or `Failure` with detail `'error'` if
+   * the object was found but could not be formatted.
+   */
+  // eslint-disable-next-line no-use-before-define
+  getJsonObject(
+    key: string,
+    context?: IJsonContext
+  ): DetailedResult<JsonObject, JsonReferenceMapFailureReason>;
+
+  /**
+   * Gets a `JsonValue` specified by key.
+   * @param key - The key of the object to be retrieved.
+   * @param context - Optional {@link IJsonContext | JSON Context} used to format the value
+   * @returns `Success` with the formatted `JsonValue` if successful. `Failure`
+   * with detail `'unknown'` if no such object exists, or `Failure` with detail `'error'` if
+   * the object was found but could not be formatted.
+   */
+  // eslint-disable-next-line no-use-before-define
+  getJsonValue(key: string, context?: IJsonContext): DetailedResult<JsonValue, JsonReferenceMapFailureReason>;
+}
+
+/**
+ * Context used to convert or edit JSON objects.
+ * @public
+ */
+export interface IJsonContext {
+  vars?: TemplateVars;
+  refs?: IJsonReferenceMap;
+  extendVars?: TemplateVarsExtendFunction;
+}

package/src/packlets/converters/converters.ts

@@ -0,0 +1,117 @@
+/*
+ * 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 { JsonArray, JsonObject } from '@fgv/ts-json-base';
+import { Converter } from '@fgv/ts-utils';
+import { IJsonContext } from '../context';
+import {
+  ConditionalJsonConverter,
+  ConditionalJsonConverterOptions,
+  JsonConverter,
+  RichJsonConverter,
+  RichJsonConverterOptions,
+  TemplatedJsonConverter,
+  TemplatedJsonConverterOptions
+} from './jsonConverter';
+
+/**
+ * A simple validating {@link JsonConverter | JSON converter}. Converts unknown to
+ * JSON or fails if the unknown contains any invalid JSON values.
+ * @public
+ */
+export const json: JsonConverter = new JsonConverter();
+
+/**
+ * A simple validating {@link JsonConverter | JSON converter}. Converts unknown
+ * to a `JsonObject`, or fails if the `unknown` contains invalid
+ * JSON or is not an object.
+ * @public
+ */
+export const jsonObject: Converter<JsonObject, IJsonContext> = json.object();
+
+/**
+ * A simple validating {@link JsonConverter | JSON converter}. Converts `unknown` to a
+ * `JsonArray`, or fails if the unknown contains invalid JSON or is
+ * not an array.
+ * @public
+ */
+export const jsonArray: Converter<JsonArray, IJsonContext> = json.array();
+
+let templatedJsonDefault: JsonConverter | undefined;
+let conditionalJsonDefault: JsonConverter | undefined;
+let richJsonDefault: JsonConverter | undefined;
+
+/**
+ * Helper function which creates a new {@link JsonConverter | JsonConverter} which converts an
+ * `unknown` value to JSON, rendering any property names or string values using mustache with
+ * the supplied context.  See the mustache documentation for details of mustache syntax and view.
+ * @param options - {@link TemplatedJsonConverterOptions | Options and context} for
+ * the conversion.
+ * @public
+ */
+export function templatedJson(options?: Partial<TemplatedJsonConverterOptions>): JsonConverter {
+  if (!options) {
+    if (!templatedJsonDefault) {
+      templatedJsonDefault = new TemplatedJsonConverter();
+    }
+    return templatedJsonDefault;
+  }
+  return new TemplatedJsonConverter(options);
+}
+
+/**
+ * Helper function which creates a new {@link JsonConverter | JsonConverter} which converts a
+ * supplied `unknown` to strongly-typed JSON, by first rendering any property
+ * names or string values using mustache with the supplied context, then applying
+ * multi-value property expansion and conditional flattening based on property names.
+ * @param options - {@link ConditionalJsonConverterOptions | Options and context} for
+ * the conversion.
+ * @public
+ */
+export function conditionalJson(options?: Partial<ConditionalJsonConverterOptions>): JsonConverter {
+  if (!options) {
+    if (!conditionalJsonDefault) {
+      conditionalJsonDefault = new ConditionalJsonConverter();
+    }
+    return conditionalJsonDefault;
+  }
+  return new ConditionalJsonConverter(options);
+}
+
+/**
+ * Helper function which creates a new {@link JsonConverter | JsonConverter} which converts a
+ * supplied `unknown` to strongly-typed JSON, by first rendering any property
+ * names or string values using mustache with the supplied context, then applying
+ * multi-value property expansion and conditional flattening based on property names.
+ * @param options - {@link RichJsonConverterOptions | Options and context} for
+ * the conversion.
+ * @public
+ */
+export function richJson(options?: Partial<RichJsonConverterOptions>): JsonConverter {
+  if (!options) {
+    if (!richJsonDefault) {
+      richJsonDefault = new RichJsonConverter();
+    }
+    return richJsonDefault;
+  }
+  return new RichJsonConverter(options);
+}

package/src/packlets/converters/index.ts

@@ -0,0 +1,26 @@
+/*
+ * 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 './converters';
+
+export * from './jsonConverter';
+export { Converters };