@fjell/core 4.4.49 → 4.4.50

package/dist/index.js

@@ -1519,6 +1519,50 @@ function getErrorInfo(error) {
   };
 }
 
+// src/event/events.ts
+function isCreateEvent(event) {
+  return event.eventType === "create";
+}
+function isUpdateEvent(event) {
+  return event.eventType === "update";
+}
+function isDeleteEvent(event) {
+  return event.eventType === "delete";
+}
+function isActionEvent(event) {
+  return event.eventType === "action";
+}
+
+// src/event/subscription.ts
+function isItemSubscription(subscription) {
+  return "key" in subscription;
+}
+function isLocationSubscription(subscription) {
+  return "kta" in subscription && "location" in subscription;
+}
+function generateSubscriptionId() {
+  return `sub-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+function createItemSubscription(key, options) {
+  return {
+    id: generateSubscriptionId(),
+    key,
+    eventTypes: options?.eventTypes,
+    scopes: options?.scopes,
+    query: options?.query
+  };
+}
+function createLocationSubscription(kta, location, options) {
+  return {
+    id: generateSubscriptionId(),
+    kta,
+    location,
+    eventTypes: options?.eventTypes,
+    scopes: options?.scopes,
+    query: options?.query
+  };
+}
+
 // src/operations/Operations.ts
 function isPriKey2(key) {
   return !("loc" in key) || !key.loc;
@@ -1527,6 +1571,203 @@ function isComKey2(key) {
   return "loc" in key && key.loc && Array.isArray(key.loc) && key.loc.length > 0;
 }
 
+// src/event/matching.ts
+function doesEventMatchSubscription(event, subscription) {
+  if (!doesScopeMatch(event.scopes, subscription.scopes)) {
+    return false;
+  }
+  if (!doesEventTypeMatch(event.eventType, subscription.eventTypes)) {
+    return false;
+  }
+  if (isItemSubscription(subscription)) {
+    return doesKeyMatch(event.key, subscription.key);
+  } else if (isLocationSubscription(subscription)) {
+    return doesKeyMatchLocation(event.key, subscription.kta, subscription.location);
+  }
+  return false;
+}
+function doesScopeMatch(eventScopes, subscriptionScopes) {
+  if (!subscriptionScopes || subscriptionScopes.length === 0) {
+    return true;
+  }
+  return subscriptionScopes.some(
+    (requiredScope) => eventScopes.includes(requiredScope)
+  );
+}
+function doesEventTypeMatch(eventType, subscriptionEventTypes) {
+  if (!subscriptionEventTypes || subscriptionEventTypes.length === 0) {
+    return true;
+  }
+  return subscriptionEventTypes.includes(eventType);
+}
+function doesKeyMatch(eventKey, subscriptionKey) {
+  if (isPriKey2(eventKey) && isPriKey2(subscriptionKey)) {
+    return eventKey.pk === subscriptionKey.pk && eventKey.kt === subscriptionKey.kt;
+  }
+  if (isComKey2(eventKey) && isComKey2(subscriptionKey)) {
+    const eventComKey = eventKey;
+    const subscriptionComKey = subscriptionKey;
+    if (eventComKey.pk !== subscriptionComKey.pk || eventComKey.kt !== subscriptionComKey.kt) {
+      return false;
+    }
+    if (eventComKey.loc.length !== subscriptionComKey.loc.length) {
+      return false;
+    }
+    return eventComKey.loc.every((eventLocKey, index) => {
+      const subLocKey = subscriptionComKey.loc[index];
+      return eventLocKey.lk === subLocKey.lk && eventLocKey.kt === subLocKey.kt;
+    });
+  }
+  return false;
+}
+function doesKeyMatchLocation(eventKey, subscriptionKta, subscriptionLocation) {
+  const targetItemType = subscriptionKta[subscriptionKta.length - 1];
+  if (eventKey.kt !== targetItemType) {
+    return false;
+  }
+  if (isPriKey2(eventKey)) {
+    return subscriptionLocation.length === 0;
+  }
+  if (isComKey2(eventKey)) {
+    const comKey = eventKey;
+    return doesLocationMatch(comKey.loc, subscriptionLocation, subscriptionKta);
+  }
+  return false;
+}
+function doesLocationMatch(eventLocation, subscriptionLocation, _subscriptionKta) {
+  if (subscriptionLocation.length === 0) {
+    return true;
+  }
+  if (eventLocation.length < subscriptionLocation.length) {
+    return false;
+  }
+  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;
+}
+function findMatchingSubscriptions(event, subscriptions) {
+  return subscriptions.filter(
+    (subscription) => doesEventMatchSubscription(event, subscription)
+  );
+}
+function extractLocationValues(location) {
+  return location.map((locKey) => String(locKey.lk));
+}
+function compareLocationValues(location1, location2) {
+  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;
+  });
+}
+
+// src/event/types.ts
+var STANDARD_EVENT_TYPES = {
+  CREATE: "create",
+  UPDATE: "update",
+  DELETE: "delete",
+  ACTION: "action"
+};
+var STANDARD_SCOPES = {
+  FIRESTORE: "firestore",
+  SEQUELIZE: "sequelize",
+  POSTGRESQL: "postgresql",
+  MYSQL: "mysql",
+  MONGODB: "mongodb",
+  REDIS: "redis"
+};
+var SubscriptionStatus = /* @__PURE__ */ ((SubscriptionStatus2) => {
+  SubscriptionStatus2["PENDING"] = "pending";
+  SubscriptionStatus2["ACTIVE"] = "active";
+  SubscriptionStatus2["PAUSED"] = "paused";
+  SubscriptionStatus2["ERROR"] = "error";
+  SubscriptionStatus2["CANCELLED"] = "cancelled";
+  return SubscriptionStatus2;
+})(SubscriptionStatus || {});
+var DEFAULT_EVENT_CONFIG = {
+  maxBatchSize: 100,
+  maxBatchWaitTime: 50,
+  // 50ms
+  maxRetryAttempts: 3,
+  retryDelay: 1e3,
+  // 1 second
+  enableStats: true,
+  maxSubscriptions: 1e3,
+  subscriptionCleanupInterval: 3e5
+  // 5 minutes
+};
+var EventSystemError = class extends Error {
+  constructor(message, code, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "EventSystemError";
+  }
+};
+var SubscriptionError = class extends EventSystemError {
+  constructor(message, subscriptionId, details) {
+    super(message, "SUBSCRIPTION_ERROR", { subscriptionId, ...details });
+    this.subscriptionId = subscriptionId;
+    this.name = "SubscriptionError";
+  }
+};
+var EventEmissionError = class extends EventSystemError {
+  constructor(message, eventType, details) {
+    super(message, "EVENT_EMISSION_ERROR", { eventType, ...details });
+    this.eventType = eventType;
+    this.name = "EventEmissionError";
+  }
+};
+var EventMatchingError = class extends EventSystemError {
+  constructor(message, details) {
+    super(message, "EVENT_MATCHING_ERROR", details);
+    this.name = "EventMatchingError";
+  }
+};
+function createEventSystemError(type, message, details) {
+  switch (type) {
+    case "subscription":
+      return new SubscriptionError(message, details?.subscriptionId || "unknown", details);
+    case "emission":
+      return new EventEmissionError(message, details?.eventType || "unknown", details);
+    case "matching":
+      return new EventMatchingError(message, details);
+    case "general":
+    default:
+      return new EventSystemError(message, "GENERAL_ERROR", details);
+  }
+}
+function isEventSystemError(error) {
+  return error instanceof EventSystemError;
+}
+
+// src/event/index.ts
+var EVENT_SYSTEM_VERSION = "1.0.0";
+var SUPPORTED_EVENT_TYPES = [
+  "create",
+  "update",
+  "delete",
+  "action"
+];
+var SUPPORTED_SCOPES = [
+  "firestore",
+  "sequelize",
+  "postgresql",
+  "mysql",
+  "mongodb",
+  "redis"
+];
+
 // src/operations/wrappers/createOneWrapper.ts
 var logger9 = logger_default.get("operations", "wrappers", "one");
 function createOneWrapper(coordinate, implementation, options = {}) {
@@ -2078,12 +2319,23 @@ export {
   AItemService,
   ActionError,
   BusinessLogicError,
+  DEFAULT_EVENT_CONFIG,
   Dictionary,
   DuplicateError,
+  EVENT_SYSTEM_VERSION,
+  EventEmissionError,
+  EventMatchingError,
+  EventSystemError,
   IFactory,
   IQFactory,
   NotFoundError,
   PermissionError,
+  STANDARD_EVENT_TYPES,
+  STANDARD_SCOPES,
+  SUPPORTED_EVENT_TYPES,
+  SUPPORTED_SCOPES,
+  SubscriptionError,
+  SubscriptionStatus,
   ValidationError,
   abbrevAgg,
   abbrevCompoundCondition,
@@ -2093,6 +2345,7 @@ export {
   abbrevQuery,
   abbrevRef,
   cPK,
+  compareLocationValues,
   constructPriKey,
   createActionWrapper,
   createAllActionWrapper,
@@ -2100,34 +2353,52 @@ export {
   createAllWrapper,
   createCoordinate,
   createCreateWrapper,
+  createEventSystemError,
   createFacetWrapper,
   createFindOneWrapper,
   createFindWrapper,
   createGetWrapper,
+  createItemSubscription,
+  createLocationSubscription,
   createNormalizedHashFunction,
   createOneWrapper,
   createRemoveWrapper,
   createUpdateWrapper,
   createUpsertWrapper,
+  doesEventMatchSubscription,
+  doesEventTypeMatch,
+  doesKeyMatch,
+  doesKeyMatchLocation,
+  doesLocationMatch,
+  doesScopeMatch,
   enhanceError,
   executeWithContext,
   executeWithContextSync,
   extractKeyTypeArray,
+  extractLocationValues,
+  findMatchingSubscriptions,
   generateKeyArray,
+  generateSubscriptionId,
   getErrorInfo,
   ikToLKA,
   isActionError,
+  isActionEvent,
   isComItem,
   isComKey,
   isComKeyEqual,
   isComKeyEqualNormalized,
   isCondition,
+  isCreateEvent,
+  isDeleteEvent,
+  isEventSystemError,
   isItemKey,
   isItemKeyEqual,
   isItemKeyEqualNormalized,
+  isItemSubscription,
   isLocKey,
   isLocKeyEqual,
   isLocKeyEqualNormalized,
+  isLocationSubscription,
   isComKey2 as isOperationComKey,
   isPriKey2 as isOperationPriKey,
   isPriItem,
@@ -2135,6 +2406,7 @@ export {
   isPriKeyEqual,
   isPriKeyEqualNormalized,
   isQueryMatch,
+  isUpdateEvent,
   isValidComKey,
   isValidItemKey,
   isValidLocKey,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/core",
   "description": "Core Item and Key Framework for Fjell",
-  "version": "4.4.49",
+  "version": "4.4.50",
   "keywords": [
     "core",
     "fjell"

package/src/event/emitter.ts

@@ -0,0 +1,247 @@
+import { ComKey, ItemTypeArray, LocKeyArray, PriKey } from '../keys';
+import { Item } from '../items';
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { ActionEvent, BaseEvent, CreateEvent, DeleteEvent, UpdateEvent } 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>;
+
+// Type aliases for common usage patterns in libraries
+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>;