@yanit/jsondb 0.1.1

package/src/Utils.js

@@ -0,0 +1,205 @@
+/**
+ * 工具函数模块
+ */
+
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+/**
+ * 生成唯一 ID（类似 MongoDB ObjectId 简化版）
+ * @returns {string} 24 位十六进制字符串
+ */
+export function generateId() {
+  const timestamp = Math.floor(Date.now() / 1000).toString(16).padStart(8, '0');
+  const randomPart = createHash('sha256')
+    .update(Math.random().toString() + Date.now().toString())
+    .digest('hex')
+    .substring(0, 16);
+  return timestamp + randomPart;
+}
+
+/**
+ * 深拷贝对象
+ * @param {any} obj - 要拷贝的对象
+ * @returns {any} 拷贝后的对象
+ */
+export function deepClone(obj) {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+/**
+ * 获取嵌套对象的值
+ * @param {Object} obj - 对象
+ * @param {string} path - 路径，如 'user.name'
+ * @returns {any} 值
+ */
+export function getNestedValue(obj, path) {
+  if (!path || typeof path !== 'string') {
+    return obj;
+  }
+  
+  const keys = path.split('.');
+  let result = obj;
+  
+  for (const key of keys) {
+    if (result === null || result === undefined) {
+      return undefined;
+    }
+    result = result[key];
+  }
+  
+  return result;
+}
+
+/**
+ * 设置嵌套对象的值
+ * @param {Object} obj - 对象
+ * @param {string} path - 路径，如 'user.name'
+ * @param {any} value - 值
+ */
+export function setNestedValue(obj, path, value) {
+  const keys = path.split('.');
+  let current = obj;
+  
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (!(key in current)) {
+      current[key] = {};
+    }
+    current = current[key];
+  }
+  
+  current[keys[keys.length - 1]] = value;
+}
+
+/**
+ * 删除嵌套对象的属性
+ * @param {Object} obj - 对象
+ * @param {string} path - 路径，如 'user.name'
+ * @returns {boolean} 是否删除成功
+ */
+export function deleteNestedValue(obj, path) {
+  const keys = path.split('.');
+  let current = obj;
+  
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (!(keys[i] in current)) {
+      return false;
+    }
+    current = current[keys[i]];
+  }
+  
+  return delete current[keys[keys.length - 1]];
+}
+
+/**
+ * 确保目录存在
+ * @param {string} dirPath - 目录路径
+ */
+export function ensureDir(dirPath) {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirname(dirPath), { recursive: true });
+  }
+}
+
+/**
+ * 检查值是否匹配类型
+ * @param {any} value - 值
+ * @param {string} type - 类型名称
+ * @returns {boolean}
+ */
+export function isType(value, type) {
+  if (type === 'array') {
+    return Array.isArray(value);
+  }
+  if (type === 'null') {
+    return value === null;
+  }
+  if (type === 'object') {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+  }
+  return typeof value === type;
+}
+
+/**
+ * 比较两个值
+ * @param {any} a - 值 a
+ * @param {any} b - 值 b
+ * @returns {number} -1, 0, 1
+ */
+export function compareValues(a, b) {
+  if (a === b) return 0;
+  if (a === null) return -1;
+  if (b === null) return 1;
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+/**
+ * 将排序规范转换为比较函数
+ * @param {Object} sortSpec - 排序规范，如 { age: -1, name: 1 }
+ * @returns {Function} 比较函数
+ */
+export function createSortFunction(sortSpec) {
+  const keys = Object.keys(sortSpec);
+  
+  return (a, b) => {
+    for (const key of keys) {
+      const direction = sortSpec[key];
+      const aVal = getNestedValue(a, key);
+      const bVal = getNestedValue(b, key);
+      
+      const cmp = compareValues(aVal, bVal);
+      if (cmp !== 0) {
+        return cmp * direction;
+      }
+    }
+    return 0;
+  };
+}
+
+/**
+ * 投影文档字段
+ * @param {Object} doc - 文档
+ * @param {Object} projection - 投影规范
+ * @returns {Object} 投影后的文档
+ */
+export function projectDocument(doc, projection) {
+  if (!projection) {
+    return deepClone(doc);
+  }
+  
+  const result = {};
+  const keys = Object.keys(projection);
+  
+  // 检查是包含模式还是排除模式
+  let isIncludeMode = false;
+  for (const key of keys) {
+    if (key !== '_id' && projection[key]) {
+      isIncludeMode = true;
+      break;
+    }
+  }
+  
+  // 处理 _id 字段
+  if (projection._id !== undefined) {
+    if (projection._id) {
+      result._id = doc._id;
+    }
+  } else if (isIncludeMode) {
+    result._id = doc._id;
+  }
+  
+  // 处理其他字段
+  for (const key of keys) {
+    if (key === '_id') continue;
+    
+    if (projection[key]) {
+      result[key] = getNestedValue(doc, key);
+    }
+  }
+  
+  return result;
+}

package/src/Utils.ts

@@ -0,0 +1,205 @@
+/**
+ * 工具函数模块
+ */
+
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+/**
+ * 生成唯一 ID（类似 MongoDB ObjectId 简化版）
+ * @returns 24 位十六进制字符串
+ */
+export function generateId(): string {
+  const timestamp = Math.floor(Date.now() / 1000).toString(16).padStart(8, '0');
+  const randomPart = createHash('sha256')
+    .update(Math.random().toString() + Date.now().toString())
+    .digest('hex')
+    .substring(0, 16);
+  return timestamp + randomPart;
+}
+
+/**
+ * 深拷贝对象
+ * @param obj - 要拷贝的对象
+ * @returns 拷贝后的对象
+ */
+export function deepClone<T>(obj: T): T {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+/**
+ * 获取嵌套对象的值
+ * @param obj - 对象
+ * @param path - 路径，如 'user.name'
+ * @returns 值
+ */
+export function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  if (!path || typeof path !== 'string') {
+    return obj;
+  }
+
+  const keys = path.split('.');
+  let result: unknown = obj;
+
+  for (const key of keys) {
+    if (result === null || result === undefined) {
+      return undefined;
+    }
+    result = (result as Record<string, unknown>)[key];
+  }
+
+  return result;
+}
+
+/**
+ * 设置嵌套对象的值
+ * @param obj - 对象
+ * @param path - 路径，如 'user.name'
+ * @param value - 值
+ */
+export function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void {
+  const keys = path.split('.');
+  let current: Record<string, unknown> = obj;
+
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (!(key in current)) {
+      current[key] = {};
+    }
+    current = current[key] as Record<string, unknown>;
+  }
+
+  current[keys[keys.length - 1]] = value;
+}
+
+/**
+ * 删除嵌套对象的属性
+ * @param obj - 对象
+ * @param path - 路径，如 'user.name'
+ * @returns 是否删除成功
+ */
+export function deleteNestedValue(obj: Record<string, unknown>, path: string): boolean {
+  const keys = path.split('.');
+  let current: Record<string, unknown> = obj;
+
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (!(keys[i] in current)) {
+      return false;
+    }
+    current = current[keys[i]] as Record<string, unknown>;
+  }
+
+  return delete current[keys[keys.length - 1]];
+}
+
+/**
+ * 确保目录存在
+ * @param dirPath - 目录路径
+ */
+export function ensureDir(dirPath: string): void {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirname(dirPath), { recursive: true });
+  }
+}
+
+/**
+ * 检查值是否匹配类型
+ * @param value - 值
+ * @param type - 类型名称
+ * @returns 是否匹配
+ */
+export function isType(value: unknown, type: string): boolean {
+  if (type === 'array') {
+    return Array.isArray(value);
+  }
+  if (type === 'null') {
+    return value === null;
+  }
+  if (type === 'object') {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+  }
+  return typeof value === type;
+}
+
+/**
+ * 比较两个值
+ * @param a - 值 a
+ * @param b - 值 b
+ * @returns -1, 0, 1
+ */
+export function compareValues(a: unknown, b: unknown): number {
+  if (a === b) return 0;
+  if (a === null) return -1;
+  if (b === null) return 1;
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+/**
+ * 将排序规范转换为比较函数
+ * @param sortSpec - 排序规范，如 { age: -1, name: 1 }
+ * @returns 比较函数
+ */
+export function createSortFunction(sortSpec: Record<string, number>): (a: Record<string, unknown>, b: Record<string, unknown>) => number {
+  const keys = Object.keys(sortSpec);
+
+  return (a: Record<string, unknown>, b: Record<string, unknown>) => {
+    for (const key of keys) {
+      const direction = sortSpec[key];
+      const aVal = getNestedValue(a, key);
+      const bVal = getNestedValue(b, key);
+
+      const cmp = compareValues(aVal, bVal);
+      if (cmp !== 0) {
+        return cmp * direction;
+      }
+    }
+    return 0;
+  };
+}
+
+/**
+ * 投影文档字段
+ * @param doc - 文档
+ * @param projection - 投影规范
+ * @returns 投影后的文档
+ */
+export function projectDocument(doc: Record<string, unknown>, projection?: Record<string, unknown>): Record<string, unknown> {
+  if (!projection) {
+    return deepClone(doc);
+  }
+
+  const result: Record<string, unknown> = {};
+  const keys = Object.keys(projection);
+
+  // 检查是包含模式还是排除模式
+  let isIncludeMode = false;
+  for (const key of keys) {
+    if (key !== '_id' && projection[key]) {
+      isIncludeMode = true;
+      break;
+    }
+  }
+
+  // 处理 _id 字段
+  if (projection._id !== undefined) {
+    if (projection._id) {
+      result._id = doc._id;
+    }
+  } else if (isIncludeMode) {
+    result._id = doc._id;
+  }
+
+  // 处理其他字段
+  for (const key of keys) {
+    if (key === '_id') continue;
+
+    if (projection[key]) {
+      result[key] = getNestedValue(doc, key);
+    }
+  }
+
+  return result;
+}

package/src/errors.js

@@ -0,0 +1,93 @@
+/**
+ * JSONDB 错误类定义
+ */
+
+/**
+ * 基础错误类
+ */
+export class JSONDBError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'JSONDBError';
+  }
+}
+
+/**
+ * 数据库不存在错误
+ */
+export class DatabaseNotFoundError extends JSONDBError {
+  constructor(dbPath) {
+    super(`数据库不存在：${dbPath}`);
+    this.name = 'DatabaseNotFoundError';
+  }
+}
+
+/**
+ * 数据库已存在错误
+ */
+export class DatabaseExistsError extends JSONDBError {
+  constructor(dbPath) {
+    super(`数据库已存在：${dbPath}`);
+    this.name = 'DatabaseExistsError';
+  }
+}
+
+/**
+ * 集合不存在错误
+ */
+export class CollectionNotFoundError extends JSONDBError {
+  constructor(collectionName) {
+    super(`集合不存在：${collectionName}`);
+    this.name = 'CollectionNotFoundError';
+  }
+}
+
+/**
+ * 集合已存在错误
+ */
+export class CollectionExistsError extends JSONDBError {
+  constructor(collectionName) {
+    super(`集合已存在：${collectionName}`);
+    this.name = 'CollectionExistsError';
+  }
+}
+
+/**
+ * 文档未找到错误
+ */
+export class DocumentNotFoundError extends JSONDBError {
+  constructor(query) {
+    super(`文档未找到：${JSON.stringify(query)}`);
+    this.name = 'DocumentNotFoundError';
+  }
+}
+
+/**
+ * 索引错误
+ */
+export class IndexError extends JSONDBError {
+  constructor(message) {
+    super(message);
+    this.name = 'IndexError';
+  }
+}
+
+/**
+ * 查询错误
+ */
+export class QueryError extends JSONDBError {
+  constructor(message) {
+    super(message);
+    this.name = 'QueryError';
+  }
+}
+
+/**
+ * 验证错误
+ */
+export class ValidationError extends JSONDBError {
+  constructor(message) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}

