@cloudbase/database 1.4.3 → 1.5.1

package/tests/gateway-contract.test.ts

@@ -0,0 +1,180 @@
+import { EJSON } from 'bson'
+import { Db } from '../src/index'
+import { Transaction } from '../src/transaction/index'
+
+/**
+ * GATEWAY 模式接口名契约测试
+ *
+ * js-sdk（packages/cloudbase/database/src/index.ts 的 gateWayFunc）在
+ * endPointMode === 'GATEWAY' 时按 action 名查表路由到 RESTful 网关，
+ * 表外的 action 会 fallback 到 super.send() 走老通道，导致网关被绕过。
+ *
+ * 本测试用与 js-sdk gateWayFunc 相同的接口名集合模拟 GATEWAY 分发，
+ * 验证 2.0 引擎发出的所有 action 都能命中映射表，
+ * 任何一侧改名/新增接口而另一侧未同步时，此测试会失败。
+ */
+describe('GATEWAY 模式接口名契约（与 js-sdk gateWayFunc 对齐）', () => {
+  // 与 js-sdk gateWayFunc 的 key 保持一致
+  const GATEWAY_ACTIONS = [
+    // 旧接口名（0.12.x 引擎）
+    'database.queryDocument',
+    'database.addDocument',
+    'database.updateDocument',
+    'database.deleteDocument',
+    'database.countDocument',
+    'database.addCollection',
+    'database.aggregate',
+    // 事务（新旧引擎同名）
+    'database.startTransaction',
+    'database.commitTransaction',
+    'database.abortTransaction',
+    'database.getInTransaction',
+    'database.updateDocInTransaction',
+    'database.deleteDocInTransaction',
+    'database.insertDocInTransaction',
+    'database.runCommands',
+    // 新接口名（2.0 引擎，js-sdk gateWayFunc 已添加映射）
+    'database.getDocument',
+    'database.insertDocument',
+    'database.modifyDocument',
+    'database.removeDocument',
+    'database.calculateDocument',
+    'database.aggregateDocuments'
+  ]
+
+  let hitActions: string[]
+
+  class MockGatewayReq {
+    async send(action: string) {
+      if (GATEWAY_ACTIONS.indexOf(action) < 0) {
+        throw new Error(`GATEWAY 模式下无此接口映射: ${action}`)
+      }
+      hitActions.push(action)
+
+      // 按接口返回 2.0 引擎期望的最小响应结构
+      switch (action) {
+        case 'database.getDocument':
+          return {
+            data: { list: [EJSON.stringify({ _id: 'doc1', name: 'Alice' })] },
+            requestId: 'gw-req-get'
+          }
+        case 'database.insertDocument':
+          return {
+            data: { insertedIds: ['new-id'] },
+            requestId: 'gw-req-insert'
+          }
+        case 'database.modifyDocument':
+          return {
+            data: { updated: 1, upsert_id: 'doc1' },
+            requestId: 'gw-req-modify'
+          }
+        case 'database.removeDocument':
+          return {
+            data: { deleted: 1 },
+            requestId: 'gw-req-remove'
+          }
+        case 'database.calculateDocument':
+          return {
+            data: { total: 5 },
+            requestId: 'gw-req-count'
+          }
+        case 'database.aggregateDocuments':
+          return {
+            data: { list: [EJSON.stringify({ total: 1 })] },
+            requestId: 'gw-req-agg'
+          }
+        case 'database.startTransaction':
+          return { transactionId: 'gw-tx-001' }
+        case 'database.commitTransaction':
+        case 'database.abortTransaction':
+          return { requestId: 'gw-req-tx' }
+        default:
+          return { data: { ok: 1 }, requestId: 'gw-req-default' }
+      }
+    }
+  }
+
+  beforeEach(() => {
+    hitActions = []
+    Db.reqClass = MockGatewayReq as any
+  })
+
+  function createDb() {
+    return new Db({ env: 'test-env' })
+  }
+
+  async function createInitedTransaction(db: Db) {
+    const tx = new Transaction(db)
+    await tx.init()
+    return tx
+  }
+
+  it('collection CRUD 应全部命中网关映射表', async () => {
+    const db = createDb()
+    const coll = db.collection('users')
+
+    await coll.where({ age: 18 }).get()
+    await coll.where({ age: 18 }).count()
+    await coll.where({ age: 18 }).update({ age: 19 })
+    await coll.where({ age: 18 }).remove()
+    await coll.add({ name: 'New' })
+    await coll
+      .aggregate()
+      .match({ age: { $gt: 10 } })
+      .end()
+
+    expect(hitActions).toEqual([
+      'database.getDocument',
+      'database.calculateDocument',
+      'database.modifyDocument',
+      'database.removeDocument',
+      'database.insertDocument',
+      'database.aggregateDocuments'
+    ])
+  })
+
+  it('document CRUD 应全部命中网关映射表', async () => {
+    const db = createDb()
+    const doc = db.collection('users').doc('doc1')
+
+    await doc.get()
+    await doc.create({ name: 'Alice' })
+    await doc.set({ name: 'Alice2' })
+    await doc.update({ name: 'Alice3' })
+    await doc.remove()
+
+    expect(hitActions).toEqual([
+      'database.getDocument',
+      'database.insertDocument',
+      'database.modifyDocument',
+      'database.modifyDocument',
+      'database.removeDocument'
+    ])
+  })
+
+  it('事务操作应全部命中网关映射表', async () => {
+    const db = createDb()
+    const tx = await createInitedTransaction(db)
+
+    await tx.collection('users').where({ age: 18 }).get()
+    await tx.collection('users').where({ age: 18 }).update({ age: 19 })
+    await tx.collection('users').add({ name: 'TxNew' })
+    await tx.collection('users').doc('doc1').set({ name: 'TxSet' })
+    await tx.commit()
+
+    expect(hitActions).toEqual([
+      'database.startTransaction',
+      'database.getDocument',
+      'database.modifyDocument',
+      'database.insertDocument',
+      'database.modifyDocument',
+      'database.commitTransaction'
+    ])
+  })
+
+  it('createCollection 应命中网关映射表', async () => {
+    const db = createDb()
+    await db.createCollection('new-coll')
+    expect(hitActions).toEqual(['database.addCollection'])
+  })
+})

