address review: add documentation comments and findStream streaming test

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Agent-Logs-Url: https://github.com/objectstack-ai/spec/sessions/01412f6e-dbc1-4384-a4d7-5b6bd4a575b0

Author: Copilot

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

@@ -243,6 +243,11 @@ export class SqlDriver implements IDataDriver {
     return null;
   }
 
+  /**
+   * Stream records matching a structured query.
+   * NOTE: Current implementation fetches all results then yields them.
+   * TODO: Use Knex .stream() for true cursor-based streaming on large datasets.
+   */
   async *findStream(object: string, query: QueryInput, options?: DriverOptions): AsyncGenerator<Record<string, any>> {
     const results = await this.find(object, query, options);
     for (const row of results) {
@@ -321,6 +326,11 @@ export class SqlDriver implements IDataDriver {
     return await builder.insert(data).returning('*');
   }
 
+  /**
+   * Batch-update multiple records by ID.
+   * NOTE: Current implementation performs sequential updates for correctness.
+   * TODO: Optimize with SQL CASE statements or batched transactions for performance.
+   */
   async bulkUpdate(object: string, updates: Array<{ id: string | number; data: Record<string, any> }>, options?: DriverOptions): Promise<Record<string, any>[]> {
     const results: Record<string, any>[] = [];
     for (const { id, data } of updates) {

packages/spec/src/contracts/data-engine.test.ts

@@ -272,5 +272,46 @@ describe('Data Engine Contract', () => {
       expect(await driver.count('users')).toBe(42);
       expect(driver.explain).toBeDefined();
     });
+
+    it('should support findStream with yielded values', async () => {
+      const records = [{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }];
+      const driver: DriverInterface = {
+        name: 'streamer',
+        version: '1.0.0',
+        supports: { ...minimalCapabilities, streaming: true },
+        connect: async () => {},
+        disconnect: async () => {},
+        checkHealth: async () => true,
+        execute: async () => ({}),
+        find: async () => records,
+        findStream: () => (async function* () {
+          for (const r of records) yield r;
+        })(),
+        findOne: async () => null,
+        create: async (_obj, data) => ({ id: '1', ...data }),
+        update: async (_obj, _id, data) => ({ id: '1', ...data }),
+        upsert: async (_obj, data) => ({ id: '1', ...data }),
+        delete: async () => true,
+        count: async () => records.length,
+        bulkCreate: async () => [],
+        bulkUpdate: async () => [],
+        bulkDelete: async () => {},
+        beginTransaction: async () => ({}),
+        commit: async () => {},
+        rollback: async () => {},
+        syncSchema: async () => {},
+        dropTable: async () => {},
+      };
+
+      const stream = driver.findStream('users', {} as any);
+      const collected: any[] = [];
+      for await (const row of stream as AsyncIterable<any>) {
+        collected.push(row);
+      }
+
+      expect(collected).toHaveLength(2);
+      expect(collected[0].name).toBe('Alice');
+      expect(collected[1].name).toBe('Bob');
+    });
   });
 });