@graph-knowledge/api 0.1.0

package/src/lib/validators/element-type-validators/base-element-validator.js

@@ -0,0 +1,96 @@
+import { ValidationError } from "../../errors/api-errors";
+/**
+ * Base class for element type validators.
+ * Provides common validation logic for position, dimensions, and colors.
+ */
+export class BaseElementValidator {
+    /**
+     * Validates common element properties (position, dimensions, rotation).
+     * @param input The element input to validate
+     * @throws ValidationError if validation fails
+     */
+    validateCommon(input) {
+        this.validatePosition(input);
+        this.validateDimensions(input);
+        this.validateRotation(input);
+    }
+    /**
+     * Validates position properties (x, y).
+     */
+    validatePosition(input) {
+        if (typeof input.x !== "number" || isNaN(input.x)) {
+            throw new ValidationError("x must be a valid number", "x");
+        }
+        if (typeof input.y !== "number" || isNaN(input.y)) {
+            throw new ValidationError("y must be a valid number", "y");
+        }
+        if (input.x < 0) {
+            throw new ValidationError("x must be non-negative", "x");
+        }
+        if (input.y < 0) {
+            throw new ValidationError("y must be non-negative", "y");
+        }
+    }
+    /**
+     * Validates dimension properties (width, height).
+     */
+    validateDimensions(input) {
+        if (input.width !== undefined) {
+            if (typeof input.width !== "number" || isNaN(input.width)) {
+                throw new ValidationError("width must be a valid number", "width");
+            }
+            if (input.width < 0) {
+                throw new ValidationError("width must be non-negative", "width");
+            }
+        }
+        if (input.height !== undefined) {
+            if (typeof input.height !== "number" || isNaN(input.height)) {
+                throw new ValidationError("height must be a valid number", "height");
+            }
+            if (input.height < 0) {
+                throw new ValidationError("height must be non-negative", "height");
+            }
+        }
+    }
+    /**
+     * Validates rotation property.
+     */
+    validateRotation(input) {
+        if (input.rotation !== undefined) {
+            if (typeof input.rotation !== "number" || isNaN(input.rotation)) {
+                throw new ValidationError("rotation must be a valid number", "rotation");
+            }
+            if (input.rotation < 0 || input.rotation >= 360) {
+                throw new ValidationError("rotation must be in range [0, 360)", "rotation");
+            }
+        }
+    }
+    /**
+     * Validates a hex color string.
+     * @param value The color value to validate
+     * @param field The field name for error messages
+     */
+    validateColor(value, field) {
+        if (value === undefined)
+            return;
+        if (typeof value !== "string") {
+            throw new ValidationError(`${field} must be a string`, field);
+        }
+        if (!value.match(/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/)) {
+            throw new ValidationError(`${field} must be a valid hex color (e.g., #FF0000)`, field);
+        }
+    }
+    /**
+     * Validates stroke width.
+     */
+    validateStrokeWidth(value, field) {
+        if (value === undefined)
+            return;
+        if (typeof value !== "number" || isNaN(value)) {
+            throw new ValidationError(`${field} must be a valid number`, field);
+        }
+        if (value < 0) {
+            throw new ValidationError(`${field} must be non-negative`, field);
+        }
+    }
+}

package/src/lib/validators/element-type-validators/connector-validator.d.ts

@@ -0,0 +1,13 @@
+import { IElementTypeValidator } from "../../interfaces/element-validator.interface";
+import { AnyElementInput } from "../../types/element-input-types";
+import { BaseElementValidator } from "./base-element-validator";
+/**
+ * Validator for connector elements.
+ */
+export declare class ConnectorValidator extends BaseElementValidator implements IElementTypeValidator {
+    readonly elementType = "connector";
+    validate(input: AnyElementInput): void;
+    private validateAnchor;
+    private validateLineStyle;
+    private validateMarker;
+}

package/src/lib/validators/element-type-validators/connector-validator.js

