(DOCSP-15613): Node.js collections type

source/sdk/node/data-types/collections.txt

@@ -14,3 +14,124 @@ Collections - Node.js SDK
 
 Overview
 --------
+
+{+service-short+} has several types to represent groups of objects,
+which we call **collections**. A collection is an object that contains
+zero or more instances of one :ref:`{+service-short+} type
+<node-object-types>`. {+service-short+} collections are **homogenous**:
+all objects in a collection are of the same type.
+
+You can filter and sort any collection using {+client-database+}'s
+:ref:`query engine <node-client-query-engine>`. Collections are
+:ref:`live <node-live-objects>`, so they always reflect the current state
+of the :term:`{+realm+} instance` on the current thread. You can also
+listen for changes in the collection by subscribing to :ref:`collection
+notifications <node-register-a-collection-change-listener>`.
+
+.. _node-realm-results:
+
+Results
+-------
+A :js-sdk:`Results <Realm.Results.html>` collection represents the
+lazily-evaluated results of a query operation. Results are immutable:
+you cannot add or remove elements to or from the results collection.
+Results have an associated query that determines their contents.
+
+.. seealso::
+
+   :ref:`Reads <node-realm-database-reads>`
+
+.. _node-realm-list:
+
+Lists
+-----
+A :js-sdk:`List <Realm.List.html>` represents a :ref:`to-many
+relationship <node-to-many-relationship>` between two {+service-short+}
+types. Lists are mutable: within a write transaction, you can add and
+remove elements to and from a list. Lists are not associated with a
+query and are declared as a property of an :ref:`object model
+<node-object-schemas>`.
+
+.. seealso::
+
+   :ref:`To-Many Relationships <node-to-many-relationship>`
+
+.. _node-lazy-evaluated-results:
+
+Results are Lazily Evaluated
+----------------------------
+{+client-database+} only runs a query when you actually request the
+results of that query. This lazy evaluation enables you to write
+elegant, highly performant code for handling large data sets and complex
+queries.
+
+.. _node-live-collections:
+
+Collections are Live
+--------------------
+Like :ref:`live objects <node-live-objects>`, {+service-short+} collections
+are usually **live**:
+
+- Live results collections always reflect the current results of the associated query.
+- Live lists always reflect the current state of the relationship on the {+realm+} instance.
+
+A collection is **not** live when: 
+- the collection is enumerated using a :mdn:`for..in <Web/JavaScript/Reference/Statements/for...in>` or :mdn:`for..of <Web/JavaScript/Reference/Statements/for...of>` statement. ``for...in`` and ``for...of`` enumerate over the objects which matched the query when the enumeration is begun even if some of them are deleted or modified to be excluded by the filter during the enumeration.
+- the collection is a frozen :js-sdk:`Results.snapshot() <Realm.Collection.html#snapshot>` 
+
+Combined with :ref:`collection notifications
+<node-change-notifications>`, live collections enable clean,
+reactive code. For example, suppose your view displays the
+results of a query. You can keep a reference to the results
+collection in your view class, then read the results
+collection as needed without having to refresh it or
+validate that it is up-to-date.
+
+.. important:: Indexes may change
+
+   Since results update themselves automatically, do not
+   store the positional index of an object in the collection
+   or the count of objects in a collection. The stored index
+   or count value could be outdated by the time you use
+   it.
+
+.. _node-working-with-collections:
+
+Working With Collections
+------------------------
+
+.. _node-limiting-query-results:
+
+Limiting Query Results
+~~~~~~~~~~~~~~~~~~~~~~
+As a result of lazy evaluation, you do not need any special
+mechanism to limit query results with {+client-database+}. For example, if
+your query matches thousands of objects, but you only want
+to load the first ten, simply access only the first ten
+elements of the results collection.
+
+.. _node-realm-result-pagination:
+
+Pagination
+~~~~~~~~~~
+Thanks to lazy evaluation, the common task of pagination
+becomes quite simple. For example, suppose you have a
+results collection associated with a query that matches
+thousands of objects in your {+realm+}. You display one hundred
+objects per page. To advance to any page, simply access the
+elements of the results collection starting at the index
+that corresponds to the target page.
+
+Summary
+-------
+- A {+service-short+} **collection** is a homogenous container of zero
+  or more instances of one
+  :ref:`{+service-short+} type <node-object-types>`.
+- There are two main kinds of collection: **lists** and **results**.
+  Lists define the :ref:`to-many relationships <node-to-many-relationship>`
+  of your {+service-short+} types, while results represent the
+  lazily-loaded output of a :ref:`read operation <node-realm-database-reads>`.
+- Lazy evaluation of results collections means there is no need to
+  design a special query to get limited or paginated results. Perform
+  the query and read from the results collection as needed.
+- Data in {+service-short+} is *live*, which means that an object always reflects its most recent saved state.