DEV Community: Bitovi

Customize Jira's Advanced Planning Tool for Multiple Teams & Projects

amycutlip — Tue, 10 Sep 2024 15:40:04 +0000

Jira’s Advanced Planning tool (the artist formerly known as Advanced Roadmaps) allows users to manage work across multiple projects, products, and teams. However, if you try to use Advanced Planning at scale, it is impossible to set up plans that give each organizational unit what it needs—a plan that shows their work and how it relates to other teams' work.

We’ve created PlanWeaver, a handful of open source Jira automations that give projects, products, and teams the ability to separate and report on the work of each unit or team involved in their program.

In this article, you’ll learn why PlanWeaver is necessary for managing advanced plans at scale and how to implement the automations that make reporting on programs easier and more intuitive.

Why is PlanWeaver needed?

In most large organizations, multiple projects, products, and teams coordinate in various ways. In this article, we’ll use a fictional restaurant technology company called FastCo to illustrate how PlanWeaver can improve clarity within an organization.

In our example, FastCo has multiple products serviced by multiple teams:

FastCo’s products and teams need to support multiple projects, programs, and initiatives that can vary in size and complexity. FastCo has multiple simultaneous implementation programs: Good Burger and Sunny Sushi. Each program contains initiatives that need to be completed by various teams:

Out of the box, Advanced Planning doesn’t provide an easy way to visualize all projects on a team or program level.

Team Level

A team wants to see all the projects they are involved in and the other teams in those projects (so dependencies can be mapped).

The image below shows all the initiatives that the Order team is involved in, as well as the work of other teams in those initiatives.

Program Level

A program wants to see all work within the program, across all of the program's initiatives. The image below shows Sunny Sushi’s work plan; a view not easily available out of box.

The PlanWeaver automations simplify the creation of complex plans by tagging issues. These tags allow you to build the plans as shown above.

Program-level views with Parent Tags

Enter Parent and Child Tags. The PlanWeaver automations add two fields to issues that are Epic or higher in the issue hierarchy:

Parent Tags - The project key of all parent issues of the current issue
Child Tags - The project key of all children of the current issue (and the project key of epic siblings)

Let's see how PlanWeaver’s tags work individually to create useful plans.

Program-level views with Parent Tags

Parent Tags help you build a program or project-level view. Every child of a higher-order issue is tagged with that issue’s project key.

In the image below, Parent Tags allow users to see all of the work related to the Good Burger program. We can see multiple initiatives and their related epics across various teams. Simply querying by the parent tag allows a user to see an organized view of the work planned for the program.

Use the following filter for this Advanced Timeline Plan view:

"Parent Tags[Labels]" = GOODBURGER or project = "Good Burger"

There are two automation files for Parent Tags: one that updates Parent Tags when an issue is changed, and one that populates the Parent Tags in parent issues.

⬇️ Download JSON file

Team views with Child Tags

Child Tags help you build a view of not only a team’s work but also related work from other projects. Child tags improve the Advanced Plans view when a single team has work across multiple programs or projects and needs a way to view it all along with the dependencies.

Below is a view for the Order team, displaying not only the work for the team across multiple initiatives but also the work from other teams that may have dependencies with the Order team’s work:

Use the following filter for this Advanced Timeline Plan view:

"Child Tags[Labels]" = ORDER

There are three JSON files for Child Tags: one to update Child Tags when a parent issue is changed, another to update Child Tags when an issue is moved, and a final automation to update a parent issue's tags when Child Tags change.

⬇️ Download JSON file

Conclusion

Out of the box, it's a challenge to use Jira’s Advanced Planning at an enterprise scale. With our open source PlanWeaver add-on, Advanced Planning becomes more useful for teams to view their work across programs. Adding Epic-level tags enhances reporting and allows program managers and teams to view their work—and how their work impacts other teams—more intuitively.

At Bitovi, we focus on helping our clients make the right decisions for their products and company. Developing new ways to view work, like our PlanWeaver automation, is another way we’re working to perfect product delivery. We’ll have another post soon walking through how to import and use the PlanWeaver automations. In the meantime, be sure to join our Community Discord for support and inspiration. Happy planning!

Protect Your Business from IT Disasters: Lessons from the CrowdStrike Outage

amycutlip — Thu, 25 Jul 2024 19:32:26 +0000

Businesses heavily rely on IT infrastructure for smooth operations and security, but what happens when that infrastructure breaks? Thousands of companies were blindsided by a sudden CrowdStrike outage on Friday, July 19th, leading to a projected cost of $1 Billion. With an estimated 8.5 million devices impacted by the outage, over 5,000 canceled flights, and hundreds of hospital computer systems offline, you’re probably wondering: What can I do to prevent a CrowdStrike-level business disruption?

In this blog, you’ll learn the business impacts of IT disasters, how to prevent them, and the steps you can take today to protect your organization from similar threats.

Up first: Who is Bitovi?

Bitovi is a digital product consultancy dedicated to perfecting product delivery. We’ve provided Quality Engineering Consulting to businesses of all sizes—from lean startups to Fortune 500 enterprises. We write about improving software engineering and delivery practices.

Learn more about Bitovi’s digital consulting services.

Business disruptions and financial losses from IT outages

The CrowdStrike outage serves as a wake-up call to businesses about the severe disruptions that IT failures can cause. Financial losses, operational disruptions, and reputation damage—when critical IT infrastructure fails, the ripple effects can be vast and costly.

Financial losses from IT disasters like the CrowdStrike outage

During the CrowdStrike outage, businesses faced immediate operational challenges. With over 8.5 million devices affected globally, revenue loss during the downtime period was a severe blow to many companies' financial health.

The estimated $1 billion cost reflects not only lost productivity but also the emergency IT remediation efforts required to address the outage. Businesses had to bear the costs associated with restoring operations, including overtime payments to IT staff and, in some cases, hiring specialized consultants.

The financial impacts of IT disruptions are overwhelming, but there is a way forward. Investing in a robust Quality Engineering practice allows organizations to prevent significant disruptions and address them quickly if they do occur.

“In light of the CrowdStrike outage, investing in Quality Engineering is essential. It helps prevent disruptions and ensures quick recovery, minimizing financial losses and protecting business reputation,” says Bitovi’s Director of Quality Engineering Consulting, Denison Luz.

Operational disruptions caused by IT outages

On a human level, the operational disruptions were more devastating than the financial impacts. Industries that depend on real-time data and continuous operations, like airlines, healthcare, and banking, were particularly hard hit. The outage led to the cancellation of over 5,000 flights, causing widespread travel chaos and leaving passengers stranded in airports worldwide. Hospitals struggled to maintain patient care as critical computer systems went offline, forcing staff to revert to manual processes prone to errors and inefficiencies. The impact on patient safety and care quality was a stark reminder of how dependent modern healthcare systems are on reliable IT infrastructure.

[nurse quote, verifying with sources]

These disruptions underscored the need for robust and resilient IT systems that can withstand unexpected failures. Quality Engineering establishes safeguards like regression testing, which ensures new updates are compatible with older systems, keeping systems online and providing critical services.

Reputation damage caused by IT infrastructure failures

Reputation damage is another critical aspect that businesses must consider. For businesses, trust is paramount. An outage that compromises security or disrupts services can erode customer confidence and damage a company’s reputation. The long-term impact on customer trust can be even more damaging than the immediate financial losses. Companies that experience significant outages often face backlash from customers and negative media coverage, which can take years to recover from.

The CrowdStrike outage is a potent reminder that IT resilience is not just a technical issue but a critical business priority. Ensuring that your IT systems are robust and capable of withstanding failures can protect your business from severe financial losses and operational disruptions. It is essential for business leaders to prioritize Quality Engineering and proactive measures to safeguard their organizations against similar threats. Not sure where to start? It’s not too late to preserve your reputation for quality—Bitovi’s Quality Engineering Consultants are available to help enhance your testing practices.

Implementing Quality Engineering to prevent IT outages

People sleeping in airports, plunging stock prices, healthcare disruptions—the CrowdStrike outage made waves beyond the tech industry, affecting millions of businesses and individuals worldwide.

Establishing robust IT infrastructure and proactive measures to prevent such disasters has never been more important. Businesses must recognize the vulnerabilities in their systems and the need for continuous monitoring and quality engineering to ensure resilience.

Investing in advanced Quality Engineering practices and implementing regular quality checks can help in identifying potential points of failure before they lead to significant disruptions. Moreover, having a well-defined incident response plan can mitigate the impact when an outage does occur. Proactive measures like stress testing systems and regular drills can prepare businesses to handle unexpected IT failures more effectively, minimizing downtime and associated costs.

Bitovi can help establish the safeguards to protect your business from IT disruptions. Contact our Quality Engineering Consulting experts for a free consultation.

Hatchify: The Fastest Way to Build JSON: APIs

Heather Stevens — Fri, 22 Mar 2024 14:58:44 +0000

Last week, Bitovi Hatchify officially left the nest! Hatchify is a suite of low-code libraries that provides a powerful scaffold to build CRUD-heavy applications, eliminate boilerplate, and enable your team to focus on domain-specific functionality from day one. Hatchify empowers you to build admin views, dashboards, and B2B apps faster, all while retaining uncompromising flexibility.

One of Hatchify’s long-term objectives is to help developers move faster across all layers of the web stack. In the initial release, we’re most proud of our backend feature set that helps get CRUD API development out of the way early. We built the fastest way to get a high-quality JSON: API implementation packed with features like advanced filtering capabilities, related data queries, and specified response fields.

APIs, Accelerated

A high-quality CRUD API can require typing up a tedious amount of boilerplate code. The API standards, the ORM, the basic route handlers — there’s lots to do before you even have a running app to iterate on. Although code generation tools can help you get a leg up on the initial effort, they can add friction should you eventually need to modify all the generated output. By dynamically defining the backend at runtime, based on your data model, Hatchify solves the same problems as code generation without the friction of schema updates. Hatchify applications adapt to data model & library updates without having to revise all of the generated files.

In addition to saving you time on boilerplate, the API provided by Hatchify fully implements the JSON: API specification, which stipulates solid standards to define the peculiarities of CRUD REST APIs. Get back all the time spent bike-shedding how to implement standard API features like filtering, pagination, including related data, etc. JSON: API offers consistent practices for frontend and backend developers to agree on how resources are fetched and returned. Since Hatchify provides the core of your API for you, you can count on it’s standardized functionality to give your API a consistent start.

Data Modeling

To save all of this time, Hatchify depends on descriptions of the data it will be serving. This data model is written in a simple TypeScript format we call Schemas. Using those descriptions, Hatchify produces a starter application that your team can begin iterating on immediately. Schemas are consumed by the Hatchify ORM, HTTP router, and frontend elements, to configure themselves appropriately for the different resources held in your database.

For example, two schemas for a simple to-do list application:

From that business context, Hatchify can provide a fully functional API, a basic UI, and a React-hook interface to trivialize API access from React-based apps. The API features are showcased in the example below:

We can create an API for two different resources with the ability to:

Do basic CRUD
Use advanced filters
Query-related data in a single request
- Including normalization of related data
Query only for specified fields
Use page or offset/limit-based pagination

For a complete devo of the above capabilities, head to our demo on StackBlitz.

Now that you have the foundational CRUD structure managed, you can seamlessly transition to expanding your API capabilities with any custom endpoints you might need.

Flexibility First

