@adaas/a-utils 0.1.6 → 0.1.8

package/src/lib/A-Manifest/README.md

@@ -0,0 +1,201 @@
+# A-Manifest Usage Guide
+
+The `A_Manifest` class provides a flexible configuration system for controlling component access and method permissions using regex patterns. It allows you to include or exclude components for particular methods based on sophisticated rule-based configurations.
+
+## Core Concepts
+
+### 1. **Component-Level Rules**
+Apply rules to all methods of a component:
+
+```typescript
+const manifest = new A_Manifest([
+    {
+        component: UserController,
+        exclude: [GuestUser] // Guests cannot access any UserController methods
+    }
+]);
+```
+
+### 2. **Method-Level Rules**
+Apply specific rules to individual methods:
+
+```typescript
+const manifest = new A_Manifest([
+    {
+        component: UserController,
+        methods: [
+            {
+                method: 'delete',
+                apply: [AdminUser, SuperAdmin] // Only admins can delete
+            },
+            {
+                method: 'post',
+                exclude: [GuestUser] // Guests cannot create
+            }
+        ]
+    }
+]);
+```
+
+### 3. **Regex Support**
+Use regex patterns for flexible matching:
+
+```typescript
+const manifest = new A_Manifest([
+    {
+        component: UserController,
+        methods: [
+            {
+                method: /^(post|put|delete)$/, // Match mutating operations
+                exclude: [GuestUser]
+            }
+        ]
+    }
+]);
+```
+
+## API Reference
+
+### Constructor
+```typescript
+new A_Manifest(config: A_UTILS_TYPES__Manifest_Init)
+```
+
+Creates a new manifest with the provided configuration.
+
+### isAllowed()
+```typescript
+isAllowed<T extends A_Component>(
+    ctor: T | A_TYPES__Component_Constructor<T>,
+    method: string
+): A_ManifestChecker
+```
+
+Returns a fluent checker to verify if access is allowed.
+
+**Usage:**
+```typescript
+const allowed = manifest.isAllowed(UserController, 'post').for(GuestUser);
+```
+
+### isExcluded()
+```typescript
+isExcluded<T extends A_Component>(
+    ctor: T | A_TYPES__Component_Constructor<T>,
+    method: string
+): A_ManifestChecker
+```
+
+Returns a fluent checker to verify if access is explicitly excluded.
+
+**Usage:**
+```typescript
+const excluded = manifest.isExcluded(UserController, 'post').for(GuestUser);
+```
+
+## Configuration Types
+
+### A_UTILS_TYPES__Manifest_ComponentLevelConfig
+```typescript
+{
+    component: A_TYPES__Component_Constructor<T>,
+    methods?: Array<A_UTILS_TYPES__Manifest_MethodLevelConfig<T>>,
+    apply?: Array<A_UTILS_TYPES__Manifest_AllowedComponents> | RegExp,
+    exclude?: Array<A_UTILS_TYPES__Manifest_AllowedComponents> | RegExp
+}
+```
+
+### A_UTILS_TYPES__Manifest_MethodLevelConfig
+```typescript
+{
+    method: string | RegExp,
+    apply?: Array<A_UTILS_TYPES__Manifest_AllowedComponents> | RegExp,
+    exclude?: Array<A_UTILS_TYPES__Manifest_AllowedComponents> | RegExp
+}
+```
+
+## Rule Precedence
+
+1. **Method-level rules** override component-level rules
+2. **Exclude rules** take precedence over apply rules
+3. **No rules** = allow by default
+
+## Advanced Examples
+
+### Example 1: Hierarchical Permissions
+```typescript
+const manifest = new A_Manifest([
+    {
+        component: UserController,
+        exclude: [GuestUser], // Base rule: no access for guests
+        methods: [
+            {
+                method: 'get',
+                apply: [GuestUser, RegisteredUser, AdminUser] // Override: guests can read
+            },
+            {
+                method: 'delete',
+                apply: [AdminUser] // Only admins can delete
+            }
+        ]
+    }
+]);
+```
+
+### Example 2: Using Regex for Complex Patterns
+```typescript
+const manifest = new A_Manifest([
+    {
+        component: AdminController,
+        methods: [
+            {
+                method: /^admin/, // Methods starting with "admin"
+                apply: [SuperAdmin] // Only super admins
+            },
+            {
+                method: /^(get|list)/, // Read operations
+                apply: [AdminUser, SuperAdmin] // All admins
+            }
+        ]
+    }
+]);
+```
+
+### Example 3: Multiple Components
+```typescript
+const manifest = new A_Manifest([
+    {
+        component: UserController,
+        exclude: [GuestUser]
+    },
+    {
+        component: AdminController,
+        apply: [AdminUser, SuperAdmin]
+    },
+    {
+        component: PublicController,
+        // No rules = accessible to all
+    }
+]);
+```
+
+## Best Practices
+
+1. **Start with restrictive rules** and add exceptions rather than the opposite
+2. **Use component-level rules** for broad access control
+3. **Use method-level rules** for fine-grained permissions
+4. **Leverage regex patterns** for dynamic method matching
+5. **Test your configurations** thoroughly with the provided fluent API
+
+## Error Handling
+
+The manifest will throw `A_ManifestError` for:
+- Invalid configuration structure
+- Non-component constructors in configuration
+- Malformed regex patterns
+
+## Performance Considerations
+
+- Rules are compiled to regex patterns during initialization
+- Runtime checks are optimized for fast pattern matching
+- Consider the number of rules when designing complex hierarchies

