npm package: @itzarty_/persisto
Description: **Persistent, auto-saving in-memory object with optional encryption, expiration, and built-in scheduler.**
Author: Arty
Latest version: 1.0.1

# Persisto

**Persistent, auto-saving in-memory object with optional encryption, expiration, and built-in scheduler.**

---

## Features

- **Auto-persisting object** — All changes are automatically serialized and saved to disk.
- **Transparent API** — Interact with a normal object, changes are tracked automatically.
- **Optional encryption** — Plug in your own crypto layer for storage security.
- **Custom presets** — Provide default values on initialization.
- **Expiration support** — Auto-delete entries after a set duration.
- **Integrated scheduler** — Register named tasks, trigger listeners, and manage periodic jobs.

---

## Installation

```bash
npm install @itzarty_/persisto
```

---

## Quick Start

```js
const Persisto = require('@itzarty_/persisto');
const persisto = new Persisto({
  file: './memory.bin',
  preset: { counter: 0 },
  crypto: {
    encrypt: buf => buf, // Replace with your encryption
    decrypt: buf => buf  // Replace with your decryption
  }
});

// Access the proxied object
persisto.memory.counter++;
persisto.memory.username = "Alice";

// Set a value with expiration (5 seconds)
persisto.memory.temp = {
  value: 42,
  [persisto.symbols.expiration]: 5000
};

// Use the scheduler
persisto.scheduler.register({
  name: 'heartbeat',
  interval: true,
  timeout: 1000
});

persisto.scheduler.listen((name, task) => {
  console.log(`Task "${name}" executed.`, task.data);
});
```

---

## API

### Factory function

```js
const mem = require('@itzarty_/persisto')(options)
```

**Options:**

| Option   | Type   | Default            | Description                                                          |
| -------- | ------ | ------------------ | -------------------------------------------------------------------- |
| `file`   | string | `'./persisto.bin'` | Path to storage file.                                                |
| `preset` | object | `{}`               | Default values for the object.                                       |
| `crypto` | object | none               | `{ encrypt: fn, decrypt: fn }` functions applied to serialized data. |

---

### Returned object

```js
{
  memory,     // Proxied data store
  symbols,    // Special symbols (e.g., expiration)
  scheduler   // Task scheduler API
}
```

#### `memory`

A proxy-wrapped object with:

- Automatic save on **set**, **delete**, or **function call return**.
- Nested objects are also proxied.
- Supports value expiration by assigning a property with the symbol key `symbols.expiration` (value in milliseconds).

**Example:**

```js
persisto.memory.session = {
  token: 'abc123',
  [persisto.symbols.expiration]: 10_000 // expires in 10 seconds
};
```

#### `symbols`

Currently contains:

- `symbols.expiration` — Attach to an object to auto-delete it after given milliseconds.

#### `scheduler`

Built-in lightweight task scheduler.

##### `scheduler.register({ name, data, interval, timeout })`

Registers a task.

- **name** (string) — Task name.
- **data** (object) — Arbitrary data passed to listeners.
- **interval** (bool) — Whether the task repeats.
- **timeout** (ms) — Delay before first/next execution.

##### `scheduler.listen(callback)`

Registers a listener called when any task triggers.\
`callback(name, task)` is called with the task name and config.

##### `scheduler.tasks()`

Returns the current tasks object. Each task has a `.remove()` method to unregister it.

---

## Persistence

Data is serialized via `v8.serialize()` and saved to the specified `file`.\
If `crypto` is provided, the `encrypt`/`decrypt` functions are applied during save/load.

Writes are throttled to **max 1 every 250ms** to avoid excessive disk I/O.

---

## Expiration

When you store an object with a `symbols.expiration` property (milliseconds), it will be automatically removed after that delay — even across restarts (pending expiration times are restored on load).

---

## License

MIT