@connecttomahdi/rxdb 17.0.0-beta.17

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

@@ -0,0 +1,85 @@
+import type { Func } from 'mocha';
+import assert from 'assert';
+import type { RxCollection } from '../../types';
+import { promiseWait, requestIdlePromise } from '../utils/index.ts';
+import type { RxReplicationState } from '../replication/index.ts';
+
+export function testMultipleTimes(times: number, title: string, test: Func) {
+    new Array(times).fill(0).forEach(() => {
+        it(title, test);
+    });
+}
+
+export async function ensureCollectionsHaveEqualState<RxDocType>(
+    c1: RxCollection<RxDocType>,
+    c2: RxCollection<RxDocType>,
+    logContext?: string
+) {
+    await requestIdlePromise();
+    const getJson = async (collection: RxCollection<RxDocType>) => {
+        const docs = await collection.find().exec();
+        return docs.map(d => d.toJSON());
+    };
+    const json1 = await getJson(c1);
+    const json2 = await getJson(c2);
+    try {
+        assert.deepStrictEqual(
+            json1,
+            json2
+        );
+    } catch (err) {
+        console.error('ensureCollectionsHaveEqualState(' + logContext + ') states not equal (c1:' + c1.name + ', c2:' + c2.name + '):');
+        console.dir({
+            c1: json1,
+            c2: json2
+        });
+        console.log('----------');
+        throw err;
+    }
+}
+
+/**
+ * Waits until the collections have the equal state.
+ */
+export async function awaitCollectionsHaveEqualState<RxDocType>(
+    c1: RxCollection<RxDocType>,
+    c2: RxCollection<RxDocType>,
+    logContext?: string,
+    timeout = 8000
+) {
+    let i = 0;
+    const startTime = Date.now();
+    while (true) {
+        i++;
+        try {
+            await ensureCollectionsHaveEqualState(
+                c1,
+                c2,
+                logContext
+            );
+            return;
+        } catch (err) {
+            if ((Date.now() - startTime) > timeout) {
+                throw err;
+            } else {
+                await promiseWait(50 * i);
+            }
+        }
+    }
+}
+
+
+
+export function ensureReplicationHasNoErrors(replicationState: RxReplicationState<any, any>) {
+    /**
+     * We do not have to unsubscribe because the observable will cancel anyway.
+     */
+    replicationState.error$.subscribe((err: any) => {
+        console.error('ensureReplicationHasNoErrors() has error:');
+        console.log(err);
+        if (err?.parameters?.errors) {
+            throw err.parameters.errors[0];
+        }
+        throw err;
+    });
+}

package/src/plugins/update/index.ts

@@ -0,0 +1,57 @@
+/**
+ * this plugin allows delta-updates with mongo-like-syntax
+ * It's using mingo internally
+ * @link https://github.com/kofrasa/mingo
+ */
+import { runQueryUpdateFunction } from '../../rx-query-helper.ts';
+import type {
+    RxDocument,
+    RxQuery,
+    RxPlugin,
+    UpdateQuery
+} from '../../types/index.d.ts';
+import { mingoUpdater } from './mingo-updater.ts';
+
+export function incrementalUpdate<RxDocType>(
+    this: RxDocument<RxDocType>,
+    updateObj: UpdateQuery<RxDocType>
+): Promise<RxDocument<RxDocType>> {
+    return this.incrementalModify((docData) => {
+        const newDocData = mingoUpdater<RxDocType>(docData, updateObj);
+        return newDocData;
+    });
+}
+
+export function update<RxDocType>(
+    this: RxDocument<RxDocType>,
+    updateObj: UpdateQuery<RxDocType>
+): Promise<RxDocument<RxDocType>> {
+    const oldDocData = this._data;
+    const newDocData = mingoUpdater(oldDocData, updateObj);
+    return this._saveData(newDocData, oldDocData);
+}
+
+export async function RxQueryUpdate(
+    this: RxQuery,
+    updateObj: UpdateQuery<any>
+): Promise<any> {
+    return runQueryUpdateFunction(
+        this.asRxQuery,
+        (doc) => doc.update(updateObj),
+    );
+}
+
+
+export const RxDBUpdatePlugin: RxPlugin = {
+    name: 'update',
+    rxdb: true,
+    prototypes: {
+        RxDocument: (proto: any) => {
+            proto.update = update;
+            proto.incrementalUpdate = incrementalUpdate;
+        },
+        RxQuery: (proto: any) => {
+            proto.update = RxQueryUpdate;
+        }
+    }
+};