@@ -0,0 +1,66 @@
+import { ValidationError } from "../../errors/api-errors";
+import { BaseElementValidator } from "./base-element-validator";
+/**
+ * Valid connector anchor points matching the graph editor's snap geometry labels.
+ */
+const VALID_ANCHORS = [
+    "edge-top",
+    "edge-right",
+    "edge-bottom",
+    "edge-left",
+    "center"
+];
+const VALID_LINE_STYLES = ["solid", "dashed", "dotted"];
+const VALID_MARKERS = ["none", "arrow", "diamond", "circle"];
+/**
+ * Validator for connector elements.
+ */
+export class ConnectorValidator extends BaseElementValidator {
+    elementType = "connector";
+    validate(input) {
+        if (input.type !== "connector") {
+            throw new ValidationError(`Expected type "connector", got "${input.type}"`, "type");
+        }
+        const connectorInput = input;
+        // Note: Connectors don't use x/y positions - they're determined by connected elements
+        // So we don't call validateCommon() which requires x/y
+        // Required fields
+        if (!connectorInput.startElementId ||
+            typeof connectorInput.startElementId !== "string") {
+            throw new ValidationError("startElementId is required", "startElementId");
+        }
+        if (!connectorInput.endElementId ||
+            typeof connectorInput.endElementId !== "string") {
+            throw new ValidationError("endElementId is required", "endElementId");
+        }
+        // Validate connector-specific properties
+        this.validateAnchor(connectorInput.startAnchor, "startAnchor");
+        this.validateAnchor(connectorInput.endAnchor, "endAnchor");
+        this.validateColor(connectorInput.strokeColor, "strokeColor");
+        this.validateStrokeWidth(connectorInput.strokeWidth, "strokeWidth");
+        this.validateLineStyle(connectorInput.lineStyle);
+        this.validateMarker(connectorInput.startMarker, "startMarker");
+        this.validateMarker(connectorInput.endMarker, "endMarker");
+    }
+    validateAnchor(value, field) {
+        if (value === undefined)
+            return;
+        if (!VALID_ANCHORS.includes(value)) {
+            throw new ValidationError(`${field} must be one of: ${VALID_ANCHORS.join(", ")}`, field);
+        }
+    }
+    validateLineStyle(value) {
+        if (value === undefined)
+            return;
+        if (!VALID_LINE_STYLES.includes(value)) {
+            throw new ValidationError(`lineStyle must be one of: ${VALID_LINE_STYLES.join(", ")}`, "lineStyle");
+        }
+    }
+    validateMarker(value, field) {
+        if (value === undefined)
+            return;
+        if (!VALID_MARKERS.includes(value)) {
+            throw new ValidationError(`${field} must be one of: ${VALID_MARKERS.join(", ")}`, field);
+        }
+    }
+}

package/src/lib/validators/element-type-validators/custom-shape-validator.d.ts

@@ -0,0 +1,22 @@
+import { IElementTypeValidator } from "../../interfaces/element-validator.interface";
+import { AnyElementInput } from "../../types/element-input-types";
+import { BaseElementValidator } from "./base-element-validator";
+/**
+ * Validator for custom shape elements.
+ * Handles elements with type "custom:{shapeId}".
+ */
+export declare class CustomShapeValidator extends BaseElementValidator implements IElementTypeValidator {
+    private readonly shapeId;
+    /**
+     * Creates a validator for a specific custom shape.
+     * @param shapeId The custom shape ID this validator handles
+     */
+    constructor(shapeId: string);
+    get elementType(): string;
+    validate(input: AnyElementInput): void;
+}
+/**
+ * Factory function to create a custom shape validator.
+ * @param shapeId The custom shape ID
+ */
+export declare function createCustomShapeValidator(shapeId: string): CustomShapeValidator;

package/src/lib/validators/element-type-validators/custom-shape-validator.js

