{"id":17771408,"url":"https://github.com/rootslab/camphora","last_synced_at":"2025-05-12T23:42:35.646Z","repository":{"id":17578976,"uuid":"20382448","full_name":"rootslab/camphora","owner":"rootslab","description":"Camphora, a tiny module for NFU (Not Frequently Used) in-memory caching, with linear Aging.","archived":false,"fork":false,"pushed_at":"2018-02-10T14:40:28.000Z","size":58,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-12T23:42:31.787Z","etag":null,"topics":["caching","inmem-cache","nfu","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rootslab.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-06-01T17:40:40.000Z","updated_at":"2017-12-05T13:33:09.000Z","dependencies_parsed_at":"2022-09-26T21:31:35.017Z","dependency_job_id":null,"html_url":"https://github.com/rootslab/camphora","commit_stats":null,"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fcamphora","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fcamphora/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fcamphora/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fcamphora/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rootslab","download_url":"https://codeload.github.com/rootslab/camphora/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253843168,"owners_count":21972867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["caching","inmem-cache","nfu","nodejs"],"created_at":"2024-10-26T21:32:46.197Z","updated_at":"2025-05-12T23:42:35.629Z","avatar_url":"https://github.com/rootslab.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"### Camphora\n\n[![NPM VERSION](http://img.shields.io/npm/v/camphora.svg?style=flat)](https://www.npmjs.org/package/camphora)\n[![CODACY BADGE](https://img.shields.io/codacy/b18ed7d95b0a4707a0ff7b88b30d3def.svg?style=flat)](https://www.codacy.com/public/44gatti/camphora)\n[![CODECLIMATE-TEST-COVERAGE](https://img.shields.io/codeclimate/c/rootslab/camphora.svg?style=flat)](https://codeclimate.com/github/rootslab/camphora)\n[![LICENSE](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://github.com/rootslab/camphora#mit-license)\n\n![NODE VERSION](https://img.shields.io/node/v/camphora.svg)\n[![TRAVIS CI BUILD](http://img.shields.io/travis/rootslab/camphora.svg?style=flat)](http://travis-ci.org/rootslab/camphora)\n[![BUILD STATUS](http://img.shields.io/david/rootslab/camphora.svg?style=flat)](https://david-dm.org/rootslab/camphora)\n[![DEVDEPENDENCY STATUS](http://img.shields.io/david/dev/rootslab/camphora.svg?style=flat)](https://david-dm.org/rootslab/camphora#info=devDependencies)\n\n[![NPM MONTHLY](http://img.shields.io/npm/dm/camphora.svg?style=flat)](http://npm-stat.com/charts.html?package=camphora)\n![NPM YEARLY](https://img.shields.io/npm/dy/camphora.svg)\n\n[![NPM GRAPH](https://nodei.co/npm/camphora.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/camphora/)\n\n\u003e _**Camphora**_, a tiny module for __NFU__ _(Not Frequently Used)_ __in-memory caching__, with linear _Aging_.\n\n\u003e In this custom implementation:\n - when a new entry is __read or updated__ for the __first time__ its __age__ counter is set to __-1__.\n - if the entry __still exists__, its __age__ will be __decremented by -2__.\n - when a entry ( exisiting or not ) was read or updated, each __age__ counter for the __other entries__,\n   will be __incremented by 1__.\n - when the __max capacity__ is reached, the entry with the __highest age__ value will be evicted.\n - when two or more entries have the __same highest age__ value, the entry with the __oldest updateAt__\n   value will be chosen for eviction, as for the __LRU__ algorithm.\n\n### Install\n\n```bash\n$ npm install camphora [-g]\n// clone repo\n$ git clone git@github.com:rootslab/camphora.git\n```\n\u003e __require__:\n\n```javascript\nvar Camphora = require( 'camphora' );\n```\n\u003e See [examples](example/).\n\n### Run Tests\n\n```bash\n$ cd camphora/\n$ npm test\n```\n### Constructor\n\n\u003e Create an instance, the argument within [ ] is optional.\n\n```javascript\nCamphora( [ Object opt ] )\n// or\nnew Camphora( [ Object opt ] )\n```\n\n#### Options\n\n\u003e Default options are listed.\n\n```javascript\nopt = {\n    /*\n     * Set the max number of entries in the cache.\n     * When this value will be reached, an element with the highest \"age\"\n     * among others, will be evicted from the cache.\n     *\n     * NOTE: 'capacity' is not related to the cache size in bytes.\n     */\n    , capacity : 1024\n\n    /*\n     * Choose an algorithm to encode objects into keys. \n     *\n     * NOTE: Algorithm is dependent on the available algorithms\n     * supported by the version of OpenSSL on the platform.\n     * Examples are 'sha1', 'md5', 'sha256', 'sha512', etc.\n     * On recent releases, openssl list-message-digest-algorithms\n     * will display the available digest algorithms.\n     * See http://nodejs.org/api/crypto.html#crypto_crypto_createhash_algorithm.\n     */\n    , algorithm : 'sha1'\n\n    /*\n     * Choose a particular encoding for the digest/key. \n     *\n     * NOTE: The encoding can be 'hex', 'binary' or 'base64'.\n     * If no encoding is provided, then a buffer is returned.\n     * See http://nodejs.org/api/crypto.html#crypto_hash_digest_encoding\n     */\n    , output_encoding : 'hex'\n\n    /*\n     * Change how the input encoding will be intepreted.\n     *\n     * NOTE: set the encoding of the given input, it can be 'utf8', 'ascii'\n     * or 'binary'. If no encoding is provided and the input is a string,\n     * an encoding of 'binary' is enforced.\n     * If data is a Buffer then input_encoding is ignored.\n     * See http://nodejs.org/api/crypto.html#crypto_hash_update_data_input_encoding\n     */\n    , input_encoding : 'binary'\n\n    /*\n     * For default, cache keys are encrypted with the same algorithm\n     * used for data.\n     * Set it to false to use unencrypted/cleartext key names.\n     * \n     * NOTE: if encryption is disabled, methods like #get and #peek will accept\n     * the same unencrypted argument for the key.\n     */\n     , encrypt_keys : true\n}\n```\n\n### Properties\n\n```javascript\n/*\n * An object/hash that holds cached objects.\n * Every cache entry is an object/hash:\n *\n * 'kdigest' : {\n *      age : Number\n *      , key : String\n *      , kdigest : String\n *      , data : Buffer | String | null\n *      , ddigest : String | null\n *      , dbytes : Number\n *      , updateAt : Number\n *  }\n *\n * - 'age' indicates the current 'freshness' of the key.\n * - 'key' contains the actual (JSON.stringify) value of the key.\n * - 'kdigest' is the string result of the key encoding.\n * - 'data' contains the current payload associated with the key.\n * - 'ddigest' is the string result of the payload data encoding.\n * - 'dbytes' indicates the current size in bytes of data.\n * - 'updatedAt' holds the last access timestamp.\n */\nCamphora.cache\n\n/*\n * An object/hash that holds current options.\n */\nCamphora.options\n\n```\n\n### Methods\n\n\u003e Arguments within [ ] are optional, '|' indicates multiple type for an argument.\n\n```javascript\n/*\n * Load a file entry into the cache.\n * It returns the new or updated object entry.\n * Default options are:\n */\n file_load_opt = {\n     /*\n      * For default, #load method saves the file data\n      * and its resulting digest into the cache.\n      * If it set to false, only data digest will be stored.\n      */\n      payload : true\n\n     /*\n      * For default, #load method uses the entire path ( filepath + '/' + filename ) to\n      * generate the digest key; this value is used to store file entry into the cache\n      * and to retrieve it.\n      * If it is set, only the filename will be used to generate the digest key.\n      */\n      , filepath : null\n\n     /*\n      * fs.readFile default options\n      * See http://nodejs.org/api/fs.html#fs_fs_readfile_filename_options_callback\n      */\n      , encoding : null\n      , flag : 'r'\n }\n\nCamphora#load = function ( String filename [, Object file_load_opt [, Function cback ] ] ) : undefined\n\n/*\n * Read or Create an object/key entry into the cache, without payload data.\n * It returns the new or updated object entry. \n *\n * NOTE: 'key' argument will be converted with JSON.stringify().\n *\n * NOTE: It affects 'age' properties in the cache.\n */\nCamphora#read = function ( Object key ) : Object\n\n/*\n * Update or Create an object/key entry into the cache, optionally specifying\n * additional payload data.\n * It returns the new or updated object entry. \n *\n * NOTE: 'key' argument will be converted with JSON.stringify().\n *\n * NOTE: It affects 'age' properties in the cache.\n */\nCamphora#update = function ( Object key [, Buffer payload | String payload ] ) : Object\n\n/*\n * Evict a key/object entry from the cache.\n * It returns true if entry exists, false otherwise.\n *\n * NOTE: 'key' argument will be converted with JSON.stringify().\n */\nCamphora#evict = function ( Object key ) : Boolean\n\n/*\n * Peek an object/key entry from the cache.\n * It returns the Object entry, or undefined if it doesn't exist.\n *\n * NOTE: It doesn't affect 'age' properties in the cache.\n *\n * NOTE: 'key' argument will be converted with JSON.stringify().\n */\nCamphora#peek = function ( Object key ) : Object\n\n/*\n * Get an object/key entry from the cache, using its actual encoded value.\n * It returns the Object entry, or undefined if it doesn't exist.\n *\n * NOTE: It doesn't affect 'age' properties in the cache.\n */\nCamphora#get = function ( String encoded_key ) : Object\n\n/*\n * Delete a key/object entry from the cache, using its actual encoded value.\n * It returns true if entry exists, false otherwise.\n */\nCamphora#delete = function ( String encoded_key ) : Boolean\n\n/*\n * Clear the cache.\n * It returns the current number of entries evicted.\n */\nCamphora#clear = function () : Number\n\n/*\n * Reset age properties for all entries in the cache.\n * It returns the current number of entries updated.\n */\nCamphora#reset = function () : Number\n\n/*\n * Get the current cache size.\n * It returns an Array:\n * [ Number total_number_of_entries, Number total_bytes_of_payload_data ]\n */\nCamphora#size = function () : Array\n\n/*\n * Get all the ( encoded ) keys in the cache.\n */\nCamphora#keys = function () : Array\n```\n\n------------------------------------------------------------------------\n\n\n### MIT License\n\n\u003e Copyright (c) 2013-present \u0026lt; Guglielmo Ferri : 44gatti@gmail.com \u0026gt;\n\n\u003e Permission is hereby granted, free of charge, to any person obtaining\n\u003e a copy of this software and associated documentation files (the\n\u003e 'Software'), to deal in the Software without restriction, including\n\u003e without limitation the rights to use, copy, modify, merge, publish,\n\u003e distribute, sublicense, and/or sell copies of the Software, and to\n\u003e permit persons to whom the Software is furnished to do so, subject to\n\u003e the following conditions:\n\n\u003e __The above copyright notice and this permission notice shall be\n\u003e included in all copies or substantial portions of the Software.__\n\n\u003e THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,\n\u003e EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\n\u003e MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\n\u003e IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\n\u003e CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\n\u003e TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\n\u003e SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootslab%2Fcamphora","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frootslab%2Fcamphora","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootslab%2Fcamphora/lists"}