@smartive/graphql-magic 15.3.1 → 15.4.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
-## [15.3.1](https://github.com/smartive/graphql-magic/compare/v15.3.0...v15.3.1) (2024-04-04)
+# [15.4.0](https://github.com/smartive/graphql-magic/compare/v15.3.1...v15.4.0) (2024-04-04)
 
 
-### Bug Fixes
+### Features
 
-* **deps:** update docusaurus monorepo to v3.2.0 ([485e127](https://github.com/smartive/graphql-magic/commit/485e127761189bf0c104e6d0a90115d3d21e6c0c))
+* Docs! ([67446c8](https://github.com/smartive/graphql-magic/commit/67446c8a318a851ad86c37d34dca3633962a2b83))

package/docs/docs/1-tutorial.md

@@ -9,7 +9,7 @@ Let's create a blog with `graphql-magic`!
 First create a `next.js` website:
 
 ```
-npx create-next-app@latest magic-blog --ts --app --tailwind --eslint --src
+npx create-next-app@latest magic-blog --ts --app --tailwind --eslint --src-dir
 cd magic-blog
 ```
 

package/docs/docs/2-models.md

@@ -31,17 +31,17 @@ The most powerful model kind. Entities are models that are stored in database ta
 }
 ```
 
-These are the entity options
+These are the entity options:
 
-### description
+### `description`
 
-Will appear as graphql description
+Will appear as description in the graphql schema.
 
-### plural
+### `plural`
 
 `graphql-magic` detects natural language plurals of model names with the `inflection` npm package. You can override this here.
 
-### creatable
+### `creatable`
 
 When `creatable` is `true`, the entity can be created using a dedicated graphql `create<ModelName>` mutation.
 
@@ -49,7 +49,7 @@ For this to work, at least one entity field needs to be marked as `creatable`.
 
 `creatable` also accepts an object to override properties of the implicitly generated `createdBy` and `createdAt` fields.
 
-### updatable
+### `updatable`
 
 When `updatable` is `true`, the entity can be created using a dedicated graphql `delete<ModelName>` mutation.
 
@@ -59,7 +59,7 @@ For this to work, at least one entity field needs to be marked as `updatable`.
 
 If a field is updatable, a `<ModelName>Revisions` table is created (containing only the updatable fields) and extended with each update.
 
-### deletable
+### `deletable`
 
 When `deletable` is `true`, the entity can be created using a dedicated graphql `delete<ModelName>` mutation.
 
@@ -67,7 +67,7 @@ This is a soft delete (the `deleted` field is set to `true`), and the entity can
 
 `deletable` also accepts an object to override properties of the implicitly generated `deleted`, `deletedBy` and `deletedAt` fields.
 
-### queriable
+### `queriable`
 
 When `queriable` is `true` a graphql `Query` becomes available to fetch exactly one element by id.
 
@@ -92,7 +92,7 @@ query {
 }
 ```
 
-### listQueriable
+### `listQueriable`
 
 When `listQueriable` is `true` a graphql `Query` becomes available to fetch a list of elements of this model.
 
@@ -117,20 +117,19 @@ query {
 }
 ```
 
-### displayField
+### `displayField`
 
 The name of the field that ought to be used as display value, e.g. a `Post`'s `title`.
 
-### defaultOrderBy
+### `defaultOrderBy`
 
 An array of orders with the same structure as the `orderBy` parameters in graphql queries. The implicit default order by is `[{ createdAt: 'DESC }]`.
 
-### fields
+### `fields`
 
-An array of fields. See [fields](./fields.md)
+An array of fields. See [fields](./fields)
 
-
-## Scalar
+## Scalars
 
 Used for graphql scalars, e.g.
 
@@ -141,7 +140,7 @@ Used for graphql scalars, e.g.
 }
 ```
 
-## Enum
+## Enums
 
 An enum that is available as type in the database:
 
@@ -153,7 +152,7 @@ An enum that is available as type in the database:
 }
 ```
 
-## Raw enum
+## Raw enums
 
 An enum that is *not* available as type in the database:
 
@@ -165,7 +164,7 @@ An enum that is *not* available as type in the database:
 }
 ```
 
-## Interface
+## Interfaces
 
 Types that can be inherited from, e.g.
 
@@ -193,7 +192,7 @@ Types that can be inherited from, e.g.
 }
 ```
 
-## Object
+## Objects
 
 Custom types that *don't* correspond to database tables. To be used e.g. as return types for custom resolvers or JSON fields. These can also be used to extend `Query` or `Mutation` which are themselves of that type. E.g.
 
@@ -237,7 +236,7 @@ query {
 }
 ```
 
-## Input
+## Inputs
 
 A custom input type. To be combined with custom mutations, e.g.
 

package/docs/docs/3-fields.md

@@ -1,10 +1,91 @@
 # Fields
 
-Note that some fields are generated implicitly, such as `id`, `createdAt`/`createdBy` if the model is creatable.
+Models of kind `'entity'`, `'object'`, `'interface'` (see the docs on [models](./models)) have an option called `fields`.
 
-## Fields of fields
+```ts
+const modelDefinitions: ModelDefinitions = [
+  {
+    kind: 'entity',
+    name: 'User',
+    fields: [
+        // Fields
+    ]
+  },
+]
+
+export const models = new Models(modelDefinitions)
+```
+
+## Kinds
+
+Fields can have various kinds, based on the field `kind`:
+
+### Primitive fields
+
+Primitive fields are fields where `kind` is either undefined or set to `'primitive'`. They can have the following `type`:
+
+* `ID`
+* `Boolean`
+* `String` with optional fields `stringType` and `maxLength`
+* `Int` with optional fields `intType`
+* `Float` with optional fields `floatType`, `double`, `precision`, `scale`
+* `Upload`
+
+Examples:
+
+```ts
+{
+    name: 'Person',
+    fields: [
+        {
+            type: 'String',
+            name: 'name',
+        },
+        {
+            type: 'Int',
+            name: 'name',
+        }
+    ]
+}
+```
+
+### Enums
+
+When `kind` is `enum`. Requires as `type` the name of a separately defined model of kind `'enum'`. Has optional field `possibleValues` to allow only a subset of available values in mutations.
+
+### Custom
+
+When `kind` is `custom`. Requires as `type` the name of a separately defined model of kind `'object'`.
+
+If this is an entity field, `graphql-magic` will not try to fetch the result from the database and instead assume the presence of a custom resolver for this field and .
+
+### JSON
+
+This kind is only available in entity fields. When `kind` is `json`, `graphql-magic` assumes that this is a `json` column in the database and returns the data as is. The `type` needs be the name of a separately defined model of kind `object` that describes the structure of the `JSON`.
+
+### Relations
+
+This kind is only available in entity fields. When `kind` is `relation`, the field describes a link to an entity table. The `type` therefore needs to be the name of a model of kind `'entity'`.
+
+## Options
+
+Fields generally have the following options:
+
+### `kind`
+
+Fields can have various kinds, which affect other available options. Available kinds:
+
+* `undefined` or `'primitive'`
+* `'enum'`
+* `'custom'`
+* `'json'`
+* `'relation'`
 
-Fields generally have the following fields available for configuration:
+For more details, see section on [kinds](#kinds) below.
+
+### `type`
+
+This represents the graphql "return type", which can be a primitive or a separate model (depending on the [kind](#kinds)).
 
 ### `description`
 
@@ -244,50 +325,13 @@ If `true` this field will be available in the update mutation for the entity.
 
 Also accepts an object that defines a list of `roles` to restrict creation to specific roles.
 
-## Kinds of fields
-
-Primitive fields can have various kinds, based on the field `kind`:
-
-### Primitive fields
-
-Primitive fields are fields where `kind` is either undefined or set to `"primitive"`.
-
-Primitive fields can have various types based on the `type` field:
-
-* `ID`
-* `Boolean`
-* `String` with optional fields `stringType` and `maxLength`
-* `Int` with optional fields `intType`
-* `Float` with optional fields `floatType`, `double`, `precision`, `scale`
-* `Upload`
-
-### Enums
-
-When `kind` is `enum`. Requires as `type` the name of a separately defined model of kind `enum`. Has optional field `possibleValues` to allow only a subset of available values in mutations.
-
-### Custom
-
-When `kind` is `custom`. Requires as `type` the name of a separately defined model of kind `object`.
-
-If this is an entity field, `graphql-magic` will not try to fetch the result from the database and instead assume the presence of a custom resolver for this field and .
-
-### JSON
-
-This kind is only available in entity fields. When `kind` is `json`, `graphql-magic` assumes that this is a `json` column in the database and returns the data as is. The `type` needs be the name of a separately defined model of kind `object` that describes the structure of the `JSON`.
-
-### Relations
-
-This kind is only available in entity fields. When `kind` is `relation`, the field describes a link to an entity table. The `type` therefore needs to be the name of a model of kind `entity`.
-
-Relation fields accept the following fields:
-
-### toOne
+### `toOne`
 
-If `toOne` is `true` this marks a one-to-one relation, meaning that the reverse relation will not point to an array as is the default.
+Only available on relation fields. If `toOne` is `true` this marks a one-to-one relation, meaning that the reverse relation will not point to an array as is the default.
 
-### reverse
+### `reverse`
 
-`graphql-magic` automatically generates a name for the reverse relation, e.g. for a `Comment` pointing to `Post`:
+Only available on relation fiels. `graphql-magic` automatically generates a name for the reverse relation, e.g. for a `Comment` pointing to `Post`:
 
 ```ts
 {
@@ -304,6 +348,6 @@ If `toOne` is `true` this marks a one-to-one relation, meaning that the reverse
 
 the reverse relation will automatically be `Post.comments`. With `reverse` this name can be overridden.
 
-### onDelete
+### `onDelete`
 
-can be `"cascade"` (default) or `"set-null"`.
+Only available on relation fields. Can be `"cascade"` (default) or `"set-null"`.

package/docs/docs/4-generation.md

@@ -1,17 +1,10 @@
 # Code generation
 
-Whenever the models have been changed it is necessary generate code use the `graphql-magic` cli.
+`graphql-magic` generates a lot of utility code for you based on the models, in particular typescript types.
 
-This can be done directly with `npx gqm generate`. We recommend to create a `package.json` script and to always generate code after install (or with `npm run generate`):
+This can be done directly with `npx gqm generate`.
 
-```
-"scripts": {
-    "bootstrap": "npm ci && npm run generate",
-    "generate": "gqm generate"
-}
-```
-
-First-time this applies the following changes to the repo:
+During the first run, the tool applies the following changes to the repo:
 
 * Generate `.gqmrc.json` file.
 * Add local database connection variables to `.env` file.
@@ -23,9 +16,19 @@ First-time this applies the following changes to the repo:
 With each application, it generates the following files in the configured "generated" folder:
 
 * `schema.graphql` - the schema of the api, for reference
-* `models.json` - the final models object including generated fields such as "id"... for reference
+* `models.json` - the final models array, including generated fields such as "id","createdBy"... for reference
 * `api/index.ts` - the server-side model typescipt types
 * `client/index.ts` - the client-side typescript types for the provided queries
 * `client/mutations.ts` - standard mutation queries for all models
 * `db/index.ts` - types for data from/to the database
 * `db/knex.ts` - types to extend the `knex` query builder
+
+Whenever the models have been changed, it is necessary regenerate this code.
+It is recommended to create a `package.json` script and to always generate code after install (or with `npm run generate`):
+
+```
+"scripts": {
+    "bootstrap": "npm ci && npm run generate",
+    "generate": "gqm generate"
+}
+```

package/docs/docs/5-migrations.md

@@ -1,12 +1,16 @@
 # Migrations
 
-After changing the models, if you have an existing database running to compare the models with, you can generate a migration like this:
+Migrations are there to keep the database schema in sync with the models.
+
+## Generating migrations
+
+After changing the models with database-relevant changes (and after initial setup), you'll need to have an existing database running to compare the models with, then generate a migration like this:
 
 ```
 npx gqm generate-migration
 ```
 
-We recommend creating a `package.json` script for this:
+It is recommended to create a `package.json` script for this:
 
 ```
 "generate-migration": "gqm generate-migration"
@@ -14,15 +18,19 @@ We recommend creating a `package.json` script for this:
 
 Note: if you are in a `feat/<feature-name>` branch, the script will use that as name for the migration.
 
-This will generate a migration in the `migrations` folder. Check whether it needs to be adapted.
+This will generate a migration file in the `migrations` folder (without running the migration itself yet). Check whether it needs to be adapted.
+
+## Running migrations
+
+Migrations themselves are managed with `knex` (see the [knex migration docs](https://knexjs.org/guide/migrations.html)). 
 
-You can then run it with `knex` migration commands (using `env-cmd` to add db connection variables in `.env`):
+For example, to migrate to the latest version (using `env-cmd` to add db connection variables in `.env`):
 
 ```
 npx env-cmd knex migrate:latest
 ```
 
-We recommend creating a `package.json` script and always running it before starting the development server.
+It is recommended to create a `package.json` script and always running it before starting the development server.
 
 ```
 "migrate: "env-cmd knex migrate:latest"

package/docs/docs/6-graphql-server.md

@@ -0,0 +1,242 @@
+# Graphql server
+
+## `executeQuery`
+
+`graphql-magic` generates an `execute.ts` file for you, with this structure:
+
+```ts
+import knexConfig from "@/knexfile";
+import { Context, User, execute } from "@smartive/graphql-magic";
+import { randomUUID } from "crypto";
+import { knex } from 'knex';
+import { DateTime } from "luxon";
+import { models } from "../config/models";
+
+export const executeGraphql = async <T, V = undefined>(
+  body: {
+    query: string;
+    operationName?: string;
+    variables?: V;
+    options?: { email?: string };
+}): Promise<{ data: T }> => {
+  const db = knex(knexConfig);
+  let user: User | undefined;
+  // TODO: get user
+
+  const result = await execute({
+    req: null as unknown as Context['req'],
+    body,
+    knex: db as unknown as Context['knex'],
+    locale: 'en',
+    locales: ['en'],
+    user,
+    models: models,
+    permissions: { ADMIN: true, UNAUTHENTICATED: true },
+    now: DateTime.local(),
+  });
+  await db.destroy();
+
+  // https://github.com/vercel/next.js/issues/47447#issuecomment-1500371732
+  return JSON.parse(JSON.stringify(result)) as { data: T };
+}
+```
+
+This is where you can set up your graphql server with
+
+* user authentication (see the [Tutorial](./tutorial) for an example with auth0)
+* custom resolvers (see [Custom resolvers](#custom-resolvers))
+* mutation hooks (see [Mutation hooks](#mutation-hooks))
+
+## Graphql API
+
+If you only need to execute graphql on the server (e.g. on `next.js` server components or server actions), you don't need a graphql endpoint.
+If you need client side querying, use `executeGraphql` to create a graphql endpoint, e.g. in `src/app/api/graphql/route.ts`:
+
+```ts
+export const POST = (req) => {
+    return await executeGraphql(req.body)
+}
+```
+
+## Custom resolvers
+
+Sometimes you'll need a custom resolver, at the level of root queries, mutations or existing models. For that you need to create a `additionalResolvers` object.
+
+```ts
+export const additionalResolvers = {
+    // custom resolvers go here
+}
+```
+
+Then feed it to `graphql-magic`'s `execute` function:
+
+```ts
+const result = await execute({
+    ...
+    additionalResolvers
+})
+```
+
+### Custom queries
+
+For that you'll need to extend the `Query` model (and define any needed additional models), e.g.:
+
+```ts
+{
+    kind: 'object',
+    name: 'Stats',
+    fields: [
+        {
+            name: 'usersCount'
+            type: 'Int'
+        },
+        {
+            name: 'postsCount',
+            type: 'Int'
+        }
+    ]
+},
+{
+    kind: 'object',
+    name: 'Query',
+    fields: [
+        // You'll need to define a custom resolver for this one
+        {
+            kind: 'custom',
+            name: 'stats',
+            type: 'Stats'
+        }
+    ]
+}
+```
+
+then implement the custom resolver as usual:
+
+```ts
+const additionalResolvers = {
+    Query: {
+        stats: (parent, args, ctx, schema) => {
+            // Implement custom resolver here
+        }
+    }
+}
+```
+
+### Custom mutations
+
+For that you'll need to extend the `Mutation` model (and define any needed additional models), e.g.:
+
+```ts
+{
+    kind: 'input',
+    name: 'BulkDeleteWhereInput'
+    fields: [
+        {
+            kind: 'ID',
+            name: 'ids',
+            list: true
+        }
+    ]
+},
+{
+    kind: 'object',
+    name: 'Mutation',
+    fields: [
+        // You'll need to define a custom resolver for this one
+        {
+            kind: 'custom',
+            name: 'bulkDelete',
+            args: [
+                {
+                    kind: 'custom',
+                    name: 'where',
+                    type: 'BulkDeleteWhereInput'
+                }
+            ]
+            type: 'Boolean'
+        }
+    ]
+}
+```
+
+then implement the custom resolver as usual:
+
+```ts
+const additionalResolvers = {
+    Mutation: {
+        bulkDelete: (parent, args, ctx, schema) => {
+            // Implement custom resolver here
+        }
+    }
+}
+```
+
+### Custom model resolvers
+
+Sometimes you need to add a custom field to an existing model. For that, add a field of `kind: 'custom'` to the model.
+
+```ts
+{
+    kind: 'entity',
+    name: 'User',
+    fields: [
+        // ...
+        {
+            kind: 'custom',
+            name: 'isAdmin',
+            type: 'Boolean'
+        }
+    ]
+}
+```
+
+
+then implement the custom resolver as usual:
+
+```ts
+const additionalResolvers = {
+    User: {
+        isAdmin: (parent, args, ctx, schema) => {
+            // Implement custom resolver here
+        }
+    }
+}
+```
+
+## Mutation hooks
+
+Sometimes you'll need some custom handling of mutations, before or after the change is committed to the database (e.g. for special data validation, or triggering cleanup work).
+
+For this we can implement a global `mutationHook` function that will be called for all mutations with parameters describing the context:
+
+```ts
+import { MutationHook } from '@smartive/graphql-magic';
+
+export const mutationHook: MutationHook = (model, action, when, data: { prev, input, normalizedInput, next }, ctx) => {
+    switch (model.name) {
+        // perform model specific tasks
+    }
+
+    // perform global tasks
+}
+```
+
+Then feed it to `graphql-magic`'s `execute` function:
+
+```ts
+const result = await execute({
+    ...
+    mutationHook
+})
+```
+
+The mutation hook function takes the following arguments:
+
+* `model` the model for the entity being mutated
+* `action`: can be `'create'`, `'update'`, `'delete'` or `'restore'`
+* `when`: either `"before"` or `"after"` the mutation is committed to the database
+* `data` containing the entity in various states:
+    * `prev`: the previous entity (undefined in creation mutations)
+    * `input`: input from the user
+    * `normalizedInput`: input to feed to the database (e.g. including generated values such as `id`, `createdAt`...)
+    * `next`: the full next entity after changes are applied

package/docs/docs/{6-graphql.md → 7-graphql-client.md}

@@ -14,59 +14,60 @@ module.exports = {
 };
 ```
 
-## `executeQuery`
+## Querying mechanisms
 
-`graphql-magic` generates an `executeQuery` function for you, which you can adapt to your needs.
+### Server side
 
-It handles things such as:
+On the server side, and with `next.js` server actions, a graphql api becomes unnecessary, and you can execute query directly using `executeQuery`:
 
-* user authentication (see the [Tutorial](./tutorial) for an example with auth0)
-* custom resolvers (see [Custom resolvers](./custom-resolvers))
-* mutation hooks (see [Mutation hooks](./mutation-hooks))
-
-TODO
-
-
-## Queries
+```tsx
+import { GetMeQuery, GetPostsQuery } from "@/generated/client";
+import { GET_POSTS } from "@/graphql/client/queries/get-posts";
+import { executeGraphql } from "@/graphql/execute";
 
-Typically, you'll put graphql queries in `src/graphql/client/queries`, e.g. `get-posts.ts`
+async function Posts({ me }: { me: GetMeQuery['me'] }) {
+  const { data: { posts } } = await executeGraphql<GetPostsQuery>({ query: GET_POSTS })
 
-```ts
-import { gql } from '@smartive/graphql-magic';
-
-export const GET_POSTS = gql`
-  query GetPosts {
-    posts {
-        id
-        title
-        content
-        createdBy {
-            username
-        }
-        comments {
-            id
-            createdBy {
-                username
-            }
-            content
-        }
-    }
-  }
-`;
+  return <div>
+    {posts.map(post => <div key={post.id}>
+      <article>
+        <h2>{post.title}</h2>
+        <div>by {post.createdBy.username}</div>
+        <p>{post.content}</p>
+        <h4>Comments</h4>
+        {post.comments.map(comment => (<div key={comment.id}>
+          <div>{comment.createdBy.username}</div>
+          <p>{comment.content}</p> by {comment.createdBy.username}
+        </div>)
+        )}
+      </article>
+    </div>)}
+  </div>
+}
 ```
 
-The query can then be used like so:
+### Client side
+
+On the client, you'd need to set up a graphql endpoint and then query it like any other graphql api, such as with [`@apollo/client`](https://www.apollographql.com/docs/react/get-started).
 
 ```tsx
 import { GetMeQuery, GetPostsQuery } from "@/generated/client";
 import { GET_POSTS } from "@/graphql/client/queries/get-posts";
 import { executeGraphql } from "@/graphql/execute";
+import { gql, useQuery } from '@apollo/client';
 
-async function Posts({ me }: { me: GetMeQuery['me'] }) {
-  const { data: { posts } } = await executeGraphql<GetPostsQuery>({ query: GET_POSTS })
+function Posts({ me }: { me: GetMeQuery['me'] }) {
+  const { loading, error, data } = useQuery<GetPostsQuery>({ query: GET_POSTS })
+
+  if (loading) {
+    return 'Loading...';
+  }
+  if (error) {
+    return `Error! ${error.message}`;
+  }
 
   return <div>
-    {posts.map(post => <div key={post.id}>
+    {res?.data?.posts.map(post => <div key={post.id}>
       <article>
         <h2>{post.title}</h2>
         <div>by {post.createdBy.username}</div>
@@ -83,11 +84,31 @@ async function Posts({ me }: { me: GetMeQuery['me'] }) {
 }
 ```
 
-Client-side: TODO
-
 ## Mutations
 
-Mutation queries are generated by `graphql-magic` directly so you don't need to write them. Use like this:
+Mutation queries are generated by `graphql-magic` directly so you don't need to write them. They have a very simple structure:
+
+```ts
+export const CREATE_POST = gql`
+  mutation CreatePostMutation($data: CreatePost!) {
+    createPost(data: $data) { id }
+  }
+`;
+
+export const UPDATE_POST = gql`
+  mutation UpdatePostMutation($id: ID!, $data: UpdatePost!) {
+    updatePost(where: { id: $id }, data: $data) { id }
+  }
+`;
+
+export const DELETE_POST = gql`
+  mutation DeletePostMutation($id: ID!) {
+    deletePost(where: { id: $id })
+  }
+`;
+```
+
+Use like this:
 
 ```tsx
 import { CreatePostMutationMutation, CreatePostMutationMutationVariables } from "@/generated/client";
@@ -127,4 +148,4 @@ async function CreatePost() {
 }
 ```
 
-Client-side: TODO
+Just like with queries, if is necessary to perform mutations on the client, use a graphql client instead of `executeGraphql`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartive/graphql-magic",
-  "version": "15.3.1",
+  "version": "15.4.0",
   "description": "",
   "source": "src/index.ts",
   "type": "module",

package/docs/docs/7-custom-resolvers.md

@@ -1,3 +0,0 @@
-# Custom resolvers (TODO)
-
-TODO

package/docs/docs/8-mutation-hooks.md

@@ -1,3 +0,0 @@
-# Hooks (TODO)
-
-TODO