@connecttomahdi/rxdb 17.1.0 → 17.1.1

package/dist/types/types/plugins/replication-graphql.d.ts

@@ -0,0 +1,98 @@
+import { ClientOptions } from 'graphql-ws';
+import { RxReplicationWriteToMasterRow } from '../replication-protocol.ts';
+import { ById, MaybePromise } from '../util.ts';
+import {
+    ReplicationOptions,
+    ReplicationPullHandlerResult,
+    ReplicationPullOptions,
+    ReplicationPushHandlerResult,
+    ReplicationPushOptions
+} from './replication.ts';
+
+export interface RxGraphQLReplicationQueryBuilderResponseObject {
+    query: string;
+    operationName?: string;
+    variables: any;
+}
+
+export type RxGraphQLReplicationClientState = {
+    headers: ById<string>;
+    credentials: RequestCredentials | undefined;
+};
+
+export type RxGraphQLReplicationQueryBuilderResponse =
+    RxGraphQLReplicationQueryBuilderResponseObject |
+    Promise<RxGraphQLReplicationQueryBuilderResponseObject>;
+export type RxGraphQLReplicationPushQueryBuilder = (
+    // typed 'any' because the data might be modified by the push.modifier.
+    rows: RxReplicationWriteToMasterRow<any>[]
+) => RxGraphQLReplicationQueryBuilderResponse;
+
+export type RxGraphQLPullWSOptions = Omit<ClientOptions, 'url' | 'shouldRetry' | 'webSocketImpl'>;
+
+export type RxGraphQLReplicationPullQueryBuilder<CheckpointType> = (
+    latestPulledCheckpoint: CheckpointType | undefined,
+    limit: number
+) => RxGraphQLReplicationQueryBuilderResponse;
+export type GraphQLSyncPullOptions<RxDocType, CheckpointType> = Omit<
+    ReplicationPullOptions<RxDocType, CheckpointType>,
+    'handler' | 'stream$'
+> & {
+    queryBuilder: RxGraphQLReplicationPullQueryBuilder<CheckpointType>;
+    streamQueryBuilder?: RxGraphQLReplicationPullStreamQueryBuilder;
+    /**
+     * The path to the data in the GraphQL response.
+     * If set, the data will be taken from the response at this path.
+     * @example ['data', 'foo', 'bar'] or 'data.foo.bar'
+     */
+    dataPath?: string | string[];
+    responseModifier?: RxGraphQLPullResponseModifier<RxDocType, CheckpointType>;
+    includeWsHeaders?: boolean;
+    wsOptions?: RxGraphQLPullWSOptions;
+};
+
+export type RxGraphQLPullResponseModifier<RxDocType, CheckpointType> = (
+    // the exact response that was returned from the server
+    plainResponse: ReplicationPullHandlerResult<RxDocType, CheckpointType> | any,
+    // either 'handler' if it came from the pull.handler, or 'stream' if it came from the pull.stream
+    origin: 'handler' | 'stream',
+    requestCheckpoint?: CheckpointType
+) => MaybePromise<ReplicationPullHandlerResult<RxDocType, CheckpointType>>;
+
+export type RxGraphQLPushResponseModifier<RxDocType> = (
+    // the exact response that was returned from the server
+    plainResponse: ReplicationPushHandlerResult<RxDocType> | any,
+) => MaybePromise<ReplicationPushHandlerResult<RxDocType>>;
+
+export type RxGraphQLReplicationPullStreamQueryBuilder = (headers: { [k: string]: string; }) => RxGraphQLReplicationQueryBuilderResponse;
+
+export type GraphQLSyncPushOptions<RxDocType> = Omit<
+    ReplicationPushOptions<RxDocType>,
+    'handler'
+> & {
+    queryBuilder: RxGraphQLReplicationPushQueryBuilder;
+    /**
+     * The path to the data in the GraphQL response.
+     * If set, the data will be taken from the response at this path.
+     * @example ['data', 'foo', 'bar'] or 'data.foo.bar'
+     */
+    dataPath?: string | string[];
+    responseModifier?: RxGraphQLPushResponseModifier<RxDocType>;
+};
+
+export type GraphQLServerUrl = {
+    http?: string;
+    ws?: string;
+};
+
+export type SyncOptionsGraphQL<RxDocType, CheckpointType> = Omit<
+    ReplicationOptions<RxDocType, CheckpointType>,
+    'pull' | 'push'
+> & {
+    url: GraphQLServerUrl;
+    fetch?: WindowOrWorkerGlobalScope['fetch'];
+    headers?: { [k: string]: string; }; // send with all requests to the endpoint
+    credentials?: RequestCredentials;
+    pull?: GraphQLSyncPullOptions<RxDocType, CheckpointType>;
+    push?: GraphQLSyncPushOptions<RxDocType>;
+};

