@powership/schema

Typescript schema validation with static type inference.

Schemas are a crucial part of a microservices architecture or a detachable application architecture (global.powership). They can serve as contracts between different pieces of an application (frontend, backend, forms) and different services. So schemas should be easily portable, written and read, and that's the goal of this package.

Installation

To install:

1npm install @powership/schema

⚠️ IMPORTANT: You must enable strict mode in your tsconfig.json. This is a best practice for all TypeScript projects.

1// tsconfig.json
2{
3  // ...
4  "compilerOptions": {
5    // ...
6    "strict": true
7  }
8}

Usage

Schema

1  const addressSchema = createSchema({
2    street: 'string',
3    number: 'int?',
4  });
5
6  const schemaDefinition = {
7    name: 'string', // any string
8    email: 'email?', // email type - will validate against email regex
9    age: 'int?', // optional integer
10    notes: '[int]?',
11
12    // declaring an union
13    unionField: [['string?', '[int]?']],
14
15    // represents an enum
16    letter: ['a', 'b', 'c'],
17
18    // more detailed way to define enums
19    letterOptionalList: {
20      enum: ['x', 'y', 'z'],
21      optional: true,
22      list: true,
23    },
24
25    // using a previous schema as field type
26    optionalAddress: {
27      type: addressSchema,
28      optional: true,
29    },
30
31    // another way to define schema fields
32    deliveryAddress: {
33      schema: {
34        street: 'string',
35        number: 'int?',
36      },
37    },
38  } as const; // "as const" is needed to TS to infer types correctly
39
40  const userSchema = createSchema(schemaDefinition);
41
42  expect(() => userSchema.parse({ name: 'Antonio', letter: 'x' })).toThrow(
43    `field "letter": accepted: 'a' or 'b' or 'c', found x.`
44  );
45
46  expect(() => userSchema.parse({ name: 'antonio', letter: 'a', deliveryAddress: {} })).toThrow(
47    'field "deliveryAddress": ➤ field "street": expected type string, found undefined.'
48  );
49
50  const parsed = userSchema.parse({ name: 'antonio', letter: 'a', deliveryAddress: { street: 'alameda' } });
51
52  type InferType = typeof parsed;
53
54  assert<
55    IsExact<
56      InferType,
57      {
58        name: string;
59        email?: string | undefined;
60        age?: number | undefined;
61        notes?: number[] | undefined;
62        unionField?: string | number[] | undefined;
63        letter: 'a' | 'b' | 'c';
64        letterOptionalList?: ('x' | 'y' | 'z')[] | undefined;
65        optionalAddress?:
66          | {
67              street: string;
68              number?: number | undefined;
69            }
70          | undefined;
71
72        deliveryAddress: {
73          street: string;
74          number?: number | undefined;
75        };
76      }
77    >
78  >(true);

schemaToTypescript

Returns a string of an interface representing a PowershipSchema;

1import { schemaToTypescript } from '@powership/schema/lib/schemaToTypescript';
2
3const interfaceTxt = await schemaToTypescript('User', userSchema);
4
5const interfaceTxt = await schemaToTypescript('User', userSchema);
6expect(interfaceTxt).toBe(`
7export interface User {
8  name: string;
9  email?: Email;
10  age?: number;
11  notes?: number[];
12  unionField?: string | number[];
13  letter: "a" | "b" | "c";
14  letterOptionalList?: ("x" | "y" | "z")[];
15  optionalAddress?: {
16    street: string;
17    number?: number;
18  };
19  deliveryAddress: {
20    street: string;
21    number?: number;
22  };
23}`);

schemaToJSON

Receives a PowershipSchema and returns a json-schema

1  import { schemaToJSON } from '@powership/schema/lib/schemaToJSON';
2
3  const jsonSchema = schemaToJSON('User', userSchema);
4
5  expect(jsonSchema).toEqual({
6    properties: {
7      address: {
8        properties: {
9          number: {
10            type: 'integer',
11          },
12          street: {
13            type: 'string',
14          },
15        },
16        required: ['street'],
17        title: '',
18        type: 'object',
19      },
20      age: {
21        type: 'integer',
22      },
23      email: {
24        tsType: 'Email',
25        type: 'string',
26      },
27      letter: {
28        enum: ['a', 'b', 'c'],
29        title: 'EnumLetterUser',
30        type: 'string',
31      },
32      letterOptionalList: {
33        items: {
34          enum: ['x', 'y', 'z'],
35          title: 'Enum__subLetterOptionalList',
36          type: 'string',
37        },
38        type: 'array',
39      },
40      name: {
41        type: 'string',
42      },
43      notes: {
44        items: {
45          type: 'integer',
46        },
47        type: 'array',
48      },
49    },
50    required: ['name', 'letter'],
51    title: 'User',
52    type: 'object',
53  });

TODO

• improve documentation