Skip to content

Latest commit

 

History

History
2001 lines (1445 loc) · 29.7 KB

api.md

File metadata and controls

2001 lines (1445 loc) · 29.7 KB
Raw

Auto-generated file. Updated with NPM deploy. Update manually with 'yarn docs'.

typescript-json-schema test examples

abstract-class

export abstract class AbstractBase {
    propA:number;
    propB:string;

    abstract doNotInclude(): void;
}

abstract-extends

import { AbstractBase } from "../abstract-class/main";

class MyObjectFromAbstract extends AbstractBase {
    doNotInclude(): void { }

    propB:string;
    propC:number;
}

annotation-default

interface MyObject {
  /**
   * @default true
   */
  varBoolean: boolean;
  /**
   * @default 123
   */
  varInteger: number;
  /**
   * @default 3.21
   */
  varFloat: number;
  /**
   * @default "foo"
   */
  varString: string;
  /**
   * @default [true, false, true]
   */
  varBooleanArray: boolean[];
  /**
   * @default [1, 2, 3, 4, 5]
   */
  varIntegerArray: number[];
  /**
   * @default [1.23, 65.21, -123.40, 0, 1000000.0001]
   */
  varFloatArray: number[];
  /**
   * @default ["a", "b", "c", "..."]
   */
  varStringArray: string[];
  /**
   * @default [true, 123, 3.21, "foo"]
   */
  varMixedArray: any[];
}

annotation-id

/**
 * @$id filled#
 */
interface MySubObject {
    a: boolean;
}

interface MyObject {
    /**
     * @$id empty#
     */
    empty;

    filled: MySubObject;
}

annotation-items

interface MyObject {
  /**
   * @items {"type":"integer"}
   */
  a: number[];

  /**
   * @items {"type":"integer", "minimum":0}
   */
  b: number[];

  /**
   * @items.type integer
   * @items.minimum 0
   */
  c: number[];

  /**
   * @items.type integer
   */
  d: number[];

  /**
   * @items {"type":"string", "format":"email"}
   */
  emails: string[];

  /**
   * @items.type string
   * @items.format email
   */
  emails2: string[];

}

annotation-ref

interface MySubObject {}

interface MyObject {
    /**
     * @$ref http://my-schema.org
     */
    externalRef;

    /**
     * @$ref http://my-schema.org
     */
    externalRefOverride: MySubObject;
}

annotation-required

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;

annotation-required

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: {}
    },
];

annotation-title

/**
 * @title filled#
 */
interface MySubObject {
    a: boolean;
}

interface MyObject {
    /**
     * @title empty#
     */
    empty;

    filled: MySubObject;
}

annotation-tjs

// All of these formats are defined in this specification: http://json-schema.org/latest/json-schema-validation.html#rfc.section.8.3

interface MyRef {}

interface MyObject {
    /**
     * @TJS-format date-time
     */
    dateTime: string;

    /**
     * @TJS-format email
     */
    email: string;

    /**
     * @TJS-format hostname
     */
    hostname: string;

    /**
     * @TJS-format ipv4
     */
    ipv4: string;

    /**
     * @TJS-format ipv6
     */
    ipv6: string;

    /**
     * @TJS-format uri
     */
    uri: string;

    /**
     * @TJS-format uri-reference
     */
    uriReference: string;

    /**
     * @TJS-format uri-template
     */
    uriTemplate: string;

    /**
     * @TJS-format json-pointer
     */
    jsonPointer: string;

    /**
     * @TJS-pattern ^[a-zA-Z0-9]{4}-abc_123$
     */
    regexPattern: string;

    /**
     * @TJS-pattern ^[a-zA-Z0-9]{4}-abc_123$
     */
    regexPatternWithWhitespace: string;

    /**
     * @TJS-minimum 5
     */
    oneCharacter: number;

    /**
     * @TJS-examples ["foo", 1]
     */
    examples: string;

    /**
     * @TJS-hide
     */
    booleanAnnotationDefaultValue: string;

    /**
     * @TJS-hide true
     */
    booleanAnnotationWithTrue: string;

