@ventually/ui 0.0.0

package/README.md

@@ -0,0 +1,51 @@
+# `@ventually/ui`
+
+React UI components and a standalone monitor app for Eventually queues.
+
+## Library
+
+Use the dashboard inside your own React app:
+
+```tsx
+import { EventuallyDashboard, EventuallyUIProvider } from "@ventually/ui";
+import "@ventually/ui/styles.css"
+
+export function App() {
+  return (
+    <EventuallyUIProvider endpoint="/api/playground">
+      <EventuallyDashboard />
+    </EventuallyUIProvider>
+  );
+}
+```
+
+## Standalone Monitor
+
+Build the package:
+
+```bash
+bun --filter @ventually/ui build
+```
+
+Start the monitor app:
+
+```bash
+node packages/eventually-ui/dist/cli.js start
+```
+
+By default the app uses `/api/playground` as its backend endpoint. Override it with `--endpoint` to point at your own queue backend:
+
+```bash
+node packages/eventually-ui/dist/cli.js start \
+  --host 127.0.0.1 \
+  --port 3210 \
+  --endpoint https://your-backend.example.com/api/queues
+```
+
+Available flags:
+
+- `--host`: host to bind the local monitor server. Default: `127.0.0.1`
+- `--port`: port to bind the local monitor server. Default: `3210`
+- `--endpoint`: Eventually UI API endpoint used by the React app. Default: `/api/playground`
+
+`start` only serves the built monitor app from `dist/standalone`. It does not create a queue backend server.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+import { createReadStream } from "node:fs";
+import { access, readFile, stat } from "node:fs/promises";
+import { createServer as createHttpServer } from "node:http";
+import { dirname, extname, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 3210;
+const DEFAULT_ENDPOINT = "/api/playground";
+const CONTENT_TYPES = {
+    ".css": "text/css; charset=utf-8",
+    ".html": "text/html; charset=utf-8",
+    ".ico": "image/x-icon",
+    ".jpeg": "image/jpeg",
+    ".jpg": "image/jpeg",
+    ".js": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".png": "image/png",
+    ".svg": "image/svg+xml",
+};
+async function main() {
+    const command = process.argv[2] ?? "start";
+    if (command !== "start") {
+        console.error(`Unsupported command: ${command}`);
+        process.exit(1);
+    }
+    const port = readFlagValue("--port")
+        ? Number(readFlagValue("--port"))
+        : DEFAULT_PORT;
+    const host = readFlagValue("--host") ?? DEFAULT_HOST;
+    const endpoint = readFlagValue("--endpoint") ?? DEFAULT_ENDPOINT;
+    const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+    const standaloneRoot = resolve(packageRoot, "dist/standalone");
+    const standaloneIndexPath = resolve(standaloneRoot, "index.html");
+    await assertStandaloneBuildArtifacts(standaloneRoot, standaloneIndexPath);
+    const server = createHttpServer(async (request, response) => {
+        if (!request.url) {
+            response.statusCode = 400;
+            response.end("Missing URL");
+            return;
+        }
+        const requestPathname = readPathname(request.url);
+        if (!requestPathname) {
+            response.statusCode = 400;
+            response.end("Invalid URL");
+            return;
+        }
+        if (requestPathname.startsWith("/api/")) {
+            response.statusCode = 404;
+            response.end("Not found");
+            return;
+        }
+        await serveStandaloneAsset(request.url, response, {
+            endpoint,
+            standaloneRoot,
+            standaloneIndexPath,
+        });
+    });
+    server.listen(port, host, () => {
+        console.log(`@ventually/ui listening on http://${host}:${port} (endpoint: ${endpoint})`);
+    });
+}
+async function assertStandaloneBuildArtifacts(standaloneRoot, standaloneIndexPath) {
+    try {
+        const [rootStats, indexStats] = await Promise.all([
+            stat(standaloneRoot),
+            stat(standaloneIndexPath),
+        ]);
+        if (!rootStats.isDirectory() || !indexStats.isFile()) {
+            throw new Error("Standalone build artifacts missing");
+        }
+    }
+    catch {
+        console.error(`@ventually/ui standalone build artifacts not found at ${standaloneRoot}.\nRun \`bun --filter @ventually/ui build:standalone\` and try again.`);
+        process.exit(1);
+    }
+}
+async function serveStandaloneAsset(rawUrl, response, paths) {
+    const pathname = readPathname(rawUrl);
+    if (!pathname) {
+        response.statusCode = 400;
+        response.end("Invalid URL");
+        return;
+    }
+    const requestedPath = pathname === "/" ? paths.standaloneIndexPath : resolve(paths.standaloneRoot, `.${pathname}`);
+    if (!isPathInsideRoot(paths.standaloneRoot, requestedPath)) {
+        response.statusCode = 404;
+        response.end("Not found");
+        return;
+    }
+    const requestedStats = await safeStat(requestedPath);
+    if (requestedStats?.isFile()) {
+        if (requestedPath === paths.standaloneIndexPath) {
+            await serveInjectedIndexHtml(paths.standaloneIndexPath, paths.endpoint, response);
+            return;
+        }
+        await streamFile(requestedPath, response);
+        return;
+    }
+    if (extname(pathname)) {
+        response.statusCode = 404;
+        response.end("Not found");
+        return;
+    }
+    await serveInjectedIndexHtml(paths.standaloneIndexPath, paths.endpoint, response);
+}
+function readFlagValue(flag) {
+    const flagIndex = process.argv.indexOf(flag);
+    const value = flagIndex >= 0 ? process.argv[flagIndex + 1] : undefined;
+    return value ? value : null;
+}
+function isPathInsideRoot(root, path) {
+    const relativePath = relative(root, path);
+    return (relativePath === "" ||
+        (!relativePath.startsWith(`..${sep}`) &&
+            relativePath !== ".." &&
+            !relativePath.includes(`${sep}..${sep}`)));
+}
+async function safeStat(path) {
+    try {
+        return await stat(path);
+    }
+    catch {
+        return null;
+    }
+}
+async function streamFile(path, response) {
+    await access(path);
+    response.statusCode = 200;
+    response.setHeader("content-type", contentTypeForPath(path));
+    await new Promise((resolvePromise, rejectPromise) => {
+        const stream = createReadStream(path);
+        stream.on("error", rejectPromise);
+        response.on("finish", resolvePromise);
+        response.on("close", resolvePromise);
+        stream.pipe(response);
+    });
+}
+async function serveInjectedIndexHtml(path, endpoint, response) {
+    const html = await readFile(path, "utf8");
+    response.statusCode = 200;
+    response.setHeader("content-type", "text/html; charset=utf-8");
+    response.end(injectEndpointIntoHtml(html, endpoint));
+}
+function contentTypeForPath(path) {
+    return CONTENT_TYPES[extname(path).toLowerCase()] ?? "application/octet-stream";
+}
+function injectEndpointIntoHtml(html, endpoint) {
+    const configScript = `<script>window.__EVENTUALLY_UI_ENDPOINT__=${JSON.stringify(endpoint)};</script>`;
+    return html.includes("</head>")
+        ? html.replace("</head>", `${configScript}</head>`)
+        : `${configScript}${html}`;
+}
+function readPathname(rawUrl) {
+    try {
+        return decodeURIComponent(new URL(rawUrl, "http://localhost").pathname);
+    }
+    catch {
+        return null;
+    }
+}
+void main();

package/dist/context.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from "react";
+import type { EventuallyUIAction, EventuallyUISnapshot } from "./types.js";
+interface EventuallyUIContextValue {
+    endpoint: string;
+    error: string | null;
+    pending: string | null;
+    snapshot: EventuallyUISnapshot | null;
+    stale: boolean;
+    refresh(): Promise<void>;
+    perform(action: EventuallyUIAction, label?: string): Promise<void>;
+}
+export declare function EventuallyUIProvider({ children, endpoint, refreshInterval, initialSnapshot, }: {
+    children: ReactNode;
+    endpoint?: string;
+    refreshInterval?: number;
+    initialSnapshot?: EventuallyUISnapshot | null;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useEventuallyUI(): EventuallyUIContextValue;
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE3E,UAAU,wBAAwB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAMD,wBAAgB,oBAAoB,CAAC,EACnC,QAAQ,EACR,QAAiD,EACjD,eAAsB,EACtB,eAAsB,GACvB,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC/C,2CAmFA;AAED,wBAAgB,eAAe,6BAQ9B"}

package/dist/context.js

@@ -0,0 +1,76 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, startTransition, useContext, useEffect, useMemo, useState, } from "react";
+const EventuallyUIContext = createContext(null);
+export function EventuallyUIProvider({ children, endpoint = "http://localhost:3210/api/playground", refreshInterval = 1200, initialSnapshot = null, }) {
+    const [snapshot, setSnapshot] = useState(initialSnapshot);
+    const [error, setError] = useState(null);
+    const [pending, setPending] = useState(null);
+    async function refresh() {
+        const response = await fetch(endpoint, { cache: "no-store" });
+        if (!response.ok) {
+            throw new Error(`Eventually UI refresh failed with ${response.status}`);
+        }
+        const next = (await response.json());
+        setError(null);
+        startTransition(() => {
+            setSnapshot(next);
+        });
+    }
+    async function perform(action, label = action.action) {
+        setPending(label);
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify(action),
+            });
+            if (!response.ok) {
+                throw new Error(`Eventually UI action failed with ${response.status}`);
+            }
+            const next = (await response.json());
+            setError(null);
+            startTransition(() => {
+                setSnapshot(next);
+            });
+        }
+        catch (error) {
+            setError(error instanceof Error ? error.message : "Eventually UI request failed");
+            throw error;
+        }
+        finally {
+            setPending(null);
+        }
+    }
+    useEffect(() => {
+        void refresh().catch((error) => {
+            setError(error instanceof Error ? error.message : "Eventually UI refresh failed");
+        });
+        const timer = window.setInterval(() => {
+            void refresh().catch((error) => {
+                setError(error instanceof Error
+                    ? error.message
+                    : "Eventually UI refresh failed");
+            });
+        }, refreshInterval);
+        return () => window.clearInterval(timer);
+    }, [endpoint, refreshInterval]);
+    const value = useMemo(() => ({
+        endpoint,
+        error,
+        pending,
+        snapshot,
+        stale: error !== null,
+        refresh,
+        perform,
+    }), [endpoint, error, pending, snapshot]);
+    return (_jsx(EventuallyUIContext.Provider, { value: value, children: children }));
+}
+export function useEventuallyUI() {
+    const context = useContext(EventuallyUIContext);
+    if (!context) {
+        throw new Error("useEventuallyUI must be used inside EventuallyUIProvider.");
+    }
+    return context;
+}

