@object-ui/data-objectstack 16.1.0 → 17.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "16.1.0",
+  "version": "17.2.0",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -22,9 +22,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@objectstack/client": "^16.0.0-rc.0",
-    "@object-ui/core": "16.1.0",
-    "@object-ui/types": "16.1.0"
+    "@objectstack/client": "^17.0.0-rc.1",
+    "@objectstack/spec": "^17.0.0-rc.1",
+    "@object-ui/core": "17.2.0",
+    "@object-ui/types": "17.2.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/src/aggregate-capability.test.ts

@@ -0,0 +1,177 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * `aggregate()` against an analytics endpoint that cannot answer.
+ *
+ * WHY THIS EXISTS. `@objectstack/client`'s `analytics.query()` returns
+ * `res.json()` WITHOUT checking `res.ok`, so a non-2xx never throws — the error
+ * body arrives where rows were expected. The adapter's row parser matched none
+ * of its shapes, produced `[]`, and returned it as a RESULT: the `catch` that
+ * promises a client-side fallback never ran, and a KPI on a deployment without
+ * `@objectstack/service-analytics` rendered a confident **zero**.
+ *
+ * That is the same lie framework#3891 removed from the server side (a degraded
+ * shim answering 200 with unscoped numbers), reproduced one layer up. These
+ * tests pin the three outcomes:
+ *   - capability absent (404 / 501)  → client-side fallback over a scoped find();
+ *   - our body is off-contract (400) → THROWS, never silently re-answered;
+ *   - a normal result                → untouched.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ObjectStackAdapter, clearSharedDiscoveryCache } from './index';
+
+const RECORDS = [
+  { id: '1', stage: 'won', amount: 100 },
+  { id: '2', stage: 'won', amount: 50 },
+  { id: '3', stage: 'lost', amount: 20 },
+];
+
+/**
+ * A fetch mock answering discovery, the analytics query (with `analyticsBody`
+ * at `analyticsStatus`), and the `/data` read the fallback performs.
+ */
+function makeFetch(analyticsStatus: number, analyticsBody: unknown) {
+  const calls: string[] = [];
+  const fetchImpl = vi.fn(async (url: any, init?: any) => {
+    const u = String(url);
+    calls.push(`${init?.method ?? 'GET'} ${u}`);
+    if (u.includes('/api/v1/discovery')) {
+      return { ok: true, status: 200, statusText: 'OK', json: async () => ({ success: true, data: { version: 'v1', routes: {} } }) } as any;
+    }
+    if (u.includes('/api/v1/analytics/query')) {
+      return {
+        ok: analyticsStatus >= 200 && analyticsStatus < 300,
+        status: analyticsStatus,
+        statusText: 'x',
+        json: async () => analyticsBody,
+      } as any;
+    }
+    // The fallback's scoped read.
+    return {
+      ok: true, status: 200, statusText: 'OK',
+      json: async () => ({ success: true, data: { object: 'opportunity', records: RECORDS, total: RECORDS.length } }),
+    } as any;
+  });
+  return { fetchImpl, calls };
+}
+
+function makeAdapter(fetchImpl: any) {
+  return new ObjectStackAdapter({
+    baseUrl: 'http://localhost:3000',
+    autoReconnect: false,
+    fetch: fetchImpl as any,
+  });
+}
+
+const SUM_BY_STAGE = { function: 'sum', field: 'amount', groupBy: 'stage' };
+
+describe('aggregate() when the analytics capability is absent', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  it('404 (routes not mounted, framework#4019) falls back instead of returning an empty result', async () => {
+    const { fetchImpl, calls } = makeFetch(404, { error: 'Not found' });
+    const rows = await makeAdapter(fetchImpl).aggregate('opportunity', SUM_BY_STAGE);
+
+    // Pre-fix this was `[]` — a chart reading "no data" on a populated table.
+    expect(rows.length).toBeGreaterThan(0);
+    const won = rows.find((r: any) => r.stage === 'won');
+    expect(won?.amount).toBe(150);
+    // It really did fall back to a server-side read (not invent numbers).
+    expect(calls.some((c) => c.includes('/api/v1/data'))).toBe(true);
+  });
+
+  it('501 NOT_IMPLEMENTED (REST route, no service) falls back the same way', async () => {
+    const { fetchImpl } = makeFetch(501, {
+      code: 'NOT_IMPLEMENTED',
+      message: 'Analytics is not available on this deployment.',
+    });
+    const rows = await makeAdapter(fetchImpl).aggregate('opportunity', SUM_BY_STAGE);
+    expect(rows.find((r: any) => r.stage === 'won')?.amount).toBe(150);
+  });
+
+  it('warns ONCE per adapter, not once per widget', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const { fetchImpl } = makeFetch(404, { error: 'Not found' });
+      const adapter = makeAdapter(fetchImpl);
+      await adapter.aggregate('opportunity', SUM_BY_STAGE);
+      await adapter.aggregate('opportunity', SUM_BY_STAGE);
+      await adapter.aggregate('opportunity', SUM_BY_STAGE);
+
+      const capabilityWarnings = warn.mock.calls.filter((c) =>
+        String(c[0]).includes('analytics capability unavailable'),
+      );
+      expect(capabilityWarnings).toHaveLength(1);
+      expect(String(capabilityWarnings[0][0])).toContain('@objectstack/service-analytics');
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('forwards the widget filter into the fallback (never aggregates the whole table)', async () => {
+    const { fetchImpl, calls } = makeFetch(404, { error: 'Not found' });
+    await makeAdapter(fetchImpl).aggregate('opportunity', { ...SUM_BY_STAGE, filter: { stage: 'won' } });
+
+    const dataCall = calls.find((c) => c.includes('/api/v1/data'));
+    expect(dataCall).toBeDefined();
+    expect(decodeURIComponent(dataCall!)).toContain('won');
+  });
+});
+
+describe('aggregate() when the server REJECTS our query body', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  // framework#4010 validates /analytics/query at the entry. A 400 means the
+  // adapter sent an off-contract body — answering it with numbers from the
+  // client-side path would bury our own bug behind plausible output, which is
+  // exactly the misdirection framework#3878 documented.
+  it('400 VALIDATION_FAILED throws — it must NOT be answered by the fallback', async () => {
+    const { fetchImpl, calls } = makeFetch(400, {
+      success: false,
+      error: {
+        code: 'VALIDATION_FAILED',
+        httpStatus: 400,
+        message: 'Invalid AnalyticsQuery body: measures: Invalid input',
+        details: { fields: [{ field: 'measures', code: 'invalid_type' }] },
+      },
+    });
+
+    const err = await makeAdapter(fetchImpl).aggregate('opportunity', SUM_BY_STAGE).catch((e) => e);
+
+    expect(err).toBeInstanceOf(Error);
+    expect((err as { code?: string }).code).toBe('ANALYTICS_QUERY_REJECTED');
+    expect(String(err.message)).toContain('measures');
+    // No silent second answer from a different code path.
+    expect(calls.some((c) => c.includes('/api/v1/data'))).toBe(false);
+  });
+});
+
+describe('aggregate() on a healthy analytics endpoint', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  it('returns the server rows untouched (no false capability detection)', async () => {
+    const { fetchImpl, calls } = makeFetch(200, {
+      rows: [{ stage: 'won', amount_sum: 150 }],
+      fields: [{ name: 'amount_sum', type: 'number' }],
+    });
+
+    const rows = await makeAdapter(fetchImpl).aggregate('opportunity', SUM_BY_STAGE);
+
+    // Measure key mapped back to the caller's column (`amount`), rows from the server.
+    expect(rows).toEqual([{ stage: 'won', amount: 150 }]);
+    expect(calls.some((c) => c.includes('/api/v1/data'))).toBe(false);
+  });
+
+  it('a `{ success, data: { rows } }` envelope is still a result, not an error', async () => {
+    const { fetchImpl } = makeFetch(200, { success: true, data: { rows: [{ stage: 'won', amount_sum: 150 }] } });
+    const rows = await makeAdapter(fetchImpl).aggregate('opportunity', SUM_BY_STAGE);
+    expect(rows).toEqual([{ stage: 'won', amount: 150 }]);
+  });
+});

