@trayio/tray-schema 0.0.1-beta

package/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2023 Tray.io, Inc
+
+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,70 @@
+# Tray-schema
+This module contains a collection of utilities for transforming and manipulating various representations of Tray's connector schema.
+
+# TJSTraySchemaTypeTransformer
+
+## Overview
+This part of the module takes a CDK connectors input or output typescript type definitions, along with any JSdoc annotations, and generates JSON schema representing these types. Specifically this format is Tray schema, otherwise known as CAPI schema, but importantly it is not the old way of writing connector JSON schema, which is reffered to as the legacy connector schema.
+
+To generate the full schema for a connector this utility will be invoked for each operation's input and output. Operation metadata is pulled from the handler (using a different util) and then all of this schema is stiched together (using yet another different util) to produce the final connectors.json in Tray schema format. Which will then be transformed into legcay connector schema (by yet another different util) to ensure the connector works with the legacy deployment process.
+
+Have a look at the example types used for unit tests within `src/TJSTraySchemaTypeTransformer/tests/` for examples of how to do different things with typescript and JSdoc.
+
+## Why use NPM lib typescript-json-schema
+
+We found only 2 suitable libraries for converting typescript types to JSON schema:
+- typescript-json-schema:
+    - It's functionality cannot be extended
+    - It won't throw an exception if you ask it to generate "invalid" schema
+- ts-json-schema-generator
+    - Is an extension of typescript-json-schema
+    - It's functionality can be extended
+    - It will throw an exception if you ask it to generate "invalid" schema. And this is the main reason we did not chose this library, because this library sees some of the extra properties Tray schema has as invalid.
+
+## Post processing
+To get around the non extendable nature of the typescript-json-schema lib we perform a number of different post processing steps on the generated JSON schema.
+## Enums
+Tray schema supports enum labels so users can have a enum value which is sent and an enum label which is just displayed in the UI. Adding support for enum lables is trivial, until you realise that typescript-json-schema sorts the enums alphabetically. There are a few different ways to handle this, all of them are not ideal.
+
+You can force the user to specify their enum, enum labels and enum order, which is incredibley cumbersome, they would have to write the enum list 4 times (its 4 not 3 because a TS enum needs a key and value).
+
+For now we will not allow custom enum labels, instead we try to generate they best enum label possible automatically, in addition the order of enums can't be specified. We are planning on opening a PR to the typescript-json-schema lib to add a config option to disable this sorting. This way when we have this PR merged we can enable enum labels through the @enumLabel JSdoc annotation and it will be backwards compatible for end users.
+
+## Lookup / DDLs
+Ideally DDLs would be defined in JSdoc like this, using the dot to target the property in the resulting JSON schema (e.g. @lookup.operation). Unfortunately this doesn't work with the typescript-json-schema library. So instead we use camelCased annotation names (e.g. @lookupOperation) and then use post processing to rearrange the schema. Potentially we could also raise a PR to the lib to add this dot notation support.
+```
+// ideal input
+export type Input = {
+	/**
+	 * @lookup.operation list_users_actual_ddl
+	 * @lookup.input {"include_private_channels": false,"workspace_id": "{{{workspace_id}}}"}
+	 */
+	emails: string;
+};
+
+// actual input
+export type Input = {
+	/**
+	 * @lookupOperation list_users_actual_ddl
+	 * @lookupInput {"include_private_channels": false,"workspace_id": "{{{workspace_id}}}"}
+	 */
+	emails: string;
+};
+
+// Output
+emails: {
+    type: 'string',
+    lookup: {
+        operation: 'list_users_actual_ddl',
+        input: {
+            include_private_channels: false,
+            workspace_id: '{{{workspace_id}}}',
+        },
+    },
+},
+```
+
+## Advance fields not supported yet
+Some more work is required to support advanced fields, which is when a field is hidden within the Tray UI in an expandable advanced section.
+
+Would need to add a new JSdoc annotation @advanced, this will be added to each item of the schema though when it needs to be in an array, similar to how the required fields works. So post processing would be required to strip out the individual required: true on each item and combine them into an array at the parent item level.

