@fjell/core 4.4.49 → 4.4.51

package/dist/event/emitter.d.ts

@@ -0,0 +1,140 @@
+import { ComKey, ItemTypeArray, LocKeyArray, PriKey } from '../keys';
+import { Item } from '../items';
+import { BaseEvent } from './events';
+import { Subscription, SubscriptionOptions } from './subscription';
+/**
+ * Core EventEmitter interface that storage libraries implement.
+ * Each item type gets its own EventEmitter instance for full type safety.
+ * Libraries implement separate EventEmitters per item type (UserEventEmitter, MessageEventEmitter, etc.)
+ */
+export interface EventEmitter<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> {
+    /**
+     * Emit a generic event with full control over event properties.
+     * Libraries can use this for custom events or when they need full control.
+     */
+    emit(event: BaseEvent<S, L1, L2, L3, L4, L5>): Promise<void>;
+    /**
+     * Emit a create event when an item is created.
+     * Convenience method that constructs a properly typed CreateEvent.
+     */
+    emitCreate(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, scopes: string[], item: Item<S, L1, L2, L3, L4, L5>): Promise<void>;
+    /**
+     * Emit an update event when an item is modified.
+     * Convenience method that constructs a properly typed UpdateEvent.
+     */
+    emitUpdate(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, scopes: string[], changes: string[], before?: Item<S, L1, L2, L3, L4, L5>, after?: Item<S, L1, L2, L3, L4, L5>): Promise<void>;
+    /**
+     * Emit a delete event when an item is deleted.
+     * Convenience method that constructs a properly typed DeleteEvent.
+     */
+    emitDelete(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, scopes: string[], item?: Item<S, L1, L2, L3, L4, L5>): Promise<void>;
+    /**
+     * Emit an action event when a custom action is performed.
+     * Convenience method that constructs a properly typed ActionEvent.
+     */
+    emitAction(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, scopes: string[], actionName: string, actionData?: Record<string, unknown>): Promise<void>;
+    /**
+     * Create a scoped emitter that automatically includes the specified scopes.
+     * Libraries can use this to avoid passing scopes to every emit call.
+     */
+    withScopes(scopes: string[]): ScopedEventEmitter<S, L1, L2, L3, L4, L5>;
+}
+/**
+ * Scoped EventEmitter that automatically includes configured scopes.
+ * Convenience interface for libraries to avoid passing scopes repeatedly.
+ */
+export interface ScopedEventEmitter<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> {
+    /** The scopes that will be automatically included in all events */
+    readonly scopes: string[];
+    /**
+     * Emit a generic event with automatic scope inclusion.
+     * The event should omit scopes since they'll be added automatically.
+     */
+    emit(event: Omit<BaseEvent<S, L1, L2, L3, L4, L5>, 'scopes'>): Promise<void>;
+    /**
+     * Emit a create event with automatic scope inclusion.
+     */
+    emitCreate(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, item: Item<S, L1, L2, L3, L4, L5>): Promise<void>;
+    /**
+     * Emit an update event with automatic scope inclusion.
+     */
+    emitUpdate(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, changes: string[], before?: Item<S, L1, L2, L3, L4, L5>, after?: Item<S, L1, L2, L3, L4, L5>): Promise<void>;
+    /**
+     * Emit a delete event with automatic scope inclusion.
+     */
+    emitDelete(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, item?: Item<S, L1, L2, L3, L4, L5>): Promise<void>;
+    /**
+     * Emit an action event with automatic scope inclusion.
+     */
+    emitAction(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, actionName: string, actionData?: Record<string, unknown>): Promise<void>;
+}
+/**
+ * EventSubscriber interface for subscribing to and receiving events.
+ * Each item type gets its own EventSubscriber instance for full type safety.
+ */
+export interface EventSubscriber<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> {
+    /**
+     * Subscribe to events using a full subscription object.
+     * Returns the subscription ID for later unsubscribing.
+     */
+    subscribe(subscription: Omit<Subscription<S, L1, L2, L3, L4, L5>, 'id'>): Promise<string>;
+    /**
+     * Unsubscribe from events using the subscription ID.
+     */
+    unsubscribe(subscriptionId: string): Promise<void>;
+    /**
+     * Register a callback to be called when events are received.
+     * Multiple callbacks can be registered and they'll all be called.
+     */
+    onEvent(callback: (event: BaseEvent<S, L1, L2, L3, L4, L5>) => void): void;
+    /**
+     * Remove a previously registered event callback.
+     */
+    removeEventListener(callback: (event: BaseEvent<S, L1, L2, L3, L4, L5>) => void): void;
+    /**
+     * Convenience method to subscribe to a specific item.
+     * Automatically creates an ItemSubscription with the provided options.
+     */
+    subscribeToItem(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, options?: SubscriptionOptions<S, L1, L2, L3, L4, L5>): Promise<string>;
+    /**
+     * Convenience method to subscribe to a location.
+     * Automatically creates a LocationSubscription with the provided options.
+     */
+    subscribeToLocation(kta: ItemTypeArray<S, L1, L2, L3, L4, L5>, location: LocKeyArray<L1, L2, L3, L4, L5>, options?: SubscriptionOptions<S, L1, L2, L3, L4, L5>): Promise<string>;
+    /**
+     * Get all currently active subscriptions.
+     * Useful for debugging and subscription management.
+     */
+    getActiveSubscriptions(): Subscription<S, L1, L2, L3, L4, L5>[];
+    /**
+     * Check if an event matches any active subscriptions.
+     * Used internally by libraries to determine if an event should be processed.
+     */
+    matchesSubscription(event: BaseEvent<S, L1, L2, L3, L4, L5>): boolean;
+    /**
+     * Check if an event matches a specific subscription.
+     * Used internally for subscription matching logic.
+     */
+    matchesSpecificSubscription(event: BaseEvent<S, L1, L2, L3, L4, L5>, subscription: Subscription<S, L1, L2, L3, L4, L5>): boolean;
+}
+/**
+ * Combined EventSystem interface that includes both emitter and subscriber.
+ * Libraries can implement this interface to provide both event emission and subscription.
+ */
+export interface EventSystem<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> {
+    /** Event emitter for publishing events */
+    readonly emitter: EventEmitter<S, L1, L2, L3, L4, L5>;
+    /** Event subscriber for receiving events */
+    readonly subscriber: EventSubscriber<S, L1, L2, L3, L4, L5>;
+}
+/**
+ * Factory function type for creating EventSystems.
+ * Libraries implement this to create properly configured event systems.
+ */
+export type EventSystemFactory<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> = (scopes: string[]) => EventSystem<S, L1, L2, L3, L4, L5>;
+export type UserEventEmitter = EventEmitter<'User'>;
+export type UserEventSubscriber = EventSubscriber<'User'>;
+export type UserEventSystem = EventSystem<'User'>;
+export type MessageEventEmitter<L1 extends string, L2 extends string> = EventEmitter<'Message', L1, L2>;
+export type MessageEventSubscriber<L1 extends string, L2 extends string> = EventSubscriber<'Message', L1, L2>;
+export type MessageEventSystem<L1 extends string, L2 extends string> = EventSystem<'Message', L1, L2>;