If eventually you find your API requires functionality beyond what Hatchify can provide, our modular approach to building the framework allows you to continue using whatever portions make sense for your uses case. The ORM, HTTP router, request parsing/serialization can all be used independently. We designed Hatchify to provide enough functionality for most apps while providing an easy transition for those who eventually want more control.

Bitovi is committed to keeping Hatchify free and open-source. We believe good software should be accessible to everyone, and we’ll never charge you to use Hatchify.

Our team works to support Hatchify in all modern JS/TS web applications environments, and integrate with all application (meta)frameworks. We are currently working on integration guides for Next.js, Remix and Astro. Our goal is to maintain extensive guides on how we at Bitovi (and the community) have adapted Hatchify for different usages. If you are interested in how Hatchify might work with your existing or prospective web technology stack, say “hi!” in our Discord and we can investigate that together.

Leaving The Nest

Hatchify is taking flight and we’re excited for devs to get back all the time they were going to spend writing CRUD API boilerplate. Our current roadmap includes:

Schema-driven form builder to easily create and edit data
Authorization support
Data migrations
More documentation improvements & integration guides
If there’s something you’d like to see, let us know on Github!

We want to make every dev more efficient - writing schemas in the morning, and building the important parts of their app by lunch. We hope that you’ll be one of the first. Find out more:

Read our Getting Started Guide and API Docs
Get help and support on Bitovi’s Discord
Follow Bitovi on LinkedIn and Twitter

Thanks!

🐣 Nils & The Hatchify Team

Introducing Hatchify: Low-code libraries for React, Node, and Sequelize

Heather Stevens — Wed, 13 Mar 2024 18:50:01 +0000

We are pleased to announce Hatchify - a tool that helps developers build React, NodeJS, and Sequelize apps swiftly. Hatchify provides the speed of a low-code development while enabling complete customization in the patterns familiar to React and Node developers.

If you are starting a new project, check out our Getting Started Guide.

What is Hatchify and what does it do?

Hatchify is a collection of JavaScript libraries for the frontend and backend that takes a data schema and builds commonly needed functionality (like services and grids) while allowing customization later.

To use Hatchify, define your app's data schemas as follows:

const Schemas = {
  Todo: {
    attributes: {
      name: string({ required: true }),
      dueDate: dateonly(),
      ...
    },
    relationships: {
      user: belongsTo("User"),
    },
  }
  User: {
    attributes: {
      name: string({ required: true }),
    },
    relationships: {
      todos: hasMany("Todo"),
    },
  }
}

With a schema, Hatchify creates:

Sequelize object-relational-mapping (ORM) classes
Flexible REST services
Frontend models
Frontend components

The next sections detail how you’d use these parts.

Sequelize ORM classes

hatchifyKoa(schemas).orm.models provides Sequelize classes you can use to query and manipulate the database directly:

const hatchedKoa = hatchifyKoa(schemas);
const Todo = hatchedKoa.orm.models.Todo;

await Todo.getList({where: {name: "Learn Hatchify"}})

Access to the underlying ORM allows you to weave in custom behavior such as advanced validation, while still keeping the benefits of the rest of the toolchain.

Flexible REST services

hatchifyKoa(schemas).middleware provides a flexible and expressive REST API, letting you filter, paginate, sort, specify specific fields, and even include data across tables!

GET /api/todos
  ?include=user
  &fields[User]=name
  &filter[user.name][$ilike]=%Joe%
  &page[limit]=10
  &page[offset]=0
  &sort=dueDate

Frontend model layer

hatchifyReact(schema).model creates React data models and hooks, with full TypeScript support. The React data model can take advantage of filtering, relationships, and pagination - everything the service layer provides. The hooks also update automatically when there are changes (stale-while-revalidate for the win).

const [joesTodos, joesTodosState] = hatchedReact.model.Todo.useAll({
  include: ["user"],
  fields: { "User": ["name"] },
  filter: { "user.name": { $ilike: "Joe%" } },
  page: { limit: 10, offset: 0 },
  sort: ['dueDate'],
})

hatchifyReact(schema).components includes a data grid that supports filtering, pagination, and sorting.

The Hatchify team's next major step is adding components to create and edit data.

What problem is Hatchify solving?

Hatchify is trying to fill a gap between low-code solutions and CRUD generators.

The set-up of a new project can be complex and cumbersome. This gets in the way of agile development, where there is working software to review, adjust, and iterate from.

While there are many code generators and templates to bootstrap a new project, once you start customizing the app or updating the data model, you’re on your own. You have to make those customizations manually, often in multiple different places. You can’t keep experiencing the benefits of the code generator.

Therefore, Hatchify is trying to solve 3 problems simultaneously:

Enable rapid creation of prototype applications
Enable complete customization of the application
Continually providing value while customizing or adding new features.

This means Hatchify is not a code generator or a limiting low-code tool. Instead, it’s a bunch of libraries that you can use whole or in part to match your needs.

At the start of the project, a simple schema will provide you with a working app. An app where you can have conversations with the customer; and designers and developers can begin to iterate.

When you make changes, you can rewrite just the parts you need to change. The rest of the app can still be updated like a low-code tool.

Who is it for?

Hatchify is for products that:

Have CRUD-type behavior
Anticipate a lot of customization
Are built on NodeJS, REST, and React

Hatchify can’t fully compete with a low-code tool yet. You’ll have to build functionality like forms and authorization yourself. But, Hatchify provides a lot of value connecting (with strong TypeScript support) the frontend data layer all the way to the backend model layer and back:

Who is using it?

We’re using Hatchify at Bitovi for all new application development (where Node and React are the stack). We partnered with KlearTrust, a leader in Health IT, to develop Hatchify.

KlearTrust had a good understanding of their data model and needed to quickly validate their designs, while simultaneously building a production application. You can see the sortable and filterable Hatchify DataGrid below:

Using Hatchify, KlearTrust was able to accelerate its development of the full application, providing a straightforward UI (built atop the DataGrid) to manage a reasonably complex data model. You can see Andy Schriever, Senior Vice President of KlearTrust, share his thoughts on using Hatchify.

YouTube:

We’re hopeful you will check out Hatchify and find it as useful as KlearTrust has!

What’s next?

Our goal is to make Hatchify the swiftest way to build custom CRUD apps (or the swiftest way to build the CRUD elements of larger apps). Pending community feedback, we plan to add the following features immediately:

Forms to create and edit data
CRUD authorization support
Data migrations
Continued documentation improvements

If there’s something you’d like to see, let us know on Github!

To get started on Hatchify:

Read our Getting Started Guide and API Docs
Get help and support on Bitovi’s Discord
Follow Bitovi on LinkedIn and X for updates as they happen.

Thanks!

Hatchify Team

Collection of Vue Macros in Vue.js 3.3

Eduard Krivanek — Sun, 28 May 2023 11:06:16 +0000

Many developers (myself included) were excited when Vue.js version 3.3 introduced several functionalities from Vue Macros, the collection of proposed additions to Vue.js that extend its basic functionalities with syntactic sugar.

In this post, you will learn about Vue Macros that became a part of Vue version 3.3 and how you can use them if you are not yet on version 3.3.

What is Vue Macros?

Let's go straight to the source! The official website claims the following:

Vue Macros is a library that implements proposals or ideas that have not been officially implemented by Vue. That means it will explore and extend more features and syntax sugar to Vue.

Looking at its GitHub repo, the library is well maintained. Moreover, Vue Macros supports Vue from version 2.7. To install Vue Macros, you need to run npm i -D unplugin-vue-macros, configure vite.config.ts, and the tsconfig.json as is installation suggests to start using them.

Which Macros do I want to use, you ask? Let’s look into Macros introduced as part of Vue version 3.3.

Macro defineModels

Prior to v3.3, when it came to component two-way binding with v-model, we had to implement props and emits in the child component to receive or notify the parent component about a data change. You usually end up with the following example:

    // MySearch.vue

    <template>
      <div> 
        <button
          v-for="data in store.getLoadedElements"
          :key="data.title"
          @click="() => onInput(data)"
        >
         {{ data.title }}
        </button>
      </div>
    </template>

    <script setup lang="ts">
    // some additional code

    const store = useStore();

    const props = defineProps({
      modelValue: {
         type: Element,
         required: false
      }
    });

    const emits = defineEmits<{
      (e: "update:modelValue", value: Element): void;
    }>();

    function onInput(element: Element) {
      emit('update:modelValue', element)
    }

    // some additional code
    </script>

The defineModels macro is a syntactic sugar by which you can avoid implementing two-way binding for using v-model on the component level instead of the default Vue.js implementation. You can achieve the above logic with the following syntax:

    // MySearch.vue

    <template>
      <div> 
        <button
         v-for="data in store.getLoadedElements"
         :key="data.title"
         @click="modelValue = data"
        >
         {{ data.title }}
        </button>
      </div>
    </template>

    <script setup lang="ts">
    // some additional code

    const store = useStore();
    const { modelValue } = defineModels<{ modelValue: Element }>();

    // some additional code
    </script>

Vue.js 3.3 recently received the defineModels enhancement for two-way binding under the name defineModel, which has the exact same functionality.

You will find more information in our blog post: New in Vue.js 3.3: Two-Way Binding With defineModel Macro. However, opting for the defineModel functionality in Vue.js 3.3, as it is still an experimental feature, you have to modify your vite.config.ts in the following way:

    plugins: [
      vue({
        script: {
          defineModel: true
          // ^^ enables the feature
        }
      })
    ]

Macro definePropsRefs

Reactive props destructuring was quite a requested feature from the Vue.js community. It’s safe to say the developer was excited about the feature released in Vue 3.3. However, the older Vue.js version still receives the following error message when trying to destructure props.

Fortunately, the macro definePropsRefs allows us property destructuring by writing the following code:

    const { showModal, inputValue } = definePropsRefs({
      showModal: {
        type: Boolean,
        required: false
      },
      inputValue: {
        type: String,
        required: false,
        default: ""
      }
    });

Using Vue Macros are much better developer experience than destructuring properties before version 3.3:

    const { showModal, inputValue } = toRefs(
      withDefaults(
        defineProps({
          showModal: {
            type: Boolean,
            required: false
          },
          inputValue: {
            type: String,
            required: false,
            default: ""
          }
       }),
       {
         showModal: false,
         inputValue: ""
       }
      )
    )

If you want to use defineProps an experimental feature in Vue version 3.3, you have to opt-in with the following configuration:

    // vite.config.js
    plugins: [
      vue({
        script: {
          propsDestructure: true
          // ^^ enables the feature
        }
      })
    ]

Macro defineEmit

