Powership / Modules

Powership

All-in-one full-stack package for managing complex web applications.

Powership is the full-stack package of choice for creating, managing, and scaling complex web applications with support for single-table design.

Using Powership you can quickly create types that can be easily extended, transformed into GraphQL, TypeScript, and used in both frontend and backend applications.

Table of Contents

1. Typescript Infer
2. Extending Types
3. Static typescript Infer
4. Printing Types as Typescript
5. Validation
6. Entity & CRUD
7. GraphQL

Creating and extending types

1import { createGraphQLSchema, createResolver, createType, createEntity, Infer } from 'powership';
2
3const AddressType = createType('Address', {
4  object: {
5    street: 'string',
6    number: {
7      union: ['string', 'int?'],
8    },
9  },
10});
11
12const UserType = createType(
13  {
14    object: {
15      name: 'string', // any string
16      email: 'email?', // email type - will validate against email regex
17      age: 'int?', // optional integer
18      notes: '[int]?',
19
20      // declaring a union field - will infer as `string | undefined | number[]`
21      unionField: {
22        union: ['string?', '[int]?'],
23      },
24
25      // represents an enum
26      letter: {
27        enum: ['a', 'b', 'c'],
28      },
29
30      // more detailed way to define enums
31      letterOptionalList: {
32        enum: ['x', 'y', 'z'],
33        optional: true,
34        list: true,
35      },
36
37      // using a previous object as field type
38      addresses: {
39        type: AddressType,
40        list: true,
41      },
42
43      // another way to define object fields
44      deliveryAddress: {
45        object: {
46          street: 'string',
47          number: 'int?',
48        },
49      },
50    },
51  } as const // "as const" is needed to TS to infer types correctly
52);

Extending types

1const StoreType = UserType.clone((it) =>
2  it.exclude(['addresses']).extendObjectDefinition({ storeId: 'ID', ownerId: 'string' }).graphType('Store')
3);

Static typescript infer

1type TStoreType = Infer<typeof StoreType>;

Printing types as Typescript

1const storeTS = await StoreType.typescriptPrint();
2
3expect(storeTS.split('\n')).toEqual([
4  'export interface Store {',
5  '  name: string;',
6  '  email?: Email;',
7  '  age?: number;',
8  '  notes?: number[];',
9  '  unionField?: string | number[];',
10  '  letter: "a" | "b" | "c";',
11  '  letterOptionalList?: ("x" | "y" | "z")[];',
12  '  deliveryAddress: {',
13  '    street: string;',
14  '    number?: number;',
15  '  };',
16  '  storeId: ID;',
17  '  ownerId: string;',
18  '}',
19  '',
20]);

Validation

1try {
2  const validStoreData = StoreType.parse({});
3  console.log(validStoreData);
4} catch (e) {
5  /*
6   *  Error: Store: ➤ field "ownerId": RequiredField.
7   *           ➤ field "storeId": RequiredField.
8   *           ➤ field "deliveryAddress": RequiredField.
9   *           ➤ field "letter": RequiredField.
10   *           ➤ field "name": RequiredField.
11   */
12}

Entity and CRUD

1const StoreEntity = createEntity({
2  name: 'Store',
3  type: StoreType,
4  indexes: [
5    {
6      name: 'id1', // index in database to be used
7      PK: ['.storeId'],
8    },
9    {
10      name: 'id2',
11      PK: ['.ownerId', '.storeId'],
12    },
13  ],
14});
15
16const findStoreResolver = createResolver({
17  name: 'findStore',
18  type: StoreEntity.edgeType,
19  args: {
20    storeId: 'string',
21  },
22}).resolver(async (_, { storeId /* ✨ automaticly typed as string */ }, requestContext) => {
23  const filter = {
24    storeId,
25  };
26
27  return StoreEntity.findOne({ filter, context: requestContext });
28});

GraphQL

1const graphqlSchema = createGraphQLSchema([findStoreResolver]);
2
3const schemaTXT = graphqlSchema.utils.print();
4
5expect(schemaTXT.split('\n')).toEqual([
6  'type Query {',
7  '  findStore(storeId: String!): Store_Edge!',
8  '}',
9  '',
10  'type Store_Edge {',
11  '  cursor: String!',
12  '  node: StoreEntity!',
13  '}',
14  '',
15  'type StoreEntity {',
16  '  createdAt: Date!',
17  '  createdBy: String',
18  '  id: String!',
19  '  ulid: Ulid!',
20  '  updatedAt: Date!',
21  '  updatedBy: String',
22  '',
23  '  """',
24  '  The full string value of the first index following the RegExp format "^store⋮id1⋮.*"',
25  '  """',
26  '  _id: String!',
27  '',
28  '  """',
29  '  The id1PK field in the RegExp format "^store⋮id1⋮.*"',
30  '  """',
31  '  id1PK: String!',
32  '',
33  '  """',
34  '  The id2PK field in the RegExp format "^store⋮id2⋮.*"',
35  '  """',
36  '  id2PK: String!',
37  '  name: String!',
38  '  email: String',
39  '  age: Int',
40  '  notes: [Int]',
41  '  unionField: StoreEntity_unionField',
42  '  letter: StoreEntity_letter!',
43  '  letterOptionalList: [StoreEntity_letterOptionalList]',
44  '  deliveryAddress: StoreEntity_deliveryAddress!',
45  '  storeId: ID!',
46  '  ownerId: String!',
47  '}',
48  '',
49  'scalar Date',
50  '',
51  'scalar Ulid',
52  '',
53  '"""',
54  'Union of { optional:true, type: string } | { list:true, optional:true, type: int }',
55  '"""',
56  'scalar StoreEntity_unionField',
57  '',
58  'enum StoreEntity_letter {',
59  '  a',
60  '  b',
61  '  c',
62  '}',
63  '',
64  'enum StoreEntity_letterOptionalList {',
65  '  x',
66  '  y',
67  '  z',
68  '}',
69  '',
70  'type StoreEntity_deliveryAddress {',
71  '  street: String!',
72  '  number: Int',
73  '}',
74]);