@smartive/graphql-magic 15.2.0 → 15.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
-# [15.2.0](https://github.com/smartive/graphql-magic/compare/v15.1.1...v15.2.0) (2024-04-03)
+# [15.3.0](https://github.com/smartive/graphql-magic/compare/v15.2.1...v15.3.0) (2024-04-03)
 
 
 ### Features
 
-* Finish tutorial ([c1b0a21](https://github.com/smartive/graphql-magic/commit/c1b0a215ed23773fd287cd5b5898f07f7c401af1))
+* Docs ([56d96ce](https://github.com/smartive/graphql-magic/commit/56d96ce14c44d486096f6695ebed38a6862c9129))

package/docs/docs/{tutorial.md → 1-tutorial.md}

@@ -1,7 +1,3 @@
----
-sidebar_position: 1
----
-
 # Tutorial
 
 Let's create a blog with `graphql-magic`!
@@ -17,9 +13,9 @@ npx create-next-app@latest magic-blog --ts --app --tailwind --eslint --src
 cd magic-blog
 ```
 
-Replace `app/globals.css`:
+Replace `src/app/globals.css`:
 
-```
+```css
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
@@ -69,9 +65,9 @@ label span {
 }
 ```
 
-Replace `app/page.tsx`:
+Replace `src/app/page.tsx`:
 
-```
+```tsx
 export default async function Home() {
     return <main>
       <nav>
@@ -83,7 +79,7 @@ export default async function Home() {
 
 Start the website:
 
-```
+```bash
 npm run dev
 ```
 
@@ -91,7 +87,7 @@ npm run dev
 
 Add this setting to `next.config.mjs`:
 
-```
+```ts
 const nextConfig = {
     experimental: {
         serverComponentsExternalPackages: ['knex'],
@@ -101,13 +97,13 @@ const nextConfig = {
 
 Install `@smartive/graphql-magic`:
 
-```
+```bash
 npm install @smartive/graphql-magic
 ```
 
 Run the gqm cli:
 
-```
+```bash
 npx gqm generate
 ```
 
@@ -116,7 +112,7 @@ npx gqm generate
 Let's boot a local database instance.
 Create the following `docker-compose.yml`:
 
-```
+```yml
 version: '3.4'
 services:
   postgres:
@@ -136,17 +132,17 @@ Then start it with `docker-compose up`.
 
 Generate the first migration:
 
-```
+```bash
 npx gqm generate-migration
 ```
 
-Enter "setup" as migration name. Or you could first create a `feat/setup` git branch, then it would use that name automatically.
+Enter a migration name, e.g. "setup".
 
 
 Run the migration
 
-```
-npx env-cmd knex migrate:up
+```bash
+npx env-cmd knex migrate:latest
 ```
 
 ### Auth setup
@@ -156,7 +152,7 @@ For example, follow [this tutorial](https://auth0.com/docs/quickstart/webapp/nex
 
 Assuming you used auth0, here's a bare-bones version of what `src/app/page.tsx` could look like:
 
-```
+```tsx
 import { getSession } from '@auth0/nextjs-auth0';
 
 export default async function Page() {
@@ -179,7 +175,7 @@ Now, we need to ensure that the user is stored in the database.
 
 First extend the user model in `src/config/models.ts` with the following fields:
 
-```
+```tsx
     fields: [
       {
         name: 'authId',
@@ -196,25 +192,25 @@ First extend the user model in `src/config/models.ts` with the following fields:
 
 The models have changed, generate the new types:
 
-```
+```bash
 npx gqm generate
 ```
 
 Generate the new migration:
 
-```
+```bash
 npx gqm generate-migration
 ```
 
 Edit the generated migration, then run it
 
-```
-npx env-cmd knex migrate:up
+```bash
+npx env-cmd knex migrate:latest
 ```
 
 Now let's implement the `// TODO: get user` part in the `src/graphql/execute.ts` file
 
-```
+```ts
   const session = await getSession();
   if (session) {
     let dbUser = await db('User').where({ authId: session.user.sid }).first();
@@ -235,7 +231,7 @@ Now let's implement the `// TODO: get user` part in the `src/graphql/execute.ts`
 
 Extend `src/graphql/client/queries/get-me.ts` to also fetch the user's username:
 
-```
+```ts
 import { gql } from '@smartive/graphql-magic';
 
 export const GET_ME = gql`
@@ -250,13 +246,13 @@ export const GET_ME = gql`
 
 Generate the new types:
 
-```
+```bash
 npx gqm generate
 ```
 
 Now, let's modify `src/app/page.tsx` so that it fetches the user from the database:
 
-```
+```tsx
 import { GetMeQuery } from "@/generated/client";
 import { GET_ME } from "@/graphql/client/queries/get-me";
 import { executeGraphql } from "@/graphql/execute";
@@ -277,9 +273,9 @@ export default async function Home() {
 
 ### Content!
 
-Let's create a blog by adding new models in `src/config/models.ts`:
+Let's make a blog out of this app by adding new models in `src/config/models.ts`:
 
-```
+```ts
   {
     kind: 'entity',
     name: 'Post',
@@ -330,15 +326,14 @@ Let's create a blog by adding new models in `src/config/models.ts`:
 
 Generate and run the new migrations and generate the new models:
 
-```
+```bash
 npx gqm generate-migration
-npx env-cmd knex migrate:up
-npx gqm generate
+npx env-cmd knex migrate:latest
 ```
 
 Create a new query `src/graphql/client/queries/get-posts.ts`:
 
-```
+```ts
 import { gql } from '@smartive/graphql-magic';
 
 export const GET_POSTS = gql`
@@ -362,10 +357,16 @@ export const GET_POSTS = gql`
 `;
 ```
 
+Generate the new types:
+
+```bash
+npx gqm generate
+```
+
 Now add all the logic to create and display posts and comments to `src/app/page.tsx`
 
 
-```
+```tsx
 import { CreateCommentMutationMutation, CreateCommentMutationMutationVariables, CreatePostMutationMutation, CreatePostMutationMutationVariables, GetMeQuery, GetPostsQuery } from "@/generated/client";
 import { CREATE_COMMENT, CREATE_POST } from "@/generated/client/mutations";
 import { GET_ME } from "@/graphql/client/queries/get-me";

package/docs/docs/10-admin-ui.md

@@ -0,0 +1,3 @@
+# Admin UI (TODO)
+
+TODO

package/docs/docs/2-models.md

@@ -0,0 +1,283 @@
+# Models
+
+The source of truth for `graphql-magic` is the `models` object, usually defined in `src/config/models.ts`. This is the minimal models:
+
+```ts
+const modelDefinitions: ModelDefinitions = [
+  {
+    kind: 'entity',
+    name: 'User',
+    fields: [
+    ]
+  },
+]
+
+export const models = new Models(modelDefinitions)
+```
+
+Models can have the following kinds:
+
+## Entities
+
+The most powerful model kind. Entities are models that are stored in database tables, and are defined with `kind: 'entity'`:
+
+```ts
+{
+    kind: 'entity',
+    name: 'Post',
+    fields: [
+        // ...
+    ]
+}
+```
+
+These are the entity options
+
+### description
+
+Will appear as graphql description
+
+### plural
+
+`graphql-magic` detects natural language plurals of model names with the `inflection` npm package. You can override this here.
+
+### creatable
+
+When `creatable` is `true`, the entity can be created using a dedicated graphql `create<ModelName>` mutation.
+
+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
+
+When `updatable` is `true`, the entity can be created using a dedicated graphql `delete<ModelName>` mutation.
+
+For this to work, at least one entity field needs to be marked as `updatable`.
+
+`updatable` also accepts an object to override properties of the implicitly generated `updatedBy` and `updatedAt` fields.
+
+If a field is updatable, a `<ModelName>Revisions` table is created (containing only the updatable fields) and extended with each update.
+
+### deletable
+
+When `deletable` is `true`, the entity can be created using a dedicated graphql `delete<ModelName>` mutation.
+
+This is a soft delete (the `deleted` field is set to `true`), and the entity can be restored with the graphql `restore<ModelName>` mutation.
+
+`deletable` also accepts an object to override properties of the implicitly generated `deleted`, `deletedBy` and `deletedAt` fields.
+
+### queriable
+
+When `queriable` is `true` a graphql `Query` becomes available to fetch exactly one element by id.
+
+For example, with
+
+```ts
+{
+    kind: 'entity',
+    name: 'Post',
+    queriable: true
+    ...
+}
+```
+
+the following graphql query becomes possible
+
+```graphql
+query {
+    post(where: { id: "bf9496bb-9302-4528-aebc-c97ae49c52fa"}) {
+        title
+    }
+}
+```
+
+### listQueriable
+
+When `listQueriable` is `true` a graphql `Query` becomes available to fetch a list of elements of this model.
+
+For example, with
+
+```ts
+{
+    kind: 'entity',
+    name: 'Post',
+    listQueriable: true
+    ...
+}
+```
+
+the following graphql query becomes possible
+
+```graphql
+query {
+    posts {
+        title
+    }
+}
+```
+
+### displayField
+
+The name of the field that ought to be used as display value, e.g. a `Post`'s `title`.
+
+### 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
+
+An array of fields. See [fields](./fields.md)
+
+
+## Scalar
+
+Used for graphql scalars, e.g.
+
+```ts
+{
+    kind: 'Scalar',
+    name: 'DateTime'
+}
+```
+
+## Enum
+
+An enum that is available as type in the database:
+
+```ts
+{
+    kind: 'enum',
+    name: 'Role',
+    values: ['ADMIN', 'MODERATOR', 'USER']
+}
+```
+
+## Raw enum
+
+An enum that is *not* available as type in the database:
+
+```ts
+{
+    kind: 'raw-enum',
+    name: 'Role',
+    values: ['ADMIN', 'MODERATOR', 'USER']
+}
+```
+
+## Interface
+
+Types that can be inherited from, e.g.
+
+```ts
+{
+    kind: 'interface',
+    name: 'WithContent',
+    fields: [
+        {
+            type: 'String',
+            name: 'content'
+        }
+    ]
+},
+{
+    kind: 'entity',
+    name: 'Post',
+    interfaces: ['WithContent']
+    fields: [
+        {
+            type: 'String',
+            name: 'content'
+        }
+    ]
+}
+```
+
+## Object
+
+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.
+
+```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'
+        }
+    ]
+}
+```
+
+will make this query possible:
+
+```graphql
+query {
+    stats {
+        usersCount
+        postsCount
+    }
+}
+```
+
+## Input
+
+A custom input type. To be combined with custom mutations, 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'
+        }
+    ]
+}
+```
+
+will make this mutation possible:
+
+```graphql
+mutation {
+    bulkDelete(where: { ids: [...]})
+}
+```

package/docs/docs/3-fields.md

@@ -0,0 +1,309 @@
+# Fields
+
+Note that some fields are generated implicitly, such as `id`, `createdAt`/`createdBy` if the model is creatable.
+
+## Fields of fields
+
+Fields generally have the following fields available for configuration:
+
+### `description`
+
+Will appear as description in the graphql schema.
+
+### `list`
+
+If `list` is `true` the result is an array.
+
+### `nonNull`
+
+Will make the field required both in the graphql schema and in the database.
+
+### `defaultValue`
+
+Will set this as default value in graphql mutations and in the database.
+
+### `args`
+
+An array of fields that can then be used as parameters, e.g. if this field is implemented as a custom resolver.
+
+### `directives`
+
+Graphql directives for this field.
+
+### `primary`
+
+If `true` this will generate a primary key in the database.
+
+### `unique`
+
+If `true` this will generate a unique key in the database.
+
+### `filterable`
+
+If true, this field will be available in the `where` parameter for queries of this entity.
+
+E.g. with
+
+```ts
+{
+    name: 'Post',
+    fields: [
+        {
+            name: 'name',
+            type: 'String',
+            filterable: true
+        }
+    ]
+}
+```
+
+this becomes possible:
+
+```graphql
+query {
+    posts(where: { name: "Hello World" }) {
+        title
+    }
+}
+```
+
+With relations, this enables sub-filters, e.g. with
+
+```ts
+{
+    name: 'Comment',
+    fields: [
+        {
+            kind: 'relation',
+            name: 'post',
+            type: 'Post',
+            filterable: true
+        }
+    ]
+}
+```
+
+this becomes possible:
+
+```graphql
+query {
+    comments(where: { post: { name: "Hello World" } }) {
+        content
+    }
+}
+```
+
+
+### `reverseFilterable`
+
+Only relevant on relation fields. On `true` makes the reverse relation filterable.
+
+E.g. with
+
+```ts
+{
+    name: 'Comment',
+    fields: [
+        {
+            name: 'post',
+            type: 'String',
+            reverseFilterable: true
+        }
+    ]
+}
+```
+
+this becomes possible:
+
+```graphql
+query {
+    posts(where: { comments_SOME: { name: "Hello World" } }) {
+        title
+    }
+}
+```
+
+Available filter postfixes are `_SOME` and `_NONE`.
+
+### `searchable`
+
+On `true` makes the field searchable. Search always happens across all fields marked as searchable (only one has to match). Search is case insensitive.
+
+E.g. with
+
+```ts
+{
+    name: 'Post',
+    fields: [
+        {
+            name: 'title',
+            type: 'String',
+            searchable: true
+        },
+        {
+            name: 'content',
+            type: 'String',
+            searchable: true
+        }
+
+    ]
+}
+```
+
+this becomes possible:
+
+```graphql
+query {
+    posts(search: "Hello") {
+        title
+    }
+}
+```
+
+### `orderable`
+
+On `true` makes the field available to the `orderBy` parameter.
+
+E.g. with
+
+```ts
+{
+    name: 'Post',
+    fields: [
+        {
+            name: 'title',
+            type: 'String',
+            orderable: true
+        },
+    ]
+}
+```
+
+this becomes possible:
+
+```graphql
+query {
+    posts(orderBy: [{ title: DESC }]) {
+        title
+    }
+}
+```
+
+
+### `comparable`
+
+On `true` makes the field comparable.
+
+E.g. with
+
+```ts
+{
+    name: 'Post',
+    fields: [
+        {
+            name: 'rating',
+            type: 'Int',
+            comparable: true
+        },
+    ]
+}
+```
+
+this becomes possible:
+
+```graphql
+query {
+    posts(where: { rating_GTE 4 }) {
+        title
+    }
+}
+```
+
+Available postfixes are:
+
+* `_GT`: greater than
+* `_GTE`: greater than or equal
+* `_LT`: less than
+* `_LTE`: less than or equal
+
+### `queriable`
+
+`true` by default. If explicitly set to `false`, the field won't be queriable via graphql.
+
+Also accepts an object that defines a list of `roles` to restrict access to specific roles.
+
+### `creatable`
+
+If `true` this field will be available in the create mutation for the entity.
+
+Also accepts an object that defines a list of `roles` to restrict creation to specific roles.
+
+### `updatable`
+
+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
+
+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
+
+`graphql-magic` automatically generates a name for the reverse relation, e.g. for a `Comment` pointing to `Post`:
+
+```ts
+{
+    name: 'Comment',
+    fields: [
+        {
+            kind: 'relation',
+            name: 'post',
+            type: 'Post'
+        }
+    ]
+}
+```
+
+the reverse relation will automatically be `Post.comments`. With `reverse` this name can be overridden.
+
+### onDelete
+
+can be `"cascade"` (default) or `"set-null"`.

package/docs/docs/4-generation.md

@@ -0,0 +1,31 @@
+# Code generation
+
+Whenever the models have been changed it is necessary generate code use the `graphql-magic` cli.
+
+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`):
+
+```
+"scripts": {
+    "bootstrap": "npm ci && npm run generate",
+    "generate": "gqm generate"
+}
+```
+
+First-time this applies the following changes to the repo:
+
+* Generate `.gqmrc.json` file.
+* Add local database connection variables to `.env` file.
+* Add generated folder to `.gitignore`
+* Generate `models.ts` file (if not present).
+* Generate a basic `get-me.ts` example graphql query.
+* Generate the `execute.ts` file for the execution
+
+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
+* `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

package/docs/docs/5-migrations.md

@@ -0,0 +1,31 @@
+# Migrations
+
+After changing the models, if you have an existing database running to compare the models with, you can generate a migration like this:
+
+```
+npx gqm generate-migration
+```
+
+We recommend creating a `package.json` script for this:
+
+```
+"generate-migration": "gqm generate-migration"
+```
+
+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.
+
+You can then run it with `knex` migration commands (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.
+
+```
+"migrate: "env-cmd knex migrate:latest"
+"predev: "npm run migrate"
+"dev": "next dev"
+```

package/docs/docs/6-graphql.md

@@ -0,0 +1,130 @@
+# Graphql querying
+
+For autocompletion of your queries, you can create the following `apollo.config.js` file:
+
+```ts
+module.exports = {
+  client: {
+    service: {
+      name: 'your-project',
+      localSchemaFile: './src/generated/schema.graphql',
+    },
+    includes: ['./src/**/*.ts', './src/**/*.tsx'],
+  },
+};
+```
+
+## `executeQuery`
+
+`graphql-magic` generates an `executeQuery` function for you, which you can adapt to your needs.
+
+It handles things such as:
+
+* 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
+
+Typically, you'll put graphql queries in `src/graphql/client/queries`, e.g. `get-posts.ts`
+
+```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
+        }
+    }
+  }
+`;
+```
+
+The query can then be used like so:
+
+```tsx
+import { GetMeQuery, GetPostsQuery } from "@/generated/client";
+import { GET_POSTS } from "@/graphql/client/queries/get-posts";
+import { executeGraphql } from "@/graphql/execute";
+
+async function Posts({ me }: { me: GetMeQuery['me'] }) {
+  const { data: { posts } } = await executeGraphql<GetPostsQuery>({ query: GET_POSTS })
+
+  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>
+}
+```
+
+Client-side: TODO
+
+## Mutations
+
+Mutation queries are generated by `graphql-magic` directly so you don't need to write them. Use like this:
+
+```tsx
+import { CreatePostMutationMutation, CreatePostMutationMutationVariables } from "@/generated/client";
+import { CREATE_POST } from "@/generated/client/mutations";
+import { executeGraphql } from "@/graphql/execute";
+import { revalidatePath } from "next/cache";
+
+async function CreatePost() {
+  async function createPost(formData: FormData) {
+    'use server'
+    await executeGraphql<CreatePostMutationMutation, CreatePostMutationMutationVariables>({
+      query: CREATE_POST,
+      variables: {
+        data: {
+          title: formData.get('title') as string,
+          content: formData.get('content') as string
+        }
+      }
+    })
+    revalidatePath('/')
+  }
+
+  return <form action={createPost}>
+    <h2>New Post</h2>
+    <label>
+      <span>Title</span>
+      <input name="title" />
+    </label>
+    <label>
+      <span>Content</span>
+      <textarea rows={5} name="content" />
+    </label>
+    <div>
+      <button type="submit">Create</button>
+    </div>
+  </form>
+}
+```
+
+Client-side: TODO

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

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

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

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

package/docs/docs/9-polymorphism.md

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

package/package.json

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