@fjell/core 4.4.49 → 4.4.50

package/src/event/events.ts

@@ -0,0 +1,178 @@
+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>;
+  // Note: item property (from BaseEvent) contains current state if provided
+}
+
+/**
+ * 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 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> {
+  return event.eventType === 'create';
+}
+
+/**
+ * Type guard to check if an event is an UpdateEvent
+ */
+export 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> {
+  return event.eventType === 'update';
+}
+
+/**
+ * Type guard to check if an event is a DeleteEvent
+ */
+export 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> {
+  return event.eventType === 'delete';
+}
+
+/**
+ * Type guard to check if an event is an ActionEvent
+ */
+export 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> {
+  return event.eventType === 'action';
+}

package/src/event/index.ts

@@ -0,0 +1,130 @@
+/**
+ * @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
+ */
+
+// Core Event Types
+export {
+  BaseEvent,
+  CreateEvent,
+  UpdateEvent,
+  DeleteEvent,
+  ActionEvent,
+  Event,
+  isCreateEvent,
+  isUpdateEvent,
+  isDeleteEvent,
+  isActionEvent,
+} from './events';
+
+// Subscription Interfaces
+export {
+  BaseSubscription,
+  ItemSubscription,
+  LocationSubscription,
+  Subscription,
+  SubscriptionOptions,
+  isItemSubscription,
+  isLocationSubscription,
+  generateSubscriptionId,
+  createItemSubscription,
+  createLocationSubscription,
+} from './subscription';
+
+// Event Emitter/Subscriber Interfaces
+export {
+  EventEmitter,
+  ScopedEventEmitter,
+  EventSubscriber,
+  EventSystem,
+  EventSystemFactory,
+  // Type aliases for common patterns
+  UserEventEmitter,
+  UserEventSubscriber,
+  UserEventSystem,
+  MessageEventEmitter,
+  MessageEventSubscriber,
+  MessageEventSystem,
+} from './emitter';
+
+// Subscription Matching Logic
+export {
+  doesEventMatchSubscription,
+  doesScopeMatch,
+  doesEventTypeMatch,
+  doesKeyMatch,
+  doesKeyMatchLocation,
+  doesLocationMatch,
+  findMatchingSubscriptions,
+  extractLocationValues,
+  compareLocationValues,
+} from './matching';
+
+// Shared Types and Utilities
+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 const EVENT_SYSTEM_VERSION = '1.0.0';
+
+/**
+ * Supported event types for reference.
+ * Libraries should use these standard types for consistency.
+ */
+export const SUPPORTED_EVENT_TYPES = [
+  'create',
+  'update',
+  'delete',
+  'action',
+] as const;
+
+/**
+ * Supported storage scopes for reference.
+ * Libraries should use these standard scopes for consistency.
+ */
+export const SUPPORTED_SCOPES = [
+  'firestore',
+  'sequelize',
+  'postgresql',
+  'mysql',
+  'mongodb',
+  'redis',
+] as const;

package/src/event/matching.ts

