KV Reference
The KV (Key/Value) store is a persistent, cross‑engine storage system that allows macros, PowerShellScript, JavaScriptV8, and JScript.NET blocks with macros to share values across macro runs and application restarts. KV is ideal for configurations, settings, API keys, counters, and other data that must survive beyond a single runtime session.
Overview
KV is available in all scripting engines:
- PowerShellScript
- JavaScriptV8
- JScript.NET
Unlike the runtime-only ObjectStore, KV persists data to a local encrypted SQLite database. Each record includes a Key, Value, Scope (macro, user, etc), and TimestampUtc. Macro-scoped entries are cleaned up automatically via auto-expiry.
Functions
kvSet(key, obj, [scope])kvGet(key)
All functions are available in:
- JScript.NET
- JavaScriptV8
- PowerShellScript
Storing Values
Store any value using a string key. KV stores both a plain string representation and an optional JSON representation (used for engine objects).
The scope of programatically created KV records defaults to "macro".JavaScript (V8 / JScript)
function kvSet(key, obj, scope)
{
if (scope == null) {
scope = "macro"
}
if (_server != null)
{
var objJSON = convertToJSON(obj);
_server.KVSet(key, obj, objJSON, scope);
}
}
PowerShell
function kvSet($key, $obj, $scope = "macro")
{
if ($_server -ne $null)
{
$objJSON = convertToJSON($obj)
$_server.KVSet($key, $obj, $objJSON, $scope)
}
}
Retrieving Values
kvGet returns values in a way that is convenient for script engines:
- For engine objects the server returns a string prefixed with a JSON marker. Clients detect the prefix and deserialize the JSON back into native objects.
- For non-engine primitives the server attempts a safe conversion back to common .NET primitives (int, long, bool, double, decimal, DateTime) and falls back to the raw string when conversion fails.
JavaScript (V8 / JScript)
function kvGet(key)
{
var response = null;
if (_server != null)
{
response = _server.KVGet(key);
if(typeof response == "string" && response.length > 6 && response.substring(0,6) == JSON_STRING_PREFIX)
{
response = eval("(" + response.substring(6) + ")");
}
}
return response;
}
PowerShell
function kvGet($key)
{
$response = $null
if ($_server -ne $null)
{
$response = $_server.KVGet($key)
if ($response -is [string] -and $response.length -gt 6 -and $response.Substring(0, 6) -eq $JsonStringPrefix) {
$response = $response.Substring(6) | ConvertFrom-Json
}
}
$response
}
Manage KV Store
You can add, update, and delete Key-Value records manually, by running a Manage KV Store helper-macro. The Manage KV Store helper-macro is found in Macro Main Helpers/Storage folder.
The scope of manually created KV records defaults to "user".Schema and Behavior
Each KV record contains the following columns:
- Key (TEXT PRIMARY KEY NOT NULL) — unique identifier for the record. Keys are case‑sensitive by default unless normalized in code or changed via collation.
- Value (TEXT) — optional plain string representation.
- ValueJSON (TEXT) — optional JSON string for engine objects.
- OriginalType (TEXT) — the runtime type name recorded at write time.
- Scope (TEXT) — logical scope for the record (for example,
"macro"); useful for targeted cleanup. - TimestampUtc (TEXT) — ISO 8601 UTC timestamp when the record was written.
The server enforces that Key is not null. Other columns are nullable so you can store only what you need.
Macro Cleanup and TTL
KV supports scoped cleanup. By default the KVStore constructor runs a cleanup that deletes records where
Scope = "macro" and TimestampUtc is older than 24 hours.
Use Cases
- Storing configuration and application settings that must persist across restarts
- Persisting API keys and secrets (with additional encryption or OS protections)
- Counters, feature flags, and long‑lived state shared across macros and engines
- Coordinating multi‑engine workflows where values must survive beyond a single macro run
- Storing JSON payloads produced by script engines for later retrieval