@awarns/persistence

This module defines tasks to persist the output of other tasks (namely, entities extending the base Record model). Concretely, it includes:

• A local, document-based store for entities meeting the Record interface.
• Optional one-way data synchronization of the local records store to any external store (e.g., a remote backend).
• The possibility to query and observe updates on the records stored locally.
• Ready-to-use data exporters to dump the stored records to JSON and CSV files.
• A generic data store class to define entity-specific persistence stores, for data models that don't meet the Record specification.

This plugin has been built as a wrapper of Triniwiz's NativeScript Couchbase plugin, adapted to work with the records and the task model of the AwarNS Framework.

Install the plugin using the following command line instruction:

ns plugin add @awarns/persistence

Usage

After installing and configuring this plugin, you'll be granted with two interaction mechanisms to work with it:

1. The plugin API. Through it, you'll be able to manage the stored records, query them and export them using the most common information exchange formats.
2. A task to write Record interface-compliant entities, which allows to persist one or more records locally (with optional one-way server synchronization), to later query and/or export them.

Setup

This plugin requires you to register its loader during the framework initialization, like this:

// ... platform imports
import { awarns } from '@awarns/core';
import { demoTasks } from '../tasks';
import { demoTaskGraph } from '../graph';
import { registerPersistencePlugin } from '@awarns/persistence';

import { externalRecordsStore } from './external-store';

awarns
  .init(
    demoTasks,
    demoTaskGraph,
    [
      registerPersistencePlugin({
        externalRecordsStore: externalRecordsStore,
        oldRecordsMaxAgeHours: 7 * 24 // 1 week
      }),
    ]
  )
  // ... handle initialization promise

Plugin loader config parameter options:

| Property | Type | Description | |-------------------------|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | externalRecordsStore | RecordsStore | (Optional) Inject an adapter to an external records store and enable one-way synchronization of the stored records. The table below describes the methods that this adapter needs to implement | | oldRecordsMaxAgeHours | number | (Optional) Tell the plugin to regularly cleanup old local records. By default, all records are kept |

RecordsStore (external)

| Method | Return type | Description | |--------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------| | insert(record: Record) | Promise<void> | Persist the given record. Throw an error if something goes wrong. The write will be retried during the next app initialization |

Due to that, for now, this plugin only supports one-way synchronization, the rest of the methods are meant for future use and don't need to be implemented at the moment. You can throw unimplemented errors inside them, so that you can more easily recognize when they start being used in future versions.

API

The API of this plugin can be classified in 3 groups: records' storage, data exporters and custom data stores.

Records storage

recordsStore

In the records' storage group, there is the recordsStore singleton object, with the following methods:

| Method | Return type | Description | |---------------------------------------------------------------------------------------------------------|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | insert(record: Record) | Promise<void> | Persist the given record. On success, if provided during plugin initialization, it will try to automatically synchronize the new record to the external store | | getAll(reverseOrder?: boolean, limitSize?: number) | Promise<Array<Record>> | Allows to retrieve the current latest (by default) or first records, optionally limiting the resulting list in size | | list(size?: number) | Observable<Record> | Allows to observe the "n" most recent records, where "n" is determined by the value given to the size parameter. By default, size is 100 | | listBy(recordType: string, order: 'asc' | 'desc', conditions?: Array) | Observable<Array<Record>> | Allows to observe all the records of a given type. The sorting of the records can be controlled using the order parameter. The default order is last records come first (desc). It is possible to filter the resulting records by one or more FetchConditions | | listLast(recordType: string, conditions?: Array<FetchCondition>) | Observable<Record> | Allows to obtain updates on the last record of a given type. It is possible to filter the resulting records by one or more FetchConditions | | listLastGroupedBy(recordType: string, groupByProperty: string, conditions?: Array<FetchCondition>) | Observable<Array<Record>> | Allows to obtain updates on the latest records of a given type, grouped by the unique values of a certain property. Property grouping allows nested property paths using the dot (.) character, e.g., property.nestedProperty. It is possible to filter the resulting records by one or more FetchConditions | | deleteBy(recordType: string) | Promise<void> | Allows to delete all the stored records of a given type from the local database | | clear() | Promise<void> | Allows to clear all the stored records from the local database. Use with care! To only remove old records, configure the oldRecordsMaxAgeHours option during plugin initialization | | changes (property) | Observable<Array<string>> | Listen to this observable property to know when a record has been created. It propagates updates on the ids of the records that have been recently stored |

