This article is created by heavily using Claude.ai.

The article banner is a picture of Graphue

Angular’s Dependency Injection (DI) system is powerful, but knowing when to use constructor injection versus the newer inject() function can significantly improve your code quality. With the introduction of runInInjectionContext(), we now have even more control over dependency resolution.

In this article, we’ll explore five key scenarios where inject() (sometimes with runInInjectionContext) provides better solutions than traditional constructor injection.

1. Standalone Functions (Route Guards, Interceptors)

Problem: Constructor injection requires class wrappers for simple functions.

@Injectable({
  providedIn: 'root'
})
export class AuthGuard implements CanActivate {

  constructor(
    private router: Router,
    private authService: AuthService
  ) {}

  canActivate(
    route: ActivatedRouteSnapshot,
    state: RouterStateSnapshot
  ): boolean {
    return this.authService.isLoggedIn() || this.router.navigate(['/login']);
  }
}

Solution: inject() enables dependency access in functions.

import { inject } from '@angular/core';
import { Router } from '@angular/router';

export function authGuard(): boolean {
  const router = inject(Router);
  const authService = inject(AuthService);

  return authService.isLoggedIn() || router.navigate(['/login']);
}

Key Benefits:

• less boilerplate code
• No artificial class creation
• Better tree-shakability
• Now the Angular-recommended approach.

As you may notice it is used with functional route guards.

2. Factory Functions (Creating Customized Services)

As for me — this case is similar to previous one but have different application point — creating configurable service instances in functional way.

import { inject, InjectionToken } from '@angular/core';

// Token for different logger instances
export const USER_LOGGER = new InjectionToken<Logger>('user.logger');
export const SYSTEM_LOGGER = new InjectionToken<Logger>('system.logger');

// A factory that creates specialized logger instances
export function createLogger(category: string, minLevel: 'debug'|'info'|'error') {
  const configService = inject(ConfigService);

  return {
    debug: (msg: string) => {
      if (minLevel === 'debug' && configService.isDebugEnabled) {
        console.log(`[${category}][DEBUG] ${msg}`);
      }
    },
    info: (msg: string) => {
      if (minLevel === 'debug' || minLevel === 'info') {
        console.log(`[${category}][INFO] ${msg}`);
      }
    },
    error: (msg: string) => {
      console.error(`[${category}][ERROR] ${msg}`);
    }
  };
}

// Creating provideFunction
export function provideUserLogger(minLevel: 'debug'|'info'|'error') {
  return {
    provide: USER_LOGGER,
    useFactory: () => createLogger('USER', minLevel)
  }
}

export function provideSystemLogger(minLevel: 'debug'|'info'|'error') {
  return {
    provide: SYSTEM_LOGGER,
    useFactory: () => createLogger('SYSTEM', minLevel)
  }
}

// Register in config file which will be used for Angular pp bootstrapping
export const appConfig: ApplicationConfig = {
  providers: [
    // Other providers...
    ConfigService,
    provideUserLogger('info'),
    provideSystemLogger('error')
  ]
};

Well, remembering to provide ConfigService to be able to use SYSTEM_LOGGER and USER_LOGGER providers is not very convenient, so better to modify provideSystemLogger and provideUserLogger to do that for us:

export function provideUserLogger(minLevel: 'debug'|'info'|'error') {
  return [
    ConfigService,
    {
    provide: USER_LOGGER,
    useFactory: () => createLogger('USER', minLevel),
  }]
}

export function provideSystemLogger(minLevel: 'debug'|'info'|'error') {
  return [
    ConfigService,
    {
    provide: SYSTEM_LOGGER,
    useFactory: () => createLogger('SYSTEM', minLevel),
  }]
}

Here is a playground.

3. Lazy Injection (On-Demand Service Loading)

Constructor injection instantiates all services upfront, even if they’re rarely used. inject() allows delayed injection.

It work by using the runInInjectionContext function. This function lets you create an injection context at runtime, allowing inject() to be called outside the component initialization.

import { Component, inject, Injector, runInInjectionContext } from '@angular/core';
import { HeavyDataService } from './services';

@Component({
  selector: 'app-heavy',
  template: '...'
})
export class HeavyComponent {
  // Store the injector itself
  private injector = inject(Injector);

  // Service is not injected at initialization

  private loadHeavyData() {
    // Create injection context when needed
    return runInInjectionContext(this.injector, () => {
      // Now we can safely use inject()
      const heavyService = inject(HeavyDataService);
      return heavyService.fetchData();
    });
  }

  onUserAction() {
    // Heavy service only injected when this is called
    const data = this.loadHeavyData();
    // Process data...
  }
}

Looks good, doesn’t it? Until my friend told me that to make HeavyDataService really lazy we need to use import O_o:

  private loadHeavyData() {
    // Create injection context when needed
    return runInInjectionContext(this.injector, () => {
      // Now we can safely use inject()
      return import('./services').then(({ HeavyDataService }) => {
      const heavyService = inject(HeavyDataService);
      return heavyService.fetchData();
    });
  }

4. Multi-Level Inheritance (Avoiding Constructor Hell)

TBH I am not a fan of inheriting component classes in Angular (composition over inheritance). I think it brings more mess than DRY benefits. But if you like it:

@Component({...})
export class BaseComponent {
  protected readonly router = inject(Router);
}

@Component({...})
export class MiddleComponent extends BaseComponent {
  protected readonly userService = inject(UserService);
}

@Component({...})
export class ChildComponent extends MiddleComponent {
  // Has access to both `router` and `userService`
  // No complex constructor chaining needed!
}

Benefits:

• No super() boilerplate.
• Cleaner, more maintainable inheritance.
• A child class can override a parent’s injected service by using inject() with the same token, creating its own instance.

5. Dynamic Providers (Runtime Dependency Switching)

Constructor injection requires static dependencies. inject() enables dynamic service selection.
This case is very close to example #3 with Lazy service instantiation but brings more conditional logic to the previous example.

import { Component, inject, Injector, runInInjectionContext } from '@angular/core';
import { FeatureFlagService, NewImplementationService, LegacyImplementationService } from './services';

@Component({
  selector: 'app-dynamic',
  template: '...'
})
export class DynamicComponent {
  private injector = inject(Injector);
  private featureFlag = inject(FeatureFlagService);

  // Don't inject services yet
  private service: any;

  constructor() {
    // Get the right service based on feature flag
    this.service = this.getService();
  }

  private getService() {
    return runInInjectionContext(this.injector, () => {
      // Now we can conditionally inject
      if (this.featureFlag.isNewFeatureEnabled) {
        return inject(NewImplementationService);
      } else {
        return inject(LegacyImplementationService);
      }
    });
  }

  doSomething() {
    this.service.method();
  }
}

6. Type Inference with inject() vs Constructor DI

When using InjectionTokens with constructor DI, you need to manually specify the type. Even more: you can get the type annotation wrong. Angular/TypeScript doesn’t check whether the type annotation matches the type of the InjectionToken/class.

// Define a token with a type
const CONFIG = new InjectionToken<AppConfig>('app.config');

@Component({...})
class MyComponent {
  constructor(
    // Must manually specify the type here
    @Inject(CONFIG) private config: AppConfig
  ) {}
}

Moreover, Constructor parameter decorators are not part of the ECMAScript Decorators standard. They will be unsupported once the experimentalDecorators option is removed from the TypeScript compiler

The inject() function automatically infers the correct type from the token:

// Define a token with a type
const CONFIG = new InjectionToken<AppConfig>('app.config');

@Component({...})
class MyComponent {
  // Type is automatically inferred as AppConfig
  private config = inject(CONFIG);

  ngOnInit() {
    // TypeScript knows this is AppConfig
    console.log(this.config.apiUrl);
  }
}

7. Changes in ES2022 and future deprecation of ‘useDefineForClassFields’ compiler option in typescript.

This info was introduced by Jeremy Elbourn (team lead of Angular team) in github issue comment:

Additionally, we’re adding one new recommendation: Prefer the inject function over constructor parameter injection

We’re adding this new recommendation in light of the introduction of class fields in ECMAScript 2022.

Next text is copied from Jeremy Elbourn’s github comment:

Here is a basic example:

@Component({ /* ... */ })
export class UserProfile {
  private user = this.userData.getCurrent();

  constructor(private userData: UserData) { }
}

This example works just fine when TypeScript emits ECMAScript versions less than ES2022. In these versions, the compiled JavaScript looks like this:

// Emitting ES2017
export class UserProfile {
    constructor(userData) {
        // The field initializer is inlined into the constructor
        this.userData = userData;
        this.user = this.userData.getCurrent();
    }
}

However, in ES2022 with the useDefineForClassFields option, the output looks like this:

// Emitting ES2022
export class UserProfile {
    userData;
    user = this.userData.getCurrent(); // Error! userData is not yet initialized!
    constructor(userData) {
        this.userData = userData;
    }
}

This output throws an error because the field initializer runs before the constructor and tries to use the injected dependency before it’s available. To work around this with constructor injection, you would write your code like this:

@Component({ /* ... */ })
export class UserProfile {
  // Field declaration is separated from initialization.
  private user: User;

  constructor(private userData: UserData) {
    this.user = userData.getCurrent();
  }
}

Many developers find the separation of field declaration and initialization to be undesirable. Fortunately, the inject function neatly sidesteps this problem:

@Component({ /* ... */ })
export class UserProfile {
  private userData = inject(UserData);
  private user = userData.getCurrent();
}

Appendix: Situations Where inject() Won’t Work in Angular

1. Outside Injection Context (more here)

Here are particular cases:

a) In Asynchronous Code

@Component({...})
class MyComponent {
  constructor() {
    // This will fail
    setTimeout(() => {
      const service = inject(MyService); // ERROR
    }, 1000);
  }
}

b) In Event Handlers

@Component({
  template: '<button (click)="handleClick()">Click</button>'
})
class MyComponent {
  handleClick() {
    // ERROR: No injection context in event handler
    const service = inject(MyService);
  }
}

c) In Subscription Callbacks

@Component({...})
class MyComponent {
  constructor() {
    const observable = inject(DataService).getData();

    observable.subscribe(data => {
      // ERROR: No injection context in subscription callback
      const logger = inject(LoggerService);
      logger.log(data);
    });
  }
}

d) In Standalone Functions Without runInInjectionContext

// Standalone utility function
export function formatData(data: any) {
  // ERROR: No injection context
  const formatter = inject(FormatterService);
  return formatter.format(data);
}

e) inject(…) won’t work in ngOnInit method without runInInjectionContext.

  // doesn't work
  ngOnInit(): void {
    // We need to use runInInjectionContext here
    this.serviceB = inject(MyService);
  }

// works  
  ngOnInit(): void {
    runInInjectionContext(this.injector, () => {
      this.serviceB = inject(MyService);
    });
  }

Actually, all the cases above are solved by wrapping in runInInjectionContext helper function.

2. In Regular (Non-Angular) Classes

// Regular class, not managed by Angular DI
class RegularClass {
  constructor() {
    // ERROR: No injection context
    const service = inject(SomeService);
  }
}

Final Verdict

1. Use constructor injection for standard component/service DI but consider moving to inject() if you plan to migrate to es2022.
2. Use inject() for edge cases like functions, factories, lazy loading, inheritance, and dynamic providers

More to read:

1. “The inject function is not a service locator” by Matthieu Riegler
2. Interesting drawback of using inject function in Angular 16+ (I did not check it on newer versions). Case: Angular 16+ pipe used with the template child component input value. Drawback: if in pipe we inject ChangeDetectorRef with ‘inject’ function: cdRef will be from ChildComponent; but if we inject ChangeDetectorRef using constructor injection, it will be from the ParentComponent.

Like this article? Follow me on Twitter or Buy me a coffee!

Originally published at https://dev.to on April 14, 2025.

Builders, custom typescript transformers, custom tslint rules, schematics — how not to be overwhelmed and lay it all out in your head?

AngularInDepth is moving away from Medium. This article, its updates and more recent articles are hosted on the new platform inDepth.dev

I don't know how about you but I got confused with a variety of tools that Angular CLI provides for some not straightforward Angular environment tasks. Builders, schematics, typescript transformers, custom tslint rules, AST — what are these all about, why do we need them and when do we have to use them? My brain was bleeding…

At last, I found a time to dig deeper and sort information about these tools (Hooray!)

Let's review them one by one.

(Angular CLI 9.x codebase is used).

Builders

What are builders in Angular?
In Angular builders are used to do some routine tasks: build code, run lint, run unit tests, deploy code to host-provider.

A number of Angular CLI commands run a complex process on your code, such as linting, building, or testing. The commands use …builders, which apply another tools to accomplish the desired task.

Angular provides … builders that are used by the CLI for commands such as ng build, ng test, and ng lint. Default target configurations … can be found (and customized) in the "architect" section of the workspace configuration file, angular.json.

You can also extend and customize Angular by creating your own builders, which you can run using the ng run CLI command.