package/dist/schema/LegacyTraySchemaConverter.d.ts

@@ -0,0 +1,11 @@
+import { DynamicObject } from '@trayio/commons/dynamictype/DynamicType';
+export interface LegacyTraySchemaConverterInterface {
+    convertToLegacySchema(schema: DynamicObject): DynamicObject;
+}
+export declare class LegacyTraySchemaConverter implements LegacyTraySchemaConverterInterface {
+    convertToLegacySchema(schema: DynamicObject): DynamicObject;
+    private transformLookup;
+    private transformLookupInput;
+    private transformEnums;
+}
+//# sourceMappingURL=LegacyTraySchemaConverter.d.ts.map

package/dist/schema/LegacyTraySchemaConverter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LegacyTraySchemaConverter.d.ts","sourceRoot":"","sources":["../../src/schema/LegacyTraySchemaConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAExE,MAAM,WAAW,kCAAkC;IAClD,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAAC;CAC5D;AAED,qBAAa,yBACZ,YAAW,kCAAkC;IAE7C,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa;IAY3D,OAAO,CAAC,eAAe,CAsBrB;IAEF,OAAO,CAAC,oBAAoB,CAc1B;IAEF,OAAO,CAAC,cAAc,CAoBpB;CACF"}

package/dist/schema/LegacyTraySchemaConverter.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LegacyTraySchemaConverter = void 0;
+class LegacyTraySchemaConverter {
+    constructor() {
+        this.transformLookup = (object) => {
+            if (typeof object !== 'object' || object === null)
+                return object;
+            if (object.lookup &&
+                object.lookup.operation &&
+                object.lookup.input) {
+                const lookup = object.lookup;
+                object.lookup = {
+                    url: '{{{step.ephemeral_url}}}',
+                    body: Object.assign({ step_settings: this.transformLookupInput(lookup.input), message: lookup.operation }, (lookup.authRequired && { auth_id: '{{{step.auth_id}}}' })),
+                };
+            }
+            return object;
+        };
+        this.transformLookupInput = (input) => {
+            if (typeof input !== 'object' || input === null)
+                return input;
+            const result = {};
+            Object.keys(input).forEach((key) => {
+                result[key] = {
+                    value: typeof input[key] === 'object'
+                        ? this.transformLookupInput(input[key])
+                        : input[key],
+                    type: typeof input[key],
+                };
+            });
+            return result;
+        };
+        this.transformEnums = (object) => {
+            if (typeof object !== 'object' || object === null)
+                return object;
+            if (object.enum &&
+                object.enumLabels &&
+                Array.isArray(object.enum) &&
+                Array.isArray(object.enumLabels)) {
+                object.enum = object.enum.map((enumItem, index) => ({
+                    value: enumItem,
+                    text: object.enumLabels[index],
+                }));
+                delete object.enumLabels;
+            }
+            return object;
+        };
+    }
+    convertToLegacySchema(schema) {
+        for (const [key, value] of Object.entries(schema)) {
+            if (typeof value === 'object' && value !== null) {
+                this.transformLookup(value);
+                this.transformEnums(value);
+                this.convertToLegacySchema(value);
+            }
+        }
+        return schema;
+    }
+}
+exports.LegacyTraySchemaConverter = LegacyTraySchemaConverter;

package/dist/schema/LegacyTraySchemaConverter.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=LegacyTraySchemaConverter.unit.test.d.ts.map

package/dist/schema/LegacyTraySchemaConverter.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LegacyTraySchemaConverter.unit.test.d.ts","sourceRoot":"","sources":["../../src/schema/LegacyTraySchemaConverter.unit.test.ts"],"names":[],"mappings":""}

package/dist/schema/LegacyTraySchemaConverter.unit.test.js

