@ssv/ngx.command

Command pattern - encapsulates actions with auto state tracking (isExecuting , canExecute ). Primary use: disable buttons during execution, show loading indicators.

Creating Commands

Use command() factory (requires injection context):

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

readonly isValid = signal(false); readonly saveCmd = command(() => this.save$(), this.isValid);

// Observable, function, boolean also supported readonly deleteCmd = command(() => this.delete$(), this.isValid$); readonly computeCmd = command( () => this.compute(), () => this.check(), ); readonly simpleCmd = command(() => this.action()); // No validation

Directive Usage

<!-- Basic --> <button [ssvCommand]="saveCmd">Save</button>

<!-- With loading UI --> <button [ssvCommand]="saveCmd">@if(saveCmd.$isExecuting()) { <mat-spinner diameter="20"></mat-spinner> } Save</button>

<!-- Custom CSS class --> <button [ssvCommand]="saveCmd" [ssvCommandOptions]="{executingCssClass: 'is-loading'}">Save</button>

Parameters

CRITICAL: Array args must be double-wrapped:

<!-- Single param --> <button [ssvCommand]="deleteCmd" [ssvCommandParams]="userId">Delete</button>

<!-- Multiple params --> <button [ssvCommand]="updateCmd" [ssvCommandParams]="[user, id, 'save']">Update</button>

<!-- Single ARRAY param - MUST double-wrap --> <button [ssvCommand]="bulkCmd" [ssvCommandParams]="[[items]]">Process</button>

Why: [items] spreads. Use [[items]] for single array arg.

Collections (Loops)

Isolated isExecuting per item:

@for (hero of heroes; track hero.id) { <button [ssvCommand]="{host: this, execute: removeHero$, params: [hero]}">Remove</button> }

removeHero$(hero: Hero) { return this.#http.delete(/api/heroes/${hero.id}); }

Form Integration

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

// NgForm readonly loginCmd = command(() => this.login$(), canExecuteFromNgForm(this.form()));

// Signal forms readonly saveCmd = command(() => this.save$(), canExecuteFromSignals({ valid: form.valid, dirty: form.dirty }));

State & Execution

cmd.$isExecuting(); // Signal<boolean> cmd.$canExecute(); // Signal<boolean> cmd.isExecuting; // boolean (deprecated - use signals) cmd.canExecute; // boolean (deprecated - use signals)

cmd.execute(); // Direct cmd.execute(arg1, arg2); // With params await cmd.execute(); // Returns Promise for async

Anti-Patterns

❌ Never use new Command()

• use command() factory ❌ [ssvCommandParams]="[items]" spreads - use [[items]]

❌ Sharing isExecuting in loops - use command creator {host, execute, params}

Common Patterns

// Computed validation readonly canSave = computed(() => this.isValid() && this.hasChanges()); readonly saveCmd = command(() => this.save$(), this.canSave);

// Error handling readonly saveCmd = command(() => this.#http.post('/api/save', data).pipe( catchError(err => { this.showError(err); return EMPTY; }) ) );

// Loading UI <button [ssvCommand]="saveCmd" [class.loading]="saveCmd.$isExecuting()"> @if (saveCmd.$isExecuting()) { <mat-spinner/> } @else { <mat-icon>save</mat-icon> } Save </button>

CommandInput Type

Simplify command input types in child components:

import type { CommandInput } from "@ssv/ngx.command";

// Single parameter readonly onSave = input.required<CommandInput<User>>();

// Multiple parameters readonly onUpdate = input.required<CommandInput<[user: User, id: number]>>();

// Instead of verbose: // readonly onSave = input.required<Command<(user: User) => unknown>>();

Global Config

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

provideSsvCommandOptions({ executingCssClass: "is-busy" });

Advanced

• references/advanced-patterns.md
• CommandRef, per-item canExecute, CommandInput helper

Library Ref: README | Examples | Tests