Installations

npm install swr-store

Developer Guide

BETA

Typescript

Yes

Module System

ESM

Min. Node Version

>=10

Node Version

19.6.0

NPM Version

lerna/6.5.1/node@v19.6.0+x64 (win32)

Pull Requests

Open

0

Total

1

Closed

1

Issues

Open

1

Total

3

Closed

2

Releases

2

v0.2.0

Published on 08 Nov 2020

Initial release

v0.1.0

Published on 08 Nov 2020

View all 2 releases

Contributors

1

View all 1 contributors

Languages

2

TypeScript

JavaScript

TypeScript (95.54%)

JavaScript (4.46%)

Developer

lxsmnsyc

Download Statistics

Total Downloads

7,704,452

Last Day

14,609

Last Week

60,617

Last Month

270,041

Last Year

6,304,400

GitHub Statistics

7 Stars

134 Commits

3 Watching

1 Branches

1 Contributors

Bundle Size

5.60 kB

Minified

1.99 kB

Minified + Gzipped

Bundlephobia

Maintainers

1

Package Meta Information

Latest Version

0.10.6

Package Id

swr-store@0.10.6

Unpacked Size

131.51 kB

Size

23.70 kB

File Count

29

NPM Version

lerna/6.5.1/node@v19.6.0+x64 (win32)

Node Version

19.6.0

Publised On

21 Feb 2023

Total Downloads

Cumulative downloads

Total Downloads

7,704,452

Last day

-14.4%

14,609

Compared to previous day

Last week

-8.8%

60,617

Compared to previous week

Last month

28.7%

270,041

Compared to previous month

Last year

351.7%

6,304,400

Compared to previous year

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

1

dequal

Dev Dependencies

6

@types/node eslint eslint-config-lxsmnsyc pridepack tslib typescript

Versions

swr-store

Reactive SWR stores for data-fetching.

Install

1npm install --save swr-store

1yarn add swr-store

Usage

1import { createSWRStore, trigger } from 'swr-store';
2
3const dogAPI = createSWRStore<APIResult, [string]>({
4  // Fetch data based on breed
5  get: async (breed: string) => {
6    const response = await fetch(`${API}${breed}${API_SUFFIX}`);
7    return (await response.json()) as APIResult;
8  },
9  // Allow us to revalidate the data
10  // whenever the page gets focused
11  revalidateOnFocus: true,
12
13  // Revalidate the data when the network goes
14  // back online
15  revalidateOnNetwork: true,
16});
17
18// Will be pending initially.
19// The result will change once dogAPI.get is called again
20// sometime after the fetch has assumed to be resolved.
21const result = dogAPI.get(['shiba']);
22
23if (result.status === 'pending') {
24  displaySkeleton();
25} else if (result.status === 'failure') {
26  displayFallback();
27} else if (result.status === 'success') {
28  displayUI(result.data);
29}
30
31// When click is triggered, we prompt a revalidation process
32document.getElementById('#refresh').addEventListener('click', () => {
33  // We can do local revalidation
34  dogAPI.trigger(['shiba']);
35
36  // Or a global revalidation
37  trigger('shiba');
38});

Features

Key Generation

SWR stores may derive keys based on received arguments. These keys are used to locate cache references. By default, arguments are serialized through JSON.stringify, but can be overriden by providing options.key, where the key function receives the arguments and may return a string.

1const store = createSWRStore({
2  // Only select the key
3  // note that keys are globally shared.
4  key: (id) => id,
5  
6  // An auth-based endpoint
7  get: (id, token) => getUserPrivateData({
8    userId: id,
9    token,
10  }),
11});
12
13// ...
14const privateData = store.get(userId, userToken);

Subscriptions

SWR store allows subscriptions to subscribe for cache updates. Subscribing returns a callback that allows unsubscribing to the cache updates.

