@aiao/rxdb-model 0.0.19 → 0.0.26

package/src/query-builder/models/operator.interface.ts

@@ -0,0 +1,191 @@
+import type { OperatorName } from '@aiao/rxdb';
+import type { PropertyType } from './query-builder-state.js';
+
+/**
+ * 操作符定义
+ * 包含操作符的元数据和约束
+ */
+export interface OperatorDefinition {
+  /**
+   * 操作符键值（使用 RxDB 的 OperatorName）
+   */
+  key: OperatorName;
+
+  /**
+   * 显示标签（支持国际化）
+   */
+  label: string;
+
+  /**
+   * 值类型
+   * - single: 单个值 (例如 "=")
+   * - array: 值数组 (例如 "in")
+   * - range: 范围值 [min, max] (例如 "between")
+   * - none: 无需值 (例如 "null")
+   * - subquery: 子查询条件 (例如 "exists" - 可选的嵌套规则组)
+   */
+  valueType: 'single' | 'array' | 'range' | 'none' | 'subquery';
+
+  /**
+   * 适用的字段类型
+   */
+  applicableTypes: PropertyType[];
+}
+
+/**
+ * 操作符类型（直接复用 RxDB 定义）
+ */
+export type QueryBuilderOperator = OperatorName;
+
+/**
+ * 默认操作符定义列表
+ */
+export const DEFAULT_OPERATORS: OperatorDefinition[] = [
+  // 相等操作符
+  {
+    key: '=',
+    label: '等于',
+    valueType: 'single',
+    applicableTypes: ['uuid', 'string', 'number', 'boolean', 'date', 'enum']
+  },
+  {
+    key: '!=',
+    label: '不等于',
+    valueType: 'single',
+    applicableTypes: ['uuid', 'string', 'number', 'boolean', 'date', 'enum']
+  },
+
+  // 比较操作符
+  {
+    key: '<',
+    label: '小于',
+    valueType: 'single',
+    applicableTypes: ['number', 'date', 'string']
+  },
+  {
+    key: '>',
+    label: '大于',
+    valueType: 'single',
+    applicableTypes: ['number', 'date', 'string']
+  },
+  {
+    key: '<=',
+    label: '小于等于',
+    valueType: 'single',
+    applicableTypes: ['number', 'date', 'string']
+  },
+  {
+    key: '>=',
+    label: '大于等于',
+    valueType: 'single',
+    applicableTypes: ['number', 'date', 'string']
+  },
+
+  // 字符串操作符
+  {
+    key: 'contains',
+    label: '包含',
+    valueType: 'single',
+    applicableTypes: ['string', 'array']
+  },
+  {
+    key: 'notContains',
+    label: '不包含',
+    valueType: 'single',
+    applicableTypes: ['string', 'array']
+  },
+  {
+    key: 'startsWith',
+    label: '开头是',
+    valueType: 'single',
+    applicableTypes: ['string']
+  },
+  {
+    key: 'notStartsWith',
+    label: '开头不是',
+    valueType: 'single',
+    applicableTypes: ['string']
+  },
+  {
+    key: 'endsWith',
+    label: '结尾是',
+    valueType: 'single',
+    applicableTypes: ['string']
+  },
+  {
+    key: 'notEndsWith',
+    label: '结尾不是',
+    valueType: 'single',
+    applicableTypes: ['string']
+  },
+
+  // 空值操作符（仅在 nullable 字段时通过 getForField() 动态添加）
+  {
+    key: 'null',
+    label: '为空',
+    valueType: 'none',
+    applicableTypes: []
+  },
+  {
+    key: 'notNull',
+    label: '不为空',
+    valueType: 'none',
+    applicableTypes: []
+  },
+
+  // 集合操作符
+  {
+    key: 'in',
+    label: '在列表中',
+    valueType: 'array',
+    applicableTypes: ['string', 'number', 'enum']
+  },
+  {
+    key: 'notIn',
+    label: '不在列表中',
+    valueType: 'array',
+    applicableTypes: ['string', 'number', 'enum']
+  },
+
+  // 范围操作符
+  {
+    key: 'between',
+    label: '在范围内',
+    valueType: 'range',
+    applicableTypes: ['number', 'date']
+  },
+  {
+    key: 'notBetween',
+    label: '不在范围内',
+    valueType: 'range',
+    applicableTypes: ['number', 'date']
+  },
+
+  // 关系操作符
+  {
+    key: 'exists',
+    label: '存在',
+    valueType: 'subquery',
+    applicableTypes: ['relation']
+  },
+  {
+    key: 'notExists',
+    label: '不存在',
+    valueType: 'subquery',
+    applicableTypes: ['relation']
+  }
+];
+
+/**
+ * 根据字段类型获取适用的操作符
+ *
+ * @param type - 字段类型
+ * @param operators - 操作符定义列表（默认使用内置操作符 DEFAULT_OPERATORS）
+ * @returns 适用于该字段类型的操作符数组
+ */
+export function getOperatorsForType(
+  type: PropertyType,
+  operators: OperatorDefinition[] = DEFAULT_OPERATORS
+): OperatorDefinition[] {
+  return operators.filter(op => op.applicableTypes.includes(type));
+}

