ezfw-core 1.0.0

package/components/grid/state/EzGridPersistence.ts

@@ -0,0 +1,140 @@
+// EzGrid/state/EzGridPersistence.ts
+
+import { EzError } from '../../../core/EzError.js';
+import type {
+    ColumnsSnapshot,
+    Sorter,
+    SelectionSnapshot,
+    GridStateSnapshot
+} from '../types.js';
+
+declare const ez: {
+    _gridStateRegistry: Record<string, GridRegistryEntry>;
+};
+
+export interface GridRegistryEntry {
+    _columnState?: ColumnsSnapshot | null;
+    _sortState?: Sorter[] | null;
+    _selectionState?: SelectionSnapshot | null;
+    [key: string]: unknown;
+}
+
+export interface EzGridPersistenceRef {
+    _context?: {
+        route?: string;
+        view?: string;
+    };
+    config: {
+        id?: string;
+    };
+    statefulPersist?: boolean;
+}
+
+// Re-export for backwards compatibility
+export type { GridStateSnapshot } from '../types.js';
+
+export class EzGridPersistence {
+    grid: EzGridPersistenceRef;
+
+    constructor(grid: EzGridPersistenceRef) {
+        this.grid = grid;
+    }
+
+    // ==========================================================
+    // State Key Management
+    // ==========================================================
+
+    getStateKey(): string {
+        const route = this.grid._context?.route ?? 'global';
+        const view = this.grid._context?.view ?? 'unknown';
+        const id = this.grid.config.id;
+
+        if (!id) {
+            throw new EzError({
+                code: 'EZ_GRID_STATE_001',
+                message: 'Stateful EzGrid requires a unique "id"'
+            });
+        }
+
+        return `${route}:${view}:${id}`;
+    }
+
+    getStorageKey(): string {
+        return `EZ_GRID_STATE::${this.getStateKey()}`;
+    }
+
+    // ==========================================================
+    // Storage Operations
+    // ==========================================================
+
+    load(): GridStateSnapshot | null {
+        if (!this.grid.statefulPersist) return null;
+
+        try {
+            const raw = localStorage.getItem(this.getStorageKey());
+            if (!raw) return null;
+            return JSON.parse(raw) as GridStateSnapshot;
+        } catch {
+            return null;
+        }
+    }
+
+    save(): void {
+        if (!this.grid.statefulPersist) return;
+
+        try {
+            const entry = ez._gridStateRegistry[this.getStateKey()];
+            if (!entry) return;
+
+            const snapshot: GridStateSnapshot = {
+                columnState: entry._columnState ?? null,
+                sortState: entry._sortState ?? null,
+                selectionState: entry._selectionState ?? null
+            };
+
+            localStorage.setItem(
+                this.getStorageKey(),
+                JSON.stringify(snapshot)
+            );
+        } catch {
+            // fail silently
+        }
+    }
+
+    // ==========================================================
+    // Registry Operations
+    // ==========================================================
+
+    getRegistryEntry(): GridRegistryEntry | undefined {
+        return ez._gridStateRegistry[this.getStateKey()];
+    }
+
+    setRegistryEntry(controller: GridRegistryEntry): void {
+        ez._gridStateRegistry[this.getStateKey()] = controller;
+    }
+
+    hasRegistryEntry(): boolean {
+        return !!ez._gridStateRegistry[this.getStateKey()];
+    }
+
+    updateColumnState(snapshot: ColumnsSnapshot | null): void {
+        const entry = this.getRegistryEntry();
+        if (entry) {
+            entry._columnState = snapshot;
+        }
+    }
+
+    updateSortState(snapshot: Sorter[] | null): void {
+        const entry = this.getRegistryEntry();
+        if (entry) {
+            entry._sortState = snapshot;
+        }
+    }
+
+    updateSelectionState(snapshot: SelectionSnapshot | null): void {
+        const entry = this.getRegistryEntry();
+        if (entry) {
+            entry._selectionState = snapshot;
+        }
+    }
+}

package/components/grid/state/EzGridRemote.test.js

