@connecttomahdi/rxdb 17.0.0-beta.17

package/src/plugins/test-utils/performance.ts

@@ -0,0 +1,344 @@
+import assert from 'assert';
+import {
+    createRxDatabase,
+    randomToken,
+    requestIdlePromise,
+    RxCollection,
+    RxStorage
+} from '../../index.ts';
+import { wait } from 'async-test-util';
+import { averageSchemaData, AverageSchemaDocumentType } from './schema-objects.ts';
+import { averageSchema } from './schemas.ts';
+
+export type PerformanceTestConfig = {
+    /**
+     * How many times the test loop is run.
+     * More runs give more stable averages but take longer.
+     * @default 40
+     */
+    runs?: number;
+    /**
+     * Number of collections created per database.
+     * @default 4
+     */
+    collectionsAmount?: number;
+    /**
+     * Number of documents inserted in bulk per run.
+     * @default 3000
+     */
+    docsAmount?: number;
+    /**
+     * Number of documents inserted one-by-one (serial) per run.
+     * @default 50
+     */
+    serialDocsAmount?: number;
+    /**
+     * Number of parallel queries executed per run.
+     * @default 4
+     */
+    parallelQueryAmount?: number;
+    /**
+     * Number of batches used when doing bulk inserts.
+     * @default 6
+     */
+    insertBatches?: number;
+    /**
+     * Milliseconds to wait between test operations.
+     * Set to 0 to disable waiting (useful for smoke tests).
+     * @default 100
+     */
+    waitBetweenTests?: number;
+    /**
+     * Whether to log progress and results to the console.
+     * @default true
+     */
+    log?: boolean;
+};
+
+export type PerformanceTestResult = {
+    description: string;
+    collectionsAmount: number;
+    docsAmount: number;
+    [timingKey: string]: number | string;
+};
+
+/**
+ * Runs a performance benchmark against the given RxStorage.
+ * Useful for comparing different RxStorage implementations.
+ *
+ * @param storage - The RxStorage to benchmark.
+ * @param storageDescription - A human-readable description of the storage (used in results).
+ * @param config - Optional configuration to override the defaults.
+ * @returns An object with averaged timing values for each measured operation.
+ */
+export async function runPerformanceTests(
+    storage: RxStorage<any, any>,
+    storageDescription: string,
+    config: PerformanceTestConfig = {}
+): Promise<PerformanceTestResult> {
+    const {
+        runs = 40,
+        collectionsAmount = 4,
+        docsAmount = 3000,
+        serialDocsAmount = 50,
+        parallelQueryAmount = 4,
+        insertBatches = 6,
+        waitBetweenTests = 100,
+        log = true
+    } = config;
+
+    const totalTimes: { [k: string]: number[]; } = {};
+
+    let runsDone = 0;
+    while (runsDone < runs) {
+        if (log) {
+            console.log('runsDone: ' + runsDone + ' of ' + runs);
+        }
+        runsDone++;
+
+        let time = performance.now();
+        const updateTime = (flag?: string) => {
+            if (!flag) {
+                time = performance.now();
+                return;
+            }
+            const diff = performance.now() - time;
+            if (!totalTimes[flag]) {
+                totalTimes[flag] = [diff];
+            } else {
+                totalTimes[flag].push(diff);
+            }
+            time = performance.now();
+        };
+
+        await awaitBetweenTest(waitBetweenTests);
+        updateTime();
+
+        // create database
+        const dbName = 'test-db-performance-' + randomToken(10);
+        const schema = averageSchema();
+        let collection: RxCollection<AverageSchemaDocumentType>;
+        async function createDbWithCollections() {
+            if (collection) {
+                await collection.database.close();
+            }
+            const db = await createRxDatabase({
+                name: dbName,
+                eventReduce: true,
+                /**
+                 * A RxStorage implementation
+                 * might need a full leader election cycle to be usable.
+                 * So we disable multiInstance here because it would make no sense
+                 * to measure the leader election time instead of the database
+                 * creation time.
+                */
+                multiInstance: false,
+                storage
+            });
+
+            // create collections
+            const collectionData: any = {};
+            const collectionNames: string[] = [];
+            new Array(collectionsAmount)
+                .fill(0)
+                .forEach((_v, idx) => {
+                    const name = dbName + '_col_' + idx;
+                    collectionNames.push(name);
+                    collectionData[name] = {
+                        schema,
+                        statics: {}
+                    };
+                });
+            const firstCollectionName: string = collectionNames[0];
+            const collections = await db.addCollections(collectionData);
+            /**
+             * Many storages have a lazy initialization.
+             * So it makes no sense to measure the time of database/collection creation.
+             * Instead we do a single insert and measure the time to the first insert.
+             */
+            await collections[collectionNames[1]].insert(averageSchemaData());
+            return collections[firstCollectionName];
+        }
+        collection = await createDbWithCollections();
+        updateTime('time-to-first-insert');
+        await awaitBetweenTest(waitBetweenTests);
+
+        // insert documents (in batches)
+        const docIds: string[] = [];
+        const docsPerBatch = docsAmount / insertBatches;
+        for (let i = 0; i < insertBatches; i++) {
+            const docsData = new Array(docsPerBatch)
+                .fill(0)
+                .map((_v, idx) => {
+                    const data = averageSchemaData({
+                        var1: (idx % 2) + '',
+                        var2: idx % parallelQueryAmount
+                    });
+                    docIds.push(data.id);
+                    return data;
+                });
+            updateTime();
+            await collection.bulkInsert(docsData);
+            updateTime('insert-documents-' + docsPerBatch);
+            await awaitBetweenTest(waitBetweenTests);
+        }
+
+        // refresh db to ensure we do not run on caches
+        collection = await createDbWithCollections();
+        await awaitBetweenTest(waitBetweenTests);
+
+        /**
+         * Bulk Find by id
+         */
+        updateTime();
+        const idsResult = await collection.findByIds(docIds).exec();
+        updateTime('find-by-ids-' + docsAmount);
+        assert.strictEqual(Array.from(idsResult.keys()).length, docsAmount, 'find-by-id amount');
+        await awaitBetweenTest(waitBetweenTests);
+
+        /**
+         * Serial inserts
+         */
+        updateTime();
+        let c = 0;
+        const serialIds: string[] = [];
+        while (c < serialDocsAmount) {
+            c++;
+            const data = averageSchemaData({
+                var2: 1000
+            });
+            serialIds.push(data.id);
+            await collection.insert(data);
+        }
+        updateTime('serial-inserts-' + serialDocsAmount);
+
+        // refresh db to ensure we do not run on caches
+        collection = await createDbWithCollections();
+        await awaitBetweenTest(waitBetweenTests);
+
+        /**
+         * Serial find-by-id
+         */
+        updateTime();
+        for (const id of serialIds) {
+            await collection.findByIds([id]).exec();
+        }
+        updateTime('serial-find-by-id-' + serialDocsAmount);
+        await awaitBetweenTest(waitBetweenTests);
+
+        // find by query
+        updateTime();
+        const query = collection.find({
+            selector: {},
+            sort: [
+                { var2: 'asc' },
+                { var1: 'asc' }
+            ]
+        });
+        const queryResult = await query.exec();
+        updateTime('find-by-query');
+        assert.strictEqual(queryResult.length, docsAmount + serialDocsAmount, 'find-by-query');
+
+        // refresh db to ensure we do not run on caches
+        collection = await createDbWithCollections();
+        await awaitBetweenTest(waitBetweenTests);
+
+        // find by multiple queries in parallel
+        updateTime();
+        const parallelResult = await Promise.all(
+            new Array(parallelQueryAmount).fill(0).map((_v, idx) => {
+                const subQuery = collection.find({
+                    selector: {
+                        var2: idx
+                    }
+                });
+                return subQuery.exec();
+            })
+        );
+        updateTime('find-by-query-parallel-' + parallelQueryAmount);
+        let parallelSum = 0;
+        parallelResult.forEach(r => parallelSum = parallelSum + r.length);
+        assert.strictEqual(parallelSum, docsAmount, 'parallelSum');
+        await awaitBetweenTest(waitBetweenTests);
+
+        // run count query
+        updateTime();
+        let t = 0;
+        while (t < parallelQueryAmount) {
+            const countQuery = collection.count({
+                selector: {
+                    var2: {
+                        $eq: t
+                    }
+                }
+            });
+            const countQueryResult = await countQuery.exec();
+            assert.ok(countQueryResult >= ((docsAmount / insertBatches) - 5), 'count A ' + countQueryResult);
+            assert.ok(countQueryResult < (docsAmount * 0.8), 'count B ' + countQueryResult);
+            t++;
+        }
+        updateTime('4x-count');
+        await awaitBetweenTest(waitBetweenTests);
+
+        // test property access time
+        updateTime();
+        let sum = 0;
+        for (let i = 0; i < queryResult.length; i++) {
+            const doc = queryResult[i];
+
+            // access the same property exactly 2 times
+            sum += doc.deep.deeper.deepNr;
+            sum += doc.deep.deeper.deepNr;
+        }
+        updateTime('property-access');
+        assert.ok(sum > 10);
+
+        await collection.database.remove();
+    }
+
+    const result: PerformanceTestResult = {
+        description: storageDescription,
+        collectionsAmount,
+        docsAmount
+    };
+    Object.entries(totalTimes).forEach(([key, times]) => {
+        result[key] = roundToThree(averageOfTimeValues(times, 95));
+    });
+
+    if (log) {
+        console.log('Performance test for ' + storageDescription);
+        console.log(JSON.stringify(result, null, 4));
+    }
+
+    return result;
+}
+
+export function averageOfTimeValues(
+    times: number[],
+    /**
+     * To better account for anomalies
+     * during time measurements,
+     * we strip the highest x percent.
+     */
+    striphighestXPercent: number
+): number {
+    times = times.sort((a, b) => a - b);
+    const stripAmount = Math.floor(times.length * (striphighestXPercent * 0.01));
+    const useNumbers = times.slice(0, times.length - stripAmount);
+    let total = 0;
+    useNumbers.forEach(nr => total = total + nr);
+    return total / useNumbers.length;
+}
+
+function roundToThree(num: number) {
+    return Math.round(num * 1000) / 1000;
+}
+
+async function awaitBetweenTest(waitMs: number) {
+    await requestIdlePromise();
+    if (waitMs > 0) {
+        await wait(waitMs);
+    }
+    await requestIdlePromise();
+    await requestIdlePromise();
+}