package/dist/event/events.d.ts

@@ -0,0 +1,81 @@
+import { ComKey, PriKey } from '../keys';
+import { Item } from '../items';
+/**
+ * Base event interface that all events extend.
+ * Provides core event properties with full type safety using the existing PriKey/ComKey system.
+ */
+export interface BaseEvent<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> {
+    /** Type of event - "create", "update", "delete", etc. */
+    eventType: string;
+    /** The key of the item that was affected - maintains full type safety */
+    key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>;
+    /** Which storage backend(s) generated this event - enables filtering by implementation */
+    scopes: string[];
+    /** When the event occurred */
+    timestamp: Date;
+    /** Optional: the full item content - fully typed, no loss of type information */
+    item?: Item<S, L1, L2, L3, L4, L5>;
+}
+/**
+ * Event emitted when an item is created.
+ * The item property is required since we always have the created item data.
+ */
+export interface CreateEvent<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends BaseEvent<S, L1, L2, L3, L4, L5> {
+    eventType: 'create';
+    /** The created item - always available for create events */
+    item: Item<S, L1, L2, L3, L4, L5>;
+}
+/**
+ * Event emitted when an item is updated.
+ * Provides detailed change tracking with before/after states.
+ */
+export interface UpdateEvent<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends BaseEvent<S, L1, L2, L3, L4, L5> {
+    eventType: 'update';
+    /** List of field names that were changed */
+    changes: string[];
+    /** Optional: item state before the update */
+    before?: Item<S, L1, L2, L3, L4, L5>;
+    /** Optional: item state after the update */
+    after?: Item<S, L1, L2, L3, L4, L5>;
+}
+/**
+ * Event emitted when an item is deleted.
+ * May include the deleted item data for cleanup/undo operations.
+ */
+export interface DeleteEvent<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends BaseEvent<S, L1, L2, L3, L4, L5> {
+    eventType: 'delete';
+    /** Optional: the deleted item content - useful for cleanup/undo */
+    item?: Item<S, L1, L2, L3, L4, L5>;
+}
+/**
+ * Event emitted when a custom action is performed on an item.
+ * Allows libraries to define custom event types beyond standard CRUD.
+ */
+export interface ActionEvent<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends BaseEvent<S, L1, L2, L3, L4, L5> {
+    eventType: 'action';
+    /** Name of the action that was performed */
+    actionName: string;
+    /** Optional: action-specific data */
+    actionData?: Record<string, unknown>;
+}
+/**
+ * Union type of all standard event types.
+ * Libraries can extend this with custom events if needed.
+ */
+export type Event<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> = CreateEvent<S, L1, L2, L3, L4, L5> | UpdateEvent<S, L1, L2, L3, L4, L5> | DeleteEvent<S, L1, L2, L3, L4, L5> | ActionEvent<S, L1, L2, L3, L4, L5>;
+/**
+ * Type guard to check if an event is a CreateEvent
+ */
+export declare function isCreateEvent<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(event: BaseEvent<S, L1, L2, L3, L4, L5>): event is CreateEvent<S, L1, L2, L3, L4, L5>;
+/**
+ * Type guard to check if an event is an UpdateEvent
+ */
+export declare function isUpdateEvent<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(event: BaseEvent<S, L1, L2, L3, L4, L5>): event is UpdateEvent<S, L1, L2, L3, L4, L5>;
+/**
+ * Type guard to check if an event is a DeleteEvent
+ */
+export declare function isDeleteEvent<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(event: BaseEvent<S, L1, L2, L3, L4, L5>): event is DeleteEvent<S, L1, L2, L3, L4, L5>;
+/**
+ * Type guard to check if an event is an ActionEvent
+ */
+export declare function isActionEvent<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(event: BaseEvent<S, L1, L2, L3, L4, L5>): event is ActionEvent<S, L1, L2, L3, L4, L5>;