@@ -0,0 +1,44 @@
+import { ValidationError } from "../../errors/api-errors";
+import { BaseElementValidator } from "./base-element-validator";
+/**
+ * Validator for custom shape elements.
+ * Handles elements with type "custom:{shapeId}".
+ */
+export class CustomShapeValidator extends BaseElementValidator {
+    shapeId;
+    /**
+     * Creates a validator for a specific custom shape.
+     * @param shapeId The custom shape ID this validator handles
+     */
+    constructor(shapeId) {
+        super();
+        this.shapeId = shapeId;
+    }
+    get elementType() {
+        return `custom:${this.shapeId}`;
+    }
+    validate(input) {
+        if (!input.type.startsWith("custom:")) {
+            throw new ValidationError(`Expected custom shape type, got "${input.type}"`, "type");
+        }
+        const customInput = input;
+        // Validate common properties
+        this.validateCommon(customInput);
+        // customShapeId is required
+        if (!customInput.customShapeId ||
+            typeof customInput.customShapeId !== "string") {
+            throw new ValidationError("customShapeId is required for custom shapes", "customShapeId");
+        }
+        // Validate optional style properties
+        this.validateColor(customInput.fillColor, "fillColor");
+        this.validateColor(customInput.strokeColor, "strokeColor");
+        this.validateStrokeWidth(customInput.strokeWidth, "strokeWidth");
+    }
+}
+/**
+ * Factory function to create a custom shape validator.
+ * @param shapeId The custom shape ID
+ */
+export function createCustomShapeValidator(shapeId) {
+    return new CustomShapeValidator(shapeId);
+}

package/src/lib/validators/element-type-validators/rectangle-validator.d.ts

@@ -0,0 +1,11 @@
+import { IElementTypeValidator } from "../../interfaces/element-validator.interface";
+import { AnyElementInput } from "../../types/element-input-types";
+import { BaseElementValidator } from "./base-element-validator";
+/**
+ * Validator for rectangle elements.
+ */
+export declare class RectangleValidator extends BaseElementValidator implements IElementTypeValidator {
+    readonly elementType = "rectangle";
+    validate(input: AnyElementInput): void;
+    private validateCornerRadius;
+}

package/src/lib/validators/element-type-validators/rectangle-validator.js

@@ -0,0 +1,31 @@
+import { ValidationError } from "../../errors/api-errors";
+import { BaseElementValidator } from "./base-element-validator";
+/**
+ * Validator for rectangle elements.
+ */
+export class RectangleValidator extends BaseElementValidator {
+    elementType = "rectangle";
+    validate(input) {
+        if (input.type !== "rectangle") {
+            throw new ValidationError(`Expected type "rectangle", got "${input.type}"`, "type");
+        }
+        const rectangleInput = input;
+        // Validate common properties
+        this.validateCommon(rectangleInput);
+        // Validate rectangle-specific properties
+        this.validateColor(rectangleInput.fillColor, "fillColor");
+        this.validateColor(rectangleInput.strokeColor, "strokeColor");
+        this.validateStrokeWidth(rectangleInput.strokeWidth, "strokeWidth");
+        this.validateCornerRadius(rectangleInput.cornerRadius);
+    }
+    validateCornerRadius(value) {
+        if (value === undefined)
+            return;
+        if (typeof value !== "number" || isNaN(value)) {
+            throw new ValidationError("cornerRadius must be a valid number", "cornerRadius");
+        }
+        if (value < 0) {
+            throw new ValidationError("cornerRadius must be non-negative", "cornerRadius");
+        }
+    }
+}

package/src/lib/validators/element-type-validators/text-validator.d.ts

@@ -0,0 +1,14 @@
+import { IElementTypeValidator } from "../../interfaces/element-validator.interface";
+import { AnyElementInput } from "../../types/element-input-types";
+import { BaseElementValidator } from "./base-element-validator";
+/**
+ * Validator for text elements.
+ */
+export declare class TextValidator extends BaseElementValidator implements IElementTypeValidator {
+    readonly elementType = "text";
+    validate(input: AnyElementInput): void;
+    private validateFontSize;
+    private validateFontWeight;
+    private validateTextAlign;
+    private validateLineHeight;
+}

package/src/lib/validators/element-type-validators/text-validator.js