package/src/plugins/update/mingo-updater.ts

@@ -0,0 +1,26 @@
+/**
+ * Custom build of the mingo updater for smaller build size
+ */
+import { update } from "mingo/updater";
+import {
+    clone
+} from '../utils/index.ts';
+import type {
+    UpdateQuery
+} from '../../types/index';
+
+export function mingoUpdater<T>(
+    d: T, op: UpdateQuery<T>
+): T {
+    const cloned = clone(d);
+    update<any>(
+        cloned,
+        op,
+        undefined,
+        undefined,
+        {
+            cloneMode: "none"
+        }
+    );
+    return cloned;
+}

package/src/plugins/utils/index.ts

@@ -0,0 +1,20 @@
+export * from './utils-array.ts';
+export * from './utils-blob.ts';
+export * from './utils-base64.ts';
+export * from './utils-revision.ts';
+export * from './utils-document.ts';
+export * from './utils-hash.ts';
+export * from './utils-promise.ts';
+export * from './utils-regex.ts';
+export * from './utils-string.ts';
+export * from './utils-number.ts';
+export * from './utils-object-deep-equal.ts';
+export * from './utils-object-dot-prop.ts';
+export * from './utils-object.ts';
+export * from './utils-map.ts';
+export * from './utils-error.ts';
+export * from './utils-time.ts';
+export * from './utils-other.ts';
+export * from './utils-rxdb-version.ts';
+export * from './utils-global.ts';
+export * from './utils-premium.ts';

package/src/plugins/utils/utils-array.ts

@@ -0,0 +1,152 @@
+import type {
+    MaybePromise,
+    MaybeReadonly
+} from '../../types/index.d.ts';
+
+export function lastOfArray<T>(ar: T[]): T | undefined {
+    return ar[ar.length - 1];
+}
+
+/**
+ * shuffle the given array
+ */
+export function shuffleArray<T>(arr: T[]): T[] {
+    return arr.slice(0).sort(() => (Math.random() - 0.5));
+}
+
+export function randomOfArray<T>(arr: T[]): T {
+    const randomElement = arr[Math.floor(Math.random() * arr.length)];
+    return randomElement;
+}
+
+
+export function toArray<T>(input: T | T[] | Readonly<T> | Readonly<T[]>): T[] {
+    return Array.isArray(input) ? (input as any[]).slice(0) : ([input] as any);
+}
+
+/**
+ * Split array with items into smaller arrays with items
+ * @link https://stackoverflow.com/a/7273794/3443137
+ */
+export function batchArray<T>(array: T[], batchSize: number): T[][] {
+    array = array.slice(0);
+    const ret: T[][] = [];
+    while (array.length) {
+        const batch = array.splice(0, batchSize);
+        ret.push(batch);
+    }
+    return ret;
+}
+
+/**
+ * @link https://stackoverflow.com/a/15996017
+ */
+export function removeOneFromArrayIfMatches<T>(ar: T[], condition: (x: T) => boolean): T[] {
+    ar = ar.slice();
+    let i = ar.length;
+    let done = false;
+    while (i-- && !done) {
+        if (condition(ar[i])) {
+            done = true;
+            ar.splice(i, 1);
+        }
+    }
+    return ar;
+}
+
+/**
+ * returns true if the supplied argument is either an Array<T> or a Readonly<Array<T>>
+ */
+export function isMaybeReadonlyArray(x: any): x is MaybeReadonly<any[]> {
+    // While this looks strange, it's a workaround for an issue in TypeScript:
+    // https://github.com/microsoft/TypeScript/issues/17002
+    //
+    // The problem is that `Array.isArray` as a type guard returns `false` for a readonly array,
+    // but at runtime the object is an array and the runtime call to `Array.isArray` would return `true`.
+    // The type predicate here allows for both `Array<T>` and `Readonly<Array<T>>` to pass a type check while
+    // still performing runtime type inspection.
+    return Array.isArray(x);
+}
+
+
+
+export function isOneItemOfArrayInOtherArray<T>(ar1: T[], ar2: T[]): boolean {
+    for (let i = 0; i < ar1.length; i++) {
+        const el = ar1[i];
+        const has = ar2.includes(el);
+        if (has) {
+            return true;
+        }
+    }
+    return false;
+}
+
+
+/**
+ * Use this in array.filter() to remove all empty slots
+ * and have the correct typings afterwards.
+ * @link https://stackoverflow.com/a/46700791/3443137
+ */
+export function arrayFilterNotEmpty<TValue>(value: TValue | null | undefined): value is TValue {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    return true;
+}
+
+export function countUntilNotMatching<T>(
+    ar: T[],
+    matchingFn: (v: T, idx: number) => boolean
+): number {
+    let count = 0;
+    let idx = -1;
+    for (const item of ar) {
+        idx = idx + 1;
+        const matching = matchingFn(item, idx);
+        if (matching) {
+            count = count + 1;
+        } else {
+            break;
+        }
+    }
+    return count;
+}
+
+export async function asyncFilter<T>(array: T[], predicate: (item: T, index: number, a: T[]) => MaybePromise<boolean>): Promise<T[]> {
+    const filters = await Promise.all(
+        array.map(predicate)
+    );
+
+    return array.filter((...[, index]) => filters[index]);
+}
+
+/**
+ * @link https://stackoverflow.com/a/3762735
+ */
+export function sumNumberArray(array: number[]): number {
+    let count = 0;
+    for (let i = array.length; i--;) {
+        count += array[i];
+    }
+    return count;
+}
+
+export function maxOfNumbers(arr: number[]): number {
+    return Math.max(...arr);
+}
+
+/**
+ * @link https://gist.github.com/telekosmos/3b62a31a5c43f40849bb
+ */
+export function uniqueArray(arrArg: string[]): string[] {
+    return arrArg.filter(function (elem, pos, arr) {
+        return arr.indexOf(elem) === pos;
+    });
+}
+
+
+export function sortByObjectNumberProperty<T>(property: keyof T) {
+    return (a: T, b: T) => {
+        return (b as any)[property] - (a as any)[property];
+    }
+}

