@jupyterlite/services 0.1.0 → 0.7.0-rc.0

package/src/kernel/tokens.ts

@@ -0,0 +1,222 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import type { Remote } from 'comlink';
+
+import { IObservableMap } from '@jupyterlab/observables';
+
+import { Kernel, KernelMessage, KernelSpec } from '@jupyterlab/services';
+
+import { Token } from '@lumino/coreutils';
+
+import { IObservableDisposable } from '@lumino/disposable';
+
+import { ISignal } from '@lumino/signaling';
+
+import { KernelSpecs } from './kernelspecs';
+
+/**
+ * The kernel name of last resort.
+ */
+export const FALLBACK_KERNEL = 'javascript';
+
+/**
+ * The token for the kernel client.
+ */
+export const IKernelClient = new Token<IKernelClient>(
+  '@jupyterlite/services:IKernelClient',
+);
+
+/**
+ * An interface for the Kernels service.
+ */
+export interface IKernelClient extends Kernel.IKernelAPIClient {
+  /**
+   * Signal emitted when the kernels map changes
+   */
+  readonly changed: ISignal<IKernelClient, IObservableMap.IChangedArgs<IKernel>>;
+
+  /**
+   * Handle stdin request received from Service Worker.
+   */
+  handleStdin(
+    inputRequest: KernelMessage.IInputRequestMsg,
+  ): Promise<KernelMessage.IInputReplyMsg>;
+
+  /**
+   * Shut down all kernels.
+   */
+  shutdownAll: () => Promise<void>;
+}
+
+/**
+ * The token for the kernel spec client.
+ */
+export const IKernelSpecClient = new Token<IKernelSpecClient>(
+  '@jupyterlite/services:IKernelSpecClient',
+);
+
+/**
+ * An interface for the kernel spec client.
+ */
+export interface IKernelSpecClient extends KernelSpec.IKernelSpecAPIClient {}
+
+/**
+ * An interface for a kernel running in the browser.
+ */
+export interface IKernel extends IObservableDisposable {
+  /**
+   * The id of the server-side kernel.
+   */
+  readonly id: string;
+
+  /**
+   * The name of the server-side kernel.
+   */
+  readonly name: string;
+
+  /**
+   * The location in the virtual filesystem from which the kernel was started.
+   */
+  readonly location: string;
+
+  /**
+   * A promise that is fulfilled when the kernel is ready.
+   */
+  readonly ready: Promise<void>;
+
+  /**
+   * Handle an incoming message from the client.
+   *
+   * @param msg The message to handle
+   */
+  handleMessage(msg: KernelMessage.IMessage): Promise<void>;
+}
+
+/**
+ * A namespace for IKernel statics.
+ */
+export namespace IKernel {
+  /**
+   * The type for the send message function.
+   */
+  export type SendMessage = (msg: KernelMessage.IMessage) => void;
+
+  /**
+   * The instantiation options for an IKernel.
+   */
+  export interface IOptions {
+    /**
+     * The kernel id.
+     */
+    id: string;
+
+    /**
+     * The name of the kernel.
+     */
+    name: string;
+
+    /**
+     * The location in the virtual filesystem from which the kernel was started.
+     */
+    location: string;
+
+    /**
+     * The method to send messages back to the server.
+     */
+    sendMessage: SendMessage;
+  }
+}
+
+/**
+ * The token for the kernel spec service.
+ */
+export const IKernelSpecs = new Token<IKernelSpecs>(
+  '@jupyterlite/services:IKernelSpecs',
+);
+
+/**
+ * The interface for the kernel specs service.
+ */
+export interface IKernelSpecs {
+  /**
+   * Get the kernel specs.
+   */
+  readonly specs: KernelSpec.ISpecModels | null;
+
+  /**
+   * Get the default kernel name.
+   */
+  readonly defaultKernelName: string;
+
+  /**
+   * Get the kernel factories for the current kernels.
+   */
+  readonly factories: KernelSpecs.KernelFactories;
+
+  /**
+   * Signal emitted when the specs change.
+   */
+  readonly changed: ISignal<IKernelSpecs, KernelSpec.ISpecModels | null>;
+
+  /**
+   * Register a new kernel spec
+   *
+   * @param options The kernel spec options.
+   */
+  register: (options: KernelSpecs.IKernelOptions) => void;
+}
+
+/**
+ * An interface for a comlink-based worker kernel
+ */
+export interface IWorkerKernel {
+  /**
+   * Handle any lazy setup activities.
+   */
+  initialize(options: IWorkerKernel.IOptions): Promise<void>;
+  execute(
+    content: KernelMessage.IExecuteRequestMsg['content'],
+    parent: any,
+  ): Promise<KernelMessage.IExecuteReplyMsg['content']>;
+  complete(
+    content: KernelMessage.ICompleteRequestMsg['content'],
+    parent: any,
+  ): Promise<KernelMessage.ICompleteReplyMsg['content']>;
+  inspect(
+    content: KernelMessage.IInspectRequestMsg['content'],
+    parent: any,
+  ): Promise<KernelMessage.IInspectReplyMsg['content']>;
+  isComplete(
+    content: KernelMessage.IIsCompleteRequestMsg['content'],
+    parent: any,
+  ): Promise<KernelMessage.IIsCompleteReplyMsg['content']>;
+  commInfo(
+    content: KernelMessage.ICommInfoRequestMsg['content'],
+    parent: any,
+  ): Promise<KernelMessage.ICommInfoReplyMsg['content']>;
+  commOpen(content: KernelMessage.ICommOpenMsg, parent: any): Promise<void>;
+  commMsg(content: KernelMessage.ICommMsgMsg, parent: any): Promise<void>;
+  commClose(content: KernelMessage.ICommCloseMsg, parent: any): Promise<void>;
+  inputReply(
+    content: KernelMessage.IInputReplyMsg['content'],
+    parent: any,
+  ): Promise<void>;
+}
+
+/**
+ * A namespace for worker kernels.
+ **/
+export namespace IWorkerKernel {
+  /**
+   * Common values likely to be required by all kernels.
+   */
+  export interface IOptions {
+    /**
+     * The base URL of the kernel server.
+     */
+    baseUrl: string;
+  }
+}
+
+export interface IRemoteKernel extends Remote<IWorkerKernel> {}

