@ssv/ngx.command 2.3.2 → 3.0.0-dev.1

package/src/command-ref.directive.ts

@@ -0,0 +1,57 @@
+import { Observable } from "rxjs";
+import { Directive, OnInit, OnDestroy, Input } from "@angular/core";
+
+import { ICommand, CommandCreator } from "./command.model";
+import { isCommandCreator } from "./command.util";
+import { Command } from "./command";
+
+const NAME_CAMEL = "ssvCommandRef";
+
+/**
+ * Command creator ref, directive which allows creating Command in the template
+ * and associate it to a command (in order to share executions).
+ * @example
+ * ### Most common usage
+ * ```html
+ * <div #actionCmd="ssvCommandRef" [ssvCommandRef]="{host: this, execute: removeHero$, canExecute: isValid$}">
+ *    <button [ssvCommand]="actionCmd.command" [ssvCommandParams]="hero">
+ *      Remove
+ *    </button>
+ *    <button [ssvCommand]="actionCmd.command" [ssvCommandParams]="hero">
+ *       Remove
+ *    </button>
+ * </div>
+ * ```
+ *
+ */
+@Directive({
+	selector: `[${NAME_CAMEL}]`,
+	exportAs: NAME_CAMEL,
+	standalone: true,
+})
+export class CommandRefDirective implements OnInit, OnDestroy {
+
+	@Input(NAME_CAMEL) commandCreator: CommandCreator | undefined;
+
+	get command(): ICommand { return this._command; }
+	private _command!: ICommand;
+
+	ngOnInit(): void {
+		if (isCommandCreator(this.commandCreator)) {
+			const isAsync = this.commandCreator.isAsync || this.commandCreator.isAsync === undefined;
+
+			const execFn = this.commandCreator.execute.bind(this.commandCreator.host);
+			this._command = new Command(execFn, this.commandCreator.canExecute as Observable<boolean> | undefined, isAsync);
+		} else {
+			throw new Error(`${NAME_CAMEL}: [${NAME_CAMEL}] is not defined properly!`);
+		}
+	}
+
+	ngOnDestroy(): void {
+		// console.log("[commandRef::destroy]");
+		if (this._command) {
+			this._command.destroy();
+		}
+	}
+
+}

package/src/command.directive.ts

