README.md

   1 # Build Cache wrapper for minifying HTML files
   2
   3 An NDCODE project.
   4
   5 ## Overview
   6
   7 The `min_html_cache` package exports a single constructor
   8   `MinHTMLCache(diag)`
   9 which must be called with the `new` operator. The resulting cache object stores
  10 the `utf-8`-encoded text of HTML files loaded from disk and minified.
  11
  12 See the `build_cache`, `disk_build`, and `html-minifier` packages for more
  13 information. The `MinHTMLCache` object is essentially a wrapper object which
  14 routes the request between these packages, to ensure that the minified HTML
  15 text is either retrieved from RAM or minified from a source file as required.
  16
  17 ## Calling API
  18
  19 Suppose one has a `MinHTMLCache` instance named `mhc`. It behaves somewhat like
  20 an ES6 `Map` object, except that it only has the `mhc.get()` function, because
  21 new objects are added to the cache by attempting to `get` them.
  22
  23 The interface for the `MinHTMLCache`-provided instance function `mhc.get()` is:
  24
  25 `await mhc.get(key)` &mdash; retrieves the object stored under `key`, where
  26 `key` is the on-disk pathname to a HTML file. A `Buffer` object is returned,
  27 containing the `utf-8`-encoded text resulting from running `html-minifier` on
  28 the source file. The pathname and the returned result are cached for future
  29 reuse.
  30
  31 Before returning the cached copy, the existence and modification time of the
  32 HTML file 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 loaded and minified and the cache updated for next time. The
  35 minification is via disk, and skipped if an up-to-date disk result is present.
  36
  37 ## About dependencies
  38
  39 The `min_html_cache` is in NDCODE org-scope, as in `@ndcode/min_html_cache`. We
  40 also have in NDCODE org-scope, some lightly modified versions of popular
  41 packages such as `html-minifier`, with added NDCODE hooks. Packages such as
  42 this one, which simply use `html-minifier` in a standard way without using the
  43 NDCODE hooks, still depend on `@ndcode/html-minifier` for consistency. This
  44 means that when embedded in an NDCODE project, only one copy of each dependency
  45 is loaded. If this isn't desired, please feel free to fork the package and
  46 adjust it.
  47
  48 ## About diagnostics
  49
  50 The `diag` argument to the constructor is a `bool`, which if `true` causes
  51 messages to be printed via `console.log()` for all activities except for the
  52 common case of retrieval when the object is already up-to-date. A `diag` value
  53 of `undefined` is treated as `false`, thus it can be omitted in the usual case.
  54
  55 ## To be implemented
  56
  57 The `html-minifier` package is called with standard NDCODE options. This is
  58 part of the reason to have `min_html_cache`, so as to provide a consistent
  59 interface to minifiers for JavaScript, CSS, SVG and so on. However, if some
  60 control of the underlying minifier is needed in future, we could add an
  61 `options` object to pass through, in which we'd inject our NDCODE options where
  62 not overridden.
  63
  64 It is intended that we will shortly add a timer function (or possibly just a
  65 function that the user should call periodically) to flush built templates from
  66 the cache after a stale time. There is otherwise no way to delete an object
  67 from the cache, except by first deleting it on disk, then trying to `get` it.
  68
  69 ## GIT repository
  70
  71 The development version can be cloned, downloaded, or browsed with `gitweb` at:
  72 https://git.ndcode.org/public/min_html_cache.git
  73
  74 ## License
  75
  76 All of our NPM packages are MIT licensed, please see LICENSE in the repository.
  77
  78 ## Contributions
  79
  80 The caching system is under active development (and is part of a larger project
  81 that is also under development) and thus the API is tentative. Please go ahead
  82 and incorporate the system into your project, or try out our example webserver
  83 built on the system, subject to the caution that the API could change. Please
  84 send us your experience and feedback, and let us know of improvements you make.
  85
  86 Contact: Nick Downing <nick@ndcode.org>