@@ -0,0 +1,573 @@
+// ==========================================================
+// EzGridRemote - Unit Tests
+// ==========================================================
+// Para correr: npm test EzGridRemote
+// ==========================================================
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { EzGridRemote } from './EzGridRemote.js';
+
+// ==========================================================
+// Mock Setup
+// ==========================================================
+
+// Mock del objeto global ez
+const mockEz = {
+    _api: {
+        request: vi.fn()
+    },
+    getController: vi.fn()
+};
+
+// Instalar mock global antes de cada test
+beforeEach(() => {
+    globalThis.ez = mockEz;
+    vi.clearAllMocks();
+});
+
+afterEach(() => {
+    delete globalThis.ez;
+});
+
+// Helper para crear mock de grid
+function createMockGrid(options = {}) {
+    return {
+        controller: {
+            state: {
+                page: 1,
+                pageSize: 25
+            },
+            setLoading: vi.fn(),
+            setError: vi.fn(),
+            _lastSortSnapshot: null,
+            _lastFilterSnapshot: null
+        },
+        config: {
+            controller: options.controllerName || 'TestController'
+        }
+    };
+}
+
+// ==========================================================
+// Constructor & Config
+// ==========================================================
+
+describe('EzGridRemote - Configuration', () => {
+
+    it('should normalize string api to object', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        expect(remote.config.api.read).toBe('v1/users');
+        expect(remote.config.api.create).toBe('v1/users');
+        expect(remote.config.api.update).toBe('v1/users');
+        expect(remote.config.api.delete).toBe('v1/users');
+    });
+
+    it('should preserve object api', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: {
+                read: 'v1/users',
+                create: 'v1/users/create'
+            }
+        });
+
+        expect(remote.config.api.read).toBe('v1/users');
+        expect(remote.config.api.create).toBe('v1/users/create');
+    });
+
+    it('should use default source paths', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        expect(remote.config.source.dataPath).toBe('data');
+        expect(remote.config.source.countPath).toBe('count');
+    });
+
+    it('should use custom source paths', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users',
+            source: {
+                dataPath: 'result.items',
+                countPath: 'result.total'
+            }
+        });
+
+        expect(remote.config.source.dataPath).toBe('result.items');
+        expect(remote.config.source.countPath).toBe('result.total');
+    });
+
+    it('should default filter mode to onInput', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        expect(remote.config.filter).toBe('onInput');
+    });
+
+    it('should preserve filter mode onEnter', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users',
+            filter: 'onEnter'
+        });
+
+        expect(remote.config.filter).toBe('onEnter');
+    });
+
+});
+
+// ==========================================================
+// isEnabled
+// ==========================================================
+
+describe('EzGridRemote.isEnabled', () => {
+
+    it('should return true when read api is configured', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        expect(remote.isEnabled()).toBe(true);
+    });
+
+    it('should return false when no config', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, null);
+
+        expect(remote.isEnabled()).toBe(false);
+    });
+
+    it('should return false when no read api', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: {}
+        });
+
+        expect(remote.isEnabled()).toBe(false);
+    });
+
+});
+
+// ==========================================================
+// URL Building
+// ==========================================================
+
+describe('EzGridRemote._buildReadUrl', () => {
+
+    it('should build basic URL with pagination', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        const url = remote._buildReadUrl({ page: 1, pageSize: 25 });
+
+        expect(url).toBe('v1/users?page=1&pageSize=25');
+    });
+
+    it('should include sort params', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        const url = remote._buildReadUrl({
+            page: 1,
+            pageSize: 25,
+            sort: [{ property: 'name', direction: 'ASC' }]
+        });
+
+        expect(url).toContain('sortBy=name');
+        expect(url).toContain('sortDir=ASC');
+    });
+
+    it('should include filters as JSON', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        const filters = [{ field: 'name', operator: 'LIKE', value: 'John' }];
+        const url = remote._buildReadUrl({
+            page: 1,
+            pageSize: 25,
+            filters
+        });
+
+        expect(url).toContain('filters=');
+        expect(url).toContain(encodeURIComponent(JSON.stringify(filters)));
+    });
+
+});
+
+// ==========================================================
+// Response Parsing
+// ==========================================================
+
+describe('EzGridRemote._parseResponse', () => {
+
+    it('should parse data and count from default paths', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        const response = {
+            data: [{ id: 1 }, { id: 2 }],
+            count: 100
+        };
+
+        const result = remote._parseResponse(response);
+
+        expect(result.data).toEqual([{ id: 1 }, { id: 2 }]);
+        expect(result.total).toBe(100);
+    });
+
+    it('should parse data from nested path', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users',
+            source: {
+                dataPath: 'result.items',
+                countPath: 'result.total'
+            }
+        });
+
+        const response = {
+            result: {
+                items: [{ id: 1 }],
+                total: 50
+            }
+        };
+
+        const result = remote._parseResponse(response);
+
+        expect(result.data).toEqual([{ id: 1 }]);
+        expect(result.total).toBe(50);
+    });
+
+    it('should return empty array if data is not array', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        const result = remote._parseResponse({ data: null });
+
+        expect(result.data).toEqual([]);
+    });
+
+    it('should use data length if count not available', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        const result = remote._parseResponse({
+            data: [{ id: 1 }, { id: 2 }, { id: 3 }]
+        });
+
+        expect(result.total).toBe(3);
+    });
+
+});
+
+// ==========================================================
+// Callback Resolution
+// ==========================================================
+
+describe('EzGridRemote._resolveCallback', () => {
+
+    it('should return function as-is', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, { api: 'v1/users' });
+
+        const fn = () => 'test';
+        const result = remote._resolveCallback(fn);
+
+        expect(result).toBe(fn);
+    });
+
+    it('should resolve ControllerName:functionName format', () => {
+        const mockController = {
+            handleData: vi.fn().mockReturnValue('handled')
+        };
+        mockEz.getController.mockReturnValue(mockController);
+
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, { api: 'v1/users' });
+
+        const result = remote._resolveCallback('UserController:handleData');
+
+        expect(mockEz.getController).toHaveBeenCalledWith('UserController');
+        expect(typeof result).toBe('function');
+        expect(result()).toBe('handled');
+    });
+
+    it('should resolve functionName using config.controller', () => {
+        const mockController = {
+            onLoad: vi.fn().mockReturnValue('loaded')
+        };
+        mockEz.getController.mockReturnValue(mockController);
+
+        const grid = createMockGrid({ controllerName: 'MyController' });
+        const remote = new EzGridRemote(grid, { api: 'v1/users' });
+
+        const result = remote._resolveCallback('onLoad');
+
+        expect(mockEz.getController).toHaveBeenCalledWith('MyController');
+        expect(typeof result).toBe('function');
+    });
+
+    it('should return null for invalid string reference', () => {
+        mockEz.getController.mockReturnValue(null);
+
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, { api: 'v1/users' });
+
+        const result = remote._resolveCallback('nonExistent');
+
+        expect(result).toBe(null);
+    });
+
+    it('should return null for non-function/non-string', () => {
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, { api: 'v1/users' });
+
+        expect(remote._resolveCallback(123)).toBe(null);
+        expect(remote._resolveCallback(null)).toBe(null);
+        expect(remote._resolveCallback({})).toBe(null);
+    });
+
+});
+
+// ==========================================================
+// Load
+// ==========================================================
+
+describe('EzGridRemote.load', () => {
+
+    it('should call ez._api.request with correct URL', async () => {
+        mockEz._api.request.mockResolvedValue({
+            data: [{ id: 1 }],
+            count: 1
+        });
+
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        await remote.load();
+
+        expect(mockEz._api.request).toHaveBeenCalledWith(
+            expect.stringContaining('v1/users')
+        );
+    });
+
+    it('should return parsed data and total', async () => {
+        mockEz._api.request.mockResolvedValue({
+            data: [{ id: 1 }, { id: 2 }],
+            count: 100
+        });
+
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        const result = await remote.load();
+
+        expect(result.data).toHaveLength(2);
+        expect(result.total).toBe(100);
+    });
+
+    it('should set loading state', async () => {
+        mockEz._api.request.mockResolvedValue({ data: [], count: 0 });
+
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        await remote.load();
+
+        expect(grid.controller.setLoading).toHaveBeenCalledWith(true);
+        expect(grid.controller.setLoading).toHaveBeenCalledWith(false);
+    });
+
+    it('should call beforeLoad hook', async () => {
+        mockEz._api.request.mockResolvedValue({ data: [], count: 0 });
+
+        const beforeLoad = vi.fn();
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users',
+            listenTo: { beforeLoad }
+        });
+
+        await remote.load();
+
+        expect(beforeLoad).toHaveBeenCalledWith(
+            expect.objectContaining({ page: 1, pageSize: 25 }),
+            expect.objectContaining({ grid, remote })
+        );
+    });
+
+    it('should call afterLoad hook with result', async () => {
+        const responseData = { data: [{ id: 1 }], count: 1 };
+        mockEz._api.request.mockResolvedValue(responseData);
+
+        const afterLoad = vi.fn();
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users',
+            listenTo: { afterLoad }
+        });
+
+        await remote.load();
+
+        expect(afterLoad).toHaveBeenCalledWith(
+            expect.objectContaining({ data: [{ id: 1 }], total: 1 }),
+            expect.objectContaining({ grid, remote, response: responseData })
+        );
+    });
+
+    it('should call onError hook on failure', async () => {
+        const error = new Error('Network error');
+        mockEz._api.request.mockRejectedValue(error);
+
+        const onError = vi.fn();
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users',
+            listenTo: { onError }
+        });
+
+        await remote.load();
+
+        expect(onError).toHaveBeenCalledWith(
+            error,
+            expect.objectContaining({ grid, remote })
+        );
+    });
+
+    it('should return empty data on error', async () => {
+        mockEz._api.request.mockRejectedValue(new Error('Failed'));
+
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        const result = await remote.load();
+
+        expect(result.data).toEqual([]);
+        expect(result.total).toBe(0);
+    });
+
+    it('should prevent concurrent loads', async () => {
+        let resolveFirst;
+        mockEz._api.request.mockImplementationOnce(() =>
+            new Promise(resolve => { resolveFirst = resolve; })
+        );
+
+        const grid = createMockGrid();
+        const remote = new EzGridRemote(grid, {
+            api: 'v1/users'
+        });
+
+        // Start first load
+        const firstLoad = remote.load();
+
+        // Try second load while first is pending
+        const secondResult = await remote.load();
+
+        // Second should return empty immediately
+        expect(secondResult.data).toEqual([]);
+
+        // Complete first load
+        resolveFirst({ data: [{ id: 1 }], count: 1 });
+        await firstLoad;
+    });
+
+});
+
+// ==========================================================
+// CRUD Operations
+// ==========================================================
+
+describe('EzGridRemote CRUD', () => {
+
+    describe('create', () => {
+        it('should POST to create endpoint', async () => {
+            mockEz._api.request.mockResolvedValue({ id: 1 });
+
+            const grid = createMockGrid();
+            const remote = new EzGridRemote(grid, {
+                api: { read: 'v1/users', create: 'v1/users' }
+            });
+
+            await remote.create({ name: 'John' });
+
+            expect(mockEz._api.request).toHaveBeenCalledWith('v1/users', {
+                method: 'POST',
+                body: { name: 'John' }
+            });
+        });
+
+        it('should throw if create not configured', async () => {
+            const grid = createMockGrid();
+            const remote = new EzGridRemote(grid, {
+                api: { read: 'v1/users' }
+            });
+
+            await expect(remote.create({})).rejects.toThrow('Create endpoint not configured');
+        });
+    });
+
+    describe('update', () => {
+        it('should PUT to update endpoint with id', async () => {
+            mockEz._api.request.mockResolvedValue({ id: 1 });
+
+            const grid = createMockGrid();
+            const remote = new EzGridRemote(grid, {
+                api: { read: 'v1/users', update: 'v1/users' }
+            });
+
+            await remote.update(1, { name: 'Jane' });
+
+            expect(mockEz._api.request).toHaveBeenCalledWith('v1/users/1', {
+                method: 'PUT',
+                body: { name: 'Jane' }
+            });
+        });
+    });
+
+    describe('delete', () => {
+        it('should DELETE to endpoint with id', async () => {
+            mockEz._api.request.mockResolvedValue({});
+
+            const grid = createMockGrid();
+            const remote = new EzGridRemote(grid, {
+                api: { read: 'v1/users', delete: 'v1/users' }
+            });
+
+            await remote.delete(1);
+
+            expect(mockEz._api.request).toHaveBeenCalledWith('v1/users/1', {
+                method: 'DELETE'
+            });
+        });
+    });
+
+});