SignStixAutoPurgePrefs (SignStix JS API)

```
SignStixAutoPurgePrefs
```
Interface exposed to JavaScript for managing long-lived key/value dictionaries that automatically purge themselves after a specified Time To Live (TTL) in days.
Overview
- Each dictionary is a persistent key/value store addressable by a unique name.
- Dictionaries are created with a TTL in days; when the TTL elapses they expire and are purged.
- Expired dictionaries no longer appear as present and do not accept reads/writes.
- Callers may also explicitly destroy a dictionary before its TTL elapses.
Naming rules
- Dictionary names must be 1–64 characters consisting only of letters, digits, dot (.), underscore (_), or hyphen (-).
- Invalid names cause Functions that accept a name to return false (or behave as not present) without creating/modifying data.
- Names are unique: create is no-overwrite. If a name already exists, creation fails and returns false.
TTL
- TTL must be in the inclusive range 1–365 days.
- Creation fails if the TTL is out of range.
- Expired dictionaries are removed during housekeeping; implementations may also perform cleanup on each access.
Storage quota
- The store enforces a global quota across all dictionaries.
- Writes that would exceed the quota are refused and return false (the previous value is preserved).
- getPrefsUsageBytes() reports current usage; getPrefsQuotaBytes() reports the maximum allowed.
Result semantics
- true indicates the operation succeeded; false indicates validation failure, not found, not present, or refusal (e.g., no-overwrite or quota).
- getString(String, String) returns null when the key is absent or the dictionary is missing/expired.
Typical flow
1. Create a dictionary with a valid name and TTL (no overwrite if already present).
2. Set and get string values by key while the dictionary is present.
3. Optionally destroy it early, or allow it to expire and be cleaned up.
Note: Implementations may synchronously persist metadata so presence checks reflect changes immediately.
Since:

Player 3.3.22

Function Summary

All Functions Instance Functions Abstract Functions
Modifier and Type	Function and Description
`void`	`cleanupExpired()` Remove any dictionaries whose Time To Live (TTL) has expired.
`boolean`	`createDictionary(String dictionaryName, int ttlDays)` Create a named dictionary that will auto-delete after `ttlDays`.
`boolean`	`destroyDictionary(String dictionaryName)` Explicitly destroy a named dictionary immediately.
`long`	`getPrefsQuotaBytes()` Get the maximum storage quota (in bytes) available for all dictionaries.
`long`	`getPrefsUsageBytes()` Get the current storage usage (in bytes) across all dictionaries.
`String`	`getString(String dictionaryName, String key)` Retrieve a string value from the named dictionary.
`boolean`	`isDictionaryPresent(String dictionaryName)` Check whether a named dictionary currently exists and has not expired.
`boolean`	`setString(String dictionaryName, String key, String value)` Store a string value into the named dictionary under the given key.

- Function Detail
  - createDictionary
```
boolean createDictionary(String dictionaryName,
                         int ttlDays)
```
    Create a named dictionary that will auto-delete after ttlDays.
    Validation & behaviour:
    - Name: 1–64 chars; allowed: letters, digits, dot (.), underscore (_), hyphen (-).
    - TTL: inclusive range 1–365 days.
    - No overwrite: if the name already exists, creation is refused and false is returned.
    - Cleanup: expired dictionaries may be purged before creation so names can be reused after expiry.
    Parameters:
    
    dictionaryName - name for the new dictionary
    
    ttlDays - number of days before auto-deletion (1–365)
    
    Returns:
    
    true if created; false if the name already existed, the name was invalid, or the TTL was out of range
    
    Since:
    
    Player 3.3.22
  - destroyDictionary
```
boolean destroyDictionary(String dictionaryName)
```
    Explicitly destroy a named dictionary immediately.
    After a successful destroy, the dictionary is no longer present and reads/writes against it will fail (e.g., getString(String, String) returns null; setString(String, String, String) returns false). Destroying a non-existent or already expired dictionary returns false.
    
    Parameters:
    
    dictionaryName - name of the dictionary
    
    Returns:
    
    true if found and destroyed; false if not present or the name was invalid
    
    Since:
    
    Player 3.3.22
  - isDictionaryPresent
```
boolean isDictionaryPresent(String dictionaryName)
```
    Check whether a named dictionary currently exists and has not expired.
    
    Parameters:
    
    dictionaryName - name of the dictionary
    
    Returns:
    
    true if present; false otherwise (including invalid name)
    
    Since:
    
    Player 3.3.22
  - setString
```
boolean setString(String dictionaryName,
                  String key,
                  String value)
```
    Store a string value into the named dictionary under the given key.
    Behaviour: returns false if the dictionary is missing/expired, the name is invalid, or the write would exceed the global storage quota (in which case the previous value remains).
    
    Parameters:
    
    dictionaryName - name of the dictionary
    
    key - lookup key (implementation defines valid key format)
    
    value - string to store (retrievable via the same key)
    
    Returns:
    
    true if stored; false if the dictionary does not exist/is expired, the name was invalid, or quota prevents the write
    
    Since:
    
    Player 3.3.22
  - getString
```
String getString(String dictionaryName,
                 String key)
```
    Retrieve a string value from the named dictionary.
    
    Parameters:
    
    dictionaryName - name of the dictionary
    
    key - lookup key
    
    Returns:
    
    the stored string, or null if the key is absent, the dictionary is missing/expired, or the name is invalid
    
    Since:
    
    Player 3.3.22
  - cleanupExpired
```
void cleanupExpired()
```
    Remove any dictionaries whose Time To Live (TTL) has expired.
    Implementations may call this automatically during other operations; this Function triggers an immediate cleanup pass.
    
    Since:
    
    Player 3.3.22
  - getPrefsUsageBytes
```
long getPrefsUsageBytes()
```
    Get the current storage usage (in bytes) across all dictionaries.
    Usage reflects the total size consumed by dictionary data; implementations may exclude internal metadata.
    
    Returns:
    
    number of bytes currently consumed by stored key/value data
    
    Since:
    
    Player 3.3.22
  - getPrefsQuotaBytes
```
long getPrefsQuotaBytes()
```
    Get the maximum storage quota (in bytes) available for all dictionaries.
    When usage meets or exceeds this value, subsequent writes are refused and return false.
    
    Returns:
    
    total quota in bytes that may be used before storage is refused
    
    Since:
    
    Player 3.3.22

Interface SignStixAutoPurgePrefs

Function Summary

Function Detail

createDictionary

destroyDictionary

isDictionaryPresent

setString

getString

cleanupExpired

getPrefsUsageBytes

getPrefsQuotaBytes