MetonaSqlark/src/constants.ts

/**
 * metona-sqlark Constants — 类型定义 / 默认配置 / 枚举
 * @module constants
 */

// ---------------------------------------------------------------------------
//  存储模式
// ---------------------------------------------------------------------------

/** 存储模式 */
export type StorageMode = 'memory' | 'disk' | 'hybrid' | 'aria';

/** 磁盘引擎类型 */
export type DiskEngine = 'indexeddb' | 'opfs';

/** 所有存储模式 */
export const STORAGE_MODES: StorageMode[] = ['memory', 'disk', 'hybrid', 'aria'];

/** 所有磁盘引擎 */
export const DISK_ENGINES: DiskEngine[] = ['indexeddb', 'opfs'];

// ---------------------------------------------------------------------------
//  字段类型
// ---------------------------------------------------------------------------

/** 字段数据类型 */
export type FieldType = 'string' | 'number' | 'boolean' | 'date' | 'json';

/** 所有字段类型 */
export const FIELD_TYPES: FieldType[] = ['string', 'number', 'boolean', 'date', 'json'];

// ---------------------------------------------------------------------------
//  列定义 & 表结构
// ---------------------------------------------------------------------------

/** 列定义 */
export interface ColumnDef {
  /** 字段类型 */
  type: FieldType;
  /** 是否主键 */
  primaryKey?: boolean;
  /** 是否必填 */
  required?: boolean;
  /** 是否唯一 */
  unique?: boolean;
  /** 默认值 */
  default?: unknown;
  /** 是否创建索引 */
  index?: boolean;
  /** 外键引用: 'table.column' */
  references?: string;
  /** 删除级联: 'CASCADE' | 'SET NULL' | 'RESTRICT' */
  onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
  /** 更新级联: 'CASCADE' | 'SET NULL' | 'RESTRICT' */
  onUpdate?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
  /** 字符串最大长度 */
  maxLength?: number;
  /** 数字最小值 */
  min?: number;
  /** 数字最大值 */
  max?: number;
}

/** 表结构定义 */
export interface TableSchema {
  /** 表名 */
  name: string;
  /** 列定义映射 */
  columns: Record<string, ColumnDef>;
}

// ---------------------------------------------------------------------------
//  数据库配置
// ---------------------------------------------------------------------------

/** 数据库配置 */
export interface DatabaseConfig {
  /** 数据库名称 */
  name: string;
  /** 存储模式 */
  mode?: StorageMode;
  /** 磁盘引擎（仅 mode='disk'|'hybrid' 时生效） */
  diskEngine?: DiskEngine;
  /** 版本号 */
  version?: number;
  /** 插件列表 */
  plugins?: MetonaPlugin[];
  /** 数据库就绪回调 */
  onReady?: (db: unknown) => void;
  /** 错误回调 */
  onError?: (error: Error) => void;
  /** 查询结果行数上限（默认 0，0 表示不限制） */
  maxRowsPerQuery?: number;
  /** 调试模式（启用后输出详细操作日志） */
  debug?: boolean;
  /** 多标签页同步（v0.3.2）：BroadcastChannel 广播表变更，其他标签页自动刷新 */
  multiTabSync?: boolean;
}

/** 数据库默认配置 */
export const DB_DEFAULTS: Readonly<Required<Omit<DatabaseConfig, 'plugins' | 'onReady' | 'onError'>>> = Object.freeze({
  name: 'metona-sqlark',
  mode: 'hybrid' as const,
  diskEngine: 'indexeddb' as const,
  version: 1,
  maxRowsPerQuery: 0, // 0 = 不限制
  debug: false,
  multiTabSync: false,
});

// ---------------------------------------------------------------------------
//  Where 操作符
// ---------------------------------------------------------------------------

/** Where 条件操作符 */
export type WhereOperator = '$eq' | '$ne' | '$gt' | '$gte' | '$lt' | '$lte' | '$in' | '$nin' | '$like' | '$and' | '$or' | '$not';

/** 简单条件值：直接相等 */
export type SimpleCondition = unknown;

/** 操作符条件 */
export type OperatorCondition = Partial<Record<WhereOperator, unknown>>;

/** 字段条件：简单值 | 操作符对象 */
export type FieldCondition = SimpleCondition | OperatorCondition;

/** Where 条件对象 */
export type WhereCondition = Record<string, FieldCondition>;

// ---------------------------------------------------------------------------
//  排序
// ---------------------------------------------------------------------------

/** 排序方向 */
export type SortDirection = 'asc' | 'desc';

/** 排序定义 */
export interface OrderBy {
  /** 列名 */
  column: string;
  /** 排序方向 */
  direction: SortDirection;
  /** v0.4.0: NULL 值排序位置（first 排最前 / last 排最后，默认同引擎行为） */
  nulls?: 'first' | 'last';
}

// ---------------------------------------------------------------------------
//  查询计划（引擎层使用）
// ---------------------------------------------------------------------------

/** 查询计划 — 由 Executor 编译 AST 后生成 */
export interface QueryPlan {
  /** 表名 */
  table: string;
  /** 要返回的列（undefined = 全部，['*'] = 全部） */
  columns?: string[];
  /** 过滤条件 */
  where?: WhereCondition;
  /** 排序 */
  orderBy?: OrderBy[];
  /** 限制条数 */
  limit?: number;
  /** 偏移量 */
  offset?: number;
}

// ---------------------------------------------------------------------------
//  插件接口
// ---------------------------------------------------------------------------

/** 钩子名称 */
export type HookName =
  | 'beforeCreateTable' | 'afterCreateTable'
  | 'beforeDropTable' | 'afterDropTable'
  | 'beforeInsert' | 'afterInsert'
  | 'beforeUpdate' | 'afterUpdate'
  | 'beforeDelete' | 'afterDelete'
  | 'beforeQuery' | 'afterQuery'
  | 'beforeTransaction' | 'afterTransaction';

/** 插件定义 */
export interface MetonaPlugin {
  /** 插件名称 */
  name: string;
  /** 插件版本 */
  version: string;
  /** 描述 */
  description?: string;
  /** 优先级，越大越先执行 */
  priority?: number;
  /** 安装 */
  install(db: unknown): void;
  /** 销毁 */
  destroy(): void;
}

// ---------------------------------------------------------------------------
//  错误类型
// ---------------------------------------------------------------------------

/** 数据库错误 */
export class DatabaseError extends Error {
  constructor(
    message: string,
    public code: string,
    public details?: unknown,
  ) {
    super(message);
    this.name = 'DatabaseError';
  }
}

// ---------------------------------------------------------------------------
//  版本
// ---------------------------------------------------------------------------

export const VERSION = '0.4.1';