@deepnote/blocks 3.2.1 → 4.0.0

package/dist/index.cjs

@@ -28,23 +28,70 @@ yaml = __toESM(yaml);
 let ts_dedent = require("ts-dedent");
 ts_dedent = __toESM(ts_dedent);
 
-//#region src/blocks.ts
-var UnsupportedBlockTypeError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "UnsupportedBlockTypeError";
+//#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
-const executableBlockTypes = new Set([
-	"code",
-	"sql",
-	"notebook-function",
-	"visualization",
-	"button",
-	"big-number",
+/**
+* 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",
@@ -54,6 +101,15 @@ const executableBlockTypes = new Set([
 	"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.
@@ -69,6 +125,15 @@ 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 */
@@ -482,7 +547,7 @@ const deepnoteSnapshotSchema = deepnoteFileSchema.extend({
 *
 * @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
@@ -492,11 +557,11 @@ const deepnoteSnapshotSchema = deepnoteFileSchema.extend({
 * ```
 */
 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");
 	}
 }
 /**
@@ -506,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:
@@ -518,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" });
 	}
 }
 /**
@@ -539,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();
 }
@@ -559,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 });
 	}
 }
 
@@ -574,10 +639,9 @@ 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;
 }
@@ -629,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 ?? "";
@@ -640,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>";
@@ -914,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) {
@@ -950,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`
@@ -1029,15 +1093,6 @@ function createPythonCodeForNotebookFunctionBlock(block) {
   `;
 }
 
-//#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/blocks/sql-blocks.ts
 function createPythonCodeForSqlBlock(block) {
@@ -1109,7 +1164,16 @@ function createPythonCode(block, executionContext) {
 }
 
 //#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;
@@ -1121,6 +1185,7 @@ exports.environmentSchema = environmentSchema;
 exports.executionErrorSchema = executionErrorSchema;
 exports.executionSchema = executionSchema;
 exports.executionSummarySchema = executionSummarySchema;
+exports.getSqlEnvVarName = getSqlEnvVarName;
 exports.isExecutableBlock = isExecutableBlock;
 exports.isExecutableBlockType = isExecutableBlockType;
 exports.parseYaml = parseYaml;

package/dist/index.d.cts

@@ -1,8 +1,55 @@
 import { z } from "zod";
 
-//#region src/blocks.d.ts
-declare class UnsupportedBlockTypeError extends Error {
-  constructor(message: string);
+//#region src/errors.d.ts
+/**
+ * Base error class for all Deepnote errors.
+ */
+declare class DeepnoteError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Generic parse failure, optionally associated with a file path.
+ */
+declare class ParseError extends DeepnoteError {
+  filePath?: string;
+  constructor(message: string, options?: ErrorOptions & {
+    filePath?: string;
+  });
+}
+/**
+ * YAML syntax or duplicate key errors.
+ */
+declare class YamlParseError extends ParseError {}
+/**
+ * BOM or invalid UTF-8 encoding errors.
+ */
+declare class EncodingError extends ParseError {}
+/**
+ * Zod schema validation failures.
+ */
+declare class SchemaValidationError extends ParseError {}
+/**
+ * Prohibited YAML features: anchors, aliases, merge keys, tags.
+ */
+declare class ProhibitedYamlFeatureError extends ParseError {
+  feature: string;
+  constructor(message: string, options: ErrorOptions & {
+    feature: string;
+    filePath?: string;
+  });
+}
+/**
+ * Thrown when a block type is not supported.
+ */
+declare class UnsupportedBlockTypeError extends DeepnoteError {}
+/**
+ * Thrown when a value is invalid (e.g., slider value, date interval).
+ */
+declare class InvalidValueError extends DeepnoteError {
+  value: unknown;
+  constructor(message: string, options: ErrorOptions & {
+    value: unknown;
+  });
 }
 //#endregion
 //#region src/deserialize-file/deepnote-file-schema.d.ts
@@ -23417,6 +23464,11 @@ declare const deepnoteSnapshotSchema: z.ZodObject<{
 type DeepnoteSnapshot = z.infer<typeof deepnoteSnapshotSchema>;
 //#endregion
 //#region src/blocks/executable-blocks.d.ts
+/**
+ * Block types that represent user input widgets.
+ * These blocks capture user input and define variables.
+ */
+declare const INPUT_BLOCK_TYPES: Set<string>;
 /**
  * Type guard to check if a block is an executable block.
  * Executable blocks can have outputs and be executed by the runtime.
@@ -23428,6 +23480,10 @@ declare function isExecutableBlock(block: DeepnoteBlock): block is ExecutableBlo
  */
 declare function isExecutableBlockType(type: string): boolean;
 //#endregion
+//#region src/blocks/sql-utils.d.ts
+declare function convertToEnvironmentVariableName(str: string): string;
+declare function getSqlEnvVarName(integrationId: string): string;
+//#endregion
 //#region src/blocks/table-state.d.ts
 interface TableState {
   cellFormattingRules?: {
@@ -23467,7 +23523,7 @@ declare function deserializeDeepnoteFile(yamlContent: string): DeepnoteFile;
  *
  * @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
@@ -23504,4 +23560,4 @@ interface ButtonExecutionContext {
 //#region src/python-code.d.ts
 declare function createPythonCode(block: DeepnoteBlock, executionContext?: ButtonExecutionContext): string;
 //#endregion
-export { type DeepnoteBlock, type DeepnoteFile, type DeepnoteSnapshot, type Environment, type ExecutableBlock, type Execution, type ExecutionError, type ExecutionSummary, type TableState, UnsupportedBlockTypeError, createMarkdown, createPythonCode, decodeUtf8NoBom, deepnoteBlockSchema, deepnoteFileSchema, deepnoteSnapshotSchema, deserializeDeepnoteFile, environmentSchema, executionErrorSchema, executionSchema, executionSummarySchema, isExecutableBlock, isExecutableBlockType, parseYaml, stripMarkdown };
+export { type DeepnoteBlock, DeepnoteError, type DeepnoteFile, type DeepnoteSnapshot, EncodingError, type Environment, type ExecutableBlock, type Execution, type ExecutionError, type ExecutionSummary, INPUT_BLOCK_TYPES, InvalidValueError, ParseError, ProhibitedYamlFeatureError, SchemaValidationError, type TableState, UnsupportedBlockTypeError, YamlParseError, convertToEnvironmentVariableName, createMarkdown, createPythonCode, decodeUtf8NoBom, deepnoteBlockSchema, deepnoteFileSchema, deepnoteSnapshotSchema, deserializeDeepnoteFile, environmentSchema, executionErrorSchema, executionSchema, executionSummarySchema, getSqlEnvVarName, isExecutableBlock, isExecutableBlockType, parseYaml, stripMarkdown };

package/dist/index.d.ts

@@ -1,8 +1,55 @@
 import { z } from "zod";
 
-//#region src/blocks.d.ts
-declare class UnsupportedBlockTypeError extends Error {
-  constructor(message: string);
+//#region src/errors.d.ts
+/**
+ * Base error class for all Deepnote errors.
+ */
+declare class DeepnoteError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Generic parse failure, optionally associated with a file path.
+ */
+declare class ParseError extends DeepnoteError {
+  filePath?: string;
+  constructor(message: string, options?: ErrorOptions & {
+    filePath?: string;
+  });
+}
+/**
+ * YAML syntax or duplicate key errors.
+ */
+declare class YamlParseError extends ParseError {}
+/**
+ * BOM or invalid UTF-8 encoding errors.
+ */
+declare class EncodingError extends ParseError {}
+/**
+ * Zod schema validation failures.
+ */
+declare class SchemaValidationError extends ParseError {}
+/**
+ * Prohibited YAML features: anchors, aliases, merge keys, tags.
+ */
+declare class ProhibitedYamlFeatureError extends ParseError {
+  feature: string;
+  constructor(message: string, options: ErrorOptions & {
+    feature: string;
+    filePath?: string;
+  });
+}
+/**
+ * Thrown when a block type is not supported.
+ */
+declare class UnsupportedBlockTypeError extends DeepnoteError {}
+/**
+ * Thrown when a value is invalid (e.g., slider value, date interval).
+ */
+declare class InvalidValueError extends DeepnoteError {
+  value: unknown;
+  constructor(message: string, options: ErrorOptions & {
+    value: unknown;
+  });
 }
 //#endregion
 //#region src/deserialize-file/deepnote-file-schema.d.ts
@@ -23417,6 +23464,11 @@ declare const deepnoteSnapshotSchema: z.ZodObject<{
 type DeepnoteSnapshot = z.infer<typeof deepnoteSnapshotSchema>;
 //#endregion
 //#region src/blocks/executable-blocks.d.ts
+/**
+ * Block types that represent user input widgets.
+ * These blocks capture user input and define variables.
+ */
+declare const INPUT_BLOCK_TYPES: Set<string>;
 /**
  * Type guard to check if a block is an executable block.
  * Executable blocks can have outputs and be executed by the runtime.
@@ -23428,6 +23480,10 @@ declare function isExecutableBlock(block: DeepnoteBlock): block is ExecutableBlo
  */
 declare function isExecutableBlockType(type: string): boolean;
 //#endregion
+//#region src/blocks/sql-utils.d.ts
+declare function convertToEnvironmentVariableName(str: string): string;
+declare function getSqlEnvVarName(integrationId: string): string;
+//#endregion
 //#region src/blocks/table-state.d.ts
 interface TableState {
   cellFormattingRules?: {
@@ -23467,7 +23523,7 @@ declare function deserializeDeepnoteFile(yamlContent: string): DeepnoteFile;
  *
  * @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
@@ -23504,4 +23560,4 @@ interface ButtonExecutionContext {
 //#region src/python-code.d.ts
 declare function createPythonCode(block: DeepnoteBlock, executionContext?: ButtonExecutionContext): string;
 //#endregion
-export { type DeepnoteBlock, type DeepnoteFile, type DeepnoteSnapshot, type Environment, type ExecutableBlock, type Execution, type ExecutionError, type ExecutionSummary, type TableState, UnsupportedBlockTypeError, createMarkdown, createPythonCode, decodeUtf8NoBom, deepnoteBlockSchema, deepnoteFileSchema, deepnoteSnapshotSchema, deserializeDeepnoteFile, environmentSchema, executionErrorSchema, executionSchema, executionSummarySchema, isExecutableBlock, isExecutableBlockType, parseYaml, stripMarkdown };
+export { type DeepnoteBlock, DeepnoteError, type DeepnoteFile, type DeepnoteSnapshot, EncodingError, type Environment, type ExecutableBlock, type Execution, type ExecutionError, type ExecutionSummary, INPUT_BLOCK_TYPES, InvalidValueError, ParseError, ProhibitedYamlFeatureError, SchemaValidationError, type TableState, UnsupportedBlockTypeError, YamlParseError, convertToEnvironmentVariableName, createMarkdown, createPythonCode, decodeUtf8NoBom, deepnoteBlockSchema, deepnoteFileSchema, deepnoteSnapshotSchema, deserializeDeepnoteFile, environmentSchema, executionErrorSchema, executionSchema, executionSummarySchema, getSqlEnvVarName, isExecutableBlock, isExecutableBlockType, parseYaml, stripMarkdown };

package/dist/index.js

@@ -2,23 +2,70 @@ import { z } from "zod";
 import { parseDocument } from "yaml";
 import { dedent } from "ts-dedent";
 
-//#region src/blocks.ts
-var UnsupportedBlockTypeError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "UnsupportedBlockTypeError";
+//#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
-const executableBlockTypes = new Set([
-	"code",
-	"sql",
-	"notebook-function",
-	"visualization",
-	"button",
-	"big-number",
+/**
+* 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",
@@ -28,6 +75,15 @@ const executableBlockTypes = new Set([
 	"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.
@@ -43,6 +99,15 @@ 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 */
@@ -456,7 +521,7 @@ const deepnoteSnapshotSchema = deepnoteFileSchema.extend({
 *
 * @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
@@ -466,11 +531,11 @@ const deepnoteSnapshotSchema = deepnoteFileSchema.extend({
 * ```
 */
 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");
 	}
 }
 /**
@@ -480,10 +545,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:
@@ -492,13 +557,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" });
 	}
 }
 /**
@@ -513,8 +578,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();
 }
@@ -533,8 +598,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 });
 	}
 }
 
@@ -548,10 +613,9 @@ 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;
 }
@@ -603,7 +667,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 ?? "";
@@ -614,7 +678,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>";
@@ -888,9 +952,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) {
@@ -924,7 +988,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 dedent`
       ${range.pythonCode(sanitizedPythonVariableName)}`;
 	} else return dedent`
@@ -1003,15 +1067,6 @@ function createPythonCodeForNotebookFunctionBlock(block) {
   `;
 }
 
-//#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/blocks/sql-blocks.ts
 function createPythonCodeForSqlBlock(block) {
@@ -1083,4 +1138,4 @@ function createPythonCode(block, executionContext) {
 }
 
 //#endregion
-export { UnsupportedBlockTypeError, createMarkdown, createPythonCode, decodeUtf8NoBom, deepnoteBlockSchema, deepnoteFileSchema, deepnoteSnapshotSchema, deserializeDeepnoteFile, environmentSchema, executionErrorSchema, executionSchema, executionSummarySchema, isExecutableBlock, isExecutableBlockType, parseYaml, stripMarkdown };
+export { DeepnoteError, EncodingError, INPUT_BLOCK_TYPES, InvalidValueError, ParseError, ProhibitedYamlFeatureError, SchemaValidationError, UnsupportedBlockTypeError, YamlParseError, convertToEnvironmentVariableName, createMarkdown, createPythonCode, decodeUtf8NoBom, deepnoteBlockSchema, deepnoteFileSchema, deepnoteSnapshotSchema, deserializeDeepnoteFile, environmentSchema, executionErrorSchema, executionSchema, executionSummarySchema, getSqlEnvVarName, isExecutableBlock, isExecutableBlockType, parseYaml, stripMarkdown };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepnote/blocks",
-  "version": "3.2.1",
+  "version": "4.0.0",
   "description": "",
   "keywords": [],
   "repository": {