Using defineEmits wasn’t such a bad experience. You declared and used emits in the following way:

    const emit = defineEmits<{
      (e: 'foo', id: number): void
      (e: 'bar', name: string): void
    }>()

    emit('foo', 10);
    emit('bar', '10'');

Using defineEmit from Vue Macros, you get the advantage of declaring individual emits in the following way:

    <script setup>
    // Declare emit
    const foo = defineEmit<number[]>('foo')

    // Infer emit name from variable name
    const bar = defineEmit<string[]>()

    // Emit array of strings
    const test = defineEmit<string[][]>() 

    foo(10)
    bar('10')
    test(['test1', 'test2'])
    </script>

Vue 3.3 brought a little bit of syntactic sugar, working with defineEmits in the following way:

    const emit = defineEmits<{
      foo: [id: number]
      bar: [name: string]
    }>()

Fortunately, there is no opting-in for this feature, so you can use it right away!

Macro defineSlots

When working with scoped slots in Vue.js, one problem we faced was not knowing what properties were available on the parent component. Here is the following example before Vue version 3.3:

    <!-- <ChildComponent> template -->
    <div>
      <slot :text="greetingMessage" :count="1"></slot>
    </div>

    // ------------------------------------------

    <!-- <ParentComponent> template -->
    <MyComponent v-slot="slotProps">
      {{ slotProps.text }} {{ slotProps.count }}
    </MyComponent>

A developer may access slotProps.anything and receive an error only during the runtime.

Vue.js 3.3 introduced defineSlots, which use types slots, eliminating the parent component of accessing non-existing props from the child. Here is the following example:

    <!-- <ChildComponent> -->

    <template>
      <div v-for="item of items" :key="item">
        <h2>Name</h2>

        <!-- default slot -->
        <slot name="itemNameSlot" :item-name="item">
           {{ item }}
        </slot>
      </div>
    </template>

    <script setup lang="ts">
    const items = ref<string[]>(["item1", "item2", "item3"]);

    defineSlots<{
      itemNameSlot: (props: { itemName: string }) => any;
    }>();
    </script>

    // ----------------------------

    <!-- <ParentComponent> -->

    <template>
      <main>
       <Test>
         <template #itemNameSlot="{ itemName }">
           <a :href="`/someurl/${itemName}`"> 
             {{ itemName }} - click 
           </a>
         </template>
       </Test>
      </main>
    </template>

If you replace the itemName with a different value in the #itemNameSlot="{ itemName }" in the parent component, you will receive the following error:

Fortunately, there is already a macro for the same functionality with the same name - defineSlots from Vue Macros if you are not yet on version 3.3.

Summary

Vue.js 3.3 brought new features that developers were waiting for. The community has already implemented most of these features in a package called Vue Macros. It is a small but convenient collection of utils that can be used even on Vue version 2.7.

Vue.js Reactivity System: Ref, reactive, shallowRef, & shallowReactive

Eduard Krivanek — Thu, 18 May 2023 10:55:55 +0000

Vue.js is a popular JavaScript framework that provides developers with various tools to create dynamic and reactive web applications.

One of the key features of Vue is its reactivity system, which enables the framework to efficiently update the view when the state changes. In this blog post, you’ll learn the different types of reactive objects, such as ref and reactive, when to use which, and ones that you maybe haven’t heard of like shallowRef and shallowReactive.

What is Ref?

The ref function is used to create a reactive reference to a single value. This value can be a primitive type like a string or number or an object or array.

To access the value of the ref function, you need to use the .value keyword. By using reactive references, such as ref, Vue under the hood will track any changes made to this instance and update the DOM if the value of the variable changes. An example can be seen in the following code.

<template>
  <div>
    <button @click="onButtonClick">Toggle Div</button>

    <!-- hidden text -->
    <div v-if="dataModel.showDiv">Here is some hidden text</div>

    <!-- counter value -->
    <div>🚀 Counter value: {{ dataModel.counter }} 🚀</div>
  </div>
</template>

<script setup lang="ts">
const dataModel = ref({ showDiv: false, counter: 0 });

const onButtonClick = () => {
  dataModel.value.showDiv = !dataModel.value.showDiv;
  dataModel.value.counter++;

  console.log(`counter: ${dataModel.counter}`);
};
</script>

Every time you click on the button, a div will be revealed/hidden, and a counter will be incremented. Such a real-world example, I know! In order to tell Vue that you want to make the dataModel reactive, you need to use ref otherwise, the DOM will receive no updates.

What if I don’t use Ref?

Coming back to the above example, you may ask, what would happen if I use a simple object instead of the ref function? Let’s try to execute the following code:

<template>
  <div>
    <button @click="onButtonClick">Toggle Div</button>

    <!-- hidden text -->
    <div v-if="dataModel.showDiv">Here is some hidden text</div>

    <!-- counter value -->
    <div>🚀 Counter value: {{ dataModel.counter }} 🚀</div>
  </div>
</template>

<script setup lang="ts">
const dataModel = {
  counter: 0,
  showDiv: false
};

const onButtonClick = () => {
  dataModel.counter++;
  dataModel.showDiv = !dataModel.showDiv;

  console.log(`counter: ${dataModel.counter}`);
};
</script>

The only change is replacing the ref function with a normal object. However, with the simple change, the whole DOM will stop being reactive, so any change made to the object will not be reflected in the HTML.

Reactive

The reactive function creates a reactive object that can hold any number of properties. However, reactive can't hold primitives. You will receive the following error:

When the properties of this object are updated, the view is updated automatically. This powerful feature makes it easy to create complex reactive applications. Here’s an example of how to use reactive:

<template>
  <div>
    <button @click="onButtonClick">Toggle Div</button>

    <!-- hidden text -->
    <div v-if="dataModel.showDiv">Here is some hidden text</div>

    <!-- counter value -->
    <div>🚀 Counter value: {{ dataModel.counter }} 🚀</div>
  </div>
</template>

<script setup lang="ts">
const dataModel = reactive({
  counter: 0,
  showDiv: false
});

const onButtonClick = () => {
  dataModel.counter++;
  dataModel.showDiv = !dataModel.showDiv;

  console.log(`counter: ${dataModel.counter}`);
};
</script>

⚠️ Warning
When working with the reactive function, always access the object by its keys. When you try to change the reactive variable reference, the reactivity will break. In the following code, you can see an example of a broken reactivity

let dataModel = reactive({
  counter: 0
});

const onButtonClick = () => {
  dataModel = reactive({
    counter: dataModel.counter + 1
  });
};

Should I use Ref or Reactive?

You will find in the documentation that ref is used mainly for primitives but also can be used for objects while reactive is only used for objects.

At first glance, the main difference is just using the .value keyword when accessing the value of the ref property. However, another thing is with the implementation. Taking a look at the ref implementation from Github, you can see the following code:

class RefImpl<T> {
  private _value: T
  private _rawValue: T

  public dep?: Dep = undefined
  public readonly __v_isRef = true

  constructor(value: T, public readonly __v_isShallow: boolean) {
    this._rawValue = __v_isShallow ? value : toRaw(value)
    this._value = __v_isShallow ? value : toReactive(value)
  }

  get value() {
    trackRefValue(this)
    return this._value
  }

  set value(newVal) {
    const useDirectValue =
      this.__v_isShallow || isShallow(newVal) || isReadonly(newVal)
    newVal = useDirectValue ? newVal : toRaw(newVal)
   if (hasChanged(newVal, this._rawValue)) {
     this._rawValue = newVal
     this._value = useDirectValue ? newVal : toReactive(newVal)
     triggerRefValue(this, newVal)
   }
  }
}

Every time you create a reactive variable by ref, passing an object into its constructor, on line 10, it is treated as you would use the reactive keyword. So should I use ref or reactive for objects?

This is a personal preference, but I use ref almost all the time. Despite tediously writing the .value to access the ref’s value, the Vue team is aware of the problem, and the open RFC - Reactivity Transform, was aiming to solve this issue, however, seems like it was abandoned.

Reactivity transform is not yet part of the official Vue.js package, however, you can install Vue Macros, that enrich your VueJS experience with the following configuration:

// vite.config.ts 
import vue from "@vitejs/plugin-vue";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    vue({
     // used to enable tranctivity transform
     reactivityTransform: true
    }),
  ]
});

And use reactivity transformation from Vue Macros in the following way:

<template>
 ...
</template>

<script setup lang="ts">
const dataModel1 = $ref({
  counter: 0
});

const dataModel2 = ref({
  counter: 0
});

const onButtonClick = () => {
  dataModel1.counter++;

  dataModel2.value.counter++;
};
</script>

Reactivity API

Vue provides additional functions to achieve reactivity with high performance in your application. You can learn more about them on the official documentation, however, it is worth highlighting two of them, which are shallowRef and shallowReactive.

ShallowRef

The shallowRef function is similar to ref, but with one key difference: the changes made to its properties will trigger a change only if you change the memory reference. It is used for performance optimizations of large data structures or integration with external state management systems. Looking at the official documents, the Vue community provides us with the following example.

const state = shallowRef({ count: 1 })

// does NOT trigger change
state.value.count = 2

// does trigger change
state.value = { count: 2 }

Examples of when you should prefer using shallowRef instead of ref can be working with chart data, where you want to exclude basic reactivity for application optimization but still have reactivity if you change the data reference. Another example can be working with dynamic components, such as the following example.

<template>
  <section>
    <!-- display buttons for dynamic component -->
    <button @click="dynamicComponent = Comp1">Comp1</button>
    <button @click="dynamicComponent = Comp2">Comp2</button>

    <!-- dynamic component -->
    <keep-alive>
      <component :is="dynamicComponent" />
    </keep-alive>
  </section>
</template>

<script setup lang="ts">
import Comp1 from "../shared/Comp1.vue";
import Comp2 from "../shared/Comp2.vue";

const dynamicComponent = shallowRef();
</script>

ShallowReactive

The shallowReactive function is similar to reactive, without nested objects, because changes made to the properties of nested objects or arrays will not trigger the update of the view. One may consider using it to get minor performance, instructing Vue that nested properties don’t have to be reactive. However, even the Vue.js team gives a warning about its usage.

NOTE: Shallow data structures should only be used for root level state in a component. Avoid nesting it inside a deep reactive object as it creates a tree with inconsistent reactivity behavior which can be difficult to understand and debug.

Here is an example of using shallowReactive:

<template>
  <div>
    <button @click="onButtonClick">Toggle Div</button>

    <!-- hidden text -->
    <div v-if="dataModel.showDiv.value">Some hidden text</div>

    <!-- counter value -->
    <div>🚀 Counter value: {{ dataModel.counter }} 🚀</div>
  </div>
</template>

<script setup lang="ts">
const dataModel = shallowReactive({
  counter: 0,
  showDiv: {
    value: false
  }
});

const onButtonClick = () => {
  // trigger reactivity
  dataModel.counter++;

  // doesn't trigger reactivity
  dataModel.showDiv.value = !dataModel.showDiv.value;

  console.log(`counter: ${dataModel.counter}`);
};
</script>

Summary

In this blog post, you learned the differences between ref and reactive in Vue.js. In conclusion, there are small minor differences between both of them. However, when it comes to production applications, you can use either of them.

If you liked the content, hit me up with a following or feel free to reach out to me on eduardkrivanek.com

New in Vue.js 3.3: Two-Way Binding With defineModel Macro

Eduard Krivanek — Sat, 13 May 2023 07:39:05 +0000

With the upcoming VueJS version 3.3 the community once again doesn’t disappoint and releases many useful features for developers to be more productive, and ship features faster.

One of the newly welcomed features is defineModel which allows us to implement much smoother 2-way binding. Let’s demonstrate its usage in the following blogpost.

What is 2-Way Binding?

Two-way binding is a feature in VueJS that allows changes in the data to update the view automatically and vice versa. This means that when the user updates the view, the underlying data is also updated, and when the data is updated programmatically, the view is automatically updated to reflect the new data. It is achieved using the v-model directive, which binds a form input element to a piece of data.

<template>
    <input v-model="message" />
</template>

<script setup>
    import { ref } from 'vue'

    const message = ref('Hello from Bitovi!') 
</script>

