Saved objects extensions refactor merge

packages/core/plugins/core-plugins-server-internal/src/plugin_context.ts

@@ -234,7 +234,9 @@ export function createPluginSetupContext<TPlugin, TPluginDependencies>(
  },
  savedObjects: {
  setClientFactoryProvider: deps.savedObjects.setClientFactoryProvider,
- addClientWrapper: deps.savedObjects.addClientWrapper,
+ addEncryptionExtension: deps.savedObjects.addEncryptionExtension,
+ addSecurityExtension: deps.savedObjects.addSecurityExtension,
+ addSpacesExtension: deps.savedObjects.addSpacesExtension,
  registerType: deps.savedObjects.registerType,
  getKibanaIndex: deps.savedObjects.getKibanaIndex,
  },

packages/core/saved-objects/core-saved-objects-api-browser/src/apis/base.ts

@@ -8,7 +8,12 @@
 
 import { SimpleSavedObject } from '../simple_saved_object';
 
-/** @public */
+/**
+ * Batch response for simple saved objects
+ *
+ * @public
+ */
 export interface SavedObjectsBatchResponse<T = unknown> {
+ /** Array of simple saved objects */
  savedObjects: Array<SimpleSavedObject<T>>;
 }

packages/core/saved-objects/core-saved-objects-api-browser/src/apis/bulk_create.ts

@@ -9,18 +9,23 @@
 import type { SavedObjectsCreateOptions } from './create';
 
 /**
- * @param type - Create a SavedObject of the given type
- * @param attributes - Create a SavedObject with the given attributes
+ * Per-object parameters for bulk create operation
  *
  * @public
  */
 export interface SavedObjectsBulkCreateObject<T = unknown> extends SavedObjectsCreateOptions {
+ /** Create a SavedObject of this type. */
  type: string;
+ /** Attributes for the saved object to be created. */
  attributes: T;
 }
 
-/** @public */
+/**
+ * Options for bulk create operation
+ *
+ * @public
+ * */
 export interface SavedObjectsBulkCreateOptions {
- /** If a document with the given `id` already exists, overwrite it's contents (default=false). */
+ /** If a document with the given `id` already exists, overwrite its contents (default=false). */
  overwrite?: boolean;
 }

packages/core/saved-objects/core-saved-objects-api-browser/src/apis/bulk_delete.ts

@@ -8,20 +8,38 @@
 
 import { SavedObjectError } from '@kbn/core-saved-objects-common';
 
-/** @public */
+/**
+ * Options for bulk delete operation
+ *
+ * @public
+ */
 export interface SavedObjectsBulkDeleteOptions {
+ /** Force deletion of any objects that exist in multiple namespaces (default=false) */
  force?: boolean;
 }
 
-/** @public */
+/**
+ * Single item within the statuses array of the bulk delete response
+ *
+ * @public
+ */
 export interface SavedObjectsBulkDeleteResponseItem {
+ /** saved object id */
  id: string;
+ /** saved object type */
  type: string;
+ /** true if the delete operation succeeded*/
  success: boolean;
+ /** error from delete operation (undefined if no error) */
  error?: SavedObjectError;
 }
 
-/** @public */
+/**
+ * Return type of the Saved Objects `bulkDelete()` method.
+ *
+ * @public
+ */
 export interface SavedObjectsBulkDeleteResponse {
+ /** array of statuses per object */
  statuses: SavedObjectsBulkDeleteResponseItem[];
 }

packages/core/saved-objects/core-saved-objects-api-browser/src/apis/bulk_resolve.ts

@@ -8,7 +8,12 @@
 
 import type { ResolvedSimpleSavedObject } from './resolve';
 
-/** @public */
+/**
+ * Return type of the Saved Objects `bulkResolve()` method.
+ *
+ * @public
+ */
 export interface SavedObjectsBulkResolveResponse<T = unknown> {
+ /** Array of {@link ResolvedSimpleSavedObject} that were resolved */
  resolved_objects: Array<ResolvedSimpleSavedObject<T>>;
 }

packages/core/saved-objects/core-saved-objects-api-browser/src/apis/bulk_update.ts

@@ -8,16 +8,33 @@
 
 import type { SavedObjectReference } from '@kbn/core-saved-objects-common';
 
-/** @public */
+/**
+ * Per-object parameters for bulk update operation
+ *
+ * @public
+ */
 export interface SavedObjectsBulkUpdateObject<T = unknown> {
+ /** Type of the saved object to update */
  type: string;
+ /** ID of the saved object to update */
  id: string;
+ /** The attributes to update */
  attributes: T;
+ /** The version string for the saved object */
  version?: string;
+ /** Array of references to other saved objects */
  references?: SavedObjectReference[];
 }
 
