diff --git a/socket.io-client/legacy/socket.io-client-1.2.0.d.ts b/socket.io-client/legacy/socket.io-client-1.2.0.d.ts new file mode 100644 index 000000000..c5d783764 --- /dev/null +++ b/socket.io-client/legacy/socket.io-client-1.2.0.d.ts @@ -0,0 +1,45 @@ +// Type definitions for socket.io-client 1.2.0 +// Project: http://socket.io/ +// Definitions by: PROGRE +// Definitions: https://github.com/borisyankov/DefinitelyTyped + +declare var io: SocketIOClientStatic; + +declare module 'socket.io-client' { + export = io; +} + +interface SocketIOClientStatic { + (host: string, details?: any): SocketIOClient.Socket; + (details?: any): SocketIOClient.Socket; + connect(host: string, details?: any): SocketIOClient.Socket; + connect(details?: any): SocketIOClient.Socket; + protocol: number; + Socket: { new (...args: any[]): SocketIOClient.Socket }; + Manager: SocketIOClient.ManagerStatic; +} + +declare module SocketIOClient { + interface Socket { + on(event: string, fn: Function): Socket; + once(event: string, fn: Function): Socket; + off(event?: string, fn?: Function): Socket; + emit(event: string, ...args: any[]): Socket; + listeners(event: string): Function[]; + hasListeners(event: string): boolean; + connected: boolean; + } + + interface ManagerStatic { + (url: string, opts: any): SocketIOClient.Manager; + new (url: string, opts: any): SocketIOClient.Manager; + } + + interface Manager { + reconnection(v: boolean): Manager; + reconnectionAttempts(v: boolean): Manager; + reconnectionDelay(v: boolean): Manager; + reconnectionDelayMax(v: boolean): Manager; + timeout(v: boolean): Manager; + } +} diff --git a/socket.io-client/socket.io-client.d.ts b/socket.io-client/socket.io-client.d.ts index c5d783764..7e15773e6 100644 --- a/socket.io-client/socket.io-client.d.ts +++ b/socket.io-client/socket.io-client.d.ts @@ -1,45 +1,650 @@ -// Type definitions for socket.io-client 1.2.0 +// Type definitions for socket.io-client 1.3.5 // Project: http://socket.io/ -// Definitions by: PROGRE +// Definitions by: divillysausages // Definitions: https://github.com/borisyankov/DefinitelyTyped declare var io: SocketIOClientStatic; declare module 'socket.io-client' { - export = io; + export = io; } interface SocketIOClientStatic { - (host: string, details?: any): SocketIOClient.Socket; - (details?: any): SocketIOClient.Socket; - connect(host: string, details?: any): SocketIOClient.Socket; - connect(details?: any): SocketIOClient.Socket; - protocol: number; - Socket: { new (...args: any[]): SocketIOClient.Socket }; - Manager: SocketIOClient.ManagerStatic; + + /** + * Looks up an existing 'Manager' for multiplexing. If the user summons: + * 'io( 'http://localhost/a' );' + * 'io( 'http://localhost/b' );' + * + * We reuse the existing instance based on the same scheme/port/host, and + * we initialize sockets for each namespace. If autoConnect isn't set to + * false in the options, then we'll automatically connect + * @param uri The uri that we'll connect to, including the namespace, where '/' is the default one (e.g. http://localhost:4000/somenamespace) + * @opts Any connect options that we want to pass along + * @return A Socket object + */ + ( uri: string, opts?: SocketIOClient.ConnectOpts ): SocketIOClient.Socket; + + /** + * Auto-connects to the window location and defalt namespace. + * E.g. window.protocol + '//' + window.host + ':80/' + * @opts Any connect options that we want to pass along + * @return A Socket object + */ + ( opts?: SocketIOClient.ConnectOpts ): SocketIOClient.Socket; + + /** + * @see the default constructor (io(uri, opts)) + */ + connect( uri: string, opts?: SocketIOClient.ConnectOpts ): SocketIOClient.Socket; + + /** + * @see the default constructor (io(opts)) + */ + connect( opts?: SocketIOClient.ConnectOpts ): SocketIOClient.Socket; + + /** + * The socket.io protocol revision number this client works with + * @default 4 + */ + protocol: number; + + /** + * Socket constructor - exposed for the standalone build + */ + Socket: SocketIOClient.Socket; + + /** + * Manager constructor - exposed for the standalone build + */ + Manager: SocketIOClient.ManagerStatic; } declare module SocketIOClient { - interface Socket { - on(event: string, fn: Function): Socket; - once(event: string, fn: Function): Socket; - off(event?: string, fn?: Function): Socket; - emit(event: string, ...args: any[]): Socket; - listeners(event: string): Function[]; - hasListeners(event: string): boolean; - connected: boolean; - } + + /** + * The base emiter class, used by Socket and Manager + */ + interface Emitter { + /** + * Adds a listener for a particular event. Calling multiple times will add + * multiple listeners + * @param event The event that we're listening for + * @param fn The function to call when we get the event. Parameters depend on the + * event in question + * @return This Emitter + */ + on( event: string, fn: Function ):Emitter; + + /** + * @see on( event, fn ) + */ + addEventListener( event: string, fn: Function ):Emitter; + + /** + * Adds a listener for a particular event that will be invoked + * a single time before being automatically removed + * @param event The event that we're listening for + * @param fn The function to call when we get the event. Parameters depend on + * the event in question + * @return This Emitter + */ + once( event: string, fn: Function ):Emitter; + + /** + * Removes a listener for a particular type of event. This will either + * remove a specific listener, or all listeners for this type of event + * @param event The event that we want to remove the listener of + * @param fn The function to remove, or null if we want to remove all functions + * @return This Emitter + */ + off( event: string, fn?: Function ):Emitter; + + /** + * @see off( event, fn ) + */ + removeListener( event: string, fn?: Function ):Emitter; + + /** + * @see off( event, fn ) + */ + removeEventListener( event: string, fn?: Function ):Emitter; + + /** + * Removes all event listeners on this object + * @return This Emitter + */ + removeAllListeners():Emitter; + + /** + * Emits 'event' with the given args + * @param event The event that we want to emit + * @param args Optional arguments to emit with the event + * @return Emitter + */ + emit( event: string, ...args: any[] ):Emitter; + + /** + * Returns all the callbacks for a particular event + * @param event The event that we're looking for the callbacks of + * @return An array of callback Functions, or an empty array if we don't have any + */ + listeners( event: string ):Function[]; + + /** + * Returns if we have listeners for a particular event + * @param event The event that we want to check if we've listeners for + * @return True if we have listeners for this event, false otherwise + */ + hasListeners( event: string ):boolean; + } + + /** + * The Socket static interface + */ + interface SocketStatic { + + /** + * Creates a new Socket, used for communicating with a specific namespace + * @param io The Manager that's controlling this socket + * @param nsp The namespace that this socket is for (@default '/') + * @return A new Socket + */ + ( io: SocketIOClient.Manager, nsp: string ): Socket; + + /** + * Creates a new Socket, used for communicating with a specific namespace + * @param io The Manager that's controlling this socket + * @param nsp The namespace that this socket is for (@default '/') + * @return A new Socket + */ + new ( url: string, opts: any ): SocketIOClient.Manager; + } + + /** + * The Socket that we use to connect to a Namespace on the server + */ + interface Socket extends Emitter { + + /** + * The Manager that's controller this socket + */ + io: SocketIOClient.Manager; + + /** + * The namespace that this socket is for + * @default '/' + */ + nsp: string; + + /** + * Are we currently connected? + * @default false + */ + connected: boolean; + + /** + * Are we currently disconnected? + * @default true + */ + disconnected: boolean; + + /** + * Opens our socket so that it connects. If the 'autoConnect' option for io is + * true (default), then this is called automatically when the Socket is created + */ + open(): Socket; + + /** + * @see open(); + */ + connect(): Socket; + + /** + * Sends a 'message' event + * @param args Any optional arguments that we want to send + * @see emit + * @return This Socket + */ + send( ...args: any[] ):Socket; + + /** + * An override of the base emit. If the event is one of: + * connect + * connect_error + * connect_timeout + * disconnect + * error + * reconnect + * reconnect_attempt + * reconnect_failed + * reconnect_error + * reconnecting + * then the event is emitted normally. Otherwise, if we're connected, the + * event is sent. Otherwise, it's buffered. + * + * If the last argument is a function, then it will be called + * as an 'ack' when the response is received. The parameter(s) of the + * ack will be whatever data is returned from the event + * @param event The event that we're emitting + * @param args Optional arguments to send with the event + * @return This Socket + */ + emit( event: string, ...args: any[] ):Socket; + + /** + * Disconnects the socket manually + * @return This Socket + */ + close():Socket; + + /** + * @see close() + */ + disconnect():Socket; + } - interface ManagerStatic { - (url: string, opts: any): SocketIOClient.Manager; - new (url: string, opts: any): SocketIOClient.Manager; - } + /** + * The Manager static interface + */ + interface ManagerStatic { + /** + * Creates a new Manager + * @param uri The URI that we're connecting to (e.g. http://localhost:4000) + * @param opts Any connection options that we want to use (and pass to engine.io) + * @return A Manager + */ + ( uri: string, opts?: SocketIOClient.ConnectOpts ): SocketIOClient.Manager; + + /** + * Creates a new Manager with the default URI (window host) + * @param opts Any connection options that we want to use (and pass to engine.io) + */ + ( opts: SocketIOClient.ConnectOpts ):SocketIOClient.Manager; + + /** + * @see default constructor + */ + new ( uri: string, opts?: SocketIOClient.ConnectOpts ): SocketIOClient.Manager; + + /** + * @see default constructor + */ + new ( opts: SocketIOClient.ConnectOpts ):SocketIOClient.Manager; + } - interface Manager { - reconnection(v: boolean): Manager; - reconnectionAttempts(v: boolean): Manager; - reconnectionDelay(v: boolean): Manager; - reconnectionDelayMax(v: boolean): Manager; - timeout(v: boolean): Manager; - } + /** + * The Manager class handles all the Namespaces and Sockets that we're using + */ + interface Manager extends Emitter { + + /** + * All the namespaces currently controlled by this Manager, and the Sockets + * that we're using to communicate with them + */ + nsps: { [namespace:string]: Socket }; + + /** + * The connect options that we used when creating this Manager + */ + opts: SocketIOClient.ConnectOpts; + + /** + * The state of the Manager. Either 'closed', 'opening', or 'open' + */ + readyState: string; + + /** + * The URI that this manager is for (host + port), e.g. 'http://localhost:4000' + */ + uri: string; + + /** + * The currently connected sockets + */ + connected: Socket[]; + + /** + * If we should auto connect (also used when creating Sockets). Set via the + * opts object + */ + autoConnect: boolean; + + /** + * Gets if we should reconnect automatically + * @default true + */ + reconnection(): boolean; + + /** + * Sets if we should reconnect automatically + * @param v True if we should reconnect automatically, false otherwise + * @default true + * @return This Manager + */ + reconnection( v: boolean ): Manager; + + /** + * Gets the number of reconnection attempts we should try before giving up + * @default Infinity + */ + reconnectionAttempts(): number; + + /** + * Sets the number of reconnection attempts we should try before giving up + * @param v The number of attempts we should do before giving up + * @default Infinity + * @return This Manager + */ + reconnectionAttempts( v: number ): Manager; + + /** + * Gets the delay in milliseconds between each reconnection attempt + * @default 1000 + */ + reconnectionDelay(): number; + + /** + * Sets the delay in milliseconds between each reconnection attempt + * @param v The delay in milliseconds + * @default 1000 + * @return This Manager + */ + reconnectionDelay( v: number ): Manager; + + /** + * Gets the max reconnection delay in milliseconds between each reconnection + * attempt + * @default 5000 + */ + reconnectionDelayMax(): number; + + /** + * Sets the max reconnection delay in milliseconds between each reconnection + * attempt + * @param v The max reconnection dleay in milliseconds + * @return This Manager + */ + reconnectionDelayMax( v: number ): Manager; + + /** + * Gets the randomisation factor used in the exponential backoff jitter + * when reconnecting + * @default 0.5 + */ + randomizationFactor(): number; + + /** + * Sets the randomisation factor used in the exponential backoff jitter + * when reconnecting + * @param The reconnection randomisation factor + * @default 0.5 + * @return This Manager + */ + randomizationFactor( v: number ): Manager; + + /** + * Gets the timeout in milliseconds for our connection attempts + * @default 20000 + */ + timeout(): number; + + /** + * Sets the timeout in milliseconds for our connection attempts + * @param The connection timeout milliseconds + * @return This Manager + */ + timeout(v: boolean): Manager; + + /** + * Sets the current transport socket and opens our connection + * @param fn An optional callback to call when our socket has either opened, or + * failed. It can take one optional parameter of type Error + * @return This Manager + */ + open( fn?: (err?: any) => void ): Manager; + + /** + * @see open( fn ); + */ + connect( fn?: (err?: any) => void ): Manager; + + /** + * Creates a new Socket for the given namespace + * @param nsp The namespace that this Socket is for + * @return A new Socket, or if one has already been created for this namespace, + * an existing one + */ + socket( nsp: string ): Socket; + } + + /** + * Options we can pass to the socket when connecting + */ + interface ConnectOpts { + + /** + * Should we force a new Manager for this connection? + * @default false + */ + forceNew?: boolean; + + /** + * Should we multiplex our connection (reuse existing Manager) ? + * @default true + */ + multiplex?: boolean; + + /** + * The path to get our client file from, in the case of the server + * serving it + * @default '/socket.io' + */ + path?: string; + + /** + * Should we allow reconnections? + * @default true + */ + reconnection?: boolean; + + /** + * How many reconnection attempts should we try? + * @default Infinity + */ + reconnectionAttempts?: boolean; + + /** + * The time delay in milliseconds between reconnection attempts + * @default 1000 + */ + reconnectionDelay?: number; + + /** + * The max time delay in milliseconds between reconnection attempts + * @default 5000 + */ + reconnectionDelayMax?: number; + + /** + * Used in the exponential backoff jitter when reconnecting + * @default 0.5 + */ + randomizationFactor?: number; + + /** + * The timeout in milliseconds for our connection attempt + * @default 20000 + */ + timeout?: number; + + /** + * Should we automically connect? + * @default true + */ + autoConnect?: boolean; + + /** + * The host that we're connecting to. Set from the URI passed when connecting + */ + host?: string; + + /** + * The hostname for our connection. Set from the URI passed when connecting + */ + hostname?: string; + + /** + * If this is a secure connection. Set from the URI passed when connecting + */ + secure?: boolean; + + /** + * The port for our connection. Set from the URI passed when connecting + */ + port?: string; + + /** + * Any query parameters in our uri. Set from the URI passed when connecting + */ + query?: Object; + + /** + * `http.Agent` to use, defaults to `false` (NodeJS only) + */ + agent?: string|boolean; + + /** + * Whether the client should try to upgrade the transport from + * long-polling to something better. + * @default true + */ + upgrade?: boolean; + + /** + * Forces JSONP for polling transport. + */ + forceJSONP?: boolean; + + /** + * Determines whether to use JSONP when necessary for polling. If + * disabled (by settings to false) an error will be emitted (saying + * "No transports available") if no other transports are available. + * If another transport is available for opening a connection (e.g. + * WebSocket) that transport will be used instead. + * @default true + */ + jsonp?: boolean; + + /** + * Forces base 64 encoding for polling transport even when XHR2 + * responseType is available and WebSocket even if the used standard + * supports binary. + */ + forceBase64?: boolean; + + /** + * Enables XDomainRequest for IE8 to avoid loading bar flashing with + * click sound. default to `false` because XDomainRequest has a flaw + * of not sending cookie. + * @default false + */ + enablesXDR?: boolean; + + /** + * The param name to use as our timestamp key + * @default 't' + */ + timestampParam?: string; + + /** + * Whether to add the timestamp with each transport request. Note: this + * is ignored if the browser is IE or Android, in which case requests + * are always stamped + * @default false + */ + timestampRequests?: boolean; + + /** + * A list of transports to try (in order). Engine.io always attempts to + * connect directly with the first one, provided the feature detection test + * for it passes. + * @default ['polling','websocket'] + */ + transports?: string[]; + + /** + * The port the policy server listens on + * @default 843 + */ + policyPost?: number; + + /** + * If true and if the previous websocket connection to the server succeeded, + * the connection attempt will bypass the normal upgrade process and will + * initially try websocket. A connection attempt following a transport error + * will use the normal upgrade process. It is recommended you turn this on + * only when using SSL/TLS connections, or if you know that your network does + * not block websockets. + * @default false + */ + rememberUpgrade?: boolean; + + /** + * Are we only interested in transports that support binary? + */ + onlyBinaryUpgrades?: boolean; + + /** + * (SSL) Certificate, Private key and CA certificates to use for SSL. + * Can be used in Node.js client environment to manually specify + * certificate information. + */ + pfx?: string; + + /** + * (SSL) Private key to use for SSL. Can be used in Node.js client + * environment to manually specify certificate information. + */ + key?: string; + + /** + * (SSL) A string or passphrase for the private key or pfx. Can be + * used in Node.js client environment to manually specify certificate + * information. + */ + passphrase?: string + + /** + * (SSL) Public x509 certificate to use. Can be used in Node.js client + * environment to manually specify certificate information. + */ + cert?: string; + + /** + * (SSL) An authority certificate or array of authority certificates to + * check the remote host against.. Can be used in Node.js client + * environment to manually specify certificate information. + */ + ca?: string|string[]; + + /** + * (SSL) A string describing the ciphers to use or exclude. Consult the + * [cipher format list] + * (http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT) for + * details on the format.. Can be used in Node.js client environment to + * manually specify certificate information. + */ + ciphers?: string; + + /** + * (SSL) If true, the server certificate is verified against the list of + * supplied CAs. An 'error' event is emitted if verification fails. + * Verification happens at the connection level, before the HTTP request + * is sent. Can be used in Node.js client environment to manually specify + * certificate information. + */ + rejectUnauthorized?: boolean; + + } } diff --git a/socket.io/legacy/socket.io-1.2.0.d.ts b/socket.io/legacy/socket.io-1.2.0.d.ts new file mode 100644 index 000000000..3f3c042fe --- /dev/null +++ b/socket.io/legacy/socket.io-1.2.0.d.ts @@ -0,0 +1,96 @@ +// Type definitions for socket.io 1.2.0 +// Project: http://socket.io/ +// Definitions by: PROGRE +// Definitions: https://github.com/borisyankov/DefinitelyTyped + +/// + +declare module 'socket.io' { + var server: SocketIOStatic; + + export = server; +} + +interface SocketIOStatic { + (): SocketIO.Server; + (srv: any, opts?: any): SocketIO.Server; + (port: number, opts?: any): SocketIO.Server; + (opts: any): SocketIO.Server; + + listen: SocketIOStatic; +} + +declare module SocketIO { + interface Server { + serveClient(v: boolean): Server; + path(v: string): Server; + adapter(v: any): Server; + origins(v: string): Server; + sockets: Namespace; + attach(srv: any, opts?: any): Server; + attach(port: number, opts?: any): Server; + listen(srv: any, opts?: any): Server; + listen(port: number, opts?: any): Server; + bind(srv: any): Server; + onconnection(socket: any): Server; + of(nsp: string): Namespace; + emit(name: string, ...args: any[]): Socket; + use(fn: Function): Namespace; + + on(event: 'connection', listener: (socket: Socket) => void): Namespace; + on(event: 'connect', listener: (socket: Socket) => void): Namespace; + on(event: string, listener: Function): Namespace; + } + + interface Namespace extends NodeJS.EventEmitter { + name: string; + connected: { [id: string]: Socket }; + use(fn: Function): Namespace; + in(room: string): Namespace; + + on(event: 'connection', listener: (socket: Socket) => void): Namespace; + on(event: 'connect', listener: (socket: Socket) => void): Namespace; + on(event: string, listener: Function): Namespace; + } + + interface Socket { + rooms: string[]; + client: Client; + conn: any; + request: any; + id: string; + handshake: { + headers: any; + time: string; + address: any; + xdomain: boolean; + secure: boolean; + issued: number; + url: string; + query: any; + }; + + emit(name: string, ...args: any[]): Socket; + join(name: string, fn?: Function): Socket; + leave(name: string, fn?: Function): Socket; + to(room: string): Socket; + in(room: string): Socket; + send(...args: any[]): Socket; + write(...args: any[]): Socket; + + on(event: string, listener: Function): Socket; + once(event: string, listener: Function): Socket; + removeListener(event: string, listener: Function): Socket; + removeAllListeners(event: string): Socket; + broadcast: Socket; + volatile: Socket; + connected: boolean; + disconnect(close?: boolean): Socket; + } + + interface Client { + conn: any; + request: any; + id: string; + } +} diff --git a/socket.io/socket.io.d.ts b/socket.io/socket.io.d.ts index 3f3c042fe..045e0007a 100644 --- a/socket.io/socket.io.d.ts +++ b/socket.io/socket.io.d.ts @@ -1,96 +1,823 @@ -// Type definitions for socket.io 1.2.0 +// Type definitions for socket.io 1.3.5 // Project: http://socket.io/ -// Definitions by: PROGRE +// Definitions by: divillysausages // Definitions: https://github.com/borisyankov/DefinitelyTyped /// declare module 'socket.io' { - var server: SocketIOStatic; + var server: SocketIOStatic; - export = server; + export = server; } interface SocketIOStatic { - (): SocketIO.Server; - (srv: any, opts?: any): SocketIO.Server; - (port: number, opts?: any): SocketIO.Server; - (opts: any): SocketIO.Server; + /** + * Default Server constructor + */ + (): SocketIO.Server; + + /** + * Creates a new Server + * @param srv The HTTP server that we're going to bind to + * @param opts An optional parameters object + */ + (srv: any, opts?: SocketIO.ServerOptions): SocketIO.Server; + + /** + * Creates a new Server + * @param port A port to bind to, as a number, or a string + * @param An optional parameters object + */ + (port: string|number, opts?: SocketIO.ServerOptions): SocketIO.Server; + + /** + * Creates a new Server + * @param A parameters object + */ + (opts: SocketIO.ServerOptions): SocketIO.Server; + /** + * Backwards compatibility + * @see io().listen() + */ listen: SocketIOStatic; } declare module SocketIO { - interface Server { - serveClient(v: boolean): Server; - path(v: string): Server; - adapter(v: any): Server; - origins(v: string): Server; - sockets: Namespace; - attach(srv: any, opts?: any): Server; - attach(port: number, opts?: any): Server; - listen(srv: any, opts?: any): Server; - listen(port: number, opts?: any): Server; - bind(srv: any): Server; - onconnection(socket: any): Server; - of(nsp: string): Namespace; - emit(name: string, ...args: any[]): Socket; - use(fn: Function): Namespace; + + interface Server { + + /** + * A dictionary of all the namespaces currently on this Server + */ + nsps: {[namespace: string]: Namespace}; + + /** + * The default '/' Namespace + */ + sockets: Namespace; + + /** + * Sets the 'json' flag when emitting an event + */ + json: Server; + + /** + * Server request verification function, that checks for allowed origins + * @param req The http.IncomingMessage request + * @param fn The callback to be called. It should take one parameter, err, + * which will be null if there was no problem, and one parameter, success, + * of type boolean + */ + checkRequest( req:any, fn:( err: any, success: boolean ) => void ):void; + + /** + * Gets whether we're serving the client.js file or not + * @default true + */ + serveClient(): boolean; + + /** + * Sets whether we're serving the client.js file or not + * @param v True if we want to serve the file, false otherwise + * @default true + * @return This Server + */ + serveClient( v: boolean ): Server; + + /** + * Gets the client serving path + * @default '/socket.io' + */ + path(): string; + + /** + * Sets the client serving path + * @param v The path to serve the client file on + * @default '/socket.io' + * @return This Server + */ + path( v: string ): Server; + + /** + * Gets the adapter that we're going to use for handling rooms + * @default typeof Adapter + */ + adapter(): any; + + /** + * Sets the adapter (class) that we're going to use for handling rooms + * @param v The class for the adapter to create + * @default typeof Adapter + * @return This Server + */ + adapter( v: any ): Server; + + /** + * Gets the allowed origins for requests + * @default "*:*" + */ + origins(): string; + + /** + * Sets the allowed origins for requests + * @param v The allowed origins, in host:port form + * @default "*:*" + * return This Server + */ + origins( v: string ): Server; + + /** + * Attaches socket.io to a server + * @param srv The http.Server that we want to attach to + * @param opts An optional parameters object + * @return This Server + */ + attach( srv: any, opts?: ServerOptions ): Server; + + /** + * Attaches socket.io to a port + * @param port The port that we want to attach to + * @param opts An optional parameters object + * @return This Server + */ + attach( port: number, opts?: ServerOptions ): Server; + + /** + * @see attach( srv, opts ) + */ + listen( srv: any, opts?: ServerOptions ): Server; + + /** + * @see attach( port, opts ) + */ + listen( port: number, opts?: ServerOptions ): Server; + + /** + * Binds socket.io to an engine.io intsance + * @param src The Engine.io (or compatible) server to bind to + * @return This Server + */ + bind( srv: any ): Server; + + /** + * Called with each incoming connection + * @param socket The Engine.io Socket + * @return This Server + */ + onconnection( socket: any ): Server; + + /** + * Looks up/creates a Namespace + * @param nsp The name of the NameSpace to look up/create. Should start + * with a '/' + * @return The Namespace + */ + of( nsp: string ): Namespace; + + /** + * Closes the server connection + */ + close():void; - on(event: 'connection', listener: (socket: Socket) => void): Namespace; - on(event: 'connect', listener: (socket: Socket) => void): Namespace; - on(event: string, listener: Function): Namespace; - } + /** + * The event fired when we get a new connection + * @param event The event being fired: 'connection' + * @param listener A listener that should take one parameter of type Socket + * @return The default '/' Namespace + */ + on( event: 'connection', listener: ( socket: Socket ) => void ): Namespace; + + /** + * @see on( 'connection', listener ) + */ + on( event: 'connect', listener: ( socket: Socket ) => void ): Namespace; + + /** + * Base 'on' method to add a listener for an event + * @param event The event that we want to add a listener for + * @param listener The callback to call when we get the event. The parameters + * for the callback depend on the event + * @return The default '/' Namespace + */ + on( event: string, listener: Function ): Namespace; + + /** + * Targets a room when emitting to the default '/' Namespace + * @param room The name of the room that we're targeting + * @return The default '/' Namespace + */ + to( room: string ): Namespace; + + /** + * @see to( room ) + */ + in( room: string ): Namespace; + + /** + * Registers a middleware function, which is a function that gets executed + * for every incoming Socket, on the default '/' Namespace + * @param fn The function to call when we get a new incoming socket. It should + * take one parameter of type Socket, and one callback function to call to + * execute the next middleware function. The callback can take one optional + * parameter, err, if there was an error. Errors passed to middleware callbacks + * are sent as special 'error' packets to clients + * @return The default '/' Namespace + */ + use( fn: ( socket:Socket, fn: ( err?: any ) => void ) =>void ): Namespace; + + /** + * Emits an event to the default Namespace + * @param event The event that we want to emit + * @param args Any number of optional arguments to pass with the event. If the + * last argument is a function, it will be called as an ack. The ack should + * take whatever data was sent with the packet + * @return The default '/' Namespace + */ + emit( event: string, ...args: any[]): Namespace; + + /** + * Sends a 'message' event + * @see emit( event, ...args ) + * @return The default '/' Namespace + */ + send( ...args: any[] ): Namespace; + + /** + * @see send( ...args ) + */ + write( ...args: any[] ): Namespace; + } + + /** + * Options to pass to our server when creating it + */ + interface ServerOptions { + + /** + * The path to server the client file to + * @default '/socket.io' + */ + path?: string; + + /** + * Should we serve the client file? + * @default true + */ + serveClient?: boolean; + + /** + * The adapter to use for handling rooms. NOTE: this should be a class, + * not an object + * @default typeof Adapter + */ + adapter?: Adapter; + + /** + * Accepted origins + * @default '*:*' + */ + origins?: string; + + /** + * How many milliseconds without a pong packed to consider the connection closed (engine.io) + * @default 60000 + */ + pingTimeout?: number; + + /** + * How many milliseconds before sending a new ping packet (keep-alive) (engine.io) + * @default 25000 + */ + pingInterval?: number; + + /** + * How many bytes or characters a message can be when polling, before closing the session + * (to avoid Dos) (engine.io) + * @default 10E7 + */ + maxHttpBufferSize?: number; + + /** + * A function that receives a given handshake or upgrade request as its first parameter, + * and can decide whether to continue or not. The second argument is a function that needs + * to be called with the decided information: fn( err, success ), where success is a boolean + * value where false means that the request is rejected, and err is an error code (engine.io) + * @default null + */ + allowRequest?: (request:any, callback: (err: number, success: boolean) => void) => void; + + /** + * Transports to allow connections to (engine.io) + * @default ['polling','websocket'] + */ + transports?: string[]; + + /** + * Whether to allow transport upgrades (engine.io) + * @default true + */ + allowUpgrades?: boolean; + + /** + * parameters of the WebSocket permessage-deflate extension (see ws module). + * Set to false to disable (engine.io) + * @default true + */ + perMessageDeflate?: Object|boolean; + + /** + * Parameters of the http compression for the polling transports (see zlib). + * Set to false to disable, or set an object with parameter "threshold:number" + * to only compress data if the byte size is above this value (1024) (engine.io) + * @default true|1024 + */ + httpCompression?: Object|boolean; + + /** + * Name of the HTTP cookie that contains the client sid to send as part of + * handshake response headers. Set to false to not send one (engine.io) + * @default "io" + */ + cookie?: string|boolean; + } - interface Namespace extends NodeJS.EventEmitter { - name: string; - connected: { [id: string]: Socket }; - use(fn: Function): Namespace; - in(room: string): Namespace; + /** + * The Namespace, sandboxed environments for sockets, each connection + * to a Namespace requires a new Socket + */ + interface Namespace extends NodeJS.EventEmitter { + + /** + * The name of the NameSpace + */ + name: string; + + /** + * The controller Server for this Namespace + */ + server: Server; + + /** + * A list of all the Sockets connected to this Namespace + */ + sockets: Socket[]; + + /** + * A dictionary of all the Sockets connected to this Namespace, where + * the Socket ID is the key + */ + connected: { [id: string]: Socket }; + + /** + * The Adapter that we're using to handle dealing with rooms etc + */ + adapter: Adapter; + + /** + * Sets the 'json' flag when emitting an event + */ + json: Namespace; + + /** + * Registers a middleware function, which is a function that gets executed + * for every incoming Socket + * @param fn The function to call when we get a new incoming socket. It should + * take one parameter of type Socket, and one callback function to call to + * execute the next middleware function. The callback can take one optional + * parameter, err, if there was an error. Errors passed to middleware callbacks + * are sent as special 'error' packets to clients + * @return This Namespace + */ + use( fn: ( socket:Socket, fn: ( err?: any ) => void ) =>void ): Namespace; + + /** + * Targets a room when emitting + * @param room The name of the room that we're targeting + * @return This Namespace + */ + to( room: string ): Namespace; + + /** + * @see to( room ) + */ + in( room: string ): Namespace; + + /** + * Sends a 'message' event + * @see emit( event, ...args ) + * @return This Namespace + */ + send( ...args: any[] ): Namespace; + + /** + * @see send( ...args ) + */ + write( ...args: any[] ): Namespace; - on(event: 'connection', listener: (socket: Socket) => void): Namespace; - on(event: 'connect', listener: (socket: Socket) => void): Namespace; - on(event: string, listener: Function): Namespace; - } + /** + * The event fired when we get a new connection + * @param event The event being fired: 'connection' + * @param listener A listener that should take one parameter of type Socket + * @return This Namespace + */ + on( event: 'connection', listener: ( socket: Socket ) => void ): Namespace; + + /** + * @see on( 'connection', listener ) + */ + on( event: 'connect', listener: ( socket: Socket ) => void ): Namespace; + + /** + * Base 'on' method to add a listener for an event + * @param event The event that we want to add a listener for + * @param listener The callback to call when we get the event. The parameters + * for the callback depend on the event + * @ This Namespace + */ + on( event: string, listener: Function ): Namespace; + } - interface Socket { - rooms: string[]; - client: Client; - conn: any; - request: any; - id: string; - handshake: { - headers: any; - time: string; - address: any; - xdomain: boolean; - secure: boolean; - issued: number; - url: string; - query: any; - }; + /** + * The socket, which handles our connection for a namespace. NOTE: while + * we technically extend NodeJS.EventEmitter, we're not putting it here + * as we have a problem with the emit() event (as it's overridden with a + * different return) + */ + interface Socket { + + /** + * The namespace that this socket is for + */ + nsp: Namespace; + + /** + * The Server that our namespace is in + */ + server: Server; + + /** + * The Adapter that we use to handle our rooms + */ + adapter: Adapter; + + /** + * The unique ID for this Socket. Regenerated at every connection. This is + * also the name of the room that the Socket automatically joins on connection + */ + id: string; + + /** + * The http.IncomingMessage request sent with the connection. Useful + * for recovering headers etc + */ + request: any; + + /** + * The Client associated with this Socket + */ + client: Client; + + /** + * The underlying Engine.io Socket instance + */ + conn: { + + /** + * The ID for this socket - matches Client.id + */ + id: string; + + /** + * The Engine.io Server for this socket + */ + server: any; + + /** + * The ready state for the client. Either 'opening', 'open', 'closing', or 'closed' + */ + readyState: string; + + /** + * The remote IP for this connection + */ + remoteAddress: string; + }; + + /** + * The list of rooms that this Socket is currently in + */ + rooms: string[]; + + /** + * Is the Socket currently connected? + */ + connected: boolean; + + /** + * Is the Socket currently disconnected? + */ + disconnected: boolean; + + /** + * The object used when negociating the handshake + */ + handshake: { + /** + * The headers passed along with the request. e.g. 'host', + * 'connection', 'accept', 'referer', 'cookie' + */ + headers: any; + + /** + * The current time, as a string + */ + time: string; + + /** + * The remote address of the connection request + */ + address: string; + + /** + * Is this a cross-domain request? + */ + xdomain: boolean; + + /** + * Is this a secure request? + */ + secure: boolean; + + /** + * The timestamp for when this was issued + */ + issued: number; + + /** + * The request url + */ + url: string; + + /** + * Any query string parameters in the request url + */ + query: any; + }; + + /** + * Sets the 'json' flag when emitting an event + */ + json: Socket; + + /** + * Sets the 'volatile' flag when emitting an event. Volatile messages are + * messages that can be dropped because of network issues and the like. Use + * for high-volume/real-time messages where you don't need to receive *all* + * of them + */ + volatile: Socket; + + /** + * Sets the 'broadcast' flag when emitting an event. Broadcasting an event + * will send it to all the other sockets in the namespace except for yourself + */ + broadcast: Socket; + + /** + * Emits an event to this client. If the 'broadcast' flag was set, this will + * emit to all other clients, except for this one + * @param event The event that we want to emit + * @param args Any number of optional arguments to pass with the event. If the + * last argument is a function, it will be called as an ack. The ack should + * take whatever data was sent with the packet + * @return This Socket + */ + emit( event: string, ...args: any[]): Socket; + + /** + * Targets a room when broadcasting + * @param room The name of the room that we're targeting + * @return This Socket + */ + to( room: string ): Socket; + + /** + * @see to( room ) + */ + in( room: string ): Socket; + + /** + * Sends a 'message' event + * @see emit( event, ...args ) + */ + send( ...args: any[] ): Socket; + + /** + * @see send( ...args ) + */ + write( ...args: any[] ): Socket; + + /** + * Joins a room. You can join multiple rooms, and by default, on connection, + * you join a room with the same name as your ID + * @param name The name of the room that we want to join + * @param fn An optional callback to call when we've joined the room. It should + * take an optional parameter, err, of a possible error + * @return This Socket + */ + join( name: string, fn?: ( err?: any ) => void ): Socket; + + /** + * Leaves a room + * @param name The name of the room to leave + * @param fn An optional callback to call when we've left the room. It should + * take on optional parameter, err, of a possible error + */ + leave( name: string, fn?: Function ): Socket; + + /** + * Leaves all the rooms that we've joined + */ + leaveAll(): void; + + /** + * Disconnects this Socket + * @param close If true, also closes the underlying connection + * @return This Socket + */ + disconnect( close: boolean ): Socket; + + /** + * Adds a listener for a particular event. Calling multiple times will add + * multiple listeners + * @param event The event that we're listening for + * @param fn The function to call when we get the event. Parameters depend on the + * event in question + * @return This Socket + */ + on( event: string, fn: Function ): Socket; + + /** + * @see on( event, fn ) + */ + addListener( event: string, fn: Function ): Socket; + + /** + * Adds a listener for a particular event that will be invoked + * a single time before being automatically removed + * @param event The event that we're listening for + * @param fn The function to call when we get the event. Parameters depend on + * the event in question + * @return This Socket + */ + once( event: string, fn: Function ): Socket; + + /** + * Removes a listener for a particular type of event. This will either + * remove a specific listener, or all listeners for this type of event + * @param event The event that we want to remove the listener of + * @param fn The function to remove, or null if we want to remove all functions + * @return This Socket + */ + removeListener( event: string, fn?: Function ): Socket; + + /** + * Removes all event listeners on this object + * @return This Socket + */ + removeAllListeners(): Socket; + + /** + * Sets the maximum number of listeners this instance can have + * @param n The max number of listeners we can add to this emitter + * @return This Socket + */ + setMaxListeners( n: number ): Socket; + + /** + * Returns all the callbacks for a particular event + * @param event The event that we're looking for the callbacks of + * @return An array of callback Functions, or an empty array if we don't have any + */ + listeners( event: string ):Function[]; + } + + /** + * The interface used when dealing with rooms etc + */ + interface Adapter extends NodeJS.EventEmitter { + + /** + * The namespace that this adapter is for + */ + nsp: Namespace; + + /** + * A dictionary of all the rooms that we have in this namespace, each room + * a dictionary of all the sockets currently in that room + */ + rooms: {[room: string]: {[id: string]: boolean }}; + + /** + * A dictionary of all the socket ids that we're dealing with, and all + * the rooms that the socket is currently in + */ + sids: {[id: string]: {[room: string]: boolean}}; + + /** + * Adds a socket to a room. If the room doesn't exist, it's created + * @param id The ID of the socket to add + * @param room The name of the room to add the socket to + * @param callback An optional callback to call when the socket has been + * added. It should take an optional parameter, error, if there was a problem + */ + add( id: string, room: string, callback?: ( err?: any ) => void ): void; + + /** + * Removes a socket from a room. If there are no more sockets in the room, + * the room is deleted + * @param id The ID of the socket that we're removing + * @param room The name of the room to remove the socket from + * @param callback An optional callback to call when the socket has been + * removed. It should take on optional parameter, error, if there was a problem + */ + del( id: string, room: string, callback?: ( err?: any ) => void ): void; + + /** + * Removes a socket from all the rooms that it's joined + * @param id The ID of the socket that we're removing + */ + delAll( id: string ):void; + + /** + * Broadcasts a packet + * @param packet The packet to broadcast + * @param opts Any options to send along: + * - rooms: An optional list of rooms to broadcast to. If empty, the packet is broadcast to all sockets + * - except: A list of Socket IDs to exclude + * - flags: Any flags that we want to send along ('json', 'volatile', 'broadcast') + */ + broadcast( packet: any, opts: { rooms?: string[], except?: string[], flags?: {[flag: string]: boolean} } ):void; + } - emit(name: string, ...args: any[]): Socket; - join(name: string, fn?: Function): Socket; - leave(name: string, fn?: Function): Socket; - to(room: string): Socket; - in(room: string): Socket; - send(...args: any[]): Socket; - write(...args: any[]): Socket; - - on(event: string, listener: Function): Socket; - once(event: string, listener: Function): Socket; - removeListener(event: string, listener: Function): Socket; - removeAllListeners(event: string): Socket; - broadcast: Socket; - volatile: Socket; - connected: boolean; - disconnect(close?: boolean): Socket; - } - - interface Client { - conn: any; - request: any; - id: string; - } + /** + * The client behind each socket (can have multiple sockets) + */ + interface Client { + /** + * The Server that this client belongs to + */ + server: Server; + + /** + * The underlying Engine.io Socket instance + */ + conn: { + + /** + * The ID for this socket - matches Client.id + */ + id: string; + + /** + * The Engine.io Server for this socket + */ + server: any; + + /** + * The ready state for the client. Either 'opening', 'open', 'closing', or 'closed' + */ + readyState: string; + + /** + * The remote IP for this connection + */ + remoteAddress: string; + }; + + /** + * The ID for this client. Regenerated at every connection + */ + id: string; + + /** + * The http.IncomingMessage request sent with the connection. Useful + * for recovering headers etc + */ + request: any; + + /** + * The list of sockets currently connect via this client (i.e. to different + * namespaces) + */ + sockets: Socket[]; + + /** + * A dictionary of all the namespaces for this client, with the Socket that + * deals with that namespace + */ + nsps: {[nsp: string]: Socket}; + } }