package/src/nbconvert/exporters.ts

@@ -0,0 +1,177 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Contents } from '@jupyterlab/services';
+
+import { IExporter } from './tokens';
+
+/**
+ * Base class for notebook exporters.
+ */
+export abstract class BaseExporter implements IExporter {
+  /**
+   * The MIME type of the exported format.
+   */
+  abstract readonly mimeType: string;
+
+  /**
+   * Export a notebook to this format.
+   *
+   * @param model The notebook model to export
+   * @param path The path to the notebook
+   */
+  abstract export(model: Contents.IModel, path: string): Promise<void>;
+
+  /**
+   * Trigger a browser download of the exported content.
+   *
+   * @param content The content to download
+   * @param mimeType The MIME type of the content
+   * @param filename The filename for the download
+   */
+  protected triggerDownload(content: string, mimeType: string, filename: string): void {
+    const element = document.createElement('a');
+    element.href = `data:${mimeType};charset=utf-8,${encodeURIComponent(content)}`;
+    element.download = filename;
+    document.body.appendChild(element);
+    element.click();
+    document.body.removeChild(element);
+  }
+}
+
+/**
+ * Exporter for notebook format (.ipynb).
+ */
+export class NotebookExporter extends BaseExporter {
+  /**
+   * The MIME type of the exported format.
+   */
+  readonly mimeType = 'application/x-ipynb+json';
+
+  /**
+   * Export a notebook to .ipynb format.
+   *
+   * @param model The notebook model to export
+   * @param path The path to the notebook
+   */
+  async export(model: Contents.IModel, path: string): Promise<void> {
+    const mime = model.mimetype ?? 'application/json';
+    const content = JSON.stringify(model.content, null, 2);
+    this.triggerDownload(content, mime, path);
+  }
+}
+
+/**
+ * Exporter for executable script format.
+ */
+export class ScriptExporter extends BaseExporter {
+  /**
+   * The MIME type of the exported format.
+   */
+  readonly mimeType = 'text/x-script';
+
+  /**
+   * Export a notebook to executable script format.
+   *
+   * @param model The notebook model to export
+   * @param path The path to the notebook
+   */
+  async export(model: Contents.IModel, path: string): Promise<void> {
+    const { content, extension } = this.convertToScript(model.content);
+    const filename = path.replace(/\.ipynb$/, extension);
+    this.triggerDownload(content, 'text/plain', filename);
+  }
+
+  /**
+   * Convert a notebook to a script file.
+   *
+   * @param content The notebook content
+   * @returns The script content and file extension
+   */
+  private convertToScript(content: any): {
+    content: string;
+    extension: string;
+  } {
+    // Get the language from the notebook metadata
+    const languageInfo = content.metadata?.language_info;
+    const language = languageInfo?.name || 'python';
+    const fileExtension = languageInfo?.file_extension || '.py';
+
+    // Extract code cells and convert to script
+    const cells = content.cells || [];
+    const scriptLines: string[] = [];
+
+    for (const cell of cells) {
+      if (cell.cell_type === 'code') {
+        // Add code cell content
+        const source = Array.isArray(cell.source) ? cell.source.join('') : cell.source;
+        scriptLines.push(source);
+        // Add blank line between cells
+        scriptLines.push('');
+      } else if (cell.cell_type === 'markdown' || cell.cell_type === 'raw') {
+        // Add markdown and raw cells as comments
+        const source = Array.isArray(cell.source) ? cell.source.join('') : cell.source;
+        const commentedSource = this.commentLines(source, language);
+        scriptLines.push(commentedSource);
+        // Add blank line between cells
+        scriptLines.push('');
+      }
+    }
+
+    return {
+      content: scriptLines.join('\n') + '\n',
+      extension: fileExtension,
+    };
+  }
+
+  /**
+   * Comment out lines based on the language.
+   *
+   * @param text The text to comment
+   * @param language The programming language
+   * @returns The commented text
+   */
+  private commentLines(text: string, language: string): string {
+    const lines = text.split('\n');
+    const commentChar = this.getCommentChar(language);
+
+    return lines.map((line) => `${commentChar} ${line}`).join('\n');
+  }
+
+  /**
+   * Get the comment character for a given language.
+   *
+   * @param language The programming language
+   * @returns The comment character(s) for that language
+   */
+  private getCommentChar(language: string): string {
+    // Map of languages to their comment characters
+    const commentMap: { [key: string]: string } = {
+      python: '#',
+      r: '#',
+      julia: '#',
+      ruby: '#',
+      bash: '#',
+      shell: '#',
+      perl: '#',
+      javascript: '//',
+      typescript: '//',
+      java: '//',
+      c: '//',
+      cpp: '//',
+      'c++': '//',
+      scala: '//',
+      go: '//',
+      rust: '//',
+      swift: '//',
+      kotlin: '//',
+      matlab: '%',
+      octave: '%',
+      lua: '--',
+      sql: '--',
+      haskell: '--',
+    };
+
+    return commentMap[language.toLowerCase()] || '#';
+  }
+}

