@object-ui/core 3.0.2 → 3.1.0

package/src/actions/__tests__/UndoManager.test.ts

@@ -0,0 +1,320 @@
+/**
+ * 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 { UndoManager, type UndoableOperation } from '../UndoManager';
+
+function makeOp(id: string, type: 'create' | 'update' | 'delete' = 'update'): UndoableOperation {
+  return {
+    id,
+    type,
+    objectName: 'Account',
+    recordId: `rec-${id}`,
+    timestamp: Date.now(),
+    description: `op-${id}`,
+    undoData: { prev: id },
+    redoData: { next: id },
+  };
+}
+
+describe('UndoManager', () => {
+  let manager: UndoManager;
+
+  beforeEach(() => {
+    manager = new UndoManager({ maxHistory: 5 });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Basic push / pop (existing behaviour)
+  // ---------------------------------------------------------------------------
+  describe('basic push/pop', () => {
+    it('pushes and peeks', () => {
+      const op = makeOp('1');
+      manager.push(op);
+      expect(manager.canUndo).toBe(true);
+      expect(manager.peekUndo()).toEqual(op);
+      expect(manager.undoCount).toBe(1);
+    });
+
+    it('popUndo moves to redo stack', () => {
+      const op = makeOp('1');
+      manager.push(op);
+      const popped = manager.popUndo();
+      expect(popped).toEqual(op);
+      expect(manager.canUndo).toBe(false);
+      expect(manager.canRedo).toBe(true);
+      expect(manager.peekRedo()).toEqual(op);
+    });
+
+    it('popRedo moves back to undo stack', () => {
+      manager.push(makeOp('1'));
+      manager.popUndo();
+      const redone = manager.popRedo();
+      expect(redone?.id).toBe('1');
+      expect(manager.canUndo).toBe(true);
+      expect(manager.canRedo).toBe(false);
+    });
+
+    it('push clears redo stack', () => {
+      manager.push(makeOp('1'));
+      manager.popUndo();
+      expect(manager.canRedo).toBe(true);
+      manager.push(makeOp('2'));
+      expect(manager.canRedo).toBe(false);
+    });
+
+    it('trims beyond maxHistory', () => {
+      for (let i = 0; i < 7; i++) manager.push(makeOp(String(i)));
+      expect(manager.undoCount).toBe(5);
+      // Oldest operations should have been shifted out
+      expect(manager.getHistory()[0].id).toBe('2');
+    });
+
+    it('clear removes everything', () => {
+      manager.push(makeOp('1'));
+      manager.clear();
+      expect(manager.canUndo).toBe(false);
+      expect(manager.canRedo).toBe(false);
+    });
+
+    it('subscribe notifies on changes', () => {
+      const listener = vi.fn();
+      const unsub = manager.subscribe(listener);
+      manager.push(makeOp('1'));
+      expect(listener).toHaveBeenCalledTimes(1);
+      unsub();
+      manager.push(makeOp('2'));
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // pushBatch
+  // ---------------------------------------------------------------------------
+  describe('pushBatch', () => {
+    it('pushes multiple operations atomically', () => {
+      const ops = [makeOp('a'), makeOp('b'), makeOp('c')];
+      manager.pushBatch(ops);
+      expect(manager.undoCount).toBe(3);
+      expect(manager.getHistory().map((o) => o.id)).toEqual(['a', 'b', 'c']);
+    });
+
+    it('clears redo stack', () => {
+      manager.push(makeOp('1'));
+      manager.popUndo();
+      expect(manager.canRedo).toBe(true);
+      manager.pushBatch([makeOp('x')]);
+      expect(manager.canRedo).toBe(false);
+    });
+
+    it('notifies listeners exactly once', () => {
+      const listener = vi.fn();
+      manager.subscribe(listener);
+      manager.pushBatch([makeOp('a'), makeOp('b')]);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('is a no-op for empty array', () => {
+      const listener = vi.fn();
+      manager.subscribe(listener);
+      manager.pushBatch([]);
+      expect(listener).not.toHaveBeenCalled();
+      expect(manager.undoCount).toBe(0);
+    });
+
+    it('trims to maxHistory when batch exceeds limit', () => {
+      const ops = Array.from({ length: 8 }, (_, i) => makeOp(String(i)));
+      manager.pushBatch(ops);
+      expect(manager.undoCount).toBe(5);
+      // Oldest should be trimmed
+      expect(manager.getHistory()[0].id).toBe('3');
+      expect(manager.getHistory()[4].id).toBe('7');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // popUndoBatch / popRedoBatch
+  // ---------------------------------------------------------------------------
+  describe('popUndoBatch', () => {
+    it('pops multiple operations from undo to redo', () => {
+      manager.pushBatch([makeOp('a'), makeOp('b'), makeOp('c')]);
+      const popped = manager.popUndoBatch(2);
+      expect(popped.map((o) => o.id)).toEqual(['b', 'c']);
+      expect(manager.undoCount).toBe(1);
+      expect(manager.redoCount).toBe(2);
+    });
+
+    it('clamps to available stack size', () => {
+      manager.push(makeOp('1'));
+      const popped = manager.popUndoBatch(10);
+      expect(popped).toHaveLength(1);
+      expect(manager.undoCount).toBe(0);
+    });
+
+    it('returns empty array when nothing to undo', () => {
+      expect(manager.popUndoBatch(3)).toEqual([]);
+    });
+
+    it('notifies listeners once', () => {
+      manager.pushBatch([makeOp('a'), makeOp('b')]);
+      const listener = vi.fn();
+      manager.subscribe(listener);
+      manager.popUndoBatch(2);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('popRedoBatch', () => {
+    it('pops multiple operations from redo to undo', () => {
+      manager.pushBatch([makeOp('a'), makeOp('b'), makeOp('c')]);
+      manager.popUndoBatch(3);
+      expect(manager.redoCount).toBe(3);
+      const redone = manager.popRedoBatch(2);
+      expect(redone.map((o) => o.id)).toEqual(['b', 'c']);
+      expect(manager.undoCount).toBe(2);
+      expect(manager.redoCount).toBe(1);
+    });
+
+    it('clamps to available stack size', () => {
+      manager.push(makeOp('1'));
+      manager.popUndo();
+      const redone = manager.popRedoBatch(5);
+      expect(redone).toHaveLength(1);
+    });
+
+    it('returns empty array when nothing to redo', () => {
+      expect(manager.popRedoBatch(3)).toEqual([]);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // getHistory / getRedoHistory
+  // ---------------------------------------------------------------------------
+  describe('getHistory / getRedoHistory', () => {
+    it('getHistory returns shallow copy of undo stack', () => {
+      manager.push(makeOp('1'));
+      manager.push(makeOp('2'));
+      const history = manager.getHistory();
+      expect(history).toHaveLength(2);
+      // Mutating the copy must not affect the manager
+      history.pop();
+      expect(manager.undoCount).toBe(2);
+    });
+
+    it('getRedoHistory returns shallow copy of redo stack', () => {
+      manager.push(makeOp('1'));
+      manager.push(makeOp('2'));
+      manager.popUndo();
+      const redoHistory = manager.getRedoHistory();
+      expect(redoHistory).toHaveLength(1);
+      expect(redoHistory[0].id).toBe('2');
+      // Mutating the copy must not affect the manager
+      redoHistory.pop();
+      expect(manager.redoCount).toBe(1);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // saveToStorage / loadFromStorage
+  // ---------------------------------------------------------------------------
+  describe('persistence', () => {
+    let storage: Record<string, string>;
+
+    beforeEach(() => {
+      storage = {};
+      vi.stubGlobal('localStorage', {
+        getItem: vi.fn((key: string) => storage[key] ?? null),
+        setItem: vi.fn((key: string, value: string) => { storage[key] = value; }),
+        removeItem: vi.fn((key: string) => { delete storage[key]; }),
+      });
+    });
+
+    it('round-trips undo/redo stacks through localStorage', () => {
+      manager.push(makeOp('1'));
+      manager.push(makeOp('2'));
+      manager.popUndo(); // '2' goes to redo
+
+      manager.saveToStorage();
+
+      const fresh = new UndoManager({ maxHistory: 5 });
+      fresh.loadFromStorage();
+
+      expect(fresh.undoCount).toBe(1);
+      expect(fresh.redoCount).toBe(1);
+      expect(fresh.peekUndo()?.id).toBe('1');
+      expect(fresh.peekRedo()?.id).toBe('2');
+    });
+
+    it('preserves all UndoableOperation fields', () => {
+      const op = makeOp('full');
+      manager.push(op);
+      manager.saveToStorage();
+
+      const fresh = new UndoManager();
+      fresh.loadFromStorage();
+      const restored = fresh.peekUndo()!;
+      expect(restored.id).toBe(op.id);
+      expect(restored.type).toBe(op.type);
+      expect(restored.objectName).toBe(op.objectName);
+      expect(restored.recordId).toBe(op.recordId);
+      expect(restored.timestamp).toBe(op.timestamp);
+      expect(restored.description).toBe(op.description);
+      expect(restored.undoData).toEqual(op.undoData);
+      expect(restored.redoData).toEqual(op.redoData);
+    });
+
+    it('is a no-op when localStorage has no data', () => {
+      const fresh = new UndoManager();
+      fresh.loadFromStorage();
+      expect(fresh.undoCount).toBe(0);
+      expect(fresh.redoCount).toBe(0);
+    });
+
+    it('handles corrupt localStorage data gracefully', () => {
+      storage['objectui:undo-history'] = 'not-valid-json!!!';
+      const fresh = new UndoManager();
+      expect(() => fresh.loadFromStorage()).not.toThrow();
+      expect(fresh.undoCount).toBe(0);
+    });
+
+    it('notifies listeners after loading', () => {
+      manager.push(makeOp('1'));
+      manager.saveToStorage();
+
+      const fresh = new UndoManager();
+      const listener = vi.fn();
+      fresh.subscribe(listener);
+      fresh.loadFromStorage();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Boundary: batch larger than maxHistory
+  // ---------------------------------------------------------------------------
+  describe('boundary: batch larger than maxHistory', () => {
+    it('trims oldest entries when batch overflows maxHistory', () => {
+      // maxHistory is 5
+      manager.push(makeOp('existing'));
+      const batch = Array.from({ length: 6 }, (_, i) => makeOp(`batch-${i}`));
+      manager.pushBatch(batch);
+      expect(manager.undoCount).toBe(5);
+      // 1 existing + 6 batch = 7 total, trimmed to last 5
+      const ids = manager.getHistory().map((o) => o.id);
+      expect(ids).toEqual(['batch-1', 'batch-2', 'batch-3', 'batch-4', 'batch-5']);
+    });
+
+    it('works when batch itself equals maxHistory', () => {
+      const batch = Array.from({ length: 5 }, (_, i) => makeOp(`b-${i}`));
+      manager.pushBatch(batch);
+      expect(manager.undoCount).toBe(5);
+      expect(manager.getHistory()[0].id).toBe('b-0');
+      expect(manager.getHistory()[4].id).toBe('b-4');
+    });
+  });
+});

package/src/actions/index.ts

@@ -7,4 +7,6 @@
  */
 
 export * from './ActionRunner.js';
