@object-ui/data-objectstack 3.0.2 → 3.1.0

package/dist/index.cjs

@@ -749,6 +749,7 @@ var ObjectStackAdapter = class {
     __publicField(this, "reconnectAttempts", 0);
     __publicField(this, "baseUrl");
     __publicField(this, "token");
+    __publicField(this, "fetchImpl");
     this.client = new import_client.ObjectStackClient(config);
     this.metadataCache = new MetadataCache(config.cache);
     this.autoReconnect = config.autoReconnect ?? true;
@@ -756,6 +757,7 @@ var ObjectStackAdapter = class {
     this.reconnectDelay = config.reconnectDelay ?? 1e3;
     this.baseUrl = config.baseUrl;
     this.token = config.token;
+    this.fetchImpl = config.fetch || globalThis.fetch.bind(globalThis);
   }
   /**
    * Ensure the client is connected to the server.
@@ -868,34 +870,40 @@ var ObjectStackAdapter = class {
    */
   async find(resource, params) {
     await this.connect();
+    if (params?.$expand && params.$expand.length > 0) {
+      const result2 = await this.rawFindWithPopulate(resource, params);
+      return this.normalizeQueryResult(result2, params);
+    }
     const queryOptions = this.convertQueryParams(params);
     const result = await this.client.data.find(resource, queryOptions);
-    if (Array.isArray(result)) {
-      return {
-        data: result,
-        total: result.length,
-        page: 1,
-        pageSize: result.length,
-        hasMore: false
-      };
-    }
-    const resultObj = result;
-    const records = resultObj.records || resultObj.value || [];
-    const total = resultObj.total ?? resultObj.count ?? records.length;
-    return {
-      data: records,
-      total,
-      // Calculate page number safely
-      page: params?.$skip && params.$top ? Math.floor(params.$skip / params.$top) + 1 : 1,
-      pageSize: params?.$top,
-      hasMore: params?.$top ? records.length === params.$top : false
-    };
+    return this.normalizeQueryResult(result, params);
   }
   /**
    * Find a single record by ID.
    */
-  async findOne(resource, id, _params) {
+  async findOne(resource, id, params) {
     await this.connect();
+    if (params?.$expand && params.$expand.length > 0) {
+      try {
+        const findParams = {
+          ...params,
+          $filter: { _id: String(id) },
+          $top: 1
+        };
+        const result = await this.rawFindWithPopulate(resource, findParams);
+        if (Array.isArray(result)) {
+          return result[0] || null;
+        }
+        const resultObj = result;
+        const records = resultObj.records || resultObj.value || [];
+        return records[0] || null;
+      } catch (error) {
+        if (error?.status === 404) {
+          return null;
+        }
+        throw error;
+      }
+    }
     try {
       const result = await this.client.data.get(resource, String(id));
       return result.record;
@@ -1060,6 +1068,92 @@ var ObjectStackAdapter = class {
       );
     }
   }
+  /**
+   * Normalize the result from data.find() or data.query() into a consistent QueryResult.
+   */
+  normalizeQueryResult(result, params) {
+    if (Array.isArray(result)) {
+      return {
+        data: result,
+        total: result.length,
+        page: 1,
+        pageSize: result.length,
+        hasMore: false
+      };
+    }
+    const resultObj = result;
+    const records = resultObj.records || resultObj.value || [];
+    const total = resultObj.total ?? resultObj.count ?? records.length;
+    return {
+      data: records,
+      total,
+      // Calculate page number safely
+      page: params?.$skip && params.$top ? Math.floor(params.$skip / params.$top) + 1 : 1,
+      pageSize: params?.$top,
+      hasMore: params?.$top ? records.length === params.$top : false
+    };
+  }
+  /**
+   * Make a raw GET request to the data API with `populate` as a URL query param.
+   * Used when $expand is needed, since the client SDK's data.find() does not
+   * support populate/expand. The server's REST API routes GET /data/:object
+   * to findData({ object, query: req.query }) which processes `populate`.
+   */
+  async rawFindWithPopulate(resource, params) {
+    const queryParams = new URLSearchParams();
+    if (params.$expand && params.$expand.length > 0) {
+      queryParams.set("populate", params.$expand.join(","));
+    }
+    if (params.$top !== void 0) {
+      queryParams.set("top", String(params.$top));
+    }
+    if (params.$skip !== void 0) {
+      queryParams.set("skip", String(params.$skip));
+    }
+    if (params.$select && params.$select.length > 0) {
+      queryParams.set("select", params.$select.join(","));
+    }
+    if (params.$orderby) {
+      if (Array.isArray(params.$orderby)) {
+        const sortStr = params.$orderby.map((item) => {
+          if (typeof item === "string") return item;
+          const field = item.field;
+          const order = item.order || "asc";
+          return order === "desc" ? `-${field}` : field;
+        }).join(",");
+        queryParams.set("sort", sortStr);
+      } else {
+        const sortStr = Object.entries(params.$orderby).map(([field, order]) => order === "desc" ? `-${field}` : field).join(",");
+        queryParams.set("sort", sortStr);
+      }
+    }
+    if (params.$filter) {
+      queryParams.set("filter", JSON.stringify(params.$filter));
+    }
+    const baseUrl = this.baseUrl.replace(/\/$/, "");
+    const qs = queryParams.toString();
+    const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+    const dataPath = hasApiVersionSuffix ? "/data" : "/api/v1/data";
+    const url = `${baseUrl}${dataPath}/${resource}${qs ? `?${qs}` : ""}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    const res = await this.fetchImpl(url, { method: "GET", headers });
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({ message: res.statusText }));
+      const err = new Error(errorBody?.error?.message || errorBody?.message || res.statusText);
+      err.status = res.status;
+      throw err;
+    }
+    const body = await res.json();
+    if (body && typeof body.success === "boolean" && "data" in body) {
+      return body.data;
+    }
+    return body;
+  }
   /**
    * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
    * Maps OData-style conventions to ObjectStack conventions.
@@ -1215,6 +1309,69 @@ var ObjectStackAdapter = class {
       return null;
     }
   }
+  /**
+   * Perform server-side aggregation via the ObjectStack analytics API.
+   * Uses `this.client.analytics.query()` from @objectstack/client to leverage
+   * the SDK's built-in auth, headers, and fetch configuration.
+   * Falls back to client-side aggregation via find() if the analytics endpoint
+   * is not available.
+   */
+  async aggregate(resource, params) {
+    await this.connect();
+    try {
+      const payload = {
+        object: resource,
+        measures: [{ field: params.field, function: params.function }],
+        dimensions: [params.groupBy]
+      };
+      if (params.filter) {
+        payload.filters = params.filter;
+      }
+      const data = await this.client.analytics.query(payload);
+      if (Array.isArray(data)) return data;
+      if (data?.data && Array.isArray(data.data)) return data.data;
+      if (data?.results && Array.isArray(data.results)) return data.results;
+      return [];
+    } catch {
+      const result = await this.find(resource);
+      const records = result.data || [];
+      if (records.length === 0) return [];
+      return this.aggregateClientSide(records, params);
+    }
+  }
+  /** Client-side aggregation fallback */
+  aggregateClientSide(records, params) {
+    const { field, function: aggFn, groupBy } = params;
+    const groups = {};
+    for (const record of records) {
+      const key = String(record[groupBy] ?? "Unknown");
+      if (!groups[key]) groups[key] = [];
+      groups[key].push(record);
+    }
+    return Object.entries(groups).map(([key, group]) => {
+      const values = group.map((r) => Number(r[field]) || 0);
+      let result;
+      switch (aggFn) {
+        case "count":
+          result = group.length;
+          break;
+        case "avg":
+          result = values.length > 0 ? values.reduce((a, b) => a + b, 0) / values.length : 0;
+          break;
+        case "min":
+          result = values.length > 0 ? Math.min(...values) : 0;
+          break;
+        case "max":
+          result = values.length > 0 ? Math.max(...values) : 0;
+          break;
+        case "sum":
+        default:
+          result = values.reduce((a, b) => a + b, 0);
+          break;
+      }
+      return { [groupBy]: key, [field]: result };
+    });
+  }
   /**
    * Get multiple metadata items from ObjectStack.
    * Uses v3.0.0 metadata API pattern: getItems for batch retrieval.

package/dist/index.d.cts

@@ -711,6 +711,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private reconnectAttempts;
     private baseUrl;
     private token?;
+    private fetchImpl;
     constructor(config: {
         baseUrl: string;
         token?: string;
@@ -764,7 +765,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     /**
      * Find a single record by ID.
      */
-    findOne(resource: string, id: string | number, _params?: QueryParams): Promise<T | null>;
+    findOne(resource: string, id: string | number, params?: QueryParams): Promise<T | null>;
     /**
      * Create a new record.
      */
@@ -787,6 +788,17 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to array of results
      */
     bulk(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]>;
+    /**
+     * Normalize the result from data.find() or data.query() into a consistent QueryResult.
+     */
+    private normalizeQueryResult;
+    /**
+     * Make a raw GET request to the data API with `populate` as a URL query param.
+     * Used when $expand is needed, since the client SDK's data.find() does not
+     * support populate/expand. The server's REST API routes GET /data/:object
+     * to findData({ object, query: req.query }) which processes `populate`.
+     */
+    private rawFindWithPopulate;
     /**
      * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
      * Maps OData-style conventions to ObjectStack conventions.
@@ -841,6 +853,21 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Returns null if the server doesn't support page metadata.
      */
     getPage(pageId: string): Promise<unknown | null>;
+    /**
+     * Perform server-side aggregation via the ObjectStack analytics API.
+     * Uses `this.client.analytics.query()` from @objectstack/client to leverage
+     * the SDK's built-in auth, headers, and fetch configuration.
+     * Falls back to client-side aggregation via find() if the analytics endpoint
+     * is not available.
+     */
+    aggregate(resource: string, params: {
+        field: string;
+        function: string;
+        groupBy: string;
+        filter?: any;
+    }): Promise<any[]>;
+    /** Client-side aggregation fallback */
+    private aggregateClientSide;
     /**
      * Get multiple metadata items from ObjectStack.
      * Uses v3.0.0 metadata API pattern: getItems for batch retrieval.

package/dist/index.d.ts

@@ -711,6 +711,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private reconnectAttempts;
     private baseUrl;
     private token?;
+    private fetchImpl;
     constructor(config: {
         baseUrl: string;
         token?: string;
@@ -764,7 +765,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     /**
      * Find a single record by ID.
      */
-    findOne(resource: string, id: string | number, _params?: QueryParams): Promise<T | null>;
+    findOne(resource: string, id: string | number, params?: QueryParams): Promise<T | null>;
     /**
      * Create a new record.
      */
@@ -787,6 +788,17 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to array of results
      */
     bulk(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]>;
+    /**
+     * Normalize the result from data.find() or data.query() into a consistent QueryResult.
+     */
+    private normalizeQueryResult;
+    /**
+     * Make a raw GET request to the data API with `populate` as a URL query param.
+     * Used when $expand is needed, since the client SDK's data.find() does not
+     * support populate/expand. The server's REST API routes GET /data/:object
+     * to findData({ object, query: req.query }) which processes `populate`.
+     */
+    private rawFindWithPopulate;
     /**
      * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
      * Maps OData-style conventions to ObjectStack conventions.
@@ -841,6 +853,21 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Returns null if the server doesn't support page metadata.
      */
     getPage(pageId: string): Promise<unknown | null>;
+    /**
+     * Perform server-side aggregation via the ObjectStack analytics API.
+     * Uses `this.client.analytics.query()` from @objectstack/client to leverage
+     * the SDK's built-in auth, headers, and fetch configuration.
+     * Falls back to client-side aggregation via find() if the analytics endpoint
+     * is not available.
+     */
+    aggregate(resource: string, params: {
+        field: string;
+        function: string;
+        groupBy: string;
+        filter?: any;
+    }): Promise<any[]>;
+    /** Client-side aggregation fallback */
+    private aggregateClientSide;
     /**
      * Get multiple metadata items from ObjectStack.
      * Uses v3.0.0 metadata API pattern: getItems for batch retrieval.

package/dist/index.js

@@ -709,6 +709,7 @@ var ObjectStackAdapter = class {
     __publicField(this, "reconnectAttempts", 0);
     __publicField(this, "baseUrl");
     __publicField(this, "token");
+    __publicField(this, "fetchImpl");
     this.client = new ObjectStackClient(config);
     this.metadataCache = new MetadataCache(config.cache);
     this.autoReconnect = config.autoReconnect ?? true;
@@ -716,6 +717,7 @@ var ObjectStackAdapter = class {
     this.reconnectDelay = config.reconnectDelay ?? 1e3;
     this.baseUrl = config.baseUrl;
     this.token = config.token;
+    this.fetchImpl = config.fetch || globalThis.fetch.bind(globalThis);
   }
   /**
    * Ensure the client is connected to the server.
@@ -828,34 +830,40 @@ var ObjectStackAdapter = class {
    */
   async find(resource, params) {
     await this.connect();
+    if (params?.$expand && params.$expand.length > 0) {
+      const result2 = await this.rawFindWithPopulate(resource, params);
+      return this.normalizeQueryResult(result2, params);
+    }
     const queryOptions = this.convertQueryParams(params);
     const result = await this.client.data.find(resource, queryOptions);
-    if (Array.isArray(result)) {
-      return {
-        data: result,
-        total: result.length,
-        page: 1,
-        pageSize: result.length,
-        hasMore: false
-      };
-    }
-    const resultObj = result;
-    const records = resultObj.records || resultObj.value || [];
-    const total = resultObj.total ?? resultObj.count ?? records.length;
-    return {
-      data: records,
-      total,
-      // Calculate page number safely
-      page: params?.$skip && params.$top ? Math.floor(params.$skip / params.$top) + 1 : 1,
-      pageSize: params?.$top,
-      hasMore: params?.$top ? records.length === params.$top : false
-    };
+    return this.normalizeQueryResult(result, params);
   }
   /**
    * Find a single record by ID.
    */
-  async findOne(resource, id, _params) {
+  async findOne(resource, id, params) {
     await this.connect();
+    if (params?.$expand && params.$expand.length > 0) {
+      try {
+        const findParams = {
+          ...params,
+          $filter: { _id: String(id) },
+          $top: 1
+        };
+        const result = await this.rawFindWithPopulate(resource, findParams);
+        if (Array.isArray(result)) {
+          return result[0] || null;
+        }
+        const resultObj = result;
+        const records = resultObj.records || resultObj.value || [];
+        return records[0] || null;
+      } catch (error) {
+        if (error?.status === 404) {
+          return null;
+        }
+        throw error;
+      }
+    }
     try {
       const result = await this.client.data.get(resource, String(id));
       return result.record;
@@ -1020,6 +1028,92 @@ var ObjectStackAdapter = class {
       );
     }
   }
+  /**
+   * Normalize the result from data.find() or data.query() into a consistent QueryResult.
+   */
+  normalizeQueryResult(result, params) {
+    if (Array.isArray(result)) {
+      return {
+        data: result,
+        total: result.length,
+        page: 1,
+        pageSize: result.length,
+        hasMore: false
+      };
+    }
+    const resultObj = result;
+    const records = resultObj.records || resultObj.value || [];
+    const total = resultObj.total ?? resultObj.count ?? records.length;
+    return {
+      data: records,
+      total,
+      // Calculate page number safely
+      page: params?.$skip && params.$top ? Math.floor(params.$skip / params.$top) + 1 : 1,
+      pageSize: params?.$top,
+      hasMore: params?.$top ? records.length === params.$top : false
+    };
+  }
+  /**
+   * Make a raw GET request to the data API with `populate` as a URL query param.
+   * Used when $expand is needed, since the client SDK's data.find() does not
+   * support populate/expand. The server's REST API routes GET /data/:object
+   * to findData({ object, query: req.query }) which processes `populate`.
+   */
+  async rawFindWithPopulate(resource, params) {
+    const queryParams = new URLSearchParams();
+    if (params.$expand && params.$expand.length > 0) {
+      queryParams.set("populate", params.$expand.join(","));
+    }
+    if (params.$top !== void 0) {
+      queryParams.set("top", String(params.$top));
+    }
+    if (params.$skip !== void 0) {
+      queryParams.set("skip", String(params.$skip));
+    }
+    if (params.$select && params.$select.length > 0) {
+      queryParams.set("select", params.$select.join(","));
+    }
+    if (params.$orderby) {
+      if (Array.isArray(params.$orderby)) {
+        const sortStr = params.$orderby.map((item) => {
+          if (typeof item === "string") return item;
+          const field = item.field;
+          const order = item.order || "asc";
+          return order === "desc" ? `-${field}` : field;
+        }).join(",");
+        queryParams.set("sort", sortStr);
+      } else {
+        const sortStr = Object.entries(params.$orderby).map(([field, order]) => order === "desc" ? `-${field}` : field).join(",");
+        queryParams.set("sort", sortStr);
+      }
+    }
+    if (params.$filter) {
+      queryParams.set("filter", JSON.stringify(params.$filter));
+    }
+    const baseUrl = this.baseUrl.replace(/\/$/, "");
+    const qs = queryParams.toString();
+    const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+    const dataPath = hasApiVersionSuffix ? "/data" : "/api/v1/data";
+    const url = `${baseUrl}${dataPath}/${resource}${qs ? `?${qs}` : ""}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    const res = await this.fetchImpl(url, { method: "GET", headers });
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({ message: res.statusText }));
+      const err = new Error(errorBody?.error?.message || errorBody?.message || res.statusText);
+      err.status = res.status;
+      throw err;
+    }
+    const body = await res.json();
+    if (body && typeof body.success === "boolean" && "data" in body) {
+      return body.data;
+    }
+    return body;
+  }
   /**
    * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
    * Maps OData-style conventions to ObjectStack conventions.
@@ -1175,6 +1269,69 @@ var ObjectStackAdapter = class {
       return null;
     }
   }
+  /**
+   * Perform server-side aggregation via the ObjectStack analytics API.
+   * Uses `this.client.analytics.query()` from @objectstack/client to leverage
+   * the SDK's built-in auth, headers, and fetch configuration.
+   * Falls back to client-side aggregation via find() if the analytics endpoint
+   * is not available.
+   */
+  async aggregate(resource, params) {
+    await this.connect();
+    try {
+      const payload = {
+        object: resource,
+        measures: [{ field: params.field, function: params.function }],
+        dimensions: [params.groupBy]
+      };
+      if (params.filter) {
+        payload.filters = params.filter;
+      }
+      const data = await this.client.analytics.query(payload);
+      if (Array.isArray(data)) return data;
+      if (data?.data && Array.isArray(data.data)) return data.data;
+      if (data?.results && Array.isArray(data.results)) return data.results;
+      return [];
+    } catch {
+      const result = await this.find(resource);
+      const records = result.data || [];
+      if (records.length === 0) return [];
+      return this.aggregateClientSide(records, params);
+    }
+  }
+  /** Client-side aggregation fallback */
+  aggregateClientSide(records, params) {
+    const { field, function: aggFn, groupBy } = params;
+    const groups = {};
+    for (const record of records) {
+      const key = String(record[groupBy] ?? "Unknown");
+      if (!groups[key]) groups[key] = [];
+      groups[key].push(record);
+    }
+    return Object.entries(groups).map(([key, group]) => {
+      const values = group.map((r) => Number(r[field]) || 0);
+      let result;
+      switch (aggFn) {
+        case "count":
+          result = group.length;
+          break;
+        case "avg":
+          result = values.length > 0 ? values.reduce((a, b) => a + b, 0) / values.length : 0;
+          break;
+        case "min":
+          result = values.length > 0 ? Math.min(...values) : 0;
+          break;
+        case "max":
+          result = values.length > 0 ? Math.max(...values) : 0;
+          break;
+        case "sum":
+        default:
+          result = values.reduce((a, b) => a + b, 0);
+          break;
+      }
+      return { [groupBy]: key, [field]: result };
+    });
+  }
   /**
    * Get multiple metadata items from ObjectStack.
    * Uses v3.0.0 metadata API pattern: getItems for batch retrieval.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -20,9 +20,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@objectstack/client": "^3.0.4",
-    "@object-ui/core": "3.0.2",
-    "@object-ui/types": "3.0.2"
+    "@objectstack/client": "^3.2.0",
+    "@object-ui/core": "3.1.0",
+    "@object-ui/types": "3.1.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/src/expand.test.ts

@@ -0,0 +1,245 @@
+/**
+ * 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.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ObjectStackAdapter } from './index';
+
+// We test the adapter's $expand handling.
+// When $expand is present, the adapter makes a raw GET request to the REST API
+// with `populate` as a URL query param (since the client SDK's data.find()
+// QueryOptions does not support populate/expand).
+// The key scenarios:
+//   1. find() with $expand → raw GET /api/v1/data/:object?populate=...
+//   2. find() without $expand → client.data.find() (GET) as before
+//   3. findOne() with $expand → raw GET /api/v1/data/:object?filter={_id:...}&populate=...
+//   4. findOne() without $expand → client.data.get() as before
+
+describe('ObjectStackAdapter $expand support', () => {
+  let adapter: ObjectStackAdapter;
+  let mockClient: any;
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    // Create a mock fetch that returns a successful response
+    mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ records: [], total: 0 }),
+    });
+
+    adapter = new ObjectStackAdapter({
+      baseUrl: 'http://localhost:3000',
+      autoReconnect: false,
+      fetch: mockFetch,
+    });
+
+    // Mock the internal client after construction
+    mockClient = {
+      data: {
+        find: vi.fn().mockResolvedValue({ records: [], total: 0 }),
+        query: vi.fn().mockResolvedValue({ records: [], total: 0 }),
+        get: vi.fn().mockResolvedValue({ record: { _id: '1', name: 'Test' } }),
+      },
+      connect: vi.fn().mockResolvedValue(undefined),
+      discover: vi.fn().mockResolvedValue({ status: 'ok' }),
+    };
+
+    // Inject mock client and mark as connected to bypass connect()
+    (adapter as any).client = mockClient;
+    (adapter as any).connected = true;
+  });
+
+  describe('find() with $expand', () => {
+    it('should make a raw GET request with populate query param when $expand is present', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          records: [{ _id: '1', name: 'Order 1', customer: { _id: '2', name: 'Alice' } }],
+          total: 1,
+        }),
+      });
+
+      const result = await adapter.find('order', {
+        $top: 10,
+        $expand: ['customer', 'account'],
+      });
+
+      // Should use raw fetch, not client.data.query or client.data.find
+      expect(mockFetch).toHaveBeenCalled();
+      const fetchUrl = mockFetch.mock.calls[0][0] as string;
+      expect(fetchUrl).toContain('/api/v1/data/order');
+      expect(fetchUrl).toContain('populate=customer%2Caccount');
+      expect(fetchUrl).toContain('top=10');
+      expect(mockClient.data.find).not.toHaveBeenCalled();
+      expect(result.data).toHaveLength(1);
+      expect(result.data[0].customer).toEqual({ _id: '2', name: 'Alice' });
+    });
+
+    it('should pass filters and sort as query params', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ records: [], total: 0 }),
+      });
+
+      await adapter.find('order', {
+        $filter: { status: 'active' },
+        $orderby: [{ field: 'name', order: 'asc' }],
+        $top: 50,
+        $skip: 10,
+        $expand: ['customer'],
+      });
+
+      expect(mockFetch).toHaveBeenCalled();
+      const fetchUrl = mockFetch.mock.calls[0][0] as string;
+      expect(fetchUrl).toContain('populate=customer');
+      expect(fetchUrl).toContain('top=50');
+      expect(fetchUrl).toContain('skip=10');
+      expect(fetchUrl).toContain('sort=name');
+      expect(fetchUrl).toContain('filter=');
+    });
+
+    it('should use data.find() when $expand is not present', async () => {
+      mockClient.data.find.mockResolvedValue({ records: [{ _id: '1', name: 'Test' }], total: 1 });
+
+      const result = await adapter.find('order', { $top: 10 });
+
+      expect(mockClient.data.find).toHaveBeenCalled();
+      expect(result.data).toHaveLength(1);
+    });
+
+    it('should use data.find() when $expand is an empty array', async () => {
+      mockClient.data.find.mockResolvedValue({ records: [], total: 0 });
+
+      await adapter.find('order', { $top: 10, $expand: [] });
+
+      expect(mockClient.data.find).toHaveBeenCalled();
+    });
+  });
+
+  describe('findOne() with $expand', () => {
+    it('should make a raw GET request with _id filter and populate when $expand is present', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          records: [{ _id: 'order-1', name: 'Order 1', customer: { _id: '2', name: 'Alice' } }],
+        }),
+      });
+
+      const result = await adapter.findOne('order', 'order-1', {
+        $expand: ['customer', 'account'],
+      });
+
+      expect(mockFetch).toHaveBeenCalled();
+      const fetchUrl = mockFetch.mock.calls[0][0] as string;
+      expect(fetchUrl).toContain('/api/v1/data/order');
+      expect(fetchUrl).toContain('populate=customer%2Caccount');
+      expect(fetchUrl).toContain('top=1');
+      expect(fetchUrl).toContain('filter=');
+      // Verify the filter contains _id
+      const filterParam = new URL(fetchUrl).searchParams.get('filter');
+      expect(filterParam).toBeTruthy();
+      const parsedFilter = JSON.parse(filterParam!);
+      expect(parsedFilter).toEqual({ _id: 'order-1' });
+      expect(mockClient.data.get).not.toHaveBeenCalled();
+      expect(result).toEqual({ _id: 'order-1', name: 'Order 1', customer: { _id: '2', name: 'Alice' } });
+    });
+
+    it('should return null when raw request returns no records', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ records: [] }),
+      });
+
+      const result = await adapter.findOne('order', 'nonexistent', {
+        $expand: ['customer'],
+      });
+
+      expect(result).toBeNull();
+    });
+
+    it('should use data.get() when $expand is not present', async () => {
+      mockClient.data.get.mockResolvedValue({ record: { _id: '1', name: 'Test' } });
+
+      const result = await adapter.findOne('order', '1');
+
+      expect(mockClient.data.get).toHaveBeenCalledWith('order', '1');
+      expect(result).toEqual({ _id: '1', name: 'Test' });
+    });
+
+    it('should return null for 404 errors without $expand', async () => {
+      mockClient.data.get.mockRejectedValue({ status: 404 });
+
+      const result = await adapter.findOne('order', 'nonexistent');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('raw request format', () => {
+    it('should include Authorization header when token is set', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ records: [], total: 0 }),
+      });
+
+      (adapter as any).token = 'test-token';
+
+      await adapter.find('order', {
+        $expand: ['customer'],
+      });
+
+      expect(mockFetch).toHaveBeenCalled();
+      const fetchInit = mockFetch.mock.calls[0][1];
+      expect(fetchInit.headers.Authorization).toBe('Bearer test-token');
+    });
+
+    it('should unwrap response envelope with success/data wrapper', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          success: true,
+          data: {
+            records: [{ _id: '1', name: 'Order' }],
+            total: 1,
+          },
+        }),
+      });
+
+      const result = await adapter.find('order', {
+        $expand: ['customer'],
+      });
+
+      expect(result.data).toHaveLength(1);
+    });
+
+    it('should not double /api/v1 when baseUrl already includes it', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ records: [], total: 0 }),
+      });
+
+      // Create adapter with /api/v1 in baseUrl
+      const apiAdapter = new ObjectStackAdapter({
+        baseUrl: 'http://localhost:3000/api/v1',
+        autoReconnect: false,
+        fetch: mockFetch,
+      });
+      (apiAdapter as any).client = mockClient;
+      (apiAdapter as any).connected = true;
+
+      await apiAdapter.find('order', {
+        $expand: ['customer'],
+      });
+
+      expect(mockFetch).toHaveBeenCalled();
+      const fetchUrl = mockFetch.mock.calls[0][0] as string;
+      // Should be /api/v1/data/order not /api/v1/api/v1/data/order
+      expect(fetchUrl).toBe('http://localhost:3000/api/v1/data/order?populate=customer');
+      expect(fetchUrl).not.toContain('/api/v1/api/v1');
+    });
+  });
+});

package/src/index.ts

@@ -98,6 +98,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   private reconnectAttempts: number = 0;
   private baseUrl: string;
   private token?: string;
+  private fetchImpl: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 
   constructor(config: {
     baseUrl: string;
@@ -118,6 +119,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     this.reconnectDelay = config.reconnectDelay ?? 1000;
     this.baseUrl = config.baseUrl;
     this.token = config.token;
+    this.fetchImpl = config.fetch || globalThis.fetch.bind(globalThis);
   }
 
   /**
@@ -254,39 +256,54 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   async find(resource: string, params?: QueryParams): Promise<QueryResult<T>> {
     await this.connect();
 
-    const queryOptions = this.convertQueryParams(params);
-    const result: unknown = await this.client.data.find<T>(resource, queryOptions);
-
-    // Handle legacy/raw array response (e.g. from some mock servers or non-OData endpoints)
-    if (Array.isArray(result)) {
-      return {
-        data: result,
-        total: result.length,
-        page: 1,
-        pageSize: result.length,
-        hasMore: false,
-      };
+    // When $expand is requested, use a raw GET request to the REST API with
+    // `populate` as a URL query param. The server's REST plugin routes
+    // GET /data/:object to protocol.findData({ object, query: req.query }),
+    // which parses `populate` (comma-separated) into an array for lookup expansion.
+    // We use a raw request because the client SDK's data.find() QueryOptions
+    // interface does not include populate/expand fields.
+    if (params?.$expand && params.$expand.length > 0) {
+      const result = await this.rawFindWithPopulate(resource, params);
+      return this.normalizeQueryResult(result, params);
     }
 
-    const resultObj = result as { records?: T[]; total?: number; value?: T[]; count?: number };
-    const records = resultObj.records || resultObj.value || [];
-    const total = resultObj.total ?? resultObj.count ?? records.length;
-    return {
-      data: records,
-      total,
-      // Calculate page number safely
-      page: params?.$skip && params.$top ? Math.floor(params.$skip / params.$top) + 1 : 1,
-      pageSize: params?.$top,
-      hasMore: params?.$top ? records.length === params.$top : false,
-    };
+    const queryOptions = this.convertQueryParams(params);
+    const result: unknown = await this.client.data.find<T>(resource, queryOptions);
+    return this.normalizeQueryResult(result, params);
   }
 
   /**
    * Find a single record by ID.
    */
