{
  // jest config
  "testEnvironment": "node",
  "preset": "ts-jest",
  "testTimeout": 60000
}

About testcontainers

In case you're wondering what testcontainers are; it's a library that provides lightweight containers for your tests. It allows you to easily set up dependencies, so you can run your tests against in a "real" environment. You can E2E test a CRUD backend with a real database, or test against an actual message queue. It adds a lot of reliability since the dependencies are very close to the real deal, and it makes E2E/integration test set up a breeze.

Here's an example test using nestjs with drizzle as an ORM:

import { runMigrations } from '@db/migrate';
import { schema } from '@db/schema';
import { DrizzlePostgresModule } from '@knaadh/nestjs-drizzle-postgres';
import { INestApplication } from '@nestjs/common';
import { PostgreSqlContainer } from '@testcontainers/postgresql';
import { StartedPostgreSqlContainer } from '@testcontainers/postgresql/build/postgresql-container';
import request from 'supertest';

import { UserModule } from '../src/user/user.module';

describe('users e2e', () => {
  let app: INestApplication;
  let postgresContainer: StartedPostgreSqlContainer;

  beforeAll(async () => {
    postgresContainer = await new PostgreSqlContainer().start();

    // add DATABASE_URL to env so we can use it for our migrations
    process.env.DATABASE_URL = postgresContainer.getConnectionUri();

    const moduleFixture = await Test.createTestingModule({
      imports: [
        DrizzlePostgresModule.registerAsync({
          tag: 'DB',
          useFactory() {
            return {
              postgres: {
                url: postgresContainer.getConnectionUri(),
              },
              config: { schema },
            };
          },
        }),
        UserModule,
      ],
    }).compile();

    // this also runs a seed method for testdata in non dev environments
    await runMigrations();

    app = moduleFixture.createNestApplication();
    await app.init();
  });

  afterAll(async () => {
    await app.close();
    await postgresContainer.stop();
  });

  it('Get users', () => {
    // Run actual http request against server with postgres database
    return request(app.getHttpServer())
      .get('/users')
      .expect(200)
      .expect([{ id: 1, name: 'Marijn' }]);
  });
});

.editorconfig

.editorconfig will be picked up by all editors unless specified otherwise. This config has overlap with prettier, moving all config that is not unique to .editorconfig, to prettier config, makes both easier to maintain.

root = true

[*]
charset = utf-8
insert_final_newline = true
trim_trailing_whitespace = true

prettier

Prettier is as an opinionated formatter with little configuration options, using it without any configuration is perfectly justifiable.

{
  "printWidth": 100,
  "singleQuote": true,
  "arrowParens": "avoid",
  "plugins": ["prettier-plugin-organize-imports", "prettier-plugin-organize-attributes"]
}

Angular being pretty verbose justifies the increased print width for me, you can still view 2 files open on a small screen side by side.

For plugins; prettier-plugin-organize-imports is mandatory since it eliminates review comments about unused imports. I would recommend prettier-plugin-organize-attributes, for consistency’s sake.

ESLint

ESLint can be an obtuse tool both in its usage and configuration. I would not recommend using ESLint in combination with the angular CLI for the majority of projects. Setting up ESLint with the angular CLI requires extra configuration and dependencies while adding no benefits in most scenarios. I would consider the angular CLI in multi project repo's so projects can be linted individually.

For configuration, I use a single file, that can be extended:

{
  "root": true,
  "ignorePatterns": [
    "**/build/**",
    "**/coverage/**",
    "**/dist/**",
    "**/generated/**",
    "**/node_modules/**"
  ],
  "extends": ["prettier"],
  "overrides": [/* abreviated */]
}

Prettier configuration being extended here is the only exiting line since it's needed to play nice with prettier. The overrides look as follows:

{
  "overrides": [
    {
      "files": ["*.ts"],
      "extends": [
        "eslint:recommended",
        "plugin:@typescript-eslint/recommended",
        "plugin:@angular-eslint/recommended",
        "plugin:@angular-eslint/template/process-inline-templates"
      ],
      "rules": {
        "no-console": ["error", { "allow": ["warn", "error"] }],
        "@angular-eslint/prefer-standalone": "error",
        "@angular-eslint/use-lifecycle-interface": "error"
      }
    },
    {
      "files": ["*.html"],
      "extends": [
        "plugin:@angular-ESLint/template/recommended",
        "plugin:@angular-ESLint/template/accessibility"
      ],
      "rules": {
        "@angular-eslint/template/prefer-control-flow": "error",
        "@angular-eslint/template/prefer-ngsrc": "error"
      }
    }
  ]
}

Only recommended rulesets are chosen, most rules chosen are to enforce use of modern angular features. My recommendation is to only extend these rules to prevent problems specific to your organisation.

