2024 Industry Survey:
Data Consistency in Front-End Projects

Showcase Scenario

Imagine a scenario where we have a full-stack application that manages a list of users. We want to make sure that the user data model remains consistent on both the client (ie. React with TypeScript) and the server (ie. Node.js with Express and TypeScript). We can achieve this by defining TypeScript types or interfaces in a shared module that both the front-end and back-end can import.

export interface User {
  id: string;
  name: string;
  email: string;
  isActive: boolean;
}

We can then use this type in our components and back-end code to validate our data at compile-time.

import { User } from './types';

// Example user list
const users: User[] = [
  { id: '1', name: 'Alice', email: 'alice@example.com', isActive: true },
  { id: '2', name: 'Bob', email: 'bob@example.com', isActive: false },
];

function fetchUsers(): Promise<User[]> {
  // Fetch users from the back-end API
  return fetch('/api/users').then((res) => res.json());
}

// Usage in component logic...

Note: If your back-end is written in a different technology, such as Go, then types must be mirrored in both projects. This can be done either manually or by using transpiling tools from a declarative SSOT, such as Morphe specification files in tandem with Dia-compatible ecosystem plugins.

Key Features

As we know, each approach has trade-offs that must be carefully weighed for each project.

This approach has many advantages:

1. Simplicity and Readability: Using plain objects keeps the code simple and easy to read. It aligns closely with vanilla JavaScript, making it accessible to developers transitioning from JavaScript to TypeScript. Plain objects are also highly flexible, allowing developers to define interfaces and types without being tied to class hierarchies or more complex patterns.
2. Type Safety: TypeScript’s static compile-time type checking ensures that objects adhere to defined shapes, ultimately reducing runtime errors and making code more predictable.
3. Easy Adoption: Teams already familiar with JavaScript can adopt TypeScript with plain objects with minimal learning curve. There is no need for transpilation beyond what is necessary for TypeScript itself; the output remains clean and efficient JavaScript.

But also comes with some disadvantages:

1. Compile-time checking: Typescript follows the principle of compile-time checking. If your server returns an unexpected format that does not adhere to the defined type, your application will likely exhibit strange behaviors or result in errors at run-time.
2. Lack of enforced constraints: Related to the previous point: plain TypeScript / JavaScript objects cannot prevent invalid states or ensure data integrity, potentially requiring extra validation code.
3. Maintenance challenges: Plain objects can lead to inconsistent or redundant type definitions across large, distributed codebases, increasing the risk of type drift and making refactoring harder. As projects grow, this can negatively impact scalable maintainability when contrasted against more structured approaches.

Showcase Scenario

Zod compensates for some of the issues that exist in Typescript-only projects. To explore this in more detail, we will continue with the previous example of managing a list of users.

Let's define our User schema with Zod and then derive our front-end type from it:

import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  name: z.string().min(2, "Name must be at least 2 characters"),
  email: z.string().email("Invalid email format"),
  isActive: z.boolean()
});

type User = z.infer<typeof UserSchema>;

function validateUser(data: unknown): User {
  return UserSchema.parse(data);
}

In our other front-end code we can then use this schema definition and accompanying type for runtime validation:

const users: User[] = [
  { id: '1', name: 'Alice', email: 'alice@example.com', isActive: true },
  { id: '2', name: 'Bob', email: 'bob@example.com', isActive: false }
];

function fetchUsers(): Promise<User[]> {
  return fetch('/api/users')
    .then(response => response.json())
    .then(data => {
      // Validate and parse the response data
      return z.array(UserSchema).parse(data);
    });
}

// In a React component
function UserList() {
  const [users, setUsers] = useState<User[]>([]);

  useEffect(() => {
    fetchUsers().then(setUsers).catch(console.error);
  }, []);

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>
          {user.name} ({user.email}) - {user.isActive ? 'Active' : 'Inactive'}
        </li>
      ))}
    </ul>
  );
}

Key Features

Zod's growing popularity is indicative of the potential upsides for engineers in larger projects:

1. TypeScript integration: Zod is built with TypeScript in mind, allowing you to infer TypeScript types from your schemas. This ensures consistency between both your runtime checks and compile-time types.
2. Parse, don't validate: Zod follows the "parse, don't validate" philosophy, transforming unknown data into typed data structures, which can help prevent type errors in your application.
3. Rich validation: Zod provides a wide range of built-in validations and allows for custom validation logic, enabling complex data integrity rules. It also offers detailed error messages when validation fails, making it easier to debug issues with incoming data.

But also comes with some disadvantages:

