uTools - 新一代效率工具平台

Appearance

本地数据库 ​

uTools 提供了本地数据库的 API，基于 nosql 的设计，通过它可以实现一些简单的数据存储和读取。 它可以很方便的使用，数据存储在本地计算机系统，如果用户开启同步，可在多个设备之间实现秒级同步。 uTools 的很多插件应用就像是一个轻型的应用程序，除去远端服务的数据持久化，在插件内，我们也需要为离线数据存储提供支持，在没有网络时程序依然可以提供完整的服务。

警告

在多个设备编辑同一个数据库文档时，将产生冲突，数据库会统一选择一个版本作为最终版本，为了尽可能避免冲突，应该将内容合理的分散在多个文档，而不是都存放在一个数据库文档中。

utools.db.put(doc) / utools.db.promises.put(doc) ​

创建或更新数据库文档，文档内容不超过 1M

类型定义 ​

ts
function put(doc: DbDoc): DbResult;
ts
function put(doc: DbDoc): Promise<DbResult>;
DbDoc 类型定义
ts
interface DbDoc {
  _id: string;
  _rev?: string;
  [key:string]: unknown
}

字段说明 ​

  • _id

    唯一键，如果 _id 不存在，则会创建一个新的文档，如果 _id 已经存在，则会进行更新。

  • _rev

    文档版本，用于解决冲突，对文档进行更新操作时，_rev 不可省略，否则更新将失败。

  • data

    文档内容，更新 data 时都要传入完整的 data (如果 data 是对象的话)，无法对单个字段进行更新。

DbResult 类型定义
ts
interface DbResult {
  id: string;
  rev: string;
  ok: boolean;
}

字段说明 ​

  • id

    唯一键，与 _id 相同。

  • rev

    文档版本，与 _rev 相同。

  • ok

    操作是否成功。

示例代码 ​

ts
// 创建
const doc = utools.db.put({
  _id: "my-doc",
  data: "hello world",
});

// 更新
utools.db.put({
  _id: doc.id,
  _rev: doc.rev,
  data: "hello world 2",
});
ts
// 创建
const doc = await utools.db.promises.put({
  _id: "my-doc",
  data: "hello world",
});

// 更新
await utools.db.promises.put({
  _id: doc.id,
  _rev: doc.rev,
  data: "hello world 2",
});

utools.db.get(id) / utools.db.promises.get(id) ​

通过文档 id 获取数据库文档

类型定义 ​

ts
function get(id: string): DbDoc | undefined;
ts
function get(id: string): Promise<DbDoc | undefined>;

DbDoc 参考 DbDoc 类型定义

示例代码 ​

ts
const doc = utools.db.get("my-doc");
if (doc.ok) {
  console.log(doc.data);
}
ts
const doc = await utools.db.promises.get("my-doc");
if (doc.ok) {
  console.log(doc.data);
}

utools.db.remove(doc) / utools.db.promises.remove(doc) ​

删除数据库文档，可以通过文档对象或者文档 id 删除

类型定义 ​

ts
function remove(doc: DbDoc): DbResult;
function remove(id: string, rev: string): DbResult;
ts
function remove(doc: DbDoc): Promise<DbResult>;
function remove(id: string, rev: string): Promise<DbResult>;

DBResult 参考 DbResult 类型定义

示例代码 ​

ts
const doc = utools.db.get("my-doc");
if (doc.ok) {
  utools.db.remove(doc);
  console.log("删除成功");
}
ts
const doc = await utools.db.promises.get("my-doc");
if (doc.ok) {
  await utools.db.promises.remove(doc);
  console.log("删除成功");
}

utools.db.bulkDocs(docs) / utools.db.promises.bulkDocs(docs) ​

批量创建或更新数据库文档

类型定义 ​

ts
function bulkDocs(docs: DbDoc[]): DbResult[];
ts
function bulkDocs(docs: DbDoc[]): Promise<DbResult[]>;

DbDoc 参考 DbDoc 类型定义 DbResult 参考 DbResult 类型定义

示例代码 ​

ts
const docs = [
  { _id: "my-doc-1", data: "hello world" },
  { _id: "my-doc-2", data: "hello world 2" },
];
const result = utools.db.bulkDocs(docs);
console.log(
  "批量创建成功，一共更新了",
  result.filter((doc) => doc.ok).length,
  "个文档"
);
ts
const docs = [
  { _id: "my-doc-1", data: "hello world" },
  { _id: "my-doc-2", data: "hello world 2" },
];
const result = await utools.db.promises.bulkDocs(docs);
console.log(
  "批量创建成功，一共更新了",
  result.filter((doc) => doc.ok).length,
  "个文档"
);

