@ductape/sdk 0.1.6 → 0.1.8

package/dist/graph/graphs.service.d.ts

@@ -1,617 +0,0 @@
-/**
- * Graph Service
- *
- * Main service class for graph database operations.
- * Provides a unified API for working with different graph databases
- * (Neo4j, Neptune, ArangoDB, Memgraph).
- *
- * Based on Ductape Graph API documentation.
- */
-import { GraphFeature } from './types/enums';
-import { IGraphConfig, IGraphConnectionConfig, IGraphConnectionResult, IGraphConnectionContext, IGraphServiceConfig, IGraphTestConnectionResult } from './types/connection.interface';
-import { ICreateNodeOptions, ICreateNodeResult, IFindNodesOptions, IFindNodesResult, IUpdateNodeOptions, IUpdateNodeResult, IDeleteNodeOptions, IDeleteNodeResult, IMergeNodeOptions, IMergeNodeResult, INode, IAddLabelsOptions, IAddLabelsResult, IRemoveLabelsOptions, IRemoveLabelsResult, ISetLabelsOptions, ISetLabelsResult } from './types/node.interface';
-import { ICreateRelationshipOptions, ICreateRelationshipResult, IFindRelationshipsOptions, IFindRelationshipsResult, IUpdateRelationshipOptions, IUpdateRelationshipResult, IDeleteRelationshipOptions, IDeleteRelationshipResult, IMergeRelationshipOptions, IMergeRelationshipResult, IRelationship, ICreateRelationshipIndexOptions } from './types/relationship.interface';
-import { ITraverseOptions, ITraverseResult, IShortestPathOptions, IShortestPathResult, IAllPathsOptions, IAllPathsResult, INeighborhoodOptions, INeighborhoodResult, IConnectedComponentsOptions, IConnectedComponentsResult } from './types/traversal.interface';
-import { IGraphTransaction, IGraphTransactionOptions, TransactionCallback } from './types/transaction.interface';
-import { IRawQueryResult, ICountNodesResult, ICountRelationshipsResult, IGraphStatistics, IFullTextSearchOptions, IFullTextSearchResult, IVectorSearchOptions, IVectorSearchResult, IGraphWhereClause } from './types/query.interface';
-import { ICreateNodeIndexOptions, ICreateNodeConstraintOptions, IListIndexesResult, IListConstraintsResult, ICreateIndexResult, ICreateConstraintResult, IDropIndexResult, IDropConstraintResult, IListLabelsResult, IListRelationshipTypesResult, IGraphAction, ICreateGraphActionOptions, IUpdateGraphActionOptions, IExecuteGraphActionOptions, IExecuteGraphActionResult, IListGraphActionsResult } from './types/schema.interface';
-import { IProductGraph } from '../types/productsBuilder.types';
-import { IGraphActionDispatchInput, IGraphOperationDispatchInput, IDispatchResult } from '../types/processor.types';
-/**
- * Main graph database service
- */
-export declare class GraphService {
-    /** Adapter factory for creating database-specific adapters */
-    private adapterFactory;
-    /** Cache of adapters by connection key */
-    private adapters;
-    /** Connection contexts */
-    private connectionContexts;
-    /** Currently active connection context */
-    private currentContext;
-    /** Transaction manager */
-    private transactionManager;
-    /** Service configuration */
-    private config;
-    /** Product builders cache */
-    private productBuilders;
-    /** Local graph configurations */
-    private localConfigs;
-    /** LogService instance for logging operations */
-    private logService;
-    /** Current product ID for logging */
-    private productId;
-    /** CacheManager for two-tier caching (Redis + remote) */
-    private cacheManager;
-    /** Private keys cache for products (keyed by product tag) */
-    private privateKeys;
-    private _privateKey;
-    constructor(config?: IGraphServiceConfig & {
-        private_key: string;
-        access_key: string;
-    });
-    /**
-     * Update service configuration
-     */
-    updateConfig(config: IGraphServiceConfig & {
-        private_key: string;
-        access_key: string;
-    }): void;
-    /**
-     * Get service configuration
-     */
-    getConfig(): IGraphServiceConfig | null;
-    /**
-     * Create a new ProductBuilder instance
-     */
-    private createNewProductBuilder;
-    /**
-     * Get or create a ProductBuilder instance for the given product tag
-     */
-    private getProductBuilder;
-    /**
-     * Initialize logging service
-     */
-    private initializeLogService;
-    /**
-     * Create a new ProcessorService instance for job scheduling
-     */
-    private createNewProcessor;
-    /**
-     * Register a new graph database
-     * As documented in getting-started.md
-     *
-     * @example
-     * ```ts
-     * await ductape.graph.create({
-     *   name: 'Social Graph',
-     *   tag: 'social-graph',
-     *   type: 'neo4j',
-     *   description: 'Stores user relationships',
-     *   envs: [
-     *     { slug: 'dev', connection_url: 'bolt://localhost:7687' },
-     *     { slug: 'prd', connection_url: 'bolt://neo4j-prod:7687' },
-     *   ],
-     * });
-     * ```
-     */
-    create(graphConfig: IGraphConfig, productTag?: string): Promise<void>;
-    /**
-     * Create local adapter and connection context for a graph configuration.
-     * This is a lightweight operation that only sets up local state without API calls.
-     * Use this when the graph config is already fetched/decrypted from the API.
-     *
-     * @param graphConfig - The graph configuration (already decrypted if from API)
-     */
-    private createAdapter;
-    /**
-     * Generate a secret key for graph configuration field
-     * Format: GRAPH_{PRODUCT}_{ASSET_TAG}_{ENV}_{KEY}
-     *
-     * Where:
-     * - PRODUCT = productTag.split('.')[1] (second part after workspace)
-     * - ASSET_TAG = if graphTag starts with same workspace prefix, use second part; otherwise sanitize full tag
-     * - All parts are automatically capitalized
-     */
-    private generateGraphSecretKey;
-    /**
-     * Store a value as a secret if it exists and is not already a secret reference
-     * @returns The secret reference if stored, or the original value
-     */
-    private storeAsSecretIfNeeded;
-    /**
-     * Fetch all graphs for a product using the product component fetcher
-     * @param productTag - The product tag
-     * @returns Array of IProductGraph objects
-     */
-    fetchAllGraphs(productTag: string): Promise<IProductGraph[]>;
-    /**
-     * Fetch a specific graph by tag using the product component fetcher
-     * @param productTag - The product tag
-     * @param graphTag - The graph tag
-     * @returns The IProductGraph object or null if not found
-     */
-    fetchGraphByTag(productTag: string, graphTag: string): Promise<IProductGraph | null>;
-    /**
-     * Fetch all registered graphs for a product
-     */
-    fetchAll(productTag?: string): Promise<IGraphConfig[]>;
-    /**
-     * Fetch a specific graph configuration
-     */
-    fetch(graphTag: string, productTag?: string): Promise<IGraphConfig | null>;
-    /**
-     * Update graph configuration
-     */
-    update(graphTag: string, updates: Partial<IGraphConfig>, productTag?: string): Promise<void>;
-    /**
-     * Delete a graph configuration
-     */
-    delete(graphTag: string, productTag?: string): Promise<void>;
-    /**
-     * Convert IProductGraph to IGraphConfig
-     */
-    private productGraphToConfig;
-    /**
-     * Connect to a graph database
-     * As documented in getting-started.md
-     *
-     * @example
-     * ```ts
-     * await ductape.graph.connect({
-     *   env: 'dev',
-     *   product: 'my-app',
-     *   graph: 'social-graph',
-     * });
-     * ```
-     */
-    connect(config: IGraphConnectionConfig): Promise<IGraphConnectionResult>;
-    /**
-     * Disconnect any existing connection to this graph from the SDK (shared registry and this instance) before creating a fresh one.
-     */
-    private disconnectExistingForResource;
-    private connectAndRegisterGraphShared;
-    private runGraphConnect;
-    /**
-     * Test connection to a graph database
-     */
-    testConnection(config: IGraphConnectionConfig): Promise<IGraphTestConnectionResult>;
-    /**
-     * Disconnect from current graph
-     */
-    disconnect(): Promise<void>;
-    /**
-     * Disconnect from all graphs
-     */
-    closeAll(): Promise<void>;
-    /**
-     * Create a node
-     * As documented in nodes.md
-     */
-    createNode<T = any>(options: ICreateNodeOptions<T> & {
-        session?: string;
-    }, transaction?: IGraphTransaction): Promise<ICreateNodeResult<T>>;
-    /**
-     * Find nodes by criteria
-     * As documented in nodes.md
-     */
-    findNodes<T = any>(options: IFindNodesOptions & {
-        session?: string;
-    }, transaction?: IGraphTransaction): Promise<IFindNodesResult<T>>;
-    /**
-     * Find a node by ID
-     * As documented in nodes.md
-     */
-    findNodeById<T = any>(id: string | number, transaction?: IGraphTransaction): Promise<INode<T> | null>;
-    /**
-     * Update a node
-     * As documented in nodes.md
-     */
-    updateNode<T = any>(options: IUpdateNodeOptions<T> & {
-        session?: string;
-    }, transaction?: IGraphTransaction): Promise<IUpdateNodeResult<T>>;
-    /**
-     * Delete a node
-     * As documented in nodes.md
-     */
-    deleteNode(options: IDeleteNodeOptions & {
-        session?: string;
-    }, transaction?: IGraphTransaction): Promise<IDeleteNodeResult>;
-    /**
-     * Merge (upsert) a node
-     * As documented in nodes.md
-     */
-    mergeNode<T = any>(options: IMergeNodeOptions<T>, transaction?: IGraphTransaction): Promise<IMergeNodeResult<T>>;
-    /**
-     * Add labels to an existing node
-     *
-     * @example
-     * ```ts
-     * const result = await graphService.addLabels({
-     *   id: 'node-123',
-     *   labels: ['Admin', 'Verified'],
-     * });
-     * console.log(result.node.labels); // ['Person', 'Admin', 'Verified']
-     * ```
-     */
-    addLabels<T = any>(options: IAddLabelsOptions, transaction?: IGraphTransaction): Promise<IAddLabelsResult<T>>;
-    /**
-     * Remove labels from an existing node
-     *
-     * @example
-     * ```ts
-     * const result = await graphService.removeLabels({
-     *   id: 'node-123',
-     *   labels: ['Temporary'],
-     * });
-     * console.log(result.removedLabels); // ['Temporary']
-     * ```
-     */
-    removeLabels<T = any>(options: IRemoveLabelsOptions, transaction?: IGraphTransaction): Promise<IRemoveLabelsResult<T>>;
-    /**
-     * Set labels on a node (replaces all existing labels)
-     *
-     * @example
-     * ```ts
-     * const result = await graphService.setLabels({
-     *   id: 'node-123',
-     *   labels: ['Person', 'Employee'],
-     * });
-     * console.log(result.previousLabels); // ['Person', 'Contractor']
-     * console.log(result.newLabels); // ['Person', 'Employee']
-     * ```
-     */
-    setLabels<T = any>(options: ISetLabelsOptions, transaction?: IGraphTransaction): Promise<ISetLabelsResult<T>>;
-    /**
-     * Create a relationship
-     * As documented in relationships.md
-     */
-    createRelationship<T = any>(options: ICreateRelationshipOptions<T> & {
-        session?: string;
-    }, transaction?: IGraphTransaction): Promise<ICreateRelationshipResult<T>>;
-    /**
-     * Find relationships by criteria
-     * As documented in relationships.md
-     */
-    findRelationships<T = any>(options: IFindRelationshipsOptions & {
-        session?: string;
-    }, transaction?: IGraphTransaction): Promise<IFindRelationshipsResult<T>>;
-    /**
-     * Find a relationship by ID
-     */
-    findRelationshipById<T = any>(id: string | number, transaction?: IGraphTransaction): Promise<IRelationship<T> | null>;
-    /**
-     * Update a relationship
-     * As documented in relationships.md
-     */
-    updateRelationship<T = any>(options: IUpdateRelationshipOptions<T> & {
-        session?: string;
-    }, transaction?: IGraphTransaction): Promise<IUpdateRelationshipResult<T>>;
-    /**
-     * Delete a relationship
-     * As documented in relationships.md
-     */
-    deleteRelationship(options: IDeleteRelationshipOptions & {
-        session?: string;
-    }, transaction?: IGraphTransaction): Promise<IDeleteRelationshipResult>;
-    /**
-     * Merge (upsert) a relationship
-     * As documented in relationships.md
-     */
-    mergeRelationship<T = any>(options: IMergeRelationshipOptions<T>, transaction?: IGraphTransaction): Promise<IMergeRelationshipResult<T>>;
-    /**
-     * Traverse the graph from a starting node
-     * As documented in traversals.md
-     */
-    traverse<TNode = any, TRel = any>(options: ITraverseOptions, transaction?: IGraphTransaction): Promise<ITraverseResult<TNode, TRel>>;
-    /**
-     * Find the shortest path between two nodes
-     * As documented in traversals.md
-     */
-    shortestPath<TNode = any, TRel = any>(options: IShortestPathOptions, transaction?: IGraphTransaction): Promise<IShortestPathResult<TNode, TRel>>;
-    /**
-     * Find all paths between two nodes
-     * As documented in traversals.md
-     */
-    allPaths<TNode = any, TRel = any>(options: IAllPathsOptions, transaction?: IGraphTransaction): Promise<IAllPathsResult<TNode, TRel>>;
-    /**
-     * Get the neighborhood of a node
-     * As documented in traversals.md
-     */
-    getNeighborhood<TNode = any, TRel = any>(options: INeighborhoodOptions, transaction?: IGraphTransaction): Promise<INeighborhoodResult<TNode, TRel>>;
-    /**
-     * Find connected components in the graph
-     * As documented in traversals.md
-     */
-    findConnectedComponents<TNode = any>(options: IConnectedComponentsOptions, transaction?: IGraphTransaction): Promise<IConnectedComponentsResult<TNode>>;
-    /**
-     * Count nodes matching criteria
-     * As documented in overview.md
-     */
-    countNodes(labels?: string[], where?: IGraphWhereClause, transaction?: IGraphTransaction, session?: string): Promise<ICountNodesResult>;
-    /**
-     * Count relationships matching criteria
-     * As documented in overview.md
-     */
-    countRelationships(types?: string[], where?: IGraphWhereClause, transaction?: IGraphTransaction): Promise<ICountRelationshipsResult>;
-    /**
-     * Get graph statistics
-     * As documented in overview.md
-     */
-    getStatistics(transaction?: IGraphTransaction, session?: string): Promise<IGraphStatistics>;
-    /**
-     * Full-text search
-     * As documented in overview.md
-     */
-    fullTextSearch<T = any>(options: IFullTextSearchOptions, transaction?: IGraphTransaction): Promise<IFullTextSearchResult<T>>;
-    /**
-     * Vector similarity search
-     * As documented in overview.md
-     */
-    vectorSearch<T = any>(options: IVectorSearchOptions, transaction?: IGraphTransaction): Promise<IVectorSearchResult<T>>;
-    /**
-     * Execute a raw query
-     * As documented in overview.md
-     *
-     * @example
-     * ```ts
-     * const result = await ductape.graph.query(
-     *   'MATCH (p:Person)-[:FRIENDS_WITH]->(f) WHERE p.name = $name RETURN f',
-     *   { name: 'Alice' }
-     * );
-     * ```
-     */
-    query<T = any>(queryString: string, params?: Record<string, any>, transaction?: IGraphTransaction): Promise<IRawQueryResult<T>>;
-    /**
-     * Create a node index
-     * As documented in overview.md
-     */
-    createNodeIndex(options: ICreateNodeIndexOptions): Promise<ICreateIndexResult>;
-    /**
-     * Create a node constraint
-     * As documented in overview.md
-     */
-    createNodeConstraint(options: ICreateNodeConstraintOptions): Promise<ICreateConstraintResult>;
-    /**
-     * Create a relationship index
-     */
-    createRelationshipIndex(options: ICreateRelationshipIndexOptions): Promise<ICreateIndexResult>;
-    /**
-     * List all indexes
-     * As documented in overview.md
-     */
-    listIndexes(): Promise<IListIndexesResult>;
-    /**
-     * List all constraints
-     */
-    listConstraints(): Promise<IListConstraintsResult>;
-    /**
-     * Drop an index
-     */
-    dropIndex(name: string): Promise<IDropIndexResult>;
-    /**
-     * Drop a constraint
-     */
-    dropConstraint(name: string): Promise<IDropConstraintResult>;
-    /**
-     * List all node labels with counts and property information
-     * Used for GraphExplorer sidebar
-     */
-    listLabels(): Promise<IListLabelsResult>;
-    /**
-     * List all relationship types with counts
-     * Used for GraphExplorer sidebar
-     */
-    listRelationshipTypes(): Promise<IListRelationshipTypesResult>;
-    /** Local cache of graph actions */
-    private actions;
-    /**
-     * Generate a URL-safe tag from a name
-     */
-    private generateActionTag;
-    /**
-     * Create a new graph action (saved parameterized query)
-     *
-     * @example
-     * ```ts
-     * const action = await graphService.createAction({
-     *   name: 'Find Persons',
-     *   description: 'Find persons with configurable limit',
-     *   operation: 'findNodes',
-     *   query: {
-     *     operation: 'findNodes',
-     *     options: { labels: ['Person'], limit: '{{limit}}' }
-     *   },
-     *   parameters: [
-     *     { name: 'limit', path: 'options.limit', defaultValue: 25, type: 'number' }
-     *   ]
-     * }, 'my-product');
-     * ```
-     */
-    createAction(options: ICreateGraphActionOptions, productTag?: string): Promise<IGraphAction>;
-    /**
-     * List all actions for a graph
-     */
-    listActions(graphTag?: string, productTag?: string): Promise<IListGraphActionsResult>;
-    /**
-     * Get a specific action by tag
-     */
-    getAction(actionTag: string, graphTag?: string, productTag?: string): Promise<IGraphAction | null>;
-    /**
-     * Update an existing action
-     */
-    updateAction(actionTag: string, updates: IUpdateGraphActionOptions, graphTag?: string, productTag?: string): Promise<IGraphAction>;
-    /**
-     * Delete an action
-     */
-    deleteAction(actionTag: string, graphTag?: string, productTag?: string): Promise<void>;
-    /**
-     * Execute a graph action with parameter substitution
-     *
-     * @example
-     * ```ts
-     * const result = await graphService.execute({
-     *   product: 'my-app',
-     *   env: 'dev',
-     *   graph: 'social-graph',
-     *   action: 'find-persons',
-     *   input: { limit: 50 }
-     * });
-     * ```
-     */
-    execute<T = any>(options: IExecuteGraphActionOptions): Promise<IExecuteGraphActionResult<T>>;
-    /**
-     * Action dispatch operations - for predefined graph actions.
-     */
-    get action(): {
-        /**
-         * Dispatches a graph action to run as a scheduled job.
-         * @param {IGraphActionDispatchInput} data - The graph action dispatch input.
-         * @returns {Promise<IDispatchResult>} The dispatch result with job ID and status.
-         * @example
-         * // Schedule a graph action to run in 1 hour
-         * await ductape.graph.action.dispatch({
-         *   product: 'my-product',
-         *   env: 'production',
-         *   graph: 'social-graph',
-         *   event: 'compute-recommendations',
-         *   input: { userId: '123', limit: 10 },
-         *   schedule: { start_at: Date.now() + 3600000 }
-         * });
-         *
-         * // Run on a cron schedule
-         * await ductape.graph.action.dispatch({
-         *   product: 'my-product',
-         *   env: 'production',
-         *   graph: 'analytics-graph',
-         *   event: 'aggregate-metrics',
-         *   input: {},
-         *   schedule: { cron: '0 0 * * *' } // Daily at midnight
-         * });
-         */
-        dispatch: (data: IGraphActionDispatchInput) => Promise<IDispatchResult>;
-    };
-    /**
-     * Dispatches a graph operation to run as a scheduled job.
-     * Use this for direct graph operations (traverse, query, createNode, deleteNodes, etc.).
-     * @param {IGraphOperationDispatchInput} data - The graph operation dispatch input.
-     * @returns {Promise<IDispatchResult>} The dispatch result with job ID and status.
-     * @example
-     * // Schedule a graph traversal operation
-     * await ductape.graph.dispatch({
-     *   product: 'my-product',
-     *   env: 'production',
-     *   graph: 'social-graph',
-     *   operation: 'traverse',
-     *   input: { startNode: 'user:123', direction: 'outgoing', depth: 3 },
-     *   schedule: { start_at: Date.now() + 3600000 }
-     * });
-     *
-     * // Run periodic graph cleanup
-     * await ductape.graph.dispatch({
-     *   product: 'my-product',
-     *   env: 'production',
-     *   graph: 'session-graph',
-     *   operation: 'deleteNodes',
-     *   input: { filter: { expired: true } },
-     *   schedule: { cron: '0 4 * * *' } // Daily at 4 AM
-     * });
-     */
-    dispatch(data: IGraphOperationDispatchInput): Promise<IDispatchResult>;
-    /**
-     * Substitute parameter placeholders in a query object
-     */
-    private substituteParameters;
-    /**
-     * Set a nested value in an object using a dot-notation path
-     */
-    private setNestedValue;
-    /**
-     * Execute an operation based on the query object
-     */
-    private executeOperation;
-    /**
-     * Execute operations within a transaction
-     * As documented in transactions.md
-     *
-     * @example
-     * ```ts
-     * const result = await ductape.graph.executeTransaction(async (transaction) => {
-     *   const alice = await ductape.graph.createNode({
-     *     labels: ['Person'],
-     *     properties: { name: 'Alice' },
-     *   }, transaction);
-     *
-     *   const bob = await ductape.graph.createNode({
-     *     labels: ['Person'],
-     *     properties: { name: 'Bob' },
-     *   }, transaction);
-     *
-     *   await ductape.graph.createRelationship({
-     *     type: 'FRIENDS_WITH',
-     *     startNodeId: alice.node.id,
-     *     endNodeId: bob.node.id,
-     *   }, transaction);
-     *
-     *   return { alice, bob };
-     * });
-     * ```
-     */
-    executeTransaction<T>(callback: TransactionCallback<T>, options?: IGraphTransactionOptions): Promise<T>;
-    /**
-     * Begin a manual transaction
-     * As documented in transactions.md
-     */
-    beginTransaction(options?: IGraphTransactionOptions): Promise<IGraphTransaction>;
-    /**
-     * Commit a transaction
-     */
-    commitTransaction(transaction: IGraphTransaction): Promise<void>;
-    /**
-     * Rollback a transaction
-     */
-    rollbackTransaction(transaction: IGraphTransaction): Promise<void>;
-    /** Maximum retry attempts for auto-reconnection */
-    private readonly maxReconnectRetries;
-    /** Flag to track if reconnection is in progress */
-    private reconnecting;
-    /**
-     * Get the current adapter (synchronous, throws if not connected)
-     */
-    private getAdapter;
-    /**
-     * Ensure a connection exists for the given graph/env/product (connect on demand).
-     * Use before getAdapter() when options include graph+env+product (e.g. from proxy).
-     */
-    private ensureConnectionFor;
-    /**
-     * Get the current adapter with automatic reconnection on failure
-     */
-    private getAdapterWithReconnect;
-    /**
-     * Attempt to reconnect to the graph database
-     */
-    private attemptReconnect;
-    /**
-     * Execute an operation with automatic retry on connection errors
-     */
-    private executeWithRetry;
-    /**
-     * Check if an error is a connection-related error that can be retried
-     * Note: "No connection established" errors are NOT retriable - they indicate
-     * connect() was never called, not that a connection was lost
-     */
-    private isConnectionError;
-    /**
-     * Fetch graph configuration from product API
-     */
-    private fetchGraphFromProduct;
-    /**
-     * Get current connection context
-     */
-    getCurrentContext(): IGraphConnectionContext | null;
-    /**
-     * Check if a feature is supported by the current adapter
-     */
-    supportsFeature(feature: GraphFeature): boolean;
-}