@smartive/graphql-magic 15.2.1 → 15.3.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
-## [15.2.1](https://github.com/smartive/graphql-magic/compare/v15.2.0...v15.2.1) (2024-04-03)
+## [15.3.1](https://github.com/smartive/graphql-magic/compare/v15.3.0...v15.3.1) (2024-04-04)
 
 
 ### Bug Fixes
 
-* Finish intro ([4ecc445](https://github.com/smartive/graphql-magic/commit/4ecc44575901cbe731dca7b70f109da6eaa847ba))
+* **deps:** update docusaurus monorepo to v3.2.0 ([485e127](https://github.com/smartive/graphql-magic/commit/485e127761189bf0c104e6d0a90115d3d21e6c0c))

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

@@ -1,7 +1,3 @@
----
-sidebar_position: 1
----
-
 # Tutorial
 
 Let's create a blog with `graphql-magic`!
@@ -19,7 +15,7 @@ cd magic-blog
 
 Replace `src/app/globals.css`:
 
-```
+```css
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
@@ -71,7 +67,7 @@ label span {
 
 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,7 +132,7 @@ Then start it with `docker-compose up`.
 
 Generate the first migration:
 
-```
+```bash
 npx gqm generate-migration
 ```
 
@@ -145,8 +141,8 @@ 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";
@@ -279,7 +275,7 @@ export default async function Home() {
 
 Let's make a blog out of this app by adding new models in `src/config/models.ts`:
 
-```
+```ts
   {
     kind: 'entity',
     name: 'Post',
@@ -330,14 +326,14 @@ Let's make a blog out of this app 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 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`
@@ -363,14 +359,14 @@ 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: [...]})
+}
+```