+export * from './ActionEngine.js';
 export * from './TransactionManager.js';
+export * from './UndoManager.js';

package/src/adapters/ApiDataSource.ts

@@ -15,6 +15,8 @@ import type {
   QueryResult,
   HttpRequest,
   HttpMethod,
+  AggregateParams,
+  AggregateResult,
 } from '@object-ui/types';
 
 // ---------------------------------------------------------------------------
@@ -297,6 +299,31 @@ export class ApiDataSource<T = any> implements DataSource<T> {
     return null;
   }
 
+  async aggregate(_resource: string, params: AggregateParams): Promise<AggregateResult[]> {
+    const queryParams: Record<string, unknown> = {
+      field: params.field,
+      function: params.function,
+      groupBy: params.groupBy,
+    };
+    if (params.filter) {
+      queryParams.filter = typeof params.filter === 'string'
+        ? params.filter
+        : JSON.stringify(params.filter);
+    }
+
+    const raw = await this.request<any>(this.readConfig, {
+      pathSuffix: 'aggregate',
+      method: 'GET',
+      queryParams,
+    });
+
+    // Normalize: the API might return an array or an object with data/results
+    if (Array.isArray(raw)) return raw;
+    if (raw?.data && Array.isArray(raw.data)) return raw.data;
+    if (raw?.results && Array.isArray(raw.results)) return raw.results;
+    return [];
+  }
+
   // -----------------------------------------------------------------------
   // Helpers
   // -----------------------------------------------------------------------

