@ssv/ngx.command 0.0.0-PLACEHOLDER

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();
+		});
+	});
+});

package/src/command.ts

@@ -0,0 +1,170 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Observable, combineLatest, Subscription, Subject, BehaviorSubject, of, EMPTY } from "rxjs";
+import { tap, map, filter, switchMap, catchError, finalize, take } from "rxjs/operators";
+import { ICommand } from "./command.model";
+
+/**
+ * Command object used to encapsulate information which is needed to perform an action.
+ */
+export class Command implements ICommand {
+
+	/** Determines whether the command is currently executing, as a snapshot value. */
+	get isExecuting(): boolean {
+		return this._isExecuting;
+	}
+
+	/** Determines whether the command can execute or not, as a snapshot value. */
+	get canExecute(): boolean {
+		return this._canExecute;
+	}
+
+	/** Determines whether the command is currently executing, as an observable. */
+	get isExecuting$(): Observable<boolean> {
+		return this._isExecuting$.asObservable();
+	}
+
+	/** Determines whether to auto destroy when having 0 subscribers. */
+	autoDestroy = true;
+
+	/** Determines whether the command can execute or not, as an observable. */
+	readonly canExecute$: Observable<boolean>;
+
+	private _isExecuting$ = new BehaviorSubject<boolean>(false);
+	private _isExecuting = false;
+	private _canExecute = true;
+	private executionPipe$ = new Subject<unknown[] | undefined>();
+	private isExecuting$$ = Subscription.EMPTY;
+	private canExecute$$ = Subscription.EMPTY;
+	private executionPipe$$ = Subscription.EMPTY;
+	private subscribersCount = 0;
+
+	/**
+	 * Creates an instance of Command.
+	 *
+	 * @param execute Execute function to invoke - use `isAsync: true` when `Observable<any>`.
+	 * @param canExecute Observable which determines whether it can execute or not.
+	 * @param isAsync Indicates that the execute function is async e.g. Observable.
+	 */
+	constructor(
+		execute: (...args: unknown[]) => unknown,
+		canExecute$?: Observable<boolean>,
+		isAsync?: boolean,
+	) {
+		if (canExecute$) {
+			this.canExecute$ = combineLatest([
+				this._isExecuting$,
+				canExecute$
+			]).pipe(
+				map(([isExecuting, canExecuteResult]) => {
+					// console.log("[command::combineLatest$] update!", { isExecuting, canExecuteResult });
+					this._isExecuting = isExecuting;
+					this._canExecute = !isExecuting && !!canExecuteResult;
+					return this._canExecute;
+				}),
+			);
+			this.canExecute$$ = this.canExecute$.subscribe();
+		} else {
+			this.canExecute$ = this._isExecuting$.pipe(
+				map(x => {
+					const canExecute = !x;
+					this._canExecute = canExecute;
+					return canExecute;
+				})
+			);
+			this.isExecuting$$ = this._isExecuting$
+				.pipe(tap(x => this._isExecuting = x))
+				.subscribe();
+		}
+		this.executionPipe$$ = this.buildExecutionPipe(execute, isAsync).subscribe();
+	}
+
+	/** Execute function to invoke. */
+	execute(...args: unknown[]): void {
+		// console.warn("[command::execute]", args);
+		this.executionPipe$.next(args);
+	}
+
+	/** Disposes all resources held by subscriptions. */
+	destroy(): void {
+		// console.warn("[command::destroy]");
+		this.executionPipe$$.unsubscribe();
+		this.canExecute$$.unsubscribe();
+		this.isExecuting$$.unsubscribe();
+	}
+
+	subscribe(): void {
+		this.subscribersCount++;
+	}
+
+	unsubscribe(): void {
+		this.subscribersCount--;
+		// console.log("[command::unsubscribe]", { autoDestroy: this.autoDestroy, subscribersCount: this.subscribersCount });
+		if (this.autoDestroy && this.subscribersCount <= 0) {
+			this.destroy();
+		}
+	}
+
+	private buildExecutionPipe(execute: (...args: unknown[]) => any, isAsync?: boolean): Observable<unknown> {
+		let pipe$ = this.executionPipe$.pipe(
+			// tap(x => console.warn(">>>> executionPipe", this._canExecute)),
+			filter(() => this._canExecute),
+			tap(() => {
+				// console.log("[command::executionPipe$] do#1 - set execute", { args: x });
+				this._isExecuting$.next(true);
+			})
+		);
+
+		const execFn = isAsync
+			? switchMap<unknown[] | undefined, any[]>(args => {
+				if (args) {
+					return execute(...args);
+				}
+				return execute();
+			})
+			: tap((args: unknown[] | undefined) => {
+				if (args) {
+					execute(...args);
+					return;
+				}
+				execute();
+			});
+
+		pipe$ = pipe$.pipe(
+			switchMap(args => of(args).pipe(
+				execFn,
+				finalize(() => {
+					// console.log("[command::executionPipe$]  finalize inner#1 - set idle");
+					this._isExecuting$.next(false);
+				}),
+				take(1),
+				catchError(error => {
+					console.error("Unhandled execute error", error);
+					return EMPTY;
+				}),
+			)),
+			tap(
+				() => {
+					// console.log("[command::executionPipe$] tap#2 - set idle");
+					this._isExecuting$.next(false);
+				},
+			)
+		);
+		return pipe$;
+	}
+
+}
+
+/**
+ * Async Command object used to encapsulate information which is needed to perform an action,
+ * which takes an execute function as Observable/Promise.
+ */
+export class CommandAsync extends Command {
+
+	constructor(
+		execute: (...args: any[]) => Observable<unknown> | Promise<unknown>,
+		canExecute$?: Observable<boolean>,
+	) {
+		super(execute, canExecute$, true);
+	}
+
+}

