@aiao/rxdb 0.0.1

package/README.md

@@ -0,0 +1 @@
+# rxdb

package/RxDB.d.ts

@@ -0,0 +1,51 @@
+import { Observable } from 'rxjs';
+import { SetRequired } from 'type-fest';
+import { EntityManager } from './entity/EntityManager';
+import { AdapterFactory, RxDBAdapters } from './rxdb-adapter';
+import { RxDBEvent, RxDBEventMap } from './rxdb-events';
+import { Plugin } from './rxdb-plugin';
+import { RxDBContext, RxDBOptions } from './rxdb.interface';
+import { SchemaManager } from './schema/SchemaManager';
+type EventListener<T> = (event: T) => void;
+type RxDBConfig = SetRequired<RxDBOptions, 'relationQueryDeep'>;
+/**
+ * RxDB
+ */
+export declare class RxDB {
+    #private;
+    /**
+     * Schema 管理
+     */
+    readonly schema: SchemaManager;
+    /**
+     * Entity 管理
+     */
+    readonly em: EntityManager;
+    /**
+     * 设置环境上下文
+     */
+    get context(): RxDBContext;
+    set context(context: RxDBContext);
+    readonly options: RxDBConfig;
+    constructor(options: RxDBOptions);
+    /**
+     * 注册适配器
+     */
+    adapter<K extends keyof RxDBAdapters>(adapterName: K, adapter: AdapterFactory): this;
+    /**
+     * 获取适配器
+     */
+    getAdapter<K extends keyof RxDBAdapters>(adapterName: K): Observable<RxDBAdapters[K]>;
+    /**
+     * 安装插件
+     */
+    use<Options = any>(plugin: Plugin<Options>, options?: Options): this;
+    /**
+     * 连接适配器
+     */
+    connect<K extends keyof RxDBAdapters>(adapterName: K): Observable<import('./rxdb-adapter').IRxDBAdapter>;
+    addEventListener<T extends keyof RxDBEventMap>(type: T, listener: EventListener<RxDBEventMap[T]>): void;
+    removeEventListener<T extends keyof RxDBEventMap>(type: T, listener: EventListener<RxDBEventMap[T]>): void;
+    dispatchEvent(event: RxDBEvent): void;
+}
+export {};

package/RxDBError.d.ts

@@ -0,0 +1,13 @@
+/**
+ * RxDB 基础错误类型
+ */
+export declare class RxDBError extends Error {
+    messageTemplate: string;
+    data: {
+        [name: string]: string | number;
+    };
+    constructor(messageTemplate: string, data?: {
+        [name: string]: string | number;
+    });
+    toString(): string;
+}

package/entity/@Entity.d.ts

@@ -0,0 +1,29 @@
+import { EntityMetadataOptions } from './entity-metadata-options.interface';
+import { AbstractEntityType, EntityType } from './entity.interface';
+/**
+ * 装饰后的实体类型
+ * 根据原始类型是否为抽象类，返回相应的构造函数类型
+ */
+type DecoratedEntityType<T extends EntityType | AbstractEntityType> = T extends EntityType ? new (initData?: Partial<InstanceType<T>>) => InstanceType<T> : abstract new (initData?: Partial<InstanceType<T>>) => InstanceType<T>;
+/**
+ * 实体装饰器
+ * 用于将类标记为 RxDB 实体，并处理元数据、代理和生命周期
+ *
+ * 该装饰器会：
+ * 1. 转换并存储实体元数据
+ * 2. 处理实体的默认值和初始值
+ * 3. 为实体创建代理，以支持变更跟踪和关系管理
+ * 4. 处理抽象实体和具体实体的不同行为
+ *
+ * @example
+ * ```typescript
+ * // 基本用法
+ * @Entity({ name: 'User' })
+ * class User extends EntityBase {}
+ * ```
+ *
+ * @param metadataOptions - 实体元数据选项，包含名称、显示名称、属性、关系、索引等配置
+ * @returns 类装饰器函数
+ */
+export declare const Entity: (metadataOptions: EntityMetadataOptions) => <T extends EntityType | AbstractEntityType>(target: T) => DecoratedEntityType<T>;
+export {};

