@deepnote/convert 2.1.3 → 2.3.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { DeepnoteBlock, DeepnoteFile, Environment, Execution } from "@deepnote/blocks";
+import { DeepnoteBlock, DeepnoteFile, DeepnoteSnapshot, Environment, Execution } from "@deepnote/blocks";
 
 //#region src/types/jupyter.d.ts
 
@@ -6,6 +6,35 @@ import { DeepnoteBlock, DeepnoteFile, Environment, Execution } from "@deepnote/b
  * Shared Jupyter Notebook type definitions used by both
  * deepnote-to-jupyter and jupyter-to-deepnote converters.
  */
+/**
+ * Jupyter output types - used for cell outputs.
+ */
+interface JupyterOutputBase {
+  output_type: string;
+}
+interface JupyterStreamOutput extends JupyterOutputBase {
+  output_type: 'stream';
+  name: 'stdout' | 'stderr';
+  text: string | string[];
+}
+interface JupyterDisplayDataOutput extends JupyterOutputBase {
+  output_type: 'display_data';
+  data: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+}
+interface JupyterExecuteResultOutput extends JupyterOutputBase {
+  output_type: 'execute_result';
+  data: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  execution_count?: number | null;
+}
+interface JupyterErrorOutput extends JupyterOutputBase {
+  output_type: 'error';
+  ename: string;
+  evalue: string;
+  traceback: string[];
+}
+type JupyterOutput = JupyterStreamOutput | JupyterDisplayDataOutput | JupyterExecuteResultOutput | JupyterErrorOutput;
 interface JupyterCell {
   /** Top-level block_group field present in cloud-exported notebooks */
   block_group?: string;
@@ -110,6 +139,27 @@ declare function convertDeepnoteToJupyterNotebooks(deepnoteFile: DeepnoteFile):
  * Each notebook in the Deepnote project becomes a separate .ipynb file.
  */
 declare function convertDeepnoteFileToJupyterFiles(deepnoteFilePath: string, options: ConvertDeepnoteFileToJupyterOptions): Promise<void>;
+/**
+ * Converts a single Deepnote block to a Jupyter cell.
+ * This is useful for streaming export scenarios where blocks need to be
+ * processed one at a time rather than converting an entire notebook at once.
+ *
+ * @param block - A single DeepnoteBlock to convert
+ * @returns A JupyterCell object
+ *
+ * @example
+ * ```typescript
+ * import { convertBlockToJupyterCell } from '@deepnote/convert'
+ * import type { JupyterCell } from '@deepnote/convert'
+ *
+ * // Streaming export example
+ * for await (const block of blockStream) {
+ *   const cell: JupyterCell = convertBlockToJupyterCell(block)
+ *   outputStream.write(JSON.stringify(cell))
+ * }
+ * ```
+ */
+declare function convertBlockToJupyterCell(block: DeepnoteBlock): JupyterCell;
 //#endregion
 //#region src/types/marimo.d.ts
 /**
@@ -408,6 +458,9 @@ interface ConvertIpynbFilesToDeepnoteFileOptions {
   outputPath: string;
   projectName: string;
 }
+interface ReadAndConvertIpynbFilesOptions {
+  projectName: string;
+}
 interface ConvertJupyterNotebookOptions {
   /** Custom ID generator function. Defaults to crypto.randomUUID(). */
   idGenerator?: () => string;
@@ -446,6 +499,15 @@ declare function convertJupyterNotebookToBlocks(notebook: JupyterNotebook, optio
 declare function convertJupyterNotebooksToDeepnote(notebooks: JupyterNotebookInput[], options: {
   projectName: string;
 }): DeepnoteFile;
+/**
+ * Reads and converts multiple Jupyter Notebook (.ipynb) files into a DeepnoteFile.
+ * This function reads the files and returns the converted DeepnoteFile without writing to disk.
+ *
+ * @param inputFilePaths - Array of paths to .ipynb files
+ * @param options - Conversion options including project name
+ * @returns A DeepnoteFile object
+ */
+declare function readAndConvertIpynbFiles(inputFilePaths: string[], options: ReadAndConvertIpynbFilesOptions): Promise<DeepnoteFile>;
 /**
  * Converts multiple Jupyter Notebook (.ipynb) files into a single Deepnote project file.
  */
@@ -456,9 +518,14 @@ interface ConvertMarimoFilesToDeepnoteFileOptions {
   outputPath: string;
   projectName: string;
 }
+interface ReadAndConvertMarimoFilesOptions {
+  projectName: string;
+}
 interface ConvertMarimoAppOptions {
   /** Custom ID generator function. Defaults to crypto.randomUUID(). */
   idGenerator?: () => string;
+  /** Outputs from Marimo session cache, keyed by code_hash */
+  outputs?: Map<string, JupyterOutput[]>;
 }
 interface MarimoAppInput {
   filename: string;
@@ -490,7 +557,7 @@ declare function parseMarimoFormat(content: string): MarimoApp;
  * This is the lowest-level conversion function.
  *
  * @param app - The Marimo app object to convert
- * @param options - Optional conversion options including custom ID generator
+ * @param options - Optional conversion options including custom ID generator and outputs
  * @returns Array of DeepnoteBlock objects
  */
 declare function convertMarimoAppToBlocks(app: MarimoApp, options?: ConvertMarimoAppOptions): DeepnoteBlock[];
@@ -509,6 +576,15 @@ interface ConvertMarimoAppsToDeepnoteOptions {
  * @returns A DeepnoteFile object
  */
 declare function convertMarimoAppsToDeepnote(apps: MarimoAppInput[], options: ConvertMarimoAppsToDeepnoteOptions): DeepnoteFile;
+/**
+ * Reads and converts multiple Marimo (.py) files into a DeepnoteFile.
+ * This function reads the files and returns the converted DeepnoteFile without writing to disk.
+ *
+ * @param inputFilePaths - Array of paths to Marimo .py files
+ * @param options - Conversion options including project name
+ * @returns A DeepnoteFile object
+ */
+declare function readAndConvertMarimoFiles(inputFilePaths: string[], options: ReadAndConvertMarimoFilesOptions): Promise<DeepnoteFile>;
 /**
  * Converts multiple Marimo (.py) files into a single Deepnote project file.
  */
@@ -519,6 +595,9 @@ interface ConvertPercentFilesToDeepnoteFileOptions {
   outputPath: string;
   projectName: string;
 }
+interface ReadAndConvertPercentFilesOptions {
+  projectName: string;
+}
 interface ConvertPercentNotebookOptions {
   /** Custom ID generator function. Defaults to crypto.randomUUID(). */
   idGenerator?: () => string;
@@ -565,6 +644,15 @@ declare function convertPercentNotebookToBlocks(notebook: PercentNotebook, optio
 declare function convertPercentNotebooksToDeepnote(notebooks: PercentNotebookInput[], options: {
   projectName: string;
 }): DeepnoteFile;
+/**
+ * Reads and converts multiple percent format (.py) files into a DeepnoteFile.
+ * This function reads the files and returns the converted DeepnoteFile without writing to disk.
+ *
+ * @param inputFilePaths - Array of paths to percent format .py files
+ * @param options - Conversion options including project name
+ * @returns A DeepnoteFile object
+ */
+declare function readAndConvertPercentFiles(inputFilePaths: string[], options: ReadAndConvertPercentFilesOptions): Promise<DeepnoteFile>;
 /**
  * Converts multiple percent format (.py) files into a single Deepnote project file.
  */
@@ -575,6 +663,9 @@ interface ConvertQuartoFilesToDeepnoteFileOptions {
   outputPath: string;
   projectName: string;
 }
+interface ReadAndConvertQuartoFilesOptions {
+  projectName: string;
+}
 interface ConvertQuartoDocumentOptions {
   /** Custom ID generator function. Defaults to crypto.randomUUID(). */
   idGenerator?: () => string;
@@ -625,9 +716,249 @@ declare function convertQuartoDocumentToBlocks(document: QuartoDocument, options
 declare function convertQuartoDocumentsToDeepnote(documents: QuartoDocumentInput[], options: {
   projectName: string;
 }): DeepnoteFile;
+/**
+ * Reads and converts multiple Quarto (.qmd) files into a DeepnoteFile.
+ * This function reads the files and returns the converted DeepnoteFile without writing to disk.
+ *
+ * @param inputFilePaths - Array of paths to .qmd files
+ * @param options - Conversion options including project name
+ * @returns A DeepnoteFile object
+ */
+declare function readAndConvertQuartoFiles(inputFilePaths: string[], options: ReadAndConvertQuartoFilesOptions): Promise<DeepnoteFile>;
 /**
  * Converts multiple Quarto (.qmd) files into a single Deepnote project file.
  */
 declare function convertQuartoFilesToDeepnoteFile(inputFilePaths: string[], options: ConvertQuartoFilesToDeepnoteFileOptions): Promise<void>;
 //#endregion
-export { type ConvertBlocksToJupyterOptions, type ConvertDeepnoteFileToMarimoOptions, type ConvertDeepnoteFileToPercentOptions, type ConvertDeepnoteFileToQuartoOptions, type ConvertIpynbFilesToDeepnoteFileOptions, type ConvertJupyterNotebookOptions, type ConvertMarimoAppOptions, type ConvertMarimoAppsToDeepnoteOptions, type ConvertMarimoFilesToDeepnoteFileOptions, type ConvertPercentFilesToDeepnoteFileOptions, type ConvertPercentNotebookOptions, type ConvertQuartoDocumentOptions, type ConvertQuartoFilesToDeepnoteFileOptions, type JupyterCell, type JupyterNotebook, type JupyterNotebookInput, type MarimoApp, type MarimoAppInput, type MarimoCell, type NotebookFormat, type PercentCell, type PercentNotebook, type PercentNotebookInput, type QuartoCell, type QuartoCellOptions, type QuartoDocument, type QuartoDocumentInput, type QuartoFrontmatter, convertBlocksToJupyterNotebook, convertBlocksToMarimoApp, convertBlocksToPercentNotebook, convertBlocksToQuartoDocument, convertDeepnoteFileToJupyterFiles as convertDeepnoteFileToJupyter, convertDeepnoteFileToMarimoFiles, convertDeepnoteFileToPercentFiles, convertDeepnoteFileToQuartoFiles, convertDeepnoteToJupyterNotebooks, convertDeepnoteToMarimoApps, convertDeepnoteToPercentNotebooks, convertDeepnoteToQuartoDocuments, convertIpynbFilesToDeepnoteFile, convertJupyterNotebookToBlocks, convertJupyterNotebooksToDeepnote, convertMarimoAppToBlocks, convertMarimoAppsToDeepnote, convertMarimoFilesToDeepnoteFile, convertPercentFilesToDeepnoteFile, convertPercentNotebookToBlocks, convertPercentNotebooksToDeepnote, convertQuartoDocumentToBlocks, convertQuartoDocumentsToDeepnote, convertQuartoFilesToDeepnoteFile, detectFormat, parseMarimoFormat, parsePercentFormat, parseQuartoFormat, serializeMarimoFormat, serializePercentFormat, serializeQuartoFormat };
+//#region src/snapshot/hash.d.ts
+/**
+ * Computes a SHA-256 hash of the given content.
+ *
+ * @param content - The content to hash
+ * @returns Hash string in format 'sha256:{hex}'
+ */
+declare function computeContentHash(content: string): string;
+/**
+ * Computes a snapshot hash from the file's key properties.
+ * The hash is based on: version, environment.hash, integrations, and all block contentHashes.
+ *
+ * @param file - The DeepnoteFile to compute hash for
+ * @returns Hash string in format 'sha256:{hex}'
+ */
+declare function computeSnapshotHash(file: DeepnoteFile): string;
+/**
+ * Adds content hashes to all blocks in a DeepnoteFile that don't already have them.
+ * Returns a new DeepnoteFile with hashes added (does not mutate the input).
+ *
+ * @param file - The DeepnoteFile to add hashes to
+ * @returns A new DeepnoteFile with content hashes added
+ */
+declare function addContentHashes(file: DeepnoteFile): DeepnoteFile;
+//#endregion
+//#region src/snapshot/types.d.ts
+/**
+ * Options for snapshot operations
+ */
+interface SnapshotOptions {
+  /** Directory where snapshot files are stored (default: 'snapshots') */
+  snapshotDir?: string;
+}
+/**
+ * Result of splitting a DeepnoteFile into source and snapshot
+ */
+interface SplitResult {
+  /** The source file without outputs */
+  source: DeepnoteFile;
+  /** The snapshot file containing outputs */
+  snapshot: DeepnoteSnapshot;
+}
+/**
+ * Block output information stored in a snapshot
+ */
+interface BlockOutput {
+  /** Block ID */
+  id: string;
+  /** Content hash of the source when output was generated */
+  contentHash?: string;
+  /** Execution count */
+  executionCount?: number | null;
+  /** When execution started */
+  executionStartedAt?: string;
+  /** When execution finished */
+  executionFinishedAt?: string;
+  /** Output data */
+  outputs?: unknown[];
+}
+/**
+ * Information about a snapshot file
+ */
+interface SnapshotInfo {
+  /** Full path to the snapshot file */
+  path: string;
+  /** Project name slug */
+  slug: string;
+  /** Project ID */
+  projectId: string;
+  /** Timestamp or 'latest' */
+  timestamp: string;
+}
+/**
+ * Options for merging a snapshot into a source file
+ */
+interface MergeOptions {
+  /** Whether to skip blocks with mismatched content hashes (default: false) */
+  skipMismatched?: boolean;
+}
+//#endregion
+//#region src/snapshot/lookup.d.ts
+/**
+ * Parses a snapshot filename into its components.
+ *
+ * @param filename - The snapshot filename to parse
+ * @returns Parsed components or null if filename doesn't match pattern
+ */
+declare function parseSnapshotFilename(filename: string): {
+  slug: string;
+  projectId: string;
+  timestamp: string;
+} | null;
+/**
+ * Finds all snapshot files for a given project.
+ *
+ * @param projectDir - Directory containing the .deepnote file
+ * @param projectId - The project UUID to search for
+ * @param options - Snapshot options
+ * @returns Array of SnapshotInfo objects, sorted by timestamp (newest first)
+ */
+declare function findSnapshotsForProject(projectDir: string, projectId: string, options?: SnapshotOptions): Promise<SnapshotInfo[]>;
+/**
+ * Loads the latest snapshot for a project.
+ *
+ * @param sourceFilePath - Path to the source .deepnote file
+ * @param projectId - The project UUID
+ * @param options - Snapshot options
+ * @returns The parsed DeepnoteSnapshot or null if not found
+ */
+declare function loadLatestSnapshot(sourceFilePath: string, projectId: string, options?: SnapshotOptions): Promise<DeepnoteSnapshot | null>;
+/**
+ * Loads and parses a snapshot file.
+ *
+ * @param snapshotPath - Path to the snapshot file
+ * @returns The parsed DeepnoteSnapshot
+ */
+declare function loadSnapshotFile(snapshotPath: string): Promise<DeepnoteSnapshot>;
+/**
+ * Gets the snapshot directory path for a source file.
+ *
+ * @param sourceFilePath - Path to the source .deepnote file
+ * @param options - Snapshot options
+ * @returns The snapshot directory path
+ */
+declare function getSnapshotDir(sourceFilePath: string, options?: SnapshotOptions): string;
+/**
+ * Checks if a snapshot exists for a project.
+ *
+ * @param sourceFilePath - Path to the source .deepnote file
+ * @param projectId - The project UUID
+ * @param options - Snapshot options
+ * @returns True if at least one snapshot exists
+ */
+declare function snapshotExists(sourceFilePath: string, projectId: string, options?: SnapshotOptions): Promise<boolean>;
+/**
+ * Extracts project information from a source file path.
+ *
+ * @param sourceFilePath - Path to the source .deepnote file
+ * @returns Object with directory and filename without extension
+ */
+declare function parseSourceFilePath(sourceFilePath: string): {
+  dir: string;
+  name: string;
+};
+//#endregion
+//#region src/snapshot/merge.d.ts
+/**
+ * Merges outputs from a snapshot into a source file.
+ * Returns a new DeepnoteFile with outputs added from the snapshot.
+ *
+ * @param source - The source DeepnoteFile (without outputs)
+ * @param snapshot - The snapshot containing outputs
+ * @param options - Merge options
+ * @returns A new DeepnoteFile with outputs merged in
+ */
+declare function mergeSnapshotIntoSource(source: DeepnoteFile, snapshot: DeepnoteSnapshot, options?: MergeOptions): DeepnoteFile;
+/**
+ * Counts blocks with outputs in a file.
+ *
+ * @param file - The DeepnoteFile to count outputs in
+ * @returns Number of blocks that have outputs
+ */
+declare function countBlocksWithOutputs(file: DeepnoteFile): number;
+//#endregion
+//#region src/snapshot/split.d.ts
+/**
+ * Creates a slug from a project name.
+ * Normalizes accented characters to ASCII equivalents (e.g., é → e),
+ * converts to lowercase, replaces spaces and special chars with hyphens,
+ * removes consecutive hyphens, and trims leading/trailing hyphens.
+ *
+ * @param name - The project name to slugify
+ * @returns A URL-safe slug
+ */
+declare function slugifyProjectName(name: string): string;
+/**
+ * Generates a snapshot filename from project info.
+ *
+ * @param slug - The project name slug
+ * @param projectId - The project UUID
+ * @param timestamp - Timestamp string or 'latest'
+ * @returns Filename in format '{slug}_{projectId}_{timestamp}.snapshot.deepnote'
+ */
+declare function generateSnapshotFilename(slug: string, projectId: string, timestamp?: string): string;
+/**
+ * Splits a DeepnoteFile into a source file (no outputs) and a snapshot file (outputs only).
+ *
+ * @param file - The complete DeepnoteFile with outputs
+ * @returns Object containing source and snapshot files
+ */
+declare function splitDeepnoteFile(file: DeepnoteFile): SplitResult;
+/**
+ * Checks if a DeepnoteFile has any outputs.
+ *
+ * @param file - The DeepnoteFile to check
+ * @returns True if any block has outputs
+ */
+declare function hasOutputs(file: DeepnoteFile): boolean;
+//#endregion
+//#region src/write-deepnote-file.d.ts
+interface WriteDeepnoteFileOptions {
+  /** The DeepnoteFile to write */
+  file: DeepnoteFile;
+  /** Path where the main .deepnote file should be written */
+  outputPath: string;
+  /** Project name used for snapshot filename */
+  projectName: string;
+  /** When true, outputs are included in the main file (disables snapshot mode) */
+  singleFile?: boolean;
+}
+interface WriteDeepnoteFileResult {
+  /** Path to the written source file */
+  sourcePath: string;
+  /** Path to the snapshot file (only if outputs were split) */
+  snapshotPath?: string;
+}
+/**
+ * Writes a DeepnoteFile to disk, optionally splitting outputs into a snapshot file.
+ *
+ * When singleFile is false (default) and the file contains outputs:
+ * - Splits the file in memory into source (no outputs) and snapshot (with outputs)
+ * - Writes both files in parallel
+ *
+ * When singleFile is true or there are no outputs:
+ * - Writes the complete file as-is
+ *
+ * @param options - Write options including the file, output path, and project name
+ * @returns Object containing paths to the written files
+ */
+declare function writeDeepnoteFile(options: WriteDeepnoteFileOptions): Promise<WriteDeepnoteFileResult>;
+//#endregion
+export { type BlockOutput, type ConvertBlocksToJupyterOptions, type ConvertDeepnoteFileToMarimoOptions, type ConvertDeepnoteFileToPercentOptions, type ConvertDeepnoteFileToQuartoOptions, type ConvertIpynbFilesToDeepnoteFileOptions, type ConvertJupyterNotebookOptions, type ConvertMarimoAppOptions, type ConvertMarimoAppsToDeepnoteOptions, type ConvertMarimoFilesToDeepnoteFileOptions, type ConvertPercentFilesToDeepnoteFileOptions, type ConvertPercentNotebookOptions, type ConvertQuartoDocumentOptions, type ConvertQuartoFilesToDeepnoteFileOptions, type JupyterCell, type JupyterNotebook, type JupyterNotebookInput, type MarimoApp, type MarimoAppInput, type MarimoCell, type MergeOptions, type NotebookFormat, type PercentCell, type PercentNotebook, type PercentNotebookInput, type QuartoCell, type QuartoCellOptions, type QuartoDocument, type QuartoDocumentInput, type QuartoFrontmatter, type ReadAndConvertIpynbFilesOptions, type ReadAndConvertMarimoFilesOptions, type ReadAndConvertPercentFilesOptions, type ReadAndConvertQuartoFilesOptions, type SnapshotInfo, type SnapshotOptions, type SplitResult, type WriteDeepnoteFileOptions, type WriteDeepnoteFileResult, addContentHashes, computeContentHash, computeSnapshotHash, convertBlockToJupyterCell, convertBlocksToJupyterNotebook, convertBlocksToMarimoApp, convertBlocksToPercentNotebook, convertBlocksToQuartoDocument, convertDeepnoteFileToJupyterFiles, convertDeepnoteFileToMarimoFiles, convertDeepnoteFileToPercentFiles, convertDeepnoteFileToQuartoFiles, convertDeepnoteToJupyterNotebooks, convertDeepnoteToMarimoApps, convertDeepnoteToPercentNotebooks, convertDeepnoteToQuartoDocuments, convertIpynbFilesToDeepnoteFile, convertJupyterNotebookToBlocks, convertJupyterNotebooksToDeepnote, convertMarimoAppToBlocks, convertMarimoAppsToDeepnote, convertMarimoFilesToDeepnoteFile, convertPercentFilesToDeepnoteFile, convertPercentNotebookToBlocks, convertPercentNotebooksToDeepnote, convertQuartoDocumentToBlocks, convertQuartoDocumentsToDeepnote, convertQuartoFilesToDeepnoteFile, countBlocksWithOutputs, detectFormat, findSnapshotsForProject, generateSnapshotFilename, getSnapshotDir, hasOutputs, loadLatestSnapshot, loadSnapshotFile, mergeSnapshotIntoSource, parseMarimoFormat, parsePercentFormat, parseQuartoFormat, parseSnapshotFilename, parseSourceFilePath, readAndConvertIpynbFiles, readAndConvertMarimoFiles, readAndConvertPercentFiles, readAndConvertQuartoFiles, serializeMarimoFormat, serializePercentFormat, serializeQuartoFormat, slugifyProjectName, snapshotExists, splitDeepnoteFile, writeDeepnoteFile };