UNPKG

@theia/core

Version:

Theia is a cloud & desktop IDE framework implemented in TypeScript.

271 lines • 15 kB
import { JSONValue } from '@lumino/coreutils'; import { Disposable, DisposableCollection } from '../disposable.js'; import { Emitter, Event } from '../event.js'; import { Deferred } from '../promise-util.js'; import URI from '../uri.js'; import { PreferenceLanguageOverrideService } from './preference-language-override-service.js'; import { PreferenceProvider, PreferenceProviderDataChange, PreferenceProviderDataChanges, PreferenceResolveResult } from './preference-provider.js'; import { PreferenceSchemaService } from './preference-schema.js'; import { PreferenceScope } from './preference-scope.js'; import { PreferenceConfigurations } from './preference-configurations.js'; import { ILogger } from '../logger.js'; type AtLeastOneKey<T> = { [K in keyof T]: Pick<T, K> & Partial<Omit<T, K>>; }[keyof T]; interface PreferenceGetOptionsRaw<T> { /** Value to return when no stored value exists for the preference. */ fallback: T | undefined; /** URI of the resource for which to retrieve the preference. */ resource: string | undefined; /** Language-override identifier (e.g. `'typescript'`). */ override: string | undefined; } /** * Options for {@link PreferenceService.get()}. At least one of the keys has to be present. */ export type PreferenceGetOptions<T> = AtLeastOneKey<PreferenceGetOptionsRaw<T>>; /** * Representation of a preference change. A preference value can be set to `undefined` for a specific scope. * This means that the value from a more general scope will be used. */ export interface PreferenceChange { readonly preferenceName: string; readonly scope: PreferenceScope; /** * URIs of the scopes in which this change applies. */ readonly domain?: string[]; /** * Tests wether the given resource is affected by the preference change. * @param resourceUri the uri of the resource to test. */ affects(resourceUri?: string, overrideIdentifier?: string): boolean; readonly affectedOverrides: readonly string[]; } export declare class PreferenceChangeImpl implements PreferenceChange { readonly affectedOverrides: readonly string[]; protected readonly change: PreferenceProviderDataChange; constructor(change: PreferenceProviderDataChange, affectedOverrides: readonly string[]); get preferenceName(): string; get scope(): PreferenceScope; get domain(): string[] | undefined; affects(resourceUri?: string, overrideIdentifier?: string): boolean; } export type PreferenceChanges = PreferenceChange[]; export declare const PreferenceService: unique symbol; /** * Service to manage preferences including, among others, getting and setting preference values as well * as listening to preference changes. * * Depending on your use case you might also want to look at {@link createPreferenceProxy} with which * you can easily create a typesafe schema-based interface for your preferences. Internally the proxy * uses the PreferenceService so both approaches are compatible. */ export interface PreferenceService extends Disposable { /** * Promise indicating whether the service successfully initialized. */ readonly ready: Promise<void>; /** * Indicates whether the service has successfully initialized. Will be `true` when {@link PreferenceService.ready the `ready` Promise} resolves. */ readonly isReady: boolean; /** * Retrieve the stored value for the given preference. * * @param preferenceName the preference identifier. * @param options optional lookup options. * - `fallback` – value to return when no stored value exists. * - `resource` – URI of the resource for which the preference is stored (enables per-resource values, e.g. `files.encoding`). * - `override` – language-override identifier (e.g. `'typescript'`). * * @returns the stored value when it exists, otherwise `options.fallback` (or `undefined` when no fallback is given). */ get(preferenceName: string, defaultValue: string): string; get(preferenceName: string, defaultValue: number): number; get(preferenceName: string, defaultValue: boolean): boolean; get<T extends string | number | boolean>(preferenceName: string, defaultValue: T): T; get<T extends unknown[]>(preferenceName: string, defaultValue: T): T; get<T>(preferenceName: string, options: PreferenceGetOptions<T> & { fallback: T; }): T; get<T>(preferenceName: string, options?: PreferenceGetOptions<T>): T | undefined; /** * Sets the given preference to the given value. * * @param preferenceName the preference identifier. * @param value the new value of the preference. * @param scope the scope for which the value shall be set, i.e. user, workspace etc. * When the folder scope is specified a resourceUri must be provided. * @param resourceUri the uri of the resource for which the preference is stored. This used to store * a potentially different value for the same preference for different resources, for example `files.encoding`. * @param overrideIdentifier the identifier of the override to use. * * @returns a promise which resolves to `undefined` when setting the preference was successful. Otherwise it rejects * with an error. */ set(preferenceName: string, value: any, scope?: PreferenceScope, resourceUri?: string, overrideIdentifier?: string): Promise<void>; /** * Determines and applies the changes necessary to apply `value` to either the `resourceUri` supplied or the active session. * If there is no setting for the `preferenceName`, the change will be applied in user scope. * If there is a setting conflicting with the specified `value`, the change will be applied in the most specific scope with a conflicting value. * * @param preferenceName the identifier of the preference to modify. * @param value the value to which to set the preference. `undefined` will reset the preference to its default value. * @param resourceUri the uri of the resource to which the change is to apply. If none is provided, folder scope will be ignored. * @param overrideIdentifier the identifier of the override to use. */ updateValue(preferenceName: string, value: any, resourceUri?: string, overrideIdentifier?: string): Promise<void>; /** * Registers a callback which will be called whenever a preference is changed. */ onPreferenceChanged: Event<PreferenceChange>; /** * Registers a callback which will be called whenever one or more preferences are changed. */ onPreferencesChanged: Event<PreferenceChanges>; /** * Retrieve the stored value for the given preference and resourceUri in all available scopes. * * @param preferenceName the preference identifier. * @param resourceUri the uri of the resource for which the preference is stored. * @param overrideIdentifier the identifier of the override to use. * Values for the override are returned where defined, values of the base preference otherwise. * * @return an object containing the value of the given preference for all scopes. */ inspect<T extends JSONValue>(preferenceName: string, resourceUri?: string, overrideIdentifier?: string): PreferenceInspection<T> | undefined; /** * For behavior, see {@link PreferenceService.inspect}. * * @returns the value in the scope specified. */ inspectInScope<T extends JSONValue>(preferenceName: string, scope: PreferenceScope, resourceUri?: string, overrideIdentifier?: string): T | undefined; /** * Retrieve the stored value for the given preference and resourceUri. * * @param preferenceName the preference identifier. * @param defaultValue the value to return when no value for the given preference is stored. * @param resourceUri the uri of the resource for which the preference is stored. This used to retrieve * a potentially different value for the same preference for different resources, for example `files.encoding`. * @param overrideIdentifier the identifier of the override to use. * * @returns an object containing the value stored for the given preference and resourceUri when it exists, * otherwise the given default value. If determinable the object will also contain the uri of the configuration * resource in which the preference was stored. */ resolve<T>(preferenceName: string, defaultValue?: T, resourceUri?: string, overrideIdentifier?: string): PreferenceResolveResult<T>; /** * Returns the uri of the configuration resource for the given scope and optional resource uri. * * @param scope the PreferenceScope to query for. * @param resourceUri the optional uri of the resource-specific preference handling * @param sectionName the optional preference section to query for. * * @returns the uri of the configuration resource for the given scope and optional resource uri it it exists, * `undefined` otherwise. */ getConfigUri(scope: PreferenceScope, resourceUri?: string, sectionName?: string): URI | undefined; } /** * Return type of the {@link PreferenceService.inspect} call. */ export interface PreferenceInspection<T = JSONValue> { /** * The preference identifier. */ preferenceName: string; /** * Value in default scope. */ defaultValue: T | undefined; /** * Value in user scope. */ globalValue: T | undefined; /** * Value in workspace scope. */ workspaceValue: T | undefined; /** * Value in folder scope. */ workspaceFolderValue: T | undefined; /** * Value in session scope (in-memory, set via `--session-preference`). */ sessionValue?: T | undefined; /** * The value that is active, i.e. the value set in the lowest scope available. */ value: T | undefined; } export type PreferenceInspectionScope = keyof Omit<PreferenceInspection<unknown>, 'preferenceName'>; /** * We cannot load providers directly in the case if they depend on `PreferenceService` somehow. * It allows to load them lazily after DI is configured. */ export declare const PreferenceProviderProvider: unique symbol; export type PreferenceProviderProvider = (scope: PreferenceScope, uri?: URI) => PreferenceProvider | undefined; export declare class PreferenceServiceImpl implements PreferenceService { protected readonly onPreferenceChangedEmitter: Emitter<PreferenceChange>; readonly onPreferenceChanged: Event<PreferenceChange>; protected readonly onPreferencesChangedEmitter: Emitter<PreferenceChanges>; readonly onPreferencesChanged: Event<PreferenceChanges>; protected readonly toDispose: DisposableCollection; protected readonly schemaService: PreferenceSchemaService; protected readonly providerProvider: PreferenceProviderProvider; protected readonly configurations: PreferenceConfigurations; protected readonly preferenceOverrideService: PreferenceLanguageOverrideService; protected readonly logger: ILogger; protected readonly preferenceProviders: Map<PreferenceScope, PreferenceProvider>; protected initializeProviders(): Promise<void>; protected init(): void; dispose(): void; protected readonly _ready: Deferred<void>; get ready(): Promise<void>; protected _isReady: boolean; get isReady(): boolean; protected getAffectedOverrides(change: PreferenceProviderDataChange): string[]; protected reconcilePreferences(changes: PreferenceProviderDataChanges): void; protected getProvider(scope: PreferenceScope): PreferenceProvider | undefined; has(preferenceName: string, resourceUri?: string, overrideIdentifier?: string): boolean; get(preferenceName: string, defaultValue: string): string; get(preferenceName: string, defaultValue: number): number; get(preferenceName: string, defaultValue: boolean): boolean; get<T extends string | number | boolean>(preferenceName: string, defaultValue: T): T; get<T extends unknown[]>(preferenceName: string, defaultValue: T): T; get<T>(preferenceName: string, options: PreferenceGetOptions<T> & { fallback: T; }): T; get<T>(preferenceName: string, options?: PreferenceGetOptions<T>): T | undefined; resolve<T>(preferenceName: string, defaultValue?: T, resourceUri?: string, overrideIdentifier?: string): PreferenceResolveResult<T>; set(preferenceName: string, value: any, scope: PreferenceScope | undefined, resourceUri?: string, overrideIdentifier?: string): Promise<void>; /** * When a preference is written to a persistent scope, drop any in-memory session * override (set via `--session-preference`) for the same key so that the explicit * change takes effect for the remainder of the session. Without this, the session * scope would keep shadowing the user's change because it has higher precedence. * * Note: this fires for any write to a persistent scope, including programmatic * writes from extensions. Extensions that race with startup CLI overrides will * therefore clear them. This is intentional: a programmatic write is "explicit" * from the preference system's point of view, but consumers should be aware. * * Session preferences are global (no per-resource scoping), so `resourceUri` is * not threaded through. */ protected evictSessionOverride(preferenceName: string, writtenScope: PreferenceScope, overrideIdentifier?: string): Promise<void>; inspect<T extends JSONValue>(preferenceName: string, resourceUri?: string, overrideIdentifier?: string): PreferenceInspection<T> | undefined; inspectInScope<T extends JSONValue>(preferenceName: string, scope: PreferenceScope, resourceUri?: string, overrideIdentifier?: string): T | undefined; protected getScopedValueFromInspection<T>(inspection: PreferenceInspection<T>, scope: PreferenceScope): T | undefined; updateValue(preferenceName: string, value: any, resourceUri?: string, overrideIdentifier?: string): Promise<void>; protected getScopesToChange(inspection: PreferenceInspection<any>, intendedValue: any): PreferenceScope[]; protected doHas(preferenceName: string, resourceUri?: string, overrideIdentifier?: string): boolean; protected doInspectInScope<T>(preferenceName: string, scope: PreferenceScope, resourceUri?: string, overrideIdentifier?: string): T | undefined; protected doGet<T>(preferenceName: string, defaultValue?: T, resourceUri?: string, overrideIdentifier?: string): T | undefined; protected doResolve<T>(preferenceName: string, defaultValue?: T, resourceUri?: string, overrideIdentifier?: string): PreferenceResolveResult<T>; getConfigUri(scope: PreferenceScope, resourceUri?: string, sectionName?: string): URI | undefined; } export {}; //# sourceMappingURL=preference-service.d.ts.map