1
2// Local subscription
3const unsubscribe = userDetails.subscribe([userId], (result) => {
4  if (result.status === 'pending') {
5    displaySkeleton();
6  } else if (result.status === 'failure') {
7    displayFallback();
8  } else if (result.status === 'success') {
9    displayUI(result.data);
10  }
11});
12
13// global subscription
14import { subscribe } from 'swr-store';
15
16const unsubscribe = subscribe(`/user/${userId}`, (result) => {
17  if (result.status === 'pending') {
18    displaySkeleton();
19  } else if (result.status === 'failure') {
20    displayFallback();
21  } else if (result.status === 'success') {
22    displayUI(result.data);
23  }
24});

Hydration

SWR store may present an initial data through options.initialData. This data is used only when the store finds an empty cache value. Initial data is also useful for opting-out of initial pending phase and providing a way for SSR pages to hydrate stores.

1const userDetails = createSWRStore({
2  get: (id) => getUserDetails(id),
3
4  initialData: prefetchedData,
5});

Stores can also be hydrated manually through mutate.

Calling store.get also allows lazy hydration, in which the provided initial data is preferred rather than options.initialData.

1const result = userDetails.get([userId], {
2  // If there's no cache, prefetched data is used
3  // then attempts revalidation
4  initialData: prefetchedData,
5});

Do note that options.initialData won't hydrate the actual store but present a fallback data when the result is still pending. You can use options.hydrate to overwrite the current cached data.

Lazy Revalidation

SWR stores are lazily revalidated whenever store.get is called.

1// Initial fetch
2const result = store.get([]);
3
4setTimeout(() => {
5  // May contain the resolved result
6  // or a new one if the cache has been invalidated.
7  const newResult = store.get([]);
8});

Revalidation on get may be opt-out by providing shouldRevalidate:

1const result = store.get([], {
2  shouldRevalidate: false,
3});

Global Revalidation

SWR stores share the same global cache, and can be prompted with a global manual revalidation. trigger and mutate are similar to store's store.trigger and store.mutate except that they accept the cache key instead of the store's expected arguments.

Stores subscribers are may be notified (trigger does not guarantee a notification, while mutate guarantees a notification) for the cache update.

1import { trigger, mutate } from 'swr-store';
2
3const userDetails = createSWRStore({
4  // Transform id into a cache key
5  key: (id) => `/user/${id}`,
6  
7  // An auth-based endpoint
8  get: (id) => getUserDetails(id),
9});
10
11// ...
12// Global trigger
13trigger(`/user/${userId}`);
14
15// Or mutate
16mutate(`/user/${userId}`, {
17  data: {
18    name: 'John Doe',
19    age: 16,
20  },
21  status: 'success',
22});

Local Revalidation

SWR stores can be manually revalidated by calling store.trigger or store.mutate.

store.trigger(args, shouldRevalidate = true): Triggers a revalidation from the given arguments. Arguments are passed to options.key to locate the cache.
store.mutate(args, result, shouldRevalidate = true): Mutates the cache with result. Cache is located based on the key generated from the arguments passed to options.key.

1// Local revalidation
2userDetails.trigger([userId]);
3
4// is the same as 
5trigger(`/user/${userId}`);
6
7// Since userDetails yields the same key format.

Auto Revalidation

SWR stores are able to automatically revalidate data based on DOM events. This feature can be activated based on the following options:

options.revalidateOnFocus: Automatically revalidates data when the window 'focus' event is triggered. Defaults to false.
options.revalidateOnVisibility: Automatically revalidates data when the document 'visibilitychange' event is triggered, specifically, if the page is 'visible'. Defaults to false.
options.revalidateOnNetwork: Automatically revalidates data when the window 'online' event is triggered. Defaults to false.

Polling Revalidation

SWR stores are able to poll for revalidation. They are different to event-based revalidation as polling revalidation happens in intervals.

This behavior can be activated through the following options:

options.refreshInterval: Amount of time (in milliseconds) the revalidation goes through in intervals. Defaults to undefined (Does not poll). Polling begins immediately after the lazy setup has been triggered.

The default behavior can be overriden by the following options:

options.refreshWhenHidden: Overrides the default polling behavior and only begins polling after the page becomes hidden (triggered by document visibilitychange event.). Once the document becomes visible, polling halts.
options.refreshWhenBlurred: Overrides the default polling behavior and only begins polling after the page loses focus (triggered by window blur and focus events). Once the page is focused again, polling halts.
options.refreshWhenOffline: Overrides the default polling behavior and only begins polling after the page becomes offline (triggered by window offline and online events). Once the page is focused again, polling halts.

Lazy Setup

SWR stores are lazily setup: polling and automatic revalidation only begins when there are subscribers to the stores. Once a store receives a subscriber (through store.subscribe method), the store lazily sets up the revalidation processes, this way, automatic processes are conserved and are only added when needed.

Stores also halt from automatic revalidation if they lose all subscribers through reference-counting.

Cache Age

SWR stores can define how 'fresh' or 'stale' the cache is, which can alter the revalidation behavior:

If the cache is 'fresh', revalidation phases skips the fetching stage.
If the cache is 'stale', revalidation phases goes through, but the result does not return to 'pending' state.

These behavior can be defined through the following options:

options.freshAge: Defines how long the cache stays 'fresh', in milliseconds. Defaults to 2000. (2 seconds).
options.staleAge: Defines how long the cache stays 'stale' after becoming 'fresh', in milliseconds. Defaults to 30000 (30 seconds).

A cache is 'fresh' when the time between the cache was updated and was read is between the options.freshAge value, otherwise, the cache automatically becomes 'stale'. A cache that has been 'stale' will continue being 'stale' until the time between the cache became 'stale' and was read is between the options.staleAge.

Cache invalidation always happen lazily: checking for cache age only happens when the revalidation process is requested upon (usually automatically through polling or revalidation on events) or manually (mutate or trigger).

Deduplication

SWR Stores throttles data fetching processes through the caching strategy. Cache maintain a timestamp internally, marking valid requests and cache references, establishing race conditions.

CSR-Only Revalidation and Fetching

SWR stores' cache revalidation and data-fetching only happens on client-side.

Success Bailouts

SWR stores, by default, deeply compare success data in between cache updates. This behavior prevents re-notifying subscribers when the contents of the data remains the same. This behavior can be overriden by providing a compare function in options.compare.

mutate accepts an custom compare function to override this behavior as a fourth parameter.

Retries

SWR stores implements the exponential backoff algorithm for retry intervals whenever a request fails. By default, SWR stores retry indefinitely until the request resolves successfully at a maximum interval of 5000ms. Limit can be defined through options.maxRetryCount and the interval can be overriden with options.maxRetryInterval.

License

MIT © lxsmnsyc

No vulnerabilities found.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

License

Determines if the project has defined a license.

0

Maintained

Determines if the project is "actively maintained".

0

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

0

SAST

Determines if the project uses static code analysis.

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Fuzzing

Determines if the project uses fuzzing.

0

Branch-Protection

Determines if the default and release branches are protected with GitHub's branch protection settings.

0

Security-Policy

Determines if the project has published a security policy.

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Score

1.7

/10

Last Scanned on 2025-01-27

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More

Other packages similar to swr-store

swr-store

Installations

Developer Guide

Yes

ESM

>=10

19.6.0

lerna/6.5.1/node@v19.6.0+x64 (win32)

Pull Requests

0

1

1

Issues

1

3

2

Releases

Contributors

Languages

Developer

lxsmnsyc

Download Statistics

GitHub Statistics

Bundle Size

5.60 kB

1.99 kB

Maintainers

Package Meta Information

Total Downloads

7,704,452

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

Dev Dependencies

swr-store

Install

Usage

Features

Key Generation

Subscriptions

Hydration

Lazy Revalidation

Global Revalidation

Local Revalidation

Auto Revalidation

Polling Revalidation

Lazy Setup

Cache Age

Deduplication

CSR-Only Revalidation and Fetching

Success Bailouts

Retries

License

10

10

0

0

0

0

0

0

0

0

1.7

/10