@fjell/core 4.4.48 → 4.4.50

package/src/errors/ActionError.ts

@@ -0,0 +1,69 @@
+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

@@ -0,0 +1,24 @@
+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

@@ -0,0 +1,57 @@
+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

@@ -0,0 +1,24 @@
+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()
+      }
+    });
+  }
+}
+

package/src/errors/PermissionError.ts

@@ -0,0 +1,31 @@
+import { ActionError } from './ActionError';
+
+export class PermissionError extends ActionError {
+  constructor(
+    message: string,
+    requiredPermission?: string,
+    currentPermissions?: string[]
+  ) {
+    super({
+      code: 'PERMISSION_DENIED',
+      message,
+      operation: { type: 'action', name: '', params: {} },
+      context: {
+        itemType: '',
+        ...(requiredPermission && { requiredPermission })
+      },
+      details: {
+        ...(requiredPermission && {
+          suggestedAction: `Required permission: ${requiredPermission}`,
+          expectedValue: requiredPermission
+        }),
+        ...(currentPermissions && { conflictingValue: currentPermissions }),
+        retryable: false
+      },
+      technical: {
+        timestamp: new Date().toISOString()
+      }
+    });
+  }
+}
+

package/src/errors/ValidationError.ts

@@ -0,0 +1,27 @@
+import { ActionError } from './ActionError';
+
+export class ValidationError extends ActionError {
+  constructor(
+    message: string,
+    validOptions?: string[],
+    suggestedAction?: string,
+    conflictingValue?: any
+  ) {
+    super({
+      code: 'VALIDATION_ERROR',
+      message,
+      operation: { type: 'create', name: '', params: {} }, // Will be filled by wrapper
+      context: { itemType: '' }, // Will be filled by wrapper
+      details: {
+        validOptions,
+        suggestedAction,
+        retryable: true,
+        conflictingValue
+      },
+      technical: {
+        timestamp: new Date().toISOString()
+      }
+    });
+  }
+}
+

package/src/errors/index.ts

@@ -0,0 +1,7 @@
+export * from './ActionError';
+export * from './ValidationError';
+export * from './NotFoundError';
+export * from './BusinessLogicError';
+export * from './PermissionError';
+export * from './DuplicateError';
+

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>;

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';
+}