{"id":13447114,"url":"https://github.com/jonschlinkert/data-store","last_synced_at":"2025-04-04T21:08:33.311Z","repository":{"id":16586669,"uuid":"19340957","full_name":"jonschlinkert/data-store","owner":"jonschlinkert","description":"Easily get, set and persist config data. Fast. Supports dot-notation in keys. No dependencies.","archived":false,"fork":false,"pushed_at":"2022-06-28T03:49:53.000Z","size":208,"stargazers_count":160,"open_issues_count":7,"forks_count":27,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-28T20:07:49.262Z","etag":null,"topics":["cache","conf","config","configstore","data","javascript","json","nodejs","persist","store","stort"],"latest_commit_sha":null,"homepage":"https://github.com/jonschlinkert","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/jonschlinkert.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-05-01T09:45:51.000Z","updated_at":"2024-08-07T07:37:36.000Z","dependencies_parsed_at":"2022-08-18T03:10:34.863Z","dependency_job_id":null,"html_url":"https://github.com/jonschlinkert/data-store","commit_stats":null,"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonschlinkert%2Fdata-store","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonschlinkert%2Fdata-store/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonschlinkert%2Fdata-store/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonschlinkert%2Fdata-store/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonschlinkert","download_url":"https://codeload.github.com/jonschlinkert/data-store/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249526,"owners_count":20908212,"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":["cache","conf","config","configstore","data","javascript","json","nodejs","persist","store","stort"],"created_at":"2024-07-31T05:01:08.582Z","updated_at":"2025-04-04T21:08:33.288Z","avatar_url":"https://github.com/jonschlinkert.png","language":"JavaScript","readme":"# data-store [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=W8YFZ425KND68) [![NPM version](https://img.shields.io/npm/v/data-store.svg?style=flat)](https://www.npmjs.com/package/data-store) [![NPM monthly downloads](https://img.shields.io/npm/dm/data-store.svg?style=flat)](https://npmjs.org/package/data-store) [![NPM total downloads](https://img.shields.io/npm/dt/data-store.svg?style=flat)](https://npmjs.org/package/data-store) [![Build Status](https://travis-ci.org/jonschlinkert/data-store.svg?branch=master)](https://travis-ci.org/jonschlinkert/data-store)\n\n\u003e Easily persist and load config data. No dependencies.\n\nPlease consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.\n\n- [Install](#install)\n- [Usage example](#usage-example)\n- [API](#api)\n- [Options](#options)\n- [Example: setting path options](#example-setting-path-options)\n- [About](#about)\n\n_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_\n\n## Install\n\nInstall with [npm](https://www.npmjs.com/) (requires [Node.js](https://nodejs.org/en/) \u003e=8):\n\n```sh\n$ npm install --save data-store\n```\n\n## Usage example\n\nBy default a JSON file is created with the name of the store in the `~/.config/data-store/` directory. This is completely customizable via [options](#options).\n\n```js\n// create a config store (\"foo.json\") in the current working directory\nconst store = require('data-store')({ path: process.cwd() + '/foo.json' });\n\nstore.set('one', 'two'); \nconsole.log(store.data); //=\u003e { one: 'two' }\n\nstore.set('x.y.z', 'boom!');\nstore.set({ c: 'd' });\n\nconsole.log(store.get('e.f'));\n//=\u003e 'g'\n\nconsole.log(store.get());\n//=\u003e { name: 'app', data: { a: 'b', c: 'd', e: { f: 'g' } } }\n\nconsole.log(store.data);\n//=\u003e { a: 'b', c: 'd', e: { f: 'g' } }\n```\n\nYou may also access the `Store` class if you need to extend or modify the class:\n\n```js\nconst { Store } = require('data-store');\n\nclass MyClass extends Store {\n  constructor(...args) {\n    super(...args);\n  }\n}\n```\n\n## API\n\n### [Store](index.js#L34)\n\nInitialize a new `Store` with the given `name`, `options` and `default` data.\n\n**Params**\n\n* `name` **{String}**: Store name to use for the basename of the `.json` file.\n* `options` **{object}**: See all [available options](#options).\n* `defaults` **{object}**: An object to initialize the store with.\n\n**Example**\n\n```js\nconst store = require('data-store')('abc');\n//=\u003e '~/data-store/a.json'\n\nconst store = require('data-store')('abc', { cwd: 'test/fixtures' });\n//=\u003e './test/fixtures/abc.json'\n```\n\n### [.set](index.js#L84)\n\nAssign `value` to `key` and save to the file system. Can be a key-value pair, array of objects, or an object.\n\n**Params**\n\n* `key` **{String}**\n* `val` **{any}**: The value to save to `key`. Must be a valid JSON type: String, Number, Array or Object.\n* `returns` **{Object}** `Store`: for chaining\n\n**Example**\n\n```js\n// key, value\nstore.set('a', 'b');\n//=\u003e {a: 'b'}\n\n// extend the store with an object\nstore.set({a: 'b'});\n//=\u003e {a: 'b'}\n```\n\n### [.merge](index.js#L127)\n\nAssign `value` to `key` while retaining prior members of `value` if `value` is a map. If `value` is not a map, overwrites like `.set`.\n\n**Params**\n\n* `key` **{String}**\n* `val` **{any}**: The value to merge to `key`. Must be a valid JSON type: String, Number, Array or Object.\n* `returns` **{Object}** `Store`: for chaining\n\n**Example**\n\n```js\nstore.set('a', { b: c });\n//=\u003e {a: { b: c }}\n\nstore.merge('a', { d: e });\n//=\u003e {a: { b: c, d: e }}\n\nstore.set('a', 'b');\n//=\u003e {a: 'b'}\n\nstore.merge('a', { c : 'd' });\n//=\u003e {a: { c : 'd' }}\n```\n\n### [.union](index.js#L154)\n\nAdd the given `value` to the array at `key`. Creates a new array if one doesn't exist, and only adds unique values to the array.\n\n**Params**\n\n* `key` **{String}**\n* `val` **{any}**: The value to union to `key`. Must be a valid JSON type: String, Number, Array or Object.\n* `returns` **{Object}** `Store`: for chaining\n\n**Example**\n\n```js\nstore.union('a', 'b');\nstore.union('a', 'c');\nstore.union('a', 'd');\nstore.union('a', 'c');\nconsole.log(store.get('a'));\n//=\u003e ['b', 'c', 'd']\n```\n\n### [.get](index.js#L179)\n\nGet the stored `value` of `key`.\n\n**Params**\n\n* `key` **{String}**\n* `returns` **{any}**: The value to store for `key`.\n\n**Example**\n\n```js\nstore.set('a', {b: 'c'});\nstore.get('a');\n//=\u003e {b: 'c'}\n\nstore.get();\n//=\u003e {a: {b: 'c'}}\n```\n\n### [.has](index.js#L208)\n\nReturns `true` if the specified `key` has a value.\n\n**Params**\n\n* `key` **{String}**\n* `returns` **{Boolean}**: Returns true if `key` has\n\n**Example**\n\n```js\nstore.set('a', 42);\nstore.set('c', null);\n\nstore.has('a'); //=\u003e true\nstore.has('c'); //=\u003e true\nstore.has('d'); //=\u003e false\n```\n\n### [.hasOwn](index.js#L235)\n\nReturns `true` if the specified `key` exists.\n\n**Params**\n\n* `key` **{String}**\n* `returns` **{Boolean}**: Returns true if `key` exists\n\n**Example**\n\n```js\nstore.set('a', 'b');\nstore.set('b', false);\nstore.set('c', null);\nstore.set('d', true);\nstore.set('e', undefined);\n\nstore.hasOwn('a'); //=\u003e true\nstore.hasOwn('b'); //=\u003e true\nstore.hasOwn('c'); //=\u003e true\nstore.hasOwn('d'); //=\u003e true\nstore.hasOwn('e'); //=\u003e true\nstore.hasOwn('foo'); //=\u003e false\n```\n\n### [.del](index.js#L256)\n\nDelete one or more properties from the store.\n\n**Params**\n\n* `keys` **{String|Array}**: One or more properties to delete.\n\n**Example**\n\n```js\nstore.set('foo.bar', 'baz');\nconsole.log(store.data); //=\u003e { foo: { bar: 'baz' } }\nstore.del('foo.bar');\nconsole.log(store.data); //=\u003e { foo: {} }\nstore.del('foo');\nconsole.log(store.data); //=\u003e {}\n```\n\n### [.clone](index.js#L282)\n\nReturn a clone of the `store.data` object.\n\n* `returns` **{Object}**\n\n**Example**\n\n```js\nconsole.log(store.clone());\n```\n\n### [.clear](index.js#L297)\n\nClear `store.data` to an empty object.\n\n* `returns` **{undefined}**\n\n**Example**\n\n```js\nstore.clear();\n```\n\n### [.json](index.js#L315)\n\nStringify the store. Takes the same arguments as `JSON.stringify`.\n\n**Params**\n\n* `replacer` **{Function}**: Replacer function.\n* `indent` **{String}**: Indentation to use. Default is 2 spaces.\n* `returns` **{String}**\n\n**Example**\n\n```js\nconsole.log(store.json(null, 2));\n```\n\n### [.save](index.js#L349)\n\nCalls [.writeFile()](#writefile) to persist the store to the file system, after an optional [debounce](#options) period. This method should probably not be called directly as it's used internally by other methods.\n\n* `returns` **{undefined}**\n\n**Example**\n\n```js\nstore.save();\n```\n\n### [.unlink](index.js#L370)\n\nDelete the store from the file system.\n\n* `returns` **{undefined}**\n\n**Example**\n\n```js\nstore.unlink();\n```\n\n## Options\n\n| **Option** | **Type** | **Default** | **Description** |\n| --- | --- | --- | --- |\n| `debounce` | `number` | `undefined` | Disabled by default. Milliseconds to delay writing the JSON file to the file system. This can make the store more performant by preventing multiple subsequent writes after calling `.set` or setting/getting `store.data`, but comes with the potential side effect that the config file will be outdated during the timeout. To get around this, use data-store's API to [(re-)load](#load) the file instead of directly reading the file (using `fs.readFile` for example). |\n| `indent` | `number∣null` | `2` | The indent value to pass to `JSON.stringify()` when writing the file to the fs, or when [.json()](#json) is called |\n| `name` | `string` | `undefined` | The name to use for the store file stem (`name + '.json'` is the store's file name) |\n| `home` | `string` | `process.env.XDG_CONFIG_HOME` or `path.join(os.homedir(), '.config')` | The root home directory to use |\n| `base` | `string` | `path.join(home, 'data-store')` | The relative sub-folder to join to `home` for data-store config files. |\n| `path` | `string` | `...` | Absolute file path for the data-store JSON file. This is created by joining `base` to `name + '.json'`. Setting this value directly will override the `name`, `home` and `base` values. |\n\n## Example: setting path options\n\nYou can set the store path using `options.path`:\n\n```js\nconst os = require('os');\nconst path = require('path');\nconst store = new Store({\n  path: path.join(os.homedir(), '.config/my_app/settings.json')\n});\n\nconsole.log(store.path);\n// '~/.config/my_app/settings.json'\n```\n\nOr you can set the path using a combination of path parts. The following is equivalent to the previous example:\n\n```js\nconst os = require('os');\nconst store = new Store({\n  home: os.homedir(),\n  base: '.config/my_app',\n  name: 'settings'\n});\n\nconsole.log(store.path);\n// '~/.config/my_app/settings.json'\n```\n\n## About\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eContributing\u003c/strong\u003e\u003c/summary\u003e\n\nPull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eRunning Tests\u003c/strong\u003e\u003c/summary\u003e\n\nRunning and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:\n\n```sh\n$ npm install \u0026\u0026 npm test\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eBuilding docs\u003c/strong\u003e\u003c/summary\u003e\n\n_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_\n\nTo generate the readme, run the following command:\n\n```sh\n$ npm install -g verbose/verb#dev verb-generate-readme \u0026\u0026 verb\n```\n\n\u003c/details\u003e\n\n### Related projects\n\nYou might also be interested in these projects:\n\n* [get-value](https://www.npmjs.com/package/get-value): Use property paths like 'a.b.c' to get a nested value from an object. Even works… [more](https://github.com/jonschlinkert/get-value) | [homepage](https://github.com/jonschlinkert/get-value \"Use property paths like 'a.b.c' to get a nested value from an object. Even works when keys have dots in them (no other dot-prop library can do this!).\")\n* [has-value](https://www.npmjs.com/package/has-value): Returns true if a value exists, false if empty. Works with deeply nested values using… [more](https://github.com/jonschlinkert/has-value) | [homepage](https://github.com/jonschlinkert/has-value \"Returns true if a value exists, false if empty. Works with deeply nested values using object paths.\")\n* [set-value](https://www.npmjs.com/package/set-value): Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths. | [homepage](https://github.com/jonschlinkert/set-value \"Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths.\")\n* [write](https://www.npmjs.com/package/write): Write data to a file, replacing the file if it already exists and creating any… [more](https://github.com/jonschlinkert/write) | [homepage](https://github.com/jonschlinkert/write \"Write data to a file, replacing the file if it already exists and creating any intermediate directories if they don't already exist. Thin wrapper around node's native fs methods.\")\n\n### Contributors\n\n| **Commits** | **Contributor** |  \n| --- | --- |  \n| 177 | [jonschlinkert](https://github.com/jonschlinkert) |  \n| 7   | [derrell](https://github.com/derrell) |  \n| 5   | [doowb](https://github.com/doowb) |  \n| 3   | [nytamin](https://github.com/nytamin) |  \n| 2   | [tunnckoCore](https://github.com/tunnckoCore) |  \n| 1   | [jamen](https://github.com/jamen) |  \n| 1   | [ArtskydJ](https://github.com/ArtskydJ) |  \n\n### Author\n\n**Jon Schlinkert**\n\n* [GitHub Profile](https://github.com/jonschlinkert)\n* [Twitter Profile](https://twitter.com/jonschlinkert)\n* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)\n\n### License\n\nCopyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert).\nReleased under the [MIT License](LICENSE).\n\n***\n\n_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on November 12, 2019._","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=W8YFZ425KND68"],"categories":["JavaScript","Packages","nodejs"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonschlinkert%2Fdata-store","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonschlinkert%2Fdata-store","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonschlinkert%2Fdata-store/lists"}