From 9e78c2c40c5b5bff5a8cebd80a3fa591115ee3d7 Mon Sep 17 00:00:00 2001 From: Rudolf Meijering Date: Thu, 4 Jul 2019 12:01:26 +0200 Subject: [PATCH] Update types and documentation --- .../core/public/kibana-plugin-public.md | 8 +- ...plugin-public.savedobjectsbatchresponse.md | 19 +++++ ....savedobjectsbatchresponse.savedobjects.md | 11 +++ ...savedobjectsbulkcreateobject.attributes.md | 11 +++ ...gin-public.savedobjectsbulkcreateobject.md | 19 +++++ ...ublic.savedobjectsbulkcreateobject.type.md | 11 +++ ...in-public.savedobjectsbulkcreateoptions.md | 19 +++++ ...savedobjectsbulkcreateoptions.overwrite.md | 13 +++ ...in-public.savedobjectsclient.bulkcreate.md | 2 +- ...lugin-public.savedobjectsclient.bulkget.md | 2 +- ...plugin-public.savedobjectsclient.create.md | 2 +- ...a-plugin-public.savedobjectsclient.find.md | 2 +- ...kibana-plugin-public.savedobjectsclient.md | 10 +-- ...plugin-public.savedobjectsclient.update.md | 4 +- ...gin-public.savedobjectscreateoptions.id.md | 13 +++ ...plugin-public.savedobjectscreateoptions.md | 22 +++++ ...edobjectscreateoptions.migrationversion.md | 11 +++ ...lic.savedobjectscreateoptions.overwrite.md | 13 +++ ...ic.savedobjectscreateoptions.references.md | 11 +++ ...-plugin-public.savedobjectsfindresponse.md | 21 +++++ ...in-public.savedobjectsfindresponse.page.md | 11 +++ ...public.savedobjectsfindresponse.perpage.md | 11 +++ ...n-public.savedobjectsfindresponse.total.md | 11 +++ ...plugin-public.savedobjectsupdateoptions.md | 21 +++++ ...edobjectsupdateoptions.migrationversion.md | 11 +++ ...ic.savedobjectsupdateoptions.references.md | 11 +++ ...ublic.savedobjectsupdateoptions.version.md | 11 +++ .../core/server/kibana-plugin-server.md | 2 +- ...gin-server.savedobjectsmigrationversion.md | 14 +++- src/core/public/index.ts | 22 ++++- src/core/public/public.api.md | 77 +++++++++++++++--- src/core/public/saved_objects/index.ts | 17 +++- .../saved_objects/saved_objects_client.ts | 81 +++++++++++++------ .../service/saved_objects_client.ts | 15 +++- 34 files changed, 486 insertions(+), 53 deletions(-) create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsbatchresponse.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsbatchresponse.savedobjects.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateobject.attributes.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateobject.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateobject.type.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateoptions.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateoptions.overwrite.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.id.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.migrationversion.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.overwrite.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.references.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.page.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.perpage.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.total.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.migrationversion.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.references.md create mode 100644 docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.version.md diff --git a/docs/development/core/public/kibana-plugin-public.md b/docs/development/core/public/kibana-plugin-public.md index ce4daabc754773d..a948575d8d797f7 100644 --- a/docs/development/core/public/kibana-plugin-public.md +++ b/docs/development/core/public/kibana-plugin-public.md @@ -14,7 +14,7 @@ The plugin integrates with the core system via lifecycle events: `setup` | Class | Description | | --- | --- | -| [SavedObjectsClient](./kibana-plugin-public.savedobjectsclient.md) | The SavedObjectsClient class acts as a generic data fetcher and data saver for saved objects regardless of type. | +| [SavedObjectsClient](./kibana-plugin-public.savedobjectsclient.md) | Saved Objects is Kibana's data persisentence mechanism allowing plugins to use Elasticsearch for storing plugin state. The client-side SavedObjectsClient is a thin convenience library around the SavedObjects HTTP API for interacting with Saved Objects. | | [SimpleSavedObject](./kibana-plugin-public.simplesavedobject.md) | This class is a very simple wrapper for SavedObjects loaded from the server with the [SavedObjectsClient](./kibana-plugin-public.savedobjectsclient.md).It provides basic functionality for creating/saving/deleting saved objects, but doesn't include any type-specific implementations. | | [ToastsApi](./kibana-plugin-public.toastsapi.md) | | | [UiSettingsClient](./kibana-plugin-public.uisettingsclient.md) | | @@ -53,7 +53,13 @@ The plugin integrates with the core system via lifecycle events: `setup` | [OverlayStart](./kibana-plugin-public.overlaystart.md) | | | [Plugin](./kibana-plugin-public.plugin.md) | The interface that should be returned by a PluginInitializer. | | [PluginInitializerContext](./kibana-plugin-public.plugininitializercontext.md) | The available core services passed to a PluginInitializer | +| [SavedObjectsBatchResponse](./kibana-plugin-public.savedobjectsbatchresponse.md) | | +| [SavedObjectsBulkCreateObject](./kibana-plugin-public.savedobjectsbulkcreateobject.md) | | +| [SavedObjectsBulkCreateOptions](./kibana-plugin-public.savedobjectsbulkcreateoptions.md) | | +| [SavedObjectsCreateOptions](./kibana-plugin-public.savedobjectscreateoptions.md) | | +| [SavedObjectsFindResponse](./kibana-plugin-public.savedobjectsfindresponse.md) | | | [SavedObjectsStart](./kibana-plugin-public.savedobjectsstart.md) | | +| [SavedObjectsUpdateOptions](./kibana-plugin-public.savedobjectsupdateoptions.md) | | | [UiSettingsState](./kibana-plugin-public.uisettingsstate.md) | | ## Type Aliases diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsbatchresponse.md b/docs/development/core/public/kibana-plugin-public.savedobjectsbatchresponse.md new file mode 100644 index 000000000000000..2ccddb8f71bd6df --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsbatchresponse.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsBatchResponse](./kibana-plugin-public.savedobjectsbatchresponse.md) + +## SavedObjectsBatchResponse interface + + +Signature: + +```typescript +export interface SavedObjectsBatchResponse +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [savedObjects](./kibana-plugin-public.savedobjectsbatchresponse.savedobjects.md) | Array<SimpleSavedObject<T>> | | + diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsbatchresponse.savedobjects.md b/docs/development/core/public/kibana-plugin-public.savedobjectsbatchresponse.savedobjects.md new file mode 100644 index 000000000000000..f83b6268431c7f8 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsbatchresponse.savedobjects.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsBatchResponse](./kibana-plugin-public.savedobjectsbatchresponse.md) > [savedObjects](./kibana-plugin-public.savedobjectsbatchresponse.savedobjects.md) + +## SavedObjectsBatchResponse.savedObjects property + +Signature: + +```typescript +savedObjects: Array>; +``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateobject.attributes.md b/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateobject.attributes.md new file mode 100644 index 000000000000000..e3f7e0d67608717 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateobject.attributes.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsBulkCreateObject](./kibana-plugin-public.savedobjectsbulkcreateobject.md) > [attributes](./kibana-plugin-public.savedobjectsbulkcreateobject.attributes.md) + +## SavedObjectsBulkCreateObject.attributes property + +Signature: + +```typescript +attributes: T; +``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateobject.md b/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateobject.md new file mode 100644 index 000000000000000..8f95c0533dded35 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateobject.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsBulkCreateObject](./kibana-plugin-public.savedobjectsbulkcreateobject.md) + +## SavedObjectsBulkCreateObject interface + +Signature: + +```typescript +export interface SavedObjectsBulkCreateObject extends SavedObjectsCreateOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [attributes](./kibana-plugin-public.savedobjectsbulkcreateobject.attributes.md) | T | | +| [type](./kibana-plugin-public.savedobjectsbulkcreateobject.type.md) | string | | + diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateobject.type.md b/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateobject.type.md new file mode 100644 index 000000000000000..37497b917878224 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateobject.type.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsBulkCreateObject](./kibana-plugin-public.savedobjectsbulkcreateobject.md) > [type](./kibana-plugin-public.savedobjectsbulkcreateobject.type.md) + +## SavedObjectsBulkCreateObject.type property + +Signature: + +```typescript +type: string; +``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateoptions.md b/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateoptions.md new file mode 100644 index 000000000000000..697084d8eee38c1 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateoptions.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsBulkCreateOptions](./kibana-plugin-public.savedobjectsbulkcreateoptions.md) + +## SavedObjectsBulkCreateOptions interface + + +Signature: + +```typescript +export interface SavedObjectsBulkCreateOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [overwrite](./kibana-plugin-public.savedobjectsbulkcreateoptions.overwrite.md) | boolean | If a document with the given id already exists, overwrite it's contents (default=false). | + diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateoptions.overwrite.md b/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateoptions.overwrite.md new file mode 100644 index 000000000000000..e3b425da892b243 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsbulkcreateoptions.overwrite.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsBulkCreateOptions](./kibana-plugin-public.savedobjectsbulkcreateoptions.md) > [overwrite](./kibana-plugin-public.savedobjectsbulkcreateoptions.overwrite.md) + +## SavedObjectsBulkCreateOptions.overwrite property + +If a document with the given `id` already exists, overwrite it's contents (default=false). + +Signature: + +```typescript +overwrite?: boolean; +``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.bulkcreate.md b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.bulkcreate.md index 43c532270ab2ad5..426096d96c9ba29 100644 --- a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.bulkcreate.md +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.bulkcreate.md @@ -9,5 +9,5 @@ Creates multiple documents at once Signature: ```typescript -bulkCreate: (objects?: BulkCreateOptions[], options?: HttpFetchQuery) => Promise>; +bulkCreate: (objects?: SavedObjectsBulkCreateObject[], options?: SavedObjectsBulkCreateOptions) => Promise>; ``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.bulkget.md b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.bulkget.md index 8ccee3eb3ca8f99..fc8b3c8258f9c34 100644 --- a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.bulkget.md +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.bulkget.md @@ -12,7 +12,7 @@ Returns an array of objects by id bulkGet: (objects?: { id: string; type: string; - }[]) => Promise>; + }[]) => Promise>; ``` ## Example diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.create.md b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.create.md index ae3598ae1f46d6a..d6366494f0037fe 100644 --- a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.create.md +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.create.md @@ -9,5 +9,5 @@ Persists an object Signature: ```typescript -create: (type: string, attributes: T, options?: CreateOptions) => Promise>; +create: (type: string, attributes: T, options?: SavedObjectsCreateOptions) => Promise>; ``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.find.md b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.find.md index 8091711cacb8f98..c78d9067eda3e95 100644 --- a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.find.md +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.find.md @@ -9,5 +9,5 @@ Search for objects Signature: ```typescript -find: (options?: SavedObjectsFindOptions) => Promise>; +find: (options?: SavedObjectsFindOptions) => Promise>; ``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.md b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.md index dc922ec74fe8b57..094261389fa35db 100644 --- a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.md +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.md @@ -4,7 +4,7 @@ ## SavedObjectsClient class -The SavedObjectsClient class acts as a generic data fetcher and data saver for saved objects regardless of type. +Saved Objects is Kibana's data persisentence mechanism allowing plugins to use Elasticsearch for storing plugin state. The client-side SavedObjectsClient is a thin convenience library around the SavedObjects HTTP API for interacting with Saved Objects. Signature: @@ -22,11 +22,11 @@ export declare class SavedObjectsClient | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [bulkCreate](./kibana-plugin-public.savedobjectsclient.bulkcreate.md) | | (objects?: BulkCreateOptions<SavedObjectAttributes>[], options?: HttpFetchQuery) => Promise<BatchResponse<SavedObjectAttributes>> | Creates multiple documents at once | -| [bulkGet](./kibana-plugin-public.savedobjectsclient.bulkget.md) | | (objects?: {
id: string;
type: string;
}[]) => Promise<BatchResponse<SavedObjectAttributes>> | Returns an array of objects by id | -| [create](./kibana-plugin-public.savedobjectsclient.create.md) | | <T extends SavedObjectAttributes>(type: string, attributes: T, options?: CreateOptions) => Promise<SimpleSavedObject<T>> | Persists an object | +| [bulkCreate](./kibana-plugin-public.savedobjectsclient.bulkcreate.md) | | (objects?: SavedObjectsBulkCreateObject<SavedObjectAttributes>[], options?: SavedObjectsBulkCreateOptions) => Promise<SavedObjectsBatchResponse<SavedObjectAttributes>> | Creates multiple documents at once | +| [bulkGet](./kibana-plugin-public.savedobjectsclient.bulkget.md) | | (objects?: {
id: string;
type: string;
}[]) => Promise<SavedObjectsBatchResponse<SavedObjectAttributes>> | Returns an array of objects by id | +| [create](./kibana-plugin-public.savedobjectsclient.create.md) | | <T extends SavedObjectAttributes>(type: string, attributes: T, options?: SavedObjectsCreateOptions) => Promise<SimpleSavedObject<T>> | Persists an object | | [delete](./kibana-plugin-public.savedobjectsclient.delete.md) | | (type: string, id: string) => Promise<{}> | Deletes an object | -| [find](./kibana-plugin-public.savedobjectsclient.find.md) | | <T extends SavedObjectAttributes>(options?: SavedObjectsFindOptions) => Promise<FindResults<T>> | Search for objects | +| [find](./kibana-plugin-public.savedobjectsclient.find.md) | | <T extends SavedObjectAttributes>(options?: SavedObjectsFindOptions) => Promise<SavedObjectsFindResponse<T>> | Search for objects | | [get](./kibana-plugin-public.savedobjectsclient.get.md) | | <T extends SavedObjectAttributes>(type: string, id: string) => Promise<SimpleSavedObject<T>> | Fetches a single object | ## Methods diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.update.md b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.update.md index f1ec383628020c5..5f87f46d6206f79 100644 --- a/docs/development/core/public/kibana-plugin-public.savedobjectsclient.update.md +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsclient.update.md @@ -9,7 +9,7 @@ Updates an object Signature: ```typescript -update(type: string, id: string, attributes: T, { version, migrationVersion, references }?: UpdateOptions): Promise>; +update(type: string, id: string, attributes: T, { version, migrationVersion, references }?: SavedObjectsUpdateOptions): Promise>; ``` ## Parameters @@ -19,7 +19,7 @@ update(type: string, id: string, attributes: T, | type | string | | | id | string | | | attributes | T | | -| { version, migrationVersion, references } | UpdateOptions | | +| { version, migrationVersion, references } | SavedObjectsUpdateOptions | | Returns: diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.id.md b/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.id.md new file mode 100644 index 000000000000000..fc0532a10d6395b --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.id.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsCreateOptions](./kibana-plugin-public.savedobjectscreateoptions.md) > [id](./kibana-plugin-public.savedobjectscreateoptions.id.md) + +## SavedObjectsCreateOptions.id property + +(Not recommended) Specify an id instead of having the saved objects service generate one for you. + +Signature: + +```typescript +id?: string; +``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.md b/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.md new file mode 100644 index 000000000000000..99d186dd294a602 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsCreateOptions](./kibana-plugin-public.savedobjectscreateoptions.md) + +## SavedObjectsCreateOptions interface + + +Signature: + +```typescript +export interface SavedObjectsCreateOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [id](./kibana-plugin-public.savedobjectscreateoptions.id.md) | string | (Not recommended) Specify an id instead of having the saved objects service generate one for you. | +| [migrationVersion](./kibana-plugin-public.savedobjectscreateoptions.migrationversion.md) | SavedObjectsMigrationVersion | | +| [overwrite](./kibana-plugin-public.savedobjectscreateoptions.overwrite.md) | boolean | If a document with the given id already exists, overwrite it's contents (default=false). | +| [references](./kibana-plugin-public.savedobjectscreateoptions.references.md) | SavedObjectReference[] | | + diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.migrationversion.md b/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.migrationversion.md new file mode 100644 index 000000000000000..c56b4b615e41982 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.migrationversion.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsCreateOptions](./kibana-plugin-public.savedobjectscreateoptions.md) > [migrationVersion](./kibana-plugin-public.savedobjectscreateoptions.migrationversion.md) + +## SavedObjectsCreateOptions.migrationVersion property + +Signature: + +```typescript +migrationVersion?: SavedObjectsMigrationVersion; +``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.overwrite.md b/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.overwrite.md new file mode 100644 index 000000000000000..d83541fc9e874e2 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.overwrite.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsCreateOptions](./kibana-plugin-public.savedobjectscreateoptions.md) > [overwrite](./kibana-plugin-public.savedobjectscreateoptions.overwrite.md) + +## SavedObjectsCreateOptions.overwrite property + +If a document with the given `id` already exists, overwrite it's contents (default=false). + +Signature: + +```typescript +overwrite?: boolean; +``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.references.md b/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.references.md new file mode 100644 index 000000000000000..f6bcd47a3e8d582 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectscreateoptions.references.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsCreateOptions](./kibana-plugin-public.savedobjectscreateoptions.md) > [references](./kibana-plugin-public.savedobjectscreateoptions.references.md) + +## SavedObjectsCreateOptions.references property + +Signature: + +```typescript +references?: SavedObjectReference[]; +``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.md b/docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.md new file mode 100644 index 000000000000000..548c9ed3b05b996 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsFindResponse](./kibana-plugin-public.savedobjectsfindresponse.md) + +## SavedObjectsFindResponse interface + + +Signature: + +```typescript +export interface SavedObjectsFindResponse extends SavedObjectsBatchResponse +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [page](./kibana-plugin-public.savedobjectsfindresponse.page.md) | number | | +| [perPage](./kibana-plugin-public.savedobjectsfindresponse.perpage.md) | number | | +| [total](./kibana-plugin-public.savedobjectsfindresponse.total.md) | number | | + diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.page.md b/docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.page.md new file mode 100644 index 000000000000000..ce02d6c8c499fd3 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.page.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsFindResponse](./kibana-plugin-public.savedobjectsfindresponse.md) > [page](./kibana-plugin-public.savedobjectsfindresponse.page.md) + +## SavedObjectsFindResponse.page property + +Signature: + +```typescript +page: number; +``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.perpage.md b/docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.perpage.md new file mode 100644 index 000000000000000..5cc6d1ca4903abb --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.perpage.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsFindResponse](./kibana-plugin-public.savedobjectsfindresponse.md) > [perPage](./kibana-plugin-public.savedobjectsfindresponse.perpage.md) + +## SavedObjectsFindResponse.perPage property + +Signature: + +```typescript +perPage: number; +``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.total.md b/docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.total.md new file mode 100644 index 000000000000000..67afdfaf4a73400 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsfindresponse.total.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsFindResponse](./kibana-plugin-public.savedobjectsfindresponse.md) > [total](./kibana-plugin-public.savedobjectsfindresponse.total.md) + +## SavedObjectsFindResponse.total property + +Signature: + +```typescript +total: number; +``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.md b/docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.md new file mode 100644 index 000000000000000..d555e927eecc132 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsUpdateOptions](./kibana-plugin-public.savedobjectsupdateoptions.md) + +## SavedObjectsUpdateOptions interface + + +Signature: + +```typescript +export interface SavedObjectsUpdateOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [migrationVersion](./kibana-plugin-public.savedobjectsupdateoptions.migrationversion.md) | SavedObjectsMigrationVersion | | +| [references](./kibana-plugin-public.savedobjectsupdateoptions.references.md) | SavedObjectReference[] | | +| [version](./kibana-plugin-public.savedobjectsupdateoptions.version.md) | string | | + diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.migrationversion.md b/docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.migrationversion.md new file mode 100644 index 000000000000000..dee541c9ca758c0 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.migrationversion.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsUpdateOptions](./kibana-plugin-public.savedobjectsupdateoptions.md) > [migrationVersion](./kibana-plugin-public.savedobjectsupdateoptions.migrationversion.md) + +## SavedObjectsUpdateOptions.migrationVersion property + +Signature: + +```typescript +migrationVersion?: SavedObjectsMigrationVersion; +``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.references.md b/docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.references.md new file mode 100644 index 000000000000000..eda84ec8e0bfa2a --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.references.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsUpdateOptions](./kibana-plugin-public.savedobjectsupdateoptions.md) > [references](./kibana-plugin-public.savedobjectsupdateoptions.references.md) + +## SavedObjectsUpdateOptions.references property + +Signature: + +```typescript +references?: SavedObjectReference[]; +``` diff --git a/docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.version.md b/docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.version.md new file mode 100644 index 000000000000000..9aacfa9124016c4 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.savedobjectsupdateoptions.version.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [SavedObjectsUpdateOptions](./kibana-plugin-public.savedobjectsupdateoptions.md) > [version](./kibana-plugin-public.savedobjectsupdateoptions.version.md) + +## SavedObjectsUpdateOptions.version property + +Signature: + +```typescript +version?: string; +``` diff --git a/docs/development/core/server/kibana-plugin-server.md b/docs/development/core/server/kibana-plugin-server.md index 3c0699485d98fa2..940f5ea1a6a4d90 100644 --- a/docs/development/core/server/kibana-plugin-server.md +++ b/docs/development/core/server/kibana-plugin-server.md @@ -57,7 +57,7 @@ The plugin integrates with the core system via lifecycle events: `setup` | [SavedObjectsCreateOptions](./kibana-plugin-server.savedobjectscreateoptions.md) | | | [SavedObjectsFindOptions](./kibana-plugin-server.savedobjectsfindoptions.md) | | | [SavedObjectsFindResponse](./kibana-plugin-server.savedobjectsfindresponse.md) | | -| [SavedObjectsMigrationVersion](./kibana-plugin-server.savedobjectsmigrationversion.md) | A dictionary of saved object type -> version used to determine what migrations need to be applied to a saved object. | +| [SavedObjectsMigrationVersion](./kibana-plugin-server.savedobjectsmigrationversion.md) | Information about the migrations that have been applied to this SavedObject. When Kibana starts up, KibanaMigrator detects outdated documents and migrates them based on this value. For each migration that has been applied, the plugin's name is used as a key and the latest migration version as the value. | | [SavedObjectsService](./kibana-plugin-server.savedobjectsservice.md) | | | [SavedObjectsUpdateOptions](./kibana-plugin-server.savedobjectsupdateoptions.md) | | | [SavedObjectsUpdateResponse](./kibana-plugin-server.savedobjectsupdateresponse.md) | | diff --git a/docs/development/core/server/kibana-plugin-server.savedobjectsmigrationversion.md b/docs/development/core/server/kibana-plugin-server.savedobjectsmigrationversion.md index 434e46041cf7da4..a7f652e4348bf65 100644 --- a/docs/development/core/server/kibana-plugin-server.savedobjectsmigrationversion.md +++ b/docs/development/core/server/kibana-plugin-server.savedobjectsmigrationversion.md @@ -4,10 +4,22 @@ ## SavedObjectsMigrationVersion interface -A dictionary of saved object type -> version used to determine what migrations need to be applied to a saved object. +Information about the migrations that have been applied to this SavedObject. When Kibana starts up, KibanaMigrator detects outdated documents and migrates them based on this value. For each migration that has been applied, the plugin's name is used as a key and the latest migration version as the value. Signature: ```typescript export interface SavedObjectsMigrationVersion ``` + +## Example + + +``` +migrationVersion: { + dashboard: '7.1.1', + space: '6.6.6', +} + +``` + diff --git a/src/core/public/index.ts b/src/core/public/index.ts index 26bdf4872eca2b9..977c08e66db6564 100644 --- a/src/core/public/index.ts +++ b/src/core/public/index.ts @@ -66,11 +66,29 @@ import { Plugin, PluginInitializer, PluginInitializerContext } from './plugins'; import { UiSettingsClient, UiSettingsState, UiSettingsClientContract } from './ui_settings'; import { ApplicationSetup, Capabilities, ApplicationStart } from './application'; import { DocLinksStart } from './doc_links'; -import { SavedObjectsClient, SimpleSavedObject, SavedObjectsClientContract } from './saved_objects'; -import { SavedObjectsStart } from './saved_objects/saved_objects_service'; +import { + SavedObjectsClient, + SimpleSavedObject, + SavedObjectsClientContract, + SavedObjectsStart, +} from './saved_objects'; export { CoreContext, CoreSystem } from './core_system'; export { RecursiveReadonly } from '../utils'; +export { + SavedObjectsBatchResponse, + SavedObjectsBulkCreateObject, + SavedObjectsBulkCreateOptions, + SavedObjectsCreateOptions, + SavedObjectsFindResponse, + SavedObjectsUpdateOptions, + SavedObject, + SavedObjectAttributes, + SavedObjectReference, + SavedObjectsApi, + SavedObjectsFindOptions, + SavedObjectsMigrationVersion, +} from './saved_objects'; /** * Core services exposed to the `Plugin` setup lifecycle diff --git a/src/core/public/public.api.md b/src/core/public/public.api.md index 65d860235a88510..4dbe09c843fcae8 100644 --- a/src/core/public/public.api.md +++ b/src/core/public/public.api.md @@ -11,6 +11,7 @@ import * as Rx from 'rxjs'; import { SavedObject } from 'src/core/server'; import { SavedObjectAttributes } from 'src/core/server'; import { SavedObjectReference } from 'src/core/server'; +import { SavedObjectsClientContract as SavedObjectsApi } from 'src/core/server'; import { SavedObjectsFindOptions } from 'src/core/server'; import { SavedObjectsMigrationVersion } from 'src/core/server'; import { EuiGlobalToastListToast as Toast } from '@elastic/eui'; @@ -511,35 +512,91 @@ export type RecursiveReadonly = T extends (...args: any[]) => any ? T : T ext [K in keyof T]: RecursiveReadonly; }> : T; +export { SavedObject } + +export { SavedObjectAttributes } + +export { SavedObjectReference } + +export { SavedObjectsApi } + +// @public (undocumented) +export interface SavedObjectsBatchResponse { + // (undocumented) + savedObjects: Array>; +} + +// @public (undocumented) +export interface SavedObjectsBulkCreateObject extends SavedObjectsCreateOptions { + // (undocumented) + attributes: T; + // (undocumented) + type: string; +} + +// @public (undocumented) +export interface SavedObjectsBulkCreateOptions { + overwrite?: boolean; +} + // @public export class SavedObjectsClient { constructor(http: HttpSetup); - // Warning: (ae-forgotten-export) The symbol "BulkCreateOptions" needs to be exported by the entry point index.d.ts - // Warning: (ae-forgotten-export) The symbol "BatchResponse" needs to be exported by the entry point index.d.ts - bulkCreate: (objects?: BulkCreateOptions[], options?: HttpFetchQuery) => Promise>; + bulkCreate: (objects?: SavedObjectsBulkCreateObject[], options?: SavedObjectsBulkCreateOptions) => Promise>; bulkGet: (objects?: { id: string; type: string; - }[]) => Promise>; - // Warning: (ae-forgotten-export) The symbol "CreateOptions" needs to be exported by the entry point index.d.ts - create: (type: string, attributes: T, options?: CreateOptions) => Promise>; + }[]) => Promise>; + create: (type: string, attributes: T, options?: SavedObjectsCreateOptions) => Promise>; delete: (type: string, id: string) => Promise<{}>; - // Warning: (ae-forgotten-export) The symbol "FindResults" needs to be exported by the entry point index.d.ts - find: (options?: SavedObjectsFindOptions) => Promise>; + find: (options?: SavedObjectsFindOptions) => Promise>; get: (type: string, id: string) => Promise>; - // Warning: (ae-forgotten-export) The symbol "UpdateOptions" needs to be exported by the entry point index.d.ts - update(type: string, id: string, attributes: T, { version, migrationVersion, references }?: UpdateOptions): Promise>; + update(type: string, id: string, attributes: T, { version, migrationVersion, references }?: SavedObjectsUpdateOptions): Promise>; } // @public export type SavedObjectsClientContract = PublicMethodsOf; +// @public (undocumented) +export interface SavedObjectsCreateOptions { + id?: string; + // (undocumented) + migrationVersion?: SavedObjectsMigrationVersion; + overwrite?: boolean; + // (undocumented) + references?: SavedObjectReference[]; +} + +export { SavedObjectsFindOptions } + +// @public (undocumented) +export interface SavedObjectsFindResponse extends SavedObjectsBatchResponse { + // (undocumented) + page: number; + // (undocumented) + perPage: number; + // (undocumented) + total: number; +} + +export { SavedObjectsMigrationVersion } + // @public (undocumented) export interface SavedObjectsStart { // (undocumented) client: SavedObjectsClientContract; } +// @public (undocumented) +export interface SavedObjectsUpdateOptions { + // (undocumented) + migrationVersion?: SavedObjectsMigrationVersion; + // (undocumented) + references?: SavedObjectReference[]; + // (undocumented) + version?: string; +} + // @public export class SimpleSavedObject { constructor(client: SavedObjectsClient, { id, type, version, attributes, error, references, migrationVersion }: SavedObject); diff --git a/src/core/public/saved_objects/index.ts b/src/core/public/saved_objects/index.ts index 6e0893c469efacb..0960ea1640a30b3 100644 --- a/src/core/public/saved_objects/index.ts +++ b/src/core/public/saved_objects/index.ts @@ -17,6 +17,21 @@ * under the License. */ -export { SavedObjectsClient, SavedObjectsClientContract } from './saved_objects_client'; +export { + SavedObject, + SavedObjectAttributes, + SavedObjectReference, + SavedObjectsBatchResponse, + SavedObjectsBulkCreateObject, + SavedObjectsBulkCreateOptions, + SavedObjectsClient, + SavedObjectsClientContract, + SavedObjectsApi, + SavedObjectsCreateOptions, + SavedObjectsFindOptions, + SavedObjectsFindResponse, + SavedObjectsMigrationVersion, + SavedObjectsUpdateOptions, +} from './saved_objects_client'; export { SimpleSavedObject } from './simple_saved_object'; export { SavedObjectsStart } from './saved_objects_service'; diff --git a/src/core/public/saved_objects/saved_objects_client.ts b/src/core/public/saved_objects/saved_objects_client.ts index 6fbf66e8694c15e..d2e1000966a5e54 100644 --- a/src/core/public/saved_objects/saved_objects_client.ts +++ b/src/core/public/saved_objects/saved_objects_client.ts @@ -28,6 +28,7 @@ import { SavedObjectsFindOptions, SavedObjectsMigrationVersion, } from 'src/core/server'; +// TODO: Migrate to an error modal powered by the NP? import { isAutoCreateIndexError, showAutoCreateIndexErrorPage, @@ -35,6 +36,15 @@ import { import { SimpleSavedObject } from './simple_saved_object'; import { HttpFetchQuery, HttpSetup } from '../http'; +export { + SavedObject, + SavedObjectAttributes, + SavedObjectReference, + SavedObjectsClientContract as SavedObjectsApi, + SavedObjectsFindOptions, + SavedObjectsMigrationVersion, +} from 'src/core/server'; + interface RequestParams { method: 'POST' | 'GET' | 'PUT' | 'DELETE'; path: string; @@ -42,31 +52,54 @@ interface RequestParams { body?: object; } -interface CreateOptions { +/** @public */ +export interface SavedObjectsCreateOptions { + /** + * (Not recommended) Specify an id instead of having the saved objects service generate one for you. + */ id?: string; + /** If a document with the given `id` already exists, overwrite it's contents (default=false). */ overwrite?: boolean; migrationVersion?: SavedObjectsMigrationVersion; references?: SavedObjectReference[]; } -interface BulkCreateOptions - extends CreateOptions { +/** + * @param type - Create a SavedObject of the given type + * @param attributes - Create a SavedObject with the given attributes + * + * @public + */ +export interface SavedObjectsBulkCreateObject< + T extends SavedObjectAttributes = SavedObjectAttributes +> extends SavedObjectsCreateOptions { type: string; attributes: T; } -interface UpdateOptions { +/** @public */ +export interface SavedObjectsBulkCreateOptions { + /** If a document with the given `id` already exists, overwrite it's contents (default=false). */ + overwrite?: boolean; +} + +/** @public */ +export interface SavedObjectsUpdateOptions { version?: string; migrationVersion?: SavedObjectsMigrationVersion; references?: SavedObjectReference[]; } -interface BatchResponse { +/** @public */ +export interface SavedObjectsBatchResponse< + T extends SavedObjectAttributes = SavedObjectAttributes +> { savedObjects: Array>; } -interface FindResults - extends BatchResponse { +/** @public */ +export interface SavedObjectsFindResponse + extends SavedObjectsBatchResponse { total: number; perPage: number; page: number; @@ -102,8 +135,9 @@ export type SavedObjectsClientContract = PublicMethodsOf; /** * Saved Objects is Kibana's data persisentence mechanism allowing plugins to - * use Elasticsearch for storing plugin state. The SavedObjectsClient is a thin - * "repository" for client-side plugins to interact with Saved Objects. + * use Elasticsearch for storing plugin state. The client-side + * SavedObjectsClient is a thin convenience library around the SavedObjects + * HTTP API for interacting with Saved Objects. * * @public */ @@ -151,18 +185,15 @@ export class SavedObjectsClient { /** * Persists an object * - * @param {string} type - * @param {object} [attributes={}] - * @param {object} [options={}] - * @property {string} [options.id] - force id on creation, not recommended - * @property {boolean} [options.overwrite=false] - * @property {object} [options.migrationVersion] + * @param type + * @param attributes + * @param options * @returns */ public create = ( type: string, attributes: T, - options: CreateOptions = {} + options: SavedObjectsCreateOptions = {} ): Promise> => { if (!type || !attributes) { return Promise.reject(new Error('requires type and attributes')); @@ -203,10 +234,12 @@ export class SavedObjectsClient { * @property {boolean} [options.overwrite=false] * @returns The result of the create operation containing created saved objects. */ - public bulkCreate = (objects: BulkCreateOptions[] = [], options: HttpFetchQuery = {}) => { - // TODO better options type + public bulkCreate = ( + objects: SavedObjectsBulkCreateObject[] = [], + options: SavedObjectsBulkCreateOptions = { overwrite: false } + ) => { const path = this.getPath(['_bulk_create']); - const query = pick(options, ['overwrite']) as Pick; + const query = { overwrite: options.overwrite }; const request: ReturnType = this.request({ method: 'POST', @@ -216,7 +249,7 @@ export class SavedObjectsClient { }); return request.then(resp => { resp.saved_objects = resp.saved_objects.map(d => this.createSavedObject(d)); - return renameKeys({ saved_objects: 'savedObjects' }, resp) as BatchResponse; + return renameKeys({ saved_objects: 'savedObjects' }, resp) as SavedObjectsBatchResponse; }); }; @@ -251,7 +284,7 @@ export class SavedObjectsClient { */ public find = ( options: SavedObjectsFindOptions = {} - ): Promise> => { + ): Promise> => { const path = this.getPath(['_find']); const query = renameKeys( { @@ -281,7 +314,7 @@ export class SavedObjectsClient { page: 'page', }, resp - ) as FindResults; + ) as SavedObjectsFindResponse; }); }; @@ -329,7 +362,7 @@ export class SavedObjectsClient { }); return request.then(resp => { resp.saved_objects = resp.saved_objects.map(d => this.createSavedObject(d)); - return renameKeys({ saved_objects: 'savedObjects' }, resp) as BatchResponse; + return renameKeys({ saved_objects: 'savedObjects' }, resp) as SavedObjectsBatchResponse; }); }; @@ -348,7 +381,7 @@ export class SavedObjectsClient { type: string, id: string, attributes: T, - { version, migrationVersion, references }: UpdateOptions = {} + { version, migrationVersion, references }: SavedObjectsUpdateOptions = {} ): Promise> { if (!type || !id || !attributes) { return Promise.reject(new Error('requires type, id and attributes')); diff --git a/src/core/server/saved_objects/service/saved_objects_client.ts b/src/core/server/saved_objects/service/saved_objects_client.ts index adc25a6d045e9d0..e9d6aa287f4bed6 100644 --- a/src/core/server/saved_objects/service/saved_objects_client.ts +++ b/src/core/server/saved_objects/service/saved_objects_client.ts @@ -133,8 +133,19 @@ export interface SavedObjectsUpdateResponse version used to determine - * what migrations need to be applied to a saved object. + * Information about the migrations that have been applied to this SavedObject. + * When Kibana starts up, KibanaMigrator detects outdated documents and + * migrates them based on this value. For each migration that has been applied, + * the plugin's name is used as a key and the latest migration version as the + * value. + * + * @example + * ``` + * migrationVersion: { + * dashboard: '7.1.1', + * space: '6.6.6', + * } + * ``` * * @public */