@korajs/core 0.1.0

package/dist/events-D_kDPDC9.d.cts

@@ -0,0 +1,324 @@
+/**
+ * Hybrid Logical Clock timestamp.
+ * Provides a total order that respects causality without requiring synchronized clocks.
+ */
+interface HLCTimestamp {
+    /** Physical wall-clock time in milliseconds */
+    wallTime: number;
+    /** Logical counter. Increments when wallTime hasn't changed since last event. */
+    logical: number;
+    /** Node ID for tie-breaking. Ensures total order even with identical wall+logical. */
+    nodeId: string;
+}
+/** The three mutation types an operation can represent */
+type OperationType = 'insert' | 'update' | 'delete';
+/**
+ * The atomic unit of the entire system. Every mutation produces an Operation.
+ * Operations are IMMUTABLE and CONTENT-ADDRESSED.
+ */
+interface Operation {
+    /** SHA-256 hash of (type + collection + recordId + data + timestamp + nodeId). Content-addressed. */
+    id: string;
+    /** UUID v7 of the originating device. Time-sortable. */
+    nodeId: string;
+    /** What happened */
+    type: OperationType;
+    /** Which collection (from schema) */
+    collection: string;
+    /** ID of the affected record. UUID v7 for inserts, existing ID for update/delete. */
+    recordId: string;
+    /** Field values. null for delete. For updates, contains ONLY changed fields. */
+    data: Record<string, unknown> | null;
+    /** For updates: previous values of changed fields (enables 3-way merge). null for insert/delete. */
+    previousData: Record<string, unknown> | null;
+    /** Hybrid Logical Clock timestamp. Used for causal ordering. */
+    timestamp: HLCTimestamp;
+    /** Monotonically increasing per node. Used in version vectors. */
+    sequenceNumber: number;
+    /** Operation IDs this operation causally depends on (direct parents in the DAG). */
+    causalDeps: string[];
+    /** Schema version at time of creation. Used for migration transforms. */
+    schemaVersion: number;
+}
+/**
+ * Input for creating an operation (before id and timestamp are assigned).
+ */
+interface OperationInput {
+    nodeId: string;
+    type: OperationType;
+    collection: string;
+    recordId: string;
+    data: Record<string, unknown> | null;
+    previousData: Record<string, unknown> | null;
+    sequenceNumber: number;
+    causalDeps: string[];
+    schemaVersion: number;
+}
+/** Version vector: maps nodeId to the max sequence number seen from that node */
+type VersionVector = Map<string, number>;
+/** Field kinds supported by the schema system */
+type FieldKind = 'string' | 'number' | 'boolean' | 'timestamp' | 'richtext' | 'enum' | 'array';
+/**
+ * Descriptor produced by the type builder (t.string(), t.number(), etc.).
+ * Represents a fully configured field definition.
+ */
+interface FieldDescriptor {
+    kind: FieldKind;
+    required: boolean;
+    defaultValue: unknown;
+    auto: boolean;
+    enumValues: readonly string[] | null;
+    itemKind: FieldKind | null;
+}
+/**
+ * Definition of a collection within the schema.
+ */
+interface CollectionDefinition {
+    fields: Record<string, FieldDescriptor>;
+    indexes: string[];
+    constraints: Constraint[];
+    resolvers: Record<string, CustomResolver>;
+}
+/** Custom resolver function for tier 3 merge resolution */
+type CustomResolver = (local: unknown, remote: unknown, base: unknown) => unknown;
+/**
+ * Constraint for tier 2 conflict resolution.
+ */
+interface Constraint {
+    type: 'unique' | 'capacity' | 'referential';
+    fields: string[];
+    where?: Record<string, unknown>;
+    onConflict: 'first-write-wins' | 'last-write-wins' | 'priority-field' | 'server-decides' | 'custom';
+    priorityField?: string;
+    resolve?: (local: unknown, remote: unknown, base: unknown) => unknown;
+}
+/** Relation type between collections */
+type RelationType = 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
+/** On-delete behavior for relations */
+type OnDeleteAction = 'cascade' | 'set-null' | 'restrict' | 'no-action';
+/**
+ * Definition of a relation between two collections.
+ */
+interface RelationDefinition {
+    from: string;
+    to: string;
+    type: RelationType;
+    field: string;
+    onDelete: OnDeleteAction;
+}
+/**
+ * The complete schema definition produced by defineSchema().
+ */
+interface SchemaDefinition {
+    version: number;
+    collections: Record<string, CollectionDefinition>;
+    relations: Record<string, RelationDefinition>;
+}
+/**
+ * Merge strategies available for auto-merge and constraints.
+ */
+declare const MERGE_STRATEGIES: readonly ["auto-merge", "lww", "first-write-wins", "server-decides", "custom"];
+type MergeStrategy = (typeof MERGE_STRATEGIES)[number];
+/**
+ * Connection quality levels for adaptive sync.
+ */
+declare const CONNECTION_QUALITIES: readonly ["excellent", "good", "fair", "poor", "offline"];
+type ConnectionQuality = (typeof CONNECTION_QUALITIES)[number];
+/**
+ * Injectable time source for deterministic testing of clocks.
+ */
+interface TimeSource {
+    now(): number;
+}
+/**
+ * Injectable random source for deterministic testing of UUID generation.
+ */
+interface RandomSource {
+    getRandomValues<T extends ArrayBufferView>(array: T): T;
+}
+
+/**
+ * Hybrid Logical Clock implementation based on Kulkarni et al.
+ *
+ * Provides a total order that respects causality without requiring synchronized clocks.
+ * Each call to now() returns a timestamp strictly greater than the previous one.
+ *
+ * @example
+ * ```typescript
+ * const clock = new HybridLogicalClock('node-1')
+ * const ts1 = clock.now()
+ * const ts2 = clock.now()
+ * // HybridLogicalClock.compare(ts1, ts2) < 0 (ts1 is earlier)
+ * ```
+ */
+declare class HybridLogicalClock {
+    private readonly nodeId;
+    private readonly timeSource;
+    private readonly onDriftWarning?;
+    private wallTime;
+    private logical;
+    constructor(nodeId: string, timeSource?: TimeSource, onDriftWarning?: ((driftMs: number) => void) | undefined);
+    /**
+     * Generate a new timestamp for a local event.
+     * Guarantees monotonicity: each call returns a timestamp strictly greater than the previous.
+     *
+     * @throws {ClockDriftError} If physical time is more than 5 minutes behind the HLC wallTime
+     */
+    now(): HLCTimestamp;
+    /**
+     * Update clock on receiving a remote timestamp.
+     * Merges the remote clock state with the local state to maintain causal ordering.
+     *
+     * @throws {ClockDriftError} If physical time is more than 5 minutes behind the resulting wallTime
+     */
+    receive(remote: HLCTimestamp): HLCTimestamp;
+    /**
+     * Compare two timestamps. Returns negative if a < b, positive if a > b, zero if equal.
+     * Total order: wallTime first, then logical, then nodeId (lexicographic).
+     */
+    static compare(a: HLCTimestamp, b: HLCTimestamp): number;
+    /**
+     * Serialize an HLC timestamp to a string that sorts lexicographically.
+     * Format: zero-padded wallTime:logical:nodeId
+     */
+    static serialize(ts: HLCTimestamp): string;
+    /**
+     * Deserialize an HLC timestamp from its serialized string form.
+     */
+    static deserialize(s: string): HLCTimestamp;
+    private checkDrift;
+}
+
+/**
+ * Creates an immutable, content-addressed Operation from the given parameters.
+ * The operation is deep-frozen after creation — it cannot be modified.
+ *
+ * @param input - The operation parameters (without id, which is computed)
+ * @param clock - The HLC clock to generate the timestamp
+ * @returns A frozen Operation with a content-addressed id
+ *
+ * @example
+ * ```typescript
+ * const op = await createOperation({
+ *   nodeId: 'device-1',
+ *   type: 'insert',
+ *   collection: 'todos',
+ *   recordId: 'rec-1',
+ *   data: { title: 'Ship it' },
+ *   previousData: null,
+ *   sequenceNumber: 1,
+ *   causalDeps: [],
+ *   schemaVersion: 1,
+ * }, clock)
+ * ```
+ */
+declare function createOperation(input: OperationInput, clock: HybridLogicalClock): Promise<Operation>;
+/**
+ * Validates operation input parameters. Throws OperationError with
+ * contextual information on validation failure.
+ */
+declare function validateOperationParams(input: OperationInput): void;
+/**
+ * Verify the integrity of an operation by recomputing its content hash.
+ * Returns true if the id matches the recomputed hash.
+ */
+declare function verifyOperationIntegrity(op: Operation): Promise<boolean>;
+/**
+ * Type guard for Operation interface.
+ */
+declare function isValidOperation(value: unknown): value is Operation;
+
+/**
+ * Trace of a merge decision. Records all inputs and outputs for debugging and DevTools.
+ */
+interface MergeTrace {
+    operationA: Operation;
+    operationB: Operation;
+    field: string;
+    strategy: string;
+    inputA: unknown;
+    inputB: unknown;
+    base: unknown | null;
+    output: unknown;
+    tier: 1 | 2 | 3;
+    constraintViolated: string | null;
+    duration: number;
+}
+/**
+ * All events emitted by the Kora framework.
+ * These are consumed by DevTools and can be observed by the developer.
+ */
+type KoraEvent = {
+    type: 'operation:created';
+    operation: Operation;
+} | {
+    type: 'operation:applied';
+    operation: Operation;
+    duration: number;
+} | {
+    type: 'merge:started';
+    operationA: Operation;
+    operationB: Operation;
+} | {
+    type: 'merge:completed';
+    trace: MergeTrace;
+} | {
+    type: 'merge:conflict';
+    trace: MergeTrace;
+} | {
+    type: 'constraint:violated';
+    constraint: string;
+    trace: MergeTrace;
+} | {
+    type: 'sync:connected';
+    nodeId: string;
+} | {
+    type: 'sync:disconnected';
+    reason: string;
+} | {
+    type: 'sync:sent';
+    operations: Operation[];
+    batchSize: number;
+} | {
+    type: 'sync:received';
+    operations: Operation[];
+    batchSize: number;
+} | {
+    type: 'sync:acknowledged';
+    sequenceNumber: number;
+} | {
+    type: 'query:subscribed';
+    queryId: string;
+    collection: string;
+} | {
+    type: 'query:invalidated';
+    queryId: string;
+    trigger: Operation;
+} | {
+    type: 'query:executed';
+    queryId: string;
+    duration: number;
+    resultCount: number;
+} | {
+    type: 'connection:quality';
+    quality: ConnectionQuality;
+};
+/** Extract the event type string union from KoraEvent */
+type KoraEventType = KoraEvent['type'];
+/** Extract a specific event by its type */
+type KoraEventByType<T extends KoraEventType> = Extract<KoraEvent, {
+    type: T;
+}>;
+/** Listener function for a specific event type */
+type KoraEventListener<T extends KoraEventType> = (event: KoraEventByType<T>) => void;
+/**
+ * Event emitter interface for the Kora framework.
+ * All packages that emit events must implement this interface.
+ */
+interface KoraEventEmitter {
+    on<T extends KoraEventType>(type: T, listener: KoraEventListener<T>): () => void;
+    off<T extends KoraEventType>(type: T, listener: KoraEventListener<T>): void;
+    emit<T extends KoraEventType>(event: KoraEventByType<T>): void;
+}
+
+export { type CustomResolver as C, type FieldKind as F, type HLCTimestamp as H, type KoraEvent as K, MERGE_STRATEGIES as M, type OperationType as O, type RandomSource as R, type SchemaDefinition as S, type TimeSource as T, type VersionVector as V, type FieldDescriptor as a, type CollectionDefinition as b, type RelationDefinition as c, type Operation as d, CONNECTION_QUALITIES as e, type ConnectionQuality as f, type Constraint as g, HybridLogicalClock as h, type KoraEventByType as i, type KoraEventEmitter as j, type KoraEventListener as k, type KoraEventType as l, type MergeStrategy as m, type MergeTrace as n, type OnDeleteAction as o, type OperationInput as p, type RelationType as q, createOperation as r, isValidOperation as s, validateOperationParams as t, verifyOperationIntegrity as v };