package/src/query-builder/models/query-builder-state.ts

@@ -0,0 +1,222 @@
+import { OperatorName, Rule, RuleGroup } from '@aiao/rxdb';
+
+/**
+ * UI 规则（宽松类型，用于查询构建器组件内部）
+ *
+ * @description
+ * 由于 Rule<T> 是联合类型，在 UI 组件中难以处理部分更新。
+ * 此类型提供宽松的字段类型，方便 UI 组件操作。
+ */
+export interface UIRule {
+  /**
+   * 规则唯一标识符
+   */
+  id: string;
+
+  /**
+   * 字段名
+   */
+  field: string;
+
+  /**
+   * 操作符
+   */
+  operator: string;
+
+  /**
+   * 规则值（可选）
+   */
+  value?: unknown;
+  /**
+   * EXISTS/NOT EXISTS 操作符的子查询条件
+   */
+  where?: QueryBuilderRuleGroup<Record<string, unknown>>;
+}
+
+/**
+ * 查询规则（复用 RxDB Rule 类型 + UI 元数据）
+ *
+ * @template T - 实体类型
+ * @template K - 字段键类型（自动推断）
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   name: string;
+ *   age: number;
+ *   active: boolean;
+ * }
+ *
+ * const rule: QueryBuilderRule<User> = {
+ *   id: 'rule-1',
+ *   field: 'name',      // ✅ 类型安全：只能是 'name' | 'age' | 'active'
+ *   operator: 'contains',
+ *   value: 'John'       // ✅ 类型推断为 string
+ * };
+ * ```
+ */
+export type QueryBuilderRule<T = Record<string, unknown>> = UIRule & {
+  /**
+   * 规则唯一标识符
+   * 用于 React key, Angular trackBy, Vue :key
+   */
+  id: string;
+
+  /**
+   * 字段名（类型安全的实体字段键或字符串）
+   */
+  field: string | (keyof T & string);
+
+  /**
+   * 操作符（RxDB OperatorName 或自定义字符串）
+   */
+  operator: OperatorName | string;
+};
+
+/**
+ * 规则组（复用 RxDB RuleGroup 类型 + UI 元数据）
+ *
+ * @template T - 实体类型
+ */
+export interface QueryBuilderRuleGroup<T = Record<string, unknown>> {
+  /**
+   * 规则组唯一标识符
+   */
+  id: string;
+
+  /**
+   * 逻辑组合符
+   */
+  combinator: 'and' | 'or';
+
+  /**
+   * 子规则列表（支持嵌套）
+   */
+  rules: Array<QueryBuilderRule<T> | QueryBuilderRuleGroup<T>>;
+}
+
+/**
+ * 查询构建器状态（简化版本，只包含必要字段）
+ */
+export interface QueryBuilderState<T = Record<string, unknown>> {
+  /**
+   * 根规则组
+   */
+  rootGroup: QueryBuilderRuleGroup<T>;
+}
+
+/**
+ * Schema 信息
+ */
+export interface SchemaInfo {
+  /**
+   * 实体名称
+   */
+  entityName: string;
+
+  /**
+   * 字段列表
+   */
+  fields: FieldMetadata[];
+}
+
+/**
+ * 字段元数据
+ */
+export interface FieldMetadata {
+  /**
+   * 字段名称
+   */
+  name: string;
+
+  /**
+   * 显示名称
+   */
+  displayName: string;
+
+  /**
+   * 字段类型
+   */
+  type: PropertyType;
+
+  /**
+   * 字段描述
+   */
+  description?: string;
+
+  /**
+   * 是否必填
+   */
+  required?: boolean;
+
+  /**
+   * 是否可空
+   */
+  nullable?: boolean;
+
+  /**
+   * 枚举值（如果适用）
+   */
+  enum?: unknown[];
+
+  /**
+   * 正则验证（字符串类型）
+   */
+  pattern?: string;
+
+  /**
+   * 是否是关系字段
+   */
+  isRelation?: boolean;
+
+  /**
+   * 关系目标实体名称
+   */
+  relationTarget?: string;
+
+  /**
+   * 关系类型（1:1, 1:m, m:1, m:n）
+   */
+  relationKind?: '1:1' | '1:m' | 'm:1' | 'm:n';
+
+  /**
+   * 关系目标实体的字段列表（用于 EXISTS 子查询）
+   */
+  relationFields?: FieldMetadata[];
+
+  /**
+   * keyValue 子属性字段列表（用于嵌套属性查询）
+   */
+  keyValueFields?: FieldMetadata[];
+}
+
+/**
+ * 属性类型
+ */
+export type PropertyType =
+  'uuid' | 'string' | 'number' | 'boolean' | 'date' | 'array' | 'object' | 'relation' | 'enum' | 'keyValue';
+
+/**
+ * 类型守卫：判断是否为规则组
+ *
+ * @param item - 待判断的规则或规则组
+ * @returns 若为规则组则返回 true，否则返回 false
+ */
+export function isRuleGroup<T>(item: QueryBuilderRule<T> | QueryBuilderRuleGroup<T>): item is QueryBuilderRuleGroup<T> {
+  return 'combinator' in item && 'rules' in item;
+}
+
+/**
+ * 类型守卫：判断是否为规则
+ *
+ * @param item - 待判断的规则或规则组
+ * @returns 若为规则则返回 true，否则返回 false
+ */
+export function isRule<T>(item: QueryBuilderRule<T> | QueryBuilderRuleGroup<T>): item is QueryBuilderRule<T> {
+  return 'field' in item && 'operator' in item;
+}
+
+/**
+ * 类型重导出：操作符名及 RxDB 原生规则、规则组类型
+ */
+export type { OperatorName, Rule, RuleGroup };

