@korajs/test 0.0.0-canary-20261008174129

package/dist/index.d.ts

@@ -0,0 +1,493 @@
+import * as _korajs_sync from '@korajs/sync';
+import { SyncTransport, SyncEncryptionConfig, SyncEngine, ChaosConfig } from '@korajs/sync';
+export { ChaosConfig, ChaosTransport } from '@korajs/sync';
+import * as _korajs_server from '@korajs/server';
+import { ServerTransport, ServerStore, MemoryServerStore, KoraSyncServerConfig, OperationValidator, KoraSyncServer } from '@korajs/server';
+import { KoraEventEmitter, SchemaDefinition, OperationTransform, BlobRef, VersionVector, Operation } from '@korajs/core';
+import { Store, MemoryBlobStore, CollectionAccessor, BlobManifest, ReceiveBlobResult, ContentAddressedBlobStore } from '@korajs/store';
+import { AuthSyncBinding, AuthSyncState } from '@korajs/core/bindings';
+
+/** What a device needs from its server: a way to open a session on it. */
+interface TestDeviceServer {
+    handleConnection(transport: _korajs_server.ServerTransport): string;
+}
+/**
+ * End-to-end encryption of a test device's sync traffic. Devices that must read each
+ * other's operations share the passphrase AND the key-derivation salt (shared key
+ * distribution, ENC-1, is not built yet).
+ */
+interface TestDeviceEncryption {
+    config: SyncEncryptionConfig;
+    salt: Uint8Array;
+    /** PBKDF2 iterations (lower in tests for speed). */
+    iterations?: number;
+}
+/**
+ * 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: TestDeviceServer;
+    /** Transport factory — creates a linked client/server transport pair */
+    createTransportPair: () => {
+        client: SyncTransport;
+        serverTransport: _korajs_server.ServerTransport;
+    };
+    /** Optional directory for temp DB files */
+    tmpDir: string;
+    /** Client handshake schema version. Defaults to `schema.version`. */
+    syncSchemaVersion?: number;
+    /** Schema transforms: the store folds every operation's view (transforms at fold time). */
+    operationTransforms?: OperationTransform[];
+    /** The store's local `maxOperationBytes` (RT-86). Default: the store default (256 KiB). */
+    maxOperationBytes?: number;
+    /** A pinned store node id (`StoreConfig.nodeId`), as `createKoraAuthSync` sets the device id. */
+    nodeId?: string;
+    /** What the device does with records that leave its scope. Defaults to the engine default ('retain'). */
+    scopeExit?: 'retain' | 'retract';
+    /**
+     * The signed-in user, as an auth-aware app knows it (RT-42). When set, the store binds
+     * its node to that user at open and on {@link TestDevice.authChanged}, and the sync
+     * engine never uploads another user's node on this user's session.
+     */
+    principal?: () => string | null;
+    /**
+     * Let the sync engine reconnect on its own, as over a real WebSocket: a `connect()`
+     * after the session closed opens a new transport pair to the server. Off by default
+     * (a closed pair stays closed until the next {@link TestDevice.sync}).
+     */
+    reconnectable?: boolean;
+    /**
+     * Run the device on the beta.12 pairwise pipeline (`experimental.legacyMerge`)
+     * instead of the W7 fold. Used by the comparison harness.
+     */
+    legacyMerge?: boolean;
+    /** Encrypt sync traffic end to end (protocol v2 envelope). */
+    encryption?: TestDeviceEncryption;
+    /** Upload batch size of the sync engine (default: the engine's). */
+    batchSize?: number;
+}
+/**
+ * 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;
+    };
+    /** Content-addressed blob store for out-of-band blob bytes (chunks + full blobs). */
+    readonly blobStore: MemoryBlobStore;
+    private readonly schema;
+    private readonly server;
+    private readonly encryption;
+    private readonly batchSize;
+    private encryptor;
+    private readonly mergeEngine;
+    private readonly createTransportPair;
+    private readonly adapter;
+    private readonly dbPath;
+    private readonly syncSchemaVersion;
+    private readonly operationTransforms;
+    private readonly scopeExit;
+    private readonly principal;
+    private readonly reconnectable;
+    private applyPipeline;
+    private syncEngine;
+    private blobChunkProvider;
+    private currentTransport;
+    private unsubscribeSync;
+    private unsubscribeAudit;
+    private closing;
+    constructor(options: TestDeviceOptions);
+    /**
+     * Open the store (must be called before sync or collection operations).
+     */
+    open(): Promise<void>;
+    /**
+     * The signed-in user changed (RT-42), as an auth binding reports it: like createApp,
+     * end the live session and bind the store to the new user before the next write.
+     */
+    authChanged(): 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;
+    /** Exposes the sync engine for integration tests (e.g. doc channel, chaos). */
+    getSyncEngine(): SyncEngine | null;
+    /**
+     * Operations the server rejected for this device that have not been reconciled.
+     * Empty when the device has never connected.
+     */
+    getRejectedOperations(): Promise<_korajs_sync.RejectedOperation[]>;
+    /**
+     * Stage a blob's bytes into this device's blob store, splitting them into
+     * content-addressed chunks this device can then serve to peers over the sync
+     * connection. Returns the manifest (blob hash + ordered chunk hashes) needed
+     * to pull the blob elsewhere.
+     */
+    stageBlob(bytes: Uint8Array, options?: {
+        chunkSize?: number;
+    }): Promise<BlobManifest>;
+    /**
+     * Store a blob for transfer the way `app.blobs.put` does: stage chunks, store
+     * the full blob, and store the manifest as its own content-addressed object.
+     * The returned reference carries a `manifestHash`, so a peer can pull the bytes
+     * knowing only the reference.
+     */
+    putBlob(bytes: Uint8Array, options?: {
+        chunkSize?: number;
+        mimeType?: string;
+        filename?: string;
+    }): Promise<{
+        ref: BlobRef;
+        manifest: BlobManifest;
+    }>;
+    /**
+     * Pull a blob's bytes over the live connection knowing only its reference: the
+     * manifest is resolved by `ref.manifestHash` first, then the chunks are fetched.
+     */
+    pullBlobByRef(ref: BlobRef): Promise<ReceiveBlobResult>;
+    /**
+     * Pull a blob's bytes from peers over the live sync connection. Requests only
+     * the chunks this device is missing, reassembles them, and verifies integrity
+     * against the manifest's blob hash before storing the full blob locally.
+     */
+    pullBlob(manifest: BlobManifest): Promise<ReceiveBlobResult>;
+    /** Read fully-assembled blob bytes from this device's store, or null if absent. */
+    getBlobBytes(hash: string): Promise<Uint8Array | null>;
+    /**
+     * 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>;
+    /**
+     * Wait for in-flight sync operations to settle.
+     * In-memory transports are near-synchronous, but apply/relay work is async.
+     */
+    private waitForSettled;
+    /**
+     * Wait for all pending outbound operations to be acknowledged.
+     */
+    private waitForPendingOps;
+}
+
+/**
+ * A linked client/server transport pair, as consumed by {@link TestDevice}.
+ */
+interface TransportPair {
+    client: SyncTransport;
+    serverTransport: ServerTransport;
+}
+/**
+ * Wraps a transport pair so that every sync message exchanged between the two
+ * ends is encoded to protobuf bytes and decoded back — a faithful stand-in for
+ * a real network hop that uses the protobuf wire format.
+ *
+ * Both directions are wrapped, so operations, handshakes, batches, and acks all
+ * travel as bytes rather than shared object references.
+ *
+ * @param pair - The underlying (in-memory) transport pair to wrap
+ * @returns A transport pair that routes messages through the protobuf codec
+ */
+declare function wrapTransportPairWithProtobufWire(pair: TransportPair): TransportPair;
+
+/**
+ * In-memory test server wrapping KoraSyncServer with MemoryServerStore.
+ * Handles client connections via memory transports.
+ */
+interface TestServerOptions<S extends ServerStore = MemoryServerStore> {
+    /**
+     * The server store (SQLite, Postgres, a memory store with options). Defaults to a
+     * fresh {@link MemoryServerStore}. Await {@link TestServer.ready} before use: the
+     * schema is set asynchronously.
+     */
+    store?: S;
+    /** End-to-end encryption policy of the sync server (protocol v2). */
+    encryption?: KoraSyncServerConfig['encryption'];
+    /** Handshake schema version advertised by the server. Defaults to `schema.version`. */
+    schemaVersion?: number;
+    /** Inclusive client schema versions accepted at handshake. */
+    supportedSchemaVersions?: {
+        min: number;
+        max: number;
+    };
+    /** Transform accepted legacy operations into the server schema before validation. */
+    operationTransforms?: OperationTransform[];
+    /** Enable central blob storage: the server persists and serves uploaded blob bytes. */
+    blobStorage?: boolean;
+    /** Adjudicate untrusted client operations before materialization. */
+    validateOperation?: OperationValidator;
+}
+declare class TestServer<S extends ServerStore = MemoryServerStore> {
+    readonly store: S;
+    /** Resolves once the store has the schema (needed before a SQL store is used). */
+    readonly ready: Promise<void>;
+    /** The server's central blob store, present when `blobStorage` was enabled. */
+    readonly blobStore: ContentAddressedBlobStore | null;
+    private readonly syncServer;
+    constructor(schema: SchemaDefinition, options?: TestServerOptions<S>);
+    /**
+     * 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[];
+    /** The trusted server-side write API (route context): writes authored by the server node. */
+    getKoraContext(): ReturnType<KoraSyncServer['getKoraContext']>;
+    /** The node ids the server's stores fold with and advertise in the handshake. */
+    get authoritativeNodeIds(): string[];
+    /**
+     * Get the number of connected clients.
+     */
+    getConnectionCount(): number;
+    /**
+     * Retransmit relay batches connected clients have not acknowledged. Lets a test
+     * deterministically trigger the redelivery that the server also runs on a timer,
+     * without depending on wall-clock time. `staleMs` of 0 resends every pending relay.
+     */
+    retransmitPendingRelays(staleMs?: number): void;
+    /** Every blob reference still reachable from live records on the server. */
+    getLiveBlobRefs(): Promise<BlobRef[]>;
+    /**
+     * Shut down the server and close all sessions.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * 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[];
+    /** Optional chaos transport settings applied to each device link. */
+    chaos?: ChaosConfig;
+    /**
+     * Optional wrapper applied to each device's transport pair after the base
+     * (in-memory, optionally chaos-wrapped) pair is created. Use it to route
+     * messages through the protobuf wire codec
+     * ({@link wrapTransportPairWithProtobufWire}) or to inject a controllable
+     * server clock. Called once per device connection.
+     */
+    wrapTransport?: (pair: TransportPair) => TransportPair;
+    /** Enable central blob storage on the server (persist + serve uploaded blob bytes). */
+    blobStorage?: boolean;
+    /** Adjudicate untrusted client operations on the server before materialization. */
+    validateOperation?: _korajs_server.OperationValidator;
+    /** Devices use the beta.12 pairwise pipeline (`experimental.legacyMerge`). */
+    legacyMerge?: boolean;
+    /**
+     * The server's store (SQLite, Postgres). Defaults to a fresh memory store. The
+     * network closes it.
+     */
+    serverStore?: _korajs_server.ServerStore;
+    /** Every device encrypts its sync traffic with this shared key material. */
+    encryption?: TestDeviceEncryption;
+    /** The sync server's encryption policy. */
+    serverEncryption?: _korajs_server.KoraSyncServerConfig['encryption'];
+    /** Every device store's local `maxOperationBytes` (RT-86). */
+    deviceMaxOperationBytes?: number;
+}
+/**
+ * A test network with a server and multiple devices.
+ */
+interface TestNetwork {
+    /** The test server */
+    server: TestServer<_korajs_server.ServerStore>;
+    /** 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>;
+/**
+ * Per-device configuration when devices use different local schemas or sync settings.
+ */
+interface MixedTestDeviceConfig {
+    name: string;
+    schema: SchemaDefinition;
+    syncSchemaVersion?: number;
+    operationTransforms?: OperationTransform[];
+}
+/**
+ * Create a test network where devices may use different schema versions and transforms.
+ * The server uses `serverSchema` for materialization and handshake bounds.
+ */
+declare function createMixedTestNetwork(serverSchema: SchemaDefinition, serverOptions: TestServerOptions, deviceConfigs: MixedTestDeviceConfig[]): 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>;
+/**
+ * Poll until all devices converge or timeout. Use after sync in integration tests
+ * where relay/apply work may still be in flight under parallel CI load.
+ */
+declare function expectConvergedEventually(devices: TestDevice[], schema: SchemaDefinition, options?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+}): 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>;
+
+/**
+ * Wraps a transport pair so the server side reports `serverNow()` as its
+ * handshake wall-clock time.
+ *
+ * @param pair - The underlying transport pair
+ * @param serverNow - Returns the server's true current time (ms since epoch)
+ * @returns A transport pair whose handshake responses carry the injected time
+ */
+declare function wrapTransportPairWithServerClock(pair: TransportPair, serverNow: () => number): TransportPair;
+
+/** Controllable auth binding for lifecycle and authenticated-only sync tests. */
+interface TestAuthBinding extends AuthSyncBinding {
+    readonly state: AuthSyncState;
+    setLoading(): void;
+    signIn(userId: string, token?: string): void;
+    refreshToken(token?: string): void;
+    signOut(): void;
+}
+/**
+ * Create a deterministic auth binding that can transition between loading,
+ * signed-out, and multiple authenticated users without a real auth server.
+ */
+declare function createTestAuthBinding(options?: {
+    initialUserId?: string;
+    anonymous?: boolean;
+}): TestAuthBinding;
+
+interface TestTransferMetrics {
+    connectionAttempts: number;
+    disconnections: number;
+    clientMessages: number;
+    serverMessages: number;
+    clientBytes: number;
+    serverBytes: number;
+    reset(): void;
+}
+/** Create a transport wrapper and counters for asserting reconnect and transfer cost. */
+declare function createTransportMetrics(): {
+    metrics: TestTransferMetrics;
+    wrapTransport(pair: TransportPair): TransportPair;
+};
+
+export { type CollectionDifference, type ConvergenceResult, type FieldDifference, type MixedTestDeviceConfig, type TestAuthBinding, TestDevice, type TestDeviceEncryption, type TestDeviceOptions, type TestDeviceServer, type TestNetwork, type TestNetworkOptions, TestServer, type TestServerOptions, type TestTransferMetrics, type TransportPair, checkConvergence, createMixedTestNetwork, createTestAuthBinding, createTestNetwork, createTransportMetrics, expectConverged, expectConvergedEventually, wrapTransportPairWithProtobufWire, wrapTransportPairWithServerClock };