@korajs/test 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,239 @@
+import { SchemaDefinition, Operation, KoraEventEmitter, VersionVector } from '@korajs/core';
+import * as _korajs_server from '@korajs/server';
+import { MemoryServerStore, ServerTransport } from '@korajs/server';
+import { Store, CollectionAccessor } from '@korajs/store';
+import { SyncTransport } from '@korajs/sync';
+export { ChaosConfig, ChaosTransport } from '@korajs/sync';
+
+/**
+ * In-memory test server wrapping KoraSyncServer with MemoryServerStore.
+ * Handles client connections via memory transports.
+ */
+declare class TestServer {
+    readonly store: MemoryServerStore;
+    private readonly syncServer;
+    constructor(schema: SchemaDefinition);
+    /**
+     * Register a client connection transport with the server.
+     * Returns the session ID assigned by the server.
+     */
+    handleConnection(transport: ServerTransport): string;
+    /**
+     * Get all operations stored on the server.
+     */
+    getAllOperations(): Operation[];
+    /**
+     * Get the number of connected clients.
+     */
+    getConnectionCount(): number;
+    /**
+     * Shut down the server and close all sessions.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Options for creating a TestDevice.
+ */
+interface TestDeviceOptions {
+    /** Unique device name (used for DB file naming) */
+    name: string;
+    /** Schema definition */
+    schema: SchemaDefinition;
+    /** Test server to connect to */
+    server: TestServer;
+    /** Transport factory — creates a linked client/server transport pair */
+    createTransportPair: () => {
+        client: SyncTransport;
+        serverTransport: _korajs_server.ServerTransport;
+    };
+    /** Optional directory for temp DB files */
+    tmpDir: string;
+}
+/**
+ * A virtual device in a test network.
+ * Each device has its own Store (with real SQLite), SyncEngine, and MergeEngine.
+ * Provides high-level methods for syncing, disconnecting, and inspecting state.
+ */
+declare class TestDevice {
+    readonly name: string;
+    readonly store: Store;
+    readonly emitter: KoraEventEmitter & {
+        clear(): void;
+    };
+    private readonly schema;
+    private readonly server;
+    private readonly mergeEngine;
+    private readonly createTransportPair;
+    private readonly adapter;
+    private readonly dbPath;
+    private syncEngine;
+    private currentTransport;
+    private unsubscribeSync;
+    private closing;
+    constructor(options: TestDeviceOptions);
+    /**
+     * Open the store (must be called before sync or collection operations).
+     */
+    open(): Promise<void>;
+    /**
+     * Connect to the test server and perform initial sync.
+     * If already connected, flushes any pending operations.
+     */
+    sync(): Promise<void>;
+    /**
+     * Disconnect from the test server.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Reconnect to the test server after a disconnect.
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Get a collection accessor for performing CRUD operations.
+     */
+    collection(name: string): CollectionAccessor;
+    /**
+     * Get all records from a collection (convenience method).
+     */
+    getState(collectionName: string): Promise<Record<string, unknown>[]>;
+    /**
+     * Get the device's node ID.
+     */
+    getNodeId(): string;
+    /**
+     * Get the device's version vector.
+     */
+    getVersionVector(): VersionVector;
+    /**
+     * Check if the device is currently connected to the server.
+     */
+    isConnected(): boolean;
+    /**
+     * Close the device, releasing all resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Create a SyncStore wrapper that interposes merge resolution.
+     * Simplified version of MergeAwareSyncStore from the kora meta-package.
+     */
+    private createMergeAwareSyncStore;
+    /**
+     * Wait for in-flight sync operations to settle.
+     * In-memory transports are near-synchronous, so a microtask flush suffices.
+     */
+    private waitForSettled;
+    /**
+     * Wait for all pending outbound operations to be acknowledged.
+     */
+    private waitForPendingOps;
+}
+
+/**
+ * Options for creating a test network.
+ */
+interface TestNetworkOptions {
+    /** Number of devices to create. Defaults to 2. */
+    devices?: number;
+    /** Custom device names. If not provided, uses 'device-0', 'device-1', etc. */
+    deviceNames?: string[];
+}
+/**
+ * A test network with a server and multiple devices.
+ */
+interface TestNetwork {
+    /** The test server */
+    server: TestServer;
+    /** All devices in the network */
+    devices: TestDevice[];
+    /** Temporary directory for DB files */
+    tmpDir: string;
+    /** Close all devices and the server, clean up temp files */
+    close(): Promise<void>;
+}
+/**
+ * Create a test network with a server and multiple virtual devices.
+ *
+ * Each device has its own local SQLite store and SyncEngine. Devices
+ * communicate with the server via in-memory transports.
+ *
+ * @param schema - The schema all devices share
+ * @param options - Network configuration
+ * @returns A test network with server and devices ready for use
+ *
+ * @example
+ * ```typescript
+ * const network = await createTestNetwork(schema, { devices: 2 })
+ * const [deviceA, deviceB] = network.devices
+ *
+ * await deviceA.collection('todos').insert({ title: 'Hello' })
+ * await deviceA.sync()
+ * await deviceB.sync()
+ *
+ * const todos = await deviceB.getState('todos')
+ * expect(todos).toHaveLength(1)
+ *
+ * await network.close()
+ * ```
+ */
+declare function createTestNetwork(schema: SchemaDefinition, options?: TestNetworkOptions): Promise<TestNetwork>;
+
+/**
+ * Result of a convergence check.
+ */
+interface ConvergenceResult {
+    /** Whether all devices have converged to the same state */
+    converged: boolean;
+    /** Per-collection comparison details (only populated on failure) */
+    differences: CollectionDifference[];
+}
+/**
+ * Describes a difference in a collection between devices.
+ */
+interface CollectionDifference {
+    collection: string;
+    deviceA: string;
+    deviceB: string;
+    /** Records present in deviceA but not deviceB */
+    missingInB: string[];
+    /** Records present in deviceB but not deviceA */
+    missingInA: string[];
+    /** Records present in both but with different values */
+    fieldDifferences: FieldDifference[];
+}
+/**
+ * A specific field-level difference between two devices.
+ */
+interface FieldDifference {
+    recordId: string;
+    field: string;
+    valueInA: unknown;
+    valueInB: unknown;
+}
+/**
+ * Assert that all devices have converged to identical collection states.
+ *
+ * Compares every collection across all device pairs. Throws an error
+ * with detailed diagnostics if any differences are found.
+ *
+ * @param devices - The devices to check for convergence
+ * @param schema - The schema (used to enumerate collections)
+ *
+ * @example
+ * ```typescript
+ * await deviceA.sync()
+ * await deviceB.sync()
+ * await expectConverged([deviceA, deviceB], schema)
+ * ```
+ */
+declare function expectConverged(devices: TestDevice[], schema: SchemaDefinition): Promise<void>;
+/**
+ * Check whether all devices have converged without throwing.
+ *
+ * @param devices - The devices to check
+ * @param schema - The schema (for collection enumeration)
+ * @returns Convergence result with details
+ */
+declare function checkConvergence(devices: TestDevice[], schema: SchemaDefinition): Promise<ConvergenceResult>;
+
+export { type CollectionDifference, type ConvergenceResult, type FieldDifference, TestDevice, type TestDeviceOptions, type TestNetwork, type TestNetworkOptions, TestServer, checkConvergence, createTestNetwork, expectConverged };

package/dist/index.d.ts

@@ -0,0 +1,239 @@
+import { SchemaDefinition, Operation, KoraEventEmitter, VersionVector } from '@korajs/core';
+import * as _korajs_server from '@korajs/server';
+import { MemoryServerStore, ServerTransport } from '@korajs/server';
+import { Store, CollectionAccessor } from '@korajs/store';
+import { SyncTransport } from '@korajs/sync';
+export { ChaosConfig, ChaosTransport } from '@korajs/sync';
+
+/**
+ * In-memory test server wrapping KoraSyncServer with MemoryServerStore.
+ * Handles client connections via memory transports.
+ */
+declare class TestServer {
+    readonly store: MemoryServerStore;
+    private readonly syncServer;
+    constructor(schema: SchemaDefinition);
+    /**
+     * Register a client connection transport with the server.
+     * Returns the session ID assigned by the server.
+     */
+    handleConnection(transport: ServerTransport): string;
+    /**
+     * Get all operations stored on the server.
+     */
+    getAllOperations(): Operation[];
+    /**
+     * Get the number of connected clients.
+     */
+    getConnectionCount(): number;
+    /**
+     * Shut down the server and close all sessions.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Options for creating a TestDevice.
+ */
+interface TestDeviceOptions {
+    /** Unique device name (used for DB file naming) */
+    name: string;
+    /** Schema definition */
+    schema: SchemaDefinition;
+    /** Test server to connect to */
+    server: TestServer;
+    /** Transport factory — creates a linked client/server transport pair */
+    createTransportPair: () => {
+        client: SyncTransport;
+        serverTransport: _korajs_server.ServerTransport;
+    };
+    /** Optional directory for temp DB files */
+    tmpDir: string;
+}
+/**
+ * A virtual device in a test network.
+ * Each device has its own Store (with real SQLite), SyncEngine, and MergeEngine.
+ * Provides high-level methods for syncing, disconnecting, and inspecting state.
+ */
+declare class TestDevice {
+    readonly name: string;
+    readonly store: Store;
+    readonly emitter: KoraEventEmitter & {
+        clear(): void;
+    };
+    private readonly schema;
+    private readonly server;
+    private readonly mergeEngine;
+    private readonly createTransportPair;
+    private readonly adapter;
+    private readonly dbPath;
+    private syncEngine;
+    private currentTransport;
+    private unsubscribeSync;
+    private closing;
+    constructor(options: TestDeviceOptions);
+    /**
+     * Open the store (must be called before sync or collection operations).
+     */
+    open(): Promise<void>;
+    /**
+     * Connect to the test server and perform initial sync.
+     * If already connected, flushes any pending operations.
+     */
+    sync(): Promise<void>;
+    /**
+     * Disconnect from the test server.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Reconnect to the test server after a disconnect.
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Get a collection accessor for performing CRUD operations.
+     */
+    collection(name: string): CollectionAccessor;
+    /**
+     * Get all records from a collection (convenience method).
+     */
+    getState(collectionName: string): Promise<Record<string, unknown>[]>;
+    /**
+     * Get the device's node ID.
+     */
+    getNodeId(): string;
+    /**
+     * Get the device's version vector.
+     */
+    getVersionVector(): VersionVector;
+    /**
+     * Check if the device is currently connected to the server.
+     */
+    isConnected(): boolean;
+    /**
+     * Close the device, releasing all resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Create a SyncStore wrapper that interposes merge resolution.
+     * Simplified version of MergeAwareSyncStore from the kora meta-package.
+     */
+    private createMergeAwareSyncStore;
+    /**
+     * Wait for in-flight sync operations to settle.
+     * In-memory transports are near-synchronous, so a microtask flush suffices.
+     */
+    private waitForSettled;
+    /**
+     * Wait for all pending outbound operations to be acknowledged.
+     */
+    private waitForPendingOps;
+}
+
+/**
+ * Options for creating a test network.
+ */
+interface TestNetworkOptions {
+    /** Number of devices to create. Defaults to 2. */
+    devices?: number;
+    /** Custom device names. If not provided, uses 'device-0', 'device-1', etc. */
+    deviceNames?: string[];
+}
+/**
+ * A test network with a server and multiple devices.
+ */
+interface TestNetwork {
+    /** The test server */
+    server: TestServer;
+    /** All devices in the network */
+    devices: TestDevice[];
+    /** Temporary directory for DB files */
+    tmpDir: string;
+    /** Close all devices and the server, clean up temp files */
+    close(): Promise<void>;
+}
+/**
+ * Create a test network with a server and multiple virtual devices.
+ *
+ * Each device has its own local SQLite store and SyncEngine. Devices
+ * communicate with the server via in-memory transports.
+ *
+ * @param schema - The schema all devices share
+ * @param options - Network configuration
+ * @returns A test network with server and devices ready for use
+ *
+ * @example
+ * ```typescript
+ * const network = await createTestNetwork(schema, { devices: 2 })
+ * const [deviceA, deviceB] = network.devices
+ *
+ * await deviceA.collection('todos').insert({ title: 'Hello' })
+ * await deviceA.sync()
+ * await deviceB.sync()
+ *
+ * const todos = await deviceB.getState('todos')
+ * expect(todos).toHaveLength(1)
+ *
+ * await network.close()
+ * ```
+ */
+declare function createTestNetwork(schema: SchemaDefinition, options?: TestNetworkOptions): Promise<TestNetwork>;
+
+/**
+ * Result of a convergence check.
+ */
+interface ConvergenceResult {
+    /** Whether all devices have converged to the same state */
+    converged: boolean;
+    /** Per-collection comparison details (only populated on failure) */
+    differences: CollectionDifference[];
+}
+/**
+ * Describes a difference in a collection between devices.
+ */
+interface CollectionDifference {
+    collection: string;
+    deviceA: string;
+    deviceB: string;
+    /** Records present in deviceA but not deviceB */
+    missingInB: string[];
+    /** Records present in deviceB but not deviceA */
+    missingInA: string[];
+    /** Records present in both but with different values */
+    fieldDifferences: FieldDifference[];
+}
+/**
+ * A specific field-level difference between two devices.
+ */
+interface FieldDifference {
+    recordId: string;
+    field: string;
+    valueInA: unknown;
+    valueInB: unknown;
+}
+/**
+ * Assert that all devices have converged to identical collection states.
+ *
+ * Compares every collection across all device pairs. Throws an error
+ * with detailed diagnostics if any differences are found.
+ *
+ * @param devices - The devices to check for convergence
+ * @param schema - The schema (used to enumerate collections)
+ *
+ * @example
+ * ```typescript
+ * await deviceA.sync()
+ * await deviceB.sync()
+ * await expectConverged([deviceA, deviceB], schema)
+ * ```
+ */
+declare function expectConverged(devices: TestDevice[], schema: SchemaDefinition): Promise<void>;
+/**
+ * Check whether all devices have converged without throwing.
+ *
+ * @param devices - The devices to check
+ * @param schema - The schema (for collection enumeration)
+ * @returns Convergence result with details
+ */
+declare function checkConvergence(devices: TestDevice[], schema: SchemaDefinition): Promise<ConvergenceResult>;
+
+export { type CollectionDifference, type ConvergenceResult, type FieldDifference, TestDevice, type TestDeviceOptions, type TestNetwork, type TestNetworkOptions, TestServer, checkConvergence, createTestNetwork, expectConverged };