socketioMEANseed/server/node_modules/socket.io-client/README.md
server/node_modules/socket.io-client/README.mdRaw
1
2# socket.io-client
3
4[](http://travis-ci.org/socketio/socket.io-client)
5[](https://david-dm.org/socketio/socket.io-client)
6[](https://david-dm.org/socketio/socket.io-client#info=devDependencies)
7
8
9[](http://slack.socket.io)
10
11[](https://saucelabs.com/u/socket)
12
13## How to use
14
15A standalone build of `socket.io-client` is exposed automatically by the
16socket.io server as `/socket.io/socket.io.js`. Alternatively you can
17serve the file `socket.io.js` or `socket.io.min.js` found in the `dist` folder.
18
19```html
20<script src="/socket.io/socket.io.js"></script>
21<script>
22 var socket = io('http://localhost');
23 socket.on('connect', function(){});
24 socket.on('event', function(data){});
25 socket.on('disconnect', function(){});
26</script>
27```
28
29Socket.IO is compatible with [browserify](http://browserify.org/).
30
31### Node.JS (server-side usage)
32
33 Add `socket.io-client` to your `package.json` and then:
34
35 ```js
36 var socket = require('socket.io-client')('http://localhost');
37 socket.on('connect', function(){});
38 socket.on('event', function(data){});
39 socket.on('disconnect', function(){});
40 ```
41
42## API
43
44### IO(url:String, opts:Object):Socket
45
46 Exposed as the `io` namespace in the standalone build, or the result
47 of calling `require('socket.io-client')`.
48
49 When called, it creates a new `Manager` for the given URL, and attempts
50 to reuse an existing `Manager` for subsequent calls, unless the
51 `multiplex` option is passed with `false`.
52
53 The rest of the options are passed to the `Manager` constructor (see below
54 for details).
55
56 A `Socket` instance is returned for the namespace specified by the
57 pathname in the URL, defaulting to `/`. For example, if the `url` is
58 `http://localhost/users`, a transport connection will be established to
59 `http://localhost` and a Socket.IO connection will be established to
60 `/users`.
61
62### IO#protocol
63
64 Socket.io protocol revision number this client works with.
65
66### IO#Socket
67
68 Reference to the `Socket` constructor.
69
70### IO#Manager
71
72 Reference to the `Manager` constructor.
73
74### IO#Emitter
75
76 Reference to the `Emitter` constructor.
77
78### Manager(url:String, opts:Object)
79
80 A `Manager` represents a connection to a given Socket.IO server. One or
81 more `Socket` instances are associated with the manager. The manager
82 can be accessed through the `io` property of each `Socket` instance.
83
84 The `opts` are also passed to `engine.io` upon initialization of the
85 underlying `Socket`.
86
87 Options:
88 - `reconnection` whether to reconnect automatically (`true`)
89 - `reconnectionAttempts` (`Infinity`) before giving up
90 - `reconnectionDelay` how long to initially wait before attempting a new
91 reconnection (`1000`). Affected by +/- `randomizationFactor`,
92 for example the default initial delay will be between 500 to 1500ms.
93 - `reconnectionDelayMax` maximum amount of time to wait between
94 reconnections (`5000`). Each attempt increases the reconnection delay by 2x
95 along with a randomization as above
96 - `randomizationFactor` (`0.5`), 0 <= randomizationFactor <= 1
97 - `timeout` connection timeout before a `connect_error`
98 and `connect_timeout` events are emitted (`20000`)
99 - `autoConnect` by setting this false, you have to call `manager.open`
100 whenever you decide it's appropriate
101
102#### Events
103
104 - `connect_error`. Fired upon a connection error.
105 Parameters:
106 - `Object` error object
107 - `connect_timeout`. Fired upon a connection timeout.
108 - `reconnect`. Fired upon a successful reconnection.
109 Parameters:
110 - `Number` reconnection attempt number
111 - `reconnect_attempt`. Fired upon an attempt to reconnect.
112 - `reconnecting`. Fired upon an attempt to reconnect.
113 Parameters:
114 - `Number` reconnection attempt number
115 - `reconnect_error`. Fired upon a reconnection attempt error.
116 Parameters:
117 - `Object` error object
118 - `reconnect_failed`. Fired when couldn't reconnect within `reconnectionAttempts`
119 - `ping`. Fired when a ping packet is written out to the server.
120 - `pong`. Fired when a pong is received from the server.
121 Parameters:
122 - `Number` number of ms elapsed since `ping` packet (i.e.: latency).
123
124The events above are also emitted on the individual sockets that
125reconnect that depend on this `Manager`.
126
127### Manager#reconnection(v:Boolean):Manager
128
129 Sets the `reconnection` option, or returns it if no parameters
130 are passed.
131
132### Manager#reconnectionAttempts(v:Boolean):Manager
133
134 Sets the `reconnectionAttempts` option, or returns it if no parameters
135 are passed.
136
137### Manager#reconnectionDelay(v:Boolean):Manager
138
139 Sets the `reconectionDelay` option, or returns it if no parameters
140 are passed.
141
142### Manager#reconnectionDelayMax(v:Boolean):Manager
143
144 Sets the `reconectionDelayMax` option, or returns it if no parameters
145 are passed.
146
147### Manager#timeout(v:Boolean):Manager
148
149 Sets the `timeout` option, or returns it if no parameters
150 are passed.
151
152### Socket
153
154#### Socket#id:String
155
156A property on the `socket` instance that is equal to the underlying engine.io socket id.
157
158The property is present once the socket has connected, is removed when the socket disconnects and is updated if the socket reconnects.
159
160#### Socket#compress(v:Boolean):Socket
161
162 Sets a modifier for a subsequent event emission that the event data will
163 only be _compressed_ if the value is `true`. Defaults to `true` when you don't call the method.
164
165 ```js
166 socket.compress(false).emit('an event', { some: 'data' });
167 ```
168
169#### Events
170
171 - `connect`. Fired upon a connection including a successful reconnection.
172 - `error`. Fired upon a connection error
173 Parameters:
174 - `Object` error data
175 - `disconnect`. Fired upon a disconnection.
176 - `reconnect`. Fired upon a successful reconnection.
177 Parameters:
178 - `Number` reconnection attempt number
179 - `reconnect_attempt`. Fired upon an attempt to reconnect.
180 - `reconnecting`. Fired upon an attempt to reconnect.
181 Parameters:
182 - `Number` reconnection attempt number
183 - `reconnect_error`. Fired upon a reconnection attempt error.
184 Parameters:
185 - `Object` error object
186 - `reconnect_failed`. Fired when couldn't reconnect within `reconnectionAttempts`
187
188## License
189
190[MIT](/LICENSE)