# DataStore

The `DataStore` class provides a simple, synchronous key-value storage system that persists data as JSON files within the application's user data directory.

Each instance of the store corresponds to a single JSON file, making it ideal for managing user configurations, cached data, or state management.

### Setup

{% code lineNumbers="true" %}

```javascript
const DataStore = require('positron.js/store');

const settings = new DataStore('user-settings');
```

{% endcode %}

### Constructor

#### `new DataStore(id)`

Initializes a new store instance. If a JSON file for the given `id` does not exist in the user's data directory under the `stores` folder, it will automatically be created with an empty object `{}`.

* **Parameters:**
  * `id` `(string)`: A unique identifier for the store. This will be used as the filename (e.g., `id.json`).
* **Throws:** \* `Error`: "Store id is required" if the `id` parameter is missing or falsy.

### Methods

#### `get(key)`

Retrieves a value from the store by its key.

* **Parameters:**
  * `key` `(string)`: The key of the data you want to retrieve.
* **Returns:** `any` – The value associated with the key, or `undefined` if the key does not exist.

#### `set(key, value)`

Sets or updates a key-value pair in the store. This method immediately persists the change to the disk.

* **Parameters:**
  * `key` `(string)`: The key under which the value will be stored.
  * `value` `(any)`: The value to store (must be serializable to JSON).
* **Returns:** `void`

#### `delete(key)`

Removes a specific key and its associated value from the store.

* **Parameters:**
  * `key` `(string)`: The key to delete.
* **Returns:** `void`

#### `clear()`

Resets the store by removing all key-value pairs, leaving an empty JSON object (`{}`).

* **Returns:** `void`

#### `rm()`

Deletes the JSON file from the user's data directory.

> ⚠️ **Warning:** Once called, the file is permanently removed. Attempting to call `get`, `set`, or `delete` after this without recreating the store will result in a file-not-found error.

* **Returns:** `void`

#### `create()`

Manually creates the store's JSON file if it does not already exist. If the file is already present on the disk, this method does nothing.

* **Returns:** `void`

#### `exists()`

Checks whether the store's physical JSON file currently exists in the user's data directory.

* **Returns:** `boolean` – `true` if the file exists, `false` otherwise.

#### `all()`

Retrieves the entire contents of the store file as a single JavaScript object.

* **Returns:** `object` – An object containing all the key-value pairs currently saved in the store.

### Example Usage

Here is how you can use these new methods in practice:

```javascript
const DataStore = require('positron.js/store');

const cache = new DataStore('session-cache');

// 1. Check if the store file exists on disk
if (cache.exists()) {
    console.log("Cache file is ready!");
}

// 2. Populate the store with multiple keys
cache.set('token', 'xyz123');
cache.set('expiry', 3600);

// 3. Fetch the entire dataset at once
const currentCache = cache.all();
console.log(currentCache); 
// Output: { token: 'xyz123', expiry: 3600 }

// 4. Safely ensure a file exists (useful if rm() was previously called)
cache.rm(); // File is deleted
cache.create(); // File is safely recreated as {}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://positronjs.gitbook.io/v1/modules/datastore.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.