XEMS Usage Guide

XEMS provides two primary abstraction layers: high-level session management via the xLink API and low-level storage via the fluent xems storage API.

High-Level Session Management

The xLink API is the recommended way to manage user authentication. It handles token generation, secure cookie injection, and automatic rotation.

app.post("/login", async (req, res) => {
    // Link session data to the client
    await res.xLink({ userId: "123", role: "admin" });
    res.json({ success: true });
});

app.get("/profile", (req, res) => {
    if (!req.session) return res.status(401).send("Unauthorized");
    
    const { userId, role } = req.session;
    res.json({ userId, role });
});

app.post("/logout", async (req, res) => {
    await res.xUnlink();
    res.json({ success: true });
});

Low-Level Storage (Fluent API)

The xems API provides direct access to the encrypted storage engine, allowing you to store temporary data in specific sandboxes.

import { xems } from "xypriss";

const xdb = await xems.from("cache");

// Set a value with 10-minute TTL
await xdb.set("query_result", { data: [...] }, "10m");

// Get and auto-decrypt
const result = await xdb.get("query_result");

// Delete
await xdb.del("query_result");

Multi-Server Context

Inside a route handler, always use the app instance from the request to ensure you are interacting with the correct XEMS connection.

app.get("/data", async (req, res) => {
    const runner = xems.forApp(req.app);
    const result = await runner.from("system").get("metadata");
});