tbdb 0.0.0

package/dist/adapter/MongoDB/MongoDBAdapter.d.ts

@@ -0,0 +1,59 @@
+import { ITableDBAdapterInstance, ITableDBAdapter, ITableDoc, ITableFindOptions, ITableUpdateOptions, ITableUpdateResult, ITableInsertResult, ITableSetOptions, ITableSetResult, ITableDeletedResult, ITableDefineIndexesOptions, ITableIndexConfig, ITableDeleteOptions } from "../adapter";
+import { ITableFilter, ITableUpdateOp } from "../../core/types";
+import { Collection } from "mongodb";
+export declare function MongoDBAdapter(config: {
+    auth: string;
+    dbName: string;
+}): ITableDBAdapter;
+export declare class MongoDBAdapterInstance implements ITableDBAdapterInstance {
+    collection: Collection;
+    name: string;
+    constructor(collection: Collection);
+    /** 获取一个文档 */
+    get(id: any): Promise<ITableDoc | void>;
+    /** 设置一个文档 */
+    set(id: any, value: ITableDoc): Promise<void>;
+    /** 删除一个文档 */
+    delete(id: any): Promise<void>;
+    /** 检查文档是否存在 */
+    has(id: any): Promise<boolean>;
+    /** 获取文档数量 */
+    count(filter?: ITableFilter): Promise<number>;
+    /** 清空所有文档 */
+    clear(): Promise<void>;
+    /** 清除所有数据和索引 */
+    clearAll(): Promise<void>;
+    /** 删除所有数据和索引 */
+    drop(): Promise<void>;
+    close(): Promise<void>;
+    /** 查找多个文档 */
+    findMany(filter: ITableFilter, options?: ITableFindOptions): Promise<ITableDoc[]>;
+    /** 查找单个文档 */
+    findOne(filter: ITableFilter, options?: ITableFindOptions): Promise<ITableDoc | void>;
+    /** 修改单个现有文档 */
+    updateOne(filter: ITableFilter, updateOp: ITableUpdateOp, options?: ITableUpdateOptions): Promise<ITableUpdateResult>;
+    /** 修改多个现有文档 */
+    updateMany(filter: ITableFilter, updateOp: ITableUpdateOp, options?: ITableUpdateOptions): Promise<ITableUpdateResult>;
+    /** 批量更新多个文档 */
+    bulkUpdate(updates: {
+        filter: ITableFilter;
+        updateOp: ITableUpdateOp;
+        options?: ITableUpdateOptions;
+    }[]): Promise<ITableUpdateResult>;
+    /** 插入新文档 */
+    insertMany(docs: ITableDoc[]): Promise<ITableInsertResult>;
+    /** 设置多个文档 */
+    setMany(docs: ITableDoc[], options?: ITableSetOptions): Promise<ITableSetResult>;
+    /** 删除多个文档 */
+    deleteMany(filter: ITableFilter): Promise<ITableDeletedResult>;
+    /** 删除单个文档 */
+    deleteOne(filter: ITableFilter, options?: ITableDeleteOptions): Promise<ITableDeletedResult>;
+    /** 定义索引 */
+    defineIndexes(indexes: ITableIndexConfig[], options?: ITableDefineIndexesOptions): Promise<void>;
+    /** 删除所有索引 */
+    dropIndexes(): Promise<void>;
+    /** 压缩数据库文件 */
+    compact(): Promise<void>;
+    /** 内部方法：将 MongoDB 返回的 _id  转换为文档 id */
+    __mongodbIds_to_docIds(_ids: any[]): Promise<any[]>;
+}

package/dist/adapter/MongoDB/index.d.ts

@@ -0,0 +1 @@
+export { MongoDBAdapter } from "./MongoDBAdapter";

package/dist/adapter/MongoDB/lib/docType.d.ts

