svedit 0.9.0 → 0.10.0

package/src/lib/doc_utils.js

@@ -4,17 +4,23 @@
  * These functions operate on the core document state (schema, doc, selection, config)
  * without any history management or transaction tracking.
  *
- * @import { NodeId, DocumentPath, PrimitiveType, NodeProperty, NodeArrayProperty, NodeSchema, DocumentSchema, Selection, Annotation, Document } from './types'
+ * @import { NodeId, DocumentPath, PrimitiveType, NodeProperty, NodeArrayProperty, NodeSchema, DocumentSchema, Selection, Annotation, Document, AnnotatedTextProperty, AnnotatedText, ValidateDocumentSchema } from './types'
  */
 
-import { get_selection_range, get_char_length } from './utils.js';
+import {
+	assert_path_string_segment,
+	is_path_string_segment_valid,
+	get_selection_range,
+	get_char_length,
+	serialize_path
+} from './utils.js';
 
 /**
  * Identity function — keeps schema at runtime & makes IDE infer types.
  * Similar to your define_schema pattern but for document schemas.
  *
  * @template {Record<string, NodeSchema>} S
- * @param {S} schema - The document schema to validate
+ * @param {S & ValidateDocumentSchema<S>} schema - The document schema to validate
  * @returns {S} The same schema, but with type information preserved
  */
 export function define_document_schema(schema) {
@@ -57,6 +63,84 @@ export function get_default_node_type(property_definition) {
 	);
 }
 