package/src/nbconvert/index.ts

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

package/src/nbconvert/manager.ts

@@ -0,0 +1,105 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Contents, NbConvert, NbConvertManager } from '@jupyterlab/services';
+
+import { IExporter, INbConvertExporters } from './tokens';
+
+/**
+ * Options for creating a LiteNbConvertManager.
+ */
+export interface ILiteNbConvertManagerOptions extends NbConvertManager.IOptions {
+  /**
+   * The contents manager.
+   */
+  contentsManager: Contents.IManager;
+
+  /**
+   * The exporter registry.
+   */
+  exporters: INbConvertExporters;
+}
+
+/**
+ * Custom NbConvert manager for JupyterLite with client-side export.
+ */
+export class LiteNbConvertManager extends NbConvertManager {
+  /**
+   * Construct a new LiteNbConvertManager.
+   *
+   * @param options The manager options
+   */
+  constructor(options: ILiteNbConvertManagerOptions) {
+    super(options);
+    this._contentsManager = options.contentsManager;
+    this._exporters = options.exporters;
+  }
+
+  /**
+   * Get the list of export formats available.
+   */
+  async getExportFormats(): Promise<NbConvert.IExportFormats> {
+    return this._exporters.getExportFormats();
+  }
+
+  /**
+   * Export a notebook to a given format.
+   *
+   * @param options The export options
+   */
+  async exportAs(options: NbConvert.IExportOptions): Promise<void> {
+    const { format, path } = options;
+
+    const model = await this._contentsManager.get(path, { content: true });
+    const exporter = this._exporters.get(format);
+    if (!exporter) {
+      throw new Error(`Unknown export format: ${format}`);
+    }
+    await exporter.export(model, path);
+  }
+
+  private _contentsManager: Contents.IManager;
+  private _exporters: INbConvertExporters;
+}
+
+/**
+ * Implementation of the exporter registry.
+ */
+export class Exporters implements INbConvertExporters {
+  /**
+   * Register a new exporter.
+   *
+   * @param format The export format name
+   * @param exporter The exporter instance
+   */
+  register(format: string, exporter: IExporter): void {
+    this._exporters.set(format, exporter);
+  }
+
+  /**
+   * Get an exporter by format.
+   *
+   * @param format The export format name
+   * @returns The exporter or undefined if not found
+   */
+  get(format: string): IExporter | undefined {
+    return this._exporters.get(format);
+  }
+
+  /**
+   * Get all registered export formats.
+   *
+   * @returns A map of format names to their MIME types
+   */
+  getExportFormats(): Record<string, { output_mimetype: string }> {
+    const formats: Record<string, { output_mimetype: string }> = {};
+
+    for (const [format, exporter] of this._exporters) {
+      formats[format] = { output_mimetype: exporter.mimeType };
+    }
+
+    return formats;
+  }
+
+  private _exporters = new Map<string, IExporter>();
+}