1. Learning curve: While Zod's API is designed to be intuitive, it still requires learning a new library and its concepts. While growing rapidly, Zod's ecosystem and community support may also not be as extensive as some more established solutions.
2. Application overhead: As with any runtime validation, there's a small performance cost associated with checking data structures during execution. Also, including Zod in your project will increase your bundle size, though the impact is generally minimal for most applications.
3. Schema redundancy: When working with a strongly-typed backend (e.g., TypeScript Node.js server), using Zod can lead to duplication of type definitions. You might find yourself defining types on the server, then redefining similar structures as Zod schemas on the client. This duplication can lead to maintenance challenges and potential inconsistencies if not managed carefully. While tools exist to help synchronize these definitions, they add another layer of complexity to your development process.

Showcase Scenario

Let's revisit our scenario where we have a full-stack application that manages a list of users. We want to ensure that the user data model remains consistent on both the client (e.g., React) and the server (e.g., Node.js with Express).

With JSON Schema, we can define a schema that both the front-end and back-end can use for validation.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "isActive": {
      "type": "boolean"
    }
  },
  "required": ["id", "name", "email", "isActive"]
}

Now, we can use a library like ajv to validate our data against this schema:

import Ajv from 'ajv';
import addFormats from 'ajv-formats';
import userSchema from 'schema/user.json'

const ajv = new Ajv();
addFormats(ajv);

function validateUser(user) {
  const validator = ajv.compile(userSchema);
  const valid = validator(user);
  if (!valid) console.log(validator.errors);
  return valid;
}

// Example user list
const users = [
  { id: '1', name: 'Alice', email: 'alice@example.com', isActive: true },
  { id: '2', name: 'Bob', email: 'bob@example.com', isActive: false },
];

// Validate existing users
users.forEach(user => {
  if (validateUser(user)) {
    console.log(`User ${user.name} is valid`);
  } else {
    console.log(`User ${user.name} is invalid`);
  }
});

async function fetchUsers() {
  const response = await fetch('/api/users');
  const users = await response.json();
  // Only return valid users
  return users.filter(validateUser);
}

// Usage in component logic...

In this example, we define a JSON schema for our user data and use it to validate both static data and data fetched from an API. This ensures that only valid user objects are processed by our application.

Key Features

Like basic typescript objects, JSON schemas come with trade-offs that should be considered.

They offer several advantages for ensuring data consistency:

1. Runtime validation: Unlike TypeScript, JSON schemas allow for runtime validation, catching unexpected data formats that might slip through compile-time checks.
2. Language-agnosticism: JSON schemas can be used with any programming language that can parse JSON, making them great for full-stack applications and API contracts.
3. Self-documenting: The schema itself serves as documentation for the expected data structure, which can be useful for both developers and API consumers.
4. Verbose constraints: JSON Schema allows for complex validation rules, including conditional validation, which can be harder to express with TypeScript types alone.

However, there are also some potential drawbacks:

1. Performance overhead: Validating data against a schema at runtime can introduce some performance overhead, especially for large or complex data structures.
2. Additional learning curve: While JSON Schema is powerful, it has its own syntax and concepts that developers need to learn, which is separate from learning TypeScript or JavaScript.
3. Maintenance challenges: Unlike TypeScript, JSON Schema doesn't provide static analysis in your IDE, meaning you might catch errors later in the development process. In addition, as your data model evolves, you'll need to keep your JSON schemas updated, which adds more code volume that needs to be maintained as your project grows.

Showcase Scenario

To better understand how this plays out in practice, let's use our same scenario where we have a full-stack application that manages a list of users, only this time using GraphQL with TypeScript. We'll define a GraphQL schema on the server and use it to generate TypeScript types for our front-end application.

First, let's define our GraphQL schema:

type User {
    id: ID!
    name: String!
    email: String!
    isActive: Boolean!
}

type Query {
    users: [User!]!
    user(id: ID!): User
}

type Mutation {
    createUser(name: String!, email: String!, isActive: Boolean!): User!
    updateUser(id: ID!, name: String, email: String, isActive: Boolean): User
}

Next, you can use open-source tooling such as GraphQL Codegen plugins to automatically generate TypeScript types from your GraphQL schema. The Apollo client docs have a detailed article on how to do this here.

Here's an example of what the generated types might look like:

export type User = {
  id: string;
  name: string;
  email: string;
  isActive: boolean;
};

export type Query = {
  users: Array<User>;
  user?: Maybe<User>;
};

export type Mutation = {
  createUser: User;
  updateUser?: Maybe<User>;
};

With these types in place, we can use a GraphQL client like Apollo Client to interact with our API:

import { gql, useQuery } from '@apollo/client';
import { User } from './generated/graphql';

const GET_USERS = gql`
  query GetUsers {
    users {
      id
      name
      email
      isActive
    }
  }
`;