package/src/plugins/test-utils/replication-base-test-suite.ts

@@ -0,0 +1,236 @@
+/**
+ * Base test suite for replication plugins.
+ * All replication plugins should run these tests
+ * to ensure consistent behavior across different backends.
+ *
+ * The tests use HumanDocumentType (passportId, firstName, lastName, age)
+ * with humansCollection.create() for collection creation.
+ */
+import assert from 'assert';
+import { wait } from 'async-test-util';
+import type { RxCollection } from '../../types/index.d.ts';
+import type { RxReplicationState } from '../replication/index.ts';
+import { ensureNotFalsy } from '../utils/index.ts';
+import * as humansCollection from './humans-collection.ts';
+import * as schemaObjects from './schema-objects.ts';
+import {
+    awaitCollectionsHaveEqualState,
+    ensureReplicationHasNoErrors
+} from './test-util.ts';
+
+export type ReplicationBaseTestSuiteConfig = {
+    /**
+     * Start a live replication for a collection.
+     * Must target a shared server endpoint so that multiple
+     * collections can replicate to the same backend.
+     */
+    startReplication(collection: RxCollection<any>): RxReplicationState<any, any>;
+
+    /**
+     * Run a one-shot (non-live) sync and wait for completion.
+     * Must target the same server endpoint as startReplication.
+     */
+    syncOnce(collection: RxCollection<any>): Promise<void>;
+
+    /**
+     * Get all documents from the server,
+     * including soft-deleted ones when the backend uses soft deletes.
+     */
+    getAllServerDocs(): Promise<any[]>;
+
+    /**
+     * Remove all documents from the server.
+     */
+    cleanUpServer(): Promise<void>;
+
+    /**
+     * Whether the server uses soft deletes
+     * (marks docs as deleted instead of removing them).
+     */
+    softDeletes: boolean;
+
+    /**
+     * Check if a server document is marked as deleted.
+     * Required when softDeletes is true.
+     */
+    isDeleted?(serverDoc: any): boolean;
+
+    /**
+     * Get the client primary key (passportId) from a server document.
+     * Different backends store the primary key in different fields.
+     */
+    getPrimaryOfServerDoc(serverDoc: any): string;
+
+    /**
+     * Additional wait time for eventually consistent backends (ms).
+     */
+    waitTime?: number;
+};
+
+/**
+ * Runs the base test suite for a replication plugin.
+ * Call this inside a describe() block in your replication test file.
+ *
+ * The config callbacks should target a shared server endpoint.
+ * Each test calls cleanUpServer() at the start to ensure a clean state.
+ *
+ * @example
+ * ```ts
+ * describe('replication-nats.test.ts', () => {
+ *     runReplicationBaseTestSuite({
+ *         startReplication: (collection) => syncNats(collection, natsName),
+ *         syncOnce: (collection) => syncOnceNats(collection, natsName),
+ *         getAllServerDocs: () => getAllDocsOfServer(natsName),
+ *         cleanUpServer: async () => { ... },
+ *         softDeletes: true,
+ *         isDeleted: (doc) => doc._deleted,
+ *         getPrimaryOfServerDoc: (doc) => doc.passportId,
+ *     });
+ * });
+ * ```
+ */
+export function runReplicationBaseTestSuite(config: ReplicationBaseTestSuiteConfig): void {
+    const waitTime = config.waitTime || 0;
+
+    describe('base test suite', () => {
+        describe('live replication', () => {
+            it('push replication to client-server', async () => {
+                await config.cleanUpServer();
+                const collection = await humansCollection.create(2, undefined, false);
+
+                const replicationState = config.startReplication(collection);
+                ensureReplicationHasNoErrors(replicationState);
+                await replicationState.awaitInitialReplication();
+
+                let docsOnServer = await config.getAllServerDocs();
+                assert.strictEqual(docsOnServer.length, 2);
+
+                // insert another one
+                await collection.insert(schemaObjects.humanData());
+                await replicationState.awaitInSync();
+
+                docsOnServer = await config.getAllServerDocs();
+                assert.strictEqual(docsOnServer.length, 3);
+
+                // update one
+                const doc = await collection.findOne().exec(true);
+                await doc.incrementalPatch({ age: 100 });
+                await replicationState.awaitInSync();
+                docsOnServer = await config.getAllServerDocs();
+                assert.strictEqual(docsOnServer.length, 3);
+                const serverDoc = ensureNotFalsy(
+                    docsOnServer.find(d => config.getPrimaryOfServerDoc(d) === doc.primary)
+                );
+                assert.strictEqual(serverDoc.age, 100);
+
+                // delete one
+                await doc.getLatest().remove();
+                await replicationState.awaitInSync();
+                docsOnServer = await config.getAllServerDocs();
+
+                if (config.softDeletes) {
+                    assert.strictEqual(docsOnServer.length, 3);
+                    assert.ok(docsOnServer.find(d => config.isDeleted!(d)));
+                } else {
+                    assert.strictEqual(docsOnServer.length, 2);
+                }
+
+                await collection.database.close();
+            });
+
+            it('two collections', async () => {
+                await config.cleanUpServer();
+
+                const collectionA = await humansCollection.create(0, undefined, false);
+                await collectionA.insert(schemaObjects.humanData('1aaa'));
+                const collectionB = await humansCollection.create(0, undefined, false);
+                await collectionB.insert(schemaObjects.humanData('1bbb'));
+
+                const replicationStateA = config.startReplication(collectionA);
+                ensureReplicationHasNoErrors(replicationStateA);
+                await replicationStateA.awaitInitialReplication();
+
+                const replicationStateB = config.startReplication(collectionB);
+                ensureReplicationHasNoErrors(replicationStateB);
+                await replicationStateB.awaitInitialReplication();
+
+                if (waitTime) { await wait(waitTime); }
+                await replicationStateA.awaitInSync();
+
+                await awaitCollectionsHaveEqualState(collectionA, collectionB, 'init sync');
+
+                // insert one
+                await collectionA.insert(schemaObjects.humanData('insert-a'));
+                await replicationStateA.awaitInSync();
+                await replicationStateB.awaitInSync();
+                if (waitTime) { await wait(waitTime); }
+                await awaitCollectionsHaveEqualState(collectionA, collectionB, 'after insert');
+
+                // delete one
+                await collectionB.findOne().remove();
+                await replicationStateB.awaitInSync();
+                await replicationStateA.awaitInSync();
+                if (waitTime) { await wait(waitTime); }
+                await awaitCollectionsHaveEqualState(collectionA, collectionB, 'after deletion');
+
+                // insert many
+                await collectionA.bulkInsert(
+                    new Array(10)
+                        .fill(0)
+                        .map(() => schemaObjects.humanData(undefined, undefined, 'bulk-insert-A'))
+                );
+                await replicationStateA.awaitInSync();
+                await replicationStateB.awaitInSync();
+                if (waitTime) { await wait(waitTime); }
+                await awaitCollectionsHaveEqualState(collectionA, collectionB, 'after insert many');
+
+                // insert at both collections at the same time
+                await Promise.all([
+                    collectionA.insert(schemaObjects.humanData('insert-parallel-a')),
+                    collectionB.insert(schemaObjects.humanData('insert-parallel-b'))
+                ]);
+                await replicationStateA.awaitInSync();
+                await replicationStateB.awaitInSync();
+                await replicationStateA.awaitInSync();
+                await replicationStateB.awaitInSync();
+                if (waitTime) { await wait(waitTime); }
+                await awaitCollectionsHaveEqualState(collectionA, collectionB, 'after insert both at same time');
+
+                await collectionA.database.close();
+                await collectionB.database.close();
+            });
+        });
+
+        describe('conflict handling', () => {
+            it('should keep the master state as default conflict handler', async () => {
+                await config.cleanUpServer();
+
+                const c1 = await humansCollection.create(1);
+                const c2 = await humansCollection.create(0);
+
+                await config.syncOnce(c1);
+                await config.syncOnce(c2);
+
+                const doc1 = await c1.findOne().exec(true);
+                const doc2 = await c2.findOne().exec(true);
+
+                // make update on both sides
+                await doc1.incrementalPatch({ firstName: 'c1' });
+                await doc2.incrementalPatch({ firstName: 'c2' });
+
+                await config.syncOnce(c2);
+
+                // cause conflict
+                await config.syncOnce(c1);
+
+                /**
+                 * Must have kept the master state c2
+                 */
+                assert.strictEqual(doc1.getLatest().firstName, 'c2');
+
+                await c1.database.close();
+                await c2.database.close();
+            });
+        });
+    });
+}

