feat(command-flow): shorten handler register function names

Author: Char2sGu

packages/command-flow/process-flow/src/handler.ts

@@ -24,13 +24,67 @@ export interface ProcessHandler<P extends Process<any>> {
 }
 
 export enum ProcessSchedulingStrategy {
+  /**
+   * Processes are handled one after the other.
+   */
   Sequential,
+  /**
+   * Processes are handled all at the same time.
+   */
   Concurrent,
+  /**
+   * Processes are handled one at a time,
+   * but can be preempted by a new dispatch,
+   * i.e. the previous handling will be cancelled.
+   */
   Preemptive,
+  /**
+   * Processes are handled one at a time,
+   * ignoring any new dispatches until the current handling is completed.
+   */
   Blocking,
 }
 
-export function registerProcessHandler<Types extends Type<Process<any>>[]>(
+/**
+ * Register a `ProcessHandler` for some types of processes.
+ * 
+ * The value returned from the handler will be translated
+ * into a series of `ProcessEvent`s:
+ * - `ProcessStarted` when a matching process is dispatched
+ * - `ProcessCompleted` when the returned promise resolves
+ *    or the returned observable emits a value
+ * - `ProcessFailed` when the returned promise rejects
+ *    or the returned observable emits an error
+ * 
+ * @param types array of process types to listen for
+ * @param scheduling strategy for handling multiple dispatches
+ * @remarks Requires an injection context.
+ *
+ * @example
+ *  ```typescript
+ *  onProcess(
+ *    [SomeProcess, AnotherProcess],
+ *    ProcessSchedulingStrategy.Sequential,
+ *    async (process) => {
+ *      const result = await someLogic(process);
+ *      return result;
+ *    }
+ *  );
+ *  ```
+ * 
+ * @example
+ *  ```typescript
+ *  onProcess(
+ *    [SomeProcess, AnotherProcess],
+ *    ProcessSchedulingStrategy.Sequential,
+ *    (process) => {
+ *      const observable = someLogic(process);
+ *      return observable;
+ *    }
+ *  );
+ *  ```
+F */
+export function onProcess<Types extends Type<Process<any>>[]>(
   types: Types,
   scheduling: ProcessSchedulingStrategy,
   handler: ProcessHandler<InstanceType<Types[number]>>,
@@ -68,3 +122,8 @@ export function registerProcessHandler<Types extends Type<Process<any>>[]>(
     ),
   );
 }
+
+/**
+ * @deprecated Use `onProcess` instead.
+ */
+export const registerProcessHandler = onProcess;

packages/command-flow/query-flow/src/handler.ts

@@ -14,11 +14,37 @@ import {
 } from './events';
 import { QueryResultOf as ResultOf } from './shared';
 
+/**
+ * Handler for `Query`s that
+ * produces an observable of results for the accepted queries.
+ */
 export interface QueryHandler<Q extends Query<any>> {
   (query: Q): Observable<ResultOf<Q>>;
 }
 
-export function registerQueryHandler<Types extends Type<Query<any>>[]>(
+/**
+ * Register a `QueryHandler` for some types of queries.
+ *
+ * The observable returned from the handler will be translated
+ * into a series of `QueryEvent`s:
+ * - `QueryActivated` when a matching query is dispatched
+ * - `QueryResolved` when the returned observable emits a value
+ * - `QueryErrored` when the returned observable emits an error
+ * - `QueryInactivated` when the returned observable completes
+ *
+ * The observable returned from the handler will be unsubscribed
+ * when a `DisposeQuery` command is dispatched for the query.
+ *
+ * @remarks Requires an injection context.
+ *
+ * @example
+ *  ```typescript
+ *  onQuery([SomeQuery], (query) => {
+ *    return httpClient.get(...);
+ *  });
+ *  ```
+ */
+export function onQuery<Types extends Type<Query<any>>[]>(
   types: Types,
   handler: QueryHandler<InstanceType<Types[number]>>,
 ): void {
@@ -53,3 +79,8 @@ export function registerQueryHandler<Types extends Type<Query<any>>[]>(
     ),
   );
 }
+
+/**
+ * @deprecated Use `onQuery` instead.
+ */
+export const registerQueryHandler = onQuery;

packages/command-flow/src/handlers.ts

@@ -7,15 +7,62 @@ import { CommandBus, CommandEventBus } from './buses';
 import { Command, CommandEvent } from './core';
 import { CommandFlowScheduler } from './scheduler';
 
