@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/server-side/slug-service.md

@@ -0,0 +1,323 @@
+# Developer Guide: Slug-Based URL Resolution System
+
+## Overview
+
+This document provides guidelines on implementing and using our slug-based URL resolution system. This system allows us to use human-readable identifiers in URLs (e.g., `/o/acme-corp/p/web-project`) while preserving the use of database IDs for internal operations.
+
+## Key Benefits
+
+- **User-Friendly URLs**: URLs contain readable names instead of database IDs
+- **SEO Optimization**: Improved search engine indexing with meaningful URLs
+- **Consistent API**: GraphQL queries accept slugs directly from URL parameters
+- **Clean Separation**: Resolution happens in the service layer, keeping API and data access layers clean
+
+## Architecture
+
+Our slug resolution system consists of:
+
+1. **Slug Resolvers**: Individual components that translate slugs to IDs for specific entity types
+2. **Slug Service**: Centralized service that coordinates all resolvers
+3. **Service Integration**: Entity services (Project, Organization, etc.) that utilize the slug service
+
+## Implementation Guide
+
+### 1. Slug Resolver Interface
+
+All slug resolvers implement a common interface:
+
+```typescript
+interface ISlugResolver {
+    type: string; // Entity type this resolver handles
+    resolve(slug: string, context?: any): Promise<string | null>; // Resolve slug to ID
+    validate?(slug: string): boolean; // Optional slug validation
+}
+```
+
+### 2. Creating a New Slug Resolver
+
+To add support for a new entity type (e.g., "feature"):
+
+```typescript
+@injectable()
+export class FeatureSlugResolver implements ISlugResolver {
+    public readonly type = 'feature';
+
+    constructor(
+        @inject('FeatureModel') private featureModel: mongoose.Model<any>,
+        @inject('Logger') private logger: CdmLogger.ILogger,
+    ) {
+        this.logger = logger.child({ className: FeatureSlugResolver.name });
+    }
+
+    async resolve(slug: string, context?: { projectId?: string }): Promise<string | null> {
+        try {
+            const query: any = { slug };
+
+            // Add project filter if provided
+            if (context?.projectId) {
+                query.project = new mongoose.Types.ObjectId(context.projectId);
+            }
+
+            const feature = await this.featureModel.findOne(query).lean();
+            return feature?._id?.toString() || null;
+        } catch (error) {
+            this.logger.error(`Error resolving feature slug '${slug}':`, error);
+            return null;
+        }
+    }
+
+    validate(slug: string): boolean {
+        return /^[a-z0-9-]{3,50}$/i.test(slug);
+    }
+}
+```
+
+### 3. Registering the Resolver
+
+Register your new resolver in the dependency injection container:
+
+```typescript
+// In your container configuration
+container.bind('SlugResolver').to(FeatureSlugResolver).whenTargetNamed('feature');
+container.bind('SlugResolver').to(FeatureSlugResolver); // Also bind without name for multiInject
+```
+
+### 4. Service Integration
+
+Update your service to leverage slug resolution:
+
+```typescript
+@injectable()
+export class FeatureService {
+    constructor(
+        @inject(SERVER_TYPES.IFeatureRepository) private featureRepository: IFeatureRepository,
+        @inject(SERVER_TYPES.SlugService) private slugService: SlugService,
+        @inject('Logger') private logger: CdmLogger.ILogger,
+    ) {
+        this.logger = logger.child({ className: FeatureService.name });
+    }
+
+    /**
+     * Get a feature using project and feature slugs
+     */
+    async getFeatureBySlug(featureSlug: string, projectSlug: string, orgSlug: string): Promise<IFeature> {
+        // First resolve the organization ID
+        const orgId = await this.slugService.resolveSlug('organization', orgSlug);
+        if (!orgId) {
+            throw new Error(`Organization with slug '${orgSlug}' not found`);
+        }
+
+        // Then resolve the project ID
+        const projectId = await this.slugService.resolveSlug('project', projectSlug, { orgId });
+        if (!projectId) {
+            throw new Error(`Project with slug '${projectSlug}' not found in organization '${orgSlug}'`);
+        }
+
+        // Finally resolve the feature ID
+        const featureId = await this.slugService.resolveSlug('feature', featureSlug, { projectId });
+        if (!featureId) {
+            throw new Error(`Feature with slug '${featureSlug}' not found in project '${projectSlug}'`);
+        }
+
+        // Get the feature by ID
+        return this.featureRepository.findById(featureId);
+    }
+
+    // Other methods...
+}
+```
+
+### 5. GraphQL Resolver Integration
+
+Create GraphQL resolvers that work directly with slugs:
+
+```typescript
+// In your GraphQL resolvers
+const resolvers = {
+    Query: {
+        getFeatureBySlug: async (_, { orgSlug, projectSlug, featureSlug }, { featureService }) => {
+            return featureService.getFeatureBySlug(featureSlug, projectSlug, orgSlug);
+        },
+
+        // Other resolvers...
+    },
+};
+```
+
+### 6. GraphQL Schema Definition
+
+Define GraphQL types that accept slugs:
+
+```graphql
+extend type Query {
+    getFeatureBySlug(orgSlug: String!, projectSlug: String!, featureSlug: String!): Feature
+
+    # Other queries...
+}
+```
+
+## Best Practices
+
+### Slug Format Guidelines
+
+- **Length**: 3-50 characters
+- **Characters**: Lowercase letters, numbers, hyphens
+- **Validation**: Implement `validate()` in your resolver to enforce rules
+- **Uniqueness**: Ensure slugs are unique within their parent context (e.g., projects within an organization)
+
+### Error Handling
+
+Always provide clear error messages when slugs can't be resolved:
+
+```typescript
+if (!projectId) {
+    throw new Error(`Project with slug '${projectSlug}' not found in organization '${orgSlug}'`);
+}
+```
+
+### Performance Considerations
+
+1. **Caching**: Consider caching frequently used slug resolutions
+2. **Database Indexes**: Ensure slug fields are indexed in your database schema
+3. **Batch Resolution**: Resolve multiple slugs in a single database query when possible
+
+### URL Structure Standards
+
+Follow these URL structure patterns:
+
+- `/o/:orgSlug` - Organization context
+- `/o/:orgSlug/w/:workspaceSlug` - Workspace within organization
+- `/o/:orgSlug/p/:projectSlug` - Project within organization
+- `/o/:orgSlug/p/:projectSlug/f/:featureSlug` - Feature within project
+
+### Security Considerations
+
+- **Validate Input**: Always validate slug format before querying the database
+- **Access Control**: Apply authorization checks after slug resolution
+- **Injection Prevention**: Use parameterized queries when resolving slugs
+
+## Testing
+
+### Unit Testing Resolvers
+
+```typescript
+describe('ProjectSlugResolver', () => {
+    it('should resolve a valid project slug', async () => {
+        // Setup test
+        const mockProjectModel = {
+            findOne: jest.fn().mockReturnValue({
+                lean: jest.fn().mockResolvedValue({ _id: 'project123', slug: 'web-app' }),
+            }),
+        };
+
+        const resolver = new ProjectSlugResolver(mockProjectModel, mockLogger);
+
+        // Test
+        const result = await resolver.resolve('web-app', { orgId: 'org123' });
+
+        // Assertions
+        expect(result).toBe('project123');
+        expect(mockProjectModel.findOne).toHaveBeenCalledWith({
+            slug: 'web-app',
+            organization: expect.any(Object), // MongoDB ObjectId
+        });
+    });
+
+    // Other tests...
+});
+```
+
+### Integration Testing
+
+Test the full flow from GraphQL resolver to database:
+
+```typescript
+describe('Feature GraphQL API', () => {
+    it('should fetch a feature by slugs', async () => {
+        // Setup test data in database
+
+        // Execute query
+        const result = await graphql({
+            schema,
+            source: `
+                query {
+                    getFeatureBySlug(
+                        orgSlug: "acme-corp",
+                        projectSlug: "web-app",
+                        featureSlug: "login-page"
+                    ) {
+                        id
+                        name
+                        description
+                    }
+                }
+            `,
+        });
+
+        // Assertions
+        expect(result.errors).toBeUndefined();
+        expect(result.data.getFeatureBySlug).toEqual({
+            id: expect.any(String),
+            name: 'Login Page',
+            description: 'User authentication feature',
+        });
+    });
+});
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Slug Not Found**: Verify the slug exists in the database and check case sensitivity
+2. **Hierarchical Resolution Failing**: Ensure parent entities exist and are correctly linked
+3. **Performance Issues**: Check database indexes on slug fields
+
+### Debugging Tips
+
+1. Enable debug logging in the slug service:
+
+```typescript
+this.logger.debug(`Resolving ${type} slug: ${slug} with context:`, context);
+```
+
+2. Use the MongoDB shell to verify slug existence:
+
+```
+db.projects.findOne({ slug: "web-app", organization: ObjectId("...") })
+```
+
+## Example Implementation Walkthrough
+
+### 1. Resolve Organization Slug
+
+```typescript
+// Get the organization ID from the slug
+const orgId = await slugService.resolveOrganizationSlug('acme-corp');
+// orgId = "507f1f77bcf86cd799439011"
+```
+
+### 2. Resolve Project Slug Within Organization
+
+```typescript
+// Get the project ID from the slug, within the organization context
+const projectId = await slugService.resolveProjectSlug('web-app', orgId);
+// projectId = "507f1f77bcf86cd799439012"
+```
+
+### 3. Use IDs for Database Operations
+
+```typescript
+// Now use the IDs for your database operations
+const project = await projectRepository.findById(projectId);
+```
+
+## Further Resources
+
+- Dependency Injection: [InversifyJS Documentation](https://inversify.io/)
+- GraphQL: [Apollo Server Documentation](https://www.apollographql.com/docs/apollo-server/)
+- MongoDB: [Mongoose Documentation](https://mongoosejs.com/)
+
+## Conclusion
+
+By following these guidelines, you can implement a clean, efficient slug resolution system that provides user-friendly URLs while maintaining type safety and performance in your backend operations. This system scales well with the addition of new entity types and maintains a clear separation of concerns across your application layers.

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

@@ -0,0 +1,18 @@
+---
+meta:
+    title: Tests
+    description: Tests
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Tests...
+headers:
+    Cache-Control: no-cache
+---
+
+## Tests
+
+**[Known Errors](/docs/tests/known-errors)**
+
+**[Jest template for Backend Services that connects to Mock MongoDB](/docs/tests/service-test-template)**
+
+**[Test Setup](/docs/tests/test-setup)**

package/lib/templates/content/docs/tests/jest-test-debug-vscode.md

@@ -0,0 +1,40 @@
+---
+meta:
+    title: Jest Test Debug
+    description: Jest Test Debug
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Jest Test Debug...
+headers:
+    Cache-Control: no-cache
+---
+
+## Jest Test Debug VScode
+
+1. Find the test file and test pattern you want to test.
+
+It is good to debug individual "test"
+
+for example:
+
+If I want to test only below
+
+<img width="1425" alt="image" src="https://user-images.githubusercontent.com/3382355/234813745-c05bc64d-10c1-4257-95f4-8729aa9fc578.png"/>
+
+Using lerna we use following command
+
+`lerna exec --scope=<package_name> 'yarn test Configuration.test -- -t "Test update value"'`
+
+2. To test with vscode debugger update the package path and test args under `.vscode/launch.json`
+
+<img width="1426" alt="image" src="https://user-images.githubusercontent.com/3382355/234815929-08111211-4d03-4117-865c-16b85e47fb23.png"/>
+
+3. And run the default test.
+
+Don't push the changes as it is for your internal testing only.
+
+<img width="597" alt="image" src="https://user-images.githubusercontent.com/3382355/234816355-280ba401-964f-48aa-930a-dae3fafba03d.png"/>
+
+4. Put debugger where you want to debug.
+
+<img width="1665" alt="image" src="https://user-images.githubusercontent.com/3382355/234816878-d0eeb3aa-4bea-45b1-a7be-0f60d5e6251f.png"/>

package/lib/templates/content/docs/tests/known-errors.md

@@ -0,0 +1,116 @@
+---
+meta:
+    title: Known Errors
+    description: Known Errors
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Known Errors...
+headers:
+    Cache-Control: no-cache
+---
+
+## Known Errors
+
+#### TypeError: Reflect.hasOwnMetadata is not a function
+
+```
+$ jest compatible.test
+ FAIL  src/components/Layout/components/compatible.test.tsx
+  ● Test suite failed to run
+
+    TypeError: Reflect.hasOwnMetadata is not a function
+
+      at ../../node_modules/inversify/src/annotation/injectable.ts:7:17
+```
+
+Solution:
+
+Include `import 'reflect-metadata';` at the top of the test file.
+
+#### ESM files need to be added to transformation
+
+```
+$ jest compatible.test
+ FAIL  src/components/Layout/components/compatible.test.tsx
+  ● Test suite failed to run
+
+    Jest encountered an unexpected token
+
+    This usually means that you are trying to import a file which Jest cannot parse, e.g. it's not plain JavaScript.
+
+    By default, if Jest sees a Babel config, it will use that to transform your files, ignoring "node_modules".
+
+    Here's what you can do:
+     • If you are trying to use ECMAScript Modules, see https://jestjs.io/docs/en/ecmascript-modules for how to enable it.
+     • To have some of your "node_modules" files transformed, you can specify a custom "transformIgnorePatterns" in your config.
+     • If you need a custom transformation specify a "transform" option in your config.
+     • If you simply want to mock your non-JS modules (e.g. binary assets) you can stub them out with the "moduleNameMapper" config option.
+
+    You'll find more details and examples of these config options in the docs:
+    https://jestjs.io/docs/en/configuration.html
+
+    Details:
+
+    /Users/veeramarni/Documents/development/workspace/projects/IDE/admin-layout/node_modules/@adminide-stack/user-auth0-client/lib/index.js:1
+```
+
+Solution:
+
+Jest throws error when `esm` files are used. They need to be added to `transformIgnorePatterns` in `jest.config.js` file.
+
+For example
+
+```
+    transformIgnorePatterns: [
+        '/node_modules/(?!(@vscode-alt/monaco-editor|@files-stack/server-core|@adminide-stack/platform-browser|@adminide-stack/platform-client|abortable-rx|@adminide-stack/user-auth0-client|lodash-es|react-dnd-html5-backend|react-sortable-tree|react-dnd|dnd-core)/).+\\.js$',
+    ],
+```
+
+#### Envalid need the required env variables to be available
+
+```
+$ jest compatible.test
+  ●  process.exit called with "1"
+
+      at defaultReporter (../../node_modules/envalid/src/reporter.ts:67:13
+```
+
+Solution:
+
+Test cases also need to have environment variables available when you using a package that uses `envalid`.
+
+```
+// make sure `processe.env.ENV_FILE` points
+// to `config/test/test.env` and file should exist.
+
+// package.json will have script for
+// `"test": "cross-env ENV_FILE=../../config/test/test.env jest",`
+
+require('dotenv').config({ path: process.env.ENV_FILE });
+```
+
+#### Cannot read property 'child' of undefined on React 17
+
+```
+ TypeError: Cannot read property 'child' of undefined
+
+      25 |
+      26 |
+    > 27 | const wrapper = mount(
+         |                 ^
+      28 |     <Provider store={ store } >
+      29 |         <DeleteEventFab />
+      30 |     </Provider>
+
+      at getFiber (node_modules/enzyme-adapter-react-16/src/detectFiberTags.js:15:35)
+      at detectFiberTags (node_modules/enzyme-adapter-react-16/src/detectFiberTags.js:76:15)
+      at ReactSixteenAdapter.createMountRenderer (node_modules/enzyme-adapter-react-16/src/ReactSixteenAdapter.js:465:19)
+      at ReactSixteenAdapter.createRenderer (node_modules/enzyme-adapter-react-16/src/ReactSixteenAdapter.js:820:51)
+      at new ReactWrapper (node_modules/enzyme/src/ReactWrapper.js:113:32)
+      at mount (node_modules/enzyme/src/mount.js:10:10)
+      at Object.<anonymous> (src/tests/components/DeleteEventFab.test.js:27:17)
+```
+
+Solution:
+
+Enzyme adapter and react needs to be on same version. Inorder to make it work for react-17 we need to utilize this import `import Adapter from '@wojtekmaj/enzyme-adapter-react-17';`

package/lib/templates/content/docs/tests/service-test-template.md

@@ -0,0 +1,118 @@
+---
+meta:
+    title: Service Test Template
+    description: Service Test Template
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Service Test Template...
+headers:
+    Cache-Control: no-cache
+---
+
+## Service Test Template
+
+# Jest template for Backend Services that connects to Mock MongoDB
+
+### Step 1. Jest config file within the package
+
+Provide the related jest configuration and mock mongo configuration.
+
+Here are relative path (`../../../`) is based on the package related to the root.
+
+```
+const base = require('../../../jest.config.base');
+const packageJson = require('./package');
+const merge = require('merge')
+const baseConfig = require('../../../jest.config.base');
+const mongodbConfig = require('../../../jest.config.mongodb');
+
+const mergeData = merge.recursive(
+    baseConfig,
+    {
+        "transform": {
+            "\\.(js|jsx)?$": "../../../transform.js",
+        },
+        moduleNameMapper: {
+            '^__mocks__/(.*)$': '<rootDir>/../../__mocks__/$1',
+            // we'll use commonjs version of lodash for tests 👌
+            // because we don't need to use any kind of tree shaking right?!
+            '^lodash-es$': '<rootDir>/../../../node_modules/lodash/index.js',
+            '@adminide-stack\/core': '<rootDir>/../../adminide-core/src/index.ts',
+        },
+        roots: [
+            "src",
+        ],
+    },
+    mongodbConfig,
+    {
+        globals: {
+
+        }
+    }
+);
+
+module.exports = mergeData;
+```
+
+### Step 2. Make sure you have test.env file under `config/test`
+
+You can copy the existing `dev.env` values in `test.env` unless you want to modify anything based on your testing need.
+
+### Step 3. Create test file like `AccountService.test.ts` within the same folder where you have `AccountService.ts`
+
+```
+import 'reflect-metadata';
+import * as MongoDB from 'mongodb';
+import { connection as mongooseConnection } from 'mongoose';
+import mongoose from 'mongoose';
+import { config } from 'dotenv';
+import { logger } from '@cdm-logger/server';
+import { AccountRepository } from '../../store/repositories/account-repository';
+import { AccountService } from './account-service';
+import * as data from './fixtures/account-fixture.json';
+config({ path: process.env.ENV_FILE });
+
+// needed for all test cases
+async function dropAllCollections() {
+    const collections = Object.keys(mongooseConnection.collections);
+    for (const collectionName of collections) {
+        const collection = mongooseConnection.collections[collectionName];
+        try {
+            await collection.drop();
+        } catch (error) {
+            // Sometimes this error happens, but you can safely ignore it
+            if (error.message === 'ns not found') return;
+            // This error occurs when you use it.todo. You can
+            // safely ignore this error too
+            if (error.message.includes('a background operation is currently running')) return;
+            console.log(error.message);
+        }
+    }
+}
+
+describe('test Create/Update/Delete Account Service', () => {
+    let db: MongoDB.Db;
+    let connection: MongoDB.MongoClient;
+    let accountRepo: AccountRepository;
+    let accountService: AccountService;
+    beforeAll(async () => {
+        const conn = mongoose.createConnection(process.env.MONGO_URL, { dbName: 'jest' });
+        accountRepo = new AccountRepository(conn, logger);
+        accountService = new AccountService(logger, accountRepo);
+    });
+    afterAll(async () => {
+        await dropAllCollections();
+        connection.close();
+    });
+
+    it('service ', async() => {
+        await accountRepo.create(data);
+        const result = await accountRepo.getAll({});
+        ........
+
+    });
+});
+
+```
+
+### Step 4. Now run test using `lerna exec --scope=<package name\> yarn test <test file\>`