DEV Community: Fábio Englert Moutinho

Getting Started with RxJS: All You Need to Know About Observables

Fábio Englert Moutinho — Wed, 16 Nov 2022 13:17:49 +0000

RxJS is a library that combines the Observer pattern—where Observables or Subjects notify Observers of state changes—with functional programming to handle data changes over time.

When programming with RxJS, you are usually:

Creating Observables to subscribe later
Creating new Observables by piping existing Observables
Subscribing to Observables to get data

As Observables are “the most basic building block of RxJS", having a solid understanding of Observables is paramount to becoming proficient in RxJS.

In this blog post, you’ll learn what an Observable is, the different types of Observables and how they are helpful.

What is an Observable?

In essence, Observables represent data (or a state) that changes over time. Observables have two critical methods you should know about: subscribe and pipe.

Observable.subscribe()

subscribe will start the execution of an Observable and provides a way to observe Observable emitted notifications by passing Observer handlers.

The Observer argument of subscribe allows you to react when the Observable emits a new value, errors, or completes through next, error, and complete callbacks.

Each subscription to an Observable will create a new execution of the Observable.

// emit sequential numbers every second and console.log that number
interval(1000).subscribe({
  next: (value) => console.log(value),
  error: () => {},
  complete: () => {},
});

// if you don't care about error or complete, you can pass only the next function:
interval(1000).subscribe((value) => console.log(value));

Code Available on StackBlitz

Observable.pipe()

The sole reason the pipe method exists is to improve readability.

Without pipe, composing Observable streams with operators would be a nightmare. Operators are pure functions that take a source Observable and return a new Observable.

Imagine writing the following code to compose an Observable Stream:

/**
 * 1. interval - emit sequential numbers every second
 * 2. map - multiply emitted values by 2
 * 3. map - emit a string `Result: ${x}`
 * 4. tap - log every emitted value
 */
tap((value) => console.log(value))(
  map((x) => `Result: ${x}`)(map((x: number) => x * 2)(interval(1000)))
).subscribe();

Albeit the code above is valid, the pipe method is always preferred.

Using the pipe method, the code becomes more readable:

/**
 * 1. interval - emit sequential numbers every second
 * 2. map - multiply emitted values by 2
 * 3. map - emit a string `Result: ${x}`
 * 4. tap - log every emitted value
 */
interval(1000)
  .pipe(
     map((x) => x * 2),
     map((x) => `Result: ${x}`)
  )
  .subscribe((value) => console.log(value));

Code Available on StackBlitz

What is a Subject?

The Subject class extends the Observable class to allow multicasting emissions to all Observers - in other words: each new subscription to a Subject will not create a new execution of the Subject.

Subjects keep track of all their Observers.

Subject.next(), Subject.error() and Subject.complete()

A Subject's next, error, and complete methods will call all of its Observers' next, error, and complete methods.

const mySubject1 = new Subject();
const mySubject2 = new Subject();

mySubject1.subscribe({
  next: (value) => console.log(`Subject 1 Next: ${value}`),
  error: (error) => console.log(`Subject 1 Error: ${error}`),
});

mySubject1.next('A Value');
mySubject1.error('Something bad happened');

mySubject2.subscribe({
  next: (value) => console.log(`Subject 2 Next: ${value}`),
  complete: () => console.log(`Subject 2 Complete`),
});

mySubject2.complete();

Code Available on StackBlitz

Subject.asObservable()

The asObservable method is useful when you want to hide the Subject’s methods when exposing it to consumers that should only use it as an Observable.

For example, you might expose the Subject in a service as an Observable, so components using that service will not be able to call the next method.

// MyService file
const mySubject = new Subject<MyType>();

public getSubject(): Observable<MyType> {
  return this.mySubject.asObservable();
}

// MyComponent file
myService.getSubject().next();
// Property 'next' does not exist on type 'Observable<MyType>'.

What is a BehaviorSubject?

constructor(value: T)

BehaviorSubject extends Subject to ensure late subscribers are notified with the latest emitted value.

A BehaviorSubject differs from a Subject in two ways.

BehaviorSubject requires an initial value passed in its constructor
Observers will receive the latest emitted value when they subscribe to a BehaviorSubject

const myBehaviorSubject = new BehaviorSubject('Initial Value');

myBehaviorSubject.subscribe((value) =>
  console.log(`First Subscription: ${value}`)
);

myBehaviorSubject.next('Second Value');

// a late subscription will receive the latest emitted value
myBehaviorSubject.subscribe((value) =>
  console.log(`Late Subscription: ${value}`)
);

Code Available on StackBlitz

What is a ReplaySubject?

constructor(_bufferSize: number = Infinity, _windowTime: number = Infinity, _timestampProvider: TimestampProvider = dateTimestampProvider)

ReplaySubject also extends Subject. ReplaySubject behaves similarly to BehaviorSubject but is capable of emitting multiple values when subscribed to.

ReplaySubject differs from BehaviorSubject in three ways:

A ReplaySubject does not have an initial value.
A ReplaySubject emits the last bufferSize emissions when Observers subscribe to it. Values are held in a buffer for windowTime.
A ReplaySubject still replays values for Observers even if it has been completed with an error.

const myReplaySubject = new ReplaySubject<number>();

myReplaySubject.subscribe({
  next: (value) => console.log(`ReplaySubject Next: ${value}`),
  error: (error) => console.log(`ReplaySubject Error: ${error}`),
  complete: () => console.log(`ReplaySubject Complete`),
});

myReplaySubject.next(1);
myReplaySubject.next(2);
myReplaySubject.next(3);
myReplaySubject.error('Something bad happened');

// late subscription
myReplaySubject.subscribe({
  next: (value) => console.log(`ReplaySubject Next: ${value}`),
  error: (error) => console.log(`ReplaySubject Error: ${error}`),
  complete: () => console.log(`ReplaySubject Complete`),
});