package/dist/types/types/plugins/replication.d.ts

@@ -0,0 +1,175 @@
+import { Observable } from 'rxjs';
+import type {
+    InternalStoreDocType,
+    MaybePromise,
+    RxCollection,
+    RxDocumentData,
+    RxReplicationPullStreamItem,
+    RxReplicationWriteToMasterRow,
+    WithDeleted
+} from '../../types/index.d.ts';
+
+
+export type InternalStoreReplicationPushDocType = InternalStoreDocType<{
+    checkpoint: any;
+}>;
+export type InternalStoreReplicationPullDocType<RxDocType> = InternalStoreDocType<{
+    lastPulledDoc: RxDocumentData<RxDocType>;
+}>;
+
+export type ReplicationPullHandlerResult<RxDocType, CheckpointType> = {
+    checkpoint: CheckpointType | undefined;
+    documents: WithDeleted<RxDocType>[];
+};
+
+export type ReplicationPushHandlerResult<RxDocType> = RxDocType[];
+
+export type ReplicationPullHandler<RxDocType, CheckpointType> = (
+    lastPulledCheckpoint: CheckpointType | undefined,
+    batchSize: number
+) => Promise<ReplicationPullHandlerResult<RxDocType, CheckpointType>>;
+
+export type ReplicationPullOptions<RxDocType, CheckpointType> = {
+    /**
+     * A handler that pulls the new remote changes
+     * from the remote actor.
+     */
+    handler: ReplicationPullHandler<RxDocType, CheckpointType>;
+
+
+    /**
+     * An observable that streams all document changes
+     * that are happening on the backend.
+     * Emits an document bulk together with the latest checkpoint of these documents.
+     * Also can emit a 'RESYNC' event when the client was offline and is online again.
+     *
+     * Not required for non-live replication.
+     */
+    stream$?: Observable<RxReplicationPullStreamItem<RxDocType, CheckpointType>>;
+
+    /**
+     * Amount of documents that the remote will send in one request.
+     * If the response contains less then [batchSize] documents,
+     * RxDB will assume there are no more changes on the backend
+     * that are not replicated.
+     * [default=100]
+     */
+    batchSize?: number;
+
+    /**
+     * A modifier that runs on all documents that are pulled,
+     * before they are used by RxDB.
+     * - the ones from the pull handler
+     * - the ones from the pull stream
+     */
+    modifier?: (docData: any) => MaybePromise<WithDeleted<RxDocType>>;
+
+    /**
+     * If set, the push replication
+     * will start from the given checkpoint.
+     */
+    initialCheckpoint?: any;
+};
+
+/**
+ * Gets the new write rows.
+ * Returns the current master state of all conflicting writes,
+ * so that they can be resolved on the client.
+ */
+export type ReplicationPushHandler<RxDocType> = (
+    docs: RxReplicationWriteToMasterRow<RxDocType>[]
+) => Promise<WithDeleted<RxDocType>[]>;
+export type ReplicationPushOptions<RxDocType> = {
+    /**
+     * A handler that sends the new local changes
+     * to the remote actor.
+     * On error, all documents are send again at later time.
+     */
+    handler: ReplicationPushHandler<RxDocType>;
+
+
+    /**
+     * A modifier that runs on all pushed documents before
+     * they are send into the push handler.
+     */
+    modifier?: (docData: WithDeleted<RxDocType>) => MaybePromise<any | null>;
+
+    /**
+     * How many local changes to process at once.
+     */
+    batchSize?: number;
+
+    /**
+     * If set, the push replication
+     * will start from the given checkpoint.
+     */
+    initialCheckpoint?: any;
+
+    /**
+     * When a local write happens, normally the replication will directly try to persist
+     * the change upstream.
+     *
+     * By providing a function here that returns a promise, the replication will wait until
+     * that promise resolves before running the next upstream persist cycle. This can be
+     * used to batch writes across multiple collections into a single push or to defer
+     * pushing until the CPU is idle (e.g. via requestIdleCallback).
+     *
+     * NOTE: The longer you wait here, the higher the risk of losing writes if the
+     * replication is closed unexpectedly.
+     */
+    waitBeforePersist?: () => Promise<any>;
+};
+
+
+export type ReplicationOptions<RxDocType, CheckpointType> = {
+    /**
+     * An id for the replication to identify it
+     * and so that RxDB is able to resume the replication on app reload.
+     * If you replicate with a remote server, it is recommended to put the
+     * server url into the replicationIdentifier.
+     * Like 'my-rest-replication-to-https://example.com/api/sync'
+     */
+    replicationIdentifier: string;
+    collection: RxCollection<RxDocType, unknown, unknown, unknown>;
+    /**
+     * Define a custom property that is used
+     * to flag a document as being deleted.
+     * @default '_deleted'
+     */
+    deletedField?: '_deleted' | string;
+    pull?: ReplicationPullOptions<RxDocType, CheckpointType>;
+    push?: ReplicationPushOptions<RxDocType>;
+    /**
+     * By default it will do an ongoing realtime replication.
+     * By settings live: false the replication will run once until the local state
+     * is in sync with the remote state, then it will cancel itself.
+     * @default true
+     */
+    live?: boolean;
+    /**
+     * Time in milliseconds after when a failed backend request
+     * has to be retried.
+     * This time will be skipped if a offline->online switch is detected
+     * via `navigator.onLine`
+     * @default 5000
+     */
+    retryTime?: number;
+    /**
+     * When multiInstance is `true`, like when you use RxDB in multiple browser tabs,
+     * the replication should always run in only one of the open browser tabs.
+     * If waitForLeadership is `true`, it will wait until the current instance is leader.
+     * If waitForLeadership is `false`, it will start replicating, even if it is not leader.
+     * @default true
+     */
+    waitForLeadership?: boolean;
+
+    toggleOnDocumentVisible?: boolean;
+
+    /**
+     * If this is set to `false`,
+     * the replication will not start automatically
+     * but will wait for `replicationState.start()` being called.
+     * @default true
+     */
+    autoStart?: boolean;
+};