https://angular.io/guide/cli-builder

Let’s start with understanding what builders are used for and then explore how they are implemented.

If you run ng build command — Angular CLI actually runs the builder handler function (build in our case). Let’s go step by step and see what actually goes on behind the scenes.

*Don't forget that your monorepo project can have a few applications, and in angular.json you specify builder for each specific project. And to start builder for a concrete project with Angular CLI you should add project name to the command, for example: ng build app1 (you can read more in my monorepo article here)

1. Read config in angular.json and find respective builder (projects->projectName->architect->build->builder)

"builder": "@angular-devkit/build-angular:browser", // original

OR

"builder": "@angular-builders/custom-webpack:browser", // custom

Here is code of build-angular:browser builder.

2. Create a builder instance and run it

export default createBuilder<json.JsonObject & BrowserBuilderSchema>(buildWebpackBrowser);

3. The builder runs its standard tasks:

a) assertCompatibleAngularVersion

b) buildBrowserWebpackConfigFromContext and runWebpack (webpack starts typescript compiler for your code)

c) copyAssets

d) generateBundleStats

e) generate index.html

f) Apply service worker if needed

and we get bundle files (index.html, css, js files in ./dist folder)

So what are builders used for?

Actually, they can be used for everything about your codebase: build, dev-server, run unit tests, run linter, etc

Now you can assume what ng add command does — among many other things it adds new records to angular.json file (adding a new builder) — we will talk about ng add a bit later.

Let's run ng add @angular/fire in our project and check how angular.json is changed:

As you can see — a new deploy builder was added (so we can do ng deploy now for our project to upload bundled files to FireBase hosting).

Angular CLI standard builders

As you can see from picture above — standard Angular CLI builders are located in @angular-devkit package which contains build-angular collection.

Here you can find all builders like build, karma, browser, dev-server, etc and their implementations.

Custom builders

Also, you can create your own builder for custom purposes:

1. To add extra Webpack config options (custom-webpack builders by JeB Barabanov )
2. Concat bundled JS files (ngx-build-plus builder by Manfred Steyer)
3. Automate other routine tasks for you (configure and run source-map-explorer — by Santosh Yadav)

More to read

1. Angular CLI builders (official doc)
2. Angular CLI under the hood — builders demystified by JeB Barabanov
3. Custom Angular builders list page by Santosh Yadav

Conclusion

Builders are used to do some routine tasks: build code, run lint, run unit tests, deploy code to host-provider. Also, you can create your own builders to automate some operations and add some new possibilities: add Webpack configs, run scripts, concatenate bundled files, etc.

Like this article? Buy me a coffee :-)

Schematics

Schematics transform your project: update files, install packages, add new component/modules/directives/etc files.

The Angular CLI uses schematics to apply transforms to a web-app project (modify or create project files).

Schematics are run by default by the commands ng generate, and ng add.

If you create a new version of your library that introduces potential breaking changes, you can provide an update schematic to enable the ng update command to automatically resolve any such changes in the project being updated (to do automatically changes in project code so code uses new API).

https://angular.io/guide/schematics

and

Schematics is a workflow tool for the modern web; it can apply transforms to your project, such as create a new component, or updating your code to fix breaking changes in a dependency. Or maybe you want to add a new configuration option or framework to an existing project

Schematics — An Introduction

Ok, too vague as for me. Let's make it more specific.

Do you remember how we added the possibility to deploy to FireBase hosting in the previous section with ng add @angular/fire command? We use schematics.

What did this schematics do for us?

1. Installed packages @angular/fire, firebase, firebase-tools and so on (package.json is updated also). @angular/fire contains a builder for deploying bundled code to FireBase.
2. Asked some specific questions while running (to specify options)
3. Updated angular.json — added deploy builder config. Now we can run ng deploy.

So schematics did all preparations work for us to start using deploy builder: installed packages and updated configs.

So how to run schematics

• ng new <appName> and ng generate <unitType> <unitName>— start respective schematic (using default schematics collection from @schematics/angular package).
  You can specify some default options for them in angular.json file — see more details here. Or you can set schematics options as a common line argument.
  You can override default schematics collection used by ng commands — modify project angular.json file (angular.json > cli > defaultCollection).
• ng add <packageName> — installs the package and then starts ng-add schematics from it (specified in its package.json).
• ng update <packageName> — installs a newer version of a package and then starts migration schematics from it (specified in package.json).
• You can also run schematics with schematics command
  (watch more details in this video: A Schematic Odyssey by Kevin Schuchard & Brian Love)

*Here is a nice review of angular.json structure: "Understanding the Angular CLI Workspace File" by @nitayneeman.

Where are standard Angular schematics located?

You may already know that you can generate a set of component files with the command: ng generate component some-component

Where are these files templates are take from? You can find them in @schematics package:

So ng generate command just runs component schematics. Same with other schematics: directive, pipe, module, etc

Takeaway

• In Angular builders are used to do some routine tasks: build code, run lint, run unit tests, deploy code to host-provider.
• Schematics transform your project: update files, install packages, add new component/modules/directives/etc files.
• If you want to create your builder — deliver it with schematics (to be used with ng add) that update angular.json (add that builder into) and installed respective packages.
  A nice example of such a package is "@angular/fire”. It contains both builder (here and here) and schematics for ng add (here)

I will not stop on implementation details here. If you are interested — here is a list of recommended articles to start.

More to read

1. Generating code using schematics
2. Schematics — An Introduction
3. Effective automated scaffolding with Angular Schematics
4. Overriding Angular Schematics

5. ngx-deploy-starter — create your own deploy builder (and schematics)

Custom tslint/eslint rules for Angular

What is tslint for? It shows whether developers respect code style guide. Why do we need that? Style guide increases code readability (and so maintainability). And also there are rules that help you to prevent specific bugs (like rxjs-tslint-rules).

You can install and then update project's tslint.json file to start using newly installed rules. For example

npm install rxjs-tslint-rules --save-dev

//Update your tslint.json file to extend this package:

{
  "extends": [
    "rxjs-tslint-rules"
  ],
  "rules": {
    "rxjs-add": { "severity": "error" },
    "rxjs-no-unused-add": { "severity": "error" }
  }
}

*Taken from: https://github.com/cartant/rxjs-tslint-rules/blob/master/README.md

So when you run ng lint command :

1. Angular CLI checks for lint builder in angular.json file, create it and run it.
2. Builder starts tslint
3. tslint read tslint.json file to grab all the rules and then checks your code for compliance with the rules.

I will not dive in details HOW to create custom tslint rules here since it is out of the article scope, but you can read about it in the proposed articles below.

Conclusion

• In Angular builders are used to do some routine tasks: build code, run lint, run unit tests, deploy code to host-provider.
• Schematics transform your project: update files, install packages, add new component/modules/directives/etc files.
• lint builder starts tslint which loads rules and then check your code to obey these rules — and you can create custom ones to expend for your code-style.
• You don't need Angular CLI to start tslint through lint builder — you can run it directly with tslint command (if it is installed globally) or npx tslint (if tslint is installed only locally in your project)

More to read

1. Custom TSLint rules with TSQuery
2. Migrating a TSLint Rule to ESLint
3. rxjs-tslint-rules
4. Writing custom TSLint rules from scratch
5. Custom TSLint rules — easier than you think

Did you know that:

👉 TSLint is getting deprecated

👉 The angular-eslint project is a port from codelyzer

👉The eslint-plugin-rxjs is a port from rxjs-tslint-rules

Read more in “Migrating a TSLint Rule to ESLint” by Tim Deschryver

Custom Typescript Transformers

The Angular CLI uses the AngularCompilerPlugin to transpile typescript. It is a webpack plugin that uses the typescript compiler together with various Typescript transformers to transpile the typescript to workable JS code for the browser.

David Kingma. Custom Typescript Transformers with Angular CLI

Now let's show its place in a big picture:

• we start ng build
• Angular CLI(ng) finds in angular.json respective builder

• the builder starts webpack, and webpack uses AngularCompilerPlugin.
• AngularCompilerPlugin starts typescript compiler (to compile project .ts files) and provide specific transforms also to this compiler (you can read more about it here)
• And you can provide additional typescript transforms too (👈🏽 we are here)

What do standard AngularCompilerPlugin transforms do?

For example — transform "Inline resource"- takes component decorator templateUrl value (a filename), read the file, and put template prop instead with file content as a value.

A list of transformers is located here.

You can read about many of them in the nice article of Alexey Zuev "Do you know how Angular transforms your code?".

Why may we need to code our own custom transforms?

1. You want to apply your own syntax in Angular templates, and to make Angular understand it. ngx-template-streams uses that approach (video).
2. You want to grab some specific information from one file and modify another file during build process (Here is an article that describes such example)
3. You want to find all RxJS observables in your Angular project and automatically insert unsubscribe code (a nice article from Christian Janker about that).
4. etc

How do we provide our custom transformer so the typescript compiler can apply it?

AngularCompilerPlugin has a _transformers property where all Angular standard transformers are usually added to. So we have just to modify it and add also our own customer transformer. How?

There is a special ngx-build-plus:browser builder (it replaces standard builder for ng build command) from ngx-build-plus (by Manfred Steyer). This ngx-build-plus:browser that allows to modify internal webpack configuration in Angular projects (you remember, that ng build runs a builder that starts webpack to build our project, right?:)

Since builder has instance of webpack so you can provide your plugin for this builder and can get access to AngularCompilerPlugin instance and modify its _transformers prop by adding your custom transformer to the list.

Lets better describe it step by step:

1. We install ngx-build-plus and now when we start ng build command new builder is used — ngx-build-plus:browser (previously it was standard Angular CLI builder — @angular-devkit/build-angular:browser)
2. ngx-build-plus:browser can accept our plugin (it is not TS transformer, but webpack config transformer) where you can modify webpack config (Here is an example of such plugin).
3. So your webpack-modifier plugin gets access to AngularCompilerPlugin instance and modify its _transformers prop by adding your custom transformer to the list.
4. After ngx-build-plus:browser applied you webpack-config-changer plugin and get modifier webpack config — it runs webpack build or your project.
5. During the build process, webpack applies AngularCompilerPlugin transformers (and your transformer also among other transformers) — here is an example of such dummy transformer by David Kingma.

Phew 🤓

More to read

1. Having fun with Angular and Typescript Transformers
2. Hacking the Angular compiler with your own syntax [Video]
3. Custom Typescript Transformers with Angular CLI
4. Do you know how Angular transforms your code?
5. Converting TypeScript decorators into static code using tsquery, tstemplate and transforms!
6. Writing a Custom TypeScript AST Transformer
7. Using the Compiler API

Conclusion

Let's go through all parts once more (yes, you guessed right, I was a teacher many years ago, and my mom too 😁):

• Builders are used to start some routine tasks: build code, run lint, run unit tests, deploy code to host-provider.
• Schematics transform your project: update files, install packages, add new component/modules/directives/etc files.
• lint builder starts tslint which loads rules and then check your code (typescript parser is used) to obey these rules — and you can create custom ones to expend for your code-style.
• To build angular code (which contains angular specific template constructs: *ngIf, [somePros], (click), etc) webpack uses AngularCompilerPlugin. It transforms Angular syntax converting it to something that the TypeScript compiler can understand. You can create your own template syntax (or typescript code syntax) for some purposes and make Angular (webpack) understand it too by providing custom transformer.
  Or you can use the transformer just to add something to code or modify it at build time.
  Transformers are applied only during build time.

AST Conclusion

Many of reviewed entities of Angular CLI (or related apps) uses Abstract Syntax Tree to do their work. Not to be embarrassed let's clarify that part too.

Typescript compiler parser can represent each .ts file as AST.

A linter scans an Abstract Syntax Tree (AST). Each specific lint-rule implementation is used to look for patterns in code (actually in AST).

Typescript transformers use file(s) AST also to look through and update files.

Schematics operates over project filesystem representation Tree (or Source)- you modify Tree and then these changes are applied to filesystem. (Tree is not typescript parser AST, read more here)

Builders don't use AST at all. BuilderHandler (builder implementation function) only gets input params and some architectural context (BuilderContext). BuilderContext just contains some project related information (ProjectMetadata, currentDirectory, etc).

Homework

Relax, just kidding you, no homework. Go feed your bear, play with your nuclear reactor, and don't forget to drink vodka (joking 😁).

This article is a part of my own learning process. If you found some wrong or partially wrong statement — feel free to correct me in comments.

Let’s keep in touch on Twitter!

Cheers!

Angular CLI flows. Big picture. was originally published in Angular In Depth on Medium, where people are continuing the conversation by highlighting and responding to this story.

