@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/feature-api/feature-server/repositories.md

@@ -0,0 +1,114 @@
+---
+meta:
+    title: Repositories
+    description: Repositories
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Repositories...
+headers:
+    Cache-Control: no-cache
+---
+
+# Repositories
+
+Repositories are classes or components that encapsulate the logic required to access data sources. They centralize common data access functionality, providing better
+maintainability and decoupling the infrastructure or technology used to access databases from the domain model layer. If you use an Object-Document Mapper (ODM) like
+Mongoose, the code required to query or manipulate the documents is simplified. This lets you focus on the data persistence logic rather than on data access plumbing.
+
+For every document in our app, we'll have a respective repository against that document. Document shouldn't be fetched directly without `Repository` doing
+this will be considered `Anti Pattren` and should be avoided. All use cases related to how the app will `fetch` `manipulate` and `process`a document
+should reside inside the `Repository` of that respective document.
+
+All basic database operations which we normally need to perform on a `Document` like the basic CRUD operations are already defined inside the `BaseRepository` class.
+So you need to re-write the basic stuff and focus more on advance stuff. Each repository should extend the `BaseRepository` so it can
+benefit from all these pre cooked methods.
+
+The methods provided by `BaseRepositiry` are following
+
+```typescript
+export interface IBaseRepository<T, D = Document<T>> {
+    // Returns the total document count which fullfils the provided condition
+    count(conditions?: FilterQuery<D>): Promise<number>;
+
+    // Returns the list of documents which fullfils the provided condition (if any)
+    // Provides out of box paginaytion using `limit` and `skip` params
+    // sort attribute can be used to get sorted results
+    // selected fields takes a comma serperated strinh of fields name to be returned.
+    getAll(options: GetAllArgs<D>): Promise<T[]>;
+
+    // Returns single document
+    get(conditions?: FilterQuery<D>, selectedFields?: string): Promise<T>;
+
+    // Creates new document
+    create<I>(data: I): Promise<T>;
+
+    // Create/Update (If already exists) new document
+    upsert<I>(conditions: FilterQuery<D>, update: I, options: any): Promise<T>;
+
+    // Update existing document
+    update<I>(criteria: FilterQuery<D>, update: UpdateQuery<D>, options?: any): Promise<T>;
+
+    // Update all docuemnts which matches the provdied conditions
+    bulkUpdate<I>(criteria: FilterQuery<D>, update: UpdateQuery<D>, options?: any): Promise<T[]>;
+
+    delete(criteria: FilterQuery<D>): Promise<boolean>;
+
+    // Bulk Create provided documents
+    bulkCreate<I>(data: I[]): Promise<T[]>;
+
+    // Delete all documets which matches the criteria
+    bulkDelete(criteria: FilterQuery<D>): Promise<number>;
+}
+
+export enum ISortEnum {
+    Asc = 'ASC',
+    Desc = 'DESC',
+}
+
+export type ISort = {
+    key: Scalars['String'];
+    value: ISortEnum;
+};
+
+export interface GetAllArgs<T> {
+    criteria?: FilterQuery<T>;
+    sort?: ISort;
+    skip?: number;
+    limit?: number;
+    selectedFields?: string;
+}
+```
+
+### Example
+
+If you have a document named `User` you should define both `Repository` class and interface against it like the following
+
+```typescript
+export type IUserRepository = IBaseRepository<IUser>;
+```
+
+```typescript
+import { BaseRepository, IMongoOptions } from '@common-stack/store-mongo';
+import { inject, injectable, optional } from 'inversify';
+import { Connection } from 'mongoose';
+import { logger as Logger } from '@cdm-logger/server/lib/logger';
+import { UserModelFunc } from '../models';
+
+@injectable()
+export class UserRepository extends BaseRepository<IUser> implements IUserRepository {
+    constructor(
+        @inject('MongoDBConnection')
+        db: Connection,
+        @inject('Logger')
+        logger: typeof Logger,
+        @inject('IMongoOptions')
+        @optional()
+        options?: IMongoOptions,
+    ) {
+        super(UserModelFunc, db, logger, options);
+    }
+}
+```
+
+After creating the `Repository` class, the next step is to register it with the [Dependency Injection](dependency-injection) so It can be injected easily everywhere in the app.
+After creating repository, the next step is to add [Service](services)

