DEV Community: Manufac Analytics Private Limited

Using Apache ECharts with Lit and TypeScript

Manufac — Sun, 16 Jun 2024 12:45:39 +0000

What are Web Components?

Web components are a set of web platform APIs that allow you to create new custom, reusable, encapsulated HTML tags to use in web pages and web apps.

Custom components and widgets built on the Web Component standards will work across modern browsers and can be used with any JavaScript library or framework that works with HTML.

According to MDN, the 3 main APIs for Web Components are:

For those interested in learning more, this CSS-Tricks.com article series is a great reference.

Since these APIs are all widely available, we can start using them to build custom components in production. However, there are libraries like Lit and Stencil that can simplify the development process.

Why might we need Web Components?

The FAST Project by Microsoft provides an in-depth discussion on the benefits of Web Components.

While better performance may be a reason for some, their framework-agnostic nature was the most important value proposition for our team at Manufac. For instance:

Your team can build standard Web Components to be reused across different web apps without restricting your developers to a particular framework. This benefit is particularly valuable for large enterprises with multiple teams that have diverse skill sets and preferences.
If your end product needs to integrate well with any web application, Web Components are ideal. For example, if you're building a payment solution and want to offer a ready-to-use payment button that developers can easily add to their web apps, would you prefer building separate versions for ReactJS, Angular, and VueJS? Or would you rather have a single framework-agnostic UI component?

Why not simply use JS/TS to create reusable components programmatically?

You certainly can. One way to do this is to write sub-routines that find, say, all divs with specific class names or IDs using methods such as document.getElementById, document.getElementsByClassName, and document.querySelector. You can then replace these elements with the programmatically created UI components of your choice.

However, Web Components offer an additional advantage via its shadow DOM API: encapsulation.

... because a custom element, by definition, is a piece of reusable functionality: it might be dropped into any web page and be expected to work. So it's important that code running in the page should not be able to accidentally break a custom element by modifying its internal implementation. Shadow DOM enables you to attach a DOM tree to an element, and have the internals of this tree hidden from JavaScript and CSS running in the page.

MDN provides an in-depth discussion about this here.

How can we build a portable choropleth component using Apache ECharts and Lit?

A. Import all the needed dependencies.

I am assuming that you have some familiarity with both Lit and Apache ECharts.

If not, then the following should help:
a. An interactive tutorial for Lit
b. Getting started with Apache ECharts

import { MapChart } from "echarts/charts";
import {
  TitleComponent,
  ToolboxComponent,
  TooltipComponent,
  VisualMapComponent,
  GeoComponent,
} from "echarts/components";
import { init, use, registerMap } from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";
import { LitElement, PropertyValueMap, PropertyValues, html } from "lit";
import { customElement, property, query } from "lit/decorators.js";
import type { MapSeriesOption } from "echarts/charts";
import type {
  TitleComponentOption,
  TooltipComponentOption,
  ToolboxComponentOption,
  GeoComponentOption,
  VisualMapComponentOption,
} from "echarts/components";
import type { ComposeOption, ECharts } from "echarts/core";
import { WorldChoroplethMapGeoJSON } from "./utils";
import { ChoroplethStyles } from "./styles";

The WorldChoroplethMapGeoJSON imported above is available here and ChoroplethStyles as shown below can contain your preferred styling:

import { css } from "lit";

export const ChoroplethStyles = css`
  .choropleth {
    width: 100%;
    height: 100%;
  }
`;

B. Next, we'll configure ECharts to do some bundle size optimization:

/**
 * Adapted from Echarts.
 * Ref: https://echarts.apache.org/examples/en/editor.html?c=map-usa-projection&lang=ts
 */
type WorldChoroplethMapOptions = ComposeOption<
  | GeoComponentOption
  | MapSeriesOption
  | TitleComponentOption
  | ToolboxComponentOption
  | TooltipComponentOption
  | VisualMapComponentOption
>;

/**
 * Adapted from Echarts.
 * Ref: https://echarts.apache.org/examples/en/editor.html?c=map-usa-projection&lang=ts
 */
use([
  TitleComponent,
  TooltipComponent,
  VisualMapComponent,
  GeoComponent,
  MapChart,
  ToolboxComponent, // A group of utility tools, which includes export, data view, dynamic type switching, data area zooming, and reset.
  CanvasRenderer, // If you only need to use the canvas rendering mode, the bundle will not include the SVGRenderer module, which is not needed.
]);

C. Now, we are telling ECharts which GeoJSON file to use to render the base map. This is the world map GeoJSON, but if you only need, say, the Indian or the US map, you can switch the GeoJSON file accordingly.

/**
 * Adapted from Echarts.
 * Ref: https://echarts.apache.org/examples/en/editor.html?c=map-usa-projection&lang=ts
 */
type RegisterMapParams = Parameters<typeof registerMap>;
registerMap("WorldChoroplethMap", WorldChoroplethMapGeoJSON as RegisterMapParams[1]);

D. Next, time for some data modeling. How do we want to express the countries and associated data can be specific to your own use case. Nevertheless, at a basic level, we mainly need some way to identify the country and the associated numeric value to be visualized. In the data model below, we've have a no-frills interface which does just that:

interface WorldChoroplethDatum {
  name: string;
  value: number;
}

The input data passed to the choropleth should now be like this: WorldChoroplethDatum[].

E. Finally, we've come to the core component implementation. You may want to read up a bit on the Lit lifecycle methods if the following class methods seem foreign:

/**
 * Using `firstUpdated` alongside `willUpdate` can ensure that the 
 * private variable is set correctly both initially and when properties 
 * change. 
 */
@customElement("world-choropleth")
export class WorldChoropleth extends LitElement {
  #instance: ECharts | undefined;
  #observer: ResizeObserver | undefined;
  #options: WorldChoroplethMapOptions | undefined;

  static styles = [ChoroplethStyles];

  @property({ type: Array })
  value: WorldChoroplethDatum[] = [];

  @property({ type: String })
  title = "";

  // Ref: https://lit.dev/docs/components/shadow-dom/#query
  @query("#choropleth", true)
  private _choropleth: HTMLDivElement | undefined | null;

  protected willUpdate(changedProperties: PropertyValues<this>): void {
    if (changedProperties.has("title")) {
      this.#options = {
        ...this.#options,
        title: { text: changedProperties.get("title") },
      };
    }
    if (changedProperties.has("value")) {
      const newValue = changedProperties.get("value") ?? [];
      const values = newValue.map((ele) => ele.value);
      this.#options = {
        ...this.#options,
        series: {
          ...(this.#options?.series as MapSeriesOption),
          data: newValue,
        },
        visualMap: {
          ...this.#options?.visualMap,
          min: Math.min(...values),
          max: Math.max(...values),
        },
      };
    }
  }

  protected firstUpdated = () => {
    // Initialize echarts instance
    if (this._choropleth !== null && this._choropleth !== undefined) {
      this.#instance = init(this._choropleth);
      this.#observer = new ResizeObserver(() => {
        this.#instance?.resize();
      });
      this.#observer.observe(this._choropleth);
      const values = this.value.map((ele) => ele.value);
      this.#options = {
        title: {
          left: "center",
          text: this.title,
        },
        tooltip: {
          trigger: "item",
          showDelay: 0,
          transitionDuration: 0.2,
        },
        toolbox: {
          show: true,
          left: "right",
          top: "top",
          feature: {
            saveAsImage: {},
            restore: {
              show: true,
              title: "Reset zoom",
            },
          },
        },
        visualMap: {
          id: "visual-map",
          type: "continuous",
          left: "right",
          min: Math.min(...values),
          max: Math.max(...values),
          inRange: {
            color: [
              "#313695",
              "#4575b4",
              "#74add1",
              "#abd9e9",
              "#e0f3f8",
              "#ffffbf",
              "#fee090",
              "#fdae61",
              "#f46d43",
              "#d73027",
              "#a50026",
            ],
          },
          text: ["High", "Low"],
          calculable: true,
          realtime: false,
        },
        series: {
          id: "WorldChoroplethMapSeries",
          name: "WorldChoroplethMap",
          type: "map",
          map: "WorldChoroplethMap", // Should be same as the map registered with 'registerMap'
          roam: true, // Used for zooming and spanning over the map. Ref: https://echarts.apache.org/en/option.html#series-map.roam
          /**
           * Associates individual map polygons to the key defined.
           * Ref: https://echarts.apache.org/en/option.html#series-map.nameProperty
           */
          nameProperty: "name",
          data: this.value,
        },
      };
    }
  };

  protected updated(_changedProperties: PropertyValues<this>): void {
    if (this.#options !== undefined) {
      this.#instance?.setOption(this.#options);
    }
  }

  disconnectedCallback(): void {
    super.disconnectedCallback();
    this.#observer?.disconnect();
    this.#instance?.dispose();
  }

  render() {
    return html`<div id="choropleth" class="choropleth"></div>`;
  }
}

