Introducing Obsidian: GraphQL, built for Deno
Obsidian is Deno’s first native GraphQL caching client and server module. Obsidian is equipped with lightning-fast normalized caching to support scalable, highly performant SSR React applications built with Deno.
What is Obsidian?
GraphQL is an incredible technology- a query language and runtime for your API, giving clients the power to ask for just the data they need and nothing more. Over the last five years, GraphQL has grown in popularity, especially with strong open source contributions and lasting support from its developer, Facebook.
Deno is an equally remarkable project- a secure runtime for JavaScript and TypeScript, providing a built-in package manager via ES module imports from anywhere on the web. Deno was built by Ryan Dahl, the original creator of Node.js, and is poised to offer a competitive alternative to Node’s dominant JavaScript runtime.
Obsidian arrives at the intersection of these two pioneering technologies. Obsidian is a caching GraphQL router for your Oak Deno server and a caching client for your server-side rendered React app.
We couldn’t be more excited to share Obsidian with you. Let’s take a look.
What does Obsidian do?
There are two distinct parts to Obsidian: ObsidianRouter, a caching GraphQL router built upon Deno's Oak server framework, and ObsidianWrapper, a React component that functions as a GraphQL client for your application, providing global access to fetching and caching capabilities.
Each of these parts aims to provide a seamless GraphQL implementation in Deno, with a caching layer that adheres to the following core values:
- Fast ~ Caching with obsidian should be nearly imperceptible — a client or server module should feel no slower with a caching layer
- Opinionated ~ Caching with obsidian should be structured — structure brings clarity, and clarity brings efficiency
- Consistent ~ Caching with obsidian should prize consistency — discerning truth should be automatic and transparent
Before we cover Obsidian’s caching strategies, let’s learn how you can utilize Obsidian.
ObsidianRouter
ObsidianRouter constructs a complete GraphQL endpoint for your Oak Deno server with user-defined type definitions and resolvers, and creates a caching layer via a local redis instance. Thanks to Deno’s ES module imports, installation is as simple as importing directly from deno.land. Here is an example of how to set up ObsidianRouter:
As long as we’ve got a running redis instance at the port we’ve specified, we can spin up the server and visit the /graphql endpoint to begin using our GraphQL router in the Playground:
deno run --allow-net --unstable server.tsxBefore we discuss caching, let’s examine Obsidian’s client implementation — ObsidianWrapper.
ObsidianWrapper
ObsidianWrapper is a React component that provides global access to Obsidian’s fetching and caching capabilities. Installation in your React app is a breeze — simply wrap your top-level component:
Above, we mentioned that Obsidian is designed for React apps built with server-side rendering. To utilize Obsidian’s caching capabilities in the client, we must send an obsidianSchema with our app, attached to the window object. ObsidianRouter helpfully provides this schema for us, which we can extract and send like so:
For more information about Obsidian and server-side rendering, you can learn more in our documentation.
Once we’ve wrapped our app and sent obsidianSchema, we can make caching queries to our endpoint with the gather method, which we access by invoking the useObsidian custom hook:
Caching
Obsidian is more than just a GraphQL router and client — Obsidian offers a headlining normalized caching algorithm to ensure your API stays lean and performant, even as its scope grows. To accomplish this, Obsidian normalizes outgoing responses, and reconstructs responses for incoming queries from the normalized caching layer.
This normalized approach removes replication of data in the cache, improves memory management, and opens the door to mutation consistency in the cache layer. As Obsidian grows, full stack cache coordination and robust mutation support are early on the development roadmap.
Obsidian also offers a whole-query caching strategy, as well as a ‘cacheless’ approach to provide flexibility when building out your application. You can read more about Obsidian’s caching strategies and philosophy here.
Documentation
We have provided extensive documentation on our website, obsidian.land. If you find an error in the documentation, please submit an issue via GitHub.
Open-Source & Community Contributions
Obsidian is an open-source project developed under tech accelerator OS Labs. We welcome contributions and feedback via GitHub, and if you love using Obsidian or you’re just excited by the project, we appreciate each GitHub star that comes our way.
