from-schema

Convert JSON schemas to TypeScript types

Notes

• Only a small subset of JSONschema is supported
• This library is very opinionated
• Probably don't use this in production

Example - social media post

// Import various from-schema types
import { ArraySchema, EnumSchema, FromSchema, ObjectSchema } from 'from-schema';

// Import project-specific models defined elsewhere
import { attachment } from './attachment';
import { postBody } from './postBody';
import { postTitle } from './postTitle';
import { user } from './user';

// uuid can be passed to AJV for full UUID validation
export const uuid = {
    type: 'string',
    pattern:
        '^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}$',
} as const satisfies StringSchema;

// TypeScript will see Uuid as a standard string
export type Uuid = FromSchema<typeof uuid>;
/** Equivalent:
 *  type Uuid = string;
 * */

// Define an EnumSchema for the post body type
export const bodyType = {
    enum: ['plaintext', 'markdown'],
} as const satisfies EnumSchema;

// Export a type inferred from bodyType
export type BodyType = FromSchema<typeof bodyType>;
/** Equivalent:
 *  type BodyType = 'plaintext' | 'markdown'
 * */

// Define an array of attachments (defined elsewhere)
export const attachments = {
    type: 'array',
    items: attachment,
} as const satisfies ArraySchema;

// Infer a type based on that model
export type Attachments = FromSchema<typeof attachments>;
/* Equivalent:
 *  type Attachments = {<external definition>}[];
 * */

// Define the post itself -- AJV can compile this into a validator
export const post = {
    description: 'A post containing text, images, or videos',
    type: 'object',
    properties: {
        id: uuid, // You can embed schemas in other schemas
        body: postBody, // Maybe this is a string with specific constraints?
        bodyType,
        groupId: uuid,
        attachments,
        authorId: user.properties.id, // You can model document relationships
        likes: {
            type: 'number',
        },
        publishDate: {
            type: 'string',
        },
        replies: {
            type: 'number',
        },
        title: postTitle, // Another string with constraints defined elsewhere
        thread: {
            type: 'array',
            items: uuid,
        },
    },
    required: [
        'id',
        'authorId',
        'attachments',
        'publishDate',
        'likes',
        'replies',
    ],
} as const satisfies ObjectSchema;

// Infer a TypeScript type
export type Post = FromSchema<typeof post>;
/** Equivalent:
 *  type Post = {
 *    id: string,
 *    body?: string,
 *    bodyType?: 'plaintest' | 'markdown'
 *    groupId?: string,
 *    attachments: {...}[],
 *    authorId: string,
 *    likes: number,
 *    publishDate: string,
 *    replies: number,
 *    title?: string,
 *    thread?: string[]
 *  }
 * */

Generated documentation

This section is experimental and may be removed in future.

ArraySchema

Defined in ArraySchema.ts.

export type ArraySchema = SchemaBase & {
    readonly type: 'array';
    readonly items: SchemaOrPrimitive;
    readonly maxLength?: number;
    readonly minLength?: number;
};

Represents an array schema. It extends the SchemaBase and has the following properties:

• type: Must be 'array'.
• items: The schema or primitive type for the array elements.
• maxLength (optional): The maximum length of the array.
• minLength (optional): The minimum length of the array.

BooleanSchema

Defined in BooleanSchema.ts.

export type BooleanSchema = SchemaBase & {
    readonly type: 'boolean';
};

Represents a boolean schema. It extends the SchemaBase and has the following property:

• type: Must be 'boolean'.

EnumSchemaOf

Defined in EnumSchemaOf.ts.

export type EnumSchemaOf<K> = SchemaBase & {
    readonly enum: readonly K[];
};

Represents an enumeration schema of a specific type K. It extends the SchemaBase and has the following property:

• enum: An array of values of type K that the schema can take.

EnumSchema

Defined in EnumSchema.ts.

export type EnumSchema = SchemaBase & {
    readonly enum: readonly (string | number | StringSchema | NumberSchema)[];
};

Represents an enumeration schema. It extends the SchemaBase and has the following property:

• enum: An array of string, number, StringSchema, or NumberSchema values that the schema can take.

FromObjectSchema

Defined in FromObjectSchema.ts.

export type FromObjectSchema<T extends ObjectSchema> = OnlyRequired<T> &
    OnlyOptional<T>;

A utility type that constructs an object type from an ObjectSchema. It combines the required and optional properties of the schema.

FromPropertySchemas

Defined in FromPropertySchemas.ts.

export type FromPropertySchemas<T extends ObjectSchema> = {
    -readonly [K in keyof T['properties']]: PrimitiveOrFromSchema<
        T['properties'][K]
    >;
};

A utility type that constructs an object type from the properties of an ObjectSchema. It maps each property to its primitive or schema type.

FromSchema

Defined in FromSchema.ts.