@@ -0,0 +1,192 @@
+import {
+	Directive,
+	OnInit,
+	OnDestroy,
+	Input,
+	HostListener,
+	ElementRef,
+	Renderer2,
+	ChangeDetectorRef,
+	inject,
+} from "@angular/core";
+import { Subject } from "rxjs";
+import { tap, delay, takeUntil } from "rxjs/operators";
+
+import { CommandOptions, COMMAND_OPTIONS } from "./command.options";
+import { Command } from "./command";
+import { isCommand, isCommandCreator } from "./command.util";
+import { CommandCreator, ICommand } from "./command.model";
+
+/**
+ * Controls the state of a component in sync with `Command`.
+ *
+ * @example
+ * ### Most common usage
+ * ```html
+ * <button [ssvCommand]="saveCmd">Save</button>
+ * ```
+ *
+ *
+ * ### Usage with options
+ * ```html
+ * <button [ssvCommand]="saveCmd" [ssvCommandOptions]="{executingCssClass: 'in-progress'}">Save</button>
+ * ```
+ *
+ *
+ * ### 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.*
+ *
+ * #### With single param
+ *
+ * ```html
+ * <button [ssvCommand]="saveCmd" [ssvCommandParams]="{id: 1}">Save</button>
+ * ```
+ * *NOTE: if you have only 1 argument as an array, it should be enclosed within an array e.g. `[['apple', 'banana']]`,
+ * else it will spread and you will `arg1: "apple", arg2: "banana"`*
+ *
+	* #### With multi params
+ * ```html
+ * <button [ssvCommand]="saveCmd" [ssvCommandParams]="[{id: 1}, 'hello', hero]">Save</button>
+ * ```
+ *
+ * ### Usage with Command Creator
+ * This is useful for collections (loops) or using multiple actions with different args, whilst not sharing `isExecuting`.
+ *
+ *
+ * ```html
+ * <button [ssvCommand]="{host: this, execute: removeHero$, canExecute: isValid$, params: [hero, 1337, 'xx']}">Save</button>
+ * ```
+ *
+ */
+
+const NAME_CAMEL = "ssvCommand";
+
+// let nextUniqueId = 0;
+
+@Directive({
+	selector: `[${NAME_CAMEL}]`,
+	exportAs: NAME_CAMEL,
+	standalone: true,
+})
+export class CommandDirective implements OnInit, OnDestroy {
+
+	// readonly id = `${NAME_CAMEL}-${nextUniqueId++}`;
+	private readonly globalOptions = inject(COMMAND_OPTIONS);
+	private readonly renderer = inject(Renderer2);
+	private readonly element = inject(ElementRef);
+	private readonly cdr = inject(ChangeDetectorRef);
+
+
+	@Input(NAME_CAMEL) commandOrCreator: ICommand | CommandCreator | undefined;
+
+	@Input(`${NAME_CAMEL}Options`)
+	get commandOptions(): CommandOptions { return this._commandOptions; }
+	set commandOptions(value: Partial<CommandOptions>) {
+		if (value === this._commandOptions) {
+			return;
+		}
+		this._commandOptions = {
+			...this.globalOptions,
+			...value,
+		};
+	}
+
+	@Input(`${NAME_CAMEL}Params`) commandParams: unknown | unknown[];
+
+	get command(): ICommand { return this._command; }
+
+	private _command!: ICommand;
+	private _commandOptions: CommandOptions = this.globalOptions;
+	private _destroy$ = new Subject<void>();
+
+	ngOnInit(): void {
+		// console.log("[ssvCommand::init]", this.config);
+		if (!this.commandOrCreator) {
+			throw new Error(`${NAME_CAMEL}: [${NAME_CAMEL}] should be defined!`);
+		} else if (isCommand(this.commandOrCreator)) {
+			this._command = this.commandOrCreator;
+		} else if (isCommandCreator(this.commandOrCreator)) {
+			const isAsync = this.commandOrCreator.isAsync || this.commandOrCreator.isAsync === undefined;
+
+			// todo: find something like this for ivy (or angular10+)
+			// const hostComponent = (this.viewContainer as any)._view.component;
+
+			const execFn = this.commandOrCreator.execute.bind(this.commandOrCreator.host);
+			this.commandParams = this.commandParams || this.commandOrCreator.params;
+
+			const canExec = this.commandOrCreator.canExecute instanceof Function
+				? this.commandOrCreator.canExecute.bind(this.commandOrCreator.host, this.commandParams)()
+				: this.commandOrCreator.canExecute;
+
+			// console.log("[ssvCommand::init] command creator", {
+			// 	firstParam: this.commandParams ? this.commandParams[0] : null,
+			// 	params: this.commandParams
+			// });
+			this._command = new Command(execFn, canExec, isAsync);
+		} else {
+			throw new Error(`${NAME_CAMEL}: [${NAME_CAMEL}] is not defined properly!`);
+		}
+
+		this._command.subscribe();
+		this._command.canExecute$.pipe(
+			this.commandOptions.hasDisabledDelay
+				? delay(1)
+				: tap(() => { /* stub */ }),
+			tap(x => {
+				this.trySetDisabled(!x);
+				// console.log("[ssvCommand::canExecute$]", { canExecute: x });
+				this.cdr.markForCheck();
+			}),
+			takeUntil(this._destroy$),
+		).subscribe();
+
+		if (this._command.isExecuting$) {
+			this._command.isExecuting$.pipe(
+				tap(x => {
+					// console.log("[ssvCommand::isExecuting$]", x, this.commandOptions);
+					if (x) {
+						this.renderer.addClass(
+							this.element.nativeElement,
+							this.commandOptions.executingCssClass
+						);
+					} else {
+						this.renderer.removeClass(
+							this.element.nativeElement,
+							this.commandOptions.executingCssClass
+						);
+					}
+				}),
+				takeUntil(this._destroy$),
+			).subscribe();
+		}
+	}
+
+	@HostListener("click")
+	onClick(): void {
+		// console.log("[ssvCommand::onClick]", this.commandParams);
+		if (Array.isArray(this.commandParams)) {
+			this._command.execute(...this.commandParams);
+		} else {
+			this._command.execute(this.commandParams);
+		}
+	}
+
+	ngOnDestroy(): void {
+		// console.log("[ssvCommand::destroy]");
+		this._destroy$.next();
+		this._destroy$.complete();
+		if (this._command) {
+			this._command.unsubscribe();
+		}
+	}
+
+	private trySetDisabled(disabled: boolean) {
+		if (this.commandOptions.handleDisabled) {
+			// console.warn(">>>> disabled", { id: this.id, disabled });
+			this.renderer.setProperty(this.element.nativeElement, "disabled", disabled);
+		}
+	}
+
+}
+

