@fjell/core 4.4.49 → 4.4.51

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.51",
   "keywords": [
     "core",
     "fjell"
@@ -41,14 +41,14 @@
     "docs:test": "cd docs && npm run test"
   },
   "dependencies": {
-    "@fjell/logging": "^4.4.49",
+    "@fjell/logging": "^4.4.50",
     "deepmerge": "^4.3.1",
     "luxon": "^3.7.1"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.32.0",
-    "@fjell/eslint-config": "^1.1.25",
+    "@fjell/eslint-config": "^1.1.28",
     "@swc/core": "^1.13.2",
     "@tsconfig/recommended": "^1.0.10",
     "@types/luxon": "^3.6.2",

package/src/AItemService.ts

@@ -1,38 +0,0 @@
-import { AllItemTypeArrays } from "./keys";
-
-export class AItemService<
-  S extends string,
-  L1 extends string,
-  L2 extends string = never,
-  L3 extends string = never,
-  L4 extends string = never,
-  L5 extends string = never
-> {
-
-  private pkType: S;
-  private parentService: AItemService<L1, L2, L3, L4, L5, never> | null = null;
-
-  constructor(
-    pkType: S,
-    parentService?: AItemService<L1, L2, L3, L4, L5, never>,
-  ) {
-    this.pkType = pkType;
-    if (parentService) {
-      this.parentService = parentService;
-    }
-  }
-
-  public getPkType = (): S => {
-    return this.pkType;
-  }
-
-  public getKeyTypes = (): AllItemTypeArrays<S, L1, L2, L3, L4, L5> => {
-    let keyTypes: readonly string[] = [this.getPkType()];
-
-    if (this.parentService) {
-      keyTypes = keyTypes.concat(this.parentService.getKeyTypes());
-    }
-    return keyTypes as AllItemTypeArrays<S, L1, L2, L3, L4, L5>;
-  }
-
-}

package/src/Coordinate.ts

@@ -1,35 +0,0 @@
-import type { ItemTypeArray } from "./keys";
-import LibLogger from "./logger";
-
-const logger = LibLogger.get("Coordinate");
-
-export interface Coordinate<
-  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>;
-  scopes: string[];
-  toString: () => string;
-}
-
-export const createCoordinate = <
-  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> | S, scopes: string[] = []): Coordinate<S, L1, L2, L3, L4, L5> => {
-  const ktArray = Array.isArray(kta) ? kta : [kta];
-  const toString = () => {
-    logger.debug("toString", { kta, scopes });
-    return `${ktArray.join(', ')} - ${scopes.join(', ')}`;
-  }
-  logger.debug("createCoordinate", { kta: ktArray, scopes, toString });
-  return { kta: ktArray as ItemTypeArray<S, L1, L2, L3, L4, L5>, scopes, toString };
-}
-

package/src/dictionary.ts

@@ -1,84 +0,0 @@
-import LibLogger from "./logger";
-
-const logger = LibLogger.get("Dictionary");
-
-interface DictionaryEntry<T, V> {
-  originalKey: T;
-  value: V;
-}
-
-export class Dictionary<T, V> {
-  protected map: { [key: string]: DictionaryEntry<T, V> } = {}
-  protected hashFunction = (key: T) => JSON.stringify(key);
-
-  constructor(map?: { [key: string]: V }, hashFunction?: (key: T) => string) {
-    if (hashFunction) {
-      this.hashFunction = hashFunction
-    }
-    if (map) {
-      // Convert legacy map format to new format
-      Object.entries(map).forEach(([hashedKey, value]) => {
-        try {
-          // Try to parse the key if it looks like JSON
-          const originalKey = JSON.parse(hashedKey) as T;
-          this.map[hashedKey] = { originalKey, value };
-        } catch {
-          // If parsing fails, we can't recover the original key
-          logger.warning('Cannot recover original key from legacy map entry', { hashedKey });
-        }
-      });
-    }
-  }
-
-  public set(key: T, item: V): void {
-    logger.trace('set', { key, item });
-    const hashedKey = this.hashFunction(key);
-    this.map[hashedKey] = { originalKey: key, value: item };
-  }
-
-  public get(key: T): V | null {
-    logger.trace('get', { key });
-    const hashedKey = this.hashFunction(key);
-    const entry = this.map[hashedKey];
-    // Check if entry exists AND the original key matches the requested key
-    return entry && this.keysEqual(entry.originalKey, key) ? entry.value : null;
-  }
-
-  private keysEqual(key1: T, key2: T): boolean {
-    // For basic equality check - this works for primitives and object references
-    // For deep equality, users can provide a custom hash function that avoids collisions
-    return key1 === key2;
-  }
-
-  public delete(key: T): void {
-    logger.trace('delete', { key });
-    const hashedKey = this.hashFunction(key);
-    delete this.map[hashedKey];
-  }
-
-  public keys(): T[] {
-    return Object.values(this.map).map(entry => entry.originalKey);
-  }
-
-  public values(): V[] {
-    return Object.values(this.map).map(entry => entry.value);
-  }
-
-  public includesKey(key: T): boolean {
-    const hashedKey = this.hashFunction(key);
-    const entry = this.map[hashedKey];
-    return entry ? this.keysEqual(entry.originalKey, key) : false;
-  }
-
-  public clone(): Dictionary<T, V> {
-    const clonedMap: { [key: string]: V } = {};
-    Object.entries(this.map).forEach(([hashedKey, entry]) => {
-      clonedMap[hashedKey] = entry.value;
-    });
-
-    const clone = new Dictionary<T, V>(clonedMap, this.hashFunction);
-    // Copy the entries directly to preserve original keys
-    clone.map = Object.assign({}, this.map);
-    return clone;
-  }
-}