package/dist/event/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Event System Public API
+ *
+ * This module exports all the public interfaces and utilities for the Fjell event system.
+ * The event system provides type-safe, item-level change events with full PriKey/ComKey integration.
+ *
+ * Key Features:
+ * - Full type safety using existing PriKey/ComKey system
+ * - Storage-agnostic event interfaces
+ * - Item-specific and location-based subscriptions
+ * - Separate EventEmitters per item type for optimal type safety
+ * - Real-time awareness for application needs (not reliable business execution)
+ *
+ * Usage:
+ * - Libraries implement EventEmitter/EventSubscriber interfaces
+ * - Applications subscribe to events through library instances
+ * - Events are delivered through callback functions with full type safety
+ */
+export { BaseEvent, CreateEvent, UpdateEvent, DeleteEvent, ActionEvent, Event, isCreateEvent, isUpdateEvent, isDeleteEvent, isActionEvent, } from './events';
+export { BaseSubscription, ItemSubscription, LocationSubscription, Subscription, SubscriptionOptions, isItemSubscription, isLocationSubscription, generateSubscriptionId, createItemSubscription, createLocationSubscription, } from './subscription';
+export { EventEmitter, ScopedEventEmitter, EventSubscriber, EventSystem, EventSystemFactory, UserEventEmitter, UserEventSubscriber, UserEventSystem, MessageEventEmitter, MessageEventSubscriber, MessageEventSystem, } from './emitter';
+export { doesEventMatchSubscription, doesScopeMatch, doesEventTypeMatch, doesKeyMatch, doesKeyMatchLocation, doesLocationMatch, findMatchingSubscriptions, extractLocationValues, compareLocationValues, } from './matching';
+export { STANDARD_EVENT_TYPES, StandardEventType, STANDARD_SCOPES, StandardScope, SubscriptionStatus, SubscriptionMetadata, ManagedSubscription, EventHandler, SafeEventHandler, EventBatch, EventStats, EventSystemConfig, DEFAULT_EVENT_CONFIG, EventSystemError, SubscriptionError, EventEmissionError, EventMatchingError, createEventSystemError, isEventSystemError, ExtractItemType, ExtractEventTypes, } from './types';
+/**
+ * Version of the event system API.
+ * Used for compatibility checking and debugging.
+ */
+export declare const EVENT_SYSTEM_VERSION = "1.0.0";
+/**
+ * Supported event types for reference.
+ * Libraries should use these standard types for consistency.
+ */
+export declare const SUPPORTED_EVENT_TYPES: readonly ["create", "update", "delete", "action"];
+/**
+ * Supported storage scopes for reference.
+ * Libraries should use these standard scopes for consistency.
+ */
+export declare const SUPPORTED_SCOPES: readonly ["firestore", "sequelize", "postgresql", "mysql", "mongodb", "redis"];

