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,
+      setEncryptionExtension: deps.savedObjects.setEncryptionExtension,
+      setSecurityExtension: deps.savedObjects.setSecurityExtension,
+      setSpacesExtension: deps.savedObjects.setSpacesExtension,
       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/resolve.ts

@@ -7,7 +7,7 @@
  */
 
 import type { SavedObjectsResolveResponse } from '@kbn/core-saved-objects-api-server';
-import { SimpleSavedObject } from '../simple_saved_object';
+import type { SimpleSavedObject } from '../simple_saved_object';
 
 /**
  * This interface is a very simple wrapper for SavedObjects resolved from the server

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[]