package/src/lib/A-Manifest/classes/A-ManifestChecker.class.ts

@@ -0,0 +1,24 @@
+import { A_TYPES__Component_Constructor } from "@adaas/a-concept";
+import { A_Manifest } from "../A-Manifest.context";
+
+/**
+ * Fluent API for checking manifest permissions
+ */
+export class A_ManifestChecker {
+    constructor(
+        private manifest: A_Manifest,
+        private component: A_TYPES__Component_Constructor,
+        private method: string,
+        private checkExclusion: boolean = false
+    ) {}
+
+    for(target: A_TYPES__Component_Constructor): boolean {
+        const result = this.manifest.internal_checkAccess({
+            component: this.component,
+            method: this.method,
+            target: target
+        });
+
+        return this.checkExclusion ? !result : result;
+    }
+}

package/tests/A-Manifest.test.ts

@@ -0,0 +1,290 @@
+import { A_Component } from "@adaas/a-concept";
+import { A_Manifest } from "../src/lib/A-Manifest/A-Manifest.context";
+
+describe('A_Manifest', () => {
+    it('Should deny access to excluded components at component level', () => {
+        class UserController extends A_Component {
+            get() { return 'user.get'; }
+            post() { return 'user.post'; }
+        }
+        class GuestUser extends A_Component {}
+        class RegisteredUser extends A_Component {}
+
+        const manifest = new A_Manifest([
+            {
+                component: UserController,
+                exclude: [GuestUser]
+            }
+        ]);
+
+        expect(manifest.isAllowed(UserController, 'get').for(GuestUser)).toBe(false);
+        expect(manifest.isAllowed(UserController, 'post').for(GuestUser)).toBe(false);
+        expect(manifest.isAllowed(UserController, 'get').for(RegisteredUser)).toBe(true);
+    });
+
+    it('Should allow access only to included components at component level', () => {
+        class AdminController extends A_Component {
+            get() { return 'admin.get'; }
+            adminPanel() { return 'admin.adminPanel'; }
+        }
+        class AdminUser extends A_Component {}
+        class SuperAdmin extends A_Component {}
+        class RegisteredUser extends A_Component {}
+
+        const manifest = new A_Manifest([
+            {
+                component: AdminController,
+                apply: [AdminUser, SuperAdmin]
+            }
+        ]);
+
+        expect(manifest.isAllowed(AdminController, 'get').for(RegisteredUser)).toBe(false);
+        expect(manifest.isAllowed(AdminController, 'get').for(AdminUser)).toBe(true);
+        expect(manifest.isAllowed(AdminController, 'adminPanel').for(SuperAdmin)).toBe(true);
+    });
+
+    it('Should respect method-level exclusion rules', () => {
+        class UserController extends A_Component {
+            get() { return 'user.get'; }
+            post() { return 'user.post'; }
+            delete() { return 'user.delete'; }
+        }
+        class GuestUser extends A_Component {}
+        class RegisteredUser extends A_Component {}
+        class AdminUser extends A_Component {}
+        class SuperAdmin extends A_Component {}
+
+        const manifest = new A_Manifest([
+            {
+                component: UserController,
+                methods: [
+                    {
+                        method: 'delete',
+                        apply: [AdminUser, SuperAdmin]
+                    },
+                    {
+                        method: 'post',
+                        exclude: [GuestUser]
+                    }
+                ]
+            }
+        ]);
+
+        expect(manifest.isAllowed(UserController, 'get').for(GuestUser)).toBe(true);
+        expect(manifest.isAllowed(UserController, 'post').for(GuestUser)).toBe(false);
+        expect(manifest.isAllowed(UserController, 'post').for(RegisteredUser)).toBe(true);
+        expect(manifest.isAllowed(UserController, 'delete').for(RegisteredUser)).toBe(false);
+        expect(manifest.isAllowed(UserController, 'delete').for(AdminUser)).toBe(true);
+    });
+
+    it('Should handle regex patterns for method matching', () => {
+        class UserController extends A_Component {
+            get() { return 'user.get'; }
+            post() { return 'user.post'; }
+            put() { return 'user.put'; }
+            delete() { return 'user.delete'; }
+        }
+        class GuestUser extends A_Component {}
+        class RegisteredUser extends A_Component {}
+
+        const manifest = new A_Manifest([
+            {
+                component: UserController,
+                methods: [
+                    {
+                        method: /^(post|put|delete)$/,
+                        exclude: [GuestUser]
+                    }
+                ]
+            }
+        ]);
+
+        expect(manifest.isAllowed(UserController, 'get').for(GuestUser)).toBe(true);
+        expect(manifest.isAllowed(UserController, 'post').for(GuestUser)).toBe(false);
+        expect(manifest.isAllowed(UserController, 'put').for(GuestUser)).toBe(false);
+        expect(manifest.isAllowed(UserController, 'delete').for(GuestUser)).toBe(false);
+        expect(manifest.isAllowed(UserController, 'post').for(RegisteredUser)).toBe(true);
+    });
+
+    it('Should allow method-level overrides of component-level rules', () => {
+        class UserController extends A_Component {
+            get() { return 'user.get'; }
+            post() { return 'user.post'; }
+        }
+        class AdminController extends A_Component {
+            get() { return 'admin.get'; }
+        }
+        class GuestUser extends A_Component {}
+        class RegisteredUser extends A_Component {}
+        class AdminUser extends A_Component {}
+        class SuperAdmin extends A_Component {}
+
+        const manifest = new A_Manifest([
+            {
+                component: UserController,
+                exclude: [GuestUser],
+                methods: [
+                    {
+                        method: 'get',
+                        apply: [GuestUser, RegisteredUser, AdminUser, SuperAdmin]
+                    }
+                ]
+            },
+            {
+                component: AdminController,
+                apply: [AdminUser, SuperAdmin]
+            }
+        ]);
+
+        // Method-level rule Should override component-level exclusion
+        expect(manifest.isAllowed(UserController, 'get').for(GuestUser)).toBe(true);
+        
+        // Component-level exclusion Should apply to methods without specific rules
+        expect(manifest.isAllowed(UserController, 'post').for(GuestUser)).toBe(false);
+        
+        // Other component rules Should work independently
+        expect(manifest.isAllowed(AdminController, 'get').for(RegisteredUser)).toBe(false);
+        expect(manifest.isAllowed(AdminController, 'get').for(AdminUser)).toBe(true);
+    });
+
+    it('Should work with isExcluded method', () => {
+        class UserController extends A_Component {
+            post() { return 'user.post'; }
+        }
+        class GuestUser extends A_Component {}
+        class RegisteredUser extends A_Component {}
+
+        const manifest = new A_Manifest([
+            {
+                component: UserController,
+                exclude: [GuestUser]
+            }
+        ]);
+
+        expect(manifest.isExcluded(UserController, 'post').for(GuestUser)).toBe(true);
+        expect(manifest.isExcluded(UserController, 'post').for(RegisteredUser)).toBe(false);
+    });
+
+    it('Should handle empty configuration and allow all by default', () => {
+        class UserController extends A_Component {
+            get() { return 'user.get'; }
+        }
+        class GuestUser extends A_Component {}
+
+        const manifest = new A_Manifest([]);
+
+        expect(manifest.isAllowed(UserController, 'get').for(GuestUser)).toBe(true);
+    });
+
+    it('Should handle component with no specific rules and allow all by default', () => {
+        class UserController extends A_Component {
+            get() { return 'user.get'; }
+        }
+        class GuestUser extends A_Component {}
+
+        const manifest = new A_Manifest([
+            {
+                component: UserController
+                // No apply or exclude rules
+            }
+        ]);
+
+        expect(manifest.isAllowed(UserController, 'get').for(GuestUser)).toBe(true);
+    });
+
+    it('Should apply component-level rules to all methods when no method rules exist', () => {
+        class UserController extends A_Component {
+            get() { return 'user.get'; }
+            post() { return 'user.post'; }
+        }
+        class GuestUser extends A_Component {}
+
+        const manifest = new A_Manifest([
+            {
+                component: UserController,
+                exclude: [GuestUser]
+            }
+        ]);
+
+        expect(manifest.isAllowed(UserController, 'get').for(GuestUser)).toBe(false);
+        expect(manifest.isAllowed(UserController, 'post').for(GuestUser)).toBe(false);
+        expect(manifest.isAllowed(UserController, 'anyMethod').for(GuestUser)).toBe(false);
+    });
+
+    it('Should throw error for invalid configuration type', () => {
+        expect(() => {
+            // @ts-ignore - Testing runtime error
+            new A_Manifest("invalid");
+        }).toThrow();
+    });
+
+    it('Should throw error for non-component constructor in configuration', () => {
+        class GuestUser extends A_Component {}
+
+        expect(() => {
+            new A_Manifest([
+                {
+                    // @ts-ignore - Testing runtime error
+                    component: "not-a-constructor",
+                    exclude: [GuestUser]
+                }
+            ]);
+        }).toThrow();
+    });
+
+    it('Should handle multiple method rules for the same component', () => {
+        class UserController extends A_Component {
+            get() { return 'user.get'; }
+            post() { return 'user.post'; }
+            put() { return 'user.put'; }
+            delete() { return 'user.delete'; }
+        }
+        class GuestUser extends A_Component {}
+        class RegisteredUser extends A_Component {}
+        class AdminUser extends A_Component {}
+
+        const manifest = new A_Manifest([
+            {
+                component: UserController,
+                methods: [
+                    {
+                        method: 'get',
+                        apply: [GuestUser, RegisteredUser, AdminUser]
+                    },
+                    {
+                        method: 'post',
+                        apply: [RegisteredUser, AdminUser]
+                    },
+                    {
+                        method: 'delete',
+                        apply: [AdminUser]
+                    }
+                ]
+            }
+        ]);
+
+        expect(manifest.isAllowed(UserController, 'get').for(GuestUser)).toBe(true);
+        expect(manifest.isAllowed(UserController, 'post').for(GuestUser)).toBe(false);
+        expect(manifest.isAllowed(UserController, 'post').for(RegisteredUser)).toBe(true);
+        expect(manifest.isAllowed(UserController, 'delete').for(RegisteredUser)).toBe(false);
+        expect(manifest.isAllowed(UserController, 'delete').for(AdminUser)).toBe(true);
+        expect(manifest.isAllowed(UserController, 'put').for(GuestUser)).toBe(true); // No rule = allow
+    });
+
+    it('Should prioritize exclude rules over apply rules', () => {
+        class UserController extends A_Component {
+            post() { return 'user.post'; }
+        }
+        class RegisteredUser extends A_Component {}
+
+        const manifest = new A_Manifest([
+            {
+                component: UserController,
+                apply: [RegisteredUser],
+                exclude: [RegisteredUser] // Exclude Should take precedence
+            }
+        ]);
+
+        expect(manifest.isAllowed(UserController, 'post').for(RegisteredUser)).toBe(false);
+    });
+});