package/src/command.directive.xspec.ts

@@ -0,0 +1,105 @@
+// import {Observable} from "rxjs/Observable";
+// import {inject, addProviders, async} from "@angular/core/testing";
+// import {TestComponentBuilder, ComponentFixture} from "@angular/compiler/testing";
+// import {Component, provide} from "@angular/core";
+
+// import {Command, ICommand, CommandDirective} from "./index";
+
+// @Component({
+// 	template: `<button class="btn" [ssvCommand]="saveCmd" >Save</button>`,
+// 	directives: [
+// 		CommandDirective
+// 	]
+// })
+// class TestContainer {
+// 	saveCmd = new Command(() => Observable.of("yey").delay(2000), null, true);
+// }
+
+// @Component({
+// 	template: `<button class="btn" [ssvCommand]="emptyCmd" >Save</button>`,
+// 	directives: [
+// 		CommandDirective
+// 	]
+// })
+// class NullCommandTestContainer {
+
+// }
+
+// describe("CommandDirectiveSpecs", () => {
+
+// 	let testComponentBuilder: TestComponentBuilder;
+
+// 	beforeEach(inject([
+// 		TestComponentBuilder
+// 	], (
+// 		_testComponentBuilder: TestComponentBuilder
+// 	) => {
+// 			testComponentBuilder = _testComponentBuilder;
+// 		})
+// 	);
+
+// 	describe("given an undefined command", () => {
+// 		xit("should throw error", async(() => {
+// 			testComponentBuilder
+// 				.createAsync(NullCommandTestContainer)
+// 				.then((fixture: ComponentFixture<NullCommandTestContainer>) => {
+// 					expect(() => {
+// 						fixture.detectChanges();
+// 					}).toThrowError("[commandDirective] command should be defined!");
+// 				});
+
+// 		}));
+// 	});
+
+// 	describe("given command isExecuting is set to true", () => {
+// 		xit("should have element disabled", async(() => {
+// 			testComponentBuilder
+// 				.createAsync(TestContainer)
+// 				.then((fixture: ComponentFixture<TestContainer>) => {
+// 					fixture.detectChanges();
+// 					let container = fixture.componentInstance as TestContainer;
+// 					let element = fixture.debugElement.nativeElement.querySelector("button");
+// 					element.click();
+// 					fixture.detectChanges();
+// 					expect(element).toBeDisabled();
+// 				});
+// 		}));
+
+// 		xit("should have executingCssClass added", () => {
+
+// 		});
+
+// 		xdescribe("when isExecuting has been finished", () => {
+// 			xit("should have element enabled", () => {
+
+// 			});
+
+// 			xit("should have executingCssClass removed", () => {
+
+// 			});
+// 		});
+// 	});
+
+// 	xdescribe("given command canExecute is set to true", () => {
+// 		xit("should have element enabled", () => {
+
+// 		});
+// 	});
+
+// 	xdescribe("given command canExecute is set to false", () => {
+// 		xit("should have element disabled", () => {
+
+// 		});
+// 	});
+
+// 	xdescribe("given commandOptions are provided", () => {
+// 		xdescribe("when isExecuting is set true", () => {
+// 			xit("should have executingCssClass added with the provided option", () => {
+
+// 			});
+// 		});
+
+// 	});
+
+
+// });

package/src/command.model.ts

@@ -0,0 +1,36 @@
+import { Observable } from "rxjs";
+
+export interface ICommand {
+	/** Determines whether the command is currently executing, as a snapshot value. */
+	readonly isExecuting: boolean;
+	/** Determines whether the command is currently executing, as an observable. */
+	readonly isExecuting$: Observable<boolean>;
+	/** Determines whether the command can execute or not, as a snapshot value. */
+	readonly canExecute: boolean;
+	/** Determines whether the command can execute or not, as an observable. */
+	readonly canExecute$: Observable<boolean>;
+
+	/** Determines whether to auto destroy when having 0 subscribers (defaults to `true`). */
+	autoDestroy: boolean;
+
+	/** Execute function to invoke. */
+	execute(...args: unknown[]): void;
+
+	/** Disposes all resources held by subscriptions. */
+	destroy(): void;
+
+	/** Subscribe listener, in order to handle auto disposing. */
+	subscribe(): void;
+
+	/** Unsubscribe listener, in order to handle auto disposing. */
+	unsubscribe(): void;
+}
+
+export interface CommandCreator {
+	execute: (...args: unknown[]) => Observable<unknown> | Promise<unknown> | void;
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+	canExecute?: Observable<boolean> | Function;
+	params?: unknown | unknown[];
+	isAsync?: boolean;
+	host: unknown;
+}

