tmp-cache - npm Package Compare versions

Comparing version 0.0.0 to 1.0.0

package.json

 {
   "name": "tmp-cache",
-  "version": "0.0.0"
+  "version": "1.0.0",
+  "repository": "lukeed/tmp-cache",
+  "description": "A least-recently-used cache manager in 35 lines of code",
+  "main": "lib/index.js",
+  "license": "MIT",
+  "author": {
+    "name": "Luke Edwards",
+    "email": "[e-mail]",
+    "url": "lukeed.com"
+  },
+  "engines": {
+    "node": ">=6"
+  },
+  "scripts": {
+    "test": "tape test/*.js | tap-spec"
+  },
+  "files": [
+    "lib"
+  ],
+  "keywords": [
+    "cache",
+    "lru",
+    "lru-cache",
+    "mru"
+  ],
+  "devDependencies": {
+    "tap-spec": "^4.1.1",
+    "tape": "^4.8.0"
+  }
 }

readme.md

@@ -1,16 +0,16 @@
-# dset [![Build Status](https://travis-ci.org/lukeed/dset.svg?branch=master)](https://travis-ci.org/lukeed/dset)
+# tmp-cache [![Build Status](https://travis-ci.org/lukeed/tmp-cache.svg?branch=master)](https://travis-ci.org/lukeed/tmp-cache)
 
-> A tiny (135B) utility for safely writing deep Object values~!
+> A least-recently-used cache manager in 35 lines of code~!
 
-This module exposes two module definitions:
+LRU caches operate on a first-in-first-out queue. This means that the first item is the oldest and will therefore be deleted once the `max` limit has been reached.
 
-* **ES Module**: `dist/dset.es.js`
-* **CommonJS**: `dist/dset.js`
+When a `maxAge` value is set, items are given an expiration date. This allows existing items to become stale over time which, depending on your `stale` config, is equivalent to the item not existing at all!
 
