tbdb 0.0.0

package/dist/core/Table.d.ts

@@ -0,0 +1,240 @@
+import { ITableDBAdapterInstance, ITableDBAdapter, ITableDefineIndexesOptions, ITableDeletedResult, ITableDeleteOptions, ITableDoc, ITableFindOptions, ITableIndexConfig, ITableInsertResult, ITableSetOptions, ITableSetResult, ITableUpdateOptions, ITableUpdateResult } from "../adapter/adapter";
+import { exportBinary, exportBinaryToFile, importBinary, importBinaryFromFile } from "./backup";
+import { __check_filter, __check_find_options, __check_input_doc, __check_output_doc, __check_update_op } from "./check";
+import { ICursorPagingOptions, IReCursorPaging, IReSkipPaging, ISkipPagingOptions } from "./list";
+import { __schema_init, ISchemaHints } from "./schema";
+import { ITableFilter, ITableUpdateOp } from "./types";
+export interface ITableOptions<TSchema, TPlv extends IPlvMap = IPlvMap> {
+    /** Talbe 名称
+     *
+     * 会作为存储时的表名或集合名使用
+     */
+    name: string;
+    /** 文档 schema 定义
+     *
+     * 使用 `fzz dto` 来定义，可以用来校验文档结构，定义索引等
+     */
+    schema?: TSchema;
+    /** 索引定义
+     *
+     *  优先级大于 schema 的索引定义
+     */
+    indexes?: ITableIndexConfig[];
+    /** 指定 Adapter */
+    adapter?: ITableDBAdapter;
+    /** 是否启用标记删除功能 */
+    enableMarkDelete?: boolean;
+    /** 是否启用目录树功能 */
+    enableTree?: boolean;
+    /** 预设投影列表 */
+    projections?: TPlv;
+}
+export interface ITableGetBaseOptions {
+    /** 是否忽略标记删除的文档 */
+    ignoreMarkDelete?: boolean;
+}
+export interface IPlvMap {
+    [plvName: string]: string[] | {
+        [field: string]: 1 | -1;
+    };
+}
+/**
+ * 数据表对象
+ * 实现类似 MongoDB 的 NoSQL 数据存储 API
+ *
+ * 底层可以使用 SQLite, indexedDB, MongoDB
+ */
+export declare class Table<TSchema extends ITableDoc = ITableDoc, TPlv extends IPlvMap = IPlvMap> {
+    static globalAdapter?: ITableDBAdapter;
+    name: string;
+    options: ITableOptions<TSchema, TPlv>;
+    adapter: ITableDBAdapterInstance;
+    schema: TSchema;
+    inited: Promise<boolean>;
+    constructor(tableOptions: ITableOptions<TSchema, TPlv>);
+    init(): Promise<boolean>;
+    __schema_hints: ISchemaHints;
+    __schema_init: typeof __schema_init;
+    __check_filter: typeof __check_filter;
+    __check_output_doc: typeof __check_output_doc;
+    __check_find_options: typeof __check_find_options;
+    __check_input_doc: typeof __check_input_doc;
+    __check_update_op: typeof __check_update_op;
+    /** 获取单个文档 */
+    get(id: any, options?: ITableGetBaseOptions): Promise<TSchema | void>;
+    /** 设置单个文档 */
+    set(id: any, doc: Partial<TSchema>): Promise<void>;
+    /** 删除单个文档 */
+    delete(id: any, options?: ITableDeleteOptions): Promise<void>;
+    /** 检查单个文档是否存在 */
+    has(id: any, options?: ITableGetBaseOptions): Promise<boolean>;
+    /** 统计文档数量 */
+    count(filter?: ITableFilter, options?: ITableGetBaseOptions): Promise<number>;
+    /** 清空所有文档 */
+    clear(): Promise<void>;
+    /** 清除所有文档和索引 */
+    clearAll(): Promise<void>;
+    /** 关闭连接 */
+    close(): Promise<void>;
+    /** 根据 filter 查找多个文档
+     *
+     * 可以使用选项中的 `limit`,`offset`, `pageIndex`, `sort` 来分页查询结果，但更
+     * 推荐使用 `listPaging` 和 `listIdPaging` 来进行分页查询
+     *
+     * fitler 用法：
+     * 1. 精确匹配: `{ field: value }`, `$eq`
+     * 2. 比较操作符:`$gt`, `$gte`, `$lt`, `$lte`, `$ne`
+     * 3. 包含操作符: `$in`, `$nin`
+     * 4. 逻辑操作符: `$and`, `$or`, `$not`，`$nor`
+     * 5. 字符串匹配: `$like`, `$regex`
+     * 6. 数组操作: `$elemMatch`, `$all`, `$size`
+     * 7. 存在操作: `$exists`
+     */
+    findMany(filter: ITableFilter, options?: ITableFindOptions): Promise<TSchema[]>;
+    /** 根据 filter 查找单个文档
+     *  如果有多个匹配的文档，则只返回第一个匹配的文档
+     *
+     * fitler 用法：
+     * 1. 精确匹配: `{ field: value }`, `$eq`
+     * 2. 比较操作符:`$gt`, `$gte`, `$lt`, `$lte`, `$ne`
+     * 3. 包含操作符: `$in`, `$nin`
+     * 4. 逻辑操作符: `$and`, `$or`, `$not`，`$nor`
+     * 5. 字符串匹配: `$like`, `$regex`
+     * 6. 数组操作: `$elemMatch`, `$all`, `$size`
+     * 7. 存在操作: `$exists`
+     */
+    findOne(filter: ITableFilter, options?: ITableFindOptions): Promise<TSchema | void>;
+    /** 修改单个现有文档
+     *
+     * 根据 filter 的匹配第一个文档，再根据 updateOp 进行更新
+     *
+     * updateOp 用法：
+     * 1. 设置字段： `$set`,`$unset`,`$setOnInsert`,`$rename`
+     * 2. 数值运算： `$inc`, `$mul`, `$min`, `$max`
+     * 3. 数组运算： `$push`, `$pop`, `$addToSet`, `$pull`
+     *
+     * @param options.upsert 如果没有匹配的文档，是否插入新文档，默认 false
+     * @param options.sort 如果 fitler 匹配多个文档，使用 sort 来决定更新哪一个文档
+     *
+     */
+    updateOne(filter: ITableFilter, updateOp: ITableUpdateOp<TSchema>, options?: ITableUpdateOptions): Promise<ITableUpdateResult>;
+    /** 修改多个现有文档
+     *
+     *  根据 filter 的匹配多个文档，再根据 updateOp 进行更新
+     *
+     *  updateOp 用法：
+     * 1. 设置字段： `$set`,`$unset`,`$setOnInsert`,`$rename`
+     * 2. 数值运算： `$inc`, `$mul`, `$min`, `$max`
+     * 3. 数组运算： `$push`, `$pop`, `$addToSet`, `$pull`
+     *
+     *
+     * @param options.upsert 如果没有匹配的文档，是否插入新文档，默认 false
+     */
+    updateMany(filter: ITableFilter, updateOp: ITableUpdateOp<TSchema>, options?: ITableUpdateOptions): Promise<ITableUpdateResult>;
+    /**
+     * 批量进行多次更新操作
+     */
+    bulkUpdate(updates: {
+        filter: ITableFilter;
+        updateOp: ITableUpdateOp<TSchema>;
+        options?: ITableUpdateOptions;
+    }[]): Promise<ITableUpdateResult>;
+    /** 插入新文档
+     *
+     *  如果目标文档的 ID 已存在，会忽略，不会进行覆盖，并且继续插入其他文档\n
+     *  文档必须有 ID 字段，如果没有 ID 字段会自动生成一个唯一 ID
+     */
+    insertMany(docs: Partial<TSchema>[]): Promise<ITableInsertResult>;
+    /** 插入单个新文档
+     *
+     * 如果目标文档的 ID 已存在，会忽略，不会进行覆盖\
+     * 相当于调用 `insertMany([doc])`
+     */
+    insertOne(doc: Partial<TSchema>): Promise<ITableInsertResult>;
+    /** 设置多个文档
+     *
+     * 根据 doc 的 id 匹配，如果已存在则进行 update 否则进行 insert\
+     *
+     * @param options.merge  是对存在 doc 进行深度合并而不是浅合并（Object.assign），深度合并时可以使用 `__overwrite__` 标记来强制覆盖子对象
+     * @param options.overwrite  是否对 doc 进行覆盖而不是浅合并，把新文档完全替换掉已存在的文档
+     * @param options.insertOnly  是否只插入新文档，已存在的文档不进行更新
+     * @param options.updateOnly  是否只更新已存在的文档，未存在的文档不进行插入
+     *
+     */
+    setMany(docs: Partial<TSchema>[], options?: ITableSetOptions): Promise<ITableSetResult>;
+    /** 删除多个文档
+     *
+     * 根据 filter 的匹配结果，可能会删除多个文档
+     *
+     * fitler 用法：
+     * 1. 精确匹配: `{ field: value }`, `$eq`
+     * 2. 比较操作符:`$gt`, `$gte`, `$lt`, `$lte`, `$ne`
+     * 3. 包含操作符: `$in`, `$nin`
+     * 4. 逻辑操作符: `$and`, `$or`, `$not`，`$nor`
+     * 5. 字符串匹配: `$like`, `$regex`
+     * 6. 数组操作: `$elemMatch`, `$all`, `$size`
+     * 7. 存在操作: `$exists`
+     */
+    deleteMany(filter: ITableFilter, options?: ITableDeleteOptions): Promise<ITableDeletedResult>;
+    /** 删除单个文档
+     *
+     * 只会删除第一个匹配的文档
+     *
+     * fitler 用法：
+     * 1. 精确匹配: `{ field: value }`, `$eq`
+     * 2. 比较操作符:`$gt`, `$gte`, `$lt`, `$lte`, `$ne`
+     * 3. 包含操作符: `$in`, `$nin`
+     * 4. 逻辑操作符: `$and`, `$or`, `$not`，`$nor`
+     * 5. 字符串匹配: `$like`, `$regex`
+     * 6. 数组操作: `$elemMatch`, `$all`, `$size`
+     * 7. 存在操作: `$exists`
+     *
+     * @param options.sort 如果 fitler 匹配多个文档，使用 sort 来决定删除哪一个文档
+     */
+    deleteOne(filter: ITableFilter, options?: ITableDeleteOptions): Promise<ITableDeletedResult>;
+    /** 定义索引
+     *
+     *  普通索引：\
+     *   [{ key: "fieldName"}]\
+     * 唯一索引：\
+     *   [{ key: "md5", unique: true }]\
+     * 复合索引：\
+     *  [{ key: { fieldA: 1, 'b.a': -1 }, unique: false }]\
+     * 禁用索引：\
+     *   [{ key: "fieldName", disabled: true }]\
+     * 自然排序：\
+     *  [{ key: "num", naturalSort: true }]\
+     */
+    defineIndexes(indexes: ITableIndexConfig[], options?: ITableDefineIndexesOptions): Promise<void>;
+    /** 清除所有索引 */
+    dropIndexes(): Promise<void>;
+    /** 压缩数据文件，清理碎片 */
+    compact(): Promise<void>;
+    /** 列出分页加载（使用 skip limit） */
+    listPaging<T = TSchema>(filter: any, options: ISkipPagingOptions & ITableGetBaseOptions): Promise<IReSkipPaging<T>>;
+    /** 列出分页加载（使用 cursor） */
+    listPagingByCursor<T = TSchema>(filter: any, options: ICursorPagingOptions): Promise<IReCursorPaging<T>>;
+    /** 遍历所有文档，批量处理 */
+    eachBatch(filter: any, options: {
+        pageSize?: number;
+        projection?: any;
+        sortKey?: string;
+        sortOrder?: 1 | -1;
+    } & ITableGetBaseOptions, eachFunc: (list: TSchema[], stop: () => void, batch: number) => Promise<void>): Promise<void>;
+    /** 遍历所有文档 */
+    forEach<T = TSchema>(filter: any, callbackfn: (value: T, index: number) => Promise<void>): Promise<void>;
+    /**
+     * 获取预设投影列表
+     */
+    plv(plvName: keyof TPlv): string[] | {
+        [field: string]: 1 | -1;
+    } | undefined;
+    /** 导出表数据为二进制格式 */
+    exportBinary: typeof exportBinary;
+    /** 从二进制格式导入表数据 */
+    importBinary: typeof importBinary;
+    /** 导出表数据为二进制文件 (Node.js) */
+    exportBinaryToFile: typeof exportBinaryToFile;
+    /** 从二进制文件导入表数据 (Node.js) */
+    importBinaryFromFile: typeof importBinaryFromFile;
+}