Code Available on StackBlitz

What is an AsyncSubject?

An AsyncSubject only emits the last value to its Observers when it completes. That’s it.

const myAsyncSubject = new AsyncSubject();

myAsyncSubject.subscribe({
  next: (value) => console.log(`AsyncSubject Next: ${value}`),
  complete: () => console.log(`AsyncSubject Complete`),
});

myAsyncSubject.next('First Value');
myAsyncSubject.next('Second Value');

setTimeout(() => myAsyncSubject.complete(), 3000);

Code Available on StackBlitz

On The Road to Mastering RxJS

Now that you know how to use all the Observable Types—Observable, Subject, BehaviorSubject, ReplaySubject, and AsyncSubject—we highly recommend taking a look at the operators' list in the official RxJS documentation, so you are at least exposed to most operators and know there’s a solution to every problem you are ever going to face.

Finally, Bitovi offers a free RxJS course with great introductory and advanced content. You don't want to miss it. 👀

Are Subjects a tricky subject for you?

Bitovi has expert Angular consultants ready to help you tackle your most challenging RxJS questions. Schedule your free consultation today!

Improve App Performance with the NgOptimizedImage Directive

Fábio Englert Moutinho — Tue, 06 Sep 2022 21:27:04 +0000

Newly released Angular 14.2 comes with a nifty image optimization feature that can be used to improve the performance of your application.

In this blog post, we will take a look at the exciting new NgOptimizedImage directive and explain how we used it to make this example e-commerce application perform up to 50% better on Lighthouse scores!

What is NgOptimizedImage?

NgOptimizedImage is a Directive focused on improving Image Loading performance. As a happy side-effect, NgOptimizedImage enforces best practices and improves Core Web Vitals scores, which might help your application rank higher on search engines.

Important Note: NgOptimizedImage is on Developer Preview. Features on Developer Preview might change APIs without notice. If you decide to use NgOptimizedImage on production, be aware when updating your application.

How to Use NgOptimizedImage

In order to use the NgOptimizedImage directive, identifiable by the selector img[rawSrc], you need to import NgOptimizedImage into your Module or Standalone Component.

import { NgOptimizedImage } from '@angular/common';

Set Up an Image Loader

Image Loaders are tools that host images and provide optimization services such as image resizing or compression.

Angular now provides popular Image Loader configurations out of the box. In our e-commerce application example, we set up ImageKit with the provideImageKitLoader function, whose path argument is the default URL endpoint for an account.

// src/app/app.module.ts

// ... other imports
import { NgOptimizedImage, provideImageKitLoader } from '@angular/common';

@NgModule({
  declarations: [AppComponent, HomeComponent, CartComponent],
  imports: [BrowserModule, AppRoutingModule, ScullyLibModule, NgOptimizedImage],
  providers: [provideImageKitLoader('https://ik.imagekit.io/fabioemoutinho')],
  bootstrap: [AppComponent],
})
export class AppModule {}

Understand NgOptimizedImage Properties

NgOptimizedImage adds additional properties to an img tag:

rawSrc: string: instead of src full URL, rawSrc represents the source image name

rawSrcset: string: a comma-separated list of width or pixel density descriptors. Not required, but recommended. Usually used in conjunction with sizes attribute if you want to provide different image sources for different viewport sizes.

<!-- example taken from https://angular.io/api/common/NgOptimizedImage#properties -->

<img rawSrc="hello.jpg" rawSrcset="100w, 200w" />

<!-- img tag above would output an img tag similar to the img below -->
<img src="path/hello.jpg" srcset="path/hello.jpg?w=100 100w, path/hello.jpg?w=200 200w" />

priority: boolean: defaults to false; If true, adds multiple optimizations to the image

Images are going to be lazy-loaded by default. That is, it is going to be up to the browser to decide when to load the images. While lazy-loading an image is usually a good approach, in some cases, like when you want to make sure the browser will download critical images first, you might want to set the priority property to true in order to increase the performance of your app.

The NgOptimizedImage directive also expects every image to have explicit height and width attributes.

Here are the changes we had to make on a component’s template to use the NgOptimizedImage directive.

  <!-- src/app/home/home.component.html ‐‐>

  <picture class="picture block relative overflow-hidden">
    <img
-     [src]="product.image"
+     [rawSrc]="product.id + '.jpg'"
      [alt]="product.title"
      class="img not-loaded object-contain w-full h-full absolute top-0 left-0"
      (load)="onLoadImage($event)"
      (error)="onErrorImage($event)"
+     width="200"
+     height="200"
    />
  </picture>

Performance Results

In our example application, we removed scully to better measure the impact of a vanilla implementation of the NgOptimizedImage directive on the application’s home page. We tested two different scenarios:

https://e-commerce-no-scully-example-angular-13.vercel.app/ - Angular 13.3.11
https://e-commerce-no-scully-example.vercel.app/ - Angular 14.2.0, using NgOptimizedImage

We then ran Lighthouse locally (desktop) and had the following results:

Metric	Angular 13.3.11	Angular 14.2 with NgOptimizedImage	Impact
First Contentful Paint	0.4 s	0.3 s	25% decrease
Speed Index	1.2 s	0.6 s	50% decrease
Largest Contentful Paint	1.7 s	1.0 s	41% decrease
Time to Interactive	0.5 s	0.4 s	20% decrease
Total Blocking Time	0 ms	0 ms	-
Cumulative Layout Shift	0.003	0.003	-
Performance	93	99	6.45% increase

Even though you get excellent performance results with the automatic lazy loading of images, NgOptimizedImage shines even brighter when combining the usage of image loaders with the rawSrcset property and sizes attribute. Implementing the rawSrcset property and sizes attribute enables you to further optimize your application for different devices, especially for mobile devices.

What’s Next for Angular’s Image Directive?

