Add require functionality in annotations (#399)

Author: martin-tichovsky-s2

README.md

@@ -48,6 +48,7 @@ Options:
   --rejectDateType      Rejects Date fields in type definitions.                     [boolean] [default: false]
   --id                  Set schema id.                                               [string]  [default: ""]
   --defaultNumberType   Default number type.                                         [choices: "number", "integer"] [default: "number"]
+  --tsNodeRegister      Use ts-node/register (needed for require typescript files).  [boolean] [default: false]
 ```
 
 ### Programmatic use
@@ -59,12 +60,12 @@ import * as TJS from "typescript-json-schema";
 
 // optionally pass argument to schema generator
 const settings: TJS.PartialArgs = {
-  required: true,
+    required: true,
 };
 
 // optionally pass ts compiler options
 const compilerOptions: TJS.CompilerOptions = {
-  strictNullChecks: true,
+    strictNullChecks: true,
 };
 
 // optionally pass a base path
@@ -95,7 +96,7 @@ generator.getSchemaForSymbol("AnotherType");
 // In larger projects type names may not be unique,
 // while unique names may be enabled.
 const settings: TJS.PartialArgs = {
-  uniqueNames: true,
+    uniqueNames: true,
 };
 
 const generator = TJS.buildGenerator(program, settings);
@@ -114,10 +115,10 @@ const fullSymbolList = generator.getSymbols();
 
 ```ts
 type SymbolRef = {
-  name: string;
-  typeName: string;
-  fullyQualifiedName: string;
-  symbol: ts.Symbol;
+    name: string;
+    typeName: string;
+    fullyQualifiedName: string;
+    symbol: ts.Symbol;
 };
 ```
 
@@ -131,34 +132,34 @@ For example
 
 ```ts
 export interface Shape {
-  /**
-   * The size of the shape.
-   *
-   * @minimum 0
-   * @TJS-type integer
-   */
-  size: number;
+    /**
+     * The size of the shape.
+     *
+     * @minimum 0
+     * @TJS-type integer
+     */
+    size: number;
 }
 ```
 
 will be translated to
 
 ```json
 {
-  "$ref": "#/definitions/Shape",
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "definitions": {
-    "Shape": {
-      "properties": {
-        "size": {
-          "description": "The size of the shape.",
-          "minimum": 0,
-          "type": "integer"
+    "$ref": "#/definitions/Shape",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "definitions": {
+        "Shape": {
+            "properties": {
+                "size": {
+                    "description": "The size of the shape.",
+                    "minimum": 0,
+                    "type": "integer"
+                }
+            },
+            "type": "object"
         }
-      },
-      "type": "object"
     }
-  }
 }
 ```
 
@@ -172,52 +173,52 @@ Example:
 
 ```ts
 export interface ShapesData {
-  /**
-   * Specify individual fields in items.
-   *
-   * @items.type integer
-   * @items.minimum 0
-   */
-  sizes: number[];
-
-  /**
-   * Or specify a JSON spec:
-   *
-   * @items {"type":"string","format":"email"}
-   */
-  emails: string[];
+    /**
+     * Specify individual fields in items.
+     *
+     * @items.type integer
+     * @items.minimum 0
+     */
+    sizes: number[];
+
+    /**
+     * Or specify a JSON spec:
+     *
+     * @items {"type":"string","format":"email"}
+     */
+    emails: string[];
 }
 ```
 
 Translation:
 
 ```json
 {
-  "$ref": "#/definitions/ShapesData",
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "definitions": {
-    "Shape": {
-      "properties": {
-        "sizes": {
-          "description": "Specify individual fields in items.",
-          "items": {
-            "minimum": 0,
-            "type": "integer"
-          },
-          "type": "array"
-        },
-        "emails": {
-          "description": "Or specify a JSON spec:",
-          "items": {
-            "format": "email",
-            "type": "string"
-          },
-          "type": "array"
+    "$ref": "#/definitions/ShapesData",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "definitions": {
+        "Shape": {
+            "properties": {
+                "sizes": {
+                    "description": "Specify individual fields in items.",
+                    "items": {
+                        "minimum": 0,
+                        "type": "integer"
+                    },
+                    "type": "array"
+                },
+                "emails": {
+                    "description": "Or specify a JSON spec:",
+                    "items": {
+                        "format": "email",
+                        "type": "string"
+                    },
+                    "type": "array"
+                }
+            },
+            "type": "object"
         }
-      },
-      "type": "object"
     }
-  }
 }
 ```
 
@@ -232,12 +233,80 @@ Example:
 ```typescript
 type integer = number;
 interface MyObject {
-  n: integer;
+    n: integer;
 }
 ```
 
 Note: this feature doesn't work for generic types & array types, it mainly works in very simple cases.
 
+### `require` a variable from a file
+
+(for requiring typescript files is needed to set argument `tsNodeRegister` to true)
+
+When you want to import for example an object or an array into your property defined in annotation, you can use `require`.
+
+Example:
+
+```ts
+export interface InnerData {
+    age: number;
+    name: string;
+    free: boolean;
+}
+
+export interface UserData {
+    /**
+     * Specify required object
+     *
+     * @examples require("./example.ts").example
+     */
+    data: InnerData;
+}
+```
+
+file `example.ts`
+
+```ts
+export const example: InnerData[] = [{
+  age: 30,
+  name: "Ben",
+  free: false
+}]
+```
+
+Translation:
+
+```json
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "properties": {
+        "data": {
+            "description": "Specify required object",
+            "examples": [
+                {
+                    "age": 30,
+                    "name": "Ben",
+                    "free": false
+                }
+            ],
+            "type": "object",
+            "properties": {
+                "age": { "type": "number" },
+                "name": { "type": "string" },
+                "free": { "type": "boolean" }
+            },
+            "required": ["age", "free", "name"]
+        }
+    },
+    "required": ["data"],
+    "type": "object"
+}
+```
+
+Also you can use `require(".").example`, which will try to find exported variable with name 'example' in current file. Or you can use `require("./someFile.ts")`, which will try to use default exported variable from 'someFile.ts'.
+
+Note: For `examples` a required variable must be an array.
+
 ## Background
 
 Inspired and builds upon [Typson](https://github.com/lbovet/typson/), but typescript-json-schema is compatible with more recent Typescript versions. Also, since it uses the Typescript compiler internally, more advanced scenarios are possible. If you are looking for a library that uses the AST instead of the type hierarchy and therefore better support for type aliases, have a look at [vega/ts-json-schema-generator](https://github.com/vega/ts-json-schema-generator).

package.json

@@ -48,6 +48,7 @@
     "@types/json-schema": "^7.0.6",
     "glob": "^7.1.6",
     "json-stable-stringify": "^1.0.1",
+    "ts-node": "^9.1.1",
     "typescript": "^4.1.3",
     "yargs": "^16.2.0"
   },
@@ -62,7 +63,6 @@
     "mocha": "^8.2.1",
     "prettier": "^2.2.1",
     "source-map-support": "^0.5.19",
-    "ts-node": "^9.1.1",
     "tslint": "^6.1.3"
   },
   "scripts": {

test/programs/annotation-required/examples.ts

@@ -0,0 +1,15 @@
+import { MyDefaultObject, MySubObject2 } from "./main";
+
+export const mySubObject2Example: MySubObject2[] = [{
+    bool: true,
+    string: "string",
+    object: { prop: 1 }
+}];
+
+const myDefaultExample: MyDefaultObject[] = [{
+    age: 30,
+    name: "me",
+    free: true
+}]
+
+export default myDefaultExample;

test/programs/annotation-required/main.ts

@@ -0,0 +1,40 @@
+interface MySubObject {
+    bool: boolean;
+    string: string;
+    object: object | null;
+    /**
+     * @examples require('./examples.ts').mySubObject2Example
+     */
+    subObject?: MySubObject2;
+}
+
+export interface MySubObject2 {
+    bool: boolean;
+    string: string;
+    object: object;
+}
+
+export interface MyDefaultObject {
+  age: number;
+  name: string;
+  free?: boolean;
+}
+
+export interface MyObject {
+    /**
+     * @examples require(".").innerExample
+     */
+    filled: MySubObject;
+    /**
+     * @examples require('./examples.ts')
+     */
+    defaultObject: MyDefaultObject;
+}
+
+export const innerExample: MySubObject[] = [
+    {
+        bool: true,
+        string: "string",
+        object: {}
+    },
+];