@fjell/core 4.4.48 → 4.4.50

package/README.md

@@ -109,6 +109,98 @@ const query = IQFactory.create('user')
 const results = await IQUtils.execute(query)
 ```
 
+### Operations Interface
+
+@fjell/core provides the standard Operations interface used across all fjell libraries. This interface defines the contract for working with Items:
+
+```typescript
+import { Operations, PrimaryOperations, ContainedOperations } from '@fjell/core';
+
+// For primary items
+const userOps: PrimaryOperations<User, 'user'> = ...;
+
+// For contained items
+const commentOps: ContainedOperations<Comment, 'comment', 'post'> = ...;
+```
+
+See [Operations README](src/operations/README.md) for detailed documentation.
+
+### Validation Module
+
+@fjell/core provides centralized validation functions for ensuring data integrity across the Fjell ecosystem:
+
+```typescript
+import { 
+  validateLocations, 
+  validateKey, 
+  validatePK, 
+  validateKeys 
+} from '@fjell/core/validation';
+```
+
+#### Location Validation
+
+Validates that location key arrays match the expected coordinate hierarchy:
+
+```typescript
+import { validateLocations } from '@fjell/core/validation';
+
+// Validate location array order
+validateLocations(
+  [{ kt: 'store', lk: 'store-1' }],
+  coordinate,
+  'create'  // operation name for error context
+);
+
+// Non-throwing validation
+import { isValidLocations } from '@fjell/core/validation';
+const result = isValidLocations(
+  [{ kt: 'store', lk: 'store-1' }],
+  coordinate,
+  'create'
+);
+if (!result.valid) {
+  console.log(result.error); // Validation error message
+}
+```
+
+#### Key Validation
+
+Validates PriKey and ComKey structures match library type:
+
+```typescript
+import { validateKey, validatePriKey, validateComKey } from '@fjell/core/validation';
+
+// Validate any key type
+validateKey(key, coordinate, 'get');
+
+// Validate specific key types
+validatePriKey(priKey, coordinate, 'update');
+validateComKey(comKey, coordinate, 'remove');
+```
+
+#### Item Validation
+
+Validates Item keys match expected types:
+
+```typescript
+import { validatePK, validateKeys } from '@fjell/core/validation';
+
+// Validate item has correct primary key type
+const validatedItem = validatePK(item, 'product');
+
+// Validate item key types match key type array
+const validatedItem = validateKeys(item, ['product', 'store']);
+```
+
+**Features:**
+- **Comprehensive Error Messages**: Detailed context including operation name, expected vs actual values
+- **Type Safety**: Full TypeScript support with proper type inference
+- **Performance**: Optimized O(n) validation with minimal overhead
+- **Flexible**: Both throwing and non-throwing variants available
+
+See [Validation Examples](examples/validation-example.ts) for detailed usage patterns.
+
 ## Architecture Philosophy
 
 Fjell Core is designed around **progressive enhancement**:

package/dist/Coordinate.d.ts

@@ -0,0 +1,7 @@
+import type { ItemTypeArray } from "./keys";
+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 declare 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>;

package/dist/errors/ActionError.d.ts

@@ -0,0 +1,51 @@
+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 declare class ActionError extends Error {
+    readonly errorInfo: ErrorInfo;
+    constructor(errorInfo: ErrorInfo, cause?: Error);
+    toJSON(): ErrorInfo;
+}

package/dist/errors/BusinessLogicError.d.ts

@@ -0,0 +1,4 @@
+import { ActionError } from './ActionError';
+export declare class BusinessLogicError extends ActionError {
+    constructor(message: string, suggestedAction?: string, retryable?: boolean);
+}

package/dist/errors/DuplicateError.d.ts

@@ -0,0 +1,4 @@
+import { ActionError } from './ActionError';
+export declare class DuplicateError extends ActionError {
+    constructor(message: string, existingItemIdOrKey?: string | number | any, duplicateField?: string);
+}

package/dist/errors/NotFoundError.d.ts

@@ -0,0 +1,4 @@
+import { ActionError } from './ActionError';
+export declare class NotFoundError extends ActionError {
+    constructor(message: string, itemType: string, key?: any);
+}

package/dist/errors/PermissionError.d.ts

@@ -0,0 +1,4 @@
+import { ActionError } from './ActionError';
+export declare class PermissionError extends ActionError {
+    constructor(message: string, requiredPermission?: string, currentPermissions?: string[]);
+}

package/dist/errors/ValidationError.d.ts

@@ -0,0 +1,4 @@
+import { ActionError } from './ActionError';
+export declare class ValidationError extends ActionError {
+    constructor(message: string, validOptions?: string[], suggestedAction?: string, conflictingValue?: any);
+}

package/dist/errors/index.d.ts

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

package/dist/event/emitter.d.ts

@@ -0,0 +1,140 @@
+import { ComKey, ItemTypeArray, LocKeyArray, PriKey } from '../keys';
+import { Item } from '../items';
+import { BaseEvent } 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>;
+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/dist/event/events.d.ts

@@ -0,0 +1,81 @@
+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>;
+}
+/**
+ * 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 declare 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>;
+/**
+ * Type guard to check if an event is an UpdateEvent
+ */
+export declare 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>;
+/**
+ * Type guard to check if an event is a DeleteEvent
+ */
+export declare 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>;
+/**
+ * Type guard to check if an event is an ActionEvent
+ */
+export declare 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>;

package/dist/event/index.d.ts

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

package/dist/event/matching.d.ts

@@ -0,0 +1,54 @@
+import { ComKey, ItemTypeArray, LocKeyArray, PriKey } from '../keys';
+import { BaseEvent } from './events';
+import { Subscription } from './subscription';
+/**
+ * Core subscription matching logic.
+ * Determines whether an event should be delivered to a specific subscription.
+ */
+export declare 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 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 declare function doesScopeMatch(eventScopes: string[], subscriptionScopes?: string[]): boolean;
+/**
+ * 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 declare function doesEventTypeMatch(eventType: string, subscriptionEventTypes?: string[]): boolean;
+/**
+ * Check if two keys are exactly equal.
+ * Used for item-based subscriptions that want events for a specific key.
+ */
+export declare 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;
+/**
+ * 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 declare 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;
+/**
+ * Check if an event's location keys match a subscription's location requirements.
+ * This implements the hierarchical location matching logic.
+ */
+export declare 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>, _subscriptionKta: ItemTypeArray<string, L1, L2, L3, L4, L5>): boolean;
+/**
+ * Find all subscriptions that match a given event.
+ * Used by EventSubscriber implementations to determine which subscriptions should receive an event.
+ */
+export declare 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>[];
+/**
+ * Utility function to extract the location from a ComKey for comparison purposes.
+ * Returns the location key values as strings for easier comparison.
+ */
+export declare 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[];
+/**
+ * Utility function to compare two location arrays by their values.
+ * Useful for debugging and testing location matching logic.
+ */
+export declare 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;

package/dist/event/subscription.d.ts

@@ -0,0 +1,74 @@
+import { ComKey, ItemTypeArray, LocKeyArray, PriKey } from '../keys';
+import { ItemQuery } from '../item/ItemQuery';
+/**
+ * Base subscription interface that all subscription types extend.
+ * Provides core subscription properties with full type safety.
+ */
+export interface BaseSubscription {
+    /** Unique subscription identifier - generated when subscription is created */
+    id: string;
+    /** Optional: specific event types to listen for (defaults to all if not specified) */
+    eventTypes?: string[];
+    /** Optional: storage backends to listen to (defaults to all if not specified) */
+    scopes?: string[];
+    /** Optional: additional filtering criteria using existing ItemQuery system */
+    query?: ItemQuery;
+}
+/**
+ * Subscription to events for a specific item using PriKey or ComKey.
+ * Provides exact item-level event subscriptions with full type safety.
+ */
+export interface ItemSubscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends BaseSubscription {
+    /** The specific key to subscribe to - fully typed PriKey or ComKey */
+    key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>;
+}
+/**
+ * Subscription to events for all items in a location using KTA + location array.
+ * Provides location-based event subscriptions with full type safety.
+ */
+export interface LocationSubscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends BaseSubscription {
+    /** Item type array defining the type hierarchy */
+    kta: ItemTypeArray<S, L1, L2, L3, L4, L5>;
+    /** Location key array defining the specific location */
+    location: LocKeyArray<L1, L2, L3, L4, L5>;
+}
+/**
+ * Union type of all subscription types.
+ * This allows handling any subscription type generically while maintaining type safety.
+ */
+export type Subscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> = ItemSubscription<S, L1, L2, L3, L4, L5> | LocationSubscription<S, L1, L2, L3, L4, L5>;
+/**
+ * Options for creating subscriptions.
+ * Used by convenience methods to create subscriptions without requiring full subscription objects.
+ */
+export interface SubscriptionOptions<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> {
+    /** Optional: specific event types to listen for */
+    eventTypes?: string[];
+    /** Optional: storage backends to listen to */
+    scopes?: string[];
+    /** Optional: additional filtering criteria */
+    query?: ItemQuery;
+}
+/**
+ * Type guard to check if a subscription is an ItemSubscription
+ */
+export declare function isItemSubscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(subscription: Subscription<S, L1, L2, L3, L4, L5>): subscription is ItemSubscription<S, L1, L2, L3, L4, L5>;
+/**
+ * Type guard to check if a subscription is a LocationSubscription
+ */
+export declare function isLocationSubscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(subscription: Subscription<S, L1, L2, L3, L4, L5>): subscription is LocationSubscription<S, L1, L2, L3, L4, L5>;
+/**
+ * Utility function to generate unique subscription IDs.
+ * Libraries can use this or implement their own ID generation strategy.
+ */
+export declare function generateSubscriptionId(): string;
+/**
+ * Utility function to create an ItemSubscription with generated ID.
+ * Simplifies subscription creation for library implementations.
+ */
+export declare function createItemSubscription<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(key: PriKey<S> | ComKey<S, L1, L2, L3, L4, L5>, options?: SubscriptionOptions<S, L1, L2, L3, L4, L5>): ItemSubscription<S, L1, L2, L3, L4, L5>;
+/**
+ * Utility function to create a LocationSubscription with generated ID.
+ * Simplifies subscription creation for library implementations.
+ */
+export declare function createLocationSubscription<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>, location: LocKeyArray<L1, L2, L3, L4, L5>, options?: SubscriptionOptions<S, L1, L2, L3, L4, L5>): LocationSubscription<S, L1, L2, L3, L4, L5>;