README.md

   1 # Build Cache wrapper for minifying JavaScript files
   2
   3 An NDCODE project.
   4
   5 ## Overview
   6
   7 The `min_js_cache` package exports a single constructor
   8   `MinJSCache(diag)`
   9 which must be called with the `new` operator. The resulting cache object stores
  10 the `utf-8`-encoded text of JavaScript files loaded from disk and minified.
  11
  12 See the `build_cache`, `disk_build`, and `uglify-es` packages for more
  13 information. The `MinJSCache` object is essentially a wrapper object which
  14 routes the request between these packages, to ensure that the minified
  15 JavaScript text is either retrieved from RAM or minified from a source file as
  16 required.
  17
  18 ## Calling API
  19
  20 Suppose one has a `MinJSCache` instance named `mjc`. It behaves somewhat like
  21 an ES6 `Map` object, except that it only has the `mjc.get()` function, because
  22 new objects are added to the cache by attempting to `get` them.
  23
  24 The interface for the `MinJSCache`-provided instance function `mjc.get()` is:
  25
  26 `await mjc.get(key)` &mdash; retrieves the object stored under `key`, where
  27 `key` is the on-disk pathname to a JavaScript file. A `Buffer` object is
  28 returned, containing the `utf-8`-encoded text resulting from running
  29 `uglify-es` on the source file. The pathname and the returned result are cached
  30 for future reuse.
  31
  32 Before returning the cached copy, the existence and modification time of the
  33 JavaScript 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 minified and the cache updated for next time. The
  36 minification 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 The `uglify-es` package is called with standard NDCODE options. This is part of
  48 the reason to have `min_js_cache`, so as to provide a consistent interface to
  49 minifiers for JavaScript, CSS, SVG and so on. However, if some control of the
  50 underlying minifier is needed in future, we could add an `options` object to
  51 pass through, in which we'd inject our NDCODE options where not overridden.
  52
  53 It is intended that we will shortly add a timer function (or possibly just a
  54 function that the user should call periodically) to flush built templates from
  55 the cache after a stale time. There is otherwise no way to delete an object
  56 from the cache, except by first deleting it on disk, then trying to `get` it.
  57
  58 ## GIT repository
  59
  60 The development version can be cloned, downloaded, or browsed with `gitweb` at:
  61 https://git.ndcode.org/public/min_js_cache.git
  62
  63 ## License
  64
  65 All of our NPM packages are MIT licensed, please see LICENSE in the repository.
  66
  67 ## Contributions
  68
  69 The caching system is under active development (and is part of a larger project
  70 that is also under development) and thus the API is tentative. Please go ahead
  71 and incorporate the system into your project, or try out our example webserver
  72 built on the system, subject to the caution that the API could change. Please
  73 send us your experience and feedback, and let us know of improvements you make.
  74
  75 Contact: Nick Downing <nick@ndcode.org>