Initial public version

Author: andrewshell

README.md

@@ -1,2 +1,110 @@
-# cacheous
+# cacheism
 Simple caching library 
+
+## Overview
+
+The goal of cacheism is to wrap an async function with caching logic where we
+can easily specify under what circumstances we want to return the cache or fetch
+the live data.
+
+Your callback will get passed to it a Hit if there is an existing cache stored
+or a Miss if there is no existing cache.
+
+```js
+const Cacheism = require('@andrewshell/cacheism');
+
+const datadir = __dirname + '/data';
+const cache = new Cacheism(Cacheism.store.filesystem({ datadir }));
+
+async function run() {
+    let result = await cache.go('-internal', 'hoopla', Cacheism.Status.cacheOnFail, async (existing) => {
+        if (Math.random() < 0.5) {
+            throw Error('Death');
+        }
+        return { message: 'Hoopla!' };
+    });
+
+    if (result.isHit) {
+        console.dir(result.data);
+    }
+
+    if (result.error) {
+        console.error(result.error);
+    }
+}
+
+run().catch(err => console.error(err));
+```
+
+## Statuses
+
+### Only Fresh
+
+The onlyFresh status is for times where we never want to use the cache, but we
+want to fetch the fresh data and store it in the cache for other requests.
+
+### Cache on Fail
+
+The cacheOnFail status is for times where we want to try to fetch fresh data,
+but if an error is thrown, use the cache if present.
+
+### Prefer Cache
+
+The preferCache status is for times where we want to use the cache if available
+and only fetch fresh if the cache is not available.
+
+### Only Cache
+
+The onlyCache status if for times where we don't want to attempt to fetch fresh
+data and only return the cache if present.
+
+## Results
+
+The cache.go function will always return either a Hit or a Miss object.
+
+### Hit
+
+A hit is returned when we have good data. The `cached` param will be `true` if
+the data was fetched from cache versus fresh data.
+
+```
+Hit {
+  version: 2,
+  cacheName: '-internal/hoopla',
+  cached: true,
+  created: 2022-04-22T21:05:14.094Z,
+  data: { message: 'Hoopla!' },
+  error: Error: Death
+      at /Users/andrewshell/code/personal/test-cacheism/index.js:8:15
+      at Cacheism.go (/Users/andrewshell/code/personal/cacheism/lib/cacheism.js:29:30)
+      at async run (/Users/andrewshell/code/personal/test-cacheism/index.js:7:13),
+  etag: '"15-QcHvuZdyxCmLJ4zoYIPsP6pkNoM"',
+  isHit: true,
+  isMiss: false
+}
+```
+
+In the case of Cache on Fail, the error param may be set which is the error
+thrown while fetching fresh data.
+
+### Miss
+
+A miss is returned when we don't have good data. For instance, if there wasn't
+cached data and an error was thrown while fetching fresh data. You'll also get a
+miss if you fetch with the onlyCache status and there isn't a cache.
+
+```
+Miss {
+  version: 2,
+  cacheName: '-internal/hoopla',
+  cached: false,
+  created: 2022-04-22T21:30:56.275Z,
+  data: null,
+  error: Error: Missing cache
+      at Cacheism.go (/Users/andrewshell/code/personal/cacheism/lib/cacheism.js:27:19)
+      at async run (/Users/andrewshell/code/personal/test-cacheism/index.js:7:18),
+  etag: null,
+  isHit: false,
+  isMiss: true
+}
+```

lib/cacheism.js

@@ -0,0 +1,77 @@
+const common = require('./common');
+
+function _sanitize(string) {
+  return string.replaceAll(new RegExp('[^a-z0-9]+', 'ig'), '-');
+}
+
+function Cacheism(store) {
+    this.store = store;
+    this.status = common.Status;
+}
+
+Cacheism.prototype.go = async function (cacheDomain, cachePath, status, callback) {
+    let response, name = this.cacheName(cacheDomain, cachePath);
+
+    try {
+
+        let existing = new common.Miss(name, new Error('Missing cache'));
+        let hasCache = await this.store.isset(name);
+
+        if (hasCache) {
+            existing = await this.store.get(name);
+        }
+
+        if (status >= this.status.preferCache && hasCache) {
+            response = existing;
+        } else if (status === this.status.onlyCache) {
+            throw new Error('Missing cache');
+        } else {
+            response = await callback(existing);
+            if (!(response instanceof common.Hit)) {
+                response = new common.Hit(name, response);
+            }
+            await this.store.set(response);
+        }
+
+    } catch (err) {
+
+        if (status >= this.status.cacheOnFail && await this.store.isset(name)) {
+            response = await this.store.get(name);
+            response.error = err;
+        } else {
+            response = new common.Miss(name, err);
+        }
+
+    }
+
+    Object.freeze(response);
+    return response;
+}
+
+Cacheism.prototype.cacheName = function (cacheDomain, cachePath) {
+    return `${_sanitize(cacheDomain)}/${_sanitize(cachePath)}`;
+}
+
+Cacheism.prototype.setStore = function (store) {
+    this.store = store;
+}
+
+Cacheism.prototype.hit = function (name, data, etag) {
+    return new common.Hit(name, data, etag);
+}
+
+Cacheism.prototype.miss = function (name, error) {
+    return new common.Miss(name, error);
+}
+
+Cacheism.Hit = common.Hit;
+Cacheism.Miss = common.Miss;
+Cacheism.Data = common.Data;
+Cacheism.Status = common.Status;
+
+Cacheism.store = {
+    filesystem: require('./store-filesystem'),
+    memory: require('./store-memory'),
+};
+
+module.exports = Cacheism;

