typenode v5.3.11

TypeNode

TypeScript 1.5 declarations for Node.js 0.12.

Why?

There already exists a set of Node.js type declarations in DefinitelyTyped. Why use TypeNode over those?

• Available directly on npm
• Focus on the Node.js standard library
• Split into files corresponding to Node.js standard libraries
• Up-to-date TypeScript (1.5)
• Up-to-date Node.js (0.12)
• Tested against Node.js documentation examples
  • On Travis
  • With noImplicitAny
• Working subclass chaining methods (see CRTP)

Patterns

API

Only the documented, non-deprecated, Node.js standard library API is declared. As much as possible, the type declarations follow the order of the documentation. Each page of the API documentation corresponds to one .d.ts file.

Inter-dependencies

The node.d.ts file references all other declaration files. However, it is also possible to reference individual declaration files. For this reason, declaration files reference their inter-dependencies.

Internal Ambient Modules

There are several Node.js globals of types only exposed through ambient external modules (i.e import * as events from 'events';). In order to make these types available to globals, they are declared in ambient internal modules, prefixed with __. The globally available type is then aliased or subclassed in the ambient external module.

declare module __events {
  class EventEmitter {
    // ...
  }
}

declare module 'events' {
  class EventEmitter extends EventEmitter {}
}

CRTP

Many Node.js classes that are subclassed have chaining methods (i.e. methods that return this). TypeScript has no way to represent this as a return type, so the Curiously recurring template pattern is used to enable proper chaining return types on subclasses. The generic base class is prefixed with an underscore (inside a double-underscore-prefixed ambient internal module). The regular base class as well as subclasses then extend the prefixed class.

declare module __events {
  class _EventEmitter<This extends _EventEmitter<any>> {
    setMaxListeners(n: number): This;
    // ...
  }
}

declare module 'events' {
  class EventEmitter extends __events._EventEmitter<EventEmitter> {}
}

declare module 'stream' {
  class Readable extends __events._EventEmitter<Readable> {
    // ...
  }
}

Listener & Options Naming

Types of event listeners are named by the event with a Listener suffix.

type ExitListener = (code: number, signal: string) => void;

class ChildProcess {
  on(event: 'exit', listener: ExitListener): ChildProcess;
  // ...
}

Interfaces of options objects are named by the function or method with an Options suffix.

interface SpawnOptions {
  cwd?: string;
  // ...
}

function spawn(command: string, options?: SpawnOptions): ChildProcess;

Examples

All of the examples on an API documentation page are in the corresponding .ts in example. Each example is wrapped in a function to isolate scope. All requires are moved to the top of the file as ES6-style imports.

import * as assert from 'assert';

(function() {
  assert.throws(
    function() {
      throw new Error('Wrong value');
    },
    Error
  );
});

Occurrences of var are changed to let. Explicit types are added where needed. More significant changes to get the examples to compile under TypeScript should appear below the commented out original line.

Object structure examples should be assigned to a variable of the expected type.

(function() {
  let options: child_process.ExecOptions =
    { encoding: 'utf8',
      timeout: 0,
      maxBuffer: 200*1024,
      killSignal: 'SIGTERM',
      cwd: null,
      env: null };
});

License

Copyright © 2015, Curtis McEnroe curtis@cmcenroe.me

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.