Skip to content

Commit

Permalink
Add ContextService
Browse files Browse the repository at this point in the history
  • Loading branch information
joshdover committed Jul 16, 2019
1 parent ec8ec82 commit 2070364
Show file tree
Hide file tree
Showing 27 changed files with 1,075 additions and 22 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ContextContainer](./kibana-plugin-public.contextcontainer.md) &gt; [createHandler](./kibana-plugin-public.contextcontainer.createhandler.md)

## ContextContainer.createHandler() method

Create a new handler function pre-wired to context for the plugin.

<b>Signature:</b>

```typescript
createHandler(handler: Handler<TContext, THandlerReturn, THandlerParameters>): (...rest: THandlerParameters) => Promise<THandlerReturn>;
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| handler | <code>Handler&lt;TContext, THandlerReturn, THandlerParameters&gt;</code> | |

<b>Returns:</b>

`(...rest: THandlerParameters) => Promise<THandlerReturn>`

## Remarks

This must be called when the handler is registered by the consuming plugin. If this is called later in the lifecycle it will throw an exception.

Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ContextContainer](./kibana-plugin-public.contextcontainer.md)

## ContextContainer interface

An object that handles registration of context providers and building of new context objects.

<b>Signature:</b>

```typescript
export interface ContextContainer<TContext extends {}, THandlerReturn, THandlerParameters extends any[] = []>
```

## Methods

| Method | Description |
| --- | --- |
| [createHandler(handler)](./kibana-plugin-public.contextcontainer.createhandler.md) | Create a new handler function pre-wired to context for the plugin. |
| [registerContext(contextName, provider)](./kibana-plugin-public.contextcontainer.registercontext.md) | Register a new context provider. Throws an exception if more than one provider is registered for the same context key. |

## Remarks

A `ContextContainer` can be used by any Core service or plugin (known as the "service owner") which wishes to expose APIs in a handler function. The container object will manage registering context providers and building a context object for a handler with all of the contexts that should be exposed to the handler's plugin. This is dependent on the dependencies that the handler's plugin declares.

Contexts providers are executed in the order they were registered. Each provider gets access to context values provided by any plugins that it depends on.

Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ContextContainer](./kibana-plugin-public.contextcontainer.md) &gt; [registerContext](./kibana-plugin-public.contextcontainer.registercontext.md)

## ContextContainer.registerContext() method

Register a new context provider. Throws an exception if more than one provider is registered for the same context key.

<b>Signature:</b>

```typescript
registerContext<TContextName extends keyof TContext>(contextName: TContextName, provider: ContextProvider<TContext, TContextName, THandlerParameters>): this;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| contextName | <code>TContextName</code> | The key of the <code>TContext</code> object this provider supplies the value for. |
| provider | <code>ContextProvider&lt;TContext, TContextName, THandlerParameters&gt;</code> | A [ContextProvider](./kibana-plugin-public.contextprovider.md) to be called each time a new context is created. |
<b>Returns:</b>
`this`
The `ContextContainer` for method chaining.
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ContextProvider](./kibana-plugin-public.contextprovider.md)

## ContextProvider type

A function that returns a context value for a specific key of given context type.

<b>Signature:</b>

```typescript
export declare type ContextProvider<TContext extends {}, TContextName extends keyof TContext, TProviderParameters extends any[] = []> = (context: Partial<TContext>, ...rest: TProviderParameters) => Promise<TContext[TContextName]> | TContext[TContextName];
```

## Remarks

This function will be called each time a new context is built for a handler invocation.

Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ContextSetup](./kibana-plugin-public.contextsetup.md) &gt; [createContextContainer](./kibana-plugin-public.contextsetup.createcontextcontainer.md)

## ContextSetup.createContextContainer() method

Creates a new [ContextContainer](./kibana-plugin-public.contextcontainer.md) for a service owner.

<b>Signature:</b>

```typescript
createContextContainer<TContext extends {}, TProviderParameters extends any[] = []>(): ContextContainer<TContext, TProviderParameters>;
```
<b>Returns:</b>
`ContextContainer<TContext, TProviderParameters>`
52 changes: 52 additions & 0 deletions docs/development/core/public/kibana-plugin-public.contextsetup.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ContextSetup](./kibana-plugin-public.contextsetup.md)

## ContextSetup interface

An object that handles registration of context providers and building of new context objects.

<b>Signature:</b>

```typescript
export interface ContextSetup
```

## Methods

| Method | Description |
| --- | --- |
| [createContextContainer()](./kibana-plugin-public.contextsetup.createcontextcontainer.md) | Creates a new [ContextContainer](./kibana-plugin-public.contextcontainer.md) for a service owner. |

## Remarks

