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

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

@@ -8,6 +8,7 @@
  */
 
 import { describe, expect, it, vi } from 'vitest';
+import { APIClient, type IResource, type RequestOptions } from '@nocobase/sdk';
 import { FlowContext } from '../../flowContext';
 import { FlowEngine } from '../../flowEngine';
 import { createViewScopedEngine } from '../../ViewScopedFlowEngine';
@@ -80,6 +81,326 @@ describe('dirtyAwareApiClient', () => {
     expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
   });
 
+  it('should keep request overrides local to the dirty-aware proxy', 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 originalRequest = api.request;
+    const wrappedApi = getWrappedApi(engine, api);
+    const delegatedRequest = wrappedApi.request.bind(wrappedApi);
+    const requestOverride = vi.fn((config: TestRequestOptions) => delegatedRequest(config));
+
+    wrappedApi.request = requestOverride;
+
+    await wrappedApi.request({ url: 'posts:list' });
+
+    expect(requestOverride).toHaveBeenCalledTimes(1);
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(api.request).toBe(originalRequest);
+  });
+
+  it('should keep resource overrides local to the dirty-aware proxy', async () => {
+    const engine = new FlowEngine();
+    const update = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ update })),
+    };
+    const originalResource = api.resource;
+    const wrappedApi = getWrappedApi(engine, api);
+    const delegatedResource = wrappedApi.resource.bind(wrappedApi);
+    const resourceOverride = vi.fn((...args: Parameters<TestApi['resource']>) => delegatedResource(...args));
+
+    wrappedApi.resource = resourceOverride;
+
+    await wrappedApi.resource('posts').update({ filterByTk: 1 });
+
+    expect(resourceOverride).toHaveBeenCalledTimes(1);
+    expect(update).toHaveBeenCalledTimes(1);
+    expect(api.resource).toBe(originalResource);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should route resource actions through the local request override without double-marking', async () => {
+    const engine = new FlowEngine();
+    const api = new APIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+    const delegatedRequest = wrappedApi.request.bind(wrappedApi);
+    const requestOverride = vi.fn((config: Parameters<APIClient['request']>[0]) => delegatedRequest(config));
+
+    wrappedApi.request = requestOverride as APIClient['request'];
+
+    await wrappedApi.resource('posts').update({ filterByTk: 1, values: { title: 'updated' } });
+
+    expect(requestOverride).toHaveBeenCalledTimes(1);
+    expect(transport).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should invoke custom request methods on the original api instance', async () => {
+    class StatefulRequestAPIClient extends APIClient {
+      #privateRequestCalls = 0;
+      publicRequestCalls = 0;
+
+      get privateRequestCalls() {
+        return this.#privateRequestCalls;
+      }
+
+      override request<T, R, D>(config: Parameters<APIClient['request']>[0]): Promise<R> {
+        this.#privateRequestCalls += 1;
+        this.publicRequestCalls += 1;
+        return super.request<T, R, D>(config);
+      }
+    }
+
+    const engine = new FlowEngine();
+    const api = new StatefulRequestAPIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+
+    await wrappedApi.resource('posts').update({ filterByTk: 1, values: { title: 'updated' } });
+
+    expect(transport).toHaveBeenCalledTimes(1);
+    expect(api.privateRequestCalls).toBe(1);
+    expect(api.publicRequestCalls).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should invoke custom resource methods on the original api instance', async () => {
+    class StatefulResourceAPIClient extends APIClient {
+      #privateResourceCalls = 0;
+      publicResourceCalls = 0;
+
+      get privateResourceCalls() {
+        return this.#privateResourceCalls;
+      }
+
+      override resource(...args: Parameters<APIClient['resource']>): IResource {
+        this.#privateResourceCalls += 1;
+        this.publicResourceCalls += 1;
+        return super.resource(...args);
+      }
+    }
+
+    const engine = new FlowEngine();
+    const api = new StatefulResourceAPIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+
+    await wrappedApi.request({
+      resource: 'posts',
+      action: 'update',
+      params: { filterByTk: 1, values: { title: 'updated' } },
+    });
+
+    expect(transport).toHaveBeenCalledTimes(1);
+    expect(api.privateResourceCalls).toBe(1);
+    expect(api.publicResourceCalls).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should keep one dirty mark when the request override rebuilds the config', async () => {
+    const engine = new FlowEngine();
+    const api = new APIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+    const delegatedRequest = wrappedApi.request.bind(wrappedApi);
+    const requestOverride = vi.fn((config: Parameters<APIClient['request']>[0]) => {
+      const { url, method, headers, params, data } = config as RequestOptions;
+      return delegatedRequest({ url, method, headers, params, data });
+    });
+
+    wrappedApi.request = requestOverride as APIClient['request'];
+
+    await wrappedApi.resource('posts').update({ filterByTk: 1, values: { title: 'updated' } });
+
+    expect(requestOverride).toHaveBeenCalledTimes(1);
+    expect(transport).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should keep nested mutations from a request override independent', async () => {
+    const engine = new FlowEngine();
+    const api = new APIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+    const delegatedRequest = wrappedApi.request.bind(wrappedApi);
+    const requestOverride = vi.fn(async (config: Parameters<APIClient['request']>[0]) => {
+      await delegatedRequest({ url: 'comments:create', method: 'post' });
+      return delegatedRequest(config);
+    });
+
+    wrappedApi.request = requestOverride as APIClient['request'];
+
+    await wrappedApi.resource('posts').update({ filterByTk: 1, values: { title: 'updated' } });
+
+    expect(requestOverride).toHaveBeenCalledTimes(1);
+    expect(transport).toHaveBeenCalledTimes(2);
+    expect(engine.getDataSourceDirtyVersion('main', 'comments')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should route structured requests through the local resource override without double-marking', async () => {
+    const engine = new FlowEngine();
+    const api = new APIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+    const delegatedResource = wrappedApi.resource.bind(wrappedApi);
+    const resourceOverride = vi.fn((...args: Parameters<APIClient['resource']>) => delegatedResource(...args));
+
+    wrappedApi.resource = resourceOverride;
+
+    await wrappedApi.request({
+      resource: 'posts',
+      action: 'update',
+      params: { filterByTk: 1, values: { title: 'updated' } },
+    });
+
+    expect(resourceOverride).toHaveBeenCalledTimes(1);
+    expect(transport).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should keep one dirty mark when the resource override delegates lazily', async () => {
+    const engine = new FlowEngine();
+    const api = new APIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+    const delegatedResource = wrappedApi.resource.bind(wrappedApi);
+    const resourceOverride = vi.fn(
+      (...args: Parameters<APIClient['resource']>): IResource => ({
+        update: async (...actionArgs: Parameters<IResource['update']>) => {
+          await Promise.resolve();
+          return delegatedResource(...args).update(...actionArgs);
+        },
+      }),
+    );
+
+    wrappedApi.resource = resourceOverride;
+
+    await wrappedApi.request({
+      resource: 'posts',
+      action: 'update',
+      params: { filterByTk: 1, values: { title: 'updated' } },
+    });
+
+    expect(resourceOverride).toHaveBeenCalledTimes(1);
+    expect(transport).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should keep nested mutations from a resource override independent', async () => {
+    const engine = new FlowEngine();
+    const api = new APIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+    const delegatedResource = wrappedApi.resource.bind(wrappedApi);
+    let nestedMutation: Promise<unknown> | undefined;
+    const resourceOverride = vi.fn((...args: Parameters<APIClient['resource']>) => {
+      nestedMutation = delegatedResource('comments').create({ values: { body: 'nested' } });
+      return delegatedResource(...args);
+    });
+
+    wrappedApi.resource = resourceOverride;
+
+    await wrappedApi.request({
+      resource: 'posts',
+      action: 'update',
+      params: { filterByTk: 1, values: { title: 'updated' } },
+    });
+    await nestedMutation;
+
+    expect(resourceOverride).toHaveBeenCalledTimes(1);
+    expect(transport).toHaveBeenCalledTimes(2);
+    expect(engine.getDataSourceDirtyVersion('main', 'comments')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should clear local request and resource overrides when deleted', () => {
+    const engine = new FlowEngine();
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({})),
+    };
+    const wrappedApi = getWrappedApi(engine, api);
+    const defaultRequest = wrappedApi.request;
+    const defaultResource = wrappedApi.resource;
+
+    wrappedApi.request = vi.fn();
+    wrappedApi.resource = vi.fn();
+
+    expect(Reflect.deleteProperty(wrappedApi, 'request')).toBe(true);
+    expect(Reflect.deleteProperty(wrappedApi, 'resource')).toBe(true);
+    expect(wrappedApi.request).toBe(defaultRequest);
+    expect(wrappedApi.resource).toBe(defaultResource);
+  });
+
+  it('should reject request and resource descriptor overrides without mutating the raw api', () => {
+    const engine = new FlowEngine();
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({})),
+    };
+    const wrappedApi = getWrappedApi(engine, api);
+    const originalRequest = api.request;
+    const originalResource = api.resource;
+
+    expect(Reflect.defineProperty(wrappedApi, 'request', { value: vi.fn() })).toBe(false);
+    expect(Reflect.defineProperty(wrappedApi, 'resource', { value: vi.fn() })).toBe(false);
+    expect(() => Object.defineProperty(wrappedApi, 'request', { value: vi.fn() })).toThrow(TypeError);
+    expect(() => Object.defineProperty(wrappedApi, 'resource', { value: vi.fn() })).toThrow(TypeError);
+    expect(api.request).toBe(originalRequest);
+    expect(api.resource).toBe(originalResource);
+  });
+
+  it('should reject local overrides for own methods on a non-extensible raw api', () => {
+    const engine = new FlowEngine();
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({})),
+    };
+    const wrappedApi = getWrappedApi(engine, api);
+    const defaultMethods = {
+      request: wrappedApi.request,
+      resource: wrappedApi.resource,
+    };
+
+    Object.preventExtensions(api);
+
+    for (const methodName of ['request', 'resource'] as const) {
+      expect(Reflect.set(wrappedApi, methodName, vi.fn())).toBe(false);
+      expect(wrappedApi[methodName]).toBe(defaultMethods[methodName]);
+      expect(Reflect.deleteProperty(wrappedApi, methodName)).toBe(false);
+    }
+  });
+
+  it('should keep overrides isolated between flow contexts', () => {
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({})),
+    };
+    const firstContextApi = getDirtyAwareApiClient(api, new FlowContext()) as TestApi;
+    const secondContextApi = getDirtyAwareApiClient(api, new FlowContext()) as TestApi;
+    const secondRequest = secondContextApi.request;
+    const requestOverride = vi.fn();
+
+    firstContextApi.request = requestOverride;
+
+    expect(firstContextApi.request).toBe(requestOverride);
+    expect(secondContextApi.request).toBe(secondRequest);
+    expect(api.request).not.toBe(requestOverride);
+  });
+
   it('should not mark dirty for read actions', async () => {
     const nonMutatingActions = [
       'get',

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

@@ -34,7 +34,8 @@ describe('variablesParams helpers', () => {
 
   it('inferRecordRef fallback to collection.getFilterByTK when resource has no filterByTk', () => {
     const engine = new FlowEngine();
-    const ds = engine.context.dataSourceManager.getDataSource('main')!;
+    const ds = engine.context.dataSourceManager.getDataSource('main');
+    if (!ds) throw new Error('main data source is required');
     ds.addCollection({
       name: 'users',
       filterTargetKey: 'id',
@@ -108,6 +109,32 @@ describe('variablesParams helpers', () => {
     });
   });
 
+  it('collectContextParamsForTemplate infers view.record when its meta has no descriptor', async () => {
+    const ctx: any = {
+      getPropertyOptions: () => undefined,
+      view: {
+        inputArgs: {
+          collectionName: 'posts',
+          dataSourceKey: 'main',
+          filterByTk: 3,
+        },
+      },
+    };
+
+    const res = await collectContextParamsForTemplate(ctx, {
+      recordId: '{{ ctx.view.record.id }}',
+      viewType: '{{ ctx.view.type }}',
+    });
+
+    expect(res).toEqual({
+      'view.record': {
+        collection: 'posts',
+        dataSourceKey: 'main',
+        filterByTk: 3,
+      },
+    });
+  });
+
   it('createRecordResolveOnServerWithLocal: no local record => always use server', () => {
     const resolver = createRecordResolveOnServerWithLocal(
       () => ({ name: 'posts', dataSourceKey: 'main' }) as any,

package/src/utils/associationObjectVariable.ts

@@ -51,13 +51,14 @@ function findFieldByName(collection: Collection | null | undefined, name?: strin
  * @param primaryKey 主键字段名
  * @returns 解析出的主键值，无法解析时返回 undefined
  */
-function toFilterByTk(value: unknown, primaryKey: string | string[]) {
+export function getAssociationFilterByTk(value: unknown, primaryKey: string | string[]) {
   if (value == null) return undefined;
   if (Array.isArray(primaryKey)) {
     if (typeof value !== 'object' || !value) return undefined;
-    const out: Record<string, any> = {};
+    const record = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
     for (const k of primaryKey) {
-      const v = (value as any)[k];
+      const v = record[k];
       if (typeof v === 'undefined' || v === null) return undefined;
       out[k] = v;
     }
@@ -65,7 +66,7 @@ function toFilterByTk(value: unknown, primaryKey: string | string[]) {
   }
   if (typeof value === 'string' || typeof value === 'number') return value;
   if (typeof value === 'object') {
-    return (value as any)[primaryKey];
+    return (value as Record<string, unknown>)[primaryKey];
   }
   return undefined;
 }
@@ -149,7 +150,9 @@ export function createAssociationAwareObjectMetaFactory(
           if (associationValue == null) continue;
 
           if (Array.isArray(associationValue)) {
-            const ids = associationValue.map((item) => toFilterByTk(item, primaryKey)).filter((v) => v != null);
+            const ids = associationValue
+              .map((item) => getAssociationFilterByTk(item, primaryKey))
+              .filter((v) => v != null);
             if (ids.length) {
               params[name] = {
                 collection: target,
@@ -158,7 +161,7 @@ export function createAssociationAwareObjectMetaFactory(
               };
             }
           } else {
-            const id = toFilterByTk(associationValue, primaryKey);
+            const id = getAssociationFilterByTk(associationValue, primaryKey);
             if (id != null) {
               params[name] = {
                 collection: target,

package/src/utils/dateVariable.ts

@@ -11,7 +11,7 @@ import dayjs from 'dayjs';
 
 const CTX_DATE_REGEX = /^\{\{\s*ctx\.date(?:\.(.+?))?\s*\}\}$/;
 
-const PRESET_KEYS = new Set([
+const PRESET_KEY_LIST = [
   'today',
   'now',
   'yesterday',
@@ -28,10 +28,28 @@ const PRESET_KEYS = new Set([
   'thisYear',
   'lastYear',
   'nextYear',
-]);
+] as const;
+
+export type CtxDatePreset = (typeof PRESET_KEY_LIST)[number];
+export type CtxDateRelativeDirection = 'next' | 'past';
+export type CtxDateRelativeUnit = 'day' | 'week' | 'month' | 'year';
+
+export type CtxDateExpressionConfig =
+  | { kind: 'exact'; value: string | [string, string]; format?: string }
+  | {
+      kind: 'relative';
+      direction: CtxDateRelativeDirection;
+      amount: number;
+      unit: CtxDateRelativeUnit;
+      format?: string;
+    }
+  | { kind: 'preset'; preset: CtxDatePreset; format?: string };
+
+const PRESET_KEYS = new Set<string>(PRESET_KEY_LIST);
 
 const RELATIVE_DIRECTIONS = new Set(['next', 'past']);
 const RELATIVE_UNITS = new Set(['day', 'week', 'month', 'year']);
+const MAX_DATE_FORMAT_LENGTH = 128;
 
 function parseCtxDateSegments(value: string): string[] | null {
   if (typeof value !== 'string') return null;
@@ -46,8 +64,7 @@ function parseCtxDateSegments(value: string): string[] | null {
     .filter(Boolean);
 }
 
-export function isCtxDatePathPrefix(pathSegments: string[]): boolean {
-  const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+function isBaseCtxDatePathPrefix(segments: string[]): boolean {
   if (segments[0] !== 'date') return false;
   if (segments.length === 1) return true;
 
@@ -96,6 +113,36 @@ export function isCtxDatePathPrefix(pathSegments: string[]): boolean {
   return false;
 }
 
+function decodeFormatToken(token: string): string | undefined {
+  const raw = String(token || '');
+  if (!raw.startsWith('v')) return undefined;
+  const decoded = decodeBase64Url(raw.slice(1));
+  if (!decoded || decoded.length > MAX_DATE_FORMAT_LENGTH) return undefined;
+  return decoded;
+}
+
+function splitFormattedDateSegments(segments: string[]): { baseSegments: string[]; format?: string } | null {
+  if (segments[0] !== 'date') return null;
+  if (segments[1] !== 'format') return { baseSegments: segments };
+  if (segments.length < 4) return null;
+
+  const format = decodeFormatToken(segments[2]);
+  if (!format) return null;
+  return { baseSegments: ['date', ...segments.slice(3)], format };
+}
+
+export function isCtxDatePathPrefix(pathSegments: string[]): boolean {
+  const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+  if (segments[0] !== 'date') return false;
+  if (segments.length === 1) return true;
+  if (segments[1] !== 'format') return isBaseCtxDatePathPrefix(segments);
+  if (segments.length === 2) return true;
+  if (segments.length === 3) return typeof decodeFormatToken(segments[2]) === 'string';
+
+  const formatted = splitFormattedDateSegments(segments);
+  return formatted ? isBaseCtxDatePathPrefix(formatted.baseSegments) : false;
+}
+
 function withDatePrefix(pathSegments: string[]): string[] {
   if (pathSegments[0] === 'date') {
     return pathSegments;
@@ -210,27 +257,29 @@ export function isCtxDateExpression(value: unknown): value is string {
 export function isCompleteCtxDatePath(pathSegments: string[]): boolean {
   if (!isCtxDatePathPrefix(pathSegments)) return false;
   const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
-  if (segments[0] !== 'date') return false;
+  const formatted = splitFormattedDateSegments(segments);
+  if (!formatted) return false;
+  const baseSegments = formatted.baseSegments;
 
-  if (segments[1] === 'preset') {
-    return segments.length === 3 && PRESET_KEYS.has(segments[2]);
+  if (baseSegments[1] === 'preset') {
+    return baseSegments.length === 3 && PRESET_KEYS.has(baseSegments[2]);
   }
 
-  if (segments[1] === 'relative') {
-    if (segments.length !== 5) return false;
+  if (baseSegments[1] === 'relative') {
+    if (baseSegments.length !== 5) return false;
     return (
-      RELATIVE_DIRECTIONS.has(segments[2]) &&
-      RELATIVE_UNITS.has(segments[3]) &&
-      typeof parseNumberToken(segments[4]) === 'number'
+      RELATIVE_DIRECTIONS.has(baseSegments[2]) &&
+      RELATIVE_UNITS.has(baseSegments[3]) &&
+      typeof parseNumberToken(baseSegments[4]) === 'number'
     );
   }
 
-  if (segments[1] === 'exact' && segments[2] === 'single' && segments[3] === 'date') {
-    return segments.length === 5 && /^v.+/.test(segments[4]);
+  if (baseSegments[1] === 'exact' && baseSegments[2] === 'single' && baseSegments[3] === 'date') {
+    return baseSegments.length === 5 && /^v.+/.test(baseSegments[4]);
   }
 
-  if (segments[1] === 'exact' && segments[2] === 'range' && segments[3] === 'date') {
-    return segments.length === 6 && /^v.+/.test(segments[4]) && /^v.+/.test(segments[5]);
+  if (baseSegments[1] === 'exact' && baseSegments[2] === 'range' && baseSegments[3] === 'date') {
+    return baseSegments.length === 6 && /^v.+/.test(baseSegments[4]) && /^v.+/.test(baseSegments[5]);
   }
 
   return false;
@@ -238,7 +287,10 @@ export function isCompleteCtxDatePath(pathSegments: string[]): boolean {
 
 export function parseCtxDateExpression(value: unknown): any {
   if (!isCtxDateExpression(value)) return undefined;
-  const segments = withDatePrefix(parseCtxDateSegments(value as string) || []);
+  const rawSegments = withDatePrefix(parseCtxDateSegments(value as string) || []);
+  const formatted = splitFormattedDateSegments(rawSegments);
+  if (!formatted) return undefined;
+  const segments = formatted.baseSegments;
 
   if (segments[1] === 'preset' && segments.length === 3 && PRESET_KEYS.has(segments[2])) {
     return { type: segments[2] };
@@ -276,6 +328,66 @@ export function parseCtxDateExpression(value: unknown): any {
   return undefined;
 }
 
+export function parseCtxDateExpressionConfig(value: unknown): CtxDateExpressionConfig | undefined {
+  if (!isCtxDateExpression(value)) return undefined;
+  const segments = withDatePrefix(parseCtxDateSegments(value) || []);
+  const formatted = splitFormattedDateSegments(segments);
+  if (!formatted) return undefined;
+
+  const parsed = parseCtxDateExpression(value);
+  const formatConfig = formatted.format ? { format: formatted.format } : {};
+  if (typeof parsed === 'string') {
+    return { kind: 'exact', value: parsed, ...formatConfig };
+  }
+  if (Array.isArray(parsed) && parsed.length === 2 && typeof parsed[0] === 'string' && typeof parsed[1] === 'string') {
+    return { kind: 'exact', value: [parsed[0], parsed[1]], ...formatConfig };
+  }
+
+  if (!parsed || typeof parsed !== 'object') return undefined;
+  const typed = parsed as { type?: unknown; unit?: unknown; number?: unknown };
+  if (typed.type === 'past' || typed.type === 'next') {
+    if (typeof typed.unit !== 'string' || !RELATIVE_UNITS.has(typed.unit) || typeof typed.number !== 'number') {
+      return undefined;
+    }
+    return {
+      kind: 'relative',
+      direction: typed.type,
+      amount: typed.number,
+      unit: typed.unit as CtxDateRelativeUnit,
+      ...formatConfig,
+    };
+  }
+
+  if (typeof typed.type === 'string' && PRESET_KEYS.has(typed.type)) {
+    return { kind: 'preset', preset: typed.type as CtxDatePreset, ...formatConfig };
+  }
+  return undefined;
+}
+
+export function serializeCtxDateExpressionConfig(config: CtxDateExpressionConfig): string | undefined {
+  let legacyValue: unknown;
+
+  if (config.kind === 'preset') {
+    if (!PRESET_KEYS.has(config.preset)) return undefined;
+    legacyValue = { type: config.preset };
+  } else if (config.kind === 'relative') {
+    if (!RELATIVE_DIRECTIONS.has(config.direction) || !RELATIVE_UNITS.has(config.unit)) return undefined;
+    const amount = Math.floor(Number(config.amount));
+    if (!Number.isFinite(amount) || amount <= 0) return undefined;
+    legacyValue = { type: config.direction, unit: config.unit, number: amount };
+  } else {
+    legacyValue = config.value;
+  }
+
+  const expression = serializeCtxDateValue(legacyValue);
+  if (!expression || !config.format) return expression;
+
+  const format = String(config.format);
+  if (!format.trim() || format.length > MAX_DATE_FORMAT_LENGTH) return undefined;
+  const segments = withDatePrefix(parseCtxDateSegments(expression) || []);
+  return toCtxDateExpression(['date', 'format', `v${encodeBase64Url(format)}`, ...segments.slice(1)]);
+}
+
 export function serializeCtxDateValue(value: unknown): string | undefined {
   if (isCtxDateExpression(value)) {
     return String(value).trim();
@@ -327,8 +439,23 @@ export function serializeCtxDateValue(value: unknown): string | undefined {
   return undefined;
 }
 
+function formatResolvedDateValue(value: unknown, format: string): unknown {
+  const formatValue = (item: unknown) => {
+    if (typeof item !== 'string') return item;
+    const parsed = dayjs(item);
+    return parsed.isValid() ? parsed.format(format) : item;
+  };
+  return Array.isArray(value) ? value.map(formatValue) : formatValue(value);
+}
+
 export function resolveCtxDatePath(pathSegments: string[]): any {
-  const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+  const rawSegments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+  const formatted = splitFormattedDateSegments(rawSegments);
+  if (!formatted) return undefined;
+  if (formatted.format) {
+    return formatResolvedDateValue(resolveCtxDatePath(formatted.baseSegments), formatted.format);
+  }
+  const segments = formatted.baseSegments;
   if (segments[0] !== 'date') return undefined;
 
   if (segments[1] === 'preset' && segments.length === 3) {