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

npm install @itzarty_/persisto

Quick Start

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

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

{
  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:

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