function UserList() {
  const { loading, error, data } = useQuery<{ users: User[] }>(GET_USERS);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error!</p>;

  return (
    <ul>
      {data?.users.map(user => (
        <li key={user.id}>{user.name} ({user.email})</li>
      ))}
    </ul>
  );
}

Key Features

GraphQL with strong typing provides significant benefits when striving for front-end data consistency:

1. Type safety: GraphQL's type system, combined with TypeScript, provides end-to-end type safety from your server to your client, at a marginal cost due to generative tooling.
2. Single-Source-of-Truth: The GraphQL schema serves as a single source of truth for your data model, which can be used to generate types for both front-end and back-end. This streamlined approach reduces friction without losing sleep over type-safety.
3. Minimize bandwidth: GraphQL allows clients to request exactly the data they need, reducing over-fetching and under-fetching of data. Sub-types can be easily generated, ensuring we pass around exactly what we need.

But of course we have to also consider the potential downsides:

1. Tooling dependency: The effectiveness of this approach relies heavily on tooling for code generation and enforcement of API contracts in full-stack interactions.
2. Setup complexity: Implementing a GraphQL API and setting up code generation can be more complex than a traditional REST API. Available resources do exist, but depending on your specific needs might be harder to set up.
3. Learning curve: GraphQL introduces new concepts and requires learning yet another query language, which can be challenging for teams that are already spread thin in modern-day application architectures.

Showcase Scenario

Let's revisit our user management scenario using OOP-inspired JavaScript classes. We'll define a User class that encapsulates the data and provides methods for validation and manipulation.

class User {
  constructor(id, name, email, isActive) {
    this.id = id;
    this.name = name;
    this.email = email;
    this.isActive = isActive;
  }

  // Getter methods
  getId() { return this.id; }
  getName() { return this.name; }
  getEmail() { return this.email; }
  isActive() { return this.isActive; }

  // Setter methods with validation
  setId(id) {
    if (typeof name !== 'string' || name.length < 1) {
      throw new Error('Id must be a string with at least 1 character');
    }
    this.name = name;
  }
  setName(name) {
    if (typeof name !== 'string' || name.length < 2) {
      throw new Error('Name must be a string with at least 2 characters');
    }
    this.name = name;
  }

  setEmail(email) {
    const emailRegex = /^[^s@]+@[^s@]+.[^s@]+$/;
    if (!emailRegex.test(email)) {
      throw new Error('Invalid email format');
    }
    this.email = email;
  }

  setActive(isActive) {
    if (typeof isActive !== 'boolean') {
      throw new Error('isActive must be a boolean');
    }
    this.isActive = isActive;
  }

  // Method to create a plain object representation
  toJSON() {
    return {
      id: this.id,
      name: this.name,
      email: this.email,
      isActive: this.isActive
    };
  }

  // Static method to create a User instance from plain object
  static fromJSON(json) {
    return new User(json.id, json.name, json.email, json.isActive);
  }
}

In our components and services we can then simply serialize and deserialize through our class, which offers a central source of truth for structural validity:

const users = [
  new User('1', 'Alice', 'alice@example.com', true),
  new User('2', 'Bob', 'bob@example.com', false)
];

function fetchUsers() {
  return fetch('/api/users')
    .then(response => response.json())
    .then(data => data.map(User.fromJSON));
}

// In a React component
function UserList() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    fetchUsers().then(setUsers);
  }, []);

  return (
    <ul>
      {users.map(user => (
        <li key={user.getId()}>
          {user.getName()} ({user.getEmail()}) - 
          {user.isActive() ? 'Active' : 'Inactive'}
        </li>
      ))}
    </ul>
  );
}

Key Features

Using JavaScript classes for data consistency offers several advantages:

1. Encapsulation: Classes allow you to bundle data with methods that operate on that data, providing a clean, centralized interface for interacting with your data structures.
2. Validation: You can implement validation logic within setter methods, ensuring that data always meets your criteria before it's set. This can be very useful in enforcing data consistency with data coming from multiple sources (forms, db, ...) across the stack.
3. Simple and familiar: For developers coming from strongly object-oriented languages, classes provide a familiar paradigm for managing data. No additional tooling is required, as classes are supported out-of-the-box by modern-day JS implementations.

But of course we have to also consider the potential downsides:

1. Verbosity: Class implementations can be more verbose compared to plain objects or functional approaches, potentially leading to more boilerplate code.
2. Performance: Creating instances of classes can be slightly slower and more memory-intensive than working with plain objects, though this is rarely a significant issue in most applications.
3. Typing / Immutability challenges: JavaScript classes are inherently mutable, which can make it harder to implement immutable data patterns that are often preferred in modern front-end development. Additionally, while you can combine classes with TypeScript for better type checking, plain JavaScript classes don't provide compile-time type checking.