package/dist/types/types/plugins/state.d.ts

@@ -0,0 +1,4 @@
+import type { RxStateBase } from '../../plugins/state/rx-state';
+import type { ExtendObservables, ExtendReactivity } from '../rx-document';
+
+export type RxState<T, Reactivity = unknown> = RxStateBase<T, Reactivity> & T & ExtendObservables<Required<T>> & ExtendReactivity<Required<T>, Reactivity>;

package/dist/types/types/plugins/update.d.ts

@@ -0,0 +1,23 @@
+import type { AnyKeys, AnyObject } from '../util.d.ts';
+
+// import type {
+//     UpdateExpression
+// } from 'mingo/updater';
+
+/**
+ * We use an own type here, copied from mongoose
+ * @link https://github.com/Automattic/mongoose/blob/eb292d2c4cc98ee315f118d6199a83938f06d901/types/index.d.ts#L466
+ * When the mingo library implements a schema-based type for UpdateExpression, we can use these typings instead.
+ */
+export type UpdateQuery<TSchema> = {
+    $min?: AnyKeys<TSchema> & AnyObject;
+    $max?: AnyKeys<TSchema> & AnyObject;
+    $inc?: AnyKeys<TSchema> & AnyObject;
+    $set?: AnyKeys<TSchema> & AnyObject;
+    $unset?: AnyKeys<TSchema> & AnyObject;
+    $push?: AnyKeys<TSchema> & AnyObject;
+    $addToSet?: AnyKeys<TSchema> & AnyObject;
+    $pop?: AnyKeys<TSchema> & AnyObject;
+    $pullAll?: AnyKeys<TSchema> & AnyObject;
+    $rename?: Record<string, string>;
+};