Why those lifecycle methods were used?

A. Why willUpdate?

It is a lifecycle method that gets called before the component updates. It is often used to perform operations that need to happen just before the update occurs, such as making changes to the state or properties based on the current and upcoming values.

In our case: Before updating, this method checks if the title or value properties have changed. If they have, it updates the #options object with new values. This prepares the component's state before the actual rendering.

B. Why firstUpdated?

It is called after the component's initial render, i.e., after the component has been added to the DOM for the first time. It’s used to perform tasks that require the component to be fully rendered and part of the DOM, such as interacting with the DOM, initializing third-party libraries, or setting up event listeners. It runs only once, immediately after the component's first render.

In our case: After the initial render, this method initializes the ECharts instance, sets up a ResizeObserver to handle resizing, and configures the chart options using the component's properties.

C. Why updated?

It is called after the component's update has been rendered to the DOM. It allows you to perform operations after the component has updated, such as interacting with the DOM based on new properties or states. It runs after each update (initial and subsequent updates).

In our case: After the component updates, this method sets the new options for the ECharts instance, ensuring that the chart reflects the latest data and configuration.

D. Why disconnectedCallback?

It is a lifecycle method that is invoked when a component is removed from the DOM. This method is useful for performing cleanup tasks such as removing event listeners, canceling timers, or cleaning up any other resources that the component might have allocated. It runs when the component is detached from the DOM, such as when it is removed or replaced.

In our case: When the component is removed from the DOM, this method disconnects the ResizeObserver and disposes off the ECharts instance to clean up resources and consequently, prevent memory leaks.

How can you consume such a component in your apps?

You can find some quick instructions in the official Lit docs here. For ReactJS, Lit provides additional support; this integration guide will be very helpful.

If you'd like to consume the same choropleth component share above, it can be easily installed via NPM:

yarn add @manufac/web-components

Further, we have added some example integrations in CodeSandbox to simplify the process:

These examples should help you get started quickly and more conveniently.

Interested in learning how web components can be added to Wordpress blogs/sites? Let us know in the comments and we'll be happy to share another blog for the same. 🧑‍💻😀👋

Do consider web components for your framework agnostic UI requirements; they just might be what you need!

Using Apache ECharts with ReactJS and TypeScript: Server Side Rendering (SSR)

Manufac — Thu, 19 Oct 2023 07:11:17 +0000

What is SSR?

BairesDev explains this well: Server Side Rendering (SSR) is a paradigm under which we render web pages on the server before sending them to the client.

It has both pros and cons, but some use cases may well justify its adoption. For instance, better search engine indexability could be a huge selling point for SSR for some people.

Broadly speaking, whatever aligns well with your end objectives (CSR, SSR, or a hybrid approach) is fine. However, in this article, we mainly explore how to render charts using Apache ECharts via SSR.

How does Apache ECharts help us in building SSR apps?

As a charting library, it offers built-in support for both CSR and SSR modes.

The visualization instances produced by Apache ECharts can easily be converted to PNG data URLs on the server side. Further, it exposes an isomorphic API to allow converting these instances to SVG strings as well.

Subsequently, these image strings can be rendered in the browser using the <img> element, allowing for server-side rendering (SSR) capability.

The following discussion focuses on building ReactJS SSR applications using NextJS but this approach should work as a blueprint for other frameworks too.

Before we dive into the SSR way of using ECharts, here's a quick refresher on the CSR approach.

CSR Snippets

If you pick the Canvas Renderer, here's how a CSR Scatter Plot component may look like. If the following syntax feels alien, you may want to go through two other articles in this series first: this and this.

// Import necessary modules and types from "echarts"
import { ... } from "echarts/...";
import { CanvasRenderer } from "echarts/renderers";
import { useRef, useEffect } from "react";

use([
  ...,
  ...,
  CanvasRenderer,
]);

export interface Props {
  theme?: "light" | "dark";
  data: Record<string, number>[];
}

export function CanvasRendererScatterPlot({
  theme,
  data,
}: Props): JSX.Element {
  const chartRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const chart = init(chartRef.current, theme);

    return () => {
      chart?.dispose();
    };
  }, [theme]);

  useEffect(() => {
    if (chartRef.current !== null) {
      const chart = getInstanceByDom(chartRef.current);
      const option = {...};
      chart?.setOption(option, true);
    }
  }, [data, theme]);

  return (
    <div
      ref={chartRef}
      style={...}
    />
  );
}

But if you want to pick the SVG Renderer instead, the code is mostly the same except that instead of using CanvasRenderer, we will need to use SVGRenderer.

Now, moving onto the SSR approach:

SSR Snippets

A. Canvas

import { ... } from "echarts/...";
import { CanvasRenderer } from "echarts/renderers";
import { Canvas, createCanvas } from "canvas";

use([
  ...,
  ...,
  CanvasRenderer,
]);

export function getCanvasScatterPlotServerSideProps(points: number): Canvas {
  const canvas = createCanvas(400, 500);
  const chart = init(canvas as unknown as HTMLCanvasElement);
  const option = {
    ...,
    series: {
      type: "scatter",
      encode: {
        x: "x",
        y: "y",
      },
      progressiveThreshold: points + 1,
    },
    ...
  };
  chart.setOption(option);

  return canvas;
}

The dataURL can be generated from the Canvas instance via canvas.toDataURL(). This data URL can be sent to the client which can then render the chart image as follows:

import Image from "next/image";

export function SSRCanvasRendererScatterPlot({ url }: { url: string }): JSX.Element {
  return (
    <div style={...}>
      <Image src={url} width={400} height={500} alt="SSR canvas scatter plot" />
    </div>
  );
}

B. SVG

import { ... } from "echarts/...";
import { SVGRenderer } from "echarts/renderers";

use([
  ...,
  ...,
  SVGRenderer,
]);


export function getSVGScatterPlotServerSideProps(points: number): string {
  const chart = init(null as unknown as HTMLElement, undefined, {
    renderer: "svg",
    ssr: true,
    width: 400,
    height: 500,
  });

  const option = {
    ...,
    animation: false,
    series: {
      type: "scatter",
      encode: {
        x: "x",
        y: "y",
      },
      progressiveThreshold: points + 1,
    },
    ...
  };

  chart.setOption(option);
  const chartData = chart.renderToSVGString();
  chart.dispose();
  return chartData;
}

Similar to Canvas, the SVG string can be sent to the client where it can be rendered as follows:

import Image from "next/image";