package/dist/event/matching.d.ts

@@ -0,0 +1,54 @@
+import { ComKey, ItemTypeArray, LocKeyArray, PriKey } from '../keys';
+import { BaseEvent } from './events';
+import { Subscription } from './subscription';
+/**
+ * Core subscription matching logic.
+ * Determines whether an event should be delivered to a specific subscription.
+ */
+export declare function doesEventMatchSubscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(event: BaseEvent<S, L1, L2, L3, L4, L5>, subscription: Subscription<S, L1, L2, L3, L4, L5>): boolean;
+/**
+ * Check if event scopes match subscription scope requirements.
+ *
+ * @param eventScopes - Scopes from the event (e.g., ["firestore"])
+ * @param subscriptionScopes - Optional scopes required by subscription
+ * @returns true if scopes are compatible
+ */
+export declare function doesScopeMatch(eventScopes: string[], subscriptionScopes?: string[]): boolean;
+/**
+ * Check if event type matches subscription event type requirements.
+ *
+ * @param eventType - Type from the event (e.g., "create", "update")
+ * @param subscriptionEventTypes - Optional event types required by subscription
+ * @returns true if event type is compatible
+ */
+export declare function doesEventTypeMatch(eventType: string, subscriptionEventTypes?: string[]): boolean;
+/**
+ * Check if two keys are exactly equal.
+ * Used for item-based subscriptions that want events for a specific key.
+ */
+export declare function doesKeyMatch<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(eventKey: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, subscriptionKey: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>): boolean;
+/**
+ * Check if an event key matches a location-based subscription.
+ * This is more complex as it needs to determine if the event key is "within" the subscription location.
+ */
+export declare function doesKeyMatchLocation<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(eventKey: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, subscriptionKta: ItemTypeArray<S, L1, L2, L3, L4, L5>, subscriptionLocation: LocKeyArray<L1, L2, L3, L4, L5>): boolean;
+/**
+ * Check if an event's location keys match a subscription's location requirements.
+ * This implements the hierarchical location matching logic.
+ */
+export declare function doesLocationMatch<L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(eventLocation: LocKeyArray<L1, L2, L3, L4, L5>, subscriptionLocation: LocKeyArray<L1, L2, L3, L4, L5>, _subscriptionKta: ItemTypeArray<string, L1, L2, L3, L4, L5>): boolean;
+/**
+ * Find all subscriptions that match a given event.
+ * Used by EventSubscriber implementations to determine which subscriptions should receive an event.
+ */
+export declare function findMatchingSubscriptions<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(event: BaseEvent<S, L1, L2, L3, L4, L5>, subscriptions: Subscription<S, L1, L2, L3, L4, L5>[]): Subscription<S, L1, L2, L3, L4, L5>[];
+/**
+ * Utility function to extract the location from a ComKey for comparison purposes.
+ * Returns the location key values as strings for easier comparison.
+ */
+export declare function extractLocationValues<L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(location: LocKeyArray<L1, L2, L3, L4, L5>): string[];
+/**
+ * Utility function to compare two location arrays by their values.
+ * Useful for debugging and testing location matching logic.
+ */
+export declare function compareLocationValues<L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(location1: LocKeyArray<L1, L2, L3, L4, L5>, location2: LocKeyArray<L1, L2, L3, L4, L5>): boolean;