package/entity/@TreeEntity.d.ts

@@ -0,0 +1,50 @@
+import { EntityMetadataOptions } from './entity-metadata-options.interface';
+/**
+ * 树形结构类型
+ *
+ * 目前仅支持邻接表模型，未来可能支持其他模型：
+ * - 'closure-table': 闭包表模型
+ * - 'nested-set': 嵌套集模型
+ * - 'materialized-path': 物化路径模型
+ *
+ * 参考资料：
+ * - https://www.slideshare.net/slideshow/models-for-hierarchical-data/4179181
+ * - https://schinckel.net/2014/09/13/long-live-adjacency-lists/
+ */
+type TreeType = 'adjacency-list';
+/**
+ * 树形实体元数据选项接口
+ * 扩展基本实体元数据，添加树形结构特定配置
+ */
+interface TreeEntityMetadataOptions extends EntityMetadataOptions {
+    /**
+     * 树形结构类型
+     * 指定使用哪种树形结构模型
+     */
+    treeType: TreeType;
+}
+/**
+ * 树形实体装饰器
+ * 用于将类标记为树形结构实体，并处理树形特定的元数据
+ *
+ * 该装饰器基于基础的Entity装饰器，但添加了树形结构特定的处理：
+ * 1. 设置默认仓库为TreeRepository
+ * 2. 处理树形结构特定的元数据
+ * 3. 支持树形结构的查询和操作
+ *
+ * 树形实体通常包含以下关系：
+ * - parent: 指向父节点的关系
+ * - children: 指向子节点的关系集合
+ *
+ * @example
+ * ```typescript
+ * @TreeEntity({
+ *   name: 'Category',
+ *   treeType: 'adjacency-list'
+ * })
+ * class Category extends TreeAdjacencyListEntityBase {
+ * }
+ * ```
+ */
+export declare const TreeEntity: (metadataOptions: TreeEntityMetadataOptions) => <T extends import('./entity.interface').EntityType | import('./entity.interface').AbstractEntityType>(target: T) => T extends import('./entity.interface').EntityType ? new (initData?: Partial<InstanceType<T>> | undefined) => InstanceType<T> : abstract new (initData?: Partial<InstanceType<T>> | undefined) => InstanceType<T>;
+export {};

package/entity/EntityBase.d.ts

@@ -0,0 +1,49 @@
+import { IEntity, UUID } from './entity.interface';
+/**
+ * 实体基类装饰器配置
+ * 定义了所有实体共有的基础属性
+ */
+export declare abstract class EntityBase implements IEntity {
+    /**
+     * 实体唯一标识符
+     * 自动生成的UUID，作为主键
+     */
+    readonly id: UUID;
+    /**
+     * 创建时间
+     * 实体创建时自动设置为当前时间
+     */
+    readonly createdAt: Date;
+    /**
+     * 更新时间
+     * 实体创建或更新时自动设置为当前时间
+     */
+    readonly updatedAt: Date;
+    /**
+     * 删除时间
+     * 实体被软删除时设置为当前时间，否则为null
+     */
+    readonly removedAt?: Date | null;
+    /**
+     * 创建者ID
+     * 记录创建此实体的用户ID
+     */
+    readonly createdBy?: UUID | null;
+    /**
+     * 更新者ID
+     * 记录最后更新此实体的用户ID
+     */
+    readonly updatedBy?: UUID | null;
+    /**
+     * 删除者ID
+     * 记录删除此实体的用户ID
+     */
+    readonly removedBy?: UUID | null;
+    /**
+     * 实体基类构造函数
+     * 子类会通过 Entity 装饰器增强此构造函数
+     *
+     * @param initData - 可选的初始化数据
+     */
+    constructor(initData?: any);
+}

package/entity/EntityManager.d.ts