package/src/errors.ts

@@ -0,0 +1,93 @@
+/**
+ * JSONDB 错误类定义
+ */
+
+/**
+ * 基础错误类
+ */
+export class JSONDBError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'JSONDBError';
+  }
+}
+
+/**
+ * 数据库不存在错误
+ */
+export class DatabaseNotFoundError extends JSONDBError {
+  constructor(dbPath: string) {
+    super(`数据库不存在：${dbPath}`);
+    this.name = 'DatabaseNotFoundError';
+  }
+}
+
+/**
+ * 数据库已存在错误
+ */
+export class DatabaseExistsError extends JSONDBError {
+  constructor(dbPath: string) {
+    super(`数据库已存在：${dbPath}`);
+    this.name = 'DatabaseExistsError';
+  }
+}
+
+/**
+ * 集合不存在错误
+ */
+export class CollectionNotFoundError extends JSONDBError {
+  constructor(collectionName: string) {
+    super(`集合不存在：${collectionName}`);
+    this.name = 'CollectionNotFoundError';
+  }
+}
+
+/**
+ * 集合已存在错误
+ */
+export class CollectionExistsError extends JSONDBError {
+  constructor(collectionName: string) {
+    super(`集合已存在：${collectionName}`);
+    this.name = 'CollectionExistsError';
+  }
+}
+
+/**
+ * 文档未找到错误
+ */
+export class DocumentNotFoundError extends JSONDBError {
+  constructor(query: Record<string, unknown>) {
+    super(`文档未找到：${JSON.stringify(query)}`);
+    this.name = 'DocumentNotFoundError';
+  }
+}
+
+/**
+ * 索引错误
+ */
+export class IndexError extends JSONDBError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'IndexError';
+  }
+}
+
+/**
+ * 查询错误
+ */
+export class QueryError extends JSONDBError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'QueryError';
+  }
+}
+
+/**
+ * 验证错误
+ */
+export class ValidationError extends JSONDBError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}