+/**
+ * @param {import('./types').PropertyDefinition} property_definition
+ * @returns {any}
+ */
+function get_property_default(property_definition) {
+	if ('default' in property_definition) return structuredClone(property_definition.default);
+
+	if (property_definition.type === 'string') return '';
+	if (property_definition.type === 'integer') return 0;
+	if (property_definition.type === 'number') return 0;
+	if (property_definition.type === 'boolean') return false;
+	if (property_definition.type === 'annotated_text') return { text: '', annotations: [] };
+	if (property_definition.type === 'node_array') return [];
+	if (
+		property_definition.type === 'string_array' ||
+		property_definition.type === 'number_array' ||
+		property_definition.type === 'boolean_array' ||
+		property_definition.type === 'integer_array'
+	) {
+		return [];
+	}
+
+	return undefined;
+}
+
+/**
+ * Fill omitted properties with schema defaults and Svedit's built-in type defaults.
+ *
+ * This is a convenience helper for schema evolution, not a complete document
+ * migration system. Callers are still responsible for proper migrations when
+ * schema changes cannot be represented by defaults, such as property renames or
+ * data transformations.
+ *
+ * @param {any} node - The node to fill defaults for
+ * @param {DocumentSchema} schema - The document schema
+ * @returns {any} A shallow copy of the node with cloned default values filled in
+ */
+export function fill_node_defaults(node, schema) {
+	const node_schema = schema[node.type];
+	if (!node_schema) return { ...node };
+
+	const node_with_defaults = { ...node };
+
+	for (const [property_name, property_definition] of Object.entries(node_schema.properties)) {
+		if (node_with_defaults[property_name] === undefined) {
+			const property_default = get_property_default(property_definition);
+			if (property_default !== undefined) node_with_defaults[property_name] = property_default;
+		}
+	}
+
+	return node_with_defaults;
+}
+
+/**
+ * Fill omitted properties with schema defaults and Svedit's built-in type defaults across a document.
+ *
+ * This does not infer values, rename fields, or make an invalid migration valid
+ * by itself. Call this as one step in an explicit document migration when it is
+ * appropriate.
+ *
+ * @param {Document} doc - The document to fill defaults for
+ * @param {DocumentSchema} schema - The document schema
+ * @returns {Document} A document copy with cloned default values filled in
+ */
+export function fill_document_defaults(doc, schema) {
+	/** @type {Record<string, any>} */
+	const nodes = {};
+
+	for (const [node_id, node] of Object.entries(doc.nodes)) {
+		nodes[node_id] = fill_node_defaults(node, schema);
+	}
+
+	return {
+		...doc,
+		nodes
+	};
+}
+
 /**
  * Validate a document schema to ensure all referenced node types exist.
  * @param {DocumentSchema} document_schema - The document schema to validate
@@ -66,6 +150,7 @@ export function validate_document_schema(document_schema) {
 	// Check that all referenced node types exist
 	for (const [node_type, node_schema] of Object.entries(document_schema)) {
 		for (const [prop_name, prop_def] of Object.entries(node_schema.properties)) {
+			assert_path_string_segment(prop_name, `Property name "${prop_name}"`);
 			if (prop_def.type === 'node' || prop_def.type === 'node_array') {
 				const missing_types = prop_def.node_types.filter(
 					(ref_type) => !(ref_type in document_schema)
@@ -118,12 +203,88 @@ function validate_primitive_value(type, value) {
 	}
 }
 
+/**
+ * Validate annotated text annotations for bounds, references, allowed types, and exclusivity.
+ *
+ * @param {string} node_id - Owner node id, used for error messages
+ * @param {string} prop_name - Owner property name, used for error messages
+ * @param {AnnotatedText} value - Annotated text value to validate
+ * @param {AnnotatedTextProperty} prop_def - Annotated text property definition
+ * @param {Record<string, any>} all_nodes - All document nodes
+ * @param {boolean} require_references - Whether referenced nodes must already exist
+ * @throws {Error} Throws if annotations are invalid
+ */
+function validate_annotated_text_property(node_id, prop_name, value, prop_def, all_nodes, require_references) {
+	const char_length = get_char_length(value.text);
+	const annotations = value.annotations;
+
+	for (const [index, annotation] of annotations.entries()) {
+		if (
+			typeof annotation !== 'object' ||
+			annotation === null ||
+			!Number.isInteger(annotation.start_offset) ||
+			!Number.isInteger(annotation.end_offset) ||
+			!is_id_valid(annotation.node_id)
+		) {
+			throw new Error(
+				`Node ${node_id} property ${prop_name} has an invalid annotation at index ${index}. Annotations must have integer start_offset/end_offset and a valid node_id.`
+			);
+		}
+
+		if (annotation.start_offset < 0 || annotation.end_offset > char_length) {
+			throw new Error(
+				`Node ${node_id} property ${prop_name} annotation ${annotation.node_id} is out of bounds: ${annotation.start_offset}-${annotation.end_offset}, text length is ${char_length}.`
+			);
+		}
+
+		if (annotation.start_offset >= annotation.end_offset) {
+			throw new Error(
+				`Node ${node_id} property ${prop_name} annotation ${annotation.node_id} must not be empty or reversed: ${annotation.start_offset}-${annotation.end_offset}.`
+			);
+		}
+
+		const referenced_node = all_nodes[annotation.node_id];
+		if (!referenced_node) {
+			if (require_references) {
+				throw new Error(
+					`Node ${node_id} property ${prop_name} annotation references missing node ${annotation.node_id}.`
+				);
+			}
+			continue;
+		}
+
+		if (prop_def.node_types?.length && !prop_def.node_types.includes(referenced_node.type)) {
+			throw new Error(
+				`Node ${node_id} property ${prop_name} annotation references node ${annotation.node_id} of type ${referenced_node.type}, but only types [${prop_def.node_types.join(', ')}] are allowed.`
+			);
+		}
+	}
+
+	const sorted_annotations = annotations
+		.map((annotation, index) => ({ annotation, index }))
+		.sort((a, b) =>
+			a.annotation.start_offset - b.annotation.start_offset ||
+			a.annotation.end_offset - b.annotation.end_offset
+		);
+
+	for (let index = 1; index < sorted_annotations.length; index++) {
+		const previous = sorted_annotations[index - 1];
+		const current = sorted_annotations[index];
+
+		if (current.annotation.start_offset < previous.annotation.end_offset) {
+			throw new Error(
+				`Node ${node_id} property ${prop_name} has overlapping annotations: annotation index ${previous.index} (${previous.annotation.node_id}, ${previous.annotation.start_offset}-${previous.annotation.end_offset}) overlaps annotation index ${current.index} (${current.annotation.node_id}, ${current.annotation.start_offset}-${current.annotation.end_offset}). Annotations must be exclusive.`
+			);
+		}
+	}
+}
+
 /**
  * @param {string} id
  * @returns {boolean}
  */
