assemblerjs 1.1.24 → 1.1.26

package/README.md

@@ -25,6 +25,7 @@ A modern, type-safe, and lightweight [Dependency Injection](https://en.wikipedia
 - ♻️ **Lifecycle Hooks** - `onRegister`, `onInit`, `onDispose`
 - 📡 **Built-in Event System** - Integrated EventManager
 - 🔀 **AOP/Transversals** - Cross-cutting concerns (logging, security, caching, performance)
+  - 🎯 **Caller Tracking** - Audit logging, authorization, and request tracing with full caller context
 - 🎨 **Custom Decorators** - Easy creation with `ParameterDecoratorFactory` and `createConstructorDecorator`
 - 🔧 **Flexible Configuration** - Runtime configuration override
 - 🏷️ **Tags Support** - Group and retrieve dependencies by tags

package/dist/index.d.ts

@@ -467,6 +467,14 @@ declare interface Buildable<T> {
     configuration: Record<string, any>;
 }
 
+/**
+ * Metadata about a woven instance caller
+ */
+declare interface CallerMetadata {
+    className: string;
+    identifier?: string | symbol;
+}
+
 /**
  * Injection binds a concrete class to itself as identifier
  * and provides a configuration object that will be passed to context.
@@ -1357,6 +1365,140 @@ export declare interface TransversalMetadata {
     instance?: any;
 }
 
+/**
+ * TransversalWeaver handles the weaving of aspects onto target instances.
+ * It creates Proxy wrappers to intercept method calls and apply advices.
+ */
+export declare class TransversalWeaver {
+    /**
+     * Registry mapping woven proxy instances to their caller metadata.
+     * Uses WeakMap to allow garbage collection of instances.
+     */
+    private static callerRegistry;
+    /**
+     * Stack context for caller information.
+     * Independent of Transversals - works even without any engaged aspects.
+     * Allows tracking callers from external sources (Vue, Node, etc).
+     */
+    private static callerStack;
+    /**
+     * Register caller metadata for a woven instance.
+     * This allows manual registration if needed beyond automatic weaving.
+     *
+     * @param instance The woven instance
+     * @param className The name of the calling class
+     * @param identifier Optional identifier of the caller
+     */
+    static registerCaller<T extends object>(instance: T, className: string, identifier?: string | symbol): void;
+    /**
+     * Get the caller metadata for a woven instance.
+     *
+     * @param instance The woven instance
+     * @returns The caller metadata or undefined if not found
+     */
+    static getCallerMetadata(instance: object): CallerMetadata | undefined;
+    /**
+     * Execute a function with caller context.
+     * The caller info will be available in Transversal advices if present,
+     * or accessible via getCurrentCaller() at any time.
+     *
+     * Works with or without Transversals engaged.
+     *
+     * @param caller The name of the calling component/class
+     * @param identifier Optional identifier (class reference, symbol, etc)
+     * @param fn The function to execute
+     * @returns The result of the function (may be a Promise)
+     *
+     * @example
+     * ```typescript
+     * // From Vue component
+     * TransversalWeaver.withCaller('MyVueComponent', () => {
+     *   await userService.save(data);
+     * });
+     *
+     * // From Node with identifier
+     * TransversalWeaver.withCaller('UserService', UserService, () => {
+     *   await dataService.process();
+     * });
+     * ```
+     */
+    static withCaller<T>(caller: string, identifier?: string | symbol | (() => T | Promise<T>), fn?: () => T | Promise<T>): T | Promise<T>;
+    /**
+     * Wrap a function with caller context.
+     * Returns a new function that will execute with the specified caller context.
+     * Useful for creating wrapped functions that can be called multiple times.
+     *
+     * @param caller The name of the calling component/class
+     * @param identifier Optional identifier (class reference, symbol, etc)
+     * @param fn The function to wrap
+     * @returns A wrapped function that maintains caller context on each call
+     *
+     * @example
+     * ```typescript
+     * // In Vue component
+     * const mergeClasses = TransversalWeaver.wrapCaller(
+     *   'LeafletMap',
+     *   'LeafletMap.vue',
+     *   (...args: any[]) => tailwind.mergeClasses(...args)
+     * );
+     *
+     * // Now each call maintains the caller context
+     * mergeClasses('class1', 'class2'); // Advices see caller: LeafletMap
+     * ```
+     */
+    static wrapCaller<T extends (...args: any[]) => any>(caller: string, identifier?: string | symbol | T, fn?: T): T;
+    /**
+     * Get the current caller metadata from the context stack.
+     * Returns undefined if no caller context is active.
+     * Works even if no Transversal is engaged.
+     *
+     * @returns The current caller metadata or undefined
+     *
+     * @example
+     * ```typescript
+     * TransversalWeaver.withCaller('MyComponent', () => {
+     *   const caller = TransversalWeaver.getCurrentCaller();
+     *   console.log(caller?.className); // 'MyComponent'
+     * });
+     * ```
+     */
+    static getCurrentCaller(): CallerMetadata | undefined;
+    /**
+     * Weaves transversals onto an instance.
+     * Returns a Proxy if transversals apply, otherwise returns the original instance.
+     *
+     * @param instance The instance to weave transversals onto
+     * @param concrete The concrete class of the instance
+     * @param context The assembler context
+     * @returns The woven instance (may be a Proxy)
+     */
+    static weave<T>(instance: T, concrete: Concrete<T>, context: AssemblerContext): T;
+    /**
+     * Executes the advice chain (before -> around -> method -> after).
+     * Handles both synchronous and asynchronous execution.
+     *
+     * @param advices The advices to execute
+     * @param originalMethod The original method to call
+     * @param target The target instance
+     * @param args The method arguments
+     * @param joinPoint The join point information
+     * @returns The method result (may be a Promise)
+     */
+    private static executeAdviceChain;
+    /**
+     * Builds the proceed chain for around advices.
+     * Each advice can call proceed() to continue to the next advice or the original method.
+     *
+     * @param aroundAdvices The around advices to chain
+     * @param originalMethod The original method
+     * @param target The target instance
+     * @param args The method arguments
+     * @param joinPoint The join point information
+     * @returns The result of the advice chain
+     */
+    private static buildAroundChain;
+}
+
 /**
  * Injects an object passed with `string`, `symbol` or abstract class identifier.
  * The identifier can be:

package/dist/index.js

@@ -14,19 +14,20 @@ const eventManager_abstract = require('./index10.js');
 const decorators = require('./index11.js');
 const affect = require('./index12.js');
 const transversalManager = require('./index13.js');
-const abstract$1 = require('./index14.js');
-const _await = require('./index15.js');
-const indexFactory = require('./index16.js');
-const parameterDecoratorFactory = require('./index17.js');
-const context = require('./index18.js');
-const configuration = require('./index19.js');
-const definition = require('./index20.js');
-const dispose = require('./index21.js');
-const use = require('./index22.js');
-const global = require('./index23.js');
-const optional = require('./index24.js');
-const helpers$1 = require('./index25.js');
-const constructorDecorator = require('./index26.js');
+const transversalWeaver = require('./index14.js');
+const abstract$1 = require('./index15.js');
+const _await = require('./index16.js');
+const indexFactory = require('./index17.js');
+const parameterDecoratorFactory = require('./index18.js');
+const context = require('./index19.js');
+const configuration = require('./index20.js');
+const definition = require('./index21.js');
+const dispose = require('./index22.js');
+const use = require('./index23.js');
+const global = require('./index24.js');
+const optional = require('./index25.js');
+const helpers$1 = require('./index26.js');
+const constructorDecorator = require('./index27.js');
 
 
 
@@ -49,6 +50,7 @@ exports.Transversal = decorators.Transversal;
 exports.isTransversal = decorators.isTransversal;
 exports.Affect = affect.Affect;
 exports.TransversalManager = transversalManager.TransversalManager;
+exports.TransversalWeaver = transversalWeaver.TransversalWeaver;
 exports.AbstractTransversal = abstract$1.AbstractTransversal;
 exports.Await = _await.Await;
 exports.createParamIndexDecorator = indexFactory.createParamIndexDecorator;

package/dist/index.mjs

@@ -10,16 +10,17 @@ export { AbstractEventManager } from './index10.mjs';
 export { After, Around, Before, Transversal, isTransversal } from './index11.mjs';
 export { Affect } from './index12.mjs';
 export { TransversalManager } from './index13.mjs';
-export { AbstractTransversal } from './index14.mjs';
-export { Await } from './index15.mjs';
-export { createParamIndexDecorator } from './index16.mjs';
-export { ParameterDecoratorFactory } from './index17.mjs';
-export { Context } from './index18.mjs';
-export { Configuration } from './index19.mjs';
-export { Definition } from './index20.mjs';
-export { Dispose } from './index21.mjs';
-export { Use, decorateUse } from './index22.mjs';
-export { Global, decorateGlobal } from './index23.mjs';
-export { Optional } from './index24.mjs';
-export { getDecoratedParametersIndexes, getParamIndexKey, getParamValueKey, getParameterIndexes, getParameterValues } from './index25.mjs';
-export { ConstructorDecorator, createConstructorDecorator } from './index26.mjs';
+export { TransversalWeaver } from './index14.mjs';
+export { AbstractTransversal } from './index15.mjs';
+export { Await } from './index16.mjs';
+export { createParamIndexDecorator } from './index17.mjs';
+export { ParameterDecoratorFactory } from './index18.mjs';
+export { Context } from './index19.mjs';
+export { Configuration } from './index20.mjs';
+export { Definition } from './index21.mjs';
+export { Dispose } from './index22.mjs';
+export { Use, decorateUse } from './index23.mjs';
+export { Global, decorateGlobal } from './index24.mjs';
+export { Optional } from './index25.mjs';
+export { getDecoratedParametersIndexes, getParamIndexKey, getParamValueKey, getParameterIndexes, getParameterValues } from './index26.mjs';
+export { ConstructorDecorator, createConstructorDecorator } from './index27.mjs';

package/dist/index11.js

@@ -2,10 +2,10 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-const constants = require('./index28.js');
-const reflection = require('./index36.js');
+const constants = require('./index29.js');
+const reflection = require('./index30.js');
 const decorator = require('./index2.js');
-const schema = require('./index38.js');
+const schema = require('./index31.js');
 
 function isTransversal(e) {
     try {

package/dist/index11.mjs

@@ -1,7 +1,7 @@
-import { ReflectValue } from './index28.mjs';
-import { getCustomMetadata, defineCustomMetadata } from './index36.mjs';
+import { ReflectValue } from './index29.mjs';
+import { getCustomMetadata, defineCustomMetadata } from './index30.mjs';
 import { Assemblage } from './index2.mjs';
-import { getDefinition } from './index38.mjs';
+import { getDefinition } from './index31.mjs';
 
 function isTransversal(e) {
     try {

package/dist/index12.js

@@ -2,8 +2,8 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-require('./index27.js');
-const constants = require('./index28.js');
+require('./index28.js');
+const constants = require('./index29.js');
 
 function Affect(t, f) {
     return function(o, c, n) {

package/dist/index12.mjs

@@ -1,5 +1,5 @@
-import './index27.mjs';
-import { ReflectValue } from './index28.mjs';
+import './index28.mjs';
+import { ReflectValue } from './index29.mjs';
 
 function Affect(t, f) {
     return function(o, c, n) {

package/dist/index13.js

@@ -5,7 +5,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const core = require('@assemblerjs/core');
 const pointcutMatcher = require('./index41.js');
 const affect = require('./index12.js');
-const schema = require('./index38.js');
+const schema = require('./index31.js');
 
 class TransversalManager {
     static getInstance(e) {

package/dist/index13.mjs

@@ -1,7 +1,7 @@
 import { isClass } from '@assemblerjs/core';
 import { PointcutMatcher } from './index41.mjs';
 import { getAffectedMethods } from './index12.mjs';
-import { getDefinition } from './index38.mjs';
+import { getDefinition } from './index31.mjs';
 
 class TransversalManager {
     static getInstance(e) {

package/dist/index14.js

@@ -2,8 +2,173 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-class AbstractTransversal {
-    static onRegister(s, t) {}
+const transversalManager = require('./index13.js');
+const affect = require('./index12.js');
+
+class TransversalWeaver {
+    static registerCaller(t, e, r) {
+        this.callerRegistry.set(t, {
+            className: e,
+            identifier: r
+        });
+    }
+    static getCallerMetadata(t) {
+        return this.callerRegistry.get(t);
+    }
+    static withCaller(t, e, r) {
+        if (typeof e === 'function') {
+            r = e;
+            e = undefined;
+        }
+        const n = {
+            className: t,
+            identifier: e
+        };
+        this.callerStack.push(n);
+        const a = r();
+        if (a instanceof Promise) {
+            return a.finally(()=>this.callerStack.pop());
+        }
+        this.callerStack.pop();
+        return a;
+    }
+    static wrapCaller(t, e, r) {
+        if (typeof e === 'function') {
+            r = e;
+            e = undefined;
+        }
+        const n = {
+            className: t,
+            identifier: e
+        };
+        return (...t)=>{
+            this.callerStack.push(n);
+            try {
+                const e = r(...t);
+                if (e instanceof Promise) {
+                    return e.finally(()=>this.callerStack.pop());
+                }
+                this.callerStack.pop();
+                return e;
+            } catch (t) {
+                this.callerStack.pop();
+                throw t;
+            }
+        };
+    }
+    static getCurrentCaller() {
+        return this.callerStack[this.callerStack.length - 1];
+    }
+    static weave(r, n, a) {
+        const s = transversalManager.TransversalManager.getInstance(a);
+        const c = s.getAspectsForTarget(n);
+        const l = Object.getPrototypeOf(r);
+        const o = Object.getOwnPropertyNames(l).some((t)=>{
+            if (t === 'constructor') return false;
+            const r = Object.getOwnPropertyDescriptor(l, t);
+            if (!r) return false;
+            const n = r.value && typeof r.value === 'function';
+            const a = r.get && typeof r.get === 'function';
+            if (!n && !a) return false;
+            const s = affect.getAffectedMethods(l, t);
+            return s.length > 0;
+        });
+        if (c.length === 0 && !o) {
+            return r;
+        }
+        const i = new Proxy(r, {
+            get (t, e, r) {
+                const n = Reflect.get(t, e, r);
+                if (typeof n !== 'function') {
+                    return n;
+                }
+                return function(...r) {
+                    const a = String(e);
+                    const l = TransversalWeaver.getCurrentCaller() ?? TransversalWeaver.callerRegistry.get(this);
+                    const o = {
+                        target: t,
+                        methodName: a,
+                        args: r,
+                        caller: l?.className,
+                        callerIdentifier: l?.identifier
+                    };
+                    const i = s.getAdvicesForJoinPoint(o, c, t, e);
+                    return TransversalWeaver.executeAdviceChain(i, n, t, r, o);
+                };
+            }
+        });
+        TransversalWeaver.callerRegistry.set(i, {
+            className: n.name,
+            identifier: n.name
+        });
+        return i;
+    }
+    static executeAdviceChain(t, e, r, n, a) {
+        const s = t.filter((t)=>t.type === 'before');
+        const c = t.filter((t)=>t.type === 'around');
+        const l = t.filter((t)=>t.type === 'after');
+        try {
+            for (const t of s){
+                const e = {
+                    ...a,
+                    config: t.config
+                };
+                t.method.call(t.transversalInstance, e);
+            }
+            let t;
+            if (c.length > 0) {
+                t = this.buildAroundChain(c, e, r, n, a);
+            } else {
+                t = e.apply(r, n);
+            }
+            if (t instanceof Promise) {
+                return t.then((t)=>{
+                    for (const e of l){
+                        const r = {
+                            ...a,
+                            result: t
+                        };
+                        e.method.call(e.transversalInstance, r);
+                    }
+                    return t;
+                }).catch((t)=>{
+                    a.error = t;
+                    throw t;
+                });
+            }
+            for (const e of l){
+                const r = {
+                    ...a,
+                    result: t,
+                    config: e.config
+                };
+                e.method.call(e.transversalInstance, r);
+            }
+            return t;
+        } catch (t) {
+            a.error = t;
+            throw t;
+        }
+    }
+    static buildAroundChain(t, e, r, n, a) {
+        let s = 0;
+        const c = ()=>{
+            if (s < t.length) {
+                const e = t[s++];
+                const r = {
+                    ...a,
+                    proceed: c,
+                    config: e.config
+                };
+                return e.method.call(e.transversalInstance, r);
+            } else {
+                return e.apply(r, n);
+            }
+        };
+        return c();
+    }
 }
+TransversalWeaver.callerRegistry = new WeakMap();
+TransversalWeaver.callerStack = [];
 
-exports.AbstractTransversal = AbstractTransversal;
+exports.TransversalWeaver = TransversalWeaver;

package/dist/index14.mjs

@@ -1,5 +1,170 @@
-class AbstractTransversal {
-    static onRegister(s, t) {}
+import { TransversalManager } from './index13.mjs';
+import { getAffectedMethods } from './index12.mjs';
+
+class TransversalWeaver {
+    static registerCaller(t, e, r) {
+        this.callerRegistry.set(t, {
+            className: e,
+            identifier: r
+        });
+    }
+    static getCallerMetadata(t) {
+        return this.callerRegistry.get(t);
+    }
+    static withCaller(t, e, r) {
+        if (typeof e === 'function') {
+            r = e;
+            e = undefined;
+        }
+        const n = {
+            className: t,
+            identifier: e
+        };
+        this.callerStack.push(n);
+        const a = r();
+        if (a instanceof Promise) {
+            return a.finally(()=>this.callerStack.pop());
+        }
+        this.callerStack.pop();
+        return a;
+    }
+    static wrapCaller(t, e, r) {
+        if (typeof e === 'function') {
+            r = e;
+            e = undefined;
+        }
+        const n = {
+            className: t,
+            identifier: e
+        };
+        return (...t)=>{
+            this.callerStack.push(n);
+            try {
+                const e = r(...t);
+                if (e instanceof Promise) {
+                    return e.finally(()=>this.callerStack.pop());
+                }
+                this.callerStack.pop();
+                return e;
+            } catch (t) {
+                this.callerStack.pop();
+                throw t;
+            }
+        };
+    }
+    static getCurrentCaller() {
+        return this.callerStack[this.callerStack.length - 1];
+    }
+    static weave(r, n, a) {
+        const s = TransversalManager.getInstance(a);
+        const c = s.getAspectsForTarget(n);
+        const l = Object.getPrototypeOf(r);
+        const o = Object.getOwnPropertyNames(l).some((t)=>{
+            if (t === 'constructor') return false;
+            const r = Object.getOwnPropertyDescriptor(l, t);
+            if (!r) return false;
+            const n = r.value && typeof r.value === 'function';
+            const a = r.get && typeof r.get === 'function';
+            if (!n && !a) return false;
+            const s = getAffectedMethods(l, t);
+            return s.length > 0;
+        });
+        if (c.length === 0 && !o) {
+            return r;
+        }
+        const i = new Proxy(r, {
+            get (t, e, r) {
+                const n = Reflect.get(t, e, r);
+                if (typeof n !== 'function') {
+                    return n;
+                }
+                return function(...r) {
+                    const a = String(e);
+                    const l = TransversalWeaver.getCurrentCaller() ?? TransversalWeaver.callerRegistry.get(this);
+                    const o = {
+                        target: t,
+                        methodName: a,
+                        args: r,
+                        caller: l?.className,
+                        callerIdentifier: l?.identifier
+                    };
+                    const i = s.getAdvicesForJoinPoint(o, c, t, e);
+                    return TransversalWeaver.executeAdviceChain(i, n, t, r, o);
+                };
+            }
+        });
+        TransversalWeaver.callerRegistry.set(i, {
+            className: n.name,
+            identifier: n.name
+        });
+        return i;
+    }
+    static executeAdviceChain(t, e, r, n, a) {
+        const s = t.filter((t)=>t.type === 'before');
+        const c = t.filter((t)=>t.type === 'around');
+        const l = t.filter((t)=>t.type === 'after');
+        try {
+            for (const t of s){
+                const e = {
+                    ...a,
+                    config: t.config
+                };
+                t.method.call(t.transversalInstance, e);
+            }
+            let t;
+            if (c.length > 0) {
+                t = this.buildAroundChain(c, e, r, n, a);
+            } else {
+                t = e.apply(r, n);
+            }
+            if (t instanceof Promise) {
+                return t.then((t)=>{
+                    for (const e of l){
+                        const r = {
+                            ...a,
+                            result: t
+                        };
+                        e.method.call(e.transversalInstance, r);
+                    }
+                    return t;
+                }).catch((t)=>{
+                    a.error = t;
+                    throw t;
+                });
+            }
+            for (const e of l){
+                const r = {
+                    ...a,
+                    result: t,
+                    config: e.config
+                };
+                e.method.call(e.transversalInstance, r);
+            }
+            return t;
+        } catch (t) {
+            a.error = t;
+            throw t;
+        }
+    }
+    static buildAroundChain(t, e, r, n, a) {
+        let s = 0;
+        const c = ()=>{
+            if (s < t.length) {
+                const e = t[s++];
+                const r = {
+                    ...a,
+                    proceed: c,
+                    config: e.config
+                };
+                return e.method.call(e.transversalInstance, r);
+            } else {
+                return e.apply(r, n);
+            }
+        };
+        return c();
+    }
 }
+TransversalWeaver.callerRegistry = new WeakMap();
+TransversalWeaver.callerStack = [];
 
-export { AbstractTransversal };
+export { TransversalWeaver };