README.md

   1 # Build Cache wrapper for minifying CSS files
   2
   3 An NDCODE project.
   4
   5 ## Overview
   6
   7 The `less_css_cache` package exports a single constructor
   8   `LessCSSCache(diag)`
   9 which must be called with the `new` operator. The resulting cache object stores
  10 the `utf-8`-encoded text of CSS files loaded from disk and minified.
  11
  12 See the `build_cache`, `disk_build`, and `less` packages for more information.
  13 The `LessCSSCache` object is essentially a wrapper object which routes the
  14 request between these packages, to ensure that the minified CSS text is either
  15 retrieved from RAM or minified from a source file as required.
  16
  17 ## Calling API
  18
  19 Suppose one has a `LessCSSCache` instance named `lcc`. It behaves somewhat like
  20 an ES6 `Map` object, except that it only has the `lcc.get()` function, because
  21 new objects are added to the cache by attempting to `get` them.
  22
  23 The interface for the `LessCSSCache`-provided instance function `lcc.get()` is:
  24
  25 `await lcc.get(key)` &mdash; retrieves the object stored under `key`, where
  26 `key` is the on-disk pathname to a CSS file. A `Buffer` object is returned,
  27 containing the `utf-8`-encoded text resulting from running `clean-css` on the
  28 source file. The pathname and the returned result are cached for future reuse.
  29
  30 Before returning the cached copy, the existence and modification times of the
  31 main CSS file _and all dependents_ on disk are checked to make sure that the
  32 cache is up-to-date. The dependencies are discovered the first time the main
  33 file is compiled, and saved in a separate (hidden) dependency file, alongside
  34 the (hidden) output file. If the main CSS file doesn't exist or it includes a
  35 source file that doesn't exist (possibly a source file whose deletion triggered
  36 recompilation), an `ENOENT` exception is thrown, or if the file and all current
  37 dependencies exist with valid syntax, they are compiled and the cache updated.
  38 If the file is not in cache but the disk output is up-to-date, it is reloaded.
  39
  40 ## About diagnostics
  41
  42 The `diag` argument to the constructor is a `bool`, which if `true` causes
  43 messages to be printed via `console.log()` for all activities except for the
  44 common case of retrieval when the object is already up-to-date. A `diag` value
  45 of `undefined` is treated as `false`, thus it can be omitted in the usual case.
  46
  47 ## To be implemented
  48
  49 The `less` package is called with standard NDCODE options. This is part of the
  50 reason to have `less_css_cache`, so as to provide a consistent interface to
  51 minifiers or compilers for Javascript, CSS, SVG, etc. However, if some control
  52 of the underlying compiler is needed in future, we could add an `options`
  53 object to pass through, in which we'd inject our NDCODE options where not
  54 overridden.
  55
  56 It is intended that we will shortly add a timer function (or possibly just a
  57 function that the user should call periodically) to flush built templates from
  58 the cache after a stale time. There is otherwise no way to delete an object
  59 from the cache, except by first deleting it on disk, then trying to `get` it.
  60
  61 ## GIT repository
  62
  63 The development version can be cloned, downloaded, or browsed with `gitweb` at:
  64 https://git.ndcode.org/public/less_css_cache.git
  65
  66 ## License
  67
  68 All of our NPM packages are MIT licensed, please see LICENSE in the repository.
  69
  70 ## Contributions
  71
  72 The caching system is under active development (and is part of a larger project
  73 that is also under development) and thus the API is tentative. Please go ahead
  74 and incorporate the system into your project, or try out our example webserver
  75 built on the system, subject to the caution that the API could change. Please
  76 send us your experience and feedback, and let us know of improvements you make.
  77
  78 Contact: Nick Downing <nick@ndcode.org>