--- /dev/null
+# Build Cache wrapper for minifying CSS files
+
+An NDCODE project.
+
+## Overview
+
+The `less_css_cache` package exports a single constructor
+ `LessCSSCache(diag)`
+which must be called with the `new` operator. The resulting cache object stores
+the `utf-8`-encoded text of CSS files loaded from disk and minified.
+
+See the `build_cache`, `disk_build`, and `less` packages for more information.
+The `LessCSSCache` object is essentially a wrapper object which routes the
+request between these packages, to ensure that the minified CSS text is either
+retrieved from RAM or minified from a source file as required.
+
+## Calling API
+
+Suppose one has a `LessCSSCache` instance named `lcc`. It behaves somewhat like
+an ES6 `Map` object, except that it only has the `lcc.get()` function, because
+new objects are added to the cache by attempting to `get` them.
+
+The interface for the `LessCSSCache`-provided instance function `lcc.get()` is:
+
+`await lcc.get(key)` — retrieves the object stored under `key`, where
+`key` is the on-disk pathname to a CSS file. A `Buffer` object is returned,
+containing the `utf-8`-encoded text resulting from running `clean-css` on the
+source file. The pathname and the returned result are cached for future reuse.
+
+Before returning the cached copy, the existence and modification times of the
+main CSS file _and all dependents_ on disk are checked to make sure that the
+cache is up-to-date. The dependencies are discovered the first time the main
+file is compiled, and saved in a separate (hidden) dependency file, alongside
+the (hidden) output file. If the main CSS file doesn't exist or it includes a
+source file that doesn't exist (possibly a source file whose deletion triggered
+recompilation), an `ENOENT` exception is thrown, or if the file and all current
+dependencies exist with valid syntax, they are compiled and the cache updated.
+If the file is not in cache but the disk output is up-to-date, it is reloaded.
+
+## About diagnostics
+
+The `diag` argument to the constructor is a `bool`, which if `true` causes
+messages to be printed via `console.log()` for all activities except for the
+common case of retrieval when the object is already up-to-date. A `diag` value
+of `undefined` is treated as `false`, thus it can be omitted in the usual case.
+
+## To be implemented
+
+The `less` package is called with standard NDCODE options. This is part of the
+reason to have `less_css_cache`, so as to provide a consistent interface to
+minifiers or compilers for Javascript, CSS, SVG, etc. However, if some control
+of the underlying compiler is needed in future, we could add an `options`
+object to pass through, in which we'd inject our NDCODE options where not
+overridden.
+
+It is intended that we will shortly add a timer function (or possibly just a
+function that the user should call periodically) to flush built templates from
+the cache after a stale time. There is otherwise no way to delete an object
+from the cache, except by first deleting it on disk, then trying to `get` it.
+
+## GIT repository
+
+The development version can be cloned, downloaded, or browsed with `gitweb` at:
+https://git.ndcode.org/public/less_css_cache.git
+
+## License
+
+All of our NPM packages are MIT licensed, please see LICENSE in the repository.
+
+## Contributions
+
+The caching system is under active development (and is part of a larger project
+that is also under development) and thus the API is tentative. Please go ahead
+and incorporate the system into your project, or try out our example webserver
+built on the system, subject to the caution that the API could change. Please
+send us your experience and feedback, and let us know of improvements you make.
+
+Contact: Nick Downing <nick@ndcode.org>
public / less_css_cache.git / commitdiff