package/src/index.js

@@ -0,0 +1,90 @@
+/**
+ * JSONDB - 基于 Node.js 的轻量级 JSON 数据库
+ * 支持 MongoDB 风格语法
+ * 
+ * @example
+ * import { Database } from 'jsondb';
+ * 
+ * const db = new Database('./data/mydb');
+ * await db.open();
+ * 
+ * const users = db.collection('users');
+ * await users.insertOne({ name: 'Alice', age: 25 });
+ * 
+ * await db.close();
+ */
+
+export { Database } from './Database.js';
+export { Collection } from './Collection.js';
+export { Cursor } from './Cursor.js';
+
+// 导出错误类
+export {
+  JSONDBError,
+  DatabaseNotFoundError,
+  DatabaseExistsError,
+  CollectionNotFoundError,
+  CollectionExistsError,
+  DocumentNotFoundError,
+  IndexError,
+  QueryError,
+  ValidationError
+} from './errors.js';
+
+// 导出工具函数
+export {
+  generateId,
+  deepClone,
+  getNestedValue,
+  setNestedValue,
+  deleteNestedValue
+} from './Utils.js';
+
+// 导出查询操作符
+export {
+  matchQuery,
+  applyUpdate,
+  comparisonOperators,
+  logicalOperators,
+  elementOperators,
+  arrayOperators
+} from './Operators.js';
+
+// 导出 Schema 验证
+export {
+  Schema,
+  createSchema,
+  createValidator,
+  validators
+} from './Schema.js';
+
+// 导出批量操作
+export {
+  BulkOperation,
+  createBulkOp,
+  bulkInsert,
+  bulkUpdate,
+  bulkDelete
+} from './BulkOp.js';
+
+// 导出查询缓存
+export {
+  QueryCache,
+  globalQueryCache,
+  cacheQuery
+} from './QueryCache.js';
+
+// 导出事务
+export {
+  Transaction,
+  TransactionStatus,
+  OperationType,
+  createTransaction,
+  withTransaction
+} from './Transaction.js';
+
+/**
+ * 默认导出
+ */
+import { Database } from './Database.js';
+export default Database;