@semiont/event-sourcing 0.2.28-build.40

package/dist/index.d.ts

@@ -0,0 +1,606 @@
+import { ResourceId, ResourceAnnotations, AnnotationId, ResourceEvent, StoredEvent, EventQuery as EventQuery$1 } from '@semiont/core';
+import { components, ResourceUri, AnnotationUri } from '@semiont/api-client';
+
+/**
+ * View Storage - Materialized Views
+ *
+ * Stores materialized views of resource state and annotations
+ * Built from event streams, can be rebuilt at any time
+ *
+ * Stores both ResourceDescriptor metadata and ResourceAnnotations, but keeps them logically separate
+ */
+
+type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
+interface ResourceView {
+    resource: ResourceDescriptor;
+    annotations: ResourceAnnotations;
+}
+interface ViewStorage {
+    save(resourceId: ResourceId, view: ResourceView): Promise<void>;
+    get(resourceId: ResourceId): Promise<ResourceView | null>;
+    delete(resourceId: ResourceId): Promise<void>;
+    exists(resourceId: ResourceId): Promise<boolean>;
+    getAll(): Promise<ResourceView[]>;
+}
+declare class FilesystemViewStorage implements ViewStorage {
+    private basePath;
+    constructor(basePath: string, projectRoot?: string);
+    private getProjectionPath;
+    save(resourceId: ResourceId, projection: ResourceView): Promise<void>;
+    get(resourceId: ResourceId): Promise<ResourceView | null>;
+    delete(resourceId: ResourceId): Promise<void>;
+    exists(resourceId: ResourceId): Promise<boolean>;
+    getAll(): Promise<ResourceView[]>;
+}
+
+/**
+ * Type definitions for event-sourcing package
+ */
+interface IdentifierConfig {
+    baseUrl: string;
+}
+
+/**
+ * Identifier conversion functions - Convert between short IDs and W3C-compliant HTTP URIs
+ *
+ * These functions handle the conversion between:
+ * - Short IDs (e.g., "abc123") - used internally in events
+ * - HTTP URIs (e.g., "http://localhost:4000/resources/abc123") - used in API responses
+ *
+ * The W3C Web Annotation Model requires HTTP(S) URIs for @id fields.
+ *
+ * All functions are pure - they take config explicitly as a parameter.
+ */
+
+declare function toResourceUri(config: IdentifierConfig, id: ResourceId): ResourceUri;
+declare function toAnnotationUri(config: IdentifierConfig, id: AnnotationId): AnnotationUri;
+
+/**
+ * Event Storage - Physical Storage Layer
+ *
+ * Handles file I/O operations for event storage:
+ * - JSONL file writing/reading
+ * - 4-hex sharding (65,536 shards)
+ * - File rotation
+ * - Event stream initialization
+ *
+ * @see docs/EVENT-STORE.md#eventstorage for architecture details
+ */
+
+interface EventStorageConfig {
+    basePath: string;
+    dataDir: string;
+    maxEventsPerFile?: number;
+    enableSharding?: boolean;
+    numShards?: number;
+    enableCompression?: boolean;
+}
+/**
+ * EventStorage handles physical storage of events
+ * Owns: file I/O, sharding, AND sequence/hash tracking
+ */
+declare class EventStorage {
+    private config;
+    private resourceSequences;
+    private resourceLastHash;
+    constructor(config: EventStorageConfig);
+    /**
+     * Calculate shard path for a resource ID
+     * Uses jump consistent hash for uniform distribution
+     * Special case: __system__ events bypass sharding
+     */
+    getShardPath(resourceId: ResourceId): string;
+    /**
+     * Get full path to resource's event directory
+     */
+    getResourcePath(resourceId: ResourceId): string;
+    /**
+     * Initialize directory structure for a resource's event stream
+     * Also loads sequence number and last hash if stream exists
+     */
+    initializeResourceStream(resourceId: ResourceId): Promise<void>;
+    /**
+     * Append an event - handles EVERYTHING for event creation
+     * Creates ID, timestamp, metadata, checksum, sequence tracking, and writes to disk
+     */
+    appendEvent(event: Omit<ResourceEvent, 'id' | 'timestamp'>, resourceId: ResourceId): Promise<StoredEvent>;
+    /**
+     * Write an event to storage (append to JSONL)
+     * Internal method - use appendEvent() instead
+     */
+    private writeEvent;
+    /**
+     * Count events in a specific file
+     */
+    countEventsInFile(resourceId: ResourceId, filename: string): Promise<number>;
+    /**
+     * Read all events from a specific file
+     */
+    readEventsFromFile(resourceId: ResourceId, filename: string): Promise<StoredEvent[]>;
+    /**
+     * Get list of event files for a resource (sorted by sequence)
+     */
+    getEventFiles(resourceId: ResourceId): Promise<string[]>;
+    /**
+     * Create a new event file for rotation
+     */
+    createNewEventFile(resourceId: ResourceId): Promise<string>;
+    /**
+     * Get the last event from a specific file
+     */
+    getLastEvent(resourceId: ResourceId, filename: string): Promise<StoredEvent | null>;
+    /**
+     * Get all events for a resource across all files
+     */
+    getAllEvents(resourceId: ResourceId): Promise<StoredEvent[]>;
+    /**
+     * Get all resource IDs by scanning shard directories
+     */
+    getAllResourceIds(): Promise<ResourceId[]>;
+    /**
+     * Create filename for event file
+     */
+    private createEventFilename;
+    /**
+     * Get current sequence number for a resource
+     */
+    getSequenceNumber(resourceId: ResourceId): number;
+    /**
+     * Increment and return next sequence number for a resource
+     */
+    getNextSequenceNumber(resourceId: ResourceId): number;
+    /**
+     * Get last event hash for a resource
+     */
+    getLastEventHash(resourceId: ResourceId): string | null;
+    /**
+     * Set last event hash for a resource
+     */
+    setLastEventHash(resourceId: ResourceId, hash: string): void;
+}
+
+/**
+ * EventLog - Event Persistence Layer
+ *
+ * Single Responsibility: Event persistence only
+ * - Appends events to storage (JSONL files)
+ * - Retrieves events by resource
+ * - Queries events with filters
+ *
+ * Does NOT handle:
+ * - Pub/sub notifications (see EventBus)
+ * - View updates (see ViewManager)
+ */
+
+interface EventLogConfig {
+    basePath: string;
+    dataDir: string;
+    enableSharding?: boolean;
+    maxEventsPerFile?: number;
+}
+declare class EventLog {
+    readonly storage: EventStorage;
+    constructor(config: EventLogConfig);
+    /**
+     * Append event to log
+     * @param event - Resource event (from @semiont/core)
+     * @param resourceId - Branded ResourceId (from @semiont/core)
+     * @returns Stored event with metadata (sequence number, timestamp, checksum)
+     */
+    append(event: Omit<ResourceEvent, 'id' | 'timestamp'>, resourceId: ResourceId): Promise<StoredEvent>;
+    /**
+     * Get all events for a resource
+     * @param resourceId - Branded ResourceId (from @semiont/core)
+     */
+    getEvents(resourceId: ResourceId): Promise<StoredEvent[]>;
+    /**
+     * Get all resource IDs
+     * @returns Array of branded ResourceId types
+     */
+    getAllResourceIds(): Promise<ResourceId[]>;
+    /**
+     * Query events with filter
+     * @param resourceId - Branded ResourceId (from @semiont/core)
+     * @param filter - Optional event filter
+     */
+    queryEvents(resourceId: ResourceId, filter?: EventQuery$1): Promise<StoredEvent[]>;
+}
+
+/**
+ * Event Subscriptions - Real-time Event Pub/Sub
+ *
+ * Manages subscriptions for both resource-scoped and system-level events:
+ * - Resource subscriptions: notifications for a specific resource's events
+ * - Global subscriptions: notifications for all system-level events
+ * - Fire-and-forget notification pattern (non-blocking)
+ * - Automatic cleanup of empty subscription sets
+ *
+ * SINGLETON PATTERN: All EventStore instances share the same EventSubscriptions
+ * to ensure SSE connections receive events from any EventStore instance.
+ *
+ * @see docs/EVENT-STORE.md#eventsubscriptions for architecture details
+ */
+
+type EventCallback = (event: StoredEvent) => void | Promise<void>;
+interface EventSubscription {
+    resourceUri: ResourceUri;
+    callback: EventCallback;
+    unsubscribe: () => void;
+}
+/**
+ * EventSubscriptions manages real-time event pub/sub
+ * Supports both resource-scoped and global subscriptions
+ */
+declare class EventSubscriptions {
+    private subscriptions;
+    private globalSubscriptions;
+    /**
+     * Subscribe to events for a specific resource using full URI
+     * Returns an EventSubscription with unsubscribe function
+     */
+    subscribe(resourceUri: ResourceUri, callback: EventCallback): EventSubscription;
+    /**
+     * Subscribe to all system-level events (no resourceId)
+     * Returns an EventSubscription with unsubscribe function
+     *
+     * Use this for consumers that need to react to global events like:
+     * - entitytype.added (global entity type collection changes)
+     * - Future system-level events (user.created, workspace.created, etc.)
+     */
+    subscribeGlobal(callback: EventCallback): EventSubscription;
+    /**
+     * Notify all subscribers for a resource when a new event is appended
+     * @param resourceUri - Full resource URI (e.g., http://localhost:4000/resources/abc123)
+     */
+    notifySubscribers(resourceUri: ResourceUri, event: StoredEvent): Promise<void>;
+    /**
+     * Notify all global subscribers when a system-level event is appended
+     */
+    notifyGlobalSubscribers(event: StoredEvent): Promise<void>;
+    /**
+     * Get subscription count for a resource (useful for debugging)
+     */
+    getSubscriptionCount(resourceUri: ResourceUri): number;
+    /**
+     * Get total number of active subscriptions across all resources
+     */
+    getTotalSubscriptions(): number;
+    /**
+     * Get total number of global subscriptions
+     */
+    getGlobalSubscriptionCount(): number;
+}
+declare function getEventSubscriptions(): EventSubscriptions;
+
+/**
+ * EventBus - Event Pub/Sub Layer
+ *
+ * Single Responsibility: Event pub/sub only
+ * - Publishes events to subscribers
+ * - Manages subscriptions (resource-scoped and global)
+ * - Converts ResourceId to ResourceUri internally
+ *
+ * Does NOT handle:
+ * - Event persistence (see EventLog)
+ * - View updates (see ViewManager)
+ */
+
+interface EventBusConfig {
+    identifierConfig: IdentifierConfig;
+}
+/**
+ * EventBus wraps EventSubscriptions with a clean API
+ * Handles ID-to-URI conversion internally for type safety
+ */
+declare class EventBus {
+    readonly subscriptions: EventSubscriptions;
+    private identifierConfig;
+    constructor(config: EventBusConfig);
+    /**
+     * Publish event to subscribers
+     * - Resource events: notifies resource-scoped subscribers
+     * - System events: notifies global subscribers
+     * @param event - Stored event (from @semiont/core)
+     */
+    publish(event: StoredEvent): Promise<void>;
+    /**
+     * Subscribe to events for a specific resource
+     * @param resourceId - Branded ResourceId (from @semiont/core)
+     * @param callback - Event callback function
+     * @returns EventSubscription with unsubscribe function
+     */
+    subscribe(resourceId: ResourceId, callback: EventCallback): EventSubscription;
+    /**
+     * Subscribe to all system-level events
+     * @param callback - Event callback function
+     * @returns EventSubscription with unsubscribe function
+     */
+    subscribeGlobal(callback: EventCallback): EventSubscription;
+    /**
+     * Unsubscribe from resource events
+     * @param resourceId - Branded ResourceId (from @semiont/core)
+     * @param callback - Event callback function to remove
+     */
+    unsubscribe(resourceId: ResourceId, callback: EventCallback): void;
+    /**
+     * Unsubscribe from global events
+     * @param callback - Event callback function to remove
+     */
+    unsubscribeGlobal(callback: EventCallback): void;
+    /**
+     * Get subscriber count for a resource
+     * @param resourceId - Branded ResourceId (from @semiont/core)
+     * @returns Number of active subscribers
+     */
+    getSubscriberCount(resourceId: ResourceId): number;
+    /**
+     * Get total number of active subscriptions across all resources
+     */
+    getTotalSubscriptions(): number;
+    /**
+     * Get total number of global subscriptions
+     */
+    getGlobalSubscriptionCount(): number;
+}
+
+/**
+ * View Materializer - Materialized View Management
+ *
+ * Materializes resource views from events:
+ * - Full view materialization from scratch
+ * - Incremental view updates
+ * - System-level views (entity types)
+ *
+ * @see docs/EVENT-STORE.md#viewmaterializer for architecture details
+ */
+
+interface ViewMaterializerConfig {
+    basePath: string;
+    backendUrl: string;
+}
+/**
+ * ViewMaterializer builds and maintains materialized views from events
+ */
+declare class ViewMaterializer {
+    private viewStorage;
+    private config;
+    constructor(viewStorage: ViewStorage, config: ViewMaterializerConfig);
+    /**
+     * Materialize resource view from events
+     * Loads existing view if cached, otherwise rebuilds from events
+     */
+    materialize(events: StoredEvent[], resourceId: ResourceId): Promise<ResourceView | null>;
+    /**
+     * Materialize view incrementally with a single event
+     * Falls back to full rebuild if view doesn't exist
+     */
+    materializeIncremental(resourceId: ResourceId, event: ResourceEvent, getAllEvents: () => Promise<StoredEvent[]>): Promise<void>;
+    /**
+     * Materialize view from event list (full rebuild)
+     */
+    private materializeFromEvents;
+    /**
+     * Apply an event to ResourceDescriptor state (metadata only)
+     */
+    private applyEventToResource;
+    /**
+     * Apply an event to ResourceAnnotations (annotation collections only)
+     */
+    private applyEventToAnnotations;
+    /**
+     * Materialize entity types view - System-level view
+     */
+    materializeEntityTypes(entityType: string): Promise<void>;
+}
+
+/**
+ * ViewManager - Materialized View Management Layer
+ *
+ * Single Responsibility: View updates only
+ * - Updates resource views from events
+ * - Updates system views (entity types)
+ * - Rebuilds views when needed
+ *
+ * Does NOT handle:
+ * - Event persistence (see EventLog)
+ * - Pub/sub notifications (see EventBus)
+ */
+
+interface ViewManagerConfig {
+    basePath: string;
+    backendUrl: string;
+}
+/**
+ * ViewManager wraps ViewMaterializer with a clean API
+ * Handles both resource and system-level views
+ */
+declare class ViewManager {
+    readonly materializer: ViewMaterializer;
+    constructor(viewStorage: ViewStorage, config: ViewManagerConfig);
+    /**
+     * Update resource view with a new event
+     * Falls back to full rebuild if view doesn't exist
+     * @param resourceId - Branded ResourceId (from @semiont/core)
+     * @param event - Resource event (from @semiont/core)
+     * @param getAllEvents - Function to retrieve all events for rebuild if needed
+     */
+    materializeResource(resourceId: ResourceId, event: ResourceEvent, getAllEvents: () => Promise<StoredEvent[]>): Promise<void>;
+    /**
+     * Update system-level view (currently only entity types)
+     * @param eventType - Type of system event
+     * @param payload - Event payload
+     */
+    materializeSystem(eventType: string, payload: any): Promise<void>;
+    /**
+     * Get resource view (builds from events if needed)
+     * @param resourceId - Branded ResourceId (from @semiont/core)
+     * @param events - Stored events for the resource (from @semiont/core)
+     * @returns Resource view or null if no events
+     */
+    getOrMaterialize(resourceId: ResourceId, events: StoredEvent[]): Promise<ResourceView | null>;
+}
+
+/**
+ * EventStore - Orchestration Layer
+ *
+ * Coordinates event sourcing operations across 3 focused components:
+ * - EventLog: Event persistence (append, retrieve, query)
+ * - EventBus: Pub/sub notifications (publish, subscribe)
+ * - ViewManager: View updates (resource and system)
+ *
+ * Thin coordination layer - delegates all work to specialized components.
+ *
+ * @see docs/EVENT-STORE.md for complete architecture documentation
+ */
+
+/**
+ * EventStore orchestrates event sourcing operations
+ * Delegates to specialized components for focused functionality
+ * NO state - just coordination between components
+ */
+declare class EventStore {
+    readonly log: EventLog;
+    readonly bus: EventBus;
+    readonly views: ViewManager;
+    constructor(config: EventStorageConfig, viewStorage: ViewStorage, identifierConfig: IdentifierConfig);
+    /**
+     * Append an event to the store
+     * Coordinates: persistence → view → notification
+     */
+    appendEvent(event: Omit<ResourceEvent, 'id' | 'timestamp'>): Promise<StoredEvent>;
+}
+
+/**
+ * Sharding Utilities
+ *
+ * Shared utilities for consistent sharding across all storage layers
+ * Uses Google's Jump Consistent Hash algorithm for even distribution
+ */
+/**
+ * TEMPORARY: Simple modulo-based hash sharding
+ *
+ * ⚠️ TODO: Replace with proper Jump Consistent Hash implementation
+ *
+ * This is a TEMPORARY implementation using simple modulo. It works and provides
+ * good distribution, but does NOT provide the minimal reshuffling property of
+ * Jump Consistent Hash when changing bucket counts.
+ *
+ * The proper implementation should use Google's Jump Consistent Hash algorithm:
+ * Reference: "A Fast, Minimal Memory, Consistent Hash Algorithm" by Lamping & Veach (2014)
+ * https://arxiv.org/abs/1406.2294
+ *
+ * Working implementations exist in npm packages like:
+ * - jumphash (https://www.npmjs.com/package/jumphash)
+ * - jump-gouache (https://github.com/bhoudu/jump-gouache)
+ *
+ * The algorithm requires proper 64-bit integer handling with BigInt to avoid
+ * precision loss in JavaScript. The previous attempt failed due to incorrect
+ * BigInt arithmetic in the while loop condition.
+ *
+ * Until replaced, this modulo approach will cause ALL data to be reshuffled
+ * if bucket count changes, rather than the optimal O(n/k) reshuffling that
+ * Jump Consistent Hash provides.
+ *
+ * @param key - The key to hash (typically a resource ID)
+ * @param numBuckets - Number of shards/buckets (default: 65536 for 4-hex sharding)
+ * @returns Shard number (0 to numBuckets-1)
+ */
+declare function jumpConsistentHash(key: string, numBuckets?: number): number;
+/**
+ * Get 4-hex shard path for a key
+ *
+ * @param key - The key to hash (typically a resource ID)
+ * @param numBuckets - Number of shards (default: 65536)
+ * @returns Path segments like ['ab', 'cd']
+ */
+declare function getShardPath(key: string, numBuckets?: number): [string, string];
+/**
+ * Calculate SHA-256 hash of data
+ */
+declare function sha256(data: string | object): string;
+
+/**
+ * Event Query - Read Operations
+ *
+ * Handles querying and reading events from storage:
+ * - Query events with filters (type, user, timestamp, sequence)
+ * - Get all events for a resource
+ * - Get last event from a file
+ * - Efficient streaming reads from JSONL files
+ *
+ * @see docs/EVENT-STORE.md#eventquery for architecture details
+ */
+
+/**
+ * EventQuery handles all read operations for events
+ * Uses EventStorage for file access, adds query filtering
+ */
+declare class EventQuery {
+    private eventStorage;
+    constructor(eventStorage: EventStorage);
+    /**
+     * Query events with filters
+     * Supports filtering by: userId, eventTypes, timestamps, sequence number, limit
+     */
+    queryEvents(query: EventQuery$1): Promise<StoredEvent[]>;
+    /**
+     * Get all events for a specific resource (no filters)
+     */
+    getResourceEvents(resourceId: ResourceId): Promise<StoredEvent[]>;
+    /**
+     * Get the last event from a specific file
+     * Useful for initializing sequence numbers and last hashes
+     */
+    getLastEvent(resourceId: ResourceId, filename: string): Promise<StoredEvent | null>;
+    /**
+     * Get the latest event for a resource across all files
+     */
+    getLatestEvent(resourceId: ResourceId): Promise<StoredEvent | null>;
+    /**
+     * Get event count for a resource
+     */
+    getEventCount(resourceId: ResourceId): Promise<number>;
+    /**
+     * Check if a resource has any events
+     */
+    hasEvents(resourceId: ResourceId): Promise<boolean>;
+}
+
+/**
+ * Event Validator - Event Chain Integrity
+ *
+ * Validates event chain integrity using cryptographic hashing:
+ * - prevEventHash links to previous event's checksum
+ * - Each event's checksum is verified against its payload
+ * - Detects broken chains and tampered events
+ *
+ * @see docs/EVENT-STORE.md#eventvalidator for architecture details
+ */
+
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * EventValidator verifies event chain integrity
+ * Uses cryptographic checksums to detect broken chains or tampering
+ */
+declare class EventValidator {
+    /**
+     * Validate event chain integrity for a resource's events
+     * Checks that each event properly links to the previous event
+     */
+    validateEventChain(events: StoredEvent[]): ValidationResult;
+    /**
+     * Validate a single event's checksum
+     * Useful for validating events before writing them
+     */
+    validateEventChecksum(event: StoredEvent): boolean;
+    /**
+     * Validate that an event properly links to a previous event
+     * Returns true if the link is valid or if this is the first event
+     */
+    validateEventLink(currentEvent: StoredEvent, previousEvent: StoredEvent | null): boolean;
+}
+
+export { EventBus, type EventBusConfig, type EventCallback, EventLog, type EventLogConfig, EventQuery, EventStorage, type EventStorageConfig, EventStore, type EventSubscription, EventSubscriptions, EventValidator, FilesystemViewStorage, type IdentifierConfig, type ResourceView, ViewManager, type ViewManagerConfig, ViewMaterializer, type ViewStorage, getEventSubscriptions, getShardPath, jumpConsistentHash, sha256, toAnnotationUri, toResourceUri };