From 37c5a5bf390d2bb3af4307ed28544d9acbd73665 Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Thu, 6 May 2021 10:23:51 -0400 Subject: [PATCH 01/15] Add content to Node.js > Data Types > Collections.txt --- source/sdk/node/data-types/collections.txt | 29 ++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index f0675fafbd..c355e6da94 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -14,3 +14,32 @@ 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 +`. {+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 `. Collections are +:ref:`live `, 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 `. + +Lists +----- + + + +Overview +Lists & LinkingObjects +Results Collection +Results are Lazily Evaluated +Collections are Live +Working With Collections + Iteration + Limiting Query Results + Pagination +Summary \ No newline at end of file From ed0a4758056110d0fd02cc7a942147b28b404e29 Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Thu, 6 May 2021 10:27:08 -0400 Subject: [PATCH 02/15] Removed unneeded spacing --- source/sdk/node/data-types/collections.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index c355e6da94..1eac9e8464 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -31,8 +31,6 @@ notifications `. Lists ----- - - Overview Lists & LinkingObjects Results Collection From 9c52218d78d2ba8794d4d7c4111ed0d59fddc3ed Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Thu, 6 May 2021 11:56:01 -0400 Subject: [PATCH 03/15] clean up collections page + add headers --- source/sdk/node/data-types/collections.txt | 25 ++++++++++++++++------ 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index 1eac9e8464..a62c65061e 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -30,14 +30,25 @@ notifications `. Lists ----- +note about linking objects + +Results +------- -Overview -Lists & LinkingObjects -Results Collection Results are Lazily Evaluated +---------------------------- + Collections are Live +-------------------- + Working With Collections - Iteration - Limiting Query Results - Pagination -Summary \ No newline at end of file +------------------------ + +Iteration +~~~~~~~~~ + +Limiting Query Results +~~~~~~~~~~~~~~~~~~~~~~ + +Summary +------- \ No newline at end of file From 546f6f9deacc9e6e363f5a4d87067ecb8dd0dbc2 Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Thu, 6 May 2021 14:52:59 -0400 Subject: [PATCH 04/15] Filled out collections page --- source/sdk/node/data-types/collections.txt | 95 ++++++++++++++++++++-- 1 file changed, 89 insertions(+), 6 deletions(-) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index a62c65061e..93602ab8f4 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -28,27 +28,110 @@ of the :term:`{+realm+} instance` on the current thread. You can also listen for changes in the collection by subscribing to :ref:`collection notifications `. -Lists ------ -note about linking objects +.. _node-realm-results: Results ------- +A :js-sdk:`Results ` 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-list: + +Lists +----- +A :js-sdk:`List ` represents a :ref:`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 +`. + +.. seealso:: + + :ref:`To-Many Relationships ` + +.. _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 `, {+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 ` or :mdn:`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() ` + +Combined with :ref:`collection 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 ------------------------ -Iteration -~~~~~~~~~ +.. _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 -------- \ No newline at end of file +------- +- A {+service-short+} **collection** is a homogenous container of zero + or more instances of one + :ref:`{+service-short+} type `. +- There are two main kinds of collection: **lists** and **results**. + Lists define the :ref:`to-many relationships ` + of your {+service-short+} types, while results represent the + lazily-loaded output of a :ref:`read operation `. +- 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 \ No newline at end of file From aec1cfc164be9df1b9a55903fa1334eecd238768 Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Thu, 6 May 2021 15:00:42 -0400 Subject: [PATCH 05/15] fix refs --- source/sdk/node/data-types/collections.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index 93602ab8f4..0492b9b983 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -23,7 +23,7 @@ all objects in a collection are of the same type. You can filter and sort any collection using {+client-database+}'s :ref:`query engine `. Collections are -:ref:`live `, so they always reflect the current state +:ref:`live `, 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 `. @@ -69,7 +69,7 @@ queries. Collections are Live -------------------- -Like :ref:`live objects `, {+service-short+} collections +Like :ref:`live objects `, {+service-short+} collections are usually **live**: - Live results collections always reflect the current results of the associated query. From 9df9602d3fb98addebc3fc7234a7ea5b1582fe45 Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Thu, 6 May 2021 15:02:15 -0400 Subject: [PATCH 06/15] fix typo --- source/sdk/node/data-types/collections.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index 0492b9b983..ac31b6c273 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -134,4 +134,4 @@ Summary - 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 \ No newline at end of file +- Data in {+service-short+} is *live*, which means that an object always reflects its most recent saved state. \ No newline at end of file From 037dd7e9bfcd95908e70e1b5b160efba8a2a9288 Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Fri, 7 May 2021 10:36:05 -0400 Subject: [PATCH 07/15] Update source/sdk/node/data-types/collections.txt --- source/sdk/node/data-types/collections.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index ac31b6c273..7102a1dc94 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -60,7 +60,7 @@ query and are declared as a property of an :ref:`object model Results are Lazily Evaluated ---------------------------- -{+client-database+} only runs a query when you actually request the +{+client-database+} only runs a query when you 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. @@ -134,4 +134,4 @@ Summary - 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. \ No newline at end of file +- Data in {+service-short+} is *live*, which means that an object always reflects its most recent saved state. From b1f88fe2e6b5284dee9f7ba0307775c947c85d02 Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Fri, 7 May 2021 10:37:20 -0400 Subject: [PATCH 08/15] Update source/sdk/node/data-types/collections.txt --- source/sdk/node/data-types/collections.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index 7102a1dc94..5bb50f8450 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -76,7 +76,7 @@ are usually **live**: - 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 ` or :mdn:`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 enumerated using a :mdn:`for..in ` or :mdn:`for..of ` statement. ``for...in`` and ``for...of`` enumerate over the objects that 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() ` Combined with :ref:`collection notifications From f65f804af56caf732841691f14fb53e43b75b8be Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Tue, 11 May 2021 10:49:24 -0400 Subject: [PATCH 09/15] Update source/sdk/node/data-types/collections.txt Co-authored-by: Dachary --- source/sdk/node/data-types/collections.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index 5bb50f8450..2989628770 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -62,7 +62,7 @@ Results are Lazily Evaluated ---------------------------- {+client-database+} only runs a query when you request the results of that query. This lazy evaluation enables you to write -elegant, highly performant code for handling large data sets and complex +elegant, highly-performant code for handling large data sets and complex queries. .. _node-live-collections: From 233d37ad37cb1b7609ee35ce6c5f5f32422bf2eb Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Tue, 11 May 2021 10:50:16 -0400 Subject: [PATCH 10/15] fix rst --- source/sdk/node/data-types/collections.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index 5bb50f8450..23521c5eb2 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -76,6 +76,7 @@ are usually **live**: - 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 ` or :mdn:`for..of ` statement. ``for...in`` and ``for...of`` enumerate over the objects that 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() ` From a1a1b1210fe03d958265cd7441a43e634f69997a Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Tue, 11 May 2021 11:04:07 -0400 Subject: [PATCH 11/15] fix woridng --- source/sdk/node/data-types/collections.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index ab80b6ae44..d72455e20d 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -77,7 +77,7 @@ are usually **live**: A collection is **not** live when: -- the collection is enumerated using a :mdn:`for..in ` or :mdn:`for..of ` statement. ``for...in`` and ``for...of`` enumerate over the objects that 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. +- It is a results collection that you are iterating through using a :mdn:`for..in ` or :mdn:`for..of ` statement. Both statements will continue to iterate through objects in the collection even if you have deleted or modified the collection's objects to exclude them from the filter that produced the results collection. - the collection is a frozen :js-sdk:`Results.snapshot() ` Combined with :ref:`collection notifications From ad18ac79955e186b1def7df8e1d938ea4b45cf27 Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Tue, 11 May 2021 11:05:20 -0400 Subject: [PATCH 12/15] added ref --- source/sdk/node/data-types/collections.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index d72455e20d..773f312897 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -77,7 +77,7 @@ are usually **live**: A collection is **not** live when: -- It is a results collection that you are iterating through using a :mdn:`for..in ` or :mdn:`for..of ` statement. Both statements will continue to iterate through objects in the collection even if you have deleted or modified the collection's objects to exclude them from the filter that produced the results collection. +- it is a :ref:`results collection ` that you are iterating through using a :mdn:`for..in ` or :mdn:`for..of ` statement. Both statements will continue to iterate through objects in the collection even if you have deleted or modified the collection's objects to exclude them from the filter that produced the results collection. - the collection is a frozen :js-sdk:`Results.snapshot() ` Combined with :ref:`collection notifications From 6d16272442598e2c4659b44e50acaaa3705caf6c Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Tue, 11 May 2021 11:06:19 -0400 Subject: [PATCH 13/15] removed unneeded word --- source/sdk/node/data-types/collections.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index 773f312897..e8648002f1 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -81,7 +81,7 @@ A collection is **not** live when: - the collection is a frozen :js-sdk:`Results.snapshot() ` Combined with :ref:`collection notifications -`, live collections enable clean, +`, live collections enable 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 From 21a5e340d5270f9e2526b5546416c17a7822e2da Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Tue, 11 May 2021 11:07:40 -0400 Subject: [PATCH 14/15] removed unneeded word --- source/sdk/node/data-types/collections.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index e8648002f1..8adc2e8c55 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -108,7 +108,7 @@ 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 +to load the first ten, access only the first ten elements of the results collection. .. _node-realm-result-pagination: From 8775ba53c350215ee9eca0927e7a422b5e2aefa8 Mon Sep 17 00:00:00 2001 From: Mohammad Hunan Chughtai Date: Tue, 11 May 2021 11:10:41 -0400 Subject: [PATCH 15/15] added period --- source/sdk/node/data-types/collections.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/node/data-types/collections.txt b/source/sdk/node/data-types/collections.txt index 8adc2e8c55..22faee6f5c 100644 --- a/source/sdk/node/data-types/collections.txt +++ b/source/sdk/node/data-types/collections.txt @@ -78,7 +78,7 @@ are usually **live**: A collection is **not** live when: - it is a :ref:`results collection ` that you are iterating through using a :mdn:`for..in ` or :mdn:`for..of ` statement. Both statements will continue to iterate through objects in the collection even if you have deleted or modified the collection's objects to exclude them from the filter that produced the results collection. -- the collection is a frozen :js-sdk:`Results.snapshot() ` +- the collection is a frozen :js-sdk:`Results.snapshot() `. Combined with :ref:`collection notifications `, live collections enable