@cloudbase/database 0.11.0 → 0.12.1

package/tests/transaction-query.test.ts

@@ -0,0 +1,657 @@
+import { EJSON } from 'bson'
+import { Query } from '../src/transaction/query'
+import { Transaction } from '../src/transaction/index'
+import { ErrorCode } from '../src/constant'
+
+// ===================== Mock 工具 =====================
+
+/** 创建一个模拟的 TransactionAPI（_request） */
+function createMockRequest(sendFn?: jest.Mock) {
+  return {
+    send: sendFn || jest.fn().mockResolvedValue({
+      data: 'null',
+      requestId: 'mock-req-id'
+    })
+  }
+}
+
+/** 创建一个模拟的 Transaction 实例 */
+function createMockTransaction(overrides?: {
+  transactionId?: string
+  sendFn?: jest.Mock
+}) {
+  const txId = overrides?.transactionId || 'mock-tx-id-123'
+  const request = createMockRequest(overrides?.sendFn)
+
+  const transaction = {
+    getRequestMethod: jest.fn().mockReturnValue(request),
+    getTransactionId: jest.fn().mockReturnValue(txId)
+  } as unknown as Transaction
+
+  return { transaction, request, txId }
+}
+
+// ===================== 测试用例 =====================
+
+describe('Transaction Query', () => {
+
+  // ---------- 构造函数 ----------
+  describe('constructor', () => {
+    it('应正确初始化默认参数', () => {
+      const { transaction } = createMockTransaction()
+      const _query = new Query(transaction, 'test-coll')
+
+      // 内部属性通过链式调用间接验证
+      expect(transaction.getRequestMethod).toHaveBeenCalled()
+      expect(transaction.getTransactionId).toHaveBeenCalled()
+      expect(_query).toBeTruthy()
+    })
+
+    it('应接受可选的 fieldFilters、fieldOrders 和 queryOptions', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(
+        transaction,
+        'test-coll',
+        { name: 'test' },
+        [{ field: 'age', direction: 'asc' }],
+        { limit: 10, offset: 5 }
+      )
+      // 构造不应抛出
+      expect(query).toBeTruthy()
+    })
+  })
+
+  // ---------- where ----------
+  describe('where()', () => {
+    it('传入合法对象应返回新的 Query 实例', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+      const newQuery = query.where({ age: 18 })
+
+      expect(newQuery).toBeInstanceOf(Query)
+      expect(newQuery).not.toBe(query) // 返回新实例
+    })
+
+    it('传入非对象应抛出 QueryParamTypeError', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+
+      expect(() => query.where('invalid' as any)).toThrow(ErrorCode.QueryParamTypeError)
+      expect(() => query.where(123 as any)).toThrow(ErrorCode.QueryParamTypeError)
+      expect(() => query.where(null as any)).toThrow(ErrorCode.QueryParamTypeError)
+    })
+
+    it('所有值均为 undefined 应抛出 QueryParamValueError', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+
+      expect(() => query.where({ a: undefined, b: undefined })).toThrow(
+        ErrorCode.QueryParamValueError
+      )
+    })
+
+    it('空对象不应抛出错误', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+
+      // 空对象 keys.length === 0，不会走 checkFlag 分支
+      expect(() => query.where({})).not.toThrow()
+    })
+
+    it('部分值为 undefined 但至少有一个非 undefined 时不应抛出', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+
+      expect(() => query.where({ a: undefined, b: 1 })).not.toThrow()
+    })
+  })
+
+  // ---------- orderBy ----------
+  describe('orderBy()', () => {
+    it('传入合法字段和方向应返回新的 Query 实例', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+      const newQuery = query.orderBy('name', 'asc')
+
+      expect(newQuery).toBeInstanceOf(Query)
+      expect(newQuery).not.toBe(query)
+    })
+
+    it('可链式调用多次 orderBy', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+      const newQuery = query.orderBy('name', 'asc').orderBy('age', 'desc')
+
+      expect(newQuery).toBeInstanceOf(Query)
+    })
+
+    it('传入非法排序方向应抛出错误', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+
+      expect(() => query.orderBy('name', 'invalid' as any)).toThrow(ErrorCode.DirectionError)
+    })
+  })
+
+  // ---------- limit ----------
+  describe('limit()', () => {
+    it('传入合法整数应返回新的 Query 实例', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+      const newQuery = query.limit(10)
+
+      expect(newQuery).toBeInstanceOf(Query)
+      expect(newQuery).not.toBe(query)
+    })
+
+    it('传入非整数应抛出错误', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+
+      expect(() => query.limit(1.5)).toThrow()
+      expect(() => query.limit(NaN)).toThrow()
+    })
+  })
+
+  // ---------- skip ----------
+  describe('skip()', () => {
+    it('传入合法整数应返回新的 Query 实例', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+      const newQuery = query.skip(20)
+
+      expect(newQuery).toBeInstanceOf(Query)
+      expect(newQuery).not.toBe(query)
+    })
+
+    it('传入非整数应抛出错误', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+
+      expect(() => query.skip(2.3)).toThrow()
+    })
+  })
+
+  // ---------- field ----------
+  describe('field()', () => {
+    it('truthy 的非对象值应被转为 1', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+      const newQuery = query.field({ name: true, age: 'yes', score: 1 })
+
+      expect(newQuery).toBeInstanceOf(Query)
+      expect(newQuery).not.toBe(query)
+    })
+
+    it('falsy 值应被转为 0', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+      const newQuery = query.field({ name: true, secret: false, hidden: 0 })
+
+      expect(newQuery).toBeInstanceOf(Query)
+    })
+
+    it('对象类型的值应保持不变', () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'test-coll')
+      const projection = { name: { $slice: 1 } }
+      const newQuery = query.field(projection)
+
+      expect(newQuery).toBeInstanceOf(Query)
+      // 对象值不会被转为 1
+      expect(projection.name).toEqual({ $slice: 1 })
+    })
+  })
+
+  // ---------- get ----------
+  describe('get()', () => {
+    it('应正确发送请求并返回文档列表', async () => {
+      const mockData = [{ _id: 'doc1', name: 'Alice' }, { _id: 'doc2', name: 'Bob' }]
+      const sendFn = jest.fn().mockResolvedValue({
+        data: EJSON.stringify(mockData, { relaxed: false }),
+        requestId: 'req-001',
+        total: 2,
+        limit: 100,
+        offset: 0
+      })
+      const { transaction, txId } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users')
+
+      const result = await query.get()
+
+      // 验证请求参数
+      expect(sendFn).toHaveBeenCalledWith('database.getInTransaction', expect.objectContaining({
+        collectionName: 'users',
+        transactionId: txId,
+        limit: 100 // 默认 limit
+      }))
+
+      // 验证返回结构
+      expect(result.requestId).toBe('req-001')
+      expect(result.total).toBe(2)
+      expect(result.limit).toBe(100)
+      expect(result.offset).toBe(0)
+      expect(Array.isArray(result.data)).toBe(true)
+      expect(result.data.length).toBe(2)
+    })
+
+    it('data 为 "null" 时应返回空数组', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        data: 'null',
+        requestId: 'req-002'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users')
+
+      const result = await query.get()
+
+      expect(result.data).toEqual([])
+      expect(result.requestId).toBe('req-002')
+    })
+
+    it('返回单个文档对象时应包装为数组', async () => {
+      const singleDoc = { _id: 'doc1', name: 'Alice' }
+      const sendFn = jest.fn().mockResolvedValue({
+        data: EJSON.stringify(singleDoc, { relaxed: false }),
+        requestId: 'req-003'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users')
+
+      const result = await query.get()
+
+      expect(result.data.length).toBe(1)
+    })
+
+    it('limit 超过 1000 时应限制为 1000', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        data: 'null',
+        requestId: 'req-004'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users', undefined, [], { limit: 5000 })
+
+      await query.get()
+
+      expect(sendFn).toHaveBeenCalledWith('database.getInTransaction', expect.objectContaining({
+        limit: 1000
+      }))
+    })
+
+    it('limit 小于 1000 时应使用设定值', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        data: 'null',
+        requestId: 'req-005'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users', undefined, [], { limit: 50 })
+
+      await query.get()
+
+      expect(sendFn).toHaveBeenCalledWith('database.getInTransaction', expect.objectContaining({
+        limit: 50
+      }))
+    })
+
+    it('设置了 offset 应正确传参', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        data: 'null',
+        requestId: 'req-006'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users', undefined, [], { offset: 10 })
+
+      await query.get()
+
+      expect(sendFn).toHaveBeenCalledWith('database.getInTransaction', expect.objectContaining({
+        offset: 10
+      }))
+    })
+
+    it('设置了 orderBy 应正确传参', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        data: 'null',
+        requestId: 'req-007'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const orders = [{ field: 'age', direction: 'desc' as const }]
+      const query = new Query(transaction, 'users', undefined, orders)
+
+      await query.get()
+
+      expect(sendFn).toHaveBeenCalledWith('database.getInTransaction', expect.objectContaining({
+        order: [{ field: 'age', direction: 'desc' }]
+      }))
+    })
+
+    it('设置了 projection 应正确传参', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        data: 'null',
+        requestId: 'req-008'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users', undefined, [], { projection: { name: 1 } })
+
+      await query.get()
+
+      expect(sendFn).toHaveBeenCalledWith('database.getInTransaction', expect.objectContaining({
+        projection: { name: 1 }
+      }))
+    })
+
+    it('设置了 fieldFilters 应作为 query 参数传递', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        data: 'null',
+        requestId: 'req-009'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const filters = { age: { $gt: 18 } }
+      const query = new Query(transaction, 'users', filters)
+
+      await query.get()
+
+      expect(sendFn).toHaveBeenCalledWith('database.getInTransaction', expect.objectContaining({
+        query: filters
+      }))
+    })
+
+    it('接口返回错误码应抛出异常', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        code: 'DATABASE_ERROR',
+        message: 'something went wrong',
+        requestId: 'req-err'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users')
+
+      await expect(query.get()).rejects.toEqual(expect.objectContaining({
+        code: 'DATABASE_ERROR'
+      }))
+    })
+
+    it('返回的 result 不含 total/limit/offset 时结果中不应包含对应字段', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        data: 'null',
+        requestId: 'req-010'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users')
+
+      const result = await query.get()
+
+      expect(result).not.toHaveProperty('total')
+      expect(result).not.toHaveProperty('limit')
+      expect(result).not.toHaveProperty('offset')
+    })
+  })
+
+  // ---------- count ----------
+  describe('count()', () => {
+    it('应返回 total 和 requestId', async () => {
+      const mockData = [{ _id: '1' }, { _id: '2' }, { _id: '3' }]
+      const sendFn = jest.fn().mockResolvedValue({
+        data: EJSON.stringify(mockData, { relaxed: false }),
+        requestId: 'req-cnt-001',
+        total: 3
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users')
+
+      const result = await query.count()
+
+      expect(result.requestId).toBe('req-cnt-001')
+      expect(result.total).toBe(3)
+    })
+
+    it('后端返回 total 字段时应优先使用后端值', async () => {
+      const mockData = [{ _id: '1' }]
+      const sendFn = jest.fn().mockResolvedValue({
+        data: EJSON.stringify(mockData, { relaxed: false }),
+        requestId: 'req-cnt-002',
+        total: 100 // 后端总数与 data 长度不同（分页场景）
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users')
+
+      const result = await query.count()
+
+      expect(result.total).toBe(100)
+    })
+
+    it('后端未返回 total 时应根据 data 长度计算', async () => {
+      const mockData = [{ _id: '1' }, { _id: '2' }]
+      const sendFn = jest.fn().mockResolvedValue({
+        data: EJSON.stringify(mockData, { relaxed: false }),
+        requestId: 'req-cnt-003'
+        // 无 total 字段
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users')
+
+      const result = await query.count()
+
+      expect(result.total).toBe(2)
+    })
+
+    it('data 为 "null" 且无 total 时应返回 0', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        data: 'null',
+        requestId: 'req-cnt-004'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users')
+
+      const result = await query.count()
+
+      expect(result.total).toBe(0)
+    })
+
+    it('应携带 fieldFilters 作为 query 参数', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        data: 'null',
+        requestId: 'req-cnt-005'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const filters = { status: 'active' }
+      const query = new Query(transaction, 'users', filters)
+
+      await query.count()
+
+      expect(sendFn).toHaveBeenCalledWith('database.getInTransaction', expect.objectContaining({
+        query: filters
+      }))
+    })
+
+    it('接口返回错误码应抛出异常', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        code: 'PERMISSION_DENIED',
+        message: 'no access',
+        requestId: 'req-cnt-err'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users')
+
+      await expect(query.count()).rejects.toEqual(expect.objectContaining({
+        code: 'PERMISSION_DENIED'
+      }))
+    })
+  })
+
+  // ---------- update ----------
+  describe('update()', () => {
+    it('应正确发送更新请求', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        requestId: 'req-upd-001',
+        updated: EJSON.stringify(1, { relaxed: false })
+      })
+      const { transaction, txId } = createMockTransaction({ sendFn })
+      const filters = { name: 'Alice' }
+      const query = new Query(transaction, 'users', filters)
+
+      const result = await query.update({ age: 25 })
+
+      expect(sendFn).toHaveBeenCalledWith('database.updateDocInTransaction', expect.objectContaining({
+        collectionName: 'users',
+        transactionId: txId,
+        query: filters
+      }))
+      expect(result.requestId).toBe('req-upd-001')
+      expect(result.updated).toBe(1)
+    })
+
+    it('传入空数据或非对象应抛出错误', async () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'users')
+
+      await expect(query.update(null as any)).rejects.toThrow('参数必需是非空对象')
+      await expect(query.update(undefined as any)).rejects.toThrow('参数必需是非空对象')
+      await expect(query.update('str' as any)).rejects.toThrow('参数必需是非空对象')
+    })
+
+    it('更新数据包含 _id 应抛出错误', async () => {
+      const { transaction } = createMockTransaction()
+      const query = new Query(transaction, 'users')
+
+      await expect(query.update({ _id: 'some-id', name: 'test' })).rejects.toThrow('不能更新_id的值')
+    })
+
+    it('接口返回错误码应抛出异常', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        code: 'DATABASE_ERROR',
+        message: 'update failed',
+        requestId: 'req-upd-err'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users', { name: 'test' })
+
+      await expect(query.update({ age: 20 })).rejects.toEqual(expect.objectContaining({
+        code: 'DATABASE_ERROR'
+      }))
+    })
+  })
+
+  // ---------- remove ----------
+  describe('remove()', () => {
+    it('应正确发送删除请求', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        requestId: 'req-del-001',
+        deleted: EJSON.stringify(3, { relaxed: false })
+      })
+      const { transaction, txId } = createMockTransaction({ sendFn })
+      const filters = { status: 'inactive' }
+      const query = new Query(transaction, 'users', filters)
+
+      const result = await query.remove()
+
+      expect(sendFn).toHaveBeenCalledWith('database.deleteDocInTransaction', expect.objectContaining({
+        collectionName: 'users',
+        transactionId: txId,
+        query: filters
+      }))
+      expect(result.requestId).toBe('req-del-001')
+      expect(result.deleted).toBe(3)
+    })
+
+    it('有 queryOptions 时应输出警告', async () => {
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      const sendFn = jest.fn().mockResolvedValue({
+        requestId: 'req-del-002',
+        deleted: EJSON.stringify(0, { relaxed: false })
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users', {}, [], { limit: 10 })
+
+      await query.remove()
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        '`offset`, `limit` and `projection` are not supported in remove() operation'
+      )
+      warnSpy.mockRestore()
+    })
+
+    it('有 orderBy 时应输出警告', async () => {
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      const sendFn = jest.fn().mockResolvedValue({
+        requestId: 'req-del-003',
+        deleted: EJSON.stringify(0, { relaxed: false })
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const orders = [{ field: 'name', direction: 'asc' as const }]
+      const query = new Query(transaction, 'users', {}, orders)
+
+      await query.remove()
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        '`orderBy` is not supported in remove() operation'
+      )
+      warnSpy.mockRestore()
+    })
+
+    it('接口返回错误码应抛出异常', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        code: 'PERMISSION_DENIED',
+        message: 'cannot delete',
+        requestId: 'req-del-err'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users', { name: 'test' })
+
+      await expect(query.remove()).rejects.toEqual(expect.objectContaining({
+        code: 'PERMISSION_DENIED'
+      }))
+    })
+  })
+
+  // ---------- 链式调用 ----------
+  describe('链式调用', () => {
+    it('where → orderBy → limit → skip → field → get 全链路调用', async () => {
+      const mockData = [{ _id: 'doc1', name: 'Alice', age: 20 }]
+      const sendFn = jest.fn().mockResolvedValue({
+        data: EJSON.stringify(mockData, { relaxed: false }),
+        requestId: 'req-chain-001',
+        total: 1
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const query = new Query(transaction, 'users')
+
+      const result = await query
+        .where({ age: 20 })
+        .orderBy('name', 'asc')
+        .limit(10)
+        .skip(5)
+        .field({ name: true, age: true })
+        .get()
+
+      expect(result.data.length).toBe(1)
+      expect(result.requestId).toBe('req-chain-001')
+
+      // 验证请求参数中包含各种设置
+      const callArgs = sendFn.mock.calls[0][1]
+      expect(callArgs.collectionName).toBe('users')
+      expect(callArgs.limit).toBe(10)
+      expect(callArgs.offset).toBe(5)
+      expect(callArgs.order).toEqual([{ field: 'name', direction: 'asc' }])
+      expect(callArgs.projection).toBeDefined()
+      expect(callArgs.query).toBeDefined()
+    })
+
+    it('每次链式调用都返回新的 Query 实例，不影响原实例', async () => {
+      const sendFn = jest.fn().mockResolvedValue({
+        data: 'null',
+        requestId: 'req-immutable'
+      })
+      const { transaction } = createMockTransaction({ sendFn })
+      const baseQuery = new Query(transaction, 'users')
+
+      const q1 = baseQuery.where({ age: 18 })
+      const q2 = baseQuery.where({ name: 'Bob' })
+      const q3 = q1.limit(5)
+
+      // 都是不同的实例
+      expect(q1).not.toBe(baseQuery)
+      expect(q2).not.toBe(baseQuery)
+      expect(q3).not.toBe(q1)
+      expect(q1).not.toBe(q2)
+    })
+  })
+})