@@ -0,0 +1,264 @@
+import { ComKey, ItemTypeArray, LocKeyArray, PriKey } from '../keys';
+import { isComKey, isPriKey } from '../operations/Operations';
+import { BaseEvent } from './events';
+import { isItemSubscription, isLocationSubscription, Subscription } from './subscription';
+
+/**
+ * Core subscription matching logic.
+ * Determines whether an event should be delivered to a specific subscription.
+ */
+export 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 scope compatibility first (most efficient filter)
+  if (!doesScopeMatch(event.scopes, subscription.scopes)) {
+    return false;
+  }
+
+  // Check event type compatibility
+  if (!doesEventTypeMatch(event.eventType, subscription.eventTypes)) {
+    return false;
+  }
+
+  // Check key/location pattern matching
+  if (isItemSubscription(subscription)) {
+    return doesKeyMatch(event.key, subscription.key);
+  } else if (isLocationSubscription(subscription)) {
+    return doesKeyMatchLocation(event.key, subscription.kta, subscription.location);
+  }
+
+  return false;
+}
+
+/**
+ * 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 function doesScopeMatch(
+  eventScopes: string[],
+  subscriptionScopes?: string[]
+): boolean {
+  // If subscription doesn't specify scopes, accept events from any scope
+  if (!subscriptionScopes || subscriptionScopes.length === 0) {
+    return true;
+  }
+
+  // Check if any of the event's scopes match any of the subscription's required scopes
+  return subscriptionScopes.some(requiredScope =>
+    eventScopes.includes(requiredScope)
+  );
+}
+
+/**
+ * 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 function doesEventTypeMatch(
+  eventType: string,
+  subscriptionEventTypes?: string[]
+): boolean {
+  // If subscription doesn't specify event types, accept all event types
+  if (!subscriptionEventTypes || subscriptionEventTypes.length === 0) {
+    return true;
+  }
+
+  // Check if the event type is in the subscription's allowed types
+  return subscriptionEventTypes.includes(eventType);
+}
+
+/**
+ * Check if two keys are exactly equal.
+ * Used for item-based subscriptions that want events for a specific key.
+ */
+export 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 {
+  // Both must be the same type (PriKey or ComKey)
+  if (isPriKey(eventKey) && isPriKey(subscriptionKey)) {
+    return eventKey.pk === subscriptionKey.pk && eventKey.kt === subscriptionKey.kt;
+  }
+
+  if (isComKey(eventKey) && isComKey(subscriptionKey)) {
+    const eventComKey = eventKey as ComKey<S, L1, L2, L3, L4, L5>;
+    const subscriptionComKey = subscriptionKey as ComKey<S, L1, L2, L3, L4, L5>;
+    
+    // Compare primary key and key type
+    if (eventComKey.pk !== subscriptionComKey.pk || eventComKey.kt !== subscriptionComKey.kt) {
+      return false;
+    }
+
+    // Compare location arrays
+    if (eventComKey.loc.length !== subscriptionComKey.loc.length) {
+      return false;
+    }
+
+    // Check each location key
+    return eventComKey.loc.every((eventLocKey, index) => {
+      const subLocKey = subscriptionComKey.loc[index];
+      return eventLocKey.lk === subLocKey.lk && eventLocKey.kt === subLocKey.kt;
+    });
+  }
+
+  return false; // Different key types don't match
+}
+
+/**
+ * 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 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 {
+  // First, check if the key type matches the target type in the KTA
+  const targetItemType = subscriptionKta[subscriptionKta.length - 1];
+  if (eventKey.kt !== targetItemType) {
+    return false;
+  }
+
+  // For PriKey events
+  if (isPriKey(eventKey)) {
+    // PriKey can only match location subscriptions with empty locations (root level)
+    return subscriptionLocation.length === 0;
+  }
+
+  // For ComKey events
+  if (isComKey(eventKey)) {
+    const comKey = eventKey as ComKey<S, L1, L2, L3, L4, L5>;
+    // The event's location must match the subscription location exactly or be a sub-location
+    return doesLocationMatch(comKey.loc, subscriptionLocation, subscriptionKta);
+  }
+
+  return false;
+}
+
+/**
+ * Check if an event's location keys match a subscription's location requirements.
+ * This implements the hierarchical location matching logic.
+ */
+export 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>,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  _subscriptionKta: ItemTypeArray<string, L1, L2, L3, L4, L5>
+): boolean {
+  // If subscription location is empty, it matches all locations (root level subscription)
+  if (subscriptionLocation.length === 0) {
+    return true;
+  }
+
+  // Event location must be at least as deep as subscription location
+  if (eventLocation.length < subscriptionLocation.length) {
+    return false;
+  }
+
+  // Check that all subscription location keys match the corresponding event location keys
+  for (let i = 0; i < subscriptionLocation.length; i++) {
+    const eventLocKey = eventLocation[i];
+    const subLocKey = subscriptionLocation[i];
+
+    if (!eventLocKey || !subLocKey) {
+      return false;
+    }
+
+    if (eventLocKey.lk !== subLocKey.lk || eventLocKey.kt !== subLocKey.kt) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Find all subscriptions that match a given event.
+ * Used by EventSubscriber implementations to determine which subscriptions should receive an event.
+ */
+export 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>[] {
+  return subscriptions.filter(subscription =>
+    doesEventMatchSubscription(event, subscription)
+  );
+}
+
+/**
+ * Utility function to extract the location from a ComKey for comparison purposes.
+ * Returns the location key values as strings for easier comparison.
+ */
+export 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[] {
+  return location.map(locKey => String(locKey.lk));
+}
+
+/**
+ * Utility function to compare two location arrays by their values.
+ * Useful for debugging and testing location matching logic.
+ */
+export 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 {
+  if (location1.length !== location2.length) {
+    return false;
+  }
+
+  return location1.every((locKey1, index) => {
+    const locKey2 = location2[index];
+    return locKey1.lk === locKey2.lk && locKey1.kt === locKey2.kt;
+  });
+}