remix-client-cache

npm GitHub npm npm GitHub top language

重要信息

此库现在是 React Router 生态系统的一部分，并在 React Router 之上运行。它应该与 remix.run 兼容，但如果您遇到问题，1.1.0 版本是最后一个可与 remix.run 一起使用的版本。

remix-client-cache 是一个强大且轻量级的库，专为 Remix.run 设计，用于使用 clientLoaders 在客户端缓存服务器加载器数据。

默认情况下，它使用过时数据重验证策略，并在从服务器加载后热交换过时信息。它还允许您使特定键或多个键的缓存失效。

它允许您传入您选择的适配器来缓存您的数据。

它带有一个默认适配器，该适配器使用内存存储来缓存您的数据。

对 localStorage、sessionStorage 和 localforage 包的一流支持。您只需将它们作为参数提供给 configureGlobalCache。

安装

npm install remix-client-cache

基本用法

这是使用默认内存适配器使用 remix-client-cache 的示例。

import { json, type LoaderFunctionArgs } from "@remix-run/node";
import { ClientLoaderFunctionArgs } from "@remix-run/react";

import { cacheClientLoader, useCachedLoaderData } from "remix-client-cache";

export const loader = async ({ params }: LoaderFunctionArgs) => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/users/${params.user}`
  );
  const user = await response.json();
  await new Promise((resolve) => setTimeout(resolve, 1000));
  return json({ user: { ...user, description: Math.random() } });
};


// Caches the loader data on the client
export const clientLoader = (args: ClientLoaderFunctionArgs) => cacheClientLoader(args);
  
// make sure you turn this flag on
clientLoader.hydrate = true;

export default function Index() {
  // The data is automatically cached for you and hot swapped when refetched
  const { user } = useCachedLoaderData<typeof loader>(); 

  return (
    <div>
      {user.name} <hr /> {user.email}
      <hr />
      {user.username}
      <hr />
      {user.website} <hr />
      {user.description} 
    </div>
  );
}

缓存适配器

该库导出一个您需要实现的接口才能创建自己的缓存适配器。该接口称为 CacheAdapter。它与 Storage 的接口非常匹配，并且要求您具有以下方法

getItem：接受一个键，并返回一个 Promise，该 Promise 解析为存储在该键处的值
setItem：接受一个键和一个值，并返回一个 Promise，该 Promise 在值存储时解析
removeItem：接受一个键，并返回一个 Promise，该 Promise 在值被删除时解析

cacheLoaderData 将使用库附带的默认内存缓存适配器。如果您需要高级用例，请确保您提供的适配器实现了 CacheAdapter 接口。

// Inside your entry.client.tsx file 
import { RemixBrowser } from "@remix-run/react";
import { startTransition, StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";

import { configureGlobalCache } from "remix-client-cache";

// You can use the configureGlobalCache function to override the libraries default in-memory cache adapter
configureGlobalCache(() => localStorage); // uses localStorage as the cache adapter

startTransition(() => {
  hydrateRoot(
    document,
    <StrictMode>
      <RemixBrowser />
    </StrictMode>
  );
});

您可以使用 configureGlobalCache 函数来覆盖库的默认内存缓存适配器。它将全局切换到您提供给它的任何适配器。

如果您想为每个路由设置一个适配器，可以使用 createCacheAdapter 创建一个适配器并将其提供给您的钩子和函数。


import { createCacheAdapter, useCachedLoaderData } from "remix-client-cache";

const { adapter } = createCacheAdapter(() => localStorage); // uses localStorage as the cache adapter


// Caches the loader data on the client
export const clientLoader = (args: ClientLoaderFunctionArgs) => cacheClientLoader(args, { 
  // We pass our custom adapter to the clientLoader
  adapter
});
  
// make sure you turn this flag on
clientLoader.hydrate = true;

export default function Index() {
  const { user } = useCachedLoaderData<typeof loader>({ 
    // We use the adapter returned by the createCacheAdapter function
    adapter
  });

  return (
    <div>
      {user.name} <hr /> {user.email}
      <hr />
      {user.username}
      <hr />
      {user.website} <hr />
      {user.description} 
    </div>
  );
}

以下是一些如何使用不同全局适配器使用该库的示例。

configureGlobalCache(() => localStorage); // uses localStorage as the cache adapter
configureGlobalCache(() => sessionStorage); // uses sessionStorage as the cache adapter
configureGlobalCache(() => localforage); // uses localforage as the cache adapter

以及使用不同的每个路由适配器

const { adapter } = createCacheAdapter(() => localStorage); // uses localStorage as the cache adapter
const { adapter } = createCacheAdapter(() => sessionStorage); // uses sessionStorage as the cache adapter
const { adapter } = createCacheAdapter(() => localforage); // uses localforage as the cache adapter

假设您想使用一个自定义适配器，该适配器使用数据库来存储数据。

您可以通过实现 CacheAdapter 接口并将其传递给 configureGlobalCache 或 createCacheAdapter 函数来做到这一点。

class DatabaseAdapter implements CacheAdapter {
  async getItem(key: string) {
    // get the item from the database
  }

  async setItem(key: string, value: string) {
    // set the item in the database
  }

  async removeItem(key: string) {
    // remove the item from the database
  }
}

configureGlobalCache(() => new DatabaseAdapter()); // uses your custom adapter as the cache adapter globally
const { adapter } = createCacheAdapter(() => new DatabaseAdapter()); // uses your custom adapter as the cache adapter per route

API

createCacheAdapter

创建缓存适配器并返回它的函数。它接受一个参数，即用于存储数据的 adapter。

import { createCacheAdapter } from "remix-client-cache";

const { adapter } = createCacheAdapter(() => localStorage); // uses localStorage as the cache adapter

configureGlobalCache

配置全局缓存适配器的函数。它接受一个参数，即用于存储数据的 adapter。

import { configureGlobalCache } from "remix-client-cache";

configureGlobalCache(() => localStorage); // uses localStorage as the cache adapter

cacheClientLoader

用于缓存使用 clientLoader 导出从加载器管道传输到您的组件的数据。

它接受两个参数，第一个是传递给 clientLoader 函数的 ClientLoaderFunctionArgs 对象，第二个是具有以下属性的对象

type - 告诉客户端加载器是否应使用正常的缓存机制，该机制存储数据并提前返回该数据而不是重新获取，或者是否应使用 staleWhileRevalidate 机制，该机制返回缓存的数据并在后台重新获取。
key - 用于在缓存中存储数据的键。默认为当前路由路径，包括搜索参数和哈希值。（例如，/user/1?name=John#profile）
adapter - 用于存储数据的缓存适配器。默认为库附带的内存适配器。

import { json, type LoaderFunctionArgs } from "@remix-run/node";
import { ClientLoaderFunctionArgs } from "@remix-run/react"; 
import { cacheClientLoader, useCachedLoaderData } from "remix-client-cache";

export const loader = async ({ params }: LoaderFunctionArgs) => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/users/${params.user}`
  );
  const user = await response.json();
  await new Promise((resolve) => setTimeout(resolve, 1000));
  return json({ user: { ...user, description: Math.random() } });
};

