Intuitive structural type notation for JavaScript.
JavaScript
Latest commit 501567c Sep 28, 2016 @Mouvedia Mouvedia committed on GitHub typo

README.md

Rtype

Join the chat at https://gitter.im/ericelliott/rtype

Intuitive structural type notation for JavaScript.

Dear JSDoc,

We've had some good times. But it's over. I've moved on.

I've switched to Rtype. Now my interface docs are alive!

~ Eric

(param: Type) => ReturnType

This repository is for the notation documentation and parser.

If you're interested in using rtype to build interfaces in your standard JavaScript code, see rfx.

Table of Contents

About Rtype

  • Great for simple documentation.
  • Compiler-agnostic type notation - for use with ECMAScript standard tools.
  • Low learning curve for JavaScript developers.
  • Can embed in JS as strings, for example with rfx. Affords easy runtime reflection.
  • Standing on the shoulders of giants. Inspired by: ES6, TypeScript, Haskell, Flow, & React

What is Rtype?

Rtype is a JS-native representation of structural type interfaces with a TypeScript-inspired notation that's great for documentation.

Status: RFC

Developer preview. Please comment.

Currently in-use for production library API documentation, but breaking changes are expected.

In the future, the rtype library will parse rtype strings and return predicate functions for runtime type checking. Static analysis tools are also in development. If you're interested in helping, please contact us.

Why?

Perhaps the most important part of API documentation is to quickly grasp the function signatures and data structures required to work with the API. There are existing standards for this stuff, but we think we can improve on them:

  • JSDoc is too verbose, not intuitive, and painful to maintain.
  • TypeScript's structural types are very appealing, but opting into TypeScript's JS superset and runtime limitations is not.

We want a type representation that is very clear to modern JavaScript developers (ES2015+), that could potentially be used at runtime with simple utilities.

Why Not Just Use TypeScript?

We want the best of all worlds:

  • An intuitive way to describe interfaces for the purposes of documentation, particularly function signatures.
  • Runtime accessible type reflection (even in production) with optional runtime type checks that can be disabled in production (like React.PropTypes). See rfx.
  • A way to specify types in standard ES2015+ code. Use any standard JS compiler. See rfx.
  • An easy way to generate interface documentation (like JSDoc).

TypeScript is great for compile-time and IDE features, and you could conceivably generate docs with it, but runtime features are lacking. For example, I want the ability to query function signatures inside the program at runtime, along with the ability to turn runtime type checking on and off. AFAIK, that's not possible with TypeScript (yet - there is experimental runtime support using experimental features of the ESNext Reflect API).

Reading Function Signatures

Function types are described by a function signature. The function signature tells you each parameter and its type, separated by a colon, and the corresponding return type:

(param: Type) => ReturnType

To make the signature familiar to readers, we use common JavaScript idioms such as destructuring, defaults, and rest parameters:

(...args: [...String]) => Any
({ count = 0: Number }) => Any

If a parameter or property has a default value, most built-in types can be inferred:

({ count = 0 }) => Any

If the type is a union or Any, it must be specified:

({ collection = []: Array | Object }) => Any

Optionally, you may name the return value, similar to named parameters:

(param: Type) => name: Type

Or even name a signature to reuse it later on:

connect(options: Object) => connection: Object

Optional Parameters

Optional parameters can be indicated with ?:

(param: Type, optParam?: Type) => ReturnType

Anonymous Parameters

Parameter names can be omitted:

is(Any) => Boolean

In the case of an anonymous optional parameter the type must be prefixed by ?::

toggle(String, ?: Boolean) => Boolean

In the case of an anonymous rest parameter, simply omit the name:

(...: [...Any]) => Array

Reserved Types

Builtin Types

Array, Boolean, Function, Number, Object, RegExp, String, Symbol
ArrayBuffer, Date, Error, Map, Promise, Proxy, Set, WeakMap, WeakSet

Many builtin types are named after JavaScript constructors. Many syntax highlighters will make the types stand out when the signature is rendered in the docs.

The Any Type

The special type Any means that any type is allowed:

(...args: [...Any]) => Array

The Void Type

The special type Void should only be used to indicate that a function returns no meaningful value (i.e., undefined). Since Void is the default return type, it can be optionally omitted. Nevertheless Void return types should usually be explicitly annotated to denote function side-effects.

set(name: String, value: String) => Void

Is equivalent to:

set(name: String, value: String)

The Predicate Type

The special type Predicate is a function with the following signature:

(...args: [...Any]) => Boolean

The Iterable Type

Arrays, typed arrays, strings, maps and sets are iterable. Additionally any object that implements the @@iterator method can be iterated.

(paramName: Iterable) => Void

Is equivalent to

interface IterableObject {
  [Symbol.iterator]: () => Iterator
}

interface Iterator {
  next() {
    done: Boolean,
    value?: Any
  }
}

(paramName: IterableObject) => Void

The TypedArray Type

It covers these contructors: Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array, Float64Array.

Literal Types

Literals are also accepted as types.

signatureName(param1: String, param2: 'value1' | 'value2' | 'value3') => -1 | 0 | 1

Tuples

The type of arrays' elements can also be specified:

// an array that contains exactly 2 elements
[Number, String]