utools.db.allDocs([ids]) / utools.db.promises.allDocs([ids]) ​

获取数据库中所有文档，可以通过传入字符串进行筛选，此时会匹配 dataStartsWith 字段以传入字符串为前缀的所有文档。也可以传入字符串数组，此时匹配所有 id 为传入字符串数组中的任意一个的文档。 若没有传递参数，则返回所有文档。

类型定义 ​

ts
function allDocs(): DbDoc[];
function allDocs(ids: string[]): DbDoc[];
function allDocs(dataStartsWith: string): DbDoc[];
ts
function allDocs(): Promise<DbDoc[]>;
function allDocs(ids: string[]): Promise<DbDoc[]>;
function allDocs(dataStartsWith: string): Promise<DbDoc[]>;

DbDoc 参考 DbDoc 类型定义

示例代码 ​

ts
const docs = utools.db.allDocs();
console.log("获取到", docs.length, "个文档");
const docs2 = utools.db.allDocs(["my-doc-1", "my-doc-2"]);
console.log("获取到", docs2.length, "个文档");
const docs3 = utools.db.allDocs("my-doc-");
console.log("获取到", docs3.length, "个文档");
ts
const docs = await utools.db.promises.allDocs();
console.log("获取到", docs.length, "个文档");
const docs2 = await utools.db.promises.allDocs(["my-doc-1", "my-doc-2"]);
console.log("获取到", docs2.length, "个文档");
const docs3 = await utools.db.promises.allDocs("my-doc-");
console.log("获取到", docs3.length, "个文档");

utools.db.postAttachment(id, attachment, type) / utools.db.promises.postAttachment(id, attachment, type) ​

存储附件到新文档，附件只能被创建不能被更新，创建的附件最大不超过 10M

类型定义 ​

ts
function postAttachment(
  id: string,
  attachment: Attachment,
  type: string
): DbResult;
ts
function postAttachment(
  id: string,
  attachment: Attachment,
  type: string
): Promise<DbResult>;

DbResult 参考 DbResult 类型定义

type 为附件类型，参考 mime/type，比如 image/png、text/plain 。

Attachment 类型定义
ts
type Attachment = Buffer | Uint8Array;

Buffer 参考 Node.js Buffer

示例代码 ​

ts
const file = fs.readFileSync("./test.png");
const doc = utools.db.postAttachment("my-doc", file, "image/png");
if (doc.ok) {
  console.log("附件存储成功");
}
ts
const file = await fs.promises.readFile("./test.png");
const doc = await utools.db.promises.postAttachment(
  "my-doc",
  file,
  "image/png"
);
if (doc.ok) {
  console.log("附件存储成功");
}

utools.db.getAttachment(id) / utools.db.promises.getAttachment(id) ​

获取附件

类型定义 ​

ts
function getAttachment(id: string): Uint8Array;
ts
function getAttachment(id: string): Promise<Uint8Array>;

示例代码 ​

ts
const file = utools.db.getAttachment("my-doc");
fs.writeFileSync("./test.png", file);
ts
const file = await utools.db.promises.getAttachment("my-doc");
await fs.promises.writeFile("./test.png", file);

utools.db.getAttachmentType(id) / utools.db.promises.getAttachmentType(id) ​

获取附件类型

类型定义 ​

ts
function getAttachmentType(id: string): string;
ts
function getAttachmentType(id: string): Promise<string>;

type 为附件类型，参考 mime/type，比如 image/png、text/plain 。 :::

示例代码 ​

ts
const type = utools.db.getAttachmentType("my-doc");
console.log("附件类型为", type);
ts
const type = await utools.db.promises.getAttachmentType("my-doc");
console.log("附件类型为", type);

utools.db.replicateStateFromCloud() / utools.db.promises.replicateStateFromCloud() ​

云端数据状态复制

类型定义 ​

ts
function replicateStateFromCloud(): State;
ts
function replicateStateFromCloud(): Promise<State>;
State 类型定义
ts
type State = null | 0 | 1;

null: 未开启云端同步 0: 云端同步已完成 1: 云端同步中

示例代码 ​

ts
const state = utools.db.replicateStateFromCloud();
if (state === 1) {
  console.log("云端同步中");
} else {
  console.log("云端同步已完成");
}
ts
const state = await utools.db.promises.replicateStateFromCloud();
if (state === 1) {
  console.log("云端同步中");
} else {
  console.log("云端同步已完成");
}

Copyright © 2019-present 福州猿力信息科技有限公司