export function SSRSVGRendererScatterPlot({
  svgDataString,
}: {
  svgDataString: string;
}): JSX.Element {
  return (
    <div style={{ ... }}>
      <Image
        src={`data:image/svg+xml;utf8,${encodeURIComponent(svgDataString)}`}
        width={400}
        height={500}
        alt="SSR SVG scatter plot"
      />
    </div>
  );
}

Now that we know how to generate charts on server-side, we simply need a mechanism to fetch that data on the client-side for final rendering. The API Routes approach is showcased below. However, the Server Components approach should work fine as well.

// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
import { getCanvasScatterPlotServerSideProps } from "@/components/SSRCanvasRendererScatterPlot";
import { getSVGScatterPlotServerSideProps } from "@/components/SSRSVGRendererScatterplot";
import { SSRScatterPlotData } from "@/components/utils";
import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(req: NextApiRequest, res: NextApiResponse<SSRScatterPlotData>) {
  const { points } = req.query;
  let ssrData: SSRScatterPlotData = { svgDataString: "", canvasDataURL: "" };
  ...
  ...
  const canvas = getCanvasScatterPlotServerSideProps(...);
  const svgDataString = getSVGScatterPlotServerSideProps(...);
  ssrData = { svgDataString, canvasDataURL: canvas.toDataURL() };
  res.status(200).json(ssrData);
}

And then, we can consume those image strings as shown below:


export const getServerSideData = async (...) => {
  ...
  const rawRes = await fetch(`/api/...`, {
    method: "GET",
  });
  const { canvasDataURL, svgDataString } = (await rawRes.json());
  return {
    canvasDataURL,
    svgDataString,
  };
};

...
...

const [ssrData, setSSRData] = useState();

useEffect(() => {
  ...
  getServerSideData(...)
    .then((res) => {
      setSSRData(res);
    })
    .catch(console.log);
  setData(scatterPlotData);
}, [value]);

...
...

<Grid>
  <Grid.Col span={6} h="50vh">
    {ssrData?.canvasDataURL === undefined ? null : (
      <SSRCanvasRendererScatterPlot url={ssrData.canvasDataURL} />
    )}
  </Grid.Col>
  <Grid.Col span={6} h="50vh">
    {ssrData?.svgDataString === undefined ? null : (
      <SSRSVGRendererScatterPlot svgDataString={ssrData.svgDataString} />
    )}
  </Grid.Col>
</Grid>

Parting Notes

Generating charts on server-side via ECharts is achievable, thanks to the in-built support that ECharts provide.
The approach involves creating a PNG or SVG string on the server side and then rendering that string on client side using the <img> element's src attribute.
Although ECharts provide support for animation in server-side rendered charts by embedding CSS animations in the output SVG string, those animations can still feel limited as compared to JS animations.
While rendering a scatter plot on server-side via SVG renderer, we observed that all the points were getting rendered in 1 corner instead of their expected places. Disabling the animation fixed the issue.
Another thing that made us scratched our heads for a bit was the progressive rendering feature that ECharts provides.

Since ECharts 4, "progressive rendering" is supported in its workflow, which processes and renders data chunk by chunk alone with each frame, avoiding to block the UI thread of the browser.

Although it can be desirable in CSR cases, for SSR it understandably led to partial rendering of the chart whenever the data exceeded the progressiveThreshold. We resolved this issue by always setting the progressiveThreshold to value greater than the size of the data so that progressive rendering doesn't trigger.

Interacting with Shimmer3 using Node SerialPort

Manufac — Sun, 23 Apr 2023 09:46:24 +0000

The Web Bluetooth API allows us to connect and interact with Bluetooth Low Energy (BLE) devices. But what are these BLE devices, and is there any other category of bluetooth devices too?

A Nordic Semiconductor blog explains it well. The W3C Draft Community Group Report on Web Bluetooth also indicates towards two major modes of Bluetooth protocols: Bluetooth Classic and Bluetooth Low Energy (alias, Bluetooth Smart). The Classic variant can support data transfer speeds of upto 24 Mbps, whereas BLE is limited to about 1MBps only.

But then why is BLE "smart"? The hint is in the name. BLE protocol allow the devices to leave their transmitter off most of the time, hence, reducing their energy/battery consumption.

So, we have Web Bluetooth API to handle BLE devices. We've established that in the past as well, but what about Bluetooth Classic devices? How to connect to those? Bluetooth Classic has good use cases in audio streaming applications. Even if BLE Audio takes over these audio applications in the future, there can still be legacy Bluetooth devices that you need to connect to.

BTW, Auracast, which is one of the BLE Audio capabilities, looks so cool!

In this article, we'll try to address how to connect to a Bluetooth Classic device in the JS/TS world. Instead of just giving a general overview of such a process, we will also focus on connecting a NodeJS application to Shimmer3, a legacy Bluetooth device.

We hope that at least some of the learnings shared below are transferable to your own use cases and help you connect to your devices without feeling too information-constrained.

Let's begin!

There are some legacy bluetooth (Bluetooth Classic) devices that emulate a serial port. Hence, we can treat such devices as serial devices and open up the possibility to utilize tools like the Web Serial API (for browser environments) and Node SerialPort (for NodeJS environments) to interact with them.

Under this premise, here's how we interacted with a Shimmer3 device (which does emulate a serial port) via a NodeJS application.

The Shimmer team has open sourced the code for interacting with a Shimmer3 device using Python. The JS/TS approach that we are sharing is built upon the learnings of their Python source code.

ShimmerResearch / shimmer3

Shimmer3 applications for Code Composer Studio

FW_Shimmer3

LogAndStream, S3_Sleep settings

compiler information:

workbench: TI CCS v11.2.0.00007

compiler version: TI v21.6.0.LTS

output format:

eabi (ELF)

View on GitHub

Steps:

A. Fetch a list of all available Serial Port devices.

import { SerialPort } from "serialport";
const availablePorts = await SerialPort.list();

B. Establish connection with the desired port (the one corresponding to the Shimmer3 device).

const port = new SerialPort({ path: comPort, baudRate: 115200 });

115200 was chosen as the baud rate as per the Shimmer team's GitHub info. This value indicates that the concerned port is capable of transferring a maximum of 115200 bits per second. Further, instantiating the SerialPort class immediately opens the port. As per the Web Serial API specifications draft, it is necessary to open the port before beginning any communication with the device.

C. The only thing left now is communicate with the device. The data can be read and written in the following way:

import { Buffer } from "node:buffer";

// Read

port.on('data', (data: Buffer) => {
  console.log(`Data: ${data}`);
});

// Write

port.write('Message Details');

// OR

port.write(Buffer.from('Message Details'));

D. Once done, the port can simply be closed:

port.close()

Now that we have a general handle over things, let's get into some specifics to understand how a typical communication between a serial port device and a NodeJS application might look like.

You might have already inferred by now that serial ports support 2-way data transfer (data coming from the device & data going to the device).

In the context of Shimmer3, the data that gets sent to the device are some types of commands. In return, the device responds back with some type of response.

Say, we want to read Battery Voltage, GSR, and PPG values from the device. We can convey it to the device via:

import { pack } from "python-struct";

const command = pack("BBBB", 0x08, 0x04, 0x21, 0x00); 
port.write(command);

Thereafter, we should wait for the device to acknowledge & accept our command. The acknowledgement message that Shimmer3 returns looks like:

port.on("data", (res: Buffer) => {
    const acknowledgment = pack("B", 0xff);
    if (res.toString() === acknowledgment.toString()) {
      console.log("Device has acknowledged our command.");
    }
});

Similarly, we can specify the sampling frequency to the device via:

const samplingFrequency = 2;
const clockWait = 32768 / samplingFrequency;
const command = pack("<BH", 0x05, clockWait);
port.write(command);

For each such command, we should wait for an acknowledgement as done above.

Finally, we can ask the device to start streaming by sending the following command:

