--- /dev/null
+/ndcode-menu_cache-*.tgz
+/node_modules
+/pnpm-lock.yaml
--- /dev/null
+Copyright (C) 2018 Nick Downing <nick@ndcode.org>
+SPDX-License-Identifier: MIT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
--- /dev/null
+/*
+ * Copyright (C) 2021 Nick Downing <nick@ndcode.org>
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+let BuildCache = require('@ndcode/build_cache')
+let assert = require('assert')
+let disk_build = require('@ndcode/disk_build')
+let fs = require('fs')
+let util = require('util')
+
+let fs_readFile = util.promisify(fs.readFile)
+let fs_writeFile = util.promisify(fs.writeFile)
+
+let MenuCache = function(diag1, diag) {
+ if (!this instanceof MenuCache)
+ throw new Error('MenuCache is a constructor')
+ BuildCache.call(this, diag)
+ this.diag1 = diag1
+}
+
+MenuCache.prototype = Object.create(BuildCache.prototype)
+
+MenuCache.prototype.build = async function(key, result) {
+ let render = await disk_build(
+ key,
+ async temp_pathname => {
+ let text = await fs_readFile(key, {encoding: 'utf-8'})
+ if (this.diag1)
+ console.log(`loaded json file ${key}`)
+ menu = JSON.parse(text)
+ entries = menu.entries
+ index = {}
+ for (let i = 0; i < entries.length; ++i)
+ index[entries[i].dir] = i
+ menu.index = index
+ return /*await*/ fs_writeFile(
+ temp_pathname,
+ JSON.stringify(menu) + '\n',
+ {encoding: 'utf-8'}
+ )
+ },
+ this.diag1
+ )
+ assert(render.deps.length === 0)
+ let text = await fs_readFile(render.pathname, {encoding: 'utf-8'})
+ if (this.diag1)
+ console.log(`loaded json file ${render.pathname}`)
+ result.value = JSON.parse(text)
+}
+
+module.exports = MenuCache
--- /dev/null
+# Build Cache wrapper for indexing JSON menu files
+
+An NDCODE project.
+
+## Overview
+
+The `menu_cache` package exports a single constructor
+ `MenuCache(diag)`
+which must be called with the `new` operator. The resulting cache object stores
+JSON objects consisting of a JSON file `_menu.json` loaded from a specific
+directory, with a minor modification performed at build time which inserts an
+index into the JSON. This makes it easier to update the menu structure of the
+site, since you only have to list the menu entries and they're auto-indexed.
+
+See the `build_cache` and `disk_build` packages for more information. The
+`MenuCache` object is essentially a wrapper object which routes the request
+between these packages, to ensure that the indexed JSON is either retrieved
+from RAM or indexed from a source file as required.
+
+## Calling API
+
+Suppose one has a `MenuCache` instance named `mc`. It behaves somewhat like
+an ES6 `Map` object, except that it only has the `mc.get()` function, because
+new objects are added to the cache by attempting to `get` them.
+
+The interface for the `MenuCache`-provided instance function `mc.get()` is:
+
+`await mc.get(key)` — retrieves the object stored under `key`, where
+`key` is the on-disk pathname to a JSON file. A JSON object is returned,
+consisting of the loaded JSON objected modified to contain the required index.
+
+Before returning the cached copy, the existence and modification time of the
+JSON 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 indexed and the cache updated for next time. The
+indexing is via disk, and skipped if an up-to-date disk result is present.
+
+## 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
+
+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/menu_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>
--- /dev/null
+{
+ "name": "@ndcode/menu_cache",
+ "version": "0.1.0",
+ "description": "Menu loader, caching front-end with live reindexing",
+ "keywords": [
+ "menu",
+ "indexing",
+ "reindexing",
+ "server-side",
+ "render",
+ "cache",
+ "live",
+ "recompile"
+ ],
+ "homepage": "https://www.ndcode.org",
+ "author": "Nick Downing <nick@ndcode.org>",
+ "license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "https://git.ndcode.org/public/menu_cache.git"
+ },
+ "bugs": {
+ "email": "nick@ndcode.org"
+ },
+ "main": "MenuCache.js",
+ "engines": {
+ "node": ">=0.4.0"
+ },
+ "directories": {},
+ "dependencies": {
+ "@ndcode/build_cache": "^0.1.0",
+ "@ndcode/disk_build": "^0.1.1",
+ "assert": "^1.4.1"
+ },
+ "devDependencies": {}
+}
public / menu_cache.git / commitdiff