Rules for selector prefix are omitted since it's redundant for single app projects. For multi-app projects you can add config files per app, that extend from this parent config and add the rules @angular-ESLint/directive-selector and "@angular-ESLint/component-selector". This way you can enforce prefixes on components like app1-component and app2-component on a per-app basis.

pre-commit

Lint-staged and husky are recommended by prettier for javascript projects. If you use a polyglot monorepo there are alternatives, like pre-commit and husky-dotnet.

{
  "lint-staged": {
    "**/*.{css,html,json,md,js,ts,yaml}": "prettier --write --ignore-unknown",
    "**/*.{js,ts,html}": "eslint --fix"
  }
}

Alternatives

Currently, there aren't any viable alternatives to these tools, there are in development but nothing mature yet. Most new tooling seems to focus on speed, but I'd like to see tooling that reduces the amount of setup and dependencies.

Conclusion

Having a decent set-up for prettier and ESLint can provide a decent basis for code quality. By keeping the configuration minimal you can later on easily modify and extend it when specific needs arise.

Executes <command> either from a local node_modules/.bin, or from a central cache, installing any packages needed in order for <command> to run.

So, when you run a script, npx prettier it will look in your node_modules/.bin first for an executable to run. If nothing is found in your node_modules, npx will start looking for any version in your local cache (~/.npm folder on unix, %LocalAppData%\npm-cache on windows). If nothing is found, it will install the latest version of the package it can find.

While this is great if you just want to run a standalone script: like scaffolding a new project or formatting some code, this can lead to issues in CI. In a CI environment, you want to run commands with the versions specified in your package.json, nothing else.

If something in your pipeline breaks around the installation of node_modules, npx usage can lead to further issues. Say you are using an older version of jest, but you run a script with npx, your test can be run with a different jest version than the one you've configured. This can lead to unintended behavior or worse, false positives.

Running your scripts without npx ensures this is not possible, your CI environment will only use the dependencies specified or break. This seems preferable to me versus a mechanism that can potentially introduce flakiness.

The behavior

@Component({
    providers: [{
        provide: NG_VALUE_ACCESSOR,
        useExisting: forwardRef(() => InputRetainsComponent),
        multi: true,
    }],
    template: `
    <input
      [value]="value"
      (input)="onChange($event)"
    />`,
})
export class InputRetainsComponent implements ControlValueAccessor

A component that implements ControlValueAccessor implements a couple of methods to interact with the Angular forms API.

onChange(event: Event): void {
    const value: string = (<HTMLInputElement>event.target).value;
    this.changed(value);
}

A changed method is registered as callback in this component. Whenever the value in the ui changes the method is called and the form is notified through the callback.

writeValue(value: string): void {
    this.value = value;
}

On the other side you have a writeValue function that the form uses to write the value to the custom formcontrol. Now if you write anything in your input in the ui and call setValue, the ui will update. However, when you call .reset() on the form the input will retain its value.

The fix

The solution is to write the value directly to the view, you don't need to keep an internal value;

    template: `
        <input #inputRef />`,
...
  writeValue(value: string): void {
    const ref = this.inputRef();
    ref && (ref.nativeElement.value = value);
  }

The explanation

An answer is actually in the comments of the ControlValueAccessor interface.

@usageNotes
### Write a value to the element

The following example writes a value to the native DOM element.