package/dist/context.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.test.d.ts.map

package/dist/context.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.test.d.ts","sourceRoot":"","sources":["../src/context.test.tsx"],"names":[],"mappings":""}

package/dist/context.test.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// @vitest-environment jsdom
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { EventuallyUIProvider, useEventuallyUI } from "./context.js";
+function Probe() {
+    const { error, stale } = useEventuallyUI();
+    return (_jsxs("div", { children: [_jsx("span", { "data-testid": "stale", children: String(stale) }), _jsx("span", { "data-testid": "error", children: error ?? "none" })] }));
+}
+describe("EventuallyUIProvider", () => {
+    afterEach(() => {
+        cleanup();
+        vi.unstubAllGlobals();
+    });
+    it("surfaces refresh failures to consumers", async () => {
+        vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
+            ok: false,
+            status: 503,
+        }));
+        render(_jsx(EventuallyUIProvider, { endpoint: "/api/playground", refreshInterval: 10_000, children: _jsx(Probe, {}) }));
+        await waitFor(() => {
+            expect(screen.getByTestId("stale").textContent).toBe("true");
+            expect(screen.getByTestId("error").textContent).toBe("Eventually UI refresh failed with 503");
+        });
+    });
+});

package/dist/dashboard.d.ts

@@ -0,0 +1,3 @@
+import "./index.css";
+export declare function EventuallyDashboard(): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=dashboard.d.ts.map

package/dist/dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../src/dashboard.tsx"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAC;AAkUrB,wBAAgB,mBAAmB,4CAggBlC"}