Two-way binding is useful because it eliminates the need for manual event handling to keep the view and data in sync, which can be tedious and error-prone. Using v-model is the equivalent of

<template>
    <input 
      :value="message" 
      @input="message = $event.target.value" 
    />
</template>

<script setup>
    import { ref } from 'vue'

    const message = ref('Hello from Bitovi!') 
</script>

Custom 2-way binding

An example may be having a custom search component, allowing the user to type some value into the search, which will display multiple options until he chooses one. This behavior is demonstrated in the following code:

// MySearch.vue

<template>
  <div>
    <!-- search text input -->
    <input v-model="searchRef" type="text" placeholder="Search"/>

    <!-- display selected value -->
    <div v-if="props.modelValue">
      Selected: {{ props.modelValue.title }}
    </div>

    <!-- results -->
    <div v-if="searchRef.length > 3">
      <button
        v-for="data in store.getLoadedElements"
        :key="data.id"
        @click="onClick(data)"
      >
        {{ data.title }}
      </button>
    </div>
  </div>
</template>

<script setup lang="ts">
// imports

const store = useStore();

const props = defineProps({
  modelValue: {
    type: Object as PropType<Element | null>,
    required: true,
    default: null
  }
});

const emit = defineEmits<{
  (e: "update:modelValue", value: Element): void;
}>();

// reference to search input
const searchRef = ref<string>("");

// fetch data from API
watchEffect(() => {
   store.fetchElements(searchRef.value);
});

const onClick = (data: Element) => {
  emit("update:modelValue", data);
};
</script>

In the above example, to make the custom 2-way binding work, you use defineProps to create a modelValue input property for the component and you use the defineEmits with update:modelValue to notify the parent about the change.

The usage of the above child component is achieved by the following syntax in another component.

<MySearch v-model="someRef" />
<!-- same as -->
<MySearch
    :modelValue="someRef"
    @update:modelValue="someRef = $event"
/>

NOTE: One useful tip is that you can define multiple properties for the MySearch component into the defineProps and defineEmits. The name modelValue is the name for the default value, however creating multiple properties, you can access them in the parent component by <MySearch v-model:first="first" v-model:second="second"/>.

Using defineModel

With the upcoming VueJS version, 3.3 comes a new defineModel macro, you no longer need to write out all the above-mentioned steps to implement custom 2-way binding.

This new feature is available from version-3.3.0-alpha.9, however, It is still considered an experimental feature. If you wish to use it or have difficulty upgrading to version 3.3m, you can still use its alternative, defineModels, from Vue Macros library, by which this feature was inspired. Overal they work the same way.

After completing the installation guidelines, you can use defineModels with the following syntax:

// MySearch.vue

<template>
  <div>
    <!-- search text input -->
    <input v-model="searchRef" type="text" placeholder="Search"/>

    <!-- display selected value -->
    <div v-if="modelValue">Selected: {{ modelValue.title }}</div>

    <!-- results -->
    <div v-if="searchRef.length > 3">
      <button
        v-for="data in store.getLoadedElements"
        :key="data.title"
        @click="modelValue = data"
      >
        {{ data.title }}
      </button>
    </div>
  </div>
</template>

<script setup lang="ts">
// imports

const store = useStore();
const { modelValue } = defineModels<{ modelValue: Element }>();

// reference to search input
const searchRef = ref<string>("");

// fetch data from API
watchEffect(() => {
  store.fetchElements(searchRef.value);
});
</script>

The macro defineModels replaces the previously used defineProps and defineEmits into one functionality.

Every time, the user passes some value to this component by <MySearch :modelValue="someRef" /> the MySearch component will be updated and also on the other hand, in line 16, when the user selects an element, by modelValue = data, the listener on the parent component will be triggered.

Summary

It’s great to see that the VueJS team recognizes valuable contributions from developers to the VueJS ecosystem and over time, they ship their implementation. With the upcoming version 3.3, VueJS brings us many more useful tools that will speed up our development.

5 Tips To Improve Angular Performance

Eduard Krivanek — Tue, 25 Apr 2023 15:39:53 +0000

As an Angular developer, you understand the importance of building high-performing web apps. Slow loading times, sluggish UI, and poor user experience can all harm your website's reputation and deter users from returning.

Fear not—there is a better way! In this blog post, you’ll learn five actionable tips that you can use immediately to boost your web application's performance. From avoiding memory leaks to running analytics outside of NgZone, let’s cover a variety of strategies to give your customers the best experience.

1. Prevent Memory Leaks

A memory leak in an Angular application occurs when objects in the application's memory are no longer needed but are not released by the garbage collector because they are still being referenced.

In the context of observables, if subscription is not unsubscribed when the component is destroyed or removed from the DOM, the observable and its associated resources will continue to exist in memory, even though they are no longer needed. Over time, this can cause a buildup of unused memory, which can slow down the application, reduce its performance, and even crash the application in extreme cases.

Suppose a user uploads an image. The application stores the image data in memory until it can be saved to a database. To do this, the application uses a Subject to which it subscribes when an image is uploaded. However, suppose the application does not unsubscribe from the Subject when the image has been saved to the database. In that case, the Subject will continue to hold a reference to the image data in memory.

@Component({})
export class ImageUploaderComponent implements OnInit {
  imageSubject = new Subject();

  ngOnInit() {
    // Subscribe to imageSubject to store uploaded images in memory
    this.imageSubject.subscribe(imageData => {
      this.saveImageToDatabase(imageData);
    });
  }

  uploadImage(imageData: any) {
    // Emit imageData to imageSubject
    this.imageSubject.next(imageData);
  }

  saveImageToDatabase(imageData: any) {
    // Save image data to database
    // ...
  }

  ngOnDestroy() {
    // Memory leak occurs if we don't unsubscribe
    // Unsubscribe from imageSubject to prevent memory leaks
    this.imageSubject.unsubscribe();
  }
}

Additionally, as memory leaks are often difficult to diagnose, they can be frustrating for developers to troubleshoot and resolve. Therefore, Angular developers must proactively prevent memory leaks by adequately unsubscribing from observables when they are no longer needed.

The most recommended way of subscribing to an observable is to use the Async Pipe or the rxjs takeUntil operator.

2. Change Detection Strategy

In Angular, components have two change detection strategies: Default and OnPush. The Default change detection strategy checks for changes in all components and their children on every change detection cycle, such as on any user event, typing into the form, clicking on buttons, you name it. This can be resource-intensive, especially in large applications with many components, leading to performance issues.

On the other hand, the OnPush change detection strategy only checks for changes in components if the component's input properties have changed or if an event has been triggered by the component or one of its children. This can significantly reduce the number of change detection cycles and improve the application's performance.

The differences between the two strategies are demonstrated in the following pictures, where on the left, we see the Default strategy, and on the right, the OnPush change detection strategy.

In general, using the OnPush change detection strategy for components is recommended whenever possible, especially in larger applications. This can help to improve the performance and scalability of the application. Even if the Default change detection strategy may be appropriate in smaller applications or in situations where the performance impact is negligible, it is still not recommended, as it may lead to bad development practices in the long run.

3. Memoize Function Calls

In Angular, function calls in the template are prohibited because they can cause performance issues. When a function is called in the template, it is re-executed every time change detection runs, like for every triggered user event, which can be very frequent in complex applications and lead to a lot of unnecessary processing and application slowdown.

Consider the following scenario of having two components allowing to search for entities on the server and displaying them while calculating additional data on the frontend.

@Component({
    selector: 'app-example-function-call',
    template: `
  <!-- search anime -->
  <app-search-anime [formControl]="animeSearchControl"></app-search-anime>

  <!-- table body -->
  <div *ngFor="let data of loadedAnime$ | async">
    <!-- .... -->
    <div>{{ hardMathEquasionFunctionCall(data) }}</div>
  </div>`,
})
export class ExampleFunctionCallComponent {

    animeSearchControl = new FormControl<AnimeData>({});
    loadedAnime$!: Observable<AnimeData[]>;

    ngOnInit(): void {
        this.loadedAnime$ = this.animeSearchControl.valueChanges.pipe(
            scan((acc, curr) => [...acc, curr], [] as AnimeData[])
        );
    }

    // this function is re-executed every time an user event happens
    hardMathEquasionFunctionCall(anime: AnimeData): number {
        console.log('Function call')
        return hardMathEquasion(anime.score);
    }
}

Here is a example of the above mentioned problem.

Unlike functions, which are re-executed every time change detection runs, Angular pipes are only executed when their input value changes. This means that pipes can help reduce unnecessary processing and improve the application's overall performance. Additionally, pipes are reusable and can be shared across different components, which can help to reduce code duplication and improve code maintainability.

One quick trick to solve all your function calls in a template without rewriting them as Pipes is using Memoization. Without going deep into the topic, memoization stores the previously calculated result of the subproblem. It uses the stored result for the same subproblem, removing the extra effort to calculate again for the same problem.

By understanding the concept of memorization, you can create a custom function decorator, as it is in the following code snippet, and apply it to all function call in the template so that the will behave exactly as Angular Pipes.

export function customMemoize() {
 // Value cache stored in the closure
 const cacheLookup: { [key: string]: any } = {};

 return (target: any, key: any, descriptor: any) => {
   const originalMethod = descriptor.value;

   descriptor.value = function () {
     // arguments can be object -> stringify it
     const keyString = JSON.stringify(arguments);

     // cached data
     if (keyString in cacheLookup) {
       return cacheLookup[keyString];
     }

     // call the function with arguments
     const calculation = originalMethod.apply(this, arguments);
     // save data to cache
     cacheLookup[keyString] = calculation;
     // return calculated data
     return calculation;
   };

   return descriptor;
 };
}

For more information on how memoization can be used in Angular, check out one of our open-source examples.

4. Use RxJS Pipes for Frequent Data Updates

It’s not a secret that we must react to user input in our application and modify, load, or send some data to the backend. The problem starts to arise when we frequently update a large data set. Let’s look at some examples and how RxJs pipes can help us.

DistinctUntilChanged & DebounceTime

The distinctUntilChanged operator filters out consecutive duplicate values emitted by an observable. The debounceTime operator filters out values emitted by an observable that occur too frequently by ignoring values emitted too close together in time.

@Component({
  selector: 'app-search-box',
  standalone: true,
  imports: [CommonModule, ReactiveFormsModule],
  template: `
    <input type="text" [formControl]="searchInput">
    <ul>
      <li *ngFor="let result of searchResults$ | async">
        {{ result }}
      </li>
    </ul>
  `
})
export class SearchBoxComponent implements OnInit {
  searchResults$!: Observable<string[]>;
  searchInput = new FormControl<string>('');

  constructor(private searchService: SearchService) {}

  ngOnInit() {
    // Create an observable from the search input element
    this.searchResults$ = this.searchInput.valueChanges.pipe(
      // Apply the operators to the search input  
      debounceTime(300), 
      distinctUntilChanged(),
      // Call the search service to perform a search using the search term
      switchMap(value => this.searchService.search(value))
    );
  }
}

BufferTime

When having an observable that emits a large collection of values multiple times per second and causes application slowdown because of frequent UI rendering, we can opt for the bufferTime operator. A real-life use case may be connected to a stock market web socket API that frequently emits data. However, we catch incoming data for 5000 milliseconds and then update the UI.