@@ -0,0 +1,140 @@
+import { Repository } from '../repository/Repository';
+import { RxDB } from '../RxDB';
+import { EntityType, RowId, UUID } from './entity.interface';
+import { EntityStatusOptions } from './EntityStatus';
+/**
+ * 实体管理器
+ *
+ * 负责管理实体的整个生命周期，包括：
+ * 1. 实体的创建、更新和删除
+ * 2. 实体缓存管理
+ * 3. 实体关系处理
+ * 4. 实体仓库访问
+ * 5. 实体代理和变更跟踪
+ *
+ * 实体管理器是连接实体、仓库和数据库的桥梁，
+ * 它确保实体状态的一致性，并处理实体间的关系。
+ */
+export declare class EntityManager {
+    #private;
+    readonly rxdb: RxDB;
+    /**
+     * 创建实体管理器实例
+     *
+     * 构造函数会：
+     * 1. 为所有注册的实体类型添加静态和实例方法
+     * 2. 设置实体关系处理
+     * 3. 配置实体代理和删除检查
+     *
+     * @param rxdb - RxDB实例，提供数据库访问和事件分发
+     */
+    constructor(rxdb: RxDB);
+    /**
+     * 创建实体引用
+     * 根据提供的数据创建或获取实体实例，并设置其状态
+     * 如果实体已存在于缓存中，则返回缓存的实例
+     *
+     * @template T 实体类型
+     * @param EntityType - 实体类型
+     * @param data - 实体数据，必须包含id
+     * @param [status] - 可选的实体状态配置
+     * @returns 创建或获取的实体实例
+     */
+    createEntityRef<T extends EntityType>(EntityType: T, data: Partial<InstanceType<T>> & {
+        id: UUID;
+    }, status?: EntityStatusOptions<T>): any;
+    /**
+     * 获取实体引用
+     * 从缓存中获取指定ID的实体实例
+     *
+     * @template T 实体类型
+     * @param EntityType - 实体类型
+     * @param id - 实体ID
+     * @returns 实体实例，如果不存在则返回undefined
+     */
+    getEntityRef<T extends EntityType>(EntityType: T, id: UUID): InstanceType<T> | undefined;
+    /**
+     * 检查实体是否在缓存中
+     * 判断指定ID的实体是否已在缓存中初始化
+     *
+     * @template T 实体类型
+     * @param EntityType - 实体类型
+     * @param id - 实体ID
+     * @returns 如果实体在缓存中存在则返回true
+     */
+    hasEntityRef<T extends EntityType>(EntityType: T, id: UUID): boolean;
+    /**
+     * 添加实体到缓存
+     * 将实体实例添加到对应类型的缓存映射中
+     *
+     * @template T 实体类型
+     * @param entity - 要缓存的实体实例
+     */
+    addEntityCache<T extends EntityType>(entity: InstanceType<T>): void;
+    /**
+     * 从缓存中删除实体
+     * 将实体实例从缓存映射中移除
+     *
+     * @template T 实体类型
+     * @param entity - 要移除的实体实例
+     */
+    removeEntityCache<T extends EntityType>(entity: InstanceType<T>): void;
+    /**
+     * 更新实体的行ID映射
+     * 建立数据库行ID到实体UUID的映射关系
+     *
+     * @template T 实体类型
+     * @param entity - 实体实例
+     * @param rowId - 数据库行ID
+     */
+    updateEntityRowId<T extends EntityType>(entity: InstanceType<T>, rowId: RowId): void;
+    /**
+     * 保存实体
+     * 根据实体状态决定是创建新实体还是更新现有实体
+     * 如果有关联实体需要保存，会使用事务进行批量保存
+     *
+     * @template T 实体类型
+     * @param data - 要保存的实体实例
+     * @returns 保存后的实体实例
+     */
+    save<T extends EntityType>(data: InstanceType<T>): Promise<InstanceType<T>>;
+    /**
+     * 删除实体
+     * 从数据库中删除实体，并分发相关事件
+     *
+     * @template T 实体类型
+     * @param data - 要删除的实体实例
+     * @returns 删除后的实体实例
+     * @throws 如果删除失败，抛出错误
+     */
+    remove<T extends EntityType>(data: InstanceType<T>): Promise<InstanceType<T>>;
+    /**
+     * 创建实体
+     * 在数据库中创建新实体，并分发相关事件
+     *
+     * @template T 实体类型
+     * @param data - 要创建的实体实例
+     * @returns 创建后的实体实例
+     * @throws 如果创建失败，抛出错误
+     */
+    create<T extends EntityType>(data: InstanceType<T>): Promise<InstanceType<T>>;
+    /**
+     * 更新实体
+     * 在数据库中更新实体，只更新已修改的属性，并分发相关事件
+     *
+     * @template T 实体类型
+     * @param data - 要更新的实体实例
+     * @returns 更新后的实体实例
+     * @throws 如果更新失败，抛出错误
+     */
+    update<T extends EntityType>(data: InstanceType<T>): Promise<InstanceType<T>>;
+    /**
+     * 获取实体仓库
+     * 获取指定实体类型的仓库实例
+     *
+     * @template T 实体类型
+     * @param EntityType - 实体类型
+     * @returns 实体仓库实例
+     */
+    getRepository<T extends EntityType>(EntityType: T): Repository<T>;
+}

