@nicia-ai/typegraph 0.2.0 → 0.3.0

package/dist/index-Dkicw49A.d.ts

@@ -0,0 +1,373 @@
+/**
+ * TypeGraph Error Hierarchy
+ *
+ * All errors extend TypeGraphError with:
+ * - `code`: Machine-readable error code for programmatic handling
+ * - `category`: Classification for error handling strategies
+ * - `suggestion`: Optional recovery guidance for users
+ * - `details`: Structured context about the error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await store.nodes.Person.create({ name: "" });
+ * } catch (error) {
+ *   if (isTypeGraphError(error)) {
+ *     console.error(error.toUserMessage());
+ *     if (isUserRecoverable(error)) {
+ *       // Show to user for correction
+ *     }
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Error category for programmatic handling.
+ *
+ * - `user`: Caused by invalid input or incorrect usage. Recoverable by fixing input.
+ * - `constraint`: Business rule or schema constraint violation. Recoverable by changing data.
+ * - `system`: Internal error or infrastructure issue. May require investigation or retry.
+ */
+type ErrorCategory = "user" | "constraint" | "system";
+/**
+ * Options for TypeGraphError constructor.
+ */
+type TypeGraphErrorOptions = Readonly<{
+    /** Structured context about the error */
+    details?: Record<string, unknown>;
+    /** Error category for handling strategies */
+    category: ErrorCategory;
+    /** Recovery guidance for users */
+    suggestion?: string;
+    /** Underlying cause of the error */
+    cause?: unknown;
+}>;
+/**
+ * Base error class for all TypeGraph errors.
+ *
+ * Provides structured error information for both programmatic handling
+ * and user-friendly messages.
+ */
+declare class TypeGraphError extends Error {
+    /** Machine-readable error code (e.g., "VALIDATION_ERROR") */
+    readonly code: string;
+    /** Error category for handling strategies */
+    readonly category: ErrorCategory;
+    /** Structured context about the error */
+    readonly details: Readonly<Record<string, unknown>>;
+    /** Recovery guidance for users */
+    readonly suggestion?: string;
+    constructor(message: string, code: string, options: TypeGraphErrorOptions);
+    /**
+     * Returns a user-friendly error message with suggestion if available.
+     */
+    toUserMessage(): string;
+    /**
+     * Returns a detailed string representation for logging.
+     */
+    toLogString(): string;
+}
+/**
+ * Validation issue from Zod or custom validation.
+ */
+type ValidationIssue = Readonly<{
+    /** Path to the invalid field (e.g., "address.city") */
+    path: string;
+    /** Human-readable error message */
+    message: string;
+    /** Zod error code if from Zod validation */
+    code?: string;
+}>;
+/**
+ * Details for ValidationError.
+ */
+type ValidationErrorDetails = Readonly<{
+    /** Type of entity being validated */
+    entityType?: "node" | "edge";
+    /** Kind/type name of the entity */
+    kind?: string;
+    /** Operation being performed */
+    operation?: "create" | "update";
+    /** Entity ID if updating */
+    id?: string;
+    /** Individual validation issues */
+    issues: readonly ValidationIssue[];
+}>;
+/**
+ * Thrown when schema validation fails during node or edge operations.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await store.nodes.Person.create({ email: "invalid" });
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.log(error.details.issues);
+ *     // [{ path: "email", message: "Invalid email" }]
+ *   }
+ * }
+ * ```
+ */
+declare class ValidationError extends TypeGraphError {
+    readonly details: ValidationErrorDetails;
+    constructor(message: string, details: ValidationErrorDetails, options?: {
+        cause?: unknown;
+        suggestion?: string;
+    });
+}
+/**
+ * Thrown when a node is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await store.nodes.Person.get("nonexistent-id");
+ * } catch (error) {
+ *   if (error instanceof NodeNotFoundError) {
+ *     console.log(error.details.kind, error.details.id);
+ *   }
+ * }
+ * ```
+ */
+declare class NodeNotFoundError extends TypeGraphError {
+    constructor(kind: string, id: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when an edge is not found.
+ */
+declare class EdgeNotFoundError extends TypeGraphError {
+    constructor(kind: string, id: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a kind is not found in the graph registry.
+ */
+declare class KindNotFoundError extends TypeGraphError {
+    constructor(kind: string, type: "node" | "edge", options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when edge endpoint node does not exist or is deleted.
+ */
+declare class EndpointNotFoundError extends TypeGraphError {
+    constructor(details: Readonly<{
+        edgeKind: string;
+        endpoint: "from" | "to";
+        nodeKind: string;
+        nodeId: string;
+    }>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when edge endpoint has wrong node type.
+ */
+declare class EndpointError extends TypeGraphError {
+    constructor(details: Readonly<{
+        edgeKind: string;
+        endpoint: "from" | "to";
+        actualKind: string;
+        expectedKinds: readonly string[];
+    }>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when uniqueness constraint is violated.
+ */
+declare class UniquenessError extends TypeGraphError {
+    constructor(details: Readonly<{
+        constraintName: string;
+        kind: string;
+        existingId: string;
+        newId: string;
+        fields: readonly string[];
+    }>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when cardinality constraint is violated.
+ */
+declare class CardinalityError extends TypeGraphError {
+    constructor(details: Readonly<{
+        edgeKind: string;
+        fromKind: string;
+        fromId: string;
+        cardinality: string;
+        existingCount: number;
+    }>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when disjointness constraint is violated.
+ *
+ * Disjoint types cannot share the same ID - a node cannot be both
+ * a Person and an Organization if they are declared disjoint.
+ */
+declare class DisjointError extends TypeGraphError {
+    constructor(details: Readonly<{
+        nodeId: string;
+        attemptedKind: string;
+        conflictingKind: string;
+    }>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when deletion is blocked due to existing edges (restrict behavior).
+ */
+declare class RestrictedDeleteError extends TypeGraphError {
+    constructor(details: Readonly<{
+        nodeKind: string;
+        nodeId: string;
+        edgeCount: number;
+        edgeKinds: readonly string[];
+    }>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when optimistic locking detects a concurrent modification.
+ *
+ * This occurs when two operations try to update the same entity simultaneously.
+ * The operation with the stale version fails.
+ */
+declare class VersionConflictError extends TypeGraphError {
+    constructor(details: Readonly<{
+        kind: string;
+        id: string;
+        expectedVersion: number;
+        actualVersion: number;
+    }>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when the schema in code doesn't match the schema in the database.
+ */
+declare class SchemaMismatchError extends TypeGraphError {
+    constructor(details: Readonly<{
+        graphId: string;
+        expectedHash: string;
+        actualHash: string;
+    }>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when schema migration fails.
+ */
+declare class MigrationError extends TypeGraphError {
+    constructor(message: string, details: Readonly<{
+        graphId: string;
+        fromVersion: number;
+        toVersion: number;
+        reason?: string;
+    }>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when graph configuration is invalid.
+ *
+ * This includes invalid schema definitions, ontology conflicts,
+ * and other configuration issues detected at graph creation time.
+ */
+declare class ConfigurationError extends TypeGraphError {
+    constructor(message: string, details?: Record<string, unknown>, options?: {
+        cause?: unknown;
+        suggestion?: string;
+    });
+}
+/**
+ * Thrown when a database operation fails unexpectedly.
+ *
+ * This indicates a system-level failure in the database backend,
+ * not a user-recoverable error.
+ */
+declare class DatabaseOperationError extends TypeGraphError {
+    constructor(message: string, details: Readonly<{
+        operation: string;
+        entity: string;
+    }>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a query predicate cannot be compiled for the target database.
+ */
+declare class UnsupportedPredicateError extends TypeGraphError {
+    constructor(message: string, details?: Readonly<Record<string, unknown>>, options?: {
+        cause?: unknown;
+        suggestion?: string;
+    });
+}
+/**
+ * Thrown when a compiler invariant is violated.
+ *
+ * This indicates a bug in the query compiler — the compiler reached
+ * a state that should be unreachable. These errors are not user-recoverable.
+ */
+declare class CompilerInvariantError extends TypeGraphError {
+    constructor(message: string, details?: Readonly<Record<string, unknown>>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Type guard for TypeGraphError.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await store.nodes.Person.create({});
+ * } catch (error) {
+ *   if (isTypeGraphError(error)) {
+ *     console.log(error.code, error.category);
+ *   }
+ * }
+ * ```
+ */
+declare function isTypeGraphError(error: unknown): error is TypeGraphError;
+/**
+ * Check if error is recoverable by user action (user or constraint error).
+ *
+ * User-recoverable errors can typically be resolved by:
+ * - Fixing invalid input data
+ * - Using different IDs or values
+ * - Deleting conflicting data first
+ *
+ * @example
+ * ```typescript
+ * if (isUserRecoverable(error)) {
+ *   showErrorToUser(error.toUserMessage());
+ * } else {
+ *   logAndAlertOps(error);
+ * }
+ * ```
+ */
+declare function isUserRecoverable(error: unknown): boolean;
+/**
+ * Check if error indicates a system/infrastructure issue.
+ *
+ * System errors typically require:
+ * - Retry logic (for transient failures)
+ * - Investigation (for persistent failures)
+ * - Ops team notification
+ */
+declare function isSystemError(error: unknown): boolean;
+/**
+ * Check if error is a constraint violation.
+ */
+declare function isConstraintError(error: unknown): boolean;
+/**
+ * Extract suggestion from error if available.
+ */
+declare function getErrorSuggestion(error: unknown): string | undefined;
+
+export { CardinalityError as C, DatabaseOperationError as D, EdgeNotFoundError as E, KindNotFoundError as K, MigrationError as M, NodeNotFoundError as N, RestrictedDeleteError as R, SchemaMismatchError as S, TypeGraphError as T, UniquenessError as U, type ValidationIssue as V, ValidationError as a, CompilerInvariantError as b, ConfigurationError as c, DisjointError as d, EndpointError as e, EndpointNotFoundError as f, type ErrorCategory as g, type TypeGraphErrorOptions as h, UnsupportedPredicateError as i, type ValidationErrorDetails as j, VersionConflictError as k, getErrorSuggestion as l, isConstraintError as m, isSystemError as n, isTypeGraphError as o, isUserRecoverable as p };