@Component({
  selector: 'app-stock-updates',
  template: `
    <h2>Stock Updates</h2>
    <div *ngFor="let update of updates">{{ update }}</div>
  `
})
export class StockUpdatesComponent implements OnInit {
  updates$!: Observable<string[]>;

  ngOnInit() {
    // Connect to the WebSocket endpoint that emits stock market updates
    const socket = webSocket('wss://example.com/updates');

    // Apply the bufferTime operator to the WebSocket observable
    this.updates$ = socket
      .pipe(
        bufferTime(5000),
        // Concatenate the buffered updates and add them to the updates array
        scan((acc, curr) => [...acc, ...curr], [])
      );
  }
}

Other RxJs operators that can be useful to worth with frequent data emotions are:

auditTime - ignores the source observable for a given amount of time
throttleTime - ignores subsequent source values for provided milliseconds

RunOursideAngular

The runOutsideAngular method is helpful when short-lived heavy computations need to be executed within an Angular application, such as when performing data processing, rendering large datasets, or working with complex algorithms.

By executing these computations outside the Angular zone, the application can remain responsive and provide a smooth user experience.

A real-world use case for ngZone.runOutsideAngular might be a large file upload or download or a complex data processing task that requires significant processing time. By running these tasks outside Angular's change detection, we can ensure that the application remains responsive and doesn't freeze up.

@Component({
  selector: 'app-my-component',
  template: `
    <input type="file" (change)="onFileChange($event)">
    <button (click)="uploadImage()">Upload Image</button>
    <div *ngIf="uploadResult">Result: {{ uploadResult }}</div>
  `
})
export class MyComponent {
  uploadResult: string;

  constructor(
    private ngZone: NgZone, 
    private imageUploadService: ImageUploadService,
    private cd: ChangeDetectorRef
  ) {}

  onFileChange(event) {
    // Get the selected file from the input element
    const file = event.target.files[0];

    // Pass the file to the image upload service to prepare for upload
    this.imageUploadService.prepareImageForUpload(file);
  }

  uploadImage() {
    // Call the image upload service to upload the prepared image
    this.ngZone.runOutsideAngular(() => {
      // uploading images <-- blocking operation, may freez up the UI
      this.imageUploadService.uploadImage().subscribe(result => {
        // Update the component state with the upload result
        this.ngZone.run(() => {
          this.uploadResult = result;
          // Manually trigger change detection
          this.cd.detectChanges();
        });
      });
    });
  }
}

NOTE: It is essential to note that any changes made during the execution of the heavy computation will not trigger change detection, and developers will need to trigger change detection if necessary manually.

5. Web Workers for Heavy Computation

For heavy computation that may run through the whole lifecycle of the application, we can opt for web workers. Web workers are designed to execute heavy computations in separate threads, which can significantly improve the performance and responsiveness of the application and user experience.

However, using web workers requires more setup and coordination than using runOutsideAngular, as developers must manage multiple threads and handle communication between them.

// my-worker.ts

// Define a function that will be executed in the web worker
function doHeavyComputation(input: number): number {
  // Perform some heavy computation here
  return input * input;
}

// Set up a message listener to receive messages from the main thread
addEventListener('message', event => {
  // When a message is received, extract the data from the event
  const data = event.data;

  // Call the function and return the result to the main thread
  const result = doHeavyComputation(data.input);
  postMessage(result);
});

// my-component.component.ts
@Component({
  selector: 'app-my-component',
  template: `Result: {{ result }}`
})
export class MyComponent {
  result: number;

  constructor() {
    // Create a new instance of the Worker class
    const worker = new Worker('./my-worker.ts', { type: 'module' });

    // Set up a message listener to receive messages from the web worker
    worker.addEventListener('message', event => {
      // When a message is received, extract the data 
      // from the event and update the component state
      const data = event.data;
      this.result = data;
    });

    // Send a message to the web worker
    worker.postMessage({ input: 5 });
  }
}

If you are writing a web worker that uses CommonJS modules instead of ES modules, you can specify this by setting { type: 'classic' } instead of { type: 'module' }. However, ES modules are generally recommended unless you have a specific reason to use CommonJS modules.

