Référence de l'API JavaScript

EmDash exporte des fonctions pour interroger le contenu et travailler avec l’aperçu, les paramètres, les menus, les taxonomies, les zones de widgets, les sections et la recherche.

Requêtes de contenu

Les fonctions de requête d’EmDash suivent le modèle des collections de contenu en direct d’Astro, renvoyant { entries, error } ou { entry, error } pour une gestion élégante des erreurs.

getEmDashCollection()

Récupère toutes les entrées d’une collection. L’exemple suivant charge tous les articles et vérifie les erreurs :

import { getEmDashCollection } from "emdash";

const { entries: posts, error } = await getEmDashCollection("posts");

if (error) {
	console.error("Failed to load posts:", error);
}

Paramètres

Options

Le paramètre options accepte le filtre suivant :

interface CollectionFilter {
	status?: "draft" | "published" | "archived";
	limit?: number;
	where?: Record<string, string | string[]>; // Filter by field or taxonomy
}

Valeur de retour

La fonction se résout en un CollectionResult :

interface CollectionResult<T> {
	entries: ContentEntry<T>[]; // Empty array if error or none found
	error?: Error; // Set if query failed
}

Exemples

Les exemples suivants filtrent par statut et taxonomie, limitent les résultats et gèrent les erreurs :

// Get all published posts
const { entries: posts } = await getEmDashCollection("posts", {
	status: "published",
});

// Get latest 5 posts
const { entries: latest } = await getEmDashCollection("posts", {
	limit: 5,
	status: "published",
});

// Filter by taxonomy
const { entries: newsPosts } = await getEmDashCollection("posts", {
	status: "published",
	where: { category: "news" },
});

// Handle errors
const { entries, error } = await getEmDashCollection("posts");
if (error) {
	return new Response("Server error", { status: 500 });
}

getEmDashEntry()

Récupère une entrée unique par slug ou ID. L’exemple suivant charge un article et redirige s’il manque :

import { getEmDashEntry } from "emdash";

const { entry: post, error } = await getEmDashEntry("posts", "my-post-slug");

if (!post) {
	return Astro.redirect("/404");
}

Paramètres

Le mode aperçu est géré automatiquement — le middleware détecte les jetons _preview et sert le contenu brouillon via AsyncLocalStorage. Le paramètre facultatif options n’accepte qu’un locale pour la résolution du slug ; l’état d’aperçu ne nécessite aucun paramètre.

Valeur de retour

La fonction se résout en un EntryResult :

interface EntryResult<T> {
	entry: ContentEntry<T> | null; // null if not found
	error?: Error; // Set only for actual errors, not "not found"
	isPreview: boolean; // true if draft content is being served
}

Exemples

Les exemples suivants récupèrent par slug et ID, lisent l’état d’aperçu et distinguent les erreurs de “non trouvé” :

// Get by slug
const { entry: post } = await getEmDashEntry("posts", "hello-world");

// Get by ID
const { entry: post } = await getEmDashEntry("posts", "01HXK5MZSN0FVXT2Q3KPRT9M7D");

// Preview is automatic — isPreview is true when a valid _preview token is present
const { entry, isPreview, error } = await getEmDashEntry("posts", slug);

// Handle errors vs not-found
if (error) {
	return new Response("Server error", { status: 500 });
}
if (!entry) {
	return Astro.redirect("/404");
}

Types de contenu

ContentEntry

Les fonctions de requête renvoient des entrées sous la forme suivante :

interface ContentEntry<T = Record<string, unknown>> {
	id: string;
	data: T;
	edit: EditProxy; // Visual editing annotations
}

Le proxy edit fournit des annotations d’édition visuelle. Répartissez-le sur les éléments pour activer l’édition en ligne : {...entry.edit.title}. En production, cela ne produit aucune sortie.

L’objet data contient tous les champs de contenu plus les champs système :

• id - Identifiant unique
• slug - Identifiant compatible URL
• status - “draft” | “published” | “archived”
• createdAt - Horodatage ISO
• updatedAt - Horodatage ISO
• publishedAt - Horodatage ISO ou null
• Plus tous les champs personnalisés définis dans votre schéma de collection

Système d’aperçu

generatePreviewToken()

Génère un jeton d’aperçu pour le contenu brouillon. L’exemple suivant crée un jeton qui expire dans une heure :

import { generatePreviewToken } from "emdash";

const token = await generatePreviewToken({
	contentId: "posts:01HXK5MZSN...",
	secret: process.env.EMDASH_ADMIN_SECRET,
	expiresIn: 3600, // 1 hour
});