@@ -0,0 +1,9 @@
+import { ITableValue } from "../../../core/types";
+/**
+ * ITableValue 转换为 MongoDB 可存储格式
+ */
+export declare function jsToMongo(data: any, parseFilter?: boolean): any | Promise<any>;
+/**
+ * MongoDB 数据还原为原始 ITableValue 类型
+ */
+export declare function mongoToJs(data: any): ITableValue;

package/dist/adapter/MongoDB/lib/normalizeProjection.d.ts

@@ -0,0 +1,13 @@
+import { Document } from "mongodb";
+/** 规范化投影参数（仅转换格式，不处理 _id） */
+export declare function normalizeProjection(proj?: string[] | Record<string, 1 | -1>): Document | undefined;
+/**
+ * 构建最终的 MongoDB projection 选项
+ *
+ * 规则：
+ * - 无 projection：默认排除 _id
+ * - 只有 { _id: 1 }：返回全部字段（包括 _id）
+ * - 指定字段但无 _id：排除 _id
+ * - 指定字段且有 _id：按用户设置
+ */
+export declare function buildProjection(userProjection?: string[] | Record<string, 1 | -1>): Document | undefined;

package/dist/adapter/MongoDB/lib/normalizeSort.d.ts

@@ -0,0 +1,3 @@
+import { Sort } from "mongodb";
+/** 规范化排序参数 */
+export declare function normalizeSort(sort?: string[] | Record<string, 1 | -1>): Sort | undefined;

package/dist/adapter/MongoDB/test/base.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter/MongoDB/test/docType.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter/MongoDB/test/fitler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter/MongoDB/test/getTestMongo.d.ts

@@ -0,0 +1 @@
+export declare function getTestAdapter(tableName?: string): Promise<import("../../adapter").ITableDBAdapterInstance>;

package/dist/adapter/MongoDB/test/setMany.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter/MongoDB/test/updateOne.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter/MongoDB/useMongoDB.d.ts

@@ -0,0 +1,4 @@
+export declare const useMongoDB: (config: {
+    auth: string;
+    dbName: string;
+}) => Promise<import("mongodb").Db>;

package/dist/adapter/SQLite/SQLiteAdapter.d.ts

@@ -0,0 +1,49 @@
+import Database from "better-sqlite3";
+import { ITableDBAdapterInstance, ITableDBAdapter, ITableDefineIndexesOptions, ITableDeletedResult, ITableDeleteOptions, ITableDoc, ITableFindOptions, ITableIndexConfig, ITableInsertResult, ITableSetOptions, ITableSetResult, ITableUpdateOptions, ITableUpdateResult } from "../adapter";
+import { ITableFilter, ITableUpdateOp } from "../../core/types";
+export declare function SQLiteAdapter(config: {
+    filename: string;
+    safe?: boolean | "full";
+    zstd?: boolean;
+}): ITableDBAdapter;
+export declare class SQLiteAdapterInstance implements ITableDBAdapterInstance {
+    private db;
+    private tableName;
+    private config;
+    name: string;
+    constructor(db: Database.Database, tableName: string, config: {
+        filename: string;
+        safe?: boolean | "full";
+        zstd?: boolean;
+    });
+    /**
+     * 将对象中所有 undefined 转换为 null，保持 MongoDB 一致性
+     * 注意：不处理 Map、Set、Date、Buffer 等特殊类型，由 serialize/deserialize 处理
+     */
+    private normalizeUndefined;
+    get(id: any): Promise<ITableDoc | void>;
+    set(id: any, value: ITableDoc): Promise<void>;
+    delete(id: any): Promise<void>;
+    has(id: any): Promise<boolean>;
+    count(filter?: ITableFilter): Promise<number>;
+    clear(): Promise<void>;
+    clearAll(): Promise<void>;
+    drop(): Promise<void>;
+    close(): Promise<void>;
+    findMany(filter: ITableFilter, options?: ITableFindOptions): Promise<ITableDoc[]>;
+    findOne(filter: ITableFilter, options?: ITableFindOptions): Promise<ITableDoc | void>;
+    updateMany(filter: ITableFilter, updateOp: ITableUpdateOp<ITableDoc>, options?: ITableUpdateOptions): Promise<ITableUpdateResult>;
+    bulkUpdate(updates: {
+        filter: ITableFilter;
+        updateOp: ITableUpdateOp<ITableDoc>;
+        options?: ITableUpdateOptions;
+    }[]): Promise<ITableUpdateResult>;
+    updateOne(filter: ITableFilter, updateOp: ITableUpdateOp<ITableDoc>, options?: ITableUpdateOptions): Promise<ITableUpdateResult>;
+    insertMany(docs: ITableDoc[]): Promise<ITableInsertResult>;
+    setMany(docs: Partial<ITableDoc>[], options?: ITableSetOptions): Promise<ITableSetResult>;
+    deleteMany(filter: ITableFilter): Promise<ITableDeletedResult>;
+    deleteOne(filter: ITableFilter, options?: ITableDeleteOptions): Promise<ITableDeletedResult>;
+    defineIndexes(indexes: ITableIndexConfig[], options?: ITableDefineIndexesOptions): Promise<void>;
+    dropIndexes(): Promise<void>;
+    compact(): Promise<void>;
+}