package/tests/index.test.ts

@@ -0,0 +1,283 @@
+import { EJSON } from 'bson'
+import { Db } from '../src/index'
+
+describe('数据库请求参数测试', function() {
+  // 模拟请求类，用于捕获和验证请求参数
+  class MockRequest {
+    private config: any;
+
+    constructor(config: any) {
+      this.config = config;
+    }
+
+    async send(action: string, data: any) {
+      // 验证 instance 和 database 参数是否正确传递
+      if (this.config.instance) {
+        expect(data).toHaveProperty('instance', this.config.instance);
+      }
+      if (this.config.database) {
+        expect(data).toHaveProperty('database', this.config.database);
+      }
+
+      // 返回符合各操作期望的数据结构
+      switch (action) {
+        case 'database.getDocument':
+          return {
+            data: {
+              list: [
+                EJSON.stringify({ _id: 'doc1', name: '测试文档1', value: 100 }),
+                EJSON.stringify({ _id: 'doc2', name: '测试文档2', value: 200 })
+              ]
+            },
+            requestId: 'mock-request-id-123456',
+            total: 2,
+            limit: 100,
+            offset: 5
+          };
+        case 'database.insertDocument':
+          return {
+            data: { insertedIds: ['doc-new'] },
+            requestId: 'mock-request-id-insert'
+          };
+        case 'database.modifyDocument':
+          return {
+            data: { updated: 1, upsert_id: 'doc1' },
+            requestId: 'mock-request-id-modify'
+          };
+        case 'database.aggregateDocuments':
+          return {
+            data: { list: [] },
+            requestId: 'mock-request-id-aggregate'
+          };
+        default:
+          return { data: { ok: 1 } };
+      }
+    }
+  }
+
+  // 测试配置
+  const testConfig = {
+    env: 'test-env',
+    instance: 'test-instance',
+    database: 'test-database'
+  };
+
+  // 在每个测试前配置
+  beforeEach(function() {
+    Db.reqClass = MockRequest;
+  });
+
+  it('集合查询操作应包含 instance 和 database 参数', async function() {
+    const db = new Db(testConfig);
+    const coll = db.collection('test-collection');
+    await coll.where({}).get();
+  });
+
+  it('集合添加操作应包含 instance 和 database 参数', async function() {
+    const db = new Db(testConfig);
+    const coll = db.collection('test-collection');
+    await coll.add({ name: '新文档', value: 300 });
+  });
+
+  it('文档更新操作应包含 instance 和 database 参数', async function() {
+    const db = new Db(testConfig);
+    const coll = db.collection('test-collection');
+    const doc = coll.doc('doc1');
+    await doc.update({ value: 150 });
+  });
+
+  it('聚合操作应包含 instance 和 database 参数', async function() {
+    const db = new Db(testConfig);
+    const coll = db.collection('test-collection');
+    const aggregate = coll
+      .aggregate()
+      .match({ value: { $gt: 50 } })
+      .group({ _id: null, total: { $sum: '$value' } });
+    await aggregate.end();
+  });
+
+  it('创建集合操作应包含 instance 和 database 参数', async function() {
+    const db = new Db(testConfig);
+    await db.createCollection('new-collection');
+  });
+
+  it('应支持 const res = await db.collection(\'xxx\').get() 方式调用', async function() {
+    const db = new Db(testConfig);
+    const coll = db.collection('test-collection');
+
+    // 测试直接调用 get() 而不传递 where 条件
+    const res = await coll.get();
+
+    // 验证返回结果的结构
+    expect(res).toHaveProperty('data');
+    expect(res).toHaveProperty('requestId');
+    expect(res).toHaveProperty('total');
+    expect(res).toHaveProperty('limit');
+    expect(res).toHaveProperty('offset');
+
+    // 验证返回的数据
+    expect(Array.isArray(res.data)).toBe(true);
+    expect(res.data.length).toBe(2);
+    expect(res.data[0]).toHaveProperty('_id', 'doc1');
+    expect(res.data[0]).toHaveProperty('name', '测试文档1');
+    expect(res.data[1]).toHaveProperty('_id', 'doc2');
+    expect(res.data[1]).toHaveProperty('name', '测试文档2');
+  });
+
+  // ---------- timeout 透传（per-request，经 createRequest 第三参数） ----------
+  describe('timeout 透传', function() {
+    it('options({timeout}) 应把 timeout 作为 send 第三参透传', async function() {
+      let capturedArgs: any[] = [];
+      class TimeoutReq {
+        constructor(_config: any) {}
+        async send(...args: any[]) {
+          capturedArgs = args;
+          return { data: { list: [] }, requestId: 'req-timeout' };
+        }
+      }
+      Db.reqClass = TimeoutReq as any;
+
+      const db = new Db({ env: 'test-env' });
+      await db.collection('users').options({ timeout: 500 }).get();
+
+      expect(capturedArgs[0]).toBe('database.getDocument');
+      expect(capturedArgs[2]).toEqual({ timeout: 500 });
+    });
+
+    it('未设置 timeout 时第三参应为空对象', async function() {
+      let capturedArgs: any[] = [];
+      class TimeoutReq {
+        constructor(_config: any) {}
+        async send(...args: any[]) {
+          capturedArgs = args;
+          return { data: { list: [] }, requestId: 'req-no-timeout' };
+        }
+      }
+      Db.reqClass = TimeoutReq as any;
+
+      const db = new Db({ env: 'test-env' });
+      await db.collection('users').get();
+
+      expect(capturedArgs[2]).toEqual({});
+    });
+
+    it('timeout 与 instance/database 注入应共存', async function() {
+      let capturedArgs: any[] = [];
+      class TimeoutReq {
+        constructor(_config: any) {}
+        async send(...args: any[]) {
+          capturedArgs = args;
+          return { data: { list: [] }, requestId: 'req-mix' };
+        }
+      }
+      Db.reqClass = TimeoutReq as any;
+
+      const db = new Db({ env: 'test-env', instance: 'inst-1', database: 'db-1' });
+      await db.collection('users').options({ timeout: 1000 }).get();
+
+      expect(capturedArgs[1]).toMatchObject({ instance: 'inst-1', database: 'db-1' });
+      expect(capturedArgs[2]).toEqual({ timeout: 1000 });
+    });
+  });
+
+  // ---------- callback 兼容（对齐 0.12.x 旧调用风格） ----------
+  describe('callback 兼容', function() {
+    it('collection().get(callback) 应调用 callback(0, result) 且返回 undefined', async function() {
+      const db = new Db(testConfig);
+      const coll = db.collection('test-collection');
+
+      const callback = jest.fn();
+      const retVal = coll.get(callback);
+
+      // 对齐 master 行为：传 callback 时返回 undefined
+      expect(retVal).toBeUndefined();
+
+      // 等 callback 被调用
+      await new Promise<void>(resolve => {
+        const timer = setInterval(() => {
+          if (callback.mock.calls.length > 0) {
+            clearInterval(timer);
+            resolve();
+          }
+        }, 10);
+      });
+
+      expect(callback).toHaveBeenCalledTimes(1);
+      const [err, result] = callback.mock.calls[0];
+      expect(err).toBe(0);
+      expect(result).toHaveProperty('data');
+      expect(result.data.length).toBe(2);
+      expect(result).toHaveProperty('requestId');
+    });
+
+    it('collection().add(data, callback) 应调用 callback(0, result)', async function() {
+      const db = new Db(testConfig);
+      const coll = db.collection('test-collection');
+
+      const callback = jest.fn();
+      coll.add({ name: 'cb-doc' }, callback);
+
+      await new Promise<void>(resolve => {
+        const timer = setInterval(() => {
+          if (callback.mock.calls.length > 0) {
+            clearInterval(timer);
+            resolve();
+          }
+        }, 10);
+      });
+
+      const [err, result] = callback.mock.calls[0];
+      expect(err).toBe(0);
+      expect(result).toHaveProperty('id', 'doc-new');
+      expect(result).toHaveProperty('requestId');
+    });
+
+    it('doc().get(callback) 应调用 callback(0, result)', async function() {
+      const db = new Db(testConfig);
+      const doc = db.collection('test-collection').doc('doc1');
+
+      const callback = jest.fn();
+      doc.get(callback);
+
+      await new Promise<void>(resolve => {
+        const timer = setInterval(() => {
+          if (callback.mock.calls.length > 0) {
+            clearInterval(timer);
+            resolve();
+          }
+        }, 10);
+      });
+
+      const [err, result] = callback.mock.calls[0];
+      expect(err).toBe(0);
+      expect(result).toHaveProperty('data');
+      expect(result).toHaveProperty('requestId');
+    });
+
+    it('请求异常时应调用 callback(err)', async function() {
+      class FailRequest {
+        async send() {
+          throw new Error('network down');
+        }
+      }
+      Db.reqClass = FailRequest as any;
+
+      const db = new Db(testConfig);
+      const callback = jest.fn();
+      db.collection('test-collection').get(callback);
+
+      await new Promise<void>(resolve => {
+        const timer = setInterval(() => {
+          if (callback.mock.calls.length > 0) {
+            clearInterval(timer);
+            resolve();
+          }
+        }, 10);
+      });
+
+      const [err] = callback.mock.calls[0];
+      expect(err).toBeInstanceOf(Error);
+      expect(err.message).toBe('network down');
+    });
+  });
+});