-  async findOne(resource: string, id: string | number, _params?: QueryParams): Promise<T | null> {
+  async findOne(resource: string, id: string | number, params?: QueryParams): Promise<T | null> {
     await this.connect();
 
+    // When $expand is requested, use a raw GET request with a filter by _id
+    // and populate. The installed server v3.0.10's getData() does not support
+    // expand/populate, so we route through findData which does.
+    if (params?.$expand && params.$expand.length > 0) {
+      try {
+        const findParams: QueryParams = {
+          ...params,
+          $filter: { _id: String(id) },
+          $top: 1,
+        };
+        const result = await this.rawFindWithPopulate(resource, findParams);
+        // Handle array responses (some servers return data as flat arrays)
+        if (Array.isArray(result)) {
+          return result[0] || null;
+        }
+        const resultObj = result as { records?: T[]; value?: T[] };
+        const records = resultObj.records || resultObj.value || [];
+        return records[0] || null;
+      } catch (error: unknown) {
+        if ((error as Record<string, unknown>)?.status === 404) {
+          return null;
+        }
+        throw error;
+      }
+    }
+
     try {
       const result = await this.client.data.get<T>(resource, String(id));
       return result.record;
@@ -490,6 +507,115 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * Normalize the result from data.find() or data.query() into a consistent QueryResult.
+   */
+  private normalizeQueryResult(result: unknown, params?: QueryParams): QueryResult<T> {
+    // Handle legacy/raw array response (e.g. from some mock servers or non-OData endpoints)
+    if (Array.isArray(result)) {
+      return {
+        data: result,
+        total: result.length,
+        page: 1,
+        pageSize: result.length,
+        hasMore: false,
+      };
+    }
+
+    const resultObj = result as { records?: T[]; total?: number; value?: T[]; count?: number };
+    const records = resultObj.records || resultObj.value || [];
+    const total = resultObj.total ?? resultObj.count ?? records.length;
+    return {
+      data: records,
+      total,
+      // Calculate page number safely
+      page: params?.$skip && params.$top ? Math.floor(params.$skip / params.$top) + 1 : 1,
+      pageSize: params?.$top,
+      hasMore: params?.$top ? records.length === params.$top : false,
+    };
+  }
+
+  /**
+   * Make a raw GET request to the data API with `populate` as a URL query param.
+   * Used when $expand is needed, since the client SDK's data.find() does not
+   * support populate/expand. The server's REST API routes GET /data/:object
+   * to findData({ object, query: req.query }) which processes `populate`.
+   */
+  private async rawFindWithPopulate(resource: string, params: QueryParams): Promise<unknown> {
+    const queryParams = new URLSearchParams();
+
+    // Populate: comma-separated field names for lookup expansion
+    if (params.$expand && params.$expand.length > 0) {
+      queryParams.set('populate', params.$expand.join(','));
+    }
+
+    // Pagination
+    if (params.$top !== undefined) {
+      queryParams.set('top', String(params.$top));
+    }
+    if (params.$skip !== undefined) {
+      queryParams.set('skip', String(params.$skip));
+    }
+
+    // Selection
+    if (params.$select && params.$select.length > 0) {
+      queryParams.set('select', params.$select.join(','));
+    }
+
+    // Sorting
+    if (params.$orderby) {
+      if (Array.isArray(params.$orderby)) {
+        const sortStr = params.$orderby.map(item => {
+          if (typeof item === 'string') return item;
+          const field = item.field;
+          const order = item.order || 'asc';
+          return order === 'desc' ? `-${field}` : field;
+        }).join(',');
+        queryParams.set('sort', sortStr);
+      } else {
+        const sortStr = Object.entries(params.$orderby)
+          .map(([field, order]) => order === 'desc' ? `-${field}` : field)
+          .join(',');
+        queryParams.set('sort', sortStr);
+      }
+    }
+
+    // Filter
+    if (params.$filter) {
+      queryParams.set('filter', JSON.stringify(params.$filter));
+    }
+
+    const baseUrl = this.baseUrl.replace(/\/$/, '');
+    const qs = queryParams.toString();
+    // Avoid doubling /api/v1 if baseUrl already includes it
+    const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+    const dataPath = hasApiVersionSuffix ? '/data' : '/api/v1/data';
+    const url = `${baseUrl}${dataPath}/${resource}${qs ? `?${qs}` : ''}`;
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+    if (this.token) {
+      headers['Authorization'] = `Bearer ${this.token}`;
+    }
+
+    const res = await this.fetchImpl(url, { method: 'GET', headers });
+
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({ message: res.statusText }));
+      const err = new Error(errorBody?.error?.message || errorBody?.message || res.statusText) as any;
+      err.status = res.status;
+      throw err;
+    }
+
+    const body = await res.json();
+    // Unwrap standard response envelope { success, data }
+    if (body && typeof body.success === 'boolean' && 'data' in body) {
+      return body.data;
+    }
+    return body;
+  }
+
   /**
    * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
    * Maps OData-style conventions to ObjectStack conventions.
@@ -690,6 +816,69 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * Perform server-side aggregation via the ObjectStack analytics API.
+   * Uses `this.client.analytics.query()` from @objectstack/client to leverage
+   * the SDK's built-in auth, headers, and fetch configuration.
+   * Falls back to client-side aggregation via find() if the analytics endpoint
+   * is not available.
+   */
+  async aggregate(resource: string, params: { field: string; function: string; groupBy: string; filter?: any }): Promise<any[]> {
+    await this.connect();
+
+    try {
+      const payload: Record<string, unknown> = {
+        object: resource,
+        measures: [{ field: params.field, function: params.function }],
+        dimensions: [params.groupBy],
+      };
+      if (params.filter) {
+        payload.filters = params.filter;
+      }
+
+      const data = await this.client.analytics.query(payload);
+      if (Array.isArray(data)) return data;
+      if (data?.data && Array.isArray(data.data)) return data.data;
+      if (data?.results && Array.isArray(data.results)) return data.results;
+      return [];
+    } catch {
+      // If the analytics endpoint is not available, fall back to
+      // find() + client-side aggregation
+      const result = await this.find(resource as any);
+      const records = result.data || [];
+      if (records.length === 0) return [];
+
+      return this.aggregateClientSide(records, params);
+    }
+  }
+
+  /** Client-side aggregation fallback */
+  private aggregateClientSide(records: any[], params: { field: string; function: string; groupBy: string }): any[] {
+    const { field, function: aggFn, groupBy } = params;
+    const groups: Record<string, any[]> = {};
+
+    for (const record of records) {
+      const key = String(record[groupBy] ?? 'Unknown');
+      if (!groups[key]) groups[key] = [];
+      groups[key].push(record);
+    }
+
+    return Object.entries(groups).map(([key, group]) => {
+      const values = group.map(r => Number(r[field]) || 0);
+      let result: number;
+
+      switch (aggFn) {
+        case 'count': result = group.length; break;
+        case 'avg': result = values.length > 0 ? values.reduce((a, b) => a + b, 0) / values.length : 0; break;
+        case 'min': result = values.length > 0 ? Math.min(...values) : 0; break;
+        case 'max': result = values.length > 0 ? Math.max(...values) : 0; break;
+        case 'sum': default: result = values.reduce((a, b) => a + b, 0); break;
+      }
+
+      return { [groupBy]: key, [field]: result };
+    });
+  }
+
   /**
    * Get multiple metadata items from ObjectStack.
    * Uses v3.0.0 metadata API pattern: getItems for batch retrieval.