package/src/command.options.ts

@@ -0,0 +1,45 @@
+import { EnvironmentProviders, InjectionToken, makeEnvironmentProviders } from "@angular/core";
+
+export interface CommandOptions {
+	/**
+	 * Css Class which gets added/removed on the Command element's host while Command `isExecuting$`.
+	 */
+	executingCssClass: string;
+
+	/** Determines whether the disabled will be handled by the directive or not.
+	 * Disable handled by directive's doesn't always play nice when used with other component/pipe/directive and they also handle disabled.
+	 * This disables the handling manually and need to pass explicitly `[disabled]="!saveCmd.canExecute"`.
+	 */
+	handleDisabled: boolean;
+
+	/** Determine whether to set a `delay(1)` when setting the disabled. Which might be needed when working with external
+	 * components/directives (such as material button)
+	 */
+	hasDisabledDelay: boolean;
+}
+
+const DEFAULT_OPTIONS = Object.freeze<CommandOptions>({
+	executingCssClass: "executing",
+	handleDisabled: true,
+	hasDisabledDelay: false,
+});
+
+export const COMMAND_OPTIONS = new InjectionToken<CommandOptions>("SSV_COMMAND_OPTIONS", {
+	factory: () => DEFAULT_OPTIONS,
+});
+
+export function provideSsvCommandOptions(options: CommandOptions | (() => CommandOptions)): EnvironmentProviders {
+	let opts = typeof options === "function" ? options() : options;
+	opts = opts
+		? {
+			...DEFAULT_OPTIONS,
+			...opts,
+		}
+		: DEFAULT_OPTIONS;
+	return makeEnvironmentProviders([
+		{
+			provide: DEFAULT_OPTIONS,
+			useValue: opts,
+		},
+	]);
+}

package/src/command.spec.ts

