Stocare cheie-valoare

​

Prezentare generală

  ┌─────────────────┐   kv.set(key, value)   ┌──────────────────────────┐
  │ Logic function  │ ─────────────────────▶ │ Application KV store     │
  │ (your handler)  │ ◀───────────────────── │  key (unique)  │  value  │
  └─────────────────┘   kv.get(key)          └──────────────────────────┘

​

Get, set, delete

import { kv } from 'twenty-sdk/logic-function';

// Read a value. Returns null when the key is missing.
const cursor = await kv.get<string>('sync-cursor:linear');

// Write a value. Creates the entry on first write, updates it afterwards.
await kv.set('sync-cursor:linear', newCursor);

// Delete an entry. Returns true when an entry was removed.
await kv.delete('sync-cursor:linear');

​

Domenii de aplicare

• WORKSPACE (implicit) — intrarea este privată pentru instalarea curentă a workspace-ului aplicației tale. Fiecare workspace care instalează aplicația primește propriul set independent de chei. Aceasta este opțiunea potrivită pentru cache-uri, cursoare și stare specifică fiecărui workspace.
• SERVER — intrarea este partajată între fiecare instalare a aplicației tale de pe server. Intrările de tip server se comportă ca niște claim-uri: valoarea stocată este întotdeauna workspaceId-ul care a revendicat cheia (omite value la set pentru a revendica cheia pentru workspace-ul curent), iar doar acel workspace o poate suprascrie sau șterge. Orice instalare poate citi intrarea.

// In the connected workspace, when the external account is linked:
await kv.set(`slack:team:${teamId}`, undefined, { scope: 'SERVER' });

// In the server-route resolver (owner workspace), on each webhook:
const workspaceId = await kv.get<string>(`slack:team:${teamId}`, {
  scope: 'SERVER',
});

​

Folosește-l: păstrează în cache un apel costisitor

import { defineLogicFunction } from 'twenty-sdk/define';
import { kv } from 'twenty-sdk/logic-function';

const ONE_HOUR_MS = 60 * 60 * 1000;

type CachedRate = { rate: number; fetchedAt: number };

const handler = async (params: { from: string; to: string }) => {
  const cacheKey = `cache:exchange-rate:${params.from}:${params.to}`;
  const cached = await kv.get<CachedRate>(cacheKey);

  if (cached && Date.now() - cached.fetchedAt < ONE_HOUR_MS) {
    return { rate: cached.rate, cached: true };
  }

  const response = await fetch(
    `https://api.example.com/rate?from=${params.from}&to=${params.to}`,
  );
  const { rate } = (await response.json()) as { rate: number };

  await kv.set(cacheKey, { rate, fetchedAt: Date.now() });

  return { rate, cached: false };
};

export default defineLogicFunction({
  universalIdentifier: 'd9b2f4e6-1c83-4a07-9e52-6b1d3c8a0f47',
  name: 'get-exchange-rate',
  timeoutSeconds: 10,
  handler,
});

​

Tipare și sfaturi

• Spații de nume. Prefixează cheile pentru a păstra domeniile diferite separate — sync-cursor:linear, cache:exchange-rate:USD:EUR, lock:nightly-report.
• Expiry (TTL). Store-ul nu are expirare integrată. Stochează un timestamp în interiorul valorii (ca în exemplul de cache) și verifică-l la citire sau curăță cheile învechite dintr-o funcție declanșată de cron.
• Ce să stochezi. Orice valoare serializabilă JSON — numere, stringuri, array-uri, obiecte. Păstrează intrările mici; acesta este pentru coordonare și caching, nu pentru blob-uri mari sau fișiere. Pentru fișiere, folosește un câmp FILES și uploadFile.
• Vizibilitate. Intrările se află în baza de date Postgres a instanței, nu ca înregistrări ale spațiului de lucru — nu apar niciodată în interfața spațiului de lucru, nu fac parte din modelul de date al aplicației tale și nu necesită permisiuni de rol sau de obiect.

​

Alternativă: un obiect de stocare interogabil

• Limitarea la o înregistrare. Adaugă o relație de la obiectul de stocare la obiectul țintă, în loc să codifici id-ul în cheie.
• Vizibilitate și permisiuni. Rândurile trăiesc în baza de date a workspace-ului ca orice altă înregistrare, astfel încât pot fi interogate prin API și respectă rolul aplicației tale. Pentru a ține store-ul în afara UI-ului principal, nu îl include în navigation menu.