add TS doc

elastic · Feb 6, 2023 · 70bdfb6 · 70bdfb6
1 parent cd3ae20
commit 70bdfb6
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 6 deletions.
diff --git a/packages/core/saved-objects/core-saved-objects-server/index.ts b/packages/core/saved-objects/core-saved-objects-server/index.ts
@@ -99,6 +99,7 @@ export type {
   SavedObjectModelMigrationContext,
   SavedObjectModelMigrationFn,
   SavedObjectModelBidirectionalMigration,
+  SavedObjectModelMigrationResult,
 } from './src/model_version';
 
 export type {

diff --git a/packages/core/saved-objects/core-saved-objects-server/src/model_version/index.ts b/packages/core/saved-objects/core-saved-objects-server/src/model_version/index.ts
@@ -11,6 +11,7 @@ export type {
   SavedObjectModelMigrationContext,
   SavedObjectModelMigrationFn,
   SavedObjectModelBidirectionalMigration,
+  SavedObjectModelMigrationResult,
 } from './migration';
 
 export type {

diff --git a/packages/core/saved-objects/core-saved-objects-server/src/model_version/migration.ts b/packages/core/saved-objects/core-saved-objects-server/src/model_version/migration.ts
@@ -9,14 +9,18 @@
 import type { SavedObjectSanitizedDoc } from '../serialization';
 import type { SavedObjectsMigrationLogger } from '../migration';
 
-// alias to more easily adapt later
+/**
+ * Document type used during model migration.
+ *
+ * @public
+ */
 export type SavedObjectModelMigrationDoc<T = unknown> = SavedObjectSanitizedDoc<T>;
 
-export type SavedObjectModelMigrationFn<InputAttributes = unknown, OutputAttributes = unknown> = (
-  doc: SavedObjectModelMigrationDoc<InputAttributes>,
-  context: SavedObjectModelMigrationContext
-) => SavedObjectModelMigrationDoc<OutputAttributes>;
-
+/**
+ * Context passed down to {@link SavedObjectModelMigrationFn | migration functions}.
+ *
+ * @public
+ */
 export interface SavedObjectModelMigrationContext {
   /**
    * logger instance to be used by the migration handler
@@ -28,6 +32,37 @@ export interface SavedObjectModelMigrationContext {
   readonly modelVersion: number;
 }
 
+/**
+ * Return type for the {@link SavedObjectModelMigrationFn | migration functions}
+ *
+ * @public
+ */
+export interface SavedObjectModelMigrationResult<DocAttrs = unknown> {
+  document: SavedObjectModelMigrationDoc<DocAttrs>;
+}
+
+/**
+ * Migration function for the model version API.
+ *
+ * Similar to the old migration system, model version migrations take the document to migrate
+ * and a context object as input and must return the transformed document in its return value.
+ *
+ * @public
+ */
+export type SavedObjectModelMigrationFn<InputAttributes = unknown, OutputAttributes = unknown> = (
+  document: SavedObjectModelMigrationDoc<InputAttributes>,
+  context: SavedObjectModelMigrationContext
+) => SavedObjectModelMigrationResult<OutputAttributes>;
+
+/**
+ * A bidirectional migration.
+ *
+ * Bidirectional migrations define migration functions that can be used to
+ * migrate from the lower version to the higher one (`up`), and the other way around,
+ * from the higher version to the lower one (`down`)
+ *
+ * @public
+ */
 export interface SavedObjectModelBidirectionalMigration<
   PreviousAttributes = unknown,
   NewAttributes = unknown