@@ -0,0 +1,469 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const LegacyTraySchemaConverter_1 = require("./LegacyTraySchemaConverter");
+describe('LegacyTraySchemaConverter', () => {
+    const converter = new LegacyTraySchemaConverter_1.LegacyTraySchemaConverter();
+    describe('convertToLegacySchema', () => {
+        it('should convert a connector schema with a lookup to legacy schema', () => {
+            const schema = {
+                type: 'object',
+                properties: {
+                    id: {
+                        type: 'number',
+                        lookup: {
+                            operation: 'list_tables_ddl',
+                            input: {
+                                workspace_id: '{{{workspace_id}}}',
+                                project_id: '{{{project_id}}}',
+                                service: {
+                                    name: '{{{service_name}}}',
+                                    version: 1,
+                                },
+                            },
+                        },
+                    },
+                },
+                additionalProperties: false,
+                required: ['id'],
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                advanced: [],
+            };
+            const expected = {
+                type: 'object',
+                properties: {
+                    id: {
+                        type: 'number',
+                        lookup: {
+                            url: '{{{step.ephemeral_url}}}',
+                            body: {
+                                step_settings: {
+                                    workspace_id: {
+                                        value: '{{{workspace_id}}}',
+                                        type: 'string',
+                                    },
+                                    project_id: {
+                                        value: '{{{project_id}}}',
+                                        type: 'string',
+                                    },
+                                    service: {
+                                        type: 'object',
+                                        value: {
+                                            name: {
+                                                value: '{{{service_name}}}',
+                                                type: 'string',
+                                            },
+                                            version: {
+                                                value: 1,
+                                                type: 'number',
+                                            },
+                                        },
+                                    },
+                                },
+                                message: 'list_tables_ddl',
+                            },
+                        },
+                    },
+                },
+                additionalProperties: false,
+                required: ['id'],
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                advanced: [],
+            };
+            const result = converter.convertToLegacySchema(schema);
+            expect(result).toEqual(expected);
+        });
+        it('should convert a connector schema with a lookup and include authId on DDL when authRequired is true', () => {
+            const schema = {
+                type: 'object',
+                properties: {
+                    id: {
+                        type: 'number',
+                        lookup: {
+                            operation: 'list_tables_ddl',
+                            input: {
+                                workspace_id: '{{{workspace_id}}}',
+                                project_id: '{{{project_id}}}',
+                                service: {
+                                    name: '{{{service_name}}}',
+                                    version: 1,
+                                },
+                            },
+                            authRequired: true,
+                        },
+                    },
+                },
+                additionalProperties: false,
+                required: ['id'],
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                advanced: [],
+            };
+            const expected = {
+                type: 'object',
+                properties: {
+                    id: {
+                        type: 'number',
+                        lookup: {
+                            url: '{{{step.ephemeral_url}}}',
+                            body: {
+                                step_settings: {
+                                    workspace_id: {
+                                        value: '{{{workspace_id}}}',
+                                        type: 'string',
+                                    },
+                                    project_id: {
+                                        value: '{{{project_id}}}',
+                                        type: 'string',
+                                    },
+                                    service: {
+                                        type: 'object',
+                                        value: {
+                                            name: {
+                                                value: '{{{service_name}}}',
+                                                type: 'string',
+                                            },
+                                            version: {
+                                                value: 1,
+                                                type: 'number',
+                                            },
+                                        },
+                                    },
+                                },
+                                message: 'list_tables_ddl',
+                                auth_id: '{{{step.auth_id}}}',
+                            },
+                        },
+                    },
+                },
+                additionalProperties: false,
+                required: ['id'],
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                advanced: [],
+            };
+            const result = converter.convertToLegacySchema(schema);
+            expect(result).toEqual(expected);
+        });
+        it('should convert a connector schema with a lookup to legacy schema and also has a lookup field', () => {
+            const schema = {
+                type: 'object',
+                properties: {
+                    id: {
+                        type: 'number',
+                        lookup: {
+                            operation: 'list_tables_ddl',
+                            input: {
+                                workspace_id: '{{{workspace_id}}}',
+                                project_id: '{{{project_id}}}',
+                            },
+                        },
+                    },
+                    lookup: {
+                        type: 'string',
+                        lookup: {
+                            operation: 'list_tables_ddl',
+                            input: {
+                                workspace_id: '{{{workspace_id}}}',
+                                project_id: '{{{project_id}}}',
+                            },
+                        },
+                    },
+                },
+                additionalProperties: false,
+                required: ['id'],
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                advanced: [],
+            };
+            const expected = {
+                type: 'object',
+                properties: {
+                    id: {
+                        type: 'number',
+                        lookup: {
+                            url: '{{{step.ephemeral_url}}}',
+                            body: {
+                                step_settings: {
+                                    workspace_id: {
+                                        value: '{{{workspace_id}}}',
+                                        type: 'string',
+                                    },
+                                    project_id: {
+                                        value: '{{{project_id}}}',
+                                        type: 'string',
+                                    },
+                                },
+                                message: 'list_tables_ddl',
+                            },
+                        },
+                    },
+                    lookup: {
+                        type: 'string',
+                        lookup: {
+                            url: '{{{step.ephemeral_url}}}',
+                            body: {
+                                step_settings: {
+                                    workspace_id: {
+                                        value: '{{{workspace_id}}}',
+                                        type: 'string',
+                                    },
+                                    project_id: {
+                                        value: '{{{project_id}}}',
+                                        type: 'string',
+                                    },
+                                },
+                                message: 'list_tables_ddl',
+                            },
+                        },
+                    },
+                },
+                additionalProperties: false,
+                required: ['id'],
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                advanced: [],
+            };
+            const result = converter.convertToLegacySchema(schema);
+            expect(result).toEqual(expected);
+        });
+        it('should convert a schema with an enum', () => {
+            const schema = {
+                type: 'object',
+                properties: {
+                    actions: {
+                        description: 'example dropdown',
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                text: { type: 'string' },
+                                type: {
+                                    type: 'string',
+                                    enum: ['default always', 'primary-one', 'the_danger'],
+                                    enumLabels: ['Default Always', 'Primary One', 'The Danger'],
+                                },
+                            },
+                            additionalProperties: false,
+                            required: ['text', 'type'],
+                            advanced: [],
+                        },
+                    },
+                    name: { type: 'string' },
+                },
+                additionalProperties: false,
+                required: ['actions', 'name'],
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                advanced: [],
+            };
+            const expected = {
+                type: 'object',
+                properties: {
+                    actions: {
+                        description: 'example dropdown',
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                text: { type: 'string' },
+                                type: {
+                                    type: 'string',
+                                    enum: [
+                                        {
+                                            value: 'default always',
+                                            text: 'Default Always',
+                                        },
+                                        {
+                                            value: 'primary-one',
+                                            text: 'Primary One',
+                                        },
+                                        {
+                                            value: 'the_danger',
+                                            text: 'The Danger',
+                                        },
+                                    ],
+                                },
+                            },
+                            additionalProperties: false,
+                            required: ['text', 'type'],
+                            advanced: [],
+                        },
+                    },
+                    name: { type: 'string' },
+                },
+                required: ['actions', 'name'],
+                additionalProperties: false,
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                advanced: [],
+            };
+            const result = converter.convertToLegacySchema(schema);
+            expect(result).toEqual(expected);
+        });
+        it('should convert a schema with an enum and a field name as enum', () => {
+            const schema = {
+                type: 'object',
+                properties: {
+                    actions: {
+                        description: 'example dropdown',
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                text: { type: 'string' },
+                                type: {
+                                    type: 'string',
+                                    enum: ['default always', 'primary-one', 'the_danger'],
+                                    enumLabels: ['Default Always', 'Primary One', 'The Danger'],
+                                },
+                            },
+                            additionalProperties: false,
+                            required: ['text', 'type'],
+                            advanced: [],
+                        },
+                    },
+                    enum: { type: 'string' },
+                },
+                additionalProperties: false,
+                required: ['actions', 'enum'],
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                advanced: [],
+            };
+            const expected = {
+                type: 'object',
+                properties: {
+                    actions: {
+                        description: 'example dropdown',
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                text: { type: 'string' },
+                                type: {
+                                    type: 'string',
+                                    enum: [
+                                        {
+                                            value: 'default always',
+                                            text: 'Default Always',
+                                        },
+                                        {
+                                            value: 'primary-one',
+                                            text: 'Primary One',
+                                        },
+                                        {
+                                            value: 'the_danger',
+                                            text: 'The Danger',
+                                        },
+                                    ],
+                                },
+                            },
+                            additionalProperties: false,
+                            required: ['text', 'type'],
+                            advanced: [],
+                        },
+                    },
+                    enum: { type: 'string' },
+                },
+                additionalProperties: false,
+                required: ['actions', 'enum'],
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                advanced: [],
+            };
+            const result = converter.convertToLegacySchema(schema);
+            expect(result).toEqual(expected);
+        });
+        it('should convert lookups and enums in nested objects', () => {
+            const schema = {
+                properties: {
+                    id: {
+                        type: 'object',
+                        properties: {
+                            lookup: {
+                                input: {
+                                    input1: 'value1',
+                                    input2: 'value2',
+                                },
+                                operation: 'operation',
+                            },
+                        },
+                    },
+                    nested: {
+                        properties: {
+                            sort_by: {
+                                type: {
+                                    type: 'string',
+                                    enum: ['value1', 'value2'],
+                                    enumLabels: ['Value 1', 'Value 2'],
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+            const expected = {
+                properties: {
+                    id: {
+                        type: 'object',
+                        properties: {
+                            lookup: {
+                                url: '{{{step.ephemeral_url}}}',
+                                body: {
+                                    step_settings: {
+                                        input1: {
+                                            value: 'value1',
+                                            type: 'string',
+                                        },
+                                        input2: {
+                                            value: 'value2',
+                                            type: 'string',
+                                        },
+                                    },
+                                    message: 'operation',
+                                },
+                            },
+                        },
+                    },
+                    nested: {
+                        properties: {
+                            sort_by: {
+                                type: {
+                                    type: 'string',
+                                    enum: [
+                                        {
+                                            value: 'value1',
+                                            text: 'Value 1',
+                                        },
+                                        {
+                                            value: 'value2',
+                                            text: 'Value 2',
+                                        },
+                                    ],
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+            const result = converter.convertToLegacySchema(schema);
+            expect(result).toEqual(expected);
+        });
+        it('should preserve the schema without a lookup and an enum', () => {
+            const schema = {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                },
+                additionalProperties: false,
+                required: ['actions'],
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                advanced: [],
+            };
+            const expected = {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                },
+                additionalProperties: false,
+                required: ['actions'],
+                $schema: 'http://json-schema.org/draft-07/schema#',
+                advanced: [],
+            };
+            const result = converter.convertToLegacySchema(schema);
+            expect(result).toEqual(expected);
+        });
+    });
+});

package/dist/schema/TJSTraySchemaGenerator.d.ts

@@ -0,0 +1,9 @@
+import * as TJS from 'typescript-json-schema';
+import { Either } from 'fp-ts/Either';
+import { DynamicObject } from '@trayio/commons/dynamictype/DynamicType';
+import { TraySchemaGenerator } from './TraySchemaGenerator';
+export declare class TJSTraySchemaGenerator implements TraySchemaGenerator {
+    generateFromType(type: string, path: string): Either<Error, DynamicObject>;
+    jsonSchemaToTraySchema(schema: TJS.Definition): TJS.Definition;
+}
+//# sourceMappingURL=TJSTraySchemaGenerator.d.ts.map

package/dist/schema/TJSTraySchemaGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TJSTraySchemaGenerator.d.ts","sourceRoot":"","sources":["../../src/schema/TJSTraySchemaGenerator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,GAAG,MAAM,wBAAwB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAe,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,qBAAa,sBAAuB,YAAW,mBAAmB;IACjE,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC;IAqC1E,sBAAsB,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,UAAU;CAwG9D"}