@arcanejs/protocol 0.7.0 → 0.8.0

package/README.md

@@ -1,43 +1,108 @@
-# `@arcanejs/diff`
+# `@arcanejs/protocol`
 
-[![NPM Version](https://img.shields.io/npm/v/%40arcanejs%2Fdiff)](https://www.npmjs.com/package/@arcanejs/diff)
+[![NPM Version](https://img.shields.io/npm/v/%40arcanejs%2Fprotocol)](https://www.npmjs.com/package/@arcanejs/protocol)
 
-This package provides an easy way to:
+TypeScript protocol contracts for ArcaneJS.
 
-- Create diffs by comparing objects
-- Update objects by applying diffs
+This package defines the shared wire/message types used between:
 
-This library is written in TypeScript,
-and produces diffs that are type-safe,
-and can only be applied to objects that match the type
-of the objects being compared.
+- ArcaneJS server runtime (`@arcanejs/toolkit`)
+- Browser frontend stage (`@arcanejs/toolkit/frontend` + `@arcanejs/toolkit-frontend`)
+- Custom extensions (custom namespaces/components)
 
-This package is part of the
-[`arcanejs` project](https://github.com/ArcaneWizards/arcanejs#arcanejs),
-and is used to maintain a copy of a JSON tree in downstream clients in real-time
-via websockets.
+## Install
 
-## Usage
+```bash
+npm install @arcanejs/protocol
+```
+
+## What It Defines
+
+## Base protocol (`@arcanejs/protocol`)
+
+- Base component envelope (`BaseComponentProto`, `AnyComponentProto`)
+- Server messages:
+  - `metadata`
+  - `tree-full`
+  - `tree-diff`
+  - `call-response`
+  - `pong`
+- Client messages:
+  - `component-message`
+  - `component-call`
+  - `ping`
+- Type helpers for call/response pair typing:
+  - `BaseClientComponentCallPair`
+  - `CallForPair`
+  - `ReturnForPair`
+
+## Core namespace (`@arcanejs/protocol/core`)
+
+Core component protocol types and guards:
+
+- Component types: `ButtonComponent`, `GroupComponent`, `LabelComponent`, `RectComponent`, `SliderButtonComponent`, `SwitchComponent`, `TabComponent`, `TabsComponent`, `TextInputComponent`, `TimelineComponent`
+- Message types: `CoreComponentMessage` and specific message variants
+- Call type map: `CoreComponentCalls`
+- Guards:
+  - `isCoreComponent(...)`
+  - `isCoreComponentMessage(...)`
+  - `isCoreComponentCall(...)`
+
+## Supporting modules
+
+- `@arcanejs/protocol/styles`: shared style contracts (`GroupComponentStyle`, `LabelComponentStyle`)
+- `@arcanejs/protocol/logging`: logger contract (`Logger`)
+
+## Usage Example
 
 ```ts
-import { diffJson, Diff } from '@arcanejs/diff/diff';
-import { patchJson } from '@arcanejs/diff/patch';
+import type {
+  ServerMessage,
+  ClientMessage,
+  BaseComponentProto,
+  CallForPair,
+  ReturnForPair,
+} from '@arcanejs/protocol';
+
+import type {
+  CoreComponentCalls,
+  CoreComponentMessage,
+} from '@arcanejs/protocol/core';
+
+const onServerMessage = (msg: ServerMessage) => {
+  if (msg.type === 'tree-full') {
+    const root: BaseComponentProto<string, string> = msg.root;
+    console.log(root.namespace, root.component);
+  }
+};
 
-type E = {
-  foo: string;
-  bar?: number[];
+const message: CoreComponentMessage = {
+  type: 'component-message',
+  namespace: 'core',
+  componentKey: 1,
+  component: 'switch',
 };
 
-const a: E = { foo: 'bar' };
-const b: E = { foo: 'baz', bar: [1] };
+const callMessage: CallForPair<'core', CoreComponentCalls, 'press'> = {
+  type: 'component-call',
+  namespace: 'core',
+  componentKey: 5,
+  action: 'press',
+};
+
+type PressReturn = ReturnForPair<CoreComponentCalls, 'press'>; // true
+const _resultExample: PressReturn = true;
 
-const diffA: Diff<E> = diffJson(a, b);
+const _clientMessage: ClientMessage = message;
+```
 
-const resultA = patchJson(a, diffA);
+## Notes
 
-console.log(resultB); // { foo: 'baz', bar: [1] }
+- This package is primarily type contracts and guard helpers.
+- `tree-diff` payloads use `Diff<...>` from `@arcanejs/diff`.
+- `ping`/`pong` can be used for browser/server clock sync. `pong` includes `serverTimeMillis`.
+- Custom namespaces should follow the same pattern as `core`: define component proto types, message/call unions, and guard helpers.
 
-const c = { baz: 'foo' };
+## Example Reference
 
-const resultB = patchJson(c, diffA); // TypeScript Type Error: Property 'baz' is missing in type '{ foo: string; bar?: number[] | undefined; }' but required in type '{ baz: string; }'
-```
+- Custom protocol implementation example: <https://github.com/ArcaneWizards/arcanejs/blob/main/examples/custom-components/src/custom-proto.ts>

package/dist/index.d.mts

@@ -12,6 +12,12 @@ type MetadataMessage = {
      * The UUID for the current connection
      */
     connectionUuid: string;
+    clockSync: {
+        /**
+         * How often the frontend should send ping requests.
+         */
+        pingIntervalMs: number;
+    } | null;
 };
 type SendTreeMsg = {
     type: 'tree-full';
@@ -32,7 +38,15 @@ type CallResponseMsg<Namespace extends string, T> = {
     success: false;
     errorMessage: string;
 });
-type ServerMessage = MetadataMessage | SendTreeMsg | UpdateTreeMsg | CallResponseMsg<string, unknown>;
+type PongResponseMessage = {
+    type: 'pong';
+    pingId: number;
+    /**
+     * Server clock time in milliseconds.
+     */
+    serverTimeMillis: number;
+};
+type ServerMessage = MetadataMessage | SendTreeMsg | UpdateTreeMsg | CallResponseMsg<string, unknown> | PongResponseMessage;
 type BaseClientComponentMessage<Namespace extends string> = {
     type: 'component-message';
     namespace: Namespace;
@@ -57,6 +71,10 @@ type ReturnForPair<Pairs, Action extends string & keyof Pairs> = Pairs extends R
 }> ? R : never;
 type AnyClientComponentMessage = BaseClientComponentMessage<string>;
 type AnyClientComponentCall = BaseClientComponentCall<string, string>;
-type ClientMessage = AnyClientComponentMessage | AnyClientComponentCall;
+type PingRequestMessage = {
+    type: 'ping';
+    pingId: number;
+};
+type ClientMessage = AnyClientComponentMessage | AnyClientComponentCall | PingRequestMessage;
 
-export type { AnyClientComponentCall, AnyClientComponentMessage, AnyComponentProto, BaseClientComponentCall, BaseClientComponentCallPair, BaseClientComponentMessage, BaseComponentProto, CallForPair, CallResponseMsg, ClientMessage, MetadataMessage, ReturnForPair, SendTreeMsg, ServerMessage, UpdateTreeMsg };
+export type { AnyClientComponentCall, AnyClientComponentMessage, AnyComponentProto, BaseClientComponentCall, BaseClientComponentCallPair, BaseClientComponentMessage, BaseComponentProto, CallForPair, CallResponseMsg, ClientMessage, MetadataMessage, PingRequestMessage, PongResponseMessage, ReturnForPair, SendTreeMsg, ServerMessage, UpdateTreeMsg };

package/dist/index.d.ts

@@ -12,6 +12,12 @@ type MetadataMessage = {
      * The UUID for the current connection
      */
     connectionUuid: string;
+    clockSync: {
+        /**
+         * How often the frontend should send ping requests.
+         */
+        pingIntervalMs: number;
+    } | null;
 };
 type SendTreeMsg = {
     type: 'tree-full';
@@ -32,7 +38,15 @@ type CallResponseMsg<Namespace extends string, T> = {
     success: false;
     errorMessage: string;
 });
-type ServerMessage = MetadataMessage | SendTreeMsg | UpdateTreeMsg | CallResponseMsg<string, unknown>;
+type PongResponseMessage = {
+    type: 'pong';
+    pingId: number;
+    /**
+     * Server clock time in milliseconds.
+     */
+    serverTimeMillis: number;
+};
+type ServerMessage = MetadataMessage | SendTreeMsg | UpdateTreeMsg | CallResponseMsg<string, unknown> | PongResponseMessage;
 type BaseClientComponentMessage<Namespace extends string> = {
     type: 'component-message';
     namespace: Namespace;
@@ -57,6 +71,10 @@ type ReturnForPair<Pairs, Action extends string & keyof Pairs> = Pairs extends R
 }> ? R : never;
 type AnyClientComponentMessage = BaseClientComponentMessage<string>;
 type AnyClientComponentCall = BaseClientComponentCall<string, string>;
-type ClientMessage = AnyClientComponentMessage | AnyClientComponentCall;
+type PingRequestMessage = {
+    type: 'ping';
+    pingId: number;
+};
+type ClientMessage = AnyClientComponentMessage | AnyClientComponentCall | PingRequestMessage;
 
-export type { AnyClientComponentCall, AnyClientComponentMessage, AnyComponentProto, BaseClientComponentCall, BaseClientComponentCallPair, BaseClientComponentMessage, BaseComponentProto, CallForPair, CallResponseMsg, ClientMessage, MetadataMessage, ReturnForPair, SendTreeMsg, ServerMessage, UpdateTreeMsg };
+export type { AnyClientComponentCall, AnyClientComponentMessage, AnyComponentProto, BaseClientComponentCall, BaseClientComponentCallPair, BaseClientComponentMessage, BaseComponentProto, CallForPair, CallResponseMsg, ClientMessage, MetadataMessage, PingRequestMessage, PongResponseMessage, ReturnForPair, SendTreeMsg, ServerMessage, UpdateTreeMsg };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcanejs/protocol",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": false,
   "description": "The JSON protocol types for the @arcanejs Toolkit",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@arcanejs/diff": "^0.5.1"
+    "@arcanejs/diff": "^0.5.2"
   },
   "devDependencies": {
     "@types/eslint": "^8.56.5",