const command = pack("B", 0x07);
port.write(command);

The data can be received the same way as done before:

port.on("data", (res: Buffer) => {
  // Do whatever
}

Once done, the streaming can be stopped and the port can be closed:

const command = pack("B", 0x20);
port.write(command);
// Wait for acknowledgement, and then close the port
...
...
port.close();

That's it; that's the majority of the workflow. YMMV depending on the device you end up using, the structure of the request (command) and response messages, your data post-processing needs, etc.

Parting Notes:

So far, we have seen how to open the serial port, set up the device, start streaming, receive data, stop streaming, and finally, close the port. However, it still may not have made complete sense since were dealing with binary format.

What does the following stuff from earlier even mean?

import { pack } from "python-struct";

const command = pack("BBBB", 0x08, 0x04, 0x21, 0x00);

struct is a Python core module and python-struct happens to be a JS equivalent of it. Essentially, this module helps in packing data into binary format in a structured way so that the data can later be decoded & consumed properly by the receiving device. The decoding/unpacking can be done using the unpack command.

Here's a good primer on struct:

Node SerialPort also ships with a bunch of parsers to turn the binary data into readable bits of messages. Depending on your use case, these parsers may turn out to be more suitable as compared to python-struct. Likewise, some interesting use cases might even warrant using these parsers in tandem with python-struct.

Interacting with Polar Verity Sense using Web Bluetooth

Manufac — Sun, 18 Sep 2022 10:03:21 +0000

How can I connect a Bluetooth device to my web application?

If you are looking for an answer to the above question, read on. More specifically, we'll try to decipher how can you use the Web Bluetooth API to connect to a standards compliant BLE device.

While our discussion applies to any standards compliant BLE device, the example focuses on Polar Verity Sense, Heart Rate Monitoring, and Device Battery Level Monitoring. Polar, among other things, is a top manufacturer of heart rate sensors.

Steps:

Request device connection using navigator.bluetooth.requestDevice.
- The method allows you to filter the available devices present in your vicinity.
- This is good because we can utilize this filter to showcase only those devices to the end user that are relevant to the web app.
- For instance, if our app is focused solely on connecting to Polar Verity Sense devices, we can do:

  const device = await navigator.bluetooth.requestDevice({
      filters: [
        {
          namePrefix: "Polar Sense",
          manufacturerData: [{ companyIdentifier: 0x006b }],
        },
      ],
      acceptAllDevices: false,
      optionalServices: [0x180d, 0x180f]
    });

Here, 0x006b is a unique identifier assigned by the Bluetooth Special Interest Group (SIG) specifically to the Polar Electro OY company. If you are working with devices by some other manufacturers, this list can come in handy.

One manufacturer can have multiple devices/products in the market. For example: Polar Verity Sense and Polar H10.

If we want to further filter down on the devices, the namePrefix can help achieve that. In our case, our focus was Polar Verity Sense and all such devices show up in the available BLE devices list as Polar Sense XXXXXX. Hence, the namePrefix of Polar Sense was used.

Note: The available BLE devices list shows up as soon as your fire navigator.bluetooth.requestDevice method. From the list, you can then select the device you want to connect to. Here's how it looks.

Moving further, it is an API quirk that acceptAllDevices must not be true if filters are defined. Please go through the TypeError exceptions to dig more.

You may encounter an error like this:

Origin is not allowed to access any service. Tip: Add the service UUID to 'optionalServices' in requestDevice() options.

To tackle this, optionalServices property can be defined as well. Since, we only care about heart rate and device battery level monitoring, only the corresponding GATT services are specified: 0x180d, 0x180f. If you are interested in allowing other services or knowing the codes for other services, this document should greatly help. If you don't know which services your device supports, you can also obtain a list of all the available services in your device.

Once you have access to the BluetoothDevice object, you can initiate a connection to the device's GATT server via the following.

const gattServer = await device.gatt?.connect();

MDN: The BluetoothDevice.gatt read-only property returns a reference to the device's BluetoothRemoteGATTServer.

After the GATT server is connected to, you can access the concerned services via:

  const heartRateService = await gattServer?.getPrimaryService(0x180d);
  const batteryLevelService = await gattServer?.getPrimaryService(0x180f);

A "service" is simply a collection of attributes that we may be interested in. The attributes which holds the value of the property of interest are termed as characteristics. Now, we want to obtain the heart rate and battery level characteristics from the respective services:

  const heartRate = await heartRateService?.getCharacteristic(0x2a37);
  const batteryLevel = await batteryLevelService?.getCharacteristic(0x2a19);

0x2a37 and 0x2a19 are the BluetoothCharacteristicUUIDs which can be obtained from this document. Similar to services, you can also discover a list of characteristics contained by your service of interest.

At this stage, all the necessary connections are established and all the required object references are obtained. Now, we simply need to start listening to the changes in these "charateristics". The API is rather simple here:

heartRate.addEventListener("characteristicvaluechanged", () => { ... }
batteryLevel.addEventListener("characteristicvaluechanged", () => { ... }

The above snippet simply start listening to the "changes" in characteristics of interest. We also need to tell the device to regularly publish its data to our web app as follows:

await heartRate.startNotifications();
await batteryLevel.startNotifications();

Fortunately, we also have the option to read any characteristics on-demand via:

const batteryData = await batteryLevel.readValue();
const heartData = await heartRate.readValue();

Now, the more interesting part arrives. The data/characteristic's values that we get from the device is in binary format and is exposed via DataView. As a result, we need to parse them in a certain way to make them inferable. Each characteristic can pack its data in certain way. Hence, as the characteristic's type changes, the parsing logic may also need to be changed.
The parsing logic for heart rate and battery level characteristics are:

function parseHeartRate(input: DataView): number {
  const dataFlag = input.getUint8(0);
  let heartRate = NaN;
  if (dataFlag === 0) {
    heartRate = input.getUint8(1);
  } else {
    heartRate = input.getUint16(0);
  }
  return heartRate;
}

function parseBatteryLevel(input: DataView): number {
  return input.getUint8(0);
}

If you encounter a different characteristic in your use case, you can derive the parsing logic yourself by going through the respective service specifications.
Once you finally have the data in the desired form/type, you enter into a realm of endless possibilities wherein you can your data can behave the way your business logic demands.

Parting Notes:

We strongly recommend going through Communicating with Bluetooth devices over JavaScript for deeper dive into the subject.
Web Bluetooth Samples are live samples that can help you rapidly test your BLE devices without any coding/initial setup.
Bluetooth Generic Attribute Profile presents a good primer on the terms like "server", "service", "attributes", "characteristics", etc. in the BLE context.

Using Web Bluetooth in an Electron App in 2022

Manufac — Sun, 12 Jun 2022 14:17:00 +0000

The Web Bluetooth API is quite a thoughtful browser feature that allows you to interact with your BLE peripherals. If you have such a device handy at the moment, consider testing its capabilities via this link. Say, you could conveniently find out the device information "characteristics" of your peripheral which include details like manufacturer's name, firmware, hardware, and software details, model number, etc. via Bluetooth. I wouldn't dive deeper into the capabilities of the API and shall be assuming that you know how it works.

One thing to note is that this API is currently experimental and isn't too widely supported. Fortunately, Chromium and hence, Chrome and Edge support it to a decent extent which is good enough for a lot of common use cases.

Its availability in Chromium indicates that Electron Apps can utilize it as well. However, the developer experience in doing so isn't too ideal. At the time of this writing, when we "request" a connection to a BLE peripheral, the Electron app doesn't show you any popup window to allow you to select the device you want to connect with. Instead, it silently connects with the first available device which doesn't sound so great. This article is dedicated to getting past this issue.

Chrome and Edge don't have this issue. You get a popup containing a list of devices to choose from.

Okay, so let's quickly reiterate the problem: we don't have access to any popup window or UI to select the preferred BLE device from an Electron App.

Now, what could be the solution? Any frontend developers caught any hint? 👩‍💻🤔

Well, if there is no popup, then let's simply create a popup. 😅

Yes, the solution is that straightforward only if we know what Inter-Process Communication in Electron means. The Electron team has already published a great primer on it. IMO, it should be enough to learn all what we need regarding IPC.

Electron App developers would know that it runs on 2 processes: main and renderer. The main process handles the NodeJS side of things and is responsible for spawning the renderer process which in turn is responsible for rendering the web page.

Now what happens is that once we fire a Bluetooth connection request (requestDevice) in the renderer process, it interestingly triggers a "select-bluetooth-device" event in the main process. The payload of this event contains an array of all the available BLE devices. Upon receiving that list, we need to send it to the renderer process to create the required popup UI. This is where IPC is used: to help the main and the renderer processes communicate with each other.

Now, let's zoom in and look at the code:

Renderer: I need to connected to a BLE so I have triggered requestDevice.

const device = await navigator.bluetooth.requestDevice({...});

Main: Since I was listening to "select-bluetooth-device", I have received the device list. Sending it to you via the xyz channel.

  win.webContents.on("select-bluetooth-device", (event, devices, callback) => {
    event.preventDefault();
    win.webContents.send("xyz", devices);
    console.log("Bluetooth device list dispatched.");
  });

Renderer: Since I was already listening to the xyz channel, I have received the device list. I'll use it to create my popup.

// preload.ts
handleBluetoothDevices: (callback: (evt: IpcRendererEvent, value: ElectronBluetoothDevice[]) => void) => {
    // Fire the callback when we receive something on the "xyz" channel
    ipcRenderer.on("xyz", callback);
},

// renderer.ts
window.electronAPI?.handleBluetoothDevices((_evt: IpcRendererEvent, value: ElectronBluetoothDevice[]) => { 
  // Use the devices array to create the popup
 });

Renderer: I created my popup and the user has selected a device. I am sending the device ID to you (via the abc channel) because you have the "means" to connect to a BLE.

// renderer.ts
window.electronAPI?.selectBluetoothDevice(deviceID);

// preload.ts
selectBluetoothDevice: (value: string) => {
    // Send the device ID to "main"
    ipcRenderer.send("abc", value);
},

Main: I was listening to the abc channel and have received the device ID. Connecting to the device now.

  ipcMain.on("abc", (_evt: IpcMainEvent, value: string) => {
    ...
    console.log(`Bluetooth device '(${value})' selected.`);
  });

Now, how does `main` connects to a BLE?

Recall the following:

win.webContents.on("select-bluetooth-device", (event, devices, callback) => {

Here, apart from getting the device list, we also get a "one-time" callback. When this callback is fired with "", the BLE connection terminates and when it is fired with a device ID, a connection to the corresponding BLE peripheral gets established. Finally, you can start interacting with your device. 🚀

Parting Notes:

Since Web Bluetooth API is supported in Chromium, we may be naively thinking of it as a straightforward process. The intent behind this article was to uncover some intricate details which a first time implementer may not know.
This SO entry ❤️ can be quite helpful in explaining the workflow in more depth. Recommend anyone in the process of utilizing the Web Bluetooth API in an Electron App to go through it.
macOS users remember to allow Chromium and your IDE (say, VS Code) access to Bluetooth via System Preferences if you don't want to waste a few hours scratching your head. Speaking from experience.

Using Apache ECharts with React and TypeScript: Regression Transform

Manufac — Sun, 27 Feb 2022 14:33:00 +0000

In one of our previous articles, Using Apache ECharts with React and TypeScript: Using Aggregate Transform, we talked about a few data transformation functionalities available in the ECharts ecosystem.

echarts-stat happens to be a very popular ECharts plugin useful in performing a wide range of data transformations like regression, histogram binning, k-means clustering, etc. However, it doesn't seem to be on an active development cycle and is currently suffering from at least 1 TS compatibility issue.

In essence, this plugin is written in JS and has a .d.ts file to expose the type information. Unfortunately, the type definition file doesn't export any of the transforms. Consequently, our TSC starts complaining when we try to import any of the transforms.

Turns out that module augmentation is a neat solution to this missing types problem. Here's what we ended up doing to fix the missing types/modules error:

// some-name.d.ts

import type { ExternalDataTransform } from "@manufac/echarts-simple-transform";

/**
 * Needed because of: https://github.com/ecomfe/echarts-stat/issues/35
 * Module augmentation: https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation
 */
declare module "echarts-stat" {
  let transform: {
    regression: ExternalDataTransform;
    histogram: ExternalDataTransform;
    clustering: ExternalDataTransform;
  };
}

You may obtain more information on @manufac/echarts-simple-transform in Using Apache ECharts with React and TypeScript: Using Aggregate Transform.

Okay, now how to use `echarts-stat` with TypeScript and React?

Since the TSC errors are now resolved by the addition of the declaration file (as described above) in our project, we can safely import "transform" from "echarts-stat". Here's the full recipe:

import { transform } from "echarts-stat";
import { ScatterChart, LineChart } from "echarts/charts";
import { TransformComponent } from "echarts/components";
import { init, getInstanceByDom, use, registerTransform } from "echarts/core";
import { useRef, useEffect } from "react";
import type { ScatterSeriesOption, LineSeriesOption } from "echarts/charts";
import type { ECharts, ComposeOption } from "echarts/core";

// Register the required components
use([
  TitleComponent,
  TooltipComponent,
  GridComponent,
  DatasetComponent,
  LegendComponent,
  ToolboxComponent,
  CanvasRenderer,
  ScatterChart,
  LineChart, // In order to plot regression lines
  TransformComponent, // Built-in transform (filter, sort)
]);

registerTransform(transform.regression); // No missing module error due to module augmentation as done above

// As per docs: https://echarts.apache.org/handbook/en/basics/import/#minimal-option-type-in-typescript
export interface ScatterPlotChartProps extends BaseEChartsProps {
  option: ComposeOption<TitleComponentOption | TooltipComponentOption | GridComponentOption | DatasetComponentOption | ScatterSeriesOption | LineSeriesOption>;
}

export function ScatterPlotChart({
  option,
  style,
  settings,
  loading,
  theme,
}: ScatterPlotChartProps): JSX.Element {
  const chartRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    // Initialize chart
    let chart: ECharts | undefined;
    if (chartRef.current !== null) {
      chart = init(chartRef.current, theme);
    }

    // Add chart resize listener
    // ResizeObserver is leading to a bit janky UX
    function resizeChart() {
      chart?.resize();
    }
    window.addEventListener("resize", resizeChart);

    // Return cleanup function
    return () => {
      chart?.dispose();
      window.removeEventListener("resize", resizeChart);
    };
  }, [theme]);

  useEffect(() => {
    // Update chart
    if (chartRef.current !== null) {
      const chart = getInstanceByDom(chartRef.current);
      chart?.setOption(option, settings);
    }
  }, [option, settings, theme]);

  useEffect(() => {
    // Update chart
    if (chartRef.current !== null) {
      const chart = getInstanceByDom(chartRef.current);
      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
      loading === true ? chart?.showLoading() : chart?.hideLoading();
    }
  }, [loading, theme]);

  return (
      <div ref={chartRef} style={{ width: "100%", height: "100px", ...style }} />
  );
}

And, how does an `option` object look like?

The entire props object is shown below which can be passed to the ScatterPlotChart component as <ScatterPlotChart {...props} />.

const props = {
  option: {
    dataset: [
      {
        source: [[1, 2], [4, 7], [2, 6], [3, 8], ...]
      },
      {
        transform: {
          type: "ecStat:regression",
          config: { method: "polynomial", order: 3 },
        },
      },
    ],
    grid: {
      containLabel: true,
    },
    title: {
      text: "Scatter-Regression Chart",
      left: "center",
    },
    legend: {
      bottom: 5,
    },
    tooltip: {
      trigger: "item",
    },
    xAxis: {
      name: "Year of Experience",
    },
    yAxis: {
      name: "Salary",
    },
    series: [
      {
        name: "Experience-Salary",
        type: "scatter",
      },
      {
        name: "Cubic Polynomial",
        type: "line",
        datasetIndex: 1,
        symbol: "none",
        // to show regression formule
        endLabel: {
          show: true,
          distance: -200, // distance of endLabel from the grid
          formatter: (params) => {
            const datum = params.data as (string | number)[];
            return datum[2].toString();
          },
        },
      },
    ],
  },
  style: {
    height: "300px",
  },
}

Parting Notes

If the use of use(...) function and ComposeOption<...> generic type seems weird, you should go through our older article, Using Apache ECharts with React and TypeScript: Optimizing Bundle Size, to learn more about it. TLDR: they are a way to optimize the bundle size.
This plugin doesn't export regression coefficient value (R^2) which seems to be an important missing feature. Nevertheless, the plugin looks pretty comprehensive in that it supports so many kinds of data transformations. For instance, even within just the regression transform, it supports linear, logarithmic, exponential, and polynomial (nth order) flavors.
It would have been way nicer if this plugin (echarts-stat) was more actively maintained though.

Thanks for reading. Feel free to share your views and suggestions. 📚 📖

Using Apache ECharts with React and TypeScript: Using Aggregate Transform

Manufac — Sun, 27 Feb 2022 11:50:00 +0000

While dealing with scatter plots, bar charts, etc., it is common to run into requirements wherein you need to perform some data-transformation prior to rendering any visualization. For instance, you may want to sort all the bars in your bar chart in an ascending order, showcase linear regression in your scatter plot, or filter data points belonging to a certain date range. Fortunately, Apache ECharts supports some of these use-cases out-of-the-box.

However, native support for 2 important (IMO) transformations is still missing: regression (in scatter plot) and group-and-aggregate (in bar chart). Since Apache ECharts supports custom data-transforms as well, we were fortunate to find third-party transformation plugins for both of our needs: echarts-simple-transform and echarts-stat. ✨

echarts-simple-transform plugin, however, isn't that well maintained currently and has TypeScript compatibility issues as well. We addressed the shortcomings of this plugin in a new fork and published it as: @manufac/echarts-simple-transform.

This article shall delve into how to use @manufac/echarts-simple-transform with TypeScript & React.

Prerequisites

You may want to look into 2 of our previous articles first, to obtain a better understanding of how to integrate ECharts with TypeScript and React:

Once you have understood how to integrate Apache ECharts with React and TypeScript, and how the bundle optmization workflow/syntax looks like, the rest of the article shall be much easier to grasp.

Some Key Notes

You need to register an external data transform first in order to use it. This is the only differentiating thing about the source code. The rest of the source code can be implemented as mentioned in the prerequisite articles.

import { registerTransform, ... } from "echarts/core";
import { aggregate } from "@manufac/echarts-simple-transform";
import type { ExternalDataTransform } from "@manufac/echarts-simple-transform";

registerTransform(aggregate as ExternalDataTransform);

The as assertion in as ExternalDataTransform is needed due to a type mismatch error. Since @manufac/echarts-simple-transform exports ExternalDataTransform, the type mismatch error is easily dealt with using as assertion. This isn't possible with echarts-simple-transform since it doesn't export any types and you may have to resort to @ts-ignore there.
We understand that using as assertion may not be an ideal fix but efforts were taken to refactor some types/interfaces present inside echarts-simple-transform such that as assertion isn't needed. After trying out various alternates, we speculate that some changes are needed in the echarts project itself to update the registerTransform function typings so that it can easily accommodate external/third-party transforms.
echarts-simple-transform has an issue with correctly aggregating (summing up) single element groups. @manufac/echarts-simple-transform overcomes that shortcoming as well. Apart from this bug fix, all of the remaining functionality is kept unchanged.
More differences between the two variants are listed in our project README.

How to use the `aggregate` transform?

Here's the complete recipe:

import { aggregate } from "@manufac/echarts-simple-transform";
import { BarChart } from "echarts/charts";
import { TransformComponent } from "echarts/components";
import { init, getInstanceByDom, use, registerTransform } from "echarts/core";
import { useRef, useEffect } from "react";
import type { ExternalDataTransform } from "@manufac/echarts-simple-transform";
import type { BarSeriesOption } from "echarts/charts";
import type { ECharts, ComposeOption, SetOptionOpts } from "echarts/core";

// Register the required components
use([
  TitleComponent,
  TooltipComponent,
  GridComponent,
  DatasetComponent,
  LegendComponent,
  ToolboxComponent,
  CanvasRenderer,
  BarChart,
  TransformComponent, // Built-in transform (filter, sort)
]);

registerTransform(aggregate as ExternalDataTransform); // `as` assertion is needed

export interface BarChartProps {
  style?: CSSProperties;
  settings?: SetOptionOpts;
  loading?: boolean;
  theme?: "light" | "dark";
  option: ComposeOption<TitleComponentOption | TooltipComponentOption | GridComponentOption | DatasetComponentOption | BarSeriesOption>;
}

export function BarChart({
  option,
  style,
  settings,
  loading,
  theme,
}: BarChartProps): JSX.Element {
  const chartRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    // Initialize chart
    let chart: ECharts | undefined;
    if (chartRef.current !== null) {
      chart = init(chartRef.current, theme);
    }

    // Add chart resize listener
    // ResizeObserver is leading to a bit janky UX
    function resizeChart() {
      chart?.resize();
    }
    window.addEventListener("resize", resizeChart);

    // Return cleanup function
    return () => {
      chart?.dispose();
      window.removeEventListener("resize", resizeChart);
    };
  }, [theme]);

  useEffect(() => {
    // Update chart
    if (chartRef.current !== null) {
      const chart = getInstanceByDom(chartRef.current);
      chart?.setOption(option, settings);
    }
  }, [option, settings, theme]);

  useEffect(() => {
    // Update chart
    if (chartRef.current !== null) {
      const chart = getInstanceByDom(chartRef.current);
      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
      loading === true ? chart?.showLoading() : chart?.hideLoading();
    }
  }, [loading, theme]);

  return (
      <div ref={chartRef} style={{ width: "100%", height: "100px", ...style }} />
  );
}

Finally, the option object can be constructed as given in this documentation.

How to implement a custom data transform?

If you have any use cases which are aren't covered by any of the existing plugins, you could consider implementing one on your own. We couldn't locate any official documentation guiding such a task, so we suggest looking into the source code of the existing plugins as the first step.

These source codes can be especially helpful:

If you liked this post, please consider upvoting this issue on GitHub. Hopefully, that way this aggregate transform shall get natively supported by Apache ECharts and we developers won't need to rely on any third-party solution. 🕺

Using Apache ECharts with React and TypeScript: Optimizing Bundle Size

Manufac — Mon, 17 Jan 2022 06:03:00 +0000

In our first article on this topic, Using Apache ECharts with React and TypeScript, we received a valuable insight from one of our readers.

They suggested looking into Use Apache ECharts with bundler and NPM in order to minimize your bundle size. Now, who doesn't want that!? We tried out the approach and integrated it with our ReactJS workflow.

Key take away was: Import only what you need and let the bundler do its job.

Import the needed functions, charts, chart-components, etc.

import { CanvasRenderer } from "echarts/renderers";
import { init, getInstanceByDom, use } from "echarts/core";
import { HeatmapChart, ScatterChart, LineChart, GraphChart, BarChart } from "echarts/charts";
import {
  LegendComponent,
  GridComponent,
  TooltipComponent,
  ToolboxComponent,
  VisualMapComponent,
  TitleComponent,
  DataZoomComponent,
} from "echarts/components";
import type { ECharts, ComposeOption, SetOptionOpts } from "echarts/core";

Import the corresponding (needed) types:

import type { ECharts, ComposeOption, SetOptionOpts } from "echarts/core";
import type {
  BarSeriesOption,
  LineSeriesOption,
  ScatterSeriesOption,
} from "echarts/charts";
import type { TitleComponentOption, GridComponentOption } from "echarts/components";

// Register the required components
use([
  LegendComponent,
  ScatterChart,
  LineChart,
  BarChart,
  GridComponent,
  TooltipComponent,
  TitleComponent,
  ToolboxComponent, // A group of utility tools, which includes export, data view, dynamic type switching, data area zooming, and reset.
  DataZoomComponent, // Used in Line Graph Charts
  CanvasRenderer, // If you only need to use the canvas rendering mode, the bundle will not include the SVGRenderer module, which is not needed.
]);

Combine the corresponding types.

// Combine an Option type with only required components and charts via ComposeOption
export type EChartsOption = ComposeOption<
  | BarSeriesOption
  | LineSeriesOption
  | TitleComponentOption
  | GridComponentOption
  | ScatterSeriesOption
>;

Here's the complete piece of code:

import { useRef, useEffect } from "react";
import { CanvasRenderer } from "echarts/renderers";
import { init, getInstanceByDom, use } from "echarts/core";
import { HeatmapChart, ScatterChart, LineChart, GraphChart, BarChart } from "echarts/charts";
import {
  LegendComponent,
  GridComponent,
  TooltipComponent,
  ToolboxComponent,
  VisualMapComponent,
  TitleComponent,
  DataZoomComponent,
} from "echarts/components";
import type { ECharts, ComposeOption, SetOptionOpts } from "echarts/core";
import type {
  BarSeriesOption,
  LineSeriesOption,
  ScatterSeriesOption,
} from "echarts/charts";
import type { TitleComponentOption, GridComponentOption } from "echarts/components";

// Register the required components
use([
  LegendComponent,
  ScatterChart,
  LineChart,
  BarChart,
  GridComponent,
  TooltipComponent,
  TitleComponent,
  ToolboxComponent, // A group of utility tools, which includes export, data view, dynamic type switching, data area zooming, and reset.
  DataZoomComponent, // Used in Line Graph Charts
  CanvasRenderer, // If you only need to use the canvas rendering mode, the bundle will not include the SVGRenderer module, which is not needed.
]);

// Combine an Option type with only required components and charts via ComposeOption
export type EChartsOption = ComposeOption<
  | BarSeriesOption
  | LineSeriesOption
  | TitleComponentOption
  | GridComponentOption
  | ScatterSeriesOption
>;

export interface ReactEChartsProps {
  option: EChartsOption;
  style?: CSSProperties;
  settings?: SetOptionOpts;
  loading?: boolean;
  theme?: "light" | "dark";
}

export function ReactECharts({
  option,
  style,
  settings,
  loading,
  theme,
}: ReactEChartsProps): JSX.Element {
  const chartRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    // Initialize chart
    let chart: ECharts | undefined;
    if (chartRef.current !== null) {
      chart = init(chartRef.current, theme);
    }

    // Add chart resize listener
    // ResizeObserver is leading to a bit janky UX
    function resizeChart() {
      chart?.resize();
    }
    window.addEventListener("resize", resizeChart);

    // Return cleanup function
    return () => {
      chart?.dispose();
      window.removeEventListener("resize", resizeChart);
    };
  }, [theme]);

  useEffect(() => {
    // Update chart
    if (chartRef.current !== null) {
      const chart = getInstanceByDom(chartRef.current);
      chart?.setOption(option, settings);
    }
  }, [option, settings, theme]); // Whenever theme changes we need to add option and setting due to it being deleted in cleanup function

  useEffect(() => {
    // Update chart
    if (chartRef.current !== null) {
      const chart = getInstanceByDom(chartRef.current);
      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
      loading === true ? chart?.showLoading() : chart?.hideLoading();
    }
  }, [loading, theme]);

  return <div ref={chartRef} style={{ width: "100%", height: "100px", ...style }} />;
}