package/dist/adapter/SQLite/index.d.ts

@@ -0,0 +1 @@
+export { SQLiteAdapter } from "./SQLiteAdapter";

package/dist/adapter/SQLite/test/sqlite-find-sort.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter/SQLite/test/sqlite-merge-union.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter/SQLite/test/sqlite-overwrite.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter/SQLite/test/sqlite-zstd.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter/SQLite/test/sqlite.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter/SQLite/utils/matcher.d.ts

@@ -0,0 +1,9 @@
+import { ITableFilter } from "../../../core/types";
+/**
+ * 判断文档是否匹配 Filter
+ * 用于 SQLite 自定义函数 JsMatch
+ *
+ * @param doc 纯 JS 对象（已反序列化）
+ * @param filter 查询条件
+ */
+export declare function matches(doc: any, filter: ITableFilter): boolean;

package/dist/adapter/SQLite/utils/mongoToSql.d.ts

@@ -0,0 +1,10 @@
+import { ITableFilter } from "../../../core/types";
+import { ITableFindOptions } from "../../adapter";
+export interface ISqlQuery {
+    where: string;
+    params: any[];
+    sort?: string;
+    limit?: number;
+    offset?: number;
+}
+export declare function mongoToSql(filter: ITableFilter, options?: ITableFindOptions): Promise<ISqlQuery>;

package/dist/adapter/SQLite/utils/patch.d.ts

@@ -0,0 +1,10 @@
+import { ITableUpdateOp } from "../../../core/types";
+/**
+ * 在内存中对文档应用 MongoDB 风格的更新操作
+ * 直接修改传入的 doc 对象
+ * @returns 是否发生了修改
+ */
+export declare function applyUpdate(doc: any, op: ITableUpdateOp): boolean;
+export declare function isPlainObject(v: any): any;
+export declare function flattenObject(obj: any, prefix?: string, result?: any): any;
+export declare function deepMergeWithArrayUnion(target: any, source: any): any;

package/dist/adapter/SQLite/utils/serializer.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 将 JS 对象序列化为 SQLite 可存储的 JSON 友好格式
+ * 异步版本：支持 Blob 转 Base64
+ */
+export declare function serialize(value: any): Promise<any>;
+/**
+ * 同步版本：不支持 Blob (除非 Blob逻辑是sync的，但通常不是)
+ * 用于 JsPatch 等同步环境
+ */
+export declare function serializeSync(value: any): any;
+/**
+ * 将 SQLite 存储的 JSON 格式反序列化为 JS 对象
+ */
+export declare function deserialize(value: any): any;

package/dist/adapter/SQLite/utils/zstdHelper.d.ts

