@aiao/rxdb 0.0.1

package/entity/entity-metadata-options.interface.d.ts

@@ -0,0 +1,434 @@
+import { SetRequired } from 'type-fest';
+import { EntityType } from './entity.interface';
+/**
+ * 实体字段基础值对象接口
+ * 定义实体属性的基本特性
+ */
+interface IEntityObject {
+    /**
+     * 名字
+     * 非大写开头的英文单词，只能包含英文单词和下划线
+     */
+    name: Uncapitalize<string>;
+    /**
+     * 显示名称
+     * @example "用户", "订单项"
+     */
+    displayName?: string;
+    /**
+     * 是否唯一
+     * 如果为 true 那么这个数据得值不允许重复
+     * @default false
+     */
+    unique?: boolean;
+    /**
+     * 是否为只读
+     * 如果为 true 那么这个数据只有创建的时候写一次，在更新数据时，这个列的值不会被更新
+     * 如果为 false 那么在更新数据时，这个列的值会被更新
+     * @default false
+     */
+    readonly?: boolean;
+    /**
+     * 是否可以为 NULL
+     * @default false
+     */
+    nullable?: boolean;
+}
+/**
+ * 实体排序接口
+ * 定义实体属性的排序能力
+ */
+interface ISortable {
+    /**
+     * 是否可排序
+     * @default false
+     */
+    sortable?: boolean;
+}
+/**
+ * 实体属性类型枚举
+ * 定义实体属性支持的数据类型
+ */
+export declare enum PropertyType {
+    /**
+     * uuid
+     */
+    uuid = "uuid",
+    /**
+     * 字符串
+     */
+    string = "string",
+    /**
+     * 数字
+     */
+    number = "number",
+    /**
+     * 整数
+     */
+    integer = "integer",
+    /**
+     * 布尔
+     */
+    boolean = "boolean",
+    /**
+     * 日期
+     */
+    date = "date",
+    /**
+     * json
+     */
+    json = "json"
+}
+/**
+ * 实体关系类型枚举
+ * 定义实体之间可能的关系类型
+ *
+ * 支持四种标准的实体关系类型：
+ * - 一对一：一个实体只关联另一个实体的一个实例
+ * - 一对多：一个实体关联另一个实体的多个实例
+ * - 多对一：多个实体关联另一个实体的一个实例
+ * - 多对多：多个实体关联另一个实体的多个实例，通常需要中间表
+ */
+export declare enum RelationKind {
+    ONE_TO_ONE = "1:1",
+    ONE_TO_MANY = "1:m",
+    MANY_TO_ONE = "m:1",
+    MANY_TO_MANY = "m:n"
+}
+/**
+ * 标量类型
+ * 定义可以直接存储的基本数据类型
+ */
+export type RxDBScalar = boolean | number | string | bigint | Date | Uint8Array;
+/**
+ * 实体关系基础类型接口
+ * 所有关系类型的基础接口
+ */
+interface EntityRelationMetadataBase extends ISortable {
+    /**
+     * 名字
+     */
+    name: Uncapitalize<string>;
+    /**
+     * 显示名称
+     * @example "用户", "订单项"
+     */
+    displayName?: string;
+    /**
+     * 类型
+     */
+    kind: RelationKind;
+    /**
+     * 关联的实体
+     * @default "public"
+     */
+    mappedNamespace?: Lowercase<string>;
+    /**
+     * 关联的实体
+     */
+    mappedEntity: Capitalize<string>;
+}
+/**
+ * 一对一关系元数据接口
+ * 定义两个实体之间的一对一关系
+ */
+interface EntityRelationOneToOneMetadataOptions extends EntityRelationMetadataBase, IEntityObject {
+    kind: RelationKind.ONE_TO_ONE;
+}
+/**
+ * 一对多关系元数据接口
+ * 定义一个实体与多个实体之间的关系
+ */
+interface EntityRelationOneToManyMetadataOptions extends EntityRelationMetadataBase {
+    kind: RelationKind.ONE_TO_MANY;
+    /**
+     * 关联实体的属性名
+     */
+    mappedProperty: Uncapitalize<string>;
+}
+/**
+ * 多对一关系元数据接口
+ * 定义多个实体与一个实体之间的关系
+ */
+interface EntityRelationManyToOneMetadataOptions extends EntityRelationMetadataBase, IEntityObject {
+    kind: RelationKind.MANY_TO_ONE;
+}
+/**
+ * 多对多关系元数据接口
+ * 定义多个实体与多个实体之间的关系，通常需要中间表（连接表）
+ *
+ * 多对多关系允许一个实体的多个实例关联到另一个实体的多个实例。
+ * 例如：学生和课程的关系，一个学生可以选多门课程，一门课程可以有多个学生。
+ * 这种关系需要一个中间表来存储两个实体之间的关联关系。
+ */
+interface EntityRelationManyToManyMetadataOptions extends EntityRelationMetadataBase {
+    kind: RelationKind.MANY_TO_MANY;
+    /**
+     * 关联实体的属性名
+     */
+    mappedProperty: Uncapitalize<string>;
+    /**
+     * 中间表（连接表）的实体类型
+     * 用于存储多对多关系中两个实体之间的关联
+     * 中间表通常包含两个外键，分别指向关联的两个实体
+     */
+    junctionEntityType?: EntityType;
+}
+/**
+ * 实体关系元数据联合类型
+ * 包含所有可能的关系类型（一对一、一对多、多对一、多对多）
+ *
+ * 在定义实体时，可以使用这些关系类型来配置实体之间的关联
+ * 系统会根据关系类型自动处理外键、查询和关联操作
+ */
+export type EntityRelationMetadataOptions = EntityRelationOneToOneMetadataOptions | EntityRelationOneToManyMetadataOptions | EntityRelationManyToOneMetadataOptions | EntityRelationManyToManyMetadataOptions;
+export type EntityRelationOneToOneMetadata = SetRequired<EntityRelationOneToOneMetadataOptions, 'mappedNamespace'>;
+export type EntityRelationOneToManyMetadata = SetRequired<EntityRelationOneToManyMetadataOptions, 'mappedNamespace'>;
+export type EntityRelationManyToOneMetadata = SetRequired<EntityRelationManyToOneMetadataOptions, 'mappedNamespace'>;
+export type EntityRelationManyToManyMetadata = SetRequired<EntityRelationManyToManyMetadataOptions, 'mappedNamespace' | 'junctionEntityType'>;
+export type EntityRelationMetadata = EntityRelationOneToOneMetadata | EntityRelationOneToManyMetadata | EntityRelationManyToOneMetadata | EntityRelationManyToManyMetadata;
+/**
+ * 默认非主键属性元数据接口
+ * 定义普通实体属性的元数据
+ */
+interface EntityPropertyDefaultMetadataOptions extends IEntityObject, ISortable {
+    primary?: false;
+    /**
+     * 类型
+     */
+    type: PropertyType;
+    /**
+     * 默认值
+     * 创建数据时如果没有数据就用 default
+     */
+    default?: RxDBScalar | (() => RxDBScalar);
+}
+/**
+ * 整数主键属性元数据接口
+ * 定义使用整数类型作为主键的属性元数据
+ */
+interface EntityPrimaryIntegerPropertyMetadataOptions extends IEntityObject, ISortable {
+    /**
+     * 是否主键
+     */
+    primary: true;
+    /**
+     * 类型
+     */
+    type: PropertyType.integer;
+    /**
+     * 默认值
+     * 创建数据时如果没有数据就用 default
+     */
+    default?: RxDBScalar | (() => RxDBScalar);
+}
+/**
+ * UUID主键属性元数据接口
+ * 定义使用UUID类型作为主键的属性元数据
+ */
+interface EntityPrimaryUUIDPropertyMetadataOptions extends IEntityObject, ISortable {
+    /**
+     * 是否主键
+     */
+    primary: true;
+    /**
+     * 类型
+     */
+    type: PropertyType.uuid;
+    /**
+     * 默认值
+     * 创建数据时如果没有数据就用 default
+     */
+    default?: RxDBScalar | (() => RxDBScalar);
+}
+/**
+ * 日期属性元数据接口
+ * 定义日期类型属性的特殊元数据
+ */
+interface EntityDatePropertyMetadataOptions extends EntityPropertyDefaultMetadataOptions {
+    /**
+     * 类型
+     */
+    type: PropertyType.date;
+    /**
+     * 默认值
+     * 创建数据时如果没有数据就用 default
+     * CURRENT_TIMESTAMP 默认当前时间
+     */
+    default?: RxDBScalar | (() => RxDBScalar) | 'CURRENT_TIMESTAMP';
+}
+/**
+ * 实体属性元数据联合类型
+ * 包含所有可能的属性类型元数据
+ */
+export type EntityPropertyMetadataOptions = EntityPrimaryIntegerPropertyMetadataOptions | EntityPrimaryUUIDPropertyMetadataOptions | EntityPropertyDefaultMetadataOptions | EntityDatePropertyMetadataOptions;
+export type EntityPropertyMetadata = EntityPropertyMetadataOptions;
+/**
+ * 实体索引元数据接口
+ * 定义实体索引的配置
+ */
+export interface EntityIndexMetadataOptions extends IEntityObject {
+    properties?: string[];
+}
+/**
+ * 实体定义元数据选项接口
+ * 用于配置 @Entity 装饰器的完整选项，定义实体的结构和行为
+ *
+ * 这个接口是实体定义的核心，包含了实体的所有配置信息：
+ * - 基本信息：名称、命名空间、显示名称
+ * - 结构信息：属性、关系、索引
+ * - 行为信息：抽象类标记、日志配置、同步策略
+ *
+ * @example
+ * ```typescript
+ * @Entity({
+ *   name: 'User',
+ *   displayName: '用户',
+ *   properties: [
+ *     { name: 'name', type: PropertyType.string, displayName: '姓名' },
+ *     { name: 'age', type: PropertyType.number, displayName: '年龄' }
+ *   ],
+ *   relations: [
+ *     { name: 'profile', kind: RelationKind.ONE_TO_ONE, mappedEntity: 'Profile' },
+ *     { name: 'posts', kind: RelationKind.ONE_TO_MANY, mappedEntity: 'Post', mappedProperty: 'author' }
+ *   ]
+ * })
+ * class User extends EntityBase {}
+ * ```
+ */
+export interface EntityMetadataOptions {
+    /**
+     * 命名空间
+     * 只能包含小写的英文字母
+     * 在 postgres 里会变成 schema
+     * 在 sqlite 会变成 table 的前缀
+     * @example "app", "system"
+     * @default "public"
+     */
+    namespace?: Lowercase<string>;
+    /**
+     * 名称
+     */
+    name: Capitalize<string>;
+    /**
+     * 自定义 repository
+     */
+    repository?: 'Repository' | 'TreeRepository' | string;
+    /**
+     * 继承的基类
+     */
+    extends?: string[];
+    /**
+     * 是否开启日志
+     */
+    log?: boolean;
+    /**
+     * 实体同步配置
+     */
+    sync?: SyncOptions;
+    /**
+     * 显示名称
+     * @example "用户", "订单项"
+     */
+    displayName?: string;
+    /**
+     * 是否为抽象实体
+     * 抽象类是不能被实例化的
+     */
+    abstract?: boolean;
+    /**
+     * 实体的属性表
+     * 自己定义的属性，不包括继承的
+     */
+    properties?: EntityPropertyMetadataOptions[];
+    /**
+     * 实体的关系配置
+     * 自己定义的关系，不包括继承的
+     *
+     * 定义实体与其他实体之间的关联关系，支持四种关系类型：
+     * - ONE_TO_ONE：一对一关系，如用户和用户资料
+     * - ONE_TO_MANY：一对多关系，如用户和用户的多篇文章
+     * - MANY_TO_ONE：多对一关系，如多篇文章和一个作者
+     * - MANY_TO_MANY：多对多关系，如学生和课程
+     *
+     * 系统会根据关系配置自动处理外键、查询和关联操作
+     */
+    relations?: EntityRelationMetadataOptions[];
+    /**
+     * 实体的索引配置
+     * 自己定义的索引，不包括继承的
+     */
+    indexes?: EntityIndexMetadataOptions[];
+}
+/**
+ * 同步适配器选项接口
+ * 定义数据同步适配器的配置
+ */
+export interface SyncAdapterOptions {
+    adapter: string;
+}
+/**
+ * 同步类型枚举
+ * 定义不同的数据同步策略，控制本地数据和远程数据之间的同步方式
+ *
+ * 支持四种同步策略：
+ * - Full：全量同步，同步所有数据
+ * - Filter：条件同步，根据过滤条件同步部分数据
+ * - None：不同步，可以配置为只使用本地数据或只使用远程数据
+ */
+export declare enum SyncType {
+    /**
+     * 全量同步
+     */
+    Full = "full",
+    /**
+     * 根据查询同步
+     */
+    Filter = "filter",
+    /**
+     * 不同步
+     */
+    None = "None"
+}
+/**
+ * 全量同步配置接口
+ * 定义完整数据同步的配置
+ */
+interface SyncFull {
+    type: SyncType.Full;
+    local: SyncAdapterOptions;
+    remote: SyncAdapterOptions;
+}
+/**
+ * 条件同步配置接口
+ * 定义基于过滤条件的数据同步配置
+ */
+interface SyncFilter {
+    type: SyncType.Filter;
+    local: SyncAdapterOptions;
+    remote: SyncAdapterOptions;
+}
+/**
+ * 远程数据配置接口
+ * 定义只访问远程数据而不同步到本地的配置
+ */
+interface Remote {
+    type: SyncType.None;
+    local?: SyncAdapterOptions;
+    remote: SyncAdapterOptions;
+}
+/**
+ * 本地数据配置接口
+ * 定义只访问本地数据而不同步到远程的配置
+ */
+interface Local {
+    type: SyncType.None;
+    local: SyncAdapterOptions;
+    remote?: SyncAdapterOptions;
+}
+/**
+ * 同步配置联合类型
+ * 包含所有可能的同步配置类型
+ */
+export type SyncOptions = SyncFull | SyncFilter | Remote | Local;
+export {};

