README.md

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