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:

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

where "scope" is optional, and defaults to 'macro' if ommited.

All functions are available in:

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:

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:

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