Parting Comments

The approach is worth trying out to check for any significant reductions in your bundle size; the small increase in your SLOC may eventually be well justified by a large decrease in your bundle size. In 1 particular scenario, we shaved off 4 MB from our bundle but depending upon your use case, YMMW.
One question may pop in our minds: "how do we know exactly what to import?". One thing you can try is simply observing your console logs. ECharts may throw useful warnings in case something critical is missing. Something like this:

Cheers! 👩‍💻👨‍💻

Using Apache ECharts with React and TypeScript

Manufac — Sat, 03 Jul 2021 05:09:00 +0000

What is Apache ECharts?

It's a cool data-visualization library like Highcharts, Chart.js, amCharts, Vega-Lite, and numerous others. A lot of companies/products including AWS are using it in production.

It supports numerous charts out-of-the-box. Here's a wide range of examples to help you out. We also found their echarts-liquidfill extension quite useful.

Different teams have varying criteria behind adopting a data visualization library. If you happen to use Apache ECharts, this feed may help you integrate it with your React + TypeScript codebase.

How to integrate with React and TypeScript?

You can implement a React functional component and reuse it in different parts of the app to avoid declaring useEffect hook and subscribing/unsubscribing to the "resize" event multiple times.

// React-ECharts.tsx

import React, { useRef, useEffect } from "react";
import { init, getInstanceByDom } from "echarts";
import type { CSSProperties } from "react";
import type { EChartsOption, ECharts, SetOptionOpts } from "echarts";

