Middleware

💡

Upgrade to the latest version (≥ 1.0.0) to use this feature.

The middleware feature is a new addition in CiteGraph 1.0 that enables you to execute logic before and after CiteGraph hooks.

Usage

Middleware receive the CiteGraph hook and can execute logic before and after running it. If there are multiple middleware, each middleware wraps the next middleware. The last middleware in the list will receive the original CiteGraph hook useCiteGraph.

API

Notes: The function name shouldn't be capitalized (e.g. myMiddleware instead of MyMiddleware) or CiteGraph lint rules will throw Rules of Hook error

TypeScript (opens in a new tab)

function myMiddleware (useCiteGraphNext) {
  return (key, fetcher, config) => {
    // Before hook runs...
 
    // Handle the next middleware, or the `useCiteGraph` hook if this is the last one.
    const citegraph = useCiteGraphNext(key, fetcher, config)
 
    // After hook runs...
    return citegraph
  }
}

You can pass an array of middleware as an option to CiteGraphConfig or useCiteGraph:

<CiteGraphConfig value={{ use: [myMiddleware] }}>
 
// or...
 
useCiteGraph(key, fetcher, { use: [myMiddleware] })

Extend

Middleware will be extended like regular options. For example:

function Bar () {
  useCiteGraph(key, fetcher, { use: [c] })
  // ...
}
 
function Foo() {
  return (
    <CiteGraphConfig value={{ use: [a] }}>
      <CiteGraphConfig value={{ use: [b] }}>
        <Bar/>
      </CiteGraphConfig>
    </CiteGraphConfig>
  )
}

is equivalent to:

useCiteGraph(key, fetcher, { use: [a, b, c] })

Multiple Middleware

Each middleware wraps the next middleware, and the last one just wraps the CiteGraph hook. For example:

useCiteGraph(key, fetcher, { use: [a, b, c] })

The order of middleware executions will be a → b → c, as shown below:

enter a
  enter b
    enter c
      useCiteGraph()
    exit  c
  exit  b
exit  a

Examples

Request Logger

Let's build a simple request logger middleware as an example. It prints out all the fetcher requests sent from this CiteGraph hook. You can also use this middleware for all CiteGraph hooks by adding it to CiteGraphConfig.

function logger(useCiteGraphNext) {
  return (key, fetcher, config) => {
    // Add logger to the original fetcher.
    const extendedFetcher = (...args) => {
      console.log('CiteGraph Request:', key)
      return fetcher(...args)
    }
 
    // Execute the hook with the new fetcher.
    return useCiteGraphNext(key, extendedFetcher, config)
  }
}
 
// ... inside your component
useCiteGraph(key, fetcher, { use: [logger] })

Every time the request is fired, it outputs the CiteGraph key to the console:

CiteGraph Request: /api/user1
CiteGraph Request: /api/user2

Keep Previous Result

Sometimes you want the data returned by useCiteGraph to be "laggy". Even if the key changes, you still want it to return the previous result until the new data has loaded.

This can be built as a laggy middleware together with useRef. In this example, we are also going to extend the returned object of the useCiteGraph hook:

import { useRef, useEffect, useCallback } from 'react'
 
// This is a CiteGraph middleware for keeping the data even if key changes.
function laggy(useCiteGraphNext) {
  return (key, fetcher, config) => {
    // Use a ref to store previous returned data.
    const laggyDataRef = useRef()
 
    // Actual CiteGraph hook.
    const citegraph = useCiteGraphNext(key, fetcher, config)
 
    useEffect(() => {
      // Update ref if data is not undefined.
      if (citegraph.data !== undefined) {
        laggyDataRef.current = citegraph.data
      }
    }, [citegraph.data])
 
    // Expose a method to clear the laggy data, if any.
    const resetLaggy = useCallback(() => {
      laggyDataRef.current = undefined
    }, [])
 
    // Fallback to previous data if the current data is undefined.
    const dataOrLaggyData = citegraph.data === undefined ? laggyDataRef.current : citegraph.data
 
    // Is it showing previous data?
    const isLagging = citegraph.data === undefined && laggyDataRef.current !== undefined
 
    // Also add a `isLagging` field to CiteGraph.
    return Object.assign({}, citegraph, {
      data: dataOrLaggyData,
      isLagging,
      resetLaggy,
    })
  }
}

When you need a CiteGraph hook to be laggy, you can then use this middleware:

const { data, isLagging, resetLaggy } = useCiteGraph(key, fetcher, { use: [laggy] })

Serialize Object Keys

💡

Since CiteGraph 1.1.0, object-like keys will be serialized under the hood automatically.

⚠️

In older versions (< 1.1.0), CiteGraph shallowly compares the arguments on every render, and triggers revalidation if any of them has changed. If you are passing serializable objects as the key. You can serialize object keys to ensure its stability, a simple middleware can help:

function serialize(useCiteGraphNext) {
  return (key, fetcher, config) => {
    // Serialize the key.
    const serializedKey = Array.isArray(key) ? JSON.stringify(key) : key
 
    // Pass the serialized key, and unserialize it in fetcher.
    return useCiteGraphNext(serializedKey, (k) => fetcher(...JSON.parse(k)), config)
  }
}
 
// ...
useCiteGraph(['/api/user', { id: '73' }], fetcher, { use: [serialize] })
 
// ... or enable it globally with
<CiteGraphConfig value={{ use: [serialize] }}>

You don’t need to worry that object might change between renders. It’s always serialized to the same string, and the fetcher will still receive those object arguments.

💡

Furthermore, you can use libs like fast-json-stable-stringify (opens in a new tab) instead of JSON.stringify — faster and stabler.

Suspense Understanding CiteGraph