package/dist/event/subscription.d.ts

@@ -0,0 +1,74 @@
+import { ComKey, ItemTypeArray, LocKeyArray, PriKey } from '../keys';
+import { ItemQuery } from '../item/ItemQuery';
+/**
+ * Base subscription interface that all subscription types extend.
+ * Provides core subscription properties with full type safety.
+ */
+export interface BaseSubscription {
+    /** Unique subscription identifier - generated when subscription is created */
+    id: string;
+    /** Optional: specific event types to listen for (defaults to all if not specified) */
+    eventTypes?: string[];
+    /** Optional: storage backends to listen to (defaults to all if not specified) */
+    scopes?: string[];
+    /** Optional: additional filtering criteria using existing ItemQuery system */
+    query?: ItemQuery;
+}
+/**
+ * Subscription to events for a specific item using PriKey or ComKey.
+ * Provides exact item-level event subscriptions with full type safety.
+ */
+export interface ItemSubscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends BaseSubscription {
+    /** The specific key to subscribe to - fully typed PriKey or ComKey */
+    key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>;
+}
+/**
+ * Subscription to events for all items in a location using KTA + location array.
+ * Provides location-based event subscriptions with full type safety.
+ */
+export interface LocationSubscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends BaseSubscription {
+    /** Item type array defining the type hierarchy */
+    kta: ItemTypeArray<S, L1, L2, L3, L4, L5>;
+    /** Location key array defining the specific location */
+    location: LocKeyArray<L1, L2, L3, L4, L5>;
+}
+/**
+ * Union type of all subscription types.
+ * This allows handling any subscription type generically while maintaining type safety.
+ */
+export type Subscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> = ItemSubscription<S, L1, L2, L3, L4, L5> | LocationSubscription<S, L1, L2, L3, L4, L5>;
+/**
+ * Options for creating subscriptions.
+ * Used by convenience methods to create subscriptions without requiring full subscription objects.
+ */
+export interface SubscriptionOptions<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> {
+    /** Optional: specific event types to listen for */
+    eventTypes?: string[];
+    /** Optional: storage backends to listen to */
+    scopes?: string[];
+    /** Optional: additional filtering criteria */
+    query?: ItemQuery;
+}
+/**
+ * Type guard to check if a subscription is an ItemSubscription
+ */
+export declare function isItemSubscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(subscription: Subscription<S, L1, L2, L3, L4, L5>): subscription is ItemSubscription<S, L1, L2, L3, L4, L5>;
+/**
+ * Type guard to check if a subscription is a LocationSubscription
+ */
+export declare function isLocationSubscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(subscription: Subscription<S, L1, L2, L3, L4, L5>): subscription is LocationSubscription<S, L1, L2, L3, L4, L5>;
+/**
+ * Utility function to generate unique subscription IDs.
+ * Libraries can use this or implement their own ID generation strategy.
+ */
+export declare function generateSubscriptionId(): string;
+/**
+ * Utility function to create an ItemSubscription with generated ID.
+ * Simplifies subscription creation for library implementations.
+ */
+export declare function createItemSubscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, options?: SubscriptionOptions<S, L1, L2, L3, L4, L5>): ItemSubscription<S, L1, L2, L3, L4, L5>;
+/**
+ * Utility function to create a LocationSubscription with generated ID.
+ * Simplifies subscription creation for library implementations.
+ */
+export declare function createLocationSubscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(kta: ItemTypeArray<S, L1, L2, L3, L4, L5>, location: LocKeyArray<L1, L2, L3, L4, L5>, options?: SubscriptionOptions<S, L1, L2, L3, L4, L5>): LocationSubscription<S, L1, L2, L3, L4, L5>;