A while ago I was employed and what was new for me — I got MacBookPro as a work laptop. It was a new experience for me (since the last 20 years I've been using only Windows 95/../10).

Whilst overall I am quite satisfied with the Mac experience, but I have a few small things that I still miss on Mac that was possible on Windows.

Feel free to advise your favorite Mac apps that may cover these gaps — I would appreciate it.

So let's go 😎

#1. I cannot stretch the application window on two screens.

I often work with Chrome Dev Tools. And on Windows computer I placed DelTools panel to the right and stretched window so panel appeared on another monitor.

Unfortunately, I didn't find the way to do this on Mac. The only solution is to open Chrome Dev Tools as a separate window and then move DevTools window to another monitor screen. But it is not the same experience.

#2. There is no shortcut ‘Minimize all windows’ 😢

There are often many open apps on my screen. Some sometimes I just want to minimize them all and open the one I need. But there is no 'Minimize all windows (Show Desktop)' button like on Windows 7 taskbar. I miss it a lot.

I did find such a button in Windows 10 but:

"In Windows versions prior to Windows 7, there was a button which minimized all opened Windows and showed the desktop. In Windows 10, there is no such button. Instead, to minimize all open windows and show the Desktop, you need to move the mouse pointer to the right edge of the taskbar (or the bottom edge if your taskbar is vertical) and click a tiny invisible button."

Add the Show Desktop button next to Start in Windows 10

I didn't find such a shortcut in macOS. But to archive a bit similar experience you can use:

1. Use Mission Control button to see all open windows and switch between them

2. Show Mac Desktop with Command + F3
But it doesn't work the same way as in Windows. Yes, you see the Desktop but once you press any app on a Dec — all the apps windows will return to its screen positions. While in Windows they become minimized and you can maximize the app you want to work with.

#3. Dock only visible on one screen at the moment

In Windows, you see the taskbar on each screen while in MacOS you have to choose on which screen you have it. Maybe for someone, it is a benefit but for me, it is not convenient to make it appear each time I need to maximize other apps.

#4. No 'Delete' button on a keyboard

Actually there is but it works as BackSpace on PC (deleting character before the cursor).

You can achieve this behavior by pressing fn+Delete button but not the same experience.

#5. PuntoSwitcher (keyboard layout input language correction) works for 2 languages only

I am a native speaker for Ukrainian and Russian language (what is quite usually in Ukraine). And also uses the English language quite often too. Sometimes if you forget to switch languages — you get some abracadabra (Jabberwocky) text.

Not to erase it and then input again I used to use PuntoSwitcher. It works quite good and by hotkey press changes language layout for last edited work so you don't have to re-type it again:

If you have 3 languages — then in windows just press twice to convert to a language you need. But not on Mac — you cannot convert to language 1, then 2 and then 3 — just 1 and 2. And you should choose in options (in Punto for Mac) which two languages you will be able to switch between 😭.

Conclusion

Well. All these imperfections are not a disaster for me. And after being fired from my last job I still continue using MacBookPro (I was allowed to buy my work laptop for a good price). But these are things I definitely would like to have:-) Do you have such staff you miss too? Share in comments!

BTW usually I write articles on Angular and RxJS! So if you are interested -let’s keep in touch on Twitter.

Cheers!

In this article, I will tell you how to avoid simple pitfalls while working with ngRx to improve your family-work balance:-)

Introduction

If you work with Angular you definitely know about the most popular state management system for Angular applications ngRx/Store.

Let's recall what it is to be on the same page:

@ngrx/store

… is RxJS powered state management for Angular applications, inspired by Redux. Store is a controlled state container designed to help write performant, consistent applications on top of Angular.

Here is the flow diagram from official documentation describing how it works:

Components send Actions that is an object with a mandatory property type and optionally other properties with data to be stored to the central object — a Store. Actions are being handled by reducers, a special functions that make data from actions and put them to Store (or modify Store). Other components can subscribe to Store updates (to a specific part of the Store) with selectors (actually selectors determines which part of the Store updates you want to monitor). In simple cases, selectors receive state object as an argument and return you some property of the state object:

(state) => state.prop1

Before I start to keep your time let's review the simplest example. Not to re-invent the bicycle I will use the simplified example from the official doc.

We will create a Store with counter value, and action/reducer that increases that counter value.

Let's create an action:

// src/app/counter.actions.ts

import { createAction } from '@ngrx/store';

export const increment = createAction('[Counter Component] Increment');

Reducer:

//src/app/counter.reducer.ts

import { createReducer, on } from '@ngrx/store';
import { increment } from './counter.actions';

export const initialState = 0;
const _counterReducer = createReducer(initialState,
   on(increment, state => state + 1)
);

export function counterReducer(state, action) {
   return _counterReducer(state, action);
}

Add StoreModule module to app.module.ts

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { StoreModule } from '@ngrx/store';

import { counterReducer } from './counter.reducer';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    StoreModule.forRoot({ count: counterReducer })
  ],
  providers: [],
  bootstrap: [AppComponent],
})

export class AppModule {}

You can see that we specify our reducer in this line

StoreModule.forRoot({ count: counterReducer })

To read count value we just need to use select function in a component:

// in some component
import { Store, select } from '@ngrx/store'
...

constructor(private store: Store<{ count: number }>) {

this.count$ = store.pipe(select('count')); 
// now we have observable that will emit values on each count update

// old school approach
//this.count$ = store.pipe(select(state => state.count));

}

What if we don't want to keep count in the main app module?
We can put it to a feature module.

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    StoreModule.forRoot({}),
    StoreModule.forFeature('featureName', { count: counterReducer })
  ],
  providers: [],
  bootstrap: [AppComponent],
})

export class AppModule {}

Now our selector to grab the value from feature-branch of the Store state will be:

// count.selectors.ts
export const selectFeature = createFeatureSelector<FeatureState>('featureName');

export const countSelector = createSelector(selectFeature, (state) => state.count);

// And in some component
this.count$ = store.pipe(select(countSelector));

Now let's check how all this works:

All our actions and Store state changes we can observe with nice Chrome plugin: Redux DevTools:
1. Install a plugin in Chome
2. install @ngrx/store-devtools module to your Angular app:
 — ng add @ngrx/store-devtools
- Or npm i @ngrx/store-devtools (in that case you should add StoreDevtoolsModule to AppModule manually)

3. monitor your Store in Chrome Dev Tools (Redux tab)

Simple, right?

At that place, you may ask yourself why do we need an article that just represents the official documentation example? Because even with these simple flows you can spend hours on debugging if something doesn't work as expected.

I revealed 5 often mistakes in my (and my fellow developers) practice.

#1. Redux-DevTools doesn't display undefined props in actions

Say we have an action that sends not the only type of message but also some additional info:

{
 type: SOME_TYPE,
 value: this.someProp
}

For that purpose lets modify a bit our code:

// counter.actions.ts
...
export const increment = createAction('[Counter Component] Increment', props<{value: number}>());

// counter.reducer.ts
const counterReducerFunc = createReducer(initialState,
  on(increment, (state, {value}) => state + 1 + value)
);

//app.component.ts
public value;
...

increment() {
// provide additional value to actionCreator function  this.store.dispatch(increment({value: this.value})); 
}

Now our reducer should increase state value by 1 and add value.

But, something goes wrong and you want to debug the actions in Redux Dev Tools.

Ok, count got NAN value, this is not correct. And why don't we see value prop in action tab content in ReduxDevTools? Only type field is present.

The answer is that a) we forgot to assign some number to value property, b) Chrome plugins cannot get undefined values since it cannot be stringified.

Let's assign value with 0.

//app.component.ts
public value = 0; // or other number value

Now we can observe this prop in ReduxDevTools:

I spend an hour to reveal it. Maybe you will waste less time after reading this:)

You can take a look at code in this branch of the article GitHub repo. Or check it in a ng-run.com playground.

Take away: better to use null if you need to specify empty value since null can be stringified and can be shown in ReduxDevTools.

#2. StoreDevModule may slow down the app

Once upon a time, I had a big list of objects in a Store. And some user operations modified data on the specific Action type and put them back to Store and then components displayed that data.

What our testers observed that starting from a few hundreds of items in a list each user operation caused small but noticeable UI update lags. And this was not rendering but JS issue.

After checking with ChromeDevTools on Performance tab (you can read more about it here) I got this picture:

Do you remember why it may happen? Yes, because we send data to our ReduxDevTools plugin to be able to monitor Store Actions and state.

Since we added StoreDevToolsModule manually to the AppModule — we missed option to turn it off for prod builds:

imports: [
  StoreModule.forRoot({}),
  StoreModule.forFeature(featureKey, {items: itemsReducer}),
  BrowserModule,
  // StoreDevtoolsModule.instrument({ maxAge: 25, logOnly: environment.production }), // missed logOnly option
  EffectsModule.forRoot([AppEffects])
],

After I added it — UI started to feel much better:-)

Takeaway: do not forget logOnly option when you use StoreDevtoolsModule to monitor your ngrx/Store activities. Actually, if you install it with ng add @ngrx/store-devtools then this option will be added automatically. You read more about logOnly here.

You can play with the code in GitHub repo branch. Or start this branch on ng-run.com Angular playground by Alexey Zuev. For that just copy GitHub branch link and add ng-run.com/github/<yourlink> like this:

Branch link: 
https://github.com/kievsash/ngrx-store-and5sillyMistakes/tree/pitfall_2_StoreDevtoolsModule_slow_down

Now lets start it on ng-run.com

https://ng-run.com/github/kievsash/ngrx-store-and5sillyMistakes/tree/pitfall_2_StoreDevtoolsModule_slow_down

Like this article? Buy me a coffee :-)

#3. You import feature module but it doesn't work

a) Ok, So you have nice feature Angular module where you put:

// feature.module.ts

...

