npm package: @ndcode/min_css_cache
Description: CSS minimizer, caching front-end with live recompilation
Latest version: 0.1.0

# Build Cache wrapper for minifying CSS files

An NDCODE project.

## Overview

The `min_css_cache` package exports a single constructor
  `MinCSSCache(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 `clean-css` packages for more
information. The `MinCSSCache` 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 `MinCSSCache` instance named `mcc`. It behaves somewhat like
an ES6 `Map` object, except that it only has the `mcc.get()` function, because
new objects are added to the cache by attempting to `get` them.

The interface for the `MinCSSCache`-provided instance function `mcc.get()` is:

`await mcc.get(key)` &mdash; 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 time of the
CSS file on disk is checked to make sure that the cache is up-to-date.
Otherwise, if the file doesn't exist an `ENOENT` exception is thrown, or if the
file exists it is loaded and minified and the cache updated for next time. The
minification is via disk, and skipped if an up-to-date disk result is present.

## About dependencies

The `min_css_cache` is in NDCODE org-scope, as in `@ndcode/min_css_cache`. We
also have in NDCODE org-scope, some lightly modified versions of popular
packages such as `clean-css`, with added NDCODE hooks. Packages such as this
one, which simply use `clean-css` in a standard way without using the NDCODE
hooks, still depend on `@ndcode/clean-css` for consistency. This means that
when embedded in an NDCODE project, only one copy of each dependency is loaded.
If this isn't desired, please feel free to fork the package and adjust it.

## 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 `clean-css` package is called with standard NDCODE options. This is part of
the reason to have `min_css_cache`, so as to provide a consistent interface to
minifiers for JavaScript, CSS, SVG and so on. However, if some control of the
underlying minifier 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/min_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>