verifyPreviewToken()

Vérifie un jeton d’aperçu et lit sa charge utile :

import { verifyPreviewToken } from "emdash";

const result = await verifyPreviewToken({
	token,
	secret: process.env.EMDASH_ADMIN_SECRET,
});

if (result.valid) {
	const { cid, exp, iat } = result.payload;
	// cid is "collection:id" format, e.g. "posts:my-draft-post"
}

isPreviewRequest()

Vérifie si une requête inclut un jeton d’aperçu, puis le lit :

import { isPreviewRequest, getPreviewToken } from "emdash";

if (isPreviewRequest(Astro.url)) {
	const token = getPreviewToken(Astro.url);
	// Verify and show preview content
}

Convertisseurs de contenu

Conversion entre les formats Portable Text et ProseMirror :

import { prosemirrorToPortableText, portableTextToProsemirror } from "emdash";

// From ProseMirror (editor) to Portable Text (storage)
const portableText = prosemirrorToPortableText(prosemirrorDoc);

// From Portable Text to ProseMirror
const prosemirrorDoc = portableTextToProsemirror(portableText);

Paramètres du site

Lire les paramètres à l’échelle du site avec getSiteSettings et getSiteSetting :

import { getSiteSettings, getSiteSetting } from "emdash";

// Get all settings
const settings = await getSiteSettings();

// Get single setting
const title = await getSiteSetting("title");

Les paramètres sont en lecture seule depuis l’API d’exécution. Utilisez l’API d’administration pour les mettre à jour.

Menus

Récupérer les menus de navigation et itérer sur leurs éléments, y compris les enfants imbriqués :

import { getMenu, getMenus } from "emdash";

// Get all menus
const menus = await getMenus();

// Get specific menu with items
const primaryMenu = await getMenu("primary");

if (primaryMenu) {
	primaryMenu.items.forEach(item => {
		console.log(item.label, item.url);
		// Nested items for dropdowns
		item.children.forEach(child => console.log("  -", child.label));
	});
}

Taxonomies

Récupérer les termes de taxonomie, un terme unique, les termes d’une entrée ou les entrées par terme :

import { getTaxonomyTerms, getTerm, getEntryTerms, getEntriesByTerm } from "emdash";

// Get all terms for a taxonomy (tree structure for hierarchical)
const categories = await getTaxonomyTerms("category");

// Get single term
const news = await getTerm("category", "news");

// Get terms assigned to a content entry
const postCategories = await getEntryTerms("posts", "post-123", "category");

// Get entries with a specific term
const newsPosts = await getEntriesByTerm("posts", "category", "news");

Zones de widgets

Récupérer les zones de widgets et les widgets qu’elles contiennent :

import { getWidgetArea, getWidgetAreas } from "emdash";

// Get all widget areas
const areas = await getWidgetAreas();

// Get specific widget area with widgets
const sidebar = await getWidgetArea("sidebar");

if (sidebar) {
	sidebar.widgets.forEach(widget => {
		console.log(widget.type, widget.title);
	});
}

Sections

Récupérer les sections et les filtrer :

import { getSection, getSections } from "emdash";

// Get all sections (paginated)
const { items, nextCursor } = await getSections();

// Filter sections
const { items: themeSections } = await getSections({ source: "theme" });
const { items: results } = await getSections({ search: "newsletter" });

// Get a single section by slug
const cta = await getSection("newsletter-cta");

getSections(options?) renvoie { items: Section[]; nextCursor?: string }. Les options sont source ("theme" | "user" | "import"), search, limit (par défaut 50, max 100) et cursor.

Recherche

Exécuter une recherche globale dans les collections. Les résultats incluent des extraits mis en surbrillance :

import { search } from "emdash";

const results = await search("hello world", {
	collections: ["posts", "pages"],
	status: "published",
	limit: 20,
});

// search() resolves to { items, nextCursor? }
results.items.forEach(result => {
	console.log(result.title);
	console.log(result.snippet); // Contains <mark> tags
	console.log(result.score);
});

Gestion des erreurs

EmDash exporte des classes d’erreur pour gérer des échecs spécifiques. L’exemple suivant capture les erreurs de validation et de schéma :

import {
  EmDashDatabaseError,
  EmDashValidationError,
  EmDashStorageError,
  SchemaError,
} from "emdash";

try {
  await repo.create({ ... });
} catch (error) {
  if (error instanceof EmDashValidationError) {
    console.error("Validation failed:", error.message);
  }
  if (error instanceof SchemaError) {
    console.error("Schema error:", error.code, error.details);
  }
}