diff --git a/packages/realm/src/Collection.ts b/packages/realm/src/Collection.ts index 92e05dea4c4..9a6bcd55a6e 100644 --- a/packages/realm/src/Collection.ts +++ b/packages/realm/src/Collection.ts @@ -107,12 +107,6 @@ export abstract class Collection< /** * Add a listener `callback` which will be called when a **live** collection instance changes. * @param callback - A function to be called when changes occur. - * @param callback.collection - The collection instance that changed, - * @param callback.changes - An object with information about the changes. - * @param callback.changes.insertions - The indices in the collection where objects were inserted. - * @param callback.changes.newModifications - The indices in the collection where objects were modified. - * @param callback.changes.oldModifications - The indices in the collection where objects were modified. - * @param callback.changes.deletions - The indices in the collection where objects were deleted. * @param keyPaths - Indicates a lower bound on the changes relevant for the listener. This is a lower bound, since if multiple listeners are added (each with their own `keyPaths`) the union of these key-paths will determine the changes that are considered relevant for all listeners registered on the collection. In other words: A listener might fire more than the key-paths specify, if other listeners with different key-paths are present. * @note `deletions and `oldModifications` report the indices in the collection before the change happened, * while `insertions` and `newModifications` report the indices into the new version of the collection. diff --git a/packages/realm/src/Configuration.ts b/packages/realm/src/Configuration.ts index 096648bba0d..55bc7c0fa2d 100644 --- a/packages/realm/src/Configuration.ts +++ b/packages/realm/src/Configuration.ts @@ -16,18 +16,18 @@ // //////////////////////////////////////////////////////////////////////////// -import { +import type { AnyRealmObject, + AppConfiguration, ObjectSchema, Realm, RealmObjectConstructor, SyncConfiguration, - TypeAssertionError, - assert, - validateRealmSchema, - validateSyncConfiguration, + User, } from "./internal"; +import { TypeAssertionError, assert, validateRealmSchema, validateSyncConfiguration } from "./internal"; + /** * A function which can be called to migrate a Realm from one version of the schema to another. */ @@ -55,7 +55,7 @@ export type MigrationOptions = { export type BaseConfiguration = { /** * The path to the file where the Realm database should be stored. For synced Realms, a relative path - * is used together with the {@link AppConfiguration.id | app ID} and {@link User.id | user ID} in order + * is used together with the {@link AppConfiguration} and {@link User.id} in order * to avoid collisions with other apps or users. * An absolute path is left untouched and on some platforms (iOS and Android) the app might not have * permissions to create or open the file - permissions are not validated. diff --git a/packages/realm/src/Object.ts b/packages/realm/src/Object.ts index 958342b100a..51135039f5b 100644 --- a/packages/realm/src/Object.ts +++ b/packages/realm/src/Object.ts @@ -488,10 +488,6 @@ export class RealmObject = { deleted: boolean; changedProperties: (keyof T)[] }; -export type ObjectChangeCallback = (object: RealmObject & T, changes: ObjectChangeSet) => void; +export type ObjectChangeSet = { + /** + * Is `true` if the object has been deleted. + */ + deleted: boolean; + /** + * An array of properties that have changed their value. + */ + changedProperties: (keyof T)[]; +}; + +export type ObjectChangeCallback = ( + /** + * The object that changed. + */ object: RealmObject & T, + /** + * A dictionary with information about the changes. + */ + changes: ObjectChangeSet, +) => void; /** @internal */ export class ObjectListeners { diff --git a/packages/realm/src/OrderedCollection.ts b/packages/realm/src/OrderedCollection.ts index 5eb60e4dfe2..a604345277e 100644 --- a/packages/realm/src/OrderedCollection.ts +++ b/packages/realm/src/OrderedCollection.ts @@ -46,13 +46,32 @@ type PropertyType = string; export type SortDescriptor = string | [string, boolean]; export type CollectionChangeSet = { + /** + * The indices in the collection where objects were inserted. + */ insertions: number[]; + /** + * The indices in the collection where objects were modified. + */ deletions: number[]; + /** + * The indices in the collection where objects were modified. + */ newModifications: number[]; + /** + * The indices in the collection where objects were deleted. + */ oldModifications: number[]; }; + export type CollectionChangeCallback = ( + /** + * The collection instance that changed, + */ collection: OrderedCollection, + /** + * An object with information about the changes. + */ changes: CollectionChangeSet, ) => void; diff --git a/packages/realm/src/Realm.ts b/packages/realm/src/Realm.ts index 4d02674f107..c07e25601a8 100644 --- a/packages/realm/src/Realm.ts +++ b/packages/realm/src/Realm.ts @@ -171,10 +171,18 @@ export class Realm { /** * Checks if the Realm already exists on disk. - * @param arg - The configuration for the Realm or the path to it. + * @param path - The path for a Realm. + * @throws An {@link Error} if anything in the provided {@link path} is invalid. + * @returns `true` if the Realm exists on the device, `false` if not. + */ + public static exists(path: string): boolean; + /** + * Checks if the Realm already exists on disk. + * @param config - The configuration of a Realm. * @throws An {@link Error} if anything in the provided {@link config} is invalid. * @returns `true` if the Realm exists on the device, `false` if not. */ + public static exists(config: Configuration): boolean; public static exists(arg: Configuration | string = {}): boolean { const config = typeof arg === "string" ? { path: arg } : arg; validateConfiguration(config); @@ -182,15 +190,31 @@ export class Realm { return fs.exists(path); } + /** + * Open the default Realm asynchronously with a promise. + * @returns A promise that will be resolved with the Realm instance when it's available. + */ + public static open(): ProgressRealmPromise; + + /** + * Open a Realm asynchronously with a promise. If the Realm is synced, it will be fully + * synchronized before it is available. + * @param path - The path for the Realm. + * @returns A promise that will be resolved with the Realm instance when it's available. + */ + public static open(path: string): ProgressRealmPromise; + /** * Open a Realm asynchronously with a promise. If the Realm is synced, it will be fully * synchronized before it is available. - * In the case of query-based sync, {@link Configuration.scheme | config.schema} is required. An exception will be - * thrown if {@link Configuration.scheme | config.schema} is not defined. - * @param arg - The configuration for the Realm or the path to it. + * In the case of query-based sync, {@link Configuration.schema} is required. An exception will be + * thrown if {@link Configuration.schema} is not defined. + * @param config - The configuration for the Realm. * @returns A promise that will be resolved with the Realm instance when it's available. - * @throws An {@link Error} if anything in the provided {@link arg} is invalid. + * @throws An {@link Error} if anything in the provided {@link config} is invalid. */ + public static open(config: Configuration): ProgressRealmPromise; + public static open(arg: Configuration | string = {}): ProgressRealmPromise { const config = typeof arg === "string" ? { path: arg } : arg; return new ProgressRealmPromise(config); @@ -905,9 +929,6 @@ export class Realm { * @param callback - Function to be called when a change event occurs. * Each callback will only be called once per event, regardless of the number of times * it was added. - * @param callback.realm - The Realm in which the change event occurred. - * @param callback.name - The name of the event that occurred. - * @param callback.schema - The schema of the Realm file when the event occurred. * @throws An {@link Error} if an invalid event {@link eventName} is supplied, if Realm is closed or if {@link callback} is not a function. */ addListener(eventName: RealmEventName, callback: RealmListenerCallback): void { @@ -1162,33 +1183,43 @@ export namespace Realm { export import kmToRadians = internal.kmToRadians; export import miToRadians = internal.miToRadians; + export import AnyCollection = internal.AnyCollection; + export import AnyDictionary = internal.AnyDictionary; + export import AnyList = internal.AnyList; + export import AnyRealmObject = internal.AnyRealmObject; + export import AnyResults = internal.AnyResults; + export import AnyUser = internal.AnyUser; + export import ApiKey = internal.ApiKey; export import AppChangeCallback = internal.AppChangeCallback; + export import AssertionError = internal.AssertionError; export import AppConfiguration = internal.AppConfiguration; export import AppServicesFunction = internal.AppServicesFunction; export import BaseConfiguration = internal.BaseConfiguration; export import BaseObjectSchema = internal.BaseObjectSchema; export import BaseSyncConfiguration = internal.BaseSyncConfiguration; + export import CanonicalGeoPoint = internal.CanonicalGeoPoint; + export import CanonicalGeoPolygon = internal.CanonicalGeoPolygon; export import CanonicalObjectSchema = internal.CanonicalObjectSchema; - export import CanonicalPropertySchema = internal.CanonicalPropertySchema; export import CanonicalPropertiesTypes = internal.CanonicalPropertiesTypes; - export import ClientResetMode = internal.ClientResetMode; - export import ClientResetFallbackCallback = internal.ClientResetFallbackCallback; - export import ClientResetBeforeCallback = internal.ClientResetBeforeCallback; + export import CanonicalPropertySchema = internal.CanonicalPropertySchema; export import ClientResetAfterCallback = internal.ClientResetAfterCallback; - export import ClientResetManualConfiguration = internal.ClientResetManualConfiguration; + export import ClientResetBeforeCallback = internal.ClientResetBeforeCallback; + export import ClientResetConfig = internal.ClientResetConfig; export import ClientResetDiscardUnsyncedChangesConfiguration = internal.ClientResetDiscardUnsyncedChangesConfiguration; - export import ClientResetRecoverUnsyncedChangesConfiguration = internal.ClientResetRecoverUnsyncedChangesConfiguration; + export import ClientResetFallbackCallback = internal.ClientResetFallbackCallback; + export import ClientResetManualConfiguration = internal.ClientResetManualConfiguration; + export import ClientResetMode = internal.ClientResetMode; export import ClientResetRecoverOrDiscardUnsyncedChangesConfiguration = internal.ClientResetRecoverOrDiscardUnsyncedChangesConfiguration; - export import ClientResetConfig = internal.ClientResetConfig; + export import ClientResetRecoverUnsyncedChangesConfiguration = internal.ClientResetRecoverUnsyncedChangesConfiguration; + export import Collection = internal.Collection; export import CollectionChangeCallback = internal.CollectionChangeCallback; export import CollectionChangeSet = internal.CollectionChangeSet; export import CollectionPropertyTypeName = internal.CollectionPropertyTypeName; - export import Collection = internal.Collection; export import CompensatingWriteError = internal.CompensatingWriteError; export import CompensatingWriteInfo = internal.CompensatingWriteInfo; + export import Configuration = internal.Configuration; export import ConfigurationWithoutSync = internal.ConfigurationWithoutSync; export import ConfigurationWithSync = internal.ConfigurationWithSync; - export import Configuration = internal.Configuration; export import ConnectionNotificationCallback = internal.ConnectionNotificationCallback; export import ConnectionState = internal.ConnectionState; export import Credentials = internal.Credentials; @@ -1199,14 +1230,26 @@ export namespace Realm { export import DictionaryChangeSet = internal.DictionaryChangeSet; export import ErrorCallback = internal.ErrorCallback; export import FlexibleSyncConfiguration = internal.FlexibleSyncConfiguration; + export import GeoBox = internal.GeoBox; + export import GeoCircle = internal.GeoCircle; + export import GeoPoint = internal.GeoPoint; + export import GeoPolygon = internal.GeoPolygon; + export import GeoPosition = internal.GeoPosition; export import IndexDecorator = internal.IndexDecorator; + export import IndexedType = internal.IndexedType; + export import InitialSubscriptions = internal.InitialSubscriptions; export import List = internal.List; export import LocalAppConfiguration = internal.LocalAppConfiguration; + export import Logger = internal.Logger; + export import LoggerCallback = internal.LoggerCallback; export import MapToDecorator = internal.MapToDecorator; - export import MetadataMode = internal.MetadataMode; export import Metadata = internal.Metadata; + export import MetadataMode = internal.MetadataMode; export import MigrationCallback = internal.MigrationCallback; + export import MigrationOptions = internal.MigrationOptions; export import Mixed = internal.Types.Mixed; + export import MongoDB = internal.MongoDB; + export import MongoDBService = internal.MongoDBService; export import NumericLogLevel = internal.NumericLogLevel; export import ObjectChangeCallback = internal.ObjectChangeCallback; export import ObjectChangeSet = internal.ObjectChangeSet; @@ -1222,6 +1265,7 @@ export namespace Realm { export import ProgressDirection = internal.ProgressDirection; export import ProgressMode = internal.ProgressMode; export import ProgressNotificationCallback = internal.ProgressNotificationCallback; + export import ProgressRealmPromise = internal.ProgressRealmPromise; export import PropertiesTypes = internal.PropertiesTypes; export import PropertySchema = internal.PropertySchema; export import PropertySchemaParseError = internal.PropertySchemaParseError; @@ -1230,11 +1274,14 @@ export namespace Realm { export import PropertyTypeName = internal.PropertyTypeName; export import ProviderType = internal.ProviderType; export import ProxyType = internal.ProxyType; + export import RealmEvent = internal.RealmEvent; export import RealmEventName = internal.RealmEventName; + export import RealmListenerCallback = internal.RealmListenerCallback; export import RealmObjectConstructor = internal.RealmObjectConstructor; export import RelationshipPropertyTypeName = internal.RelationshipPropertyTypeName; export import Results = internal.Results; export import SchemaParseError = internal.SchemaParseError; + export import SecretApiKey = internal.SecretApiKey; export import SessionState = internal.SessionState; export import SessionStopPolicy = internal.SessionStopPolicy; export import Set = internal.RealmSet; @@ -1245,18 +1292,17 @@ export namespace Realm { export import SubscriptionSetState = internal.SubscriptionSetState; export import SyncConfiguration = internal.SyncConfiguration; export import SyncError = internal.SyncError; + export import SyncProxyConfig = internal.SyncProxyConfig; + export import TypeAssertionError = internal.TypeAssertionError; + export import Unmanaged = internal.Unmanaged; export import UpdateMode = internal.UpdateMode; + export import User = internal.User; export import UserChangeCallback = internal.UserChangeCallback; + export import UserIdentity = internal.UserIdentity; export import UserState = internal.UserState; - export import User = internal.User; export import WaitForSync = internal.WaitForSync; - export import GeoBox = internal.GeoBox; - export import GeoCircle = internal.GeoCircle; - export import GeoPoint = internal.GeoPoint; - export import GeoPolygon = internal.GeoPolygon; - export import CanonicalGeoPolygon = internal.CanonicalGeoPolygon; - export import CanonicalGeoPoint = internal.CanonicalGeoPoint; - export import GeoPosition = internal.GeoPosition; + export import WatchOptionsFilter = internal.WatchOptionsFilter; + export import WatchOptionsIds = internal.WatchOptionsIds; // Deprecated exports below /** @deprecated Will be removed in v13.0.0. Please use {@link internal.AppServicesFunction} */ @@ -1271,6 +1317,10 @@ export namespace Realm { export import ObjectClass = internal.RealmObjectConstructor; /** @deprecated Will be removed in v13.0.0. Please use {@link internal.PropertyTypeName} */ export import PropertyType = internal.PropertyTypeName; + /** @deprecated Use the another {@link internal.ClientResetMode} than {@link internal.ClientResetMode.Manual}. */ + export import ClientResetError = internal.ClientResetError; + /** @deprecated Use the another {@link internal.ClientResetMode} than {@link internal.ClientResetMode.Manual}. */ + export import PushClient = internal.PushClient; } //Set default logger and log level. diff --git a/packages/realm/src/RealmListeners.ts b/packages/realm/src/RealmListeners.ts index 7b0ac10bccd..d549721147f 100644 --- a/packages/realm/src/RealmListeners.ts +++ b/packages/realm/src/RealmListeners.ts @@ -24,7 +24,20 @@ export enum RealmEvent { BeforeNotify = "beforenotify", } -export type RealmListenerCallback = (realm: Realm, name: RealmEvent, schema?: CanonicalObjectSchema[]) => void; +export type RealmListenerCallback = ( + /** + * The Realm in which the change event occurred. + */ + realm: Realm, + /** + * The name of the event that occurred. + */ + name: RealmEvent, + /** + * The schema of the Realm file when the event occurred. + */ + schema?: CanonicalObjectSchema[], +) => void; // Temporary functions to work between event names and corresponding enums // TODO: We should update the external API to take a `RealmEvent` instead of a string. diff --git a/packages/realm/src/Unmanaged.ts b/packages/realm/src/Unmanaged.ts index d75cd761689..e8af6fa2786 100644 --- a/packages/realm/src/Unmanaged.ts +++ b/packages/realm/src/Unmanaged.ts @@ -16,9 +16,7 @@ // //////////////////////////////////////////////////////////////////////////// -// eslint-disable-next-line @typescript-eslint/no-unused-vars -import { Collection, Dictionary, List, RealmObject } from "./internal"; -import { AnyRealmObject } from "./Object"; +import type { AnyRealmObject, Collection, Dictionary, List, Realm } from "./internal"; /* eslint-disable-next-line @typescript-eslint/no-explicit-any -- We define these once to avoid using "any" through the code */ export type AnyCollection = Collection; diff --git a/packages/realm/src/app-services/App.ts b/packages/realm/src/app-services/App.ts index 6b3a67b5091..2c6aadb4a26 100644 --- a/packages/realm/src/app-services/App.ts +++ b/packages/realm/src/app-services/App.ts @@ -19,7 +19,7 @@ import type { AnyFetch } from "@realm/fetch"; import { AnyUser, - Configuration, + BaseConfiguration, Credentials, DefaultFunctionsFactory, DefaultObject, @@ -66,7 +66,7 @@ export type Metadata = { /** * The 512-bit (64-byte) encryption key used to encrypt and decrypt meta data in Realm Apps. * This will not change the encryption key for individual Realms. This should still be set in - * {@link Configuration.encryptionKey} when opening the Realm. + * {@link BaseConfiguration.encryptionKey} when opening the Realm. * @since 12.2.0 */ encryptionKey?: ArrayBuffer; diff --git a/packages/realm/src/app-services/MongoDBCollection.ts b/packages/realm/src/app-services/MongoDBCollection.ts index 28405976f30..9f8b86ec502 100644 --- a/packages/realm/src/app-services/MongoDBCollection.ts +++ b/packages/realm/src/app-services/MongoDBCollection.ts @@ -389,6 +389,22 @@ export type ChangeEvent = | DropDatabaseEvent | InvalidateEvent; +export type WatchOptionsIds = { + /** + * A list of document IDs for which change events you want to watch. + */ + ids: T["_id"][]; + filter?: never; +}; + +export type WatchOptionsFilter = { + ids?: never; + /** + * A filter for which change events you want to watch. + */ + filter: Filter; +}; + /** * A remote collection of documents in a MongoDB database. */ @@ -651,14 +667,12 @@ export class MongoDBCollection { * * 1. Polyfills for `fetch` and `ReadableStream`: https://www.npmjs.com/package/react-native-polyfill-globals * 2. Babel plugin enabling async generator syntax: https://npmjs.com/package/@babel/plugin-proposal-async-generator-functions - * @param options.filter - A filter for which change events you want to watch. - * @param options.ids - A list of document IDs for which change events you want to watch. * @returns An async generator of change events. * @see https://docs.mongodb.com/manual/reference/change-events/ */ watch(): AsyncGenerator>; - watch(options: { ids: T["_id"][]; filter?: never }): AsyncGenerator>; - watch(options: { ids?: never; filter: Filter }): AsyncGenerator>; + watch(options: WatchOptionsIds): AsyncGenerator>; + watch(options: WatchOptionsFilter): AsyncGenerator>; async *watch({ ids, filter, diff --git a/packages/realm/src/app-services/PushClient.ts b/packages/realm/src/app-services/PushClient.ts index 09027680a90..ffdfb183f01 100644 --- a/packages/realm/src/app-services/PushClient.ts +++ b/packages/realm/src/app-services/PushClient.ts @@ -19,6 +19,7 @@ import { binding } from "../internal"; /** * Authentication provider where users identify using an API-key. + * @deprecated https://www.mongodb.com/docs/atlas/app-services/reference/push-notifications/ */ export class PushClient { /** @internal */ diff --git a/packages/realm/src/app-services/User.ts b/packages/realm/src/app-services/User.ts index 0e01dda2b59..379ae77210a 100644 --- a/packages/realm/src/app-services/User.ts +++ b/packages/realm/src/app-services/User.ts @@ -238,7 +238,7 @@ export class User< /** * Use this to call functions defined by the Atlas App Services application, as this user. - * @returns A {@link FunctionsFactory} that can be used to call the app's functions. + * @returns A {@link UserFunctionsFactoryType} that can be used to call the app's functions. */ get functions(): UserFunctionsFactoryType { return createFactory(this as User, undefined);