-/** @public */
+/**
+ * Options for bulk update operation
+ *
+ * @public
+ * */
 export interface SavedObjectsBulkUpdateOptions {
+ /**
+ * The namespace from which to apply the bulk update operation
+ * Not permitted if spaces extension is enabled
+ */
  namespace?: string;
 }

packages/core/saved-objects/core-saved-objects-api-browser/src/apis/create.ts

@@ -11,7 +11,11 @@ import type {
  SavedObjectsMigrationVersion,
 } from '@kbn/core-saved-objects-common';
 
-/** @public */
+/**
+ * Options for creating a saved object.
+ *
+ * @public
+ */
 export interface SavedObjectsCreateOptions {
  /**
  * (Not recommended) Specify an id instead of having the saved objects service generate one for you.
@@ -23,5 +27,6 @@ export interface SavedObjectsCreateOptions {
  migrationVersion?: SavedObjectsMigrationVersion;
  /** A semver value that is used when upgrading objects between Kibana versions. */
  coreMigrationVersion?: string;
+ /** Array of referenced saved objects. */
  references?: SavedObjectReference[];
 }

packages/core/saved-objects/core-saved-objects-api-browser/src/apis/delete.ts

@@ -6,8 +6,12 @@
  * Side Public License, v 1.
  */
 
-/** @public */
+/**
+ * Options for deleting a saved object.
+ *
+ * @public
+ */
 export interface SavedObjectsDeleteOptions {
- /** Force deletion of an object that exists in multiple namespaces */
+ /** Force deletion of an object that exists in multiple namespaces (default=false) */
  force?: boolean;
 }

packages/core/saved-objects/core-saved-objects-api-browser/src/apis/find.ts

@@ -9,7 +9,11 @@
 import type { SavedObjectsFindOptions as SavedObjectFindOptionsServer } from '@kbn/core-saved-objects-api-server';
 import type { SavedObjectsBatchResponse } from './base';
 
+export type { SavedObjectsFindOptionsReference } from '@kbn/core-saved-objects-api-server';
+
 /**
+ * Browser options for finding saved objects
+ *
  * @public
  */
 export type SavedObjectsFindOptions = Omit<
@@ -24,16 +28,12 @@ export type SavedObjectsFindOptions = Omit<
  */
 export interface SavedObjectsFindResponse<T = unknown, A = unknown>
  extends SavedObjectsBatchResponse<T> {
+ /** aggregations from the search query */
  aggregations?: A;
+ /** total number of results */
  total: number;
+ /** number of results per page */
  perPage: number;
+ /** current page in results*/
  page: number;
 }
-
-/**
- * @public
- */
-export interface SavedObjectsFindOptionsReference {
- type: string;
- id: string;
-}

packages/core/saved-objects/core-saved-objects-api-browser/src/apis/update.ts

@@ -8,9 +8,16 @@
 
 import type { SavedObjectReference } from '@kbn/core-saved-objects-common';
 
-/** @public */
+/**
+ * Options for updating a saved object
+ *
+ * @public
+ */
 export interface SavedObjectsUpdateOptions<Attributes = unknown> {
+ /** version of the saved object */
  version?: string;
+ /** Alternative attributes for the saved object if upserting */
  upsert?: Attributes;
+ /** Array of references to other saved objects */
  references?: SavedObjectReference[];
 }

packages/core/saved-objects/core-saved-objects-api-browser/src/saved_objects_client.ts

