Obsidian 2.0 Launch

Introduction

Team Obsidian and Open Source Labs would like to announce the official launch of Obsidian 2.0!

Obsidian is Deno’s first native GraphQL caching client and server module. For first-time Obsidian users, please go to Obsidian’s official website, which provides detailed documentation on the library and how to get started. For veteran Obsidian users, we will highlight three of Obsidian 2.0’s updates below.

1. Flexible Query Matches

Obsidian now supports more flexible query matches when using the normalized caching strategy. Previously, Obsidian’s cache would only return data on a perfect one-to-one query match. There were cases when the relevant response data was already located in the cache; however, the cache couldn’t perfectly match the query, so it would make a network request for the data. With the recent changes to Obsidian’s underlying caching algorithms, it now supports more flexible query matches. This means less unnecessary network requests and faster response times for your application’s users. Please see the following example:

const query1 = `{
  movie(id: 1) {
    id
    title
    genre
  }
}`;
const query2 = `{
  movie(id: 1) {
    id
    title
  }
}`;

Previously, Obsidian would require two network requests to fulfill these queries. Now, Obsidian 2.0 stores the initial query in the cache in a way that an additional network request will be unnecessary for the second query.

2. Mutation Caching Support

Obsidian 2.0 now supports mutation caching. Obsidian applications can create, delete, and update elements while making sure their cache is always up to date. Previously, a mutation query cleared the entire cache. Now, there is automatic caching for the update and delete mutations and with minimal developer input, created mutations can also be cached correctly. This allows developers to create more advanced applications and gives them the ability to configure their cache to meet their specific mutation needs.

// gql query for all movies
const query = `{
  movies {
    id
    title
  }
}`;
// client-side cache after query
const cache = {
  ROOT_QUERY: {
    movies: ['Movie~1', 'Movie~2'],
  },
  ROOT_MUTATION: {},
  'Movie~1': {
    id: '1',
    title: 'Fight Club',
  },
  'Movie~2': {
    id: '2',
    title: 'Moneyball',
  },
};
// gql mutation to add a movie
const mutation = `{
  addMovie(title: "Ad Astra" ) {
    id
    title
  }
}`;
// developer-defined update function
function updateMovies(cache, respObj) {
  const { movies } = cache.read(query).data;
  const newMovie = respObj.data.addMovie;
  const updatedRespObj = { 
    data: { 
      movies: [newMovie, ...movies] 
    }
  };
  cache.write(query, updatedRespObj);
}
// mutation sent via Obsidian api
mutate(mutation, { update: updateMovies });
// client-side cache after mutation
const cache = {
  ROOT_QUERY: {
    movies: ['Movie~3', 'Movie~1', 'Movie~2'],
  },
  ROOT_MUTATION: {
    'addMovie:(title:"AdAstra")': 'Movie~3',
  },
  'Movie~1': {
    id: '1',
    title: 'Fight Club',
  },
  'Movie~2': {
    id: '2',
    title: 'Moneyball',
  },
  'Movie~3': {
    id: '3',
    title: 'Ad Astra',
  },
};

3. ‘Schemaless’ Obsidian Client

Obsidian no longer requires the client to have access to the GraphQL schema for normalized caching. Previously, to utilize normalized caching, an Obsidian Client needed to be working in tandem with a server that used an Obsidian Router and passed a schema. Developers can now use Obsidian with any GraphQL endpoint and take advantage of normalized caching.

Conclusion

A demo app can be found here, which showcases all of Obsidian’s exciting new features. More documentation on how to get started with Obsidian can be found at obsidian.land.

We look forward to seeing what people build with Obsidian and all of its new features. Please direct any feature requests or bugs to the issues tab on our github.

Thank you,

Team Obsidian

Lourent Flores, Linkedin & Github
Eric Marcatoma, Linkedin & Github
Derek Miller, Linkedin & Github
Esma Sahraoui, Linkedin & Github
Spencer Stockton, Linkedin & Github