package/dist/core/backup.d.ts

@@ -0,0 +1,38 @@
+import type { Table } from "./Table";
+export interface IBackupOptions {
+    /** 是否压缩备份数据 gzip，默认 true */
+    compress?: boolean;
+    /** 备份进度回调，百分比 0~100 */
+    progress?: (percent: number) => void;
+}
+export interface IImportOptions {
+    /** 恢复进度回调，百分比 0~100 */
+    progress?: (percent: number) => void;
+    /**
+     *  是否在导入前清空现有数据，默认 false，即合并导入
+     *  如果设置为 true，会先清空表数据和索引，再导入
+     */
+    clear?: boolean;
+    /** 指定只恢复某些文档的 ID 列表，默认恢复所有文档*/
+    docIds?: string[];
+    /** 是否忽略索引恢复，默认 false，即恢复索引 */
+    ignoreIndexes?: boolean;
+}
+/** 备份为 ReadableStream (Web Standard) */
+export declare function exportBinaryStream(this: Table, options?: IBackupOptions): ReadableStream<Uint8Array>;
+/** 从 ReadableStream 恢复 (Web Standard) */
+export declare function importBinaryStream(this: Table, stream: ReadableStream<Uint8Array>, options?: IImportOptions): Promise<{
+    docsCount: number;
+}>;
+/** 备份 Table 到的数据和索引配置到二进制格式 (In-Memory) */
+export declare function exportBinary(this: Table, options?: IBackupOptions): Promise<Uint8Array>;
+/** 从二进制格式的数据恢复 Table 数据和索引配置 (In-Memory) */
+export declare function importBinary(this: Table, data: Uint8Array, options?: IImportOptions): Promise<{
+    docsCount: number;
+}>;
+/** 备份到文件 (Node.js Stream) */
+export declare function exportBinaryToFile(this: Table, filePath: string, options?: IBackupOptions): Promise<void>;
+/** 从文件恢复 (Node.js Stream) */
+export declare function importBinaryFromFile(this: Table, filePath: string, options?: IImportOptions): Promise<{
+    docsCount: number;
+}>;

