@cdmbase/wiki-browser 12.0.18-alpha.10

package/lib/templates/content/docs/feature-api/feature-server/setup-resource-crud.md

@@ -0,0 +1,359 @@
+---
+meta:
+    title: Setup Resource CRUD
+    description: Setup Resource CRUD
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Setup Resource CRUD...
+headers:
+    Cache-Control: no-cache
+---
+
+## Setup Resource CRUD
+
+This guide will walk you through on how to add CRUD operations against any new/existing resource
+in the app without much hassle. There are few simple steps you need to follow and in the end you'll have
+all the required GraphQL queries and mutations against that resource.
+
+## Define Schema
+
+For each resource we have schema definitions in multiple formats to be used by respective lib,
+
+### GraphQL
+
+GraphQL type needs to be defined in the GraphQL schema, to be used by GraphQL server and later on these will
+be used to generate typescript definitions using [GraphQL codegen](https://the-guild.dev/graphql/codegen). You need to
+define both return
+types
+and input types
+
+```graphql
+
+type User{}
+type Users{
+    totalCount: Int!,
+    data: [User!]
+}
+
+input CreateInput{
+
+}
+input UpdateUserInput{
+
+}
+```
+
+### Typescript
+
+Typescript definitions are auto generated by GraphQL schema, to be used by Typescript compiler. All you need to is to
+run
+
+```sh
+npn run generateGraphql
+```
+
+> Note: We are assuming that you have already updated `codegen.yml`configs with your module
+
+### Mongoose Model
+
+Mongoose model schema to be used by mongoose for mongo DB operations. Create a new Mongoose Model
+file under `store/models`, following the naming convention `<resource-name>-model.ts` e.g. `user-model.ts`
+
+```typescript
+import { Connection, Document, Model, Schema } from 'mongoose';
+import { addIdVirtualFields, commonModeSchemaOptions } from '@common-stack/store-mongo';
+import { IUser } from 'generated-modals';
+
+export type IUserMongoModel = Document & IUser;
+export const userScehma = new Schema<IUserMongoModel>(
+    {
+        //.. schema definition for model
+    },
+    commonModeSchemaOptions,
+);
+
+addIdVirtualFields(userScehma);
+export type UserModelType = Model<IUserMongoModel>;
+export const UserModelFunc: (db: Connection) => UserModelType = (db) => db.model<IUserMongoModel>('users', userScehma);
+```
+
+## Define Repository
+
+We are using repositories to communicate with db and perform all db operations. You repository should encapsulate all db
+related logic and
+how you are communicating with the db giving an abstraction to upper level services, so they don't have
+to worry about the which data source is being used.
+
+Create a new Repository file under `store/repositoires`, following the naming convention `<resource-name>-repository.ts`
+e.g `user-repository.ts` and
+
+repository type definitions under `interfaces/<resource-name>-service-interface.ts` e.g `user-service-interface.ts`
+
+```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);
+    }
+}
+```
+
+When you extend from the `BaseRepository` it adds the following methods to your repository
+
+```typescript
+export interface GetAllArgs<T> {
+    criteria?: FilterQuery<T>;
+    sort?: ISort;
+    skip?: number;
+    limit?: number;
+    selectedFields?: string;
+}
+
+export interface IBaseRepository<T, D = Document<T>> {
+    count(conditions?: FilterQuery<D>): Promise<number>;
+
+    getAll(options: GetAllArgs<D>): Promise<T[]>;
+
+    get(conditions?: FilterQuery<D>, selectedFields?: string): Promise<T>;
+
+    create<I>(data: I): Promise<T>;
+
+    upsert<I>(conditions: FilterQuery<D>, update: I, options: any): Promise<T>;
+
+    update<I>(criteria: FilterQuery<D>, update: UpdateQuery<D>, options?: any): Promise<T>;
+
+    bulkUpdate<I>(criteria: FilterQuery<D>, update: UpdateQuery<D>, options?: any): Promise<T[]>;
+
+    delete(criteria: FilterQuery<D>): Promise<boolean>;
+
+    bulkGet(ids: string[], selectedFields?: string): Promise<T[]>;
+
+    bulkCreate<I>(data: I[]): Promise<T[]>;
+
+    bulkDelete(criteria: FilterQuery<D>): Promise<number>;
+}
+```
+
+You can then use these methods to perform CRUD on your resource.
+
+### Register with DI
+
+Once you have your repository set up and in place, you need to register it with the Dependency Injection so it can
+injected where
+required
+
+```typescript
+// containers/container.ts
+
+export const localContainerModule: (settings) => interfaces.ContainerModule = () =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        //...existing bindings
+        bind(TYPES.UserRepository).to(UserRepository).inSingletonScope().whenTargetIsDefault();
+    });
+
+export const externalContainerModule: (settings) => interfaces.ContainerModule = () =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        //...existing bindings
+        bind(TYPES.UserRepository).to(UserRepository).inSingletonScope().whenTargetIsDefault();
+    });
+```
+
+> Note: This assumes that `TYPES` constant has already been updated with the new value.
+
+## Define Service
+
+Services incorporate your business rules and domain logic, service utilize `repository` to communicate with the data
+store, a service can consume other service
+if needed to fetch or make changes to other resources.
+
+Create a new service file under `services`, following the naming convention `<resource-name>-service.ts`
+e.g `user-service.ts`and type
+definition for it under `interfaces`
+
+```typescript
+// interfaces/user-service.interface.ts
+
+export type IUseraService = BaseService<IUser, IUserInput, IUserUpdateInput>;
+```
+
+```typescript
+// services/user-service.ts
+
+import { inject, injectable } from 'inversify';
+import { CommonType } from '@common-stack/core';
+import { ServiceBroker } from 'moleculer';
+import { logger as Logger } from '@cdm-logger/server/lib/logger';
+
+@injectable()
+export class UserService extends BaseService<IUser, IUserInput, IUserUpdateInput> implements IUserService {
+    constructor(
+        @inject(TYPES.UserRepository)
+        private readonly repository: IUserRepository,
+    ) {
+        super(repository);
+    }
+}
+```
+
+By extending the `BaseService` the following methods gets added to the new `Service`
+
+```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;
+    }>;
+}
+```
+
+### Register with the DI
+
+Once you have your service file in place, next step is to register it too, with the DI so It can be injected on demand wherever required
+
+```typescript
+// containers/container.ts
+export const localContainerModule: (settings) => interfaces.ContainerModule = () =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        //...existing bindings
+        bind(TYPES.UserService).to(UserService).inSingletonScope().whenTargetIsDefault();
+    });
+export const externalContainerModule: (settings) => interfaces.ContainerModule = () =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        //...existing bindings
+        bind(TYPES.UserService).to(UserService).inSingletonScope().whenTargetIsDefault();
+    });
+```
+
+## Add Queries and Mutations
+
+Update GraphQL schema to have the new types, queries and mutations, by convention your newly added queries and mutation
+names should look like this.
+
+```graphql
+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!
+}
+```
+
+After adding to the GraphQL schema generate the new types and next step is to add the resolver for those operations.
+
+```typescript
+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:
+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),
+});
+```
+
+</blockquote>
+
+in main resolvers file, register your newly added resolver.
+
+```typescript
+export const resolvers = [...exisitngResolvers, userResolver];
+```
+
+The last thing you need to do is to register the `resolvers` to [Feature](feature.md) API (If it's not already registered).
+Once everything is done you will have the above defined GraphQL queries and mutation performing CRUD on the resource.

package/lib/templates/content/docs/feature-api/index.md

@@ -0,0 +1,18 @@
+---
+meta:
+    title: Feature  API
+    description: Feature  API
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Feature  API...
+headers:
+    Cache-Control: no-cache
+---
+
+## Feature Api
+
+**[Feature Browser](/docs/feature-api/feature-browser)**
+
+**[Feature Mobile](/docs/feature-api/feature-mobile)**
+
+**[Feature Server](/docs/feature-api/feature-server)**

package/lib/templates/content/docs/graphql/apolloClient-mutation.md

@@ -0,0 +1,94 @@
+---
+meta:
+    title: Apollo Client Mutation
+    description: Apollo Client Mutation
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Apollo Client Mutation...
+headers:
+    Cache-Control: no-cache
+---
+
+## How to write a mutation with optimistic update and actual cache update:
+
+### Writing a Mutation with Optimistic Update and Cache Update
+
+1. **Define the Mutation with Optimistic Response:**
+    - Create the mutation with an `optimisticResponse` to immediately update the UI with predicted results.
+
+    ```typescript
+    updateOrgClient({
+        variables: { updateRequest: { id: client.id, payload: newClient } },
+        optimisticResponse: {
+            __typename: 'Mutation',
+            updateOrgClient: {
+                ...newClient,
+                id: client.id,
+            },
+        },
+        update(cache, { data }) {
+            if (data?.updateOrgClient) {
+                cache.modify({
+                    fields: {
+                        getOrgClient(existingData = {}) {
+                            return {
+                                ...existingData,
+                                ...data.updateOrgClient,
+                            };
+                        },
+                    },
+                });
+            }
+        },
+    });
+    ```
+
+2. **Cache Update:**
+    - Use the `update` function to modify the cache after the mutation completes.
+
+    ```typescript
+    update(cache, { data }) {
+        if (data?.updateOrgClient) {
+            cache.modify({
+                fields: {
+                    getOrgClient(existingData = {}) {
+                        return {
+                            ...existingData,
+                            ...data.updateOrgClient,
+                        };
+                    },
+                },
+            });
+        }
+    }
+    ```
+
+3. **Adding a New Client with Optimistic Response:**
+    - Handle adding a new client similarly, generating a temporary ID.
+    ```typescript
+    addClient({
+        variables: { client: newClient },
+        optimisticResponse: {
+            __typename: 'Mutation',
+            addClient: {
+                ...newClient,
+                id: Math.random().toString(36).substring(2, 15), // Generate a temporary ID
+            },
+        },
+        update(cache, { data }) {
+            if (data?.addClient) {
+                cache.modify({
+                    fields: {
+                        getClients(existingClients = []) {
+                            return [...existingClients, data.addClient];
+                        },
+                    },
+                });
+            }
+        },
+    });
+    ```
+
+By following these steps, you can implement mutations with optimistic updates and actual cache updates effectively.
+
+References for optimistic update can be found [here](https://www.apollographql.com/docs/react/performance/optimistic-ui)

package/lib/templates/content/docs/graphql/index.md

@@ -0,0 +1,14 @@
+---
+meta:
+    title: Graphql
+    description: Graphql
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Graphql...
+headers:
+    Cache-Control: no-cache
+---
+
+## Graphql
+
+**[Scalars](/docs/graphql/scalars)**

package/lib/templates/content/docs/graphql/scalars.md

@@ -0,0 +1,15 @@
+---
+meta:
+    title: Scalars
+    description: Scalars
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Scalars...
+headers:
+    Cache-Control: no-cache
+---
+
+## Scalars
+
+Timestamp
+The JavaScript Date is an integer. Type represents date and time as number of milliseconds from start of the UNIX epoch.

package/lib/templates/content/docs/help/index.md

@@ -0,0 +1,14 @@
+---
+meta:
+    title: Help
+    description: Help
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Help...
+headers:
+    Cache-Control: no-cache
+---
+
+## Help
+
+**[Welcome](/docs/help/intro)**

package/lib/templates/content/docs/help/intro.md

@@ -0,0 +1,16 @@
+---
+meta:
+    title: Welcome
+    description: Welcome
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Welcome...
+headers:
+    Cache-Control: no-cache
+---
+
+## Welcome
+
+These pages are primarily intended for those who wish to contribute to the CDE Base projects by submitting bug reports, suggesting new features, building extensions, commenting on new ideas, or even by submitting pull requests.
+
+Please refer to the sidebar (on the right) for details on Contributing to CDE Code, and Documentation.

package/lib/templates/content/docs/intl/ant-design-menu-translation.md

@@ -0,0 +1,74 @@
+---
+meta:
+    title: Ant Design Menu Translation
+    description: Ant Design Menu Translation
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Ant Design Menu Translation...
+headers:
+    Cache-Control: no-cache
+---
+
+## Ant Design Menu Translation
+
+To enable menu translations, we need to use translation keys in the menu routes and apply the `t` function when rendering the menu.
+
+For instance, consider the following routes:
+
+```
+{
+        path: `${ORG_STD_ROUTES.USER_BASE_PATH}`,
+        key: 'usermenu',
+        tab: 'User Account',
+        exact: false,
+        name: 'User',
+        component: () => import('./components/Account'),
+        position: IMenuPosition.BOTTOM,
+        icon: 'AiOutlineUser',
+        priority: 1,
+        // authority: ['admin', 'user'],
+    },
+    {
+        path: `${ORG_STD_ROUTES.USER_BASE_PATH}/billing`,
+        key: 'usermenu.billing',
+        exact: true,
+        name: 'Billing Setting',
+        component: () => import('./components/Billing'),
+        position: IMenuPosition.BOTTOM,
+        priority: 3,
+        authority: ['admin', 'user'],
+    },
+```
+
+In the routes above, we need to use translation keys in the route names instead of the actual names. For example, instead of using route names like `User` and `Billing Setting`, we should use translation keys such as `menu.user` and `menu.billing_setting`.
+
+Here are the updated routes to make translations work:
+
+```
+{
+        path: `${ORG_STD_ROUTES.USER_BASE_PATH}`,
+        key: 'usermenu',
+        tab: 'User Account',
+        exact: false,
+        name: 'menu.user',
+        component: () => import('./components/Account'),
+        position: IMenuPosition.BOTTOM,
+        icon: 'AiOutlineUser',
+        priority: 1,
+        // authority: ['admin', 'user'],
+    },
+    {
+        path: `${ORG_STD_ROUTES.USER_BASE_PATH}/billing`,
+        key: 'usermenu.billing',
+        exact: true,
+        name: 'menu.billing_setting',
+        component: () => import('./components/Billing'),
+        position: IMenuPosition.BOTTOM,
+        priority: 3,
+        authority: ['admin', 'user'],
+    },
+```
+
+The translation keys should be defined in the `menu.json` file in the package that have those menu as follows:
+
+![image](https://github.com/user-attachments/assets/7e1e1aab-fe32-402b-8ac5-3626087f3418)