@playfast/reform-remote-node 1.0.1 → 1.1.0

package/package.json

@@ -1,36 +1,38 @@
 {
   "name": "@playfast/reform-remote-node",
-  "playbook": "./playbook",
-  "version": "1.0.1",
-  "type": "module",
+  "version": "1.1.0",
   "description": "Node WebSocket server adapter for reform-remote — serves a reform scene's UI over the `ws` package, one isolated runtime per connection.",
   "keywords": [
-    "reform",
     "effect",
-    "websocket",
-    "remote",
     "node",
-    "server"
+    "reform",
+    "remote",
+    "server",
+    "websocket"
   ],
+  "bugs": {
+    "url": "https://github.com/playfast/reform/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/playfast/reform.git",
     "directory": "packages/reform-remote-node"
   },
-  "bugs": {
-    "url": "https://github.com/playfast/reform/issues"
-  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
   "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
     ".": "./src/index.ts",
     "./*": "./src/*.ts"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "clean": "rm -rf dist .tsbuildinfo",
     "check": "tsc --noEmit",
@@ -44,16 +46,14 @@
   "dependencies": {
     "ws": "^8.18.0"
   },
-  "peerDependencies": {
-    "effect": "*",
-    "react": "^19.0.0",
-    "@playfast/reform": "*",
-    "@playfast/reform-remote": "*"
-  },
   "devDependencies": {
     "@types/ws": "^8.5.13"
   },
-  "publishConfig": {
-    "access": "public"
-  }
+  "peerDependencies": {
+    "@playfast/reform": "*",
+    "@playfast/reform-remote": "*",
+    "effect": "*",
+    "react": "^19.0.0"
+  },
+  "playbook": "./playbook"
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 import type { Server } from 'node:http'
+import { Schema } from 'effect'
 import { type RawData, WebSocketServer } from 'ws'
-import type { Scene } from '@playfast/reform'
+import type { AnyScene } from '@playfast/reform/internal'
 import {
   type InvokeMessage,
   type RemoteTransport,
@@ -8,53 +9,84 @@ import {
   serveShared,
 } from '@playfast/reform-remote'
 
-/**
- * @playfast/reform-remote-node — serve a reform scene's UI over WebSocket from a
- * Node process, using the `ws` package. The scene runs ONCE as a single shared
- * runtime (`serveShared`); every connection attaches to it via `addClient`, so all
- * clients see and drive the same state. Sockets are wrapped with JSON framing: the
- * already-`_tag`-discriminated wire messages need no envelope. The Bun-native
- * equivalent is `@playfast/reform-remote-bun`; the browser/web client is
- * `@playfast/reform-remote-web`.
- */
-
 export interface NodeWebSocketOptionsExternalApi {
-  /** The scene to run — ONE shared runtime that every connection attaches to. */
-  readonly scene: Scene
-  /** Listen on this port (use `0` for an ephemeral port; read it back from `wss.address()`). */
+  readonly scene: AnyScene
   readonly port?: number
-  /** Attach to an existing HTTP server instead of opening a port. */
   readonly server?: Server
-  /** Restrict upgrades to this path. */
   readonly path?: string
 }
 
 export interface NodeWebSocketServer {
-  /** The underlying `ws` server — for reading the bound address, or further config. */
   readonly wss: WebSocketServer
-  /** Dispose the shared runtime and close the server. */
   readonly stop: () => Promise<void>
 }
 
-const parseInvoke = (frame: RawData): InvokeMessage =>
-  // oxlint-disable-next-line reform-rules/no-json-parse-stringify, reform-rules/no-type-assertion -- wire frame decode; InvokeMessage is a structural type with no Schema here
-  JSON.parse(frame.toString()) as InvokeMessage
+const WirePropSchema = Schema.Union(
+  Schema.Struct({
+    _tag: Schema.Literal('Data'),
+    name: Schema.String,
+    value: Schema.Unknown,
+  }),
+  Schema.Struct({
+    _tag: Schema.Literal('Event'),
+    name: Schema.String,
+    handle: Schema.String,
+  }),
+)
+const WireNodeSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  parentId: Schema.NullOr(Schema.String),
+  childIndex: Schema.Number,
+  slot: Schema.NullOr(Schema.String),
+  key: Schema.NullOr(Schema.String),
+  props: Schema.Array(WirePropSchema),
+})
+const WirePatchSchema = Schema.Union(
+  Schema.Struct({ _tag: Schema.Literal('Upsert'), node: WireNodeSchema }),
+  Schema.Struct({ _tag: Schema.Literal('Delete'), id: Schema.String }),
+)
+const InvokeMessageJson: Schema.Schema<InvokeMessage, string, never> = Schema.parseJson(
+  Schema.Struct({
+    _tag: Schema.Literal('Invoke'),
+    handle: Schema.String,
+    payload: Schema.Unknown,
+  }),
+)
+const ServerMessageJson: Schema.Schema<ServerMessage, string, never> = Schema.parseJson(
+  Schema.Union(
+    Schema.Struct({
+      _tag: Schema.Literal('Snapshot'),
+      tree: Schema.Array(WireNodeSchema),
+    }),
+    Schema.Struct({
+      _tag: Schema.Literal('Patches'),
+      patches: Schema.Array(WirePatchSchema),
+    }),
+  ),
+)
+const decodeInvokeMessage: (input: unknown) => InvokeMessage =
+  Schema.decodeUnknownSync(InvokeMessageJson)
+const encodeServerMessage: (message: ServerMessage) => string = Schema.encodeSync(ServerMessageJson)
+
+const parseInvoke = (frame: RawData): InvokeMessage => decodeInvokeMessage(frame.toString())
 
-export const serveNodeWebSocket = (options: NodeWebSocketOptionsExternalApi): NodeWebSocketServer => {
-  const wss =
+export const serveNodeWebSocket = (
+  options: NodeWebSocketOptionsExternalApi,
+): NodeWebSocketServer => {
+  const serverConfig =
     options.server !== undefined
-      ? new WebSocketServer({ server: options.server, path: options.path })
-      : new WebSocketServer({ port: options.port === undefined ? 0 : options.port, path: options.path })
+      ? { server: options.server, path: options.path }
+      : { port: options.port === undefined ? 0 : options.port, path: options.path }
+  const wss = new WebSocketServer(serverConfig)
 
-  // One shared runtime for the whole server; every socket attaches to it.
   const shared = serveShared({ scene: options.scene })
 
   wss.on('connection', (socket) => {
     const handlers = new Set<(message: InvokeMessage) => void>()
     const transport: RemoteTransport<ServerMessage, InvokeMessage> = {
-      // oxlint-disable-next-line reform-rules/no-json-parse-stringify -- wire frame encode; ServerMessage is a structural type with no Schema here
-      send: (message) => socket.send(JSON.stringify(message)),
-      onMessage: (handler) => {
+      send: (message: ServerMessage): void => void socket.send(encodeServerMessage(message)),
+      onMessage: (handler: (message: InvokeMessage) => void): (() => void) => {
         handlers.add(handler)
         return () => void handlers.delete(handler)
       },
@@ -72,8 +104,7 @@ export const serveNodeWebSocket = (options: NodeWebSocketOptionsExternalApi): No
     wss,
     stop: async (): Promise<void> => {
       await shared.dispose()
-      // Terminate live sockets so `wss.close` doesn't block waiting for them to
-      // drain on their own — `close` only fires its callback once all are gone.
+      // `wss.close` waits for live sockets to drain.
       wss.clients.forEach((client) => client.terminate())
       await new Promise<void>((resolve, reject) =>
         wss.close((error) => (error === undefined ? resolve() : reject(error))),

package/src/server.test.ts

@@ -2,8 +2,7 @@ import type { AddressInfo } from 'node:net'
 import { afterEach, expect, test, vi } from 'vitest'
 import { Layer, Schema as S } from 'effect'
 
-// Real loopback socket I/O: headroom so the full parallel suite can't starve it past
-// the 5s default (passes fast in isolation; 30s still fails a genuine hang).
+// Real loopback I/O: headroom so parallel suite can't starve past 5s default.
 vi.setConfig({ testTimeout: 30_000, hookTimeout: 30_000 })
 import {
   Composition,
@@ -13,18 +12,16 @@ import {
   State,
   StateGroup,
   Ui,
-  Wire,
   mount,
   provide,
   scene,
   ui,
 } from '@playfast/reform'
-import type { WireNode, WireProp } from '@playfast/reform'
+import { Wire } from '@playfast/reform/internal'
+import type { WireNode, WireProp } from '@playfast/reform/internal'
 import type { ServerMessage } from '@playfast/reform-remote'
 import { type NodeWebSocketServer, serveNodeWebSocket } from './index'
 
-// A self-contained counter scene (the adapter packages stay independent of the
-// core package's test fixtures, which aren't part of its public surface).
 class Count extends State.make('count', S.Number) {}
 class Counters extends StateGroup.make(Count) {}
 class Bumped extends Event.make('Bumped', S.Struct({ by: S.Number })) {}
@@ -33,11 +30,19 @@ class CounterUi extends ui('Counter', {
   props: S.Struct({ count: S.Number }),
   events: { bump: S.Struct({ by: S.Number }) },
 }) {}
-class Counter extends Composition.make('Counter', { title: 'Counter', ui: CounterUi, states: [Count] }) {}
+
+class Counter extends Composition.make('Counter', {
+  title: 'Counter',
+  ui: CounterUi,
+  states: [Count],
+})<Counter>() {}
 
 const counterScene = () => {
   const presentation = Layer.mergeAll(
-    provide(CounterUi, Ui.make(CounterUi, ({ count }) => `count:${count}`)),
+    provide(
+      CounterUi,
+      Ui.make(CounterUi, ({ count }) => `count:${count}`),
+    ),
     StateGroup.live(Counters, { count: 0 }),
   )
   const app = Layer.mergeAll(
@@ -111,9 +116,7 @@ test('every connection shares ONE runtime — a bump on one socket reaches the o
   open.add(host)
   const port = await listening(host)
 
-  // Attach every listener BEFORE awaiting: the shared server snapshots a new client
-  // off its pre-rendered baseline immediately, so a lazily-attached listener could miss
-  // the frame (a real `connect()` client registers its handler synchronously).
+  // Attach listeners before await: shared server snapshots immediately; lazy attach can miss the frame.
   const a = new WebSocket(`ws://localhost:${port}`)
   const snapAP = nextMessage(a, (m) => m._tag === 'Snapshot')
   const b = new WebSocket(`ws://localhost:${port}`)
@@ -122,7 +125,6 @@ test('every connection shares ONE runtime — a bump on one socket reaches the o
     const snapA = await snapAP
     const snapB = await snapBP
 
-    // a bumps; BOTH a and b receive the broadcast diff off the shared runtime.
     const frameAP = nextMessage(a, (m) => m._tag === 'Patches')
     const frameBP = nextMessage(b, (m) => m._tag === 'Patches')
     a.send(JSON.stringify({ _tag: 'Invoke', handle: '0:bump', payload: { by: 4 } }))
@@ -139,7 +141,6 @@ test('every connection shares ONE runtime — a bump on one socket reaches the o
     )
     expect(countOf(treeA[0]!)).toBe(4)
     expect(countOf(treeB[0]!)).toBe(4)
-    // A late joiner snapshots the CURRENT shared count (4), not a fresh 0.
     const c = new WebSocket(`ws://localhost:${port}`)
     const snapC = await nextMessage(c, (m) => m._tag === 'Snapshot')
     expect(countOf((snapC._tag === 'Snapshot' ? snapC.tree : [])[0]!)).toBe(4)