@@ -0,0 +1,66 @@
+import { ValidationError } from "../../errors/api-errors";
+import { BaseElementValidator } from "./base-element-validator";
+/**
+ * Validator for text elements.
+ */
+export class TextValidator extends BaseElementValidator {
+    elementType = "text";
+    validate(input) {
+        if (input.type !== "text") {
+            throw new ValidationError(`Expected type "text", got "${input.type}"`, "type");
+        }
+        const textInput = input;
+        // Validate common properties
+        this.validateCommon(textInput);
+        // Text content is required
+        if (textInput.text === undefined || textInput.text === null) {
+            throw new ValidationError("text is required for text elements", "text");
+        }
+        if (typeof textInput.text !== "string") {
+            throw new ValidationError("text must be a string", "text");
+        }
+        // Validate text-specific properties
+        this.validateColor(textInput.fillColor, "fillColor");
+        this.validateFontSize(textInput.fontSize);
+        this.validateFontWeight(textInput.fontWeight);
+        this.validateTextAlign(textInput.textAlign);
+        this.validateLineHeight(textInput.lineHeight);
+    }
+    validateFontSize(value) {
+        if (value === undefined)
+            return;
+        if (typeof value !== "number" || isNaN(value)) {
+            throw new ValidationError("fontSize must be a valid number", "fontSize");
+        }
+        if (value <= 0) {
+            throw new ValidationError("fontSize must be positive", "fontSize");
+        }
+    }
+    validateFontWeight(value) {
+        if (value === undefined)
+            return;
+        if (typeof value !== "number" || isNaN(value)) {
+            throw new ValidationError("fontWeight must be a valid number", "fontWeight");
+        }
+        if (value < 100 || value > 900) {
+            throw new ValidationError("fontWeight must be between 100 and 900", "fontWeight");
+        }
+    }
+    validateTextAlign(value) {
+        if (value === undefined)
+            return;
+        if (!["left", "center", "right"].includes(value)) {
+            throw new ValidationError('textAlign must be "left", "center", or "right"', "textAlign");
+        }
+    }
+    validateLineHeight(value) {
+        if (value === undefined)
+            return;
+        if (typeof value !== "number" || isNaN(value)) {
+            throw new ValidationError("lineHeight must be a valid number", "lineHeight");
+        }
+        if (value <= 0) {
+            throw new ValidationError("lineHeight must be positive", "lineHeight");
+        }
+    }
+}

package/src/lib/validators/element-type-validators/uml-validators.d.ts

@@ -0,0 +1,58 @@
+import { IElementTypeValidator } from "../../interfaces/element-validator.interface";
+import { AnyElementInput } from "../../types/element-input-types";
+import { BaseElementValidator } from "./base-element-validator";
+/**
+ * Base validator for UML elements.
+ * Provides common validation for UML-specific properties.
+ */
+declare abstract class BaseUmlValidator extends BaseElementValidator implements IElementTypeValidator {
+    abstract readonly elementType: string;
+    validate(input: AnyElementInput): void;
+    /**
+     * Override in subclasses for type-specific validation.
+     */
+    protected validateSpecific(_input: AnyElementInput): void;
+}
+/**
+ * Validator for UML class elements.
+ */
+export declare class UmlClassValidator extends BaseUmlValidator {
+    readonly elementType = "uml-class";
+    protected validateSpecific(input: AnyElementInput): void;
+}
+/**
+ * Validator for UML interface elements.
+ */
+export declare class UmlInterfaceValidator extends BaseUmlValidator {
+    readonly elementType = "uml-interface";
+    protected validateSpecific(input: AnyElementInput): void;
+}
+/**
+ * Validator for UML component elements.
+ */
+export declare class UmlComponentValidator extends BaseUmlValidator {
+    readonly elementType = "uml-component";
+    protected validateSpecific(input: AnyElementInput): void;
+}
+/**
+ * Validator for UML package elements.
+ */
+export declare class UmlPackageValidator extends BaseUmlValidator {
+    readonly elementType = "uml-package";
+    protected validateSpecific(input: AnyElementInput): void;
+}
+/**
+ * Validator for UML artifact elements.
+ */
+export declare class UmlArtifactValidator extends BaseUmlValidator {
+    readonly elementType = "uml-artifact";
+    protected validateSpecific(input: AnyElementInput): void;
+}
+/**
+ * Validator for UML note elements.
+ */
+export declare class UmlNoteValidator extends BaseUmlValidator {
+    readonly elementType = "uml-note";
+    protected validateSpecific(input: AnyElementInput): void;
+}
+export {};

