1 | import { IDataConnector } from '@jupyterlab/statedb';
|
2 | import { JSONValue, PartialJSONValue, ReadonlyJSONObject, ReadonlyPartialJSONObject, ReadonlyPartialJSONValue } from '@lumino/coreutils';
|
3 | import { IDisposable } from '@lumino/disposable';
|
4 | import { ISignal } from '@lumino/signaling';
|
5 | import { ISettingRegistry } from './tokens';
|
6 | /**
|
7 | * An implementation of a schema validator.
|
8 | */
|
9 | export interface ISchemaValidator {
|
10 | /**
|
11 | * Validate a plugin's schema and user data; populate the `composite` data.
|
12 | *
|
13 | * @param plugin - The plugin being validated. Its `composite` data will be
|
14 | * populated by reference.
|
15 | *
|
16 | * @param populate - Whether plugin data should be populated, defaults to
|
17 | * `true`.
|
18 | *
|
19 | * @returns A list of errors if either the schema or data fail to validate or
|
20 | * `null` if there are no errors.
|
21 | */
|
22 | validateData(plugin: ISettingRegistry.IPlugin, populate?: boolean): ISchemaValidator.IError[] | null;
|
23 | }
|
24 | /**
|
25 | * A namespace for schema validator interfaces.
|
26 | */
|
27 | export declare namespace ISchemaValidator {
|
28 | /**
|
29 | * A schema validation error definition.
|
30 | */
|
31 | interface IError {
|
32 | /**
|
33 | * The keyword whose validation failed.
|
34 | */
|
35 | keyword: string | string[];
|
36 | /**
|
37 | * The error message.
|
38 | */
|
39 | message?: string;
|
40 | /**
|
41 | * Optional parameter metadata that might be included in an error.
|
42 | */
|
43 | params?: ReadonlyJSONObject;
|
44 | /**
|
45 | * The path in the schema where the error occurred.
|
46 | */
|
47 | schemaPath: string;
|
48 | /**
|
49 | * @todo handle new fields from ajv8
|
50 | **/
|
51 | schema?: unknown;
|
52 | /**
|
53 | * @todo handle new fields from ajv8
|
54 | **/
|
55 | instancePath: string;
|
56 | /**
|
57 | * @todo handle new fields from ajv8
|
58 | **/
|
59 | propertyName?: string;
|
60 | /**
|
61 | * @todo handle new fields from ajv8
|
62 | **/
|
63 | data?: unknown;
|
64 | /**
|
65 | * @todo handle new fields from ajv8
|
66 | **/
|
67 | parentSchema?: unknown;
|
68 | }
|
69 | }
|
70 | /**
|
71 | * The default implementation of a schema validator.
|
72 | */
|
73 | export declare class DefaultSchemaValidator implements ISchemaValidator {
|
74 | /**
|
75 | * Instantiate a schema validator.
|
76 | */
|
77 | constructor();
|
78 | /**
|
79 | * Validate a plugin's schema and user data; populate the `composite` data.
|
80 | *
|
81 | * @param plugin - The plugin being validated. Its `composite` data will be
|
82 | * populated by reference.
|
83 | *
|
84 | * @param populate - Whether plugin data should be populated, defaults to
|
85 | * `true`.
|
86 | *
|
87 | * @returns A list of errors if either the schema or data fail to validate or
|
88 | * `null` if there are no errors.
|
89 | */
|
90 | validateData(plugin: ISettingRegistry.IPlugin, populate?: boolean): ISchemaValidator.IError[] | null;
|
91 | /**
|
92 | * Add a schema to the validator.
|
93 | *
|
94 | * @param plugin - The plugin ID.
|
95 | *
|
96 | * @param schema - The schema being added.
|
97 | *
|
98 | * @returns A list of errors if the schema fails to validate or `null` if there
|
99 | * are no errors.
|
100 | *
|
101 | * #### Notes
|
102 | * It is safe to call this function multiple times with the same plugin name.
|
103 | */
|
104 | private _addSchema;
|
105 | private _composer;
|
106 | private _validator;
|
107 | }
|
108 | /**
|
109 | * The default concrete implementation of a setting registry.
|
110 | */
|
111 | export declare class SettingRegistry implements ISettingRegistry {
|
112 | /**
|
113 | * Create a new setting registry.
|
114 | */
|
115 | constructor(options: SettingRegistry.IOptions);
|
116 | /**
|
117 | * The data connector used by the setting registry.
|
118 | */
|
119 | readonly connector: IDataConnector<ISettingRegistry.IPlugin, string, string>;
|
120 | /**
|
121 | * The schema of the setting registry.
|
122 | */
|
123 | readonly schema: ISettingRegistry.ISchema;
|
124 | /**
|
125 | * The schema validator used by the setting registry.
|
126 | */
|
127 | readonly validator: ISchemaValidator;
|
128 | /**
|
129 | * A signal that emits the name of a plugin when its settings change.
|
130 | */
|
131 | get pluginChanged(): ISignal<this, string>;
|
132 | /**
|
133 | * The collection of setting registry plugins.
|
134 | */
|
135 | readonly plugins: {
|
136 | [name: string]: ISettingRegistry.IPlugin;
|
137 | };
|
138 | /**
|
139 | * Get an individual setting.
|
140 | *
|
141 | * @param plugin - The name of the plugin whose settings are being retrieved.
|
142 | *
|
143 | * @param key - The name of the setting being retrieved.
|
144 | *
|
145 | * @returns A promise that resolves when the setting is retrieved.
|
146 | */
|
147 | get(plugin: string, key: string): Promise<{
|
148 | composite: PartialJSONValue | undefined;
|
149 | user: PartialJSONValue | undefined;
|
150 | }>;
|
151 | /**
|
152 | * Load a plugin's settings into the setting registry.
|
153 | *
|
154 | * @param plugin - The name of the plugin whose settings are being loaded.
|
155 | *
|
156 | * @param forceTransform - An optional parameter to force replay the transforms methods.
|
157 | *
|
158 | * @returns A promise that resolves with a plugin settings object or rejects
|
159 | * if the plugin is not found.
|
160 | */
|
161 | load(plugin: string, forceTransform?: boolean): Promise<ISettingRegistry.ISettings>;
|
162 | /**
|
163 | * Reload a plugin's settings into the registry even if they already exist.
|
164 | *
|
165 | * @param plugin - The name of the plugin whose settings are being reloaded.
|
166 | *
|
167 | * @returns A promise that resolves with a plugin settings object or rejects
|
168 | * with a list of `ISchemaValidator.IError` objects if it fails.
|
169 | */
|
170 | reload(plugin: string): Promise<ISettingRegistry.ISettings>;
|
171 | /**
|
172 | * Remove a single setting in the registry.
|
173 | *
|
174 | * @param plugin - The name of the plugin whose setting is being removed.
|
175 | *
|
176 | * @param key - The name of the setting being removed.
|
177 | *
|
178 | * @returns A promise that resolves when the setting is removed.
|
179 | */
|
180 | remove(plugin: string, key: string): Promise<void>;
|
181 | /**
|
182 | * Set a single setting in the registry.
|
183 | *
|
184 | * @param plugin - The name of the plugin whose setting is being set.
|
185 | *
|
186 | * @param key - The name of the setting being set.
|
187 | *
|
188 | * @param value - The value of the setting being set.
|
189 | *
|
190 | * @returns A promise that resolves when the setting has been saved.
|
191 | *
|
192 | */
|
193 | set(plugin: string, key: string, value: JSONValue): Promise<void>;
|
194 | /**
|
195 | * Register a plugin transform function to act on a specific plugin.
|
196 | *
|
197 | * @param plugin - The name of the plugin whose settings are transformed.
|
198 | *
|
199 | * @param transforms - The transform functions applied to the plugin.
|
200 | *
|
201 | * @returns A disposable that removes the transforms from the registry.
|
202 | *
|
203 | * #### Notes
|
204 | * - `compose` transformations: The registry automatically overwrites a
|
205 | * plugin's default values with user overrides, but a plugin may instead wish
|
206 | * to merge values. This behavior can be accomplished in a `compose`
|
207 | * transformation.
|
208 | * - `fetch` transformations: The registry uses the plugin data that is
|
209 | * fetched from its connector. If a plugin wants to override, e.g. to update
|
210 | * its schema with dynamic defaults, a `fetch` transformation can be applied.
|
211 | */
|
212 | transform(plugin: string, transforms: {
|
213 | [phase in ISettingRegistry.IPlugin.Phase]?: ISettingRegistry.IPlugin.Transform;
|
214 | }): IDisposable;
|
215 | /**
|
216 | * Upload a plugin's settings.
|
217 | *
|
218 | * @param plugin - The name of the plugin whose settings are being set.
|
219 | *
|
220 | * @param raw - The raw plugin settings being uploaded.
|
221 | *
|
222 | * @returns A promise that resolves when the settings have been saved.
|
223 | */
|
224 | upload(plugin: string, raw: string): Promise<void>;
|
225 | /**
|
226 | * Load a plugin into the registry.
|
227 | */
|
228 | private _load;
|
229 | /**
|
230 | * Preload a list of plugins and fail gracefully.
|
231 | */
|
232 | private _preload;
|
233 | /**
|
234 | * Save a plugin in the registry.
|
235 | */
|
236 | private _save;
|
237 | /**
|
238 | * Transform the plugin if necessary.
|
239 | */
|
240 | private _transform;
|
241 | /**
|
242 | * Validate and preload a plugin, compose the `composite` data.
|
243 | */
|
244 | private _validate;
|
245 | private _pluginChanged;
|
246 | private _ready;
|
247 | private _transformers;
|
248 | private _unloadedPlugins;
|
249 | }
|
250 | /**
|
251 | * Base settings specified by a JSON schema.
|
252 | */
|
253 | export declare class BaseSettings<T extends ISettingRegistry.IProperty = ISettingRegistry.IProperty> {
|
254 | constructor(options: {
|
255 | schema: T;
|
256 | });
|
257 | /**
|
258 | * The plugin's schema.
|
259 | */
|
260 | get schema(): T;
|
261 | /**
|
262 | * Checks if any fields are different from the default value.
|
263 | */
|
264 | isDefault(user: ReadonlyPartialJSONObject): boolean;
|
265 | /**
|
266 | * Calculate the default value of a setting by iterating through the schema.
|
267 | *
|
268 | * @param key - The name of the setting whose default value is calculated.
|
269 | *
|
270 | * @returns A calculated default JSON value for a specific setting.
|
271 | */
|
272 | default(key?: string): PartialJSONValue | undefined;
|
273 | private _schema;
|
274 | }
|
275 | /**
|
276 | * A manager for a specific plugin's settings.
|
277 | */
|
278 | export declare class Settings extends BaseSettings<ISettingRegistry.ISchema> implements ISettingRegistry.ISettings {
|
279 | /**
|
280 | * Instantiate a new plugin settings manager.
|
281 | */
|
282 | constructor(options: Settings.IOptions);
|
283 | /**
|
284 | * The plugin name.
|
285 | */
|
286 | readonly id: string;
|
287 | /**
|
288 | * The setting registry instance used as a back-end for these settings.
|
289 | */
|
290 | readonly registry: ISettingRegistry;
|
291 | /**
|
292 | * A signal that emits when the plugin's settings have changed.
|
293 | */
|
294 | get changed(): ISignal<this, void>;
|
295 | /**
|
296 | * The composite of user settings and extension defaults.
|
297 | */
|
298 | get composite(): ReadonlyPartialJSONObject;
|
299 | /**
|
300 | * Test whether the plugin settings manager disposed.
|
301 | */
|
302 | get isDisposed(): boolean;
|
303 | get plugin(): ISettingRegistry.IPlugin;
|
304 | /**
|
305 | * The plugin settings raw text value.
|
306 | */
|
307 | get raw(): string;
|
308 | /**
|
309 | * Whether the settings have been modified by the user or not.
|
310 | */
|
311 | get isModified(): boolean;
|
312 | /**
|
313 | * The user settings.
|
314 | */
|
315 | get user(): ReadonlyPartialJSONObject;
|
316 | /**
|
317 | * The published version of the NPM package containing these settings.
|
318 | */
|
319 | get version(): string;
|
320 | /**
|
321 | * Return the defaults in a commented JSON format.
|
322 | */
|
323 | annotatedDefaults(): string;
|
324 | /**
|
325 | * Dispose of the plugin settings resources.
|
326 | */
|
327 | dispose(): void;
|
328 | /**
|
329 | * Get an individual setting.
|
330 | *
|
331 | * @param key - The name of the setting being retrieved.
|
332 | *
|
333 | * @returns The setting value.
|
334 | *
|
335 | * #### Notes
|
336 | * This method returns synchronously because it uses a cached copy of the
|
337 | * plugin settings that is synchronized with the registry.
|
338 | */
|
339 | get(key: string): {
|
340 | composite: ReadonlyPartialJSONValue | undefined;
|
341 | user: ReadonlyPartialJSONValue | undefined;
|
342 | };
|
343 | /**
|
344 | * Remove a single setting.
|
345 | *
|
346 | * @param key - The name of the setting being removed.
|
347 | *
|
348 | * @returns A promise that resolves when the setting is removed.
|
349 | *
|
350 | * #### Notes
|
351 | * This function is asynchronous because it writes to the setting registry.
|
352 | */
|
353 | remove(key: string): Promise<void>;
|
354 | /**
|
355 | * Save all of the plugin's user settings at once.
|
356 | */
|
357 | save(raw: string): Promise<void>;
|
358 | /**
|
359 | * Set a single setting.
|
360 | *
|
361 | * @param key - The name of the setting being set.
|
362 | *
|
363 | * @param value - The value of the setting.
|
364 | *
|
365 | * @returns A promise that resolves when the setting has been saved.
|
366 | *
|
367 | * #### Notes
|
368 | * This function is asynchronous because it writes to the setting registry.
|
369 | */
|
370 | set(key: string, value: JSONValue): Promise<void>;
|
371 | /**
|
372 | * Validates raw settings with comments.
|
373 | *
|
374 | * @param raw - The JSON with comments string being validated.
|
375 | *
|
376 | * @returns A list of errors or `null` if valid.
|
377 | */
|
378 | validate(raw: string): ISchemaValidator.IError[] | null;
|
379 | /**
|
380 | * Handle plugin changes in the setting registry.
|
381 | */
|
382 | private _onPluginChanged;
|
383 | private _changed;
|
384 | private _isDisposed;
|
385 | }
|
386 | /**
|
387 | * A namespace for `SettingRegistry` statics.
|
388 | */
|
389 | export declare namespace SettingRegistry {
|
390 | /**
|
391 | * The instantiation options for a setting registry
|
392 | */
|
393 | interface IOptions {
|
394 | /**
|
395 | * The data connector used by the setting registry.
|
396 | */
|
397 | connector: IDataConnector<ISettingRegistry.IPlugin, string>;
|
398 | /**
|
399 | * Preloaded plugin data to populate the setting registry.
|
400 | */
|
401 | plugins?: ISettingRegistry.IPlugin[];
|
402 | /**
|
403 | * The number of milliseconds before a `load()` call to the registry waits
|
404 | * before timing out if it requires a transformation that has not been
|
405 | * registered.
|
406 | *
|
407 | * #### Notes
|
408 | * The default value is 7000.
|
409 | */
|
410 | timeout?: number;
|
411 | /**
|
412 | * The validator used to enforce the settings JSON schema.
|
413 | */
|
414 | validator?: ISchemaValidator;
|
415 | }
|
416 | /**
|
417 | * Reconcile the menus.
|
418 | *
|
419 | * @param reference The reference list of menus.
|
420 | * @param addition The list of menus to add.
|
421 | * @param warn Warn if the command items are duplicated within the same menu.
|
422 | * @returns The reconciled list of menus.
|
423 | */
|
424 | function reconcileMenus(reference: ISettingRegistry.IMenu[] | null, addition: ISettingRegistry.IMenu[] | null, warn?: boolean, addNewItems?: boolean): ISettingRegistry.IMenu[];
|
425 | /**
|
426 | * Merge two set of menu items.
|
427 | *
|
428 | * @param reference Reference set of menu items
|
429 | * @param addition New items to add
|
430 | * @param warn Whether to warn if item is duplicated; default to false
|
431 | * @returns The merged set of items
|
432 | */
|
433 | function reconcileItems<T extends ISettingRegistry.IMenuItem>(reference?: T[], addition?: T[], warn?: boolean, addNewItems?: boolean): T[] | undefined;
|
434 | /**
|
435 | * Remove disabled entries from menu items
|
436 | *
|
437 | * @param items Menu items
|
438 | * @returns Filtered menu items
|
439 | */
|
440 | function filterDisabledItems<T extends ISettingRegistry.IMenuItem>(items: T[]): T[];
|
441 | /**
|
442 | * Reconcile default and user shortcuts and return the composite list.
|
443 | *
|
444 | * @param defaults - The list of default shortcuts.
|
445 | *
|
446 | * @param user - The list of user shortcut overrides and additions.
|
447 | *
|
448 | * @returns A loadable list of shortcuts (omitting disabled and overridden).
|
449 | */
|
450 | function reconcileShortcuts(defaults: ISettingRegistry.IShortcut[], user: ISettingRegistry.IShortcut[]): ISettingRegistry.IShortcut[];
|
451 | /**
|
452 | * Merge two set of toolbar items.
|
453 | *
|
454 | * @param reference Reference set of toolbar items
|
455 | * @param addition New items to add
|
456 | * @param warn Whether to warn if item is duplicated; default to false
|
457 | * @returns The merged set of items
|
458 | */
|
459 | function reconcileToolbarItems(reference?: ISettingRegistry.IToolbarItem[], addition?: ISettingRegistry.IToolbarItem[], warn?: boolean): ISettingRegistry.IToolbarItem[] | undefined;
|
460 | }
|
461 | /**
|
462 | * A namespace for `Settings` statics.
|
463 | */
|
464 | export declare namespace Settings {
|
465 | /**
|
466 | * The instantiation options for a `Settings` object.
|
467 | */
|
468 | interface IOptions {
|
469 | /**
|
470 | * The setting values for a plugin.
|
471 | */
|
472 | plugin: ISettingRegistry.IPlugin;
|
473 | /**
|
474 | * The system registry instance used by the settings manager.
|
475 | */
|
476 | registry: ISettingRegistry;
|
477 | }
|
478 | }
|