export interface ReactEChartsProps {
  option: EChartsOption;
  style?: CSSProperties;
  settings?: SetOptionOpts;
  loading?: boolean;
  theme?: "light" | "dark";
}

export function ReactECharts({
  option,
  style,
  settings,
  loading,
  theme,
}: ReactEChartsProps): JSX.Element {
  const chartRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    // Initialize chart
    let chart: ECharts | undefined;
    if (chartRef.current !== null) {
      chart = init(chartRef.current, theme);
    }

    // Add chart resize listener
    // ResizeObserver is leading to a bit janky UX
    function resizeChart() {
      chart?.resize();
    }
    window.addEventListener("resize", resizeChart);

    // Return cleanup function
    return () => {
      chart?.dispose();
      window.removeEventListener("resize", resizeChart);
    };
  }, [theme]);

  useEffect(() => {
    // Update chart
    if (chartRef.current !== null) {
      const chart = getInstanceByDom(chartRef.current);
      chart.setOption(option, settings);
    }
  }, [option, settings, theme]); // Whenever theme changes we need to add option and setting due to it being deleted in cleanup function

  useEffect(() => {
    // Update chart
    if (chartRef.current !== null) {
      const chart = getInstanceByDom(chartRef.current);
      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
      loading === true ? chart.showLoading() : chart.hideLoading();
    }
  }, [loading, theme]);

  return <div ref={chartRef} style={{ width: "100%", height: "100px", ...style }} />;
}