@@ -0,0 +1,12 @@
+import { Database } from "better-sqlite3";
+/**
+ * 检查文件是否为 ZSTD 压缩文件 (Magic Number: 0xFD2FB528)
+ */
+export declare function isZstdFile(filepath: string): boolean;
+/**
+ * 如果数据库文件存在且被 zstd 压缩，则解压它。
+ * @param filename 数据库文件名
+ */
+export declare function checkAndDecompressDb(filename: string): void;
+export declare function prepareForCompression(db: Database): void;
+export declare function compressFile(filename: string): void;

package/dist/adapter/adapter.d.ts

@@ -0,0 +1,237 @@
+import { ITableFilter, ITableValue, ITableUpdateOp } from "../core/types";
+export type ITableDoc = Record<string, ITableValue> & {
+    id: any;
+    _createDate?: Date;
+    _updateDate?: Date;
+    _deleteDate?: Date;
+    _isDeleted?: boolean;
+};
+export type ITableDBAdapter = {
+    name: string;
+    useAdapterInstance(tableName: string): Promise<ITableDBAdapterInstance>;
+};
+export interface ITableDBAdapterInstance {
+    name: string;
+    get(id: any): Promise<ITableDoc | void>;
+    set(id: any, value: Partial<ITableDoc>): Promise<void>;
+    delete(id: any): Promise<void>;
+    has(id: any): Promise<boolean>;
+    count(filter?: ITableFilter): Promise<number>;
+    /** 清空所有数据，不包括索引 */
+    clear(): Promise<void>;
+    /** 清除所有数据和索引 */
+    clearAll(): Promise<void>;
+    /** 删除表 */
+    drop(): Promise<void>;
+    /** 安全的关闭连接 */
+    close(): Promise<void>;
+    /** 查找多个文档 */
+    findMany(filter: ITableFilter, options?: ITableFindOptions): Promise<ITableDoc[]>;
+    /** 查找单个文档 */
+    findOne(filter: ITableFilter, options?: ITableFindOptions): Promise<ITableDoc | void>;
+    /** 修改单个现有文档
+     *  如果没有匹配的文档，则不进行任何操作
+     *  只会修改第一个匹配的文档
+     */
+    updateOne(filter: ITableFilter, updateOp: ITableUpdateOp<ITableDoc>, options?: ITableUpdateOptions): Promise<ITableUpdateResult>;
+    /** 修改多个现有文档
+     *  如果没有匹配的文档，则不进行任何操作
+     *  根据 filter 的匹配结果，可能会修改多个文档
+     */
+    updateMany(filter: ITableFilter, updateOp: ITableUpdateOp<ITableDoc>, options?: ITableUpdateOptions): Promise<ITableUpdateResult>;
+    /** 批量修改多个文档
+     *  根据每个 update 的 filter 进行匹配 ，可能会修改多个文档
+     */
+    bulkUpdate(updates: {
+        filter: ITableFilter;
+        updateOp: ITableUpdateOp<ITableDoc>;
+        options?: ITableUpdateOptions;
+    }[]): Promise<ITableUpdateResult>;
+    /** 插入新文档
+     *
+     *  如果目标文档的 ID 已存在，会忽略，不会进行覆盖，并且继续插入其他文档
+     */
+    insertMany(docs: Partial<ITableDoc>[]): Promise<ITableInsertResult>;
+    /** 设置多个文档
+     *
+     * 根据 doc 的 id 匹配，如果已存在则进行 update 否则进行 insert\
+     * 可以通过 options 控制只插入新文档或只覆盖已存在文档
+     */
+    setMany(docs: Partial<ITableDoc>[], options?: ITableSetOptions): Promise<ITableSetResult>;
+    /** 删除多个文档
+     *
+     * 根据 filter 的匹配结果，可能会删除多个文档
+     */
+    deleteMany(filter: ITableFilter): Promise<ITableDeletedResult>;
+    /** 删除单个文档
+     *
+     * 只会删除第一个匹配的文档
+     */
+    deleteOne(filter: ITableFilter, options?: ITableDeleteOptions): Promise<ITableDeletedResult>;
+    /**
+     * 定义索引
+     * 指定 data 中哪些字段需要创建索引，可以加快查询速度
+     *
+     */
+    defineIndexes(indexes: ITableIndexConfig[], options?: ITableDefineIndexesOptions): Promise<void>;
+    /** 删除所有索引 */
+    dropIndexes(): Promise<void>;
+    /**
+     * 在插入或更新文档前，进行检查和修正\
+     *  直接修改传入的 doc 对象\
+     */
+    onCheckInputDoc?(doc: ITableDoc | void): any;
+    /**
+     * 在输出文档前，进行检查和修正\
+     * 直接修改传入的 doc 对象\
+     */
+    onCheckOutputDoc?(doc: ITableDoc | void): any;
+    /**
+     * 在 fitler 实际使用前，进行检查和修正\
+     * 直接修改传入的 filter 对象\
+     */
+    onCheckFilter?(filter: ITableFilter): any;
+    /** 压缩数据库文件，回收空间
+     *
+     * mongodb 会使用 compact 命令进行压缩\
+     * sqlite 会使用 VACUUM 命令进行压缩\
+     */
+    compact(): Promise<void>;
+}
+export interface ITableFindOptions {
+    /** 限制返回的记录数（每一页） */
+    limit?: number;
+    /** 跳过的记录数（页码 * 每页记录数） */
+    offset?: number;
+    /** 投影字段列表
+     *
+     *  可以是字符串数组，表示包含的字段列表\
+     *  也可以是字段映射对象，1 表示包含该字段，-1 表示排除该字段\
+     *  不能同时包含和排除字段
+     *
+     *  可以是 plv 预设投影名称
+     */
+    projection?: string[] | Record<string, 1 | -1>;
+    /** 排序字段列表
+     *
+     * 可以是字符串数组， 前面加 `-` 表示降序，\
+     * 也可以是字段映射对象，1 表示升序，-1 表示降序
+     */
+    sort?: string[] | Record<string, 1 | -1>;
+    /** 排序时按自然排序， numericOrdering:true locale: "zh" */
+    naturalSort?: boolean;
+    /** 排序时是否区分大小写，默认区分 */
+    caseSensitive?: boolean;
+    /** 排序时是否进行数字排序，默认不进行 */
+    numericOrdering?: boolean;
+    /** 是否忽略标记删除逻辑，默认 false */
+    ignoreMarkDelete?: boolean;
+}
+export interface ITableUpdateOptions {
+    /** 是否在没有匹配的文档时插入一个新文档，然后再进行更新操作 */
+    upsert?: boolean;
+    /** 排序字段列表
+     *  只在 updateOne 中有效，用于当 filter 有多个匹配文档时，优先更新哪个文档
+     *
+     * 可以是字符串数组， 前面加 `-` 表示降序，\
+     * 也可以是字段映射对象，1 表示升序，-1 表示降序
+     */
+    sort?: string[] | Record<string, 1 | -1>;
+}
+export interface ITableDeleteOptions {
+    /** 排序字段列表
+     *  用于当 filter 有多个匹配文档时，优先删除哪个文档
+     *
+     * 可以是字符串数组， 前面加 `-` 表示降序，\
+     * 也可以是字段映射对象，1 表示升序，-1 表示降序
+     */
+    sort?: string[] | Record<string, 1 | -1>;
+    /** 是否忽略标记删除逻辑，直接物理删除文档，默认 false */
+    readDelete?: boolean;
+}
+export interface ITableSetOptions {
+    /** 是否合并对象字段而不是覆盖，默认 false
+     *
+     * - 对于数组的合并，采用的是集合合并，
+     *   即新的数组元素检查原数组中是否已存在，不存在就添加，类似于 `$addToSet` 操作，遵循的是 BSON 值的比较规则
+     */
+    merge?: boolean;
+    /** 是否对 doc 进行覆盖而不是浅合并，把新文档完全替换掉已存在的文档 */
+    overwrite?: boolean;
+    /** 是否只插入新文档，已存在的文档不进行更新 */
+    insertOnly?: boolean;
+    /** 是否只更新已存在的文档，不存在的文档不进行插入 */
+    updateOnly?: boolean;
+}
+export interface ITableDefineIndexesOptions {
+    /** 是否强制重新创建索引，默认 false */
+    rebuild?: boolean;
+}
+export interface ITableUpdateResult {
+    /** 匹配到的文档数量 */
+    matchedCount: number;
+    /** 成功修改的文档数量 */
+    modifiedCount: number;
+    /** 如果进行了 upsert 操作，返回新插入的文档 ID 列表 */
+    upsertedIds?: any[];
+}
+export interface ITableInsertResult {
+    /** 成功插入的文档数量 */
+    insertedCount: number;
+    /** 因为已存在而跳过的文档数量 */
+    skippedCount: number;
+    /** 成功插入的文档 ID 列表 */
+    insertedIds: string[];
+    /** 已存在未插入的文档 ID 列表 */
+    skippedIds: string[];
+}
+export interface ITableSetResult {
+    /** 成功插入的新文档数量 */
+    insertedCount: number;
+    /** 因为已存在而被覆盖的文档数量 */
+    overwriteCount: number;
+    /** 成功插入的新文档 ID 列表 */
+    insertedIds: string[];
+}
+export interface ITableDeletedResult {
+    /** 成功删除的文档数量 */
+    deletedCount: number;
+}
+export type ITableIndexConfig = {
+    /**
+     * 要索引的字段
+     *
+     * 可以用 `.` 表示嵌套字段\
+     * 可以用对象表示复合索引，如 { city: 1, age: -1 } 表示对 city 升序，age 降序,\
+     * 复合索引的字段顺序很重要，先按 city 排序，再按 age 排序
+     */
+    key: string | Record<string, 1 | -1>;
+    /** 索引名称
+     *  默认为字段名或复合字段名的连接字符串 + "_1" ，MongoDB 默认规则
+     */
+    name?: string;
+    /** 索引类型 */
+    type?: string;
+    /** 是否禁用该索引（删除此索引）
+     *  需要指定 name 选项才能删除对应的索引
+     */
+    disabled?: boolean;
+    /** 是否唯一，默认 false */
+    unique?: boolean;
+    /** 语言/区域设置  */
+    locale?: string | "en" | "zh" | "jp";
+    /** 是否按数字排序\
+     *  如果为真，则 '2' 会排在 '10' 前面
+     */
+    numericOrdering?: boolean;
+    /**
+     * 是否使用自然排序
+     * 相当于 numericOrdering = true, locale = "zh"
+     */
+    naturalSort?: boolean;
+    /** 区分大小写
+     *
+     *  默认 true，区分大小写，如果为 false，则 'a' 和 'A' 视为相同字符
+     */
+    caseSensitive?: boolean;
+};

package/dist/benchmark/1-single-crud.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/benchmark/2-batch-crud.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/benchmark/3-paging.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/benchmark/base.try.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/benchmark/utils.d.ts

@@ -0,0 +1,15 @@
+import { Table } from "../core/Table";
+import { ITableDoc } from "../adapter/adapter";
+export interface IBenchDoc extends ITableDoc {
+    id: string;
+    name: string;
+    age: number;
+    tags: string[];
+    meta: {
+        created: number;
+        updated: number;
+    };
+}
+export declare function createBenchTable(name: string, enableMarkDelete?: boolean): Promise<Table<IBenchDoc, import("../core/Table").IPlvMap>>;
+export declare function generateDoc(i: number): IBenchDoc;
+export declare function prepareTableData(table: Table<IBenchDoc>, count: number): Promise<void>;