Change from pnpm to npm, add ./link.sh shortcut for npm style package linking
[zip_cache.git] / README.md
1 # Build Cache wrapper for zipfiles
2
3 An NDCODE project.
4
5 ## Overview
6
7 The `zip_cache` package exports a single constructor
8   `ZipCache(diag)`
9 which must be called with the `new` operator. The resulting cache object stores
10 the decompressed contents of zipfiles loaded from disk.
11
12 See the `build_cache` and `yauzl` packages for more information. The `ZipCache`
13 object is essentially a wrapper object which routes the request between the
14 `build_cache` package and the streaming `yauzl` zipfile-reading API, to ensure
15 that the zipfile contents are retrieved from either RAM or disk as required.
16
17 ## Calling API
18
19 Suppose one has a `ZipCache` instance named `zc`. It behaves somewhat like an
20 ES6 `Map` object, except that it only has the `zc.get()` function, because new
21 objects are added to the cache by attempting to `get` them.
22
23 The interface for the `ZipCache`-provided instance function `zc.get()` is:
24
25 `await zc.get(key)` — retrieves the object stored under `key`, where
26 `key` is the on-disk pathname to a zipfile. A dictionary mapping `String` to
27 `Buffer` objects is returned, where the `String` is the absolute pathname of a
28 file within the zipfile (always beginning with `/`), and the `Buffer` is the
29 binary contents of the file. This dictionary is then cached for future use.
30
31 Before returning the cached dictionary, the existence and modification time of
32 the zipfile on disk is checked to make sure that the cache is up-to-date.
33 Otherwise, if the file doesn't exist an `ENOENT` exception is thrown, or if the
34 file exists it is scanned and decompressed and the cache updated for next time.
35
36 ## About diagnostics
37
38 The `diag` argument to the constructor is a `bool`, which if `true` causes
39 messages to be printed via `console.log()` for all activities except for the
40 common case of retrieval when the object is already up-to-date. A `diag` value
41 of `undefined` is treated as `false`, thus it can be omitted in the usual case.
42
43 ## To be implemented
44
45 It is intended that we will shortly add a timer function (or possibly just a
46 function that the user should call periodically) to flush built templates from
47 the cache after a stale time. There is otherwise no way to delete an object
48 from the cache, except by first deleting it on disk, then trying to `get` it.
49
50 ## GIT repository
51
52 The development version can be cloned, downloaded, or browsed with `gitweb` at:
53 https://git.ndcode.org/public/zip_cache.git
54
55 ## License
56
57 All of our NPM packages are MIT licensed, please see LICENSE in the repository.
58
59 ## Contributions
60
61 The caching system is under active development (and is part of a larger project
62 that is also under development) and thus the API is tentative. Please go ahead
63 and incorporate the system into your project, or try out our example webserver
64 built on the system, subject to the caution that the API could change. Please
65 send us your experience and feedback, and let us know of improvements you make.
66
67 Contact: Nick Downing <nick@ndcode.org>