For ∅ or more and 1 or more element(s) of the same type you can use the rest operator like so:

// 0 or more
[...Number]

// 1 or more
[Number...]
//which is equivalent to
[Number, ...Number]

Union Types

Union types are denoted with the pipe symbol, |:

(userInput: String|Number) => String|Number

Constructors

Constructors in JavaScript require the new keyword. You can identify a constructor signature using the new keyword as if you were demonstrating usage:

new User({ username: String }) => UserInstance: Object

In JavaScript, a class or constructor is not synonymous with an interface. The class or constructor definition describe the function signature to create the object instances. A separate signature is needed to describe the instances created by the function. For that, use a separate interface with a different name:

interface UserInstance {
  username: String,
  credentials: String
}

Accessor Descriptors

An accessor function is defined by prefixing a method with get or set.

new User({ username: String }) => {
  username: String,
  get name() => String,
  set name(newName: String) // return type defaults to Void
}

Throwing functions

To indicate that a function can throw an error you can use the throws keyword.

(paramName: Type) => Type, throws: TypeError|DOMException

For the generic Error type, you can optionally omit the throw type:

(paramName: Type) => Type, throws

Is equivalent to:

(paramName: Type) => Type, throws: Error

Dependencies

You can optionally list your functions' dependencies. In the future, add-on tools may automatically scan your functions and list dependencies for you, which could be useful for documentation and to identify polyfill requirements.

// one dependency
signatureName() => Type, requires: functionA

// several dependencies
signatureName()
  => Type,
  requires: functionA, functionB

Interface: User Defined Types

You can create your own types using the interface keyword.

An interface can spell out the structure of an object:

interface UserInstance {
  name: String,
  avatarUrl?: Url,
  about?: String
}

Interfaces support builtin literal types:

interface UserInstance {
  name: /\w+/,
  description?: '',
  friends?: [],
  profile?: {}
}

A one-line interface doesn't need brackets:

interface Name: /\w+/

Function Interface

A regular function signature is a shorthand for a function interface:

user({ name: String, avatarUrl?: Url }) => UserInstance

A function interface must have a function signature:

interface user {
  ({ name: String,  avatarUrl?: Url }) => UserInstance
}

For polymorphic functions, use multiple function signatures:

interface Collection {
  (items: [...Array]) => [...Array],
  (items: [...Object]) => [...Object]
}

Note that named function signatures in an interface block indicate methods, rather than additional function signatures:

interface Collection {
  (signatureParam: Any) => Any, // Collection() signature
  method1(items: [...Array]) => [...Array], // method
  method2(items: [...Object]) => [...Object] // method
}

// in JS:
// typeof Collection === 'function'
// typeof Collection.method1 === 'function'
// typeof Collection.method2 === 'function'

Predicate Literals

Interfaces may use predicate literals, terminated by a semicolon:

interface Integer (number) => number === parseInt(number, 10);

You can combine predicate literals with interface blocks. Semicolon disambiguates:

interface EnhancedInteger (number) => number === parseInt(number, 10); {
  isDivisibleBy3() => Boolean,
  double() => Number
}

Multi-line example:

interface EnhancedInteger (number) => {
  return number === parseInt(number, 10);
}; {
  isDivisibleBy3() => Boolean,
  double() => Number
}

Composing types

Whenever you want to compose an interface out of several others, use the spread operator for that:

interface Person {
  name: Name,
  birthDate: Number,
}

interface User {
  username: String,
  description?: String,
  kudos = 0: Number,
}

interface HumanUser {
  ...Person,
  ...User,
  avatarUrl: String,
}

You can also use the spread inside object type literals:

interface Company {
  name: Name,
  owner: { ...Person, shareStake: Number },
}

In case of a name conflict, properties with same names are merged. It means all prerequisites must be satisfied. It’s fine to make types more specific through type literals:

interface Creature {
  name: String,
  character: String,
  strength: (number) => (number >= 0 && number <= 100),
}

interface Human {
  ...Creature,
  name: /^(.* )?[A-Z][a-z]+$/,
  character: 'friendly' | 'grumpy',
}

To make sure we can run a static type check for you, we don’t allow merging two different literals. So this would result in a compile error:

// Invalid!
interface Professor {
  ...Human,
  name: /^prof\. \w+$/,
}

Obviously, merging incompatible interfaces is also invalid:

// Invalid!
interface Bot {
  ...Creature,
  name: Number,
}

Event Emitters

When composing an observable interface, you can use the emits keyword to describe the events it emits:

interface Channel {
  ...EventEmitter
}, emits: {
  'messageAdded': (body: String, authorId: Number),
  'memberJoined': (id: Number, { name: String, email: String })
}

Comments

Standard JS comment syntax applies, e.g.:

// A single-line comment, can appear at the end of a line.

/*
  A multi-line comment.
  Can span many lines.
*/

interfaces.rtype

If you find yourself using the same custom types all over your project, you can keep their definitions in one interfaces.rtype file in the root of the project. Don’t forget to set up your editor so that it treats *.rtype files as JavaScript.

At the moment you can use this file for documenting your project. But we’re soon rolling out analysis tools for rtype. In the future they will be able to import the file and use your definitions for static type analysis.

References

Somewhat related ideas and inspiration sources.