From 7b2dcfc17ce0d4cbae876130477df60a167a5253 Mon Sep 17 00:00:00 2001 From: Mariusz Nowak Date: Fri, 23 Feb 2018 16:50:18 +0100 Subject: [PATCH] docs: prettier --- README.md | 292 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 160 insertions(+), 132 deletions(-) diff --git a/README.md b/README.md index 795fa4c..59afe7f 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ [![npm version][npm-image]][npm-url] # Memoizee + ## Complete memoize/cache solution for JavaScript _Originally derived from [es5-ext](https://github.com/medikoo/es5-ext) package._ @@ -12,25 +13,25 @@ Memoization is best technique to save on memory or CPU cycles when we deal with ### Features -* Works with any type of function arguments – __no serialization is needed__ -* Works with [__any length of function arguments__](#arguments-length). Length can be set as fixed or dynamic. -* One of the [__fastest__](#benchmarks) available solutions. -* Support for [__promises__](#promise-returning-functions) and [__asynchronous functions__](#nodejs-callback-style-functions) -* [__Primitive mode__](#primitive-mode) which assures fast performance when arguments are convertible to strings. -* [__WeakMap based mode__](#weakmap-based-configurations) for garbage collection friendly configuration -* Can be configured [__for methods__](#memoizing-methods) (when `this` counts in) -* Cache [__can be cleared manually__](#manual-clean-up) or [__after specified timeout__](#expire-cache-after-given-period-of-time) -* Cache size can be __[limited on LRU basis](#limiting-cache-size)__ -* Optionally [__accepts resolvers__](#resolvers) that normalize function arguments before passing them to underlying function. -* Optional [__reference counter mode__](#reference-counter), that allows more sophisticated cache management -* [__Profile tool__](#profiling--statistics) that provides valuable usage statistics -* Covered by [__over 500 unit tests__](#tests) +* Works with any type of function arguments – **no serialization is needed** +* Works with [**any length of function arguments**](#arguments-length). Length can be set as fixed or dynamic. +* One of the [**fastest**](#benchmarks) available solutions. +* Support for [**promises**](#promise-returning-functions) and [**asynchronous functions**](#nodejs-callback-style-functions) +* [**Primitive mode**](#primitive-mode) which assures fast performance when arguments are convertible to strings. +* [**WeakMap based mode**](#weakmap-based-configurations) for garbage collection friendly configuration +* Can be configured [**for methods**](#memoizing-methods) (when `this` counts in) +* Cache [**can be cleared manually**](#manual-clean-up) or [**after specified timeout**](#expire-cache-after-given-period-of-time) +* Cache size can be **[limited on LRU basis](#limiting-cache-size)** +* Optionally [**accepts resolvers**](#resolvers) that normalize function arguments before passing them to underlying function. +* Optional [**reference counter mode**](#reference-counter), that allows more sophisticated cache management +* [**Profile tool**](#profiling--statistics) that provides valuable usage statistics +* Covered by [**over 500 unit tests**](#tests) ### Installation -In your project path — __note the two `e`'s in `memoizee`:__ +In your project path — **note the two `e`'s in `memoizee`:** - $ npm install memoizee + $ npm install memoizee _`memoize` name was already taken, therefore project is published as `memoizee` on NPM._ @@ -39,14 +40,16 @@ To port it to Browser or any other (non CJS) environment, use your favorite CJS ### Usage ```javascript -var memoize = require('memoizee'); +var memoize = require("memoizee"); -var fn = function (one, two, three) { /* ... */ }; +var fn = function(one, two, three) { + /* ... */ +}; memoized = memoize(fn); -memoized('foo', 3, 'bar'); -memoized('foo', 3, 'bar'); // Cache hit +memoized("foo", 3, "bar"); +memoized("foo", 3, "bar"); // Cache hit ``` ### Configuration @@ -55,16 +58,16 @@ All below options can be applied in any combination #### Arguments length -By default fixed number of arguments that function take is assumed (it's read from function's `length` property) this can be overridden: +By default fixed number of arguments that function take is assumed (it's read from function's `length` property) this can be overridden: ```javascript memoized = memoize(fn, { length: 2 }); -memoized('foo'); // Assumed: 'foo', undefined -memoized('foo', undefined); // Cache hit +memoized("foo"); // Assumed: 'foo', undefined +memoized("foo", undefined); // Cache hit -memoized('foo', 3, {}); // Third argument is ignored (but passed to underlying function) -memoized('foo', 3, 13); // Cache hit +memoized("foo", 3, {}); // Third argument is ignored (but passed to underlying function) +memoized("foo", 3, 13); // Cache hit ``` Dynamic _length_ behavior can be forced by setting _length_ to `false`, that means memoize will work with any number of arguments. @@ -72,32 +75,33 @@ Dynamic _length_ behavior can be forced by setting _length_ to `false`, that mea ```javascript memoized = memoize(fn, { length: false }); -memoized('foo'); -memoized('foo'); // Cache hit -memoized('foo', undefined); -memoized('foo', undefined); // Cache hit +memoized("foo"); +memoized("foo"); // Cache hit +memoized("foo", undefined); +memoized("foo", undefined); // Cache hit -memoized('foo', 3, {}); -memoized('foo', 3, 13); -memoized('foo', 3, 13); // Cache hit +memoized("foo", 3, {}); +memoized("foo", 3, 13); +memoized("foo", 3, 13); // Cache hit ``` #### Primitive mode -If we work with large result sets, or memoize hot functions, default mode may not perform as fast as we expect. In that case it's good to run memoization in _primitive_ mode. To provide fast access, results are saved in hash instead of an array. Generated hash ids are result of arguments to string conversion. __Mind that this mode will work correctly only if stringified arguments produce unique strings.__ +If we work with large result sets, or memoize hot functions, default mode may not perform as fast as we expect. In that case it's good to run memoization in _primitive_ mode. To provide fast access, results are saved in hash instead of an array. Generated hash ids are result of arguments to string conversion. **Mind that this mode will work correctly only if stringified arguments produce unique strings.** ```javascript memoized = memoize(fn, { primitive: true }); -memoized('/path/one'); -memoized('/path/one'); // Cache hit +memoized("/path/one"); +memoized("/path/one"); // Cache hit ``` #### Cache id resolution (normalization) By default cache id for given call is resolved either by: -- Direct Comparison of values passed in arguments as they are. In such case two different objects, even if their characteristics is exactly same (e.g. `var a = { foo: 'bar' }, b = { foo: 'bar' }`) will be treated as two different values. -- Comparison of stringified values of given arguments (`primitive` mode), which serves well, when arguments are expected to be primitive values, or objects that stringify naturally do unique values (e.g. arrays) + +* Direct Comparison of values passed in arguments as they are. In such case two different objects, even if their characteristics is exactly same (e.g. `var a = { foo: 'bar' }, b = { foo: 'bar' }`) will be treated as two different values. +* Comparison of stringified values of given arguments (`primitive` mode), which serves well, when arguments are expected to be primitive values, or objects that stringify naturally do unique values (e.g. arrays) Still above two methods do not serve all cases, e.g. if we want to memoize function where arguments are hash objects which we do not want to compare by instance but by its content. @@ -107,15 +111,20 @@ There's a `normalizer` option through which we can pass custom cache id normaliz e.g. if we want to memoize a function where argument is a hash object which we do not want to compare by instance but by its content, then we can achieve it as following: ```javascript -var mfn = memoize(function (hash) { - // body of memoized function -}, { normalizer: function (args) { - // args is arguments object as accessible in memoized function - return JSON.stringify(args[0]); -} }); +var mfn = memoize( + function(hash) { + // body of memoized function + }, + { + normalizer: function(args) { + // args is arguments object as accessible in memoized function + return JSON.stringify(args[0]); + } + } +); -mfn({ foo: 'bar' }); -mfn({ foo: 'bar' }); // Cache hit +mfn({ foo: "bar" }); +mfn({ foo: "bar" }); // Cache hit ``` #### Argument resolvers @@ -125,14 +134,21 @@ When we're expecting arguments of certain type it's good to coerce them before d ```javascript memoized = memoize(fn, { length: 2, resolvers: [String, Boolean] }); -memoized(12, [1,2,3].length); +memoized(12, [1, 2, 3].length); memoized("12", true); // Cache hit -memoized({ toString: function () { return "12"; } }, {}); // Cache hit +memoized( + { + toString: function() { + return "12"; + } + }, + {} +); // Cache hit ``` -__Note. If your arguments are collections (arrays or hashes) that you want to memoize by content (not by self objects), you need to cast them to strings__, for it's best to just use [primitive mode](#primitive-mode). Arrays have standard string representation and work with primitive mode out of a box, for hashes you need to define `toString` method, that will produce unique string descriptions, or rely on `JSON.stringify`. +**Note. If your arguments are collections (arrays or hashes) that you want to memoize by content (not by self objects), you need to cast them to strings**, for it's best to just use [primitive mode](#primitive-mode). Arrays have standard string representation and work with primitive mode out of a box, for hashes you need to define `toString` method, that will produce unique string descriptions, or rely on `JSON.stringify`. -Similarly __if you want to memoize functions by their code representation not by their objects, you should use primitive mode__. +Similarly **if you want to memoize functions by their code representation not by their objects, you should use primitive mode**. #### Memoizing asynchronous functions @@ -144,8 +160,10 @@ The difference from natural behavior is that in case when promise was rejected w the result is immediately removed from memoize cache, and not kept as further reusable result. ```javascript -var afn = function (a, b) { - return new Promise(function (res) { res(a + b); }); +var afn = function(a, b) { + return new Promise(function(res) { + res(a + b); + }); }; memoized = memoize(afn, { promise: true }); @@ -159,19 +177,18 @@ Default handling stands purely on _then_ which has side-effect of muting eventua Alternatively we can other (explained below), by stating with `promise` option desired mode: ```javascript -memoized = memoize(afn, { promise: 'done:finally' }); +memoized = memoize(afn, { promise: "done:finally" }); ``` - Supported modes +Supported modes -- `then` _(default)_. Values are resolved purely by passing callbacks to `promise.then`. __Side effect is that eventual unhandled rejection on given promise -come with no logged warning!__, and that to avoid implied error swallowing both states are resolved tick after callbacks were invoked +* `then` _(default)_. Values are resolved purely by passing callbacks to `promise.then`. **Side effect is that eventual unhandled rejection on given promise + come with no logged warning!**, and that to avoid implied error swallowing both states are resolved tick after callbacks were invoked -- `done` Values are resolved purely by passing callback to `done` method. __Side effect is that eventual unhandled rejection on given promise come with no logged warning!__. - -- `done:finally` The only method that may work with no side-effects assuming that promise implementaion does not throw unconditionally -if no _onFailure_ callback was passed to `done`, and promise error was handled by other consumer (this is not commonly implemented _done_ behavior). Otherwise side-effect is that exception is thrown on promise rejection (highly not recommended) +* `done` Values are resolved purely by passing callback to `done` method. **Side effect is that eventual unhandled rejection on given promise come with no logged warning!**. +* `done:finally` The only method that may work with no side-effects assuming that promise implementaion does not throw unconditionally + if no _onFailure_ callback was passed to `done`, and promise error was handled by other consumer (this is not commonly implemented _done_ behavior). Otherwise side-effect is that exception is thrown on promise rejection (highly not recommended) ##### Node.js callback style functions @@ -179,21 +196,21 @@ With _async_ option we indicate that we memoize asynchronous (Node.js style) fun Operations that result with an error are not cached. ```javascript -afn = function (a, b, cb) { - setTimeout(function () { - cb(null, a + b); - }, 200); +afn = function(a, b, cb) { + setTimeout(function() { + cb(null, a + b); + }, 200); }; memoized = memoize(afn, { async: true }); -memoized(3, 7, function (err, res) { - memoized(3, 7, function (err, res) { - // Cache hit - }); +memoized(3, 7, function(err, res) { + memoized(3, 7, function(err, res) { + // Cache hit + }); }); -memoized(3, 7, function (err, res) { - // Cache hit +memoized(3, 7, function(err, res) { + // Cache hit }); ``` @@ -202,29 +219,35 @@ memoized(3, 7, function (err, res) { When we are defining a prototype, we may want to define a method that will memoize it's results in relation to each instance. A basic way to obtain that would be: ```javascript -var Foo = function () { - this.bar = memoize(this.bar.bind(this), { someOption: true }); - // ... constructor logic +var Foo = function() { + this.bar = memoize(this.bar.bind(this), { someOption: true }); + // ... constructor logic }; -Foo.prototype.bar = function () { - // ... method logic +Foo.prototype.bar = function() { + // ... method logic }; ``` There's a lazy methods descriptor generator provided: ```javascript -var d = require('d'); -var memoizeMethods = require('memoizee/methods'); +var d = require("d"); +var memoizeMethods = require("memoizee/methods"); -var Foo = function () { - // ... constructor logic +var Foo = function() { + // ... constructor logic }; -Object.defineProperties(Foo.prototype, memoizeMethods({ - bar: d(function () { - // ... method logic - }, { someOption: true }) -})); +Object.defineProperties( + Foo.prototype, + memoizeMethods({ + bar: d( + function() { + // ... method logic + }, + { someOption: true } + ) + }) +); ``` #### WeakMap based configurations @@ -235,9 +258,11 @@ This mode works only for functions of which first argument is expected to be an It can be combined with other options mentioned across documentation. However due to WeakMap specificity global clear is not possible. ```javascript -var memoize = require('memoizee/weak'); +var memoize = require("memoizee/weak"); -var memoized = memoize(function (obj) { return Object.keys(obj); }); +var memoized = memoize(function(obj) { + return Object.keys(obj); +}); var obj = { foo: true, bar: false }; memoized(obj); @@ -251,7 +276,7 @@ memoized(obj); // Cache hit Delete data for particular call. ```javascript -memoized.delete('foo', true); +memoized.delete("foo", true); ``` Arguments passed to `delete` are treated with same rules as input arguments passed to function @@ -269,11 +294,11 @@ With _maxAge_ option we can ensure that cache for given call is cleared after pr ```javascript memoized = memoize(fn, { maxAge: 1000 }); // 1 second -memoized('foo', 3); -memoized('foo', 3); // Cache hit -setTimeout(function () { - memoized('foo', 3); // No longer in cache, re-executed - memoized('foo', 3); // Cache hit +memoized("foo", 3); +memoized("foo", 3); // Cache hit +setTimeout(function() { + memoized("foo", 3); // No longer in cache, re-executed + memoized("foo", 3); // Cache hit }, 2000); ``` @@ -282,19 +307,19 @@ Additionally we may ask to _pre-fetch_ in a background a value that is about to ```javascript memoized = memoize(fn, { maxAge: 1000, preFetch: true }); // Defaults to 0.33 -memoized('foo', 3); -memoized('foo', 3); // Cache hit +memoized("foo", 3); +memoized("foo", 3); // Cache hit -setTimeout(function () { - memoized('foo', 3); // Cache hit +setTimeout(function() { + memoized("foo", 3); // Cache hit }, 500); -setTimeout(function () { - memoized('foo', 3); // Cache hit, silently pre-fetched in next tick +setTimeout(function() { + memoized("foo", 3); // Cache hit, silently pre-fetched in next tick }, 800); -setTimeout(function () { - memoized('foo', 3); // Cache hit +setTimeout(function() { + memoized("foo", 3); // Cache hit }, 1300); ``` @@ -303,15 +328,15 @@ _Pre-fetch_ timespan can be customized: ```javascript memoized = memoize(fn, { maxAge: 1000, preFetch: 0.6 }); -memoized('foo', 3); -memoized('foo', 3); // Cache hit +memoized("foo", 3); +memoized("foo", 3); // Cache hit -setTimeout(function () { - memoized('foo', 3); // Cache hit, silently pre-fetched in next tick +setTimeout(function() { + memoized("foo", 3); // Cache hit, silently pre-fetched in next tick }, 500); -setTimeout(function () { - memoized('foo', 3); // Cache hit +setTimeout(function() { + memoized("foo", 3); // Cache hit }, 1300); ``` @@ -324,13 +349,13 @@ We can track number of references returned from cache, and manually delete them. ```javascript memoized = memoize(fn, { refCounter: true }); -memoized('foo', 3); // refs: 1 -memoized('foo', 3); // Cache hit, refs: 2 -memoized('foo', 3); // Cache hit, refs: 3 -memoized.deleteRef('foo', 3); // refs: 2 -memoized.deleteRef('foo', 3); // refs: 1 -memoized.deleteRef('foo', 3); // refs: 0, Cache purged for 'foo', 3 -memoized('foo', 3); // Re-executed, refs: 1 +memoized("foo", 3); // refs: 1 +memoized("foo", 3); // Cache hit, refs: 2 +memoized("foo", 3); // Cache hit, refs: 3 +memoized.deleteRef("foo", 3); // refs: 2 +memoized.deleteRef("foo", 3); // refs: 1 +memoized.deleteRef("foo", 3); // refs: 0, Cache purged for 'foo', 3 +memoized("foo", 3); // Re-executed, refs: 1 ``` ##### Limiting cache size @@ -339,20 +364,19 @@ With _max_ option you can limit cache size, it's backed with [LRU algorithm](htt The _size_ relates purely to count of results we want to keep in cache, it doesn't relate to memory cost associated with cache value (but such feature is likely to be introduced with next version of memoizee). - ```javascript memoized = memoize(fn, { max: 2 }); -memoized('foo', 3); -memoized('bar', 7); -memoized('foo', 3); // Cache hit -memoized('bar', 7); // Cache hit -memoized('lorem', 11); // Cache cleared for 'foo', 3 -memoized('bar', 7); // Cache hit -memoized('foo', 3); // Re-executed, Cache cleared for 'lorem', 11 -memoized('lorem', 11); // Re-executed, Cache cleared for 'bar', 7 -memoized('foo', 3); // Cache hit -memoized('bar', 7); // Re-executed, Cache cleared for 'lorem', 11 +memoized("foo", 3); +memoized("bar", 7); +memoized("foo", 3); // Cache hit +memoized("bar", 7); // Cache hit +memoized("lorem", 11); // Cache cleared for 'foo', 3 +memoized("bar", 7); // Cache hit +memoized("foo", 3); // Re-executed, Cache cleared for 'lorem', 11 +memoized("lorem", 11); // Re-executed, Cache cleared for 'bar', 7 +memoized("foo", 3); // Cache hit +memoized("bar", 7); // Re-executed, Cache cleared for 'lorem', 11 ``` ##### Registering dispose callback @@ -360,19 +384,23 @@ memoized('bar', 7); // Re-executed, Cache cleared for 'lorem', 11 You can register a callback to be called on each value removed from the cache: ```javascript -memoized = memoize(fn, { dispose: function (value) { /*…*/ } }); +memoized = memoize(fn, { + dispose: function(value) { + /*…*/ + } +}); -var foo3 = memoized('foo', 3); -var bar7 = memoized('bar', 7); -memoized.clear('foo', 3); // Dispose called with foo3 value -memoized.clear('bar', 7); // Dispose called with bar7 value +var foo3 = memoized("foo", 3); +var bar7 = memoized("bar", 7); +memoized.clear("foo", 3); // Dispose called with foo3 value +memoized.clear("bar", 7); // Dispose called with bar7 value ``` ### Benchmarks Simple benchmark tests can be found in _benchmark_ folder. Currently it's just plain simple calculation of fibonacci sequences. To run it you need to install other test candidates: - $ npm install underscore lodash lru-cache secondary-cache + $ npm install underscore lodash lru-cache secondary-cache Example output taken under Node v0.10.35 on 2011 MBP Pro: @@ -393,7 +421,7 @@ Fibonacci 3000 x10: If you want to make sure how much you benefit from memoization or just check if memoization works as expected, loading profile module will give access to all valuable information. -__Module needs to be imported before any memoization (that we want to track) is configured. Mind also that running profile module affects performance, it's best not to use it in production environment__ +**Module needs to be imported before any memoization (that we want to track) is configured. Mind also that running profile module affects performance, it's best not to use it in production environment** ```javascript var memProfile = require('memoizee/profile'); @@ -409,7 +437,7 @@ memoize(fn, { profileName: 'Another Function' }) Access statistics at any time: ```javascript -memProfile.statistics; // Statistics accessible for programmatic use +memProfile.statistics; // Statistics accessible for programmatic use console.log(memProfile.log()); // Output statistics data in readable form ``` @@ -435,7 +463,7 @@ Memoize statistics: ### Tests - $ npm test + $ npm test Project cross-browser compatibility to be supported by: @@ -444,7 +472,7 @@ Project cross-browser compatibility to be supported by: ### Contributors * [@puzrin](https://github.com/puzrin) (Vitaly Puzrin) - * Proposal and help with coining right _pre-fetch_ logic for [_maxAge_](https://github.com/medikoo/memoize#expire-cache-after-given-period-of-time) variant + * Proposal and help with coining right _pre-fetch_ logic for [_maxAge_](https://github.com/medikoo/memoize#expire-cache-after-given-period-of-time) variant [nix-build-image]: https://semaphoreci.com/api/v1/medikoo/memoizee/branches/master/shields_badge.svg [nix-build-url]: https://semaphoreci.com/medikoo/memoizee