Cell Interfaces

/**
 * A cell union type representing all possible cell types
 */
type ICell = IRawCell | IMarkdownCell | ICodeCell | IUnrecognizedCell;

/**
 * A type describing the type of cell
 */
type CellType = 'code' | 'markdown' | 'raw' | string;

/**
 * The base cell interface that all cells extend
 */
interface IBaseCell extends PartialJSONObject {
  /** String identifying the type of cell */
  cell_type: string;
  /** Contents of the cell, represented as an array of lines or single string */
  source: MultilineString;
  /** Cell-level metadata */
  metadata: Partial<ICellMetadata>;
}

/**
 * Union metadata type for all cell types
 */
type ICellMetadata = IBaseCellMetadata | IRawCellMetadata | ICodeCellMetadata;

/**
 * Cell-level metadata base interface
 */
interface IBaseCellMetadata extends PartialJSONObject {
  /** Whether the cell is trusted (security-related) */
  trusted: boolean;
  /** The cell's name. If present, must be a non-empty string */
  name: string;
  /** The Jupyter metadata namespace */
  jupyter: Partial<IBaseCellJupyterMetadata>;
  /** The cell's tags. Tags must be unique, and must not contain commas */
  tags: string[];
}

/**
 * The Jupyter metadata namespace for cells
 */
interface IBaseCellJupyterMetadata extends PartialJSONObject {
  /** Whether the source is hidden */
  source_hidden: boolean;
}

/**
 * A code cell interface for executable code
 */
interface ICodeCell extends IBaseCell {
  /** Cell identifier (optional in nbformat 4.4, required in 4.5+) */
  id?: string;
  /** String identifying the type of cell */
  cell_type: 'code';
  /** Cell-level metadata */
  metadata: Partial<ICodeCellMetadata>;
  /** Execution, display, or stream outputs */
  outputs: IOutput[];
  /** The code cell's prompt number. Will be null if the cell has not been run */
  execution_count: ExecutionCount;
}

/**
 * Metadata for a code cell
 */
interface ICodeCellMetadata extends IBaseCellMetadata {
  /** Whether the cell is collapsed/expanded */
  collapsed: boolean;
  /** The Jupyter metadata namespace */
  jupyter: Partial<ICodeCellJupyterMetadata>;
  /** Whether the cell's output is scrolled, unscrolled, or autoscrolled */
  scrolled: boolean | 'auto';
}

/**
 * The Jupyter metadata namespace for code cells
 */
interface ICodeCellJupyterMetadata extends IBaseCellJupyterMetadata {
  /** Whether the outputs are hidden */
  outputs_hidden: boolean;
}

import { ICodeCell, ExecutionCount } from "@jupyterlab/nbformat";

const codeCell: ICodeCell = {
  cell_type: 'code',
  source: ['print("Hello, world!")', 'x = 42'],
  metadata: {
    trusted: true,
    name: "hello_world",
    jupyter: {
      source_hidden: false,
      outputs_hidden: false
    },
    tags: ["example"],
    collapsed: false,
    scrolled: false
  },
  outputs: [],
  execution_count: null
};

/**
 * A markdown cell interface for documentation
 */
interface IMarkdownCell extends IBaseCell {
  /** Cell identifier (optional in nbformat 4.4, required in 4.5+) */
  id?: string;
  /** String identifying the type of cell */
  cell_type: 'markdown';
  /** Cell attachments (e.g., inline images) */
  attachments?: IAttachments;
}

import { IMarkdownCell } from "@jupyterlab/nbformat";

const markdownCell: IMarkdownCell = {
  cell_type: 'markdown',
  source: ['# Title', '', 'Some **bold** text.'],
  metadata: {
    trusted: true,
    name: "title_cell",
    jupyter: {
      source_hidden: false
    },
    tags: ["documentation"]
  }
};

/**
 * A raw cell interface for unprocessed text
 */
interface IRawCell extends IBaseCell {
  /** Cell identifier (optional in nbformat 4.4, required in 4.5+) */
  id?: string;
  /** String identifying the type of cell */
  cell_type: 'raw';
  /** Cell-level metadata */
  metadata: Partial<IRawCellMetadata>;
  /** Cell attachments */
  attachments?: IAttachments;
}

/**
 * Metadata for the raw cell
 */
interface IRawCellMetadata extends IBaseCellMetadata {
  /** Raw cell metadata format for nbconvert */
  format: string;
}

/**
 * An unrecognized cell interface for unknown cell types
 */
interface IUnrecognizedCell extends IBaseCell {}

/**
 * Test whether a cell is a raw cell
 */
function isRaw(cell: ICell): cell is IRawCell;

/**
 * Test whether a cell is a markdown cell  
 */
function isMarkdown(cell: ICell): cell is IMarkdownCell;

/**
 * Test whether a cell is a code cell
 */
function isCode(cell: ICell): cell is ICodeCell;

import { ICell, isCode, isMarkdown, isRaw } from "@jupyterlab/nbformat";

function processCells(cells: ICell[]): void {
  cells.forEach((cell, index) => {
    if (isCode(cell)) {
      console.log(`Cell ${index}: Code cell with ${cell.outputs.length} outputs`);
      console.log(`Execution count: ${cell.execution_count}`);
    } else if (isMarkdown(cell)) {
      console.log(`Cell ${index}: Markdown cell`);
    } else if (isRaw(cell)) {
      console.log(`Cell ${index}: Raw cell with format: ${cell.metadata.format || 'none'}`);
    } else {
      console.log(`Cell ${index}: Unrecognized cell type: ${cell.cell_type}`);
    }
  });
}

/**
 * The code cell's prompt number. Will be null if the cell has not been run
 */
type ExecutionCount = number | null;

/**
 * A multiline string that can be a single string or array of strings
 */
type MultilineString = string | string[];

/**
 * Media attachments (e.g. inline images)
 */
interface IAttachments {
  [key: string]: IMimeBundle | undefined;
}