hikma-engine
Version:
Code Knowledge Graph Indexer - A sophisticated TypeScript-based indexer that transforms Git repositories into multi-dimensional knowledge stores for AI agents
204 lines • 9.15 kB
TypeScript
/**
* @file Structured error classes for comprehensive API error handling.
* Provides detailed error information with proper HTTP status codes and helpful messages.
*/
/**
* Base API error class with structured information.
*/
export declare abstract class BaseAPIError extends Error {
abstract readonly statusCode: number;
abstract readonly errorCode: string;
abstract readonly isOperational: boolean;
readonly timestamp: string;
readonly requestId?: string;
readonly details?: any;
readonly context?: Record<string, any>;
constructor(message: string, details?: any, context?: Record<string, any>, requestId?: string);
/**
* Converts error to JSON format for API responses.
*/
toJSON(): {
success: false;
error: {
code: string;
message: string;
details?: any;
stack?: string;
};
meta: {
timestamp: string;
requestId?: string;
context?: Record<string, any>;
};
};
/**
* Logs the error with appropriate level and context.
*/
log(): void;
}
/**
* Validation errors (400 Bad Request).
*/
export declare class ValidationError extends BaseAPIError {
readonly statusCode = 400;
readonly errorCode = "VALIDATION_ERROR";
readonly isOperational = true;
constructor(message: string, field?: string, value?: any, constraint?: string, requestId?: string);
static required(field: string, requestId?: string): ValidationError;
static invalid(field: string, value: any, constraint: string, requestId?: string): ValidationError;
static format(field: string, expectedFormat: string, requestId?: string): ValidationError;
}
/**
* Authentication errors (401 Unauthorized).
*/
export declare class AuthenticationError extends BaseAPIError {
readonly statusCode = 401;
readonly errorCode = "AUTHENTICATION_ERROR";
readonly isOperational = true;
constructor(message?: string, requestId?: string);
static invalidToken(requestId?: string): AuthenticationError;
static missingToken(requestId?: string): AuthenticationError;
}
/**
* Authorization errors (403 Forbidden).
*/
export declare class AuthorizationError extends BaseAPIError {
readonly statusCode = 403;
readonly errorCode = "AUTHORIZATION_ERROR";
readonly isOperational = true;
constructor(message?: string, requiredPermission?: string, requestId?: string);
static insufficientPermissions(permission: string, requestId?: string): AuthorizationError;
}
/**
* Resource not found errors (404 Not Found).
*/
export declare class NotFoundError extends BaseAPIError {
readonly statusCode = 404;
readonly errorCode = "RESOURCE_NOT_FOUND";
readonly isOperational = true;
constructor(resource: string, identifier?: string, requestId?: string);
static route(method: string, path: string, requestId?: string): NotFoundError;
static endpoint(endpoint: string, requestId?: string): NotFoundError;
}
/**
* Rate limiting errors (429 Too Many Requests).
*/
export declare class RateLimitError extends BaseAPIError {
readonly statusCode = 429;
readonly errorCode = "RATE_LIMIT_EXCEEDED";
readonly isOperational = true;
constructor(limit: number, windowMs: number, retryAfter?: number, requestId?: string);
}
/**
* Search service errors (500 Internal Server Error).
*/
export declare class SearchServiceError extends BaseAPIError {
readonly statusCode = 500;
readonly errorCode = "SEARCH_SERVICE_ERROR";
readonly isOperational = true;
constructor(message: string, searchType?: string, query?: string, originalError?: Error, requestId?: string);
static semanticSearchFailed(query: string, error: Error, requestId?: string): SearchServiceError;
static structuralSearchFailed(query: string, error: Error, requestId?: string): SearchServiceError;
static gitSearchFailed(query: string, error: Error, requestId?: string): SearchServiceError;
static hybridSearchFailed(query: string, error: Error, requestId?: string): SearchServiceError;
static comprehensiveSearchFailed(query: string, error: Error, requestId?: string): SearchServiceError;
}
/**
* Database errors (500 Internal Server Error).
*/
export declare class DatabaseError extends BaseAPIError {
readonly statusCode = 500;
readonly errorCode = "DATABASE_ERROR";
readonly isOperational = true;
constructor(message: string, operation?: string, database?: string, originalError?: Error, requestId?: string);
static connectionFailed(database: string, error: Error, requestId?: string): DatabaseError;
static queryFailed(operation: string, error: Error, requestId?: string): DatabaseError;
}
/**
* Cache errors (500 Internal Server Error).
*/
export declare class CacheError extends BaseAPIError {
readonly statusCode = 500;
readonly errorCode = "CACHE_ERROR";
readonly isOperational = true;
constructor(message: string, operation?: string, originalError?: Error, requestId?: string);
static operationFailed(operation: string, error: Error, requestId?: string): CacheError;
}
/**
* Configuration errors (500 Internal Server Error).
*/
export declare class ConfigurationError extends BaseAPIError {
readonly statusCode = 500;
readonly errorCode = "CONFIGURATION_ERROR";
readonly isOperational = false;
constructor(message: string, configKey?: string, expectedValue?: string, requestId?: string);
static missing(configKey: string, requestId?: string): ConfigurationError;
static invalid(configKey: string, expectedValue: string, requestId?: string): ConfigurationError;
}
/**
* Generic internal server errors (500 Internal Server Error).
*/
export declare class InternalServerError extends BaseAPIError {
readonly statusCode = 500;
readonly errorCode = "INTERNAL_SERVER_ERROR";
readonly isOperational = false;
constructor(message?: string, originalError?: Error, requestId?: string);
static unexpected(error: Error, requestId?: string): InternalServerError;
}
/**
* Service unavailable errors (503 Service Unavailable).
*/
export declare class ServiceUnavailableError extends BaseAPIError {
readonly statusCode = 503;
readonly errorCode = "SERVICE_UNAVAILABLE";
readonly isOperational = true;
constructor(service: string, reason?: string, retryAfter?: number, requestId?: string);
static searchService(reason?: string, requestId?: string): ServiceUnavailableError;
static database(database: string, reason?: string, requestId?: string): ServiceUnavailableError;
}
/**
* Utility function to create appropriate error from unknown error.
*/
export declare function createAPIError(error: unknown, requestId?: string, context?: Record<string, any>): BaseAPIError;
/**
* Type guard to check if error is operational.
*/
export declare function isOperationalError(error: unknown): boolean;
/**
* Error factory for common API errors.
*/
export declare const APIErrors: {
validation: {
required: (field: string, requestId?: string) => ValidationError;
invalid: (field: string, value: any, constraint: string, requestId?: string) => ValidationError;
format: (field: string, format: string, requestId?: string) => ValidationError;
};
auth: {
invalidToken: (requestId?: string) => AuthenticationError;
missingToken: (requestId?: string) => AuthenticationError;
insufficientPermissions: (permission: string, requestId?: string) => AuthorizationError;
};
notFound: {
route: (method: string, path: string, requestId?: string) => NotFoundError;
endpoint: (endpoint: string, requestId?: string) => NotFoundError;
resource: (resource: string, id?: string, requestId?: string) => NotFoundError;
};
search: {
semanticFailed: (query: string, error: Error, requestId?: string) => SearchServiceError;
structuralFailed: (query: string, error: Error, requestId?: string) => SearchServiceError;
gitFailed: (query: string, error: Error, requestId?: string) => SearchServiceError;
hybridFailed: (query: string, error: Error, requestId?: string) => SearchServiceError;
comprehensiveFailed: (query: string, error: Error, requestId?: string) => SearchServiceError;
};
service: {
unavailable: (service: string, reason?: string, requestId?: string) => ServiceUnavailableError;
searchUnavailable: (reason?: string, requestId?: string) => ServiceUnavailableError;
databaseUnavailable: (database: string, reason?: string, requestId?: string) => ServiceUnavailableError;
};
internal: (message?: string, error?: Error, requestId?: string) => InternalServerError;
rateLimit: (limit: number, windowMs: number, retryAfter?: number, requestId?: string) => RateLimitError;
authentication: (message: string, requestId?: string) => AuthenticationError;
authorization: (message: string, requestId?: string) => AuthorizationError;
timeout: (message: string, requestId?: string) => InternalServerError;
};
//# sourceMappingURL=api-errors.d.ts.map