package/dist/core/check.d.ts

@@ -0,0 +1,28 @@
+import { ITableDoc } from "../adapter/adapter";
+import { Table } from "./Table";
+import { ITableFilter, ITableUpdateOp } from "./types";
+/**
+ * 在 fitler 实际使用前，进行检查和修正
+ */
+export declare function __check_filter(this: Table, filter: ITableFilter, options?: {
+    ignoreMarkDelete?: boolean;
+    realDelete?: boolean;
+} & Record<string, any>): void;
+/**
+ * 在插入或更新文档前，进行检查和修正
+ */
+export declare function __check_input_doc(this: Table, doc: Partial<ITableDoc> | void): void;
+/**
+ * 在插入或更新文档前，进行检查和修正
+ */
+export declare function __check_find_options(this: Table, options?: {
+    projection?: any;
+}): void;
+/**
+ * 在输出文档前，进行检查和修正
+ */
+export declare function __check_output_doc(this: Table, doc: Partial<ITableDoc> | void): void;
+/**
+ * 在更新操作前，进行检查和修正
+ */
+export declare function __check_update_op(this: Table, updateOp: ITableUpdateOp | void): void;

package/dist/core/defineTable.d.ts

@@ -0,0 +1,26 @@
+import { ITableDBAdapter, ITableDoc } from "../adapter/adapter";
+import { ITableOptions, Table } from "./Table";
+/** 定义一个 Table，返回一个 useTable 函数
+ *
+ *  useTable 函数调用后返回表实例（单例）
+ *
+ * @param tableOptions Table 的配置选项
+ *
+ * @example
+ * ```ts
+ *
+ *  const useUserTable = defineTable({name: "user"})
+ *
+ *  // 在需要使用的地方
+ *  const userTable = await useUserTable()
+ *
+ *
+ * // 如果要指定 adapter
+ * const useCustomTable = defineTable({adapter : SQLiteAdapter({filename: ":memory:"})})
+ */
+export declare function defineTable<TSchema extends ITableDoc = ITableDoc>(tableOptions: ITableOptions<TSchema>): UseTalbeFunction<TSchema>;
+export type UseTalbeFunction<TSchema extends ITableDoc = ITableDoc> = (opitons?: {
+    adapter?: ITableDBAdapter;
+}) => Promise<Table<TSchema>>;
+/** 定义全局的数据库适配器（SQLite/MongoDB） */
+export declare function defineGlobalDBAdapter(adapter: ITableDBAdapter): void;