NOTE: Note that web workers have some restrictions on what APIs are available to them (for example, they don't have access to the DOM), so you may need to modify your code accordingly. Additionally, you may want to handle errors and other edge cases to ensure that your web worker is robust and reliable.

Summary

In this blog post, you learned how to identify common issues in your Angular application and saw potential solutions. Angular is a large ecosystem. It provides lots of features, hovewer it is very easy to make a mistake a build up the tech debt that may eventually slow down your release and competitive advantage.

GraphQL: Everything You Need to Know

Eduard Krivanek — Mon, 13 Mar 2023 06:16:29 +0000

Are you thinking about designing a backend API? You probably already know about REST architecture. You might even know that the REST architecture doesn’t handle complex applications very well.

If so, you might be struggling to answer the following questions:

How much data should I return with each endpoint?
Will I return the same data on mobile as to desktop devices?
Do I want to have real-time updates if something changes?

Enter GraphQL. In this post, learn everything you need to know about GraphQL. Discover GraphQL’s benefits and limitations and decide whether it’s the right tool for your backend API project. 🙌

The Problem With REST

REST stands for REpresentational State Transfer, where endpoints are structured around objects, like users, groups, comments, etc.

REST is a specification that has been around for a long time, and today it’s still the most standard, widely-accepted way to write an API. Despite REST maturity, the main issue spins around one question.

What data should I return by my endpoints?

One business case you might encounter is a need to display a list of users and a list of each user’s recently added comments.

In other words, fetch a list of entities, and for each entity, fetch another related list of entities. There are two ways of solving this problem using REST.

Modeling Endpoints Around Resources

Having one endpoint per resource is a very maintainable approach for backend developers. It is relatively scalable but introduces unnecessary complexity on the client side, meaning the client needs to make multiple API calls to structure a data model. In this example, you could have the following endpoints:

getUsers() - return a list of users
getCommentsByUserId(userId: string) - returns a list of comments for a specific userId

Using a resource-based approach, a relatively common N + 1 problem can arise, where the client side is required to call the server N + 1 times to fetch one collection of resource + N child resources.

const getUserWithComments = async (): Promise<User[]> => {
  // fetch a list of users
  let users = await getUsers();

  // new HTTP request for each user
  for(let i = 0; i < users.length; i++){
    const user = users[i];
    // loading comments from the server
    user.comments = await getCommentsByUserId(user.id);
  }

  return users;
}

Resource-based endpoints may lead to slow rendering because it takes time to load all the data, and you can overload the server with too many API calls.

Returning the Exact Needed Shape of the Data

Endpoints can also be structured to return the exact shape of data the client wants to work with. You could have an endpoint, such as getUsersWithComments(), that would return users with their comments in one HTTP round trip. This approach works until it doesn’t.

This approach establishes a close relationship between the client and the server. Whenever the management requests to change the UI, where additional data should be displayed or removed, the frontend developers have to contact backend developers to adjust the returning data from a specific endpoint.

This approach is challenging to maintain, especially when considering having multiple endpoints that return some mixed data type for the consumer or having separate endpoints for mobile devices. In the worst case, you could end up with too many endpoints returning a combination of objects, not knowing which endpoints are even used.

What Are My Options?

Delegating the responsibility of defining the returning data shape to the server side, sooner or later, the frontend developers will encounter one of the two problems mentioned above. To put gas into the fire, the following problems in the REST architecture weren’t even mentioned :

Sending fewer data to mobile users
Having real-time communication
Having API documentation (and following it)

The groundwork has been laid. Let’s talk about GraphQL!

What is GraphQL?

GraphQL is a query language that delegates the responsibility of defining the shape of data being returned from the server to the client by the client. The server provides a playground and documentation for its API, where the client can see all available executable methods. Queries to get data, mutations to modify data, and subscriptions for real-time communication (we will get back to it later).

When calling a server-side method, a JSON data structure is included in the message payload that describes the returning object property fields for which the server has to return value.

Because GraphQL solves under-fetching and over-fetching, the client only gets back data for fields that are included in the payload of the HTTP request. No more, no less.

GraphQL Models Relationships ❤️

GraphQL models a relationship between objects. It enables retrieving all required data by one HTTP round trip. Relationship modeling means if an entity has a 1-to-N relationship with another one, we can request this relational information in one query.

GraphQL Resolvers

To resolve object relationships, you guessed it, resolvers are used. A resolver is a function, the main building block why we even consider using GrapQL in the first place, that's responsible for populating the data for a single field for the object type.

Resolvers can be understood as an enhancement to add additional fields for an entity class that doesn’t exist in the database but is calculated on the server side.

Their usefulness lies in their execution. A function registered as a Resolver is not executed until it is called. The code snippet below represents a piece of the above-displayed database UML diagram using the NestJS framework.

@ObjectType()
export class Movie {
    @Field(() => Int)
    id: number;

    @Field(() => String)
    createdAt: Date;

    @Field(() => String)
    updatedAt: Date;

    @Field(() => String, {
        nullable: false,
        description: "User's title to the movie",
        defaultValue: '',
    })
    title: string;

    @Field(() => String, {
        nullable: true,
        description: "User's description to the movie",
    })
    description: string;
}

@Resolver(() => Movie)
export class MovieResolver {
    constructor(private movieCommentService: MovieCommentService) {}

    @ResolveField('movieComment', () => [MovieComment])
    async getMovieComment(@Parent() movie: Movie) {
        const { id } = movie;
        return this.movieCommentService.getAllMovieCommetsByMovieId(id);
    }
}

Loading comments for a Movie object require making an expensive database select operation. Furthermore, you don't always need to load comments for a Movie, only when the user requires them.

Decorating a method with the @ResolveField decorator (NestJS syntax) executes the inside logic only when the client requests data for that field name, in this case, for movieComment.

NOTE: The API creator should provide descriptions for resolver fields, especially the ones that execute an expensive server-side operation, like database calls, so that the consumers won’t query unnecessary fields just because they can.

Benefits of GraphQL

In the REST architecture, the question that is always present is, “What data does this endpoint return?”. Testing endpoints by Postman, or in better cases, having swagger for backend documentation, still doesn’t guarantee that the returned Object’s properties will not be undefined and are the type that the documentation describes. For a better developer experience, GraphQL provides the following advantages:

GraphQL playground
Predefined schema
Generating TypeScript types
Real-time communication
Device adaptations
Batch query execution

The biggest major benefit worth highlighting is GraphQL decouples the dependency between the server and the consumer.

The consumer only receives back values for fields included in the GraphQL operation. The server can create a very complex schema and offer a return type that has 60+ properties to query, but the consumer will only receive back values for the fields which were included in the GraphQL operation.

GraphQL Playground

GraphQL Playground is an IDE created and maintained by Prisma. It’s built on top of GraphQL and serves as API documentation for every available query, mutation, and subscription. The consumer can inspect the return type of each operation and test server-side functionalities. For an open API, check out SpaceX GraphQL API.

Predefined Schema

When inspecting GraphQL data types throughout the playground, you might notice some fields include an exclamation mark. (!)

It serves as insurance that the server has to provide the correct data type and can not return a null value for them.

Taking a look at the attached image by querying fields like User.id, User.createdAt, the server will never return a null value for these fields. If it had happened, we would receive the following error from the query operation.

{
  "errors": [
    {
      "message": "Cannot return null for non-nullable field User.id.",
      "statusCode": 500
    }
  ],
  "data": null
}

Using array types, like for the movieCommentsUserLeft: [MovieComment!]!, the outer exclamation mark, []! means that the API will always return back a list of values, even an empty list, and the returned value will never be null.

On the other hand, the inner exclamation mark [MovieComment!] describes that the elements inside the list will always be objects. It is impossible for a null value to be part of the list. If it had happened, the whole query would fail, and no data would have been returned.

Generating TypeScript Types

The major benefit of the exposed GraphQL schema is that developers define GraphQL operations and use libraries, such as graphql-code-generator, that allow generating TypeScript types from the server-side schema.

Using a generator prevents manual handwriting of TypeScript Interfaces for all API responses, and if the server-side schema change, the whole TypeScript schema can be regenerated by one command.

An example can be seen in the image below, where at the left, we define a query operation launchesPast expecting a LaunchLast fragment to be returned, and on the right, we see the generated TypeScript types by graphql-code-generator.

Using GrapQL fragments, we can share pieces of logic in multiple queries and mutations that will return the same data type. Generated fragments can then be used for type-checking on the client side.

Real-Time Communication

In the traditional REST world, to achieve real-time communication, you need to use WebSockets. You know they suck. What endpoint should I listen to? What data will I receive back? Is the connection alive?

Instead of Polling data from the server, subscriptions are used to listen to asynchronous emitted events. Subscriptions maintain an active connection to the server, listening and waiting for the server to push updates. The main benefit of using subscriptions is the type safety, such that, as in queries, the consumer can select which fields to receive values back.

Device Adaptations

This is more or less just a piece of advice. When working on a small screen device, like a mobile phone, you usually don’t show as much data compared to a desktop resolution. Therefore it is not required to fetch as much data as a desktop device.

The solution you may go with is to create two separate queries for the same operation, one for a desktop device to fetch a large quantity of data and one for a mobile device to load less data and use conditional statements to execute them based on the client’s device.

Batch Query Execution

Having a GraphQL API, you can execute multiple queries at once by sending one HTTP request. Taking a look at SpaceX API, you can select multiple independent queries and fetch data in one round trip.

{
  launchesPast(limit: 3) {
    mission_name
    launch_date_local
    launch_site {
        site_name
    }
  }
  historiesResult(limit: 3) {
    data {
      details
  }
    }
  missions(limit: 3) {
    name
    twitter
  }
}

Drawbacks of GraphQL

There has never been a point in time when technology was so great that it would not have any downside. Let’s take a look at some concerns you have to be aware of when choosing GraphQL architecture.

N + 1 Problem

Once you start learning about GraphQL, the first problem you hear about is the “N+1 problem”. Let’s describe an example scenario by the SpaceX API of how it may happen.

You want to fetch past launches from one table, and for each of them, you want to get the site_name from another table. Using REST, you may have the following endpoint.

route: '/launches/past',
method: 'GET',
queryParam: 'limit'

that could result in the following Database calls

SELECT * FROM launches limit = {limit};

-- pass the fetched launches.ids the the second query
SELECT * FROM launch_sites WHERE launch_id in (1, 2, 3);

With two queries, you will have your desired result. Beware that this works because you have already loaded a list of launches, and you pass their launch.id to the second query.

In GraphQL, to load launch_sites from a different table, you would probably use resolvers attached to the Launch entity, like in the following snippet.

schema = `{
  type Query {
launchesPast(limit: Int!): [Launch!]!
  } 

  # from table launches
  type Launch {
    id: Int!
    mission_name: String 
    launch_site: [Launch_sites!]!
  } 

  # from table launch_sites
  type Launch_sites {
    id: Int! 
    site_name: String
  }
}`

resolvers = {
  Query: {
    launchesPast: async (_: null, args: { limit: number })  => {
      return ORM.getAllLaunches(limit)
    }
  }
  Launch: {
   launch_site:  async (launchObj, args) => {
     return ORM.getLaunchSitesById(launchObj.id)
    }
  },
}

However, suppose you execute the below query. In that case, you will create N database calls for N Launches to get their site_name because every resolver function only knows about its parent, and GraphQL executes a separate resolver function for every field.

query LaunchesPastQuery($limit: Int!) {
  launchesPast(limit: $limit) {  # fetches Launch entities (1 query)
      id
      mission_name
      launch_site {        # fetches Sites for each Launch (N queries for N Launches)
            site_name   
        }
    }
}                           # Therefore = N + 1 round trips

will translate to the following pseudo-SQL:

SELECT * FROM launches limit = {limit};

-- pass the fetched launches.ids the the second query
SELECT * FROM launch_sites WHERE launch_id in (1);
SELECT * FROM launch_sites WHERE launch_id in (2);
SELECT * FROM launch_sites WHERE launch_id in (3);

The N+1 problem is further exacerbated in GraphQL because neither clients nor servers can predict how expensive a request is until it’s executed. In REST, costs are predictable because there’s one trip per endpoint requested. In GraphQL, there’s only one endpoint, and it’s not indicative of the potential size of incoming requests.

Facebook previously introduced a solution to the N+1 issue by creating DataLoader, a library that batches requests specifically for JavaScript. Also, Shopify took DataLoader as inspiration and built the GraphQL Batch Ruby library.

What DataLoader does is wait for all resolvers to load in their individual keys and then hit the database once with the keys, and return a promise that resolves an array of the values. It batches queries instead of executing them one at a time.

NOTE: N+1 is the biggest problem you may encounter by having a GraphQL server. Before implementing the server-side logic, you need to have a rough understanding of how entity relationships will be resolved because once you deal with a large database and millions of data, having a bad implementation will hugely increase your tech debt and massively impact the performance of the application.

Schema Dependency

Having a predefined schema that is being exchanged between the server and the consumer is advantageous, even so, when the exclamation mark (!) is used on type fields so that the consumer knows which fields will never have a null value.

Exclamation marks or so-called not-null values can, however, ruin the whole query. Let’s have an example that, for some Launch entity, it saved ID column in the database, or any column that must have a present value, will suddenly be null (code snippet on line 17.).

schema = `{
  type Query {
    launchesPast: [Launch!]!
  } 

  # from table launches
  type Launch {
    id: Int!
    mission_name: String 
  } 
}`

resolvers = {
  Query: {
    launchesPast: async ()  => {
      const allLaunches = await ORM.getAllLaunches()
      allLaunches[3].id = null; // <-- will cause the query to fail

      return allLaunches;
    }
  }
}

If the consumer requests a list of Launch entities by the launchesPast query, the whole query will fail and you will receive the following error message:

Cannot return null for non-nullable field Launch.id

In conclusion, if you query a list of objects, and only one of them does not match the returning schema (it has a null value for a field that has the exclamation mark (!)), then your whole query will fail, and you will not receive back any data.

Nested Recursion

As a query language for APIs, GraphQL gives clients the power to execute queries to get exactly what they need. But what if a client sends a query asking for many fields and resources? With GraphQL, users can’t simply run any query they want.

authors {
  name
  books {
    title
    authors {
      name
      books {
        title
        authors {
          name
        }
      }
    }
  }
}

I think you can see the problem here. A GraphQL API must be carefully designed, and to prevent such a nested data loading, you can use libraries like graphql-cost-analysis to set a maximumCost for your whole schema and, for each operation, define a complexity value. So when the consumer uses your API, the sum of all complexity from each operation can not exceed the total maximumCost. Otherwise, the consumer’s request will be blocked.

HTTP Status Codes

Whenever Apollo Server encounters errors while processing a GraphQL operation, its response to the client includes an errors array containing each error that occurred. Despite any occurred error, the status code of each request will have a code 200, but the returned payload will have a list of occurred errors with the statusCode of 500.

Error code 500 is not necessarily the best way to notify your consumers that something went wrong. You want to use status codes for unauthenticated/unauthorized requests, redirects, etc. For information on configuring error handling on the server side, check out Apollo server Error handling.

Scaling with Subscriptions

As previously mentioned in the Real-time Communication section, subscriptions are a helpful feature in GraphQL for asynchronous emitted events from the server side. The problem is with scaling the server horizontally into multiple instances to manage request overload.

If you use subscriptions to notify a group of users and you have multiple instances of your backend application, you never want your clients to be directly connected to a specific instance. What may happen is that one GraphQL instance pushes data via subscription, but clients who are connected to a different instance will not be notified about that change. Consider using https://redis.io/ as your load-balancer. Read more about GraphQL subscriptions with Redis Pub Sub.

Do I need a GraphQL server?

The battle between GraphQL vs REST has been ongoing for quite some time. Primarily because these two API styles have different approaches when dealing with data transfer over internet protocols.

For most applications, there won’t be any increase in performance by simply migrating to GraphQL. However, when an app starts to scale, that is when the value of migrating to GraphQL comes to play. It presents a powerful and elegant solution for teams that have been restricted to the traditional REST API. Also, a common case for a GraphQL can be to hide multiple complex systems behind it, legacy infrastructures, or third-party APIs that are enormous in size and difficult to maintain and handle.

When considering the adaption of GraphQL, it may be useful to read the journeys of other companies implementing it. You may be interested in PayPal's Adoption of GraphQL, Netflix's Rapid Development with GraphQL Microservices, or Shopify's New Admin API in GraphQL.

Summary

Choosing the right tech stack or architecture design for an application is never an easy decision. You have to consider the problems each decision solves and the complexity it brings.

Through this article, you learned what GraphQL is, why developers, especially frontend developers, love it so much, how it can improve your development journey, and also what concerns to be aware of.

Angular & Apollo Client: Apollo Cache Configuration

Eduard Krivanek — Mon, 02 Jan 2023 14:30:17 +0000

Apollo-client might be a go-to library for connecting a frontend application to a GraphQL server; however, it was initially built as a comprehensive state management library. The Apollo client’s cache allows persisting local data both with reactive variables and client cache queries and can extend server-side objects with local properties.

By the end of this post, you will have a solid understanding of how Apollo client cache works, but if you are unfamiliar with Apollo, check out Angular & Apollo Client: Getting Started with GraphQL in Angular or go through the source code on GitHub.

Extending GraphQL Schema with Local Data

To store client-side information in objects received from a GraphQL server, you can use a local-only field.

Let’s have an example for extending a server-side Movie object, which has fields like Id, title, etc., with an additional isSelected property, allowing selecting any movie to perform some logical operation on the chosen entities.

# Original Movie type provided by the server

type Movie {
    id: Int!
    createdAt: String!
    updatedAt: String!
    title: String!
    description: String
    movieComment: [MovieComment!]!
}

Generating Types

Create a {{name}}.graphql file where you tell graphql-code-generator how you want to extend the server-side schema. Include your file location into the codegen.yml file under the schema section which instructs graphql-code-generator to inspect locally-defined GraphQL types and merge them with the server-side schema.

In this example, you create a local.schema.graphql file in which you extend a Movie type with an isSelected: MovieSelectType! field. The isSelected field will be a local attribute for the Movie object that doesn’t initially exist when you first fetch a list of Movie objects from the server side.

Despite that, you mark the isSelected field as required using the exclamation mark (!), and you will configure the Apollo client to always return some value for it. You include the local.schema.graphql file location under the schema property in codegen.yml.

# src/graphql/graphql-local-schema/local.schema.graphql

enum MovieSelectType {
    SELECTED
    UNSELECTED
}

extend type Movie {
    isSelected: MovieSelectType!
}

# codegen.yml

generates:
  # where to generate file
  ./src/app/graphql/graphql-custom-backend.service.ts: 
    schema:
      # where the server lives
      - http://localhost:3001/graphql
      # where is our local schema
      - src/app/graphql/graphql-local-schema/*.graphql 
    ...

Running the script npm run generate-types ("generate-types": "graphql-codegen --config codegen.yml") will generate an additional isSelected field on the Movie type.

Simply querying the isSelected field would throw an error Cannot query field "isSelected" on type "Movie", because the Apollo client expects isSelected to be provided by the server.

You must add the @client decorator, which tells Apollo-client to skip server-side validation.

fragment MovieInfo on Movie {
    id
    ...
    isSelected @client
}

Reading Local Only Fields

Though you no longer get an error after registering isSelected as a local-only field, inspecting the server-side Movie objects by Apollo Client Devtools, you see that they do not contain the isSelected property.

If you had called Movie.isSelected you would get undefined. To customize how a particular field is read, you use the field policy field in Apollo’s InMemoryCache.

The right place to define a return value for local-only fields is to implement a read(...) function, that the Apollo client always executes by default when you call a specific GraphQL object property. The read(...) function in its argument provides the actual object’s property value and it must return the same data type as the property.

In this example, the selectType for read(selectType?: MovieSelectType) at its initial state is undefined, since the server doesn’t resolve any data for that field, so you return a default MovieSelectType.Unselected value. However, if you later set the selectType property for a Movie object, you return the current value.

const cache = new InMemoryCache({
    typePolicies: {
        Movie: {
            fields: {
                title: {
                    read(title: string) {
                        return title.toUpperCase();
                    },
                },
                isSelected: {
                    read(selectType?: MovieSelectType) {
                        return selectType ?? MovieSelectType.Unselected;
                    },
                },
            },
        },
    },
});

Client-Side Schema

Another common use case for cache manipulation is storing local, client-side data in the Apollo client cache as a single source of truth. Use cases might include:

Storing system configuration
Storing edited form state
Storing filtered table state

A practical use for Angular developers is to persist local data in Apollo’s cache using one of two approaches:

Directly write and read from the cache
Use reactive variables

Let’s take a look at both of these methods

Extending Type Query

You first need to provide a client-side schema, meaning you register queries, which will be used only on the client side of the application. Registering additional queries can be achieved by extending the global Query type in GraphQL.

You create two queries in local.schema.graphql since you have already configured graphql-code-generator to generate TypesScript types from this file. Query getAllLocalMovies will return Movie objects from the Apollo cache, while getAllLocalMoviesReactiveVars will use reactive variables.

# src/graphql/graphql-local-schema/local.schema.graphql

extend type Query {
        # for Apollo cache query
    getAllLocalMovies: [Movie!]! 
        # for reactive variables
    getAllLocalMoviesReactiveVars: [Movie!]! 
}

To use these queries, you have to attach the @client decorator, telling Apollo-client to resolve them on the client side and prevent executing them against the server.

# src/graphql/graphql-custom-backend/movie-local.graphql

query GetAllLocalMovies {
    getAllLocalMovies @client {
        ...MovieInfo
    }
}

query GetAllLocalMoviesReactiveVars {
    getAllLocalMoviesReactiveVars @client {
        ...MovieInfo
    }
}

Finally, regenerate the TypeScript schema by npm run generate-types, which will create executable GetAllLocalMoviesReactiveVarsGQL and GetAllLocalMoviesGQL API calls.

Client Queries

To update local application data using client queries, you must implement the following steps:

Inject private apollo: Apollo to the service or component for Apollo client cache reference
Create a data type you want to save into the cache
Update query data by the writeQuery methods. Example: calling this.apollo.client.cache.writeQuery({...}), which can be seen in MovieLocalService in the code snippet below, line 22, with the following arguments:

a.) query - TypeScript constant that wraps the whole client-side query we want to update. By using graphql-code-generator, you define GraphQL queries in {{name}}.graphql file and generate constants by the registered npm script npm run generate-types. For example:

export const GetAllLocalMoviesDocument = gql`
    query GetAllLocalMovies {
        getAllLocalMovies @client {
            ...MovieInfo
        }
    }
    ${MovieInfoFragmentDoc}
`;

b.) data - An object where you set the properties to what __typename you want to change. In most cases, you are updating a Query type, and the second attribute is the name of the query, defined in {{name}}.graphql, that returns data you want to overwrite. For example:

data: {
    __typename: 'Query',
    getAllLocalMovies: movie,
},

c.) id - Object’s identification key when you update only one specific object, optional parameter

4.) Implementing merge and read functions in the InMemoryCache.Query, if you intend to add additional logic for updating or reading client queries

Let’s take a look at the following code snippet on how you would create and store local Movie entities in the local getAllLocalMovies query.

export class MovieLocalService {
    constructor(
        ..
        private apollo: Apollo
    ) {}
    ....

    onMovieAddToApolloCache({title, description}: MovieInputCreate): void {
      const rightNow = new Date();
      // create object
        const movie: MovieInfoFragment = {
            __typename: 'Movie',
            id: rightNow.getTime(), // fake ID
            title,
            description,
            createdAt: rightNow.toISOString(),
            updatedAt: rightNow.toISOString(),
            isSelected: MovieSelectType.Unselected, // local only field
        };

      // update cache
      this.apollo.client.cache.writeQuery({
            query: GetAllLocalMoviesDocument,
            data: {
                __typename: 'Query',
                getAllLocalMovies: movie,
            },
        });
    }
}

GetAllLocalMoviesDocument is a generated constant variable by graphql-code-generator from GetAllLocalMovies query defined in movie-local.graphql file. In the method onMovieAddToApolloCache(...) you create a new Movie object and save it into getAllLocalMovies array.

However, by saving a new Movie into getAllLocalMovies array, it is possible to overwrite its already existing list of values with just a single object. To avoid losing the stored list of Movie values, implement merge and read functions in InMemoryCache, Query type.

const cache = new InMemoryCache({
    typePolicies: {
        Movie: {
            ...
        },
        Query: {
            fields: {
                getAllLocalMovies: {
                    read(data?: MovieInfoFragment[]) {
                        return data ?? [];
                    },
                    merge(
                        existing: MovieInfoFragment[] = [], 
                        incoming: MovieInfoFragment | MovieInfoFragment[]
                    ) {
                        // if array is passed, rewrite already saved movies
                        if (Array.isArray(incoming)) {
                            return [...incoming];
                        }
                        return [incoming, ...existing];
                    },
                },
            },
        },
    },
});

As mentioned previously read(...) function is executed when getAllLocalMovies query is called. The initial read(...) execution would return undefined because no data had yet been saved into the cache, so instead, we return an empty array.

Function merge(...) is executed when you write something into getAllLocalMovies array in Apollo cache, like in the previous code snippet by getAllLocalMovies: movie, where you instruct Apollo cache to store the newly created movie object alongside the already stored ones.

Working with client queries can be tedious. You have to update Apollo cache by writeQuery, using the right query document and in its data change the correct field, and also implement merge(...) and read(...) functions. On the other hand, its major benefit is the ability to inspect the local state by Apollo Client Devtools and the option of adopting libraries such as Apollo-cache-persist to persist the cache state in client-side storage on application reload.

Reactive variables

When you don’t care about storing the application’s local state in the Apollo cache, you can adopt the reactive variables approach. Create a reactive variable with the makeVar<T>() function.

export const localMoviesReactiveVars = makeVar<MovieInfoFragment[]>([]);

You have already generated a getAllLocalMoviesReactiveVars query from movie-local.graphql, so you also have to tell Apollo’s InMemoryCache how to perform the read() operation on this query.

const cache = new InMemoryCache({
        typePolicies: {
            Movie: {
                ...
            },
            Query: {
                queryType: true,
                fields: {
                    getAllLocalMoviesReactiveVars: {
                        read() {
                            return localMoviesReactiveVars();
                        },
                    },
                    getAllLocalMovies: {
                        ...
                    },
                },
            },
        },
    });

Use getAllLocalMoviesReactiveVars generated query in MovieLocalService, to return data from localMoviesReactiveVars() reactive variable or push data into it.

export class MovieLocalService {
    constructor(
        private getAllLocalMoviesReactiveVarsGQL: GetAllLocalMoviesReactiveVarsGQL,
        ...
    ) {}

    // get current state of reactive variable
    get allLocalMoviesReactiveVars(): MovieInfoFragment[] {
        return localMoviesReactiveVars();
    }

    // subscribe on state change
    getAllLocalMoviesReactiveVars(): Observable<MovieInfoFragment[]> {
        return this.getAllLocalMoviesReactiveVarsGQL.watch()
        .valueChanges.pipe(
            map((res) => res.data.getAllLocalMoviesReactiveVars)
        );
    }

    // add new Movie to reactive variables
    onMovieAddToReactiveVariables({title, description}: MovieInputCreate): void {
        const rightNow = new Date();
        const movie: MovieInfoFragment = {
            __typename: 'Movie',
            id: rightNow.getTime(), // fake ID
            title,
            description,
            createdAt: rightNow.toISOString(),
            updatedAt: rightNow.toISOString(),
            isSelected: MovieSelectType.Unselected,
        };

        // save movie to reactive variables
        localMoviesReactiveVars([movie, ...localMoviesReactiveVars()]);
    }

    ....
}

As an Angular developer, you may be asking, what is the difference between reactive variables provided by Apollo client compared to RxJs BehaviorSubject? Honestly, not much. Using reactive variables, you lose the option to inspect your local state in the Apollo cache with Apollo client devtools, compared to client-side queries. In the end, reactive variables and BehaviorSubjects behave the same way, and you lose debugging opportunities.

Summary

Apollo client can be a valuable tool to cache client-side data without bringing additional external libraries into the picture. In this example, you learned how to extend the server-side schema with a local-only field and two ways to store local data with the help of the Apollo client library.

Angular v15 Directive Composition API

Eduard Krivanek — Thu, 17 Nov 2022 07:44:45 +0000

One of the advantages of using the Angular ecosystem is that it never forgets about you. If Angular can’t solve your request right away because the current technology doesn’t allow it, they often return to it. An example of this is issue #8785, which was open for 6 years but was finally solved in 2022.

The Problem with Inheritance

Some developers like to work smarter, not harder. They like to define some logic once, create a function only in one place and reuse it everywhere, following the principle of don’t repeat yourself.

When having multiple Angular elements (Components, Directives, Pipes) that share the same logic, it is common to abstract that logic into a parent class and extend the parent using Inheritance.

@Directive()
export abstract class ParentCalculation {
    calculation1(value: number = 1): number {
        return 1 * value;
    }

    // restricted only for Components
    calculation2(value: number = 2): number {
        return 2 * value;
    }
}
// ---------------------------------------
@Component({
    selector: 'app-component1',
    template: `
        <button (click)="calculation1()">calculation1</button>
        <button (click)="calculation2()">calculation2</button>
    `,
})
export class Component1 extends ParentCalculation {
    constructor() {
        super();
    }
}
// ---------------------------------------
@Pipe({
    name: 'app-pipe1',
})
export class Pipe1 extends ParentCalculation implements PipeTransform {
    transform(value: number) {
        return this.calculation1(value);
    }
}

Inheritance works… Until it doesn’t. Let’s demonstrate the following problem: What if the method calculation2 inside the ParentCalculation class would be restricted only to be executed for Components and not for Pipes?

What if many more components would extend the ParentCalculation class, and we realize we will need to add an additional calculation3 method because we, once again, have a repeated logic across multiple places that would be great to abstract?

Abstracting a common logic into the ParentCalculation could be a good idea. Still, we would expose unused methods (calculation2 and calculation3) to every child class (Component, Pipe, Directive) even if they don’t need to or can’t use them.

Enter JavaScript Composition

Composition is a design pattern to implement a has-a relationship. To achieve this, you can use an instance variable that refers to other objects. The main benefits of compositions are:

Composition allows changing the behavior at runtime as long as the composed object implements the correct behavior
It Decouples the dependency on the parent class, so if the parent behavior changes, it will not break the child component execution.
It makes testing less complex because we have to mock Objects, not actual dependency classes

An example of Composition is the following code snippet

interface Human {
    name!: string;
}

class Person implements Human {
    name!: string;

    constructor(name: string) {
        this.name = name;
    }
}

class Employee {
    salary!: number;
    human!: Human;

    constructor(h: Human, salary: number) {
        this.human = h;
        this.salary = salary;
    }
}

const person = new Person('Romero');
const employee = new Employee(person, 80000);

Composition API in Angular

Composition sounds interesting in theory, but you might wonder how we can use it in Angular. Let me introduce you to a new composition API directive called hostDirective, available in Angular v15.

Composition allows composing functionalities from multiple standalone Directives into a more complex Directive or Component. Let me demonstrate it in the following snippet.

@Directive({
    selector: '[appClickLogging]',
    standalone: true,
})
export class ButtonDirective {
    @HostBinding('attr.data-button-type')
    @Input()
    type: 'success' | 'primary' | 'default' = 'default';

    @HostListener('click', ['$event'])
    onClick() {
        console.log(`%c [Log]: ${this.type}`, 'color: #3f51b5'));
    }
}

// directive for all primary mat-button
@Directive({
    selector: 'button[color="primary"]',
    standalone: true,
    hostDirectives: [ButtonDirective],
})
export class ButtonPrimaryDirective {
    constructor(@Host() buttonDirective: ButtonDirective) {
        buttonDirective.type = 'primary';
    }
}

The ButtonDirective we created using Angular’s @HostListener('click') is console logging each click event inside the onClick method. It is a standard Angular Directive used in the following approach:

<button appClickLogging type="success">
  Logging Success button
</button>

Let’s consider a scenario where a product manager asks us to track every primary button click.

Instead of manually attaching the appClickLogging to all primary buttons, we can create a ButtonPrimaryDirective with a button[color="primary"] selector to select all <button mat-flat-button color="primary">button</button> buttons. And, using Composition, attach the directive that already implements the logging mechanism inside the hostDirectives.

Attaching the ButtonDirective class into a hostDirectives, we can get a reference to that class inside our child component constructor by using dependency injection like:

constructor(@Host() buttonDirective: ButtonDirective)

Using @Host is optional but helps Angular resolve dependencies. Learn more about resolution modifiers.

Logging steps for some specific button is quite a common use case when we, for example, want to track how the user navigates through our page to find out how our application is being used.

Angular Implementation of hostDirectives

Opening the source of the hostDirectives implementation, we can inspect that we can pass a class, Type<unknown>, into the hostDirectives or an object and specify inputs and outputs properties.

// Code snippet from Angular source
/**
  * Standalone directives that should be applied to the 
  * host whenever the directive is matched.
  * By default none of the inputs or outputs of the 
  * host directives will be available on the host,
  * unless they are specified 
  * in the `inputs` or `outputs` properties.
  */
hostDirectives?: (Type<unknown> | {
    directive: Type<unknown>;
    inputs?: string[];
    outputs?: string[];
})[];

Let’s look at an example of how to use inputs and outputs properties for the hostDirectives.

@Directive({
    selector: '[appClickLogging]',
    standalone: true,
})
export class ButtonDirective {
    @Output() clickedEvent = new EventEmitter<void>();
    @Output() mouseEnterEvent = new EventEmitter<void>();

    @Input() loggingName: string = 'Base';

    @HostBinding('attr.data-button-type')
    @Input()
    type: 'success' | 'primary' | 'default' = 'default';

    @HostListener('click')
    onClick() {
        this.clickedEvent.emit();
    }

    @HostListener('mouseenter')
    onMouseenter() {
        this.mouseEnterEvent.emit();
    }
}

// ---------------------------------------------
@Directive({
    selector: '[appClickLoggingEnhanced]',
    standalone: true,
    hostDirectives: [
        {
            directive: ButtonDirective,
            inputs: ['loggingName'], // <-- inputs
            outputs: ['mouseEnterEvent'], // <-- outputs
        },
    ],
})
export class ButtonDirectiveEnhancedDirective {
    constructor(@Host() buttonDirective: ButtonDirective) {
        buttonDirective.type = 'success';
    }
}

// ---------------------------------------------
@Component({
    selector: 'app-test',
    template: `
        <button appClickLoggingEnhanced 
                (mouseEnterEvent)="onMouseEnterEvent()" 
                [loggingName]="testName">
            Button text
        </button>
    `,
    imports: [ButtonDirectiveEnhancedDirective],
    standalone: true,
})
export class TestComponent {
    testName = 'Test name';

    onMouseEnterEvent(): void {
        console.log('[TestComponent]: mouse enter');
    }
}

What inputs and outputs properties allow is to define which properties from the composite @Directive class are allowed to be exposed by the parent directive.

In our case, ButtonDirective has two inputs and two outputs, and it works as a normal directive. However, we need to tell ButtonDirectiveEnhancedDirective which properties it can expose from the ButtonDirective.

Exposing loggingName from ButtonDirectiveEnhancedDirective allows defining the @Input() in TestComponent. If the loggingName was removed from inputs in ButtonDirectiveEnhancedDirective, the compiler would throw the following error.

Angular Composition API restrictions

NOTE: Remember the following.

You can use hostDirectives in both Components and Directives

Classes in hostDirectives must be decorated with @Directive decorator

The hostDirectives directive can be used only for standalone components

Use inputs and outputs to expose properties from the composed hostDirectives

Accessing the composed directive instance inside the constructor, like constructor(buttonDirective: ButtonDirective), without including it into hostDirectives, would result in an error message No provider for ButtonDirective found in NodeInjector

Check out the proposed PR and the massive code implementation to find out more about implementing the hostDirectives support for the Angular compiler.

Composition API Examples

Using Composition in Angular instead of Inheritance may be a little bit difficult to wrap your head around. You may not instantly come up with use cases for how to use the new hostDirectives directive, so let me demonstrate its purpose in the following examples.

Example 1

We have created a TypingTrackingDirective directive, that by attaching it to any input element will log out the user’s input. We are asked to add this implementation to all textarea inputs

@Directive({
    selector: 'appTypingTracking',
    standalone: true,
})
export class TypingTrackingDirective {
    @HostListener('focus', ['$event.target.value'])
    onFocus(value: string) {
        console.log(value);
    }

    @HostListener('input', ['$event.target.value'])
    onInput(value: string) {
        console.log(`Tracking input: ${value}`);
    }
}

@Directive({
    selector: 'textarea',
    standalone: true,
    hostDirectives: [TypingTrackingDirective],
})
export class InputTrackingDirective {}

Example 2

A common practice is to use takeUntil RxJS operator with some Subject when subscribing to an Observable. This logic is repeated in multiple places, so let’s abstract it.

// Credits: 
// https://twitter.com/_crisbeto/status/1582475442715385858

@Directive({
    standalone: true,
})
export class DestroyDirective implements OnDestroy {
    private destroy$ = new Subject<void>();

    get pipe() {
        return pipe(takeUntil(this.destroy$));
    }

    ngOnDestroy(): void {
        this.destroy$.next();
        this.destroy$.complete();
    }
}

@Component({
    selector: 'app-test',
    template: '...',
    standalone: true,
    providers: [ApiService, DestroyDirective],
})
export class CompositionNewComponent {
    private untilDestroyed = inject(DestroyDirective).pipe;

    constructor(private apiService: ApiService) {
        this.apiService.linstenToUserWS()
            .pipe(this.untilDestroyed))
            .subscribe(res => console.log(res))
    }
}