package/src/plugins/test-utils/replication.ts

@@ -0,0 +1,95 @@
+import { Observable } from 'rxjs';
+import { rxStorageInstanceToReplicationHandler } from '../../replication-protocol/index.ts';
+import type {
+    DeepReadonly,
+    ReplicationPullHandler,
+    ReplicationPushHandler,
+    RxCollection,
+    RxReplicationPullStreamItem,
+    RxReplicationWriteToMasterRow
+} from '../../types';
+import { deepEqual } from '../utils/index.ts';
+
+/**
+ * Creates a pull handler that always returns
+ * all documents.
+*/
+export function getPullHandler<RxDocType, CheckpointType>(
+    remoteCollection: RxCollection<RxDocType, {}, {}, {}>
+): ReplicationPullHandler<RxDocType, CheckpointType> {
+    const helper = rxStorageInstanceToReplicationHandler<RxDocType, CheckpointType>(
+        remoteCollection.storageInstance,
+        remoteCollection.database.conflictHandler as any,
+        remoteCollection.database.token
+    );
+    const handler: ReplicationPullHandler<RxDocType, CheckpointType> = async (
+        latestPullCheckpoint: CheckpointType | undefined,
+        batchSize: number
+    ) => {
+        const result = await helper.masterChangesSince(latestPullCheckpoint, batchSize);
+        return result;
+    };
+    return handler;
+}
+export function getPullStream<RxDocType>(
+    remoteCollection: RxCollection<RxDocType, {}, {}, {}>
+): Observable<RxReplicationPullStreamItem<RxDocType, any>> {
+    const helper = rxStorageInstanceToReplicationHandler(
+        remoteCollection.storageInstance,
+        remoteCollection.conflictHandler,
+        remoteCollection.database.token
+    );
+    return helper.masterChangeStream$;
+}
+export function getPushHandler<RxDocType>(
+    remoteCollection: RxCollection<RxDocType, {}, {}, {}>
+): ReplicationPushHandler<RxDocType> {
+    const helper = rxStorageInstanceToReplicationHandler(
+        remoteCollection.storageInstance,
+        remoteCollection.conflictHandler,
+        remoteCollection.database.token
+    );
+    const handler: ReplicationPushHandler<RxDocType> = async (
+        rows: RxReplicationWriteToMasterRow<RxDocType>[]
+    ) => {
+        const result = await helper.masterWrite(rows);
+        return result;
+    };
+    return handler;
+}
+
+
+export async function ensureEqualState<RxDocType>(
+    collectionA: RxCollection<RxDocType>,
+    collectionB: RxCollection<RxDocType>,
+    context?: string
+) {
+    const [
+        docsA,
+        docsB
+    ] = await Promise.all([
+        collectionA.find().exec().then(docs => docs.map(d => d.toJSON(true))),
+        collectionB.find().exec().then(docs => docs.map(d => d.toJSON(true)))
+    ]);
+
+    docsA.forEach((docA, idx) => {
+        const docB = docsB[idx];
+        const cleanDocToCompare = (doc: DeepReadonly<RxDocType>) => {
+            return Object.assign({}, doc, {
+                _meta: undefined,
+                _rev: undefined
+            });
+        };
+
+
+        if (!deepEqual(
+            cleanDocToCompare(docA),
+            cleanDocToCompare(docB)
+        )) {
+            console.log('## ERROR: State not equal (context: "' + context + '")');
+            console.log(JSON.stringify(docA, null, 4));
+            console.log(JSON.stringify(docB, null, 4));
+            throw new Error('STATE not equal (context: "' + context + '")');
+        }
+    });
+}

package/src/plugins/test-utils/revisions.ts

@@ -0,0 +1,4 @@
+export const EXAMPLE_REVISION_1 = '1-12080c42d471e3d2625e49dcca3b8e1a';
+export const EXAMPLE_REVISION_2 = '2-22080c42d471e3d2625e49dcca3b8e2b';
+export const EXAMPLE_REVISION_3 = '3-32080c42d471e3d2625e49dcca3b8e3c';
+export const EXAMPLE_REVISION_4 = '4-42080c42d471e3d2625e49dcca3b8e3c';