@arcanejs/protocol 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +92 -27
  2. package/dist/core.d.mts +2 -2
  3. package/dist/core.d.ts +2 -2
  4. package/dist/index.d.mts +42 -3
  5. package/dist/index.d.ts +42 -3
  6. package/package.json +3 -3
package/README.md CHANGED
@@ -1,43 +1,108 @@
1
- # `@arcanejs/diff`
1
+ # `@arcanejs/protocol`
2
2
 
3
- [![NPM Version](https://img.shields.io/npm/v/%40arcanejs%2Fdiff)](https://www.npmjs.com/package/@arcanejs/diff)
3
+ [![NPM Version](https://img.shields.io/npm/v/%40arcanejs%2Fprotocol)](https://www.npmjs.com/package/@arcanejs/protocol)
4
4
 
5
- This package provides an easy way to:
5
+ TypeScript protocol contracts for ArcaneJS.
6
6
 
7
- - Create diffs by comparing objects
8
- - Update objects by applying diffs
7
+ This package defines the shared wire/message types used between:
9
8
 
10
- This library is written in TypeScript,
11
- and produces diffs that are type-safe,
12
- and can only be applied to objects that match the type
13
- of the objects being compared.
9
+ - ArcaneJS server runtime (`@arcanejs/toolkit`)
10
+ - Browser frontend stage (`@arcanejs/toolkit/frontend` + `@arcanejs/toolkit-frontend`)
11
+ - Custom extensions (custom namespaces/components)
14
12
 
15
- This package is part of the
16
- [`arcanejs` project](https://github.com/ArcaneWizards/arcanejs#arcanejs),
17
- and is used to maintain a copy of a JSON tree in downstream clients in real-time
18
- via websockets.
13
+ ## Install
19
14
 
20
- ## Usage
15
+ ```bash
16
+ npm install @arcanejs/protocol
17
+ ```
18
+
19
+ ## What It Defines
20
+
21
+ ## Base protocol (`@arcanejs/protocol`)
22
+
23
+ - Base component envelope (`BaseComponentProto`, `AnyComponentProto`)
24
+ - Server messages:
25
+ - `metadata`
26
+ - `tree-full`
27
+ - `tree-diff`
28
+ - `call-response`
29
+ - `pong`
30
+ - Client messages:
31
+ - `component-message`
32
+ - `component-call`
33
+ - `ping`
34
+ - Type helpers for call/response pair typing:
35
+ - `BaseClientComponentCallPair`
36
+ - `CallForPair`
37
+ - `ReturnForPair`
38
+
39
+ ## Core namespace (`@arcanejs/protocol/core`)
40
+
41
+ Core component protocol types and guards:
42
+
43
+ - Component types: `ButtonComponent`, `GroupComponent`, `LabelComponent`, `RectComponent`, `SliderButtonComponent`, `SwitchComponent`, `TabComponent`, `TabsComponent`, `TextInputComponent`, `TimelineComponent`
44
+ - Message types: `CoreComponentMessage` and specific message variants
45
+ - Call type map: `CoreComponentCalls`
46
+ - Guards:
47
+ - `isCoreComponent(...)`
48
+ - `isCoreComponentMessage(...)`
49
+ - `isCoreComponentCall(...)`
50
+
51
+ ## Supporting modules
52
+
53
+ - `@arcanejs/protocol/styles`: shared style contracts (`GroupComponentStyle`, `LabelComponentStyle`)
54
+ - `@arcanejs/protocol/logging`: logger contract (`Logger`)
55
+
56
+ ## Usage Example
21
57
 
22
58
  ```ts
23
- import { diffJson, Diff } from '@arcanejs/diff/diff';
24
- import { patchJson } from '@arcanejs/diff/patch';
59
+ import type {
60
+ ServerMessage,
61
+ ClientMessage,
62
+ BaseComponentProto,
63
+ CallForPair,
64
+ ReturnForPair,
65
+ } from '@arcanejs/protocol';
66
+
67
+ import type {
68
+ CoreComponentCalls,
69
+ CoreComponentMessage,
70
+ } from '@arcanejs/protocol/core';
71
+
72
+ const onServerMessage = (msg: ServerMessage) => {
73
+ if (msg.type === 'tree-full') {
74
+ const root: BaseComponentProto<string, string> = msg.root;
75
+ console.log(root.namespace, root.component);
76
+ }
77
+ };
25
78
 
26
- type E = {
27
- foo: string;
28
- bar?: number[];
79
+ const message: CoreComponentMessage = {
80
+ type: 'component-message',
81
+ namespace: 'core',
82
+ componentKey: 1,
83
+ component: 'switch',
29
84
  };
30
85
 
31
- const a: E = { foo: 'bar' };
32
- const b: E = { foo: 'baz', bar: [1] };
86
+ const callMessage: CallForPair<'core', CoreComponentCalls, 'press'> = {
87
+ type: 'component-call',
88
+ namespace: 'core',
89
+ componentKey: 5,
90
+ action: 'press',
91
+ };
92
+
93
+ type PressReturn = ReturnForPair<CoreComponentCalls, 'press'>; // true
94
+ const _resultExample: PressReturn = true;
33
95
 
34
- const diffA: Diff<E> = diffJson(a, b);
96
+ const _clientMessage: ClientMessage = message;
97
+ ```
35
98
 
36
- const resultA = patchJson(a, diffA);
99
+ ## Notes
37
100
 
38
- console.log(resultB); // { foo: 'baz', bar: [1] }
101
+ - This package is primarily type contracts and guard helpers.
102
+ - `tree-diff` payloads use `Diff<...>` from `@arcanejs/diff`.
103
+ - `ping`/`pong` can be used for browser/server clock sync. `pong` includes `serverTimeMillis`.
104
+ - Custom namespaces should follow the same pattern as `core`: define component proto types, message/call unions, and guard helpers.
39
105
 
40
- const c = { baz: 'foo' };
106
+ ## Example Reference
41
107
 
42
- 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; }'
43
- ```
108
+ - Custom protocol implementation example: <https://github.com/ArcaneWizards/arcanejs/blob/main/examples/custom-components/src/custom-proto.ts>
package/dist/core.d.mts CHANGED
@@ -120,9 +120,9 @@ interface CoreComponentCalls {
120
120
  return: true;
121
121
  };
122
122
  }
123
- declare const isCoreComponentMessage: <C extends "group" | "slider_button" | "switch" | "text-input">(message: BaseClientComponentMessage<string>, component: C) => message is CoreComponentMessage & {
123
+ declare const isCoreComponentMessage: <C extends CoreComponentMessage["component"]>(message: BaseClientComponentMessage<string>, component: C) => message is CoreComponentMessage & {
124
124
  component: C;
125
125
  };
126
- declare const isCoreComponentCall: <A extends "press">(call: BaseClientComponentCall<string, string>, action: A) => call is CoreComponentCalls[A]["call"];
126
+ declare const isCoreComponentCall: <A extends keyof CoreComponentCalls>(call: BaseClientComponentCall<string, string>, action: A) => call is CoreComponentCalls[A]["call"];
127
127
 
128
128
  export { type ButtonComponent, type ButtonPressMessage, type CoreComponent, type CoreComponentCalls, type CoreComponentMessage, type CoreNamespace, type DefaultGroupCollapsedState, type Gradient, type GroupCollapsedState, type GroupComponent, type GroupHeaderComponent, type GroupTitleChangeMessage, type LabelComponent, type RectComponent, type SliderButtonComponent, type SliderButtonUpdateMessage, type SwitchComponent, type SwitchToggleMessage, type TabComponent, type TabsComponent, type TextInputComponent, type TextInputUpdateMessage, type TimelineComponent, type TimelineState, isCoreComponent, isCoreComponentCall, isCoreComponentMessage };
package/dist/core.d.ts CHANGED
@@ -120,9 +120,9 @@ interface CoreComponentCalls {
120
120
  return: true;
121
121
  };
122
122
  }
123
- declare const isCoreComponentMessage: <C extends "group" | "slider_button" | "switch" | "text-input">(message: BaseClientComponentMessage<string>, component: C) => message is CoreComponentMessage & {
123
+ declare const isCoreComponentMessage: <C extends CoreComponentMessage["component"]>(message: BaseClientComponentMessage<string>, component: C) => message is CoreComponentMessage & {
124
124
  component: C;
125
125
  };
126
- declare const isCoreComponentCall: <A extends "press">(call: BaseClientComponentCall<string, string>, action: A) => call is CoreComponentCalls[A]["call"];
126
+ declare const isCoreComponentCall: <A extends keyof CoreComponentCalls>(call: BaseClientComponentCall<string, string>, action: A) => call is CoreComponentCalls[A]["call"];
127
127
 
128
128
  export { type ButtonComponent, type ButtonPressMessage, type CoreComponent, type CoreComponentCalls, type CoreComponentMessage, type CoreNamespace, type DefaultGroupCollapsedState, type Gradient, type GroupCollapsedState, type GroupComponent, type GroupHeaderComponent, type GroupTitleChangeMessage, type LabelComponent, type RectComponent, type SliderButtonComponent, type SliderButtonUpdateMessage, type SwitchComponent, type SwitchToggleMessage, type TabComponent, type TabsComponent, type TextInputComponent, type TextInputUpdateMessage, type TimelineComponent, type TimelineState, isCoreComponent, isCoreComponentCall, isCoreComponentMessage };
package/dist/index.d.mts CHANGED
@@ -12,6 +12,12 @@ type MetadataMessage = {
12
12
  * The UUID for the current connection
13
13
  */
14
14
  connectionUuid: string;
15
+ clockSync: {
16
+ /**
17
+ * How often the frontend should send ping requests.
18
+ */
19
+ pingIntervalMs: number;
20
+ } | null;
15
21
  };
16
22
  type SendTreeMsg = {
17
23
  type: 'tree-full';
@@ -32,7 +38,20 @@ type CallResponseMsg<Namespace extends string, T> = {
32
38
  success: false;
33
39
  errorMessage: string;
34
40
  });
35
- type ServerMessage = MetadataMessage | SendTreeMsg | UpdateTreeMsg | CallResponseMsg<string, unknown>;
41
+ type BaseNotificationMessage<Namespace extends string, Notification extends string> = {
42
+ type: 'notification';
43
+ namespace: Namespace;
44
+ notification: Notification;
45
+ };
46
+ type PongResponseMessage = {
47
+ type: 'pong';
48
+ pingId: number;
49
+ /**
50
+ * Server clock time in milliseconds.
51
+ */
52
+ serverTimeMillis: number;
53
+ };
54
+ type ServerMessage = MetadataMessage | SendTreeMsg | UpdateTreeMsg | CallResponseMsg<string, unknown> | BaseNotificationMessage<string, string> | PongResponseMessage;
36
55
  type BaseClientComponentMessage<Namespace extends string> = {
37
56
  type: 'component-message';
38
57
  namespace: Namespace;
@@ -55,8 +74,28 @@ type CallForPair<Namespace extends string, Pairs, Action extends string & keyof
55
74
  type ReturnForPair<Pairs, Action extends string & keyof Pairs> = Pairs extends Record<Action, {
56
75
  return: infer R;
57
76
  }> ? R : never;
77
+ type BaseClientComponentCallUpload<Namespace extends string, Action extends string> = {
78
+ type: 'component-call-upload';
79
+ namespace: Namespace;
80
+ componentKey: number;
81
+ requestId: number;
82
+ action: Action;
83
+ };
84
+ type BaseClientComponentCallDownload<Namespace extends string, Action extends string> = {
85
+ type: 'component-call-download';
86
+ namespace: Namespace;
87
+ componentKey: number;
88
+ requestId: number;
89
+ action: Action;
90
+ };
58
91
  type AnyClientComponentMessage = BaseClientComponentMessage<string>;
59
92
  type AnyClientComponentCall = BaseClientComponentCall<string, string>;
60
- type ClientMessage = AnyClientComponentMessage | AnyClientComponentCall;
93
+ type AnyClientComponentCallUpload = BaseClientComponentCallUpload<string, string>;
94
+ type AnyClientComponentCallDownload = BaseClientComponentCallDownload<string, string>;
95
+ type PingRequestMessage = {
96
+ type: 'ping';
97
+ pingId: number;
98
+ };
99
+ type ClientMessage = AnyClientComponentMessage | AnyClientComponentCall | AnyClientComponentCallUpload | AnyClientComponentCallDownload | PingRequestMessage;
61
100
 
62
- export type { AnyClientComponentCall, AnyClientComponentMessage, AnyComponentProto, BaseClientComponentCall, BaseClientComponentCallPair, BaseClientComponentMessage, BaseComponentProto, CallForPair, CallResponseMsg, ClientMessage, MetadataMessage, ReturnForPair, SendTreeMsg, ServerMessage, UpdateTreeMsg };
101
+ export type { AnyClientComponentCall, AnyClientComponentCallDownload, AnyClientComponentCallUpload, AnyClientComponentMessage, AnyComponentProto, BaseClientComponentCall, BaseClientComponentCallDownload, BaseClientComponentCallPair, BaseClientComponentCallUpload, BaseClientComponentMessage, BaseComponentProto, BaseNotificationMessage, CallForPair, CallResponseMsg, ClientMessage, MetadataMessage, PingRequestMessage, PongResponseMessage, ReturnForPair, SendTreeMsg, ServerMessage, UpdateTreeMsg };
package/dist/index.d.ts CHANGED
@@ -12,6 +12,12 @@ type MetadataMessage = {
12
12
  * The UUID for the current connection
13
13
  */
14
14
  connectionUuid: string;
15
+ clockSync: {
16
+ /**
17
+ * How often the frontend should send ping requests.
18
+ */
19
+ pingIntervalMs: number;
20
+ } | null;
15
21
  };
16
22
  type SendTreeMsg = {
17
23
  type: 'tree-full';
@@ -32,7 +38,20 @@ type CallResponseMsg<Namespace extends string, T> = {
32
38
  success: false;
33
39
  errorMessage: string;
34
40
  });
35
- type ServerMessage = MetadataMessage | SendTreeMsg | UpdateTreeMsg | CallResponseMsg<string, unknown>;
41
+ type BaseNotificationMessage<Namespace extends string, Notification extends string> = {
42
+ type: 'notification';
43
+ namespace: Namespace;
44
+ notification: Notification;
45
+ };
46
+ type PongResponseMessage = {
47
+ type: 'pong';
48
+ pingId: number;
49
+ /**
50
+ * Server clock time in milliseconds.
51
+ */
52
+ serverTimeMillis: number;
53
+ };
54
+ type ServerMessage = MetadataMessage | SendTreeMsg | UpdateTreeMsg | CallResponseMsg<string, unknown> | BaseNotificationMessage<string, string> | PongResponseMessage;
36
55
  type BaseClientComponentMessage<Namespace extends string> = {
37
56
  type: 'component-message';
38
57
  namespace: Namespace;
@@ -55,8 +74,28 @@ type CallForPair<Namespace extends string, Pairs, Action extends string & keyof
55
74
  type ReturnForPair<Pairs, Action extends string & keyof Pairs> = Pairs extends Record<Action, {
56
75
  return: infer R;
57
76
  }> ? R : never;
77
+ type BaseClientComponentCallUpload<Namespace extends string, Action extends string> = {
78
+ type: 'component-call-upload';
79
+ namespace: Namespace;
80
+ componentKey: number;
81
+ requestId: number;
82
+ action: Action;
83
+ };
84
+ type BaseClientComponentCallDownload<Namespace extends string, Action extends string> = {
85
+ type: 'component-call-download';
86
+ namespace: Namespace;
87
+ componentKey: number;
88
+ requestId: number;
89
+ action: Action;
90
+ };
58
91
  type AnyClientComponentMessage = BaseClientComponentMessage<string>;
59
92
  type AnyClientComponentCall = BaseClientComponentCall<string, string>;
60
- type ClientMessage = AnyClientComponentMessage | AnyClientComponentCall;
93
+ type AnyClientComponentCallUpload = BaseClientComponentCallUpload<string, string>;
94
+ type AnyClientComponentCallDownload = BaseClientComponentCallDownload<string, string>;
95
+ type PingRequestMessage = {
96
+ type: 'ping';
97
+ pingId: number;
98
+ };
99
+ type ClientMessage = AnyClientComponentMessage | AnyClientComponentCall | AnyClientComponentCallUpload | AnyClientComponentCallDownload | PingRequestMessage;
61
100
 
62
- export type { AnyClientComponentCall, AnyClientComponentMessage, AnyComponentProto, BaseClientComponentCall, BaseClientComponentCallPair, BaseClientComponentMessage, BaseComponentProto, CallForPair, CallResponseMsg, ClientMessage, MetadataMessage, ReturnForPair, SendTreeMsg, ServerMessage, UpdateTreeMsg };
101
+ export type { AnyClientComponentCall, AnyClientComponentCallDownload, AnyClientComponentCallUpload, AnyClientComponentMessage, AnyComponentProto, BaseClientComponentCall, BaseClientComponentCallDownload, BaseClientComponentCallPair, BaseClientComponentCallUpload, BaseClientComponentMessage, BaseComponentProto, BaseNotificationMessage, CallForPair, CallResponseMsg, ClientMessage, MetadataMessage, PingRequestMessage, PongResponseMessage, ReturnForPair, SendTreeMsg, ServerMessage, UpdateTreeMsg };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arcanejs/protocol",
3
- "version": "0.7.0",
3
+ "version": "0.9.0",
4
4
  "private": false,
5
5
  "description": "The JSON protocol types for the @arcanejs Toolkit",
6
6
  "license": "MIT",
@@ -34,7 +34,7 @@
34
34
  "./package.json": "./package.json"
35
35
  },
36
36
  "dependencies": {
37
- "@arcanejs/diff": "^0.5.1"
37
+ "@arcanejs/diff": "^0.6.0"
38
38
  },
39
39
  "devDependencies": {
40
40
  "@types/eslint": "^8.56.5",
@@ -42,7 +42,7 @@
42
42
  "check-export-map": "^1.3.1",
43
43
  "eslint": "^8.57.0",
44
44
  "tsup": "^8.1.0",
45
- "typescript": "^5.3.3",
45
+ "typescript": "^5.7",
46
46
  "@arcanejs/eslint-config": "^0.0.0",
47
47
  "@arcanejs/typescript-config": "^0.0.0"
48
48
  },