collections@0.5.1
This adaptor exports the following namespaced functions:
- collections.each(name, query, callback)
- collections.get(name, query)
- collections.remove(name, query)
- collections.set(keygen, values)
collections
These functions belong to the collections namespace.
collections.each
each(name, query, callback)
Iterate over all values in a collection which match the provided query.
each() maintains a low memory footprint by streaming items individually.
You can pass a string key-pattern as a query, or pass a query object.
The callback function will be invoked for each value with three parameters:
state, value and key.
Changing the page size does not affect the callback function (only one item is
ever passed at a time).
| Param | Type | Description |
|---|---|---|
| name | string | The name of the collection to remove from |
| query | string | QueryOptions | A string key or key pattern (with wildcards '*') to remove, or a query object |
| callback | function | A callback invoked for each item (state, value, key) => void |
This operation writes the following keys to state:
| State Key | Description |
|---|---|
| data.cursor | if values are still left on the server, a cursor string will be written to state.data |
Example: Iterate over a range of values with wildcards
collections.each('my-collection', 'record-2024*-appointment-*', (state, value, key) => {
state.cumulativeCost += value.cost;
})
Example: Iterate over a range of values with date filters
collections.each('my-collection', { createdBefore: new Date().toString() }, (state, value, key) => {
state.cumulativeCost += value.cost;
})
collections.get
get(name, query)
Fetch one or more values from a collection. For large datasets, we recommend using each(), which streams data. You can pass a specific key as a string to only fetch one item, or pass a query with a key-pattern or a date filter. If not all matching values are returned, the cursor position is written to state.data
| Param | Type | Description |
|---|---|---|
| name | string | The name of the collection to fetch from |
| query | string | QueryOptions | A string key or key pattern (with wildcards '*') to fetch, or a query object |
This operation writes the following keys to state:
| State Key | Description |
|---|---|
| data | the downloaded values as an array unless a specific key was specified, in which case state.data is the value |
Example: Get a specific value from a collection
collections.get('my-collection', '556e0a62')
Example: Get a range of values from a collection with a key pattern
collections.get('my-collection', '2024*')
Example: Get all values created since the end of January 2024
collections.get('my-collection', { createdAfter: '202401')
collections.remove
remove(name, query)
Remove one or more values from a collection. You can pass a specific key as a string to only fetch one item, or pass a query with a key-pattern or a date filter.
| Param | Type | Description |
|---|---|---|
| name | string | The name of the collection to remove from |
| query | string | QueryOptions | A string key or key pattern (with wildcards '*') to remove, or a query object |
Example: Remove a specific value from a collection
collections.remove('my-collection', '556e0a62')
Example: Remove a range of values from a collection with a key pattern
collections.remove('my-collection', '2024*')
Example: Remove all values created since the end of January 2024
collections.remove('my-collection', { createdAfter: '202401')
collections.set
set(keygen, values)
Adds one or more values to a collection. If a key already exists, its value will be replaced by the new value. You can pass a string key and a single value, or a key generator function and an array of values. The function will be called for each value, passing each value as the first argument, and should return a string key.
| Param | Description |
|---|---|
| keygen | a function which generates a key for each value: (value, index) => key. Pass a string to set a static key for a single item. |
| values | an array of values to set, or a single value. |
Example: Set a number of values using each value's id property as a key
collections.set('my-collection', (item) => item.id, $.data)
Example: Set a number of values, generating an id from a string template
collections.set('my-collection', (item) => `${item.category}-${Date.now()}`, $.data)
Example: Set a single value with a static key
collections.set('my-collection', 'city-codes', { NY: 'New York', LDN: 'London' }})
Interfaces
QueryOptions
Query options. All dates should be parseable as ISO 8601 strings, see https://simple.wikipedia.org/wiki/ISO_8601
Properties
| Name | Type | Description |
|---|---|---|
| key | string | key or key pattern to match against. Patterns support wildcards, eg 2024-01* |
| createdBefore | string | matches values that were created before the start of the provided date |
| createdAfter | string | matches values that were created after the end of the provided date |
| limit | number | limit the maximum amount of results. If Infinity or unset, all items will be fetched. Default: Infnity. |
| pageSize | number | specify the number of values downloaded per page (or chunk). Default 1000. |
| cursor | string | set the cursor position to start searching from a specific index. |