Chrome’s blog post announcement about NgOptimizedImage directive presents an interesting roadmap, and we can expect many improvements like automatic srcset and sizes attributes for responsive images, automatic height and width attributes and more.

Angular v14.2 introduces other interesting features that we will talk about next, stay tuned on Bitovi's Twitter.

Need help staying up to date with the latest version of Angular to take advantage of these cool new features? Contact us for Angular Consulting help!

Bitovi ESLint Config: Handpicked Rules to Improve Your Code

Fábio Englert Moutinho — Mon, 08 Aug 2022 16:00:00 +0000

Linting is an important step to ensure code quality, and it fits well as an automated process in the development pipeline. Most teams use the default lint configuration provided by their framework, missing opportunities to prevent runtime errors and increase code quality with the extended set of ESLint rules.

Bitovi is happy to announce the @bitovi/eslint-config and @bitovi/eslint-plugin packages!

In pursuit of greater code quality and better standards for Bitovi's clients and the Community, we carefully handpicked the best ESLint rules and created some of our own to fill existing gaps. We built @bitovi/eslint-config upon existing recommended rule sets and selected rules to avoid common pitfalls based on experience with clients and internal projects.

What’s in Bitovi ESLint Config?

Our ESLint-config package has dedicated Angular and React rule sets, but your project can also benefit from other specific rule sets like RxJS. Here are a few of the Angular set rules included in our ESLint config:

Keep code clean by removing unused variables - @typescript-eslint/no-unused-vars
Avoid accessibility issues with keyboard navigation - @angular-eslint/template/no-positive-tabindex
Ensure elements with click event bindings are accessible - @angular-eslint/template/click-events-have-key-events
Ensure component classes with click event bindings are accessible - @bitovi/host-listener-click-events-have-key-events

Start harnessing the full extent of Bitovi’s recommended ESLint rules by following two short steps.

1. Installation

Install the ESLint-config package to get started! Run npm i -D @bitovi/eslint-config, which is short for npm install --save-dev @bitovi/eslint-config.

2. Usage

Once installation is done, you can add any of the rules provided by @bitovi/eslint-config to your project's ESLint config file extends array.

  extends: [
    '@bitovi/eslint-config/angular',
  ]

  // or, if you only want a specific rule set like RxJS
  extends: [
    '@bitovi/eslint-config/rules/rxjs',
  ]

What’s next?

We plan to add more custom ESLint rules to @bitovi/eslint-plugin package to help your project be more accessible, have a better SEO and Lighthouse Scores, and more!

Interested in learning more? Take a look at our Roadmap.

Do you have ideas or suggestions? We’d love to hear about them. You can open an issue at @bitovi/eslint-config repository.

If you have any questions, let us know in our Community Slack!

Always Know When to Use Share vs. ShareReplay

Fábio Englert Moutinho — Mon, 25 Jul 2022 15:17:10 +0000

Using share and shareReplay is pretty darn confusing. The way share and shareReplay work is not always obvious and might lead to unexpected behavior in your application.

Fortunately, you have found this article and after reading you’ll understand the differences between share and shareReplay.

The share operator will multicast values emitted by a source Observable for subscribers.

Multicast means data is sent to multiple destinations.

As such, share allows you to avoid multiple executions of the source Observable when there are multiple subscriptions. share is particularly useful if you need to prevent repeated API calls or costly operations executed by Observables.

The slightly modified code from the official documentation below has a shared source Observable that emits random numbers at 1-second intervals, up to two emissions. You can also run the example on StackBlitz.

import { interval, tap, map, take, share } from 'rxjs';

const source$ = interval(1000).pipe(
  tap((x) => console.log('Processing: ', x)),
  map(() => Math.round(Math.random() * 100)),
  take(2),
  // if you remove share, you will see that
  // each subscription will have its own execution of the source observable
  share()
);

source$.subscribe((x) => console.log('subscription 1: ', x));
source$.subscribe((x) => console.log('subscription 2: ', x));

setTimeout(
  // this subscription arrives late to the party. What will happen?
  () => source$.subscribe((x) => console.log('subscription 3: ', x)),
  1500
);

/* Example Run
### share operator logs:
--- 1 second
Processing: 0
subscription 1: 33
subscription 2: 33
--- 2 seconds
Processing: 1
subscription 1: 12
subscription 2: 12
subscription 3: 12

### without share operator logs:
--- 1 second
Processing: 0
subscription 1: 55
Processing: 0
subscription 2: 65
--- 2 seconds
Processing: 1
subscription 1: 64
Processing: 1
subscription 2: 2
--- 2.5 seconds
Processing: 0
subscription 3: 42
--- 3.5 seconds
Processing: 1
subscription 3: 95
*/

share 's Inner Observable: Subject

When you subscribe to a shared Observable, you are actually subscribing to a Subject exposed by the share operator. The share operator also manages an inner Subscription to the source Observable. The inner Subject is the reason multiple subscribers receive the same shared value, as they are receiving values from the Subject exposed by the share operator. See previous example on StackBlitz.

share's RefCount

share keeps a count of subscribers. Once the subscriber count reaches 0, share will unsubscribe from the source Observable and reset its inner Observable (the Subject). The following (late) subscriber will trigger a new Subscription to the source Observable, or in other words, a new execution of the source Observable. Here’s an example of this behavior, also available on StackBlitz.

import { defer, delay, of, share, shareReplay, tap } from 'rxjs';

const source$ = defer(() => of(Math.round(Math.random() * 100))).pipe(
  tap((x) => console.log('Processing: ', x)),
  delay(1000),
  // shareReplay({ bufferSize: 1, refCount: true }),
  share()
);

source$.subscribe((x) => console.log('subscription 1: ', x));
source$.subscribe((x) => console.log('subscription 2: ', x));

setTimeout(
  () => source$.subscribe((x) => console.log('subscription 3: ', x)),
  3500
);