+/**
+ * Handler for `Command`s that
+ * consume commands and optionally produce events.
+ *
+ * It can be regarded as a RxJS operator that
+ * transforms a command into a `CommandEvent` or `void`.
+ * - when a `CommandEvent` is emitted, the event will be published
+ * - when a `void` is emitted, nothing will happen
+ *
+ * @example
+ * The built-in RxJS operator `map` is the simplest form of a command handler.
+ *  ```typescript
+ *  const handler: CommandHandler<SomeCommand> = map((command) => {
+ *    const event = new SomeCommandEvent(command);
+ *    return event;
+ *  });
+ *  ```
+ * `map` can also be used to return `void`:
+ *  ```typescript
+ *  const handler: CommandHandler<SomeCommand> = map((command) => {
+ *    console.log(command);
+ *  });
+ *  ```
+ *
+ * @example
+ * A more complex handler can be created using the `pipe` operator:
+ *  ```typescript
+ *  const handler: CommandHandler<SomeCommand> = pipe(
+ *   filter((command) => someCondition(command)),
+ *   map((command) => new SomeCommandEvent(command)),
+ *  );
+ *  ```
+ */
 export interface CommandHandler<C extends Command> {
   (stream: Observable<C>): Observable<void | CommandEvent<C>>;
 }
 
-export interface CommandEventHandler<E extends CommandEvent> {
-  (stream: Observable<E>): Observable<void | Command>;
-}
-
-export function registerCommandHandler<Types extends Type<Command>[]>(
+/**
+ * Register a `CommandHandler` for some types of commands.
+ * @param types array of command types to listen for
+ * @remarks Requires an injection context.
+ *
+ * @example
+ * ```typescript
+ *  onCommand([SomeCommand, AnotherCommand], map((command) => {
+ *   console.log(command);
+ *  }));
+ * ```
+ * @example
+ * ```typescript
+ *  onCommand([SomeCommand, AnotherCommand], map((command) => {
+ *   return new SomeEvent(command);
+ *  }));
+ * ```
+ */
+export function onCommand<Types extends Type<Command>[]>(
   types: Types,
   handler: CommandHandler<InstanceType<Types[number]>>,
 ): void {
@@ -33,7 +80,67 @@ export function registerCommandHandler<Types extends Type<Command>[]>(
     .subscribe();
 }
 
-export function registerCommandEventHandler<Types extends Type<CommandEvent>[]>(
+/**
+ * @deprecated Use `onCommand` instead.
+ */
+export const registerCommandHandler = onCommand;
+
+/**
+ * Handler for `CommandEvent`s that
+ * consume events and optionally produce new commands.
+ *
+ * It can be regarded as a RxJS operator that
+ * transforms a command event into a `Command` or `void`.
+ * - when a `Command` is emitted, the command will be dispatched
+ * - when a `void` is emitted, nothing will happen
+ *
+ * @example
+ * The built-in RxJS operator `map` is the simplest form of a command event handler.
+ *  ```typescript
+ *  const handler: CommandEventHandler<SomeCommandEvent> = map((event) => {
+ *    const command = new SomeCommand(event);
+ *    return command;
+ *  });
+ *  ```
+ * `map` can also be used to return `void`:
+ *  ```typescript
+ *  const handler: CommandEventHandler<SomeCommandEvent> = map((event) => {
+ *    console.log(event);
+ *  });
+ *  ```
+ *
+ * @example
+ * A more complex handler can be created using the `pipe` operator:
+ *  ```typescript
+ *  const handler: CommandEventHandler<SomeCommandEvent> = pipe(
+ *    filter((event) => someCondition(event)),
+ *    map((event) => new SomeCommand(event)),
+ *  );
+ *  ```
+ */
+export interface CommandEventHandler<E extends CommandEvent> {
+  (stream: Observable<E>): Observable<void | Command>;
+}
+
+/**
+ * Register a `CommandEventHandler` for some types of command events.
+ * @param types array of command event types to listen for
+ * @remarks Requires an injection context.
+ *
+ * @example
+ *  ```typescript
+ *  onEvent([SomeCommandEvent, AnotherCommandEvent], map((event) => {
+ *    console.log(event);
+ *  }));
+ *  ```
+ * @example
+ *  ```typescript
+ *  onEvent([SomeCommandEvent, AnotherCommandEvent], map((event) => {
+ *    return new SomeCommand(event);
+ *  }));
+ *  ```
+ */
+export function onEvent<Types extends Type<CommandEvent>[]>(
   types: Types,
   handler: CommandEventHandler<InstanceType<Types[number]>>,
 ): void {
@@ -50,3 +157,8 @@ export function registerCommandEventHandler<Types extends Type<CommandEvent>[]>(
     )
     .subscribe();
 }
+
+/**
+ * @deprecated Use `onEvent` instead.
+ */
+export const registerCommandEventHandler = onEvent;