Entités

Une application PRISM dispose de deux façons de travailler avec des données relationnelles :

1. defineEntity : un générateur d'écrans d'administration piloté par configuration. Il associe une entité à un CRUD complet, adossé aux procédures de la Platform API.
2. Requêtes SQL : le tagged template sql du framework, pour les requêtes que vous écrivez vous-même.

defineEntity

defineEntity associe une entité à des écrans liste / détail / création / édition et au CRUD correspondant, adossés aux procédures tRPC de la Platform API.

Les procédures de lecture sont typées : list.proc et getById.proc n'acceptent que des noms du catalogue de procédures du kit, donc une faute de frappe y est une erreur de compilation. Le type de la réponse de list.proc est aussi transmis aux adaptateurs rows et total. Les noms de crud.create, crud.update et crud.delete sont de simples chaînes : vérifiez-les vous-même.

Configuration

Les lectures et les écritures passent par le kit, qui appelle lui-même la Platform API : vous n'avez pas de client à écrire. L'adresse de l'API, le tenant et le site viennent de configureManage(...), appelé une seule fois dans un module que chaque route importe pour son effet de bord :

// src/lib/manage-setup.ts
import { configureManage } from "@bext-stack/manage/config";

configureManage({
  appId: "<app-id>",
  cmBase: "…",
  host: "…",
  origin: "…",
  tenantId: "…",
  siteId: "…",
});

Le ré-export mince

Pour publier une entité générée, ré-exportez le module d'entité du kit depuis un fichier de route, après l'import du module de configuration :

// src/app/manage/posts/page.tsx
import "../../../lib/manage-setup";
export { loader, default } from "@bext-stack/manage/entities/posts";

Une entité fournit un module par écran qu'elle possède (certaines n'ont qu'une liste) :

Exemple : la base de connaissances du helpdesk

L'entité « articles » de la base de connaissances du helpdesk est une configuration defineEntity reliée à ces procédures :

Un extrait de cette configuration :

import { defineEntity } from "@bext-stack/manage/lib/entity";

export const helpdeskKbArticles = defineEntity({
  name: "article",
  namePlural: "articles",
  icon: "book-open",
  basePath: "/manage/helpdesk/knowledge-base",
  list: {
    proc: "helpdeskKb.getArticles",
    rows: (r) => (Array.isArray(r) ? r : []),
    total: (r) => (Array.isArray(r) ? r.length : 0),
    input: (q) => ({
      search: q.search || undefined,
      status: q.filters.status || undefined,
    }),
  },
  getById: { proc: "helpdeskKb.getArticleById" },
  crud: {
    create: "helpdeskKb.createArticle",
    update: "helpdeskKb.updateArticle",
    delete: "helpdeskKb.deleteArticle",
  },
  // colonnes, filtres et champs de formulaire omis
});

Voir Helpdesk.

Requêtes SQL

Pour écrire vos propres requêtes, le framework exporte un helper SQL en tagged template :

import { sql, database } from "@bext-stack/framework";

const db = database("data.sqlite");
const posts = db.all(sql`SELECT id, title FROM posts WHERE author_id = ${authorId}`);

Un tableau interpolé devient une liste de paramètres, pratique pour IN (...). Les fragments se combinent sans perdre la numérotation des paramètres :

const rows = db.all(sql`
  SELECT id, title FROM ${sql.id("posts")}
  WHERE id IN (${ids})
  ${sql.if(authorId, sql`AND author_id = ${authorId}`)}
  ORDER BY created_at ${sql.raw(desc ? "DESC" : "ASC")}
`);

const conds = [sql`status = ${status}`, sql`author_id = ${authorId}`];
const count = db.get(sql`SELECT COUNT(*) AS n FROM posts WHERE ${sql.join(conds, " AND ")}`);

const { changes } = db.run(sql`UPDATE posts SET status = ${"archived"} WHERE id = ${id}`);

Le client createSdk offre aussi sdk.db.all, sdk.db.get et sdk.db.exec avec des paramètres ? (voir la Présentation du SDK). Ces appels sont asynchrones ; exec retourne { changes, lastInsertId }. Chaque paramètre est envoyé sous forme de chaîne : les nombres sont convertis, et null ou undefined deviennent une chaîne vide. Écrivez NULL dans le texte SQL quand il vous faut une vraie valeur nulle.

Et ensuite