package/tests/transaction-query.test.ts

@@ -0,0 +1,207 @@
+import { EJSON } from 'bson'
+import { Db } from '../src/index'
+import { Transaction } from '../src/transaction/index'
+
+describe('Transaction（新事务 API）', () => {
+  let sendFn: jest.Mock
+
+  class MockRequest {
+    send(action: string, data: any) {
+      return sendFn(action, data)
+    }
+  }
+
+  beforeEach(() => {
+    sendFn = jest.fn()
+    Db.reqClass = MockRequest as any
+  })
+
+  function createDb() {
+    return new Db({ env: 'test-env' })
+  }
+
+  async function createInitedTransaction(db: Db, txId = 'tx-001') {
+    const tx = new Transaction(db)
+    sendFn.mockResolvedValueOnce({ transactionId: txId })
+    await tx.init()
+    return tx
+  }
+
+  function findCall(action: string) {
+    return sendFn.mock.calls.find(c => c[0] === action)
+  }
+
+  // ---------- 初始化 ----------
+  describe('init()', () => {
+    it('应调用 database.startTransaction 并记录 transactionId', async () => {
+      const db = createDb()
+      const tx = await createInitedTransaction(db, 'tx-init')
+
+      expect(findCall('database.startTransaction')).toBeDefined()
+      expect(tx.getTransactionId()).toBe('tx-init')
+    })
+
+    it('init 不带 data 参数时（send(START) 单参）在配置 instance/database 下不应崩溃', async () => {
+      class NoDataReq {
+        async send(...args: any[]) {
+          if (args[0] === 'database.startTransaction') {
+            return { transactionId: 'tx-nodata' }
+          }
+          return { data: { list: [] }, requestId: 'r' }
+        }
+      }
+      Db.reqClass = NoDataReq as any
+
+      const db = new Db({ env: 'test-env', instance: 'inst-1', database: 'db-1' })
+      const tx = new Transaction(db)
+      await tx.init() // 不应抛 TypeError
+
+      expect(tx.getTransactionId()).toBe('tx-nodata')
+    })
+  })
+
+  // ---------- 事务内查询 ----------
+  describe('collection() + where().get()', () => {
+    it('应把 transactionId 传给 database.getDocument', async () => {
+      const db = createDb()
+      const tx = await createInitedTransaction(db)
+
+      sendFn.mockResolvedValueOnce({ data: { list: [] }, requestId: 'req-1' })
+
+      await tx.collection('users').where({ age: 18 }).get()
+
+      const call = findCall('database.getDocument')
+      expect(call).toBeDefined()
+      expect(call![1]).toMatchObject({
+        collectionName: 'users',
+        transactionId: 'tx-001'
+      })
+    })
+
+    it('get() 应解析 EJSON list 并返回文档数组', async () => {
+      const db = createDb()
+      const tx = await createInitedTransaction(db)
+
+      const list = [
+        EJSON.stringify({ _id: 'doc1', name: 'Alice' }),
+        EJSON.stringify({ _id: 'doc2', name: 'Bob' })
+      ]
+      sendFn.mockResolvedValueOnce({ data: { list }, requestId: 'req-2', total: 2 })
+
+      const result = await tx.collection('users').where({}).get()
+
+      expect(result.data.length).toBe(2)
+      expect(result.data[0]).toMatchObject({ _id: 'doc1', name: 'Alice' })
+      expect(result.total).toBe(2)
+      expect(result.requestId).toBe('req-2')
+    })
+  })
+
+  // ---------- 事务内更新 ----------
+  describe('collection() + where().update()', () => {
+    it('应把 transactionId 传给 database.modifyDocument', async () => {
+      const db = createDb()
+      const tx = await createInitedTransaction(db)
+
+      sendFn.mockResolvedValueOnce({ data: { updated: 1 }, requestId: 'req-3' })
+
+      const result = await tx.collection('users').where({ name: 'Alice' }).update({ age: 25 })
+
+      const call = findCall('database.modifyDocument')
+      expect(call).toBeDefined()
+      expect(call![1]).toMatchObject({
+        collectionName: 'users',
+        transactionId: 'tx-001'
+      })
+      expect(result.updated).toBe(1)
+    })
+  })
+
+  // ---------- 事务内删除 ----------
+  describe('collection() + where().remove()', () => {
+    it('应把 transactionId 传给 database.removeDocument', async () => {
+      const db = createDb()
+      const tx = await createInitedTransaction(db)
+
+      sendFn.mockResolvedValueOnce({ data: { deleted: 3 }, requestId: 'req-4' })
+
+      const result = await tx.collection('users').where({ status: 'inactive' }).remove()
+
+      const call = findCall('database.removeDocument')
+      expect(call).toBeDefined()
+      expect(call![1]).toMatchObject({
+        collectionName: 'users',
+        transactionId: 'tx-001'
+      })
+      expect(result.deleted).toBe(3)
+    })
+  })
+
+  // ---------- 事务内计数 ----------
+  describe('collection() + where().count()', () => {
+    it('应调用 database.calculateDocument 并返回 total', async () => {
+      const db = createDb()
+      const tx = await createInitedTransaction(db)
+
+      sendFn.mockResolvedValueOnce({ data: { total: 5 }, requestId: 'req-5' })
+
+      const result = await tx.collection('users').where({ age: { $gt: 18 } }).count()
+
+      expect(findCall('database.calculateDocument')).toBeDefined()
+      expect(result.total).toBe(5)
+    })
+  })
+
+  // ---------- 事务内插入 ----------
+  describe('collection().add()', () => {
+    it('应把 transactionId 传给 database.insertDocument，并返回事务兼容结果', async () => {
+      const db = createDb()
+      const tx = await createInitedTransaction(db)
+
+      sendFn.mockResolvedValueOnce({ data: { insertedIds: ['new-id'] }, requestId: 'req-6' })
+
+      const result = await tx.collection('users').add({ name: 'New' })
+
+      const call = findCall('database.insertDocument')
+      expect(call).toBeDefined()
+      expect(call![1]).toMatchObject({
+        collectionName: 'users',
+        transactionId: 'tx-001'
+      })
+      expect(result).toMatchObject({ inserted: 1, ok: 1, id: 'new-id' })
+    })
+  })
+
+  // ---------- 事务内文档操作 ----------
+  describe('collection().doc().set()', () => {
+    it('应把 transactionId 传给 database.modifyDocument', async () => {
+      const db = createDb()
+      const tx = await createInitedTransaction(db)
+
+      sendFn.mockResolvedValueOnce({ data: { updated: 1, upsert_id: 'doc1' }, requestId: 'req-7' })
+
+      await tx.collection('users').doc('doc1').set({ name: 'Set' })
+
+      const call = findCall('database.modifyDocument')
+      expect(call).toBeDefined()
+      expect(call![1]).toMatchObject({
+        collectionName: 'users',
+        transactionId: 'tx-001'
+      })
+    })
+  })
+
+  // ---------- 提交 ----------
+  describe('commit()', () => {
+    it('应调用 database.commitTransaction 并携带 transactionId', async () => {
+      const db = createDb()
+      const tx = await createInitedTransaction(db, 'tx-cmt')
+
+      sendFn.mockResolvedValueOnce({ requestId: 'req-cmt' })
+      await tx.commit()
+
+      const call = findCall('database.commitTransaction')
+      expect(call![1]).toEqual({ transactionId: 'tx-cmt' })
+    })
+  })
+})