package/entity/entity-metadata.interface.d.ts

@@ -0,0 +1,67 @@
+import { ReadonlyDeep, SetRequired } from 'type-fest';
+import { EntityIndexMetadataOptions, EntityMetadataOptions, EntityPropertyMetadata, EntityRelationMetadata } from './entity-metadata-options.interface';
+export type EntityIndexMetadata = EntityIndexMetadataOptions;
+/**
+ * 实体元数据类型
+ * 包含实体的所有元数据信息，如属性、关系、索引等
+ */
+export type EntityMetadataType = SetRequired<EntityMetadataOptions, 'namespace' | 'displayName' | 'repository'> & {
+    properties: EntityPropertyMetadata[];
+    relations: EntityRelationMetadata[];
+    indexes: EntityIndexMetadata[];
+    /**
+     * 继承的实体名称列表
+     * 表示当前实体继承自哪些实体
+     */
+    extends: string[];
+    /**
+     * 自定义仓库名称
+     * 指定实体使用的仓库类型，可以是标准仓库、树形仓库或自定义仓库
+     */
+    repository: 'Repository' | 'TreeRepository' | string;
+    /**
+     * 实体所有属性的映射
+     * 键为属性名，值为属性元数据
+     */
+    propertyMap: Map<string, EntityPropertyMetadata>;
+    /**
+     * 有默认值的属性列表
+     * 包含所有设置了默认值的属性元数据
+     */
+    defaultValueProperties: EntityPropertyMetadata[];
+    /**
+     * 实体所有关系的映射
+     * 键为关系属性名，值为关系元数据
+     */
+    relationMap: Map<string, EntityRelationMetadata>;
+    /**
+     * 实体外键关系的映射
+     */
+    foreignKeyRelationMap: Map<string, EntityRelationMetadata>;
+    /**
+     * 实体外键关系列表
+     * 包含所有涉及外键的关系元数据
+     */
+    foreignKeyRelations: EntityRelationMetadata[];
+    /**
+     * 实体外键名称列表
+     * 包含所有外键字段的名称
+     */
+    foreignKeyNames: string[];
+    /**
+     * 实体所有索引的映射
+     * 键为索引名，值为索引元数据
+     */
+    indexMap: Map<string, EntityIndexMetadata>;
+    /**
+     * 判断属性名是否是外键
+     *
+     * @param name - 要检查的属性名
+     */
+    isForeignKey(name: string): boolean;
+};
+/**
+ * 实体元数据（只读版本）
+ * 实体元数据的只读深度副本，防止元数据被修改
+ */
+export type EntityMetadata = ReadonlyDeep<EntityMetadataType>;

