Source: database.js

  1. /*
  2.  * Copyright 2017-2019, Intel Corporation
  3.  *
  4.  * Redistribution and use in source and binary forms, with or without
  5.  * modification, are permitted provided that the following conditions
  6.  * are met:
  7.  *
  8.  *     * Redistributions of source code must retain the above copyright
  9.  *       notice, this list of conditions and the following disclaimer.
  10.  *
  11.  *     * Redistributions in binary form must reproduce the above copyright
  12.  *       notice, this list of conditions and the following disclaimer in
  13.  *       the documentation and/or other materials provided with the
  14.  *       distribution.
  15.  *
  16.  *     * Neither the name of the copyright holder nor the names of its
  17.  *       contributors may be used to endorse or promote products derived
  18.  *       from this software without specific prior written permission.
  19.  *
  20.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21.  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22.  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23.  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  24.  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27.  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28.  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29.  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30.  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31.  */
  33. /**
  34.  * Main Node.js pmemkv class.
  35.  *
  36.  * It contains Node.js pmemkv public enum *constants* and class *db* with its
  37.  * functions and members.
  38.  *
  39.  * @link   https://github.com/pmem/pmemkv-nodejs
  40.  * @file   This files defines the *db* class and exports *constants* enum.
  41.  * @since  1.0
  42.  */
  44. const pmemkv = require('bindings')('pmemkv');
  46. /** @class Main Node.js pmemkv class, it provides functions to operate on data in database.
  47.  *		If an error/exception is thrown from a method it will contain *status* variable.
  48.  *		Possible statuses are enumerated in constants.status.
  49. */
  50. class db {
  51. 	/**
  52. 	 * Creates an instance of db.
  53. 	 *
  54. 	 * @constructor
  55. 	 * @throws {Error} on any failure.
  56. 	 * @param {string} engine Name of the engine to work with.
  57. 	 * @param {object} config JSON like config with parameters specified for the engine.
  58. 	 */
  59. 	constructor(engine, config) {
  60. 		this._stopped = false;
  61. 		this._db = new pmemkv.db(engine, config);
  62. 		Object.defineProperty(this, '_db', {configurable: false, writable: false});
  63. 	}
  65. 	/**
  66. 	 * Stops the database.
  67. 	 */
  68. 	stop() {
  69. 		if (!this._stopped) {
  70. 			this._stopped = true;
  71. 			Object.defineProperty(this, '_stopped', {configurable: false, writable: false});
  72. 			this._db.stop();
  73. 		}
  74. 	}
  76. 	/**
  77. 	 * Returns value of *stopped* property.
  78. 	 *
  79. 	 * @return {boolean} true if stopped, false otherwise.
  80. 	 */
  81. 	get stopped() {
  82. 		return this._stopped;
  83. 	}
  85. 	/**
  86. 	 * Executes function for every record stored in db. Callback is called
  87. 	 *	only with the key of each record.
  88. 	 *
  89. 	 * @throws {Error} on any failure.
  90. 	 * @param {Function} callback - function to be called for every element stored in db.
  91. 	 *		It has only one param - key (for each returned element).
  92. 	 */
  93. 	get_keys(callback) {
  94. 		this._db.get_keys(callback);
  95. 	}
  97. 	/**
  98. 	 * Executes function for every record stored in db, whose keys are greater
  99. 	 *	than the given *key*. Callback is called only with the key of each record.
  100. 	 *
  101. 	 * @throws {Error} on any failure.
  102. 	 * @param {string} key - sets the lower bound for querying.
  103. 	 * @param {Function} callback - function to be called for each returned element.
  104. 	 *		It has only one param - key (for each returned element).
  105. 	 */
  106. 	get_keys_above(key, callback) {
  107. 		this._db.get_keys_above(key, callback);
  108. 	}
  110. 	/**
  111. 	 * Executes function for every record stored in db, whose keys are less than
  112. 	 *	the given *key*. Callback is called only with the key of each record.
  113. 	 *
  114. 	 * @throws {Error} on any failure.
  115. 	 * @param {string} key - sets the upper bound for querying.
  116. 	 * @param {Function} callback - function to be called for each returned element.
  117. 	 *		It has only one param - key (for each returned element).
  118. 	 */
  119. 	get_keys_below(key, callback) {
  120. 		this._db.get_keys_below(key, callback);
  121. 	}
  123. 	/**
  124. 	 * Executes function for every record stored in db, whose keys are
  125. 	 *	greater than the *key1* and less than the *key2*. Callback is
  126. 	 *	called only with the key of each record.
  127. 	 *
  128. 	 * @throws {Error} on any failure.
  129. 	 * @param {string} key1 - sets the lower bound for querying.
  130. 	 * @param {string} key2 - sets the upper bound for querying.
  131. 	 * @param {Function} callback - function to be called for each returned element.
  132. 	 *		It has only one param - key (for each returned element).
  133. 	 */
  134. 	get_keys_between(key1, key2, callback) {
  135. 		this._db.get_keys_between(key1, key2, callback);
  136. 	}
  138. 	/**
  139. 	 * Returns number of currently stored elements in db.
  140. 	 *
  141. 	 * @throws {Error} on any failure.
  142. 	 * @return {number|object} Number of records stored in db
  143. 	 *	or empty Value() if error occurred.
  144. 	 */
  145. 	get count_all() {
  146. 		return this._db.count_all();
  147. 	}
  149. 	/**
  150. 	 * Returns number of currently stored elements in db, whose keys are
  151. 	 *	greater than the given *key*.
  152. 	 *
  153. 	 * @throws {Error} on any failure.
  154. 	 * @param {string} key - sets the lower bound of counting.
  155. 	 * @return {number|object} Number of records in db matching query
  156. 	 *	or empty Value() if error occurred.
  157. 	 */
  158. 	count_above(key) {
  159. 		return this._db.count_above(key);
  160. 	}
  162. 	/**
  163. 	 * Returns number of currently stored elements in db, whose keys are
  164. 	 *	less than the given *key*.
  165. 	 *
  166. 	 * @throws {Error} on any failure.
  167. 	 * @param {string} key - sets the upper bound of counting.
  168. 	 * @return {number|object} Number of records in db matching query
  169. 	 *	or empty Value() if error occurred.
  170. 	 */
  171. 	count_below(key) {
  172. 		return this._db.count_below(key);
  173. 	}
  175. 	/**
  176. 	 * Returns number of currently stored elements in db, whose keys are
  177. 	 *	greater than the *key1* and less than the *key2*.
  178. 	 *
  179. 	 * @throws {Error} on any failure.
  180. 	 * @param {string} key1 - sets the lower bound of counting.
  181. 	 * @param {string} key2 - sets the upper bound of counting.
  182. 	 * @return {number|object} Number of records in db matching query
  183. 	 *	or empty Value() if error occurred.
  184. 	 */
  185. 	count_between(key1, key2) {
  186. 		return this._db.count_between(key1, key2);
  187. 	}
  189. 	/**
  190. 	 * Executes function for every record stored in db.
  191. 	 *
  192. 	 * @throws {Error} on any failure.
  193. 	 * @param {Function} callback - function to be called for every element stored in db.
  194. 	 */
  195. 	get_all(callback) {
  196. 		this._db.get_all(callback)
  197. 	}
  199. 	/**
  200. 	 * Executes function for every record stored in db, whose keys are
  201. 	 *	greater than the given *key*.
  202. 	 *
  203. 	 * @throws {Error} on any failure.
  204. 	 * @param {string} key - sets the lower bound for querying.
  205. 	 * @param {Function} callback - function to be called for each returned element.
  206. 	 */
  207. 	get_above(key, callback) {
  208. 		this._db.get_above(key, callback)
  209. 	}
  211. 	/**
  212. 	 * Executes function for every record stored in db, whose keys are
  213. 	 *	less than the given *key*.
  214. 	 *
  215. 	 * @throws {Error} on any failure.
  216. 	 * @param {string} key - sets the upper bound for querying.
  217. 	 * @param {Function} callback - function to be called for each returned element.
  218. 	 */
  219. 	get_below(key, callback) {
  220. 		this._db.get_below(key, callback)
  221. 	}
  223. 	/**
  224. 	 * Executes function for every record stored in db, whose keys are
  225. 	 *	greater than the *key1* and less than the *key2*.
  226. 	 *
  227. 	 * @throws {Error} on any failure.
  228. 	 * @param {string} key1 - sets the lower bound for querying.
  229. 	 * @param {string} key2 - sets the upper bound for querying.
  230. 	 * @param {Function} callback - function to be called for each returned element.
  231. 	 */
  232. 	get_between(key1, key2, callback) {
  233. 		this._db.get_between(key1, key2, callback)
  234. 	}
  236. 	/**
  237. 	 * Checks existence of record with given *key*.
  238. 	 *
  239. 	 * @throws {Error} on any failure.
  240. 	 * @param {string} key - record's key to query for.
  241. 	 * @return {boolean} True if record with given key exists, False otherwise.
  242. 	 */
  243. 	exists(key) {
  244. 		return this._db.exists(key);
  245. 	}
  247. 	/**
  248. 	 * Gets value of record with given *key*.
  249. 	 *
  250. 	 * @throws {Error} on any failure.
  251. 	 * @param {string} key - record's key to query for.
  252. 	 * @return {object} string with value stored for this key,
  253. 	 *	env.Undefined() if not found, or empty Value() if error.
  254. 	 */
  255. 	get(key) {
  256. 		return this._db.get(key);
  257. 	}
  259. 	/**
  260. 	 * Inserts a key-value pair into pmemkv database.
  261. 	 *
  262. 	 * @throws {Error} on any failure.
  263. 	 * @param {string} key - record's key; record will be put into database under its name.
  264. 	 * @param {string} value - data to be inserted into this new database record.
  265. 	 */
  266. 	put(key, value) {
  267. 		this._db.put(key, value);
  268. 	}
  270. 	/**
  271. 	 * Removes from database record with given *key*.
  272. 	 *
  273. 	 * @throws {Error} on any failure.
  274. 	 * @param {string} key - record's key to query for, to be removed.
  275. 	 * @return {boolean} True if pmemkv returned status OK, False if status NOT_FOUND.
  276. 	 */
  277. 	remove(key) {
  278. 		return this._db.remove(key);
  279. 	}
  280. }
  282. module.exports = db;
  283. module.exports.constants = pmemkv.constants;