@jupyterlite/settings 0.2.2 → 0.3.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupyterlite/settings",
-  "version": "0.2.2",
+  "version": "0.3.0-alpha.0",
   "description": "JupyterLite - Settings",
   "homepage": "https://github.com/jupyterlite/jupyterlite",
   "bugs": {
@@ -27,7 +27,8 @@
     "lib/*.js.map",
     "lib/*.js",
     "style/*.css",
-    "style/index.js"
+    "style/index.js",
+    "src/**/*.{ts,tsx}"
   ],
   "scripts": {
     "build": "tsc -b",
@@ -42,9 +43,9 @@
     "watch": "tsc -b --watch"
   },
   "dependencies": {
-    "@jupyterlab/coreutils": "~6.0.9",
-    "@jupyterlab/settingregistry": "~4.0.9",
-    "@jupyterlite/localforage": "^0.2.2",
+    "@jupyterlab/coreutils": "~6.1.1",
+    "@jupyterlab/settingregistry": "~4.1.1",
+    "@jupyterlite/localforage": "^0.3.0-alpha.0",
     "@lumino/coreutils": "^2.1.2",
     "json5": "^2.2.0",
     "localforage": "^1.9.0"
@@ -52,12 +53,12 @@
   "devDependencies": {
     "@babel/core": "^7.11.6",
     "@babel/preset-env": "^7.12.1",
-    "@jupyterlab/testutils": "~4.0.9",
+    "@jupyterlab/testutils": "~4.1.1",
     "@types/jest": "^29.5.3",
     "jest": "^29.6.2",
     "rimraf": "~5.0.1",
     "ts-jest": "^29.1.1",
-    "typescript": "~5.0.4"
+    "typescript": "~5.1.6"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+export * from './settings';
+export * from './tokens';

package/src/settings.ts

@@ -0,0 +1,195 @@
+import { PageConfig, URLExt } from '@jupyterlab/coreutils';
+
+import { PromiseDelegate } from '@lumino/coreutils';
+
+import * as json5 from 'json5';
+
+import type localforage from 'localforage';
+
+import { IPlugin, ISettings, SettingsFile } from './tokens';
+
+/**
+ * The name of the local storage.
+ */
+const DEFAULT_STORAGE_NAME = 'JupyterLite Storage';
+
+/**
+ * A class to handle requests to /api/settings
+ */
+export class Settings implements ISettings {
+  constructor(options: Settings.IOptions) {
+    this._localforage = options.localforage;
+    this._storageName = options.storageName || DEFAULT_STORAGE_NAME;
+    this._storageDrivers = options.storageDrivers || null;
+
+    this._ready = new PromiseDelegate();
+  }
+
+  /**
+   * A promise that resolves when the settings storage is fully initialized
+   */
+  get ready(): Promise<void> {
+    return this._ready.promise;
+  }
+
+  /**
+   * A lazy reference to initialized storage
+   */
+  protected get storage(): Promise<LocalForage> {
+    return this.ready.then(() => this._storage as LocalForage);
+  }
+
+  /**
+   * Finish any initialization after server has started and all extensions are applied.
+   */
+  async initialize() {
+    await this.initStorage();
+    this._ready.resolve(void 0);
+  }
+
+  /**
+   * Prepare the storage
+   */
+  protected async initStorage() {
+    this._storage = this.defaultSettingsStorage();
+  }
+
+  /**
+   * Get default options for localForage instances
+   */
+  protected get defaultStorageOptions(): LocalForageOptions {
+    const driver = this._storageDrivers?.length ? this._storageDrivers : null;
+    return {
+      version: 1,
+      name: this._storageName,
+      ...(driver ? { driver } : {}),
+    };
+  }
+
+  /**
+   * Create a settings store.
+   */
+  protected defaultSettingsStorage(): LocalForage {
+    return this._localforage.createInstance({
+      description: 'Offline Storage for Settings',
+      storeName: 'settings',
+      ...this.defaultStorageOptions,
+    });
+  }
+
+  /**
+   * Get settings by plugin id
+   *
+   * @param pluginId the id of the plugin
+   *
+   */
+  async get(pluginId: string): Promise<IPlugin | undefined> {
+    const all = await this.getAll();
+    const settings = all.settings as IPlugin[];
+    const setting = settings.find((setting: IPlugin) => {
+      return setting.id === pluginId;
+    });
+    return setting;
+  }
+
+  /**
+   * Get all the settings
+   */
+  async getAll(): Promise<{ settings: IPlugin[] }> {
+    const allCore = await this._getAll('all.json');
+    let allFederated: IPlugin[] = [];
+    try {
+      allFederated = await this._getAll('all_federated.json');
+    } catch {
+      // handle the case where there is no federated extension
+    }
+
+    // JupyterLab 4 expects all settings to be returned in one go
+    // so append the settings from federated plugins to the core ones
+    const all = allCore.concat(allFederated);
+
+    // return existing user settings if they exist
+    const storage = await this.storage;
+    const settings = await Promise.all(
+      all.map(async (plugin) => {
+        const { id } = plugin;
+        const raw = ((await storage.getItem(id)) as string) ?? plugin.raw;
+        return {
+          ...Private.override(plugin),
+          raw,
+          settings: json5.parse(raw),
+        };
+      }),
+    );
+    return { settings };
+  }
+
+  /**
+   * Save settings for a given plugin id
+   *
+   * @param pluginId The id of the plugin
+   * @param raw The raw settings
+   *
+   */
+  async save(pluginId: string, raw: string): Promise<void> {
+    await (await this.storage).setItem(pluginId, raw);
+  }
+
+  /**
+   * Get all the settings for core or federated plugins
+   */
+  private async _getAll(file: SettingsFile): Promise<IPlugin[]> {
+    const settingsUrl = PageConfig.getOption('settingsUrl') ?? '/';
+    const all = (await (
+      await fetch(URLExt.join(settingsUrl, file))
+    ).json()) as IPlugin[];
+    return all;
+  }
+
+  private _storageName: string = DEFAULT_STORAGE_NAME;
+  private _storageDrivers: string[] | null = null;
+  private _storage: LocalForage | undefined;
+  private _localforage: typeof localforage;
+  private _ready: PromiseDelegate<void>;
+}
+
+/**
+ * A namespace for settings metadata.
+ */
+export namespace Settings {
+  /**
+   * Initialization options for settings.
+   */
+  export interface IOptions {
+    localforage: typeof localforage;
+    storageName?: string | null;
+    storageDrivers?: string[] | null;
+  }
+}
+
+/**
+ * A namespace for private data
+ */
+namespace Private {
+  const _overrides: Record<string, IPlugin['schema']['default']> = JSON.parse(
+    PageConfig.getOption('settingsOverrides') || '{}',
+  );
+
+  /**
+   * Override the defaults of the schema with ones from PageConfig
+   *
+   * @see https://github.com/jupyterlab/jupyterlab_server/blob/v2.5.2/jupyterlab_server/settings_handler.py#L216-L227
+   */
+  export function override(plugin: IPlugin): IPlugin {
+    if (_overrides[plugin.id]) {
+      if (!plugin.schema.properties) {
+        // probably malformed, or only provides keyboard shortcuts, etc.
+        plugin.schema.properties = {};
+      }
+      for (const [prop, propDefault] of Object.entries(_overrides[plugin.id] || {})) {
+        plugin.schema.properties[prop].default = propDefault;
+      }
+    }
+    return plugin;
+  }
+}

package/src/tokens.ts

@@ -0,0 +1,75 @@
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+
+import { JSONObject, PartialJSONObject, Token } from '@lumino/coreutils';
+
+/**
+ * The token for the settings service.
+ */
+export const ISettings = new Token<ISettings>('@jupyterlite/settings:ISettings');
+
+/**
+ * The settings file to request
+ */
+export type SettingsFile = 'all.json' | 'all_federated.json';
+
+/**
+ * An interface for the plugin settings.
+ */
+export interface IPlugin extends PartialJSONObject {
+  /**
+   * The name of the plugin.
+   */
+  id: string;
+
+  /**
+   * The settings for the plugin.
+   */
+  settings: JSONObject;
+
+  /**
+   * The raw user settings data as a string containing JSON with comments.
+   */
+  raw: string;
+
+  /**
+   * The JSON schema for the plugin.
+   */
+  schema: ISettingRegistry.ISchema;
+
+  /**
+   * The published version of the NPM package containing the plugin.
+   */
+  version: string;
+}
+
+/**
+ * The interface for the Settings service.
+ */
+export interface ISettings {
+  /**
+   * A promise that resolves after the settings have been full initialized
+   */
+  ready: Promise<void>;
+
+  /**
+   * Get settings by plugin id
+   *
+   * @param pluginId the id of the plugin
+   *
+   */
+  get(pluginId: string): Promise<IPlugin | undefined>;
+
+  /**
+   * Get all the settings
+   */
+  getAll(): Promise<{ settings: IPlugin[] }>;
+
+  /**
+   * Save settings for a given plugin id
+   *
+   * @param pluginId The id of the plugin
+   * @param raw The raw settings
+   *
+   */
+  save(pluginId: string, raw: string): Promise<void>;
+}