    /**
     * @TJS-hide false
     */
    booleanAnnotationWithFalse: string;

    /**
     * @TJS-ignore
     */
    complexWithRefIgnored: MyRef;
}

any-unknown

export interface MyObject {
    a: any;
    b: unknown;
}

argument-id

interface MyObject {
    someProp: string;
    referenceType: ReferenceType;
}

interface ReferenceType {
    reference: true;
}

array-and-description

export interface MyObject {
  /**
   * A name
   */
  name?: string;
  description?: string;
  test: any[];
}

array-empty

type MyEmptyArray = [];

array-readonly

export type MyReadOnlyArray = ReadonlyArray<number>;

array-types

type MyArray = Array<string | number>;

builtin-names

declare namespace Ext {
    export class Array {
    }

    export class Foo {
        bar: Ext.Array;
    }
}

class-extends

class Base {
    propA:number;
}

class MyObject extends Base {
    propB:number;
}

class-single

class MyObject {
    constructor() {}
    propA:number;
    propB:number;
    doNotInclude(): void {}
}

comments

/**
 * Description of Vector3D, a type alias to a array of integers with length 3
 * If run without useTypeAliasRef, this comment should be ignored but
 * the other annotations should be inherited
 * @minItems 3
 * @maxItems 3
 */
type Vector3D = number[];

/**
 * Description of MyObject, a top level object,
 * which also has a comment that spans
 * multiple lines
 *
 * @additionalProperties false
 * @unsupportedAnnotationThatShouldBeIgnored
 */
interface MyObject {

    /**
     * Description of opacity, a field with min/max values
     * @minimum 0
     * @maximum 100
     */
    opacity: number;

    /**
     * Description of field position, of aliased type Vector3D, which should inherit its annotations
     */
    position: Vector3D;

    /**
     * Description of rotation, a field with an anonymous type
     */
    rotation: {
        /**
         * Description of the value yaw inside an anonymous type, with min/max annotations
         * @minimum -90
         * @maximum 90
         */
        yaw: number;
    };
}

comments-from-lib

/**
 * Use this comment
 */
export type MyObject = Pick<BigThing, "prop1">;

/**
 * Not this comment though
 */
interface BigThing {
  prop1: string;
  prop2: string;
};

comments-imports

/**
 * Description of Color.
 *
 * @pattern ^[0-9a-f]{6}$
 */
export type Color = string;

comments-imports

import { Color } from "./color";
import { Text } from "./text";

/** Description of MyObject */
export interface MyObject {
    /** Description of MyObject color property. */
    color: Color;

    /** Description of MyObject text property. */
    text: Text;
}

comments-imports

import { Color } from "./color";

/**
 * Description of Text interface.
 */
export interface Text {
    /** Description of text property. */
    text: string;

    /** Description of text color property. */
    color: Color;
}

comments-inline-tags

/**
 * This is MyOtherObject
 */
interface MyOtherObject {
  prop1: string;
}

/**
 * This is MyObject. It extends {@link MyOtherObject} and {@link SomeOtherObject}.
 */
interface MyObject extends MyOtherObject {
  prop2: string;
}

comments-override

/**
 * Type-level description
 * @additionalProperties true
 */
export interface MySubObject {
    value: string;
}

export interface MyObject {
    list: MySubObject[];

    sub1: MySubObject;

    /**
     * Property-level description
     * @additionalProperties false
     */
    sub2: MySubObject;

    /**
     * Date property description
     */
    date: Date;
}

custom-dates

namespace foo {
  export interface Date {
    day?: number;
    month?: number;
    year?: number;
  }

  export interface Bar {
    date: Date;
  }
}

dates

type DateAlias = Date;

interface MyObject {
    var1: Date;
    var2: DateAlias;
    /**
     * @format date
     */
    var3: Date;
    /**
     * @format date
     */
    var4: DateAlias;
}

default-properties

type Foo = "a" | "b" | "c" | boolean | number;

class MyObject {
    varBoolean: Foo = <any> false;
    varInteger: Foo = <any> 123;
    varString: Foo = <any> "123";
}

enums-compiled-compute