package/src/query-builder/models/validation.interface.ts

@@ -0,0 +1,184 @@
+import type { OperatorName } from '@aiao/rxdb';
+import type { PropertyType } from './query-builder-state.js';
+
+/**
+ * 验证规则
+ */
+export interface ValidationRule {
+  /**
+   * 规则名称
+   */
+  name: string;
+
+  /**
+   * 适用的字段类型（可选，undefined 表示适用于所有类型）
+   */
+  appliesTo?: PropertyType[];
+
+  /**
+   * 错误消息
+   */
+  message: string;
+
+  /**
+   * 验证函数
+   * @returns true 表示通过，false 表示失败
+   */
+  validate: (context: ValidationContext) => boolean;
+}
+
+/**
+ * 验证上下文
+ */
+export interface ValidationContext {
+  /**
+   * 字段类型
+   */
+  fieldType: PropertyType;
+
+  /**
+   * 操作符
+   */
+  operator: OperatorName;
+
+  /**
+   * 当前值
+   */
+  value: unknown;
+
+  /**
+   * 是否必填
+   */
+  required?: boolean;
+
+  /**
+   * 枚举值
+   */
+  enum?: unknown[];
+
+  /**
+   * 正则验证
+   */
+  pattern?: string;
+}
+
+/**
+ * 验证错误项
+ */
+export interface ValidationError {
+  /**
+   * 字段名
+   */
+  field: string;
+
+  /**
+   * 规则名
+   */
+  rule: string;
+
+  /**
+   * 错误消息
+   */
+  message: string;
+}
+
+/**
+ * 验证结果
+ */
+export interface ValidationResult {
+  /**
+   * 是否有效
+   */
+  valid: boolean;
+
+  /**
+   * 错误列表
+   */
+  errors?: ValidationError[];
+}
+
+/**
+ * 跳过 nil 和数组值的前置检查。
+ * 内置验证规则共用：值为 null/undefined 时不验证，数组由 valueType 规则处理。
+ *
+ * @returns `true` 表示应跳过后续验证（值为 nil 或数组）
+ */
+function shouldSkipValidation(value: unknown): boolean {
+  return value === undefined || value === null || Array.isArray(value);
+}
+
+/**
+ * 内置验证规则
+ */
+export const BUILTIN_VALIDATION_RULES: ValidationRule[] = [
+  {
+    name: 'stringType',
+    appliesTo: ['string'],
+    message: '值必须是字符串类型',
+    validate: context => {
+      if (shouldSkipValidation(context.value)) return true;
+      return typeof context.value === 'string';
+    }
+  },
+  {
+    name: 'numberType',
+    appliesTo: ['number'],
+    message: '值必须是数字类型',
+    validate: context => {
+      if (shouldSkipValidation(context.value)) return true;
+      return typeof context.value === 'number' && !isNaN(context.value);
+    }
+  },
+  {
+    name: 'booleanType',
+    appliesTo: ['boolean'],
+    message: '值必须是布尔类型',
+    validate: context => {
+      if (shouldSkipValidation(context.value)) return true;
+      return typeof context.value === 'boolean';
+    }
+  },
+  {
+    name: 'dateType',
+    appliesTo: ['date'],
+    message: '值必须是有效日期',
+    validate: context => {
+      if (shouldSkipValidation(context.value)) return true;
+      if (context.value instanceof Date) {
+        return !isNaN(context.value.getTime());
+      }
+      if (typeof context.value === 'string') {
+        const date = new Date(context.value);
+        return !isNaN(date.getTime());
+      }
+      return false;
+    }
+  },
+  {
+    name: 'enumType',
+    appliesTo: ['enum'],
+    message: '值必须是枚举中的有效选项',
+    validate: context => {
+      if (context.value === undefined || context.value === null) return true;
+      if (!context.enum || context.enum.length === 0) return true;
+      if (Array.isArray(context.value)) {
+        return (context.value as unknown[]).every(v => (context.enum as unknown[]).includes(v));
+      }
+      return context.enum.includes(context.value);
+    }
+  },
+  {
+    name: 'patternType',
+    appliesTo: ['string'],
+    message: '值不符合要求的格式',
+    validate: context => {
+      if (shouldSkipValidation(context.value)) return true;
+      if (!context.pattern || typeof context.value !== 'string') return true;
+      try {
+        return new RegExp(context.pattern).test(context.value);
+      } catch {
+        return true;
+      }
+    }
+  }
+];

package/src/query-builder/services/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Services 导出
+ */
+
+export * from './operator-registry.service.js';
+export * from './query-builder.service.js';
+export * from './query-converter.service.js';
+export * from './schema-parser.service.js';
+export * from './validation.service.js';