package/dist/types/types/plugins/webmcp.d.ts

@@ -0,0 +1,40 @@
+import type {
+    RxDatabase,
+    RxCollection
+} from '../../index.d.ts';
+
+import type { Observable } from 'rxjs';
+
+export interface WebMCPOptions {
+    /**
+     * If true, modifier tools (insert, upsert, delete) will not be registered
+     * for this database or collection.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * If true, delays queries until all replication states of the collection
+     * are in sync.
+     * @default true
+     */
+    awaitReplicationsInSync?: boolean;
+}
+
+export interface WebMCPLogEvent {
+    collectionName: string;
+    databaseName: string;
+    toolName: string;
+    args: any;
+    result?: any;
+    error?: any;
+}
+
+export interface RxWebMCPPlugin {
+    name: 'webmcp';
+    rxdb: true;
+    prototypes: {
+        RxDatabase: (proto: any) => void;
+        RxCollection: (proto: any) => void;
+    };
+    hooks?: any;
+}

package/dist/types/types/query-planner.d.ts

@@ -0,0 +1,47 @@
+export type RxQueryPlanKey = string | number | undefined;
+
+export type RxQueryPlanerOpts = {
+    startKey: RxQueryPlanKey;
+    endKey: RxQueryPlanKey;
+    /**
+     * True if the first matching document
+     * must also be included into the result set.
+     */
+    inclusiveStart: boolean;
+    /**
+     * True if the last matching document
+     * must also be included into the result set.
+     */
+    inclusiveEnd: boolean;
+};
+
+export type RxQueryPlan = {
+    index: string[];
+    /**
+     * If the index does not match the sort params,
+     * we have to resort the query results manually
+     * after fetching them from the index.
+     */
+    sortSatisfiedByIndex: boolean;
+
+    /**
+     * If the whole selector matching is satisfied
+     * by the index, we do not have to run a does-document-data-match-query
+     * stuff.
+     */
+    selectorSatisfiedByIndex: boolean;
+
+    startKeys: RxQueryPlanKey[];
+    endKeys: RxQueryPlanKey[];
+    /**
+     * True if the first matching document
+     * must also be included into the result set.
+     */
+    inclusiveStart: boolean;
+    /**
+     * True if the last matching document
+     * must also be included into the result set.
+     */
+    inclusiveEnd: boolean;
+
+};

package/dist/types/types/replication-protocol.d.ts

