@nocobase/flow-engine 2.2.0-beta.7 → 2.2.0-beta.8

package/src/utils/__tests__/dirtyAwareApiClient.test.ts

@@ -0,0 +1,392 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { FlowContext } from '../../flowContext';
+import { FlowEngine } from '../../flowEngine';
+import { createViewScopedEngine } from '../../ViewScopedFlowEngine';
+import { DATA_SOURCE_DIRTY_EVENT } from '../../views/viewEvents';
+import { getDirtyAwareApiClient, SKIP_DATA_SOURCE_DIRTY } from '../dirtyAwareApiClient';
+
+type TestRequestOptions = {
+  url?: string;
+  resource?: string;
+  action?: string;
+  headers?: Record<string, string>;
+  params?: unknown;
+};
+
+type TestResource = Record<string, (...args: unknown[]) => Promise<unknown>>;
+
+type TestApi = {
+  auth: { locale: string };
+  request: (config: TestRequestOptions) => Promise<unknown>;
+  resource: (name: string, of?: unknown, headers?: Record<string, string>, cancel?: boolean) => TestResource;
+};
+
+function getWrappedApi(engine: FlowEngine, api: TestApi): TestApi {
+  return getDirtyAwareApiClient(api, engine.context) as TestApi;
+}
+
+describe('dirtyAwareApiClient', () => {
+  it('should return non-api values as-is', () => {
+    const context = new FlowContext();
+    const value = { request: vi.fn() };
+
+    expect(getDirtyAwareApiClient(value, context)).toBe(value);
+  });
+
+  it('should mark the resource dirty after mutating resource actions succeed', async () => {
+    const engine = new FlowEngine();
+    const list = vi.fn(async () => ({ data: { data: [] } }));
+    const update = vi.fn(async () => ({ data: { data: { id: 1 } } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ list, update })),
+    };
+    const wrappedApi = getWrappedApi(engine, api);
+
+    await wrappedApi.resource('posts').list();
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(0);
+
+    await wrappedApi.resource('posts').update({ filterByTk: 1, values: { title: 't' } });
+
+    expect(update).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+    expect(getDirtyAwareApiClient(api, engine.context)).toBe(wrappedApi);
+  });
+
+  it('should not double-wrap an already dirty-aware api', async () => {
+    const engine = new FlowEngine();
+    const update = vi.fn(async () => ({ data: { data: { id: 1 } } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ update })),
+    };
+
+    const wrappedApi = getWrappedApi(engine, api);
+    const wrappedAgain = getDirtyAwareApiClient(wrappedApi, engine.context) as TestApi;
+    await wrappedAgain.resource('posts').update({ filterByTk: 1 });
+
+    expect(wrappedAgain).toBe(wrappedApi);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should not mark dirty for read actions', async () => {
+    const nonMutatingActions = [
+      'get',
+      'getSystemSettings',
+      'list',
+      'listByUser',
+      'query',
+      'count',
+      'check',
+      'preview',
+      'test',
+      'find',
+      'exists',
+      'aggregate',
+      'listMine',
+      'parents',
+      'children',
+      'search',
+      'send',
+      'testConnection',
+      'refresh',
+      'run',
+      'runById',
+      'unknownCustomAction',
+    ];
+
+    for (const actionName of nonMutatingActions) {
+      const engine = new FlowEngine();
+      const api: TestApi = {
+        auth: { locale: 'zh-CN' },
+        request: vi.fn(async () => ({ data: { ok: true } })),
+        resource: vi.fn(() => ({
+          [actionName]: vi.fn(async () => ({ data: { data: [] } })),
+        })),
+      };
+
+      await getWrappedApi(engine, api).resource('posts')[actionName]();
+
+      expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(0);
+    }
+  });
+
+  it('should mark dirty for known mutating action variants', async () => {
+    const mutatingActions = [
+      'create',
+      'execute',
+      'updateOrCreate',
+      'firstOrCreate',
+      'setFields',
+      'updateProfile',
+      'saveAsTemplate',
+      'remove/abc',
+    ];
+
+    for (const actionName of mutatingActions) {
+      const engine = new FlowEngine();
+      const api: TestApi = {
+        auth: { locale: 'zh-CN' },
+        request: vi.fn(async () => ({ data: { ok: true } })),
+        resource: vi.fn(() => ({
+          [actionName]: vi.fn(async () => ({ data: { ok: true } })),
+        })),
+      };
+
+      await getWrappedApi(engine, api).resource('posts')[actionName]();
+
+      expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+    }
+  });
+
+  it('should not mark dirty when a mutating action fails', async () => {
+    const engine = new FlowEngine();
+    const update = vi.fn(async () => {
+      throw new Error('update failed');
+    });
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ update })),
+    };
+
+    await expect(getWrappedApi(engine, api).resource('posts').update({ filterByTk: 1 })).rejects.toThrow(
+      'update failed',
+    );
+
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(0);
+  });
+
+  it('should mark association resource and parent collection dirty', async () => {
+    const engine = new FlowEngine();
+    const dirtyEvents: Array<{ dataSourceKey: string; resourceNames: string[] }> = [];
+    engine.emitter.on(DATA_SOURCE_DIRTY_EVENT, (event) => dirtyEvents.push(event));
+    const add = vi.fn(async () => ({ data: { data: null } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ add })),
+    };
+
+    await getWrappedApi(engine, api)
+      .resource('users.roles', 1, { 'x-data-source': 'external' })
+      .add({ values: [1, 2] });
+
+    expect(engine.getDataSourceDirtyVersion('external', 'users.roles')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('external', 'users')).toBe(1);
+    expect(dirtyEvents).toEqual([{ dataSourceKey: 'external', resourceNames: ['users.roles', 'users'] }]);
+  });
+
+  it('should mark resource-action request mutations dirty after success', async () => {
+    const engine = new FlowEngine();
+    const request = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(),
+    };
+
+    await getWrappedApi(engine, api).request({
+      resource: 'posts',
+      action: 'update',
+      headers: { 'X-Data-Source': 'analytics' },
+      params: { filterByTk: 1 },
+    });
+
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('analytics', 'posts')).toBe(1);
+  });
+
+  it('should mark URL-form resource mutations dirty after success', async () => {
+    const engine = new FlowEngine();
+    const request = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(),
+    };
+    const wrappedApi = getWrappedApi(engine, api);
+
+    await wrappedApi.request({ url: 'posts:update' });
+    await wrappedApi.request({
+      url: '/api/posts:update?filterByTk=1',
+      headers: { 'x-data-source': 'external' },
+    });
+    await wrappedApi.request({
+      url: '/api/posts/1/tags:set',
+      headers: { 'X-Data-Source': 'analytics' },
+    });
+
+    expect(request).toHaveBeenCalledTimes(3);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('external', 'posts')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('analytics', 'posts.tags')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('analytics', 'posts')).toBe(1);
+  });
+
+  it('should resolve data source resource URLs to the nested data source target', async () => {
+    const engine = new FlowEngine();
+    const request = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(),
+    };
+
+    await getWrappedApi(engine, api).request({
+      url: 'dataSources/external/collections:update',
+    });
+
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('external', 'collections')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'dataSources.collections')).toBe(0);
+    expect(engine.getDataSourceDirtyVersion('main', 'dataSources')).toBe(0);
+  });
+
+  it('should resolve dataSources resourceOf requests to the nested data source target', async () => {
+    const engine = new FlowEngine();
+    const request = vi.fn(async () => ({ data: { ok: true } }));
+    const update = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(() => ({ update })),
+    };
+    const wrappedApi = getWrappedApi(engine, api);
+
+    await wrappedApi.request({
+      resource: 'dataSources.collections',
+      resourceOf: 'external',
+      action: 'update',
+    } as TestRequestOptions & { resourceOf: string });
+    await wrappedApi.resource('dataSources.roles', 'external').update({ values: { allow: true } });
+    await wrappedApi.resource('dataSources/external/roles').update({ values: { allow: false } });
+
+    expect(engine.getDataSourceDirtyVersion('external', 'collections')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('external', 'roles')).toBe(2);
+    expect(engine.getDataSourceDirtyVersion('main', 'dataSources.collections')).toBe(0);
+    expect(engine.getDataSourceDirtyVersion('main', 'dataSources.roles')).toBe(0);
+  });
+
+  it('should skip dirty marking and strip the internal skip flag from raw requests', async () => {
+    const engine = new FlowEngine();
+    const request = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(),
+    };
+
+    await getWrappedApi(engine, api).request({
+      url: 'posts:update',
+      [SKIP_DATA_SOURCE_DIRTY]: true,
+    } as TestRequestOptions & { [SKIP_DATA_SOURCE_DIRTY]: boolean });
+
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(request.mock.calls[0][0]).not.toHaveProperty(SKIP_DATA_SOURCE_DIRTY);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(0);
+  });
+
+  it('should strip configured API base from URL-form mutations', async () => {
+    const engine = new FlowEngine();
+    const request = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(),
+    };
+    engine.context.defineProperty('app', {
+      value: {
+        getApiUrl(pathname = '') {
+          return `https://app.example.com/foo/api/${pathname.replace(/^\//, '')}`;
+        },
+      },
+    });
+    const wrappedApi = getWrappedApi(engine, api);
+
+    await wrappedApi.request({ url: '/foo/api/posts:update' });
+    await wrappedApi.request({
+      url: 'https://app.example.com/foo/api/users/1/roles:set',
+      headers: { 'x-data-source': 'external' },
+    });
+
+    expect(request).toHaveBeenCalledTimes(2);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'foo.api.posts')).toBe(0);
+    expect(engine.getDataSourceDirtyVersion('external', 'users.roles')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('external', 'users')).toBe(1);
+  });
+
+  it('should not mark URL-form resource dirty for reads, failed mutations, or external URLs', async () => {
+    const engine = new FlowEngine();
+    const request = vi
+      .fn()
+      .mockResolvedValueOnce({ data: { data: [] } })
+      .mockResolvedValueOnce({ data: { data: [] } })
+      .mockRejectedValueOnce(new Error('request failed'))
+      .mockResolvedValueOnce({ data: { ok: true } })
+      .mockResolvedValueOnce({ data: { ok: true } });
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(),
+    };
+    const wrappedApi = getWrappedApi(engine, api);
+
+    await wrappedApi.request({ url: 'posts:list' });
+    await wrappedApi.request({ url: '/api/posts:parents' });
+    await expect(wrappedApi.request({ url: '/api/posts:update' })).rejects.toThrow('request failed');
+    await wrappedApi.request({ url: 'https://example.com/api/posts:update' });
+    await wrappedApi.request({ url: '//example.com/api/posts:update' });
+
+    expect(request).toHaveBeenCalledTimes(5);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(0);
+  });
+
+  it('should mark opener engine dirty when called from a scoped view context', async () => {
+    const root = new FlowEngine();
+    const scoped = createViewScopedEngine(root);
+    const update = vi.fn(async () => ({ data: { data: { id: 1 } } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ update })),
+    };
+
+    await getWrappedApi(scoped, api)
+      .resource('posts')
+      .update({ filterByTk: 1, values: { title: 't' } });
+
+    expect(root.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+    expect(scoped.context.engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should not double-mark when the context exposes a scoped engine proxy', async () => {
+    const root = new FlowEngine();
+    const scoped = createViewScopedEngine(root);
+    const context = new FlowContext();
+    const update = vi.fn(async () => ({ data: { data: { id: 1 } } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ update })),
+    };
+    context.defineProperty('engine', { value: scoped });
+
+    await (getDirtyAwareApiClient(api, context) as TestApi).resource('posts').update({ filterByTk: 1 });
+
+    expect(root.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+    expect(scoped.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+});

package/src/utils/__tests__/openViewRouteState.test.ts

@@ -0,0 +1,40 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { decodeOpenViewRouteState, encodeOpenViewRouteState, isOpenViewRouteStateToken } from '../openViewRouteState';
+
+describe('openViewRouteState', () => {
+  it('encodes route state as an 8-letter view-bound token', () => {
+    const token = encodeOpenViewRouteState('popup', { mode: 'dialog', size: 'large' });
+
+    expect(token).toMatch(/^[A-Za-z]{8}$/);
+    expect(isOpenViewRouteStateToken(token)).toBe(true);
+    expect(decodeOpenViewRouteState('popup', token)).toEqual({ mode: 'dialog', size: 'large' });
+    expect(decodeOpenViewRouteState('other-popup', token)).toBeUndefined();
+  });
+
+  it('can encode mode without leaking a default size', () => {
+    const token = encodeOpenViewRouteState('popup', { mode: 'embed' });
+
+    expect(token).toMatch(/^[A-Za-z]{8}$/);
+    expect(decodeOpenViewRouteState('popup', token)).toEqual({ mode: 'embed' });
+  });
+
+  it('generates distinct tokens for supported route state combinations', () => {
+    const modes = [undefined, 'drawer', 'dialog', 'embed'] as const;
+    const sizes = [undefined, 'small', 'medium', 'large'] as const;
+    const tokens = modes.flatMap((mode) =>
+      sizes
+        .map((size) => encodeOpenViewRouteState('popup', { mode, size }))
+        .filter((token): token is string => !!token),
+    );
+
+    expect(new Set(tokens).size).toBe(tokens.length);
+  });
+});

package/src/utils/__tests__/parsePathnameToViewParams.test.ts

@@ -8,6 +8,7 @@
  */
 
 import { parsePathnameToViewParams } from '../parsePathnameToViewParams';
+import { encodeOpenViewRouteState } from '../openViewRouteState';
 
 describe('parsePathnameToViewParams', () => {
   test('should return single view param for basic admin path', () => {
@@ -48,6 +49,41 @@ describe('parsePathnameToViewParams', () => {
     expect(result).toEqual([{ viewUid: 'xxx' }, { viewUid: 'yyy', filterByTk: '1', sourceId: '1' }]);
   });
 
+  test('should parse RunJS openView route state without losing route params', () => {
+    const token = encodeOpenViewRouteState('yyy', { mode: 'dialog', size: 'large' });
+    if (!token) {
+      throw new Error('Expected openView route state token.');
+    }
+    const result = parsePathnameToViewParams(`/admin/xxx/view/yyy/opts/${token}/filterbytk/1/sourceid/2`);
+
+    expect(result).toEqual([
+      { viewUid: 'xxx' },
+      {
+        viewUid: 'yyy',
+        openViewRouteState: { mode: 'dialog', size: 'large' },
+        filterByTk: '1',
+        sourceId: '2',
+      },
+    ]);
+  });
+
+  test('should ignore invalid RunJS openView opts and keep following params', () => {
+    const result = parsePathnameToViewParams('/admin/xxx/view/yyy/opts/AbCdEfGh/filterbytk/1');
+
+    expect(result).toEqual([{ viewUid: 'xxx' }, { viewUid: 'yyy', filterByTk: '1' }]);
+  });
+
+  test('should not parse bare RunJS openView route state token segments', () => {
+    const token = encodeOpenViewRouteState('yyy', { mode: 'dialog', size: 'large' });
+    if (!token) {
+      throw new Error('Expected openView route state token.');
+    }
+    const result = parsePathnameToViewParams(`/admin/xxx/view/yyy/${token}/filterbytk/1`);
+
+    expect(result[1]).toMatchObject({ viewUid: 'yyy' });
+    expect(result[1]?.openViewRouteState).toBeUndefined();
+  });
+
   test('should handle multiple views with different filterByTk and sourceId', () => {
     const result = parsePathnameToViewParams(
       '/admin/xxx/view/yyy/filterbytk/1/sourceid/1/view/zzz/filterbytk/2/sourceid/2',

package/src/utils/dataSourceDirty.ts

@@ -0,0 +1,126 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import type { FlowEngine } from '../flowEngine';
+import { DATA_SOURCE_DIRTY_EVENT } from '../views/viewEvents';
+
+type MarkDataSourceDirtyOptions = {
+  engine?: FlowEngine;
+  dataSourceKey?: unknown;
+  resourceName?: unknown;
+  includePreviousEngines?: boolean;
+};
+
+export function getHeaderValue(headers: unknown, name: string): unknown {
+  if (!headers || typeof headers !== 'object') {
+    return undefined;
+  }
+
+  const maybeHeaders = headers as { get?: (key: string) => unknown };
+  if (typeof maybeHeaders.get === 'function') {
+    const value = maybeHeaders.get(name);
+    if (value != null && value !== '') {
+      return value;
+    }
+  }
+
+  const lowerName = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers as Record<string, unknown>)) {
+    if (key.toLowerCase() === lowerName) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+export function getDataSourceKeyFromHeaders(headers: unknown): string {
+  const value = getHeaderValue(headers, 'x-data-source');
+  if (Array.isArray(value)) {
+    return String(value[0] || 'main');
+  }
+  return value == null || value === '' ? 'main' : String(value);
+}
+
+export function getAffectedResourceNames(resourceName: unknown): string[] {
+  const name = String(resourceName || '').trim();
+  if (!name) {
+    return [];
+  }
+
+  const names = new Set<string>([name]);
+  if (name.includes('.')) {
+    names.add(name.split('.')[0]);
+  }
+  return Array.from(names);
+}
+
+function getDirtyTargetEngines(engine: FlowEngine, includePreviousEngines?: boolean): FlowEngine[] {
+  if (!includePreviousEngines) {
+    return [engine];
+  }
+
+  const engines: FlowEngine[] = [];
+  const seen = new Set<FlowEngine>();
+  let current: FlowEngine | undefined = engine;
+  let guard = 0;
+
+  while (current && guard++ < 50) {
+    if (!seen.has(current)) {
+      engines.push(current);
+      seen.add(current);
+    }
+    current = current.previousEngine;
+  }
+
+  return engines;
+}
+
+export function markDataSourceDirty(options: MarkDataSourceDirtyOptions): string[] {
+  const { engine, resourceName, includePreviousEngines } = options;
+  if (!engine?.markDataSourceDirty) {
+    return [];
+  }
+
+  const resourceNames = getAffectedResourceNames(resourceName);
+  if (!resourceNames.length) {
+    return [];
+  }
+
+  const dataSourceKey = String(options.dataSourceKey || 'main');
+  const targetEngines = getDirtyTargetEngines(engine, includePreviousEngines);
+  const beforeVersions = new Map<FlowEngine, Map<string, number>>();
+
+  for (const targetEngine of targetEngines) {
+    const versions = new Map<string, number>();
+    beforeVersions.set(targetEngine, versions);
+    for (const name of resourceNames) {
+      versions.set(name, targetEngine.getDataSourceDirtyVersion?.(dataSourceKey, name) || 0);
+    }
+  }
+
+  for (const targetEngine of targetEngines) {
+    const versions = beforeVersions.get(targetEngine);
+    for (const name of resourceNames) {
+      const before = versions?.get(name) || 0;
+      const current = targetEngine.getDataSourceDirtyVersion?.(dataSourceKey, name) || 0;
+      if (current !== before) {
+        continue;
+      }
+      targetEngine.markDataSourceDirty(dataSourceKey, name);
+    }
+  }
+
+  engine.emitter?.emit?.(DATA_SOURCE_DIRTY_EVENT, {
+    dataSourceKey,
+    resourceNames,
+  });
+
+  return resourceNames;
+}