realm/dist/app-services/SyncConfiguration.d.ts

Realm by MongoDB is an offline-first mobile database: an alternative to SQLite and key-value stores

import { AnyUser, BSON, ClientResetError, MutableSubscriptionSet, Realm, SyncError, SyncSession, binding } from "../internal";
export type PartitionValue = string | number | BSON.ObjectId | BSON.UUID | null;
export declare enum OpenRealmBehaviorType {
    DownloadBeforeOpen = "downloadBeforeOpen",
    OpenImmediately = "openImmediately"
}
export declare enum OpenRealmTimeOutBehavior {
    OpenLocalRealm = "openLocalRealm",
    ThrowException = "throwException"
}
export type OpenRealmBehaviorConfiguration = {
    type: OpenRealmBehaviorType;
    timeOut?: number;
    timeOutBehavior?: OpenRealmTimeOutBehavior;
};
export type ErrorCallback = (session: SyncSession, error: SyncError | ClientResetError) => void;
export type ClientResetFallbackCallback = (session: SyncSession, path: string) => void;
export type ClientResetBeforeCallback = (localRealm: Realm) => void;
export type ClientResetAfterCallback = (localRealm: Realm, remoteRealm: Realm) => void;
export declare enum SessionStopPolicy {
    AfterUpload = "after-upload",
    Immediately = "immediately",
    Never = "never"
}
/**
 */
export declare enum ClientResetMode {
    /** @deprecated See {@link Realm.App.Sync.initiateClientReset} */
    Manual = "manual",
    /**
     * Download a fresh copy from the server.
     */
    DiscardUnsyncedChanges = "discardUnsyncedChanges",
    /**
     * Merged remote and local, unsynced changes.
     */
    RecoverUnsyncedChanges = "recoverUnsyncedChanges",
    /**
     * Download a fresh copy from the server if recovery of unsynced changes is not possible.
     */
    RecoverOrDiscardUnsyncedChanges = "recoverOrDiscardUnsyncedChanges"
}
export type ClientResetManualConfiguration = {
    mode: ClientResetMode.Manual;
    onManual?: ClientResetFallbackCallback;
};
export type ClientResetDiscardUnsyncedChangesConfiguration = {
    mode: ClientResetMode.DiscardUnsyncedChanges;
    onAfter?: ClientResetAfterCallback;
    /**
     * Called before sync initiates a client reset.
     */
    onBefore?: ClientResetBeforeCallback;
};
export type ClientResetRecoverUnsyncedChangesConfiguration = {
    mode: ClientResetMode.RecoverUnsyncedChanges;
    onAfter?: ClientResetAfterCallback;
    /**
     * Called before sync initiates a client reset.
     */
    onBefore?: ClientResetBeforeCallback;
    /**
     * Called if recovery or discard fail.
     */
    onFallback?: ClientResetFallbackCallback;
};
export type ClientResetRecoverOrDiscardUnsyncedChangesConfiguration = {
    mode: ClientResetMode.RecoverOrDiscardUnsyncedChanges;
    onAfter?: ClientResetAfterCallback;
    /**
     * Called before sync initiates a client reset.
     */
    onBefore?: ClientResetBeforeCallback;
    /**
     * Called if recovery or discard fail.
     */
    onFallback?: ClientResetFallbackCallback;
};
export type ClientResetConfig = ClientResetManualConfiguration | ClientResetDiscardUnsyncedChangesConfiguration | ClientResetRecoverUnsyncedChangesConfiguration | ClientResetRecoverOrDiscardUnsyncedChangesConfiguration;
export type SSLConfiguration = {
    /**
     * Whether the SSL certificates must be validated. This should generally
     * be `true` in production.
     *
     * Default is `true`.
     */
    validate?: boolean;
    /**
     * The path where to find trusted SSL certificates used to validate the
     * server certificate. If `undefined`, validation will be delegated to
     * the provided `validateCertificates` callback.
     */
    certificatePath?: string;
    /**
     * A callback function used to validate the server's SSL certificate. It
     * is invoked for every certificate in the certificate chain starting from
     * the root downward. An SSL connection will be established if all certificates
     * are accepted. The certificate will be accepted if the callback returns `true`,
     * or rejected if returning `false`. This callback is only invoked if
     * `certificatePath` is `undefined`.
     */
    validateCertificates?: SSLVerifyCallback;
};
export type SSLVerifyCallback = (sslVerifyObject: SSLVerifyObject) => boolean;
export type SSLVerifyObject = {
    /**
     * The address that the SSL connection is being established to.
     */
    serverAddress: string;
    /**
     * The port that the SSL connection is being established to.
     */
    serverPort: number;
    /**
     * The certificate using the PEM format.
     */
    pemCertificate: string;
    /**
     * The result of OpenSSL's pre-verification of the certificate. If `true`,
     * the certificate has been accepted and will generally be safe to trust.
     * If `false`, it has been rejected and the user should do an independent
     * validation step.
     */
    acceptedByOpenSSL: boolean;
    /**
     * The position of the certificate in the certificate chain. The actual
     * server certificate has `depth` 0 (lowest) and also contains the host
     * name, while all other certificates up the chain have higher depths in
     * increments of 1.
     */
    depth: number;
};
export declare enum ProxyType {
    HTTP = "http",
    HTTPS = "https"
}
export type SyncProxyConfig = {
    address: string;
    port: number;
    type: ProxyType;
};
/**
 * This describes the different options used to create a {@link Realm} instance with Atlas App Services synchronization.
 */
