Merge pull request #961 from objectstack-ai/copilot/cleanup-legacy-driver-sql-support

Author: hotlong

CHANGELOG.md

@@ -22,6 +22,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   schema (added `create`, `read`, `update`, `delete`, `bulkCreate`, `bulkUpdate`, `bulkDelete`,
   `savepoints`, `queryCTE`, `jsonQuery`, `geospatialQuery`, `streaming`, `schemaSync`, etc.).
 
+### Removed
+- **`@objectstack/driver-sql` — Legacy query key fallbacks** — Removed support for deprecated
+  query keys `filters` (use `where`), `sort` (use `orderBy`), `skip` (use `offset`), and `top`
+  (use `limit`) from `find`, `updateMany`, `deleteMany`, and `count` methods. The SQL driver now
+  strictly follows the `IDataDriver` / `QueryAST` protocol. All `as any` casts for legacy key
+  access have been eliminated. Tests updated to use only standard `QueryAST` keys.
+
 ### Deprecated
 - **`DriverInterface`** — Use `IDataDriver` from `@objectstack/spec/contracts` instead.
   `DriverInterface` remains as a type alias in both `@objectstack/spec/contracts` and

packages/plugins/driver-sql/src/sql-driver-advanced.test.ts

@@ -144,7 +144,7 @@ describe('SqlDriver Advanced Operations (SQLite)', () => {
     });
 
     it('should update many records', async () => {
-      const result = await driver.updateMany('orders', { status: 'pending' } as any, { status: 'processing' });
+      const result = await driver.updateMany('orders', { where: { status: 'pending' } } as any, { status: 'processing' });
 
       expect(result).toBeGreaterThan(0);
 
@@ -153,7 +153,7 @@ describe('SqlDriver Advanced Operations (SQLite)', () => {
     });
 
     it('should delete many records', async () => {
-      const result = await driver.deleteMany('orders', { status: 'cancelled' } as any);
+      const result = await driver.deleteMany('orders', { where: { status: 'cancelled' } } as any);
 
       expect(result).toBe(1);
 
@@ -162,10 +162,10 @@ describe('SqlDriver Advanced Operations (SQLite)', () => {
     });
 
     it('should handle empty bulk update and delete', async () => {
-      const result = await driver.updateMany('orders', { status: 'nonexistent' } as any, { status: 'updated' });
+      const result = await driver.updateMany('orders', { where: { status: 'nonexistent' } } as any, { status: 'updated' });
       expect(result).toBe(0);
 
-      const deleteResult = await driver.deleteMany('orders', { id: 'nonexistent' } as any);
+      const deleteResult = await driver.deleteMany('orders', { where: { id: 'nonexistent' } } as any);
       expect(deleteResult).toBe(0);
     });
   });
@@ -365,7 +365,7 @@ describe('SqlDriver Advanced Operations (SQLite)', () => {
 
     it('should handle count with complex filters', async () => {
       const count = await driver.count('orders', {
-        $and: [{ status: 'completed' }, { amount: { $gt: 100 } }],
+        where: { $and: [{ status: 'completed' }, { amount: { $gt: 100 } }] },
       } as any);
 
       expect(count).toBe(2);

packages/plugins/driver-sql/src/sql-driver-queryast.test.ts

@@ -72,22 +72,22 @@ describe('SqlDriver (QueryAST Format)', () => {
   });
 
   describe('QueryAST Format Support', () => {
-    it('should support QueryAST with "top" instead of "limit"', async () => {
+    it('should support QueryAST with limit and orderBy', async () => {
       const results = await driver.find('products', {
         fields: ['name', 'price'],
-        top: 2,
-        sort: [{ field: 'price', order: 'asc' as const }],
+        limit: 2,
+        orderBy: [{ field: 'price', order: 'asc' as const }],
       } as any);
 
       expect(results.length).toBe(2);
       expect(results[0].name).toBe('Mouse');
       expect(results[1].name).toBe('Chair');
     });
 
-    it('should support QueryAST sort format with object notation', async () => {
+    it('should support QueryAST orderBy with object notation', async () => {
       const results = await driver.find('products', {
         fields: ['name'],
-        sort: [
+        orderBy: [
           { field: 'category', order: 'asc' as const },
           { field: 'price', order: 'desc' as const },
         ],
@@ -98,12 +98,12 @@ describe('SqlDriver (QueryAST Format)', () => {
       expect(results[3].name).toBe('Desk');
     });
 
-    it('should support QueryAST with filters and pagination', async () => {
+    it('should support QueryAST with where, offset, limit, and orderBy', async () => {
       const results = await driver.find('products', {
-        filters: [['category', '=', 'Electronics']],
-        skip: 1,
-        top: 1,
-        sort: [{ field: 'price', order: 'asc' as const }],
+        where: [['category', '=', 'Electronics']],
+        offset: 1,
+        limit: 1,
+        orderBy: [{ field: 'price', order: 'asc' as const }],
       } as any);
 
       expect(results.length).toBe(1);
@@ -131,20 +131,20 @@ describe('SqlDriver (QueryAST Format)', () => {
       expect(furniture.total_price).toBe(550);
     });
 
-    it('should support count with QueryAST format', async () => {
+    it('should support count with QueryAST where clause', async () => {
       const count = await driver.count('products', {
-        filters: [['price', '>', 300]],
+        where: [['price', '>', 300]],
       } as any);
       expect(count).toBe(3);
     });
   });
 
-  describe('Backward Compatibility', () => {
-    it('should still support legacy UnifiedQuery format with "limit"', async () => {
+  describe('Standard QueryAST Pagination', () => {
+    it('should support limit with orderBy using standard keys', async () => {
       const results = await driver.find('products', {
         fields: ['name'],
         limit: 2,
-        sort: [['price', 'asc']],
+        orderBy: [['price', 'asc']],
       } as any);
 
       expect(results.length).toBe(2);
@@ -161,14 +161,12 @@ describe('SqlDriver (QueryAST Format)', () => {
       const electronics = results.find((r: any) => r.category === 'Electronics');
       expect(electronics.avg_price).toBeCloseTo(541.67, 1);
     });
-  });
 
-  describe('Mixed Format Support', () => {
-    it('should handle query with both top and skip', async () => {
+    it('should support offset and limit with orderBy', async () => {
       const results = await driver.find('products', {
-        top: 3,
-        skip: 2,
-        sort: [{ field: 'name', order: 'asc' as const }],
+        limit: 3,
+        offset: 2,
+        orderBy: [{ field: 'name', order: 'asc' as const }],
       } as any);
 
       expect(results.length).toBe(3);
@@ -177,4 +175,69 @@ describe('SqlDriver (QueryAST Format)', () => {
       expect(results[2].name).toBe('Mouse');
     });
   });
+
+  describe('Legacy Keys Are Ignored', () => {
+    it('should ignore legacy "filters" key — only "where" is recognized', async () => {
+      const results = await driver.find('products', {
+        filters: [['category', '=', 'Furniture']],
+      } as any);
+
+      // "filters" is not recognized, so no WHERE clause is applied — returns all rows
+      expect(results.length).toBe(5);
+    });
+
+    it('should use "where" and ignore "filters" when both are present', async () => {
+      const results = await driver.find('products', {
+        where: [['category', '=', 'Electronics']],
+        filters: [['category', '=', 'Furniture']],
+      } as any);
+
+      // Only "where" is applied — returns Electronics, not Furniture
+      expect(results.every((r: any) => r.category === 'Electronics')).toBe(true);
+      expect(results.length).toBe(3);
+    });
+
+    it('should ignore legacy "sort" key — only "orderBy" is recognized', async () => {
+      const results = await driver.find('products', {
+        fields: ['name'],
+        limit: 5,
+        orderBy: [{ field: 'price', order: 'desc' as const }],
+        sort: [{ field: 'price', order: 'asc' as const }],
+      } as any);
+
+      // "sort" is ignored; "orderBy" (desc) is applied — most expensive first
+      expect(results.length).toBe(5);
+      expect(results[0].name).toBe('Laptop');
+      expect(results[4].name).toBe('Mouse');
+    });
+
+    it('should ignore legacy "skip" key — only "offset" is recognized', async () => {
+      const results = await driver.find('products', {
+        skip: 3,
+        orderBy: [{ field: 'name', order: 'asc' as const }],
+      } as any);
+
+      // "skip" is not recognized — no offset applied, returns all 5 rows
+      expect(results.length).toBe(5);
+    });
+
+    it('should ignore legacy "top" key — only "limit" is recognized', async () => {
+      const results = await driver.find('products', {
+        top: 2,
+        orderBy: [{ field: 'name', order: 'asc' as const }],
+      } as any);
+
+      // "top" is not recognized — no limit applied, returns all 5 rows
+      expect(results.length).toBe(5);
+    });
+
+    it('should ignore legacy "filters" in count — only "where" is recognized', async () => {
+      const count = await driver.count('products', {
+        filters: [['price', '>', 300]],
+      } as any);
+
+      // "filters" is not recognized — counts all rows
+      expect(count).toBe(5);
+    });
+  });
 });

packages/plugins/driver-sql/src/sql-driver.test.ts

@@ -93,7 +93,7 @@ describe('SqlDriver (SQLite Integration)', () => {
   });
 
   it('should count objects', async () => {
-    const count = await driver.count('users', { age: 17 } as any);
+    const count = await driver.count('users', { where: { age: 17 } } as any);
     expect(count).toBe(2);
   });
 

packages/plugins/driver-sql/src/sql-driver.ts

@@ -177,16 +177,14 @@ export class SqlDriver implements IDataDriver {
       builder.select('*');
     }
 
-    // WHERE — support both `where` (standard) and `filters` (legacy)
-    const filterCondition = query.where || (query as any).filters;
-    if (filterCondition) {
-      this.applyFilters(builder, filterCondition);
+    // WHERE
+    if (query.where) {
+      this.applyFilters(builder, query.where);
     }
 
-    // ORDER BY — support both `orderBy` (standard) and `sort` (legacy)
-    const sortArray = query.orderBy || (query as any).sort;
-    if (sortArray && Array.isArray(sortArray)) {
-      for (const item of sortArray) {
+    // ORDER BY
+    if (query.orderBy && Array.isArray(query.orderBy)) {
+      for (const item of query.orderBy) {
         const field = item.field || item[0];
         const dir = item.order || item[1] || 'asc';
         if (field) {
@@ -195,12 +193,9 @@ export class SqlDriver implements IDataDriver {
       }
     }
 
-    // PAGINATION — support both offset/limit (standard) and skip/top (legacy)
-    const offsetValue = query.offset ?? (query as any).skip;
-    const limitValue = query.limit ?? (query as any).top;
-
-    if (offsetValue !== undefined) builder.offset(offsetValue);
-    if (limitValue !== undefined) builder.limit(limitValue);
+    // PAGINATION
+    if (query.offset !== undefined) builder.offset(query.offset);
+    if (query.limit !== undefined) builder.limit(query.limit);
 
     let results: any[];
     try {
@@ -347,30 +342,23 @@ export class SqlDriver implements IDataDriver {
 
   async updateMany(object: string, query: QueryAST, data: any, options?: DriverOptions): Promise<number> {
     const builder = this.getBuilder(object, options);
-    const filters = query.where || (query as any).filters || query;
-    if (filters) this.applyFilters(builder, filters);
+    if (query.where) this.applyFilters(builder, query.where);
     const count = await builder.update(data);
     return count || 0;
   }
 
   async deleteMany(object: string, query: QueryAST, options?: DriverOptions): Promise<number> {
     const builder = this.getBuilder(object, options);
-    const filters = query.where || (query as any).filters || query;
-    if (filters) this.applyFilters(builder, filters);
+    if (query.where) this.applyFilters(builder, query.where);
     const count = await builder.delete();
     return count || 0;
   }
 
   async count(object: string, query?: QueryAST, options?: DriverOptions): Promise<number> {
     const builder = this.getBuilder(object, options);
 
-    let actualFilters = query as any;
-    if (query && (query.where || (query as any).filters)) {
-      actualFilters = query.where || (query as any).filters;
-    }
-
-    if (actualFilters) {
-      this.applyFilters(builder, actualFilters);
+    if (query?.where) {
+      this.applyFilters(builder, query.where);
     }
 
     const result = await builder.count<{ count: number }[]>('* as count');
@@ -742,7 +730,7 @@ export class SqlDriver implements IDataDriver {
       }
 
       for (const [key, value] of Object.entries(filters)) {
-        if (['filters', 'sort', 'limit', 'skip', 'offset', 'fields', 'orderBy'].includes(key)) continue;
+        if (['limit', 'offset', 'fields', 'orderBy'].includes(key)) continue;
         builder.where(key, value as any);
       }
       return;