package/dist/event/types.d.ts

@@ -0,0 +1,186 @@
+import { BaseEvent } from './events';
+import { Subscription } from './subscription';
+/**
+ * Common event types used throughout the event system.
+ * Libraries can extend these with custom event types as needed.
+ */
+export declare const STANDARD_EVENT_TYPES: {
+    readonly CREATE: "create";
+    readonly UPDATE: "update";
+    readonly DELETE: "delete";
+    readonly ACTION: "action";
+};
+/**
+ * Type for standard event type values.
+ */
+export type StandardEventType = typeof STANDARD_EVENT_TYPES[keyof typeof STANDARD_EVENT_TYPES];
+/**
+ * Common scope identifiers used by storage libraries.
+ * Libraries should use these standard scopes for consistency.
+ */
+export declare const STANDARD_SCOPES: {
+    readonly FIRESTORE: "firestore";
+    readonly SEQUELIZE: "sequelize";
+    readonly POSTGRESQL: "postgresql";
+    readonly MYSQL: "mysql";
+    readonly MONGODB: "mongodb";
+    readonly REDIS: "redis";
+};
+/**
+ * Type for standard scope values.
+ */
+export type StandardScope = typeof STANDARD_SCOPES[keyof typeof STANDARD_SCOPES];
+/**
+ * Status of a subscription.
+ * Used to track subscription lifecycle and health.
+ */
+export declare enum SubscriptionStatus {
+    PENDING = "pending",// Subscription created but not yet active
+    ACTIVE = "active",// Subscription is active and receiving events
+    PAUSED = "paused",// Subscription is paused (not receiving events)
+    ERROR = "error",// Subscription has encountered an error
+    CANCELLED = "cancelled"
+}
+/**
+ * Metadata about a subscription's current state.
+ * Used for monitoring and debugging subscription health.
+ */
+export interface SubscriptionMetadata {
+    /** Current status of the subscription */
+    status: SubscriptionStatus;
+    /** When the subscription was created */
+    createdAt: Date;
+    /** When the subscription was last updated */
+    updatedAt: Date;
+    /** When the subscription last received an event */
+    lastEventAt?: Date;
+    /** Total number of events received by this subscription */
+    eventCount: number;
+    /** Any error that occurred with this subscription */
+    lastError?: Error;
+    /** Additional metadata specific to the storage implementation */
+    implementationMetadata?: Record<string, unknown>;
+}
+/**
+ * Enhanced subscription interface that includes metadata.
+ * Used internally by libraries for subscription management.
+ */
+export type ManagedSubscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> = Subscription<S, L1, L2, L3, L4, L5> & {
+    /** Metadata about this subscription's state */
+    metadata: SubscriptionMetadata;
+};
+/**
+ * Event handler function type.
+ * Used for type-safe event callbacks.
+ */
+export type EventHandler<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> = (event: BaseEvent<S, L1, L2, L3, L4, L5>) => void | Promise<void>;
+/**
+ * Event handler with error handling.
+ * Allows handlers to indicate success/failure for better error tracking.
+ */
+export type SafeEventHandler<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> = (event: BaseEvent<S, L1, L2, L3, L4, L5>) => Promise<{
+    success: boolean;
+    error?: Error;
+}>;
+/**
+ * Batch of events for efficient processing.
+ * Used when multiple events need to be processed together.
+ */
+export interface EventBatch<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> {
+    /** Events in this batch */
+    events: BaseEvent<S, L1, L2, L3, L4, L5>[];
+    /** When this batch was created */
+    createdAt: Date;
+    /** Optional: transaction ID if these events are part of a transaction */
+    transactionId?: string;
+    /** Optional: batch metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Statistics about event processing.
+ * Used for monitoring and performance analysis.
+ */
+export interface EventStats {
+    /** Total events processed */
+    totalEvents: number;
+    /** Events processed by type */
+    eventsByType: Record<string, number>;
+    /** Events processed by scope */
+    eventsByScope: Record<string, number>;
+    /** Average event processing time in milliseconds */
+    averageProcessingTime: number;
+    /** Number of active subscriptions */
+    activeSubscriptions: number;
+    /** Number of failed event deliveries */
+    failedDeliveries: number;
+    /** When these stats were last updated */
+    lastUpdated: Date;
+}
+/**
+ * Configuration for event system behavior.
+ * Used by libraries to customize event processing.
+ */
+export interface EventSystemConfig {
+    /** Maximum number of events to batch together */
+    maxBatchSize?: number;
+    /** Maximum time to wait before processing a batch (milliseconds) */
+    maxBatchWaitTime?: number;
+    /** Maximum number of retry attempts for failed event deliveries */
+    maxRetryAttempts?: number;
+    /** Delay between retry attempts (milliseconds) */
+    retryDelay?: number;
+    /** Whether to enable event statistics collection */
+    enableStats?: boolean;
+    /** Maximum number of subscriptions to allow */
+    maxSubscriptions?: number;
+    /** Cleanup interval for inactive subscriptions (milliseconds) */
+    subscriptionCleanupInterval?: number;
+}
+/**
+ * Default configuration values.
+ * Libraries can use these as defaults and override as needed.
+ */
+export declare const DEFAULT_EVENT_CONFIG: Required<EventSystemConfig>;
+/**
+ * Error types specific to the event system.
+ * Used for better error handling and debugging.
+ */
+export declare class EventSystemError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, details?: Record<string, unknown> | undefined);
+}
+export declare class SubscriptionError extends EventSystemError {
+    readonly subscriptionId: string;
+    constructor(message: string, subscriptionId: string, details?: Record<string, unknown>);
+}
+export declare class EventEmissionError extends EventSystemError {
+    readonly eventType: string;
+    constructor(message: string, eventType: string, details?: Record<string, unknown>);
+}
+export declare class EventMatchingError extends EventSystemError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Utility function to create standardized error messages.
+ */
+export declare function createEventSystemError(type: 'subscription' | 'emission' | 'matching' | 'general', message: string, details?: Record<string, unknown>): EventSystemError;
+/**
+ * Utility function to check if an error is an EventSystemError.
+ */
+export declare function isEventSystemError(error: unknown): error is EventSystemError;
+/**
+ * Utility type for extracting the item type from an event.
+ */
+export type ExtractItemType<T> = T extends BaseEvent<infer S, any, any, any, any, any> ? S : never;
+/**
+ * Utility type for extracting all type parameters from an event.
+ */
+export type ExtractEventTypes<T> = T extends BaseEvent<infer S, infer L1, infer L2, infer L3, infer L4, infer L5> ? {
+    S: S;
+    L1: L1;
+    L2: L2;
+    L3: L3;
+    L4: L4;
+    L5: L5;
+} : never;

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from "./dictionary";
 export * from "./keys";
 export * from "./items";
 export * from "./Coordinate";
+export * from "./Coordinate";
 export { IFactory } from "./item/IFactory";
 export { AItemService } from "./AItemService";
 export * from './key/KUtils';
@@ -13,6 +14,7 @@ export * from './item/ItemQuery';
 export * from './validation';
 export * from './errors';
 export * from './operations';
+export * from './event';
 export type { Operations, OperationParams, AffectedKeys, CreateOptions } from './operations/Operations';
 export { isPriKey as isOperationPriKey, isComKey as isOperationComKey } from './operations/Operations';
 export type { GetMethod, CreateMethod, UpdateMethod, RemoveMethod, UpsertMethod, AllMethod, OneMethod, FindMethod, FindOneMethod, FinderMethod, ActionMethod, ActionOperationMethod, AllActionMethod, AllActionOperationMethod, FacetMethod, FacetOperationMethod, AllFacetMethod, AllFacetOperationMethod, OperationsExtensions } from './operations/methods';