export type BaseSyncConfiguration = {
    /**
     * A {@link Realm.User} object obtained by calling `Realm.App.logIn`.
     */
    user: AnyUser;
    /**
     * Whether to create a new file and sync in background or wait for the file to be synced.
     * @default
     * {
     *   type: OpenRealmBehaviorType.DownloadBeforeOpen,
     *   timeOut: 30 * 1000,
     *   timeOutBehavior: OpenRealmTimeOutBehavior.ThrowException,
     * }
     */
    newRealmFileBehavior?: OpenRealmBehaviorConfiguration;
    /**
     * Whether to open existing file and sync in background or wait for the sync of the file to complete and then open.
     * If not set, the Realm will be downloaded before opened.
     * @default
     * {
     *   type: OpenRealmBehaviorType.DownloadBeforeOpen,
     *   timeOut: 30 * 1000,
     *   timeOutBehavior: OpenRealmTimeOutBehavior.ThrowException,
     * }
     */
    existingRealmFileBehavior?: OpenRealmBehaviorConfiguration;
    /**
     * A callback function which is called in error situations.
     * The callback is passed two arguments: `session` and `syncError`.
     * If `syncError.name == "ClientReset"`, `syncError.path` and `syncError.config` are set and `syncError.readOnly` is true (deprecated, see `Realm.App.Sync~ClientResetConfiguration`).
     * Otherwise, `syncError` can have up to five properties: `name`, `message`, `isFatal`, `category`, and `code`.
     */
    onError?: ErrorCallback;
    /**
     * Custom HTTP headers, which are included when making requests to the server.
     */
    customHttpHeaders?: Record<string, string>;
    /**
     * SSL configuration.
     */
    ssl?: SSLConfiguration;
    /**
     * Configuration of Client Reset
     */
    clientReset?: ClientResetConfig;
    /**
     * Set to true, all async operations (such as opening the Realm with `Realm.open`) will fail when a non-fatal error, such as a timeout, occurs.
     */
    cancelWaitsOnNonFatalError?: boolean;
    /** @internal */
    _sessionStopPolicy?: SessionStopPolicy;
    /**
     * HTTP proxy configuration (node.js/Electron only)
     */
    proxyConfig?: SyncProxyConfig;
};
export type InitialSubscriptions = {
    /**
     * A callback to make changes to a SubscriptionSet.
     * @see {@link SubscriptionSet.update} for more information.
     */
    update: (mutableSubscriptions: MutableSubscriptionSet, realm: Realm) => void;
    /**
     * If `true`, the {@link InitialSubscriptions.update} callback will be rerun every time the Realm is
     * opened (e.g. every time a user opens your app), otherwise (by default) it
     * will only be run if the Realm does not yet exist.
     */
    rerunOnOpen?: boolean;
};
export type FlexibleSyncConfiguration = BaseSyncConfiguration & {
    flexible: true;
    partitionValue?: never;
    /**
     * Optional object to configure the setup of an initial set of flexible
     * sync subscriptions to be used when opening the Realm. If this is specified,
     * {@link Realm.open} will not resolve until this set of subscriptions has been
     * fully synchronized with the server.
     * @example
     * const config: Realm.Configuration = {
     *   sync: {
     *     user,
     *     flexible: true,
     *     initialSubscriptions: {
     *       update: (subs, realm) => {
     *         subs.add(realm.objects('Task'));
     *       },
     *       rerunOnOpen: true,
     *     },
     *   },
     *   // ... rest of config ...
     * };
     * const realm = await Realm.open(config);
     *
     * // At this point, the Realm will be open with the data for the initial set
     * // subscriptions fully synchronised.
     */
    initialSubscriptions?: InitialSubscriptions;
};
export type PartitionSyncConfiguration = BaseSyncConfiguration & {
    flexible?: never;
    partitionValue: PartitionValue;
    initialSubscriptions?: never;
};
export type SyncConfiguration = FlexibleSyncConfiguration | PartitionSyncConfiguration;
/** @internal */
export declare function toBindingSyncConfig(config: SyncConfiguration): binding.SyncConfig_Relaxed;
/**
 * Validate the fields of a user-provided realm sync configuration.
 * @internal
 */
export declare function validateSyncConfiguration(config: unknown): asserts config is SyncConfiguration;