@cdmbase/wiki-browser 12.0.18-alpha.10

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

@@ -0,0 +1,81 @@
+---
+meta:
+    title: Dependency Injection
+    description: Dependency Injection
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Dependency Injection...
+headers:
+    Cache-Control: no-cache
+---
+
+# Dependency Injection
+
+## What is DI
+
+As our applications grow and evolves, each one of our code entities will internally require instances of other objects,
+which are better known as dependencies
+in the world of software engineering. The action of passing such `dependencies` to the dependent client is known
+as `injection`, and it also entails the participation
+of another code entity, named the `injector`. The injector will take responsibility for instantiating and bootstrapping
+the required dependencies so they are ready for
+use from the very moment they are successfully injected in the client. This is very important since the client knows
+nothing about how to instantiate its own dependencies
+and is only aware of the interface they implement in order to use them.
+
+In short, `DI` helps you write code in a loosely coupled way and makes your code more testable and reusable.”
+
+### How to register
+
+To achieve `DI` in our Ap, we are using [InversifyJS](https://inversify.io/). This doc will walk you through on how to
+register your entities such
+as classes (services,repositories) and constants with the dependency injection.
+`Feature` server API exposes two ways to register entities with the DI, which are following using
+either `createContainerFunc` and `createHemeraContainerFunc`.
+
+- `createContainerFunc` entities registered via this options will be registered locally inside the gateway
+- `createHemeraContainerFunc`entities registered via this options will be registered as external to gateway and local to
+  micro service.
+
+Both of these options take a function which has inversify `settings` as param and expects and
+Inverisfy `ContainerModule` as return value `(settings) => interfaces.ContainerModule`
+These functions by convention resides inside `container/container.ts` file
+
+### Example
+
+```typescript
+import { ContainerModule, interfaces } from 'inversify';
+
+export const localContainerModule: (settings) => interfaces.ContainerModule = () =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        bind(TYPES.UserRepository).to(UserRepository).inSingletonScope().whenTargetIsDefault();
+        bind('MongodbMigration').to(DefaultUserMigration).whenTargetNamed(DefaultUserMigration.name);
+    });
+
+export const externalContainerModule: (settings) => interfaces.ContainerModule = () =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        bind(TYPES.UserRepository).to(UserRepository).inSingletonScope().whenTargetIsDefault();
+        bind(TYPES.UserService).to(UserService).inSingletonScope().whenTargetIsDefault();
+    });
+
+export default new Feature({
+    //... Other options
+    createContainerFunc: [localContainerModule],
+    createHemeraContainerFunc: [externalContainerModule],
+});
+```
+
+Once the entities are registered, those can be easily injected anywhere when needed.
+
+### Usage
+
+```typescript
+export class UserService extends BaseService<IUser> {
+    constructor(
+        @inject(TYPES.UserRepository)
+        repository: IUserRepository,
+    ) {
+        super(repository);
+    }
+}
+```

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

@@ -0,0 +1,65 @@
+---
+meta:
+    title: Feature Server API
+    description: Feature Server API
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Feature Server API...
+headers:
+    Cache-Control: no-cache
+---
+
+## Feature Server 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
+
+- graphql-server such as resolvers, schema, directives, datasource
+- express middleware
+- preferences configuration
+- permissions configuration
+- policy configuration
+- roles configuraton
+- Graphql Rules
+- Moleculer broker services
+
+Each of these packaged module is used in the `backend-server` like below
+
+```js
+import CounterModule from '@sample-stack/counter-module-server';
+import AccountModule from '@sample-stack/account-module-server';
+import PaymentModule from '@sample-stack/payment-module-server';
+
+const feature = new Feature(DefaultFeature, CounterModule, AccountModule, PaymentModule);
+```
+
+For example provide all the required configuration to the `Feature` like below.
+
+```js
+const module = new Feature({
+    schema,
+    createDirectivesFUnc: paymentContextDirectives,
+    createDataSourceFunc: () => ({
+        stripeManager: new StripeDataSourceService(),
+    }),
+    createResolversFunc: resolver,
+    createServcieFunc: billingSErviceFunc,
+    middleware: stripeWebhookMiddleware,
+    createContainerFunc: [billingPorxyModule],
+    createHemeraContainerFunc: [billingModule],
+    postStartFunc: [(container, ctx) => initStripe(container, ctx)],
+    addBrokerClientServiceClass: [BillingMoleculerService],
+    createPreference: settings,
+    rolesUpdate: {
+        overwriteRolesPermissions: rolePermissionOverwrite,
+    },
+    addPermissions: {
+        createPermissions: billingRoleContribution,
+    },
+    addPolicies: {
+        createPolicies: BillingPolicyContribution,
+    },
+    rules,
+});
+```

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

@@ -0,0 +1,135 @@
+---
+meta:
+    title: Using DataLoader in Common Stack
+    description: Using DataLoader in Common Stack
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Using DataLoader in Common Stack...
+headers:
+    Cache-Control: no-cache
+---
+
+### Using DataLoader in Common Stack
+
+In Common Stack, DataLoader is used to optimize data fetching by batching and caching requests. This document explains how to set up and use DataLoader, specifically focusing on `AccountUserDataLoader` and its integration with a GraphQL resolver.
+You can reader further about DataLoaders [here](https://github.com/graphql/dataloader)
+
+#### 1. BulkDataLoader Implementation
+
+The `BulkDataLoader` class is a generic implementation of DataLoader, designed to work with any service that implements the `IBaseService` interface.
+
+```typescript
+import DataLoader from 'dataloader';
+import { injectable, unmanaged } from 'inversify';
+import { DataLoaderOptions, IBaseService, IDataLoader } from '../interfaces';
+
+@injectable()
+export class BulkDataLoader<T extends { id: string }> extends DataLoader<string, T | null> implements IDataLoader<T> {
+    constructor(@unmanaged() private readonly service: IBaseService<T>) {
+        super(async (ids: string[]) => {
+            const data = await this.service.getByIds(ids);
+            return ids.map((id) => data.find((record) => record.id === id) || null);
+        });
+    }
+
+    withOptions = new DataLoader<DataLoaderOptions<T>, T[]>(async (options) => {
+        const [{ searchKey, comparator, ...rest }] = options;
+        const ids = options.map((option) => option.id);
+        const results = await this.service.getAll({
+            ...rest,
+            criteria: {
+                ...rest.criteria,
+                [searchKey]: { $in: ids },
+            },
+        });
+        return ids.map((modelId) =>
+            results.filter((item) => {
+                if (typeof comparator === 'function') return comparator(modelId, item);
+                return item[searchKey].toString() === modelId.toString();
+            }),
+        );
+    });
+}
+```
+
+#### 2. DataLoader Interface
+
+The `IDataLoader` interface extends the basic DataLoader functionality to include additional options.
+
+```typescript
+import DataLoader from 'dataloader';
+import { IBaseService } from './base-service';
+
+export type DataLoaderOptions<T> = Parameters<IBaseService<T>['getAll']>[0] & {
+    id: string;
+    searchKey: keyof T;
+    comparator?: (source: unknown, target: T) => boolean;
+};
+export type IDataLoader<T> = DataLoader<string, T> & {
+    withOptions: DataLoader<DataLoaderOptions<T>, T[]>;
+};
+```
+
+#### 3. DataLoader with Service
+
+Creating a DataLoader is easy, all you have to do is
+
+```typescript
+@injectable()
+export class AccountUserDataLoader extends BulkDataLoader<IUserAccount> {
+    constructor(
+        @inject(TYPES.IAccountService)
+        accountService: IAccountService,
+    ) {
+        super(accountService);
+    }
+}
+
+@injectable()
+export class TeamsDataLoader extends BulkDataLoader<ITeam> {
+    constructor(
+        @inject(TYPES.ITeamService)
+        teamService: ITeamService,
+    ) {
+        super(teamService);
+    }
+}
+```
+
+and you will have a fully functional data loader with advanced functionality.
+Thanks to the `BulkDataLoader` parent class
+
+#### 4. GraphQL Resolver Integration
+
+You can use these data loaders in your field resolvers to batch requests, the below example will explain
+both simple and advanced use cases of account and teams data loaders.
+
+```typescript
+export const resolvers: (options: IResolverOptions) => IResolvers<IContext & MyContext> = (options) => ({
+    OrgUser: {
+        // # This will batch all ids and make a single call to db with all the ids
+        user: (root, args, { accountUserDataLoader }) => accountUserDataLoader.load(root.userId),
+        // # If you have a use case where you need to fetch other than the Id you use `withOptions`
+        // method, where you can define any key and pass additonal citeria
+        // comparator function is optional, which will help filter related result for the specific resolver
+        teamNames: async (root, args, { teamsDataLoader }) => {
+            const teams = await teamsDataLoader.withOptions.load({
+                id: root.orgName,
+                searchKey: 'orgName',
+                criteria: {
+                    'teamMembers.userId': root.userId,
+                },
+                comparator(userId: string, team) {
+                    return (
+                        team.orgName === root.orgName &&
+                        team.teamMembers.findIndex((i) => i.userId === root.userId) >= 0
+                    );
+                },
+            });
+            return teams.map((team) => (team as ITeam)?.name);
+        },
+    },
+});
+```
+
+This document outlines the setup and usage of DataLoader in the Common Stack, focusing on the `BulkDataLoader` class, its interface, a specific implementation for user accounts, and its integration into GraphQL resolvers.

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

@@ -0,0 +1,40 @@
+---
+meta:
+    title: Feature Server
+    description: Feature Server
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Feature Server...
+headers:
+    Cache-Control: no-cache
+---
+
+## Feature Server
+
+**[Feature Server API](/docs/feature-api/feature-server/feature)**
+
+**[Dependency Injection](/docs/feature-api/feature-server/dependency-injection)**
+
+**[Mongo Model](/docs/feature-api/feature-server/mongo-model)**
+
+**[Permissions](/docs/feature-api/feature-server/permissions)**
+
+**[Policies](/docs/feature-api/feature-server/policies)**
+
+**[Preferences](/docs/feature-api/feature-server/preferences)**
+
+**[Repositories](/docs/feature-api/feature-server/repositories)**
+
+**[Resolvers](/docs/feature-api/feature-server/resolvers)**
+
+**[Rules](/docs/feature-api/feature-server/rules)**
+
+**[Schema](/docs/feature-api/feature-server/schema)**
+
+**[Service](/docs/feature-api/feature-server/services)**
+
+**[Dataloader](/docs/feature-api/feature-server/dataloader)**
+
+**[Setup Resource CRUD](/docs/feature-api/feature-server/setup-resource-crud)**
+
+**[Migration](/docs/feature-api/feature-server/migration)**

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

@@ -0,0 +1,127 @@
+---
+meta:
+    title: Migration
+    description: Migration
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Migration...
+headers:
+    Cache-Control: no-cache
+---
+
+# Migration
+
+## Add migration id
+
+Migrtion Id should be unique and usually it follow date version for example `<MIGRATION_NAME>_<yyyymmdd>`. Migration script only runs once and it stores the migration id in the database, if you need to rerun the migration you need to change the version by updating `yyyymmdd`.
+
+## Add `up/down` scripts to execute
+
+### up is for loading
+
+### down is for unloading.
+
+In this example, we are renaming `status` field in Property.
+
+```
+
+// MongoDB field to update
+const fieldToUpdate = 'status';
+
+// Update values mapping
+const updateMapping = {
+  CREATED: 'created',
+  LISTED: 'listed',
+  INCOMPLETE: 'incomplete'
+};
+
+/**
+ * Updates the "status" field in a collection from "CREATED" to "created" and from "LISTED" to "listed":
+ */
+@injectable()
+export class PropertyStatusMigration {
+    private readonly logger: CdmLogger.ILogger;
+
+    constructor(
+        @inject(TYPES.PropertyRepository)
+        private propertyRepository: IBaseRepository<IPropertyType>,
+        @inject('Logger')
+        logger: CdmLogger.ILogger,
+    ) {
+        this.logger = logger.child({ className: PropertyStatusMigration.name });
+    }
+
+    get id(): string {
+        return 'PropertyStatusMigration_20230603';
+    }
+
+    get data(): IPropertyTypeInput[] {
+        return propertyTypes;
+    }
+
+    async up(): Promise<void> {
+        await this.down();
+        this.propertyRepository.bulkUpdate(    { [fieldToUpdate]: { $in: ['CREATED', 'LISTED', 'INCOMPLETE'] } },
+        [
+          {
+            $set: {
+              [fieldToUpdate]: {
+                $cond: {
+                  if: { $eq: [`$${fieldToUpdate}`, 'CREATED'] },
+                  then: updateMapping.CREATED,
+                  else: {
+                    $cond: {
+                      if: { $eq: [`$${fieldToUpdate}`, 'LISTED'] },
+                      then: updateMapping.LISTED,
+                      else: updateMapping.INCOMPLETE
+                    }
+                  }
+                }
+              }
+            }
+          }
+        ],
+        function(err, result) {
+          if (err) {
+            this.logger.error('Error updating documents:', err);
+          } else {
+            this.logger.debug('Documents updated successfully.');
+          }
+        })
+        this.logger.info(`PropertyStatusMigration_20230603 Property Status migration done!`);
+    }
+
+    async down(): Promise<void> {
+        this.logger.info(`Nothing to do`);
+    }
+}
+
+```
+
+Migration scritp runs when the backend server start and it runs `down` first before `up` script.
+
+## Bind to Migration Container
+
+```
+/**
+ * Local services and exposed microservices to serve remote connections.
+ * Operates within in the Gateway.
+ *
+ */
+export const localContainerModule: (settings) => interfaces.ContainerModule = () =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        ..... rest of the code ...
+        bind('MongodbMigration').to(PropertyStatusMigration).whenTargetNamed(PropertyStatusMigration.name);
+
+    });
+```
+
+## Add to the feature
+
+```
+export default new Feature(
+    {
+       ... rest...
+        createContainerFunc: [localContainerModule],
+    });
+```

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

@@ -0,0 +1,72 @@
+---
+meta:
+    title: Mongo Model
+    description: Mongo Model
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Mongo Model...
+headers:
+    Cache-Control: no-cache
+---
+
+# Mongo Model
+
+## Overview
+
+We are following the `ODM` object data modeling pattern, which dictate that for each document in the mongo db, we'll
+have a `Model` in our codebase which will contain the definition regarding how our database document will look like, what fields it'll have and how to
+validate them like `unique` , `required` validations. We are using [Mongoose](https://mongoosejs.com/) to define these models
+and to communicate with the MongoDB.
+
+## Mongoose
+
+In order to communicate with the database we are using [Mongoose](https://mongoosejs.com/). An object data modeling (
+ODM) library
+specifically designed for NodeJS to work with the [MongoDB](https://www.mongodb.com/). What this means in practical
+terms is that you can define your data model in
+just one place, in your code. It allows defining schemas for our data to fit into, while also abstracting the access
+to MongoDB. This way we can ensure all saved documents share a structure and contain required properties.
+
+### Schema
+
+While Mongo is schema-less, SQL defines a schema via the table definition. A
+Mongoose [Schema](https://mongoosejs.com/docs/guide.html) is a document data structure
+(or shape of the document) that is enforced via the application layer.
+
+### Models
+
+[Models](https://mongoosejs.com/docs/models.html) are fancy constructors compiled from Schema definitions. An instance of a model is called a [document](https://mongoosejs.com/docs/documents.html).
+Models are responsible for creating and reading documents from the underlying MongoDB database.
+
+### Defining Model
+
+```typescript
+import { Connection, Document, Model, Schema } from 'mongoose';
+import { addIdVirtualFields, commonModeSchemaOptions } from '@common-stack/store-mongo'; // Common Utility funtion, for common opeations
+import { IUser } from 'generated-modals'; // Typescript definiton for the Model
+
+export type IUserMongoModel = Document & IUser;
+export type UserModelType = Model<IUserMongoModel>;
+
+// First Step is to Define Schmea
+export const userScehma = new Schema<IUserMongoModel>(
+    {
+        firstName: { type: Schema.Types.String },
+        lastName: { type: Schema.Types.String },
+        email: { type: Schema.Types.String, required: true, unique: true },
+        active: { type: Schema.Types.Boolean, default: false },
+        // For collection you just need to pass the field definiton inside brackets []
+        comments: [{ type: Schema.Types.ObjectId, ref: 'commments' }], // Just to explain, how we can have cross document ref
+    },
+    commonModeSchemaOptions, // Adds timestamos (createdAt, updatedAt)
+);
+
+// Once schema is defined we can add/override methods on the schmea object
+addIdVirtualFields(userScehma); // Add `id` field which will contain document objectId, instead of `_id`
+
+// By calling `.model` on active db connection we instantiate a `model` instance (document).
+// Firs param is the name of the `collection`, which should always be plural whereas the second one is the schema definition of that model
+export const UserModelFunc: (db: Connection) => UserModelType = (db) => db.model<IUserMongoModel>('users', userScehma);
+```
+
+The next step is to [Define Repository](repositories) for this model.

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

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

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

@@ -0,0 +1,57 @@
+---
+meta:
+    title: Policies
+    description: Policies
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Policies...
+headers:
+    Cache-Control: no-cache
+---
+
+## Policies
+
+```js
+const connector = new Feature({
+    createPreference: {
+        'files.trimTrailingWhitespace': {
+            type: 'boolean',
+            default: false,
+            description: 'When enabled, will trim trailing whitespace when saving a file.',
+            settings: 'both',
+            enum: [],
+            enumDescriptions: [],
+            overridable: true,
+        },
+    },
+});
+const connector2 = new Feature({
+    createPreference: {
+        'files.autosave': {
+            type: 'boolean',
+            default: false,
+            description: 'Some Description',
+            settings: 'both',
+            enum: [],
+            enumDescriptions: [],
+            overridable: true,
+        },
+    },
+});
+
+const connector3 = new Feature({
+    overwritePreference: {
+        'files.trimTrailingWhitespace.default': true,
+    },
+});
+const connector4 = new Feature({
+    overwritePreference: {
+        'files.autosave.description': 'new one',
+    },
+});
+
+const feature = new Feature(connector, connector2, connector3, connector4);
+const finalPreferences = feature.getPreferences();
+
+expect(finalPreferences).toEqual(finalSettings);
+```

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

@@ -0,0 +1,57 @@
+---
+meta:
+    title: Preferences
+    description: Preferences
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Preferences...
+headers:
+    Cache-Control: no-cache
+---
+
+## Preferences
+
+```js
+const connector = new Feature({
+    createPreference: {
+        'files.trimTrailingWhitespace': {
+            type: 'boolean',
+            default: false,
+            description: 'When enabled, will trim trailing whitespace when saving a file.',
+            settings: 'both',
+            enum: [],
+            enumDescriptions: [],
+            overridable: true,
+        },
+    },
+});
+const connector2 = new Feature({
+    createPreference: {
+        'files.autosave': {
+            type: 'boolean',
+            default: false,
+            description: 'Some Description',
+            settings: 'both',
+            enum: [],
+            enumDescriptions: [],
+            overridable: true,
+        },
+    },
+});
+
+const connector3 = new Feature({
+    overwritePreference: {
+        'files.trimTrailingWhitespace.default': true,
+    },
+});
+const connector4 = new Feature({
+    overwritePreference: {
+        'files.autosave.description': 'new one',
+    },
+});
+
+const feature = new Feature(connector, connector2, connector3, connector4);
+const finalPreferences = feature.getPreferences();
+
+expect(finalPreferences).toEqual(finalSettings);
+```