0
# swrv
1

2
swrv (pronounced "swerve") is a library using the Vue Composition API for remote data fetching with stale-while-revalidate caching strategy. It enables developers to create fast, reactive UIs by returning cached data immediately while simultaneously fetching fresh data in the background.
3

4
## Package Information
5

6
- **Package Name**: swrv
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install swrv`
10
- **Vue Compatibility**: Vue 3.x, Vue 2.7+
11

12
## Core Imports
13

14
```typescript
15
import useSWRV, { mutate, SWRVCache, IConfig } from "swrv";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const useSWRV = require("swrv");
22
const { mutate, SWRVCache } = require("swrv");
23
```
24

25
## Basic Usage
26

27
```typescript
28
import useSWRV from "swrv";
29

30
export default {
31
  setup() {
32
    const { data, error, isValidating, mutate } = useSWRV('/api/user', fetch);
33

34
    return {
35
      data,
36
      error,
37
      isValidating,
38
      mutate
39
    };
40
  }
41
};
42
```
43

44
## Architecture
45

46
swrv is built around several key components:
47

48
- **Core Hook**: `useSWRV` composable that provides reactive data fetching with automatic caching
49
- **Global Cache**: Shared cache instances that deduplicate requests and store responses
50
- **Request Deduplication**: Automatic deduplication of identical requests within configurable time windows
51
- **Revalidation System**: Automatic background revalidation triggered by focus, intervals, or manual calls
52
- **Error Handling**: Built-in retry logic with exponential backoff and error boundaries
53
- **Cache Adapters**: Pluggable cache implementations including memory and localStorage options
54

55
## Capabilities
56

57
### Data Fetching Hook
58

59
Core composable for reactive data fetching with automatic caching, revalidation, and error handling.
60

61
```typescript { .api }
62
function useSWRV<Data = any, Error = any>(
63
  key: IKey
64
): IResponse<Data, Error>;
65

66
function useSWRV<Data = any, Error = any>(
67
  key: IKey,
68
  fn: fetcherFn<Data> | undefined | null,
69
  config?: IConfig
70
): IResponse<Data, Error>;
71
```
72

73
[Data Fetching](./data-fetching.md)
74

75
### Global State Management
76

77
Global mutation function and cache management for coordinating data updates across components.
78

79
```typescript { .api }
80
function mutate<Data>(
81
  key: string,
82
  res: Promise<Data> | Data,
83
  cache?: SWRVCache<any>,
84
  ttl?: number
85
): Promise<{data: Data, error: any, isValidating: boolean}>;
86
```
87

88
[Global State Management](./global-state.md)
89

90
### Cache System
91

92
Configurable cache implementations for storing fetched data with TTL support and automatic expiration.
93

94
```typescript { .api }
95
class SWRVCache<CacheData> {
96
  constructor(ttl?: number);
97
  get(k: string): ICacheItem<CacheData>;
98
  set(k: string, v: any, ttl: number): void;
99
  delete(serializedKey: string): void;
100
  serializeKey(key: IKey): string;
101
}
102
```
103

104
[Cache System](./cache-system.md)
105

106
## Core Types
107

108
```typescript { .api }
109
type IKey = keyType | WatchSource<keyType>;
110
type keyType = string | any[] | null | undefined;
111
type fetcherFn<Data> = (...args: any) => Data | Promise<Data>;
112

113
interface IResponse<Data = any, Error = any> {
114
  data: Ref<Data | undefined>;
115
  error: Ref<Error | undefined>;
116
  isValidating: Ref<boolean>;
117
  isLoading: Ref<boolean>;
118
  mutate: (data?: fetcherFn<Data>, opts?: revalidateOptions) => Promise<void>;
119
}
120

121
interface IConfig<Data = any, Fn extends fetcherFn<Data> = fetcherFn<Data>> {
122
  refreshInterval?: number;
123
  cache?: LocalStorageCache | SWRVCache<any>;
124
  dedupingInterval?: number;
125
  ttl?: number;
126
  serverTTL?: number;
127
  revalidateOnFocus?: boolean;
128
  revalidateDebounce?: number;
129
  shouldRetryOnError?: boolean;
130
  errorRetryInterval?: number;
131
  errorRetryCount?: number;
132
  fetcher?: Fn;
133
  isOnline?: () => boolean;
134
  isDocumentVisible?: () => boolean;
135
}
136

137
interface revalidateOptions {
138
  shouldRetryOnError?: boolean;
139
  errorRetryCount?: number;
140
  forceRevalidate?: boolean;
141
}
142

143
interface ICacheItem<Data> {
144
  data: Data;
145
  createdAt: number;
146
  expiresAt: number;
147
}
148
```