package/src/adapters/ValueDataSource.ts

@@ -13,6 +13,8 @@ import type {
   DataSource,
   QueryParams,
   QueryResult,
+  AggregateParams,
+  AggregateResult,
 } from '@object-ui/types';
 
 // ---------------------------------------------------------------------------
@@ -36,6 +38,69 @@ function getRecordId(record: any, idField?: string): string | number | undefined
   return record._id ?? record.id;
 }
 
+/**
+ * Evaluate an AST-format filter node against a record.
+ * Supports conditions like ['field', 'op', value] and logical
+ * combinations like ['and', ...conditions] or ['or', ...conditions].
+ */
+function matchesASTFilter(record: any, filterNode: any[]): boolean {
+  if (!filterNode || filterNode.length === 0) return true;
+
+  const head = filterNode[0];
+
+  // Logical operators: ['and', ...conditions] or ['or', ...conditions]
+  if (head === 'and') {
+    return filterNode.slice(1).every((sub: any) => matchesASTFilter(record, sub));
+  }
+  if (head === 'or') {
+    return filterNode.slice(1).some((sub: any) => matchesASTFilter(record, sub));
+  }
+
+  // Condition node: [field, operator, value]
+  if (filterNode.length === 3 && typeof head === 'string') {
+    const [field, operator, target] = filterNode;
+    const value = record[field];
+
+    switch (operator) {
+      case '=':
+        return value === target;
+      case '!=':
+        return value !== target;
+      case '>':
+        return value > target;
+      case '>=':
+        return value >= target;
+      case '<':
+        return value < target;
+      case '<=':
+        return value <= target;
+      case 'in':
+        return Array.isArray(target) && target.includes(value);
+      case 'not in':
+      case 'notin': // alias used by convertFiltersToAST
+        return Array.isArray(target) && !target.includes(value);
+      case 'contains': {
+        const lv = typeof value === 'string' ? value.toLowerCase() : '';
+        return typeof value === 'string' && lv.includes(String(target).toLowerCase());
+      }
+      case 'notcontains': {
+        const lv = typeof value === 'string' ? value.toLowerCase() : '';
+        return typeof value === 'string' && !lv.includes(String(target).toLowerCase());
+      }
+      case 'startswith': {
+        const lv = typeof value === 'string' ? value.toLowerCase() : '';
+        return typeof value === 'string' && lv.startsWith(String(target).toLowerCase());
+      }
+      case 'between':
+        return Array.isArray(target) && target.length === 2 && value >= target[0] && value <= target[1];
+      default:
+        return true;
+    }
+  }
+
+  return true;
+}
+
 /**
  * Simple in-memory filter evaluation.
  * Supports flat key-value equality and basic operators ($gt, $gte, $lt, $lte, $ne, $in).
@@ -177,9 +242,13 @@ export class ValueDataSource<T = any> implements DataSource<T> {
   async find(_resource: string, params?: QueryParams): Promise<QueryResult<T>> {
     let result = [...this.items];
 
-    // Filter
-    if (params?.$filter && Object.keys(params.$filter).length > 0) {
-      result = result.filter((r) => matchesFilter(r, params.$filter!));
+    // Filter — support both MongoDB-style objects and AST-format arrays
+    if (params?.$filter) {
+      if (Array.isArray(params.$filter) && params.$filter.length > 0) {
+        result = result.filter((r) => matchesASTFilter(r, params.$filter as any[]));
+      } else if (!Array.isArray(params.$filter) && Object.keys(params.$filter).length > 0) {
+        result = result.filter((r) => matchesFilter(r, params.$filter!));
+      }
     }
 
     // Search (simple text search across all string fields)
@@ -316,6 +385,43 @@ export class ValueDataSource<T = any> implements DataSource<T> {
     return null;
   }
 
+  async aggregate(_resource: string, params: AggregateParams): Promise<AggregateResult[]> {
+    const { field, function: aggFn, groupBy } = params;
+    const groups: Record<string, any[]> = {};
+
+    for (const record of this.items as any[]) {
+      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 };
+    });
+  }
+
   // -----------------------------------------------------------------------
   // Extra utilities
   // -----------------------------------------------------------------------

package/src/adapters/__tests__/ValueDataSource.test.ts

@@ -157,6 +157,96 @@ describe('ValueDataSource — find', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// AST-format filter support
+// ---------------------------------------------------------------------------
+
+describe('ValueDataSource — AST filter', () => {
+  it('should filter with simple AST equality condition', async () => {
+    const ds = createDS();
+    const result = await ds.find('users', {
+      $filter: ['role', '=', 'admin'] as any,
+    });
+    expect(result.data).toHaveLength(2);
+    expect(result.data.every((r: any) => r.role === 'admin')).toBe(true);
+  });
+
+  it('should filter with AST "in" operator', async () => {
+    const ds = createDS();
+    const result = await ds.find('users', {
+      $filter: ['role', 'in', ['admin', 'guest']] as any,
+    });
+    expect(result.data).toHaveLength(3);
+  });
+
+  it('should filter with AST "and" logical operator', async () => {
+    const ds = createDS();
+    const result = await ds.find('users', {
+      $filter: ['and', ['role', '=', 'admin'], ['age', '>', 30]] as any,
+    });
+    expect(result.data).toHaveLength(1);
+    expect(result.data[0].name).toBe('Charlie');
+  });
+
+  it('should filter with AST "or" logical operator', async () => {
+    const ds = createDS();
+    const result = await ds.find('users', {
+      $filter: ['or', ['role', '=', 'guest'], ['name', '=', 'Alice']] as any,
+    });
+    expect(result.data).toHaveLength(2);
+  });
+
+  it('should filter with AST "!=" operator', async () => {
+    const ds = createDS();
+    const result = await ds.find('users', {
+      $filter: ['role', '!=', 'admin'] as any,
+    });
+    expect(result.data).toHaveLength(3);
+  });
+
+  it('should filter with AST "not in" operator', async () => {
+    const ds = createDS();
+    const result = await ds.find('users', {
+      $filter: ['role', 'not in', ['admin', 'guest']] as any,
+    });
+    expect(result.data).toHaveLength(2);
+    expect(result.data.every((r: any) => r.role === 'user')).toBe(true);
+  });
+
+  it('should filter with AST "contains" operator', async () => {
+    const ds = createDS();
+    const result = await ds.find('users', {
+      $filter: ['name', 'contains', 'li'] as any,
+    });
+    expect(result.data).toHaveLength(2); // Alice, Charlie
+  });
+
+  it('should filter with nested AST (and with in operator)', async () => {
+    const ds = createDS();
+    const result = await ds.find('users', {
+      $filter: ['and', ['role', 'in', ['admin', 'user']], ['age', '>=', 28]] as any,
+    });
+    expect(result.data).toHaveLength(3); // Alice (30, admin), Charlie (35, admin), Diana (28, user)
+  });
+
+  it('should return all items with empty AST filter', async () => {
+    const ds = createDS();
+    const result = await ds.find('users', { $filter: [] as any });
+    expect(result.data).toHaveLength(5);
+  });
+
+  it('should combine AST filter with sort', async () => {
+    const ds = createDS();
+    const result = await ds.find('users', {
+      $filter: ['role', '=', 'admin'] as any,
+      $orderby: { age: 'asc' },
+    });
+    expect(result.data).toHaveLength(2);
+    expect(result.data[0].name).toBe('Alice');
+    expect(result.data[1].name).toBe('Charlie');
+  });
+});
+
 // ---------------------------------------------------------------------------
 // findOne
 // ---------------------------------------------------------------------------
@@ -323,3 +413,60 @@ describe('ValueDataSource — isolation', () => {
     expect(ds.count).toBe(2);
   });
 });
+
+// ---------------------------------------------------------------------------
+// aggregate
+// ---------------------------------------------------------------------------
+
+describe('ValueDataSource — aggregate', () => {
+  const aggData = [
+    { _id: '1', category: 'A', amount: 10 },
+    { _id: '2', category: 'A', amount: 20 },
+    { _id: '3', category: 'B', amount: 30 },
+    { _id: '4', category: 'B', amount: 40 },
+    { _id: '5', category: 'B', amount: 50 },
+  ];
+
+  function createAggDS() {
+    return new ValueDataSource({ items: aggData });
+  }
+
+  it('should compute sum aggregation', async () => {
+    const ds = createAggDS();
+    const result = await ds.aggregate('items', { field: 'amount', function: 'sum', groupBy: 'category' });
+    expect(result).toHaveLength(2);
+    const groupA = result.find((r: any) => r.category === 'A');
+    const groupB = result.find((r: any) => r.category === 'B');
+    expect(groupA?.amount).toBe(30);
+    expect(groupB?.amount).toBe(120);
+  });
+
+  it('should compute count aggregation', async () => {
+    const ds = createAggDS();
+    const result = await ds.aggregate('items', { field: 'amount', function: 'count', groupBy: 'category' });
+    expect(result).toHaveLength(2);
+    expect(result.find((r: any) => r.category === 'A')?.amount).toBe(2);
+    expect(result.find((r: any) => r.category === 'B')?.amount).toBe(3);
+  });
+
+  it('should compute avg aggregation', async () => {
+    const ds = createAggDS();
+    const result = await ds.aggregate('items', { field: 'amount', function: 'avg', groupBy: 'category' });
+    expect(result.find((r: any) => r.category === 'A')?.amount).toBe(15);
+    expect(result.find((r: any) => r.category === 'B')?.amount).toBe(40);
+  });
+
+  it('should compute min aggregation', async () => {
+    const ds = createAggDS();
+    const result = await ds.aggregate('items', { field: 'amount', function: 'min', groupBy: 'category' });
+    expect(result.find((r: any) => r.category === 'A')?.amount).toBe(10);
+    expect(result.find((r: any) => r.category === 'B')?.amount).toBe(30);
+  });
+
+  it('should compute max aggregation', async () => {
+    const ds = createAggDS();
+    const result = await ds.aggregate('items', { field: 'amount', function: 'max', groupBy: 'category' });
+    expect(result.find((r: any) => r.category === 'A')?.amount).toBe(20);
+    expect(result.find((r: any) => r.category === 'B')?.amount).toBe(50);
+  });
+});