Move fluidPackage.ts from core-interface to container-definitions

BREAKING.md

@@ -21,6 +21,7 @@ There are a few steps you can take to write a good change note and avoid needing
 - [Moved `ICodeDetailsLoader` and `IFluidModuleWithDetails` interface to `@fluidframework/container-definitions`](#Moved-ICodeDetailsLoader-and-IFluidModuleWithDetails-interface-to-fluidframeworkcontainer-definitions)
 - [Removed `errorMessage` property from `ISummaryNack` interface](#Removed-errorMessage-property-from-ISummaryNack-interface)
 - [ISequencedDocumentMessage arg removed from SharedMap and SharedDirectory events](#ISequencedDocumentMessage-arg-removed-from-SharedMap-and-SharedDirectory-events)
+- [Moved `@fluidframework/core-interface#fluidPackage.ts` to `@fluidframework/container-definition#fluidPackage.ts`](#Moved-fluidframeworkcore-interfacefluidPackagets-to-fluidframeworkcontainer-definitionfluidPackagets)
 
 ### `IContainer` interface updated to expose actively used `Container` public APIs
 In order to have the `IContainer` interface be the active developer surface that is used when interacting with a `Container` instance, it has been updated to expose the APIs that are necessary for currently used behavior. The motivation here is to move away from using the `Container` class when only its type is required, and to use the `IContainer` interface instead.
@@ -86,6 +87,20 @@ The `errorMessage` property from the `ISummaryNack` interface was deprecated in
 ### `ISequencedDocumentMessage` arg removed from `SharedMap` and `SharedDirectory` events
 The `ISequencedDocumentMessage` argument in events emitted from `SharedMap` and `SharedDirectory` (the `"valueChanged"` and `"clear"` events) has been removed.  It is not recommended to access the protocol layer directly.  Note that if you were leveraging the `this` argument of these events, you will need to update your event listeners due to the arity change.
 
+### Moved `@fluidframework/core-interface#fluidPackage.ts` to `@fluidframework/container-definition#fluidPackage.ts`
+Moved the following interfaces and const from `@fluidframework/core-interface` to `@fluidframework/container-definitions`:
+- `IFluidPackageEnvironment`
+- `IFluidPackage`
+- `isFluidPackage`
+- `IFluidCodeDetailsConfig`
+- `IFluidCodeDetailsConfig`
+- `IFluidCodeDetails`
+- `IFluidCodeDetailsComparer`
+- `IProvideFluidCodeDetailsComparer`
+- `IFluidCodeDetailsComparer`
+
+They are deprecated from `@fluidframework/core-interface` and would be removed in future release. Please import them from `@fluidframework/container-definitions`.
+
 ## 0.52 Breaking changes
 - [chaincodePackage removed from Container](#chaincodePackage-removed-from-Container)
 - [`OdspDocumentInfo` type replaced with `OdspFluidDataStoreLocator` interface](#OdspDocumentInfo-type-replaced-with-OdspFluidDataStoreLocator-interface)

common/lib/container-definitions/api-report/container-definitions.api.md

@@ -16,15 +16,15 @@ import { IDocumentStorageService } from '@fluidframework/driver-definitions';
 import { IErrorEvent } from '@fluidframework/common-definitions';
 import { IEvent } from '@fluidframework/common-definitions';
 import { IEventProvider } from '@fluidframework/common-definitions';
-import { IFluidCodeDetails } from '@fluidframework/core-interfaces';
+import { IFluidCodeDetails as IFluidCodeDetails_2 } from '@fluidframework/core-interfaces';
 import { IFluidConfiguration } from '@fluidframework/core-interfaces';
 import { IFluidObject } from '@fluidframework/core-interfaces';
-import { IFluidPackage } from '@fluidframework/core-interfaces';
-import { IFluidPackageEnvironment } from '@fluidframework/core-interfaces';
+import { IFluidPackage as IFluidPackage_2 } from '@fluidframework/core-interfaces';
+import { IFluidPackageEnvironment as IFluidPackageEnvironment_2 } from '@fluidframework/core-interfaces';
 import { IFluidResolvedUrl } from '@fluidframework/driver-definitions';
 import { IFluidRouter } from '@fluidframework/core-interfaces';
 import { IPendingProposal } from '@fluidframework/protocol-definitions';
-import { IProvideFluidCodeDetailsComparer } from '@fluidframework/core-interfaces';
+import { IProvideFluidCodeDetailsComparer as IProvideFluidCodeDetailsComparer_2 } from '@fluidframework/core-interfaces';
 import { IQuorum } from '@fluidframework/protocol-definitions';
 import { IRequest } from '@fluidframework/core-interfaces';
 import { IResolvedUrl } from '@fluidframework/driver-definitions';
@@ -97,13 +97,13 @@ export interface ICodeAllowList {
 }
 
 // @public
-export interface ICodeDetailsLoader extends Partial<IProvideFluidCodeDetailsComparer> {
-    load(source: IFluidCodeDetails): Promise<IFluidModuleWithDetails>;
+export interface ICodeDetailsLoader extends Partial<IProvideFluidCodeDetailsComparer_2> {
+    load(source: IFluidCodeDetails_2): Promise<IFluidModuleWithDetails>;
 }
 
 // @public @deprecated
-export interface ICodeLoader extends Partial<IProvideFluidCodeDetailsComparer> {
-    load(source: IFluidCodeDetails): Promise<IFluidModule>;
+export interface ICodeLoader extends Partial<IProvideFluidCodeDetailsComparer_2> {
+    load(source: IFluidCodeDetails_2): Promise<IFluidModule>;
 }
 
 // @public
@@ -136,18 +136,18 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
     closeAndGetPendingLocalState(): string;
     readonly closed: boolean;
     // @deprecated
-    readonly codeDetails?: IFluidCodeDetails | undefined;
+    readonly codeDetails?: IFluidCodeDetails_2 | undefined;
     readonly connected?: boolean;
     readonly connectionState?: ConnectionState;
     deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
     // @alpha
     forceReadonly?(readonly: boolean): any;
     getAbsoluteUrl(relativeUrl: string): Promise<string | undefined>;
-    getLoadedCodeDetails?(): IFluidCodeDetails | undefined;
+    getLoadedCodeDetails?(): IFluidCodeDetails_2 | undefined;
     getQuorum(): IQuorum;
-    getSpecifiedCodeDetails?(): IFluidCodeDetails | undefined;
+    getSpecifiedCodeDetails?(): IFluidCodeDetails_2 | undefined;
     readonly isDirty: boolean;
-    proposeCodeDetails(codeDetails: IFluidCodeDetails): Promise<boolean>;
+    proposeCodeDetails(codeDetails: IFluidCodeDetails_2): Promise<boolean>;
     readonly readOnlyInfo?: ReadOnlyInfo;
     request(request: IRequest): Promise<IResponse>;
     resolvedUrl: IResolvedUrl | undefined;
@@ -183,7 +183,7 @@ export interface IContainerContext extends IDisposable {
     // (undocumented)
     getLoadedFromVersion(): IVersion | undefined;
     // @deprecated (undocumented)
-    getSpecifiedCodeDetails?(): IFluidCodeDetails | undefined;
+    getSpecifiedCodeDetails?(): IFluidCodeDetails_2 | undefined;
     // (undocumented)
     readonly id: string;
     // (undocumented)
@@ -220,9 +220,9 @@ export interface IContainerEvents extends IEvent {
     // (undocumented)
     (event: "connected", listener: (clientId: string) => void): any;
     // (undocumented)
-    (event: "codeDetailsProposed", listener: (codeDetails: IFluidCodeDetails, proposal: IPendingProposal) => void): any;
+    (event: "codeDetailsProposed", listener: (codeDetails: IFluidCodeDetails_2, proposal: IPendingProposal) => void): any;
     // (undocumented)
-    (event: "contextChanged", listener: (codeDetails: IFluidCodeDetails) => void): any;
+    (event: "contextChanged", listener: (codeDetails: IFluidCodeDetails_2) => void): any;
     // (undocumented)
     (event: "disconnected" | "attached", listener: () => void): any;
     // (undocumented)
@@ -334,39 +334,77 @@ export interface IErrorBase extends Partial<Error> {
 }
 
 // @public
-export interface IFluidBrowserPackage extends IFluidPackage {
+export interface IFluidBrowserPackage extends IFluidPackage_2 {
     // (undocumented)
     fluid: {
         browser: IFluidBrowserPackageEnvironment;
-        [environment: string]: IFluidPackageEnvironment;
+        [environment: string]: IFluidPackageEnvironment_2;
     };
 }
 
 // @public
-export interface IFluidBrowserPackageEnvironment extends IFluidPackageEnvironment {
+export interface IFluidBrowserPackageEnvironment extends IFluidPackageEnvironment_2 {
     umd: {
         files: string[];
         library: string;
     };
 }
 
+// @public
+export interface IFluidCodeDetails {
+    readonly config?: IFluidCodeDetailsConfig;
+    readonly package: string | Readonly<IFluidPackage>;
+}
+
+// @public (undocumented)
+export const IFluidCodeDetailsComparer: keyof IProvideFluidCodeDetailsComparer;
+
+// @public
+export interface IFluidCodeDetailsComparer extends IProvideFluidCodeDetailsComparer {
+    compare(a: IFluidCodeDetails, b: IFluidCodeDetails): Promise<number | undefined>;
+    satisfies(candidate: IFluidCodeDetails, constraint: IFluidCodeDetails): Promise<boolean>;
+}
+
+// @public
+export interface IFluidCodeDetailsConfig {
+    // (undocumented)
+    readonly [key: string]: string;
+}
+
 // @public
 export interface IFluidCodeResolver {
-    resolveCodeDetails(details: IFluidCodeDetails): Promise<IResolvedFluidCodeDetails>;
+    resolveCodeDetails(details: IFluidCodeDetails_2): Promise<IResolvedFluidCodeDetails>;
 }
 
 // @public (undocumented)
 export interface IFluidModule {
     // (undocumented)
-    fluidExport: IFluidObject & FluidObject<IRuntimeFactory & IProvideFluidCodeDetailsComparer>;
+    fluidExport: IFluidObject & FluidObject<IRuntimeFactory & IProvideFluidCodeDetailsComparer_2>;
 }
 
 // @public
 export interface IFluidModuleWithDetails {
-    details: IFluidCodeDetails;
+    details: IFluidCodeDetails_2;
     module: IFluidModule;
 }
 
+// @public
+export interface IFluidPackage {
+    [key: string]: unknown;
+    fluid: {
+        [environment: string]: undefined | IFluidPackageEnvironment;
+    };
+    name: string;
+}
+
+// @public
+export interface IFluidPackageEnvironment {
+    [target: string]: undefined | {
+        files: string[];
+        [key: string]: unknown;
+    };
+}
+
 // @public @deprecated (undocumented)
 export const IFluidTokenProvider: keyof IProvideFluidTokenProvider;
 
@@ -388,7 +426,7 @@ export interface IGenericError extends IErrorBase {
 
 // @public
 export interface IHostLoader extends ILoader {
-    createDetachedContainer(codeDetails: IFluidCodeDetails): Promise<IContainer>;
+    createDetachedContainer(codeDetails: IFluidCodeDetails_2): Promise<IContainer>;
     rehydrateDetachedContainerFromSnapshot(snapshot: string): Promise<IContainer>;
 }
 
@@ -438,6 +476,12 @@ export interface IProvideDeltaSender {
     readonly IDeltaSender: IDeltaSender;
 }
 
+// @public (undocumented)
+export interface IProvideFluidCodeDetailsComparer {
+    // (undocumented)
+    readonly IFluidCodeDetailsComparer: IFluidCodeDetailsComparer;
+}
+
 // @public @deprecated (undocumented)
 export interface IProvideFluidTokenProvider {
     // (undocumented)
@@ -463,8 +507,8 @@ export interface IProxyLoaderFactory {
 }
 
 // @public
-export interface IResolvedFluidCodeDetails extends IFluidCodeDetails {
-    readonly resolvedPackage: Readonly<IFluidPackage>;
+export interface IResolvedFluidCodeDetails extends IFluidCodeDetails_2 {
+    readonly resolvedPackage: Readonly<IFluidPackage_2>;
     readonly resolvedPackageCacheId: string | undefined;
 }
 
@@ -491,6 +535,12 @@ export interface IRuntimeFactory extends IProvideRuntimeFactory {
 // @public
 export const isFluidBrowserPackage: (maybePkg: any) => maybePkg is Readonly<IFluidBrowserPackage>;
 
+// @public (undocumented)
+export const isFluidCodeDetails: (details: unknown) => details is Readonly<IFluidCodeDetails>;
+
+// @public
+export const isFluidPackage: (pkg: any) => pkg is Readonly<IFluidPackage>;
+
 // @public
 export interface IThrottlingWarning extends IErrorBase {
     // (undocumented)

common/lib/container-definitions/src/fluidPackage.ts

@@ -0,0 +1,132 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+ /**
+  * Specifies an environment on Fluid property of a IFluidPackage
+  */
+export interface IFluidPackageEnvironment {
+
+    /**
+     * The name of the target. For a browser environment, this could be umd for scripts
+     * or css for styles.
+     */
+    [target: string]: undefined | {
+        /**
+         * List of files for the target. These can be relative or absolute.
+         * The code loader should resolve relative paths, and validate all
+         * full urls.
+         */
+        files: string[];
+
+        /**
+         * General access for extended fields as specific usages will
+         * likely have additional infornamation like a definition
+         * of Library, the entrypoint for umd packages
+         */
+        [key: string]: unknown;
+    }
+}
+
+/**
+ * Fluid-specific properties expected on a package to be loaded by the code loader.
+ * While compatible with the npm package format it is not necessary that that package is an
+ * npm package:
+ * {@link https://stackoverflow.com/questions/10065564/add-custom-metadata-or-config-to-package-json-is-it-valid}
+ */
+export interface IFluidPackage {
+    /**
+     * The name of the package that this code represnets
+     */
+    name: string;
+    /**
+     * This object represents the Fluid specific properties of the package
+     */
+    fluid: {
+        /**
+         * The name of the of the environment. This should be something like browser, or node
+         * and contain the necessary targets for loading this code in that environment.
+         */
+        [environment: string]:  undefined | IFluidPackageEnvironment;
+    };
+    /**
+     * General access for extended fields as specific usages will
+     * likely have additional infornamation like a definition of
+     * compatible versions, or deployment information like rings or rollouts.
+     */
+    [key: string]: unknown;
+}
+
+/**
+ * Check if the package.json defines a Fluid package
+ * @param pkg - the package json data to check if it is a Fluid package.
+ */
+export const isFluidPackage = (pkg: any): pkg is Readonly<IFluidPackage> =>
+    typeof pkg === "object"
+    && typeof pkg?.name === "string"
+    && typeof pkg?.fluid === "object";
+
+/**
+ * Package manager configuration. Provides a key value mapping of config values
+ */
+export interface IFluidCodeDetailsConfig {
+    readonly [key: string]: string;
+}
+
+/**
+ * Data structure used to describe the code to load on the Fluid document
+ */
+export interface IFluidCodeDetails {
+    /**
+     * The code package to be used on the Fluid document. This is either the package name which will be loaded
+     * from a package manager. Or the expanded Fluid package.
+     */
+    readonly package: string | Readonly<IFluidPackage>;
+
+    /**
+     * Configuration details. This includes links to the package manager and base CDNs.
+     */
+    readonly config?: IFluidCodeDetailsConfig;
+}
+
+export const isFluidCodeDetails = (details: unknown): details is Readonly<IFluidCodeDetails> =>{
+    const maybeCodeDetails = details as Partial<IFluidCodeDetails> | undefined;
+    return typeof maybeCodeDetails === "object"
+        && (typeof maybeCodeDetails?.package === "string" || isFluidPackage(maybeCodeDetails?.package))
+        && (maybeCodeDetails?.config === undefined || typeof maybeCodeDetails?.config === "object");
+};
+
+export const IFluidCodeDetailsComparer: keyof IProvideFluidCodeDetailsComparer = "IFluidCodeDetailsComparer";
+
+export interface IProvideFluidCodeDetailsComparer {
+    readonly IFluidCodeDetailsComparer: IFluidCodeDetailsComparer ;
+}
+
+/**
+ * Provides capability to compare Fluid code details.
+ */
+export interface IFluidCodeDetailsComparer extends IProvideFluidCodeDetailsComparer {
+
+    /**
+     * Determines if the `candidate` code details satisfy the constraints specified in `constraint` code details.
+     *
+     * Similar semantics to:
+     * {@link https://github.com/npm/node-semver#usage}
+     */
+    satisfies(candidate: IFluidCodeDetails, constraint: IFluidCodeDetails): Promise<boolean>;
+
+/* eslint-disable max-len */
+    /**
+     * Return a number representing the ascending sort order of the `a` and `b` code details;
+     *      `< 0` if `a < b`.
+     *      `= 0` if `a === b`.
+     *      `> 0` if `a > b`.
+     *      `undefined` if `a` is not comparable to `b`.
+     *
+     * Similar semantics to:
+     * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Description | Array.sort}
+     */
+    compare(a: IFluidCodeDetails, b: IFluidCodeDetails): Promise<number | undefined>;
+/* eslint-enable max-len */
+}

common/lib/container-definitions/src/index.ts

@@ -10,5 +10,6 @@ export * from "./deltas";
 export * from "./error";
 export * from "./loader";
 export * from "./fluidModule";
+export * from "./fluidPackage";
 export * from "./proxyLoader";
 export * from "./runtime";