/**
* Copyright 2023-present DreamNum Co., Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import type { IAccessor, IDisposable } from '../../common/di';
import { findLast, remove } from '../../common/array';
import { createIdentifier, Inject, Injector } from '../../common/di';
import { CustomCommandExecutionError } from '../../common/error';
import { sequence, sequenceAsync } from '../../common/sequence';
import { Disposable, DisposableCollection, toDisposable } from '../../shared/lifecycle';
import { IConfigService } from '../config/config.service';
import { IContextService } from '../context/context.service';
import { ILogService } from '../log/log.service';
/**
* The config key for enabling command execution logging.
* Set via `logCommandExecution` in `IUniverConfig` when calling `new Univer()`.
* @default true
*/
export const COMMAND_LOG_EXECUTION_CONFIG_KEY = 'command.logExecution';
/**
* The type of a command.
*/
export enum CommandType {
/**
* Responsible for creating, orchestrating, and executing MUTATION or OPERATION according to specific business
* logic. For example, a delete row COMMAND will generate a delete row MUTATION, an insert row MUTATION for undo,
* and a set cell content MUTATION.
*/
COMMAND = 0,
/**
* OPERATION is the change made to data that is not saved to snapshot, without conflict resolution,
* such as modifying scroll position, modifying sidebar state, etc.
*/
OPERATION = 1,
/**
* MUTATION is the change made to the data saved to snapshot, such as inserting rows and columns,
* modifying cell content, modifying filter ranges, etc. If you want to add collaborative editing capabilities to
* Univer, it is the smallest unit of conflict resolution.
*/
MUTATION = 2,
}
/**
* In Univer, all data modifications need to be executed through commands. The command-based approach can better track
* changes in values, implement functions such as undo, redo, and collaborative editing, handle complex associated
* logic between functions, etc.
*
* All commands should implements this interface or related {@link IMutation} or {@link IOperation} interface, and
* should be registered in the {@link ICommandService}.
*/
export interface ICommand
{
/**
* Identifier of the command. It should be unique in the application unless it is a {@link IMultiCommand}.
* Its pattern should be like `..`.
*
* @example { id: 'sheet.command.set-selection-frozen' }
*/
readonly id: string;
/**
* The type of the command.
*/
readonly type: CommandType;
/**
* The handler of the command.
* @param accessor The accessor to the dependency injection container.
* @param params Params of the command. Params should be serializable.
* @param options Options of the command.
* @returns The result of the command. By default it should be a boolean value which indicates the command is
* executed successfully or not.
*/
handler(accessor: IAccessor, params?: P, options?: IExecutionOptions): Promise | R;
}
/**
* A command that may have multiple implementations. Each implementation should have different `priority`
* and `preconditions` callback to determine which implementation should be executed.
*/
export interface IMultiCommand
extends ICommand
{
/** The name of the multi command. It should be unique in the application. */
name: string;
/** @ignore */
multi: true;
/** Priority of this implementation. Implementation with higher priority will be checked first. */
priority: number;
/**
* A callback function that tells `ICommandService` if this implementation should be executed.
* @param contextService The context service.
* @returns If this implementation should be executed, return `true`, otherwise return `false`.
*/
preconditions?: (contextService: IContextService) => boolean;
}
export interface IMutationCommonParams {
/**
* It is used to indicate which {@link CommandType.COMMAND} or {@link CommandType.OPERATION} triggers the mutation.
*/
trigger?: string;
/**
* Mark this mutation as a split chunk from a large mutation.
* When collaboration layer encounters this flag, it will send this mutation
* in a separate changeset to avoid oversized payloads.
*
* This is typically set by operations that split large data (e.g., copy worksheet,
* paste large ranges) into smaller chunks for better network transmission.
*/
__splitChunk__?: boolean;
}
/**
* {@link CommandType.MUTATION} should implement this interface.
*/
export interface IMutation
extends ICommand
{
type: CommandType.MUTATION;
/**
* The handler of the mutation.
* @param accessor The accessor to the dependency injection container.
* @param params Params of the mutation. Params should be serializable.
* @returns The result of the mutation. By default it should be a boolean value which indicates the mutation is
* executed successfully or not.
*/
handler(accessor: IAccessor, params: P): R;
}
/**
* {@link CommandType.OPERATION} should implement this interface.
*/
export interface IOperation
extends ICommand
{
type: CommandType.OPERATION;
/**
* The handler of the operation.
* @param accessor The accessor to the dependency injection container.
* @param params Params of the operation. Params should be serializable.
* @returns The result of the operation. By default it should be a boolean value which indicates the operation is
* executed successfully or not.
*/
handler(accessor: IAccessor, params: P): R;
}
/**
* This object represents an execution of a command.
*/
export interface ICommandInfo {
/**
* Id of the command being executed.
*/
id: string;
/**
* Type of the command.
*/
type?: CommandType;
/**
* Parameters of this execution.
*/
params?: T;
}
/** This object represents an execution of a {@link CommandType.MUTATION} */
export interface IMutationInfo {
id: string;
type?: CommandType.MUTATION;
params: T;
}
/** This object represents an execution of a {@link CommandType.OPERATION} */
export interface IOperationInfo {
id: string;
type?: CommandType.OPERATION;
params: T;
}
export interface IExecutionOptions {
/** This mutation should only be executed on the local machine, and should not be synced to replicas. */
onlyLocal?: boolean;
/** This command is from collaboration peers. */
fromCollab?: boolean;
/** This command is from snapshot load. */
fromChangeset?: boolean;
/**
* This mutation should be synced to changeset but not executed locally.
* The actual execution will be handled asynchronously via onlyLocal.
*/
syncOnly?: boolean;
[key: PropertyKey]: string | number | boolean | undefined;
}
export type CommandListener = (commandInfo: Readonly, options?: IExecutionOptions) => void;
/**
* The identifier of the command service.
*/
export const ICommandService = createIdentifier('univer.core.command-service');
/**
* The service to register and execute commands.
*/
export interface ICommandService {
disposed(): boolean;
/**
* Check if a command is already registered at the current command service.
* @param commandId The id of the command.
* @returns If the command is registered, return `true`, otherwise return `false`.
*/
hasCommand(commandId: string): boolean;
/**
* Register a command to the command service.
* @param command The command to register.
*/
registerCommand(command: ICommand