enum Enum {
  X = 1 << 1,
  Y = 1 << 2,
  Z = X | Y,
  A = 1,
}

enums-mixed

enum Enum {
    A, // = 0
    B = 1,
    C = true as any,
    D = "str" as any,
    E = null
}

interface MyObject {
  foo: Enum;
}

enums-number

enum Enum {
  X = 1,
  Y = 2
}

interface MyObject {
  foo: Enum;
}

enums-number-initialized

enum Enum {
  X = 10,
  Y,
  Z,
  A = 1,
}

enums-string

enum Enum {
    X = "x" as any,
    Y = "y" as any,
    Z = "123" as any
}

interface MyObject {
    foo: Enum;
}

enums-value-in-interface

export enum A {
  B,
  C,
  D,
};

export interface MyObject {
  code: A.B;
};

extra-properties

export interface MyObject {
    required: string;
    optional?: number;
    [name: string]: string|number;
}

force-type

/** @TJS-type number */
export class Widget {}

export interface MyObject {
    name: string;

    mainWidget: Widget;
    otherWidgets: Widget[];
}

force-type-imported

import { Widget } from "./widget";

export interface MyObject {
    name: string;

    mainWidget: Widget;
    otherWidgets: Widget[];
}

force-type-imported

/** @TJS-type number */
export class Widget {}

generate-all-types

interface MyInterface {

}

class MyObject {

}

enum MyEnum {
    Value = 0
}

generic-anonymous

interface MyGeneric<A, B> {
    a: A;
    b: B;
}

export interface MyObject {
    value1: MyGeneric<string, number>;
    value2: MyGeneric<number, string>;
}

generic-arrays

export interface MyObject {
    numberArray: Array<number>;
    stringArray: ReadonlyArray<string>;
}

generic-hell

export interface GenericA<A> {
    a: A;
}
export interface B {
    b: number;
}
export interface GenericC<C> {
    c: C;
}

export type SomeAlias<T> = SomeGeneric<T, T>;
export interface SomeGeneric<A, B> {
    a: A;
    b: B;
    c: GenericA<A>;
    d: GenericC<B>;
}

export interface MyObject extends GenericC<GenericC<GenericC<GenericA<string>>>>, B {
    someGeneric: SomeGeneric<1, 2>;
    someAlias: SomeAlias<"alias">;
}

generic-multiargs

export interface MyGeneric<A, B> {
    a: A;
    b: B;
}

export interface MyObject {
    value1: MyGeneric<string, number>;
    value2: MyGeneric<number, string>;
}

generic-multiple

export interface MyGeneric<T> {
    field: T;
}

export interface MyObject {
    value1: MyGeneric<number>;
    value2: MyGeneric<string>;
}

generic-recursive

export interface MyGeneric<A, B> {
    field: MyGeneric<B, A>;
}

export interface MyObject {
    value: MyGeneric<string, number>;
}

generic-simple

export interface MyGeneric<T> {
    field: T;
}

export interface MyObject {
    value: MyGeneric<number>;
}

ignored-required

interface MyObject {
    /**
     * @ignore
     */
    ignored: boolean;

    /**
     * @ignore
     */
    ignoredOptional?: boolean;

    required: boolean;
    optional?: boolean;
}

imports

// This file imports "MyInterface" from the other 2 files
// while also declaring a MyInterface type

import { MyInterface as module1_MyInterface } from "./module1";
import * as module2 from "./module2";

class MyInterface {
    fieldInMain: number;
}

class MyObject {
    a: MyInterface;
    b: module1_MyInterface;
    c: module2.MyInterface;
}

imports

export class MyInterface {
    fieldInModule1: string;
}

imports

export class MyInterface {
    fieldInModule2: number;
}

interface-extends

interface Base {
    propA: number;
}

export interface MyObject extends Base {
    propB: number;
}

interface-extra-props

export interface MyObject {
    required: string;
    optional?: number;
    [name: string]: string|number;
}

interface-multi

interface MyObject {
    subA: MySubObject;
    subB: MySubObject;
}
interface MySubObject {
    propA: number;
    propB: number;
}

