@deepnote/blocks 3.0.1 → 4.0.0

package/dist/index.cjs

@@ -28,6 +28,113 @@ yaml = __toESM(yaml);
 let ts_dedent = require("ts-dedent");
 ts_dedent = __toESM(ts_dedent);
 
+//#region src/errors.ts
+/**
+* Base error class for all Deepnote errors.
+*/
+var DeepnoteError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = this.constructor.name;
+	}
+};
+/**
+* Generic parse failure, optionally associated with a file path.
+*/
+var ParseError = class extends DeepnoteError {
+	filePath;
+	constructor(message, options) {
+		super(message, options);
+		this.filePath = options?.filePath;
+	}
+};
+/**
+* YAML syntax or duplicate key errors.
+*/
+var YamlParseError = class extends ParseError {};
+/**
+* BOM or invalid UTF-8 encoding errors.
+*/
+var EncodingError = class extends ParseError {};
+/**
+* Zod schema validation failures.
+*/
+var SchemaValidationError = class extends ParseError {};
+/**
+* Prohibited YAML features: anchors, aliases, merge keys, tags.
+*/
+var ProhibitedYamlFeatureError = class extends ParseError {
+	feature;
+	constructor(message, options) {
+		super(message, options);
+		this.feature = options.feature;
+	}
+};
+/**
+* Thrown when a block type is not supported.
+*/
+var UnsupportedBlockTypeError = class extends DeepnoteError {};
+/**
+* Thrown when a value is invalid (e.g., slider value, date interval).
+*/
+var InvalidValueError = class extends DeepnoteError {
+	value;
+	constructor(message, options) {
+		super(message, options);
+		this.value = options.value;
+	}
+};
+
+//#endregion
+//#region src/blocks/executable-blocks.ts
+/**
+* Block types that represent user input widgets.
+* These blocks capture user input and define variables.
+*/
+const INPUT_BLOCK_TYPES = new Set([
+	"input-text",
+	"input-textarea",
+	"input-checkbox",
+	"input-select",
+	"input-slider",
+	"input-date",
+	"input-date-range",
+	"input-file"
+]);
+const executableBlockTypes = new Set([
+	"code",
+	"sql",
+	"notebook-function",
+	"visualization",
+	"button",
+	"big-number",
+	...INPUT_BLOCK_TYPES
+]);
+/**
+* Type guard to check if a block is an executable block.
+* Executable blocks can have outputs and be executed by the runtime.
+*/
+function isExecutableBlock(block) {
+	return executableBlockTypes.has(block.type);
+}
+/**
+* Checks if a block type string represents an executable block.
+* Convenience function for when you only have the type string.
+*/
+function isExecutableBlockType(type) {
+	return executableBlockTypes.has(type);
+}
+
+//#endregion
+//#region src/blocks/sql-utils.ts
+function convertToEnvironmentVariableName(str) {
+	return (/^\d/.test(str) ? `_${str}` : str).toUpperCase().replace(/[^\w]/g, "_");
+}
+function getSqlEnvVarName(integrationId) {
+	return `SQL_${integrationId}`;
+}
+
+//#endregion
 //#region src/deserialize-file/deepnote-file-schema.ts
 /** Preprocesses any content value to empty string for blocks that don't use content */
 const emptyContent = () => zod.z.preprocess(() => "", zod.z.literal("").optional());
@@ -420,6 +527,17 @@ const deepnoteFileSchema = zod.z.object({
 	}),
 	version: zod.z.string()
 });
+const deepnoteSnapshotSchema = deepnoteFileSchema.extend({
+	environment: environmentSchema.unwrap(),
+	execution: executionSchema.unwrap(),
+	metadata: zod.z.object({
+		checksum: zod.z.string().optional(),
+		createdAt: zod.z.string(),
+		exportedAt: zod.z.string().optional(),
+		modifiedAt: zod.z.string().optional(),
+		snapshotHash: zod.z.string()
+	})
+});
 
 //#endregion
 //#region src/deserialize-file/parse-yaml.ts