export const clientLoader = (args: ClientLoaderFunctionArgs) => cacheClientLoader(args, {
  type: "swr", // default is swr, can also be set to normal
  key: "/user/1" // default is the current route path including search params and hashes
  adapter: () => localStorage // default is the in memory adapter, can be anything your wish
});
clientLoader.hydrate = true;

decacheClientLoader

用于删除使用 clientLoader 导出从加载器管道传输到您的组件的数据。

import { json, type LoaderFunctionArgs } from "@remix-run/node";
import { ClientLoaderFunctionArgs } from "@remix-run/react"; 
import { decacheClientLoader, useCachedLoaderData } from "remix-client-cache";

export const loader = async ({ params }: LoaderFunctionArgs) => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/users/${params.user}`
  );
  const user = await response.json();
  await new Promise((resolve) => setTimeout(resolve, 1000));
  return json({ user: { ...user, description: Math.random() } });
};
// The data is cached here
export const clientLoader = (args: ClientLoaderFunctionArgs) => cacheClientLoader;
clientLoader.hydrate = true;
// It is de-cached after a successful action submission via the clientAction export
export const clientAction = decacheClientLoader;

接受具有以下属性的可选对象

key - 用于在缓存中存储数据的键。
adapter - 用于存储数据的缓存适配器。

useCachedLoaderData

可用于从 clientLoader 导出获取缓存数据的钩子。必须与 cacheClientLoader 一起使用，因为从 cacheClientLoader 返回的数据被增强以与 useCachedLoaderData 一起使用，而不是标准的 useLoaderData 钩子。

import { useCachedLoaderData } from "remix-client-cache";

// Must be used together with cacheClientLoader
export const clientLoader = (args: ClientLoaderFunctionArgs) => cacheClientLoader(args, "swr");
clientLoader.hydrate = true;

export default function Index() {
  // The data is automatically cached for you and hot swapped when refetched
  const { user } = useCachedLoaderData<typeof loader>(); 

  return (
    <div>
      {user.name} <hr /> {user.email}
      <hr />
      {user.username}
      <hr />
      {user.website} <hr />
      {user.description} 
    </div>
  );
}

接受具有以下属性的可选对象

adapter - 用于存储数据的缓存适配器。默认为库附带的内存适配器。

useSwrData

用于获取热交换数据的 SWR 组件的钩子。它接受一个参数，即由 useCachedLoaderData 或 useLoaderData 钩子返回的 loaderData。

import { useCachedLoaderData, useSwrData } from "remix-client-cache";

export const clientLoader = (args: ClientLoaderFunctionArgs) => cacheClientLoader(args);
clientLoader.hydrate = true;

export default function Index() {
  // We do not destructure the data so we can pass in the object into the useSwrData hook
  const loaderData = useLoaderData<typeof loader>(); 
  // You can also use useCachedLoaderData hook with the useSwrData hook
  const loaderData = useCachedLoaderData<typeof loader>(); 
  // Pass the loader data into the hook and the component will handle everything else for you
  const SWR = useSwrData(loaderData);

  return (
    <SWR>
      {/** Hot swapped automatically */}
      {({ user }) => (
        <div>
          {data.name} <hr /> {data.email}
          <hr />
          {data.username}
          <hr />
          {data.website} <hr />
          {data.description} 
        </div>
      )}
    </SWR>
  );
}

invalidateCache

可用于使特定键的缓存失效的实用程序函数。它接受一个参数，即用于在缓存中存储数据的 key。也可以是键的数组

import { invalidateCache } from "remix-client-cache";

invalidateCache("/user/1"); // invalidates the cache for the /user/1 route

请记住，这只能在客户端上使用，因此只能在 clientLoader 或 clientAction 导出或组件本身中使用。

useCacheInvalidator

返回一个可用于使特定键的缓存失效的函数的钩子。它接受一个参数，即用于在缓存中存储数据的 key。也可以是键的数组

import { useCacheInvalidator } from "remix-client-cache";

export default function Index() {
  const { invalidateCache } = useCacheInvalidator(); 

  return (
    <div>
      // invalidates the cache for the /user/1 route
      <button onClick={ () => invalidateCache("/user/1") }>Invalidate cache</button>
    </div>
  );
}

支持

如果您喜欢这个项目，请考虑在 Github 上给一个 ⭐️ 来支持我们。

许可证

MIT

错误

如果您发现错误，请在我们在 GitHub 上的问题跟踪器上提交一个问题

贡献

感谢您考虑为 remix-client-cache 做出贡献！我们欢迎任何贡献，无论大小，包括错误报告、功能请求、文档改进或代码更改。

首先，请 fork 此存储库并在新分支中进行更改。准备好提交更改后，请打开一个 pull request，其中清楚地描述您的更改以及任何相关问题或 pull request。

请注意，所有贡献都受我们的行为准则约束。通过参与，您将被要求遵守此准则。

我们感谢您为 remix-client-cache 做出贡献并帮助它成为社区更好工具的时间和精力！