style: better readme and removed examples spaghetti code

carlocorradini · Oct 12, 2022 · a1663c9 · a1663c9
1 parent 96c97d5
commit a1663c9
Show file tree

Hide file tree

Showing 28 changed files with 138 additions and 468 deletions.
diff --git a/README.md b/README.md
@@ -33,49 +33,40 @@ yarn add graphql-auth-directive
 
 > See [examples](./examples) directory
 
-1. Add `@auth` directive to schema:
+1. Add `@auth` directive to *GraphQL* schema:
 
-   > See [Positioning](#positioning) for allowed positions
+   > `on OBJECT | FIELD | FIELD_DEFINITION`
 
    ```graphql
-   # Authentication required
-   @auth
-
-   # ADMIN Enum role required
-   @auth(roles: [ADMIN])
-
-   # ADMIN or MODERATOR Enum role required
-   @auth(roles: [ADMIN, MODERATOR])
-
-   # "ADMIN" String role required
-   @auth(roles: ["ADMIN"])
-
-   # "ADMIN" or "MODERATOR" String role required
-   @auth(roles: ["ADMIN", "MODERATOR"])
-
-   # READ_POST Enum permission required
-   @auth(permissions: [READ_POST])
-
-   # READ_POST or EDIT_POST Enum permission required
-   @auth(roles: [READ_POST, EDIT_POST])
-
-   # READ_POST String permission required
-   @auth(permissions: ["READ_POST"])
-
-   # READ_POST or EDIT_POST String permission required
-   @auth(permissions: ["READ_POST", "EDIT_POST"])
-
-   # ADMIN Enum role and EDIT_POST Enum permission required
-   @auth(roles: [ADMIN], permissions: [EDIT_POST])
-
-   # ADMIN String role and EDIT_POST String permission required
-   @auth(roles: ["ADMIN"], permissions: ["EDIT_POST"])
+   type Example @auth {
+    unprotected: String!
+    adminProtected: String! @auth(roles: [ADMIN])
+   }
+
+   type Query {
+    unprotected: String!
+    protected: String! @auth
+    adminRoleProtected: String! @auth(roles: [ADMIN])
+    adminOrModeratorRolesProtected: String! @auth(roles: [ADMIN, MODERATOR])
+    viewPermissionProtected: String! @auth(permissions: [VIEW])
+    viewOrEditPermissionsProtected: String! @auth(permissions: [VIEW, EDIT])
+    roleAndPermissionProtected: String! @auth(roles: [ADMIN], permissions: [VIEW])
+    # ...
+   }
+
+   type Mutation {
+    # Same as Query
+   }
+
+   type Subscription {
+    # Same as Query
+   }
    ```
 
-1. Create a custom `auth` function:
+1. Define a custom `auth` function:
 
    > Class based `auth` is also possible leveraging Dependency Injection (DI) mechanism. \
-   >  Create a class that implements `AuthFnClass<Context>` interface.
+   >  Define a class that implements `AuthFnClass<Context>` interface.
 
    ```ts
    import type { AuthFn } from 'graphql-auth-directive';
@@ -155,40 +146,14 @@ yarn add graphql-auth-directive
 | Name                  | Type                                           | Default Value                              | Description                                                                                                                                               |
 | --------------------- | ---------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `name`                | `string`                                       | `auth`                                     | Directive name.                                                                                                                                           |
-| `auth`                | `Auth<TContext>`                               |                                            | Auth function (`AuthFn<TContext>`) or class (`AuthFnClass<TContext>`).                                                                                    |
+| `auth`                | `Auth<TContext, TRole, TPermission>`                               |                                            | Auth function (`AuthFn<TContext, TRole, TPermission>`) or class (`AuthFnClass<TContext, TRole, TPermission>`).                                                                                    |
 | `authMode`            | `'ERROR' \| 'NULL'`                            | `ERROR`                                    | Auth mode if access is not granted. `ERROR` throws an error. `NULL` returns `null`.                                                                       |
 | `roles`               | `{ typeName?: string, defaultValue?: string }` | `{ typeName: 'String', defaultValue: '' }` | Roles configuration. `typeName` is the type name of `roles` array. `defaultValue` is the default value, an empty value is equivalent to `[]`.             |
 | `permissions`         | `{ typeName?: string, defaultValue?: string }` | `{ typeName: 'String', defaultValue: '' }` | Permissions configuration. `typeName` is the type name of `permissions` array. `defaultValue` is the default value, an empty value is equivalent to `[]`. |
 | `authenticationError` | `ClassTypeEmptyConstructor<Error>`             | `AuthenticationError`                      | Authentication error class. An error class must extends `Error`.                                                                                          |
 | `authorizationError`  | `ClassTypeEmptyConstructor<Error>`             | `AuthorizationError`                       | Authorization error class. An error class must extends `Error`.                                                                                           |
 | `container`           | `ContainerType`                                | `IOCContainer`                             | Dependency injection container.                                                                                                                           |
 
-### Positioning
-
-> `on OBJECT | FIELD | FIELD_DEFINITION`
-
-```graphql
-type Protected @auth {
-  unprotected: String!
-}
-
-type ProtectedField {
-  protected: String! @auth
-}
-
-type Query {
-  protected: String! @auth
-}
-
-type Mutation {
-  protected: String! @auth
-}
-
-type Subscription {
-  protected: String! @auth
-}
-```
-
 ## Integrations
 
 ### [TypeGraphQL](https://github.com/MichalLytek/type-graphql)

diff --git a/examples/README.md b/examples/README.md
@@ -1,13 +1,13 @@
 # Examples
 
+Every example outputs an authorization token that can be used for `@auth` resources. Remember to add the token in the header: `Authorization: Bearer <TOKEN>`
+
 Build examples:
 
 ```console
 npx tsc --build tsconfig.json
 ```
 
-Every example outputs an authorization token that can be used for `@auth` resources. Remember to add the token in the header: `Authorization: Bearer <TOKEN>`
-
 ## Simple
 
 ```console

diff --git a/examples/simple/Context.ts → examples/__commons/Context.ts b/examples/simple/Context.ts → examples/__commons/Context.ts
diff --git a/examples/simple/Post.ts → examples/__commons/Post.ts b/examples/simple/Post.ts → examples/__commons/Post.ts
diff --git a/examples/simple/User.ts → examples/__commons/User.ts b/examples/simple/User.ts → examples/__commons/User.ts
diff --git a/examples/simple/UserPermissions.ts → examples/__commons/UserPermissions.ts b/examples/simple/UserPermissions.ts → examples/__commons/UserPermissions.ts
diff --git a/examples/simple/UserRoles.ts → examples/__commons/UserRoles.ts b/examples/simple/UserRoles.ts → examples/__commons/UserRoles.ts
diff --git a/examples/simple/authFn.ts → examples/__commons/authFn.ts b/examples/simple/authFn.ts → examples/__commons/authFn.ts
diff --git a/examples/simple/authFnClass.ts → examples/__commons/authFnClass.ts b/examples/simple/authFnClass.ts → examples/__commons/authFnClass.ts
@@ -35,7 +35,6 @@ import { authFn } from './authFn';
 export class AuthFnClass
   implements IAuthFnClass<Context, UserRoles, UserPermissions>
 {
-  // eslint-disable-next-line class-methods-use-this
   public auth(
     resolverData: ResolverData<Context>,
     authData: AuthData<UserRoles, UserPermissions>

diff --git a/examples/simple/contextHelper.ts → examples/__commons/contextHelper.ts b/examples/simple/contextHelper.ts → examples/__commons/contextHelper.ts
@@ -23,9 +23,9 @@
  */
 
 import type { ExpressContext } from 'apollo-server-express';
-import type { Context } from './Context';
-import { TokenPayload, verify } from './token';
 import { AuthenticationError } from '../../src';
+import type { Context } from './Context';
+import { TokenPayload, verifyToken } from './token';
 
 export async function contextHelper({ req }: ExpressContext): Promise<Context> {
   let user: TokenPayload | undefined;
@@ -45,7 +45,7 @@ export async function contextHelper({ req }: ExpressContext): Promise<Context> {
         const token = credentials;
 
         try {
-          const decodedToken = verify(token);
+          const decodedToken = verifyToken(token);
           user = decodedToken;
         } catch (error) {
           throw new AuthenticationError();

diff --git a/examples/typegraphql/data.ts → examples/__commons/db.ts b/examples/typegraphql/data.ts → examples/__commons/db.ts
@@ -26,15 +26,16 @@ import type { User } from './User';
 import type { Post } from './Post';
 import { UserPermissions } from './UserPermissions';
 import { UserRoles } from './UserRoles';
-import { sign } from './token';
+
+export const SUPER_USER: User = {
+  id: 0,
+  secret: true,
+  roles: [UserRoles.ADMIN],
+  permissions: [UserPermissions.DELETE_POST]
+};
 
 export const users: User[] = [
-  {
-    id: 0,
-    secret: true,
-    roles: [UserRoles.ADMIN],
-    permissions: [UserPermissions.DELETE_POST]
-  },
+  SUPER_USER,
   {
     id: 1,
     secret: false,
@@ -45,4 +46,24 @@ export const users: User[] = [
 
 export const posts: Post[] = [{ id: 0, content: 'Hello World!', creatorId: 1 }];
 
-export const TOKEN = sign(users[0]);
+export function addPost(content: string, creatorId: number): Post {
+  const newPost: Post = {
+    id: posts.length > 0 ? posts[posts.length - 1].id + 1 : 0,
+    content,
+    creatorId
+  };
+  posts.push(newPost);
+  return newPost;
+}
+
+export function removePost(id: number): Post | null {
+  const postIndex = posts.findIndex((p) => p.id === id);
+  let postDeleted: Post | null = null;
+
+  if (postIndex !== -1) {
+    postDeleted = posts[postIndex];
+    posts.splice(postIndex, 1);
+  }
+
+  return postDeleted;
+}
diff --git a/examples/typegraphql/UserPermissions.ts → examples/__commons/index.ts b/examples/typegraphql/UserPermissions.ts → examples/__commons/index.ts
@@ -22,12 +22,14 @@
  * SOFTWARE.
  */
 
-import { registerEnumType } from 'type-graphql';
-
-export enum UserPermissions {
-  DELETE_POST = 'DELETE_POST'
-}
-
-registerEnumType(UserPermissions, {
-  name: 'UserPermissions'
-});
+export * from './authFn';
+export * from './authFnClass';
+export * from './Context';
+export * from './contextHelper';
+export * from './db';
+export * from './main';
+export * from './Post';
+export * from './token';
+export * from './User';
+export * from './UserPermissions';
+export * from './UserRoles';
diff --git a/examples/simple/token.ts → examples/__commons/main.ts b/examples/simple/token.ts → examples/__commons/main.ts
@@ -22,17 +22,21 @@
  * SOFTWARE.
  */
 
-import jwt from 'jsonwebtoken';
-import type { User } from './User';
+import type { GraphQLSchema } from 'graphql';
+import { ApolloServer } from 'apollo-server';
+import { contextHelper } from './contextHelper';
+import { TOKEN } from './token';
 
-export type TokenPayload = Omit<User, 'secret'>;
+export async function main(schema: GraphQLSchema) {
+  const server = new ApolloServer({ schema, context: contextHelper });
 
-const SECRET = 'secret';
+  const serverInfo = await server.listen({
+    port: 8080,
+    host: '0.0.0.0'
+  });
 
-export function sign(payload: TokenPayload) {
-  return jwt.sign(payload, SECRET);
-}
-
-export function verify(token: string) {
-  return jwt.verify(token, SECRET) as TokenPayload;
+  // eslint-disable-next-line no-console
+  console.info(`TOKEN: ${TOKEN}`);
+  // eslint-disable-next-line no-console
+  console.info(`Server started at ${serverInfo.url}`);
 }
diff --git a/examples/typegraphql/token.ts → examples/__commons/token.ts b/examples/typegraphql/token.ts → examples/__commons/token.ts
@@ -24,15 +24,18 @@
 
 import jwt from 'jsonwebtoken';
 import type { User } from './User';
+import { SUPER_USER } from './db';
 
 export type TokenPayload = Omit<User, 'secret'>;
 
 const SECRET = 'secret';
 
-export function sign(payload: TokenPayload) {
+export function signToken(payload: TokenPayload) {
   return jwt.sign(payload, SECRET);
 }
 
-export function verify(token: string) {
+export function verifyToken(token: string) {
   return jwt.verify(token, SECRET) as TokenPayload;
 }
+
+export const TOKEN = signToken(SUPER_USER);
diff --git a/examples/simple/data.ts b/examples/simple/data.ts
diff --git a/examples/simple/index.ts b/examples/simple/index.ts
@@ -23,16 +23,16 @@
  */
 
 import { makeExecutableSchema } from '@graphql-tools/schema';
-import { ApolloServer } from 'apollo-server';
 import { buildAuthDirective } from '../../src';
+import {
+  authFn,
+  Context,
+  UserRoles,
+  UserPermissions,
+  main
+} from '../__commons';
 import { typeDefs } from './typeDefs';
 import { resolvers } from './resolvers';
-import { authFn } from './authFn';
-import { contextHelper } from './contextHelper';
-import { TOKEN } from './data';
-import type { Context } from './Context';
-import type { UserRoles } from './UserRoles';
-import type { UserPermissions } from './UserPermissions';
 
 // Build auth directive
 const authDirective = buildAuthDirective<Context, UserRoles, UserPermissions>({
@@ -49,19 +49,5 @@ let schema = makeExecutableSchema({
 });
 schema = authDirective.transformer(schema);
 
-// Build server
-const server = new ApolloServer({ schema, context: contextHelper });
-
-// Start server
-async function main() {
-  const serverInfo = await server.listen({
-    port: 8080,
-    host: '0.0.0.0'
-  });
-
-  // eslint-disable-next-line no-console
-  console.info(`TOKEN: ${TOKEN}`);
-  // eslint-disable-next-line no-console
-  console.info(`Server started at ${serverInfo.url}`);
-}
-main();
+// Main
+main(schema);