A `ContextContainer` can be used by any Core service or plugin (known as the "service owner") which wishes to expose APIs in a handler function. The container object will manage registering context providers and building a context object for a handler with all of the contexts that should be exposed to the handler's plugin. This is dependent on the dependencies that the handler's plugin declares.

Contexts providers are executed in the order they were registered. Each provider gets access to context values provided by any plugins that it depends on.

## Example

How to create your own context

```ts
class MyPlugin {
setup(core) {
this.myHandlers = new Map<string, Handler>();
this.contextContainer = core.createContextContainer();
return {
registerContext: this.contextContainer.register,
registerHandler: (endpoint, handler) =>
// `createHandler` must be called immediately.
this.myHandlers.set(endpoint, this.contextContainer.createHandler(handler)),
};
}

start() {
return {
registerContext: this.contextContainer.register,
};
}
}

```

Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [CoreSetup](./kibana-plugin-public.coresetup.md) &gt; [context](./kibana-plugin-public.coresetup.context.md)

## CoreSetup.context property

[ContextSetup](./kibana-plugin-public.contextsetup.md)

<b>Signature:</b>

```typescript
context: Pick<ContextSetup, 'createContextContainer'>;
```
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ export interface CoreSetup

| Property | Type | Description |
| --- | --- | --- |
| [context](./kibana-plugin-public.coresetup.context.md) | <code>Pick&lt;ContextSetup, 'createContextContainer'&gt;</code> | [ContextSetup](./kibana-plugin-public.contextsetup.md) |
| [fatalErrors](./kibana-plugin-public.coresetup.fatalerrors.md) | <code>FatalErrorsSetup</code> | [FatalErrorsSetup](./kibana-plugin-public.fatalerrorssetup.md) |
| [http](./kibana-plugin-public.coresetup.http.md) | <code>HttpSetup</code> | [HttpSetup](./kibana-plugin-public.httpsetup.md) |
| [notifications](./kibana-plugin-public.coresetup.notifications.md) | <code>NotificationsSetup</code> | [NotificationsSetup](./kibana-plugin-public.notificationssetup.md) |
Expand Down
3 changes: 3 additions & 0 deletions docs/development/core/public/kibana-plugin-public.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
| [ChromeRecentlyAccessed](./kibana-plugin-public.chromerecentlyaccessed.md) | [APIs](./kibana-plugin-public.chromerecentlyaccessed.md) for recently accessed history. |
| [ChromeRecentlyAccessedHistoryItem](./kibana-plugin-public.chromerecentlyaccessedhistoryitem.md) | |
| [ChromeStart](./kibana-plugin-public.chromestart.md) | ChromeStart allows plugins to customize the global chrome header UI and enrich the UX with additional information about the current location of the browser. |
| [ContextContainer](./kibana-plugin-public.contextcontainer.md) | An object that handles registration of context providers and building of new context objects. |
| [ContextSetup](./kibana-plugin-public.contextsetup.md) | An object that handles registration of context providers and building of new context objects. |
| [CoreSetup](./kibana-plugin-public.coresetup.md) | Core services exposed to the <code>Plugin</code> setup lifecycle |
| [CoreStart](./kibana-plugin-public.corestart.md) | Core services exposed to the <code>Plugin</code> start lifecycle |
| [DocLinksStart](./kibana-plugin-public.doclinksstart.md) | |
Expand All @@ -58,6 +60,7 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
| --- | --- |
| [ChromeHelpExtension](./kibana-plugin-public.chromehelpextension.md) | |
| [ChromeNavLinkUpdateableFields](./kibana-plugin-public.chromenavlinkupdateablefields.md) | |
| [ContextProvider](./kibana-plugin-public.contextprovider.md) | A function that returns a context value for a specific key of given context type. |
| [HttpSetup](./kibana-plugin-public.httpsetup.md) | |
| [HttpStart](./kibana-plugin-public.httpstart.md) | |
| [PluginInitializer](./kibana-plugin-public.plugininitializer.md) | The <code>plugin</code> export at the root of a plugin's <code>public</code> directory should conform to this interface. |
Expand Down
37 changes: 37 additions & 0 deletions src/core/public/context/context.mock.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
/*
* Licensed to Elasticsearch B.V. under one or more contributor
* license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright
* ownership. Elasticsearch B.V. licenses this file to you under
* the Apache License, Version 2.0 (the "License"); you may
* not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/

import { ContextContainerImplementation } from './context';

export type ContextContainerMock = jest.Mocked<
PublicMethodsOf<ContextContainerImplementation<any, any, any>>
>;

const createContextMock = () => {
const contextMock: ContextContainerMock = {
registerContext: jest.fn(),
createHandler: jest.fn(),
setCurrentPlugin: jest.fn(),
};
return contextMock;
};

export const contextMock = {
create: createContextMock,
};
Loading

0 comments on commit 2070364

Please sign in to comment.