package/dist/events-D_kDPDC9.d.ts

@@ -0,0 +1,324 @@
+/**
+ * Hybrid Logical Clock timestamp.
+ * Provides a total order that respects causality without requiring synchronized clocks.
+ */
+interface HLCTimestamp {
+    /** Physical wall-clock time in milliseconds */
+    wallTime: number;
+    /** Logical counter. Increments when wallTime hasn't changed since last event. */
+    logical: number;
+    /** Node ID for tie-breaking. Ensures total order even with identical wall+logical. */
+    nodeId: string;
+}
+/** The three mutation types an operation can represent */
+type OperationType = 'insert' | 'update' | 'delete';
+/**
+ * The atomic unit of the entire system. Every mutation produces an Operation.
+ * Operations are IMMUTABLE and CONTENT-ADDRESSED.
+ */
+interface Operation {
+    /** SHA-256 hash of (type + collection + recordId + data + timestamp + nodeId). Content-addressed. */
+    id: string;
+    /** UUID v7 of the originating device. Time-sortable. */
+    nodeId: string;
+    /** What happened */
+    type: OperationType;
+    /** Which collection (from schema) */
+    collection: string;
+    /** ID of the affected record. UUID v7 for inserts, existing ID for update/delete. */
+    recordId: string;
+    /** Field values. null for delete. For updates, contains ONLY changed fields. */
+    data: Record<string, unknown> | null;
+    /** For updates: previous values of changed fields (enables 3-way merge). null for insert/delete. */
+    previousData: Record<string, unknown> | null;
+    /** Hybrid Logical Clock timestamp. Used for causal ordering. */
+    timestamp: HLCTimestamp;
+    /** Monotonically increasing per node. Used in version vectors. */
+    sequenceNumber: number;
+    /** Operation IDs this operation causally depends on (direct parents in the DAG). */
+    causalDeps: string[];
+    /** Schema version at time of creation. Used for migration transforms. */
+    schemaVersion: number;
+}
+/**
+ * Input for creating an operation (before id and timestamp are assigned).
+ */
+interface OperationInput {
+    nodeId: string;
+    type: OperationType;
+    collection: string;
+    recordId: string;
+    data: Record<string, unknown> | null;
+    previousData: Record<string, unknown> | null;
+    sequenceNumber: number;
+    causalDeps: string[];
+    schemaVersion: number;
+}
+/** Version vector: maps nodeId to the max sequence number seen from that node */
+type VersionVector = Map<string, number>;
+/** Field kinds supported by the schema system */
+type FieldKind = 'string' | 'number' | 'boolean' | 'timestamp' | 'richtext' | 'enum' | 'array';
+/**
+ * Descriptor produced by the type builder (t.string(), t.number(), etc.).
+ * Represents a fully configured field definition.
+ */
+interface FieldDescriptor {
+    kind: FieldKind;
+    required: boolean;
+    defaultValue: unknown;
+    auto: boolean;
+    enumValues: readonly string[] | null;
+    itemKind: FieldKind | null;
+}
+/**
+ * Definition of a collection within the schema.
+ */
+interface CollectionDefinition {
+    fields: Record<string, FieldDescriptor>;
+    indexes: string[];
+    constraints: Constraint[];
+    resolvers: Record<string, CustomResolver>;
+}
+/** Custom resolver function for tier 3 merge resolution */
+type CustomResolver = (local: unknown, remote: unknown, base: unknown) => unknown;
+/**
+ * Constraint for tier 2 conflict resolution.
+ */
+interface Constraint {
+    type: 'unique' | 'capacity' | 'referential';
+    fields: string[];
+    where?: Record<string, unknown>;
+    onConflict: 'first-write-wins' | 'last-write-wins' | 'priority-field' | 'server-decides' | 'custom';
+    priorityField?: string;
+    resolve?: (local: unknown, remote: unknown, base: unknown) => unknown;
+}
+/** Relation type between collections */
+type RelationType = 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
+/** On-delete behavior for relations */
+type OnDeleteAction = 'cascade' | 'set-null' | 'restrict' | 'no-action';
+/**
+ * Definition of a relation between two collections.
+ */
+interface RelationDefinition {
+    from: string;
+    to: string;
+    type: RelationType;
+    field: string;
+    onDelete: OnDeleteAction;
+}
+/**
+ * The complete schema definition produced by defineSchema().
+ */
+interface SchemaDefinition {
+    version: number;
+    collections: Record<string, CollectionDefinition>;
+    relations: Record<string, RelationDefinition>;
+}
+/**
+ * Merge strategies available for auto-merge and constraints.
+ */
+declare const MERGE_STRATEGIES: readonly ["auto-merge", "lww", "first-write-wins", "server-decides", "custom"];
+type MergeStrategy = (typeof MERGE_STRATEGIES)[number];
+/**
+ * Connection quality levels for adaptive sync.
+ */
+declare const CONNECTION_QUALITIES: readonly ["excellent", "good", "fair", "poor", "offline"];
+type ConnectionQuality = (typeof CONNECTION_QUALITIES)[number];
+/**
+ * Injectable time source for deterministic testing of clocks.
+ */
+interface TimeSource {
+    now(): number;
+}
+/**
+ * Injectable random source for deterministic testing of UUID generation.
+ */
+interface RandomSource {
+    getRandomValues<T extends ArrayBufferView>(array: T): T;
+}
+
+/**
+ * Hybrid Logical Clock implementation based on Kulkarni et al.
+ *
+ * Provides a total order that respects causality without requiring synchronized clocks.
+ * Each call to now() returns a timestamp strictly greater than the previous one.
+ *
+ * @example
+ * ```typescript
+ * const clock = new HybridLogicalClock('node-1')
+ * const ts1 = clock.now()
+ * const ts2 = clock.now()
+ * // HybridLogicalClock.compare(ts1, ts2) < 0 (ts1 is earlier)
+ * ```
+ */
+declare class HybridLogicalClock {
+    private readonly nodeId;
+    private readonly timeSource;
+    private readonly onDriftWarning?;
+    private wallTime;
+    private logical;
+    constructor(nodeId: string, timeSource?: TimeSource, onDriftWarning?: ((driftMs: number) => void) | undefined);
+    /**
+     * Generate a new timestamp for a local event.
+     * Guarantees monotonicity: each call returns a timestamp strictly greater than the previous.
+     *
+     * @throws {ClockDriftError} If physical time is more than 5 minutes behind the HLC wallTime
+     */
+    now(): HLCTimestamp;
+    /**
+     * Update clock on receiving a remote timestamp.
+     * Merges the remote clock state with the local state to maintain causal ordering.
+     *
+     * @throws {ClockDriftError} If physical time is more than 5 minutes behind the resulting wallTime
+     */
+    receive(remote: HLCTimestamp): HLCTimestamp;
+    /**
+     * Compare two timestamps. Returns negative if a < b, positive if a > b, zero if equal.
+     * Total order: wallTime first, then logical, then nodeId (lexicographic).
+     */
+    static compare(a: HLCTimestamp, b: HLCTimestamp): number;
+    /**
+     * Serialize an HLC timestamp to a string that sorts lexicographically.
+     * Format: zero-padded wallTime:logical:nodeId
+     */
+    static serialize(ts: HLCTimestamp): string;
+    /**
+     * Deserialize an HLC timestamp from its serialized string form.
+     */
+    static deserialize(s: string): HLCTimestamp;
+    private checkDrift;
+}
+
+/**
+ * Creates an immutable, content-addressed Operation from the given parameters.
+ * The operation is deep-frozen after creation — it cannot be modified.
+ *
+ * @param input - The operation parameters (without id, which is computed)
+ * @param clock - The HLC clock to generate the timestamp
+ * @returns A frozen Operation with a content-addressed id
+ *
+ * @example
+ * ```typescript
+ * const op = await createOperation({
+ *   nodeId: 'device-1',
+ *   type: 'insert',
+ *   collection: 'todos',
+ *   recordId: 'rec-1',
+ *   data: { title: 'Ship it' },
+ *   previousData: null,
+ *   sequenceNumber: 1,
+ *   causalDeps: [],
+ *   schemaVersion: 1,
+ * }, clock)
+ * ```
+ */
+declare function createOperation(input: OperationInput, clock: HybridLogicalClock): Promise<Operation>;
+/**
+ * Validates operation input parameters. Throws OperationError with
+ * contextual information on validation failure.
+ */
+declare function validateOperationParams(input: OperationInput): void;
+/**
+ * Verify the integrity of an operation by recomputing its content hash.
+ * Returns true if the id matches the recomputed hash.
+ */
+declare function verifyOperationIntegrity(op: Operation): Promise<boolean>;
+/**
+ * Type guard for Operation interface.
+ */
+declare function isValidOperation(value: unknown): value is Operation;
+
+/**
+ * Trace of a merge decision. Records all inputs and outputs for debugging and DevTools.
+ */
+interface MergeTrace {
+    operationA: Operation;
+    operationB: Operation;
+    field: string;
+    strategy: string;
+    inputA: unknown;
+    inputB: unknown;
+    base: unknown | null;
+    output: unknown;
+    tier: 1 | 2 | 3;
+    constraintViolated: string | null;
+    duration: number;
+}
+/**
+ * All events emitted by the Kora framework.
+ * These are consumed by DevTools and can be observed by the developer.
+ */
+type KoraEvent = {
+    type: 'operation:created';
+    operation: Operation;
+} | {
+    type: 'operation:applied';
+    operation: Operation;
+    duration: number;
+} | {
+    type: 'merge:started';
+    operationA: Operation;
+    operationB: Operation;
+} | {
+    type: 'merge:completed';
+    trace: MergeTrace;
+} | {
+    type: 'merge:conflict';
+    trace: MergeTrace;
+} | {
+    type: 'constraint:violated';
+    constraint: string;
+    trace: MergeTrace;
+} | {
+    type: 'sync:connected';
+    nodeId: string;
+} | {
+    type: 'sync:disconnected';
+    reason: string;
+} | {
+    type: 'sync:sent';
+    operations: Operation[];
+    batchSize: number;
+} | {
+    type: 'sync:received';
+    operations: Operation[];
+    batchSize: number;
+} | {
+    type: 'sync:acknowledged';
+    sequenceNumber: number;
+} | {
+    type: 'query:subscribed';
+    queryId: string;
+    collection: string;
+} | {
+    type: 'query:invalidated';
+    queryId: string;
+    trigger: Operation;
+} | {
+    type: 'query:executed';
+    queryId: string;
+    duration: number;
+    resultCount: number;
+} | {
+    type: 'connection:quality';
+    quality: ConnectionQuality;
+};
+/** Extract the event type string union from KoraEvent */
+type KoraEventType = KoraEvent['type'];
+/** Extract a specific event by its type */
+type KoraEventByType<T extends KoraEventType> = Extract<KoraEvent, {
+    type: T;
+}>;
+/** Listener function for a specific event type */
+type KoraEventListener<T extends KoraEventType> = (event: KoraEventByType<T>) => void;
+/**
+ * Event emitter interface for the Kora framework.
+ * All packages that emit events must implement this interface.
+ */
+interface KoraEventEmitter {
+    on<T extends KoraEventType>(type: T, listener: KoraEventListener<T>): () => void;
+    off<T extends KoraEventType>(type: T, listener: KoraEventListener<T>): void;
+    emit<T extends KoraEventType>(event: KoraEventByType<T>): void;
+}
+
+export { type CustomResolver as C, type FieldKind as F, type HLCTimestamp as H, type KoraEvent as K, MERGE_STRATEGIES as M, type OperationType as O, type RandomSource as R, type SchemaDefinition as S, type TimeSource as T, type VersionVector as V, type FieldDescriptor as a, type CollectionDefinition as b, type RelationDefinition as c, type Operation as d, CONNECTION_QUALITIES as e, type ConnectionQuality as f, type Constraint as g, HybridLogicalClock as h, type KoraEventByType as i, type KoraEventEmitter as j, type KoraEventListener as k, type KoraEventType as l, type MergeStrategy as m, type MergeTrace as n, type OnDeleteAction as o, type OperationInput as p, type RelationType as q, createOperation as r, isValidOperation as s, validateOperationParams as t, verifyOperationIntegrity as v };