Merge branch 'trunk' into fix/server-side-parameter-binding

Author: sgrebnov

src/client-common.ts

@@ -203,6 +203,35 @@ function convertArrowValue(value: any, field?: any): any {
  * - Timestamp types: Converts Date objects to ISO 8601 strings (without Z for timestamps without timezone)
  * - List types: Converts Arrow Vector objects to JavaScript arrays
  */
+/**
+ * Coerces a `/v1/nsql` payload into the documented {@link NsqlResponse} shape.
+ *
+ * The runtime omits `schema` entirely when the generated query returned no rows,
+ * and a runtime that does not honor the `application/vnd.spiceai.nsql.v1+json`
+ * Accept header answers with a bare array of rows. Both are normalized here so
+ * callers can always read `sql`, `data`, `schema.fields` and `row_count`.
+ */
+function normalizeNsqlResponse(payload: unknown): NsqlResponse {
+  if (Array.isArray(payload)) {
+    return {
+      row_count: payload.length,
+      schema: { fields: [] },
+      data: payload,
+      sql: '',
+    };
+  }
+
+  const result = (payload ?? {}) as Partial<NsqlResponse>;
+  const data = result.data ?? [];
+
+  return {
+    row_count: result.row_count ?? data.length,
+    schema: { fields: result.schema?.fields ?? [] },
+    data,
+    sql: result.sql ?? '',
+  };
+}
+
 function wrapTableForDecimalConversion(table: Table): Table {
   const originalToArray = table.toArray.bind(table);
 
@@ -1387,6 +1416,9 @@ export class SpiceClient {
       '/v1/nsql',
       undefined,
       JSON.stringify(request),
+      // Without this the runtime replies with a bare array of rows, which
+      // carries neither the generated SQL nor the schema.
+      { Accept: 'application/vnd.spiceai.nsql.v1+json' },
     );
 
     if (!response.ok) {
@@ -1397,7 +1429,7 @@ export class SpiceClient {
     }
 
     const result = await response.json();
-    return result as NsqlResponse;
+    return normalizeNsqlResponse(result);
   }
 
   /**

test/browser/client.test.ts

@@ -438,11 +438,12 @@ describe('Browser SpiceClient', () => {
 
   describe('NSQL (Natural Language SQL)', () => {
     test('should execute NSQL query', async () => {
+      // Shape the runtime returns for application/vnd.spiceai.nsql.v1+json.
       const mockResponse = {
-        sql: 'SELECT * FROM users LIMIT 10',
-        schema: [{ name: 'id', data_type: 'Int32' }],
-        rows: [[1]],
         row_count: 1,
+        schema: { fields: [{ name: 'id', data_type: 'Int32' }] },
+        data: [{ id: 1 }],
+        sql: 'SELECT * FROM users LIMIT 10',
       };
 
       (global.fetch as jest.Mock).mockResolvedValueOnce({
@@ -457,16 +458,70 @@ describe('Browser SpiceClient', () => {
 
       const result = await client.nsql('show me users');
 
-      expect(result).toHaveProperty('sql');
       expect(result.sql).toBe('SELECT * FROM users LIMIT 10');
+      expect(result.row_count).toBe(1);
+      expect(result.data).toEqual([{ id: 1 }]);
+      expect(result.schema.fields).toEqual([{ name: 'id', data_type: 'Int32' }]);
       expect(global.fetch).toHaveBeenCalledWith(
         'http://localhost:8090/v1/nsql',
         expect.objectContaining({
           method: 'POST',
+          headers: expect.objectContaining({
+            Accept: 'application/vnd.spiceai.nsql.v1+json',
+          }),
         }),
       );
     });
 
+    test('should normalize a bare row array into the documented shape', async () => {
+      // What the runtime sends when the Accept header is absent or stripped.
+      const rows = [{ id: 1 }, { id: 2 }];
+
+      (global.fetch as jest.Mock).mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        headers: {
+          get: jest.fn(),
+        },
+        text: jest.fn().mockResolvedValue(JSON.stringify(rows)),
+        json: jest.fn().mockResolvedValue(rows),
+      });
+
+      const result = await client.nsql('show me users');
+
+      expect(result.data).toEqual(rows);
+      expect(result.row_count).toBe(2);
+      expect(result.schema.fields).toEqual([]);
+      expect(result.sql).toBe('');
+    });
+
+    test('should tolerate an empty result set', async () => {
+      // The runtime omits schema fields entirely when no rows are returned.
+      const mockResponse = {
+        row_count: 0,
+        schema: {},
+        data: [],
+        sql: 'SELECT * FROM users WHERE false',
+      };
+
+      (global.fetch as jest.Mock).mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        headers: {
+          get: jest.fn(),
+        },
+        text: jest.fn().mockResolvedValue(JSON.stringify(mockResponse)),
+        json: jest.fn().mockResolvedValue(mockResponse),
+      });
+
+      const result = await client.nsql('show me users');
+
+      expect(result.schema.fields).toEqual([]);
+      expect(result.data).toEqual([]);
+      expect(result.row_count).toBe(0);
+      expect(result.sql).toBe('SELECT * FROM users WHERE false');
+    });
+
     test('should handle NSQL errors', async () => {
       (global.fetch as jest.Mock).mockResolvedValueOnce({
         ok: false,