imports: [
   StoreModule.forFeature(featureKey, {items: itemsReducer}),
...

You expect it should work when you added it to app.module.ts AppModule imports. But… it doesn't) You open a ChromeDevTools console and see:

Ok, so we go to ngrx/platform GitHub repo and search for 'ReducerManager' entity. And see that it is provided as REDUCER_MANAGER_PROVIDERS by StoreModule.forRoot(…) call here.
Answer is obvisous: we forgot to include StoreModule.forRoot({}) in out AppModule.

// app.module.ts
imports: [
  StoreModule.forRoot({}),
  StoreModule.forFeature(featureKey, {items: itemsReducer}),

Now it works good.

b) I found one more interesting behavior but with StoreDevtoolsModule

Ok, so you added it to AppModule:

imports: [
  StoreDevtoolsModule.instrument({ maxAge: 25, logOnly: environment.production }),
  StoreModule.forRoot({}),
  StoreModule.forFeature(featureKey, {items: itemsReducer}),

But when you open Redux tab in ChromeDevTools you see this:

Why??

Because I just put StoreDevtoolsModule in imports array BEFORE StoreModule.forRoot. So it seems like Angular tries to instantiate it before any Store is created. Just put StoreDevtoolsModule AFTER StoreModule.forRoot in AppModule decorator imports array to fix the issue.

imports: [
  StoreModule.forFeature(featureKey, {items: itemsReducer}),
  StoreModule.forRoot({}),
  StoreDevtoolsModule.instrument({ maxAge: 25, logOnly: environment.production }),

Now it works good:

Interesting that in Angular 9 putting StoreModule.forFeature BEFORE StoreModule.forRoot doesn't create any issue.

You can find the code to play with here.

#4. Exported reducer function is necessary as function calls are not supported by the AOT compiler (in Angular 8).

The title of this pitfall sounds not clear but actually it is very simple. You have reducer:

export const counterReducer = createReducer(initialState,
  on(increment, state => state + 1),
  on(decrement, state => state - 1),
  on(reset, state => 0),
);

@NgModule({
  declarations: [],
  imports: [
    StoreModule.forRoot({ count: counterReducer })
  ],
  providers: [],
})
export class CounterStateModule { }

And it works quite well…until we try to build the production code:

ERROR in Error during template compile of 'CounterStateModule'
  Function calls are not supported in decorators but 'createReducer' was called in 'counterReducer'
    'counterReducer' calls 'createReducer' at app/counter.state.ts

This is a well-know issue, you can read more about it here.

Fortunately, when I tested it on Angular 9 project with Ivy (ngRx/Store 8.6) — it was already solved! You can read more details in this issue.

You can check the code here.

Takeaway: update to Angular 9 😎

#5. Action creator is a function but if you forget to put parentheses — ngRx keeps silence.

Here is a possible pitfall reproduce code:

constructor(private store: Store<{ count: number }>) {
}

selectAll() {
  this.store.dispatch(select);//should be select() but no type error
}
unselectAll() {
  this.store.dispatch(unselect()); // correct
}

Typescript will not help you here. But fortunately, you will find a hint in ChromeDevTools console:

Takeaway: Do not put all eggs in typescript basket 🎓 Sometimes it may not help you.

Conclusion

Ok, so what we have learned in this article?

1. Use null instead of undefined as noValue to be able to observe it in ReduxDevTools Chrome plugin.
2. StoreDevModule may slow down the app. To prevent it — set logOnly option as true.
3. Do not forget to put StoreModule.forRoot({}) in AppModule when you connect other ngrx/Store feature modules.
4. Exported reducer function is not necessary in Angular 9.
5. Do not forget to put parentheses in your call action creator function.

Now you can spend more time with your family but not in debugging sessions⛷

Let’s keep in touch on Twitter!

BTW. I started a video tutorial series “Angular can waste your time” on Youtube. There I will be publishing videos about resolving tricky cases with Angular and RxJS. Take a look!

Cheers!

ngRx/Store and 5 silly mistakes was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

Let's find out (CUSTOM_ELEMENTS_SCHEMA, NO_ERRORS_SCHEMA, etc).

*Angular 8.2 source code is used for this article.

AngularInDepth is moving away from Medium. More recent articles are hosted on the new platform inDepth.dev. Thanks for being part of indepth movement!

I bet every Angular developer met such an error message in ChromeDevTools console:

Usually, this means you forgot to add a component to the module — so Angular doesn’t know anything about it.
Sometimes this error is shown on native HTML tags:

You can watch these errors by running article demo project here.

Yes, we can solve it by using [attr.someAttr]=”someValue” notation, but how does Angular know that button doesn’t have such an attribute? And can we somehow omit Angular checking for our specific cases (custom elements out of Angular scope or some specific attributes)?
This is time to introduce ElementSchemaRegistry from ‘@angular/compiler’ package.

A more elaborate version of this article is available here.

Prolog

Angular uses two ways to check component templates to be good:
1. Generating Type Checking Blocks — you can read more about it in Alexey Zuev article here.

2. Angular compiler instance uses TemplateParser which runs DomElementSchemaRegistry (implementation of ElementSchemaRegistry) methods for checking of template AST (Abstract syntax tree) nodes validity.

ElementSchemaRegistry is an abstract class that defines an interface for schema class for Angular to check its component templates (if there is such an element or if such attr exists for a specific element, etc). Here it is:

import {SchemaMetadata, SecurityContext} from '../core';

export abstract class ElementSchemaRegistry {

abstract hasProperty(tagName: string, propName: string, schemaMetas: SchemaMetadata[]): boolean;

abstract hasElement(tagName: string, schemaMetas: SchemaMetadata[]): boolean;

abstract securityContext(elementName: string, propName: string, isAttribute: boolean): SecurityContext;

abstract allKnownElementNames(): string[];

abstract getMappedPropName(propName: string): string;

abstract getDefaultComponentElementName(): string;

abstract validateProperty(name: string): {error: boolean, msg?: string};

abstract validateAttribute(name: string): {error: boolean, msg?: string};

abstract normalizeAnimationStyleProperty(propName: string): string;

abstract normalizeAnimationStyleValue(camelCaseProp: string, userProvidedProp: string, val: string|number): {error: string, value: string};

}

As you can see that it has specific methods to check if some element or some attribute exists: hasElement and hasAttribute.

How does it work under-the-hood?

DomElementSchemaRegistry extends ElementSchemaRegistry

For browser elements checking we have a special class DomElementSchemaRegistry. All DOM entities and its respective attributes are defined there. Here it is:

const SCHEMA: string[] = [  '[Element]|textContent,%classList,className,id,innerHTML,*beforecopy,*beforecut,*beforepaste,*copy,*cut,*paste,*search,*selectstart,*webkitfullscreenchange,*webkitfullscreenerror,*wheel,outerHTML,#scrollLeft,#scrollTop,slot' +      /* added manually to avoid breaking  changes */      
...
'base^[HTMLElement]|href,target',  'body^[HTMLElement]|aLink,background,bgColor,link,*beforeunload,*blur,*error,*focus,*hashchange,*languagechange,*load,*message,*offline,*online,*pagehide,*pageshow,*popstate,*rejectionhandled,*resize,*scroll,*storage,*unhandledrejection,*unload,text,vLink',  'button^[HTMLElement]|!autofocus,!disabled,formAction,formEnctype,formMethod,!formNoValidate,formTarget,name,type,value',  'canvas^[HTMLElement]|#height,#width',  'content^[HTMLElement]|select',  'dl^[HTMLElement]|!compact',  'datalist^[HTMLElement]|',  'details^[HTMLElement]|!open',  'dialog^[HTMLElement]|!open,returnValue',  'dir^[HTMLElement]|!compact',  'div^[HTMLElement]|align',  'embed^[HTMLElement]|align,height,name,src,type,width',  'fieldset^[HTMLElement]|!disabled,name',
...
  'span^[HTMLElement]|',  'style^[HTMLElement]|!disabled,media,type',  'caption^[HTMLElement]|align',  'th,td^[HTMLElement]|abbr,align,axis,bgColor,ch,chOff,#colSpan,headers,height,!noWrap,#rowSpan,scope,vAlign,width',  'col,colgroup^[HTMLElement]|align,ch,chOff,#span,vAlign,width',  'table^[HTMLElement]|align,bgColor,border,%caption,cellPadding,cellSpacing,frame,rules,summary,%tFoot,%tHead,width',  'tr^[HTMLElement]|align,bgColor,ch,chOff,vAlign',  'tfoot,thead,tbody^[HTMLElement]|align,ch,chOff,vAlign',  'template^[HTMLElement]|',  'textarea^[HTMLElement]|autocapitalize,!autofocus,#cols,defaultValue,dirName,!disabled,#maxLength,#minLength,name,placeholder,!readOnly,!required,#rows,selectionDirection,#selectionEnd,#selectionStart,value,wrap',  'title^[HTMLElement]|text',  'track^[HTMLElement]|!default,kind,label,src,srclang',  'ul^[HTMLElement]|!compact,type',  'unknown^[HTMLElement]|',  'video^media|#height,poster,#width',
...

And the list is created by exporting browser IDL (interface description language) as we can see from compiler-cli/src/ngtsc/typecheck/src/dom.ts file comments (one of the places where DomElementSchemaRegistry is instantiated).

`DomElementSchemaRegistry`, a schema * maintained by the Angular team via extraction from a browser IDL.

OK, so we have a list of DOM entities and set of methods for checking whether an HTML template is valid. How does Angular use it?

How is DomElementSchemaRegistry used?

a) AotCompiler (angular/packages/platform-browser-dynamic/src/compiler_factory.ts)

1. Typescript ts.createProgram starter needs compiler instance from compiler factory function
2. compiler_factory (lets review AOT) creates schemaParser and feed it to new TemplateParser(…) statement and then templateParser instance are fed to compiler instance constructor (here)

export function createAotCompiler(

compilerHost: AotCompilerHost, options: AotCompilerOptions,

errorCollector?: (error: any, type?: any) =>

void): {compiler: AotCompiler, reflector: StaticReflector} {

...

const elementSchemaRegistry = new DomElementSchemaRegistry();

const tmplParser = new TemplateParser(

config, staticReflector, expressionParser, elementSchemaRegistry, htmlParser, console, []);

...

const compiler = new AotCompiler(

config, options, compilerHost, staticReflector, resolver, tmplParser,

new StyleCompiler(urlResolver), viewCompiler, typeCheckCompiler,

new NgModuleCompiler(staticReflector),

new InjectableCompiler(staticReflector, !!options.enableIvy), new TypeScriptEmitter(),

summaryResolver, symbolResolver);

return {compiler, reflector: staticReflector};

}

3.
a) Сompiler instance has two(actually more but we review these two) methods _compileComponent and _createTypeCheckBlock.
b) These methods call _parseTemplate where templateParserInstance.parse is performed.

c) And it starts template parsing process (btw visitor pattern is used to iterate over AST nodes) where our DomElementSchemaRegistry instance and TemplateParseVisitor instance are used to check whether AST node (which represents template element) is valid.

For example here and here you can see code that represents messages at the beginning of the article:

private _assertElementExists(matchElement: boolean, element: html.Element) {

const elName = element.name.replace(/^:xhtml:/, '');

if (!matchElement && !this._schemaRegistry.hasElement(elName, this._schemas)) {

let errorMsg = `'${elName}' is not a known element:\n`;

errorMsg +=

`1. If '${elName}' is an Angular component, then verify that it is part of this module.\n`;

if (elName.indexOf('-') > -1) {

errorMsg +=

`2. If '${elName}' is a Web Component then add 'CUSTOM_ELEMENTS_SCHEMA' to the '@NgModule.schemas' of this component to suppress this message.`;

} else {

errorMsg +=

`2. To allow any element add 'NO_ERRORS_SCHEMA' to the '@NgModule.schemas' of this component.`;

}

this._reportError(errorMsg, element.sourceSpan !);

}

b) JIT compiler (angular/packages/platform-browser-dynamic/src/compiler_factory.ts)

AOT compiler creates an instance for TemplateParser explicitly (you remember that parser then uses schemaRegistry (instance of DomElementSchemaRegistry)).

//angular/angular/blob/8.2.x/packages/compiler/src/aot/compiler_factory.ts

...
const elementSchemaRegistry = new DomElementSchemaRegistry();

const tmplParser = new TemplateParser(config, staticReflector, expressionParser, elementSchemaRegistry, htmlParser, console, []);
...

For instantiating JIT Compiler Angular uses Injector to create respective dependencies instances to its compiler_factory.

// angular/angular/blob/8.2.x/packages/platform-browser-dynamic/src/compiler_factory.ts

export const COMPILER_PROVIDERS = <StaticProvider[]>[
...
{ provide: DomElementSchemaRegistry, deps: []},  
{ provide: ElementSchemaRegistry, useExisting: DomElementSchemaRegistry},
...
]

This means that for JIT build we can substitute DomElementSchemaRegistry with some custom ElementSchema class (we will talk about it later).

Now we know how it works. And? What to do with this knowledge?

Use cases

Let’s review a few cases where DomElementSchemaRegistry is used.

#1 CUSTOM_ERRORS_SCHEMA when we have custom elements in Angular application.

If you ever tried to use custom elements in Angular (you can read about it here) — you already know that to prevent template errors we need to add CUSTOM_ERRORS_SCHEMA to schemas:[] property of NgModule decorator object:

import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core

...
@NgModule({

declarations: [AppComponent],

schemas: [ CUSTOM_ELEMENTS_SCHEMA ],

...

})

export class AppModule {}

Why? Because Angular doesn't know anything about custom elements tags and treats them as some error in a template. You may think — how does adding CUSTOM_ELEMENTS_SCHEMA prevent Angular from throwing an error?

You remember that Template parser uses DomElementSchemaRegistry instance (_schemaRegistry) to check for the template node's validity.

_schemaRegistry has two methods _schemaRegistry.hasElement and _schemaRegistry. hasProperty. Let's take a look at them in compiler/src/schema/dom_element_schema_registry.ts file:

hasProperty(tagName: string, propName: string, schemaMetas: SchemaMetadata[]): boolean {

  if (schemaMetas.some((schema) => schema.name === NO_ERRORS_SCHEMA.name)) { return true; }

  if (tagName.indexOf('-') > -1) {

    if (isNgContainer(tagName) || isNgContent(tagName)) {

    return false;

    }

    if (schemaMetas.some((schema) => schema.name === CUSTOM_ELEMENTS_SCHEMA.name)) { return true;}

  }
...

}

hasElement(tagName: string, schemaMetas: SchemaMetadata[]): boolean {

  if (schemaMetas.some((schema) => schema.name === NO_ERRORS_SCHEMA.name)) { return true; }

  if (tagName.indexOf('-') > -1) {

    if (isNgContainer(tagName) || isNgContent(tagName)) { return true; }

  if (schemaMetas.some((schema) => schema.name === CUSTOM_ELEMENTS_SCHEMA.name)) { return true; }

}
...

}

Pay attention to that part:

if (tagName.indexOf('-') > -1) {

if (isNgContainer(tagName) || isNgContent(tagName)) {

return false;

}

if (schemaMetas.some((schema) => schema.name === CUSTOM_ELEMENTS_SCHEMA.name)) { return true;}

}

This means that if template tag has dash (-) in it, this tag is not ng-content and not ng-container, and CUSTOM_ELEMENTS_SCHEMA was added to ngModule schemas (schemaMetas variable) — then treat it as valid.

In other words, Angular just searches for a dash in name and if yes — treat it as custom element (so simple logic).

You can try the code in 2_CUSTOM_ELEMENTS_SCHEMA branch of the article demo project.

#2 Using NO_ERRORS_SCHEMA for unit testing

Looking at Angular code above you can also understand how NO_ERRORS_SCHEMA works:

if (schemaMetas.some((schema) => schema.name === NO_ERRORS_SCHEMA.name)) { return true; }

If we added NO_ERRORS_SCHEMA to ngModule decorator schemas prop — Angular doesn't do any checks at all.

It may be useful if you test your component but doesn't want to include child component into TestBed module configuration.

// my-parent.component.ts