package/src/cache/MetadataCache.ts

@@ -17,9 +17,18 @@ interface CachedSchema {
 }
 
 /**
- * Cache statistics for monitoring
+ * Statistics reported by {@link MetadataCache.getStats} for monitoring.
+ *
+ * NOT the spec's `CacheStats` (`@objectstack/spec/contracts`), whose name this
+ * interface wore until objectui#3160 (objectstack#4115 ledger batch 6). That one
+ * describes the platform's `ICacheService` — a server-side KV cache measured by
+ * `keyCount` and `memoryUsage`. This one describes the browser-side LRU in front
+ * of `/api/v1/meta/*`: it is bounded (`size`/`maxSize`), it evicts, it coalesces
+ * concurrent fetches onto one in-flight promise, and it reports a `hitRate`.
+ * Neither type has a key the other has, so this is a name collision, not a
+ * dialect — deriving would have replaced every field.
  */
-export interface CacheStats {
+export interface MetadataCacheStats {
   size: number;
   maxSize: number;
   hits: number;
@@ -218,7 +227,7 @@ export class MetadataCache {
    * 
    * @returns Cache statistics including hit rate
    */
-  getStats(): CacheStats {
+  getStats(): MetadataCacheStats {
     const total = this.stats.hits + this.stats.misses;
     const hitRate = total > 0 ? this.stats.hits / total : 0;
 

package/src/errors.test.ts

@@ -13,7 +13,7 @@ import {
   BulkOperationError,
   ConnectionError,
   AuthenticationError,
-  ValidationError,
+  DataApiValidationError,
   createErrorFromResponse,
   isObjectStackError,
   isErrorType,
@@ -189,20 +189,20 @@ describe('Error Classes', () => {
     });
   });
 
-  describe('ValidationError', () => {
+  describe('DataApiValidationError', () => {
     it('should create validation error', () => {
-      const error = new ValidationError('Invalid input');
+      const error = new DataApiValidationError('Invalid input');
 
       expect(error.message).toBe('Invalid input');
       expect(error.code).toBe('VALIDATION_ERROR');
       expect(error.statusCode).toBe(400);
       expect(error.name).toBe('ValidationError');
       expect(error).toBeInstanceOf(ObjectStackError);
-      expect(error).toBeInstanceOf(ValidationError);
+      expect(error).toBeInstanceOf(DataApiValidationError);
     });
 
     it('should include field information', () => {
-      const error = new ValidationError('Email is invalid', 'email');
+      const error = new DataApiValidationError('Email is invalid', 'email');
 
       expect(error.field).toBe('email');
       expect(error.details).toHaveProperty('field', 'email');
@@ -214,7 +214,7 @@ describe('Error Classes', () => {
         { field: 'age', message: 'Must be a positive number' },
       ];
       
-      const error = new ValidationError(
+      const error = new DataApiValidationError(
         'Validation failed',
         undefined,
         validationErrors
@@ -225,7 +225,7 @@ describe('Error Classes', () => {
     });
 
     it('should return empty array when no validation errors', () => {
-      const error = new ValidationError('Validation failed');
+      const error = new DataApiValidationError('Validation failed');
 
       expect(error.getValidationErrors()).toEqual([]);
     });
@@ -286,7 +286,7 @@ describe('Error Helpers', () => {
       expect(error.code).toBe('NOT_FOUND');
     });
 
-    it('should create ValidationError for 400 status', () => {
+    it('should create DataApiValidationError for 400 status', () => {
       const response = {
         status: 400,
         message: 'Bad request',
@@ -299,9 +299,9 @@ describe('Error Helpers', () => {
 
       const error = createErrorFromResponse(response);
 
-      expect(error).toBeInstanceOf(ValidationError);
+      expect(error).toBeInstanceOf(DataApiValidationError);
       expect(error.statusCode).toBe(400);
-      expect((error as ValidationError).validationErrors).toEqual([
+      expect((error as DataApiValidationError).validationErrors).toEqual([
         { field: 'email', message: 'Invalid email' },
       ]);
     });
@@ -379,7 +379,7 @@ describe('Error Helpers', () => {
       const bulkError = new BulkOperationError('create', 0, 1, []);
       const connError = new ConnectionError('timeout');
       const authError = new AuthenticationError();
-      const validError = new ValidationError('invalid');
+      const validError = new DataApiValidationError('invalid');
 
       expect(isObjectStackError(metadataError)).toBe(true);
       expect(isObjectStackError(bulkError)).toBe(true);
@@ -409,7 +409,7 @@ describe('Error Helpers', () => {
 
     it('should return false for non-matching error type', () => {
       const error = new MetadataNotFoundError('users');
-      expect(isErrorType(error, ValidationError)).toBe(false);
+      expect(isErrorType(error, DataApiValidationError)).toBe(false);
     });
 
     it('should return true for base class check', () => {

package/src/errors.ts

@@ -159,12 +159,24 @@ export class AuthenticationError extends ObjectStackError {
 }
 
 /**
- * Error thrown when data validation fails
+ * Error thrown when the ObjectStack data API rejects a write as invalid.
+ *
+ * NOT the spec's `ValidationError` (`@objectstack/spec/kernel`), whose name this
+ * class wore until objectui#3160 (objectstack#4115 ledger batch 6). That one is
+ * a plain DATA SHAPE — `{ field, message, code? }`, one entry in a plugin
+ * manifest's validation report — and `@object-ui/types` re-exports it under that
+ * name. This is a runtime `Error` subclass carrying an HTTP status plus a list
+ * of such entries, so the two are not even the same KIND of thing.
+ *
+ * The name follows the convention registered on objectstack#4115 for this
+ * family — `<what was validated>Validation<Error|Result>`. `@object-ui/core`
+ * took `SchemaNodeValidationError` for its SDUI-tree walk; this one belongs to
+ * the data API.
  */
-export class ValidationError extends ObjectStackError {
+export class DataApiValidationError extends ObjectStackError {
   /**
-   * Create a new ValidationError
-   * 
+   * Create a new DataApiValidationError
+   *
    * @param message - Human-readable error message
    * @param field - The field that failed validation (optional)
    * @param validationErrors - Array of validation error details
@@ -186,6 +198,12 @@ export class ValidationError extends ObjectStackError {
         ...details,
       }
     );
+    // The RUNTIME name stays `'ValidationError'` on purpose — it is the wire
+    // discriminator this adapter shares with `@objectstack/client` and with
+    // consumers that sniff `err.name` rather than `instanceof`
+    // (`normaliseClientError` here, `@object-ui/react`'s `error-message`).
+    // Renaming the TypeScript symbol is a source-level rename; renaming this
+    // string would be a behaviour change nobody asked for.
     this.name = 'ValidationError';
   }
 
@@ -232,7 +250,7 @@ export function createErrorFromResponse(response: Record<string, unknown>, conte
       return new ObjectStackError(message, 'NOT_FOUND', 404, details);
     
     case 400:
-      return new ValidationError(message, undefined, (response?.data as Record<string, unknown>)?.errors as Array<{ field: string; message: string }>, details);
+      return new DataApiValidationError(message, undefined, (response?.data as Record<string, unknown>)?.errors as Array<{ field: string; message: string }>, details);
     
     case 503:
       return new ConnectionError(message, (response?.config as Record<string, unknown>)?.url as string, details, 503);

package/src/exportDownload.test.ts

@@ -97,3 +97,45 @@ describe('ObjectStackAdapter.exportDownload', () => {
     });
   });
 });
+
+/**
+ * `search` — the half of a list this request could not carry.
+ *
+ * The route mirrored `filter` and `orderby` only, so an export taken while a
+ * search was active downloaded the UNSEARCHED superset: more rows than the
+ * screen showed, in a file that looks authoritative. Server half:
+ * objectstack#4230.
+ */
+describe('ObjectStackAdapter.exportDownload — search', () => {
+  const paramsFor = async (request: Record<string, unknown>) => {
+    const fetchImpl = vi.fn(async (_url: string, _init: RequestInit) => csvResponse());
+    await makeDS(fetchImpl).exportDownload('task', request);
+    return new URL(fetchImpl.mock.calls[0][0]).searchParams;
+  };
+
+  it('sends the term as `search`', async () => {
+    expect((await paramsFor({ search: 'acme' })).get('search')).toBe('acme');
+  });
+
+  it('sends `searchFields` as a comma list alongside the term', async () => {
+    const p = await paramsFor({ search: 'acme', searchFields: ['name', 'stage'] });
+    expect(p.get('searchFields')).toBe('name,stage');
+  });
+
+  it('omits both when no term is given — `searchFields` alone means nothing', async () => {
+    const p = await paramsFor({ searchFields: ['name'] });
+    expect(p.get('search')).toBeNull();
+    expect(p.get('searchFields')).toBeNull();
+  });
+
+  it('treats a whitespace-only term as absent, and trims a real one', async () => {
+    expect((await paramsFor({ search: '   ' })).get('search')).toBeNull();
+    expect((await paramsFor({ search: '  acme  ' })).get('search')).toBe('acme');
+  });
+
+  it('carries search and filter together — neither replaces the other', async () => {
+    const p = await paramsFor({ search: 'acme', filter: [['status', '=', 'open']] });
+    expect(p.get('search')).toBe('acme');
+    expect(JSON.parse(p.get('filter')!)).toEqual([['status', '=', 'open']]);
+  });
+});