export type FromSchema<T> = T extends StringSchema
    ? string
    : T extends NumberSchema
        ? number
        : T extends BooleanSchema
            ? boolean
            : T extends UnionSchemaOf<infer P extends SchemaOrPrimitive>
                ? PrimitiveOrFromSchema<P>
                : T extends EnumSchemaOf<infer P extends SchemaOrPrimitive>
                    ? PrimitiveOrFromSchema<P>
                    : T extends ObjectSchema
                        ? FromObjectSchema<T>
                        : T extends MapSchema
                            ? FromMapSchema<T>
                            : T extends ArraySchema
                                ? FromSchema<T['items']>[]
                                : NoSchema;

A utility type that constructs a TypeScript type from a schema type. It recursively maps the schema types to their corresponding TypeScript types.

HttpRoute

Defined in HttpRoute.ts.

export type HttpRoute = SchemaBase & {
    readonly request: ObjectSchema;
    readonly response: ObjectSchema;
    readonly authenticated: boolean;
};

Represents an HTTP route schema. It extends the SchemaBase and has the following properties:

• request: An ObjectSchema representing the request schema.
• response: An ObjectSchema representing the response schema.
• authenticated: A boolean indicating if authentication is required for the route.

MapSchema

Defined in MapSchema.ts.

export type MapSchema = {
    readonly type: 'map';
    readonly keys: StringSchema | EnumSchemaOf<string>;
    readonly values: Schema;
    readonly partial?: boolean;
};

Represents a map schema. It has the following properties:

• type: Must be 'map'.
• keys: A StringSchema or EnumSchemaOf<string> representing the schema for the map keys.
• values: The schema for the map values.
• partial (optional): A boolean indicating if the map is partial (allows undefined values).

MapSchemaOf

Defined in MapSchema.ts.

export type MapSchemaOf<
    K extends StringSchema | EnumSchemaOf<string>,
    V,
    P = false,
> = SchemaBase & {
    readonly type: 'map';
    readonly keys: K;
    readonly values: V;
    readonly partial: P;
};

Represents a map schema of specific key and value types. It extends the SchemaBase and has the following properties:

• type: Must be 'map'.
• keys: The schema for the map keys, of type K.
• values: The schema or primitive type for the map values, of type V.
• partial: A boolean indicating if the map is partial (allows undefined values), defaulting to false.

FromMapSchema

Defined in MapSchema.ts.

export type FromMapSchema<S extends MapSchema> = S['partial'] extends true
    ? {
            -readonly [key in S['keys'] extends EnumSchemaOf<infer M extends string>
                ? M
                : string]?: FromSchema<S['values']>;
        }
    : {
            -readonly [key in S['keys'] extends EnumSchemaOf<infer M extends string>
                ? M
                : string]: FromSchema<S['values']>;
        };

A utility type that constructs a map type from a MapSchema. It maps the key and value schemas to their corresponding TypeScript types, considering the partial property.

NumberSchema

Defined in NumberSchema.ts.

export type NumberSchema = SchemaBase & {
    readonly type: 'number' | 'integer';
    readonly minimum?: number;
    readonly maximum?: number;
};

Represents a number schema. It extends the SchemaBase and has the following properties:

• type: Must be 'number' or 'integer'.
• minimum (optional): The minimum value for the number.
• maximum (optional): The maximum value for the number.

ObjectSchema

Defined in ObjectSchema.ts.

export type ObjectSchemaWithoutRequired = SchemaBase & {
    readonly type: 'object';
    readonly properties: Record<string, SchemaOrPrimitive>;
    readonly minProperties?: number;
    readonly maxProperties?: number;
};

export type ObjectSchemaWithRequired = ObjectSchemaWithoutRequired & {
    readonly required: readonly string[];
};

export type ObjectSchema =
    | ObjectSchemaWithoutRequired
    | ObjectSchemaWithRequired;

Represents an object schema. It extends the SchemaBase and has the following properties:

• type: Must be 'object'.
• properties: A record of property names and their corresponding schemas or primitive types.
• minProperties (optional): The minimum number of properties required in the object.
• maxProperties (optional): The maximum number of properties allowed in the object.
• required (optional): An array of required property names.

OnlyOptional

Defined in OnlyOptional.ts.

export type OnlyOptional<T extends ObjectSchema> =
    T extends ObjectSchemaWithRequired
        ? Partial<Omit<FromPropertySchemas<T>, RequiredPropOf<T>>>
        : Partial<T['properties']>;

A utility type that constructs an object type with only the optional properties of an ObjectSchema.

OnlyRequired

Defined in OnlyRequired.ts.

export type OnlyRequired<T extends ObjectSchema> =
    T extends ObjectSchemaWithRequired
        ? Required<Pick<FromPropertySchemas<T>, RequiredPropOf<T>>>
        : Record<string, never>;