What about `echarts-for-react`?

It does a similar job as the React component implemented above. But we were having trouble in making sure that the chart resizes when the window width changes. Also, at the time of writing this article, it seemed that the library may not be that actively maintained.

You can definitely try out echarts-for-react as it seems to expose more functionalities for the end user than the component implemented above.

But creating our own component eliminated the need to add an extra dependency and gave us more control into how our component should map the input props to ECharts API.

Knowing how the integration with React and TypeScript works under-the-hood, we ourselves can extend the component as and when needed instead of relying on an external library.

Clearly, there are trade-offs involved so choose whatever is more reasonable for your use cases.

How to integrate `echarts-liquidfill` extension?

The approach is quite similar to the component implemented above.

First, we need to specify the type definition for liquidfill charts. We are using the following:

// utils.ts

import type { DefaultLabelFormatterCallbackParams, EChartsOption } from "echarts";

/**
 * interface for LiquidFillGauge series config
 */
interface LiquidFillGaugeSeries {
  name?: string;
  type: "liquidFill";
  data: (
    | number
    | {
        name?: string;
        value: number;
        direction?: "left" | "right";
        itemStyle?: {
          color?: string;
          opacity?: number;
        };
        emphasis?: {
          itemStyle?: {
            opacity?: number;
          };
        };
      }
  )[];
  silent?: boolean;