shareReplay

In some cases what you really need is a share that is able to behave as a BehaviorSubject would. For example: if a cold Observable has a share operator, like the code example above, a late subscriber to it would never get the values emitted before the subscription because it subscribed after share operator reached refCount 0, which means the share operator unsubscribed from the source Observable and reset its inner Subject. The late subscriber would thus subscribe to a new inner Subject, which runs a new execution of the source Observable, in this case that means a second API call: exactly the opposite of what you really needed.

That's why shareReplay exists: it both shares the source Observable and replays the last emissions for late subscribers.

Also, it does not keep a count of subscribers by default, but you may use the refCount option with a true value to enable that behavior.

shareReplay's Inner Observable: ReplaySubject

In contrast to share, shareReplay exposes a ReplaySubject to subscribers. ReplaySubject(1) is very similar to a BehaviorSubject.

shareReplay's RefCount

Since shareReplay does not keep track of a subscriber count by default, it is not able to unsubscribe to the source Observable. Ever. Unless you use the refCount option.

In order to use shareReplay while getting rid of memory leak issues you can use bufferSize and refCount options: shareReplay({ bufferSize: 1, refCount: true }).

shareReplay never resets its inner ReplaySubject when refCount reaches 0, but does unsubscribe from the source Observable. Late subscribers will not trigger a new execution of the source Observable and will receive up to N (bufferSize) emissions. Play with the previous example on StackBlitz to see the difference.

Use with Caution

In Angular, there are some gotchas when using share and shareReplay. Observables subscribed in the template with the async pipe might reach refCount 0 if unsubscribed automatically by the async pipe when inside a *ngIf, which would cause a new execution of the source Observable.

You might feel like the God of Time and Cache using share and shareReplay, but you should be aware that with great power comes great responsibility. If you want a partner to help you manage the high complexity of share, shareReplay and RxJS best practices, contact us today. 🙂

How to Improve Your Angular E-Commerce Application with Scully

Fábio Englert Moutinho — Tue, 21 Jun 2022 19:29:00 +0000

Scully is a “Static Site Generator for Angular apps” that enables Angular apps to pre-render pages with dynamic content to improve performance metrics like First Contentful Paint (FCP), Time to Interactive (TTI), and others which are used by Search Engines to rank your website.

But is Scully the right tool for your Angular E-Commerce Application?

Let’s find out if it suits your needs. SPOILER ALERT: yes, it probably does.

How does Scully work?

Scully provides an additional step after Angular’s build step, which will identify your application’s routes to be rendered, then serve your application and launch a browser instance to navigate through selected routes. When the browser finishes rendering each route, Scully copies its rendered content and saves everything in HTML files inside dist folder.

If you want to know how Scully works behind the curtains in more detail, take a look at The Scully Process page in the official documentation.

How Does Scully Improve An E-Commerce Application?

Search Engine Optimization (SEO) is a must for any website nowadays, especially for E-Commerce Apps.

Scully will help your E-Commerce Application rank higher on search results by statically rendering each product page, making the application load faster for users and search engines alike. Performance metrics used by search engines will also improve as a result of Scully’s pre-rendering process.

The performance improvements will also lead to lower bounce rates and higher conversion rates, as users will have a better experience while navigating.

In other words, Scully essentially caches the application with statically served files, improving load time, and making processing your application easier on browsers and search engines, since there will be no javascript functions to run and no need to make external HTTP calls to fetch data.

Installation

To install Scully, run ng add @scullyio/init.

Scully will then ask which route renderer you would like to use. As of 2022, we recommend picking Puppeteer, since other options are currently in beta.

Once installation is done, you’ll notice there’s a new Scully config file, scully.[project].config.ts, and app.module.ts now imports ScullyLibModule.

To match the usability of ng serve, when developing you’ll need to run two terminals with the following commands:

ng build --watch - whenever there’s a file change, it will trigger the build step
npx scully --scanRoutes --watch - whenever the build files generated by ng build --watch change, it will trigger Scully's build step

If you need to run both the static and regular builds at the same time, you can use npx scully serve, but you won’t have automatic updates when there are changes in builds.

Dynamic Routes

Scully provides a pre-build step where it can fetch information and decide which routes your application will render based on any logic you see fit.

In order to do that, you need to go to the ./scully.[project].config.ts file and edit the routes property inside the exported config object.

The routes property is an object that can configure multiple routes, and each route can have different logic to decide which children routes will be rendered.

In the example below, we have a /product/:slug route, and Scully will fetch the url and run the resultsHandler function with the response data. resultsHandler must return a list of objects with the property defined in the property property, which in this example has the slug value. More information at the official documentation.

Scully will then find out which routes should be rendered by replacing :slug in the route /product/:slug with the slug property value for each object in resultsHandler returned array.

export const config: ScullyConfig = {
  projectRoot: './src',
  projectName: 'PROJECT-NAME-HERE',
  outDir: './dist/static',
  routes: {
    '/product/:slug': {
      type: 'json',
      slug: {
        url: 'https://PRODUCT-API-HERE/products',
        property: 'slug',
        resultsHandler: (data) => {
          // you can process anything here,
          // but you must return a list of objects
          // that have a 'slug' property, as defined above in line 8
        },
      },
    },
  },
};

Making API Data Static

Caching API calls will make your application faster and less reliant on servers availability. With useScullyTransferState method you are able to cache the results of Observables. This means, however, that to update the data statically served by useScullyTransferState you will need to trigger a new Scully build and deploy pipeline.

The first argument of the useScullyTransferState method is the index that will be used to get the data at runtime.

The second argument expects an Observable, which means you are not limited to caching API calls, you can cache heavy operation Observables too.

// some service method
getCatalog(): Observable<Catalog> {
  return this.transferState.useScullyTransferState(
    'catalog',
    this.http.get<Catalog>('https://CATALOG-URL')
  );
}

