Skip to content

Commit 8fdfec1

Browse files
devvaannshabose
devvaannsh
authored and
abose
committed
chore: change crlf to lf line endings
1 parent c086adc commit 8fdfec1

14 files changed

Lines changed: 733 additions & 63 deletions

‎build/api-docs-generator.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -209,8 +209,8 @@ function normalizeLineEndings(content) {
209209
*/
210210
async function areFilesDifferent(file1, file2) {
211211
const [content1, content2] = await Promise.all([
212-
fs.readFile(file1, 'utf-8').then(normalizeLineEndings),
213-
fs.readFile(file2, 'utf-8').then(normalizeLineEndings)
212+
fs.readFile(file1, 'utf-8'),
213+
fs.readFile(file2, 'utf-8')
214214
]);
215215

216216
const hash1 = crypto.createHash('md5').update(content1).digest('hex');

‎docs/API-Reference/NodeConnector.md‎

Lines changed: 127 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,26 +6,126 @@ const NodeConnector = brackets.getModule("NodeConnector")
66
<a name="module_NodeConnector"></a>
77

88
## NodeConnector
9-
Node Connector Communication ModuleThis module simplifies communication between Node.js and Phoenix (phcode). A `NodeConnector` acts as an intermediary,allowing you to execute functions in Node.js from Phoenix and vice versa. You can use the `execPeer` method to callfunctions on the other side and handle communication seamlessly. Use `triggerPeer` to trigger eventson the other side.## Setting Up a `NodeConnector`To establish communication between two modules, such as `x.js` in Phoenix and `y.js` in Node.js, follow these steps:### Create `NodeConnector` in Phoenix (`x.js`)
9+
Node Connector Communication Module
10+
11+
This module simplifies communication between Node.js and Phoenix (phcode). A `NodeConnector` acts as an intermediary,
12+
allowing you to execute functions in Node.js from Phoenix and vice versa. You can use the `execPeer` method to call
13+
functions on the other side and handle communication seamlessly. Use `triggerPeer` to trigger events
14+
on the other side.
15+
16+
## Setting Up a `NodeConnector`
17+
18+
To establish communication between two modules, such as `x.js` in Phoenix and `y.js` in Node.js, follow these steps:
19+
20+
### Create `NodeConnector` in Phoenix (`x.js`)
1021

1122
**Example**
12-
```jsconst NodeConnector = require('NodeConnector');const XY_NODE_CONNECTOR_ID = 'ext_x_y'; // Use a unique IDlet nodeConnector = NodeConnector.createNodeConnector(XY_NODE_CONNECTOR_ID, exports);exports.modifyImage = async function(imageName, imageArrayBuffer) { // Perform image operations with the imageArrayBuffer // To return an ArrayBuffer, return an object with a `buffer` key. return { operationDone: 'colored, cropped', buffer: imageArrayBuffer, };};```### Create `NodeConnector` in Node.js (`y.js`)
23+
```js
24+
const NodeConnector = require('NodeConnector');
25+
const XY_NODE_CONNECTOR_ID = 'ext_x_y'; // Use a unique ID
26+
let nodeConnector = NodeConnector.createNodeConnector(XY_NODE_CONNECTOR_ID, exports);
27+
28+
exports.modifyImage = async function(imageName, imageArrayBuffer) {
29+
// Perform image operations with the imageArrayBuffer
30+
// To return an ArrayBuffer, return an object with a `buffer` key.
31+
return {
32+
operationDone: 'colored, cropped',
33+
buffer: imageArrayBuffer,
34+
};
35+
};
36+
```
37+
38+
### Create `NodeConnector` in Node.js (`y.js`)
1339
**Example**
14-
```jsconst XY_NODE_CONNECTOR_ID = 'ext_x_y'; // Use the same unique IDlet nodeConnector = global.createNodeConnector(XY_NODE_CONNECTOR_ID, exports);exports.getPWDRelative = async function(subPath) { return process.cwd + '/' + subPath;};```With these steps, a `NodeConnector` is set up, enabling two-way communication.## Executing FunctionsTo call a Node.js function from Phoenix, use the `execPeer` method.
40+
```js
41+
const XY_NODE_CONNECTOR_ID = 'ext_x_y'; // Use the same unique ID
42+
let nodeConnector = global.createNodeConnector(XY_NODE_CONNECTOR_ID, exports);
43+
44+
exports.getPWDRelative = async function(subPath) {
45+
return process.cwd + '/' + subPath;
46+
};
47+
```
48+
49+
With these steps, a `NodeConnector` is set up, enabling two-way communication.
50+
51+
## Executing Functions
52+
53+
To call a Node.js function from Phoenix, use the `execPeer` method.
1554
**Example**
16-
```js// In `x.js` (Phoenix)const fullPath = await nodeConnector.execPeer('getPWDRelative', 'sub/path.html');```To execute a Phoenix function from Node.js and transfer binary data, pass an optional ArrayBuffer.
55+
```js
56+
// In `x.js` (Phoenix)
57+
const fullPath = await nodeConnector.execPeer('getPWDRelative', 'sub/path.html');
58+
```
59+
60+
To execute a Phoenix function from Node.js and transfer binary data, pass an optional ArrayBuffer.
1761
**Example**
18-
```js// In `y.js` (Node.js)const { operationDone, buffer } = await nodeConnector.execPeer('modifyImage', {name:'theHills.png'}, imageAsArrayBuffer);```## Event HandlingThe `NodeConnector` object implements all the APIs supported by `utils/EventDispatcher`. You can trigger and listento events between Node.js and Phoenix using the `triggerPeer` and (`on`, `one` or `off`) methods.
62+
```js
63+
// In `y.js` (Node.js)
64+
const { operationDone, buffer } = await nodeConnector.execPeer('modifyImage', {name:'theHills.png'}, imageAsArrayBuffer);
65+
```
66+
67+
## Event Handling
68+
69+
The `NodeConnector` object implements all the APIs supported by `utils/EventDispatcher`. You can trigger and listen
70+
to events between Node.js and Phoenix using the `triggerPeer` and (`on`, `one` or `off`) methods.
1971
**Example**
20-
```js// In `y.js` (Node.js)nodeConnector.on('phoenixProjectOpened', (_event, projectPath) => { console.log(projectPath);});nodeConnector.one('phoenixProjectOpened', (_event, projectPath) => { console.log(projectPath + "will be received only once");});```To raise an event from Phoenix to Node.js:
72+
```js
73+
// In `y.js` (Node.js)
74+
nodeConnector.on('phoenixProjectOpened', (_event, projectPath) => {
75+
console.log(projectPath);
76+
});
77+
78+
nodeConnector.one('phoenixProjectOpened', (_event, projectPath) => {
79+
console.log(projectPath + "will be received only once");
80+
});
81+
```
82+
83+
To raise an event from Phoenix to Node.js:
2184
**Example**
22-
```js// In `x.js` (Phoenix)nodeConnector.triggerPeer('phoenixProjectOpened', '/x/project/folder');```To Switch off events
85+
```js
86+
// In `x.js` (Phoenix)
87+
nodeConnector.triggerPeer('phoenixProjectOpened', '/x/project/folder');
88+
```
89+
90+
To Switch off events
2391
**Example**
24-
```jsnodeConnector.off('phoenixProjectOpened'); // will switch off all event handlers of that name.```By Default, all events handlers with the eventName is removed when you call `nodeConnector.off(eventName)` fn.To selectively switch off event handlers, please see reference for `utils/EventDispatcher` module.### Handling ArrayBuffer Data in Function ExecutionWhen executing functions that send or receive binary data, ensure that the functions are asynchronous and accept anoptional ArrayBuffer as a parameter. To return binary data, use an object with a `buffer` key.Example of calling a function in Node.js with binary data transfer:
92+
```js
93+
nodeConnector.off('phoenixProjectOpened'); // will switch off all event handlers of that name.
94+
```
95+
96+
By Default, all events handlers with the eventName is removed when you call `nodeConnector.off(eventName)` fn.
97+
To selectively switch off event handlers, please see reference for `utils/EventDispatcher` module.
98+
99+
### Handling ArrayBuffer Data in Function Execution
100+
101+
When executing functions that send or receive binary data, ensure that the functions are asynchronous and accept an
102+
optional ArrayBuffer as a parameter. To return binary data, use an object with a `buffer` key.
103+
104+
Example of calling a function in Node.js with binary data transfer:
25105
**Example**
26-
```js// In `y.js` (Node.js)const { operationDone, buffer } = await nodeConnector.execPeer('modifyImage', {name:'name.png'}, imageArrayBuffer);```### Handling ArrayBuffer Data in Event HandlingUse the `triggerPeer` method to send binary data in events. Include the ArrayBuffer as an optional parameter.Example of sending binary data in an event from Phoenix to Node.js:
106+
```js
107+
// In `y.js` (Node.js)
108+
const { operationDone, buffer } = await nodeConnector.execPeer('modifyImage', {name:'name.png'}, imageArrayBuffer);
109+
```
110+
111+
### Handling ArrayBuffer Data in Event Handling
112+
113+
Use the `triggerPeer` method to send binary data in events. Include the ArrayBuffer as an optional parameter.
114+
115+
Example of sending binary data in an event from Phoenix to Node.js:
27116
**Example**
28-
```js// In `x.js` (Phoenix)const imageArrayBuffer = getSomeImageArrayBuffer(); // Get the ArrayBuffernodeConnector.triggerPeer('imageEdited', 'name.png', imageArrayBuffer);```## Caveats- Be cautious when sending large binary data, as it may affect performance and memory usage. Transferring large data is fully supported, but be mindful of performance.- Functions called with `execPeer` and `triggerPeer` must be asynchronous and accept a single argument. An optional second argument can be used to transfer large binary data as an ArrayBuffer.For more event handling operations and details, refer to the documentation for the `utils/EventDispatcher` module.
117+
```js
118+
// In `x.js` (Phoenix)
119+
const imageArrayBuffer = getSomeImageArrayBuffer(); // Get the ArrayBuffer
120+
nodeConnector.triggerPeer('imageEdited', 'name.png', imageArrayBuffer);
121+
```
122+
## Caveats
123+
- Be cautious when sending large binary data, as it may affect performance and memory usage. Transferring large
124+
data is fully supported, but be mindful of performance.
125+
- Functions called with `execPeer` and `triggerPeer` must be asynchronous and accept a single argument. An optional
126+
second argument can be used to transfer large binary data as an ArrayBuffer.
127+
128+
For more event handling operations and details, refer to the documentation for the `utils/EventDispatcher` module.
29129

30130
* [NodeConnector](#module_NodeConnector)
31131
* [.createNodeConnector(nodeConnectorID, moduleExports)](#module_NodeConnector..createNodeConnector) ⇒ <code>Object</code>
@@ -39,7 +139,23 @@ Node Connector Communication ModuleThis module simplifies communication betwee
39139
<a name="module_NodeConnector..createNodeConnector"></a>
40140

41141
### NodeConnector.createNodeConnector(nodeConnectorID, moduleExports) ⇒ <code>Object</code>
42-
Creates a new node connector with the specified ID and module exports.Returns a NodeConnector Object (which is an EventDispatcher withadditional `execPeer` and `triggerPeer` methods. `peer` here means, if you are executing `execPeer`in Phoenix, it will execute the named function in node side, and vice versa. You can right away startusing `execPeer`, `triggerPeer`(to send/receive events) APIs without waiting to check if theother side nodeConnector is created.Note: If the NodeConnector has not been created on the other end, requests made with `execPeer` or`triggerPeer` will be temporarily queued for up to 10 seconds to allow time for the connector to be created.If the connector is not created within this timeout period, all queued `execPeer` requests will be rejected,and all queued events will be dropped. It is recommended to call the `createNodeConnector` API on both endswithin a timeframe of less than 10 seconds(ideally same time) for seamless communication.- execPeer: A function that executes a peer function with specified parameters.- triggerPeer: A function that triggers an event to be sent to a peer.- Also contains all the APIs supported by `utils/EventDispatcher` module.
142+
Creates a new node connector with the specified ID and module exports.
143+
144+
Returns a NodeConnector Object (which is an EventDispatcher with
145+
additional `execPeer` and `triggerPeer` methods. `peer` here means, if you are executing `execPeer`
146+
in Phoenix, it will execute the named function in node side, and vice versa. You can right away start
147+
using `execPeer`, `triggerPeer`(to send/receive events) APIs without waiting to check if the
148+
other side nodeConnector is created.
149+
150+
Note: If the NodeConnector has not been created on the other end, requests made with `execPeer` or
151+
`triggerPeer` will be temporarily queued for up to 10 seconds to allow time for the connector to be created.
152+
If the connector is not created within this timeout period, all queued `execPeer` requests will be rejected,
153+
and all queued events will be dropped. It is recommended to call the `createNodeConnector` API on both ends
154+
within a timeframe of less than 10 seconds(ideally same time) for seamless communication.
155+
156+
- execPeer: A function that executes a peer function with specified parameters.
157+
- triggerPeer: A function that triggers an event to be sent to a peer.
158+
- Also contains all the APIs supported by `utils/EventDispatcher` module.
43159

44160
**Kind**: inner method of [<code>NodeConnector</code>](#module_NodeConnector)
45161
**Returns**: <code>Object</code> - - A NodeConnector Object. Also contains all the APIs supported by `utils/EventDispatcher` module.

0 commit comments

Comments
 (0)