@wiscale/velesdb-sdk 1.1.1 → 1.3.0

package/dist/index.d.mts

@@ -104,6 +104,117 @@ interface SearchResult {
     /** Vector data (if includeVectors is true) */
     vector?: number[];
 }
+/** Graph edge representing a relationship between nodes */
+interface GraphEdge {
+    /** Unique edge ID */
+    id: number;
+    /** Source node ID */
+    source: number;
+    /** Target node ID */
+    target: number;
+    /** Edge label (relationship type, e.g., "KNOWS", "FOLLOWS") */
+    label: string;
+    /** Edge properties */
+    properties?: Record<string, unknown>;
+}
+/** Request to add an edge to the graph */
+interface AddEdgeRequest {
+    /** Unique edge ID */
+    id: number;
+    /** Source node ID */
+    source: number;
+    /** Target node ID */
+    target: number;
+    /** Edge label (relationship type) */
+    label: string;
+    /** Edge properties (optional) */
+    properties?: Record<string, unknown>;
+}
+/** Response containing edges */
+interface EdgesResponse {
+    /** List of edges */
+    edges: GraphEdge[];
+    /** Total count of edges returned */
+    count: number;
+}
+/** Options for querying edges */
+interface GetEdgesOptions {
+    /** Filter by edge label */
+    label?: string;
+}
+/** Request for graph traversal (EPIC-016 US-050) */
+interface TraverseRequest {
+    /** Source node ID to start traversal from */
+    source: number;
+    /** Traversal strategy: 'bfs' or 'dfs' */
+    strategy?: 'bfs' | 'dfs';
+    /** Maximum traversal depth */
+    maxDepth?: number;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Optional cursor for pagination */
+    cursor?: string;
+    /** Filter by relationship types (empty = all types) */
+    relTypes?: string[];
+}
+/** A single traversal result item */
+interface TraversalResultItem {
+    /** Target node ID reached */
+    targetId: number;
+    /** Depth of traversal (number of hops from source) */
+    depth: number;
+    /** Path taken (list of edge IDs) */
+    path: number[];
+}
+/** Statistics from traversal operation */
+interface TraversalStats {
+    /** Number of nodes visited */
+    visited: number;
+    /** Maximum depth reached */
+    depthReached: number;
+}
+/** Response from graph traversal */
+interface TraverseResponse {
+    /** List of traversal results */
+    results: TraversalResultItem[];
+    /** Cursor for next page (if applicable) */
+    nextCursor?: string;
+    /** Whether more results are available */
+    hasMore: boolean;
+    /** Traversal statistics */
+    stats: TraversalStats;
+}
+/** Response for node degree query */
+interface DegreeResponse {
+    /** Number of incoming edges */
+    inDegree: number;
+    /** Number of outgoing edges */
+    outDegree: number;
+}
+/** Index type for property indexes */
+type IndexType = 'hash' | 'range';
+/** Index information */
+interface IndexInfo {
+    /** Node label (e.g., "Person") */
+    label: string;
+    /** Property name (e.g., "email") */
+    property: string;
+    /** Index type: 'hash' for O(1) equality, 'range' for O(log n) range queries */
+    indexType: IndexType;
+    /** Number of unique values indexed (for hash indexes) */
+    cardinality: number;
+    /** Memory usage in bytes */
+    memoryBytes: number;
+}
+/** Options for creating an index */
+interface CreateIndexOptions {
+    /** Node label to index */
+    label: string;
+    /** Property name to index */
+    property: string;
+    /** Index type: 'hash' (default) or 'range' */
+    indexType?: IndexType;
+}
 /** Backend interface that all backends must implement */
 interface IVelesDBBackend {
     /** Initialize the backend */
@@ -155,6 +266,22 @@ interface IVelesDBBackend {
     flush(collection: string): Promise<void>;
     /** Close/cleanup the backend */
     close(): Promise<void>;
+    /** Create a property index for O(1) equality lookups */
+    createIndex(collection: string, options: CreateIndexOptions): Promise<void>;
+    /** List all indexes on a collection */
+    listIndexes(collection: string): Promise<IndexInfo[]>;
+    /** Check if an index exists */
+    hasIndex(collection: string, label: string, property: string): Promise<boolean>;
+    /** Drop an index */
+    dropIndex(collection: string, label: string, property: string): Promise<boolean>;
+    /** Add an edge to the collection's knowledge graph */
+    addEdge(collection: string, edge: AddEdgeRequest): Promise<void>;
+    /** Get edges from the collection's knowledge graph */
+    getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
+    /** Traverse the graph using BFS or DFS from a source node */
+    traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
+    /** Get the in-degree and out-degree of a node */
+    getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
 }
 /** Error types */
 declare class VelesDBError extends Error {
@@ -391,6 +518,117 @@ declare class VelesDB {
      * Get the current backend type
      */
     get backendType(): string;
+    /**
+     * Create a property index for O(1) equality lookups or O(log n) range queries
+     *
+     * @param collection - Collection name
+     * @param options - Index configuration (label, property, indexType)
+     *
+     * @example
+     * ```typescript
+     * // Create hash index for fast email lookups
+     * await db.createIndex('users', { label: 'Person', property: 'email' });
+     *
+     * // Create range index for timestamp queries
+     * await db.createIndex('events', { label: 'Event', property: 'timestamp', indexType: 'range' });
+     * ```
+     */
+    createIndex(collection: string, options: CreateIndexOptions): Promise<void>;
+    /**
+     * List all indexes on a collection
+     *
+     * @param collection - Collection name
+     * @returns Array of index information
+     */
+    listIndexes(collection: string): Promise<IndexInfo[]>;
+    /**
+     * Check if an index exists
+     *
+     * @param collection - Collection name
+     * @param label - Node label
+     * @param property - Property name
+     * @returns true if index exists
+     */
+    hasIndex(collection: string, label: string, property: string): Promise<boolean>;
+    /**
+     * Drop an index
+     *
+     * @param collection - Collection name
+     * @param label - Node label
+     * @param property - Property name
+     * @returns true if index was dropped, false if it didn't exist
+     */
+    dropIndex(collection: string, label: string, property: string): Promise<boolean>;
+    /**
+     * Add an edge to the collection's knowledge graph
+     *
+     * @param collection - Collection name
+     * @param edge - Edge to add (id, source, target, label, properties)
+     *
+     * @example
+     * ```typescript
+     * await db.addEdge('social', {
+     *   id: 1,
+     *   source: 100,
+     *   target: 200,
+     *   label: 'FOLLOWS',
+     *   properties: { since: '2024-01-01' }
+     * });
+     * ```
+     */
+    addEdge(collection: string, edge: AddEdgeRequest): Promise<void>;
+    /**
+     * Get edges from the collection's knowledge graph
+     *
+     * @param collection - Collection name
+     * @param options - Query options (filter by label)
+     * @returns Array of edges
+     *
+     * @example
+     * ```typescript
+     * // Get all edges with label "FOLLOWS"
+     * const edges = await db.getEdges('social', { label: 'FOLLOWS' });
+     * ```
+     */
+    getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
+    /**
+     * Traverse the graph using BFS or DFS from a source node
+     *
+     * @param collection - Collection name
+     * @param request - Traversal request options
+     * @returns Traversal response with results and stats
+     *
+     * @example
+     * ```typescript
+     * // BFS traversal from node 100
+     * const result = await db.traverseGraph('social', {
+     *   source: 100,
+     *   strategy: 'bfs',
+     *   maxDepth: 3,
+     *   limit: 100,
+     *   relTypes: ['FOLLOWS', 'KNOWS']
+     * });
+     *
+     * for (const node of result.results) {
+     *   console.log(`Reached node ${node.targetId} at depth ${node.depth}`);
+     * }
+     * ```
+     */
+    traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
+    /**
+     * Get the in-degree and out-degree of a node
+     *
+     * @param collection - Collection name
+     * @param nodeId - Node ID
+     * @returns Degree response with inDegree and outDegree
+     *
+     * @example
+     * ```typescript
+     * const degree = await db.getNodeDegree('social', 100);
+     * console.log(`In: ${degree.inDegree}, Out: ${degree.outDegree}`);
+     * ```
+     */
+    getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
 }
 
 /**
@@ -441,6 +679,14 @@ declare class WasmBackend implements IVelesDBBackend {
     flush(collectionName: string): Promise<void>;
     close(): Promise<void>;
     private toNumericId;
+    createIndex(_collection: string, _options: CreateIndexOptions): Promise<void>;
+    listIndexes(_collection: string): Promise<IndexInfo[]>;
+    hasIndex(_collection: string, _label: string, _property: string): Promise<boolean>;
+    dropIndex(_collection: string, _label: string, _property: string): Promise<boolean>;
+    addEdge(_collection: string, _edge: AddEdgeRequest): Promise<void>;
+    getEdges(_collection: string, _options?: GetEdgesOptions): Promise<GraphEdge[]>;
+    traverseGraph(_collection: string, _request: TraverseRequest): Promise<TraverseResponse>;
+    getNodeDegree(_collection: string, _nodeId: number): Promise<DegreeResponse>;
 }
 
 /**
@@ -463,6 +709,8 @@ declare class RestBackend implements IVelesDBBackend {
     init(): Promise<void>;
     isInitialized(): boolean;
     private ensureInitialized;
+    private mapStatusToErrorCode;
+    private extractErrorPayload;
     private request;
     createCollection(name: string, config: CollectionConfig): Promise<void>;
     deleteCollection(name: string): Promise<void>;
@@ -492,6 +740,14 @@ declare class RestBackend implements IVelesDBBackend {
     isEmpty(collection: string): Promise<boolean>;
     flush(collection: string): Promise<void>;
     close(): Promise<void>;
+    createIndex(collection: string, options: CreateIndexOptions): Promise<void>;
+    listIndexes(collection: string): Promise<IndexInfo[]>;
+    hasIndex(collection: string, label: string, property: string): Promise<boolean>;
+    dropIndex(collection: string, label: string, property: string): Promise<boolean>;
+    addEdge(collection: string, edge: AddEdgeRequest): Promise<void>;
+    getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
+    traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
+    getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
 }
 
-export { type BackendType, type Collection, type CollectionConfig, type CollectionType, ConnectionError, type DistanceMetric, type FusionStrategy, type IVelesDBBackend, type MultiQuerySearchOptions, NotFoundError, RestBackend, type SearchOptions, type SearchResult, type StorageMode, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, WasmBackend };
+export { type AddEdgeRequest, type BackendType, type Collection, type CollectionConfig, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type FusionStrategy, type GetEdgesOptions, type GraphEdge, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, NotFoundError, RestBackend, type SearchOptions, type SearchResult, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, WasmBackend };

package/dist/index.d.ts

@@ -104,6 +104,117 @@ interface SearchResult {
     /** Vector data (if includeVectors is true) */
     vector?: number[];
 }
+/** Graph edge representing a relationship between nodes */
+interface GraphEdge {
+    /** Unique edge ID */
+    id: number;
+    /** Source node ID */
+    source: number;
+    /** Target node ID */
+    target: number;
+    /** Edge label (relationship type, e.g., "KNOWS", "FOLLOWS") */
+    label: string;
+    /** Edge properties */
+    properties?: Record<string, unknown>;
+}
+/** Request to add an edge to the graph */
+interface AddEdgeRequest {
+    /** Unique edge ID */
+    id: number;
+    /** Source node ID */
+    source: number;
+    /** Target node ID */
+    target: number;
+    /** Edge label (relationship type) */
+    label: string;
+    /** Edge properties (optional) */
+    properties?: Record<string, unknown>;
+}
+/** Response containing edges */
+interface EdgesResponse {
+    /** List of edges */
+    edges: GraphEdge[];
+    /** Total count of edges returned */
+    count: number;
+}
+/** Options for querying edges */
+interface GetEdgesOptions {
+    /** Filter by edge label */
+    label?: string;
+}
+/** Request for graph traversal (EPIC-016 US-050) */
+interface TraverseRequest {
+    /** Source node ID to start traversal from */
+    source: number;
+    /** Traversal strategy: 'bfs' or 'dfs' */
+    strategy?: 'bfs' | 'dfs';
+    /** Maximum traversal depth */
+    maxDepth?: number;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Optional cursor for pagination */
+    cursor?: string;
+    /** Filter by relationship types (empty = all types) */
+    relTypes?: string[];
+}
+/** A single traversal result item */
+interface TraversalResultItem {
+    /** Target node ID reached */
+    targetId: number;
+    /** Depth of traversal (number of hops from source) */
+    depth: number;
+    /** Path taken (list of edge IDs) */
+    path: number[];
+}
+/** Statistics from traversal operation */
+interface TraversalStats {
+    /** Number of nodes visited */
+    visited: number;
+    /** Maximum depth reached */
+    depthReached: number;
+}
+/** Response from graph traversal */
+interface TraverseResponse {
+    /** List of traversal results */
+    results: TraversalResultItem[];
+    /** Cursor for next page (if applicable) */
+    nextCursor?: string;
+    /** Whether more results are available */
+    hasMore: boolean;
+    /** Traversal statistics */
+    stats: TraversalStats;
+}
+/** Response for node degree query */
+interface DegreeResponse {
+    /** Number of incoming edges */
+    inDegree: number;
+    /** Number of outgoing edges */
+    outDegree: number;
+}
+/** Index type for property indexes */
+type IndexType = 'hash' | 'range';
+/** Index information */
+interface IndexInfo {
+    /** Node label (e.g., "Person") */
+    label: string;
+    /** Property name (e.g., "email") */
+    property: string;
+    /** Index type: 'hash' for O(1) equality, 'range' for O(log n) range queries */
+    indexType: IndexType;
+    /** Number of unique values indexed (for hash indexes) */
+    cardinality: number;
+    /** Memory usage in bytes */
+    memoryBytes: number;
+}
+/** Options for creating an index */
+interface CreateIndexOptions {
+    /** Node label to index */
+    label: string;
+    /** Property name to index */
+    property: string;
+    /** Index type: 'hash' (default) or 'range' */
+    indexType?: IndexType;
+}
 /** Backend interface that all backends must implement */
 interface IVelesDBBackend {
     /** Initialize the backend */
@@ -155,6 +266,22 @@ interface IVelesDBBackend {
     flush(collection: string): Promise<void>;
     /** Close/cleanup the backend */
     close(): Promise<void>;
+    /** Create a property index for O(1) equality lookups */
+    createIndex(collection: string, options: CreateIndexOptions): Promise<void>;
+    /** List all indexes on a collection */
+    listIndexes(collection: string): Promise<IndexInfo[]>;
+    /** Check if an index exists */
+    hasIndex(collection: string, label: string, property: string): Promise<boolean>;
+    /** Drop an index */
+    dropIndex(collection: string, label: string, property: string): Promise<boolean>;
+    /** Add an edge to the collection's knowledge graph */
+    addEdge(collection: string, edge: AddEdgeRequest): Promise<void>;
+    /** Get edges from the collection's knowledge graph */
+    getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
+    /** Traverse the graph using BFS or DFS from a source node */
+    traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
+    /** Get the in-degree and out-degree of a node */
+    getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
 }
 /** Error types */
 declare class VelesDBError extends Error {
@@ -391,6 +518,117 @@ declare class VelesDB {
      * Get the current backend type
      */
     get backendType(): string;
+    /**
+     * Create a property index for O(1) equality lookups or O(log n) range queries
+     *
+     * @param collection - Collection name
+     * @param options - Index configuration (label, property, indexType)
+     *
+     * @example
+     * ```typescript
+     * // Create hash index for fast email lookups
+     * await db.createIndex('users', { label: 'Person', property: 'email' });
+     *
+     * // Create range index for timestamp queries
+     * await db.createIndex('events', { label: 'Event', property: 'timestamp', indexType: 'range' });
+     * ```
+     */
+    createIndex(collection: string, options: CreateIndexOptions): Promise<void>;
+    /**
+     * List all indexes on a collection
+     *
+     * @param collection - Collection name
+     * @returns Array of index information
+     */
+    listIndexes(collection: string): Promise<IndexInfo[]>;
+    /**
+     * Check if an index exists
+     *
+     * @param collection - Collection name
+     * @param label - Node label
+     * @param property - Property name
+     * @returns true if index exists
+     */
+    hasIndex(collection: string, label: string, property: string): Promise<boolean>;
+    /**
+     * Drop an index
+     *
+     * @param collection - Collection name
+     * @param label - Node label
+     * @param property - Property name
+     * @returns true if index was dropped, false if it didn't exist
+     */
+    dropIndex(collection: string, label: string, property: string): Promise<boolean>;
+    /**
+     * Add an edge to the collection's knowledge graph
+     *
+     * @param collection - Collection name
+     * @param edge - Edge to add (id, source, target, label, properties)
+     *
+     * @example
+     * ```typescript
+     * await db.addEdge('social', {
+     *   id: 1,
+     *   source: 100,
+     *   target: 200,
+     *   label: 'FOLLOWS',
+     *   properties: { since: '2024-01-01' }
+     * });
+     * ```
+     */
+    addEdge(collection: string, edge: AddEdgeRequest): Promise<void>;
+    /**
+     * Get edges from the collection's knowledge graph
+     *
+     * @param collection - Collection name
+     * @param options - Query options (filter by label)
+     * @returns Array of edges
+     *
+     * @example
+     * ```typescript
+     * // Get all edges with label "FOLLOWS"
+     * const edges = await db.getEdges('social', { label: 'FOLLOWS' });
+     * ```
+     */
+    getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
+    /**
+     * Traverse the graph using BFS or DFS from a source node
+     *
+     * @param collection - Collection name
+     * @param request - Traversal request options
+     * @returns Traversal response with results and stats
+     *
+     * @example
+     * ```typescript
+     * // BFS traversal from node 100
+     * const result = await db.traverseGraph('social', {
+     *   source: 100,
+     *   strategy: 'bfs',
+     *   maxDepth: 3,
+     *   limit: 100,
+     *   relTypes: ['FOLLOWS', 'KNOWS']
+     * });
+     *
+     * for (const node of result.results) {
+     *   console.log(`Reached node ${node.targetId} at depth ${node.depth}`);
+     * }
+     * ```
+     */
+    traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
+    /**
+     * Get the in-degree and out-degree of a node
+     *
+     * @param collection - Collection name
+     * @param nodeId - Node ID
+     * @returns Degree response with inDegree and outDegree
+     *
+     * @example
+     * ```typescript
+     * const degree = await db.getNodeDegree('social', 100);
+     * console.log(`In: ${degree.inDegree}, Out: ${degree.outDegree}`);
+     * ```
+     */
+    getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
 }
 
 /**
@@ -441,6 +679,14 @@ declare class WasmBackend implements IVelesDBBackend {
     flush(collectionName: string): Promise<void>;
     close(): Promise<void>;
     private toNumericId;
+    createIndex(_collection: string, _options: CreateIndexOptions): Promise<void>;
+    listIndexes(_collection: string): Promise<IndexInfo[]>;
+    hasIndex(_collection: string, _label: string, _property: string): Promise<boolean>;
+    dropIndex(_collection: string, _label: string, _property: string): Promise<boolean>;
+    addEdge(_collection: string, _edge: AddEdgeRequest): Promise<void>;
+    getEdges(_collection: string, _options?: GetEdgesOptions): Promise<GraphEdge[]>;
+    traverseGraph(_collection: string, _request: TraverseRequest): Promise<TraverseResponse>;
+    getNodeDegree(_collection: string, _nodeId: number): Promise<DegreeResponse>;
 }
 
 /**
@@ -463,6 +709,8 @@ declare class RestBackend implements IVelesDBBackend {
     init(): Promise<void>;
     isInitialized(): boolean;
     private ensureInitialized;
+    private mapStatusToErrorCode;
+    private extractErrorPayload;
     private request;
     createCollection(name: string, config: CollectionConfig): Promise<void>;
     deleteCollection(name: string): Promise<void>;
@@ -492,6 +740,14 @@ declare class RestBackend implements IVelesDBBackend {
     isEmpty(collection: string): Promise<boolean>;
     flush(collection: string): Promise<void>;
     close(): Promise<void>;
+    createIndex(collection: string, options: CreateIndexOptions): Promise<void>;
+    listIndexes(collection: string): Promise<IndexInfo[]>;
+    hasIndex(collection: string, label: string, property: string): Promise<boolean>;
+    dropIndex(collection: string, label: string, property: string): Promise<boolean>;
+    addEdge(collection: string, edge: AddEdgeRequest): Promise<void>;
+    getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
+    traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
+    getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
 }
 
-export { type BackendType, type Collection, type CollectionConfig, type CollectionType, ConnectionError, type DistanceMetric, type FusionStrategy, type IVelesDBBackend, type MultiQuerySearchOptions, NotFoundError, RestBackend, type SearchOptions, type SearchResult, type StorageMode, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, WasmBackend };
+export { type AddEdgeRequest, type BackendType, type Collection, type CollectionConfig, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type FusionStrategy, type GetEdgesOptions, type GraphEdge, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, NotFoundError, RestBackend, type SearchOptions, type SearchResult, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, WasmBackend };