interface-recursion

interface MyObject {
    propA: number;
    propB: MyObject;
}

interface-single

export interface MyObject {
    propA: number;
    propB: number;
}

map-types

interface MyType {}

interface MyMap1 {
    [id: string]: MyType;
}

/**
 * The additionalProperties annotation should be ignored
 * @additionalProperties false
 */
interface MyMap2 {
    [id: string]: (string | number);
}

type MyMap3 = Readonly<MyMap2>;

interface MyObject {
    map1: MyMap1;
    map2: MyMap2;
    map3: MyMap3;
}

module-interface-deep

module MyModule {
    export interface Def {
        nest: Def;
        prev: MyModule.Def;
        propA: SubModule.HelperA;
        propB: SubModule.HelperB;
    }
    export module SubModule {
        export interface HelperA {
            propA: number;
            propB: HelperB;
        }
        export interface HelperB {
            propA: SubModule.HelperA;
            propB: Def;
        }
    }
}

module-interface-single

module MyModule {
    interface MyObject {
        propA: number;
        propB: number;
    }
}

namespace

export namespace Types {
  export const X: "x" = "x";
  export const Y: "y" = "y";
}

export type Type = typeof Types.X | typeof Types.Y;

namespace-deep-1

namespace RootNamespace {
    export interface Def {
        nest: Def;
        prev: RootNamespace.Def;

        propA: SubNamespace.HelperA;
        propB: SubNamespace.HelperB;
    }

    export namespace SubNamespace {
        export interface HelperA {
            propA: number;
            propB: HelperB;
        }
        export interface HelperB {
            propA: SubNamespace.HelperA;
            propB: Def;
        }
    }
}

namespace-deep-2

namespace RootNamespace {
    export interface Def {
        nest: Def;
        prev: RootNamespace.Def;

        propA: SubNamespace.HelperA;
        propB: SubNamespace.HelperB;
    }

    export namespace SubNamespace {
        export interface HelperA {
            propA: number;
            propB: HelperB;
        }
        export interface HelperB {
            propA: SubNamespace.HelperA;
            propB: Def;
        }
    }
}

never

export interface Never {
  neverProp: never;
  propA: string;
}

no-unrelated-definitions

export interface MyObject {
  sub: SomeDefinition;
}

interface SomeDefinition {
  is: string;
}

export interface MyOtherObject {
  sub: SomeOtherDefinition;
}

interface SomeOtherDefinition {
  is: string;
}

object-numeric-index

interface IndexInterface {
  [index: number]: number;
}

object-numeric-index-as-property

interface Target {
  objAnonymous: {
    [index: number]: number;
  };
  objInterface: IndexInterface;
  indexInType: { [index in number]?: number };
  indexInInline: { [index in number]: number };
  indexInPartialType: IndexInPartial;
  indexInPartialInline: { [index in number]?: number };
}
interface IndexInterface {
  [index: number]: number;
}

type IndexIn = { [index in number]: number };
type IndexInPartial = { [index in number]?: number };

optionals

interface MyObject {
    required:number;
    optional?:number;
}

optionals-derived

interface MyBase {
    baseRequired : number;
    baseOptional?: number;
}

interface MyDerived extends MyBase {
    derivedRequired : number;
    derivedOptional?: number;
}

private-members

export class MyObject {
    publicMember: string;
    private privateMember: string;
}

prop-override

import type { ObjectId } from './third-party'

export type MyObject = {
  /**
   * @TJS-type string
   * @description Overrides aliased type definition with this JSDoc if at least TJS-type annotation is present
   */
  _id: ObjectId
}

prop-override

// cannot modify with JSDoc because third-party sources
export class ObjectId {}

strict-null-checks

class MyObject {
     val: number;
     valNullable: number | null;
     valUndef: number | undefined;
     valOpt?: number;
     valVoid: number | void;

     valTrueOpt?: true;
     valTrueOrNull: true|null;
     valTrue: true|true; // twice to check that it will appear only once
}

string-literals

type result = "ok" | "fail" | "abort" | "";