package/src/lib/validators/element-type-validators/uml-validators.js

@@ -0,0 +1,123 @@
+import { ValidationError } from "../../errors/api-errors";
+import { BaseElementValidator } from "./base-element-validator";
+/**
+ * Base validator for UML elements.
+ * Provides common validation for UML-specific properties.
+ */
+class BaseUmlValidator extends BaseElementValidator {
+    validate(input) {
+        if (input.type !== this.elementType) {
+            throw new ValidationError(`Expected type "${this.elementType}", got "${input.type}"`, "type");
+        }
+        // Validate common properties - cast is safe since we've verified the type
+        // and UML elements always have required x/y
+        this.validateCommon(input);
+        // Validate UML-common properties
+        const umlInput = input;
+        this.validateColor(umlInput["fillColor"], "fillColor");
+        this.validateColor(umlInput["strokeColor"], "strokeColor");
+        this.validateStrokeWidth(umlInput["strokeWidth"], "strokeWidth");
+        // Delegate to subclass for type-specific validation
+        this.validateSpecific(input);
+    }
+    /**
+     * Override in subclasses for type-specific validation.
+     */
+    validateSpecific(_input) {
+        // Default: no additional validation
+    }
+}
+/**
+ * Validator for UML class elements.
+ */
+export class UmlClassValidator extends BaseUmlValidator {
+    elementType = "uml-class";
+    validateSpecific(input) {
+        const classInput = input;
+        if (classInput["name"] !== undefined &&
+            typeof classInput["name"] !== "string") {
+            throw new ValidationError("name must be a string", "name");
+        }
+        if (classInput["attributes"] !== undefined &&
+            typeof classInput["attributes"] !== "string") {
+            throw new ValidationError("attributes must be a string", "attributes");
+        }
+        if (classInput["methods"] !== undefined &&
+            typeof classInput["methods"] !== "string") {
+            throw new ValidationError("methods must be a string", "methods");
+        }
+        if (classInput["stereotype"] !== undefined &&
+            typeof classInput["stereotype"] !== "string") {
+            throw new ValidationError("stereotype must be a string", "stereotype");
+        }
+    }
+}
+/**
+ * Validator for UML interface elements.
+ */
+export class UmlInterfaceValidator extends BaseUmlValidator {
+    elementType = "uml-interface";
+    validateSpecific(input) {
+        const interfaceInput = input;
+        if (interfaceInput["name"] !== undefined &&
+            typeof interfaceInput["name"] !== "string") {
+            throw new ValidationError("name must be a string", "name");
+        }
+        if (interfaceInput["methods"] !== undefined &&
+            typeof interfaceInput["methods"] !== "string") {
+            throw new ValidationError("methods must be a string", "methods");
+        }
+    }
+}
+/**
+ * Validator for UML component elements.
+ */
+export class UmlComponentValidator extends BaseUmlValidator {
+    elementType = "uml-component";
+    validateSpecific(input) {
+        const componentInput = input;
+        if (componentInput["name"] !== undefined &&
+            typeof componentInput["name"] !== "string") {
+            throw new ValidationError("name must be a string", "name");
+        }
+    }
+}
+/**
+ * Validator for UML package elements.
+ */
+export class UmlPackageValidator extends BaseUmlValidator {
+    elementType = "uml-package";
+    validateSpecific(input) {
+        const packageInput = input;
+        if (packageInput["name"] !== undefined &&
+            typeof packageInput["name"] !== "string") {
+            throw new ValidationError("name must be a string", "name");
+        }
+    }
+}
+/**
+ * Validator for UML artifact elements.
+ */
+export class UmlArtifactValidator extends BaseUmlValidator {
+    elementType = "uml-artifact";
+    validateSpecific(input) {
+        const artifactInput = input;
+        if (artifactInput["name"] !== undefined &&
+            typeof artifactInput["name"] !== "string") {
+            throw new ValidationError("name must be a string", "name");
+        }
+    }
+}
+/**
+ * Validator for UML note elements.
+ */
+export class UmlNoteValidator extends BaseUmlValidator {
+    elementType = "uml-note";
+    validateSpecific(input) {
+        const noteInput = input;
+        if (noteInput["text"] !== undefined &&
+            typeof noteInput["text"] !== "string") {
+            throw new ValidationError("text must be a string", "text");
+        }
+    }
+}

