Latest revision as of 11:14, 22 June 2016

Potential API Changes
This page describes a new, consumable API for the JavaScript language tools that is still in development. As new features, frameworks and protocols are added or removed, the shape of the API may change in a compatible way over time.

Experimental API

In Orion 12.0 we are developing an API that will allow the JavaScript language tools to be built and directly consumed outside of Orion - say for example, as a plugin in another IDE.

To begin using the API, you first have to build the library that provides the API (as it is not part of the normal Orion client build).

On the Orion/JavaScript/Build we have step-by-step instructions on building the API bundle.

API Dependencies

Once you have built the bundle, you can consume it by requiring it (or AMD define it, etc) and instantiating the JavaScript constructor.

For example, to require it in an AMD environment, you might do:

define(function (require) {
  var orionJSLib = require("./lib/orionJavaScript");
  var orionJS = new orionJSLib(new scriptResolver());
});

and then call the API functions on orionJS as needed. When creating an instance of the API, you'll notice that you have to provide a shim to tell the tools how to find / resolve files. In the above example, we have new scriptResolver() to denote where the shim is instantiated / used. There is much more detail on the shape of the resolver object in the script resolver section.

The Script Resolver

When creating a new instance of the tools, you have to provide a way (shim) for the tools to look up and resolve files. This is what we term the scriptResolver.

Currently, the resolver must have the following shape:

ScriptResolver.prototype.getFileClient()

Returns an object that provides search and reading functions to the file system / server

ScriptResolver.prototype.getWorkspaceFile(logicalName, options)

Returns a file object for the given logical name and options

ScriptResolver.prototype.resolveRelativeFiles(path, files, metadata)

Resolves the list of possible files against the base path, optionally using the given metadata (more on the metadata object in a later section)

The File Client

The file client object is returned from the script resolver shim, and must have the following shape:

FileClient.prototype.fileServiceRootURL()

Returns the string root of the service (in most simple cases this is "/")

FileClient.prototype.search(options)

Returns a list of file objects for the given options (more on the search options in a later section)

FileClient.prototype.read(filename)

Returns the contents and metadata for a file with the given name

The Metadata Object

This object is used to describe a file (without necessarily being a handle to that file) and must contain at least the following information:

name

The string name of the file

location

The string location of the file. This is the full path to the file, such that a read could read the contents of the file

path

The string, workspace-relative path of the file

contentType

An object that contains the id of the content type

The File Object

This object is used to describe a file, and carries the contents of the file (typically this object is returned from FileClient.read. The object must have the following shape:

name

The string name of the file

location

The string, fully qualified path of the file - where it was read from

contents

The string contents of the file

Get Workspace File Options

This object is passed into ScriptResolver.getWorkspaceFile and can contain any additional options needed to find the files in the workspace.

The Search Options

This object is passed into FileClient.search, and can contain any additional options needed to perform the search.

Consuming the API

Once you have a freshly minted instance of the tools in your hand (after providing the necessary shims), you can simply make function calls for the support you would like to use.

The API is arranged with some functions directly on the instance and some of them on a Tern child object.

More specifically the API currently looks like:

JavaScript.prototype.Tern.addFile(file, text)

Add the given file and contents to Tern

JavaScript.prototype.Tern.checkRef(file, offset, origin, files, callback)

Check the given reference against the original to see if the types match

JavaScript.prototype.Tern.completions(file, offset, keywords, files, callback)

Compute content assist

JavaScript.prototype.Tern.definition(file, offset, guess, files, callback)

Get the definition at the given offset

JavaScript.prototype.Tern.delFile(file)

Delete the given file from Tern

JavaScript.prototype.Tern.documentation(file, offset, docFormat, files, callback)

Get the JSDoc for the thing at the given offset

JavaScript.prototype.Tern.environments(callback)

Get all of the detected environments from Tern (a delegate to a custom parser hook)

JavaScript.prototype.Tern.fixes(file, annotation, annotations, files, callback)

Computes the quick fixes for the given annotation, and optionally the list of similar annotations

JavaScript.prototype.Tern.implementation(file, offset, guess, files, callback)

Find the actual implementation of the thing at the given offset (not just its declaration)

JavaScript.prototype.Tern.installedPlugins(callback)

Get all of the plugins currently installed in Tern

JavaScript.prototype.Tern.lint(file, rules, env, files, callback)

Run ESLint on the given file with the given rules / settings

JavaScript.prototype.Tern.occurrences(file, offset, files, callback)

Compute the occurrences for the given file and offset

JavaScript.prototype.Tern.outline(file, files, callback)

Compute a source outline for the given file

JavaScript.prototype.Tern.rename(file, offset, newname, files, callback)

Compute a rename change set at the given offset, for the new name

JavaScript.prototype.Tern.startServer(jsonOptions, callback)

Start (or restart) the running Tern server

JavaScript.prototype.Tern.type(file, offset, callback)

Look up the type information at the given offset

More and more functionality will be added over time, such as, access to the quick fix computer, doc generation and markdown hovers. We chose to provide access to the underlying Tern server first, so we could make a Tern service on Orion for other plugins.

The Callback Function

For most of the API, you are required to give a function that will be called when the tools have completed processing your request. In all cases, the callback will be called, and will be called with the first param being an error (if one) and the second param being the results of the request.