package/entity/entity.interface.d.ts

@@ -0,0 +1,110 @@
+import { Observable } from 'rxjs';
+/**
+ * 实体类型
+ * 表示可实例化的实体构造函数类型
+ */
+export type EntityType = new (initData?: any) => any;
+/**
+ * 抽象实体类型
+ * 表示不可直接实例化的抽象实体构造函数类型
+ */
+export type AbstractEntityType = abstract new (initData?: any) => any;
+/**
+ * 实体基础接口
+ * 定义所有实体共有的基本属性，为了能更好地与远程数据同步
+ * 所有实体类都应该实现这个接口
+ */
+export interface IEntity {
+    /**
+     * id
+     */
+    id: UUID;
+    /**
+     * 创建时间
+     */
+    createdAt: Date;
+    /**
+     * 更新时间
+     */
+    updatedAt: Date;
+    /**
+     * 删除时间
+     */
+    removedAt?: Date | null;
+    /**
+     * 创建人
+     */
+    createdBy?: string | null;
+    /**
+     * 更新人
+     */
+    updatedBy?: string | null;
+    /**
+     * 删除人
+     */
+    removedBy?: string | null;
+}
+/**
+ * UUID类型
+ * 表示标准的UUID字符串格式
+ * 格式为：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ */
+export type UUID = `${string}-${string}-${string}-${string}-${string}`;
+/**
+ * 单个关系对象的访问接口
+ * 提供对单个关联实体的观察和操作能力
+ */
+export interface RelationEntityObservable<T> extends Observable<T> {
+    /**
+     * 设置关联实体
+     *
+     * @param entity - 要设置的实体或null（解除关联）
+     */
+    set: (entity: T | null) => void;
+    /**
+     * 移除关联实体
+     * 相当于设置为null
+     */
+    remove: () => void;
+}
+/**
+ * 多个关系对象的访问接口
+ * 提供对多个关联实体集合的观察和操作能力
+ */
+export interface RelationEntitiesObservable<T> extends Observable<T[]> {
+    /**
+     * 关联实体数量的可观察对象
+     */
+    count$: Observable<number>;
+    /**
+     * 添加关联实体
+     *
+     * @param entities - 要添加的实体列表
+     */
+    add: (...entities: T[]) => void;
+    /**
+     * 移除关联实体
+     *
+     * @param entities - 要移除的实体列表
+     */
+    remove: (...entities: T[]) => void;
+}
+/**
+ * SQLite行ID类型
+ * 表示SQLite数据库中的rowid
+ */
+export type SqliteRowId = bigint;
+/**
+ * PostgreSQL物理行标识类型
+ * 表示PostgreSQL数据库中的ctid（物理行位置标识）
+ * 格式为：(块号,块内偏移)
+ *
+ * @see http://postgres.cn/docs/16/ddl-system-columns.html#DDL-SYSTEM-COLUMNS-CTID
+ */
+export type PostgresCtId = `(${number},${number})`;
+/**
+ * 数据库行标识类型
+ * 统一表示不同数据库中的行标识
+ * 在SQLite中主要用于通过观察数据库变化找到级联删除的实体
+ */
+export type RowId = SqliteRowId | PostgresCtId;