@@ -0,0 +1,296 @@
+import { BehaviorSubject, Observable, Subject } from 'rxjs';
+import type {
+    RxConflictHandler,
+    RxConflictHandlerInput
+} from './conflict-handling.d.ts';
+import type { RxError, RxTypeError } from './rx-error.d.ts';
+import type {
+    BulkWriteRow,
+    RxDocumentData,
+    WithDeleted,
+    WithDeletedAndAttachments
+} from './rx-storage.d.ts';
+import type {
+    RxStorageInstance
+} from './rx-storage.interface.d.ts';
+import type { HashFunction } from './util.d.ts';
+
+export type RxStorageReplicationMeta<RxDocType, CheckpointType> = {
+
+    /**
+     * Combined primary key consisting
+     * of: [replicationId, itemId, isCheckpoint]
+     * so that the same RxStorageInstance
+     * can be used for multiple replication states.
+     */
+    id: string;
+
+    /**
+     * Either the document primaryKey
+     * or the id of the replication checkpoint.
+     */
+    itemId: string;
+
+    /**
+     * True if the doc data is about a checkpoint,
+     * False if it is about a document state from the master.
+     * Stored as a string so it can be used
+     * in the combined primary key 'id'
+     */
+    isCheckpoint: '0' | '1';
+    checkpointData?: CheckpointType;
+
+    /**
+     * the document state of the master
+     * only set if not checkpoint.
+     */
+    docData?: RxDocType | RxDocumentData<RxDocType> | any;
+    /**
+     * If the current assumed master was written while
+     * resolving a conflict, this field contains
+     * the revision of the conflict-solution that
+     * is stored in the forkInstance.
+     */
+    isResolvedConflict?: string;
+};
+
+export type RxReplicationWriteToMasterRow<RxDocType> = {
+    assumedMasterState?: WithDeletedAndAttachments<RxDocType>;
+    newDocumentState: WithDeletedAndAttachments<RxDocType>;
+};
+
+
+export type DocumentsWithCheckpoint<RxDocType, CheckpointType> = {
+    documents: WithDeletedAndAttachments<RxDocType>[];
+    checkpoint: CheckpointType;
+};
+
+
+export type RxReplicationPullStreamItem<RxDocType, MasterCheckpointType> = DocumentsWithCheckpoint<RxDocType, MasterCheckpointType> |
+    /**
+         * Emit this when the masterChangeStream$ might have missed out
+         * some events because the fork lost the connection to the master.
+         * Like when the user went offline and reconnects.
+         */
+    'RESYNC';
+
+/**
+ * The replication handler contains all logic
+ * that is required by the replication protocol
+ * to interact with the master instance.
+ * This is an abstraction so that we can use different
+ * handlers for GraphQL, REST or any other transportation layer.
+ * Even a RxStorageInstance can be wrapped in a way to represent a replication handler.
+ *
+ * The RxStorage instance of the master branch that is
+ * replicated with the fork branch.
+ * The replication algorithm is made to make
+ * as less writes on the master as possible.
+ * The master instance is always 'the truth' which
+ * does never contain conflicting document states.
+ * All conflicts are handled on the fork branch
+ * before being replicated to the master.
+ */
+export type RxReplicationHandler<RxDocType, MasterCheckpointType> = {
+    masterChangeStream$: Observable<RxReplicationPullStreamItem<RxDocType, MasterCheckpointType>>;
+    masterChangesSince(
+        checkpoint: MasterCheckpointType | undefined,
+        batchSize: number
+    ): Promise<DocumentsWithCheckpoint<RxDocType, MasterCheckpointType | undefined>>;
+    /**
+     * Writes the fork changes to the master.
+     * Only returns the conflicts if there are any.
+     * (otherwise returns an empty array.)
+     */
+    masterWrite(
+        rows: RxReplicationWriteToMasterRow<RxDocType>[]
+    ): Promise<WithDeleted<RxDocType>[]>;
+};
+
+export type RxStorageInstanceReplicationInput<RxDocType> = {
+    /**
+     * A string that uniquely identifies
+     * the replication.
+     * Ensures that checkpoint are not
+     * mixed with other replications.
+     */
+    identifier: string;
+    pullBatchSize: number;
+    pushBatchSize: number;
+    replicationHandler: RxReplicationHandler<RxDocType, any>;
+    conflictHandler: RxConflictHandler<RxDocType>;
+
+    // can be set to also replicate the _meta field of the document.
+    keepMeta?: boolean;
+
+    /**
+     * The fork is the one that contains the forked chain of document writes.
+     * All conflicts are solved on the fork and only resolved correct document data
+     * is written back to the parent.
+     */
+    forkInstance: RxStorageInstance<RxDocType, any, any>;
+
+    /**
+     * The replication needs to store some meta data
+     * for documents to know which state is at the master
+     * and how/if it diverges from the fork.
+     * In the past this was stored in the _meta field of
+     * the forkInstance documents but that was not a good design decision
+     * because it required additional writes on the forkInstance
+     * to know which documents have been upstream replicated
+     * to not cause conflicts.
+     * Using the metaInstance instead leads to better overall performance
+     * because RxDB will not re-emit query results or document state
+     * when replication meta data is written.
+     *
+     * In addition to per-document meta data,
+     * the replication checkpoints are also stored in this instance.
+     *
+     */
+    metaInstance: RxStorageInstance<RxStorageReplicationMeta<RxDocType, any>, any, any>;
+
+    /**
+     * When a write happens to the fork,
+     * normally the replication will directly try to persist.
+     *
+     * For many use cases, it is better to await the next event loop tick
+     * or to wait until the RxDatabase is idle or requestIdleCallback() calls
+     * to ensure the CPU is idle.
+     * This can improve performance because the persistence will not affect UI
+     * renders.
+     *
+     * But: The longer you wait here, the higher is the risk of losing fork
+     * writes when the replication is closed unexpected.
+     */
+    waitBeforePersist?: () => Promise<any>;
+
+    hashFunction: HashFunction;
+    skipStoringPullMeta: boolean;
+
+    initialCheckpoint?: {
+        upstream?: any;
+        downstream?: any;
+    };
+};
+
+export type RxStorageInstanceReplicationState<RxDocType> = {
+    // store the primaryPath here for better reuse and performance.
+    primaryPath: string;
+    hasAttachments: boolean;
+    input: RxStorageInstanceReplicationInput<RxDocType>;
+    events: {
+        /**
+         * Streams all document writes that have successfully
+         * been written in one direction.
+         */
+        processed: {
+            up: Subject<RxReplicationWriteToMasterRow<RxDocType>>;
+            down: Subject<BulkWriteRow<RxDocType>>;
+        };
+        resolvedConflicts: Subject<{
+            input: RxConflictHandlerInput<RxDocType>;
+            output: WithDeleted<RxDocType>;
+        }>;
+        /**
+         * Contains the cancel state.
+         * Emit true here to cancel the replication.
+         */
+        canceled: BehaviorSubject<boolean>;
+        /**
+         * Contains the pause state.
+         * Emit true here to pause the replication.
+         */
+        paused: BehaviorSubject<boolean>;
+        /**
+         * Contains true if the replication is doing something
+         * at this point in time.
+         * If this is false, it means that the replication
+         * is idle AND in sync.
+         */
+        active: {
+            [direction in RxStorageReplicationDirection]: BehaviorSubject<boolean>;
+        };
+        /**
+         * All errors that would otherwise be unhandled,
+         * get emitted here.
+         */
+        error: Subject<RxError | RxTypeError>;
+    };
+
+
+    /**
+     * Contains counters that can be used in tests
+     * or to debug problems.
+     */
+    stats: {
+        down: {
+            addNewTask: number;
+            downstreamResyncOnce: number;
+            downstreamProcessChanges: number;
+            masterChangeStreamEmit: number;
+            persistFromMaster: number;
+        };
+        up: {
+            upstreamInitialSync: number;
+            forkChangeStreamEmit: number;
+            processTasks: number;
+            persistToMaster: number;
+            persistToMasterHadConflicts: number;
+            persistToMasterConflictWrites: number;
+        };
+    };
+
+    /**
+     * Used in checkpoints and ._meta fields
+     * to ensure we do not mix up meta data of
+     * different replications.
+     * We have to use the promise because the key is hashed which runs async.
+     */
+    checkpointKey: Promise<string>;
+
+    /**
+     * Storage.bulkWrites() that are initialized from the
+     * downstream, get this flag as context-param
+     * so that the emitted event bulk can be identified
+     * to be sourced from the downstream and it will not try
+     * to upstream these documents again.
+     */
+    downstreamBulkWriteFlag: Promise<string>;
+
+    /**
+     * If this is set to true, we do not store the documents
+     * assumed server state. This is set on pull-only replications
+     * we because when we do not push anyway, we do not have to store
+     * the server state of any document.
+     */
+    skipStoringPullMeta: boolean;
+
+    /**
+     * Tracks if the streams have been in sync
+     * for at least one time.
+     */
+    firstSyncDone: {
+        [direction in RxStorageReplicationDirection]: BehaviorSubject<boolean>;
+    };
+
+    /**
+     * Can be used to detect if the replication is doing something
+     * or if it is in an idle state.
+     */
+    streamQueue: {
+        [direction in RxStorageReplicationDirection]: Promise<any>;
+    };
+
+    checkpointQueue: Promise<any>;
+
+    /**
+     * For better performance we store the last known checkpoint
+     * document so that we can likely do checkpoint storing without
+     * conflicts.
+     */
+    lastCheckpointDoc: {
+        [direction in RxStorageReplicationDirection]?: RxDocumentData<RxStorageReplicationMeta<RxDocType, any>>;
+    };
+};
+
+export type RxStorageReplicationDirection = 'up' | 'down';