@awarns/persistence

本模块定义了持久化其他任务（即扩展基本 Record 模型的实体）输出的任务。具体包括

满足 Record 接口的实体本地、基于文档的存储。
可选地将本地记录存储单向数据同步到任何外部存储（例如，远程后端）。
查询和观察本地存储的记录的更新。
可直接使用的数据导出器，将存储的记录导出到 JSON 和 CSV 文件。
通用的数据存储类，用于定义特定实体的持久化存储，适用于不符合 Record 规范的数据模型。

此插件作为 Triniwiz 的 NativeScript Couchbase 插件的包装器构建，以适应 AwarNS 框架的记录和任务模型。

使用以下命令行指令安装插件

ns plugin add @awarns/persistence

用法

安装和配置此插件后，您将获得两种交互机制来与之交互

插件 API。通过它，您可以使用最常见的信息交换格式管理存储的记录、查询它们并导出它们。
写入 Record 接口兼容实体的任务，允许将一个或多个记录本地持久化（可选的单向服务器同步），然后查询和/或导出它们。

设置

此插件要求您在框架初始化期间注册其加载器，如下所示

// ... 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

插件加载器配置参数选项

属性	类型	描述
`externalRecordsStore`	`RecordsStore`	(可选) 注入外部记录存储的适配器并启用存储记录的单向同步。下表描述了此适配器需要实现的方法
`oldRecordsMaxAgeHours`	`number`	(可选) 告诉插件定期清理旧本地记录。默认情况下，保留所有记录

RecordsStore (external)

方法	返回类型	描述
`insert(record: Record)`	`Promise<void>`	持久化给定的记录。如果出现错误，将抛出错误。在下次应用程序初始化期间将重试写入

由于目前此插件仅支持单向同步，其余方法旨在供将来使用，目前不需要实现。您可以在它们内部抛出未实现错误，以便更容易识别将来版本中它们的使用。

API

此插件的 API 可以分为 3 组：记录存储、数据导出器和自定义数据存储。

记录存储

recordsStore

在记录存储组中，有一个名为 recordsStore 的单例对象，具有以下方法

方法	返回类型	描述
`insert(record: Record)`	`Promise<void>`	持久化给定的记录。在成功后，如果插件初始化时提供，它将尝试自动将新记录同步到外部存储
`getAll(reverseOrder?: boolean, limitSize?: number)`	`Promise<Array<Record>>`	允许检索最新的（默认）或最早的记录，可选地限制结果列表的大小
`list(size?: number)`	`Observable<Record>`	允许观察“n”个最近的记录，其中“n”由size参数的值确定。默认值为`100`
`listBy(recordType: string, order: 'asc' \| 'desc', conditions?: Array)`	`Observable<Array<Record>>`	允许观察给定类型的所有记录。记录的排序可以通过order参数来控制。默认排序是最后记录先显示（`desc`）。可以通过一个或多个FetchConditions来过滤结果记录
`listLast(recordType: string, conditions?: Array<FetchCondition>)`	`Observable<Record>`	允许获取给定类型最后记录的更新。可以通过一个或多个FetchConditions来过滤结果记录
`listLastGroupedBy(recordType: string, groupByProperty: string, conditions?: Array<FetchCondition>)`	`Observable<Array<Record>>`	允许获取给定类型最新记录的更新，按特定属性的唯一值分组。属性分组允许使用点（`.`）字符使用嵌套属性路径，例如：`property.nestedProperty`。可以通过一个或多个FetchConditions来过滤结果记录
`deleteBy(recordType: string)`	`Promise<void>`	允许从本地数据库中删除给定类型的所有存储记录
`clear()`	`Promise<void>`	允许从本地数据库中清除所有存储记录。请谨慎使用！要仅删除旧记录，请在插件初始化期间配置`oldRecordsMaxAgeHours`选项
`changes` (property)	`Observable<Array<string>>`	监听此可观察属性以知道何时创建了记录。它传播最近存储的记录的ids的更新

注意：建议安装RxJS，以操作返回Observable的方法。

FetchCondition

