@fgv/ts-json-base 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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.

package/README.md

@@ -0,0 +1,455 @@
+<div align="center">
+  <h1>ts-json</h1>
+  Typescript Utilities for JSON
+</div>
+
+<hr/>
+
+## Summary
+
+Assorted JSON-related typescript utilities that I'm tired of copying from project to project. 
+
+---
+- [Summary](#summary)
+- [Installation](#installation)
+- [Overview](#overview)
+  - [Type-Safe JSON](#type-safe-json)
+  - [Templated JSON](#templated-json)
+    - [Multivalue Property Expansion](#multivalue-property-expansion)
+  - [Conditional JSON](#conditional-json)
+    - [Conditional Match Properties](#conditional-match-properties)
+    - [Defined Condition Properties](#defined-condition-properties)
+    - [Default Condition Properties](#default-condition-properties)
+    - [Flattened Unconditional Blocks](#flattened-unconditional-blocks)
+    - [Comments for Uniqueness](#comments-for-uniqueness)
+  - [Templating with Conditional JSON](#templating-with-conditional-json)
+- [API](#api)
+  - [JsonEditor class](#jsoneditor-class)
+    - [mergeObjectInPlace method](#mergeobjectinplace-method)
+    - [mergeObjectsInPlace method](#mergeobjectsinplace-method)
+    - [clone method](#clone-method)
+  - [Converters](#converters)
+    - [Simple JSON Converter](#simple-json-converter)
+    - [Templated JSON Converter](#templated-json-converter)
+    - [Conditional JSON Converter](#conditional-json-converter)
+## Installation
+
+With npm:
+```sh
+npm install ts-json
+```
+
+## Overview
+
+### Type-Safe JSON
+A handful of types express valid JSON as typescript types:
+```ts
+type JsonPrimitive = boolean | number | string | null;
+interface JsonObject { [key: string]: JsonValue }
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+interface JsonArray extends Array<JsonValue> { }
+```
+
+### Templated JSON
+*Templated JSON* is type-safe JSON, with [mustache](https://www.npmjs.com/package/mustache) template conversions applied to any string properties or keys using a supplied context.
+```ts
+    const src = {
+        '{{prop}}': '{{value}}',
+        literalValue: 'literal',
+    };
+
+    const result = JsonConverters.templatedJson({ prop: 'someProp', value: 'some value' }).convert(src);
+    // result.value is {
+    //    someProp: 'some value',
+    //    litealValue: 'literal',
+    // }
+```
+
+#### Multivalue Property Expansion
+In a templated JSON object, a key of the form ```*name=value1,value2...``` or ```"[[name]]=value1,value2,...``` is expanded to multiple values, one per item in the comma-separated list that follows the equals sign. The individual values are generated by resolving the property value with a context that includes a variable with the name specified and each of the values in the comma separated list, in turn.  For ```*``` expansion the result is a property named for the variable with an array of all values.  For ```[[``` expansion, the result is one property per value, where the property name matches the input value. For example:
+```ts
+    // with context:
+    const context = {
+        properties: ['first', 'second', 'third'],
+    };
+
+    // templated conversion of:
+    const src = {
+        '*prop={{properties}}': {
+            '{{prop}}Prop': '{{prop}} value',
+        },
+        '[[prop]]={{properties}}': {
+            '{{prop}}Prop': '{{prop}} value',
+        },
+    };
+
+    // yields
+    const expected = {
+        first: {
+            firstProp: 'first value',
+        },
+        second: {
+            secondProp: 'second value',
+        },
+        third: {
+            thirdProp: 'third value',
+        },
+        prop: ['first value', 'second value', 'third value'],
+    };
+```
+
+The converter options for templated JSON allow for an override of the function that derives the context for each of the children, so it is possible to write a custom derivation function which sets different or additional values based on the
+value passed in.
+
+### Conditional JSON
+
+*Conditional JSON* is *templated JSON*, but property names beginning with '?' reperesent conditional properties.
+
+The value of any conditional property must be a JSON object. If the condition is satisfied, (a deep copy of) the children of the conditional property value are merged into the parent object. If the condition is not satisfied, the body is ignored.
+
+#### Conditional Match Properties
+Conditional match properties are identified by names with one of these forms:
+```ts
+    '?value1=value2'
+    '?value1>=value2'
+    '?value1<=value2'
+    '?value1!=value2'
+    '?value1>value2'
+    '?value1<value2'
+```
+Where *value1* and *value2* are strings that do not include any of the valid operators. The condition is satisfied if *value2* and *value2* match according to the operator. For example:
+```ts
+    {
+        '?someValue=someValue': {
+            conditional1: 'conditional value 1',
+        },
+        '?someValue=someOtherValue': {
+            conditional2: 'conditional value 2',
+        },
+        '?3>1': {
+            conditional3: '3 is greater than 1',
+        },
+        '?3<1': {
+            conditional4: 'this is wrong',
+        },
+        unconditional: true,
+    }
+    // yields
+    {
+        conditional1: 'conditional value 1',
+        conditional3: '3 is greater than 1',
+        unconditional: true,
+    }
+```
+
+#### Defined Condition Properties
+Defined condition properties are identified by names of the form:
+```ts
+    '?value'
+```
+Where *value* is any string, including the empty string.  The condition is satisfied if *value* is not-empty or whitespace. For example:
+```ts
+    {
+        '?someValue': {
+            conditional: 'conditional value',
+        },
+        unconditional: 'unconditional value',
+    }
+    // yields
+    {
+        conditional: 'condtional value',
+        unconditional: 'unconditional value',
+    }
+```
+but
+```ts
+    {
+        '?': {
+            conditional: 'conditional value',
+        },
+        unconditional: 'unconditional value',
+    }
+    // yields
+    {
+        unconditional: 'unconditional value',
+    }
+```
+
+#### Default Condition Properties
+The special conditional property *'?default'* is satisfied if none of the immediately preceding conditional properties match, otherwise it is omitted.  For example:
+```ts
+    {
+        '?someValue=someOtherValue': {
+            conditional1: 'conditional value 1',
+        },
+        '?default': {
+            conditional1: 'default conditional value',
+        }
+    }
+    // yields
+    {
+        conditional1: 'default conditional value',
+    }
+```
+but
+```ts
+    {
+        '?someValue=someValue': {
+            conditional1: 'conditional value 1',
+        },
+        '?default': {
+            conditional1: 'default conditional value',
+        }
+    }
+    // yields
+    {
+        conditional1: 'conditional value 1',
+    }
+```
+
+#### Flattened Unconditional Blocks
+A default value is ignored if any conditional property in the same object was matched. To allow grouping of related conditional values with defaults, the conditional processor also supports
+unconditional properties with the '!' prefix.  Any unconditional object properties are flattened and omitted.  For example:
+```ts
+    {
+        '!block1': {
+            '?val1=val2': {
+                gotVal1: 'match',
+            },
+            '?default': {
+                gotVal1: 'default',
+            }
+        },
+        '!block2': {
+            '?val2=val3': {
+                gotVal2: 'match',
+            },
+            '?default': {
+                gotVal2: 'default',
+            }
+        },
+    }
+    // yields
+    {
+        gotVal1: 'default',
+        gotVal2: 'default',
+    }
+```
+
+#### Comments for Uniqueness
+In any conditional property name, anything that follows the first '#' character is ignored. This makes it possible to include multiple conditions that match the same value. For example:
+```ts
+    {
+        '?this=this': {
+            conditional: 'conditional 1',
+        },
+        unconditional: 'unconditional',
+        '?this=this': {
+            conditional: 'conditional 2'
+        }
+    }
+```
+is not valid JSON, because two properties have the same name, but:
+```ts
+    {
+        '?this=this#1': {
+            conditional: 'conditional 1',
+        },
+        unconditional: 'unconditional',
+        '?this=this#2': {
+            conditional: 'conditional 2'
+        }
+    }
+    // is valid, and yields:
+    {
+        unconditional: 'unconditional',
+        conditional: 'conditional 2',
+    }
+```
+
+### Templating with Conditional JSON
+Combined with [mustache](https://www.npmjs.com/package/mustache) templating, this conditional syntax allows simple and powerful generation or consumption of conditional JSON files.  For example, consider:
+```ts
+    {
+        userName: '{{user}}',
+        password: '{{pw}}',
+        '?{{userType}}=admin': {
+            rights: '...' // rights for admin
+        },
+        '?{{userType}}=bot': {
+            rights: '...' // rights for bot
+        }
+        '?{{default}}': {
+            rights: '...' // rights for normal user
+        },
+        '?{{externalId}}': {
+            externalId: '{{externalId}}',
+        }
+    }
+```
+Given the context:
+```ts
+    {
+        user: 'fred',
+        pw: 'freds password',
+        userType: 'admin',
+        externalId: 'freds SSO credentials',
+    }
+```
+Our example yields:
+```ts
+    {
+        userName: 'fred',
+        password: 'freds password',
+        rights: '...', // rights for admin
+        externalId: 'freds SSO credentials',
+    }
+```
+But given the context:
+```ts
+    {
+        user: 'r2d2',
+        password: 'r2s pw',
+        userType: 'bot',
+    }
+```
+We get:
+```ts
+    {
+        userName: 'r2d2',
+        password: 'r2s pw',
+        rights: '...', // rights for bot
+    }
+```
+
+## API
+
+### JsonEditor class
+The *JsonEditor* can be used to edite JSON objects in place or to clone any JSON value,
+applying a default context and optional set of editor rules (e.g. for templating, conditional,
+multi-value or reference processing) to be applied.
+
+#### mergeObjectInPlace method
+The *mergeObjectInPlace* function takes a base object an object to be merged and updates the supplied base object with values from the merge object.  For example:
+```ts
+    const base = {
+        property1: 'value 1',
+        property2: 'value 2',
+    };
+    const merge = {
+        property2: 'value 2A',
+        property3: 'value 3A',
+    };
+    const result = editor.mergeObjectInPlace(base, merge);
+    // updates the base object and returns success with base object, which means
+    // that both base and result.value have the shape:
+    {
+        property1: 'value 1',
+        property2: 'value 2A',
+        property3: 'value 3A',
+    }
+```
+
+#### mergeObjectsInPlace method
+The *mergeObjectsInPlace* function takes a base object and one or more objects to be merged, and updates the base object with values from each of the merge objects in the order supplied.  for example:
+```ts
+    const base = {
+        property1: 'value 1',
+        property2: 'value 2',
+    };
+    const mergeA = {
+        property2: 'value 2A',
+        property3: 'value 3A',
+    };
+    const mergeB = {
+        property3: 'value 3B',
+        property4: 'value 4B',
+    };
+    const result = editor.mergeObjectsInPlace(base, mergeA, mergeB);
+    // updates the base object and returns success with base object, which means
+    // that both base and result.value have the shape:
+    {
+        property1: 'value 1',
+        property2: 'value 2A',
+        property3: 'value 3B',
+        property4: 'value 4B',
+    }
+```
+
+#### clone method
+The *clone* method deep clones a supplied JSON value, applying all editor rules and
+a default or optionally supplied context.
+
+### Converters
+
+A convenience set of [ts-utils *Converters*](https://github.com/DidjaRedo/ts-utils/blob/master/README.md) and generators for the most common JSON conversions.
+
+#### Simple JSON Converter
+
+Use the *json* converter to convert unknown to type-safe JSON. Fails if the value to be converted is not valid JSON.
+```ts
+    import * as JsonConverters from '@fgv/ts-json/converters';
+
+    const result = JsonConverters.json.convert(someUnknown);
+    if (result.isSuccess()) {
+        // someUnknown was valid JSON
+        // jsonResult.value is a JsonValue deep copy of someUnknown
+    }
+    else {
+        // someUnknown was not valid JSON
+        // jsonResult.message describes the error
+    }
+```
+
+#### Templated JSON Converter
+
+Use the *templatedJson* converter to convert unknown to type-safe JSON, applying [mustache](https://www.npmjs.com/package/mustache) template conversions to any string properties or keys using the supplied context.
+```ts
+    const src = {
+        '{{prop}}': '{{value}}',
+        literalValue: 'literal',
+    };
+
+    const result = JsonConverters.templatedJson({ prop: 'someProp', value: 'some value' }).convert(src);
+    // result.value is {
+    //    someProp: 'some value',
+    //    litealValue: 'literal',
+    // }
+```
+
+#### Conditional JSON Converter
+
+Use the *conditionalJson* converter to convert unknown to type-safe JSON, applying [mustache](https://www.npmjs.com/package/mustache) template conversions to any string properties or keys using the supplied context *and* merging or omitting conditional properties as appropriate.  For example:
+```ts
+    const config =     {
+        userName: '{{user}}',
+        password: '{{pw}}',
+        '?{{userType}}=admin': {
+            rights: '...' // rights for admin
+        },
+        '?{{userType}}=bot': {
+            rights: '...' // rights for bot
+        }
+        '?{{default}}': {
+            rights: '...' // rights for normal user
+        },
+        '?{{externalId}}': {
+            externalId: '{{externalId}}',
+        }
+    };
+    const context =     {
+        user: 'fred',
+        pw: 'freds password',
+        userType: 'admin',
+        externalId: 'freds SSO credentials',
+    };
+
+    const result = JsonConverters.conditionalJson(context).convert(config);
+    // succeeds and yields
+    {
+        userName: 'fred',
+        password: 'freds password',
+        rights: '...', // rights for admin
+        externalId: 'freds SSO credentials',
+    }
+```

package/dist/ts-json-base.d.ts

@@ -0,0 +1,202 @@
+import { Converter } from '@fgv/ts-utils';
+import { Result } from '@fgv/ts-utils';
+
+/**
+ * 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 declare function classifyJsonValue(from: unknown): Result<JsonValueType>;
+
+/**
+ * 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 Files.IDirectoryConvertOptions | Options} to control
+ * conversion and filtering
+ * @public
+ */
+declare function convertJsonDirectorySync<T>(srcPath: string, options: IDirectoryConvertOptions<T>): Result<IReadDirectoryItem<T>[]>;
+
+/**
+ * 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 Files.IDirectoryToMapConvertOptions | Options} to control conversion,
+ * filtering and naming.
+ * @public
+ */
+declare function convertJsonDirectoryToMapSync<T, TC = unknown>(srcPath: string, options: IDirectoryToMapConvertOptions<T, TC>): Result<Map<string, T>>;
+
+/**
+ * Convenience function to 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
+ */
+declare function convertJsonFileSync<T>(srcPath: string, converter: Converter<T>): Result<T>;
+
+/**
+ * Options for directory conversion.
+ * TODO: add filtering, allowed and excluded.
+ * @public
+ */
+declare interface IDirectoryConvertOptions<T, TC = unknown> {
+    /**
+     * The converter used to convert incoming JSON objects.
+     */
+    converter: Converter<T, TC>;
+}
+
+/**
+ * Options controlling conversion of a directory.
+ * @public
+ */
+declare interface IDirectoryToMapConvertOptions<T, TC = unknown> extends IDirectoryConvertOptions<T, TC> {
+    transformName?: ItemNameTransformFunction<T>;
+}
+
+/**
+ * Return value for one item in a directory conversion.
+ * @public
+ */
+declare interface IReadDirectoryItem<T> {
+    /**
+     * Relative name of the file that was processed
+     */
+    filename: string;
+    /**
+     * The payload of the file.
+     */
+    item: T;
+}
+
+/**
+ * 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 declare function isJsonArray(from: unknown): from is JsonArray;
+
+/**
+ * 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 declare function isJsonObject(from: unknown): from is JsonObject;
+
+/**
+ * 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 declare function isJsonPrimitive(from: unknown): from is JsonPrimitive;
+
+/**
+ * Function to transform the name of a some entity, given an original name
+ * and the contents of the entity.
+ * @public
+ */
+declare type ItemNameTransformFunction<T> = (name: string, item: T) => Result<string>;
+
+/**
+ * A {@link JsonArray | JsonArray} is an array containing only valid {@link JsonValue | JsonValues}.
+ * @public
+ */
+export declare interface JsonArray extends Array<JsonValue> {
+}
+
+declare namespace JsonFile {
+    export {
+        readJsonFileSync,
+        convertJsonFileSync,
+        convertJsonDirectorySync,
+        convertJsonDirectoryToMapSync,
+        writeJsonFileSync,
+        IDirectoryConvertOptions,
+        IReadDirectoryItem,
+        ItemNameTransformFunction,
+        IDirectoryToMapConvertOptions
+    }
+}
+export { JsonFile }
+
+/**
+ * A {@link JsonObject | JsonObject} is a string-keyed object
+ * containing only valid {@link JsonValue | JSON values}.
+ * @public
+ */
+export declare interface JsonObject {
+    [key: string]: JsonValue;
+}
+
+/**
+ * Primitive (terminal) values allowed in by JSON.
+ * @public
+ */
+export declare type JsonPrimitive = boolean | number | string | null;
+
+/**
+ * A {@link JsonValue | JsonValue} is one of: a {@link JsonPrimitive | JsonPrimitive},
+ * a {@link JsonObject | JsonObject} or an {@link JsonArray | JsonArray}.
+ * @public
+ */
+export declare type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+
+/**
+ * Classes of {@link JsonValue | JsonValue}.
+ * @public
+ */
+export declare type JsonValueType = 'primitive' | 'object' | 'array';
+
+/**
+ * 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 declare function pickJsonObject(src: JsonObject, path: string): Result<JsonObject>;
+
+/**
+ * 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 declare function pickJsonValue(src: JsonObject, path: string): Result<JsonValue>;
+
+/**
+ * Convenience function to 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
+ */
+declare function readJsonFileSync(srcPath: string): Result<JsonValue>;
+
+/**
+ * Convenience function to 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
+ */
+declare function writeJsonFileSync(srcPath: string, value: JsonValue): Result<boolean>;
+
+export { }

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.39.1"
+    }
+  ]
+}

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+import * as JsonFile from './packlets/json-file';
+export * from './packlets/json';
+export { JsonFile };
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AAEjD,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,CAAC"}