package/src/errors/ActionError.ts

@@ -1,69 +0,0 @@
-export interface ErrorInfo {
-  code: string;
-  message: string;
-  operation: {
-    type: 'get' | 'create' | 'update' | 'remove' | 'upsert' |
-          'all' | 'one' | 'find' | 'findOne' |
-          'action' | 'allAction' | 'facet' | 'allFacet';
-    name: string;
-    params: Record<string, any>;
-  };
-  context: {
-    itemType: string;
-    key?: {
-      primary?: string | number;
-      composite?: {
-        sk: string | number;
-        kta: string[];
-        locations?: Array<{ lk: string | number; kt: string }>;
-      };
-    };
-    affectedItems?: Array<{
-      id: string | number;
-      type: string;
-      displayName?: string;
-    }>;
-    parentLocation?: {
-      id: string | number;
-      type: string;
-    };
-    requiredPermission?: string;
-  };
-  details?: {
-    validOptions?: string[];
-    suggestedAction?: string;
-    retryable?: boolean;
-    conflictingValue?: any;
-    expectedValue?: any;
-  };
-  technical?: {
-    timestamp: string;
-    requestId?: string;
-    stackTrace?: string;
-    cause?: any;
-  };
-}
-
-export class ActionError extends Error {
-  constructor(
-    public readonly errorInfo: ErrorInfo,
-    cause?: Error
-  ) {
-    super(errorInfo.message);
-    this.name = 'ActionError';
-    this.cause = cause;
-    
-    // Ensure timestamp is always set
-    if (!this.errorInfo.technical) {
-      this.errorInfo.technical = { timestamp: new Date().toISOString() };
-    }
-    if (!this.errorInfo.technical.timestamp) {
-      this.errorInfo.technical.timestamp = new Date().toISOString();
-    }
-  }
-
-  toJSON(): ErrorInfo {
-    return this.errorInfo;
-  }
-}
-

package/src/errors/BusinessLogicError.ts

@@ -1,24 +0,0 @@
-import { ActionError } from './ActionError';
-
-export class BusinessLogicError extends ActionError {
-  constructor(
-    message: string,
-    suggestedAction?: string,
-    retryable: boolean = false
-  ) {
-    super({
-      code: 'BUSINESS_LOGIC_ERROR',
-      message,
-      operation: { type: 'action', name: '', params: {} },
-      context: { itemType: '' },
-      details: {
-        suggestedAction,
-        retryable
-      },
-      technical: {
-        timestamp: new Date().toISOString()
-      }
-    });
-  }
-}
-

package/src/errors/DuplicateError.ts

@@ -1,57 +0,0 @@
-import { ActionError } from './ActionError';
-
-export class DuplicateError extends ActionError {
-  constructor(
-    message: string,
-    existingItemIdOrKey?: string | number | any,
-    duplicateField?: string
-  ) {
-    // Extract ID and build key info
-    let existingItemId: string | number | null = null;
-    let keyInfo: any = null;
-    
-    if (typeof existingItemIdOrKey === 'object' && existingItemIdOrKey !== null) {
-      // It's a key object - extract the primary key value and build proper key structure
-      existingItemId = existingItemIdOrKey.pk || existingItemIdOrKey.id || existingItemIdOrKey.primary || null;
-      
-      // Build key info with primary field set
-      if (existingItemId !== null) {
-        keyInfo = {
-          primary: existingItemId,
-          ...existingItemIdOrKey
-        };
-      } else {
-        keyInfo = existingItemIdOrKey;
-      }
-    } else if (typeof existingItemIdOrKey !== 'undefined') {
-      // It's a simple ID
-      existingItemId = existingItemIdOrKey;
-      keyInfo = { primary: existingItemId };
-    }
-    
-    super({
-      code: 'DUPLICATE_ERROR',
-      message,
-      operation: { type: 'create', name: '', params: {} },
-      context: {
-        itemType: '',
-        ...(keyInfo && { key: keyInfo }),
-        ...(existingItemId && {
-          affectedItems: [{
-            id: existingItemId,
-            type: '',
-            displayName: `Existing item with ${duplicateField || 'key'}`
-          }]
-        })
-      },
-      details: {
-        retryable: false,
-        conflictingValue: duplicateField
-      },
-      technical: {
-        timestamp: new Date().toISOString()
-      }
-    });
-  }
-}
-

package/src/errors/NotFoundError.ts

@@ -1,24 +0,0 @@
-import { ActionError } from './ActionError';
-
-export class NotFoundError extends ActionError {
-  constructor(
-    message: string,
-    itemType: string,
-    key?: any
-  ) {
-    super({
-      code: 'NOT_FOUND',
-      message,
-      operation: { type: 'get', name: '', params: {} },
-      context: {
-        itemType,
-        key: typeof key === 'object' ? key : { primary: key }
-      },
-      details: { retryable: false },
-      technical: {
-        timestamp: new Date().toISOString()
-      }
-    });
-  }
-}
-