# API

**Kind**: interface | **Module**: [Interop](https://docs.interop.io/desktop/reference/javascript/interop/index.md) | **Access**: `io.interop`

**Source**: https://docs.interop.io/desktop/reference/javascript/interop/api/index.html

## Properties

- **`instance`** (`Instance`, required)
  Instance of the current application.

## Methods

### createStream

Creates a new Interop stream.

```ts
(methodDefinition: string | MethodDefinition, options?: StreamOptions, successCallback?: (args?: object) => void, errorCallback?: (error?: string | object) => void) => Promise<Stream>
```

**Parameters**

- **`methodDefinition`** (`string | MethodDefinition`, required)
  A unique string or a [`MethodDefinition`](https://docs.interop.io/desktop/reference/javascript/interop/methoddefinition/index.md) for the stream to be registered.
- **`options`** (`StreamOptions`, optional)
  The [`StreamOptions`](https://docs.interop.io/desktop/reference/javascript/interop/streamoptions/index.md) object allows you to pass several optional callbacks which let your application
  handle subscriptions in a more detailed manner.
- **`successCallback`** (`(args?: object) => void`, optional)
  An optional handler to be called if the creation of the stream succeeds.
- **`errorCallback`** (`(error?: string | object) => void`, optional)
  An optional handler to be called in case of an error when creating a stream.

**Returns**: `Promise<Stream>`

**Example**

```ts
```javascript
io.interop.createStream(
    {
        name: "MarketData.LastTrades",
        displayName: "Publishes last trades for a symbol",
        objectTypes: ["Symbol"],
        accepts: "String symbol",
        returns: "String symbol, Double lastTradePrice, Int lastTradeSize"
    })
    .then((stream) =>
        setInterval(() =>
            stream.push(
                {
                    symbol: "GOOG",
                    lastTradePrice: 700.91,
                    lastTradeSize: 10500
                }),
            5000)
    )
    .catch(console.error);
```
```

### invoke

Invokes an Interop method with some arguments on target servers.

```ts
<T>(method: string | MethodDefinition, argumentObj?: object, target?: InstanceTarget, options?: InvokeOptions, success?: InvokeSuccessHandler<T>, error?: InvokeErrorHandler) => Promise<InvocationResult<T>>
```

**Parameters**

- **`method`** (`string | MethodDefinition`, required)
  The unique `name` or the [`MethodDefinition`](https://docs.interop.io/desktop/reference/javascript/interop/methoddefinition/index.md) of the method to be invoked.
- **`argumentObj`** (`object`, optional)
  A plain JavaScript object (or JSON) holding key/value pairs passed as named arguments to the handler of the registered Interop method.
- **`target`** (`InstanceTarget`, optional)
  Specifies which servers to target. Can be one of: "best", "all", [`Instance`](https://docs.interop.io/desktop/reference/javascript/interop/instance/index.md), `Instance[]`.
- **`options`** (`InvokeOptions`, optional)
  An optional [`InvokeOptions`] object specifying the timeouts to discover a method and to wait for a method reply.
- **`success`** (`InvokeSuccessHandler<T>`, optional)
  An [`InvokeSuccessHandler`](https://docs.interop.io/desktop/reference/javascript/interop/invokesuccesshandler/index.md) handler to be called if the invocation succeeds.
- **`error`** (`InvokeErrorHandler`, optional)
  An [`InvokeErrorHandler`](https://docs.interop.io/desktop/reference/javascript/interop/invokeerrorhandler/index.md) handler to be called in case of error.

**Returns**: `Promise<InvocationResult<T>>`

**Example**

```ts
```javascript
io.interop.invoke(
    "Sum",
    { a: 37, b: 5 }) // everything else is optional
    .then(successResult => {
        console.log(`37 + 5 = ${successResult.returned.answer}`);
    })
    .catch(err => {
        console.error(`Failed to execute Sum ${err.message}`);
    });
```
```

### methodAdded

Subscribes to the event which fires when a method is added for the first time by any application.

```ts
(callback: (method: Method) => void) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(method: Method) => void`, required)
  A handler to be called when the event fires.

**Returns**: `UnsubscribeFunction`

### methodRemoved

Subscribes to the event which fires when a method is removed from the last application offering it.

```ts
(callback: (method: Method) => void) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(method: Method) => void`, required)
  A handler to be called when the event fires.

**Returns**: `UnsubscribeFunction`

### methods

Returns all methods that match the passed filter.
If no filter is specified, returns all methods.

```ts
(filter?: MethodFilter | string) => Method[]
```

**Parameters**

- **`filter`** (`MethodFilter | string`, optional)
  An object describing a filter matching one or more Interop methods. If string will match the method by name

**Returns**: `Method[]`

### methodsForInstance

Returns all Interop methods registered by a server.

```ts
(server: Instance) => Method[]
```

**Parameters**

- **`server`** (`Instance`, required)
  An Interop [`Instance`](https://docs.interop.io/desktop/reference/javascript/interop/instance/index.md) identifying an application.

**Returns**: `Method[]`

### register

Registers a new Interop method.

```ts
<T,R>(name: string | MethodDefinition, handler: (args: T, caller: Instance) => R | void | Promise<R>) => Promise<void>
```

**Parameters**

- **`name`** (`string | MethodDefinition`, required)
  A unique string or a [`MethodDefinition`](https://docs.interop.io/desktop/reference/javascript/interop/methoddefinition/index.md) for the method to be registered.
- **`handler`** (`(args: T, caller: Instance) => R | void | Promise<R>`, required)
  The JavaScript function that will be called when the method is invoked.

**Returns**: `Promise<void>`

**Example**

```ts
```javascript
io.interop.register(
    {
        name: "Sum", // required - method name
        accepts: "int a, int b", // optional - parameters signature
        returns: "int answer" // optional - result signature
    },
    (args) => {   // required - handler function
        return { answer: args.a + args.b };
    }
);
```
```

### serverAdded

Subscribes to the event which fires when an application offering methods is discovered.

```ts
(callback: (server: Instance) => void) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(server: Instance) => void`, required)
  A handler to be called when the event fires.

**Returns**: `UnsubscribeFunction`

### serverMethodAdded

Subscribes to the event which fires when an application starts offering a method. This will be called every time a server starts offering the method,
whereas [`methodAdded()`](https://docs.interop.io/desktop/reference/javascript/interop/api/index.md#API-methodAdded) will be called only the first time the method is registered.

```ts
(callback: (info: { server: Instance; method: Method; }) => void) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(info: { server: Instance; method: Method; }) => void`, required)

**Returns**: `UnsubscribeFunction`

### serverMethodRemoved

Subscribes for the event which fires when a server stops offering a method. This will be called every time a server stops offering the method,
whereas [`methodRemoved()`](https://docs.interop.io/desktop/reference/javascript/interop/api/index.md#API-methodRemoved) will be called only when the method is removed from the last application offering it.

```ts
(callback: ( info: { server: Instance; method: Method; } ) => void) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`( info: { server: Instance; method: Method; } ) => void`, required)
  A handler to be called when the event fires.

**Returns**: `UnsubscribeFunction`

### serverRemoved

Subscribes to the event which fires when an app offering methods stops offering them or exits.

```ts
(callback: (server: Instance) => void) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(server: Instance) => void`, required)
  A handler to be called when the event fires.

**Returns**: `UnsubscribeFunction`

### servers

Returns all Interop aware applications.
Optionally, the list can be filtered to return only servers providing specific Interop method(s)
by passing a `methodFilter`.

```ts
(filter?: MethodFilter) => Instance[]
```

**Parameters**

- **`filter`** (`MethodFilter`, optional)
  An object describing a filter matching one or more Interop methods.

**Returns**: `Instance[]`

### subscribe

Subscribes to an Interop stream.

```ts
(methodDefinition: string | MethodDefinition, parameters?: SubscriptionParams) => Promise<Subscription>
```

**Parameters**

- **`methodDefinition`** (`string | MethodDefinition`, required)
  The unique `name` or the [`MethodDefinition`](https://docs.interop.io/desktop/reference/javascript/interop/methoddefinition/index.md) of the stream to subscribe to.
- **`parameters`** (`SubscriptionParams`, optional)
  An optional [`SubscriptionParams`](https://docs.interop.io/desktop/reference/javascript/interop/subscriptionparams/index.md) object with parameters.

**Returns**: `Promise<Subscription>`

**Example**

```ts
```javascript
io.interop.subscribe(
    "MarketData.LastTrades",
    {
    	   arguments: { symbol: "GOOG" },
    	   target: "all"
    })
    .then((subscription) => {
    	    // use subscription
    })
    .catch((error) => {
    	    // subscription rejected or failed
    });
```
```

### unregister

Unregisters an Interop method.

```ts
(definition: string | MethodDefinition) => void
```

**Parameters**

- **`definition`** (`string | MethodDefinition`, required)
  The unique `name` or the [`MethodDefinition`](https://docs.interop.io/desktop/reference/javascript/interop/methoddefinition/index.md) of the method to be unregistered.

**Returns**: `void`

### waitForMethod

Wait for a method to be available. If the method is already registered this will resolve immediately
otherwise will wait until the method appears

```ts
(name: string) => Promise<Method>
```

**Parameters**

- **`name`** (`string`, required)
  Name of the method to wait for

**Returns**: `Promise<Method>`

## Related types

- [Instance](https://docs.interop.io/desktop/reference/javascript/interop/instance/index.md)
- [InstanceTarget](https://docs.interop.io/desktop/reference/javascript/interop/instancetarget/index.md)
- [InvocationResult](https://docs.interop.io/desktop/reference/javascript/interop/invocationresult/index.md)
- [InvokeErrorHandler](https://docs.interop.io/desktop/reference/javascript/interop/invokeerrorhandler/index.md)
- [InvokeOptions](https://docs.interop.io/desktop/reference/javascript/interop/invokeoptions/index.md)
- [InvokeSuccessHandler](https://docs.interop.io/desktop/reference/javascript/interop/invokesuccesshandler/index.md)
- [Method](https://docs.interop.io/desktop/reference/javascript/interop/method/index.md)
- [MethodDefinition](https://docs.interop.io/desktop/reference/javascript/interop/methoddefinition/index.md)
- [MethodFilter](https://docs.interop.io/desktop/reference/javascript/interop/methodfilter/index.md)
- [Stream](https://docs.interop.io/desktop/reference/javascript/interop/stream/index.md)
- [StreamOptions](https://docs.interop.io/desktop/reference/javascript/interop/streamoptions/index.md)
- [Subscription](https://docs.interop.io/desktop/reference/javascript/interop/subscription/index.md)
- [SubscriptionParams](https://docs.interop.io/desktop/reference/javascript/interop/subscriptionparams/index.md)
- [UnsubscribeFunction](https://docs.interop.io/desktop/reference/javascript/search/unsubscribefunction/index.md)