@iadev93/zuno-express 0.0.1

package/README.md

@@ -0,0 +1,56 @@
+# @iadev93/zuno-express
+
+Express adapter for **Zuno**.
+
+Provides server‑side synchronization endpoints using Server‑Sent Events (SSE).
+
+---
+
+## Install
+
+```bash
+npm install @iadev93/zuno-express
+```
+
+Peer dependency:
+
+* `express >= 4`
+
+---
+
+## Usage
+
+```ts
+import express from "express";
+import { createZunoExpress } from "@iadev93/zuno-express";
+import { createZuno } from "@iadev93/zuno";
+
+const app = express();
+const zuno = createZuno();
+
+createZunoExpress(app, { zuno });
+
+app.listen(3000);
+```
+
+---
+
+## What It Provides
+
+* SSE endpoint for state sync
+* Snapshot delivery
+* Version‑safe event ingestion
+
+---
+
+## What It Does NOT Do
+
+* No WebSockets
+* No framework‑specific state
+* No persistence layer
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@iadev93/zuno-express",
+  "version": "0.0.1",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "@iadev93/zuno": "workspace:*",
+    "express": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.9.3",
+    "@iadev93/zuno": "workspace:*"
+  }
+}

package/src/createZunoExpress.ts

@@ -0,0 +1,36 @@
+import type { IncomingHttpHeaders } from "http"
+import { createExpressSSEHandler } from "./express-sse-handler"
+import { createExpressSyncHandler } from "./express-sync-handler"
+import { createExpressSnapshotHandler } from "./express-snapshot-handler"
+
+/**
+ * Options for creating an Express router for Zuno.
+ */
+type CreateZunoExpressOptions = {
+  headers?: IncomingHttpHeaders
+}
+
+/**
+ * Creates an Express router for Zuno.
+ *
+ * @param opts - Options for creating the Express router.
+ * @returns An object containing the SSE, sync, and snapshot handlers
+ */
+export function createZunoExpress(opts?: CreateZunoExpressOptions) {
+  const { headers } = opts ?? {}
+
+  return {
+    /**
+     * Handles SSE connections.
+     */
+    sse: createExpressSSEHandler(headers),
+    /**
+     * Handles sync connections.
+     */
+    sync: createExpressSyncHandler(),
+    /**
+     * Handles snapshot connections.
+     */
+    snapshot: createExpressSnapshotHandler(),
+  }
+}

package/src/express-snapshot-handler.ts

@@ -0,0 +1,10 @@
+import type { Request, Response } from "express"
+import { sendSnapshot } from "@iadev93/zuno/server"
+
+/**
+ * Creates an Express handler for handling Zuno state events.
+ * @returns An Express handler function.
+ */
+export function createExpressSnapshotHandler() {
+  return (req: Request, res: Response) => sendSnapshot(req, res)
+}

package/src/express-sse-handler.ts

@@ -0,0 +1,15 @@
+import type { Request, Response } from "express"
+import type { IncomingHttpHeaders } from "http";
+
+import { createSSEConnection } from "@iadev93/zuno/server";
+
+/**
+ * Creates an SSE handler for express.
+ * @returns An Express handler function.
+ */
+export function createExpressSSEHandler(headers?: IncomingHttpHeaders) {
+  /**
+   * Creates an SSE connection for the client.
+   */
+  return (req: Request, res: Response) => createSSEConnection(req, res, headers ?? {})
+}

package/src/express-sync-handler.ts

@@ -0,0 +1,30 @@
+import type { Request, Response } from "express"
+import type { ZunoStateEvent } from "@iadev93/zuno"
+
+import { applyStateEvent } from "@iadev93/zuno/server"
+
+/**
+ * Creates an Express handler for handling Zuno state events.
+ * @returns An Express handler function.
+ */
+export function createExpressSyncHandler() {
+  return (req: Request, res: Response) => {
+    /** The incoming state event to apply. */
+    const incoming = req.body as ZunoStateEvent
+
+    /** Applies the incoming state event to the target Zuno universe or store. */
+    const result = applyStateEvent(incoming)
+
+    /** If the state event is not valid, returns a 409 status code with the reason and current state. */
+    if (!result.ok) {
+      res.status(409).json({
+        reason: result.reason,
+        current: result.current,
+      })
+      return
+    }
+
+    /** Returns a 200 status code with the result. */
+    res.status(200).json({ ok: true, event: result.event })
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './createZunoExpress';

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": false,
+    "module": "ESNext",
+    "moduleResolution": "Bundler"
+  },
+  "include": [
+    "./src/**/*.ts"
+  ]
+}