feat(core): new command api syncableExecuteCommand (#4045)

packages/core/src/index.ts

@@ -88,6 +88,7 @@ export {
     type IMutationInfo,
     type IOperation,
     type IOperationInfo,
+    type ISyncableCommandExecutionOptions,
     NilCommand,
     sequenceExecute,
     sequenceExecuteAsync,

packages/core/src/services/command/command.service.ts

@@ -233,6 +233,18 @@ export interface ICommandService {
      * @param listener
      */
     beforeCommandExecuted(listener: CommandListener): IDisposable;
+    /**
+     * Execute a command with the given id and parameters syncable.
+     * @param id Identifier of the command.
+     * @param params Parameters of this execution.
+     * @param options Options of this execution.
+     * @returns The result of the execution. It is a boolean value by default which indicates the command is executed.
+     */
+    syncableExecuteCommand<P extends object = object, R = boolean, S extends boolean = false>(
+        id: string,
+        params?: P,
+        options?: IExecutionOptions & ISyncableCommandExecutionOptions<S>
+    ): S extends true ? R : Promise<R>;
 }
 
 class CommandRegistry {
@@ -272,6 +284,10 @@ class CommandRegistry {
 
 interface ICommandExecutionStackItem extends ICommandInfo { }
 
+export interface ISyncableCommandExecutionOptions<Sync extends boolean = boolean> {
+    sync?: Sync;
+}
+
 export const NilCommand: ICommand = {
     id: 'nil',
     type: CommandType.COMMAND,
@@ -431,6 +447,12 @@ export class CommandService extends Disposable implements ICommandService {
         }
     }
 
+    syncableExecuteCommand<P extends object = object, R = boolean, S extends boolean = false>(id: string, params?: P, options?: IExecutionOptions & ISyncableCommandExecutionOptions<S>): S extends true ? R : Promise<R> {
+        const sync = options?.sync || false;
+      // @ts-expect-error types
+        return sync ? this.syncExecuteCommand(id, params, options) : this.executeCommand<P, R>(id, params, options);
+    }
+
     private _pushCommandExecutionStack(stackItem: ICommandExecutionStackItem): IDisposable {
         this._commandExecutionStack.push(stackItem);
         return toDisposable(() => remove(this._commandExecutionStack, stackItem));

packages/sheets/src/facade/f-range.ts

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
-import type { CellValue, ICellData, IColorStyle, IObjectMatrixPrimitiveType, IRange, IStyleData, ITextDecoration, Nullable, Workbook, Worksheet } from '@univerjs/core';
-import type { ISetHorizontalTextAlignCommandParams, ISetStyleCommandParams, ISetTextWrapCommandParams, ISetVerticalTextAlignCommandParams, IStyleTypeValue } from '@univerjs/sheets';
+import type { CellValue, ICellData, IColorStyle, IObjectMatrixPrimitiveType, IRange, IStyleData, ISyncableCommandExecutionOptions, ITextDecoration, Nullable, Workbook, Worksheet } from '@univerjs/core';
+import type { ISetHorizontalTextAlignCommandParams, ISetRangeValuesCommandParams, ISetStyleCommandParams, ISetTextWrapCommandParams, ISetVerticalTextAlignCommandParams, IStyleTypeValue } from '@univerjs/sheets';
 import type { FHorizontalAlignment, FVerticalAlignment } from './utils';
 import { BooleanNumber, Dimension, FBase, ICommandService, Inject, Injector, Rectangle, WrapStrategy } from '@univerjs/core';
 import { FormulaDataModel } from '@univerjs/engine-formula';
@@ -309,21 +309,22 @@ export class FRange extends FBase {
      * Sets a different value for each cell in the range. The value can be a two-dimensional array or a standard range matrix (must match the dimensions of this range), consisting of numbers, strings, Boolean values or Composed of standard cell formats. If a value begins with `=`, it is interpreted as a formula.
      * @param value
      */
-    setValues(
+    setValues<S extends boolean = false>(
         value:
             | CellValue[][]
             | IObjectMatrixPrimitiveType<CellValue>
             | ICellData[][]
-            | IObjectMatrixPrimitiveType<ICellData>
-    ): Promise<boolean> {
+            | IObjectMatrixPrimitiveType<ICellData>,
+        options: ISyncableCommandExecutionOptions<S> = {}
+    ) {
+        const { sync } = options;
         const realValue = covertCellValues(value, this._range);
-
-        return this._commandService.executeCommand(SetRangeValuesCommand.id, {
+        return this._commandService.syncableExecuteCommand<ISetRangeValuesCommandParams, boolean, S>(SetRangeValuesCommand.id, {
             unitId: this._workbook.getUnitId(),
             subUnitId: this._worksheet.getSheetId(),
             range: this._range,
             value: realValue,
-        });
+        }, { sync });
     }
 
     /**