Publish version 0.1.0 to NPM

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..a841acb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,86 @@
+# Build Cache wrapper for minifying HTML files
+
+An NDCODE project.
+
+## Overview
+
+The `min_html_cache` package exports a single constructor
+  `MinHTMLCache(diag)`
+which must be called with the `new` operator. The resulting cache object stores
+the `utf-8`-encoded text of HTML files loaded from disk and minified.
+
+See the `build_cache`, `disk_build`, and `html-minifier` packages for more
+information. The `MinHTMLCache` object is essentially a wrapper object which
+routes the request between these packages, to ensure that the minified HTML
+text is either retrieved from RAM or minified from a source file as required.
+
+## Calling API
+
+Suppose one has a `MinHTMLCache` instance named `mhc`. It behaves somewhat like
+an ES6 `Map` object, except that it only has the `mhc.get()` function, because
+new objects are added to the cache by attempting to `get` them.
+
+The interface for the `MinHTMLCache`-provided instance function `mhc.get()` is:
+
+`await mhc.get(key)` — retrieves the object stored under `key`, where
+`key` is the on-disk pathname to a HTML file. A `Buffer` object is returned,
+containing the `utf-8`-encoded text resulting from running `html-minifier` 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
+HTML 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_html_cache` is in NDCODE org-scope, as in `@ndcode/min_html_cache`. We
+also have in NDCODE org-scope, some lightly modified versions of popular
+packages such as `html-minifier`, with added NDCODE hooks. Packages such as
+this one, which simply use `html-minifier` in a standard way without using the
+NDCODE hooks, still depend on `@ndcode/html-minifier` 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 `html-minifier` package is called with standard NDCODE options. This is
+part of the reason to have `min_html_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_html_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>

diff --git a/package.json b/package.json
index 822bfe5..3c3caad 100644 (file)
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@ndcode/min_html_cache",
   "version": "0.1.0",
-  "description": "HTML minimizer, caching front-end with live recompilation.",
+  "description": "HTML minimizer, caching front-end with live recompilation",
   "keywords": [
     "Less",
     "HTML",