react-susflow

Introduction

react-susflow is a library designed to simplify asynchronous data fetching and integration with React Suspense. By utilizing the sus function, developers can effortlessly make their asynchronous operations work seamlessly with React Suspense, enhancing the loading experience and error handling.

Try it in Codesandbox

Installation

To install react-susflow, run:

npm i react-susflow
yarn add react-susflow
pnpm i react-susflow

Quick Start

The react-susflow library introduces caching capabilities to optimize asynchronous data fetching. Below is a quick guide on utilizing these new features within a React application:

import {Suspense} from "react";
import {sus} from 'react-susflow';

// Define an asynchronous function for data fetching
const fetchData = async (param) => {
  const response = await fetch(`https://api.example.com/data?param=${param}`);
  if (!response.ok) {
    throw new Error('Network response was not ok');
  }
  return response.json();
};

// Wrap the async function with `sus`, specifying cache options
const resource = sus(fetchData, {
  cache: {
    enable: true, // Enable caching
    ttl: 300000 // Cache TTL set to 5 minutes, default to 1 minute
  }
});

const SusComponent = () => {
  const value = resource.read("world!");
  return <>{JSON.stringify(value)}</>;
};

const SusComponent2 = () => {
  const value = resource.read("china!", {useCache: false}); // useCache is set default to true
  return <>{JSON.stringify(value)}</>;
};

// App component with two Suspense wrappers for each resource usage
export default function App() {
  return (
    <>
      <Suspense fallback={<>Loading...</>}>
        <SusComponent/>
      </Suspense>
      <Suspense fallback={<>Loading...</>}>
        <SusComponent2/>
      </Suspense>
    </>
  );
}

This example demonstrates the use of react-susflow with caching enabled, showing how to selectively bypass the cache for certain reads using the useCache: false option.

API Reference

sus(asyncFunction, options?)

Creates a resource from an asynchronous function, optionally configuring caching.

• Parameters:

  • asyncFunction: An async function that returns a Promise.
  • options (optional): Configuration for caching.
    • cache:
      • enable (optional): Boolean to enable or disable caching.
      • ttl (optional): Time-to-live for cache entries in milliseconds.

• Returns: An object with a read method for fetching data, either from the cache or by executing the asynchronous function.

read(...params, readOptions?)

Triggers the asynchronous operation, optionally utilizing the cache based on readOptions.

• Parameters:
  • ...params: Arguments to pass to the asynchronous function.
  • readOptions (optional): Options for reading data.
    • useCache (optional): Boolean to specify whether to use the cache. Setting this to false forces a fresh fetch, bypassing the cache.

By providing a flexible caching mechanism and the ability to control cache usage on a per-read basis, react-susflow enhances data fetching strategies in React applications, offering improved performance and user experience.

Frequently Asked Questions (FAQ)

This section can provide answers to some common questions, such as how to handle errors, how to reload data, etc.

Contribution

Contributions to react-susflow are welcome! Please check out our GitHub repository for more information.

License

react-susflow is released under the MIT license.