Example 3

We want to extend the behavior of the *ngIf directive so that we are able to reveal HTML content when an HTTP request has finished, but we can also toggle its visibility by clicking on a button.

@Injectable()
export class ActiveService {
    private active$ = new BehaviorSubject<boolean>(false);

    isActive(): Observable<boolean> {
        return this.active$.asObservable();
    }

    toggleActivation(): void {
        console.log('Toggling state');
        this.active$.next(!this.active$.value);
    }
}

@Directive({
    selector: '[ifActive]',
    standalone: true,
    hostDirectives: [NgIf],
})
export class ActiveDirective implements OnInit {
    private ngIfDirective = inject(NgIf);
    private activeService = inject(ActiveService);

    ngOnInit(): void {
        this.activeService.isActive().subscribe((state) => {
            this.ngIfDirective.ngIf = state;
        });
    }
}

@Directive({
    selector: '[toggleActive]',
    standalone: true,
})
export class ToggleActiveDirective {
    constructor(
          @SkipSelf() private activeService: ActiveService
        ) {}

    @HostListener('click', ['$event'])
    onClick() {
        this.activeService.toggleActivation();
    }
}

Component({
    selector: 'app-test',
    template: `
    <!-- using ngIfActive directive -->
    <button toggleActive>Toggle Reveal</button>

    <!-- display 2 revealing block -->
    <div *ifActive>Toggling state 1111</div>
    <div *ifActive>Toggling state 2222</div>
  `,
    imports: [ToggleActiveDirective, ActiveDirective],
    standalone: true,
    providers: [ActiveService],
});
export class TestComponent {
    constructor(@Host() private activeService: ActiveService) {
        // mocking HTTP request -> reveal content after 3 seconds
        of([])
            .pipe(delay(3000))
            .subscribe(
               () => this.activeService.toggleActivation()
             );
    }
}