package/src/command.util.ts

@@ -0,0 +1,50 @@
+import { AbstractControl, AbstractControlDirective, FormControlStatus } from "@angular/forms";
+import { Observable, of } from "rxjs";
+import { map, distinctUntilChanged, startWith, delay } from "rxjs/operators";
+
+import { CommandCreator, ICommand } from "./command.model";
+import { Command } from "./command";
+
+/** Determines whether the arg object is of type `Command`. */
+export function isCommand(arg: unknown): arg is ICommand {
+	return arg instanceof Command;
+}
+
+/** Determines whether the arg object is of type `CommandCreator`. */
+export function isCommandCreator(arg: unknown): arg is CommandCreator {
+	if (arg instanceof Command) {
+		return false;
+	} else if (isAssumedType<CommandCreator>(arg) && arg.execute && arg.host) {
+		return true;
+	}
+	return false;
+}
+
+export interface CanExecuteFormOptions {
+	/** Determines whether to check for validity. (defaults: true) */
+	validity?: boolean;
+
+	/** Determines whether to check whether UI has been touched. (defaults: true) */
+	dirty?: boolean;
+}
+
+/** Get form is valid as an observable. */
+export function canExecuteFromNgForm(
+	form: AbstractControl | AbstractControlDirective,
+	options?: CanExecuteFormOptions
+): Observable<boolean> {
+	const opts: CanExecuteFormOptions = { validity: true, dirty: true, ...options };
+
+	return form.statusChanges
+		? (form.statusChanges as Observable<FormControlStatus>).pipe( // todo: remove cast when working correctly
+			delay(0),
+			startWith(form.valid),
+			map(() => !!(!opts.validity || form.valid) && !!(!opts.dirty || form.dirty)),
+			distinctUntilChanged(),
+		)
+		: of(true);
+}
+
+function isAssumedType<T = Record<string, unknown>>(x: unknown): x is Partial<T> {
+	return x !== null && typeof x === "object";
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./command";
+export * from "./command.directive";
+export * from "./command-ref.directive";
+export * from "./command.util";
+export { CommandCreator, ICommand } from "./command.model";
+export * from "./command.options";
+export * from "./module";
+export * from "./version";

package/src/module.ts

@@ -0,0 +1,17 @@
+import { NgModule } from "@angular/core";
+
+import { CommandDirective } from "./command.directive";
+import { CommandRefDirective } from "./command-ref.directive";
+
+const EXPORTED_IMPORTS = [
+	CommandDirective,
+	CommandRefDirective
+];
+
+@NgModule({
+	imports: [EXPORTED_IMPORTS],
+	exports: [EXPORTED_IMPORTS]
+})
+export class SsvCommandModule {
+
+}

package/src/test-setup.ts

@@ -0,0 +1,8 @@
+// @ts-expect-error https://thymikee.github.io/jest-preset-angular/docs/getting-started/test-environment
+globalThis.ngJest = {
+  testEnvironmentOptions: {
+    errorOnUnknownElements: true,
+    errorOnUnknownProperties: true,
+  },
+};
+import 'jest-preset-angular/setup-jest';

package/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = "0.0.0-PLACEHOLDER";

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ],
+  "extends": "../../tsconfig.base.json",
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true
+  }
+}