package/lib/templates/content/docs/feature-api/feature-server/resolvers.md

@@ -0,0 +1,126 @@
+---
+meta:
+    title: Resolvers
+    description: Resolvers
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Resolvers...
+headers:
+    Cache-Control: no-cache
+---
+
+# Resolvers
+
+GraphQL Server needs to know how to populate data for every field in your schema so that it can respond to requests for
+that data.
+To accomplish this, it uses resolvers.
+
+_A resolver is a function that's responsible for populating the data for a single field in your schema_. It can populate
+that data
+in any way you define, such as by fetching data from a back-end database or a third-party API. A resolver is the key
+architectural component that connects GraphQL fields, graph edges, queries, mutations, and subscriptions to their
+respective data sources and micro-services. Read more about
+resolvers [here](https://www.apollographql.com/docs/apollo-server/data/resolvers/)
+
+> If you don't define a resolver for a particular field, Apollo Server automatically defines
+> a [default resolver](https://www.apollographql.com/docs/apollo-server/data/resolvers/#default-resolvers) for it.
+
+We use `Schema First` approach which requires us to define GraphQL schema before we write any code for it. So in order to
+create new GraphQL types, query or mutation, you need to add them to Schema. Create your schema file under `graphql/schema/<file-name.gql`
+
+```graphql
+
+type User{}
+type Users{
+    totalCount: Int!,
+    data: [User!]
+}
+
+input CreateInput{}
+input UpdateUserInput{}
+
+extend type Query{
+    # ... existing queries
+    user(id:ID!): UserModel!
+    users(id:ID!): UserPageModel!
+}
+
+extend type Mutation{
+    createUser(user:CreateUserInput!): UserModel!
+    updateUser(id:ID!, user: UpdateUserInput!): UserModel!
+    deleteUser(id:ID!): Boolean!
+}
+```
+
+Everytime you make change to GraphQL schema, we need to re generate typescript definitions using the following command
+
+```shell
+npm run generateGraphql
+```
+
+Next, let's add resolver implementation, by convention the all resolver definitions resides under `graphql/resolvers`.
+
+```typescript
+// graphql/resovlers/user-resolver.ts
+
+export const userResolver = (): IResolvers<IContext> => ({
+    User: {
+        // # Nested resolvers for relations
+        async posts(user, _, args, { postService }) {
+            const { data, totalCount } = await userService.getAllWithCount({
+                ...args,
+                criteria: {
+                    ...args.criteria,
+                    user: user.id,
+                },
+            });
+            return {
+                totalCount,
+                data,
+            };
+        },
+    },
+    Query: {
+        async users(_, args, { userService }) {
+            const { data, totalCount } = await userService.getAllWithCount(args);
+            return {
+                totalCount,
+                data,
+            };
+        },
+        user(_, { id }, { userService }) {
+            return userService.get(id);
+        },
+    },
+    Mutation: {
+        createUser(_, { user }, { userService }) {
+            return userService.create(user);
+        },
+        updateUser(_, { id, user }, { userService }) {
+            return userService.update(id, user, false);
+        },
+        deleteUser(_, { id }, { userService }) {
+            return userService.delete(id);
+        },
+    },
+});
+```
+
+<blockquote>
+Note:
+In order to use any service in the resolver first, you need to register your service in
+the [GraphQL context](https://the-guild.dev/graphql/modules/docs/essentials/context).
+Add it under `createServiceFunc` of [Feature](feature.md) API. If it does not already exist create one.
+
+```typescript
+const createServiceFunc = (container: interfaces.Container): IService => ({
+    userService: container.get<IUserService>(TYPES.UserService),
+});
+
+export default new Feature({
+    // rest of the configutations
+    createServiceFunc,
+});
+```
+
+</blockquote>

package/lib/templates/content/docs/feature-api/feature-server/rules.md

@@ -0,0 +1,132 @@
+---
+meta:
+    title: Rules
+    description: Rules
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Rules...
+headers:
+    Cache-Control: no-cache
+---
+
+# Rules
+
+Rules represents what GraphQL operations can be performed by the requested user. Rules are generated by two simple steps, defining resource access and
+then mapping those resource access to respective GraphQL operations.
+
+- Control who can access what, we are using users's permission together with the [CASL](https://casl.js.org/v6/en) to define their abilities to manage specific resource
+- Whether Graphql request can be performed or not [GraphQL Shield](https://the-guild.dev/graphql/shield)
+
+## Access Control
+
+We use User's [Permissions](permissions.md) to evaluate what he/she can or can't access. By convention we have 4 types
+of permissions
+
+- Mange (Can perform complete CRUD)
+- View
+- Edit
+- Delete
+
+So we need to map each of them with the cas ability, how its done is using a simple function which takes permission
+as `param` and define
+abilities for the users using its permissions.
+
+```typescript
+import { AbilityBuilder, Ability } from '@casl/ability';
+import { IModule, IPermissionType, IPermissionTypes, IPreDefinePermissions } from '@adminide-stack/core';
+import { get } from 'lodash';
+
+export function defineAbilityFor(permissions: Record<string, any>) {
+    const { can, build } = new AbilityBuilder(Ability);
+
+    /***
+     *  IPreDefinePermissions = {
+     *      manageResource: 'module.resource.manage'
+     *      viewResource: 'module.resource.view',
+     *      editResource: 'module.resource.edit',
+     *      deleteResource: 'module.resource.delete'
+     *   }
+     */
+    const canManageResource = get(permissions, IPreDefinePermissions.manageResource) === IPermissionType.Allow;
+    const canViewResource = get(permissions, IPreDefinePermissions.viewResource) === IPermissionType.Allow;
+    const canEditResource = get(permissions, IPreDefinePermissions.editResource) === IPermissionType.Allow;
+    const canDeleteResource = get(permissions, IPreDefinePermissions.deleteResource) === IPermissionType.Allow;
+
+    if (canManageResource) {
+        can(IPermissionTypes.manage, IModule.Resource);
+        can(IPermissionTypes.view, IModule.Resource);
+        can(IPermissionTypes.delete, IModule.Resource);
+        can(IPermissionTypes.edit, IModule.Resource);
+    }
+    if (canViewResource) {
+        can(IPermissionTypes.view, IModule.Resource);
+    }
+    if (canEditResource) {
+        can(IPermissionTypes.edit, IModule.Resource);
+    }
+    if (canDeleteResource) {
+        can(IPermissionTypes.delete, IModule.Resource);
+    }
+    return build();
+}
+```
+
+## GraphQL Shield
+
+Once we have abilities in place next step is to use them with the Graphql operations, this is
+where [GraphQL Shield](https://the-guild.dev/graphql/shield) comes in.
+It lets you defined one to one mapping with the GraphQL operations you have, a simple resolver function which will then
+determine whether this operation can be
+performed or not
+
+```typescript
+import { rule } from 'graphql-shield';
+import { getPermissionsFromContext } from '@adminide-stack/platform-server';
+// This if the function we've just defined above
+import { defineAbilityFor } from '../ability';
+
+const options = { cache: 'contextual' };
+const rules = {
+    Query: {
+        getResource: rule(options)(async (parent, args, ctx) => {
+            const permissions = await getPermissionsFromContext(ctx);
+            return defineAbilityFor(permissions).can(IPermissionTypes.view, IModule.Resource);
+        }),
+        getResources: rule(options)(async (parent, args, ctx) => {
+            const permissions = await getPermissionsFromContext(ctx);
+            return defineAbilityFor(permissions).can(IPermissionTypes.view, IModule.Resource);
+        }),
+    },
+    Mutation: {
+        createResource: rule(options)(async (parent, args, ctx) => {
+            const permissions = await getPermissionsFromContext(ctx);
+            return defineAbilityFor(permissions).can(IPermissionTypes.create, IModule.Resource);
+        }),
+        updateResource: rule(options)(async (parent, args, ctx) => {
+            const permissions = await getPermissionsFromContext(ctx);
+            return defineAbilityFor(permissions).can(IPermissionTypes.edit, IModule.Resource);
+        }),
+        delete: rule(options)(async (parent, args, ctx) => {
+            const permissions = await getPermissionsFromContext(ctx);
+            return defineAbilityFor(permissions).can(IPermissionTypes.delete, IModule.Resource);
+        }),
+    },
+    Resource: {
+        nestedResource: rule(options)(async (parent, args, ctx) => {
+            const permissions = await getPermissionsFromContext(ctx);
+            return defineAbilityFor(permissions).can(IPermissionTypes.view, IModule.NestedResource);
+        }),
+    },
+};
+```
+
+Once we have the rules object in place, the last step is to export it and pass it on to the `Feature API`
+
+```typescript
+import { rules } from './rules';
+
+export default new Feature({
+    // rest of the config
+    rules,
+});
+```

package/lib/templates/content/docs/feature-api/feature-server/schema.md

@@ -0,0 +1,12 @@
+---
+meta:
+    title: Schema
+    description: Schema
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Schema...
+headers:
+    Cache-Control: no-cache
+---
+
+## Schema

package/lib/templates/content/docs/feature-api/feature-server/services.md

@@ -0,0 +1,102 @@
+---
+meta:
+    title: Service
+    description: Service
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Service...
+headers:
+    Cache-Control: no-cache
+---
+
+## Service
+
+Services are top level business logic tier encapsulating business logic. A services performs business related
+operations on one or multiple models. It can involve fetching data from different sources, validating and transforming
+that and in the end
+either storing or returning the result. Services should be `database` agnostic and should not care about which database
+or data sources are being used.
+
+To understand the concept of `Services` we'll take a common example of `AutheticationService` containing all the basic
+method of an authentication workflow. The methods in the class reflects business operations. `AutheticationService`
+consumes`IOAuth0Client` and `IEmailClient` to perform 0Auth and `Email` related operations thus staying completely
+agnostic of
+which
+`0Auth` and `Email` provider is being used underneath.
+
+```typescript
+class AuthenticationService {
+    constructor(
+        private readonly auth0Client: IOAuth0Client,
+        private readonly emailClient: IEmailClient,
+    ) {}
+
+    signIn() {}
+
+    signUp() {}
+
+    forgotPassoword() {}
+
+    verifyEmail() {}
+
+    generateToken() {}
+}
+```
+
+In our application, in most scenarios, services needs to fetch and store data models from and into databases. Because
+these operations are so repetitive and needed
+almost everywhere we have a `BaseService` class which basically takes care of all database related logic, so you can
+focus more on what you want to do with the data rather than on how to
+fetch/store that data. The `BaseService` consists on the following methods
+
+```typescript
+export interface IBaseService<T, C = Omit<T, 'id'>, U = C> {
+    count(conditions?: FilterQuery<Document<T>>): Promise<number>;
+
+    get(id: string): Promise<T>;
+
+    get(conditions?: string | FilterQuery<Document<T>>): Promise<T>;
+
+    getAll(options?: GetAllArgs<Document<T>>): Promise<T[]>;
+
+    getByIds(ids: string[]): Promise<T[]>;
+
+    create(data: C): Promise<T>;
+
+    insert(
+        data: (C | U) & {
+            id?: string;
+        },
+        overwrite?: boolean,
+    ): Promise<T>;
+
+    bulkCreate(data: C[]): Promise<T[]>;
+
+    update(id: string, data: U, overwrite?: boolean): Promise<T>;
+
+    delete(id: string): Promise<boolean>;
+
+    delete(conditions: string | FilterQuery<Document<T>>): Promise<boolean>;
+
+    getAllWithCount(options: GetAllArgs<Document<T>>): Promise<{
+        data: T[];
+        totalCount: number;
+    }>;
+}
+```
+
+Any services wishes to use these methods just need to extend the `BaseService`
+
+```typescript
+export class UserService extends BaseService<IUserService> implements IUserService {
+    constructor(
+        @inject(TYPES.UserRepository)
+        repository: IUserRepository,
+    ) {
+        super(repository);
+    }
+}
+```
+
+In the end, you need to register your service with the Dependency Injection, read more about
+that [here](dependency-injection)