Example 4

Let’s say we are using CdkDrag and matTooltip plenty of times in our application by the following approach

<button cdkDrag matTooltip="Info" [matTooltipHideDelay]="400">
    Click me
</button>

To compose the behavior of these two Directives, you may be tempted to create something like

@Directive({
    selector: '[appButtonTooltip]',
    standalone: true,
    hostDirectives: [
        {
            directive: MatTooltip,
            inputs: [
               'matTooltip: tooltip',
               'matTooltipHideDelay: tooltipHideDelay'
              ],
        },
        {
            directive: CdkDrag,     
        },
    ],
})
export class ButtonTooltipDirective {}

Unfortunately, this will not work. The Angular compiler will throw an error because as we previously mentioned you can only use Directives in hostDirectives in Standalone Components.

Until Angular Material Directives do not migrate to standalone Directives, you have to use the old approach: <button cdkDrag matTooltip="Info" [matTooltipHideDelay]="400">.

Summary

It is good to see that the Angular team is focusing on expanding its ecosystem and bringing new features. In this article, we described the newly added hostDirectives directive, and how it can be useful for abstracting repeated logic into one place and avoiding using Inheritance. The source code that covers this example and additional features can be found in the following GitHub repository.

For more information check out our training program!

Waiting for Angular to fix your problem?

Let us take a whack at it! Book your free Angular consulting call to talk through your project with an expert.

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!