@Component({
  selector: 'app-my-parent',
  template: `
    <div>
      <child></child> <!-- Don't want to instantiate child -->
    </div>
    <button (click)="doSomething()">Start</button>
  `,
  styleUrls: ['./my-parent.component.scss']
})

export class MyParentComponent {

  constructor() { }

  doSomething() {
    // some code
  }
}

// my-parent.spec.ts
...

beforeEach(async(() => {

  TestBed.configureTestingModule({

    declarations: [ MyParentComponent ],

    schemas: [ NO_ERRORS_SCHEMA ]

  }).compileComponents();

}));

Without NO_ERRORS_SCHEMA Angular will throw that it doesn't know anything about <child></child>. But if you don't want to test <child> — then now you know how to omit it:-)

BTW someone treats it as a bad practice but it's up to you to decide.

You can check the code here (3_NO_ERRORS_SCHEMA branch).

Like this article? Buy me a coffee :-)

#3. Redefine ElementSchemaRegistry with a custom class (where some exclusion rules are defined) — JIT Compiler version.

It may be needed if you use not only Angular on your web site so some custom elements (or attributes) should be added to exclusions.
I found a nice example of this case in StackOverflow issue:

There are some custom elements and attributes in component template (in this example they are used by third-party non-Angular code):

<foo></foo>
<div data-bar="{{ bar }}"></div>

They cause a compiler error:

Template parse errors:
'foo' is not a known element:

How can foo element and data-bar attribute be added to compiler schema?

And the perfect answer from Alexey Zuev:

You can try to override DomElementSchemaRegistry like this:

//main.ts

import { DomElementSchemaRegistry, ElementSchemaRegistry } from '@angular/compiler'
import { SchemaMetadata } from '@angular/core';

const MY_DOM_ELEMENT_SCHEMA = [
  'foo'
];

const MY_CUSTOM_PROPERTIES_SCHEMA = {
  'div': {
    'bar': 'string'
  }
};

export class CustomDomElementSchemaRegistry extends DomElementSchemaRegistry {
  constructor() {
    super();
  }

hasElement(tagName: string, schemaMetas: SchemaMetadata[]): boolean {
    return MY_DOM_ELEMENT_SCHEMA.indexOf(tagName) > -1 || 
         super.hasElement(tagName, schemaMetas);
  }

hasProperty(tagName: string, propName: string, schemaMetas: SchemaMetadata[]): boolean {
    const elementProperties = MY_CUSTOM_PROPERTIES_SCHEMA[tagName.toLowerCase()];
    return (elementProperties && elementProperties[propName]) || 
        super.hasProperty(tagName, propName, schemaMetas);
  }
}

platformBrowserDynamic().bootstrapModule(AppModule, {
  providers: [{ provide: ElementSchemaRegistry, useClass: CustomDomElementSchemaRegistry, deps: [] }]
});

Now Angular doesn't show template error for <foo> element.

But this example works in JIT compilation only — check the code at 4_Customizing_element_schema branch of article demo project.

Can we somehow make it work in AOT build?

#4 Redefine ElementSchemaRegistry with a custom class (where some exclusion rules are defined) — AOT Compiler version.