@@ -33,7 +33,12 @@ import type { SimpleSavedObject } from './simple_saved_object';
  */
 export interface SavedObjectsClientContract {
  /**
- * Persists an object
+ * Creates an object
+ *
+ * @param {string} type - the type of object to create
+ * @param {string} attributes - the attributes of the object
+ * @param {string} options {@link SavedObjectsCreateOptions}
+ * @returns The result of the create operation - the created saved object
  */
  create<T = unknown>(
  type: string,
@@ -42,7 +47,10 @@ export interface SavedObjectsClientContract {
  ): Promise<SimpleSavedObject<T>>;
 
  /**
- * Creates multiple documents at once
+ * Creates multiple objects at once
+ *
+ * @param {string} objects - an array of objects containing type, attributes
+ * @param {string} options {@link SavedObjectsBulkCreateOptions}
  * @returns The result of the create operation containing created saved objects.
  */
  bulkCreate(
@@ -52,6 +60,11 @@ export interface SavedObjectsClientContract {
 
  /**
  * Deletes an object
+ *
+ * @param {string} type - the type the of object to delete
+ * @param {string} id - the id of the object to delete
+ * @param {string} options {@link SavedObjectsDeleteOptions}
+ * @param {string} options.force - required to delete objects shared to multiple spaces
  */
  delete(type: string, id: string, options?: SavedObjectsDeleteOptions): Promise<{}>;
 
@@ -69,8 +82,8 @@ export interface SavedObjectsClientContract {
  /**
  * Search for objects
  *
- * @param {object} [options={}]
- * @property {string} options.type
+ * @param {object} [options={}] {@link SavedObjectsFindOptions}
+ * @property {string} options.type - the type or array of types to find
  * @property {string} options.search
  * @property {string} options.searchFields - see Elasticsearch Simple Query String
  * Query field argument for more information
@@ -87,8 +100,8 @@ export interface SavedObjectsClientContract {
  /**
  * Fetches a single object
  *
- * @param {string} type
- * @param {string} id
+ * @param {string} type - the type of the object to get
+ * @param {string} id - the ID of the object to get
  * @returns The saved object for the given type and id.
  */
  get<T = unknown>(type: string, id: string): Promise<SimpleSavedObject<T>>;
@@ -110,8 +123,8 @@ export interface SavedObjectsClientContract {
  /**
  * Resolves a single object
  *
- * @param {string} type
- * @param {string} id
+ * @param {string} type - the type of the object to resolve
+ * @param {string} id - the ID of the object to resolve
  * @returns The resolve result for the saved object for the given type and id.
  *
  * @note Saved objects that Kibana fails to find are replaced with an error object and an "exactMatch" outcome. The rationale behind the
@@ -144,13 +157,13 @@ export interface SavedObjectsClientContract {
  /**
  * Updates an object
  *
- * @param {string} type
- * @param {string} id
- * @param {object} attributes
- * @param {object} options
+ * @param {string} type - the type of the object to update
+ * @param {string} id - the ID of the object to update
+ * @param {object} attributes - the attributes to update
+ * @param {object} options {@link SavedObjectsUpdateOptions}
  * @prop {integer} options.version - ensures version matches that of persisted object
  * @prop {object} options.migrationVersion - The optional migrationVersion of this document
- * @returns
+ * @returns the udpated simple saved object
  */
  update<T = unknown>(
  type: string,
@@ -162,8 +175,8 @@ export interface SavedObjectsClientContract {
  /**
  * Update multiple documents at once
  *
- * @param {array} objects - [{ type, id, attributes, options: { version, references } }]
- * @returns The result of the update operation containing both failed and updated saved objects.
+ * @param {array} objects - an array of objects containing type, id, attributes, and references
+ * @returns the result of the bulk update operation containing both failed and updated saved objects.
  */
  bulkUpdate<T = unknown>(
  objects: SavedObjectsBulkUpdateObject[]

packages/core/saved-objects/core-saved-objects-api-browser/src/simple_saved_object.ts

@@ -18,29 +18,64 @@ import type { SavedObject as SavedObjectType } from '@kbn/core-saved-objects-com
  * @public
  */
 export interface SimpleSavedObject<T = unknown> {
+ /** attributes of the object, templated */
  attributes: T;
+ /** version of the saved object */
  _version?: SavedObjectType<T>['version'];
+ /** ID of the saved object, unique per type */
  id: SavedObjectType<T>['id'];
+ /** Type of the saved object */
  type: SavedObjectType<T>['type'];
+ /** Migration version of the saved object */
  migrationVersion: SavedObjectType<T>['migrationVersion'];
+ /** Core migration version of the saved object */
  coreMigrationVersion: SavedObjectType<T>['coreMigrationVersion'];
+ /** Error associated with this object, undefined if no error */
  error: SavedObjectType<T>['error'];
+ /** References to other saved objects */
  references: SavedObjectType<T>['references'];
+ /** The date this object was last updated */
  updatedAt: SavedObjectType<T>['updated_at'];
+ /** The date this object was created */
  createdAt: SavedObjectType<T>['created_at'];
  /**
  * Space(s) that this saved object exists in. This attribute is not used for "global" saved object types which are registered with
  * `namespaceType: 'agnostic'`.
  */
  namespaces: SavedObjectType<T>['namespaces'];
 
+ /**
+ * Gets an attribute of this object
+ *
+ * @param {string} key - the name of the attribute
+ * @returns The value of the attribute.
+ */
  get(key: string): any;
 
+ /**
+ * Sets an attribute of this object
+ *
+ * @param {string} key - the name of the attribute
+ * @param {string} value - the value for the attribute
+ * @returns The updated attributes of this object.
+ */
  set(key: string, value: any): T;
 
+ /**
+ * Checks if this object has an attribute
+ *
+ * @param {string} key - the name of the attribute
+ * @returns true if the attribute exists.
+ */
  has(key: string): boolean;
 
+ /**
+ * Saves this object
+ */
  save(): Promise<SimpleSavedObject<T>>;
 
+ /**
+ * Deletes this object
+ */
  delete(): Promise<{}>;
 }