```ts
writeValue(value: any): void {
  this._renderer.setProperty(this._elementRef.nativeElement, 'value', value);
}

Though it may appear strange at first, writing directly to the DOM is actually encouraged. Maybe custom form controls are excluded from normal change detection

It's still strange behavior though, the first solution only had an issue when the reset function was called. There is a mention in the MDN docs that the value attribute is used for initial value. But when using normal input binding, the value is also mirrored...

If you want to look at full code examples you can find them in the angular-control-retains-value example on GitHub.

The use cases I wanted to solve were as follows:

• This behavior should be easy to implement across multiple forms
• This behavior should work for both empty forms and pre-filled forms (like an edit page)
• This behavior should work with multiple formcontrols on a single page
• A warning should be triggered on a reload or a navigation event

My implementation consists of 3 pieces, a service that tracks the state of formcontrols, a directive that is used to register a new form and a guard that gets triggered on navigation event. Al code examples are abbreviated to be more legible, a working example can be found in the angular-form-unload example on GitHub

HasFormChangedService

This service tracks the state a formcontrol starts with and the state which the formcontrol currently has. It does this through a simple interface:

interface FormStates {
  initialState: unknown;
  currentState: unknown;
}

class HasFormChangedService {
  private formStates: Record<string, FormStates> = {};
}

The key of the record is a unique identifier, I chose to use a uuid for this, which gets created when a form is first registered. There are also functions to update the current form state and to set it to a new initial state. The register function gets called later on through our directive, the directive will hold the id and handles updates.

public registerNewForm(state?: unknown): string {
	const id = uuid();
	this.formStates[id] = { initialState: state, currentState: state };
	return id;
}

public setCurrentFormState(id: string, currentState?: unknown): void {
	if (this.isFormIdNotPresent(id)) {
		throw Error(HasFormChangedService.ERROR_MSG);
	}
	this.formStates[id].currentState = currentState;
}

public setFormState(id: string, state?: unknown): void {
	if (this.isFormIdNotPresent(id)) {
		throw Error(HasFormChangedService.ERROR_MSG);
	}
	this.formStates[id] = { initialState: state, currentState: state };
}

With this logic you can check whether any form value has changed in the service by deep comparing the initial state with the current state. You can use this function later on to show the user a warning.

public haveFormsBeenChanged(): boolean {
	return Object.values(this.formStates).some(
		(state) => !equals(state.initialState, state.currentState)
	);
}

The service also has functions to remove individual forms, or all forms from the service. This is used when individual formcontrols get removed or when you don't want to track a form anymore, like when submiting.

HasFormChangedDirective

This directive is the key to easily implement this behavior across multiple forms. By adding this directive on a page and passing it a formcontrol, it registers that control to our service, when the page gets destroyed the directive also unregisters the control:

@Directive({
  selector: '[hasFormChanged]',
})
export class HasFormChangedDirective implements OnInit, OnDestroy {
  @Input() public hasFormChanged!: AbstractControl;
  private formId = this.hasFormChangedService.registerNewForm();
  private subscription?: Subscription;

  constructor(private hasFormChangedService: HasFormChangedService) {}

  public ngOnInit(): void {
    this.hasFormChangedService.setFormState(this.formId, this.hasFormChanged.value);

    this.subscription = this.hasFormChanged.valueChanges
      .pipe(debounceTime(250))
      .subscribe((value) => {
        if (this.hasFormChanged.dirty) {
          this.hasFormChangedService.setCurrentFormState(this.formId, value);
          return;
        }
        // If we get valueChanges while the form is not dirty it usually means we are programmatically setting
        // the control, so we need to reset its state in order to check for changes from the user
        this.hasFormChangedService.setFormState(this.formId, value);
      });
  }

  public ngOnDestroy() {
    this.hasFormChangedService.removeForm(this.formId);
    this.subscription?.unsubscribe();
  }
}

There is a lot going on here, so let's unpack this :)

This directive gets used on a page like this [hasFormChanged]='formcontrol', this causes the directive to be created, before the onInit we get a formId from our service. I had to name the formControl input the same as the name of the directive or the directive wouldn't be found, I don't know why this is. We use this id to set the formState in our OnInit function, we can't do it earlier because formdata sometimes isn't loaded. Next we subscribe to valueChanges from our formControl, we only update the current state when the control is dirty. We had some logic that updates formControls programmatically, so this works in our situation, but it might not work in your situation.

@HostListener('window:beforeunload', ['$event'])
public onBeforeUnload(event: BeforeUnloadEvent): void {
	if (this.hasFormChangedService.haveFormsBeenChanged()) {
		event.preventDefault();
		event.returnValue = false;
	}
}

@HostListener('submit')
public onSubmit(): void {
	this.hasFormChangedService.clearForms();
}

In our application this feature only had to work for a specific module, you should probably add these functions in a more central point. The HostListener for onBeforeUnload is the event that gets fired when a user triggers a reload, by checking wheter haveFormsBeenChanged and executing the logic a dialog gets displayed to the user. The HostListener for onSubmit is to clear the forms of our service when the user submits a form, submitting a form usually triggers a redirect so we don't want to display a message in that case.

HasFormChangedGuard

This is the guard that gets triggered on route changes, it's the same principle as the beforeunload logic, only we use a confirmational here. We can however display custom messages in a confirmational, so we use one from our environment.

export class HasFormChangedGuard implements CanDeactivate<unknown> {
  constructor(private formChangesService: HasFormChangedService) {}

  public canDeactivate(): boolean {
    return this.formChangesService.haveFormsBeenChanged()
      ? confirm(environment.hasFormChangedMessage)
      : true;
  }
}

CancelFormDirective

We have a seperate directive for buttons that explicitly cancel a form, which shouldn't display any message.

export class CancelFormDirective {
  constructor(private hasFormChangedService: HasFormChangedService) {}

  @HostListener('click', ['$event'])
  public onClick(): void {
    this.hasFormChangedService.clearForms();
  }
}

Closing thoughts

What I like about this solution is that it's easy to implement across multiple forms and works with forms that have multiple formgroups across multiple components. I would like to have a solution for displaying the same type of warning to the user for both reloading as navigating. Also I'm pretty sure the HostListeners in the Directive can be moved to App.Component or a similair central point.

Again, the source is in the angular-form-unload example on GitHub