@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:

RecordsStore (external)

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:

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

FetchCondition

Data exporters

createRecordsExporter

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

RecordsExporterOptions

The createRecordsExporter() returns an Exporter object.

Exporter

ExportResult

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):

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

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