/** * SharePoint Framework core libraries. * * @remarks * This package provides a foundation of core classes that ensure a consistent character * across all the other SharePoint Framework APIs. Because this package is a dependency * of every other package, its design prioritizes small code size and broad applicability, * versus flexibility or richness of features. * * @packagedocumentation */ import { ActiveEcsClientFlights } from '@msinternal/ecs-flight'; import { PRIMARY_VERSIONED_PATH as _FluentIconVersionedCdnPath } from '@msinternal/odsp-core-bundle'; import { PRIMARY_VERSIONED_PATH_TEMP as _FluentIconVersionedCdnPathTemp } from '@msinternal/odsp-core-bundle'; import type { IClientSideComponentManifest } from '@microsoft/sp-module-interfaces'; import type { ILocalizedString } from '@microsoft/sp-module-interfaces'; import { VetoValues as _VetoValues } from '@msinternal/odsp-core-bundle'; /* Excluded from this release type: _BROKER_IN_USE_KEY */ /* Excluded from this release type: _Browser */ /* Excluded from this release type: _BrowserDetection */ /* Excluded from this release type: _BrowserUtilities */ /* Excluded from this release type: _ClientManifestData */ /** * Utility type to evaluate if {@link _RecursivelyExtractFromSet} should continue recursion. * * @remarks Use {@link ExtractFromSet}. This type is not meant to be used by itself. * * @public */ export declare type _ContinueRecursivelyExtractFromSet = _Stop extends true ? never : _RecursivelyExtractFromSet; /* Excluded from this release type: _DeferredClass */ /** * Indicates whether a visual control should display itself for reading or for editing. * * @public */ export declare enum DisplayMode { /** * The page, control, or editing surface is in a mode intended for reading. It may have some interactive * features, but the authoring controls are not enabled. */ Read = 1, /** * The page, control, or editing surface is in a mode intended for authoring new content. It may display * editing panels or other controls that are not part of the normal reading experience. */ Edit = 2, /* Excluded from this release type: Preview */ } /** * Utility type to ensure that `T` extends `U`. * * @public */ export declare type EnsureExtends = T extends U ? T : never; /** * Information about the system environment where the SharePoint Framework is running. * @public */ export declare class Environment { private static _type; /* Excluded from this release type: _initialize */ /** * Indicates the general type of environment where the SharePoint Framework is running. */ static get type(): EnvironmentType; } /** * Indicates the general type of environment where the SharePoint Framework is running. * * @remarks * This enum is used by the {@link Environment."type"} property. It provides a way to distinguish * environments where certain functionality may be limited or disabled. * * @public */ export declare enum EnvironmentType { /** * Indicates that the SharePoint Framework is running inside a test harness, e.g. a unit test. * There may be no user interaction at all, and network access in general may be disabled. */ Test = 0, /** * Indicates that the SharePoint Framework is running on a page from a "localhost" web server, * for example the SharePoint Workbench when hosted via "gulp serve". SharePoint REST API calls * will not be available, and in general network access may not authenticate properly. * Certain page context information may be using mock values for testing. * * @deprecated The local workbench has been removed. Use {@link EnvironmentType.SharePoint} instead. */ Local = 1, /** * Indicates that the SharePoint Framework is running on a modern SharePoint web page, * with full framework functionality. This is the normal usage scenario. */ SharePoint = 2, /** * Indicates that the framework was hosted by a classic server-rendered SharePoint page. * Some functionality may be limited, e.g. various extensibility APIs may not be supported. */ ClassicSharePoint = 3 } /* Excluded from this release type: _Envoy */ /* Excluded from this release type: _ES5CompatibleClass */ /* Excluded from this release type: _Event */ /* Excluded from this release type: _EventArgs */ /** * Utility type to extract `Type` from `Set` if and only if `Type` is in `Set`. * * @remarks If `Type` is not within `Set` then `never` is assigned. * * @public */ export declare type ExtractFromSet = _RecursivelyExtractFromSet; export { _FluentIconVersionedCdnPath } export { _FluentIconVersionedCdnPathTemp } /** * @public */ export declare enum FormDisplayMode { Display = 4, Edit = 6, New = 8 } /** * This class represents a globally unique identifier, as described by * IETF RFC 4122. * * @remarks * The input string is normalized and validated, which provides * important guarantees that simplify other code that works with the GUID. * This class also provides basic support for generating a pseudo-random GUID; * however, be aware that the uniqueness depends on the browser's `Math.random()` * function and may be not be suitable for some applications. * * See {@link https://www.ietf.org/rfc/rfc4122.txt | RFC4122} for more information. * * @public */ export declare class Guid { /** * Returns a new empty Guid instance. * * @returns A new empty Guid object. */ static readonly empty: Guid; private static readonly _guidRegEx; /** * Internal guid value */ private _guid; /** * Returns a new Guid instance with a pseudo-randomly generated GUID, according * to the version 4 UUID algorithm from RFC 4122. * * @returns A new unique Guid object */ static newGuid(randomNumberGenerator?: IRandomNumberGenerator): Guid; /** * Parses the input string to construct a new Guid object. * If the string cannot be parsed, then an error is thrown. * * @remarks * Example syntaxes accepted by this function: * * - `"d5369f3bbd7a412a9c0f7f0650bb5489"` * * - `"d5369f3b-bd7a-412a-9c0f-7f0650bb5489"` * * - `"{d5369f3b-bd7a-412a-9c0f-7f0650bb5489}"` * * - `"/Guid(d5369f3b-bd7a-412a-9c0f-7f0650bb5489)/"` * * @param guidString - The input string. * @returns A valid Guid object */ static parse(guidString: string | undefined | null): Guid; /** * Attempts to parse the input string to construct a new Guid object. * If the string cannot be parsed, then undefined is returned. * * @remarks * Example syntaxes accepted by this function: * * - `"d5369f3bbd7a412a9c0f7f0650bb5489"` * * - `"d5369f3b-bd7a-412a-9c0f-7f0650bb5489"` * * - `"{d5369f3b-bd7a-412a-9c0f-7f0650bb5489}"` * * - `"/Guid(d5369f3b-bd7a-412a-9c0f-7f0650bb5489)/"` * * @param guid - The input string. * @returns The Guid object, or undefined if the string could not be parsed. */ static tryParse(guid: string | undefined | null): Guid | undefined; /** * Indicates whether a GUID is valid, i.e. whether it would be successfully * parsed by `Guid.tryParse()`. This function is cheaper than `Guid.tryParse()` * because it does not construct a Guid object. * * @param guid - The input string. * @returns true, if the Guid is valid. */ static isValid(guid: string | undefined | null): boolean; /** * SharePoint can have guids in the form: * - `Guid(...)` * - `/Guid(...)/` * - `{...}` * _normalize transforms guids in this format to the standard * guid format. * * Example: `Guid(d5369f3b-bd7a-412a-9c0f-7f0650bb5489)` becomes `d5369f3b-bd7a-412a-9c0f-7f0650bb5489` * Example: `{d5369f3b-bd7a-412a-9c0f-7f0650bb5489}` becomes `d5369f3b-bd7a-412a-9c0f-7f0650bb5489` * * @param guid - Guid to be normalized, could already be normalized. * @returns Normalized guid. */ private static _normalize; /** * Creates a new guid. * * @returns A valid guid (according to RFC4122) */ private static _generateGuid; /** * Compare this instance to another Guid instance * * @returns True if this instance and the specified Guid object * represent the same value. */ equals(guid: Guid): boolean; /** * Returns a string representation of the GUID * * @returns The GUID value in lowercase hexadecimal without braces. * * Example: `'d5369f3b-bd7a-412a-9c0f-7f0650bb5489'` */ toString(): string; /** * Use `Guid.parse()` or `Guid.tryParse()` instead of the constructor. * @param guid - a normalized, already valid Guid string */ private constructor(); } /* Excluded from this release type: _IBrowserInformation */ /** * Implemented by an object that supports a disposal lifecycle. * * @remarks * The dispose event allows an object to free any resources that it allocated * before its lifecycle ends. * * @public */ export declare interface IDisposable { /** * Returns true if the dispose() method has been called. Once an object is disposed, * it remains in this state permanently. * * @remarks * After the object has been disposed, do not call its methods or access its properties. */ isDisposed: boolean; /** * This method is called to permanently dispose the object. * * @remarks * After the object has been disposed, do not call its methods or access its properties. */ dispose(): void; } /* Excluded from this release type: _IDynamicDataParentIframeCommunicator */ /* Excluded from this release type: _IEnvironmentData */ /* Excluded from this release type: _IExperimentContext */ /* Excluded from this release type: ILogHandler */ /* Excluded from this release type: _IPrivateSPExperiment */ /** * This is a {@link ServiceScope} contract for generating pseudorandom random numbers. * * @remarks * This interface abstracts the functionality of the system Math.random() API * for usage with a {@link ServiceScope}. For example, a unit test might replace * the default {@link RandomNumberGenerator} service with a mock implementation * that always returns the same sequence of random numbers, in order to ensure that * test failures are always repeatable. * * @public */ export declare interface IRandomNumberGenerator { /** * Returns a pseudorandom number between 0 (inclusive) and 1 (exclusive), * following the contract of Math.random(). */ generate(): number; } /* Excluded from this release type: _isDebugEnabled */ /** * A shorthand pattern for extracting well-known services from a ServiceScope. * * @public * * @deprecated This pattern has been superceded by the BaseComponentContext pattern. * This interface will be removed in a future release. */ export declare interface IServiceCollection { /** * Returns the underlying ServiceScope that the members belong to. */ readonly serviceScope: ServiceScope; } /** * The ServiceKey is a lookup key that is used when calling {@link ServiceScope.consume} * to fetch a dependency. * * @remarks * Every service key also provides a default implementation of the dependency, which will * be automatically created in the root scope if the dependency is not found. Providing a default * implementation ensures that new dependencies can be safely introduced without inadvertently * breaking components that are loaded by an older host that does not provide the new dependency. * * @public */ export declare interface IServiceKey { /** * A unique identifier for this service key. * * @remarks * This identifier is an automatically generated string that will be unique for the lifetime * of the page. Callers should not make assumptions about the formatting of this string. It is * currently based on a global counter, but this may change in the future. * * The ServiceScope uses this identifier internally as a dictionary key for finding services. * The ServiceKey is meant to be unique, even if multiple instances of the same library are * loaded on the same page, even if the same name was passed to ServiceKey.create(). * This is because each call to ServiceKey.create() could potentially provide a different * defaultCreator implementation, whereas one of the design goals of ServiceScope is that * the order in which libraries are loaded should never affect the resulting tree of scopes. */ readonly id: string; /* Excluded from this release type: _isRootService */ /** * The name of the service. * * @remarks * This name is used for logging and diagnostic purposes only. To make it unique, the * recommended convention is the package name, followed by a period, followed by the * class or interface name. * * The system does not assume that this string is unique. Instead, the {@link ServiceKey.id} * is used wherever a lookup key is needed. */ readonly name: string; /** * A callback function that constructs the default instance of this service. */ readonly defaultCreator: ServiceCreator; } /** * The service locator pattern used by the SharePoint Framework. * * @remarks * ServiceScope provides a formalized way for components to register and consume dependencies * ("services"), and to enable different implementations to be registered in different scopes. * This improves modularity by decoupling components from their dependencies in an extensible way. * * For example, suppose that various components need access to an IPageManager instance. We could * simply make the PageManager a singleton (i.e. global variable), but this will not work e.g. if * we need to create a pop-up dialog that requires a second PageManager instance. A better solution * would be to add the PageManager as a constructor parameter for each component that requires it, * however then we immediately face the problem that any code that calls these constructors * also needs a PageManager parameter. In an application with many such dependencies, business * logic that ties together many subsystems would eventually pick up a constructor parameter * for every possible dependency, which is awkward. A natural solution would be to move all the * dependencies into a class with name like "ApplicationContext", and then pass this around as our * constructor parameter. This enables the PageManager to be passed to classes that need it * without cluttering the intermediary classes that don't. However, it still has a design problem * that "ApplicationContext" has hard-coded dependencies on many unrelated things. A more flexible * approach is to make it a dictionary that can look up items for consumers/providers who know the * right lookup key (i.e. ServiceKey). This is the popular "service locator" design pattern, * familiar from the SPContext API in classic SharePoint. * * ServiceScope takes this idea a step further in two important ways: First, it provides a scoping * mechanism so that e.g. if we have two different pages, they can each provide a unique PageManager * instance while still sharing other common dependencies. Secondly, it allows for a ServiceKey * to provide a default implementation of the dependency. This is important for API stability in * our modular client-side environment: For example, suppose that version 2.0 of our application * introduced a new IDiagnosticTracing interface that a version 2.0 component will expect to consume. * If the version 2.0 component gets loaded by an older 1.0 application, it would fail. We could * fix this by requiring each consumer to check for any missing dependencies and handle that case, * but it would require a lot of checks. A better solution is to ensure that a default implementation * always exists, perhaps just a trivial behavior, so that components can assume that consume() will * always return some object that implements the contract. * * Usage: ServiceScope instances are created by calling either ServiceScope.startNewRoot() or * ServiceScope.startNewChild(). They are initially in an "unfinished" state, during which provide() * can be called to register service keys, but consume() is disallowed. After ServiceScope.finish() * is called, consume() is allowed and provide() is now disallowed. These semantics ensure that * ServiceScope.consume() always returns the same result for the same key, and does not depend on * order of initialization. It also allows us to support circular dependencies without worrying * about infinite loops. (Circular dependencies are best avoided, however this is difficult to * guarantee when working with components that were contributed by various third parties without * any coordination.) To avoid mistakes, it's best to always call consume() inside a callback from * serviceScope.whenFinished(). * * @public */ export declare interface IServiceScope { /** * This is a shorthand function that is equivalent to constructing a new instance of the * simpleServiceClass, then registering it by calling ServiceScope.provide(). * * @param serviceKey - the key that can be used later to consume the service * @param simpleServiceClass - the TypeScript class to be constructed * @returns a newly constructed instance of simpleServiceClass */ createAndProvide(serviceKey: IServiceKey, simpleServiceClass: { new (serviceScope: IServiceScope): T; }): T; /** * This is a shorthand function that constructs the default implementation of the specified * serviceKey, and then registers it by calling ServiceScope.provide(). * * @param serviceKey - the key that can be used later to consume the service * @returns a service instance that was constructed using ServiceKey.defaultCreator */ createDefaultAndProvide(serviceKey: IServiceKey): T; /** * Consumes a service from the service scope. * * @remarks * Components should call this function to "consume" a dependency, i.e. look up the serviceKey * and return the registered service instance. If the instance cannot be found, then a default * instance will be automatically created and registered with the root ServiceScope. * * @param serviceKey - the key that was used when provide() was called to register the service * @returns the service instance */ consume(serviceKey: IServiceKey): T; /** * Completes the initialization sequence for a service scope. * * @remarks * When a ServiceScope is first started, it is in an "unfinished" state where provide() is * allowed but consume() is disallowed. After calling finish(), then consume() is allowed * but provide() is disallowed. * * This formalism prevents a number of complex situations that could lead to bugs. For example, * supposed that Scope2 is a child of Scope1, and Scope1 provides instance A1 of interface A. * If someone consumes A1 from Scope2 (via inheritance) before Scope2.provide() is called * with A2, then a subsequent call to Scope2.consume() might return a different result than * the previous call. This nondeterminism could cause unpredictable results that are * difficult to diagnose. */ finish(): void; /** * Returns the parent of the current ServiceScope, or undefined if this is a root scope. * * @returns the parent service scope */ getParent(): IServiceScope | undefined; /** * Defer an operation until after {@link ServiceScope.finish} has completed. * * @remarks * It is an error to call ServiceScope.consume() before finish() has been called. * The most reliable way to protect your component against this error is to perform the * consume() calls inside a whenFinished() callback. If the service scope is already * finished, then the callback will be executed immediately. Otherwise, it will be executed * after the scope is finished in order of callback registration * * NOTE: This is not an asynchronous callback. ServiceScope initialization is typically * inexpensive and short lived. However, the control flow often threads through numerous * constructors and base classes, which can be simplified using whenFinished(). * * @param callback - A block of code that needs to call ServiceScope.consume() */ whenFinished(callback: () => void): void; /** * Add a new service to a service scope. * * @remarks * ServiceScope.provide() is used to register an implementation of the given serviceKey * for the current scope, and an implementation of a given rootServiceKey for the root scope. * It may only be used when the ServiceScope is in an "unfinished" * state, i.e. before finish() has been called. * * @param serviceKey - the key that will later be used to consume the service * @param service - the service instance that is being registered * @returns the same object that was passed as the "service" parameter */ provide(serviceKey: IServiceKey, service: T): T; /** * Constructs a new ServiceScope that is a child of the current scope. * * @remarks * The service scopes form a tree structure, such that when consuming a service, * if the key is not explicitly provided by a child scope, the parent hierarchy * will be consulted. * * @returns the newly created root ServiceScope */ startNewChild(): IServiceScope; /* Excluded from this release type: _isFinished */ } /* Excluded from this release type: _ISessionData */ /** * Utility type to check if `Type` is `never`. * * @remarks Since `never` is an empty set, the brackets are used to disable distribution over the generic type argument. * * @public */ export declare type _IsNever = [Type] extends [never] ? true : false; /** * Used with the {@link SPEvent} system, this interface is implemented by components that * can subscribe to events. * * @remarks * ISPEventObserver is an abstraction of the key features that a component must have in order * to subscribe to a SharePoint Framework event: It must have instanceId and componentId * information for diagnostics reporting, and it must have a way to notify the event system * when the component is disposed, so that its handlers can be automatically removed. * Other objects may implement this contract, as long as they meet these requirements. * * @public */ export declare interface ISPEventObserver extends IDisposable { /** * The instance identifier for the component. * * @remarks * This will be used for diagnostic reporting, e.g. if the callback function has * an uncaught exception */ readonly instanceId: string; /** * The component identifier, from the component's manifest. * * @remarks * This will be used for diagnostic reporting, e.g. if the callback function has * an uncaught exception */ readonly componentId: string; /* Excluded from this release type: manifest */ } /** * Helper type to determine if a type is a string union. * * @public */ export declare type IsStringUnion = IsUnion extends true ? (T extends string ? true : false) : false; /** * Helper type to determine if a type is a union. * * @public */ export declare type IsUnion = [T] extends [UnionToIntersection] ? false : true; /** * This is a {@link ServiceScope} contract for reading the system clock. * * @remarks * This interface abstracts the functionality of the system time APIs * for usage with a {@link ServiceScope}. For example, a unit test might replace * the default {@link TimeProvider} service with a mock implementation * that follows a manually incremented timeline, in order to ensure that * test failures are always repeatable. * * @public */ export declare interface ITimeProvider { /** * Returns the current date/time, similar to the Date class constructor. */ getDate(): Date; /** * Returns a DOMHighResTimeStamp timing measurement, as defined by the * standard performance.now() API. */ getTimestamp(): number; } /** * A basic redirectable logging system. * * @remarks * The Log class provides static methods for logging messages at different levels (verbose, * info, warning, error) and with context information. Context information helps identify * which component generated the messages and allows for filtering of log events. In a * SharePoint Framework application, these messages will appear on the developer dashboard. * * @public */ export declare class Log { private static _logHandler; /* Excluded from this release type: _initialize */ /** * Logs a message which contains detailed information that is generally only needed for * troubleshooting. * @param source - the source from where the message is logged, e.g., the class name. * The source provides context information for the logged message. * If the source's length is more than 20, only the first 20 characters are kept. * @param message - the message to be logged * If the message's length is more than 100, only the first 100 characters are kept. * @param scope - the service scope that the source uses. A service scope can provide * more context information (e.g., web part information) to the logged message. */ static verbose(source: string, message: string, scope?: ServiceScope): void; /** * Logs a general informational message. * @param source - the source from where the message is logged, e.g., the class name. * The source provides context information for the logged message. * If the source's length is more than 20, only the first 20 characters are kept. * @param message - the message to be logged * If the message's length is more than 100, only the first 100 characters are kept. * @param scope - the service scope that the source uses. A service scope can provide * more context information (e.g., web part information) to the logged message. */ static info(source: string, message: string, scope?: ServiceScope): void; /** * Logs a warning. * @param source - the source from where the message is logged, e.g., the class name. * The source provides context information for the logged message. * If the source's length is more than 20, only the first 20 characters are kept. * @param message - the message to be logged * If the message's length is more than 100, only the first 100 characters are kept. * @param scope - the service scope that the source uses. A service scope can provide * more context information (e.g., web part information) to the logged message. */ static warn(source: string, message: string, scope?: ServiceScope): void; /** * Logs an error. * @param source - the source from where the error is logged, e.g., the class name. * The source provides context information for the logged error. * If the source's length is more than 20, only the first 20 characters are kept. * @param error - the error to be logged * @param scope - the service scope that the source uses. A service scope can provide * more context information (e.g., web part information) to the logged error. */ static error(source: string, error: Error, scope?: ServiceScope): void; } /** * Utility type to get the next value for a recursive conditional evaluation. * * @remarks Use {@link ExtractFromSet}. This type is not meant to be used by itself. * @remarks `Set` should be the full set of values to recurse over and `Current` is the set of values already evaluated. Therefore, indexing into `Set` with `Current`'s length yields the next value to evaluate. * * @public */ export declare type _NextValue = Set[Current['length']]; /* Excluded from this release type: _NumericRange */ /* Excluded from this release type: _OS */ /** * This is the default implementation of {@link IRandomNumberGenerator} that simply * calls Math.random(). * * @public */ export declare class RandomNumberGenerator implements IRandomNumberGenerator { /** * The service key for IRandomNumberGenerator. */ static readonly serviceKey: IServiceKey; constructor(serviceScope: ServiceScope); /** {@inheritDoc IRandomNumberGenerator.generate} */ generate(): number; } /** * Utility type to recursively evaluate if `Type` is within `Set`. * * @remarks Use {@link ExtractFromSet}. This type is not meant to be used by itself. * * @public */ export declare type _RecursivelyExtractFromSet = _IsNever extends true ? never : _UniqueFromSet, Type>; /* Excluded from this release type: _ResponseUtilities */ /* Excluded from this release type: RootServiceKey */ /* Excluded from this release type: _safeWindowOpen */ /** * This is a type definition for the Service. * @public */ export declare type ServiceClass = { new (serviceScope: IServiceScope): T; } | { new (serviceScope: ServiceScope): T; }; /** * This is a constructor definition for the Service isntance. * @public */ export declare type ServiceClassConstructor = (new (serviceScope: IServiceScope) => T) | (new (serviceScope: ServiceScope) => T); /** * This is a callback that is used by ServiceKey.createCustom(). * @public */ export declare type ServiceCreator = ((serviceScope: IServiceScope) => T) | ((serviceScope: ServiceScope) => T); /** * The ServiceKey is a lookup key that is used when calling {@link ServiceScope.consume} * to fetch a dependency. * * @remarks * Every service key also provides a default implementation of the dependency, which will * be automatically created in the root scope if the dependency is not found. Providing a default * implementation ensures that new dependencies can be safely introduced without inadvertently * breaking components that are loaded by an older host that does not provide the new dependency. * * @public */ export declare class ServiceKey implements IServiceKey { /** * A unique identifier for this service key. * * @remarks * This identifier is an automatically generated string that will be unique for the lifetime * of the page. Callers should not make assumptions about the formatting of this string. It is * currently based on a global counter, but this may change in the future. * * The ServiceScope uses this identifier internally as a dictionary key for finding services. * The ServiceKey is meant to be unique, even if multiple instances of the same library are * loaded on the same page, even if the same name was passed to ServiceKey.create(). * This is because each call to ServiceKey.create() could potentially provide a different * defaultCreator implementation, whereas one of the design goals of ServiceScope is that * the order in which libraries are loaded should never affect the resulting tree of scopes. */ readonly id: string; /* Excluded from this release type: _isRootService */ /** * The name of the service. * * @remarks * This name is used for logging and diagnostic purposes only. To make it unique, the * recommended convention is the package name, followed by a period, followed by the * class or interface name. * * The system does not assume that this string is unique. Instead, the {@link ServiceKey.id} * is used wherever a lookup key is needed. */ readonly name: string; /** * A callback function that constructs the default instance of this service. */ readonly defaultCreator: ServiceCreator; /** * Constructs a new ServiceKey whose default implementation will be a new instance of * a TypeScript class that accepts the standard constructor parameter. * * @remarks * If you want to specify custom constructor parameters, use {@link ServiceKey.createCustom} * instead. * * @param name - A name such as "my-package.IMyService" which should be unique across packages. * @param serviceClass - the TypeScript class that implements the service. * @returns the newly created ServiceKey */ static create(name: string, serviceClass: ServiceClass): ServiceKey; /** * Constructs a new ServiceKey whose default implementation will be obtained * by invoking the specified callback. * * @param name - A name such as "my-package.IMyService" which should be unique across packages. * @param defaultCreator - a callback that returns an object that implements the T interface * @returns the newly created service key */ static createCustom(name: string, defaultCreator: ServiceCreator): ServiceKey; /* Excluded from this release type: _generateServiceId */ protected constructor(id: string, name: string, defaultCreator: ServiceCreator); } /* Excluded from this release type: _ServiceKeys */ /** * The service locator pattern used by the SharePoint Framework. * * @remarks * ServiceScope provides a formalized way for components to register and consume dependencies * ("services"), and to enable different implementations to be registered in different scopes. * This improves modularity by decoupling components from their dependencies in an extensible way. * * For example, suppose that various components need access to an IPageManager instance. We could * simply make the PageManager a singleton (i.e. global variable), but this will not work e.g. if * we need to create a pop-up dialog that requires a second PageManager instance. A better solution * would be to add the PageManager as a constructor parameter for each component that requires it, * however then we immediately face the problem that any code that calls these constructors * also needs a PageManager parameter. In an application with many such dependencies, business * logic that ties together many subsystems would eventually pick up a constructor parameter * for every possible dependency, which is awkward. A natural solution would be to move all the * dependencies into a class with name like "ApplicationContext", and then pass this around as our * constructor parameter. This enables the PageManager to be passed to classes that need it * without cluttering the intermediary classes that don't. However, it still has a design problem * that "ApplicationContext" has hard-coded dependencies on many unrelated things. A more flexible * approach is to make it a dictionary that can look up items for consumers/providers who know the * right lookup key (i.e. ServiceKey). This is the popular "service locator" design pattern, * familiar from the SPContext API in classic SharePoint. * * ServiceScope takes this idea a step further in two important ways: First, it provides a scoping * mechanism so that e.g. if we have two different pages, they can each provide a unique PageManager * instance while still sharing other common dependencies. Secondly, it allows for a ServiceKey * to provide a default implementation of the dependency. This is important for API stability in * our modular client-side environment: For example, suppose that version 2.0 of our application * introduced a new IDiagnosticTracing interface that a version 2.0 component will expect to consume. * If the version 2.0 component gets loaded by an older 1.0 application, it would fail. We could * fix this by requiring each consumer to check for any missing dependencies and handle that case, * but it would require a lot of checks. A better solution is to ensure that a default implementation * always exists, perhaps just a trivial behavior, so that components can assume that consume() will * always return some object that implements the contract. * * Usage: ServiceScope instances are created by calling either ServiceScope.startNewRoot() or * ServiceScope.startNewChild(). They are initially in an "unfinished" state, during which provide() * can be called to register service keys, but consume() is disallowed. After ServiceScope.finish() * is called, consume() is allowed and provide() is now disallowed. These semantics ensure that * ServiceScope.consume() always returns the same result for the same key, and does not depend on * order of initialization. It also allows us to support circular dependencies without worrying * about infinite loops. (Circular dependencies are best avoided, however this is difficult to * guarantee when working with components that were contributed by various third parties without * any coordination.) To avoid mistakes, it's best to always call consume() inside a callback from * serviceScope.whenFinished(). * * @public */ export declare class ServiceScope implements IServiceScope { private _registrations; private _parent; private _pendingCallbacks; private _finished; private _autocreating; /** * Create a new root-level ServiceScope. Only root-level scopes have the ability to autocreate * default implementations of ServiceKeys. * * @returns the newly created root ServiceScope */ static startNewRoot(): ServiceScope; /** * This is a shorthand function that is equivalent to constructing a new instance of the * simpleServiceClass, then registering it by calling ServiceScope.provide(). * * @param serviceKey - the key that can be used later to consume the service * @param simpleServiceClass - the TypeScript class to be constructed * @returns a newly constructed instance of simpleServiceClass */ createAndProvide(serviceKey: IServiceKey, simpleServiceClass: ServiceClass): T; /** * This is a shorthand function that constructs the default implementation of the specified * serviceKey, and then registers it by calling ServiceScope.provide(). * * @param serviceKey - the key that can be used later to consume the service * @returns a service instance that was constructed using ServiceKey.defaultCreator */ createDefaultAndProvide(serviceKey: IServiceKey): T; /** * Consumes a service from the service scope. * * @remarks * Components should call this function to "consume" a dependency, i.e. look up the serviceKey * and return the registered service instance. If the instance cannot be found, then a default * instance will be automatically created and registered with the root ServiceScope. * * @param serviceKey - the key that was used when provide() was called to register the service * @returns the service instance */ consume(serviceKey: IServiceKey): T; /** * Completes the initialization sequence for a service scope. * * @remarks * When a ServiceScope is first started, it is in an "unfinished" state where provide() is * allowed but consume() is disallowed. After calling finish(), then consume() is allowed * but provide() is disallowed. * * This formalism prevents a number of complex situations that could lead to bugs. For example, * supposed that Scope2 is a child of Scope1, and Scope1 provides instance A1 of interface A. * If someone consumes A1 from Scope2 (via inheritance) before Scope2.provide() is called * with A2, then a subsequent call to Scope2.consume() might return a different result than * the previous call. This nondeterminism could cause unpredictable results that are * difficult to diagnose. */ finish(): void; /** * Returns the parent of the current ServiceScope, or undefined if this is a root scope. * * @returns the parent service scope */ getParent(): ServiceScope | undefined; /** * Defer an operation until after {@link ServiceScope.finish} has completed. * * @remarks * It is an error to call ServiceScope.consume() before finish() has been called. * The most reliable way to protect your component against this error is to perform the * consume() calls inside a whenFinished() callback. If the service scope is already * finished, then the callback will be executed immediately. Otherwise, it will be executed * after the scope is finished in order of callback registration * * NOTE: This is not an asynchronous callback. ServiceScope initialization is typically * inexpensive and short lived. However, the control flow often threads through numerous * constructors and base classes, which can be simplified using whenFinished(). * * @param callback - A block of code that needs to call ServiceScope.consume() */ whenFinished(callback: () => void): void; /** * Add a new service to a service scope. * * @remarks * ServiceScope.provide() is used to register an implementation of the given serviceKey * for the current scope, and an implementation of a given rootServiceKey for the root scope. * It may only be used when the ServiceScope is in an "unfinished" * state, i.e. before finish() has been called. * * @param serviceKey - the key that will later be used to consume the service * @param service - the service instance that is being registered * @returns the same object that was passed as the "service" parameter */ provide(serviceKey: IServiceKey, service: T): T; /** * Constructs a new ServiceScope that is a child of the current scope. * * @remarks * The service scopes form a tree structure, such that when consuming a service, * if the key is not explicitly provided by a child scope, the parent hierarchy * will be consulted. * * @returns the newly created root ServiceScope */ startNewChild(): ServiceScope; /* Excluded from this release type: _isFinished */ protected constructor(parent: ServiceScope | undefined); /* Excluded from this release type: _registerService */ private _processPendingCallbacks; } /** * Provides access to the application's browser session and active page. * * @public */ export declare class Session { private static _applicationId; private static _pageId; private static _clientSideApplicationId; /* Excluded from this release type: _initialize */ /* Excluded from this release type: _changePage */ /** * A unique identifier for the current instance of the client-side application. * * @remarks * A unique identifier used to correlate logging and other diagnostic information. Its lifetime * persists for the duration of the client-side application instance, i.e. it begins with the * server request that renders the page, and ends e.g. when the browser tab is closed or F5 is * pressed to reload the page. Note that if the application's router supports in-place navigation * (via the history.pushState() API), the application session persists across these transitions. */ static get applicationId(): Guid; /** * The id of the currently running application */ static get clientSideApplicationId(): string; /* Excluded from this release type: _setClientSideApplicationId */ /** * A unique identifier for the current page within the client-side application. * * @remarks * A unique identifier used to correlate logging and other diagnostic information. Whereas the * {@link Session.applicationId} tracks the entire lifetime of the client-side application instance, * the pageId tracks an individual "page" that is rendered. * * For example, suppose that the application initially loads PageA, then the user does in-place * navigation (via the history.pushState() API) to PageB, then navigates back to PageA, and finally * they close the browser tab. During this sequence, the applicationId will remain the same, however * the pageId will change on each navigation. The 3 different pageId values are used by the diagnostics * e.g. to track success/failure statistics for PageA independently of PageB. * * The concept of a page is subjective and defined by the router for a particular application. */ static get pageId(): Guid; } /* Excluded from this release type: SPError */ /** * Represents a framework event that components can subscribe to. * * @remarks * Examples of events in a web application might include: the user clicking a button, the system navigating to * another page, or an item being added/removed from an abstract collection. The SharePoint Framework * represents events using instances of the SPEvent object, one for each kind of event. The SPEvent object * is typically exposed as a property of an associated class (e.g. the button that can be clicked). * When a component is interested in an event, it calls add() to register an event handler callback that * will be invoked each time the event occurs. The handler receives an SPEventArgs parameter that may * provide additional details about what happened. This is analogous to the browser's Document Object Model * (DOM) events. The main difference is the ISPEventObserver feature, which tracks which component subscribed * to each event, and automatically unsubscribes the handler when the component is disposed. * * When an event is raised, all handlers are invoked synchronously. The order in which event handlers * are called is unspecified. The event handler callback must catch any exceptions that occur during * processing; an uncaught exception will not prevent other handlers from executing, but it will be * reported as a problem with the associated component. * * @public */ export declare class SPEvent { private _name; /* Excluded from this release type: __constructor */ /** * Registers a callback that will be invoked whenever the event occurs. * * @remarks * The same object can add multiple event handlers to the same event. Since BaseComponent implements * the ISPEventObserver interface, a web part or extension can pass itself as the observer. This will cause * the event handler to be automatically unsubscribed when the web part or extension is disposed. * * @param observer - Indicates the object that is subscribing to the event: When the object is disposed, * the event handler will be automatically removed. This object is also used for diagnostic purposes, * e.g. detecting if the event handler failed to catch an exception. * @param eventHandler - A callback function that will be invoked whenever the event occurs */ add(observer: ISPEventObserver, eventHandler: (eventArgs: TEventArgs) => void): void; /** * Unregisters a callback that was registered using add(). * * @remarks * If the event handler has already been removed, or if it was never added, then this * method has no effect. * * @param observer - This must be the same observer that was passed to the add() function. * @param eventHandler - The event handler to remove; this must be the same object instance * that was passed to the add() function. */ remove(observer: ISPEventObserver, eventHandler: (eventArgs: TEventArgs) => void): void; /* Excluded from this release type: _listenerCount */ } /** * The base class for event arguments used with the {@link SPEvent} class. * * @remarks * If certain event types need to provide additional details, they will define a * subclass of SPEventArgs. * * @public */ export declare class SPEventArgs { } /* Excluded from this release type: _SPEventManager */ /* Excluded from this release type: _SPExperiment */ /* Excluded from this release type: _SPFlight */ /* Excluded from this release type: _SPKillSwitch */ /** * Utility type to evaluate if a recursive conditional evaluation should stop. * * @remarks Use {@link ExtractFromSet}. This type is not meant to be used by itself. * @remarks If `Set` and `Current` are the same length, then all values have been recursed upon. * * @public */ export declare type _Stop = Set['length'] extends Current['length'] ? true : false; /** * Helper type to extract a string union from a type. * * @public */ export declare type StringUnion = [T] extends [string] ? string extends T ? never : T : never; /** * Operations for working with strings that contain text. * * @remarks * The utilities provided by this class are intended to be simple, small, and very * broadly applicable. * * @public */ declare class Text_2 { /** * Format a string by substituting parameters. * * @remarks * This function replaces template parameters such as `"{0}"` or `"{1}"` with the * corresponding argument. If the value is null or undefined, it will be replaced * by the word `"null"` or `"undefined"`. The format string s must not be null or * undefined. * * Usage example: * * `Text.format("hello {0}!", "world")` will return `"hello world!"` */ static format(s: string, ...values: unknown[]): string; /** * Returns the input string, with all instances of `searchValue` replaced by `replaceValue`. * * @remarks * Note that JavaScript's `string.replace()` only replaces the first match, unless a * global RegExp is provided. * * @param input - The string to be modified * @param searchValue - The value to search for * @param replaceValue - The replacement text */ static replaceAll(input: string, searchValue: string, replaceValue: string): string; /* Excluded from this release type: _getLocalizedString */ } export { Text_2 as Text } /** * This is the default implementation of {@link ITimeProvider} that simply * calls the real browser APIs. * * @public */ export declare class TimeProvider implements ITimeProvider { /** * The service key for ITimeProvider. */ static readonly serviceKey: IServiceKey; constructor(serviceScope: ServiceScope); /** {@inheritDoc ITimeProvider.getDate} */ getDate(): Date; /** {@inheritDoc ITimeProvider.getTimestamp} */ getTimestamp(): number; } /** * Helper type to convert a union to an intersection. * * @public */ export declare type UnionToIntersection = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never; /** * Utility type to evaluate if `Type1` and `Type2` are the same. * * @remarks Do not use with unions. * @remarks Use {@link ExtractFromSet}. This type is not meant to be used by itself. * * @public */ export declare type _UniqueCondition = Type1 | Type2 extends Type2 ? true : false; /** * Utility type to recursively evaluate if `Type` is within `Set`. * * @remarks Use {@link ExtractFromSet}. This type is not meant to be used by itself. * @remarks `Current` is used to track the recursion, which is why `CurrentValue` is added to `Current` after {@link _UniqueCondition} is evaluated. * * @public */ export declare type _UniqueFromSet = _UniqueCondition extends true ? CurrentValue : _ContinueRecursivelyExtractFromSet; /** * Provides features for storing and retrieving URL query parameters. * * @remarks * The URL can be server-relative, and it can also be an empty or null string. * The query parameters must start with "?" to indicate the first query parameter and * use "&" for all subsequent parameters. The class also supports fragments. * * Edge case behavior: * * Empty value (www.example.com/?test=) stores key and empty value * No equals in queryParam (www.example.com/?test) stores key and undefined value * Empty queryParam (www.example.com/?&debug=on) stores undefined key and value * Query param with only equals (www.example.com/?=&debug=on stores empty string key and value * * @privateRemarks * The design of this class was that it could split the URL out into a data structure, and the user * could add items to the data structure (TBD), and then another (TBD) function would rebuild the URL. * This weird design would ensure that e.g. if no change was made to the data structure, then the * round trip wouldn't change the characters in the URL at all, which might be useful e.g. if we're * comparing URLs. * * @deprecated Use the URLSearchParams browser API instead. The SharePoint Framework includes a * polyfill for older browsers. * @public */ export declare class UrlQueryParameterCollection { private _queryParameterList; constructor(url: string); /** * Returns the value of the first matching query parameter or undefined if the key doesn't exist. * * @remarks * Examples: * ``` * this._queryParameterList = [ * {key: TEST, value: done}, * {key: DEBUG, value: false}, * {key: TEST, value: notdone}] * getValue('TEST') ---> 'done' * getValue('debug') ---> 'false' * getValue('lost') ---> undefined * ``` * @param param - the case insensitive key for the desired query parameter value. */ getValue(param: string): string | undefined; /** * Returns the values of all of the matching query parameters or undefined if the key doesn't exist. * * @remarks * Examples: * ``` * this._queryParameterList = [ * {key: TEST, value: done}, * {key: DEBUG, value: false}, * {key: TEST, value: notdone}] * getValues('TEST') ---> ['done', 'notdone'] * getValues('debug') ---> ['false'] * getValues('lost') ---> undefined * ``` * @param param - the case insensitive key for the desired query parameter value. */ getValues(param: string): (string | undefined)[] | undefined; private _getUrlQueryParameterArray; } /* Excluded from this release type: UrlUtilities */ /** * Performs common validation tests for properties and function parameters. * * @remarks * * This class implements provides a standard way to validate properties and function parameters. * Unlike debug assertions, Validate checks are always performed and will always throw an error, * even in a production release. As such, be careful not to overuse these checks in a way * that might impact performance. * * @public */ export declare class Validate { /** * Throws an exception if the specified value is not true. * @param value - the value to check * @param variableName - the program variable name, which will be mentioned in the error message */ static isTrue(value: boolean | undefined | null, variableName: string): void; /** * Throws an exception if the specified value is null or undefined. * @param value - the value to check * @param variableName - the program variable name, which will be mentioned in the error message */ static isNotNullOrUndefined(value: unknown, variableName: string): void; /** * Throws an exception if the specified string is null, undefined, or an empty string. * @param value - the value to check * @param variableName - the program variable name, which will be mentioned in the error message */ static isNonemptyString(value: string | undefined | null, variableName: string): void; /** * Throws an exception if the specified object has been disposed. * @param value - the value to check * @param className - the class name, which will be mentioned in the error message */ static isNotDisposed(value: IDisposable, className: string): void; } /** * Represents a version number with two, three, or four parts. * * @remarks * This class represents versions that follow the string format of `MAJOR.MINOR[.PATCH[.REVISION]]` * where the MAJOR, MINOR, PATCH and REVISION parts are integers. PATCH and REVISION are optional. * Leading zero digits are allowed, but they are discarded. Missing parts are treated * as zeroes for comparisons. * * Examples: `1.0`, `1.0.0`, `1.0.0.0`, `1.01`, `01.02.03`, `001.002.003.004` * * @public */ export declare class Version { private _major; private _minor; private _patch; private _revision; /** * Test whether a string is a valid version specifier. * * @param versionString - The version string * @returns true if the versionString is a valid version specifier */ static isValid(versionString: string | undefined | null): boolean; /** * Constructs a new Version instance using the version string. An exception is thrown * if the string cannot be parsed. * * @param versionString - A version string * @returns a new Version object */ static parse(versionString: string | undefined | null): Version; /** * Attempts to parse the input string to construct a new Version object. * If the string cannot be parsed, then undefined is returned. * * @param versionString - A version string * @returns The Version object, or undefined if the string could not be parsed. */ static tryParse(versionString: string | undefined | null): Version | undefined; /** * Compares two Version objects to determine which version is newer. * * @param v1 - The first version class for comparison * @param v2 - The second version class for comparison * @returns -1 if the first input is less than the second input; * 0 if the first input is equal to the second input; * 1 if the first input is greater than the second input. */ static compare(v1: Version, v2: Version): number; /* Excluded from this release type: _tryParseSPFxVersion */ /** * Returns the first component of the version string. * * @remarks * Typically a change in the major version number indicates a compatibility * break with previous versions. */ get major(): number; /** * Returns the second component of the version string. * * @remarks * Typically a change in the minor version number indicates that new features * were added, while remaining backwards compatible with previous releases. */ get minor(): number; /** * The third number in the version string, or undefined if unspecified. * * @remarks * Typically a change in the patch version number indicates a small fix that * does not affect the compatibility contract for the library. For a .NET * System.Version object, this is referred to as the "build" number. */ get patch(): number | undefined; /** * The fourth number in the version string, or undefined if unspecified. * * @remarks * This number is not part of the Semantic Versioning (SemVer) standard used * in JavaScript, but it is used by .NET version numbers. */ get revision(): number | undefined; /** * Tests whether this version is less than (i.e. older than) the input parameter. * * @remarks * * Examples: * * ``` * 0.9.9 lessThan 1.0.0 -> true; * 2.0 lessThan 2.0.0 -> false; * 3.0 lessThan 3.0.1 -> true; * 04.01 lessThan 4.1 -> false * ``` * * @param compareWith - The version to compare with * @returns A boolean indicating if this version is less than the input parameter */ lessThan(compareWith: Version): boolean; /** * Tests whether this version is greater than (i.e. newer than) the input parameter. * * @remarks * * Examples: * * ``` * 1.0.0 greaterThan 0.0.9 -> true; * 2.0 greaterThan 2.0.0 -> false; * 3.0.1 greaterThan 3.0 -> true * ``` * * @param compareWith - The version to compare with * @returns A boolean indicating if this version is greater than the input parameter */ greaterThan(compareWith: Version): boolean; /** * Tests whether this version is equal to the input parameter. * * @remarks * * Examples: * * ``` * 1.0.0 equals 1.0.0 -> true; * 2.0.1 equals 2.0.0 -> false; * 3.0 equals 3.0.0 -> true; * 04.01 equals 4.1 -> true * ``` * * @param compareWith - The version to compare with * @returns A boolean indicating if this version is equal to the input parameter */ equals(compareWith: Version): boolean; /** * Tests whether this version satisfies the compatibility requirements of the input version, * i.e. is backwards compatible. * * @remarks * In order to satisfy the compatibility requirements, this object must have the same * major version number as the input parameter, and it must NOT be older than the * input parameter. * * Examples: * * ``` * 1.0.0 satisfies 1.0.0 -> true; * 1.1.0 satisfies 1.0.0 -> true; * 2.0.0 satisfies 1.0.0 -> false; * 1.0.0 satisfies 1.1.0 -> false * ``` * * @param compareWith - The version to compare with * @returns A boolean indicating if this version is compatible with the input parameter */ satisfies(compareWith: Version): boolean; /** * Returns a string representation of the version. * * @remarks * The value is normalized and may be different from the original string (e.g. leading zeroes * may be removed). However, the number of version parts will be unchanged. */ toString(): string; /** * WARNING: Use Version.tryParse instead of the constructor. The constructor does not do any validation. * * @param major - the major version * @param minor - the minor version * @param patch - the patch number * @param revision - the revision number */ private constructor(); } export { _VetoValues } export { }