@@ -0,0 +1,215 @@
+import { BehaviorSubject, EMPTY } from "rxjs";
+
+import { Command } from "./command";
+
+describe("CommandSpecs", () => {
+	let SUT: Command;
+	let executeFn: jest.Mock<void, unknown[], unknown> ;
+	// let executeSpyFn: jest.SpyInstance<void, unknown[], unknown>;
+
+	beforeEach(() => {
+		executeFn = jest.fn();
+		// executeSpyFn = executeFn;
+	});
+
+	describe("given a command without canExecute$ param", () => {
+		beforeEach(() => {
+			SUT = new Command(executeFn);
+			// executeSpyFn = jest.spyOn(SUT, "execute");
+		});
+
+		describe("when command is initialized", () => {
+			it("should have canExecute set to true", () => {
+				expect(SUT.canExecute).toBe(true);
+			});
+
+			it("should have canExecute$ set to true", done => {
+				SUT.canExecute$.subscribe(x => {
+					expect(x).toBe(true);
+					done();
+				});
+			});
+		});
+
+		describe("when execute is invoked", () => {
+			beforeEach(() => {
+				SUT.execute();
+			});
+
+			it("should have isExecuting set to false after execute finishes", () => {
+				expect(SUT.isExecuting).toBe(false);
+			});
+
+			it("should have canExecute set to true after execute finishes", () => {
+				expect(SUT.canExecute).toBe(true);
+			});
+
+			it("should invoke execute function", () => {
+				expect(executeFn).toHaveBeenCalledTimes(1);
+			});
+		});
+	});
+
+	describe("given execute is invoked", () => {
+		describe("when canExecute is true", () => {
+			beforeEach(() => {
+				const isInitialValid = true;
+				SUT = new Command(executeFn, new BehaviorSubject<boolean>(isInitialValid));
+			});
+
+			it("should invoke execute function passed", () => {
+				SUT.execute();
+				expect(executeFn).toHaveBeenCalledTimes(1);
+			});
+		});
+
+		describe("when observable completes", () => {
+			beforeEach(() => {
+				const isInitialValid = true;
+				executeFn = jest.fn().mockImplementation(() => EMPTY);
+				SUT = new Command(executeFn, new BehaviorSubject<boolean>(isInitialValid));
+			});
+
+			it("should invoke multiple times", () => {
+				SUT.execute();
+				SUT.execute();
+				expect(SUT.isExecuting).toBeFalsy();
+				expect(executeFn).toHaveBeenCalledTimes(2);
+			});
+		});
+
+		describe("when an error is thrown", () => {
+			const _errorFn = console.error;
+			beforeAll(() => {
+				console.error = jest.fn();
+			});
+
+			beforeEach(() => {
+				const isInitialValid = true;
+				executeFn = jest.fn().mockImplementation(() => {
+					throw new Error("Execution failed!");
+				});
+				SUT = new Command(executeFn, new BehaviorSubject<boolean>(isInitialValid));
+			});
+
+			it("should invoke multiple times", () => {
+				SUT.execute();
+				SUT.execute();
+				expect(SUT.isExecuting).toBeFalsy();
+				expect(executeFn).toHaveBeenCalledTimes(2);
+			});
+
+			afterAll(() => {
+				console.error = _errorFn;
+			});
+		});
+
+		describe("when args are passed", () => {
+			beforeEach(() => {
+				const isInitialValid = true;
+				SUT = new Command(executeFn, new BehaviorSubject<boolean>(isInitialValid));
+			});
+
+			it("and has 1 param should receive 1 arg", () => {
+				const args = { name: "rexxar" };
+				SUT.execute(args);
+				expect(executeFn).toHaveBeenCalledTimes(1);
+				expect(executeFn).toHaveBeenCalledWith(args);
+			});
+
+			it("and is array param should not spread", () => {
+				const hero = { name: "rexxar" };
+				const args = [hero, "yello"];
+				SUT.execute(args);
+				expect(executeFn).toHaveBeenCalledTimes(1);
+				expect(executeFn).toHaveBeenCalledWith([hero, "yello"]);
+			});
+
+			it("and multi args are pass should receive all", () => {
+				const hero = { name: "rexxar" };
+				SUT.execute(hero, "yello");
+				expect(executeFn).toHaveBeenCalledTimes(1);
+				expect(executeFn).toHaveBeenCalledWith(hero, "yello");
+			});
+		});
+
+		describe("when canExecute is false", () => {
+			beforeEach(() => {
+				const isInitialValid = false;
+				SUT = new Command(executeFn, new BehaviorSubject<boolean>(isInitialValid));
+			});
+
+			it("should not execute the provided execute function", () => {
+				SUT.execute();
+				expect(executeFn).not.toHaveBeenCalled();
+			});
+		});
+	});
+
+	describe("given canExecute with an initial value of true", () => {
+		let canExecute$: BehaviorSubject<boolean>;
+
+		beforeEach(() => {
+			const isInitialValid = true;
+			canExecute$ = new BehaviorSubject<boolean>(isInitialValid);
+			SUT = new Command(executeFn, canExecute$);
+		});
+
+		it("should have canExecute set to true", () => {
+			expect(SUT.canExecute).toBe(true);
+		});
+
+		it("should have canExecute$ set to true", done => {
+			SUT.canExecute$.subscribe(x => {
+				expect(x).toBe(true);
+				done();
+			});
+		});
+
+		describe("when the canExecute observable changes", () => {
+			beforeEach(() => {
+				canExecute$.next(false);
+			});
+
+			it("should update canExecute", () => {
+				expect(SUT.canExecute).toBe(false);
+			});
+
+			it("should update canExecute$", done => {
+				SUT.canExecute$.subscribe(x => {
+					expect(x).toBe(false);
+					done();
+				});
+			});
+		});
+	});
+
+	describe("given canExecute with an initial value of false", () => {
+		beforeEach(() => {
+			const isInitialValid = false;
+			SUT = new Command(executeFn, new BehaviorSubject<boolean>(isInitialValid));
+		});
+
+		it("should have canExecute set to false", () => {
+			expect(SUT.canExecute).toBe(false);
+		});
+
+		it("should have canExecute$ set to false", done => {
+			SUT.canExecute$.subscribe(x => {
+				expect(x).toBe(false);
+				done();
+			});
+		});
+	});
+
+	describe("given destroy is invoked", () => {
+		beforeEach(() => {
+			const isInitialValid = false;
+			SUT = new Command(executeFn, new BehaviorSubject<boolean>(isInitialValid));
+		});
+
+		it("should destroy successfully", () => {
+			SUT.destroy();
+		});
+	});
+});