Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Review and revise documentation #5977

Merged
merged 1 commit into from
Jul 13, 2023
Merged

Review and revise documentation #5977

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions packages/realm/src/ClassHelpers.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,7 @@ import {

type ObjectWrapper = (obj: binding.Obj) => (RealmObject & DefaultObject) | null;

/**
* @internal
*/
/** @internal */
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#5937 (comment) 😆

export type ClassHelpers = {
constructor: RealmObjectConstructor;
objectSchema: binding.ObjectSchema;
Expand Down
6 changes: 2 additions & 4 deletions packages/realm/src/ClassMap.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,7 @@ import {
setClassHelpers,
} from "./internal";

/**
* @internal
*/
/** @internal */
export class ClassMap {
private mapping: Record<string, Constructor<unknown>>;
private nameByTableKey: Record<binding.TableKey, string>;
Expand Down Expand Up @@ -129,7 +127,7 @@ export class ClassMap {
properties,
wrapObject(obj) {
if (obj.isValid) {
return RealmObject.createWrapper(realm, obj, constructor);
return RealmObject.createWrapper(obj, constructor);
} else {
return null;
}
Expand Down
31 changes: 16 additions & 15 deletions packages/realm/src/Collection.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,21 +60,21 @@ export abstract class Collection<

/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/keys Array.prototype.keys}
* @returns Iterator with all keys in the collection
* @returns An iterator with all keys in the collection.
* @since 0.11.0
*/
abstract keys(): Iterable<KeyType>;

/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/keys Array.prototype.keys}
* @returns Iterator with all values in the collection
* @returns An iterator with all values in the collection.
* @since 0.11.0
*/
abstract values(): Iterable<ValueType>;

/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries Array.prototype.keys}
* @returns Iterator with all key/value pairs in the collection
* @returns An iterator with all key/value pairs in the collection.
* @since 0.11.0
*/
abstract entries(): Iterable<EntryType>;
Expand All @@ -88,7 +88,7 @@ export abstract class Collection<
* spread operators, and more.
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator Symbol.iterator}
* and the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterable iterable protocol}
* @returns Iterable of each value in the collection
* @returns An iterable of each value in the collection.
* @example
* for (let object of collection) {
* // do something with each object
Expand All @@ -106,15 +106,16 @@ 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.
* The callback function is called with two arguments:
* - `collection`: the collection instance that changed,
* - `changes`: a dictionary with keys `insertions`, `newModifications`, `oldModifications`
* and `deletions`, each containing a list of indices in the collection that were
* inserted, updated or deleted respectively. `deletions` and `oldModifications` are
* indices into the collection before the change happened, while `insertions` and
* `newModifications` are indices into the new version of the collection.
* @throws a {@link TypeAssertionError} If `callback` is not a function.
* @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.
* @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.
* @throws A {@link TypeAssertionError} if `callback` is not a function.
* @example
* wines.addListener((collection, changes) => {
* // collection === wines
Expand All @@ -134,8 +135,8 @@ export abstract class Collection<

/**
* Remove the listener `callback` from the collection instance.
* @param callback Callback function that was previously
* added as a listener through the **addListener** method.
* @param callback - Callback function that was previously
* added as a listener through the {@link Collection.addListener} method.
* @throws a {@link TypeAssertionError} If `callback` is not a function.
*/
removeListener(callback: ChangeCallbackType): void {
Expand Down
122 changes: 1 addition & 121 deletions packages/realm/src/Configuration.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ export type BaseConfiguration = {
readOnly?: boolean;
fifoFilesFallbackPath?: string;
sync?: SyncConfiguration;
/**@internal */ openSyncedRealmLocally?: true;
/** @internal */ openSyncedRealmLocally?: true;
shouldCompact?: (totalBytes: number, usedBytes: number) => boolean;
deleteRealmIfMigrationNeeded?: boolean;
disableFormatUpgrade?: boolean;
Expand All @@ -59,126 +59,6 @@ export type ConfigurationWithoutSync = BaseConfiguration & {

export type Configuration = ConfigurationWithSync | ConfigurationWithoutSync;

// export type PartitionValue = string | number | null | ObjectId | UUID;

// /**
// * A function which can be called to migrate a Realm from one version of the schema to another.
// */
// export type MigrationCallback = (oldRealm: Realm, newRealm: Realm) => void;

// export enum ClientResetModeManualOnly {
// Manual = "manual",
// }

// export enum ClientResetMode {
// Manual = "manual",
// DiscardLocal = "discardLocal",
// }

// export type ClientResetBeforeCallback = (localRealm: Realm) => void;
// export type ClientResetAfterCallback = (localRealm: Realm, remoteRealm: Realm) => void;
// export type ClientResetConfiguration<ClientResetModeT = ClientResetMode> = {
// mode: ClientResetModeT;
// clientResetBefore?: ClientResetBeforeCallback;
// clientResetAfter?: ClientResetAfterCallback;
// };

// export type BaseSyncConfiguration = {
// user: User;
// customHttpHeaders?: { [header: string]: string };
// ssl?: SSLConfiguration;
// _sessionStopPolicy?: SessionStopPolicy;
// newRealmFileBehavior?: OpenRealmBehaviorConfiguration;
// existingRealmFileBehavior?: OpenRealmBehaviorConfiguration;
// error?: ErrorCallback;
// };

// // We only allow `flexible` to be `true` or `undefined` - `{ flexible: false }`
// // is not allowed. This is because TypeScript cannot discriminate that
// // type correctly with `strictNullChecks` disabled, and there's no real use
// // case for `{ flexible: false }`.
// export type FlexibleSyncConfiguration = BaseSyncConfiguration & {
// flexible: true;
// partitionValue?: never;
// clientReset?: ClientResetConfiguration<ClientResetModeManualOnly>;
// /**
// * 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: 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?: {
// /**
// * Callback called with the {@link Realm} instance to allow you to setup the
// * initial set of subscriptions by calling `realm.subscriptions.update`.
// * See {@link SubscriptionSet.update} for more information.
// */
// update: (subs: MutableSubscriptionSet, realm: Realm) => void;
// /**
// * If `true`, the {@link 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 PartitionSyncConfiguration = BaseSyncConfiguration & {
// flexible?: never;
// partitionValue: PartitionValue;
// clientReset?: ClientResetConfiguration<ClientResetMode>;
// };

// export type SyncConfiguration = FlexibleSyncConfiguration | PartitionSyncConfiguration;

// export type BaseConfiguration = {
// encryptionKey?: ArrayBuffer | ArrayBufferView | Int8Array;
// schema?: (ObjectConstructor | ObjectSchema)[];
// schemaVersion?: number;
// shouldCompactOnLaunch?: (totalBytes: number, usedBytes: number) => boolean;
// onFirstOpen?: (realm: Realm) => void;
// path?: string;
// fifoFilesFallbackPath?: string;
// readOnly?: boolean;
// };

// export type ConfigurationWithSync = BaseConfiguration & {
// sync: SyncConfiguration;
// migration?: never;
// inMemory?: never;
// deleteRealmIfMigrationNeeded?: never;
// disableFormatUpgrade?: never;
// };

// export type ConfigurationWithoutSync = BaseConfiguration & {
// sync?: never;
// migration?: MigrationCallback;
// inMemory?: boolean;
// deleteRealmIfMigrationNeeded?: boolean;
// disableFormatUpgrade?: boolean;
// };

/**
* Validate the fields of a user-provided Realm configuration.
* @internal
Expand Down
46 changes: 24 additions & 22 deletions packages/realm/src/Dictionary.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,24 +178,26 @@ export class Dictionary<T = unknown> extends Collection<string, T, [string, T],
*/
private declare [INTERNAL]: binding.Dictionary;

/**
* @internal
*/
/** @internal */
private declare [HELPERS]: TypeHelpers;

/** @ts-expect-error We're exposing methods in the end-users namespace of keys */
[key: string]: T;

*[Symbol.iterator]() {
/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries Array.prototype.entries}
* @returns An iterator with all entries in the dictionary.
*/
*[Symbol.iterator](): Generator<[string, T]> {
yield* this.entries();
}

/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/keys Array.prototype.keys}
* @returns Iterator with all values in the dictionary
* @since 0.11.0
* @returns An iterator with all values in the dictionary.
* @since 10.5.0
* @ts-expect-error We're exposing methods in the end-users namespace of keys */
*keys() {
*keys(): Generator<string> {
const snapshot = this[INTERNAL].keys.snapshot();
const size = snapshot.size();
for (let i = 0; i < size; i++) {
Expand All @@ -206,11 +208,11 @@ export class Dictionary<T = unknown> extends Collection<string, T, [string, T],
}

/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/keys Array.prototype.keys}
* @returns Iterator with all values in the dictionary
* @since 0.11.0
* @ts-expect-error We're exposing methods in the end-users namespace of keys */
*values() {
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/values Array.prototype.values}
* @returns An iterator with all values in the dictionary.
* @since 10.5.0
* @ts-expect-error We're exposing methods in the end-users namespace of values */
*values(): Generator<T> {
const { fromBinding } = this[HELPERS];
const snapshot = this[INTERNAL].values.snapshot();
const size = snapshot.size();
Expand All @@ -221,11 +223,11 @@ export class Dictionary<T = unknown> extends Collection<string, T, [string, T],
}

/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries Array.prototype.keys}
* @returns Iterator with all key/value pairs in the dictionary
* @since 0.11.0
* @ts-expect-error We're exposing methods in the end-users namespace of keys */
*entries() {
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries Array.prototype.entries}
* @returns An iterator with all key/value pairs in the dictionary.
* @since 10.5.0
* @ts-expect-error We're exposing methods in the end-users namespace of entries */
*entries(): Generator<[string, T]> {
const { fromBinding } = this[HELPERS];
const keys = this[INTERNAL].keys.snapshot();
const values = this[INTERNAL].values.snapshot();
Expand Down Expand Up @@ -266,9 +268,9 @@ export class Dictionary<T = unknown> extends Collection<string, T, [string, T],
set(key: string, value: T): this;
/**
* Adds one or more elements with the specified key and value to the dictionary or updates value if key exists.
* @param elementsOrKey The element to add or the key of the element to add.
* @param value The value of the element to add.
* @throws an {@link AssertionError} If not inside a write transaction, if using symbol as keys, or if any value violates type constraints.
* @param elementsOrKey - The element to add or the key of the element to add.
* @param value - The value of the element to add.
takameyer marked this conversation as resolved.
Show resolved Hide resolved
* @throws An {@link AssertionError} if not inside a write transaction, if using symbol as keys, or if any value violates type constraints.
* @returns The dictionary.
* @since 10.6.0
*/
Expand All @@ -288,8 +290,8 @@ export class Dictionary<T = unknown> extends Collection<string, T, [string, T],
/**
* Removes elements from the dictionary, with the keys provided.
* This does not throw if the keys are already missing from the dictionary.
* @param key The key to be removed.
* @throws an {@link AssertionError} If not inside a write transaction.
* @param key - The key to be removed.
* @throws An {@link AssertionError} if not inside a write transaction.
* @returns The dictionary
* @since 10.6.0
* @ts-expect-error We're exposing methods in the end-users namespace of keys */
Expand Down
4 changes: 2 additions & 2 deletions packages/realm/src/GeoSpatial.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@ const earthRadiusMi = 3963.16760121; //earthRadiusKm / 1.609344 (km/mi)

/**
* Converts the input kilometer value in radians.
* @param km The kilometers to convert.
* @param km - The kilometers to convert.
* @returns The corresponding number of radians.
*/
export function kmToRadians(km: number): number {
Expand All @@ -181,7 +181,7 @@ export function kmToRadians(km: number): number {

/**
* Converts the input miles value in radians.
* @param mi The miles to convert.
* @param mi - The miles to convert.
* @returns The corresponding number of radians.
*/
export function miToRadians(mi: number): number {
Expand Down
Loading
Loading