A utility type that constructs an object type with only the required properties of an ObjectSchema.

PrimitiveOrFromSchema

Defined in PrimitiveOrFromSchema.ts.

export type PrimitiveOrFromSchema<T extends SchemaOrPrimitive> =
    T extends Schema ? FromSchema<T> : T;

A utility type that constructs a TypeScript type from a schema or primitive type. If the input is a schema, it uses FromSchema to convert it to a TypeScript type; otherwise, it returns the primitive type as is.

Primitive

Defined in Primitive.ts.

export type Primitive = string | number | boolean | string[];

Represents a primitive type, which can be a string, number, boolean, or an array of strings.

RequiredPropOf

Defined in RequiredPropOf.ts.

export type RequiredPropOf<T extends ObjectSchemaWithRequired> = Extract<
    keyof T['properties'],
    T['required'][number]
>;

A utility type that extracts the required property names from an ObjectSchemaWithRequired.

SchemaBase

Defined in SchemaBase.ts.

export type SchemaBase = {
    readonly description?: string;
};

Represents the base schema type. It has an optional description property for providing a description of the schema.

SchemaOrPrimitive

Defined in SchemaOrPrimitive.ts.

export type SchemaOrPrimitive = Schema | Primitive;

Represents a schema or primitive type.

Schema

Defined in Schema.ts.

export type Schema =
    | ArraySchema
    | BooleanSchema
    | EnumSchema
    | MapSchema
    | NumberSchema
    | ObjectSchema
    | StringSchema
    | UnionSchema;

A union type representing all the available schema types.

StringSchema

Defined in StringSchema.ts.

export type StringSchema = SchemaBase & {
    readonly type: 'string';
    readonly minLength?: number;
    readonly maxLength?: number;
    readonly pattern?: string;
    readonly format?: string;
};

Represents a string schema. It extends the SchemaBase and has the following properties:

• type: Must be 'string'.
• minLength (optional): The minimum length of the string.
• maxLength (optional): The maximum length of the string.
• pattern (optional): A regular expression pattern that the string must match.
• format (optional): A format specifier for the string (e.g., 'date', 'email').

UnionSchemaOf

Defined in UnionSchemaOf.ts.

export type UnionSchemaOf<K extends SchemaOrPrimitive> = SchemaBase & {
    readonly union: readonly K[];
};

Represents a union schema of a specific type K. It extends the SchemaBase and has the following property:

• union: An array of schemas or primitive types that the schema can take.

UnionSchema

Defined in UnionSchema.ts.

export type UnionSchema = SchemaBase & {
    readonly union: readonly SchemaOrPrimitive[];
};

Represents a union schema. It extends the SchemaBase and has the following property:

• union: An array of schemas or primitive types that the schema can take.

WebSocketRoute

Defined in WebSocketRoute.ts.

export type WebSocketRoute = SchemaBase & Record<string, never>;

Represents a WebSocket route schema. It extends the SchemaBase and has no additional properties.

Usage Examples

Here are some usage examples for the different schema types:

ArraySchema

import { ArraySchema } from './ArraySchema';

const myArraySchema: ArraySchema = {
    type: 'array',
    items: {
        type: 'string',
    },
    maxLength: 10,
    minLength: 1,
};

BooleanSchema

import { BooleanSchema } from './BooleanSchema';

const myBooleanSchema: BooleanSchema = {
    type: 'boolean',
};

EnumSchema

import { EnumSchema } from './EnumSchema';

const myEnumSchema: EnumSchema = {
    enum: ['red', 'green', 'blue'],
};

MapSchema

import { MapSchema } from './MapSchema';

const myMapSchema: MapSchema = {
    type: 'map',
    keys: {
        type: 'string',
    },
    values: {
        type: 'number',
    },
    partial: true,
};

NumberSchema

import { NumberSchema } from './NumberSchema';

const myNumberSchema: NumberSchema = {
    type: 'number',
    minimum: 0,
    maximum: 100,
};

ObjectSchema

import { ObjectSchema } from './ObjectSchema';

const myObjectSchema: ObjectSchema = {
    type: 'object',
    properties: {
        name: {
            type: 'string',
        },
        age: {
            type: 'number',
        },
    },
    required: ['name'],
};

StringSchema

import { StringSchema } from './StringSchema';

const myStringSchema: StringSchema = {
    type: 'string',
    minLength: 1,
    maxLength: 50,
    pattern: '^[A-Za-z]+$',
};

UnionSchema

import { UnionSchema } from './UnionSchema';

const myUnionSchema: UnionSchema = {
    union: [
        {
            type: 'string',
        },
        {
            type: 'number',
        },
    ],
};

Contribution

Contributions to this project are welcome. If you find any issues or have suggestions for improvements, please open an issue or submit a pull request on the project's repository.

License

This project is licensed under the MIT License.