-
Notifications
You must be signed in to change notification settings - Fork 2
/
index.html
266 lines (260 loc) · 14.1 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
<!doctype html>
<html class="default no-js">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>quicache</title>
<meta name="description" content="Documentation for quicache">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="assets/css/main.css">
</head>
<body>
<header>
<div class="tsd-page-toolbar">
<div class="container">
<div class="table-wrap">
<div class="table-cell" id="tsd-search" data-index="assets/js/search.json" data-base=".">
<div class="field">
<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
<input id="tsd-search-field" type="text" />
</div>
<ul class="results">
<li class="state loading">Preparing search index...</li>
<li class="state failure">The search index is not available</li>
</ul>
<a href="index.html" class="title">quicache</a>
</div>
<div class="table-cell" id="tsd-widgets">
<div id="tsd-filter">
<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
<div class="tsd-filter-group">
<div class="tsd-select" id="tsd-filter-visibility">
<span class="tsd-select-label">All</span>
<ul class="tsd-select-list">
<li data-value="public">Public</li>
<li data-value="protected">Public/Protected</li>
<li data-value="private" class="selected">All</li>
</ul>
</div>
<input type="checkbox" id="tsd-filter-inherited" checked />
<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
<input type="checkbox" id="tsd-filter-externals" checked />
<label class="tsd-widget" for="tsd-filter-externals">Externals</label>
<input type="checkbox" id="tsd-filter-only-exported" />
<label class="tsd-widget" for="tsd-filter-only-exported">Only exported</label>
</div>
</div>
<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
</div>
</div>
</div>
</div>
<div class="tsd-page-title">
<div class="container">
<ul class="tsd-breadcrumb">
<li>
<a href="globals.html">Globals</a>
</li>
</ul>
<h1>quicache</h1>
</div>
</div>
</header>
<div class="container container-main">
<div class="row">
<div class="col-8 col-content">
<div class="tsd-panel tsd-typography">
<a href="#quicache" id="quicache" style="color: inherit; text-decoration: none;">
<h1>quiCache</h1>
</a>
<blockquote>
<p>An in-memory key-value cache for Javascript and Typescript applications</p>
</blockquote>
<a href="#install" id="install" style="color: inherit; text-decoration: none;">
<h2>Install</h2>
</a>
<p><strong>Yarn</strong></p>
<p><code>yarn add quiCache</code></p>
<p><strong>NPM</strong></p>
<p><code>npm i --save quiCache</code></p>
<a href="#introduction" id="introduction" style="color: inherit; text-decoration: none;">
<h2>Introduction</h2>
</a>
<p>QuiCache is an in-memory caching solution for Javascript and Typescript applications. It relies only on the <code>date-fns</code> package, meaning that it should be compatible with every major JS environment out there.</p>
<p>QuiCache provides a key-value structure for data to be stored in. When adding data to the cache, you specify the key, and the data as arguments to <code>setCacheData()</code>, and quiCache handles everything else. When reading data from the cache, simply provide the key to <code>getCacheData()</code>.</p>
<a href="#api--documentation" id="api--documentation" style="color: inherit; text-decoration: none;">
<h2>API / Documentation</h2>
</a>
<p>See the <a href="./docs/index.html">docs folder</a> for full details.
Usage examples can be found at the bottom of the readme.</p>
<a href="#version-30" id="version-30" style="color: inherit; text-decoration: none;">
<h4>Version 3.0</h4>
</a>
<p>Version 3 now provides support for Typescript generics.</p>
<p>This means that <code>data</code> returned from the following methods will infer type data:</p>
<ul>
<li><code>onCacheDataAdd</code></li>
<li><code>onCacheDataAccessed</code></li>
<li><code>onCacheDataDelete</code></li>
<li><code>onCacheDataExpired</code></li>
<li><code>onCacheDataAlreadyExists</code></li>
<li><code>getCacheData</code></li>
<li><code>setCacheData</code></li>
<li><code>getAllCachedData</code></li>
<li><code>deleteCacheData</code></li>
</ul>
<p>Due to this, when creating a cache instance with <code>new QuiCache()</code>, you must also define the data type you're returning if you're fully typing it:</p>
<pre><code>interface <span class="hljs-class">IMyDataInterface </span>{
<span class="hljs-symbol"> aString:</span> string;
<span class="hljs-symbol"> aNumber:</span> number;
<span class="hljs-symbol"> aBoolean:</span> boolean;
}
const MyCache: ICacheManager<span class="hljs-params"><IMyDataInterface></span> = new QuiCache({
<span class="hljs-symbol"> cacheName:</span> <span class="hljs-string">"MyCache"</span>,
<span class="hljs-symbol"> cacheMaxAgeInSeconds:</span> <span class="hljs-number">30</span>
});</code></pre><p>You can still create and manage your cache in the same way if you're not specifying the type <code>ICacheManager</code>, but type data may not be returned.</p>
<p>This change doesn't prevent your ability to store data of <code>any</code> type in an individual cache field, but merely enhances the developer experience if you use 1 cache for data which follows a specific interface.</p>
<p>No other changes beyond those in 2.0 are required to be compatible with QuiCache 3.0.</p>
<a href="#version-20" id="version-20" style="color: inherit; text-decoration: none;">
<h4>Version 2.0</h4>
</a>
<p>Version 2 has completely overhauled the library, and is mostly incompatible with prior versions (due to changes to the constructor method and several methods being removed).</p>
<p>The changes made should drastically simplify working with the library and provide a nicer developer experience.</p>
<ul>
<li>A new method, <code>deleteCacheData()</code>, has been added to allow deletion of any cached data by providing it's field name / key</li>
<li>The concept of expired and non-expired data no longer exists - Cache data now automatically deletes when it expires</li>
<li>New optional callbacks in the constructor method have been aded: <code>onCacheDataAdd</code>, <code>onCacheDataDelete</code>, <code>onCacheDataExpired</code>, <code>onCacheDataAlreadyExists</code></li>
<li>Version 2.1.2 has added some new optional callback:<ul>
<li><code>onCacheDataAccessed</code> - this will trigger when a field is accessed in the cache</li>
<li><code>onCacheDataDoesNotAlreadyExist</code> - this will trigger if the specified field is not found in the cache when calling <code>setCacheData</code>, <code>deleteCacheData</code></li>
</ul>
</li>
<li>Enabling and disabling debug has been removed due to addition of callbacks</li>
<li>You can now provide a name to your cache, which can be useful for the callbacks</li>
<li>Methods to allow changing the cache age and name have been added</li>
<li>As of version 2.0.2 map is now used for storing data (instead of an object), meaning it is possible to set keys/fields of any type (instead of just string)<ul>
<li>At this time, only strings and numbers are accepted as keys, but supporting all primitive types is planned for a future release</li>
</ul>
</li>
</ul>
<a href="#further-notes-on-version-20" id="further-notes-on-version-20" style="color: inherit; text-decoration: none;">
<h4>Further notes on version 2.0</h4>
</a>
<ul>
<li>The constructor now expects an object with params/arguments</li>
<li>You can only specify a cache maximum age value in seconds (e.g. 120 = 2 minutes), and it is no longer possible to specify the unit of time</li>
<li>If a key already exists in the cache, it's data will <strong>not</strong> be overwritten when calling <code>setCacheData()</code></li>
<li>It is possible to update the cache max age after creation by calling <code>setCacheMaxAge()</code> and passing a value<ul>
<li>Values which were added to the cache before this method is called are <strong>not</strong> affected and will be removed at the end of the originally intended expiry time</li>
</ul>
</li>
</ul>
<a href="#interfaces" id="interfaces" style="color: inherit; text-decoration: none;">
<h2>Interfaces</h2>
</a>
<p>The following interfaces and enums are exported from quicache to assist in development;</p>
<pre><code><span class="hljs-attribute">ICacheManagerDataCache
ICacheManager</span></code></pre>
<a href="#example" id="example" style="color: inherit; text-decoration: none;">
<h2>Example</h2>
</a>
<pre><code class="language-typescript"><span class="hljs-keyword">import</span> quicache, { ICacheManager } <span class="hljs-keyword">from</span> <span class="hljs-string">"quicache"</span>;
<span class="hljs-comment">// Create an interface for your data</span>
<span class="hljs-keyword">interface</span> IMyInterface {
aString: <span class="hljs-built_in">string</span>;
aBoolean: <span class="hljs-built_in">boolean</span>;
aNumber: <span class="hljs-built_in">number</span>;
anOptionalString?: <span class="hljs-built_in">string</span>;
}
<span class="hljs-comment">// Initialize the cache with your interface</span>
<span class="hljs-keyword">const</span> myCache: ICacheManager<IMyInterface> = <span class="hljs-keyword">new</span> quicache({
cacheName: <span class="hljs-string">"MyCache"</span>,
cacheMaxAgeInSeconds: <span class="hljs-number">30</span>,
onCacheDataExpired: <span class="hljs-function">(<span class="hljs-params">data</span>) =></span>
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`Field <span class="hljs-subst">${data.field}</span> expired in cache <span class="hljs-subst">${data.cacheName}</span>`</span>),
onCacheDataAdd: <span class="hljs-function">(<span class="hljs-params">data</span>) =></span>
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`Field <span class="hljs-subst">${data.field}</span> added to cache <span class="hljs-subst">${data.cacheName}</span>`</span>),
onCacheDataAlreadyExists: <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
<span class="hljs-built_in">console</span>.log(
<span class="hljs-string">`Field <span class="hljs-subst">${data.field}</span> already exists in cache <span class="hljs-subst">${data.cacheName}</span>, and expires in <span class="hljs-subst">${data.expires}</span> seconds`</span>
);
},
});
<span class="hljs-keyword">const</span> cacheKey = <span class="hljs-string">"testData"</span>;
<span class="hljs-comment">// If the data doesn't exist in the cache, we'll create it</span>
<span class="hljs-keyword">if</span> (!myCache.cacheDataExists(cacheKey)) {
<span class="hljs-keyword">try</span> {
<span class="hljs-keyword">const</span> dataToSetInCache = {
aString: <span class="hljs-string">"ABC"</span>,
aBoolean: <span class="hljs-literal">true</span>,
aNumber: <span class="hljs-number">123</span>,
};
<span class="hljs-comment">// setCacheData returns the timestamp and data that it inserts into the cache</span>
<span class="hljs-keyword">return</span> myCache.setCacheData(cacheKey, dataToSetInCache).data;
} <span class="hljs-keyword">catch</span> (err) {
<span class="hljs-keyword">return</span> err;
}
} <span class="hljs-keyword">else</span> {
<span class="hljs-comment">// Data exists in cache, so we'll return it</span>
<span class="hljs-comment">// getCacheData returns the timestamp and data</span>
<span class="hljs-keyword">const</span> cachedata = myCache.getCacheData(cacheKey);
<span class="hljs-keyword">return</span> cachedata.data;
}</code></pre>
<a href="#authors" id="authors" style="color: inherit; text-decoration: none;">
<h2>Author(s)</h2>
</a>
<p>👤 <strong>Scott Pritchard (<a href="https://github.com/ChronSyn">Github</a>, <a href="https://twitter.com/ChronSyn">Twitter</a>)</strong></p>
</div>
</div>
<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
<nav class="tsd-navigation primary">
<ul>
<li class="globals ">
<a href="globals.html"><em>Globals</em></a>
</li>
<li class=" tsd-kind-module">
<a href="modules/_src_index_.html">"src/index"</a>
</li>
<li class=" tsd-kind-module">
<a href="modules/_src_quicache_lib_.html">"src/quicache.lib"</a>
</li>
<li class=" tsd-kind-module">
<a href="modules/_src_quicache_lib_spec_.html">"src/quicache.lib.spec"</a>
</li>
</ul>
</nav>
<nav class="tsd-navigation secondary menu-sticky">
<ul class="before-current">
</ul>
</nav>
</div>
</div>
</div>
<footer class="with-border-bottom">
<div class="container">
<h2>Legend</h2>
<div class="tsd-legend-group">
<ul class="tsd-legend">
<li class="tsd-kind-object-literal"><span class="tsd-kind-icon">Object literal</span></li>
<li class="tsd-kind-variable"><span class="tsd-kind-icon">Variable</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-interface"><span class="tsd-kind-icon">Interface</span></li>
<li class="tsd-kind-interface tsd-has-type-parameter"><span class="tsd-kind-icon">Interface with type parameter</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-enum"><span class="tsd-kind-icon">Enumeration</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-class tsd-has-type-parameter"><span class="tsd-kind-icon">Class with type parameter</span></li>
</ul>
</div>
</div>
</footer>
<div class="container tsd-generator">
<p>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p>
</div>
<div class="overlay"></div>
<script src="assets/js/main.js"></script>
</body>
</html>