@smartive/graphql-magic 15.4.0 → 16.0.0

package/docs/docs/1-tutorial.md

@@ -95,10 +95,10 @@ const nextConfig = {
 };
 ```
 
-Install `@smartive/graphql-magic`:
+Install `@smartive/graphql-magic` and needed dependencies:
 
 ```bash
-npm install @smartive/graphql-magic
+npm install @smartive/graphql-magic @graphql-codegen/typescript-compatibility
 ```
 
 Run the gqm cli:
@@ -123,7 +123,6 @@ services:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: password
       POSTGRES_HOST_AUTH_METHOD: trust
-      TZ: 'Europe/Zurich'
     ports:
       - '5432:5432'
 ```
@@ -213,14 +212,14 @@ Now let's implement the `// TODO: get user` part in the `src/graphql/execute.ts`
 ```ts
   const session = await getSession();
   if (session) {
-    let dbUser = await db('User').where({ authId: session.user.sid }).first();
+    let dbUser = await db('User').where({ authId: session.user.sub }).first();
     if (!user) {
       await db('User').insert({
         id: randomUUID(),
-        authId: session.user.sid,
+        authId: session.user.sub,
         username: session.user.nickname
       })
-      dbUser = await db('User').where({ authId: session.user.sid }).first();
+      dbUser = await db('User').where({ authId: session.user.sub }).first();
     }
     user = {
       ...dbUser!,
@@ -322,6 +321,7 @@ Let's make a blog out of this app by adding new models in `src/config/models.ts`
         updatable: true,
       }
     ]
+  }
 ```
 
 Generate and run the new migrations and generate the new models:

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

@@ -1,6 +1,6 @@
 # Graphql server
 
-## `executeQuery`
+## `executeGraphql`
 
 `graphql-magic` generates an `execute.ts` file for you, with this structure:
 
@@ -9,7 +9,6 @@ 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>(
@@ -32,7 +31,6 @@ export const executeGraphql = async <T, V = undefined>(
     user,
     models: models,
     permissions: { ADMIN: true, UNAUTHENTICATED: true },
-    now: DateTime.local(),
   });
   await db.destroy();
 

package/docs/docs/7-graphql-client.md

@@ -18,7 +18,7 @@ module.exports = {
 
 ### Server side
 
-On the server side, and with `next.js` server actions, a graphql api becomes unnecessary, and you can execute query directly using `executeQuery`:
+On the server side, and with `next.js` server actions, a graphql api becomes unnecessary, and you can execute queries directly using `executeGraphql`:
 
 ```tsx
 import { GetMeQuery, GetPostsQuery } from "@/generated/client";

package/docs/docs/8-permissions.md

@@ -0,0 +1,145 @@
+# Permissions
+
+Permissions are an object provided to the `execute` function.
+The root keys of the objects are the user roles (including the special role `UNAUTHENTICATED` for when the user object is undefined).
+
+```ts
+execute({
+    ...
+    user: {
+        // ...
+        role: 'USER' // this is the role that will apply
+    },
+    permissions: {
+        ADMIN: ... // admin permissions
+        USER: ... // user permissions
+        UNAUTHENTICATED: ... // permissions for unauthenticated users
+    }
+})
+```
+
+## Grant all permissions
+
+```ts
+ADMIN: true
+```
+
+## Actions
+
+- READ
+- CREATE
+- UPDATE
+- DELETE
+- RESTORE
+- LINK
+
+Grant all READ permissions on a specific table:
+
+```ts
+User: {} // same as User: { READ: true }
+```
+
+Grant actions other than READ on a specific table:
+
+```ts
+User: { CREATE: true }
+```
+
+## Linking
+
+The LINK permission doesn't give one permission to modify these records,
+but to use them as options for foreign keys in _other_ records that one does have the permission to CREATE/UPDATE.
+
+So, for example, if you want a manager to be able to assign a user to a task, you would model it like this:
+
+```ts
+MANAGER: {
+  User: { LINK: true }
+  Task: { UPDATE: true }
+}
+```
+
+## Narrowing the record set
+
+Use WHERE, which accepts simple table column/value pairs that are then used as sql where filter.
+
+```ts
+GUEST: {
+  Post: {
+    WHERE: { published: true }
+  }
+}
+```
+
+## Derivative permissions
+
+In the following way you can define permissions that follow the relational structure.
+
+"If I can read a board (because it is public), then I can follow all threads and their authors, and their replies, which I can like."
+
+```ts
+GUEST: {
+  Board: {
+    WHERE: { public: true }
+    RELATIONS: {
+      threads: {
+        RELATIONS: {
+          LINK: true,
+          author: {},
+          replies: {
+            CREATE: true,
+            LINK: true,
+            likes: {
+              CREATE: true
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Me
+
+You can use `me` as a special `User` record set containing just yourself.
+
+```ts
+EMPLOYEE: {
+  me: {
+    UPDATE: true,
+    LINK: true,
+    RELATIONS: {
+      tasks: {
+        UPDATE: true
+      }
+    }
+  }
+}
+```
+
+Note: for ownership patterns (I own what I create, I can update what I own),
+one must use implicitly generated relationships such as `createdPosts`, `updatedPosts`, `deletedPosts`:
+
+```ts
+GUEST: {
+  me: {
+    LINK: true,
+    RELATIONS: {
+      createdPosts: {
+        // "guests can create a post with the field createdBy === me"
+        CREATE: true,
+        UPDATE: true
+      },
+      updatedPosts: {
+        // this is necessary or it won't be possible to create a post
+        // "guests can create a post with the field updatedBy === me"
+        CREATE: true
+
+        // this is *not* necessary because the user can already update posts they created
+        // UPDATE: true
+      }
+    }
+  }
+}
+```