Not All API Requests Should Be Cached

Should you wrap every Observable with useScullyTransferState? Definitely not. There might be cases where observables should only run at runtime and don’t need to be cached.

Good examples include observables that rely on login state, like cart or user data, or when you need to hide or show specific parts of your application in the static generated version only.

// ./src/app/app.component.ts example
@Component({
  selector: 'app-root',
  template: '
    <nav>
      <app-menu></app-menu>
      <app-cart *ngIf="!isScullyRunning"></app-cart>
    </nav>
    <router-outlet></router-outlet>
  ',
})
export class AppComponent {
  readonly isScullyRunning: boolean = isScullyRunning();
}

Relying on Environment Files

When writing plugins or dealing with the Scully config file, you may need to import environment.prod.ts or some other file.

By default, Scully only transpiles .ts files inside the ./scully folder. Fortunately, it’s rather simple to tell Scully that more files need to be transpiled to JavaScript.

In ./scully/tsconfig.json file, add an include property with the patterns/files you need. The ./**/** pattern will match all files inside ./scully folder, which is the default behavior if an include property is not defined. Then, you only need to add specific files that exist outside of ./scully folder.

// ./scully/tsconfig.json
{
  "compileOnSave": false,
  "compilerOptions": {
    "esModuleInterop": true,
    "importHelpers": false,
    "lib": ["ES2019", "dom"],
    "module": "commonjs",
    "moduleResolution": "node",
    "sourceMap": true,
    "target": "es2018",
    "types": ["node"],
    "skipLibCheck": true,
    "skipDefaultLibCheck": true,
    "typeRoots": ["../node_modules/@types"],
    "allowSyntheticDefaultImports": true
  },
  "include": ["./**/*", "../src/environments/environment.prod.ts"],
  "exclude": ["./**/*spec.ts"]
}

Creating a Custom Plugin for Incremental Builds

Rendering all the pages each time a single product changes is a waste of time and resources. It might not have a huge impact when you have a small set of products, but what if your E-Commerce application has thousands of product pages to render?

Implementing incremental builds is an optimized solution where only changed content is re-rendered and deployed, saving you and your organization time and money in CI pipeline and deployments.

Scully has a very powerful plugin system that enables you to control the pre-render process. There’s more information about Scully plugins in Plugin Concept and Plugin Reference.

Below is an example of a plugin approach to render specific products by passing a list of IDs with the scully command. Command example: npx scully --productIds=1,2,3. This approach expects that the build and deploy pipeline are triggered by a system (like a CMS) with an awareness of what content has changed.

In ./scully/plugins/plugin.ts, a product plugin is registered as a router plugin, then used in ./scully.[project].config.ts file to configure how the routes in /product/:slug are handled.

// ./scully/plugins/plugin.ts
import { HandledRoute, registerPlugin, httpGetJson } from '@scullyio/scully';
import { Product } from '../../src/app/product/product.model';
import { environment } from '../../src/environments/environment.prod';

import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';

export const product = 'product';

const productRoutes = async (route?: string): Promise<HandledRoute[]> => {
  const yarg = yargs(hideBin(process.argv));
  const argv = await yarg.option('productIds', { type: 'string' }).argv;

  // if there are --productIds being passed in npx scully --productIds=1,2,3
  // then only generate static files for those products
  // else fetch all products from API and map the returned IDs.
  const productIds: string[] = argv.productIds
    ? argv.productIds.split(',')
    : ((await httpGetJson(`${environment.api.url}/products`)) as Product[]).map(
        (product) => product.id.toString()
      );
  const productRoutes: HandledRoute[] = productIds.map((id) => ({
    route: `/product/${id}`,
  }));

  return Promise.resolve(productRoutes);
};

const validator = async () => [];

registerPlugin('router', product, productRoutes, validator);

You’ll also need to update the config file to use the product plugin:

// ./scully.[project].config.ts
import './scully/plugins/plugin';

export const config: ScullyConfig = {
  projectRoot: './src',
  projectName: 'PROJECT-NAME-HERE',
  outDir: './dist/static',
  routes: {
    '/product/:slug': {
      type: 'product',
    },
  },
};

Sweet! Now when we run the Scully build with this plugin, Scully will select to pre-render either the product IDs passed as arguments - if there are any - or the returned product IDs of an API call to ${environment.api.url}/products, meaning you have great control over which routes to render.

Scully is AWESOME!

We’ve seen how Scully can solve Angular E-Commerce applications' problems in a handful of ways.

There is little downside to using Scully. The main one is the need to run an extra step between build and deploy, but as shown in this article, you can lower the impact with incremental builds. Needless to say, if you care about lower bounce rates and increasing the likelihood your website will be a top result on search engines, Scully is your friend.

As a bonus, I’ve setup an E-Commerce example app (deployed with ng build && scully) where I used Scully to pre-render the content so you can see how the output looks using your browser’s DevTools. And you can compare it with a second E-Commerce no-Scully example app (deployed with ng build only), where the Scully pre-render step is not used. By the way, here's the GitHub repo.

If you need any assistance or you just want to chat with us, you can reach us through our Bitovi Community Slack.

