.KEYVAL

Mit dem KeyValService (RAGAI.KEYVAL) kannst du beliebige Daten als Schlüssel-Wert-Paare nutzer- und bot-spezifisch speichern und abrufen. Die Daten sind an den aktuellen Nutzer und Bot gebunden – jeder Nutzer hat seine eigenen Daten pro Bot.

Optional kannst du jedem Eintrag einen Typ zuweisen, um Daten zu kategorisieren und gezielt abzufragen. Wird kein Typ angegeben, wird standardmäßig "custom" verwendet.

Permanente Speicherung

Wenn der key mit einem ! beginnt (z. B. !vorname), wird der Wert permanent gespeichert und überlebt Session-Resets.

---

Methoden

.set(key, value, type?)

Speichert einen Wert unter dem angegebenen Schlüssel. Optional kannst du einen Typ angeben, um den Eintrag zu kategorisieren.

Parameter	Typ	Beschreibung
key	string	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".

// Einfachen Wert speichern
await RAGAI.KEYVAL.set('vorname', 'Anna');

// Mit Typ
await RAGAI.KEYVAL.set('email', 'anna@example.com', 'userInfo');

// Permanent speichern (überlebt Session-Resets)
await RAGAI.KEYVAL.set('!sprache', 'de');

// Objekt speichern
await RAGAI.KEYVAL.set('profil', { name: 'Anna', abteilung: 'IT' }, 'userInfo');

.get(key, type?)

Gibt den Wert des angegebenen Schlüssels zurück. Liefert null, wenn der Schlüssel nicht existiert.

const vorname = await RAGAI.KEYVAL.get('vorname');
console.log(vorname); // 'Anna'

// Mit Typ
const email = await RAGAI.KEYVAL.get('email', 'userInfo');
console.log(email); // 'anna@example.com'

.unique(key, value, type?)

Funktioniert wie set(), hängt dem Schlüssel aber automatisch einen Zeitstempel an. Damit kannst du mehrere Einträge mit demselben Basis-Schlüssel speichern, ohne dass sie sich gegenseitig überschreiben. Ideal für Protokolle, Ereignisse oder Verlaufsdaten.

await RAGAI.KEYVAL.unique('antwort', 'Ja, das stimmt', 'quiz');
await RAGAI.KEYVAL.unique('antwort', 'Nein, falsch', 'quiz');
// Beide Einträge existieren, z. B. als 'antwort_1715000000' und 'antwort_1715000001'

.getByType(type)

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

const userInfos = await RAGAI.KEYVAL.getByType('userInfo');
console.log(userInfos);
// [{ key: 'email', value: 'anna@example.com', type: 'userInfo' }, ...]

.deleteKeyValEntry(key, type?)

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

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

---

Events

onKeyValUpdate

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

RAGAI.KEYVAL.onKeyValUpdate.subscribe((entry) => {
  console.log('KeyVal aktualisiert:', entry.key, entry.value);
});

onKeyValDelete

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

RAGAI.KEYVAL.onKeyValDelete.subscribe((entry) => {
  console.log('KeyVal gelöscht:', entry.key);
});

---

PROJECTKEYVAL – Projektweiter Schlüssel-Wert-Speicher

Der ProjectKeyValService (RAGAI.PROJECTKEYVAL) funktioniert genauso wie RAGAI.KEYVAL, speichert die Daten aber projektbezogen statt nutzerbezogen. Das bedeutet: Alle Nutzer eines Bots innerhalb desselben Projekts teilen sich diese Daten. Das ist ideal für gemeinsame Konfigurationen, projektweite Zähler oder geteilte Einstellungen.

Verfügbare Methoden

RAGAI.PROJECTKEYVAL bietet dieselbe API wie RAGAI.KEYVAL:

Methode	Beschreibung
.set(key, value, type?)	Speichert einen Wert projektweit.
.get(key, type?)	Liest einen projektweiten Wert.
.unique(key, value, type?)	Speichert einen Wert mit Zeitstempel projektweit.
.getByType(type)	Gibt alle projektweiten Einträge eines Typs zurück.
.deleteKeyValEntry(key, type?)	Löscht einen projektweiten Eintrag.

Events

Event	Beschreibung
onKeyValUpdate	Wird bei Änderungen an projektweiten Einträgen ausgelöst.
onKeyValDelete	Wird beim Löschen projektweiter Einträge ausgelöst.

Beispiele

// Projektweiten Zähler setzen
await RAGAI.PROJECTKEYVAL.set('besucherZaehler', 0, 'statistik');

// Zähler lesen und erhöhen
const zaehler = await RAGAI.PROJECTKEYVAL.get('besucherZaehler', 'statistik');
await RAGAI.PROJECTKEYVAL.set('besucherZaehler', zaehler + 1, 'statistik');

// Projektweite Konfiguration speichern
await RAGAI.PROJECTKEYVAL.set('maxVersuche', 3, 'config');

// Alle Statistik-Einträge abrufen
const statistiken = await RAGAI.PROJECTKEYVAL.getByType('statistik');
console.log(statistiken);

KEYVAL vs. PROJECTKEYVAL

• RAGAI.KEYVAL – Daten sind nutzer- und bot-spezifisch. Jeder Nutzer hat seinen eigenen Speicher.
• RAGAI.PROJECTKEYVAL – Daten sind projektweit geteilt. Alle Nutzer eines Bots im Projekt sehen dieselben Daten.

---

Beispiel: Nutzerprofil mit KeyVal aufbauen

// Nutzerdaten speichern
await RAGAI.KEYVAL.set('!name', 'Anna', 'profil');
await RAGAI.KEYVAL.set('!abteilung', 'IT', 'profil');
await RAGAI.KEYVAL.set('!sprache', 'de', 'profil');

// Alle Profil-Daten abrufen
const profil = await RAGAI.KEYVAL.getByType('profil');
profil.forEach(entry => {
  console.log(`${entry.key}: ${entry.value}`);
});

// Einzelnen Wert lesen
const name = await RAGAI.KEYVAL.get('!name', 'profil');
console.log('Hallo', name);

// Auf Änderungen reagieren
RAGAI.KEYVAL.onKeyValUpdate.subscribe((entry) => {
  if (entry.type === 'profil') {
    console.log('Profil aktualisiert:', entry.key);
  }
});