  color?: string[];
  center?: string[];
  radius?: string;
  amplitude?: number;
  waveLength?: string | number;
  phase?: number | "auto";
  period?: number | "auto" | ((value: number, index: number) => number);
  direction?: "right" | "left";
  shape?: "circle" | "rect" | "roundRect" | "triangle" | "diamond" | "pin" | "arrow" | string;

  waveAnimation?: boolean;
  animationEasing?: string;
  animationEasingUpdate?: string;
  animationDuration?: number;
  animationDurationUpdate?: number;

  outline?: {
    show?: boolean;
    borderDistance?: number;
    itemStyle?: {
      color?: string;
      borderColor?: string;
      borderWidth?: number;
      shadowBlur?: number;
      shadowColor?: string;
    };
  };

  backgroundStyle?: {
    color?: string;
    borderWidth?: string;
    borderColor?: string;
    itemStyle?: {
      shadowBlur?: number;
      shadowColor?: string;
      opacity?: number;
    };
  };

  itemStyle?: {
    opacity?: number;
    shadowBlur?: number;
    shadowColor?: string;
  };

  label?: {
    show?: true;
    color?: string;
    insideColor?: string;
    fontSize?: number;
    fontWeight?: string;
    formatter?: string | ((params: DefaultLabelFormatterCallbackParams) => string);

    align?: "left" | "center" | "right";
    baseline?: "top" | "middle" | "bottom";
    position?: "inside" | "left" | "right" | "top" | "bottom" | string[];
  };

  emphasis?: {
    itemStyle?: {
      opacity?: number;
    };
  };
}

export interface LiquidFillGaugeOption extends Omit<EChartsOption, "series"> {
  series: LiquidFillGaugeSeries;
}

Then, update the ReactEChartsProps:

export interface ReactEChartsProps {
  option: EChartsOption | LiquidFillGaugeOption;
  style?: CSSProperties;
  settings?: SetOptionOpts;
  loading?: boolean;
  theme?: "light" | "dark";
}

Finally, reuse the ReactECharts component to create LiquidFillGauge component:

// LiquidFillGauge.tsx

import React from "react";
import "echarts-liquidfill";
import type { CSSProperties } from "react";
import { ReactECharts } from "../React-ECharts";
import type { LiquidFillGaugeOption } from "../utils";

export interface LiquidFillGaugeProps {
  option: LiquidFillGaugeOption;
  style?: CSSProperties;
}

export function LiquidFillGauge({ option, style }: LiquidFillGaugeProps): JSX.Element {
  return (
    <ReactECharts
      option={option}
      style={style}
    />
  );
}

How do you call this component in an app?

Create an option object, say:

const option: ReactEChartsProps["option"] = {
    dataset: {
      source: [
        ["Commodity", "Owned", "Financed"],
        ["Commodity 1", 4, 1],
        ["Commodity 2", 2, 4],
        ["Commodity 3", 3, 6],
        ["Commodity 4", 5, 3],
      ],
    },
    tooltip: {
      trigger: "axis",
      axisPointer: {
        type: "shadow",
      },
    },
    legend: {
      data: ["Owned", "Financed"],
    },
    grid: {
      left: "10%",
      right: "0%",
      top: "20%",
      bottom: "20%",
    },
    xAxis: {
      type: "value",
    },
    yAxis: {
      type: "category",
    },
    series: [
      {
        type: "bar",
        stack: "total",
        label: {
          show: true,
        },
      },
      {
        type: "bar",
        stack: "total",
        label: {
          show: true,
        },
      },
    ],
  }

Now, simply use it as a prop as you would in any other component:

<div>
  <ReactECharts option={option} />
</div>

Do consider Apache Echarts if you are looking for a data visualization library for your projects.

Feel free to take a look at Using Apache ECharts with React and TypeScript: Optimizing Bundle Size in case you're trying to reduce your bundle size as well.

Implementing Multer Storage Engine in TypeScript

Manufac — Mon, 03 May 2021 07:28:00 +0000

Multer is pretty popular ExpressJS middleware, primarily used to handle file uploads from client to server. However, a lot of other options are available too depending on what fits your use case.

Multer plays along really well with ExpressJS and have out-of-the-box support for storing file in-disk and in-memory, on the server side. Interestingly, Multer can also be used for file streaming applications where you don't need to store the incoming file on server side and directly redirect the incoming file stream to some cloud storage service instead (say, AWS S3). When you need to support the uploads of bulky/large files (say, tens or hundreds of MBs or anything beyond that), streaming can come across as the most practical solution.

The file streaming logic can vary depending on your cloud storage service provide but in this post I'll simply present the storage engine implementation logic in generalized way which you can expand upon based on your use cases. This logic is already presented by the maintainers of Multer here but it uses object prototypes and vanilla JS. For those of us who have gotten the taste of syntactic sugar by using JS classes might find it hard to comprehend that logic right away. Moreover, owing to the popularity of TypeScript, a TS implementation of that storage engine logic may also be handy for the web dev community.

So, here's TS Classes based approach for implementing Multer's Storage Engine:

DEV Community: Manufac Analytics Private Limited

Using Apache ECharts with Lit and TypeScript

What are Web Components?

Why might we need Web Components?

Why not simply use JS/TS to create reusable components programmatically?

How can we build a portable choropleth component using Apache ECharts and Lit?

Why those lifecycle methods were used?

How can you consume such a component in your apps?

Using Apache ECharts with ReactJS and TypeScript: Server Side Rendering (SSR)

What is SSR?

How does Apache ECharts help us in building SSR apps?

CSR Snippets

SSR Snippets

Parting Notes

Interacting with Shimmer3 using Node SerialPort

ShimmerResearch / shimmer3

Shimmer3 applications for Code Composer Studio

FW_Shimmer3

LogAndStream, S3_Sleep settings

Interacting with Polar Verity Sense using Web Bluetooth

Steps:

Using Web Bluetooth in an Electron App in 2022

Now, how does main connects to a BLE?

Using Apache ECharts with React and TypeScript: Regression Transform

Okay, now how to use echarts-stat with TypeScript and React?

And, how does an option object look like?

Parting Notes

Using Apache ECharts with React and TypeScript: Using Aggregate Transform

Prerequisites

Some Key Notes

How to use the aggregate transform?

How to implement a custom data transform?

Using Apache ECharts with React and TypeScript: Optimizing Bundle Size

Parting Comments

Using Apache ECharts with React and TypeScript

What is Apache ECharts?

How to integrate with React and TypeScript?

What about echarts-for-react?

How to integrate echarts-liquidfill extension?

How do you call this component in an app?

Implementing Multer Storage Engine in TypeScript

Now, how does `main` connects to a BLE?

Okay, now how to use `echarts-stat` with TypeScript and React?

And, how does an `option` object look like?

How to use the `aggregate` transform?

What about `echarts-for-react`?

How to integrate `echarts-liquidfill` extension?