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

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

import { App, ClientResetAfterCallback, ClientResetBeforeCallback, ClientResetFallbackCallback, ClientResetMode, ErrorCallback, Realm, SessionStopPolicy, SyncConfiguration, binding } from "../internal";
export declare enum ProgressDirection {
    /**
     * Data going from the server to the client.
     */
    Download = "download",
    /**
     * Data going from the client to the server.
     */
    Upload = "upload"
}
export declare enum ProgressMode {
    ReportIndefinitely = "reportIndefinitely",
    ForCurrentlyOutstandingWork = "forCurrentlyOutstandingWork"
}
export type ProgressNotificationCallback = 
/**
 * @param transferred - The current number of bytes already transferred
 * @param transferable - The total number of transferable bytes (i.e. the number of bytes already transferred plus the number of bytes pending transfer)
 */
(transferred: number, transferable: number) => void;
export declare enum ConnectionState {
    Disconnected = "disconnected",
    Connecting = "connecting",
    Connected = "connected"
}
export type ConnectionNotificationCallback = (newState: ConnectionState, oldState: ConnectionState) => void;
export declare enum SessionState {
    /**
     * The sync session encountered a non-recoverable error and is permanently invalid. Create a new Session to continue syncing.
     */
    Invalid = "invalid",
    /**
     * The sync session is actively communicating or attempting to communicate with Atlas App Services. A session may be considered active even if it is not currently connected. To find out if a session is online, check its connection state.
     */
    Active = "active",
    /**
     * The sync session is not attempting to communicate with Atlas App Services due to the user logging out or synchronization being paused.
     */
    Inactive = "inactive"
}
/** @internal */
export declare function toBindingErrorHandler(onError: ErrorCallback): (sessionInternal: binding.SyncSession, bindingError: binding.SyncError) => void;
/** @internal */
export declare function toBindingErrorHandlerWithOnManual(onError: ErrorCallback | undefined, onManual: ClientResetFallbackCallback | undefined): ((sessionInternal: binding.SyncSession, bindingError: binding.SyncError) => void) | undefined;
/** @internal */
export declare function toBindingNotifyBeforeClientReset(onBefore: ClientResetBeforeCallback): (internal: binding.Realm) => void;
/** @internal */
export declare function toBindingNotifyAfterClientReset(onAfter: ClientResetAfterCallback): (internal: binding.Realm, tsr: binding.ThreadSafeReference) => void;
/** @internal */
export declare function toBindingNotifyAfterClientResetWithFallback(onAfter: ClientResetAfterCallback, onFallback: ClientResetFallbackCallback | undefined): (internal: binding.Realm, tsr: binding.ThreadSafeReference, didRecover: boolean) => void;
/** @internal */
export declare function toBindingStopPolicy(policy: SessionStopPolicy): binding.SyncSessionStopPolicy;
/** @internal */
export declare function toBindingClientResetMode(resetMode: ClientResetMode): binding.ClientResetMode;
export declare class SyncSession {
    /** @internal */
    private weakInternal;
    /** @internal */
    withInternal<Ret = void>(cb: (syncSession: binding.SyncSession) => Ret): Ret;
    /** @internal */
    constructor(internal: binding.SyncSession);
    /**
     * Gets the Sync-part of the configuration that the corresponding Realm was constructed with.
     */
    get config(): SyncConfiguration;
    /**
     * Gets the current state of the session.
     */
    get state(): SessionState;
    /**
     * Gets the URL of the Realm Object Server that this session is connected to.
     */
    get url(): string;
    /**
     * Gets the User that this session was created with.
     */
    get user(): Realm.User<Realm.DefaultFunctionsFactory, import("../internal").DefaultObject, Realm.DefaultUserProfileData>;
    /**
     * Gets the current state of the connection to the server. Multiple sessions might share the same underlying
     * connection. In that case, any connection change is sent to all sessions.
     *
     * Data will only be synchronized with the server if this method returns `Connected` and `state()` returns `Active` or `Dying`.
     */
    get connectionState(): App.Sync.ConnectionState;
    /**
     * Returns `true` if the session is currently active and connected to the server, `false` if not.
     */
    isConnected(): boolean;
    /**
     * Pause a sync session.
     *
     * This method is asynchronous so in order to know when the session has started you will need
     * to add a connection notification with {@link addConnectionNotification}.
     *
     * This method is idempotent so it will be a no-op if the session is already paused or if multiplexing
     * is enabled.
     * @since 2.16.0-rc.2
     */
    pause(): void;
    /**
     * Resumes a sync session that has been paused.
     *
     * This method is asynchronous so in order to know when the session has started you will need
     * to add a connection notification with {@link addConnectionNotification}.
     *
     * This method is idempotent so it will be a no-op if the session is already started or if multiplexing
     * is enabled.
     * @since 2.16.0-rc.2
     */
    resume(): void;
    /**
     * Reconnects to Altas Device Sync.
     *
     * This method is asynchronous so in order to know when the session has started you will need
     * to add a connection notification with {@link addConnectionNotification}.
     *
     * This method is idempotent so it will be a no-op if the session is already started.
     * @since 12.2.0
     */
    reconnect(): void;
    /**
     * Register a progress notification callback on a session object
     * @param direction - The progress direction to register for.
     * @param mode - The progress notification mode to use for the registration.
     * Can be either:
     *  - `reportIndefinitely` - the registration will stay active until the callback is unregistered
     *  - `forCurrentlyOutstandingWork` - the registration will be active until only the currently transferable bytes are synced
     * @param callback - Called with the following arguments:
     * 1. `transferred`: The current number of bytes already transferred
     * 2. `transferable`: The total number of transferable bytes (the number of bytes already transferred plus the number of bytes pending transfer)
     * @since 1.12.0
     */
    addProgressNotification(direction: ProgressDirection, mode: ProgressMode, callback: ProgressNotificationCallback): void;
    /**
     * Unregister a progress notification callback that was previously registered with {@link addProgressNotification}.
     * Calling the function multiple times with the same callback is ignored.
     * @param callback - A previously registered progress callback.
     * @since 1.12.0
     */
    removeProgressNotification(callback: ProgressNotificationCallback): void;
    /**
     * Registers a connection notification on the session object. This will be notified about changes to the
     * underlying connection to the Realm Object Server.
     * @param callback - Called with the following arguments:
     * 1. `newState`: The new state of the connection
     * 2. `oldState`: The state the connection transitioned from.
     * @since 2.15.0
     */
    addConnectionNotification(callback: ConnectionNotificationCallback): void;
    /**
     * Unregister a state notification callback that was previously registered with addStateNotification.
     * Calling the function multiple times with the same callback is ignored.
     * @param callback - A previously registered state callback.
     * @since 2.15.0
     */
    removeConnectionNotification(callback: ConnectionNotificationCallback): void;
    /**
     * This method returns a promise that does not resolve successfully until all known remote changes have been
     * downloaded and applied to the Realm or the specified timeout is hit in which case it will be rejected. If the method
     * times out, the download will still continue in the background.
     *
     * This method cannot be called before the Realm has been opened.
     * @param timeoutMs - maximum amount of time to wait in milliseconds before the promise will be rejected. If no timeout
     * is specified the method will wait forever.
     */
    downloadAllServerChanges(timeoutMs?: number): Promise<void>;
    /**
     * This method returns a promise that does not resolve successfully until all known local changes have been uploaded
     * to the server or the specified timeout is hit in which case it will be rejected. If the method times out, the upload
     * will still continue in the background.
     *
     * This method cannot be called before the Realm has been opened.
     * @param timeoutMs - Maximum amount of time to wait in milliseconds before the promise is rejected. If no timeout is specified the method will wait forever.
     */
    uploadAllLocalChanges(timeoutMs?: number): Promise<void>;
    /** @internal */
    _simulateError(code: number, message: string, type: string, isFatal: boolean): void;
}