README.md

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