How to Create Custom ESLint Rules (It's Not as Hard as You Think...)

Fábio Englert Moutinho — Wed, 09 Feb 2022 19:56:28 +0000

Most teams develop patterns or preferred ways of writing code, but it can be tedious to enforce adhering to those patterns, especially for new team members onboarding. To help this, we rely on linters for basic formatting, but did you know you can take preference-enforcement to the next level by writing your own lint rules?

As TypeScript developers, we use ESLint as it is capable of linting both TypeScript AND JavaScript files.

I'm going to teach you how to write custom ESLint rules that work for your team.

⚠️ Disclaimer: the rest of this post contains irony and sarcasm.

But it is probably very hard to code an ESLint rule, right? It sounds like something that only an extremely experienced developer could manage. 👀

And you are right, it would be very hard - SPOILER: coding is hard - if ESLint did not provide an awesome API for us.

So it IS possible to write custom ESLint Rules. But we need a reason to write one.

Why Write a Custom ESLint Rule?

Writing tests is boring. And you are writing tests for things that should work in the first place. Plus, what guarantee do you have that the tests themselves aren't flawed? You'd have to create tests for each test. And then tests for the test tests. You can see where this is leading: nowhere.

I've now established that tests are bad for your project. We are in eXtreme Go Horse (XGH) territory.

XGH is clear on the testing matter:

You better know what you are doing. And if you know what you are doing, why test? Tests are a waste of time. If code compiles, it’s enough.

The way to prevent anyone from wasting precious time writing tests is to write your own custom ESLint Rule that screams at you if your project has a .spec file. Sounds good!

What to Know Before Writing a Custom ESLint Rule

At the end of the day when you are writing a Custom ESLint Rule, you are providing some metadata (meta property) and callback functions for ESLint to run (create property).
create property is a function that returns an object. That object has properties that store the callback functions for ESLint.
The callback functions represent node types, selectors, or events and they will be triggered by ESLint at some point.

The basic structure of a rule looks like this:

{
  meta: {},
  create: (context) => {
    return {};
  }
}

context (on line 3), is an object provided by ESLint that might have useful data or methods you can use in our callback function.

And that's enough context. 😄

Behold the `xgh/no-testing` Rule!

Below is the full code for the no-testing rule object and an explanation of what's going on.

{
  meta: {
    type: "problem",
    messages: {
      match:
        "Found '{{filename}}' .spec file. If you knew what you were doing, you wouldn't need to test it.",
    },
  },
  create: (context) => ({
    Program: (node) => {
      const filename = context.getFilename();
      if (filename.includes(".spec")) {
        context.report({
          node,
          messageId: "match",
          data: {
            filename,
          },
        });
      }
    },
  }),
}

Inside meta, you can specify type (string) as problem, suggestion, or layout. Choose problem because you want everyone to know that you should not waste time testing.

At line 9, the create function will return an object that has a Program property. That is the top level event that ESLint runs for every file. Read about it here.

The Program property is - you guessed it - a callback function. It takes a node parameter that you don’t care about, at least not today.

Here's the interesting part. The “no-testing” logic will kick in: at line 11, you store the current file’s name in a variable. Here the context comes in handy as it has a getFileName method.

On line 12, check if filename variable contains the string .spec in it. If it does, you know it is a test file, so you call the context.report method to let ESLint know there’s something wrong with our code.

Lines 15 to 18 forward relevant data as parameters to let ESLint know which message to show. messageId matches the match property inside meta.messages.

If you want to know more about ESLint Rules, read this guide from ESLint's official documentation.

How Do I Use This Wondrous Rule?

You can start using xgh/no-testing in your project right now!

Run the command npm i -D eslint-plugin-xgh to install the ESLint plugin that wraps the no-testing rule.

All you have to do now is enable the rule in your project.

Inside your ESLint config file:

{
  "plugins": ["xgh"],
  "rules": {
    "xgh/no-testing": "error"
  },
  // ...
}

If you would like to take a closer look at the xgh eslint plugin, here's the git repository.

All Kidding Aside...

At Bitovi, we ABSOLUTELY recommend writing unit tests. This tongue-in-cheek post is to show you the possibilities available to better lint your code by writing custom rules. If you need help writing your own rules or learning better coding practices, please reach out!

Originally posted in Bitovi Blog

How to Avoid the Infamous "Cannot read properties of undefined" Error with TypeScript

Fábio Englert Moutinho — Fri, 10 Dec 2021 13:47:46 +0000

As a JavaScript developer, I’m sure you’ve encountered the frustrating runtime TypeError Cannot read properties of undefined. TypeScript gives you two ways of interpreting null and undefined types, also known as Type Check Modes, and one of them can avoid this easily overlooked TypeError.

Until TypeScript 2.0, there was only one type check mode - regular - and it considers null and undefined as subtypes of all other types. This means null and undefined values are valid values for all types.

TypeScript 2.0 introduced Strict Type Check Mode (also referred to as strict null checking mode). Strict Type Check differs from Regular Type Check because it considers null and undefined types of their own.

I’ll show you how Regular Type Check handles undefined (the same applies to null) and how Strict Type Check prevents you from introducing unwanted behavior in our code, like that infamous TypeError Cannot read properties of undefined.

When undefined becomes a problem

The function translatePowerLevel below takes a number as argument and returns strings one, two, many or it's over 9000!.

function translatePowerLevel(powerLevel: number): string {
  if (powerLevel === 1) {
    return 'one';
  }
  if (powerLevel === 2) {
    return 'two';
  }
  if (powerLevel > 2 && powerLevel <= 9000) {
    return 'many';
  }
  if (powerLevel > 9000) {
    return 'it\'s over 9000!';
  }
}

However, this code doesn't handle 0, a valid input - yes, looking at you, Yamcha.

Yamcha's Power Level

When JavaScript reaches the end of a function that has no explicit return, it returns undefined.

The translatePowerLevel function return value is typed explicitly as string, but it is possibly also returning undefined when the argument powerLevel has the value 0. Why is TypeScript not triggering an error?

In Regular Type Check Mode, TypeScript is aware that a function might return undefined. But at the same time, TypeScript infers the return type to be only of type string because TypeScript is widening the undefined type to string type.

As another example, if you assign null or undefined to variables while in Regular Type Check Mode, TypeScript will infer these variables to be of type any.

const coffee = null; 
const tea = undefined;

Interpreting undefined or null as subtypes of all other types can lead to runtime problems. For example, if you try to get the length of the result of translateNumber(0), which is undefined, JavaScript will throw this TypeError at runtime: Cannot read properties of undefined (reading 'length').

const powerLevel = translatePowerLevel(0); // undefined
console.log(powerLevel.length); // Uncaught TypeError: Cannot read properties of undefined (reading 'length')

Unfortunately, TypeScript’s Regular Type Check Mode is not able to alert you to when you may have made that mistake.

Strict Type Check Mode to the Rescue

Strict Type Check Mode changes how TypeScript interprets undefined and null values. But first, let's enable Strict Type Check Mode.

How to Enable Strict Type Check Mode in TypeScript

In the root of your project, there should be a tsconfig.json file. This is the TypeScript’s configuration file and you can read more about it here.

// tsconfig.json example
{
  "compilerOptions": {
    "module": "system",
    "noImplicitAny": true,
    "removeComments": true,
    "preserveConstEnums": true,
    "outFile": "../../built/local/tsc.js",
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

Inside compilerOptions property, all we need to do is add the property "strictNullChecks": true.

It will look something like this:

// tsconfig.json
{
  "compilerOptions": {
    "module": "system",
    "noImplicitAny": true,
    "removeComments": true,
    "preserveConstEnums": true,
    "outFile": "../../built/local/tsc.js",
    "sourceMap": true,
    "strictNullChecks": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

Now that we have switched to Strict Type Check Mode, TypeScript throws this error for translatePowerLevel function: Function lacks ending return statement and return type does not include 'undefined'.

That error message is telling you the function is returning undefined implicitly, but its return type does not include undefined in it.

Awesome! TypeScript is now aware the return type does not match all possible return values, and this could lead to problems at runtime! But how can you match the return type to all possible return values?

You can either add a return statement so the function always returns a string (solution #1), or change the return type from string to string | undefined (solution #2).

Match All Possible Return Values: Solution #1

Adding a return statement so it is always explicitly returning a value - in the code below, it is now returning the string zero.

// Solution #1: add a return statement so it always returns a string
function translatePowerLevel(powerLevel: number): string {
  if (powerLevel === 1) {
    return 'one';
 }
 if (powerLevel === 2) {
    return 'two';
  }
  if (powerLevel > 2 && powerLevel <= 9000) {
    return 'many';
  }
  if (powerLevel > 9000) {
    return 'it\'s over 9000!';
  }
  // new return statement
  return 'zero';
}

Match All Possible Return Values: Solution #2

Make the undefined return type explicit so wherever translatePowerLevel is used, you have to handle nullish values as well.

// Solution #2: return type as string | undefined
function translatePowerLevel(powerLevel: number): string | undefined {
  if (powerLevel === 1) {
    return 'one';
  }
  if (powerLevel === 2) {
    return 'two';
  }
  if (powerLevel > 2 && powerLevel <= 9000) {
    return 'many';
  }
  if (powerLevel > 9000) {
    return 'it\'s over 9000!';
  }
}

If you were to compile the following code again using Solution #2, TypeScript would throw the error Object is possibly 'undefined'.

const powerLevel = translatePowerLevel(0); // undefined
console.log(powerLevel.length); // Object is possibly 'undefined'.

When you choose a solution like Solution #2, TypeScript expects you to write code that handles possible nullish values.

There’s no reason not to use Strict Type Check Mode

Now you understand how TypeScript interprets null and undefined types and how you can migrate your project to Strict Mode.

If you are starting a new project, you should definitely enable Strict Type Check Mode from the beginning. And in case you will migrate from Regular to Strict Type Check, our team can help with strategies to do so in a less painful way.

At Bitovi we highly recommend using - or migrating to - Strict Type Check Mode, as it can help you produce better, more reliable code. If you need help with building amazing web apps feel free to reach us at bitovi.com.

Originally posted in Bitovi Blog

TypeScript Features Every Angular Developer Needs to Know

Fábio Englert Moutinho — Mon, 27 Sep 2021 14:33:57 +0000

If you’re an Angular developer, you’re missing out if you’re not using advanced TypeScript features to help you build better code.

And it’s well worth the effort: TypeScript has some great features that can make you a stronger Angular developer. 💪

BigInt

BigInt lets you represent numbers bigger than 2⁵³. This is useful when you need to perform mathematical operations on very large integers. And you can work directly with large integer IDs and high resolution timestamps.

You can create a bigint primitive in two ways:

const n0 = 1n;
const n1 = new BigInt(1);

There is no interoperability between bigint and number primitives, but they can be compared.

NOTE: BigInt support is only available for the esnext target.

Numeric Separators _

Numeric separators are great for readability. They don't change how the actual numeric value is interpreted.

 // which one is more readable?
const someNumber = 1782540173;
const anotherNumber = 1_782_540_173;
console.log(someNumber === anotherNumber); // true

Keep in mind that you can't begin or end a number with a separator. Also, you can't use two in a row.

Private Fields

TypeScript has the private keyword that is stripped out during transpilation to JavaScript. If you need private properties at runtime, JavaScript's private fields come to the rescue. Unlike TypeScript's private keyword, private fields are prepended by a # character and are private even at runtime.

If you need private properties at runtime, this is now the way to do it in modern JavaScript.

NOTE: TypeScript will gracefully implement this for older browsers given your target is at least ECMAScript 2015 (ES6).

class Person {
 #age = 30;
 constructor(public name: string) {}
}
const someone = new Person('John');
console.log(someone.#age); // Property '#age' is not accessible outside class 'Person' because it has a private identifier.
console.log(someone['#age']); // Property '#age' does not exist on type 'Person'

Operators

Nullish Coalescing ??

In JavaScript, nullish refers to a value strictly equal (===) to null or undefined.

A common pattern used in JavaScript when we want a default value is to use the OR operator ||.

function timeout(callback: Function, milliseconds: number): void {
 const wait = milliseconds || 100;
 setTimeout(callback, wait);
}

Using the OR operator in this way can cause problems. Since we are dealing with numbers in the example above, then the value 0 will be a valid milliseconds value.
However, 0 is falsy, so the default value 100 will be assigned to wait.

It’s important to distinguish between falsy values (false, 0, empty string “”, and null/undefined) and nullish values (null/undefined). Nullish values are a subset of falsy values.

Nullish coalescing is an operator that returns a default value (the second operand) in case the first operand is nullish. If the first operand is not nullish, its value is returned.

Sounds complicated, but here's a simple example.

Consider a ?? b:

will return a if a is different than null and undefined
will return b if a is equal to null or undefined

let coffee: boolean | null | undefined;
const awaken = coffee ?? false;

awaken will be assigned either coffee or false:

if coffee is not nullish, awaken will be assigned coffee
if coffee is nullish, awaken will be assigned false

Optional Chaining `?`

Have you ever seen (or written) code like this?

if (obj && obj.prop1 && obj.prop1.prop2 && obj.prop1.prop2.prop3) {
 // do something
}

Optional chaining changes how objects, properties and methods are accessed. Instead of throwing an error if they are nullish, it will short-circuit and return undefined. Optional chaining also makes your code more readable.

This is how we could rewrite the code above with optional chaining:

if (obj?.prop1?.prop2?.prop3) {
 // do something
}

Non Null Assertion `!`

Sometimes, TypeScript is unable to identify that some operand is nullish. The non null assertion operator ! comes in handy for those cases. You might use it when you want to tell TypeScript that at that specific point in the code, the operand is definitely not null and not undefined.

// imagine you have a state that represents an API response
interface State {
 status: 'pending' | 'complete';
 response: string | undefined;
};
let state: State = {
 status: 'complete',
 response: 'some text',
}
// we know that when status is 'complete' we must have a response
if (state.status === 'complete') {
 console.log(state.response.length); // Object is possibly 'undefined'.
 console.log(state.response!.length) // this works
}

Check out this post by Jennifer Wadella to learn more about the non null assertion operator in Angular.

Exponentiation **

In 2 ** 3, raises the first operand 2 to the power of the second, 3, being equivalent to 2³.

Contrary to Math.pow(), the exponentiation operator ** works with the new BigInt values.

console.log(2 ** 3);
console.log(Math.pow(2, 3)); // the old way

Assignment Operators `**=`, `&&=`, `||=`, `??=`

Assignment operators are shorthand for common assignment operations. For example, a += 1 is equivalent to a = a + 1.

Assignment operators apply an operator to two arguments, then assign the result to the left operand.

Additionally, the &&=, ||=, ??= operators will short-circuit, which means if the operation is evaluated to false, no assignment will occur.

a = a ** b; // a **= b, exponentiation
a = a && (a = b); // a &&= b, logical AND
a = a || (a = b); // a ||= b, logical OR
a = a ?? (a = b); // a ??= b, nullish coalescing
// a &&= b, also equivalent to:
if (a) {
 a = b;
}
// a ||= b, also equivalent to:
if (!a) {
 a = b;
}
// a ??= b, also equivalent to:
if (a === null || a === undefined) {
 a = b;
}

These TypeScript techniques can help you handle nullish values, improve readability, manipulate larger integers, and more. I hope you find these TypeScript features useful for your Angular code!

To learn more about Angular and TypeScript, check out the Bitovi Academy.

Originally posted in Bitovi Blog

DEV Community: Fábio Englert Moutinho

Getting Started with RxJS: All You Need to Know About Observables

What is an Observable?

Observable.subscribe()

Observable.pipe()

What is a Subject?

Subject.next(), Subject.error() and Subject.complete()

Subject.asObservable()

What is a BehaviorSubject?

What is a ReplaySubject?

What is an AsyncSubject?

On The Road to Mastering RxJS

Are Subjects a tricky subject for you?

Improve App Performance with the NgOptimizedImage Directive

What is NgOptimizedImage?

How to Use NgOptimizedImage

Set Up an Image Loader

Understand NgOptimizedImage Properties

Performance Results

What’s Next for Angular’s Image Directive?

Bitovi ESLint Config: Handpicked Rules to Improve Your Code

What’s in Bitovi ESLint Config?

1. Installation

2. Usage

What’s next?

Always Know When to Use Share vs. ShareReplay

share

share 's Inner Observable: Subject

share's RefCount

shareReplay

shareReplay's Inner Observable: ReplaySubject

shareReplay's RefCount

Use with Caution

How to Improve Your Angular E-Commerce Application with Scully

How does Scully work?

How Does Scully Improve An E-Commerce Application?

Installation

Dynamic Routes

Making API Data Static

Not All API Requests Should Be Cached

Relying on Environment Files

Creating a Custom Plugin for Incremental Builds

Scully is AWESOME!

How to Create Custom ESLint Rules (It's Not as Hard as You Think...)

Why Write a Custom ESLint Rule?

What to Know Before Writing a Custom ESLint Rule

Behold the xgh/no-testing Rule!

How Do I Use This Wondrous Rule?

All Kidding Aside...

How to Avoid the Infamous "Cannot read properties of undefined" Error with TypeScript

When undefined becomes a problem

Strict Type Check Mode to the Rescue

How to Enable Strict Type Check Mode in TypeScript

Match All Possible Return Values: Solution #1

Match All Possible Return Values: Solution #2

There’s no reason not to use Strict Type Check Mode

TypeScript Features Every Angular Developer Needs to Know

BigInt

Numeric Separators _

Private Fields

Operators

Nullish Coalescing ??

Optional Chaining ?

Non Null Assertion !

Exponentiation **

Assignment Operators **=, &&=, ||=, ??=

Behold the `xgh/no-testing` Rule!

Optional Chaining `?`

Non Null Assertion `!`

Assignment Operators `**=`, `&&=`, `||=`, `??=`