@di-framework/di-framework 0.0.0-prerelease-0 → 0.0.0-prerelease.100

package/dist/container.d.ts

@@ -40,6 +40,8 @@ type ContainerEventPayloads = {
 type Listener<T> = (payload: T) => void;
 export declare const TELEMETRY_METADATA_KEY = "di:telemetry";
 export declare const TELEMETRY_LISTENER_METADATA_KEY = "di:telemetry-listener";
+export declare const PUBLISHER_METADATA_KEY = "di:publisher";
+export declare const SUBSCRIBER_METADATA_KEY = "di:subscriber";
 declare function defineMetadata(key: string | symbol, value: any, target: any): void;
 declare function getMetadata(key: string | symbol, target: any): any;
 declare function hasMetadata(key: string | symbol, target: any): boolean;
@@ -93,12 +95,16 @@ export declare class Container {
      * Subscribe to container lifecycle events (observer pattern).
      * Returns an unsubscribe function.
      */
-    on<K extends keyof ContainerEventPayloads>(event: K, listener: Listener<ContainerEventPayloads[K]>): () => void;
+    on<K extends keyof ContainerEventPayloads | (string & {})>(event: K, listener: Listener<K extends keyof ContainerEventPayloads ? ContainerEventPayloads[K] : any>): () => void;
     /**
      * Remove a previously registered listener
      */
-    off<K extends keyof ContainerEventPayloads>(event: K, listener: Listener<ContainerEventPayloads[K]>): void;
-    private emit;
+    off<K extends keyof ContainerEventPayloads | (string & {})>(event: K, listener: Listener<K extends keyof ContainerEventPayloads ? ContainerEventPayloads[K] : any>): void;
+    emit<K extends keyof ContainerEventPayloads | (string & {})>(event: K, payload: K extends keyof ContainerEventPayloads ? ContainerEventPayloads[K] : any): void;
+    /**
+     * Apply event publishers and subscribers defined via decorators
+     */
+    private applyEvents;
     /**
      * Private method to instantiate a service
      */

package/dist/container.js

@@ -10,6 +10,8 @@ const INJECT_METADATA_KEY = "di:inject";
 const DESIGN_PARAM_TYPES_KEY = "design:paramtypes";
 export const TELEMETRY_METADATA_KEY = "di:telemetry";
 export const TELEMETRY_LISTENER_METADATA_KEY = "di:telemetry-listener";
+export const PUBLISHER_METADATA_KEY = "di:publisher";
+export const SUBSCRIBER_METADATA_KEY = "di:subscriber";
 /**
  * Simple metadata storage that doesn't require reflect-metadata
  * Works with SWC's native decorator support
@@ -200,7 +202,90 @@ export class Container {
                 listener(payload);
             }
             catch (err) {
-                console.error(`[Container] listener for '${event}' threw`, err);
+                console.error(`[Container] listener for '${String(event)}' threw`, err);
+            }
+        });
+    }
+    /**
+     * Apply event publishers and subscribers defined via decorators
+     */
+    applyEvents(instance, constructor) {
+        const className = constructor.name;
+        // Handle @Subscriber(event)
+        const subscriberMap = getMetadata(SUBSCRIBER_METADATA_KEY, constructor.prototype) || {};
+        Object.entries(subscriberMap).forEach(([event, methods]) => {
+            methods.forEach((methodName) => {
+                const method = instance[methodName];
+                if (typeof method === "function") {
+                    this.on(event, (payload) => {
+                        try {
+                            method.call(instance, payload);
+                        }
+                        catch (err) {
+                            console.error(`[Container] Subscriber '${className}.${methodName}' for event '${event}' threw`, err);
+                        }
+                    });
+                }
+            });
+        });
+        // Handle @Publisher(options)
+        const publisherMethods = getMetadata(PUBLISHER_METADATA_KEY, constructor.prototype) || {};
+        Object.entries(publisherMethods).forEach(([methodName, options]) => {
+            const originalMethod = instance[methodName];
+            if (typeof originalMethod === "function") {
+                const self = this;
+                const phase = options.phase ?? "after";
+                instance[methodName] = function (...args) {
+                    const startTime = Date.now();
+                    const emit = (result, error) => {
+                        const payload = {
+                            className,
+                            methodName,
+                            args,
+                            startTime,
+                            endTime: Date.now(),
+                            result,
+                            error,
+                        };
+                        if (options.logging) {
+                            const duration = payload.endTime - payload.startTime;
+                            const status = error
+                                ? `ERROR: ${error && error.message ? error.message : String(error)}`
+                                : "SUCCESS";
+                            console.log(`[Publisher] ${className}.${methodName} -> '${options.event}' - ${status} (${duration}ms)`);
+                        }
+                        self.emit(options.event, payload);
+                    };
+                    try {
+                        if (phase === "before" || phase === "both") {
+                            // Emit before invocation (no result yet)
+                            emit(undefined, undefined);
+                        }
+                        const result = originalMethod.apply(this, args);
+                        if (result instanceof Promise) {
+                            return result
+                                .then((val) => {
+                                if (phase === "after" || phase === "both") {
+                                    emit(val, undefined);
+                                }
+                                return val;
+                            })
+                                .catch((err) => {
+                                // Always emit on error to allow subscribers to react
+                                emit(undefined, err);
+                                throw err;
+                            });
+                        }
+                        if (phase === "after" || phase === "both") {
+                            emit(result, undefined);
+                        }
+                        return result;
+                    }
+                    catch (err) {
+                        emit(undefined, err);
+                        throw err;
+                    }
+                };
             }
         });
     }
@@ -255,6 +340,8 @@ export class Container {
         const instance = new type(...dependencies);
         // Apply Telemetry and TelemetryListener
         this.applyTelemetry(instance, type);
+        // Apply custom event publishers and subscribers
+        this.applyEvents(instance, type);
         // Call @Component() decorators on properties
         // Check both the instance and the constructor prototype for metadata
         const injectProperties = getMetadata(INJECT_METADATA_KEY, type) || {};

package/dist/decorators.d.ts

@@ -31,6 +31,41 @@ export declare function Telemetry(options?: TelemetryOptions): (target: any, pro
  * The method will be automatically registered to the container's 'telemetry' event.
  */
 export declare function TelemetryListener(): (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/**
+ * Options for the @Publisher decorator
+ */
+export interface PublisherOptions {
+    /** The custom event name to emit on the container */
+    event: string;
+    /** When to emit relative to the method invocation. Defaults to 'after'. */
+    phase?: "before" | "after" | "both";
+    /** Optional console logging for debug purposes. Defaults to false. */
+    logging?: boolean;
+}
+/**
+ * Marks a method to publish a custom event on invocation.
+ * Useful for cross-platform event-driven architectures.
+ *
+ * Example:
+ * @Container()
+ * class UserService {
+ *   @Publisher('user.created')
+ *   createUser(dto: CreateUserDto) { ... }
+ * }
+ */
+export declare function Publisher(optionsOrEvent: string | PublisherOptions): (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/**
+ * Marks a method to subscribe to a custom event emitted on the container.
+ * The decorated method will receive the published payload.
+ *
+ * Example:
+ * @Container()
+ * class AuditService {
+ *   @Subscriber('user.created')
+ *   onUserCreated(payload: any) { ... }
+ * }
+ */
+export declare function Subscriber(event: string): (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
 /**
  * Marks a class as injectable and registers it with the DI container
  *

package/dist/decorators.js

@@ -7,7 +7,7 @@
  * Works with SWC and TypeScript's native decorator support.
  * No external dependencies required (no reflect-metadata needed).
  */
-import { useContainer, Container as DIContainer, defineMetadata, getOwnMetadata, getMetadata, TELEMETRY_METADATA_KEY, TELEMETRY_LISTENER_METADATA_KEY, } from "./container";
+import { useContainer, Container as DIContainer, defineMetadata, getOwnMetadata, getMetadata, TELEMETRY_METADATA_KEY, TELEMETRY_LISTENER_METADATA_KEY, PUBLISHER_METADATA_KEY, SUBSCRIBER_METADATA_KEY, } from "./container";
 const INJECTABLE_METADATA_KEY = "di:injectable";
 const INJECT_METADATA_KEY = "di:inject";
 /**
@@ -35,6 +35,51 @@ export function TelemetryListener() {
         defineMetadata(TELEMETRY_LISTENER_METADATA_KEY, listeners, target);
     };
 }
+/**
+ * Marks a method to publish a custom event on invocation.
+ * Useful for cross-platform event-driven architectures.
+ *
+ * Example:
+ * @Container()
+ * class UserService {
+ *   @Publisher('user.created')
+ *   createUser(dto: CreateUserDto) { ... }
+ * }
+ */
+export function Publisher(optionsOrEvent) {
+    return function (target, propertyKey, descriptor) {
+        const options = typeof optionsOrEvent === "string"
+            ? { event: optionsOrEvent }
+            : optionsOrEvent;
+        const methods = getOwnMetadata(PUBLISHER_METADATA_KEY, target) || {};
+        methods[propertyKey] = {
+            event: options.event,
+            phase: options.phase ?? "after",
+            logging: options.logging ?? false,
+        };
+        defineMetadata(PUBLISHER_METADATA_KEY, methods, target);
+    };
+}
+/**
+ * Marks a method to subscribe to a custom event emitted on the container.
+ * The decorated method will receive the published payload.
+ *
+ * Example:
+ * @Container()
+ * class AuditService {
+ *   @Subscriber('user.created')
+ *   onUserCreated(payload: any) { ... }
+ * }
+ */
+export function Subscriber(event) {
+    return function (target, propertyKey, descriptor) {
+        const map = getOwnMetadata(SUBSCRIBER_METADATA_KEY, target) || {};
+        if (!map[event])
+            map[event] = [];
+        map[event].push(propertyKey);
+        defineMetadata(SUBSCRIBER_METADATA_KEY, map, target);
+    };
+}
 /**
  * Marks a class as injectable and registers it with the DI container
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@di-framework/di-framework",
-  "version": "0.0.0-prerelease-0",
+  "version": "0.0.0-prerelease.100",
   "description": "Lightweight, zero-dependency TypeScript Dependency Injection framework using decorators. Works seamlessly with SWC and TypeScript's native decorator support.",
   "main": "./dist/container.js",
   "types": "./dist/container.d.ts",