@fjell/core 4.4.50 → 4.4.51

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/core",
   "description": "Core Item and Key Framework for Fjell",
-  "version": "4.4.50",
+  "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()
-      }
-    });
-  }
-}
-

package/src/errors/PermissionError.ts

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

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

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

package/src/event/emitter.ts

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