lib/common.js

@@ -0,0 +1,81 @@
+const generateEtag = require('etag');
+
+class Status {}
+
+Status.onlyFresh = 0;
+Status.cacheOnFail = 1;
+Status.preferCache = 2;
+Status.onlyCache = 3;
+
+Object.freeze(Status);
+
+class Hit {
+    constructor(name, data, etag) {
+        this.version = 2;
+        this.cacheName = name;
+        this.cached = false;
+        this.created = new Date();
+        this.data = data;
+        this.error = null;
+        this.etag = null == etag ? generateEtag(JSON.stringify(data)) : etag;
+        this.isHit = true;
+        this.isMiss = false;
+    }
+}
+
+class Miss {
+    constructor(name, error) {
+        this.version = 2;
+        this.cacheName = name;
+        this.cached = false;
+        this.created = new Date();
+        this.data = null;
+        this.error = error;
+        this.etag = null;
+        this.isHit = false;
+        this.isMiss = true;
+    }
+}
+
+class Data {
+    constructor(version, name, created, data, etag) {
+        this.version = version;
+        this.cacheName = name;
+        this.created = created;
+        this.data = data;
+        this.etag = etag;
+    }
+
+    hit() {
+        if (2 !== this.version) {
+            throw new Error(`Unknown cache version number: ${this.version}`);
+        }
+
+        const hit = new Hit(this.cacheName, this.data, this.etag);
+        hit.cached = true;
+        hit.created = this.created;
+
+        return hit;
+    }
+
+    stringify() {
+        return JSON.stringify({
+            version: this.version,
+            cacheName: this.cacheName,
+            created: this.created,
+            data: this.data,
+            etag: this.etag,
+        }, null, 2);
+    }
+
+    static fromHit(hit) {
+        return new Data(hit.version, hit.cacheName, hit.created, hit.data, hit.etag);
+    }
+
+    static parse(value) {
+        const parsed = JSON.parse(value);
+        return new Data(parsed.version, parsed.cacheName, new Date(parsed.created), parsed.data, parsed.etag);
+    }
+}
+
+module.exports = { Hit, Miss, Data, Status };

lib/store-filesystem.js

@@ -0,0 +1,39 @@
+const common = require('./common');
+const storeFilesystem = { };
+const path = require('path');
+const fs = require('fs');
+const fsPromises = require('fs/promises');
+
+module.exports = function (config) {
+    function _mkdir(dirpath) {
+      if (false === fs.existsSync(dirpath)) {
+        fs.mkdirSync(dirpath, { recursive: true });
+      }
+    }
+
+    _mkdir(config.datadir);
+
+    storeFilesystem.get = async (cacheName) => {
+        const filename = path.resolve(config.datadir, `${cacheName}.json`);
+        const data = await fsPromises.readFile(filename, 'utf8');
+        return common.Data.parse(data).hit();
+    }
+
+    storeFilesystem.set = async (hit) => {
+        const filename = path.resolve(config.datadir, `${hit.cacheName}.json`);
+        _mkdir(path.dirname(filename));
+        await fsPromises.writeFile(filename, common.Data.fromHit(hit).stringify(), 'utf8');
+    }
+
+    storeFilesystem.isset = async (cacheName) => {
+        const filename = path.resolve(config.datadir, `${cacheName}.json`);
+        return fs.existsSync(filename);
+    }
+
+    storeFilesystem.unset = async (cacheName) => {
+        const filename = path.resolve(config.datadir, `${cacheName}.json`);
+        await fsPromises.rm(filename, { force: true });
+    }
+
+    return storeFilesystem;
+}

lib/store-memory.js

@@ -0,0 +1,23 @@
+const common = require('./common');
+
+module.exports = function (config) {
+    const storeMemory = { data: {} };
+
+    storeMemory.get = async (cacheName) => {
+        return common.Data.parse(storeMemory.data[cacheName]).hit();
+    }
+
+    storeMemory.set = async (hit) => {
+        storeMemory.data[hit.cacheName] = common.Data.fromHit(hit).stringify();
+    }
+
+    storeMemory.isset = async (cacheName) => {
+        return null != storeMemory.data[cacheName];
+    }
+
+    storeMemory.unset = async (cacheName) => {
+        delete storeMemory.data[cacheName];
+    }
+
+    return storeMemory;
+}