@@ -429,7 +547,7 @@ const deepnoteFileSchema = zod.z.object({
 *
 * @param bytes - Raw file bytes as Uint8Array
 * @returns Decoded UTF-8 string without BOM
-* @throws Error if BOM detected or invalid UTF-8 encoding
+* @throws EncodingError if BOM detected or invalid UTF-8 encoding
 *
 * @example
 * ```typescript
@@ -439,11 +557,11 @@ const deepnoteFileSchema = zod.z.object({
 * ```
 */
 function decodeUtf8NoBom(bytes) {
-	if (bytes.length >= 3 && bytes[0] === 239 && bytes[1] === 187 && bytes[2] === 191) throw new Error("UTF-8 BOM detected in Deepnote file - files must be UTF-8 without BOM");
+	if (bytes.length >= 3 && bytes[0] === 239 && bytes[1] === 187 && bytes[2] === 191) throw new EncodingError("UTF-8 BOM detected in Deepnote file - files must be UTF-8 without BOM");
 	try {
 		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
 	} catch {
-		throw new Error("Invalid UTF-8 encoding detected in Deepnote file");
+		throw new EncodingError("Invalid UTF-8 encoding detected in Deepnote file");
 	}
 }
 /**
@@ -453,10 +571,10 @@ function decodeUtf8NoBom(bytes) {
 * For proper UTF-8 validation, use decodeUtf8NoBom() on raw bytes before decoding.
 *
 * @param yamlContent - Already-decoded YAML string
-* @throws Error if BOM prefix detected
+* @throws EncodingError if BOM prefix detected
 */
 function validateNoBomPrefix(yamlContent) {
-	if (yamlContent.charCodeAt(0) === 65279) throw new Error("UTF-8 BOM detected in Deepnote file - files must be UTF-8 without BOM");
+	if (yamlContent.charCodeAt(0) === 65279) throw new EncodingError("UTF-8 BOM detected in Deepnote file - files must be UTF-8 without BOM");
 }
 /**
 * Validates that the YAML document doesn't contain prohibited features:
@@ -465,13 +583,13 @@ function validateNoBomPrefix(yamlContent) {
 * - No custom tags (!tag)
 */
 function validateYamlStructure(yamlContent) {
-	if (/(?:^|\n)\s*(?:-\s+|[\w-]+:\s*)&\w+/.test(yamlContent)) throw new Error("YAML anchors (&) are not allowed in Deepnote files");
-	if (/(?:^|\n)\s*(?:-\s+|[\w-]+:\s*)\*\w+/.test(yamlContent)) throw new Error("YAML aliases (*) are not allowed in Deepnote files");
-	if (/<<:/.test(yamlContent)) throw new Error("YAML merge keys (<<) are not allowed in Deepnote files");
+	if (/(?:^|\n)\s*(?:-\s+|[\w-]+:\s*)&\w+/.test(yamlContent)) throw new ProhibitedYamlFeatureError("YAML anchors (&) are not allowed in Deepnote files", { feature: "anchor" });
+	if (/(?:^|\n)\s*(?:-\s+|[\w-]+:\s*)\*\w+/.test(yamlContent)) throw new ProhibitedYamlFeatureError("YAML aliases (*) are not allowed in Deepnote files", { feature: "alias" });
+	if (/<<:/.test(yamlContent)) throw new ProhibitedYamlFeatureError("YAML merge keys (<<) are not allowed in Deepnote files", { feature: "merge-key" });
 	const matches = yamlContent.match(/(?:^|\n)\s*(?:-\s+|[\w-]+:\s*)(![\w/-]+)/gm);
 	if (matches) {
 		const tags = matches.map((m) => m.match(/(![\w/-]+)/)?.[1]).filter(Boolean);
-		if (tags.length > 0) throw new Error(`YAML tags are not allowed in Deepnote files: ${tags.join(", ")}`);
+		if (tags.length > 0) throw new ProhibitedYamlFeatureError(`YAML tags are not allowed in Deepnote files: ${tags.join(", ")}`, { feature: "tag" });
 	}
 }
 /**
@@ -486,8 +604,8 @@ function parseAndValidate(yamlContent) {
 	});
 	if (doc.errors.length > 0) {
 		const duplicateKeyError = doc.errors.find((err) => err.message.includes("duplicate") || err.message.includes("key"));
-		if (duplicateKeyError) throw new Error(`Duplicate keys detected in Deepnote file: ${duplicateKeyError.message}`);
-		throw new Error(`YAML parsing error: ${doc.errors[0].message}`);
+		if (duplicateKeyError) throw new YamlParseError(`Duplicate keys detected in Deepnote file: ${duplicateKeyError.message}`);
+		throw new YamlParseError(`YAML parsing error: ${doc.errors[0].message}`);
 	}
 	return doc.toJS();
 }
@@ -506,8 +624,8 @@ function parseYaml(yamlContent) {
 		validateYamlStructure(yamlContent);
 		return parseAndValidate(yamlContent);
 	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		throw new Error(`Failed to parse Deepnote file: ${message}`);
+		if (error instanceof DeepnoteError) throw error;
+		throw new ParseError(`Failed to parse Deepnote file: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
 	}
 }
 
@@ -521,23 +639,13 @@ function deserializeDeepnoteFile(yamlContent) {
 	const result = deepnoteFileSchema.safeParse(parsed);
 	if (!result.success) {
 		const issue = result.error.issues[0];
-		if (!issue) throw new Error("Invalid Deepnote file.");
+		if (!issue) throw new SchemaValidationError("Invalid Deepnote file.");
 		const path = issue.path.join(".");
-		const message = path ? `${path}: ${issue.message}` : issue.message;
-		throw new Error(`Failed to parse the Deepnote file: ${message}.`);
+		throw new SchemaValidationError(`Failed to parse the Deepnote file: ${path ? `${path}: ${issue.message}` : issue.message}.`);
 	}
 	return result.data;
 }
 
-//#endregion
-//#region src/blocks.ts
-var UnsupportedBlockTypeError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "UnsupportedBlockTypeError";
-	}
-};
-
 //#endregion
 //#region src/blocks/image-blocks.ts
 function escapeHtmlAttribute(value) {
@@ -585,7 +693,7 @@ function createMarkdownForTextBlock(block) {
 	if (block.type === "text-cell-todo") return `- ${block.metadata?.checked ? "[x]" : "[ ]"} ${escapeMarkdown(content)}`;
 	if (block.type === "text-cell-callout") return `> ${escapeMarkdown(content)}`;
 	if (block.type === "text-cell-p") return escapeMarkdown(content);
-	throw new Error("Unhandled block type.");
+	throw new UnsupportedBlockTypeError("Unhandled block type.");
 }
 function stripMarkdownFromTextBlock(block) {
 	const content = block.content ?? "";
@@ -596,7 +704,7 @@ function stripMarkdownFromTextBlock(block) {
 	if (block.type === "text-cell-todo") return content.replace(/^-+\s+\[.\]\s+/, "").trim();
 	if (block.type === "text-cell-callout") return content.replace(/^>\s+/, "").trim();
 	if (block.type === "text-cell-p") return content.trim();
-	throw new Error("Unhandled block type.");
+	throw new UnsupportedBlockTypeError("Unhandled block type.");
 }
 function createMarkdownForSeparatorBlock(_block) {
 	return "<hr>";
@@ -870,9 +978,9 @@ function createPythonCodeForInputSelectBlock(block) {
 function createPythonCodeForInputSliderBlock(block) {
 	const sanitizedPythonVariableName = sanitizePythonVariableName(block.metadata.deepnote_variable_name);
 	const value = block.metadata.deepnote_variable_value;
-	if (!/^-?\d+\.?\d*$|^-?\d*\.\d+$/.test(value)) throw new Error(`Invalid numeric value for slider input: "${value}". Expected a valid number (integer or float).`);
+	if (!/^-?\d+\.?\d*$|^-?\d*\.\d+$/.test(value)) throw new InvalidValueError(`Invalid numeric value for slider input: "${value}". Expected a valid number (integer or float).`, { value });
 	const numericValue = Number(value);
-	if (!Number.isFinite(numericValue)) throw new Error(`Invalid numeric value for slider input: "${value}". Value must be finite.`);
+	if (!Number.isFinite(numericValue)) throw new InvalidValueError(`Invalid numeric value for slider input: "${value}". Value must be finite.`, { value });
 	return `${sanitizedPythonVariableName} = ${numericValue}`;
 }
 function createPythonCodeForInputFileBlock(block) {
@@ -906,7 +1014,7 @@ function createPythonCodeForInputDateRangeBlock(block) {
 		return pythonCode.dateRangeCustomDays(sanitizedPythonVariableName, Number(customDays));
 	} else if (isValidRelativeDateInterval(block.metadata.deepnote_variable_value)) {
 		const range = DATE_RANGE_INPUT_RELATIVE_RANGES.find((range$1) => range$1.value === block.metadata.deepnote_variable_value);
-		if (!range) throw new Error(`Invalid relative date interval: "${block.metadata.deepnote_variable_value}". Expected one of: ${DATE_RANGE_INPUT_RELATIVE_RANGES.map((r) => r.value).join(", ")}.`);
+		if (!range) throw new InvalidValueError(`Invalid relative date interval: "${block.metadata.deepnote_variable_value}". Expected one of: ${DATE_RANGE_INPUT_RELATIVE_RANGES.map((r) => r.value).join(", ")}.`, { value: block.metadata.deepnote_variable_value });
 		return ts_dedent.dedent`
       ${range.pythonCode(sanitizedPythonVariableName)}`;
 	} else return ts_dedent.dedent`
@@ -939,12 +1047,50 @@ function isInputDateRangeBlock(block) {
 }
 
 //#endregion
-//#region src/blocks/sql-utils.ts
-function convertToEnvironmentVariableName(str) {
-	return (/^\d/.test(str) ? `_${str}` : str).toUpperCase().replace(/[^\w]/g, "_");
+//#region src/blocks/notebook-function-blocks.ts
+function isNotebookFunctionBlock(block) {
+	return block.type === "notebook-function";
 }
-function getSqlEnvVarName(integrationId) {
-	return `SQL_${integrationId}`;
+function createPythonCodeForNotebookFunctionBlock(block) {
+	const notebookId = block.metadata?.function_notebook_id;
+	const inputs = block.metadata?.function_notebook_inputs ?? {};
+	const exportMappings = block.metadata?.function_notebook_export_mappings ?? {};
+	if (!notebookId) return ts_dedent.dedent`
+      # Notebook Function: Not configured
+      pass
+    `;
+	const enabledExports = Object.entries(exportMappings).filter(([, mapping]) => mapping.enabled);
+	const inputsAsString = JSON.stringify(inputs);
+	const exportMappingsDict = {};
+	for (const [exportName, mapping] of enabledExports) exportMappingsDict[exportName] = mapping.variable_name;
+	const exportMappingsAsString = JSON.stringify(exportMappingsDict);
+	const inputsComment = `Inputs: ${inputsAsString}`;
+	const exportsComment = enabledExports.length > 0 ? `Exports: ${enabledExports.map(([name, mapping]) => `${name} -> ${mapping.variable_name}`).join(", ")}` : "Exports: (none)";
+	const functionCall = ts_dedent.dedent`
+    _dntk.run_notebook_function(
+        ${escapePythonString(notebookId)},
+        inputs=${inputsAsString},
+        export_mappings=${exportMappingsAsString}
+    )
+  `;
+	if (enabledExports.length === 0) return ts_dedent.dedent`
+      # Notebook Function: ${notebookId}
+      # ${inputsComment}
+      # ${exportsComment}
+      ${functionCall}
+    `;
+	if (enabledExports.length === 1) return ts_dedent.dedent`
+      # Notebook Function: ${notebookId}
+      # ${inputsComment}
+      # ${exportsComment}
+      ${enabledExports[0][1]?.variable_name} = ${functionCall}
+    `;
+	return ts_dedent.dedent`
+    # Notebook Function: ${notebookId}
+    # ${inputsComment}
+    # ${exportsComment}
+    ${enabledExports.map(([, mapping]) => mapping.variable_name).join(", ")} = ${functionCall}
+  `;
 }
 
 //#endregion
@@ -1013,18 +1159,34 @@ function createPythonCode(block, executionContext) {
 	if (isVisualizationBlock(block)) return createPythonCodeForVisualizationBlock(block);
 	if (isButtonBlock(block)) return createPythonCodeForButtonBlock(block, executionContext);
 	if (isBigNumberBlock(block)) return createPythonCodeForBigNumberBlock(block);
+	if (isNotebookFunctionBlock(block)) return createPythonCodeForNotebookFunctionBlock(block);
 	throw new UnsupportedBlockTypeError(`Creating python code from block type ${block.type} is not supported yet.`);
 }
 
 //#endregion
+exports.DeepnoteError = DeepnoteError;
+exports.EncodingError = EncodingError;
+exports.INPUT_BLOCK_TYPES = INPUT_BLOCK_TYPES;
+exports.InvalidValueError = InvalidValueError;
+exports.ParseError = ParseError;
+exports.ProhibitedYamlFeatureError = ProhibitedYamlFeatureError;
+exports.SchemaValidationError = SchemaValidationError;
+exports.UnsupportedBlockTypeError = UnsupportedBlockTypeError;
+exports.YamlParseError = YamlParseError;
+exports.convertToEnvironmentVariableName = convertToEnvironmentVariableName;
 exports.createMarkdown = createMarkdown;
 exports.createPythonCode = createPythonCode;
 exports.decodeUtf8NoBom = decodeUtf8NoBom;
 exports.deepnoteBlockSchema = deepnoteBlockSchema;
 exports.deepnoteFileSchema = deepnoteFileSchema;
+exports.deepnoteSnapshotSchema = deepnoteSnapshotSchema;
 exports.deserializeDeepnoteFile = deserializeDeepnoteFile;
 exports.environmentSchema = environmentSchema;
 exports.executionErrorSchema = executionErrorSchema;
 exports.executionSchema = executionSchema;
 exports.executionSummarySchema = executionSummarySchema;
+exports.getSqlEnvVarName = getSqlEnvVarName;
+exports.isExecutableBlock = isExecutableBlock;
+exports.isExecutableBlockType = isExecutableBlockType;
+exports.parseYaml = parseYaml;
 exports.stripMarkdown = stripMarkdown;