class MyObject {
    foo: result;
    bar: result | string;
}

string-literals-inline

class MyObject {
    foo: "ok" | "fail" | "abort" | "";
    bar: "ok" | "fail" | "abort" | string;
}

tsconfig

// This file is ignored.

export interface Excluded {
    a: string;
}

tsconfig

// This file is included by tsconfig.json and --include.

export interface IncludedAlways {
    a: string;
};

tsconfig

// This file is included by tsconfig.json.

export interface IncludedOnlyByTsConfig {
    a: string;
};

type-alias-or

interface A {}
interface B {}

type C = A | B;

interface MyObject {
    c: C;
}

type-alias-schema-override

interface All {}

type Some = Partial<All>;

interface MyObject {
  some?: Some;
}

type-alias-single

type MyString = string;

type-alias-single-annotated

/**
 * This is a description
 * @pattern ^mystring-[a-zA-Z0-9]+$
 * @minLength 10
 * @maxLength 24
 */
type MyString = string;

type-aliases

/**
 * My string
 */
type MyString = string;

/**
 * My type alias
 */
type MyAlias = MySubObject;

/**
 * My sub object
 */
interface MySubObject {
    propA: number;
    propB: number;
}

/**
 * My Object
 */
interface MyObject {
    primitive: MyString;
    object: MySubObject;
    alias: MyAlias;
}

type-aliases-alias-ref

interface MyObject {
    prop: number;
}

type MyAlias = MyObject;

type-aliases-alias-ref-topref

interface MyObject {
    prop: number;
}

type MyAlias = MyObject;

type-aliases-anonymous

export type MyExportString = string;
type MyPrivateString = string;

export interface MyObject {
    export: MyExportString;
    private: MyPrivateString;
}

type-aliases-fixed-size-array

type MyFixedSizeArray = [string, number];

type-aliases-local-namespace

namespace A {
    export interface A { a: any; }
}
namespace B {
    export interface B { b: any; }
}
namespace C {
    import A = B.B;
    export interface C { c: A; }
}
namespace D {
    import A = C.C;
    export interface D { d: A; }
}

export interface MyObject extends D.D {}

type-aliases-local-namsepace

namespace A {
    export interface A {a: any;}
}
namespace B {
    export interface B {b: any;}
}
namespace C {
    import A = B.B;
    export interface C {c: A;}
}
namespace D {
    import A = C.C;
    export interface D {d: A;}
}

interface MyObject extends D.D {}

type-aliases-mixed

export type MyString = string;

export interface MySubObject {
    propA: number;
    propB: number;
}

export interface MyObject {
    primitive: MyString;
    object: MySubObject;
}

type-aliases-multitype-array

type BasicArray = (string | number)[];

interface MyObject {
    array: BasicArray;
}

type MyArray = (string | MyObject)[];

type-aliases-object

export interface MyObject {
    number: number;
    string: string;
}

export type MyAlias = MyObject;

type-aliases-partial

export interface Foo {
    x: number;
    y: number;
}

export interface Bar {
    a: number;
    b: number;
}

export interface MyObject {
    foo: Partial<Foo>;
    bar: Partial<Bar>;
}

type-aliases-primitive

export type MyString = string;

type-aliases-recursive-alias-topref

interface MyObject {
    alias: MyAlias;
    self: MyObject;
}

type MyAlias = MyObject;

type-aliases-recursive-anonymous

interface MyObject {
    alias: MyAlias;
    self: MyObject;
}

export type MyAlias = MyObject;

type-aliases-recursive-export

export interface MyObject {
    alias: MyAlias;
    self: MyObject;
}

export type MyAlias = MyObject;

type-aliases-recursive-object-topref

interface MyObject {
    alias: MyAlias;
    self: MyObject;
}

type MyAlias = MyObject;

type-aliases-tuple

export type MyTuple = [string, number];

type-aliases-tuple-of-variable-length

export type MyTuple = [string, number, boolean?];

type-aliases-tuple-with-rest-element

export type MyTuple = [string, ...number[]];

type-aliases-union

type BasicArray = (string | number)[];

export interface MyObject {
    array: BasicArray;
}

