[npm]: https://www.npmjs.com
[commandpatternwiki]: https://en.wikipedia.org/wiki/Command_pattern

@ssv/ngx.command


[Command pattern][commandpatternwiki] implementation for angular. Command's are used to encapsulate information which is needed to perform an action.

Primary usage is to disable a button when an action is executing, or not in a valid state (e.g. busy, invalid), and also to show an activity progress while executing.

Installation

Get library via [npm]

``bash
npm install @ssv/ngx.command
`

Choose the version corresponding to your Angular version:

| library | Angular |
| ------- | ------- |
| 5.x+ | 17+ |
| 4.x+ | 17+ |
| 3.x+ | 17+ |
| 2.x+ | 10+ |
| 1.x+ | 4 to 9 |




Usage

Command


Create a new instance of Command

`ts
import { command } from "@ssv/ngx.command";

const isValid = signal(false);
const isValid$ = new BehaviorSubject(false);

// non async
saveCmd = command(() => this.save(), isValid);

// async - returns an observable/promise.
saveCmd = command(() => Observable.timer(2000), isValid);

// can execute diff ways
saveCmd = command(() => this.save(), () => isValid()); // reactive fn (signal)
saveCmd = command(() => this.save(), isValid); // signal
saveCmd = command(() => this.save(), isValid$); // rx
saveCmd = command(() => this.save(), false); // boolean (perma disabled)
`

Command Attribute (Directive)


Handles the command canExecute$, isExecuting and execute functions of the Command, in order to
enable/disable, add/remove a cssClass while executing in order alter styling during execution (if desired)
and execute when its enabled and clicked.

Generally used on a as below.

$3

`html



Save



@if(saveCmd.isExecuting) {

}
Save

`

#### Usage with params
This is useful for collections (loops) or using multiple actions with different args.
NOTE: This will share the isExecuting when used with multiple controls.

`html

Save



Save
`

#### Usage with command creator
This is useful for collections (loops) or using multiple actions with different args, whilst not sharing isExecuting.

`html
Remove
`

##### canExecute with params
`html
Remove
`

`ts
canRemoveHero$(hero: Hero, id: number, param2): Observable {
return of(id).pipe(
map(x => x === "invulnerable")
);
}
`

Usage without Attribute

It can also be used as below without the command attribute.

`html
[disabled]="!saveCmd.canExecute"
(click)="saveCmd.execute()">
Save

`

CommandRef Attribute (directive)

Command creator ref, directive which allows creating Command in the template and associate it to a command (in order to share executions).

`html
@for (hero of heroes; track hero.key) {



}
`

Utils

$3

In order to use with NgForm easily, you can use the following utility method.
This will make canExecute respond to form.valid and for form.dirty - also can optionally disable validity or dirty.

`ts
import { command, canExecuteFromNgForm, canExecuteFromSignals } from "@ssv/ngx.command";

loginCmd = command(x => this.login(), canExecuteFromNgForm(this.form));

// options - disable dirty check
loginCmd = command(x => this.login(), canExecuteFromNgForm(this.form, {
dirty: false
}));

// similar functionality using custom signals (or form which provide signals)
loginCmd = command(x => this.login(), canExecuteFromSignals({dirty: $dirty, valid: $valid}));
`

$3

Simplifies the definition when used as an input.

`ts
// For a command with a single parameter:
readonly myCmd = input.required>();
// For a command with multiple parameters:
readonly myCmd = input.required>();

// instead of
readonly myCmd = input.required unknown>>();
`




Global options

`ts
import { provideSsvCommandOptions } from "@ssv/ngx.command";

export const appConfig: ApplicationConfig = {
providers: [
provideSsvCommandOptions({
executingCssClass: "is-busy",
}),
],
};
``