You remember that JIT Compiler uses COMPILER_PROVIDERS (platform-browser-dynamic/src/compiler_factory.ts#L152):

{ provide: ElementSchemaRegistry, useExisting: DomElementSchemaRegistry},

So it was easy to substitute ElementSchemaRegistrywith some other custom class (like we did in previous example).

But it is not possible to do so for AOT Compiler since in AOT compiler factory schemaRegistry is instantiated explicitly (aot/compiler_factory.ts#L86):

const elementSchemaRegistry = new DomElementSchemaRegistry();

To make previous example work in AOT build we have to somehow re-defined DomElementSchemaRegistry.hasProperty (or hasElement) methods (thanks to Alexey Zuev for providing such an approach).

How does it work?

We copy original DomElementSchemaRegistry.hasElement implementation and then expand it with esclusion code (but after that call original method as well)

To check if it works — clome this repo (branch: 4_Customizing_element_schema) and run node ng serve --aot or node ng build --aot. Pay attention that ng in that command is not Angular CLI binary ng but our ng.js file.

I implemented the code in ng-new.js file.

Just clone the project, switch to branch and run: node ng-new build --prod . No errors! (if you try ng build — prod (standard Angular CLI command) — build will fail with template errors).

Imperfections

What I noticed that even if we add an exclusion for custom attributes, like this:

<div bar="{{title}}">Angular removed bar attribute from that div silently</div>

Angular will remove bar attribute 🤔.

If we want to keep it — you have to use Angular attr notation (but in this case no need to create exclusion rule)

<div [attr.bar]="title">Angular keep bar attribute if we use [attr.bar]="" notation</div>

For custom attributes the only case that works with providing schema exclusion is non-dynamic attributes:

<div bar="NonDymanicValue">Angular removed bar attribute from that div silently</div>

Any projects where customized ElementSchema is used?

I know two projects where customized elementSchemaRegistry is used

#1 Angular Terminal Platform

How to run an Angular application in a terminal window? Easy)

And here is a link to schema-registry.ts used in a project. Nothing special — we just validate everything:

// projects/platform-terminal/src/lib/schema-registry.ts

export class TerminalElementSchemaRegistry extends ElementSchemaRegistry {

hasProperty(_tagName: string, _propName: string): boolean {
  return true;
}

hasElement(_tagName: string, _schemaMetas: SchemaMetadata[]): boolean {
return true;
}
...

// projects/platform-terminal/src/lib/platform.ts
...

{ provide: ElementSchemaRegistry, useClass: TerminalElementSchemaRegistry, deps: [] },

You already know what this means, right?😎

#2 Applications Node-GUI

A project that allows running Angular applications as desktop applications (like Electron app.)

The author uses NodeguiElementSchemaRegistry that also allows everything (returns true on any hasElement and hasProperty request). And like in Angular terminal project — we re-define ElementSchemaRegistry in COMPILER_OPTIONS in angular-nodegui/src/lib/platform-dynamic.ts file:

provide: COMPILER_OPTIONS,
  useValue: {
    providers: [{
     provide: ElementSchemaRegistry,
     useClass: NodeguiElementSchemaRegistry,
     deps: []
   }
...

Conclusion

So let's wrap up:

1. Angular uses ElementSchemaRegistry and its implementation — DomElementSchemaRegistry — to check if attributes and elements in the component's template are valid
2. An instance of DomElementSchemaRegistry is used in TemplateParser which is used in the compiler to visit all template AST Nodes (JIT and AOT).
3. We can create our custom rules for validation. It is easy for JIT (platformBrowserDynamic) compiler and a bit tricky but also possibly for AOT build.
4. We can switch off validation by proving CUSTOM_ELEMENTS_SCHEMA and NO_ERRORS_SCHEMA in ngModule config object schemas property.
5. You can find all the code I used in the article here

Did you like this article? Then clap twice 🤓

More to read:

1. Type-checking templates in Angular ViewEngine and Ivy by Alexey Zuev.
2. How Angular builds and run — very good explanatory answer on StackOverflow — here.

3. Deep, deep, deep dive into Angular compiler by Uri Shaked.

4. MockSchemaRegistry example in Angular source code: here and here.

5. Using Custom Elements in Angular.

Let’s keep in touch on Twitter!

• BTW. I started a video tutorial series “Angular can waste your time” on Youtube. There I will be publishing videos about resolving tricky cases with Angular and RxJS. Take a look!

Special thanks to Alexey Zuev, Michael Karén and Lars Gyrup Brink Nielsen for helping with and reviewing the article!

Angular ElementSchemaRegistry for “dummies” was originally published in Angular In Depth on Medium, where people are continuing the conversation by highlighting and responding to this story.

AngularInDepth is moving away from Medium. More recent articles are hosted on the new platform inDepth.dev. Thanks for being part of indepth movement!

RxJS is quite a popular library in Angular world so for me it is always interesting to find out something new about its internals. Today I want to dig into utils folder of its GitHub repo. This article is written not for some practical usage but rather for reverse engineering enthusiasts and my curiosity.

Here is a link to RxJS 6.5 /src/internal/util/ dir. This folder is full of files. Let’s review them one by one. Some of them can bring something interesting 🔍.

#1 ArgumentOutOfRangeError.ts

The main code is next:

function ArgumentOutOfRangeErrorImpl(this: any) {  
 Error.call(this);  
 this.message = 'argument out of range';  
 this.name = 'ArgumentOutOfRangeError';  
 return this;
}

ArgumentOutOfRangeErrorImpl.prototype = Object.create(Error.prototype);

export const ArgumentOutOfRangeError: ArgumentOutOfRangeErrorCtor = ArgumentOutOfRangeErrorImpl as any;

What is interesting here?

a) We inherit from built-in Error class here. So we can throw calls instance with the message we need.

b) superclass constructor is called in an explicit way: Error.call(this);

Where it is used in RxJS source code?

Let's take a look at takeLast(count) operator — it should emit last count values after the source observable is complete. Of cause it cannot accept negative count — so:

* @throws {ArgumentOutOfRangeError} When using `takeLast(i)`, it delivers an * ArgumentOutOrRangeError to the Observer's `error` callback if `i < 0`

at line 63:

if (this.total < 0) {      throw new ArgumentOutOfRangeError;    }

Why should I know this?

Reading source code can help you to understand how the library works in edge cases. And sometimes it is the only way to understand why it works how it works.

#2 EmptyError.ts

It looks very similar to ArgumentOutOfRangeError

function EmptyErrorImpl(this: any) {
  Error.call(this);
  this.message = 'no elements in sequence';
  this.name = 'EmptyError';
  return this;
}

EmptyErrorImpl.prototype = Object.create(Error.prototype);

export const EmptyError: EmptyErrorCtor = EmptyErrorImpl as any;

But the application scope is different.

Where it is used in code?

Let's review first operator — it should emit only the first value (or the first value that meets some condition) emitted by the source Observable.

But what is sequence is empty? We can find an answer at line 69 of rxjs/src/internal/operators/first.ts

* @throws {EmptyError} Delivers an EmptyError to the Observer's `error`
* callback if the Observable completes before any `next` notification was sent.
*

And this happens in lines 86–90:

return (source: Observable<T>) => source.pipe(
    predicate ? filter((v, i) => predicate(v, i, source)) : identity,
    take(1),
    hasDefaultValue ? defaultIfEmpty<T | D>(defaultValue) : throwIfEmpty(() => new EmptyError()),
  );

*Interesting remark: you can use take(1) instead of first() with almost the same result:

source$.pipe(take(1))
vs
source$.pipe(first())

The only difference that take operator will not emit EmptyError if source$ completes before producing value.

Why should I know this?
Since first operator uses EmptyError — a final code bundle should contain EmptyError.ts file too. So when you use first operator — a final bundle size will be a bit bigger. You can read more about it here.

#3 Immediate.ts

export const Immediate = {
  setImmediate(cb: () => void): number {
    const handle = nextHandle++;
    tasksByHandle[handle] = cb;
    Promise.resolve().then(() => runIfPresent(handle));
    return handle;
  },

  clearImmediate(handle: number): void {
    delete tasksByHandle[handle];
  },
};

Just a wrapper for putting tasks to microtasks queue. it is used in AsapAction which is used by RxJS AsapScheduler. Schedulers is a separate big topic, you can read more about it in my article here. But just for this case — it schedules data to be emitted in a microtask just after the current macrotask in browser EvenLoop queue.

It is done by this code:

Promise.resolve().then(() => runIfPresent(handle));

Here is a usage example in rxjs/src/internal/scheduler/AsapAction.ts:

return scheduler.scheduled || (scheduler.scheduled = Immediate.setImmediate(
      scheduler.flush.bind(scheduler, null)
    ));

Why should I know this?
Knowing how RxJS schedule tasks (by means of special entity — Scheduler) is the key part of understanding how to write unit tests for RxJS code in Angular applications.

I released FREE video-course about main unit testing tools for RxJS code. You can get it here!

If you are curious about Schedulers topic in RxJS take a look at:

1. “So how does RxJS QueueScheduler actually work?” which also contains also common Schedulers intro.
2. “RxJS: applying asyncScheduler as an argument vs with observeOn operator”
3. Videos by Michael Hladky:
   “RxJS schedulers in depth”
   “RxJS Schedulers from outer space”

Do you like the article? You can find more interesting RxJS staff in my video-course “Hands-on RxJS”. It may be interesting as for beginners (Section 1–3) as well as experiences RxJS developers (Sections 4–7). Buy it, watch it and leave comments and evaluations!

Hands-On RxJS for Web Development | Udemy

#4 ObjectUnsubscribedError.ts

function ObjectUnsubscribedErrorImpl(this: any) {
  Error.call(this);
  this.message = 'object unsubscribed';
  this.name = 'ObjectUnsubscribedError';
  return this;
}

ObjectUnsubscribedErrorImpl.prototype = Object.create(Error.prototype);

...
export const ObjectUnsubscribedError: ObjectUnsubscribedErrorCtor = ObjectUnsubscribedErrorImpl as any;

This error is thrown when someone tries to emit with closed Subject.

Where is it used in RxJS source code?

For example, in a rxjs/src/internal/Subject.ts we throw this error in case someone wants to emit using Subject which is forcefully unsubscribed all the observers by calling special Subject.unsubscribe method.

const subj = new Subject();
let subsciption = subj.subscribe(console.log);
subj.next('Before force unsubscription');
subj.unsubscribe();
subj.next('After force unsubscription'); // Throw here!

You can check this behavior in a codepen playground.

I asked Nicholas Jamieson (RxJS core team) for possible use-cases of Subject.unsubscribe method and he did a favor to answer me:

There isn’t a usecase that I would consider valid. IMO, it should be removed. All it does is drop references to all subscribers and ensure it can’t emit further notifications. It just confuses people.
AFAICT, in .NET dispose is the terminology - instead of unsubscribe - and that makes a little more sense. With the method named unsubscribe, it's misleading.

#5 TimeoutError.ts

function TimeoutErrorImpl(this: any) {
  Error.call(this);
  this.message = 'Timeout has occurred';
  this.name = 'TimeoutError';
  return this;
}

TimeoutErrorImpl.prototype = Object.create(Error.prototype);

...
export const TimeoutError: TimeoutErrorCtor = TimeoutErrorImpl as any;

If we make a search on TimeoutError in RxJS github repo we can find out that it is used for timeout operator implementation:

export function timeout<T>(due: number | Date,                           scheduler: SchedulerLike = async): MonoTypeOperatorFunction<T> {       return timeoutWith(due, throwError(new TimeoutError()), scheduler);
}

Pay attention to interesting timeoutWith operator. We can find a description of it in its source code:

`timeoutWith` is a variation of `timeout` operator. It behaves exactly the same, still accepting as a first argument either a number or a Date, which control — respectively — when values of source Observable should be emitted or when it should complete.

The only difference is that it accepts a second, required parameter. This parameter should be an Observable which will be subscribed when source Observable fails any timeout check.

So from that phrase, we can do two interesting conclusions:
1. throwError(new TimeoutError()) is the initially erred Observable that will throw with TimeoutError if no source$ emissions happen during the specified timeout.

2. By using timeoutWith operator we can provide our own Observable that will be subscribed in case no source$ emissions happen.

Quite interesting!

Takeaways

Let's wrap up what we've learned today:

1. takeLast(count) will throw on negative values.
2. Where is a diff between take(1) and first() operators: take(1) will produce a smaller bundle size.
3. RxJS uses Promise.resolve().then for so-called Immediate value emission (used by AsapScheduler).
4. You can drop all subscribers with Subject.unsubscribe method. And if after that you will try to emit — Subject will throw an error.
5. There is an interesting timeoutWith operator, that allows to provide observable which will be subscribed if source$ will not emit in specified timeout.

I hope you enjoyed the article and that it will encourage you to do (and blog:) your own discoveries!

If you like it — plz clap. If you want part 2 — clap twice :-)

Let’s keep in touch on Twitter.

Cheers!

RxJS in-depth: Github repo ‘utils’ directory review (part 1) was originally published in Angular In Depth on Medium, where people are continuing the conversation by highlighting and responding to this story.

AngularInDepth is moving away from Medium. More recent articles are hosted on the new platform inDepth.dev. Thanks for being part of indepth movement!

Every Angular developer knows Angular Material (You don't know it? Then definitely take a look). Like many other UI libraries it provides a set of form controls and among them matInput.

It is a regular text input with the possibility to display placeholder in a nice way, to add a clear button, provide custom error messages, text length hint, and even suffixes and prefixes to improve user experience. You can look at examples here.

The problem

The task I got from a customer was to display input values in digit groups for account amount form field, like this:

Surprisingly searching though the internet didn't provide some solid solutions so I decided to create my own one. I found only two things that may help:

• This interesting paragraph is on the matInput API page:

MAT_INPUT_VALUE_ACCESSOR

This token is used to inject the object whose value should be set into MatInput. If none is provided, the native HTMLInputElement is used. Directives like MatDatepickerInput can provide themselves for this token, in order to make MatInput delegate the getting and setting of the value to them

• Angular Material’s MatDatePicker expects to be applied on top of matInput so we can use its code as an example of extending matInput.

Solution

What can we take from matDatePicker code (and not only) for our goals?:
1. It redefines MAT_INPUT_VALUE_ACCESSOR provider so we can display some text value in the DOM input field (since we need digit grouping), but return numeric value for matInput validation.

2. To apply our formatting on Angular FormControl operations (like set value to form field) we also have to implement the ControlValueAccessor interface (you can read more custom form controls in Angular here).

3. And a few more things we need to implement:

• onBlur input field event should format value
• onFocus event should unformat the value so that we can edit it as a regular number
• onInput event should send a numeric representation of value with _onChange handler (ControlValueAccessor implementation)
• Since we’re going to display commas, the input type should be set as text (not a number) but we have to make validation work (for example, min and max value)

Before we start, let's create the reactive Angular form where we are going to use our form control directive:

<!-- app.component.html -->
<form [formGroup]="myForm">
  <mat-form-field appearance="outline">
    <mat-label>Deposit Amount</mat-label>
    <input matInput <- Material input
           matInputCommified <--our directive
           formControlName="deposit"
           type="text"/>
  </mat-form-field>
</form>
<button [disabled]="myForm.invalid"
        mat-raised-button
        color="primary"
        (click)="onSubmit()"
>Submit</button>

// app.component.ts
export class AppComponent {
  title = 'ngx-material-tools-demo';

  constructor(private formBuilder: FormBuilder) {
  }

  myForm = this.formBuilder.group({
    deposit: ['', [
      Validators.required, // Validators
      Validators.min(1),
      Validators.max(1000000)
    ]],
  });

  onSubmit() {
    // some operations here
  }
}

Supporting the MAT_INPUT_ACCESSOR API

If we take a look at MAT_INPUT_ACCESSOR, it requires a very simple interface:

export declare const MAT_INPUT_VALUE_ACCESSOR: InjectionToken<{
    value: any;
}>;

If we declare a MAT_INPUT_VALUE_ACCESSOR provider the matInput directive will start working with DOM input element through our directive. In fact, it will think that our directive instance is a DOM input element which has a value property.

Why do we need it? Because when we set a value we need to apply formatting with commas to separate digit groups. When we get the value we have to remove commas and return a number to the matInput instance to support Angular validators could work correctly.

So all we have to do is to provide value as both setter and getter. Let's do this:

//mat-input-commified.directive.ts
import {Directive, ElementRef, forwardRef, HostListener, Input} from '@angular/core';
import {MAT_INPUT_VALUE_ACCESSOR} from '@angular/material';
import {NG_VALUE_ACCESSOR} from '@angular/forms';
import {numberWithCommas} from './helpers';

@Directive({
  selector: 'input[matInputCommified]',
  providers: [
    {provide: MAT_INPUT_VALUE_ACCESSOR, useExisting: MatInputCommifiedDirective}
})
export class MatInputCommifiedDirective {

  private _value: string | null;

  constructor(private elementRef: ElementRef<HTMLInputElement>,
  ) {}


  get value(): string | null {
    return this._value;
  }

  @Input('value')
  set value(value: string | null) {
    this._value = value;
    this.formatValue(value);
  }

  private formatValue(value: string | null) {
    if (value !== null) { 
      this.elementRef.nativeElement.value = numberWithCommas(value);
    } else {
      this.elementRef.nativeElement.value = '';
    }
  }


}

You may think that setter here works even if we assign formControl value but no:

this.myForm.get('deposit').setValue(10)  // setter is not called

...

<input matInput <- Material input
           matInputCommified
           formControlName="deposit" 
           [value]="10" // setter is called in that case          
           type="text"/>

The setter is called only when we assign some value with [value] property binding for the matInput directive (you can check matInput source code here and run reproduce here — thanks to Alexey Zuev for providing that info!).

To make formatting work even for formControl.setValue call we have to implement the CONTROL_VALUE_ACCESSOR interface (we will do that later).

Adding onBlur, onFocus, and onInput

OK, now we have to implement the remaining behavior:

1. Format on input blur event (when we finish editing).
2. Unformat text on focus event (when we start editing we don't need commas).
3. On text typing (onInput event), we should take the input field value and save it to the internal this._value property without any non-number symbols (only 0–9, period and minus are allowed).

Let's do that:

import {Directive, ElementRef, forwardRef, HostListener, Input} from '@angular/core';
import {MAT_INPUT_VALUE_ACCESSOR} from '@angular/material';
import {NG_VALUE_ACCESSOR} from '@angular/forms';
import {numberWithCommas} from './helpers';

@Directive({
  selector: 'input[matInputCommified]',
  providers: [
    {provide: MAT_INPUT_VALUE_ACCESSOR, useExisting: MatInputCommifiedDirective}
  ]
})
export class MatInputCommifiedDirective {
  // tslint:disable-next-line:variable-name
  private _value: string | null;

  constructor(private elementRef: ElementRef<HTMLInputElement>,
  ) {
    console.log('created directive');
  }


  get value(): string | null {
    return this._value;
  }

  @Input('value')
  set value(value: string | null) {
    this._value = value;
    this.formatValue(value);
  }

  private formatValue(value: string | null) {
    if (value !== null) {
      this.elementRef.nativeElement.value = numberWithCommas(value);
    } else {
      this.elementRef.nativeElement.value = '';
    }
  }

  private unFormatValue() {
    const value = this.elementRef.nativeElement.value;
    this._value = value.replace(/[^\d.-]/g, '');
    if (value) {
      this.elementRef.nativeElement.value = this._value;
    } else {
      this.elementRef.nativeElement.value = '';
    }
  }

  @HostListener('input', ['$event.target.value'])
  onInput(value) {
    // here we cut any non numerical symbols    
    this._value = value.replace(/[^\d.-]/g, '');
  }

  @HostListener('blur')
  _onBlur() {
    this.formatValue(this._value); // add commas
  }

  @HostListener('focus')
  onFocus() {
    this.unFormatValue(); // remove commas for editing purpose
  }

}

Ok, let's check how it works now:

Nice!

Now let's implement the CONTROL_VALUE_ACCESSOR interface to format the value even if we assign it with the FormControl#setValue method.

Adding CONTROL_VALUE_ACCESSOR

In the official Angular docs we see that this interface is quite simple:

interface ControlValueAccessor {   
  writeValue(obj: any): void   
  registerOnChange(fn: any): void   
  registerOnTouched(fn: any): void   
  setDisabledState(isDisabled: boolean)?: void 
}

I will not discuss the details of implementing a custom reactive Angular form control implementations — you can read about that here.

All we have to do is to define our writeValue method (it should apply formatting on value assignment) and register our directive as a NG_VALUE_ACCESSOR Angular provider. Here’s how it will look:

import {Directive, ElementRef, forwardRef, HostListener, Input} from '@angular/core';
import {MAT_INPUT_VALUE_ACCESSOR} from '@angular/material';
import {NG_VALUE_ACCESSOR} from '@angular/forms';
import {numberWithCommas} from './helpers';

@Directive({
  selector: 'input[matInputCommified]',
  providers: [
    {provide: MAT_INPUT_VALUE_ACCESSOR, useExisting: MatInputCommifiedDirective},
    {
      provide: NG_VALUE_ACCESSOR,
      useExisting: forwardRef(() => MatInputCommifiedDirective),
      multi: true,
    }
  ]
})
export class MatInputCommifiedDirective {
  // tslint:disable-next-line:variable-name
  private _value: string | null;

  constructor(private elementRef: ElementRef<HTMLInputElement>,
  ) {
    console.log('created directive');
  }


  get value(): string | null {
    return this._value;
  }

  @Input('value')
  set value(value: string | null) {
    this._value = value;
    this.formatValue(value);
  }

  private formatValue(value: string | null) {
    if (value !== null) {
      this.elementRef.nativeElement.value = numberWithCommas(value);
    } else {
      this.elementRef.nativeElement.value = '';
    }
  }

  private unFormatValue() {
    const value = this.elementRef.nativeElement.value;
    this._value = value.replace(/[^\d.-]/g, '');
    if (value) {
      this.elementRef.nativeElement.value = this._value;
    } else {
      this.elementRef.nativeElement.value = '';
    }
  }

  @HostListener('input', ['$event.target.value'])
  onInput(value) {
    this._value = value.replace(/[^\d.-]/g, '');
    this._onChange(this._value); // here to notify Angular Validators
  }

  @HostListener('blur')
  _onBlur() {
    this.formatValue(this._value);
  }

  @HostListener('focus')
  onFocus() {
    this.unFormatValue();
  }

  _onChange(value: any): void {
  }

  writeValue(value: any) {
    this._value = value;
    this.formatValue(this._value); // format Value
  }

  registerOnChange(fn: (value: any) => void) {
    this._onChange = fn;
  }

  registerOnTouched() {
  }

}

The code is quite self-explanatory but please note that to make Angular run validators against the entered value we should run the registered _onChange handler every time the value is changed. So we call it inside onInput method.

Let's check how our directive works now:

LGTM!

Publishing matInputCommified directive in the ngx-material-tools library

To be able to use our directive in other projects I've published it as part of the ngx-material-tools package.

You can use it this way:

npm i matInputCommified
....

// in app.module.ts
...
imports: [
  BrowserModule,
  BrowserAnimationsModule,
  MatCardModule,
  MatInputModule,
  MatFormFieldModule,
  MatButtonModule,
  NgxMaterialToolsModule, // <-- here is our module
  ReactiveFormsModule
],
...

<!-- app.component.html -->
<form [formGroup]="myForm" style="margin-top: 20px">
  <mat-form-field appearance="outline">
    <mat-label>Deposit Amount</mat-label>
    <input matInput
           matInputCommified 
           formControlName="deposit"
           type="text"/>
  </mat-form-field>
</form>

You can check how it works in this playground. Voila!

Did you like this article? Clap 🤓

Like this article? Buy me a coffee :-)

Further reading

1. Using ControlValueAccessor to Create Custom Form Controls in Angular
2. MatDatePicker input source code
3. Yaml-input directive source code
4. Adding Integrated Validation to Custom Form Controls in Angular

Conclusion

Hope someone read this text at the end of the article — if you’re one of those peeps then Merry Christmas to you and happy holidays!🎅

Special thanks to Alexey Zuev and Lars Gyrup Brink Nielsen for helping with and reviewing the article!

Angular Material matInput control with thousands separator was originally published in Angular In Depth on Medium, where people are continuing the conversation by highlighting and responding to this story.

AngularInDepth is moving away from Medium. More recent articles are hosted on the new platform inDepth.dev. Thanks for being part of indepth movement!

You may already know that Observables produce values over time. And the moment when exactly value will be emitted is controlled by a special entity — scheduler. But what is VirtualTimeScheduler? Is it possible to emit values in a virtual time? More about it in this article!

Prerequisites: you can read about RxJS Schedulers in this article or can watch this video.

Why?

To understand why you may need VirtualTimeScheduler first let's try to test such code:

getData(timeSec) {
  return this.http.get('some_url')
    .pipe(
      repeatWhen((n) => n.pipe(
        delay(timeSec * 1000),
        take(2)
      ))
    );
}

Here we make HTTP call with this.http.get function and if it succeeds it will repeat HTTP calls two more times after specified timeout.

So obviously AsyncScheduler is used by RxJS delay operator. (You remember — you can get familiar with schedulers here or here 😎)

The simplest method for testing async code is by using jasmine done callback. When a specific test is executed, jasmine holds and waits until done callback is called. So if data is provided asynchronously — we subscribe to them, run assertion when after we got all the data and then run done callback to say jasmine that we can continue. The test may look like this:

it('should emit 3 specific values', (done) => {
  const range$ = service.getData(0.01);
  const result = [];
  mockHttp = {get: () => of(42, asyncScheduler)};


  range$.subscribe({
    next: (value) => {
      result.push(value);
    },
    complete: () => {
      expect(result).toEqual([42, 42, 42]);
      done();
    }
  });

});

And in this example a drawback of jasmine done callback is becoming obvious — we cannot test code that has some big delays time. Since otherwise tests run will be too long.

How to omit it?

We can provide a smaller delay time. That's why in test code you can see that we call getData with very little value. You may ask — how to test code that uses big-time delays? And before RxJS version 6 provided TestScheduler.run method and time-progressive syntax marbles (you remember — this article is not about marble testing but about VirtualTimeScheduler😉)— we could use RxJS VirtualTimeScheduler for that.

If you are interesting in TestScheduler.run and all this modern testing RxJS staff - you may read nice articles by @kevinkreuzer or you can watch my free video-course: "RxJS unit testing in Angular application. The whole picture."

VirtualTimeScheduler

So testing Observables with jasmine done callback method is not good for big delay values. And this is where VirtualTimeScheduler can help us. It provides a virtual time mechanism so you can emulated passed time inside RxJS scheduler to run delayed tasks instantly.

In RxJS If we want to emit values with some specified delays — then AsyncScheduler is used. AsyncScheduler uses setInterval internally to schedule value emissions. What we need for testing such code is to make somehow run scheduled tasks instantly but with keeping the order of values.

VirtualTimeScheduler can do that since it inherits from AsyncScheduler and re-defined some internal methods.

If we replace AsyncScheduler instance with VirtualTimeScheduler instance in our function — then VirtualTimeScheduler prevents calling real setInterval and put a task in an internal queue (sorted by delay)

And when we call VirtualTimeScheduler instance flush function — all the delayed values will be emitted with keeping the order of values. Here you can see how it is implemented under the hood:

You may observable that we can also specify maxFrames threshold, so only specific tasks are executed which are delayed not more than the threshold value.

Now our code has to be changed — new scheduler param is added:

getData(timeSec, scheduler = asyncScheduler) {
  return this.http.get('some_url')
    .pipe(
      repeatWhen((n) => n.pipe(
        delay(timeSec * 1000, scheduler),
        take(2)
      ))
    );
}

Test code will look like:

it('should emit 3 specific values', () => {
  const scheduler = new VirtualTimeScheduler();
  service.http = {get: () => of(42, scheduler)};

  const range$ = service.getData(30, scheduler); // scheduler param
  const result = [];

  range$.subscribe({
    next: (value) => {
      result.push(value);
    }
  });

  scheduler.flush();
  expect(result).toEqual([42, 42, 42]);
});

Here are steps for writing unit tests with VirtualTimeScheduler:

1. We feed VirtualTimeScheduler to our code instead of AsyncScheduler. So there should be another scheduler param in our methods.

2. Then we get observable and subscribe to it. (you remember that cold observable is started only on subscription)

3. After that, we call flush() method that makes virtual time pass.

4. And check the final result

VirtualTimeScheduler vs TestScheduler

VirtualTimeScheduler has a child class — TestScheduler. TestScheduler has methods for marble testing.

Since TestScheduler is a child class of VirtualTimeScheduler we can take our tests with VirutlaTimeScheduler and replace its instance with TestScheduler instance.

But there are some small things you have to know not to waste time for possible issues debugging:

1. Testscheduler maxFrame value is set to 750 milliseconds — this is done as sanity checks for marble testing. So if your code delays are bigger then that value — you should reassign it. In our case, since we do not run marble testing — we have to assign Infinity value to prevent test blocking.

2. TestScheduler also demands assertion expression when you want to create an instance. This assertion is used in marble testing.

Not to test your patience — I provide the same test code with TestScheduler:

it('should emit 3 specific values', () => {
  const assertion = (actual, expected) => {
    expect(actual).toEqual(expected);
  };
  const scheduler = new TestScheduler(assertion);
  scheduler.maxFrames = Number.POSITIVE_INFINITY;

  service.http = {get: () => of(42, scheduler)};

  const range$ = service.getData(30, scheduler);
  const result = [];

  range$.subscribe({
    next: (value) => {
      result.push(value);
    }
  });

  scheduler.flush();
  expect(result).toEqual([42, 42, 42]);
});

Using TestScheduler just like VirtualTimeScheduler has the same imperfection — it is not visual and we can check only the final result. But marble testing and progressive time syntax can solve all these challenges. How? You can find it in free video-course "RxJS unit testing in Angular application. The whole picture."

Conclusion

Time to sum up.

VirtualTimeScheduler method has such pros:

1. We can provide real production delay values
2. We can test even hardcoded values — since timespans will pass instantly.

But this method has such imperfections:

1. It allows testing only the final result (after Observable is complete).
2. And additional method param is needed
3. "Using the VirtualTimeScheduler won’t help if the code under test also includes time-related, non-RxJS code, as the virtual (RxJS level mocking) and fake time (setTimeout, setInterval monkey patching) concepts differ significantly." by Nicholas Jamieson
   To omit this con you should use fakeAsync Angular helper function instead of VirtualTimeScheduler.

*Remarks: After releasing RxJS version 6 with TestScheduler.run method you should definitely use marble testing for making unit-tests. All test examples with VirtualTimeScheduler in this article were provided just to understand the topic better. But of cause may be used if you find it suitable.

More to read

1. "Tools for RxJS code unit testing in Angular 8 apps"
2. "RxJS: Testing with Fake Time"
3. "Testing Asynchronous Code in Angular Using FakeAsync"
4. Articles by Kevin Kreuzer about RxJS unit testing.

Did you like the article? Clap👏 🤓

Let’s keep in touch on Twitter!

*BTW. I started a video tutorial series “Angular can waste your time” on Youtube. There I will be publishing videos about resolving tricky cases with Angular and RxJS. Take a look!

So what is RxJS VirtualTimeScheduler? was originally published in Angular In Depth on Medium, where people are continuing the conversation by highlighting and responding to this story.

AngularInDepth is moving away from Medium. More recent articles are hosted on the new platform inDepth.dev. Thanks for being part of indepth movement!

Prerequisites: you should be familiar with the Angular framework and Angular CLI.

Introduction

Time to time on my daily tasks I have to implement some functionality that was already implemented by someone previously in a neat vanillaJS library, but… no Angular version or even ES6 module of it is available to be able to easily grab it into your Angular 8 application.

Yes, you can attach this lib in index.html with script tag but from my point of view, it hardens maintainability. Also, you should do the same for another Angular project where you might use it.

Much better for is create Angular wrapper directive (or component) and publish it as npm package so everyone (and you of course:) can easily re-use it in another project.

One of such libraries is mark.js — quite solid solution for highlighting search text inside a specified webpage section.

How mark.js works

In original implementation mark.js can be connected to a project in two ways:

$ npm install mark.js --save-dev

// in JS code
const Mark = require('mark.js');
let instance = new Mark(document.querySelector("div.context"));
instance.mark(keyword [, options]);

OR

<script src="vendor/mark.js/dist/mark.min.js"></script>

// in JS code
let instance = new Mark(document.querySelector("div.context"));
instance.mark(keyword [, options]);

And the result looks like this:

You can play with it more on mark.js configurator page.

But can we use it in Angular way? Say, like this

// some Angular module
imports: [
...
MarkjsModule // imports markjsHighlightDirective
...
]

// in some component template
<div class="content_wrapper" 
     [markjsHighlight]="searchValue"
     [markjsConfig]="config"
>

Let's also add some additional functionality. Say, scroll content_wrapper to first highlighted word:

<div class="content_wrapper" 
     [markjsHighlight]="searchText"
     [markjsConfig]="config"
     [scrollToFirstMarked]="true"
>

Now let's implement and publish Angular library with a demo application that will contain markjsHighlightDirective and its module.
We will name it ngx-markjs.

Planning Angular project structure

To generate an Angular project for our lib we will use Angular CLI.

npm install -g @angular/cli

Now let's create our project and add ngx-markjs lib to it:

ng new ngx-markjs-demo --routing=false --style=scss
// a lot of installations goes here

cd ngx-markjs-demo

ng generate lib ngx-markjs

And now lets add markjsHighlightDirective starter to our ngx-markjs lib

ng generate directive markjsHighlight --project=ngx-markjs

After deleting ngx-markjs.component.ts and ngx-markjs.service.ts in projects/ngx-markjs/src/lib/ folder which were created automatically by Angular CLI we will get next directory structure for our project:

To conveniently build our library lets add two more lines in a project package.json file to scripts section:

"scripts": {
  "ng": "ng",
  "start": "ng serve --port 4201",
  "build": "ng build",
  "build:ngx-markjs": "ng build ngx-markjs && npm run copy:lib:dist", 
  "copy:lib:dist": "cp -r ./projects/ngx-markjs/src ./dist/ngx-markjs/src",
  "test": "ng test",
  "lint": "ng lint",
  "e2e": "ng e2e"
},

build:ngx-markjs — runs build for ngx-markjs library (but not for parent demo project)

copy:lib:dist — it is convenient to have source files in npm packages as well, so this command will copy library sources to /dist/ngx-markjs folder (where compiled module will be placed after build:ngx-markjs command).

Now time to add implementation code!

*Remark: official Angular documentation about creating libraries recommends generating starter without main parent project, like this:
ng new my-workspace — create-application=false
But I decided to keep the main project and make it a demo application just for my convenience.

Connecting commonJS lib into Angular app

We need to do a few preparational steps before we start implementing our directive:

#1. Load mark.js

Mark.js library which we want to wrap is provided in CommonJS format.

There are two ways to connect script in CommonJS script:

a) Add it with script tag to index.html:

<script src="vendor/mark.js/dist/mark.min.js"></script>

b) Add it to angular.json file in a project root so Angular builder will grab and applied it (as if it was included with a script tag)

"sourceRoot": "src",
"prefix": "app",
"architect": {
  "build": {
    "builder": "@angular-devkit/build-angular:browser",
    "options": {
      "outputPath": "dist/ngx-markjs-demo",
      "index": "src/index.html",
      "main": "src/main.ts",
      "polyfills": "src/polyfills.ts",
      "tsConfig": "tsconfig.app.json",
      "aot": false,
      "assets": [
        "src/favicon.ico",
        "src/assets"
      ],
      "styles": [
        "src/styles.scss"
      ],
      "scripts": []
    },

#2. Adding mark.js to lib package.json

Now we should add mark.js lib as a dependency to our library package.json in <root>/projects/ngx-markjs/src folder (don't mix it up with src/package.json — file for main parent project).
We can add it as peerDependencies section — in that case, you should install mark.js manually prior to installing our wrapper package.

Or we can add mark.js to dependencies section — then mark.js package will be installed automatically when you run npm i ngx-markjs.

You can read more about the difference between package.json dependencies and peerDependencies in this great article.

#3. Get entity with require call.

const Mark = require('mark.js');

In our case, I would prefer to use require since mark.js code should be present only inside markjsHighlight lib module but not in whole application (until we use actually it there).

Small remark: some tslint configurations prevent using require to stimulate using es6 modules, so in that case just wrap require with /* tslint: disabled */ comment. Like this:

/* tslint:disable */
const Mark = require('mark.js');
/* tslint:enable */

The project is ready. Now it is time to implement our markjsHighlightDirective.

Wrapping mark.js in a directive

Ok, so lets plan how our markjsHighlightDirective will work:

1. It should be applied to the element with content — to get HTML element content where the text will be searched. (markjsHighlight input)
2. It should accept mark.js configuration object (markjsConfig input)
3. And we should be able to switch on and off 'scroll to marked text' feature (scrollToFirstMarked input)

For example:

<div class="content_wrapper" 
     [markjsHighlight]="searchText"
     [markjsConfig]="config"
     [scrollToFirstMarked]="true"
>

Now it is time to implement these requirements.

Adding mark.js to the library

Install mark.js to our project

npm install mark.js

And create its instance in a projects/ngx-markjs/src/lib/markjs-highlight.directive.ts file:

import {Directive} from '@angular/core';


declare var require: any;
const Mark = require('mark.js');


@Directive({
  selector: '[markjsHighlight]'
})
export class MarkjsHighlightDirective {

  constructor() {}

}

To prevent Typescript warnings — I declared require global variable.

Creating a basic directive starter

The very first starter for MarkjsHighlightDirective will be

@Directive({
  selector: '[markjsHighlight]' // our directive
})
export class MarkjsHighlightDirective implements OnChanges {

  @Input() markjsHighlight = '';  // our inputs
  @Input() markjsConfig: any = {};
  @Input() scrollToFirstMarked: boolean = false;

  @Output() getInstance = new EventEmitter<any>();

  markInstance: any;

  constructor(
    private contentElementRef: ElementRef, // host element ref
    private renderer: Renderer2 // we will use it to scroll
  ) {
  }

  ngOnChanges(changes) {  //if searchText is changed - redo marking

    if (!this.markInstance) { // emit mark.js instance (if needeed)
      this.markInstance = new Mark(this.contentElementRef.nativeElement);
      this.getInstance.emit(this.markInstance);
    }

    this.hightlightText(); // should be implemented

    if (this.scrollToFirstMarked) {
      this.scrollToFirstMarkedText();// should be implemented
    }    
  }
}

Ok, so let's go through this starter code:

1. We defined three inputs for searchText value, config and scrolling on/off functionality (as we planned earlier)
2. ngOnChanges lifeCycle hook emits instance of Mark.js to parent component (in case you want to implement some additional Mark.js behavior)
   Also, each time searchText is changed we should redo text highlight (since search text is different now) — this functionality will be implemented in this.hightlightText method.
   And if scrollToFirstMarked is set to true — then we should run this.scrollToFirstMarkedText.

Implementing highlight functionality

Our method this.hightlightText should receive searchText value, unmark previous search results and do new text highlighting. It can be successfully done with this code:

hightlightText() {
  this.markjsHighlight = this.markjsHighlight || ''; 

  if (this.markjsHighlight && this.markjsHighlight.length <= 2) {
    this.markInstance.unmark();
    return;

  } else {

    this.markInstance.unmark({
      done: () => {
        this.markInstance.mark((this.markjsHighlight || ''), this.markjsConfig);
      }
    });
  }
}

Code is self-explanatory: we check if markjsHighlight valur is not null or undefined (because with these values Mark.js instances throw the error).

Then check for text length. If it is just one letter or no text at all — we unmark text and return;

Otherwise, we unmark previously highlighted text and start new highlighting process.

Implementing a "scroll to first marked result" feature

One important remark here before we start implementing scroll feature: content wrapper element, where we apply our directive to should have css position set other than static (for example position: relative). Otherwise offset to be scrolled to will be calculated improperly.

OK, lets code this.scrollToFirstMarkedText method:

constructor(
  private contentElementRef: ElementRef,
  private renderer: Renderer2
) {
}
....

scrollToFirstMarkedText() {
  const content = this.contentElementRef.nativeElement;

// calculating offset to the first marked element
  const firstOffsetTop = (content.querySelector('mark') || {}).offsetTop || 0; 

  this.scrollSmooth(content, firstOffsetTop); // start scroll
}

scrollSmooth(scrollElement, firstOffsetTop) {
  const renderer = this.renderer;

  if (cancelAnimationId) {
    cancelAnimationFrame(cancelAnimationId);
  }
  const currentScrollTop = scrollElement.scrollTop;
  const delta = firstOffsetTop - currentScrollTop;

  animate({
    duration: 500,
    timing(timeFraction) {
      return timeFraction;
    },
    draw(progress) {
      const nextStep = currentScrollTop + progress * delta;

     // set scroll with Angular renderer
     renderer.setProperty(scrollElement, 'scrollTop', nextStep);
    }
  });
}

...
let cancelAnimationId;

// helper function for smooth scroll
function animate({timing, draw, duration}) {
  const start = performance.now();
  cancelAnimationId = requestAnimationFrame(function animate2(time) {
    // timeFraction goes from 0 to 1
    let timeFraction = (time - start) / duration;
    if (timeFraction > 1) {
      timeFraction = 1;
    }
    // calculate the current animation state
    const progress = timing(timeFraction);
    draw(progress); // draw it
    if (timeFraction < 1) {
      cancelAnimationId = requestAnimationFrame(animate2);
    }
  });
}

How it works:

1. We get content wrapper element (injected in a constructor by Angular) and query for first highlighted text node (Mark.js to highlight text wrap it in <Mark></Mark> HTML element).
2. Then start this.scrollSmooth function. scrollSmooth cancels previous scroll (if any), calculates scroll difference, delta (diff between current scroll position and offsetTop of marked element) and call an animated function which will calculate timings for smooth scrolling and do actual scroll (by calling renderer.setProperty(scrollElement, ‘scrollTop’, nextStep)).
3. Animate function is a helper taken from a very good javascript learning tutorial site javscript.info.

Our directive is ready! You can take a look at a full code here.

The only thing we have to do yet is to add a directive to NgxMarkjsModule module:

import { NgModule } from '@angular/core';
import { MarkjsHighlightDirective } from './markjs-highlight.directive';



@NgModule({
  declarations: [MarkjsHighlightDirective],
  imports: [
  ],
  exports: [MarkjsHighlightDirective]
})
export class NgxMarkjsModule { }

Applying Result

Now let's use it in our demo application:

1. Import NgxMarkjsModule to app.module.ts:

...
import {NgxMarkjsModule} from 'ngx-markjs';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    NgxMarkjsModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

2. I added some content to app.component.html and applied the directive to it:

<div class="search_input">
  <input placeholder="Search..." #search type="text">
</div>
<div class="content_wrapper"
     [markjsHighlight]="searchText$ | async"
     [markjsConfig]="searchConfig"
     [scrollToFirstMarked]="true"
>
  <p>Lorem ipsum dolor ssit amet, consectetur...a lot of text futher</p>

3. In app.component.ts we should subscribe to input change event and feed search text to markjsHighlight directive with async pipe:

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent implements AfterViewInit {
  title = 'ngx-markjs-demo';
  @ViewChild('search', {static: false}) searchElemRef: ElementRef;
  searchText$: Observable<string>;
  searchConfig = {separateWordSearch: false};

  ngAfterViewInit() {
    // create stream from inpout change event with rxjs 'from' function

    this.searchText$ = fromEvent(this.searchElemRef.nativeElement, 'keyup').pipe(
      map((e: Event) => (e.target as HTMLInputElement).value),
      debounceTime(300),
      distinctUntilChanged()
    );
  }
}

Let's start it and take a look at result:

ng serve

We did it!
The last thing to do: we should publish our directive to npm registry:

npm login
npm build:ngx-markjs
cd ./dist/ngx-markjs
npm publish

And here it is in a registry: ngx-markjs.

Conclusion

Did you meet some neat vanillaJS library which you want to use in Angular? Now you know how to do that!

Pros

1. Now we can easily import our directive in Angular 8 project.
2. Additional scroll functionality is quite neat — use it to improve user experience.

Cons

1. Possibly mark.js implemented only for a browser. So if you plan to use it in some other platforms (Angular allows it — read more about it here) — it may not work.

Related links:

1. Mark.js
2. ngx-markjs github repo.

More to read:

1. Angular Platforms in depth. Part 1.
2. Creating a Library with Angular CLI.
3. Making an Angular project mono repo

Hope you enjoyed the article. If yes —tweet about it and follow me on Twitter.

*It was originally published in codementor.io community blog.

Special thanks to Tim Deschryver and Lars Gyrup Brink Nielsen for reviewing this article.

Wrapping CommonJS library in Angular 8 directive on the example of mark.js was originally published in Angular In Depth on Medium, where people are continuing the conversation by highlighting and responding to this story.

Why, how and where for those who like RxJS :-)

Prerequisites: I assume you know RxJS and have some practice with it. If you are new to it or want to learn some advanced topics - watch my video-course "Hands-on RxJS for Web development" on Udemy.

Why

Periodically in my development practice, I meet situations when you have to emit a few values in specified timeouts.

For example:

1. To show and then hide some splash-message:

2. To do some nice animations

3. Or even just emit values for unit tests (yeah, I know about marbles, but sometimes I just want to check final value, period:)

So how it can be implemented? Ok, let's review some scenarios:

How to implement?

Ugly way

Ok, the simplest way — to run many setTimeout's, like this:

OK, not so bad, but what if I want to show more elements in different delays?

Looks oldschool and ugly. Can we do better?

Ugly way, part 2

Lets use RxJS now and try to implement it:

This code doesn't allow absolute delay (when the next emission is delayed against start/subscription moment).

To implement absolute delays approach (all delays are specified against subscription/start moment) we can use mergeMap instead of concatMap:

Looks like a lot of code, and also delays are hardcoded. We can do better. So let's go further!

Editor choice method

Ok, we already know that hardcoding values/delays is not reusable, and we also want to be able to schedule in relative (delayed against previous emissions) and non-relative/absolute (delayed against subscription moment) way. Taking all the above into account, I implemented a custom timeRange function.

Benefits:

1. Looks nice and compact.
2. Allows both absolute and relative delays to be specified.

OK, now let's show three use-cases I mentioned previously.

Where to use it

#1 Splash-message control example

Here it implementation code:

What do we do here?

1. Emit two values with 1000 and 2000 delay (values don't play any role here, actually only timings matter)
2. The first value will show splash element with a message.
3. Second will hide it (using .classList.toggle('show'))

Here is how it works:

You can play with it in a codepen here.

#2 Animating a few elements subsequent appearance

Here is the code:

We just grab a set of elements and then show them one by one with specified timeouts on each range$ Observable emission.

Here is the result:

You can check the code here.

#3 Mocking input params for unit tests code with timeRange.

How it works:

1. We mock ajax.get with a function that will return value '42' asynchronously (emulation of network request)
2. Then se debounce time = 15ms.
3. After that call getSearchResult with mocked input$ as a param and subscribe (to start the process).
4. input$ will emit three values with delays 1ms, 5ms, 30ms. Since debounceTime is set to 15ms, only second and third values will cause network request to be called (ajax.get in our case);

And result:

The code and the test can be found here.

Conclusion

I've added timeRange function to my rxjs-toolbox lib. It is not big for now. You can read more about it here: ‘forkJoin’ with the progress of completion

Have your own interesting RxJS solutions? Mention them in comments!

Did you like this article? Then tweet about it and follow me on Twitter 🤓!

Want to learn more about RxJS? Give a try to my video-course "Hands-on RxJS". It contains both total beginners content and more advanced topics as well.

Cheers.

TimeRange — RxJS custom function that emits a set of values in specified timeouts was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.