Note: It is recommended to install RxJS, to operate with the methods that return an Observable.

FetchCondition

| Property | Type | Description | |--------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | property | string | The path to the property where the condition will be applied. Works with nested property paths too, using the dot (.) character, e.g., property.nestedProperty | | comparison | '=' | The comparison operation to apply over the property values. At the moment, only property equality (=) is supported | | value | unknown | The value to use in the comparison. At the moment, comparing complex objects is not supported |

Data exporters

createRecordsExporter

In the data exporters group, there is the createRecordsExporter() function, with the following parameters:

| Parameter | Type | Description | |-----------|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | folder | Folder | System folder object. Use NativeScript FileSystem API to define where the exports file will be saved | | format | 'csv' | 'json' | Select the information exchange format to use. Defaults to csv | | options | RecordsExporterOptions | (Optional) Object containing export options such as the file name to use for the exports file, or the type of records to include in the exports |

RecordsExporterOptions

| Parameter | Type | Description | |---------------|------------|---------------------------------------------------------------------------------------------------------------------| | fileName | string | (Optional) Specify the file name to use for the exports file (without extension). Defaults to current date and time | | recordTypes | string[] | (Optional) Specify the types of records to export |

The createRecordsExporter() returns an Exporter object.

Exporter

| Method | Return type | Description | |------------|------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| | export() | Promise<ExportResult> | Tell the exporter to export the records, and save them inside to the configured exports file. Returns an ExportResult once done |

ExportResult

| Property | Return type | Description | |---------------|-------------|--------------------------------------------------| | exportCount | number | The amount of records that have been exported | | fileName | string | The name of the exports file that has been saved |

Custom data stores

AwarnsStore

In the final group, the custom data stores, the core entity is the generic AwarnsStore class. Each AwarnStore has the following methods (replace the T with the concrete entity type being stored):

| Method | Return type | Description | |-----------------------------------------------------------------------------------------------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | AwarnsStore(docType: string, serialize: (entity: T) => unknown, deserialize: (doc: unknown) => T) | AwarnsStore | Creates a new AwarnsStore instance. Takes as parameters: a string to uniquely identify the type of the entity being stored, an entity serialization function and an entity deserialization function | | create(entity: T, id?: string) | Promise<string> | Inserts a new entity into the store. Optionally, an id can be provided. When not provided, an UUID will be generated. On success, returns the id of the newly stored entity | | insert(entities: Array<T>, id?: string) | Promise<Array<string>> | Bulk-inserts multiple entities into the store. On success, returns an array with the id of the newly stored entities (the order is kept) | | get(id: string) | Promise<T> | Searches for an entity using the given id | | fetch(q?: Query) | Promise<Array<T>> | Grants access to the more advanced underlying query interface. Provides the same API as the underlying Couchbase Lite DB query() method | | update(id: string, props: unknown) | Promise<void> | Updates an existing entity with the given id, using the provided properties. Only overrides the values of the given properties | | delete(id: string) | Promise<void> | Deletes an existing entity with the given id | | clear() | Promise<void> | Clears all the entities stored in this concrete AwarnsStore. This is, all the entities that share the same docType value. To clear all the records from all the stores see the clearAwarnsDB() function next |

clearAwarnsDB

Inside the same group, there exists the clearAwarnsDB() function. Use this function to clear EVERYTHING persisted by this plugin. This is, the local records' database and any custom store created using an AwarnsStore instance. This function returns a Promise to inform about when the process has finished.

Tasks

| Task name | Description | |------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | writeRecords | Persists, inside the local records' database, one or more records contained in the invocation event's payload. If specified at plugin initialization time, it will also try to remotely synchronize the newly stored records. If the process fails, it will be retried during the next application start |

Persist records

To register this task for its use, you just need to import it and call its generator function inside your application's task list:

import { Task } from '@awarns/core/tasks';
import { writeRecordsTask } from '@awarns/persistence';

export const demoTasks: Array<Task> = [
  writeRecordsTask(),
];

Task generator parameters:

The task generator takes no parameters.

Task event output:

• writeRecordsFinished (default, no content)

Example usage in the application task graph:

This task is not meant to be used alone, check the docs of any other framework plugin of your choice to see how this task can be used with others. Some examples exist in the battery, human activity and geolocation packages, to name a few

License

Apache License Version 2.0