package/dist/core/join.d.ts

@@ -0,0 +1,23 @@
+import { Table } from "./Table";
+export interface ITableJoinOp {
+    /** 目标表 */
+    table: Table;
+    /** 本地键的字段名 */
+    localKey: string;
+    /** 目标键的字段名 */
+    targetKey: string;
+    /** 新本地键字段名
+     * 默认与 localKey 相同，会覆盖 localKey 字段。\
+     * 设置了新本地键字段名后，会新增该字段，保留原 localKey 字段。
+     */
+    newLocalKey?: string;
+    /** 目标表的投影字段列表 */
+    projection?: string[] | Record<string, 1 | -1>;
+}
+/** 连接多个 Table 的文档
+ *
+ * 根据文档中的 localKey 字段值，去目标表中查找对应的文档，并将目标文档添加到本地文档中。\
+ * 支持一对一和一对多（数组）的连接关系。
+ *
+ */
+export declare function joinListWithTable(list: any[], joinOps: ITableJoinOp[]): Promise<any[]>;

package/dist/core/list.d.ts

@@ -0,0 +1,87 @@
+import { Table } from "./Table";
+import { ITableJoinOp } from "./join";
+import { ITableFilter } from "./types";
+export interface ISkipPagingOptions {
+    /** 当前页码 */
+    pageIndex?: number;
+    /** 每页数量 */
+    pageSize?: number;
+    /** 投影字段列表
+     *
+     *  可以是字符串数组，表示包含的字段列表\
+     *  也可以是字段映射对象，1 表示包含该字段，-1 表示排除该字段\
+     *  不能同时包含和排除字段
+     */
+    projection?: string[] | Record<string, 1 | -1>;
+    /** 排序字段列表 */
+    sort?: any;
+    /** 获取总数 */
+    getTotal?: boolean;
+    /** 排序时是否区分大小写，默认区分 */
+    caseSensitive?: boolean;
+    /** 强制自然排序 */
+    naturalSort?: boolean;
+    /** 连接其他表格，根据 result.list 中的字段，把其他表的字典添加到 result */
+    join?: ITableJoinOp[];
+}
+export interface IReSkipPaging<T> {
+    /** 当前页码 */
+    pageIndex: number;
+    /** 每页记录数 */
+    pageSize: number;
+    /** 总记录数，仅当 options.getTotal 为 true 时返回 */
+    total?: number;
+    /** 是否有下一页 */
+    hasNext?: boolean;
+    /** 记录列表 */
+    list: T[];
+}
+/** 分页列表查询 (skip/limit)
+ *
+ *  采用分页查询，会排序全部数据然后跳过前面的数据，效率较低，不推荐在大数据量时使用
+ */
+export declare function listPagingBySkip<T>(table: Table, filter: ITableFilter, options: ISkipPagingOptions & {
+    ignoreMarkDelete?: boolean;
+}): Promise<IReSkipPaging<T>>;
+export interface ICursorPagingOptions {
+    /** 每页数量 */
+    pageSize?: number;
+    /**
+     * 下一页的游标
+     * (第一页传 undefined/null)
+     */
+    cursor?: any;
+    /**
+     * 排序字段
+     * ⚠️ 注意：游标分页要求排序字段的值必须是唯一的，或者结合 ID 使用。
+     * 为了性能和实现简单，这里建议使用具有唯一性的字段（如 id, createdTime(高精度), 或 uuid）
+     * 默认为 '_id'
+     */
+    sortKey?: string;
+    /** 排序方向: 1 升序, -1 降序 (默认 1) */
+    sortOrder?: 1 | -1;
+    /** 投影字段 */
+    projection?: string[] | Record<string, 1 | -1>;
+    /** 是否忽略标记删除 */
+    ignoreMarkDelete?: boolean;
+    /** 连接其他表格，根据 result.list 中的字段，把其他表的字典添加到 result */
+    join?: ITableJoinOp[];
+}
+export interface IReCursorPaging<T> {
+    /** 记录列表 */
+    list: T[];
+    /** 下一页的游标 (如果没有下一页则为 null) */
+    nextCursor: any | null;
+    /** 是否有下一页 */
+    hasNext: boolean;
+}
+/**
+ * 游标分页查询 (Cursor Based)
+ *
+ * 🚀 高性能分页方案
+ *
+ * ⚠️ 限制：
+ * 1. 只能支持单字段排序（或依赖该字段的唯一性）
+ * 2. 无法直接跳转到特定页码（只能“下一页”）
+ */
+export declare function listPagingByCursor<T>(table: Table, filter: ITableFilter, options: ICursorPagingOptions): Promise<IReCursorPaging<T>>;

package/dist/core/schema.d.ts

@@ -0,0 +1,9 @@
+import { Table } from "./Table";
+/**
+ * 对于标记为 isUUID 的字段，记录其路径信息
+ * 在存储为字符串时，可以进行 UUID 格式验证
+ */
+export interface ISchemaHints {
+    UUIDPaths: string[][];
+}
+export declare function __schema_init(this: Table): Promise<void>;