-function is_id_valid(id) {
-	return typeof id === 'string' && id.length > 0;
+export function is_id_valid(id) {
+	return typeof id === 'string' && id.length > 0 && is_path_string_segment_valid(id);
 }
 
 /**
@@ -131,9 +292,11 @@ function is_id_valid(id) {
  * @param {any} node - The node to validate
  * @param {DocumentSchema} schema - The document schema
  * @param {Record<string, any>} all_nodes - All nodes in the document to check references
+ * @param {{ require_references?: boolean }} [options] - Validation options
  * @throws {Error} Throws if the node is invalid
  */
-export function validate_node(node, schema, all_nodes = {}) {
+export function validate_node(node, schema, all_nodes = {}, options = {}) {
+	const require_references = options.require_references ?? true;
 	if (!is_id_valid(node.id)) {
 		throw new Error(`Node ${node.id} has an invalid id.`);
 	}
@@ -155,6 +318,16 @@ export function validate_node(node, schema, all_nodes = {}) {
 				);
 			}
 		}
+		if (prop_def.type === 'annotated_text') {
+			validate_annotated_text_property(
+				node.id,
+				prop_name,
+				value,
+				/** @type {AnnotatedTextProperty} */ (prop_def),
+				all_nodes,
+				require_references
+			);
+		}
 		// Check node references
 		if (prop_def.type === 'node') {
 			if (!is_id_valid(value)) {
@@ -164,7 +337,15 @@ export function validate_node(node, schema, all_nodes = {}) {
 			}
 			// Check if referenced node exists and is of allowed type
 			const referenced_node = all_nodes[value];
-			if (referenced_node && !prop_def.node_types.includes(referenced_node.type)) {
+			if (!referenced_node) {
+				if (require_references) {
+					throw new Error(
+						`Node ${node.id} property ${prop_name} references missing node ${value}.`
+					);
+				}
+				continue;
+			}
+			if (!prop_def.node_types.includes(referenced_node.type)) {
 				throw new Error(
 					`Node ${node.id} property ${prop_name} references node ${value} of type ${referenced_node.type}, but only types [${/** @type {NodeProperty} */ (prop_def).node_types.join(', ')}] are allowed.`
 				);
@@ -180,10 +361,18 @@ export function validate_node(node, schema, all_nodes = {}) {
 					`Node ${node.id} has an invalid property: ${prop_name} must be an array of node ids.`
 				);
 			}
-			// Check if all referenced nodes are of allowed types
+			// Check if all referenced nodes exist and are of allowed types
 			for (const ref_id of value) {
 				const referenced_node = all_nodes[ref_id];
-				if (referenced_node && !prop_def.node_types.includes(referenced_node.type)) {
+				if (!referenced_node) {
+					if (require_references) {
+						throw new Error(
+							`Node ${node.id} property ${prop_name} references missing node ${ref_id}.`
+						);
+					}
+					continue;
+				}
+				if (!prop_def.node_types.includes(referenced_node.type)) {
 					throw new Error(
 						`Node ${node.id} property ${prop_name} references node ${ref_id} of type ${referenced_node.type}, but only types [${prop_def.node_types.join(', ')}] are allowed.`
 					);
@@ -193,6 +382,22 @@ export function validate_node(node, schema, all_nodes = {}) {
 	}
 }
 
+/**
+ * Validate a document against its schema.
+ *
+ * @param {Document} doc - The document to validate
+ * @param {DocumentSchema} schema - The document schema
+ * @throws {Error} Throws if the document is invalid
+ */
+export function validate_document(doc, schema) {
+	if (!is_id_valid(doc.document_id)) {
+		throw new Error(`Document ${doc.document_id} has an invalid id.`);
+	}
+	for (const node of Object.values(doc.nodes)) {
+		validate_node(node, schema, doc.nodes);
+	}
+}
+
 /**
  * Gets a value from the document at the specified path.
  *
@@ -310,6 +515,31 @@ export function kind(schema, node) {
 	return schema[node.type].kind;
 }
 
+/**
+ * Checks whether an annotation node can be switched to another annotation type
+ * without losing data.
+ *
+ * @param {DocumentSchema} schema - The document schema
+ * @param {any} annotation_node - The annotation node to switch
+ * @param {string} target_annotation_type - The target annotation type
+ * @returns {boolean} True if the annotation can be switched safely
+ */
+export function can_switch_annotation_type(schema, annotation_node, target_annotation_type) {
+	if (!annotation_node || annotation_node.type === target_annotation_type) return false;
+
+	const source_schema = schema[annotation_node.type];
+	const target_schema = schema[target_annotation_type];
+	if (source_schema?.kind !== 'annotation' || target_schema?.kind !== 'annotation') return false;
+
+	const source_has_properties = Object.keys(source_schema.properties ?? {}).length > 0;
+	const target_has_properties = Object.keys(target_schema.properties ?? {}).length > 0;
+	if (source_has_properties || target_has_properties) return false;
+
+	// eslint-disable-next-line no-unused-vars
+	const { id, type, ...extra_properties } = annotation_node;
+	return Object.keys(extra_properties).length === 0;
+}
+
 /**
  * Inspects a path to get metadata about the value at that location.
  *
@@ -481,6 +711,42 @@ export function count_references_excluding_deleted(schema, doc, target_node_id,
 	return count;
 }
 
+/**
+ * Gets ids of nodes that reference any of the target nodes.
+ *
+ * @param {DocumentSchema} schema - The document schema
+ * @param {Document} doc - The document containing nodes
+ * @param {Iterable<NodeId>} target_node_ids - Node IDs to find referrers for
+ * @returns {NodeId[]} IDs of nodes with references to any target node
+ */
+export function get_referencing_node_ids(schema, doc, target_node_ids) {
+	const target_ids = new Set(target_node_ids);
+	const referencing_node_ids = new Set();
+	if (target_ids.size === 0) return [];
+
+	for (const node of Object.values(doc.nodes)) {
+		for (const [property, value] of Object.entries(node)) {
+			if (property === 'id' || property === 'type') continue;
+
+			const prop_type = property_type(schema, node.type, property);
+
+			if (prop_type === 'node_array' && Array.isArray(value)) {
+				if (value.some((id) => target_ids.has(id))) {
+					referencing_node_ids.add(node.id);
+				}
+			} else if (prop_type === 'node' && target_ids.has(value)) {
+				referencing_node_ids.add(node.id);
+			} else if (prop_type === 'annotated_text' && value?.annotations) {
+				if (value.annotations.some((annotation) => target_ids.has(annotation.node_id))) {
+					referencing_node_ids.add(node.id);
+				}
+			}
+		}
+	}
+
+	return [...referencing_node_ids];
+}
+
 /**
  * Validates a selection against the current document state.
  * Works with any object that implements get() and inspect() (Session or Transaction).
@@ -535,7 +801,7 @@ export function validate_selection(selection, session_or_transaction) {
 		}
 	} else if (selection_type === 'property') {
 		if (!session_or_transaction.inspect(selection.path)) {
-			throw new Error(`Property selection path not found: ${selection.path.join('.')}`);
+			throw new Error(`Property selection path not found: ${serialize_path(selection.path)}`);
 		}
 	}
 }

package/src/lib/index.js

@@ -18,8 +18,12 @@ export {
 	define_document_schema,
 	is_primitive_type,
 	get_default_node_type,
+	fill_node_defaults,
+	fill_document_defaults,
 	validate_document_schema,
-	validate_node
+	validate_document,
+	validate_node,
+	get_referencing_node_ids
 } from './doc_utils.js';
 
 // Command system