@xbg.solutions/backend-core 1.0.0

package/lib/utils-cache-connector/src/types.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Cache Connector Type Definitions
+ *
+ * Defines the types and interfaces for the multi-level caching system.
+ */
+/**
+ * Supported cache provider types
+ */
+export type CacheProviderType = 'memory' | 'firestore' | 'redis' | 'noop';
+/**
+ * Cache strategies for advanced behavior
+ */
+export type CacheStrategy = 'write-through' | 'write-behind' | 'cache-aside' | 'refresh-ahead';
+/**
+ * Global cache configuration (project-level)
+ */
+export interface CacheConfig {
+    /**
+     * Master switch - if false, all caching is disabled
+     */
+    enabled: boolean;
+    /**
+     * Default provider for repositories that don't specify
+     */
+    defaultProvider: CacheProviderType;
+    /**
+     * Default TTL in seconds
+     */
+    defaultTTL: number;
+    /**
+     * Global cache namespace (for versioning)
+     * Change this to invalidate all cached data
+     */
+    namespace: string;
+    /**
+     * Provider-specific configurations
+     */
+    providers: {
+        memory: MemoryCacheProviderConfig;
+        firestore: FirestoreCacheProviderConfig;
+        redis?: RedisCacheProviderConfig;
+    };
+}
+/**
+ * Memory cache provider configuration
+ */
+export interface MemoryCacheProviderConfig {
+    /**
+     * Maximum cache size in bytes
+     */
+    maxSize: number;
+    /**
+     * Interval to check for expired entries (seconds)
+     */
+    checkPeriod: number;
+    /**
+     * Whether to use LRU eviction when max size is reached
+     */
+    useClones?: boolean;
+}
+/**
+ * Firestore cache provider configuration
+ */
+export interface FirestoreCacheProviderConfig {
+    /**
+     * Which database to use for cache storage
+     */
+    database: string;
+    /**
+     * Collection name for cache entries
+     */
+    collection: string;
+    /**
+     * Enable automatic cleanup of expired entries
+     */
+    enableCleanup: boolean;
+    /**
+     * Cleanup interval in seconds
+     */
+    cleanupInterval: number;
+}
+/**
+ * Redis cache provider configuration
+ */
+export interface RedisCacheProviderConfig {
+    /**
+     * Redis server host
+     */
+    host: string;
+    /**
+     * Redis server port
+     */
+    port: number;
+    /**
+     * Redis password (optional)
+     */
+    password?: string;
+    /**
+     * Redis database number
+     */
+    db: number;
+    /**
+     * Connection timeout in milliseconds
+     */
+    connectTimeout?: number;
+    /**
+     * Enable TLS
+     */
+    tls?: boolean;
+}
+/**
+ * Repository-level cache configuration
+ */
+export interface RepositoryCacheConfig {
+    /**
+     * Enable caching for this repository (only if global is enabled)
+     */
+    enabled: boolean;
+    /**
+     * Which provider to use (overrides global default)
+     */
+    provider?: CacheProviderType;
+    /**
+     * Default TTL for this repository (overrides global default)
+     */
+    ttl?: number;
+    /**
+     * Cache key prefix for this repository
+     */
+    keyPrefix?: string;
+    /**
+     * Invalidation tags (auto-applied to all cache entries)
+     */
+    tags?: string[];
+    /**
+     * Advanced: cache strategies
+     */
+    strategies?: CacheStrategy[];
+}
+/**
+ * Method-level cache options (runtime)
+ */
+export interface CacheOptions {
+    /**
+     * Time-to-live override in seconds
+     */
+    ttl?: number;
+    /**
+     * Tags for cache invalidation
+     */
+    tags?: string[];
+    /**
+     * Force refresh, skip cache lookup
+     */
+    forceRefresh?: boolean;
+    /**
+     * Additional metadata for debugging
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * Options for setting cache entries
+ */
+export interface CacheSetOptions extends CacheOptions {
+    /**
+     * Provider to use for this operation
+     */
+    provider?: CacheProviderType;
+}
+/**
+ * Options for getting cache entries
+ */
+export interface CacheGetOptions {
+    /**
+     * Provider to use for this operation
+     */
+    provider?: CacheProviderType;
+    /**
+     * Return metadata along with value
+     */
+    includeMetadata?: boolean;
+}
+/**
+ * Options for invalidation operations
+ */
+export interface CacheInvalidateOptions {
+    /**
+     * Provider to use for this operation
+     */
+    provider?: CacheProviderType;
+    /**
+     * Pattern matching mode
+     */
+    pattern?: 'exact' | 'prefix' | 'suffix' | 'contains';
+}
+/**
+ * Cache entry metadata
+ */
+export interface CacheEntryMetadata {
+    /**
+     * When the entry was created
+     */
+    createdAt: Date;
+    /**
+     * When the entry expires
+     */
+    expiresAt: Date;
+    /**
+     * Number of times this entry has been accessed
+     */
+    hitCount: number;
+    /**
+     * Last access timestamp
+     */
+    lastAccessedAt: Date;
+    /**
+     * Tags associated with this entry
+     */
+    tags: string[];
+    /**
+     * Size in bytes (approximate)
+     */
+    size?: number;
+}
+/**
+ * Cache entry with metadata
+ */
+export interface CacheEntry<T = any> {
+    /**
+     * Cache key
+     */
+    key: string;
+    /**
+     * Cached value
+     */
+    value: T;
+    /**
+     * Entry metadata
+     */
+    metadata: CacheEntryMetadata;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    /**
+     * Total number of cache hits
+     */
+    hits: number;
+    /**
+     * Total number of cache misses
+     */
+    misses: number;
+    /**
+     * Hit ratio (hits / (hits + misses))
+     */
+    hitRatio: number;
+    /**
+     * Total number of entries in cache
+     */
+    entryCount: number;
+    /**
+     * Total size of cache in bytes
+     */
+    size: number;
+    /**
+     * Number of evictions (LRU or size-based)
+     */
+    evictions: number;
+    /**
+     * Number of expirations
+     */
+    expirations: number;
+}
+/**
+ * Cache operation result
+ */
+export interface CacheOperationResult {
+    /**
+     * Whether the operation succeeded
+     */
+    success: boolean;
+    /**
+     * Error message if operation failed
+     */
+    error?: string;
+    /**
+     * Operation duration in milliseconds
+     */
+    duration?: number;
+}
+/**
+ * Base cache provider interface
+ * All cache providers must implement this interface
+ */
+export interface ICacheProvider {
+    /**
+     * Get a value from cache
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Get a value with metadata
+     */
+    getWithMetadata<T>(key: string): Promise<CacheEntry<T> | null>;
+    /**
+     * Set a value in cache
+     */
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    /**
+     * Delete a specific key
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if a key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Invalidate cache entries by tags
+     */
+    invalidateByTags(tags: string[]): Promise<number>;
+    /**
+     * Invalidate cache entries by pattern
+     */
+    invalidateByPattern(pattern: string, mode?: 'prefix' | 'suffix' | 'contains'): Promise<number>;
+    /**
+     * Clear all cache entries
+     */
+    clear(): Promise<void>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): Promise<CacheStats>;
+    /**
+     * Get the provider type
+     */
+    getType(): CacheProviderType;
+    /**
+     * Cleanup expired entries (if supported)
+     */
+    cleanup?(): Promise<number>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/utils-cache-connector/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../utils-cache-connector/src/types.ts"],"names":[],"mappings":"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"}

package/lib/utils-cache-connector/src/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Cache Connector Type Definitions
+ *
+ * Defines the types and interfaces for the multi-level caching system.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/lib/utils-cache-connector/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../utils-cache-connector/src/types.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/lib/utils-events/src/event-bus.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Internal Event Bus
+ *
+ * Decouples components via publish/subscribe pattern.
+ * Uses Node.js EventEmitter for reliability.
+ */
+import { EventEmitter } from 'events';
+import { EventType, BaseEventPayload } from './event-types';
+declare class EventBus extends EventEmitter {
+    constructor();
+    /**
+     * Emit an event with type-safe payload
+     */
+    publish<T extends BaseEventPayload>(eventType: EventType, payload: T): boolean;
+    /**
+     * Subscribe to an event
+     */
+    subscribe<T extends BaseEventPayload>(eventType: EventType, handler: (payload: T) => void | Promise<void>): void;
+    /**
+     * Subscribe to an event (one-time only)
+     */
+    subscribeOnce<T extends BaseEventPayload>(eventType: EventType, handler: (payload: T) => void | Promise<void>): void;
+    /**
+     * Unsubscribe from an event
+     */
+    unsubscribe<T extends BaseEventPayload>(eventType: EventType, handler: (payload: T) => void | Promise<void>): void;
+    /**
+     * Unsubscribe all handlers for an event type
+     */
+    unsubscribeAll(eventType: EventType): void;
+    /**
+     * Get count of listeners for an event type
+     */
+    listenerCount(eventType: EventType): number;
+    /**
+     * Clear all event listeners (useful for testing)
+     */
+    clear(): void;
+}
+export declare const eventBus: EventBus;
+export {};
+//# sourceMappingURL=event-bus.d.ts.map

package/lib/utils-events/src/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../../../utils-events/src/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAE5D,cAAM,QAAS,SAAQ,YAAY;;IAQjC;;OAEG;IACH,OAAO,CAAC,CAAC,SAAS,gBAAgB,EAChC,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,CAAC,GACT,OAAO;IAqCV;;OAEG;IACH,SAAS,CAAC,CAAC,SAAS,gBAAgB,EAClC,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC5C,IAAI;IAIP;;OAEG;IACH,aAAa,CAAC,CAAC,SAAS,gBAAgB,EACtC,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC5C,IAAI;IAIP;;OAEG;IACH,WAAW,CAAC,CAAC,SAAS,gBAAgB,EACpC,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC5C,IAAI;IAIP;;OAEG;IACH,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAI1C;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM;IAI3C;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd;AAGD,eAAO,MAAM,QAAQ,UAAiB,CAAC"}

package/lib/utils-events/src/event-bus.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Internal Event Bus
+ *
+ * Decouples components via publish/subscribe pattern.
+ * Uses Node.js EventEmitter for reliability.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventBus = void 0;
+const events_1 = require("events");
+class EventBus extends events_1.EventEmitter {
+    constructor() {
+        super();
+        // Increase max listeners to avoid warnings in complex workflows
+        this.setMaxListeners(100);
+    }
+    /**
+     * Emit an event with type-safe payload
+     */
+    publish(eventType, payload) {
+        // Add timestamp if not provided
+        if (!payload.timestamp) {
+            payload.timestamp = new Date();
+        }
+        // Check if there are any listeners
+        const listenerCount = this.listenerCount(eventType);
+        if (listenerCount === 0) {
+            return false;
+        }
+        // Call each listener and catch any errors to prevent one failing listener
+        // from stopping others from being called
+        const rawListeners = this.rawListeners(eventType);
+        for (const rawListener of rawListeners) {
+            try {
+                // Check if this is a once listener (has a 'listener' property)
+                if (typeof rawListener === 'function' && rawListener.listener) {
+                    // For once listeners, remove them first, then call
+                    this.off(eventType, rawListener);
+                    rawListener.listener(payload);
+                }
+                else {
+                    // Regular listener
+                    rawListener(payload);
+                }
+            }
+            catch (error) {
+                // Silently catch errors from listeners
+                // This matches the behavior expected by the tests
+                // where one failing listener doesn't stop others
+            }
+        }
+        return true;
+    }
+    /**
+     * Subscribe to an event
+     */
+    subscribe(eventType, handler) {
+        this.on(eventType, handler);
+    }
+    /**
+     * Subscribe to an event (one-time only)
+     */
+    subscribeOnce(eventType, handler) {
+        this.once(eventType, handler);
+    }
+    /**
+     * Unsubscribe from an event
+     */
+    unsubscribe(eventType, handler) {
+        this.off(eventType, handler);
+    }
+    /**
+     * Unsubscribe all handlers for an event type
+     */
+    unsubscribeAll(eventType) {
+        this.removeAllListeners(eventType);
+    }
+    /**
+     * Get count of listeners for an event type
+     */
+    listenerCount(eventType) {
+        return super.listenerCount(eventType);
+    }
+    /**
+     * Clear all event listeners (useful for testing)
+     */
+    clear() {
+        this.removeAllListeners();
+    }
+}
+// Singleton instance
+exports.eventBus = new EventBus();
+//# sourceMappingURL=event-bus.js.map

package/lib/utils-events/src/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../../../utils-events/src/event-bus.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,mCAAsC;AAGtC,MAAM,QAAS,SAAQ,qBAAY;IACjC;QACE,KAAK,EAAE,CAAC;QAER,gEAAgE;QAChE,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,OAAO,CACL,SAAoB,EACpB,OAAU;QAEV,gCAAgC;QAChC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YACvB,OAAO,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QACjC,CAAC;QAED,mCAAmC;QACnC,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAEpD,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,0EAA0E;QAC1E,yCAAyC;QACzC,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;QAClD,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;YACvC,IAAI,CAAC;gBACH,+DAA+D;gBAC/D,IAAI,OAAO,WAAW,KAAK,UAAU,IAAK,WAAmB,CAAC,QAAQ,EAAE,CAAC;oBACvE,mDAAmD;oBACnD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,WAAuC,CAAC,CAAC;oBAC5D,WAAmB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;gBACzC,CAAC;qBAAM,CAAC;oBACN,mBAAmB;oBAClB,WAAwC,CAAC,OAAO,CAAC,CAAC;gBACrD,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,uCAAuC;gBACvC,kDAAkD;gBAClD,iDAAiD;YACnD,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,SAAS,CACP,SAAoB,EACpB,OAA6C;QAE7C,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,aAAa,CACX,SAAoB,EACpB,OAA6C;QAE7C,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,WAAW,CACT,SAAoB,EACpB,OAA6C;QAE7C,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,SAAoB;QACjC,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,SAAoB;QAChC,OAAO,KAAK,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,kBAAkB,EAAE,CAAC;IAC5B,CAAC;CACF;AAED,qBAAqB;AACR,QAAA,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAC"}

package/lib/utils-events/src/event-types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Event Type Definitions
+ *
+ * Base event types for the internal event bus. These cover the standard
+ * lifecycle events that most applications need out of the box.
+ *
+ * ─── Extending with project-specific events ───────────────────────────
+ *
+ * The code generator adds entity-specific CRUD events automatically
+ * (e.g. ORDER_CREATED, PRODUCT_UPDATED) via BaseService.publishEvent().
+ * Those events are cast to EventType at runtime, so they work with the
+ * event bus without being listed here.
+ *
+ * To add custom domain events (e.g. ORDER_SHIPPED, PAYMENT_FAILED):
+ *
+ *   1. Add the new member to this enum.
+ *   2. Optionally define a typed payload interface below.
+ *   3. Add the mapping to EventPayloadMap for full type safety.
+ *   4. Subscribe in your service or in subscribers/.
+ *
+ * The enum is deliberately kept small so that new projects start clean
+ * and only grow the event catalogue as needed.
+ */
+export declare enum EventType {
+    USER_CREATED = "user.created",
+    USER_UPDATED = "user.updated",
+    USER_DELETED = "user.deleted",
+    AUTH_LOGIN = "auth.login",
+    AUTH_LOGOUT = "auth.logout",
+    AUTH_TOKEN_REFRESHED = "auth.token_refreshed",
+    AUTH_TOKEN_BLACKLISTED = "auth.token_blacklisted",
+    AUTH_PASSWORD_CHANGED = "auth.password_changed",
+    FILE_UPLOADED = "file.uploaded",
+    FILE_DELETED = "file.deleted",
+    NOTIFICATION_SENT = "notification.sent",
+    NOTIFICATION_FAILED = "notification.failed",
+    /** Catch-all for external data changes (Firebase triggers, webhooks, etc.) */
+    EXTERNAL_DATA_CHANGE = "external.data.change"
+}
+/**
+ * Every event payload extends this interface.
+ * The event bus adds a `timestamp` automatically if one is not provided.
+ */
+export interface BaseEventPayload {
+    timestamp?: Date;
+    [key: string]: unknown;
+}
+/** Payload published by BaseService on entity creation */
+export interface EntityCreatedPayload extends BaseEventPayload {
+    entityId: string;
+    entityType: string;
+    action: 'CREATED';
+    userId?: string;
+    requestId?: string;
+    data?: Record<string, unknown>;
+}
+/** Payload published by BaseService on entity update */
+export interface EntityUpdatedPayload extends BaseEventPayload {
+    entityId: string;
+    entityType: string;
+    action: 'UPDATED';
+    userId?: string;
+    requestId?: string;
+    data?: Record<string, unknown>;
+}
+/** Payload published by BaseService on entity deletion */
+export interface EntityDeletedPayload extends BaseEventPayload {
+    entityId: string;
+    entityType: string;
+    action: 'DELETED';
+    userId?: string;
+    requestId?: string;
+    data?: Record<string, unknown>;
+}
+/** User lifecycle events */
+export interface UserCreatedPayload extends BaseEventPayload {
+    userUID: string;
+    email?: string;
+}
+export interface UserUpdatedPayload extends BaseEventPayload {
+    userUID: string;
+}
+export interface UserDeletedPayload extends BaseEventPayload {
+    userUID: string;
+}
+/** Authentication events */
+export interface AuthLoginPayload extends BaseEventPayload {
+    userUID: string;
+    method?: string;
+}
+export interface AuthLogoutPayload extends BaseEventPayload {
+    userUID: string;
+}
+export interface AuthTokenBlacklistedPayload extends BaseEventPayload {
+    userUID: string;
+    reason?: string;
+}
+/** File events */
+export interface FileUploadedPayload extends BaseEventPayload {
+    filePath: string;
+    contentType?: string;
+    size?: number;
+    bucket?: string;
+}
+export interface FileDeletedPayload extends BaseEventPayload {
+    filePath: string;
+}
+/** Notification events */
+export interface NotificationSentPayload extends BaseEventPayload {
+    channel: 'email' | 'sms' | 'push' | string;
+    recipientId?: string;
+}
+export interface NotificationFailedPayload extends BaseEventPayload {
+    channel: 'email' | 'sms' | 'push' | string;
+    recipientId?: string;
+    error?: string;
+}
+/** External data change (Firebase triggers, webhooks, etc.) */
+export interface ExternalDataChangePayload extends BaseEventPayload {
+    source: 'firestore' | 'auth' | 'storage' | string;
+    collection?: string;
+    documentId?: string;
+    operation?: string;
+    userId?: string;
+    filePath?: string;
+}
+/**
+ * Maps each EventType to its strongly-typed payload.
+ * Extend this map when adding new event types.
+ */
+export interface EventPayloadMap {
+    [EventType.USER_CREATED]: UserCreatedPayload;
+    [EventType.USER_UPDATED]: UserUpdatedPayload;
+    [EventType.USER_DELETED]: UserDeletedPayload;
+    [EventType.AUTH_LOGIN]: AuthLoginPayload;
+    [EventType.AUTH_LOGOUT]: AuthLogoutPayload;
+    [EventType.AUTH_TOKEN_REFRESHED]: BaseEventPayload;
+    [EventType.AUTH_TOKEN_BLACKLISTED]: AuthTokenBlacklistedPayload;
+    [EventType.AUTH_PASSWORD_CHANGED]: BaseEventPayload;
+    [EventType.FILE_UPLOADED]: FileUploadedPayload;
+    [EventType.FILE_DELETED]: FileDeletedPayload;
+    [EventType.NOTIFICATION_SENT]: NotificationSentPayload;
+    [EventType.NOTIFICATION_FAILED]: NotificationFailedPayload;
+    [EventType.EXTERNAL_DATA_CHANGE]: ExternalDataChangePayload;
+}
+//# sourceMappingURL=event-types.d.ts.map

package/lib/utils-events/src/event-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-types.d.ts","sourceRoot":"","sources":["../../../../utils-events/src/event-types.ts"],"names":[],"mappings":"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"}