@theia/core
Version:
Theia is a cloud & desktop IDE framework implemented in TypeScript.
271 lines • 15 kB
TypeScript
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