@ductape/sdk 0.0.4-v51 → 0.0.4-v52

package/dist/graph/types/schema.interface.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Graph Schema Interfaces
+ *
+ * Types for schema management (indexes, constraints)
+ * Based on Ductape Graph API documentation (overview.md)
+ */
+import { NodeConstraintType, NodeIndexType } from './enums';
+/**
+ * Options for creating a node index
+ * As documented in overview.md
+ */
+export interface ICreateNodeIndexOptions {
+    /** Index name */
+    name: string;
+    /** Node label to index */
+    label: string;
+    /** Properties to include in the index */
+    properties: string[];
+    /** Whether the index should enforce uniqueness */
+    unique?: boolean;
+    /** Index type */
+    type?: NodeIndexType | string;
+    /** Additional index options */
+    options?: {
+        sparse?: boolean;
+        unique?: boolean;
+    };
+}
+/**
+ * Options for creating a node constraint
+ * As documented in overview.md
+ */
+export interface ICreateNodeConstraintOptions {
+    /** Constraint name */
+    name: string;
+    /** Node label */
+    label: string;
+    /** Property to constrain */
+    property?: string;
+    /** Properties to constrain (for multi-property constraints) */
+    properties?: string[];
+    /** Constraint type: UNIQUE, EXISTS, NODE_KEY */
+    type: NodeConstraintType | 'UNIQUE' | 'EXISTS' | 'NODE_KEY';
+}
+/**
+ * Index information
+ */
+export interface IGraphIndex {
+    /** Index name */
+    name: string;
+    /** Label (for node indexes) or type (for relationship indexes) */
+    labelOrType: string;
+    /** Indexed properties */
+    properties: string[];
+    /** Whether unique */
+    unique: boolean;
+    /** Index type */
+    type: string;
+    /** Index state */
+    state?: string;
+}
+/**
+ * Constraint information
+ */
+export interface IGraphConstraint {
+    /** Constraint name */
+    name: string;
+    /** Label */
+    label: string;
+    /** Constrained property */
+    property: string;
+    /** Constraint type */
+    type: string;
+}
+/**
+ * Result of listing indexes
+ */
+export interface IListIndexesResult {
+    /** All indexes */
+    indexes: IGraphIndex[];
+}
+/**
+ * Result of listing constraints
+ */
+export interface IListConstraintsResult {
+    /** All constraints */
+    constraints: IGraphConstraint[];
+}
+/**
+ * Result of creating an index
+ */
+export interface ICreateIndexResult {
+    /** Whether index was created */
+    created: boolean;
+    /** Index name */
+    name: string;
+}
+/**
+ * Result of creating a constraint
+ */
+export interface ICreateConstraintResult {
+    /** Whether constraint was created */
+    created: boolean;
+    /** Constraint name */
+    name: string;
+}
+/**
+ * Result of dropping an index
+ */
+export interface IDropIndexResult {
+    /** Whether index was dropped */
+    dropped: boolean;
+}
+/**
+ * Result of dropping a constraint
+ */
+export interface IDropConstraintResult {
+    /** Whether constraint was dropped */
+    dropped: boolean;
+}
+/**
+ * Property type for schema introspection
+ */
+export type GraphPropertyType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'array' | 'point' | 'object' | 'unknown';
+/**
+ * Property definition for a label
+ */
+export interface IGraphLabelProperty {
+    /** Property name */
+    name: string;
+    /** Property type */
+    type: GraphPropertyType;
+    /** Whether property exists on all nodes with this label */
+    required?: boolean;
+}
+/**
+ * Label definition with schema information
+ */
+export interface IGraphLabel {
+    /** Label name */
+    name: string;
+    /** Number of nodes with this label */
+    count: number;
+    /** Properties found on nodes with this label */
+    properties: IGraphLabelProperty[];
+    /** Display color (optional, for UI purposes) */
+    color?: string;
+}
+/**
+ * Result of listing labels
+ */
+export interface IListLabelsResult {
+    /** All node labels */
+    labels: IGraphLabel[];
+}
+/**
+ * Relationship type definition with schema information
+ */
+export interface IGraphRelationshipType {
+    /** Relationship type name */
+    type: string;
+    /** Number of relationships of this type */
+    count: number;
+    /** Source node label(s) commonly used */
+    fromLabels?: string[];
+    /** Target node label(s) commonly used */
+    toLabels?: string[];
+    /** Properties found on relationships of this type */
+    properties?: IGraphLabelProperty[];
+}
+/**
+ * Result of listing relationship types
+ */
+export interface IListRelationshipTypesResult {
+    /** All relationship types */
+    types: IGraphRelationshipType[];
+}
+/**
+ * Parameter types for graph actions
+ */
+export type GraphActionParameterType = 'string' | 'number' | 'boolean' | 'array' | 'object';
+/**
+ * Parameter definition for a graph action
+ */
+export interface IGraphActionParameter {
+    /** Parameter name (used as placeholder {{name}}) */
+    name: string;
+    /** JSON path to the value in the query object */
+    path: string;
+    /** Default value for the parameter */
+    defaultValue: any;
+    /** Parameter type */
+    type: GraphActionParameterType;
+    /** Optional description */
+    description?: string;
+    /** Whether the parameter is required */
+    required?: boolean;
+}
+/**
+ * Graph action definition
+ * Represents a saved parameterized query that can be executed with different parameter values
+ */
+export interface IGraphAction {
+    /** Unique identifier */
+    id: string;
+    /** Unique tag (URL-safe slug) */
+    tag: string;
+    /** Display name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Operation type (e.g., findNodes, traverse, executeRaw) */
+    operation: string;
+    /** Query object with parameter placeholders */
+    query: Record<string, any>;
+    /** Parameter definitions */
+    parameters: IGraphActionParameter[];
+    /** ISO timestamp when action was created */
+    createdAt: string;
+    /** ISO timestamp when action was last updated */
+    updatedAt?: string;
+    /** Graph tag this action belongs to */
+    graphTag?: string;
+}
+/**
+ * Options for creating a graph action
+ */
+export interface ICreateGraphActionOptions {
+    /** Display name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Operation type */
+    operation: string;
+    /** Query object with parameter placeholders */
+    query: Record<string, any>;
+    /** Parameter definitions */
+    parameters: IGraphActionParameter[];
+    /** Graph tag (optional, defaults to current connected graph) */
+    graphTag?: string;
+}
+/**
+ * Options for updating a graph action
+ */
+export interface IUpdateGraphActionOptions {
+    /** Display name */
+    name?: string;
+    /** Optional description */
+    description?: string;
+    /** Query object with parameter placeholders */
+    query?: Record<string, any>;
+    /** Parameter definitions */
+    parameters?: IGraphActionParameter[];
+}
+/**
+ * Options for executing a graph action
+ */
+export interface IExecuteGraphActionOptions {
+    /** Product tag */
+    product: string;
+    /** Environment slug */
+    env: string;
+    /** Graph tag */
+    graph: string;
+    /** Action tag */
+    action: string;
+    /** Parameter values to substitute */
+    input?: Record<string, any>;
+    /** Session token in format: session_tag:jwt_token */
+    session?: string;
+    /** Cache tag for result caching */
+    cache?: string;
+}
+/**
+ * Result of executing a graph action
+ */
+export interface IExecuteGraphActionResult<T = any> {
+    /** Whether execution was successful */
+    success: boolean;
+    /** Execution time in milliseconds */
+    executionTime: number;
+    /** Result data */
+    data: T[];
+    /** Row count */
+    count: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Result of listing graph actions
+ */
+export interface IListGraphActionsResult {
+    /** All actions for the graph */
+    actions: IGraphAction[];
+}

package/dist/graph/types/schema.interface.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Graph Schema Interfaces
+ *
+ * Types for schema management (indexes, constraints)
+ * Based on Ductape Graph API documentation (overview.md)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=schema.interface.js.map

package/dist/graph/types/schema.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.interface.js","sourceRoot":"","sources":["../../../src/graph/types/schema.interface.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/dist/graph/types/transaction.interface.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Graph Transaction Interfaces
+ *
+ * Types for transaction management
+ * Based on Ductape Graph API documentation (transactions.md, overview.md)
+ */
+import { GraphIsolationLevel, GraphTransactionStatus } from './enums';
+/**
+ * Transaction object
+ * As documented in transactions.md
+ */
+export interface IGraphTransaction {
+    /** Transaction ID */
+    id: string;
+    /** Current transaction status */
+    status: GraphTransactionStatus;
+    /** Underlying database transaction object */
+    client?: any;
+    /** Native transaction object (alias for client, used by some adapters) */
+    nativeTransaction?: any;
+    /** Transaction start time */
+    startTime?: Date;
+    /** Commit the transaction */
+    commit?(): Promise<void>;
+    /** Rollback the transaction */
+    rollback?(): Promise<void>;
+}
+/**
+ * Transaction options
+ * As documented in transactions.md
+ */
+export interface IGraphTransactionOptions {
+    /** Transaction isolation level */
+    isolation?: GraphIsolationLevel | 'READ_COMMITTED' | 'SERIALIZABLE';
+    /** Transaction timeout in milliseconds */
+    timeout?: number;
+    /** Whether transaction is read-only */
+    readOnly?: boolean;
+}
+/**
+ * Transaction callback function type
+ * As documented in transactions.md
+ */
+export type TransactionCallback<T> = (transaction: IGraphTransaction) => Promise<T>;
+/**
+ * Transaction result
+ */
+export interface IGraphTransactionResult<T = any> {
+    /** Result of the transaction operations */
+    result: T;
+    /** Whether transaction was committed successfully */
+    committed: boolean;
+    /** Execution time in milliseconds */
+    executionTime?: number;
+}

package/dist/graph/types/transaction.interface.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Graph Transaction Interfaces
+ *
+ * Types for transaction management
+ * Based on Ductape Graph API documentation (transactions.md, overview.md)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=transaction.interface.js.map

package/dist/graph/types/transaction.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.interface.js","sourceRoot":"","sources":["../../../src/graph/types/transaction.interface.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/dist/graph/types/traversal.interface.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Graph Traversal Interfaces
+ *
+ * Types for traversal and pathfinding operations
+ * Based on Ductape Graph API documentation (traversals.md, overview.md)
+ */
+import { TraversalDirection } from './enums';
+import { INode, INodeFilter } from './node.interface';
+import { IRelationship, IRelationshipFilter } from './relationship.interface';
+/**
+ * Path structure representing a sequence of nodes and relationships
+ */
+export interface IPath<TNode = any, TRel = any> {
+    /** Nodes in the path */
+    nodes: INode<TNode>[];
+    /** Relationships connecting the nodes */
+    relationships: IRelationship<TRel>[];
+    /** Path length (number of relationships) */
+    length: number;
+}
+/**
+ * Options for graph traversal
+ * As documented in traversals.md
+ */
+export interface ITraverseOptions {
+    /** Starting node ID */
+    startNodeId: string | number;
+    /** Traversal direction: OUTGOING, INCOMING, or BOTH */
+    direction?: TraversalDirection | 'OUTGOING' | 'INCOMING' | 'BOTH';
+    /** Relationship types to traverse */
+    relationshipTypes?: string[];
+    /** Maximum depth to traverse */
+    maxDepth?: number;
+    /** Minimum depth to start from */
+    minDepth?: number;
+    /** Filter for nodes in the traversal */
+    nodeFilter?: INodeFilter;
+    /** Filter for relationships in the traversal */
+    relationshipFilter?: IRelationshipFilter;
+    /** Maximum number of paths to return */
+    limit?: number;
+}
+/**
+ * Result of graph traversal
+ * As documented in traversals.md
+ */
+export interface ITraverseResult<TNode = any, TRel = any> {
+    /** All discovered paths */
+    paths?: IPath<TNode, TRel>[];
+    /** All discovered nodes */
+    nodes?: INode<TNode>[];
+    /** All discovered relationships */
+    relationships?: IRelationship<TRel>[];
+    /** Total count of paths */
+    count?: number;
+}
+/**
+ * Options for shortest path finding
+ * As documented in traversals.md
+ */
+export interface IShortestPathOptions {
+    /** Starting node ID */
+    startNodeId: string | number;
+    /** Target node ID */
+    endNodeId: string | number;
+    /** Relationship types to consider */
+    relationshipTypes?: string[];
+    /** Property to use as weight (for weighted shortest path) */
+    weightProperty?: string;
+    /** Maximum depth to search */
+    maxDepth?: number;
+    /** Whether to respect relationship direction */
+    directed?: boolean;
+}
+/**
+ * Result of shortest path finding
+ * As documented in traversals.md
+ */
+export interface IShortestPathResult<TNode = any, TRel = any> {
+    /** The shortest path found (null if no path exists) */
+    path: IPath<TNode, TRel> | null;
+    /** Total weight (if using weighted path) */
+    totalWeight?: number;
+    /** Path length (number of relationships) */
+    length?: number;
+    /** Whether a path was found */
+    found?: boolean;
+}
+/**
+ * Options for finding all paths
+ * As documented in traversals.md
+ */
+export interface IAllPathsOptions {
+    /** Starting node ID */
+    startNodeId: string | number;
+    /** Target node ID */
+    endNodeId: string | number;
+    /** Relationship types to consider */
+    relationshipTypes?: string[];
+    /** Minimum path depth */
+    minDepth?: number;
+    /** Maximum path depth */
+    maxDepth?: number;
+    /** Maximum number of paths to return */
+    limit?: number;
+    /** Maximum number of paths to return (alias for limit) */
+    maxPaths?: number;
+    /** Whether to respect relationship direction */
+    directed?: boolean;
+}
+/**
+ * Result of finding all paths
+ * As documented in traversals.md
+ */
+export interface IAllPathsResult<TNode = any, TRel = any> {
+    /** All paths found */
+    paths: IPath<TNode, TRel>[];
+    /** Total count of paths */
+    count?: number;
+    /** Total count of paths (alias for count) */
+    total?: number;
+}
+/**
+ * Options for getting neighborhood
+ * As documented in traversals.md
+ */
+export interface INeighborhoodOptions {
+    /** Starting node ID */
+    nodeId: string | number;
+    /** Depth of neighborhood to explore */
+    depth?: number;
+    /** Traversal direction */
+    direction?: TraversalDirection | 'OUTGOING' | 'INCOMING' | 'BOTH';
+    /** Relationship types to consider */
+    relationshipTypes?: string[];
+    /** Filter for nodes */
+    nodeFilter?: INodeFilter;
+    /** Maximum number of results */
+    limit?: number;
+}
+/**
+ * Result of neighborhood exploration
+ * As documented in traversals.md
+ */
+export interface INeighborhoodResult<TNode = any, TRel = any> {
+    /** All nodes in the neighborhood */
+    nodes: INode<TNode>[];
+    /** All relationships in the neighborhood */
+    relationships: IRelationship<TRel>[];
+    /** Depth of exploration */
+    depth?: number;
+}
+/**
+ * Options for finding connected components
+ * As documented in traversals.md
+ */
+export interface IConnectedComponentsOptions {
+    /** Relationship types to consider */
+    relationshipTypes?: string[];
+    /** Node labels to filter by */
+    labels?: string[];
+}
+/**
+ * Connected component structure
+ */
+export interface IConnectedComponent<TNode = any> {
+    /** Nodes in the component */
+    nodes: INode<TNode>[];
+    /** Component size */
+    size: number;
+}
+/**
+ * Result of finding connected components
+ * As documented in traversals.md
+ */
+export interface IConnectedComponentsResult<TNode = any> {
+    /** All connected components */
+    components: IConnectedComponent<TNode>[];
+    /** Total number of components */
+    count: number;
+}

package/dist/graph/types/traversal.interface.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Graph Traversal Interfaces
+ *
+ * Types for traversal and pathfinding operations
+ * Based on Ductape Graph API documentation (traversals.md, overview.md)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=traversal.interface.js.map

package/dist/graph/types/traversal.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traversal.interface.js","sourceRoot":"","sources":["../../../src/graph/types/traversal.interface.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/dist/graph/utils/graph-error.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Graph Error
+ *
+ * Custom error class for graph database operations
+ * As documented in overview.md
+ */
+import { GraphErrorType } from '../types/enums';
+/**
+ * Custom error class for graph database operations
+ */
+export declare class GraphError extends Error {
+    /** Error type */
+    readonly type: GraphErrorType;
+    /** Original error if wrapped */
+    readonly originalError?: Error;
+    /** Additional error details */
+    readonly details?: Record<string, any>;
+    constructor(message: string, type?: GraphErrorType, originalError?: Error, details?: Record<string, any>);
+    /**
+     * Create a connection error
+     */
+    static connectionError(message: string, originalError?: Error): GraphError;
+    /**
+     * Create a query error
+     */
+    static queryError(message: string, originalError?: Error, details?: Record<string, any>): GraphError;
+    /**
+     * Create a validation error
+     */
+    static validationError(message: string, details?: Record<string, any>): GraphError;
+    /**
+     * Create a not found error
+     */
+    static notFoundError(message: string): GraphError;
+    /**
+     * Create a constraint violation error
+     */
+    static constraintError(message: string, originalError?: Error, details?: Record<string, any>): GraphError;
+    /**
+     * Create a transaction error
+     */
+    static transactionError(message: string, originalError?: Error): GraphError;
+    /**
+     * Create a timeout error
+     */
+    static timeoutError(message: string): GraphError;
+    /**
+     * Create an authentication error
+     */
+    static authenticationError(message: string): GraphError;
+    /**
+     * Create a configuration error
+     */
+    static configurationError(message: string, details?: Record<string, any>): GraphError;
+    /**
+     * Create an unsupported operation error
+     */
+    static unsupportedOperationError(operation: string, graphType: string): GraphError;
+    /**
+     * Wrap an unknown error as a GraphError
+     */
+    static wrap(error: unknown, defaultType?: GraphErrorType): GraphError;
+    /**
+     * Detect error type from error message
+     */
+    private static detectErrorType;
+    /**
+     * Convert error to JSON representation
+     */
+    toJSON(): Record<string, any>;
+}