-For _accessing_ deep object properties, please see [`dlv`](https://github.com/developit/dlv).
+In order to counteract this idle decay, all `set()` and `get()` operations on an item "refresh" its expiration date. By doing so, a new `expires` value is issued & the item is moved to the end of the list — aka, it's the newest kid on the block!
 
+
 ## Install
 
 ```
-$ npm install --save dset
+$ npm install --save tmp-cache
 ```
@@ -22,22 +22,29 @@
 ```js
-const dset = require('dset');
+const Cache = require('tmp-cache');
 
-let foo = { a:1, b:2 };
-let bar = { foo:123, bar:[4, 5, 6], baz:{} };
-let baz = { a:1, b:{ x:{ y:{ z:999 } } }, c:3 };
+let cache = new Cache(3); // sets "max" size
 
-dset(foo, 'd.e.f', 'hello');
-// or ~> dset(foo, ['d', 'e', 'f'], 'hello');
-console.log(foo);
-//=> { a:1, b:2, d:{ e:{ f:'hello' } } };
+cache.set('a', 1); //~> ['a']
+cache.set('b', 2); //~> ['a', 'b']
+cache.set('c', 3); //~> ['a', 'b', 'c']
+cache.get('a');    //~> ['b', 'c', 'a']
+cache.set('d', 4); //~> ['c', 'a', 'd']
+cache.peek('a');   //~> ['c', 'a', 'd']
+cache.delete('d'); //~> ['c', 'a']
+cache.has('d');    //=> false
+cache.set('e', 5); //~> ['c', 'a', 'e']
+cache.size;        //=> 3
+cache.clear();     //~> []
 
-dset(bar, 'bar.1', 999);
-// or ~> dset(bar, ['bar', 1], 999);
-console.log(bar);
-//=> { foo:123, bar:[4, 999, 6], baz:{} };
+cache = new Cache({ maxAge:10 });
 
-dset(baz, 'b.x.j.k', 'mundo');
-dset(baz, 'b.x.y.z', 'hola');
-console.log(baz);
-//=> { a:1, b:{ x:{ y:{ z:'hola' }, j:{ k:'mundo' } } }, c:3 }
+cache.set(123, 'hello'); //~> valid for 10ms
+cache.get(123); //=> 'hello'  --  resets 10ms counter
+setTimeout(_ => cache.get(123), 25); //=> undefined
+
+cache = new Cache({ maxAge:0, stale:true });
+
+cache.set('foo', [123]); //~> already stale, 0ms lifespan
+cache.get('foo'); //=> [123]  --  because options.stale
+cache.get('foo'); //=> undefined  --  previous op flagged removal
 ```
@@ -47,31 +54,92 @@
 
-### dset(obj, path, val)
+Aside from the items & changes mentioned below, `tmp-cache` extends the `Map` class, so all [properties and methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map#Map_instances) are inherited.
 
-Returns: `void`
+### Cache(options)
 
-#### obj
+Returns: `Cache extends Map`
 
-Type: `Object`
+#### options.max
 
-The Object to traverse & mutate with a value.
+Type: `Number`<br>
+Default: `Infinity`
 
-#### path
+The maximum number of items the cache will hold. Adding more entries will force the oldest, least-recently-used item to be purged.
 
-Type: `String` or `Array`
+Failure to include any `max` restriction could potentially allow infinite unique entries! They will only be purged based on their `expires` value (if set).
 
-The key path that should receive the value. May be in `x.y.z` or `['x', 'y', 'z']` formats.
+> **Note:** If `options` is an integer, then it is used as the `options.max` value.
 
-> **Note:** Please be aware that only the _last_ key actually receives the value!
+#### options.maxAge
 
-> **Important:** New Objects are created at each segment if there is not an existing structure.
+Type: `Number`<br>
+Default: `-1`
 
+The maximum age (in ms) an item is considered valid; aka, its lifespan.
+
+Items are not pro-actively pruned out as they age, but if you try to access an item that has expired, it will be purged and, by default, result in an `undefined` response.
+
+#### options.stale
+
+Type: `Boolean`<br>
+Default: `false`
+
+Allow an expired/stale item's value to be returned before deleting it.
+
+
+### Cache.set(key, value, maxAge?)
+
+Persists the item and its value into the Cache. If a `maxAge` value exists (via custom or cache-level options), an expiration date will also be stored.
+
+When setting or updating an item that already exists, the original is removed. This allows the new item to be unique & the most recently used!
+
+#### key
+Type: `String`
+
+The item's unique identifier.
+
 #### value
+Type: `Mixed`
 
-Type: `Any`
+The item's value to cache.
 
-The value that you want to set. Can be of any type!
+#### maxAge
+Type: `Number`<br>
+Default: `options.maxAge`
 
+Optionally override the [`options.maxAge`](#optionsmaxage) for this (single) operation.
 
+
+### Cache.get(key, mutate?)
+
+Retrieve an item's value by its key name. By default, this operation will refresh/update the item's expiration date.
+
+May also return `undefined` if the item does not exist, or if it has expired & [`stale`](#optionsstale) is not set.
+
+#### key
+Type: `String`
+
+The item's unique identifier.
+
+#### mutate
+Type: `Boolean`<br>
+Default: `true`
+
+Refresh the item's expiration date, marking it as _more_ recently used.
+
+
+### Cache.peek(key)
+
+Return an item's value without updating its position or refreshing its expiration date.
+
+May also return `undefined` if the item does not exist, or if it has expired & [`stale`](#optionsstale) is not set.
+
+#### key
+Type: `String`
+
+The item's unique identifier.
+
+
+
 ## License
 
 MIT © [Luke Edwards](https://lukeed.com)

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

No contributors or author data

Maintenance

Package does not specify a list of contributors or an author in package.json.

Found 1 instance in 1 package

No repository

Supply chain risk

Package does not have a linked source code repository. Without this field, a package will have no reference to the location of the source code use to generate the package.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

6938

increased by22.77%

Number of low maintenance alerts

1

decreased by-50%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

144

increased by89.47%

Number of low supply chain risk alerts

1

decreased by-50%

Worsened metrics

Dev dependency count

2

increased byInfinity%

Number of package files

4

decreased by-63.64%

Lines of code

34

decreased by-46.87%

No dependency changes