Move migration-tools to separate example package (#22267)

PACKAGES.md

@@ -189,7 +189,7 @@ The dependencies between layers are enforced by the layer-check command._
 
 | Packages | Layer Dependencies |
 | --- | --- |
-| - [@fluid-example/attributable-map](/examples/apps/attributable-map) (private)</br>- [@fluid-example/collaborative-textarea](/examples/apps/collaborative-textarea) (private)</br>- [@fluid-example/contact-collection](/examples/apps/contact-collection) (private)</br>- [@fluid-example/data-object-grid](/examples/apps/data-object-grid) (private)</br>- [@fluid-example/presence-tracker](/examples/apps/presence-tracker) (private)</br>- [@fluid-example/task-selection](/examples/apps/task-selection) (private)</br>- [@fluid-example/tree-comparison](/examples/apps/tree-comparison) (private)</br>- [@fluid-example/bubblebench-baseline](/examples/benchmarks/bubblebench/baseline) (private)</br>- [@fluid-example/bubblebench-common](/examples/benchmarks/bubblebench/common) (private)</br>- [@fluid-example/bubblebench-experimental-tree](/examples/benchmarks/bubblebench/experimental-tree) (private)</br>- [@fluid-example/bubblebench-ot](/examples/benchmarks/bubblebench/ot) (private)</br>- [@fluid-example/bubblebench-shared-tree](/examples/benchmarks/bubblebench/shared-tree) (private)</br>- [@fluid-example/odspsnapshotfetch-perftestapp](/examples/benchmarks/odspsnapshotfetch-perftestapp) (private)</br>- [@fluid-internal/tablebench](/examples/benchmarks/tablebench) (private)</br>- [@fluid-example/app-insights-logger](/examples/client-logger/app-insights-logger) (private)</br>- [@fluid-example/canvas](/examples/data-objects/canvas) (private)</br>- [@fluid-example/clicker](/examples/data-objects/clicker) (private)</br>- [@fluid-example/codemirror](/examples/data-objects/codemirror) (private)</br>- [@fluid-example/diceroller](/examples/data-objects/diceroller) (private)</br>- [@fluid-example/inventory-app](/examples/data-objects/inventory-app) (private)</br>- [@fluid-example/monaco](/examples/data-objects/monaco) (private)</br>- [@fluid-example/multiview-constellation-model](/examples/data-objects/multiview/constellation-model) (private)</br>- [@fluid-example/multiview-constellation-view](/examples/data-objects/multiview/constellation-view) (private)</br>- [@fluid-example/multiview-container](/examples/data-objects/multiview/container) (private)</br>- [@fluid-example/multiview-coordinate-model](/examples/data-objects/multiview/coordinate-model) (private)</br>- [@fluid-example/multiview-coordinate-interface](/examples/data-objects/multiview/interface) (private)</br>- [@fluid-example/multiview-plot-coordinate-view](/examples/data-objects/multiview/plot-coordinate-view) (private)</br>- [@fluid-example/multiview-slider-coordinate-view](/examples/data-objects/multiview/slider-coordinate-view) (private)</br>- [@fluid-example/multiview-triangle-view](/examples/data-objects/multiview/triangle-view) (private)</br>- [@fluid-example/prosemirror](/examples/data-objects/prosemirror) (private)</br>- [@fluid-example/smde](/examples/data-objects/smde) (private)</br>- [@fluid-example/table-document](/examples/data-objects/table-document)</br>- [@fluid-example/todo](/examples/data-objects/todo) (private)</br>- [@fluid-example/webflow](/examples/data-objects/webflow) (private)</br>- [@fluid-example/app-integration-external-data](/examples/external-data) (private)</br>- [@fluid-example/shared-tree-demo](/examples/service-clients/odsp-client/shared-tree-demo) (private)</br>- [@fluid-example/bundle-size-tests](/examples/utils/bundle-size-tests) (private)</br>- [@fluid-example/example-utils](/examples/utils/example-utils) (private)</br>- [@fluid-example/webpack-fluid-loader](/examples/utils/webpack-fluid-loader) (private)</br>- [@fluid-example/app-integration-live-schema-upgrade](/examples/version-migration/live-schema-upgrade) (private)</br>- [@fluid-example/version-migration-same-container](/examples/version-migration/same-container) (private)</br>- [@fluid-example/app-integration-schema-upgrade](/examples/version-migration/schema-upgrade) (private)</br>- [@fluid-example/tree-shim](/examples/version-migration/tree-shim) (private)</br>- [@fluid-example/app-integration-container-views](/examples/view-integration/container-views) (private)</br>- [@fluid-example/app-integration-external-views](/examples/view-integration/external-views) (private)</br>- [@fluid-example/view-framework-sampler](/examples/view-integration/view-framework-sampler) (private)</br>- [@fluid-example/property-inspector](/experimental/PropertyDDS/examples/property-inspector) (private)</br>- [@fluid-example/schemas](/experimental/PropertyDDS/examples/schemas) (private) | - [Core-Interfaces](#Core-Interfaces)</br>- [Driver-Definitions](#Driver-Definitions)</br>- [Container-Definitions](#Container-Definitions)</br>- [Core-Utils](#Core-Utils)</br>- [Client-Utils](#Client-Utils)</br>- [Telemetry-Utils](#Telemetry-Utils)</br>- [Driver-Utils](#Driver-Utils)</br>- [Other-Utils](#Other-Utils)</br>- [Tool-Utils](#Tool-Utils)</br>- [Driver](#Driver)</br>- [Loader](#Loader)</br>- [Runtime](#Runtime)</br>- [Framework](#Framework)</br>- [UberPackage](#UberPackage)</br>- [Server-Libs](#Server-Libs)</br>- [Routerlicious-Driver](#Routerlicious-Driver)</br>- [Test-Utils](#Test-Utils)</br>- [ServiceClients](#ServiceClients)</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp; |
+| - [@fluid-example/attributable-map](/examples/apps/attributable-map) (private)</br>- [@fluid-example/collaborative-textarea](/examples/apps/collaborative-textarea) (private)</br>- [@fluid-example/contact-collection](/examples/apps/contact-collection) (private)</br>- [@fluid-example/data-object-grid](/examples/apps/data-object-grid) (private)</br>- [@fluid-example/presence-tracker](/examples/apps/presence-tracker) (private)</br>- [@fluid-example/task-selection](/examples/apps/task-selection) (private)</br>- [@fluid-example/tree-comparison](/examples/apps/tree-comparison) (private)</br>- [@fluid-example/bubblebench-baseline](/examples/benchmarks/bubblebench/baseline) (private)</br>- [@fluid-example/bubblebench-common](/examples/benchmarks/bubblebench/common) (private)</br>- [@fluid-example/bubblebench-experimental-tree](/examples/benchmarks/bubblebench/experimental-tree) (private)</br>- [@fluid-example/bubblebench-ot](/examples/benchmarks/bubblebench/ot) (private)</br>- [@fluid-example/bubblebench-shared-tree](/examples/benchmarks/bubblebench/shared-tree) (private)</br>- [@fluid-example/odspsnapshotfetch-perftestapp](/examples/benchmarks/odspsnapshotfetch-perftestapp) (private)</br>- [@fluid-internal/tablebench](/examples/benchmarks/tablebench) (private)</br>- [@fluid-example/app-insights-logger](/examples/client-logger/app-insights-logger) (private)</br>- [@fluid-example/canvas](/examples/data-objects/canvas) (private)</br>- [@fluid-example/clicker](/examples/data-objects/clicker) (private)</br>- [@fluid-example/codemirror](/examples/data-objects/codemirror) (private)</br>- [@fluid-example/diceroller](/examples/data-objects/diceroller) (private)</br>- [@fluid-example/inventory-app](/examples/data-objects/inventory-app) (private)</br>- [@fluid-example/monaco](/examples/data-objects/monaco) (private)</br>- [@fluid-example/multiview-constellation-model](/examples/data-objects/multiview/constellation-model) (private)</br>- [@fluid-example/multiview-constellation-view](/examples/data-objects/multiview/constellation-view) (private)</br>- [@fluid-example/multiview-container](/examples/data-objects/multiview/container) (private)</br>- [@fluid-example/multiview-coordinate-model](/examples/data-objects/multiview/coordinate-model) (private)</br>- [@fluid-example/multiview-coordinate-interface](/examples/data-objects/multiview/interface) (private)</br>- [@fluid-example/multiview-plot-coordinate-view](/examples/data-objects/multiview/plot-coordinate-view) (private)</br>- [@fluid-example/multiview-slider-coordinate-view](/examples/data-objects/multiview/slider-coordinate-view) (private)</br>- [@fluid-example/multiview-triangle-view](/examples/data-objects/multiview/triangle-view) (private)</br>- [@fluid-example/prosemirror](/examples/data-objects/prosemirror) (private)</br>- [@fluid-example/smde](/examples/data-objects/smde) (private)</br>- [@fluid-example/table-document](/examples/data-objects/table-document)</br>- [@fluid-example/todo](/examples/data-objects/todo) (private)</br>- [@fluid-example/webflow](/examples/data-objects/webflow) (private)</br>- [@fluid-example/app-integration-external-data](/examples/external-data) (private)</br>- [@fluid-example/shared-tree-demo](/examples/service-clients/odsp-client/shared-tree-demo) (private)</br>- [@fluid-example/bundle-size-tests](/examples/utils/bundle-size-tests) (private)</br>- [@fluid-example/example-utils](/examples/utils/example-utils) (private)</br>- [@fluid-example/migration-tools](/examples/utils/migration-tools) (private)</br>- [@fluid-example/webpack-fluid-loader](/examples/utils/webpack-fluid-loader) (private)</br>- [@fluid-example/app-integration-live-schema-upgrade](/examples/version-migration/live-schema-upgrade) (private)</br>- [@fluid-example/version-migration-same-container](/examples/version-migration/same-container) (private)</br>- [@fluid-example/version-migration-separate-container](/examples/version-migration/separate-container) (private)</br>- [@fluid-example/tree-shim](/examples/version-migration/tree-shim) (private)</br>- [@fluid-example/app-integration-container-views](/examples/view-integration/container-views) (private)</br>- [@fluid-example/app-integration-external-views](/examples/view-integration/external-views) (private)</br>- [@fluid-example/view-framework-sampler](/examples/view-integration/view-framework-sampler) (private)</br>- [@fluid-example/property-inspector](/experimental/PropertyDDS/examples/property-inspector) (private)</br>- [@fluid-example/schemas](/experimental/PropertyDDS/examples/schemas) (private) | - [Core-Interfaces](#Core-Interfaces)</br>- [Driver-Definitions](#Driver-Definitions)</br>- [Container-Definitions](#Container-Definitions)</br>- [Core-Utils](#Core-Utils)</br>- [Client-Utils](#Client-Utils)</br>- [Telemetry-Utils](#Telemetry-Utils)</br>- [Driver-Utils](#Driver-Utils)</br>- [Other-Utils](#Other-Utils)</br>- [Tool-Utils](#Tool-Utils)</br>- [Driver](#Driver)</br>- [Loader](#Loader)</br>- [Runtime](#Runtime)</br>- [Framework](#Framework)</br>- [UberPackage](#UberPackage)</br>- [Server-Libs](#Server-Libs)</br>- [Routerlicious-Driver](#Routerlicious-Driver)</br>- [Test-Utils](#Test-Utils)</br>- [ServiceClients](#ServiceClients)</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp; |
 
 ### Tools
 

examples/utils/example-utils/src/index.ts

@@ -21,41 +21,25 @@ export {
 } from "./containerViewRuntimeFactory.js";
 export type {
 	DataTransformationCallback,
-	IAcceptedMigrationDetails,
 	IImportExportModel,
-	IMigratableModel,
-	IMigrationTool,
-	IMigrationToolEvents,
-	IMigrator,
-	IMigratorEvents,
 	ISameContainerMigratableModel,
 	ISameContainerMigratableModelEvents,
 	ISameContainerMigrationTool,
 	ISameContainerMigrationToolEvents,
 	ISameContainerMigrator,
 	ISameContainerMigratorEvents,
 	IVersionedModel,
-	MigrationState,
 	SameContainerMigrationState,
 } from "./migrationInterfaces/index.js";
 export {
-	MigrationToolFactory,
 	SameContainerMigrationTool,
 	SameContainerMigrationToolInstantiationFactory,
 } from "./migrationTool/index.js";
-export { Migrator, SameContainerMigrator } from "./migrator/index.js";
+export { SameContainerMigrator } from "./migrator/index.js";
 export {
-	CreateModelCallback,
-	IAttachedMigratableModel,
-	IDetachedMigratableModel,
 	IDetachedModel,
-	IMigratableModelContainerRuntimeEntryPoint,
-	IMigratableModelLoader,
 	IModelContainerRuntimeEntryPoint,
 	IModelLoader,
-	instantiateMigratableRuntime,
-	MigratableModelLoader,
-	MigratableSessionStorageModelLoader,
 	ModelContainerRuntimeFactory,
 	ModelLoader,
 	SessionStorageModelLoader,

examples/utils/example-utils/src/migrationInterfaces/index.ts

@@ -5,30 +5,17 @@
 
 export {
 	IImportExportModel,
-	IMigratableModel,
-	IVersionedModel,
-} from "./migratableModel.js";
-export {
-	IAcceptedMigrationDetails,
-	IMigrationTool,
-	IMigrationToolEvents,
-	MigrationState,
-} from "./migrationTool.js";
-export {
-	DataTransformationCallback,
-	IMigrator,
-	IMigratorEvents,
-} from "./migrator.js";
-export {
 	ISameContainerMigratableModel,
 	ISameContainerMigratableModelEvents,
+	IVersionedModel,
 } from "./sameContainerMigratableModel.js";
 export {
 	ISameContainerMigrationTool,
 	ISameContainerMigrationToolEvents,
 	SameContainerMigrationState,
 } from "./sameContainerMigrationTool.js";
 export {
+	DataTransformationCallback,
 	ISameContainerMigrator,
 	ISameContainerMigratorEvents,
 } from "./sameContainerMigrator.js";

examples/utils/example-utils/src/migrationInterfaces/sameContainerMigratableModel.ts

@@ -6,9 +6,45 @@
 import type { IContainer } from "@fluidframework/container-definitions/internal";
 import type { IEvent, IEventProvider } from "@fluidframework/core-interfaces";
 
-import type { IImportExportModel, IVersionedModel } from "./migratableModel.js";
 import type { ISameContainerMigrationTool } from "./sameContainerMigrationTool.js";
 
+/**
+ * A model with a detectable version.
+ *
+ * @remarks
+ * It's appropriate to use this version to deduce the more specific type of model.
+ * @internal
+ */
+export interface IVersionedModel {
+	/**
+	 * The string version of the model, matching the version of the container code it's paired with.
+	 */
+	readonly version: string;
+}
+
+/**
+ * A model that can import data of ImportType when in detached state, and can also export its data to ExportType.
+ * @internal
+ */
+export interface IImportExportModel<ImportType, ExportType> {
+	/**
+	 * Permit format checking in a generic manner - without knowing the type of our data or the type of the model,
+	 * we can still check whether the model supports that data.
+	 */
+	supportsDataFormat: (initialData: unknown) => initialData is ImportType;
+
+	/**
+	 * importData must be called after initialization but before modifying or attaching the model (i.e. can only
+	 * be called on an unaltered, detached model).
+	 */
+	importData: (initialData: ImportType) => Promise<void>;
+
+	/**
+	 * Export the data from the model.  Can be passed into importData() for a new container to replicate the data.
+	 */
+	exportData: () => Promise<ExportType>;
+}
+
 /**
  * @internal
  */

examples/utils/example-utils/src/migrationInterfaces/sameContainerMigrator.ts

@@ -14,6 +14,7 @@ import type {
  * The DataTransformationCallback gives an opportunity to modify the exported data before attempting an import
  * to the new model.  The modelVersion is also provided to inform the appropriate transformation to perform.
  * It is async to permit network calls or lazy-loading the transform logic within the function.
+ * @internal
  */
 export type DataTransformationCallback = (
 	exportedData: unknown,

examples/utils/example-utils/src/migrationTool/index.ts

@@ -3,7 +3,6 @@
  * Licensed under the MIT License.
  */
 
-export { MigrationToolFactory } from "./migrationTool.js";
 export {
 	SameContainerMigrationTool,
 	SameContainerMigrationToolInstantiationFactory,

examples/utils/example-utils/src/migrator/index.ts

@@ -4,4 +4,3 @@
  */
 
 export { SameContainerMigrator } from "./sameContainerMigrator.js";
-export { Migrator } from "./migrator.js";

examples/utils/example-utils/src/modelLoader/index.ts

@@ -4,19 +4,9 @@
  */
 
 export {
-	CreateModelCallback,
-	IMigratableModelContainerRuntimeEntryPoint,
-	instantiateMigratableRuntime,
-} from "./instantiateMigratableRuntime.js";
-export {
-	IAttachedMigratableModel,
 	IDetachedModel,
-	IDetachedMigratableModel,
-	IMigratableModelLoader,
 	IModelLoader,
 } from "./interfaces.js";
-export { MigratableModelLoader } from "./migratableModelLoader.js";
-export { MigratableSessionStorageModelLoader } from "./migratableSessionStorageModelLoader.js";
 export {
 	ModelContainerRuntimeFactory,
 	IModelContainerRuntimeEntryPoint,

examples/utils/example-utils/src/modelLoader/interfaces.ts

@@ -3,82 +3,6 @@
  * Licensed under the MIT License.
  */
 
-import type { IMigrationTool } from "../migrationInterfaces/index.js";
-
-// TODO: Consider just extending IAttachedMigratableModel
-/**
- * Object returned from calling IModelLoader.createDetached().
- * @internal
- */
-export interface IDetachedMigratableModel<ModelType> {
-	/**
-	 * The newly created, detached model object.
-	 */
-	model: ModelType;
-	/**
-	 * The migration tool that will be used to migrate away from this model.
-	 */
-	migrationTool: IMigrationTool;
-	/**
-	 * A function that will attach the model object to the service when called.
-	 * @returns a Promise that will resolve after attach completes with the container ID of the newly attached
-	 * container.
-	 */
-	attach: () => Promise<string>;
-}
-
-/**
- * Object returned from calling IModelLoader.createDetached().
- * @internal
- */
-export interface IAttachedMigratableModel<ModelType> {
-	/**
-	 * The newly created, detached model object.
-	 */
-	model: ModelType;
-	/**
-	 * The migration tool that will be used to migrate away from this model.
-	 */
-	migrationTool: IMigrationTool;
-}
-
-/**
- * @internal
- */
-export interface IMigratableModelLoader<ModelType> {
-	/**
-	 * Check if the IMigratableModelLoader knows how to instantiate an appropriate model for the provided container code version.
-	 * It is async to permit dynamic model loading - e.g. referring to a remote service to determine if the requested
-	 * model is available.
-	 * @param version - the container code version to check
-	 */
-	supportsVersion(version: string): Promise<boolean>;
-
-	/**
-	 * Create a detached model using the specified version of container code.
-	 * Returns an object containing the detached model plus an attach callback.  When invoked, the attach callback
-	 * returns a promise that will resolve after attach has completed with the id of the container.
-	 * @param version - the container code version to create a model for
-	 */
-	createDetached(version: string): Promise<IDetachedMigratableModel<ModelType>>;
-
-	/**
-	 * Load a model for the container with the given id.
-	 * @param id - the id of the container to load
-	 */
-	loadExisting(id: string): Promise<IAttachedMigratableModel<ModelType>>;
-
-	/**
-	 * Load a model for the container with the given id.
-	 * @param id - the id of the container to load
-	 * @param sequenceNumber - the sequence number we want to load to and pause at
-	 */
-	loadExistingPaused(
-		id: string,
-		sequenceNumber: number,
-	): Promise<IAttachedMigratableModel<ModelType>>;
-}
-
 /**
  * Object returned from calling IModelLoader.createDetached().
  * @internal

examples/version-migration/schema-upgrade/.eslintrc.cjs → examples/utils/migration-tools/.eslintrc.cjs

@@ -4,9 +4,6 @@
  */
 
 module.exports = {
-	extends: [
-		require.resolve("@fluidframework/eslint-config-fluid/minimal-deprecated"),
-		"prettier",
-	],
+	extends: [require.resolve("@fluidframework/eslint-config-fluid"), "prettier"],
 	rules: {},
 };

examples/utils/migration-tools/.gitignore

@@ -0,0 +1,52 @@
+# Compiled TypeScript and CSS
+dist
+lib
+
+# Babel
+public/scripts/es5
+
+# Logs
+logs
+*.log
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+.cache-loader
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directory
+# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git-
+node_modules
+
+# Typings
+typings
+
+# Debug log from npm
+npm-debug.log
+
+# Code coverage
+nyc
+.nyc_output/
+
+# Chart dependencies
+**/charts/*.tgz
+
+# Generated modules
+intel_modules/
+temp_modules/