fix(core): make execute sync timeout configurable

Author: unadlib

packages/core/src/getRawState.ts

@@ -16,9 +16,24 @@ import type { Internal } from './internal';
 import { handleDraft } from './asyncClientStore';
 import { uuid } from './utils';
 
-const clientExecuteSyncTimeoutMs = 1500;
+const defaultClientExecuteSyncTimeoutMs = 1500;
 const transportErrorMarker = '__coactionTransportError__';
 
+const getClientExecuteSyncTimeoutMs = (
+  options: StoreOptions<any> | ClientStoreOptions<any>
+) => {
+  const timeout = (options as ClientStoreOptions<any>).executeSyncTimeoutMs;
+  if (typeof timeout === 'undefined') {
+    return defaultClientExecuteSyncTimeoutMs;
+  }
+  if (!Number.isFinite(timeout) || timeout < 0) {
+    throw new Error(
+      'executeSyncTimeoutMs must be a finite number greater than or equal to 0'
+    );
+  }
+  return timeout;
+};
+
 const isTransportErrorEnvelope = (
   value: unknown
 ): value is Record<string, unknown> & { message: string } => {
@@ -51,6 +66,7 @@ export const getRawState = <T extends CreateState>(
   initialState: any,
   options: StoreOptions<T> | ClientStoreOptions<T>
 ) => {
+  const clientExecuteSyncTimeoutMs = getClientExecuteSyncTimeoutMs(options);
   const rawState = {} as Record<string, any>;
   const handle = (_rawState: any, _initialState: any, sliceKey?: string) => {
     internal.mutableInstance = internal.toMutableRaw?.(_initialState);

packages/core/src/interface.ts

@@ -234,6 +234,16 @@ export interface ClientTransportOptions {
    * Prefer passing `clientTransport` or `worker`.
    */
   workerType?: 'WebWorkerClient' | 'SharedWorkerClient';
+  /**
+   * How long the client should wait for sequence catch-up before falling back
+   * to `fullSync`.
+   *
+   * Increase this when worker-side execution can complete before the matching
+   * incremental `update` message arrives under heavy load.
+   *
+   * @default 1500
+   */
+  executeSyncTimeoutMs?: number;
   /**
    * Inject a pre-built client transport.
    */

packages/core/test/getRawState.branch.test.ts

@@ -9,7 +9,8 @@ type ClientStoreContext = {
 };
 
 const createClientStoreContext = (
-  emitImpl: (...args: any[]) => Promise<any>
+  emitImpl: (...args: any[]) => Promise<any>,
+  options: Record<string, unknown> = {}
 ): ClientStoreContext => {
   const subscriptions = new Set<() => void>();
   const internal = {
@@ -41,7 +42,7 @@ const createClientStoreContext = (
         return step + 1;
       }
     },
-    {}
+    options
   );
   return {
     internal,
@@ -187,6 +188,41 @@ test('client action performs fullSync when sequence catch-up times out', async (
   }
 });
 
+test('client action uses custom executeSyncTimeoutMs before falling back to fullSync', async () => {
+  vi.useFakeTimers();
+  try {
+    const { store, internal, trigger } = createClientStoreContext(
+      async (event) => {
+        if (event === 'execute') {
+          return ['ok', 2];
+        }
+        if (event === 'fullSync') {
+          return {
+            state: JSON.stringify({
+              count: 9
+            }),
+            sequence: 2
+          };
+        }
+        throw new Error(`Unexpected event: ${String(event)}`);
+      },
+      {
+        executeSyncTimeoutMs: 5_000
+      }
+    );
+    internal.sequence = 0;
+    const pending = store.getState().increment(1);
+    await Promise.resolve();
+    await vi.advanceTimersByTimeAsync(1_600);
+    expect(store.transport.emit).not.toHaveBeenCalledWith('fullSync');
+    internal.sequence = 2;
+    trigger();
+    await expect(pending).resolves.toBe('ok');
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
 test('client action rejects when fullSync fallback fails', async () => {
   vi.useFakeTimers();
   try {
@@ -210,6 +246,16 @@ test('client action rejects when fullSync fallback fails', async () => {
   }
 });
 
+test('client action rejects invalid executeSyncTimeoutMs configuration', () => {
+  expect(() => {
+    createClientStoreContext(async () => ['ok', 0], {
+      executeSyncTimeoutMs: -1
+    });
+  }).toThrow(
+    'executeSyncTimeoutMs must be a finite number greater than or equal to 0'
+  );
+});
+
 test('client action rejects when fullSync payload is invalid', async () => {
   vi.useFakeTimers();
   try {

packages/core/test/types.test.ts

@@ -22,4 +22,7 @@ test('preserves deprecated public compatibility fields', () => {
   expectTypeOf<
     ClientStoreOptions<{ count: number }>['workerType']
   >().toEqualTypeOf<'SharedWorkerClient' | 'WebWorkerClient' | undefined>();
+  expectTypeOf<
+    ClientStoreOptions<{ count: number }>['executeSyncTimeoutMs']
+  >().toEqualTypeOf<number | undefined>();
 });