package/src/nbconvert/tokens.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Token } from '@lumino/coreutils';
+
+import { Contents } from '@jupyterlab/services';
+
+/**
+ * The token for the exporter registry.
+ */
+export const INbConvertExporters = new Token<INbConvertExporters>(
+  '@jupyterlite/services:INbConvertExporters',
+  'A service for managing notebook exporters in JupyterLite',
+);
+
+/**
+ * Interface for the exporter registry.
+ */
+export interface INbConvertExporters {
+  /**
+   * Register a new exporter.
+   *
+   * @param format The export format name
+   * @param exporter The exporter instance
+   */
+  register(format: string, exporter: IExporter): void;
+
+  /**
+   * Get an exporter by format.
+   *
+   * @param format The export format name
+   * @returns The exporter or undefined if not found
+   */
+  get(format: string): IExporter | undefined;
+
+  /**
+   * Get all registered export formats.
+   *
+   * @returns A map of format names to their MIME types
+   */
+  getExportFormats(): Record<string, { output_mimetype: string }>;
+}
+
+/**
+ * Interface for a notebook exporter.
+ */
+export interface IExporter {
+  /**
+   * The MIME type of the exported format.
+   */
+  readonly mimeType: string;
+
+  /**
+   * Export a notebook to this format.
+   *
+   * @param model The notebook model to export
+   * @param path The path to the notebook
+   */
+  export(model: Contents.IModel, path: string): Promise<void>;
+}