@cdmbase/wiki-browser 12.0.18-alpha.5

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

@@ -0,0 +1,130 @@
+---
+meta:
+    title: Feature Mobile API
+    description: Feature Mobile API
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Feature Mobile API...
+headers:
+    Cache-Control: no-cache
+---
+
+# Feature Mobile API
+
+Similar to Feature Browser API, the backend Feature API support all that need to run the backend application..
+
+It is opiniated and it supports
+
+- react-native
+- expo
+- apollo-client
+- redux-observable
+- redux
+- redux-persist
+- react-navigation
+
+Components are rendered only through `react-navigation`, for that we pass `routeConfig`.
+
+Dynamic Components are provided using `slot-fill` logic using `componentFillPlugins` configuration.
+
+Third-party Scripts can be inserted into HTML page as well.
+
+Each of these packaged module is used in the `mobile-device` like below
+
+```js
+import counterModule from '@sample-stack/counter-module-mobile';
+import accountModule from '@sample-stack/account-module-mobile';
+import paymentModule from '@sample-stack/payment-module-mobile';
+
+const features = new Feature(FeatureWithRouterFactory, counterModule, accountModule, paymentModule);
+```
+
+The `mobile-device` have all required logic to consolidate the `reducers`, `epics`, `apollo-client configuration`, `react-router configuration` etc to run the application.
+
+For example provide all the required configuration to the `Feature` like below.
+
+```js
+const module = new Feature({
+    /**
+        Customizing ID in the apollo cache.
+    **/
+    dataIdFromObject,
+    /**
+        load apollo-client state management. 
+    **/
+    clientStateParams: { resolvers, typeDefs: schema },
+    /**
+        load redux-observables to manage the client state.
+    **/
+    epic: [onUserAccountNotFound],
+    /**
+        load react-router configuration to display component based on navigation. 
+        for more information check [Routing](./routing.mx)
+    **/
+    routeConfig: filteredRoutes,
+    componentFillPlugins: [
+        {
+            name: 'teams-contribution',
+            render: TeamsContribution,
+        },
+    ],
+    createContainerFunc: [Auth0Module],
+    /**
+     load reducers to the Redux Store when this Feature Module is used.
+    **/
+    reducer: { user: userReducer, redirectRoutes: redirectRoutesReducer, authErrors: authErrorsReducer },
+    /**
+        By default all redux state is persisted using redux-persist, if you need to manipulate the persist state
+        add configuration here. 
+    **/
+    reduxPersistTransforms: [blacklistErrorFilter, blacklistUserFilter],
+});
+```
+
+We don't need to put the `redux` store creation nor apollo-client setup in the Module as this action will be taken care at the higher level (frontend-server).
+
+### Client State Management
+
+Applciation state can be managed using Apollo Link State and Redux.
+
+#### Redux
+
+Support [redux's reducers](https://redux.js.org/usage/structuring-reducers/basic-reducer-structure)
+Example:
+
+```js
+const module = new Feature({
+    reducer: { user: userReducer, redirectRoutes: redirectRoutesReducer, authErrors: authErrorsReducer },
+    ....
+});
+```
+
+#### Apollo Client State Management
+
+Support [interacting with local data in Apollo Client](https://www.apollographql.com/docs/react/local-state/local-state-management/)
+
+Example:
+
+```js
+const module = new Feature({
+    clientStateParams: { resolvers, typeDefs: schema, typePolicies },
+    ....
+});
+```
+
+##### dataIdFromObject
+
+Support cusotmizing the ID in the apollo cache. More infromation is [here](https://www.apollographql.com/docs/react/caching/cache-configuration/#dataidfromobject)
+
+#### Epic
+
+Support [redux-observable](https://redux-observable.js.org/docs/basics/Epics.html)
+
+Example:
+
+```js
+const module = new Feature({
+    epic: [onUserAccountNotFound],
+    ....
+});
+```

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

@@ -0,0 +1,18 @@
+---
+meta:
+    title: Feature Mobile
+    description: Feature Mobile
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Feature Mobile...
+headers:
+    Cache-Control: no-cache
+---
+
+## Feature Mobile
+
+**[Feature Mobile API](/docs/feature-api/feature-mobile/feature)**
+
+**[Navigation](/docs/feature-api/feature-mobile/navigation)**
+
+**[Auth & Permissions](/docs/feature-api/feature-mobile/auth-permissions)**

package/lib/templates/content/docs/feature-api/feature-mobile/navigation.md

@@ -0,0 +1,187 @@
+---
+meta:
+    title: Navigation
+    description: Navigation
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Navigation...
+headers:
+    Cache-Control: no-cache
+---
+
+## Navigation
+
+## Configuring Navigation
+
+Configure through `routeConfig` in the configuration file, the format is an object of routing information.
+
+```js
+const routerConfig1: IRouteData = {
+    ['/']: {
+        exact: false,
+        container: createStackNavigator(),
+        name: 'MainStack',
+        props: {
+            initialRouteName: 'Guest',
+            screenOptions: {
+                headerShown: false,
+            },
+        },
+    },
+    ['//guest']: {
+        container: createBottomTabNavigator(),
+        exact: false,
+        name: 'Guest',
+        props: {
+            initialRouteName: 'Home',
+            screenOptions: {
+                headerShown: false,
+                tabBarLabel: 'About',
+                // tabBarIcon: ({ color }) => <Ionicons name="person" size={24} color={color} />,
+            },
+        },
+    },
+    ['//guest/home']: {
+        name: 'Home',
+        props: {
+            initialParams: {},
+            component: MyComponent,
+            options: {
+                headerShown: true,
+                tabBarLabel: 'Home',
+                headerTitle: 'Home',
+                // tabBarIcon: ({ color }) => <Ionicons name="home" size={24} color={color} />,
+            },
+        },
+    },
+    ['//guest/about']: {
+        exact: false,
+        container: createStackNavigator(),
+        name: 'About',
+        props: {
+            initialRouteName: 'Hello',
+        },
+    },
+    ['//guest/about/hello']: {
+        name: 'Hello',
+        props: {
+            initialParams: {},
+            component: MyComponent,
+            options: {
+                headerTitle: 'About',
+            },
+        },
+    },
+    ['//guest/about/personalinfo']: {
+        name: 'PersonalInfo',
+        props: {
+            initialParams: { name: 'Test' },
+            component: MyComponent,
+            options: {
+                headerTitle: 'Personal Info',
+            },
+        },
+    },
+    ['//setting']: {
+        name: 'Setting',
+        props: {
+            initialParams: {},
+            component: MyComponent,
+            options: {
+                headerShown: true,
+                headerTitle: 'Settings',
+                headerBackTitle: 'Back',
+            },
+        },
+        exact: false,
+    },
+};
+```
+
+It generates
+
+```js
+<StackNavigator
+  initialRouteName="Guest"
+  screenOptions={
+    Object {
+      "headerShown": false,
+    }
+  }
+>
+  <Screen
+    name="MainStack.Guest"
+  >
+    <BottomTabNavigator
+      initialRouteName="Home"
+      screenOptions={
+        Object {
+          "headerShown": false,
+          "tabBarLabel": "About",
+        }
+      }
+    >
+      <Screen
+        initialParams={Object {}}
+        name="MainStack.Guest.Home"
+        options={
+          Object {
+            "headerShown": true,
+            "headerTitle": "Home",
+            "tabBarLabel": "Home",
+          }
+        }
+      >
+        [Function]
+      </Screen>
+      <Screen
+        name="MainStack.Guest.About"
+      >
+        <StackNavigator
+          initialRouteName="Hello"
+        >
+          <Screen
+            initialParams={Object {}}
+            name="MainStack.Guest.About.Hello"
+            options={
+              Object {
+                "headerTitle": "About",
+              }
+            }
+          >
+            [Function]
+          </Screen>
+          <Screen
+            initialParams={
+              Object {
+                "name": "Test",
+              }
+            }
+            name="MainStack.Guest.About.PersonalInfo"
+            options={
+              Object {
+                "headerTitle": "Personal Info",
+              }
+            }
+          >
+            [Function]
+          </Screen>
+        </StackNavigator>
+      </Screen>
+    </BottomTabNavigator>
+  </Screen>
+  <Screen
+    initialParams={Object {}}
+    name="MainStack.Setting"
+    options={
+      Object {
+        "headerBackTitle": "Back",
+        "headerShown": true,
+        "headerTitle": "Settings",
+      }
+    }
+  >
+    [Function]
+  </Screen>
+</StackNavigator>
+```

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

@@ -0,0 +1,44 @@
+---
+meta:
+    title: Scheduling / Cron Jobs
+    description: Scheduling / Cron Jobs
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Scheduling / Cron Jobs...
+headers:
+    Cache-Control: no-cache
+---
+
+# Scheduling / Cron Jobs
+
+## What are Cron Jobs
+
+Cron jobs are scheduled tasks that are run automatically at specified intervals. Cron jobs are an essential component of many applications and software systems. They allow developers and system administrators to schedule and automate recurring tasks that need to be performed on a regular basis. These tasks can be anything from running a script to sending an email to cleaning up temporary files.
+
+For example, an e-commerce website might use a cron job to perform a daily inventory update, which would update the stock levels of each product based on the sales from the previous day. A social media platform might use a cron job to generate a weekly activity report for each user, which would summarize their engagement with the platform over the past week.
+Cron jobs are needed in applications because they provide a reliable and efficient way to automate repetitive tasks, reducing the workload on human operators and improving the overall efficiency of the system. They can also help ensure that critical tasks are performed on time, reducing the risk of errors or delays that could impact the user experience.
+
+In summary, cron jobs are an important tool for developers and system administrators that can help improve the performance, reliability, and functionality of an application.
+
+## Adding a Cron Job
+
+There are numerous ways to add cron jobs to your Node JS application, we are defining them
+using the [Moleculer Services](https://moleculer.services/). Creating cron jobs is simple using the
+Moleculer Service and [Cron Tasker](https://www.npmjs.com/package/@skoropletov/moleculer-cron-tasks.
+
+```typescript
+this.broker.createService({
+    name: 'cron-service', // Name of Moleculer Service
+    mixins: [CronTasks], // Cron Tasker Plugin to enable Cron Jobs
+    tasks: [
+        {
+            name: 'log-seconds', // Cron Task Name
+            cronTime: '* * * * * *', // Unix Cron Schedule
+            callback: (): void => {
+                // Call back function to run on each job
+                console.log('[!] second passed');
+            },
+        },
+    ],
+});
+```

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

@@ -0,0 +1,320 @@
+---
+meta:
+    title: Dataloader
+    description: Dataloader
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Dataloader...
+headers:
+    Cache-Control: no-cache
+---
+
+# Dataloader
+
+### How Dataloaders are Used and Their Benefits
+
+Based on [PR #2716](https://github.com/CDEBase/adminIde-stack/pull/2716), dataloaders were introduced to optimize GraphQL performance by **batching and caching** requests. This document provides an in-depth explanation of their implementation, usage, and advantages.
+
+---
+
+#### What is a DataLoader?
+
+A **DataLoader** is a utility for batching and caching requests in a GraphQL environment. It allows efficient resolution of GraphQL queries by queuing up multiple requests during execution and batching them into a single query to the database or API.
+
+---
+
+#### Implementation of Dataloaders
+
+1. **Defining the DataLoader Type**:
+    - A specific `ITeamsDataLoader` type is created to handle team entities.
+    - This type is derived from a generic `IDataLoader` interface for flexibility and reuse.
+
+    ```typescript
+    export type ITeamsDataLoader = IDataLoader<ITeam>;
+    ```
+
+2. **Integrating Dataloaders in Service Interfaces**:
+    - To ensure seamless access throughout the application, the `teamsDataLoader` is added to the `IServices` interface.
+    - This allows dependency injection and promotes consistency.
+
+    ```typescript
+    export interface IServices {
+        teamService: ITeamService;
+        accountUserDataLoader: IAccountUserDataLoader;
+        teamsDataLoader: ITeamsDataLoader;
+    }
+    ```
+
+3. **Creating the DataLoader Instance**:
+    - The DataLoader instance is initialized to handle batching and caching logic.
+    - Below is an example of how a DataLoader might be initialized and how batched results are mapped back to GraphQL child resolvers:
+
+    ```typescript
+    import DataLoader from 'dataloader';
+    import { getTeamsByIds } from './teamRepository';
+
+    export const createTeamsDataLoader = (): ITeamsDataLoader => {
+        return new DataLoader<string, ITeam>(async (teamIds) => {
+            // Fetch all teams in a single batch based on provided IDs
+            const teams = await getTeamsByIds(teamIds);
+
+            // Map the fetched teams back to their corresponding IDs
+            return teamIds.map((id) => teams.find((team) => team.id === id) || new Error(`Team not found: ${id}`));
+        });
+    };
+    ```
+
+    **Explanation of Mapping**:
+    - **Input**: A list of `teamIds` queued by the DataLoader (e.g., `['team1', 'team2', 'team3']`).
+    - **Process**: Fetch the data for all `teamIds` in a single query (e.g., `getTeamsByIds(teamIds)`).
+    - **Mapping Back**:
+        - Use the input `teamIds` to order the results so they correspond to the original request order.
+        - If a team is missing, return an error or handle it gracefully.
+
+    This ensures that the batched result aligns with the request order, even if the database query returns the results in a different sequence.
+
+4. **Using the DataLoader in GraphQL Resolvers**:
+    - Resolvers can now delegate data fetching to the DataLoader, ensuring efficient data retrieval and proper mapping back to the GraphQL schema.
+
+    ```typescript
+    const resolvers = {
+        Query: {
+            team: async (_: any, { id }: { id: string }, { services }: { services: IServices }) => {
+                return services.teamsDataLoader.load(id); // Delegates to the DataLoader
+            },
+        },
+        User: {
+            teams: async (parent: IUser, _: any, { services }: { services: IServices }) => {
+                // Batch fetch all team IDs associated with the user
+                return services.teamsDataLoader.loadMany(parent.teamIds);
+            },
+        },
+    };
+    ```
+
+---
+
+#### Benefits of Using Dataloaders
+
+1. **Batching Requests**:
+    - Groups multiple identical or related queries into a single request.
+    - Reduces the overhead caused by multiple queries, improving efficiency.
+
+    Example:
+    Without DataLoader:
+
+    ```
+    Query: getTeam(1)
+    Query: getTeam(2)
+    Query: getTeam(3)
+    ```
+
+    With DataLoader:
+
+    ```
+    Single Query: getTeams([1, 2, 3])
+    ```
+
+2. **Caching**:
+    - Automatically caches the results of requests made during the same execution cycle.
+    - Prevents fetching the same data more than once, reducing redundant calls.
+
+    Example:
+
+    ```
+    First Request: getTeam(1) -> Fetch from database
+    Second Request: getTeam(1) -> Return from cache
+    ```
+
+3. **Improved Performance**:
+    - Fewer queries mean reduced latency and lower server/database load.
+    - Scales better as the number of concurrent requests increases.
+
+4. **Solves the N+1 Problem**:
+    - In GraphQL, resolvers often make repetitive requests (N+1 Problem). DataLoader batches these queries, solving this inefficiency.
+
+    Example:
+
+    ```
+    Query: Get all teams for users
+    Team Resolvers: Fetch team for each user -> N queries
+    With DataLoader: Fetch all teams in one query
+    ```
+
+5. **Mapping Ensures Correctness**:
+    - By maintaining a consistent mapping of inputs to outputs, DataLoader guarantees that each GraphQL child resolver receives the data it requested, even if some IDs are missing.
+
+---
+
+### Key Steps to Map Batched Results Back to GraphQL Children
+
+1. **Use the Input IDs for Consistent Ordering**:
+    - The input IDs passed to the DataLoader (`teamIds`) must dictate the order of the output array.
+
+2. **Handle Missing Data Gracefully**:
+    - If the requested ID is not found in the fetched data, return an error or null to the corresponding resolver.
+    - Example:
+        ```typescript
+        teamIds.map((id) => teams.find((team) => team.id === id) || new Error(`Team not found: ${id}`));
+        ```
+
+3. **Leverage `loadMany` for Collections**:
+    - When fetching collections of data (e.g., all teams for a user), use `loadMany` to handle multiple IDs at once.
+    - Example:
+        ```typescript
+        const teamData = await services.teamsDataLoader.loadMany(parent.teamIds);
+        ```
+
+---
+
+### Example Usage in GraphQL Context
+
+Here’s how DataLoader optimizes GraphQL child resolvers:
+
+```graphql
+query {
+    user(id: "123") {
+        id
+        name
+        teams {
+            id
+            name
+        }
+    }
+}
+```
+
+- The `User` resolver fetches `teamIds` for the user.
+- The `teams` field uses `loadMany` to batch all `teamIds` into a single request.
+- DataLoader maps the results back to each team field for the user in the correct order.
+
+---
+
+### Changes Required to Add DataLoader to Existing Code
+
+#### **Steps to Integrate DataLoader**
+
+1. **Create the DataLoader File**:
+    - Create a file named `teams-dataloader.ts` for defining the DataLoader logic.
+    - This file will contain the initialization and batching logic for the `TeamsDataLoader`.
+
+2. **Modify `types.ts` to Add DataLoader Type**:
+    - Update the `TYPES` constant to include a new type for `TeamsDataLoader`.
+
+3. **Update Service Interfaces**:
+    - Add the `TeamsDataLoader` to the `IServices` interface, ensuring it can be accessed across the application.
+
+4. **Implement DataLoader in Team Service**:
+    - Use the `TeamsDataLoader` in the `ITeamService` implementation for efficient data fetching.
+
+5. **Inject DataLoader in Dependency Container**:
+    - Register the `TeamsDataLoader` in your dependency injection container, ensuring it is initialized and injected where required.
+
+### Files Modified for DataLoader Implementation
+
+Here is a list of files modified for integrating DataLoader, along with a new file for the `TeamsDataLoader`.
+
+---
+
+#### **New File: `teams-dataloader.ts`**
+
+Here you can use the `BulkDataLoader` to simplify the boilerplate code.
+
+```typescript
+import { injectable, inject } from 'inversify';
+import { BulkDataLoader } from '@common-stack/store-mongo';
+import { ITeamService, TYPES } from '@adminide-stack/account-api-core';
+import { IAccountTeam as ITeam } from '@adminide-stack/core';
+
+@injectable()
+export class TeamsDataLoader extends BulkDataLoader<ITeam & { id: string }> {
+    constructor(
+        @inject(TYPES.ITeamService)
+        teamService: ITeamService,
+    ) {
+        super(teamService as never); // Pass the teamService to the BulkDataLoader utility
+    }
+}
+```
+
+---
+
+#### **Modified File: `types.ts`**
+
+```diff
+ export const TYPES = {
+     IOrganizationRepository: Symbol('IOrganizationRepository'),
+     IOrganizationMicroservice: Symbol('IOrganizationMicroservice'),
+     AccountUserDataLoader: Symbol('AccountUserDataLoader'),
++    TeamsDataLoader: Symbol('TeamsDataLoader'),
+ };
+```
+
+---
+
+#### **Modified File: `services.ts`**
+
+```diff
+ import { IPreferencesService } from '@adminide-stack/core';
+ import { IOrganizationService } from './organization-service';
+ import { IAccountService } from './account-service';
+ import { ITeamsDataLoader, ITeamService } from './team-service';
+ import { IAccountUserDataLoader } from './account-user-data-loader';
+ import { ICountryService } from '@container-stack/territory';
+
+ export interface IServices {
+     teamService: ITeamService;
+     preferenceService?: IPreferencesService;
+     countryService?: ICountryService;
+     accountUserDataLoader: IAccountUserDataLoader;
++    teamsDataLoader: ITeamsDataLoader;
+ }
+```
+
+---
+
+#### **Modified File: `team-service.ts`**
+
+```diff
+ import { IBaseService, IDataLoader } from '@common-stack/store-mongo';
+
+ export type ITeamsDataLoader = IDataLoader<ITeam>;
+
+ export interface ITeamService extends IBaseService<ITeam> {
+     getTeam(id: string): Promise<ITeam>;
+
+     getTeamByName(orgName: string, teamName: string): Promise<ITeam>;
+ }
+```
+
+---
+
+#### **Modified File: Dependency Injection Container**
+
+Ensure the `TeamsDataLoader` is registered in your DI container:
+
+```typescript
+container.bind<IDataLoader<ITeam>>(TYPES.TeamsDataLoader).toDynamicValue(() => createTeamsDataLoader());
+```
+
+## For more details on how to use generic dataloader you can read [Generic Dataloader from common-stac](./generic-dataloader.md)
+
+### Guidelines for Developers
+
+1. **Create a DataLoader for Each Entity**:
+    - Define a specific DataLoader type for each data entity (e.g., `ITeamsDataLoader`, `IUsersDataLoader`).
+
+2. **Ensure Proper Mapping in Batch Functions**:
+    - Always map the batched results back to the original input keys.
+
+3. **Use Dependency Injection**:
+    - Pass DataLoader instances via service interfaces (`IServices`) to ensure easy access across the application.
+
+4. **Gracefully Handle Errors**:
+    - Ensure missing or invalid IDs are handled correctly without breaking the execution.
+
+---
+
+For more details on implementation, review the [files changed in PR #2716](https://github.com/CDEBase/adminIde-stack/pull/2716/files).
+
+---