Move migration-tools to separate example package

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/

examples/utils/migration-tools/README.md

@@ -0,0 +1,48 @@
+# @fluid-example/migration-tools
+
+This package contains tools for migrating data from one version to another, used by Fluid examples. They are not currently intended for use in production scenarios.
+
+See [GitHub](https://github.com/microsoft/FluidFramework) for more details on the Fluid Framework and packages within.
+
+<!-- AUTO-GENERATED-CONTENT:START (README_FOOTER) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Contribution Guidelines
+
+There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid.
+
+-   Participate in Q&A in our [GitHub Discussions](https://github.com/microsoft/FluidFramework/discussions).
+-   [Submit bugs](https://github.com/microsoft/FluidFramework/issues) and help us verify fixes as they are checked in.
+-   Review the [source code changes](https://github.com/microsoft/FluidFramework/pulls).
+-   [Contribute bug fixes](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md).
+
+Detailed instructions for working in the repo can be found in the [Wiki](https://github.com/microsoft/FluidFramework/wiki).
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+
+This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
+Use of these trademarks or logos must follow Microsoft’s [Trademark & Brand Guidelines](https://www.microsoft.com/trademarks).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+
+## Help
+
+Not finding what you're looking for in this README? Check out [fluidframework.com](https://fluidframework.com/docs/).
+
+Still not finding what you're looking for? Please [file an issue](https://github.com/microsoft/FluidFramework/wiki/Submitting-Bugs-and-Feature-Requests).
+
+Thank you!
+
+## Trademark
+
+This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
+
+Use of these trademarks or logos must follow Microsoft's [Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->

examples/utils/migration-tools/api-extractor-lint.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-lint.esm.primary.json"
+}

examples/utils/migration-tools/api-extractor.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
+}

examples/utils/migration-tools/api-report/migration-tools.alpha.api.md

@@ -0,0 +1,9 @@
+## Alpha API Report File for "@fluid-example/migration-tools"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// (No @packageDocumentation comment for this package)
+
+```

examples/utils/migration-tools/api-report/migration-tools.beta.api.md

@@ -0,0 +1,9 @@
+## Beta API Report File for "@fluid-example/migration-tools"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// (No @packageDocumentation comment for this package)
+
+```

examples/utils/migration-tools/api-report/migration-tools.public.api.md

@@ -0,0 +1,9 @@
+## Public API Report File for "@fluid-example/migration-tools"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// (No @packageDocumentation comment for this package)
+
+```