package/src/plugins/utils/utils-base64.ts

@@ -0,0 +1,49 @@
+
+/**
+ * NO! We cannot just use btoa() and atob()
+ * because they do not work correctly with binary data.
+ * @link https://stackoverflow.com/q/30106476/3443137
+ */
+import { encode, decode } from 'js-base64';
+
+/**
+ * atob() and btoa() do not work well with non ascii chars,
+ * so we have to use these helper methods instead.
+ * @link https://stackoverflow.com/a/30106551/3443137
+ */
+// Encoding UTF8 -> base64
+export function b64EncodeUnicode(str: string) {
+    return encode(str);
+}
+
+// Decoding base64 -> UTF8
+export function b64DecodeUnicode(str: string) {
+    return decode(str);
+}
+
+/**
+ * @link https://stackoverflow.com/a/9458996/3443137
+ */
+export function arrayBufferToBase64(buffer: ArrayBuffer) {
+    let binary = '';
+    const bytes = new Uint8Array(buffer);
+    const len = bytes.byteLength;
+    for (let i = 0; i < len; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+
+
+/**
+ * @link https://stackoverflow.com/a/21797381
+ */
+export function base64ToArrayBuffer(base64: string): ArrayBuffer {
+    const binary_string = atob(base64);
+    const len = binary_string.length;
+    const bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        bytes[i] = binary_string.charCodeAt(i);
+    }
+    return bytes.buffer;
+}

package/src/plugins/utils/utils-blob.ts

@@ -0,0 +1,65 @@
+import { arrayBufferToBase64 } from './utils-base64.ts';
+
+/**
+ * Since RxDB 13.0.0 we only use Blob instead of falling back to Buffer,
+ * because Node.js >18 supports Blobs anyway.
+ */
+/**
+ * depending if we are on node or browser,
+ * we have to use Buffer(node) or Blob(browser)
+ */
+export function createBlob(
+    data: string,
+    type: string
+): Blob {
+    const blob = new Blob([data], {
+        type
+    });
+    return blob;
+}
+
+export async function createBlobFromBase64(
+    base64String: string,
+    type: string
+): Promise<Blob> {
+    const base64Response = await fetch(`data:${type};base64,${base64String}`);
+    const blob = await base64Response.blob();
+    return blob;
+}
+
+export function blobToString(blob: Blob | string): Promise<string> {
+    /**
+     * in the electron-renderer we have a typed array instead of a blob
+     * so we have to transform it.
+     * @link https://github.com/pubkey/rxdb/issues/1371
+     */
+    const blobType = Object.prototype.toString.call(blob);
+    if (blobType === '[object Uint8Array]') {
+        blob = new Blob([blob]);
+    }
+    if (typeof blob === 'string') {
+        return Promise.resolve(blob);
+    }
+
+    return blob.text();
+}
+
+export async function blobToBase64String(blob: Blob | string): Promise<string> {
+    if (typeof blob === 'string') {
+        return blob;
+    }
+
+    /**
+     * in the electron-renderer we have a typed array instead of a blob
+     * so we have to transform it.
+     * @link https://github.com/pubkey/rxdb/issues/1371
+     */
+    const blobType = Object.prototype.toString.call(blob);
+    if (blobType === '[object Uint8Array]') {
+        blob = new Blob([blob]);
+    }
+
+    const arrayBuffer = await blob.arrayBuffer();
+    return arrayBufferToBase64(arrayBuffer);
+}
+

package/src/plugins/utils/utils-document.ts

@@ -0,0 +1,117 @@
+import type {
+    DeepReadonly,
+    RxDocumentData,
+    RxDocumentMeta,
+    StringKeys,
+    WithDeleted,
+    WithDeletedAndAttachments
+} from '../../types/index.d.ts';
+import { flatClone } from './utils-object.ts';
+/**
+ * We use 1 as minimum so that the value is never falsy.
+ * This const is used in several places because querying
+ * with a value lower than the minimum could give false results.
+ */
+export const RX_META_LWT_MINIMUM = 1;
+
+export function getDefaultRxDocumentMeta(): RxDocumentMeta {
+    return {
+        /**
+         * Set this to 1 to not waste performance
+         * while calling new Date()..
+         * The storage wrappers will anyway update
+         * the lastWrite time while calling transformDocumentDataFromRxDBToRxStorage()
+         */
+        lwt: RX_META_LWT_MINIMUM
+    };
+}
+
+/**
+ * Returns a revision that is not valid.
+ * Use this to have correct typings
+ * while the storage wrapper anyway will overwrite the revision.
+ */
+export function getDefaultRevision(): string {
+    /**
+     * Use a non-valid revision format,
+     * to ensure that the RxStorage will throw
+     * when the revision is not replaced downstream.
+     */
+    return '';
+}
+
+
+export function stripMetaDataFromDocument<RxDocType>(docData: RxDocumentData<RxDocType>): RxDocType {
+    return Object.assign({}, docData, {
+        _meta: undefined,
+        _deleted: undefined,
+        _rev: undefined
+    });
+}
+
+
+/**
+ * Faster way to check the equality of document lists
+ * compared to doing a deep-equal.
+ * Here we only check the ids and revisions.
+ */
+export function areRxDocumentArraysEqual<RxDocType>(
+    primaryPath: StringKeys<RxDocumentData<RxDocType>>,
+    ar1: RxDocumentData<RxDocType>[],
+    ar2: RxDocumentData<RxDocType>[]
+): boolean {
+    if (ar1.length !== ar2.length) {
+        return false;
+    }
+    let i = 0;
+    const len = ar1.length;
+    while (i < len) {
+        const row1 = ar1[i];
+        const row2 = ar2[i];
+        i++;
+
+        if (
+            row1[primaryPath] !== row2[primaryPath] ||
+            row1._rev !== row2._rev ||
+            row1._meta.lwt !== row2._meta.lwt
+        ) {
+            return false;
+        }
+    }
+    return true;
+}
+
+
+
+export function getSortDocumentsByLastWriteTimeComparator<RxDocType>(primaryPath: string) {
+    return (a: RxDocumentData<RxDocType>, b: RxDocumentData<RxDocType>) => {
+        if (a._meta.lwt === b._meta.lwt) {
+            if ((b as any)[primaryPath] < (a as any)[primaryPath]) {
+                return 1;
+            } else {
+                return -1;
+            }
+        } else {
+            return a._meta.lwt - b._meta.lwt;
+        }
+    };
+}
+export function sortDocumentsByLastWriteTime<RxDocType>(
+    primaryPath: string,
+    docs: RxDocumentData<RxDocType>[]
+): RxDocumentData<RxDocType>[] {
+    return docs.sort(getSortDocumentsByLastWriteTimeComparator(primaryPath));
+}
+
+type AnyDocFormat<RxDocType> = RxDocType | WithDeleted<RxDocType> | RxDocumentData<RxDocType> | WithDeletedAndAttachments<RxDocType>;
+export function toWithDeleted<RxDocType>(
+    docData: AnyDocFormat<RxDocType> | DeepReadonly<AnyDocFormat<RxDocType>>
+): WithDeleted<RxDocType> {
+    docData = flatClone(docData);
+    (docData as any)._deleted = !!(docData as any)._deleted;
+    return Object.assign(docData as any, {
+        _attachments: undefined,
+        _meta: undefined,
+        _rev: undefined
+    }) as any;
+}

package/src/plugins/utils/utils-error.ts

@@ -0,0 +1,53 @@
+import type {
+    PlainJsonError,
+    RxError,
+    RxTypeError
+} from '../../types/index.d.ts';
+import { ucfirst } from './utils-string.ts';
+
+
+
+/**
+ * Returns an error that indicates that a plugin is missing
+ * We do not throw a RxError because this should not be handled
+ * programmatically but by using the correct import
+ */
+export function pluginMissing(
+    pluginKey: string
+): Error {
+    const keyParts = pluginKey.split('-');
+    let pluginName = 'RxDB';
+    keyParts.forEach(part => {
+        pluginName += ucfirst(part);
+    });
+    pluginName += 'Plugin';
+    return new Error(
+        `You are using a function which must be overwritten by a plugin.
+        You should either prevent the usage of this function or add the plugin via:
+            import { ${pluginName} } from 'rxdb/plugins/${pluginKey}';
+            addRxPlugin(${pluginName});
+        `
+    );
+}
+
+
+
+export function errorToPlainJson(err: Error | TypeError | RxError | RxTypeError): PlainJsonError {
+    const ret: PlainJsonError = {
+        name: err.name,
+        message: err.message,
+        rxdb: (err as any).rxdb,
+        parameters: (err as RxError).parameters,
+        extensions: (err as any).extensions,
+        code: (err as RxError).code,
+        url: (err as RxError).url,
+        /**
+         * stack must be last to make it easier to read the json in a console.
+         * Also we ensure that each linebreak is spaced so that the chrome devtools
+         * shows urls to the source code that can be clicked to inspect
+         * the correct place in the code.
+         */
+        stack: !err.stack ? undefined : err.stack.replace(/\n/g, ' \n ')
+    };
+    return ret;
+}

package/src/plugins/utils/utils-global.ts

@@ -0,0 +1,5 @@
+/**
+ * Can be used by some plugins to have a "global" object that
+ * can be imported and mutated at will.
+ */
+export const RXDB_UTILS_GLOBAL: any = {};

package/src/plugins/utils/utils-hash.ts

@@ -0,0 +1,62 @@
+import { newRxError } from '../../rx-error.ts';
+import type { HashFunction } from '../../types/index.d.ts';
+
+/**
+ * Cache this here so we do not have to run the try-catch
+ * each time for better performance.
+ * If your JavaScript runtime does not support crypto.subtle.digest,
+ * provide your own hash function when calling createRxDatabase().
+ */
+let hashFn: typeof crypto.subtle.digest;
+function getHashFn() {
+    if (hashFn) {
+        return hashFn;
+    }
+    if (
+        typeof crypto === 'undefined' ||
+        typeof crypto.subtle === 'undefined' ||
+        typeof crypto.subtle.digest !== 'function'
+    ) {
+        throw newRxError('UT8', {
+            args: {
+                typeof_crypto: typeof crypto,
+                typeof_crypto_subtle: typeof crypto?.subtle,
+                typeof_crypto_subtle_digest: typeof crypto?.subtle?.digest
+            }
+        });
+    }
+    hashFn = crypto.subtle.digest.bind(crypto.subtle);
+    return hashFn;
+}
+
+export async function nativeSha256(input: string | ArrayBuffer | Blob) {
+    let data: BufferSource;
+    if (typeof Blob !== "undefined" && input instanceof Blob) {
+        data = await input.arrayBuffer();
+    } else if (typeof input === 'string') {
+        data = new TextEncoder().encode(input);
+    } else {
+        data = input as ArrayBuffer;
+    }
+    const hashBuffer = await getHashFn()('SHA-256', data);
+    /**
+     * @link https://jameshfisher.com/2017/10/30/web-cryptography-api-hello-world/
+     */
+    const hash = Array.prototype.map.call(
+        new Uint8Array(hashBuffer),
+        x => (('00' + x.toString(16)).slice(-2))
+    ).join('');
+    return hash;
+}
+
+export const defaultHashSha256: HashFunction = nativeSha256;
+
+export function hashStringToNumber(str: string): number {
+    let nr = 0;
+    const len = str.length;
+    for (let i = 0; i < len; i++) {
+        nr = nr + str.charCodeAt(i);
+        nr |= 0; // Convert to 32bit integer, improves performance
+    }
+    return nr;
+}