package/entity/EntityStatus.d.ts

@@ -0,0 +1,211 @@
+import { RxDB } from '../RxDB';
+import { UnixMilliseconds } from '../rxdb.interface';
+import { STATUS_CHECK, UpdatedBy } from '../rxdb.private';
+import { EntityRelationMetadata, RelationKind } from './entity-metadata-options.interface';
+import { EntityType, RowId } from './entity.interface';
+/**
+ * 实体变化记录接口
+ * 记录实体的变更信息，包括变更内容、逆向变更、时间戳等
+ *
+ * @interface
+ * @template T 实体类型
+ */
+export interface EntityPatch<T extends EntityType> {
+    /**
+     * 变化
+     */
+    patch: Partial<InstanceType<T>>;
+    /**
+     * 逆变化
+     */
+    inversePatch: Partial<InstanceType<T>>;
+    /**
+     * 更新者
+     */
+    updatedBy: UpdatedBy;
+    /**
+     * 记录的毫秒世界时间
+     */
+    recordAt: UnixMilliseconds;
+    /**
+     * 记录的程序开始的时间
+     * 用于 recordAt 一样的时候排序用
+     */
+    timeStamp: DOMHighResTimeStamp;
+    /**
+     * 数据快照
+     * 为了节省内存，只会在第一次变化时记录完整数据，后续只记录变化
+     * 如果历史记录有最大限制，需要删除，那么可以利用这个数据之上 patch 变化来计算数据
+     */
+    snapshot: any;
+}
+/**
+ * 实体状态接口
+ * 定义实体状态的基本属性和行为
+ */
+export interface IEntityStatus<T extends EntityType> {
+    /**
+     * 当前实体
+     */
+    target: InstanceType<EntityType>;
+    /**
+     * 是否已修改
+     */
+    modified?: boolean;
+    /**
+     * 是否在本地
+     */
+    local?: boolean;
+    /**
+     * 是否在远程
+     */
+    remote?: boolean;
+    /**
+     * 实体变化
+     */
+    patches?: EntityPatch<T>[];
+}
+/**
+ * 实体状态选项类型
+ * 用于创建实体状态实例时的配置选项
+ */
+export type EntityStatusOptions<T extends EntityType> = Omit<IEntityStatus<T>, 'target' | 'proxyTarget'>;
+/**
+ * 实体状态类
+ * 管理实体的状态信息，包括本地/远程状态、修改状态、变更历史等
+ * 处理实体关系和变更追踪
+ */
+export declare class EntityStatus<T extends EntityType> implements IEntityStatus<T> {
+    #private;
+    readonly rxdb: RxDB;
+    /**
+     * 标识实体是否存在于远程数据库
+     */
+    protected _remote: boolean;
+    /**
+     * 标识实体是否存在于本地数据库
+     */
+    protected _local: boolean;
+    /**
+     * 标识实体是否已被修改
+     */
+    protected _modified: boolean;
+    /**
+     * 标识实体是否已被删除
+     */
+    protected _removed: boolean;
+    /**
+     * 实体在数据库中的行ID
+     */
+    protected _rowId?: RowId;
+    /**
+     * 实体变更记录数组
+     */
+    protected _patches: EntityPatch<T>[];
+    /**
+     * 实体原始对象
+     */
+    readonly target: InstanceType<T>;
+    /**
+     * 实体代理对象
+     * 用于拦截属性访问和修改
+     */
+    readonly proxyTarget: InstanceType<T>;
+    /**
+     * 实体变更记录的可观察流
+     * 用于订阅实体变更
+     */
+    readonly patches$: import('rxjs').Observable<EntityPatch<T>[]>;
+    /**
+     * 状态检查标记
+     * 用于内部状态验证
+     */
+    [STATUS_CHECK]: boolean;
+    /**
+     * 实体原始数据
+     * 用于比较变更和恢复
+     */
+    _origin: any;
+    /**
+     * 是否已修改
+     */
+    get modified(): boolean;
+    set modified(value: boolean);
+    /**
+     * 是否已删除
+     */
+    get removed(): boolean;
+    set removed(value: boolean);
+    /**
+     * 是否是远程数据
+     */
+    get remote(): boolean;
+    set remote(value: boolean);
+    /**
+     * 是否是本地数据
+     */
+    get local(): boolean;
+    set local(value: boolean);
+    /**
+     * 获取变化
+     */
+    get patches(): EntityPatch<T>[];
+    /**
+     * 设置原始值
+     */
+    set origin(value: any);
+    get origin(): any;
+    /**
+     * 设置 rowId
+     */
+    set rowId(value: RowId);
+    get rowId(): RowId | undefined;
+    /**
+     * 创建实体状态实例
+     *
+     * @constructor
+     * @param rxdb - RxDB 实例
+     * @param data - 实体状态初始数据
+     */
+    constructor(rxdb: RxDB, data: IEntityStatus<T>);
+    /**
+     * 添加实体变更记录
+     * 记录实体的变更并发布变更事件
+     *
+     * @param patch - 变更内容
+     * @param inversePatch - 逆向变更内容，用于撤销操作
+     * @param updatedBy - 更新者信息
+     * @param [recordAt=Date.now()] - 记录时间戳
+     */
+    addEntityPatch(patch: Partial<InstanceType<T>>, inversePatch: Partial<InstanceType<T>>, updatedBy: UpdatedBy, recordAt?: number): void;
+    /**
+     * 获取需要保存的关联实体
+     * 根据关系类型的优先级排序，返回需要保存的实体数组
+     *
+     * @returns 需要保存的实体数组
+     */
+    getNeedSaveRelationEntities(): InstanceType<T>[];
+    /**
+     * 添加关系实体
+     * 根据关系类型处理实体间的关联
+     *
+     * @param relation - 关系元数据
+     * @param entity - 要关联的实体
+     */
+    addRelationEntity(relation: EntityRelationMetadata, entity: InstanceType<EntityType>): void;
+    /**
+     * 删除关系实体
+     * 根据关系类型移除实体间的关联
+     *
+     * @param relation - 关系元数据
+     * @param entity - 要移除关联的实体
+     */
+    removeRelationEntity(relation: EntityRelationMetadata, entity: InstanceType<EntityType>): void;
+    /**
+     * 获取指定关系类型的实体缓存
+     * 如果缓存不存在则创建新的缓存
+     *
+     * @param kind - 关系类型
+     */
+    getRelationCache(kind: RelationKind): Set<InstanceType<EntityType>>;
+}

package/entity/TreeEntityBase.d.ts

@@ -0,0 +1,7 @@
+import { EntityBase } from './EntityBase';
+/**
+ * 树形实体装饰器配置
+ * 定义了树形结构所需的父子关系
+ */
+export declare abstract class TreeAdjacencyListEntityBase extends EntityBase {
+}