package/entity/entity.utils.d.ts

@@ -0,0 +1,59 @@
+import { EntityMetadata } from './entity-metadata.interface';
+import { EntityType } from './entity.interface';
+/**
+ * 判断字段名是否是内部保留字段
+ * 包括基类字段、私有字段和以下划线开头的字段
+ *
+ * @param key - 要检查的字段名
+ * @returns 如果是内部保留字段则返回true，否则返回false
+ */
+export declare const isEntityInternalName: (key: string) => boolean;
+/**
+ * 设置安全的不可变属性
+ * 创建一个不可枚举、不可配置、不可写的属性
+ *
+ * @param object - 目标对象
+ * @param key - 属性键
+ * @param value - 属性值
+ * @returns 修改后的对象
+ */
+export declare const setSafeObjectKey: (object: object, key: string | symbol, value: any) => object;
+/**
+ * 设置安全的可变属性
+ * 创建一个不可枚举、不可配置但可写的属性
+ *
+ * @param object - 目标对象
+ * @param key - 属性键
+ * @param value - 属性值
+ * @returns 修改后的对象
+ */
+export declare const setSafeObjectWritableKey: (object: object, key: string | symbol, value: any) => object;
+/**
+ * 设置懒加载属性
+ * 创建一个只在首次访问时计算值的属性，后续访问直接返回计算结果
+ *
+ * @param object - 目标对象
+ * @param key - 属性键
+ * @param init - 初始化函数，用于计算属性值
+ * @returns 修改后的对象
+ */
+export declare const setSafeObjectKeyLazyInitOnce: (object: object, key: string | symbol, init: () => any) => object;
+/**
+ * 给实体实例填充默认值
+ * 根据元数据中定义的默认值，为实体的未赋值属性设置默认值
+ *
+ * @template T - 实体类型
+ * @param metadata - 实体元数据
+ * @param entity - 实体实例
+ */
+export declare const fillDefaultValue: <T extends EntityType>(metadata: EntityMetadata, entity: InstanceType<T>) => void;
+/**
+ * 给实体实例填充初始值
+ * 根据提供的初始值对象，为实体的属性设置值，同时尊重只读属性
+ *
+ * @template T - 实体类型
+ * @param metadata - 实体元数据
+ * @param entity - 实体实例
+ * @param initValue - 初始值对象
+ */
+export declare const fillInitValue: <T extends EntityType>(metadata: EntityMetadata, entity: InstanceType<T>, initValue: Partial<InstanceType<T>>) => void;