export type MyUnion = (string | MyObject)[];

type-aliases-union-namespace

export namespace Cardinal {
    export const NORTH: "north" = "north";
    export const SOUTH: "south" = "south";
    export const EAST: "east" = "east";
    export const WEST: "west" = "west";
}

export type Cardinal = typeof Cardinal.NORTH | typeof Cardinal.SOUTH | typeof Cardinal.EAST | typeof Cardinal.WEST;

export interface MyModel {
    direction: Cardinal;
}

type-anonymous

 interface MyObject {
    FieldWithAnonType: {
        SubfieldA: number;
        SubfieldB: (string | number);
        SubfieldC: {
            SubsubfieldA: number[];
        }
    };
}

type-default-number-as-integer

interface MyObject {
    as_integer: number;

    /** @TJS-type number */
    as_number: number;
}

type-function

interface MyObject {
    myFunction: Function;
}

type-globalThis

export type Test = typeof globalThis;

type-intersection

interface Type1 {
    value1: string;
    value2: number;
}
interface Type2 {
    value2: number;
    value3: boolean;
}

interface MyObject {
    value: Type1 & Type2;
}

type-intersection-recursive

interface ChildFoo {
}

interface Foo {
    readonly childFoos: Foo & ChildFoo;
}

type-mapped-types

type Keys = "str1" | "str2";

type MyMappedType = {
  [key in Keys]: string;
};

type-no-aliases-recursive-topref

interface MyObject {
    alias: MyAlias;
    self: MyObject;
}

type MyAlias = MyObject;

type-nullable

/** @nullable */
type MyType1 = string;

/** @nullable */
type MyType2 = string | number;

/** @nullable */
type MyType3 = string | number[];

/** @nullable */
type MyType4 = number[];

type Ref = { foo: number };

/** @nullable */
type MyType5 = Ref;

interface MyType6 {};

interface MyObject {
    var1: MyType1;
    var2: MyType2;
    var3: MyType3;
    var4: MyType4;
    var5: MyType5;

    /**
     * @nullable
     */
    var6: MyType6;
    var7: MyType6;
}

type-primitives

/* tslint:disable:no-inferrable-types */

// Special type, should not appear in the schema
type integer = number;

class MyObject {

    boolean1: boolean     = true;

    number1: number       = 1;

    /** @TJS-type integer */
    integer1: number      = 1;
    integer2: integer     = 1;

    string1: string       = "defaultValue";

    array1: Array<any>    = null;
    array2: Array<number> = null;

    object1: any          = null;
    object2: {}           = null;
    object3: object       = null;

}

type-recursive

/**
 * A recursive type
 */
export type TestChildren = TestChild | Array<TestChild | TestChildren>;

interface TestChild {
    type: string;
}

type-union

// Simple union (generates "type": [...])
type MyType1 = string | number;

// Non-simple union (generates a "oneOf"/"anyOf")
type MyType2 = string | number[];

interface MyObject {
    var1: MyType1;
    var2: MyType2;
}

type-union-tagged

interface Square {
    kind: "square";
    size: number;
}

interface Rectangle {
    kind: "rectangle";
    width: number;
    height: number;
}

interface Circle {
    kind: "circle";
    radius: number;
}

type Shape = Square | Rectangle | Circle;

typeof-keyword

interface MyObject {
  foo: () => string;
}

unique-names

import "./other";

class MyObject {
  is: "MyObject_1";
}

unique-names

class MyObject {
  is: "MyObject_2";
}

unique-names-multiple-subdefinitions

import "./other";

class SubObject {
  is: "SubObject_1";
}

class MyObject {
  sub: SubObject;
}

unique-names-multiple-subdefinitions

class SubObject {
  is: "SubObject_2";
}

user-symbols

export interface Context {
  ip: string;
}

user-validation-keywords

export interface MyObject {
  /**
   * Must be 'first' or 'last'
   *
   * @minLength 1
   * @chance {
   *   "pickone": [ [ "first", "last" ] ]
   * }
   * @ignoreThis 2
   * @important
   */
  name: string;
}