@adaas/a-utils 0.1.7 → 0.1.9

package/src/lib/A-Manifest/A-Manifest.context.ts

@@ -0,0 +1,198 @@
+import { A_Component, A_Fragment, A_TypeGuards, A_TYPES__Component_Constructor } from "@adaas/a-concept";
+import { A_UTILS_TYPES__Manifest_Init, A_UTILS_TYPES__Manifest_ComponentLevelConfig, A_UTILS_TYPES__Manifest_AllowedComponents, A_UTILS_TYPES__ManifestRule, A_UTILS_TYPES__ManifestQuery } from "./A-Manifest.types";
+import { A_ManifestError } from "./A-Manifest.error";
+import { A_ManifestChecker } from "./classes/A-ManifestChecker.class";
+
+
+
+
+
+export class A_Manifest extends A_Fragment {
+
+    private rules: A_UTILS_TYPES__ManifestRule[] = [];
+
+    /**
+     * A-Manifest is a configuration set that allows to include or exclude component application for the particular methods.
+     *
+     * For example, if A-Scope provides polymorphic A-Component that applies for All A-Entities in it but you have another component that should be used for only One particular Entity, you can use A-Manifest to specify this behavior.
+     * 
+     * 
+     * By default if Component is provided in the scope - it applies for all entities in it. However, if you want to exclude some entities or include only some entities for the particular component - you can use A-Manifest to define this behavior.
+     * 
+     * @param config - Array of component configurations
+     */
+    constructor(config: A_UTILS_TYPES__Manifest_Init = []) {
+        super({
+            name: 'A-Manifest',
+        });
+
+        this.prepare(config);
+    }
+
+
+    /**
+     * Should convert received configuration into internal Regexp applicable for internal storage
+     */
+    protected prepare(config: A_UTILS_TYPES__Manifest_Init) {
+        if (!A_TypeGuards.isArray(config))
+            throw new A_ManifestError(
+                A_ManifestError.ManifestInitializationError,
+                `A-Manifest configuration should be an array of configurations`
+            );
+
+        for (const item of config) {
+            this.processConfigItem(item);
+        }
+    }
+
+    /**
+     * Process a single configuration item and convert it to internal rules
+     */
+    private processConfigItem(item: A_UTILS_TYPES__Manifest_ComponentLevelConfig) {
+        if (!A_TypeGuards.isComponentConstructor(item.component))
+            throw new A_ManifestError(
+                A_ManifestError.ManifestInitializationError,
+                `A-Manifest configuration item should be a A-Component constructor`
+            );
+
+        const componentRegex = this.constructorToRegex(item.component);
+
+        // Always add component-level rule first (applies to all methods)
+        if (item.apply || item.exclude) {
+            const methodRegex = /.*/; // Match all methods
+
+            this.rules.push({
+                componentRegex,
+                methodRegex,
+                applyRegex: item.apply ? this.allowedComponentsToRegex(item.apply) : undefined,
+                excludeRegex: item.exclude ? this.allowedComponentsToRegex(item.exclude) : undefined,
+            });
+        }
+
+        // Then add method-level configurations (these will override component-level)
+        if (item.methods && item.methods.length > 0) {
+            for (const methodConfig of item.methods) {
+                const methodRegex = this.methodToRegex(methodConfig.method);
+
+                this.rules.push({
+                    componentRegex,
+                    methodRegex,
+                    applyRegex: methodConfig.apply ? this.allowedComponentsToRegex(methodConfig.apply) : undefined,
+                    excludeRegex: methodConfig.exclude ? this.allowedComponentsToRegex(methodConfig.exclude) : undefined,
+                });
+            }
+        }
+    }
+
+
+
+    /**
+     * Convert a constructor to a regex pattern
+     */
+    private constructorToRegex(ctor: A_TYPES__Component_Constructor): RegExp {
+        return new RegExp(`^${this.escapeRegex(ctor.name)}$`);
+    }
+
+    /**
+     * Convert a method name or regex to a regex pattern
+     */
+    private methodToRegex(method: string | RegExp): RegExp {
+        if (method instanceof RegExp) {
+            return method;
+        }
+        return new RegExp(`^${this.escapeRegex(method as string)}$`);
+    }
+
+    /**
+     * Convert allowed components array or regex to a single regex
+     */
+    private allowedComponentsToRegex(components: A_UTILS_TYPES__Manifest_AllowedComponents[] | RegExp): RegExp {
+        if (components instanceof RegExp) {
+            return components;
+        }
+
+        const patterns = components.map(ctor => this.escapeRegex(ctor.name));
+        return new RegExp(`^(${patterns.join('|')})$`);
+    }
+
+    /**
+     * Escape special regex characters in a string
+     */
+    private escapeRegex(str: string): string {
+        return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+
+    protected configItemToRegexp(item: A_TYPES__Component_Constructor): RegExp {
+        return this.constructorToRegex(item);
+    }
+
+
+    protected ID(component: A_TYPES__Component_Constructor, method: string) {
+        return `${component.name}.${method}`;
+    }
+
+    /**
+     * Check if a component and method combination is allowed for a target
+     */
+    isAllowed<T extends A_Component>(
+        ctor: T | A_TYPES__Component_Constructor<T>,
+        method: string
+    ): A_ManifestChecker {
+        const componentCtor = typeof ctor === 'function' ? ctor : ctor.constructor as A_TYPES__Component_Constructor;
+        return new A_ManifestChecker(this, componentCtor, method);
+    }
+
+    /**
+     * Internal method to check if access is allowed
+     */
+    internal_checkAccess(query: A_UTILS_TYPES__ManifestQuery): boolean {
+        const componentName = query.component.name;
+        const methodName = query.method;
+        const targetName = query.target.name;
+
+        // Find matching rules, sorted by specificity (method-specific rules first)
+        const matchingRules = this.rules
+            .filter(rule =>
+                rule.componentRegex.test(componentName) &&
+                rule.methodRegex.test(methodName)
+            )
+            .sort((a, b) => {
+                // Method-specific rules (not .* pattern) should come before general rules
+                const aIsGeneral = a.methodRegex.source === '.*';
+                const bIsGeneral = b.methodRegex.source === '.*';
+
+                if (aIsGeneral && !bIsGeneral) return 1;  // b comes first
+                if (!aIsGeneral && bIsGeneral) return -1; // a comes first
+                return 0; // same priority
+            });
+
+        // If no rules match, allow by default
+        if (matchingRules.length === 0) {
+            return true;
+        }
+
+        // Process rules in order of specificity (most specific first)
+        for (const rule of matchingRules) {
+            // If this rule has an exclusion that matches, deny access
+            if (rule.excludeRegex && rule.excludeRegex.test(targetName)) {
+                return false;
+            }
+
+            // If this rule has an apply list, check if target is in it
+            if (rule.applyRegex) {
+                return rule.applyRegex.test(targetName);
+            }
+        }
+
+        // If we have rules but no specific apply/exclude, allow by default
+        return true;
+    }
+
+    isExcluded<T extends A_Component>(
+        ctor: T | A_TYPES__Component_Constructor<T>,
+        method: string
+    ): A_ManifestChecker {
+        const componentCtor = typeof ctor === 'function' ? ctor : ctor.constructor as A_TYPES__Component_Constructor;
+        return new A_ManifestChecker(this, componentCtor, method, true);
+    }
+}

package/src/lib/A-Manifest/A-Manifest.error.ts

@@ -0,0 +1,7 @@
+import { A_Error } from "@adaas/a-concept";
+
+export class A_ManifestError extends A_Error {
+
+    static readonly ManifestInitializationError = 'A-Manifest Initialization Error';
+
+}

package/src/lib/A-Manifest/A-Manifest.types.ts

@@ -0,0 +1,62 @@
+import { A_Component, A_Container, A_TYPES__Component_Constructor, A_TYPES__Entity_Constructor, A_TYPES__Fragment_Constructor } from "@adaas/a-concept"
+import { A_TYPES__Container_Constructor } from "@adaas/a-concept/dist/src/global/A-Container/A-Container.types"
+
+
+export type A_UTILS_TYPES__Manifest_Init = Array<A_UTILS_TYPES__Manifest_ComponentLevelConfig>
+
+
+
+export type A_UTILS_TYPES__Manifest_ComponentLevelConfig<T extends A_Component = A_Component> = {
+    /**
+     * Component constructor
+     */
+    component: A_TYPES__Component_Constructor<T>,
+    /**
+     * Method level configurations for the component
+     */
+    methods?: Array<A_UTILS_TYPES__Manifest_MethodLevelConfig<T>>
+} & Partial<A_UTILS_TYPES__Manifest_Rules>
+
+
+
+export type A_UTILS_TYPES__Manifest_MethodLevelConfig<T extends A_Component = A_Component> = {
+    /**
+     * Method name from the component provided
+     */
+    method: string | RegExp
+} & Partial<A_UTILS_TYPES__Manifest_Rules>
+
+
+
+export type A_UTILS_TYPES__Manifest_Rules = {
+    /**
+     * A list of entities to which a component is applied
+     * 
+     * By default is for all
+     */
+    apply: Array<A_UTILS_TYPES__Manifest_AllowedComponents> | RegExp
+    /**
+     * A list of entities to which a component is excluded
+     */
+    exclude: Array<A_UTILS_TYPES__Manifest_AllowedComponents> | RegExp
+}
+
+export type A_UTILS_TYPES__Manifest_AllowedComponents = A_TYPES__Component_Constructor
+    | A_TYPES__Entity_Constructor
+    | A_TYPES__Fragment_Constructor
+    | A_TYPES__Container_Constructor
+
+
+
+export interface A_UTILS_TYPES__ManifestRule {
+    componentRegex: RegExp;
+    methodRegex: RegExp;
+    applyRegex?: RegExp;
+    excludeRegex?: RegExp;
+}
+
+export interface A_UTILS_TYPES__ManifestQuery {
+    component: A_TYPES__Component_Constructor;
+    method: string;
+    target: A_TYPES__Component_Constructor;
+}

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;
+    }
+}