status-im
/
realm-js
mirror of https://github.com/status-im/realm-js.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update JSDocs for arrays of primitives (#1357)

This commit is contained in:
Thomas Goyne 2017-09-27 17:57:41 -07:00 committed by GitHub
parent 5616fb6f50
commit e608255282
4 changed files with 164 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
docs/collection.js
View File

@ -18,17 +18,39 @@
/**
* Abstract base class containing methods shared by {@link Realm.List} and {@link Realm.Results}.
*
* A Realm Collection is a homogenous sequence of values of any of the types
* that can be stored as properties of Realm objects. A collection can be
* accessed in any of the ways that a normal Javascript Array can, including
* subscripting, enumerating with `for-of` and so on.
*
* @memberof Realm
* @since 0.11.0
*/
class Collection {
/**
* The number of objects in the collection.
* The number of values in the collection.
* @type {number}
* @readonly
*/
get length() {}
/**
* The {@linkplain Realm~PropertyType type} of values in the collection.
* @type {string}
* @readonly
* @since 2.0.0
*/
get type() {}
/**
* Whether `null` is a valid value for the collection.
* @type {boolean}
* @readonly
* @since 2.0.0
*/
get optional() {}
/**
* Checks if this collection has not been deleted and is part of a valid Realm.
* @returns {boolean} indicating if the collection can be safely accessed.
@ -38,12 +60,15 @@ class Collection {
/**
* Returns new _Results_ that represent this collection being filtered by the provided query.
*
* @param {string} query - Query used to filter objects from the collection.
* @param {...any} [arg] - Each subsequent argument is used by the placeholders
* (e.g. `$0`, `$1`, `$2`, …) in the query.
* @throws {Error} If the query or any other argument passed into this method is invalid.
* @returns {Realm.Results} filtered according to the provided query.
*
* @returns {Realm.Results<T>} filtered according to the provided query.
*
* This is currently only supported for collections of Realm Objects.
*
* See {@tutorial query-language} for details about the query language.
* @example
* let merlots = wines.filtered('variety == "Merlot" && vintage <= $0', maxYear);
@ -51,43 +76,76 @@ class Collection {
filtered(query, ...arg) {}
/**
* Returns new _Results_ that represent this collection being sorted by the provided property
* (or properties) of each object.
* @param {string|Realm.Results~SortDescriptor[]} descriptor - The property name(s) to sort
* the objects in the collection.
* @param {boolean} [reverse=false] - May only be provided if `descriptor` is a string.
* Returns new _Results_ that represent a sorted view of this collection.
*
* A collection of Realm Objects can be sorted on one or more properties of
* those objects, or of properties of objects linked to by those objects.
* To sort by a single property, simply pass the name of that property to
* `sorted()`, optionally followed by a boolean indicating if the sort should be reversed.
* For more than one property, you must pass an array of
* {@linkplain Realm.Collection~SortDescriptor sort descriptors} which list
* which properties to sort on.
*
* Collections of other types sort on the values themselves rather than
* properties of the values, and so no property name or sort descriptors
* should be supplied.
*
* @example
* // Sort wines by age
* wines.sorted('age')
* @example
* // Sort wines by price in descending order, then sort ties by age in
* // ascending order
* wines.sorted([['price', false], ['age'])
* @example
* // Sort a list of numbers in ascending order
* let sortedPrices = wine.pricesSeen.sort()
* @example
* // Sort people by how expensive their favorite wine is
* people.sort("favoriteWine.price")
*
* @param {string|Realm.Collection~SortDescriptor[]} [descriptor] - The property name(s) to sort the collection on.
* @param {boolean} [reverse=false] - Sort in descending order rather than ascended.
* May not be supplied if `descriptor` is an array of sort descriptors.
* @throws {Error} If a specified property does not exist.
* @returns {Realm.Results} sorted according to the arguments passed in
* @returns {Realm.Results<T>} sorted according to the arguments passed in.
*/
sorted(descriptor, reverse) {}
/**
* Create a frozen snapshot of the collection. This means objects added to and removed from the
* original collection will not be reflected in the _Results_ returned by this method.
* However, objects deleted from the Realm will become `null` at their respective indices.
* This is **not** a _deep_ snapshot, meaning the objects contained in this snapshot will
* continue to update as changes are made to them.
* @returns {Realm.Results} which will **not** live update.
* Create a frozen snapshot of the collection.
*
* Values added to and removed from the original collection will not be
* reflected in the _Results_ returned by this method, including if the
* values of properties are changed to make them match or not match any
* filters applied.
*
* This is **not** a _deep_ snapshot. Realm objects contained in this
* snapshot will continue to update as changes are made to them, and if
* they are deleted from the Realm they will be replaced by `null` at the
* respective indices.
*
* @returns {Realm.Results<T>} which will **not** live update.
*/
snapshot() {}
/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries Array.prototype.entries}
* @returns {Realm.Collection~Iterator} of each `[index, object]` pair in the collection
* @returns {Realm.Collection~Iterator<T>} of each `[index, object]` pair in the collection
* @since 0.11.0
*/
entries() {}
/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/keys Array.prototype.keys}
* @returns {Realm.Collection~Iterator} of each index in the collection
* @returns {Realm.Collection~Iterator<T>} of each index in the collection
* @since 0.11.0
*/
keys() {}
/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/values Array.prototype.values}
* @returns {Realm.Collection~Iterator} of each Realm object in the collection
* @returns {Realm.Collection~Iterator<T>} of each Realm object in the collection
* @since 0.11.0
*/
values() {}
@ -101,7 +159,7 @@ 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 {Realm.Collection~Iterator} of each Realm object in the collection
* @returns {Realm.Collection~Iterator<T>} of each Realm object in the collection
* @since 0.11.0
* @example
* for (let object of collection) {
@ -128,7 +186,7 @@ class Collection {
* index will be include in the return value. If negative, then the end index will be
* counted from the end of the collection. If omitted, then all objects from the start
* index will be included in the return value.
* @returns {Realm.Object[]} containing the objects from the start index up to, but not
* @returns {T[]} containing the objects from the start index up to, but not
* including, the end index.
* @since 0.11.0
*/
@ -143,7 +201,7 @@ class Collection {
* - `index` – The index of the object being processed in the collection.
* - `collection` – The collection itself.
* @param {object} [thisArg] - The value of `this` when `callback` is called.
* @returns {Realm.Object|undefined} if the `callback` did not return `true` for any object
* @returns {T|undefined} if the `callback` did not return `true` for any object
* in the collection.
* @since 0.11.0
*/
@ -166,10 +224,11 @@ class Collection {
/**
Finds the index of the given object in the collection.
* @param {Realm.Object} [object] - The object to search for in the collection.
* @throws {Error} If the argument does not belong to the realm.
* @returns {number} representing the index where the object was found, or `-1`
* if not in collection.
* @param {T} object - The value to search for in the collection.
* @throws {Error} If the argument is a {@link Realm.Object} that does not
* belong to the same Realm as the collection.
* @returns {number} representing the index where the value was found, or
* `-1` if not in collection.
* @since 1.8.2
*/
indexOf(object) {}
@ -294,7 +353,7 @@ class Collection {
/**
* Remove the listener `callback` from the collection instance.
* @param {function(collection, changes)} callback - Callback function that was previously
* added as a listener through the {@link Collection#addListener addListener} method.
* added as a listener through the {@link Collection#addListener addListener} method.
* @throws {Error} If `callback` is not a function.
*/
removeListener(callback) {}
@ -324,8 +383,9 @@ class Collection {
*/
/**
* The sort descriptors may either just be a string representing the property name, **or** an
* array with two items: `[propertyName, reverse]`
* A sort descriptor is either a string containing one or more property names
* separate by dots, **or** an array with two items: `[propertyName, reverse]`.
*
* @typedef Realm.Collection~SortDescriptor
* @type {string|Array}
*/

63
docs/list.js
View File

@ -19,59 +19,70 @@
/**
* Instances of this class will be returned when accessing object properties whose type is `"list"`
* (see {@linkplain Realm~ObjectSchemaProperty ObjectSchemaProperty}).
* The objects contained in a list are accessible through its index properties and may only be
* modified inside a {@linkplain Realm#write write} transaction.
*
* Lists mostly behave like normal Javascript Arrays, except for that they can
* only store values of a single type (indicated by the `type` and `optional`
* properties of the List), and can only be modified inside a {@linkplain
* Realm#write write} transaction.
*
* @extends Realm.Collection
* @memberof Realm
*/
class List extends Collection {
/**
* Remove the **last** object from the list and return it.
* Remove the **last** value from the list and return it.
* @throws {Error} If not inside a write transaction.
* @returns {Realm.Object|undefined} if the list is empty.
* @returns {T|undefined} if the list is empty.
*/
pop() {}
/**
* Add one or more objects to the _end_ of the list.
* @param {...Realm.Object} object - Each object’s type must match
* {@linkcode Realm~ObjectSchemaProperty objectType} specified in the schema.
* @throws {TypeError} If an `object` is of the wrong type.
* Add one or more values to the _end_ of the list.
*
* @param {...T} value - Values to add to the list.
* @throws {TypeError} If a `value` is not of a type which can be stored in
* the list, or if an object being added to the list does not match the
* {@linkcode Realm~ObjectSchema object schema} for the list.
*
* @throws {Error} If not inside a write transaction.
* @returns {number} equal to the new {@link Realm.List#length length} of the list
* after adding objects.
* @returns {number} equal to the new {@link Realm.List#length length} of
* the list after adding the values.
*/
push(...object) {}
push(...value) {}
/**
* Remove the **first** object from the list and return it.
* Remove the **first** value from the list and return it.
* @throws {Error} If not inside a write transaction.
* @returns {Realm.Object|undefined} if the list is empty.
* @returns {T|undefined} if the list is empty.
*/
shift() {}
/**
* Changes the contents of the list by removing objects and/or inserting new objects.
* Changes the contents of the list by removing value and/or inserting new value.
*
* @see {@linkcode https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice Array.prototype.splice}
* @param {number} index - The start index. If greater than the length of the list,
* the start index will be set to the length instead. If negative, then the start index
* will be counted from the end of the list (e.g. `list.length - index`).
* @param {number} [count] - The number of objects to remove from the list. If not provided,
* then all objects from the start index through the end of the list will be removed.
* @param {...Realm.Object} [object] - Objects to insert into the list starting at `index`.
* @returns {Realm.Object[]} containing the objects that were removed from the list. The
* array is empty if no objects were removed.
* @param {number} [count] - The number of values to remove from the list.
* If not provided, then all values from the start index through the end of
* the list will be removed.
* @param {...T} [value] - Values to insert into the list starting at `index`.
* @returns {T[]} containing the value that were removed from the list. The
* array is empty if no value were removed.
*/
splice(index, count, ...object) {}
/**
* Add one or more objects to the _beginning_ of the list.
* @param {...Realm.Object} object - Each object’s type must match
* {@linkcode Realm~ObjectSchemaProperty objectType} specified in the schema.
* @throws {TypeError} If an `object` is of the wrong type.
* Add one or more values to the _beginning_ of the list.
*
* @param {...T} value - Values to add to the list.
* @throws {TypeError} If a `value` is not of a type which can be stored in
* the list, or if an object being added to the list does not match the
* {@linkcode Realm~ObjectSchema object schema} for the list.
* @throws {Error} If not inside a write transaction.
* @returns {number} equal to the new {@link Realm.List#length length} of the list
* after adding objects.
* @returns {number} equal to the new {@link Realm.List#length length} of
* the list after adding the values.
*/
unshift(...object) {}
}
}

44
docs/realm.js
View File

@ -95,7 +95,7 @@ class Realm {
* Open a Realm asynchronously with a promise. If the Realm is synced, it will be fully
* synchronized before it is available.
* @param {Realm~Configuration} config
* @returns {ProgressPromise} - a promise that will be resolved with the realm instance when it's available.
* @returns {ProgressPromise} - a promise that will be resolved with the Realm instance when it's available.
*/
static open(config) {}
@ -103,7 +103,7 @@ class Realm {
* Open a Realm asynchronously with a callback. If the Realm is synced, it will be fully
* synchronized before it is available.
* @param {Realm~Configuration} config
* @param {callback(error, realm)} - will be called when the realm is ready.
* @param {callback(error, realm)} - will be called when the Realm is ready.
* @param {callback(transferred, transferable)} [progressCallback] - an optional callback for download progress notifications
* @throws {Error} If anything in the provided `config` is invalid.
*/
@ -286,6 +286,7 @@ Realm.defaultPath;
* @property {boolean} [readOnly=false] - Specifies if this Realm should be opened as read-only.
* @property {Array<Realm~ObjectClass|Realm~ObjectSchema>} [schema] - Specifies all the
* object types in this Realm. **Required** when first creating a Realm at this `path`.
* If omitted, the schema will be read from the existing Realm file.
* @property {number} [schemaVersion] - **Required** (and must be incremented) after
* changing the `schema`.
* @property {Object} [sync] - Sync configuration parameters with the following
@ -350,19 +351,39 @@ Realm.defaultPath;
* that must be unique across all objects of this type within the same Realm.
* @property {Object<string, (Realm~PropertyType|Realm~ObjectSchemaProperty)>} properties -
* An object where the keys are property names and the values represent the property type.
*
* @example
* let MyClassSchema = {
* name: 'MyClass',
* primaryKey: 'pk',
* properties: {
* pk: 'int',
* optionalFloatValue: 'float?' // or {type: 'float', optional: true}
* listOfStrings: 'string[]',
* listOfOptionalDates: 'date?[]',
* indexedInt: {type: 'int', indexed: true}
*
* linkToObject: 'MyClass',
* listOfObjects: 'MyClass[]', // or {type: 'list', objectType: 'MyClass'}
* objectsLinkingToThisObject: {type: 'linkingObjects', objectType: 'MyClass', property: 'linkToObject'}
* }
* };
*/
/**
* @typedef Realm~ObjectSchemaProperty
* @type {Object}
* @property {Realm~PropertyType} type - The type of this property.
* @property {string} [objectType] - **Required** when `type` is `"list"` or `"linkingObjects"`,
* and must match the type of an object in the same schema.
* @property {Realm~PropertyType} [objectType] - **Required** when `type` is `"list"` or `"linkingObjects"`,
* and must match the type of an object in the same schema, or, for `"list"`
* only, any other type which may be stored as a Realm property.
* @property {string} [property] - **Required** when `type` is `"linkingObjects"`, and must match
* the name of a property on the type specified in `objectType` that links to the type this property belongs to.
* @property {any} [default] - The default value for this property on creation when not
* otherwise specified.
* @property {boolean} [optional] - Signals if this property may be assigned `null` or `undefined`.
* For `"list"` properties of non-object types, this instead signals whether the values inside the list may be assigned `null` or `undefined`.
* This is not supported for `"list"` properties of object types and `"linkingObjects"` properties.
* @property {boolean} [indexed] - Signals if this property should be indexed. Only supported for
* `"string"`, `"int"`, and `"bool"` properties.
*/
@ -376,10 +397,21 @@ Realm.defaultPath;
*/
/**
* A property type may be specified as one of the standard builtin types, or as an object type
* inside the same schema.
* A property type may be specified as one of the standard builtin types, or as
* an object type inside the same schema.
*
* When specifying property types in an {@linkplain Realm~ObjectSchema object schema}, you
* may append `?` to any of the property types to indicate that it is optional
* (i.e. it can be `null` in addition to the normal values) and `[]` to
* indicate that it is instead a list of that type. For example,
* `optionalIntList: 'int?[]'` would declare a property which is a list of
* nullable integers. The property types reported by {@linkplain Realm.Collection
* collections} and in a Realm's schema will never
* use these forms.
*
* @typedef Realm~PropertyType
* @type {("bool"|"int"|"float"|"double"|"string"|"date"|"data"|"list"|"linkingObjects"|"<ObjectType>")}
*
* @property {boolean} "bool" - Property value may either be `true` or `false`.
* @property {number} "int" - Property may be assigned any number, but will be stored as a
* round integer, meaning anything after the decimal will be truncated.

1
docs/results.js
View File

@ -23,6 +23,7 @@
* {@link Realm.Results#snapshot snapshot()}, however, will **not** live update
* (and listener callbacks added through {@link Realm.Results#addListener addListener()}
* will thus never be called).
*
* @extends Realm.Collection
* @memberof Realm
*/