kapix-graphql-prisma-client

Kapix website

kapix-graphql-prisma-client

This is a client-side library made for interacting with a Graphql/Prisma API backend.

This is primarily a TypeScript library.

Installation

npm install kapix-graphql-prisma-client

Usage

This library exposes TypeScript classes to build queries and mutation based on an entitiesModels object you have to describe with a defineService() function.

This library is best used inside a downloaded Kapix Project where everything surrounding this will generated for you.

Example entitiesModels

The following code describes a simple 2 tables schema where a User has a Post List.

import type { NestedCreateInput, NestedListCreateInput, NestedUpdateInput, NestedListUpdateInput, WithOptional } from 'kapix-graphql-prisma-client-type'
import { defineModel } from 'kapix-graphql-prisma-client'
import { graphqlRequest } from '~/graphql'


export const entitiesModels = defineModel({
  name: 'YouCanPutANameHere',
  requestHandler: graphqlRequest
}, ({ entity, types, queryMode }) => ({
  user: entity.define(entity.name<Kapix.Entity.IUser, IUser, IUserWhereUniqueInput, IUserCreateInput, IUserUpdateInput>('user'), {
    fields: {
      id: types.string().uuid({
        required: true,
        isPk: true
      }),
      posts: entity.relation({
        isList: true,
        mode: `lazy`,
        entityName: `post`,
        targetProperty: `user`
      })
    },
    endpoints: {
      user: queryMode.Get,
      users: queryMode.List,
      count: queryMode.Count,
      createOneUser: queryMode.CreateOne,
      updateOneUser: queryMode.UpdateOne,
      deleteOneUser: queryMode.DeleteOne,
      createManyUser: queryMode.CreateMany,
      updateManyUser: queryMode.UpdateMany,
      deleteManyUser: queryMode.DeleteMany
    }
  }),
  post: entity.define(entity.name<Kapix.Entity.IPost, IPost, IPostWhereUniqueInput, IPostCreateInput, IPostUpdateInput>('post'), {
    fields: {
      id: entity.pks.number(),
      title: types.string().userName(),
      user: entity.relation({
        mode: `lazy`,
        targetProperty: `posts`,
        fks: [`userId`],
        required: true
      }),
      userId: entity.fks.string({
        fetchByDefault: false,
        targetProperty: `id`
      })
    },
    endpoints: {
      post: queryMode.Get,
      posts: queryMode.List,
      count: queryMode.Count,
      createOnePost: queryMode.CreateOne,
      updateOnePost: queryMode.UpdateOne,
      deleteOnePost: queryMode.DeleteOne,
      createManyPost: queryMode.CreateMany,
      updateManyPost: queryMode.UpdateMany,
      deleteManyPost: queryMode.DeleteMany
    }
  })
}))

export interface IUser extends Kapix.Entity.IUser {}
export interface IUserWhereUniqueInput {
  id?: string
}
export interface IUserCreateInput extends WithOptional<Omit<IUser, 'posts'>, 'id' > { posts?: NestedListCreateInput<Omit<IPostCreateInput, 'user' | 'userId'>, IPostWhereUniqueInput> }
export interface IUserUpdateInput extends Partial<Omit<IUser, 'posts'>> { posts?: NestedListUpdateInput<Omit<IPostUpdateInput, 'user' | 'userId'>, IPostCreateInput, IPostWhereUniqueInput> }
export interface IPost extends Kapix.Entity.IPost {}
export interface IPostWhereUniqueInput { id?: number }
export interface IPostCreateInput extends WithOptional<Omit<IPost, 'user'>, 'title' | 'id' | 'userId'> { user: NestedCreateInput<Omit<IUserCreateInput, 'posts'>, IUserWhereUniqueInput> }
export interface IPostUpdateInput extends Partial<Omit<IPost, 'user'>> { user?: NestedUpdateInput<Omit<IUserUpdateInput, 'posts'>, IUserCreateInput, IUserWhereUniqueInput> }

Queries

A simple query to get a post:

const fetchPost = await entitiesModels.Post.queries.post({
  where: {
    id: postId
  },
  select: { // optional
    ...entitiesModels.post.defaultSelect
  }
})

This will return the Post object you wanted, just as if you were writing:

`
query {
  post(
    where: {
      id: '${postId}'
    }
  ) {
    id
    title
  }
}
`

But now you have typescript to guide you.

Mutations

You can build a create input:

const postCreateInput = entitiesModels.post.factory.buildCreateInput({
  title: 'firstPost'
})

And then use it for your mutation:

const createdPost = await entitiesModels.post.mutations.createOnePost({
  data: postCreateInput,
  select: {
    ...entitiesModels.post.defaultSelect,
    userId: true,
    user: true
  }
})

This is the equivalent of:

`
mutation {
  createOnePost(
    data: {
      title: '${title}'
    }
  ) {
    id
    title
    userId
    user {
      id
    }
  }
}
`

And the same for every endpoint and entity you have described in your entitiesModel.

Mocking

There is also a built-in data mocking service with a pseudo local storage, that you can use to emulate a real server.

To activate the mocking service, simply put mockData: true in the defineService() function args.

There are multiple other options you can give to customize the mocking, that you can pass like so:

mockData: true,
config: {
  mock: {
    maxItems
    percentageOfNullWhenFieldNotRequired
    randNumberOfItemsOptions
    values
  }
}

An example that will create 10 Post objects that will exist in the pseudo local storage:

const rideOffers = await entitiesModels.post.factory.mockItems({
  id: true,
  title: true,
  user: {
    id: true
  }
}, {
  min: 10,
  max: 10
})

You can perform every action you want on these objects, as if it were a real server, so you can query and mutate on these created objects.

License

MIT License

Copyright (c) 2020-2022 Stephane LASOUR