package/src/lib/validators/element-validator-registry.d.ts

@@ -0,0 +1,18 @@
+import { IElementTypeValidator, IElementValidatorRegistry } from "../interfaces/element-validator.interface";
+import { AnyElementInput } from "../types/element-input-types";
+/**
+ * Registry for element type validators.
+ * Implements Open/Closed principle - new validators can be registered
+ * without modifying this class.
+ */
+export declare class ElementValidatorRegistry implements IElementValidatorRegistry {
+    private readonly validators;
+    constructor();
+    /**
+     * Registers built-in validators for standard element types.
+     */
+    private registerBuiltInValidators;
+    register(validator: IElementTypeValidator): void;
+    getValidator(elementType: string): IElementTypeValidator | undefined;
+    validate(input: AnyElementInput): void;
+}

package/src/lib/validators/element-validator-registry.js

@@ -0,0 +1,58 @@
+import { ValidationError } from "../errors/api-errors";
+import { RectangleValidator } from "./element-type-validators/rectangle-validator";
+import { TextValidator } from "./element-type-validators/text-validator";
+import { ConnectorValidator } from "./element-type-validators/connector-validator";
+import { UmlClassValidator, UmlInterfaceValidator, UmlComponentValidator, UmlPackageValidator, UmlArtifactValidator, UmlNoteValidator } from "./element-type-validators/uml-validators";
+import { CustomShapeValidator } from "./element-type-validators/custom-shape-validator";
+/**
+ * Registry for element type validators.
+ * Implements Open/Closed principle - new validators can be registered
+ * without modifying this class.
+ */
+export class ElementValidatorRegistry {
+    validators = new Map();
+    constructor() {
+        // Register built-in validators
+        this.registerBuiltInValidators();
+    }
+    /**
+     * Registers built-in validators for standard element types.
+     */
+    registerBuiltInValidators() {
+        this.register(new RectangleValidator());
+        this.register(new TextValidator());
+        this.register(new ConnectorValidator());
+        this.register(new UmlClassValidator());
+        this.register(new UmlInterfaceValidator());
+        this.register(new UmlComponentValidator());
+        this.register(new UmlPackageValidator());
+        this.register(new UmlArtifactValidator());
+        this.register(new UmlNoteValidator());
+    }
+    register(validator) {
+        this.validators.set(validator.elementType, validator);
+    }
+    getValidator(elementType) {
+        // Check for exact match first
+        const validator = this.validators.get(elementType);
+        if (validator) {
+            return validator;
+        }
+        // Handle custom shapes - create validator on demand
+        if (elementType.startsWith("custom:")) {
+            const shapeId = elementType.substring(7); // Remove "custom:" prefix
+            const customValidator = new CustomShapeValidator(shapeId);
+            // Cache for future use
+            this.validators.set(elementType, customValidator);
+            return customValidator;
+        }
+        return undefined;
+    }
+    validate(input) {
+        const validator = this.getValidator(input.type);
+        if (!validator) {
+            throw new ValidationError(`Unknown element type: ${input.type}`, "type");
+        }
+        validator.validate(input);
+    }
+}

package/src/lib/validators/node-validator.d.ts

@@ -0,0 +1,26 @@
+import { CreateNodeInput, UpdateNodeInput } from "../types/api-types";
+/**
+ * Validator for node operations.
+ */
+export declare class NodeValidator {
+    /**
+     * Validates input for node creation.
+     * @param input The creation input to validate
+     * @throws ValidationError if validation fails
+     */
+    validateCreate(input: CreateNodeInput): void;
+    /**
+     * Validates input for node update.
+     * @param input The update input to validate
+     * @throws ValidationError if validation fails
+     */
+    validateUpdate(input: UpdateNodeInput): void;
+    /**
+     * Validates canvas dimensions.
+     */
+    private validateCanvasDimensions;
+    /**
+     * Validates node level.
+     */
+    private validateLevel;
+}