Le funzioni di logica vengono eseguite in sandbox in processi Node.js di breve durata — una volta terminata un’esecuzione, nulla di ciò che era in memoria sopravvive. Quando devi ricordare qualcosa tra un’esecuzione e l’altra (memorizzare nella cache una costosa risposta di un’API, archiviare un cursore per sincronizzazioni incrementali, applicare un debounce al lavoro o passare lo stato da una funzione all’altra), conservalo nel database dello spazio di lavoro.
Non ti serve un apposito costrutto di archiviazione per questo: un piccolo oggetto tecnico con un campo key e un campo value ti offre un archivio di tipo key-value durevole, con ambito limitato allo spazio di lavoro, interrogabile tramite lo stesso client API tipizzato che usi già per i record.
┌─────────────────┐ set(key, value) ┌──────────────────────────┐
│ Logic function │ ───────────────────▶ │ "KV Store" object │
│ (your handler) │ ◀─────────────────── │ key (unique) │ value │
└─────────────────┘ get(key) └──────────────────────────┘
Definisci l’oggetto store
Dichiara un oggetto personalizzato con due campi — key (un TEXT univoco) e value (un RAW_JSON così puoi archiviare qualsiasi payload serializzabile in JSON). Consulta Objects per la documentazione completa di defineObject.
src/objects/kv-store.object.ts
import { defineObject, FieldType } from 'twenty-sdk/define';
export const KV_STORE_UNIVERSAL_IDENTIFIER =
'2f1c8a90-3b6d-4e2a-9c47-7d0e5a1b9f33';
export const KV_STORE_KEY_FIELD_UNIVERSAL_IDENTIFIER =
'4a7e2d11-9c83-4f60-b5a2-1e6c8d0f4b21';
export const KV_STORE_VALUE_FIELD_UNIVERSAL_IDENTIFIER =
'8b3f6c02-5d19-47ae-9f31-2c4a7e0b6d58';
export default defineObject({
universalIdentifier: KV_STORE_UNIVERSAL_IDENTIFIER,
nameSingular: 'kvStore',
namePlural: 'kvStores',
labelSingular: 'KV Store',
labelPlural: 'KV Store',
description: 'Key-value storage for logic functions',
icon: 'IconDatabase',
fields: [
{
universalIdentifier: KV_STORE_KEY_FIELD_UNIVERSAL_IDENTIFIER,
name: 'key',
type: FieldType.TEXT,
label: 'Key',
description: 'Unique lookup key',
icon: 'IconKey',
},
{
universalIdentifier: KV_STORE_VALUE_FIELD_UNIVERSAL_IDENTIFIER,
name: 'value',
type: FieldType.RAW_JSON,
label: 'Value',
description: 'Stored JSON payload',
icon: 'IconJson',
},
],
});
Imponi l’univocità della chiave
Aggiungi un indice univoco su key in modo che la stessa chiave non possa mai avere due righe. Questo è il costrutto consigliato per l’univocità — vedi Data → Unique indexes.
src/indexes/kv-store-key.index.ts
import { defineIndex } from 'twenty-sdk/define';
import {
KV_STORE_UNIVERSAL_IDENTIFIER,
KV_STORE_KEY_FIELD_UNIVERSAL_IDENTIFIER,
} from '../objects/kv-store.object';
export default defineIndex({
universalIdentifier: 'c0d4e8f2-6a1b-4c93-8e57-3f9a2d0b7e14',
objectUniversalIdentifier: KV_STORE_UNIVERSAL_IDENTIFIER,
isUnique: true,
fields: [
{
universalIdentifier: 'c0d4e8f2-6a1b-4c93-8e57-3f9a2d0b7e15',
fieldUniversalIdentifier: KV_STORE_KEY_FIELD_UNIVERSAL_IDENTIFIER,
},
],
});
Leggi e scrivi da una funzione di logica
Incapsula l’oggetto dietro a pochi piccoli helper in modo che il resto del tuo codice assomigli a un’API key-value — get, set e del. Usano CoreApiClient, che è generato dallo schema del tuo spazio di lavoro ed è completamente tipizzato rispetto all’oggetto kvStore.
src/logic-functions/handlers/kv-store.ts
import { CoreApiClient } from 'twenty-client-sdk/core';
import { isDefined } from 'twenty-sdk/utils';
const client = new CoreApiClient();
// Look up a single row by its key.
const findByKey = async (key: string) => {
const { kvStores } = await client.query({
kvStores: {
__args: { filter: { key: { eq: key } }, first: 1 },
edges: { node: { id: true, value: true } },
},
});
return kvStores.edges[0]?.node;
};
// Read a value. Returns undefined when the key is missing.
export const get = async <TValue>(key: string): Promise<TValue | undefined> => {
const row = await findByKey(key);
return isDefined(row) ? (row.value as TValue) : undefined;
};
// Write a value. Creates the row on first write, updates it afterwards (upsert).
export const set = async (key: string, value: unknown): Promise<void> => {
const existing = await findByKey(key);
if (isDefined(existing)) {
await client.mutation({
updateKvStore: {
__args: { id: existing.id, data: { value } },
id: true,
},
});
return;
}
await client.mutation({
createKvStore: {
__args: { data: { key, value } },
id: true,
},
});
};
// Delete a value. No-op when the key is missing.
export const del = async (key: string): Promise<void> => {
const existing = await findByKey(key);
if (isDefined(existing)) {
await client.mutation({
deleteKvStore: { __args: { id: existing.id }, id: true },
});
}
};
L’indice univoco protegge dai duplicati, ma due esecuzioni che scrivono la stessa nuova chiave nello stesso istante possono comunque entrare in race condition tra la ricerca e la creazione. Considera una creazione che non riesce a causa del vincolo di univocità come “qualcun altro ha vinto” — intercettala e rileggi, oppure riprova come aggiornamento.
Usalo: metti in cache una chiamata costosa
Un uso tipico consiste nel mettere in cache una risposta lenta o soggetta a limitazione di frequenza da parte di terzi, così che le esecuzioni ripetute la riutilizzino invece di sostenerne il costo ogni volta.
src/logic-functions/getExchangeRate.logic-function.ts
import { defineLogicFunction } from 'twenty-sdk/define';
import { get, set } from './handlers/kv-store';
const ONE_HOUR_MS = 60 * 60 * 1000;
type CachedRate = { rate: number; fetchedAt: number };
const handler = async (params: { from: string; to: string }) => {
const cacheKey = `exchange-rate:${params.from}:${params.to}`;
const cached = await 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 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,
});
Pattern e suggerimenti
- Namespace. Anteponi prefissi alle chiavi per tenere separate le varie aree di interesse e per rendere semplici le ricerche in blocco —
sync-cursor:linear, cache:exchange-rate:USD:EUR, lock:nightly-report. Filtra con key: { like: 'cache:%' } per elencare o cancellare un intero namespace.
- Scadenza (TTL). Lo store non ha una scadenza integrata. Archivia un timestamp all’interno del
value (come nell’esempio di cache) e verificalo in lettura, oppure aggiungi un campo DATE_TIME e cancella periodicamente le righe obsolete da una funzione attivata da cron.
- Cosa archiviare.
RAW_JSON contiene qualsiasi valore serializzabile in JSON — numeri, stringhe, array, oggetti. Mantieni ridotte le dimensioni delle voci; questo meccanismo serve per coordinamento e caching, non per grandi blob o file. Per i file, usa un campo FILES e uploadFile.
- Visibilità e autorizzazioni. Le righe risiedono nel database dello spazio di lavoro come qualsiasi altro record, quindi sono interrogabili tramite l’API e rispettano il ruolo della tua app. Per tenere lo store fuori dall’interfaccia principale, escludilo dal tuo navigation menu.
- Limitare l’ambito a un record. Hai bisogno di uno stato per record invece che di chiavi globali? Aggiungi una relation dall’oggetto store all’oggetto di destinazione invece di codificare l’id nella chiave.
Questa è una convenzione, non una funzionalità separata — il “KV Store” è semplicemente un normale oggetto personalizzato che definisci e interroghi con le API standard. Questo significa che beneficia dello stesso meccanismo di sincronizzazione, delle stesse autorizzazioni e degli stessi strumenti del resto dei dati della tua app.