属性	类型	描述
`property`	`string`	应用条件的属性路径。也支持嵌套属性路径，使用点（`.`）字符，例如：`property.nestedProperty`
`comparison`	`'='`	要应用在属性值上的比较操作。目前，只支持属性相等（`=`）
`value`	`unknown`	比较中使用的值。目前，不支持比较复杂对象

数据导出器

createRecordsExporter

在数据导出器组中，有一个createRecordsExporter()函数，具有以下参数

参数	类型	描述
`folder`	`文件夹`	系统文件夹对象。使用NativeScript FileSystem API来定义导出文件将保存的位置
`format`	`'csv' \| 'json'`	选择要使用的交换信息格式。默认为`csv`
`options`	`RecordsExporterOptions`	(可选) 包含导出选项的对象，例如用于导出文件的文件名，或要包含在导出中的记录类型

RecordsExporterOptions

参数	类型	描述
`fileName`	`string`	(可选) 指定用于导出文件的文件名（不带扩展名）。默认为当前日期和时间
`recordTypes`	`string[]`	(可选) 指定要导出的记录类型

createRecordsExporter()返回一个Exporter对象。

Exporter

方法	返回类型	描述
`export()`	`Promise<ExportResult>`	告诉导出器导出记录，并将它们保存到配置的导出文件中。完成后返回一个`ExportResult`

ExportResult

属性	返回类型	描述
`exportCount`	`number`	已导出的记录数量
`fileName`	`string`	已保存的导出文件名

自定义数据存储

AwarnsStore

在最后的组中，自定义数据存储的核心实体是通用的 AwarnsStore 类。每个 AwarnStore 具有以下方法（将 T 替换为存储的具体实体类型）

方法	返回类型	描述
`AwarnsStore(docType: string, serialize: (entity: T) => unknown, deserialize: (doc: unknown) => T)`	`AwarnsStore`	创建一个新的 AwarnsStore 实例。参数包括：一个字符串，用于唯一标识存储的实体类型，一个实体序列化函数和一个实体反序列化函数
`create(entity: T, id?: string)`	`Promise<string>`	将一个新的实体插入存储中。可选地，可以提供一个 id。如果没有提供，将生成一个 UUID。成功时，返回新存储实体的 id
`insert(entities: Array<T>, id?: string)`	`Promise<Array<string>>`	批量将多个实体插入存储中。成功时，返回一个包含新存储实体 id 的数组（保持顺序）
`get(id: string)`	`Promise<T>`	使用给定的 id 搜索实体
`fetch(q?: Query)`	`Promise<Array<T>>`	提供对更高级的底层查询接口的访问。提供与底层 Couchbase Lite DB `query()` 方法相同的 API
`update(id: string, props: unknown)`	`Promise<void>`	使用提供的属性更新具有给定 id 的现有实体。仅覆盖给定属性的值
`delete(id: string)`	`Promise<void>`	删除具有给定 id 的现有实体
`clear()`	`Promise<void>`	清除此具体 AwarnsStore 中存储的所有实体。即具有相同 `docType` 值的所有实体。要清除所有存储的记录，请参阅下一个函数 `clearAwarnsDB()`

clearAwarnsDB

在同一组内，存在一个 clearAwarnsDB() 函数。使用此函数清除此插件持久化的所有内容。即本地记录数据库以及使用 AwarnsStore 实例创建的任何自定义存储。此函数返回一个 Promise，以告知处理何时完成。

任务

任务名称	描述
`writeRecords`	在本地记录数据库中持久化调用事件的有效负载中包含的一个或多个记录。如果在使用插件时指定，它还将尝试远程同步新存储的记录。如果过程失败，它将在下一次应用程序启动时重试

持久化记录

要注册此任务以供使用，您只需导入它并在应用程序的任务列表中调用其生成函数即可

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

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

任务生成器参数

任务生成器不接收任何参数。

任务事件输出

writeRecordsFinished (默认，无内容)

在应用程序任务图中的示例使用

此任务不是单独使用的，请检查您选择的任何其他框架插件的文档，了解如何与其他任务一起使用此任务。一些示例存在于 battery、human activity 和 geolocation 包中，仅举几例

许可证

Apache 许可证版本 2.0