.KEYVAL

Speichert nutzer- und bot-spezifische Schlüssel-Wert-Paare zur Laufzeit (RAGAI.KEYVAL). Optional lässt sich jedem Eintrag ein Typ zur Kategorisierung zuweisen; Schlüssel mit !-Präfix werden dauerhaft gespeichert.

Hintergrund

Ohne !-Präfix wird ein Eintrag beim Reset der Bot-Sitzung gelöscht (z. B. nach RAGAI.resetBot()); mit !-Präfix (z. B. !sprache) übersteht er Session-Resets und ist beim nächsten Besuch desselben Nutzers wieder da. Der Speicher ist pro Bot isoliert - für projektweite, botübergreifende Daten desselben Nutzers gibt es stattdessen RAGAI.PROJECTKEYVAL (ProjectKeyValService) mit identischer API. Updates/Löschungen werden serverseitig per Socket synchronisiert (onKeyValUpdate/onKeyValDelete), damit mehrere gleichzeitig offene Tabs/Frames desselben Nutzers konsistent bleiben.

Events

onKeyValUpdate

Wird ausgelöst, wenn ein Schlüssel-Wert-Paar gesetzt oder aktualisiert wird.

RAGAI.KEYVAL.onKeyValUpdate.subscribe((value) => {
  console.log(value);
});

onKeyValDelete

Wird ausgelöst, wenn ein Schlüssel-Wert-Paar gelöscht wird.

RAGAI.KEYVAL.onKeyValDelete.subscribe((value) => {
  console.log(value);
});

Methoden

.deleteKeyValEntry(key, type?)

Löscht einen Eintrag anhand seines Schlüssels und optional seines Typs.

Parameter	Typ	Beschreibung
key	string | z.input<typeof keyValGetSchema>	Der zu löschende Schlüssel.
type	string	Optionaler Typ zur Kategorisierung. Standard: "custom".

Objekt-Form (validiert über keyValGetSchema):

Feld	Typ	Pflicht	Beschreibung
key	string	✔	Eindeutiger Schlüssel des Eintrags. Mit !-Präfix wird der Wert dauerhaft gespeichert.
type	string	– (Standard: "custom")	Optionaler Typ zur Kategorisierung der Einträge.

Rückgabewert: Promise<KeyValEntry>

Der gelöschte Eintrag.

await RAGAI.KEYVAL.deleteKeyValEntry('email', 'userInfo');

.get(key, type?)

Gibt den Wert des angegebenen Schlüssels zurück, oder null wenn er nicht existiert.

Parameter	Typ	Beschreibung
key	string | z.input<typeof keyValGetSchema>	Eindeutiger Schlüssel.
type	string	Optionaler Typ zur Kategorisierung. Standard: "custom".

Objekt-Form (validiert über keyValGetSchema):

Feld	Typ	Pflicht	Beschreibung
key	string	✔	Eindeutiger Schlüssel des Eintrags. Mit !-Präfix wird der Wert dauerhaft gespeichert.
type	string	– (Standard: "custom")	Optionaler Typ zur Kategorisierung der Einträge.

Rückgabewert: Promise<unknown>

Der gespeicherte Wert oder null.

const vorname = await RAGAI.KEYVAL.get('vorname');
const email = await RAGAI.KEYVAL.get('email', 'userInfo');

.set(key, value?, type?)

Speichert einen Wert unter dem angegebenen Schlüssel. Optional lässt sich ein Typ zur Kategorisierung angeben.

Parameter	Typ	Beschreibung
key	string | z.input<typeof keyValSetSchema>	Eindeutiger Schlüssel. Mit !-Präfix für permanente Speicherung.
value	unknown	Der zu speichernde Wert (String, Zahl, Objekt, Array etc.).
type	string	Optionaler Typ zur Kategorisierung. Standard: "custom".

Objekt-Form (validiert über keyValSetSchema):

Feld	Typ	Pflicht	Beschreibung
key	string	✔	Eindeutiger Schlüssel des Eintrags. Mit !-Präfix wird der Wert dauerhaft gespeichert.
value	any	✔	Der zu speichernde Wert (String, Zahl, Objekt, Array etc.).
type	string	– (Standard: "custom")	Optionaler Typ zur Kategorisierung der Einträge.

Rückgabewert: Promise<KeyValEntry>

Der gespeicherte Eintrag.

await RAGAI.KEYVAL.set('vorname', 'Anna');
await RAGAI.KEYVAL.set('email', 'anna@example.com', 'userInfo');
await RAGAI.KEYVAL.set('!sprache', 'de');

.unique(key, value?, type?)

Funktioniert wie set(), hängt dem Schlüssel aber automatisch einen Zeitstempel an, damit mehrere Einträge mit demselben Basis-Schlüssel nebeneinander bestehen können (z. B. für Verlaufsdaten).

Parameter	Typ	Beschreibung
key	string | z.input<typeof keyValSetSchema>	Basis-Schlüssel, wird um einen Zeitstempel ergänzt.
value	unknown	Der zu speichernde Wert.
type	string	Optionaler Typ zur Kategorisierung. Standard: "custom".

Objekt-Form (validiert über keyValSetSchema):

Feld	Typ	Pflicht	Beschreibung
key	string	✔	Eindeutiger Schlüssel des Eintrags. Mit !-Präfix wird der Wert dauerhaft gespeichert.
value	any	✔	Der zu speichernde Wert (String, Zahl, Objekt, Array etc.).
type	string	– (Standard: "custom")	Optionaler Typ zur Kategorisierung der Einträge.

Rückgabewert: Promise<KeyValEntry>

Der gespeicherte Eintrag.

await RAGAI.KEYVAL.unique('antwort', 'Ja, das stimmt', 'quiz');
await RAGAI.KEYVAL.unique('antwort', 'Nein, falsch', 'quiz');

.getByType(type)

Gibt alle Einträge eines bestimmten Typs als Array von KeyValEntry-Objekten zurück.

Parameter	Typ	Beschreibung
type	string	Der gesuchte Typ.

Rückgabewert: Promise<KeyValEntry[]>

Liste der passenden Einträge.

const userInfos = await RAGAI.KEYVAL.getByType('userInfo');