Graph Operations

/**
 * Gets a reference to a named graph
 * @param graphName - Name of the graph
 * @returns Graph instance
 */
graph(graphName: string): Graph;

/**
 * Creates a new named graph
 * @param graphName - Name for the new graph
 * @param edgeDefinitions - Array of edge relationship definitions
 * @param options - Graph creation options
 * @returns Promise resolving to Graph instance
 */
createGraph(
  graphName: string,
  edgeDefinitions: EdgeDefinitionOptions[],
  options?: CreateGraphOptions
): Promise<Graph>;

/**
 * Lists all graphs in the database
 * @returns Promise resolving to array of Graph instances
 */
graphs(): Promise<Graph[]>;

import { Database } from "arangojs";

const db = new Database();

// Create collections first
await db.createCollection("users");
await db.createCollection("departments");
await db.createEdgeCollection("works_in");
await db.createEdgeCollection("manages");

// Create a graph with edge definitions
const orgGraph = await db.createGraph("organization", [
  {
    collection: "works_in",
    from: ["users"],
    to: ["departments"]
  },
  {
    collection: "manages", 
    from: ["users"],
    to: ["users", "departments"]
  }
], {
  isSmart: false,
  options: {
    replicationFactor: 2
  }
});

// Get reference to existing graph
const existingGraph = db.graph("organization");

// List all graphs
const allGraphs = await db.graphs();
console.log(`Found ${allGraphs.length} graphs`);

/**
 * Checks if the graph exists
 * @returns Promise resolving to boolean indicating existence
 */
exists(): Promise<boolean>;

/**
 * Retrieves graph information and configuration
 * @returns Promise resolving to graph description
 */
get(): Promise<GraphDescription>;

/**
 * Creates the graph with specified edge definitions
 * @param edgeDefinitions - Array of edge relationship definitions
 * @param options - Graph creation options
 * @returns Promise resolving to graph description
 */
create(
  edgeDefinitions: EdgeDefinitionOptions[],
  options?: CreateGraphOptions
): Promise<GraphDescription>;

/**
 * Drops (deletes) the graph
 * @param dropCollections - Whether to also drop associated collections
 * @returns Promise resolving when graph is dropped
 */
drop(dropCollections?: boolean): Promise<void>;

const graph = db.graph("social_network");

// Check if graph exists
if (!(await graph.exists())) {
  await graph.create([
    {
      collection: "follows",
      from: ["users"],
      to: ["users"]
    },
    {
      collection: "likes", 
      from: ["users"],
      to: ["posts"]
    }
  ]);
}

// Get graph information
const info = await graph.get();
console.log("Graph name:", info.name);
console.log("Edge definitions:", info.edgeDefinitions);

// Drop graph but keep collections
await graph.drop(false);

/**
 * Gets a reference to a vertex collection in the graph
 * @param collectionName - Name of the vertex collection
 * @returns GraphVertexCollection instance
 */
vertexCollection(collectionName: string): GraphVertexCollection<T, U>;

/**
 * Lists all vertex collections in the graph
 * @returns Promise resolving to array of vertex collection names
 */
vertexCollections(): Promise<string[]>;

/**
 * Adds a vertex collection to the graph
 * @param collectionName - Name of collection to add as vertex collection
 * @returns Promise resolving to graph description
 */
addVertexCollection(collectionName: string): Promise<GraphDescription>;

/**
 * Removes a vertex collection from the graph
 * @param collectionName - Name of vertex collection to remove
 * @param dropCollection - Whether to also drop the collection
 * @returns Promise resolving to graph description
 */
removeVertexCollection(collectionName: string, dropCollection?: boolean): Promise<GraphDescription>;

const graph = db.graph("social_network");

// Get vertex collection reference
const users = graph.vertexCollection("users");
const posts = graph.vertexCollection("posts");

// List all vertex collections
const vertexCollections = await graph.vertexCollections();
console.log("Vertex collections:", vertexCollections);

// Add new vertex collection to graph
await graph.addVertexCollection("groups");

// Remove vertex collection from graph
await graph.removeVertexCollection("inactive_users", true);

/**
 * Checks if a vertex exists in the collection
 * @param selector - Vertex document selector
 * @param options - Options for existence check
 * @returns Promise resolving to boolean indicating existence
 */
vertexExists(selector: DocumentSelector, options?: GraphDocumentExistsOptions): Promise<boolean>;

/**
 * Retrieves a vertex document
 * @param selector - Vertex document selector
 * @param options - Options for vertex retrieval
 * @returns Promise resolving to vertex document
 */
vertex(selector: DocumentSelector, options?: ReadGraphDocumentOptions): Promise<Document<T>>;

/**
 * Saves a new vertex to the collection
 * @param data - Vertex document data
 * @param options - Options for vertex insertion
 * @returns Promise resolving to operation result
 */
save(data: DocumentData<U>, options?: InsertGraphDocumentOptions): Promise<DocumentOperationResult<T>>;

/**
 * Replaces a vertex document
 * @param selector - Vertex document selector
 * @param data - New vertex data
 * @param options - Options for vertex replacement
 * @returns Promise resolving to operation result
 */
replace(
  selector: DocumentSelector,
  data: DocumentData<U>,
  options?: ReplaceGraphDocumentOptions
): Promise<DocumentOperationResult<T>>;

/**
 * Updates a vertex document
 * @param selector - Vertex document selector
 * @param data - Partial vertex data to update
 * @param options - Options for vertex update
 * @returns Promise resolving to operation result
 */
update(
  selector: DocumentSelector,
  data: Patch<U>,
  options?: UpdateGraphDocumentOptions
): Promise<DocumentOperationResult<T>>;

/**
 * Removes a vertex from the collection
 * @param selector - Vertex document selector
 * @param options - Options for vertex removal
 * @returns Promise resolving to operation result
 */
remove(
  selector: DocumentSelector,
  options?: RemoveGraphDocumentOptions
): Promise<DocumentOperationResult<T>>;

interface User {
  name: string;
  email: string;
  department: string;
}

const graph = db.graph("organization");
const users = graph.vertexCollection<User>("users");

// Create a new vertex
const newUser = await users.save({
  name: "Alice Johnson",
  email: "alice@company.com", 
  department: "Engineering"
}, { returnNew: true });

// Check if vertex exists
const exists = await users.vertexExists(newUser._key);

// Retrieve vertex
const user = await users.vertex(newUser._key);
console.log("User:", user.name);

// Update vertex
await users.update(newUser._key, {
  department: "Senior Engineering",
  lastPromoted: new Date()
});

// Remove vertex (this will also remove connected edges)
await users.remove(newUser._key, { returnOld: true });

/**
 * Gets a reference to an edge collection in the graph
 * @param collectionName - Name of the edge collection
 * @returns GraphEdgeCollection instance
 */
edgeCollection(collectionName: string): GraphEdgeCollection<T, U>;

/**
 * Lists all edge collections in the graph
 * @returns Promise resolving to array of edge collection names
 */
edgeCollections(): Promise<string[]>;

/**
 * Adds an edge definition to the graph
 * @param edgeDefinition - Edge relationship definition
 * @returns Promise resolving to graph description
 */
addEdgeDefinition(edgeDefinition: EdgeDefinitionOptions): Promise<GraphDescription>;

/**
 * Replaces an edge definition in the graph
 * @param collectionName - Name of edge collection to replace
 * @param edgeDefinition - New edge relationship definition
 * @returns Promise resolving to graph description
 */
replaceEdgeDefinition(
  collectionName: string,
  edgeDefinition: EdgeDefinitionOptions
): Promise<GraphDescription>;

/**
 * Removes an edge definition from the graph
 * @param collectionName - Name of edge collection to remove
 * @param dropCollection - Whether to also drop the collection
 * @returns Promise resolving to graph description
 */
removeEdgeDefinition(collectionName: string, dropCollection?: boolean): Promise<GraphDescription>;

/**
 * Checks if an edge exists in the collection
 * @param selector - Edge document selector
 * @param options - Options for existence check  
 * @returns Promise resolving to boolean indicating existence
 */
edgeExists(selector: DocumentSelector, options?: GraphDocumentExistsOptions): Promise<boolean>;

/**
 * Retrieves an edge document
 * @param selector - Edge document selector
 * @param options - Options for edge retrieval
 * @returns Promise resolving to edge document
 */
edge(selector: DocumentSelector, options?: ReadGraphDocumentOptions): Promise<Edge<T>>;

/**
 * Creates a new edge between two vertices
 * @param data - Edge document data with _from and _to
 * @param options - Options for edge insertion
 * @returns Promise resolving to operation result
 */
save(data: EdgeData<U>, options?: InsertGraphDocumentOptions): Promise<DocumentOperationResult<T>>;

/**
 * Replaces an edge document
 * @param selector - Edge document selector
 * @param data - New edge data
 * @param options - Options for edge replacement
 * @returns Promise resolving to operation result
 */
replace(
  selector: DocumentSelector,
  data: EdgeData<U>,
  options?: ReplaceGraphDocumentOptions
): Promise<DocumentOperationResult<T>>;

/**
 * Updates an edge document
 * @param selector - Edge document selector
 * @param data - Partial edge data to update
 * @param options - Options for edge update
 * @returns Promise resolving to operation result
 */
update(
  selector: DocumentSelector,
  data: Patch<U>,
  options?: UpdateGraphDocumentOptions
): Promise<DocumentOperationResult<T>>;

/**
 * Removes an edge from the collection
 * @param selector - Edge document selector
 * @param options - Options for edge removal
 * @returns Promise resolving to operation result
 */
remove(
  selector: DocumentSelector,
  options?: RemoveGraphDocumentOptions
): Promise<DocumentOperationResult<T>>;

interface WorksIn {
  startDate: Date;
  position: string;
  salary?: number;
}

const graph = db.graph("organization");
const worksIn = graph.edgeCollection<WorksIn>("works_in");

// Create edge between user and department
const employment = await worksIn.save({
  _from: "users/alice",
  _to: "departments/engineering", 
  startDate: new Date("2023-01-15"),
  position: "Senior Developer",
  salary: 85000
}, { returnNew: true });

// Retrieve edge
const edge = await worksIn.edge(employment._key);
console.log("Employment:", edge.position);

// Update edge
await worksIn.update(employment._key, {
  position: "Lead Developer",
  salary: 95000,
  promotionDate: new Date()
});

// Remove edge
await worksIn.remove(employment._key);

/**
 * Performs a graph traversal starting from a vertex
 * @param startVertex - Starting vertex selector
 * @param options - Traversal configuration options
 * @returns Promise resolving to traversal results
 */
traversal(startVertex: DocumentSelector, options?: TraversalOptions): Promise<TraversalResult>;

/**
 * Finds shortest paths between vertices
 * @param startVertex - Starting vertex selector
 * @param endVertex - Target vertex selector  
 * @param options - Shortest path options
 * @returns Promise resolving to path results
 */
shortestPath(
  startVertex: DocumentSelector,
  endVertex: DocumentSelector,
  options?: ShortestPathOptions
): Promise<ShortestPathResult>;

const graph = db.graph("social_network");

// Traverse from a user to find connections
const traversal = await graph.traversal("users/alice", {
  direction: "outbound",
  minDepth: 1,
  maxDepth: 3,
  edgeCollections: ["follows", "likes"]
});

console.log("Found connections:", traversal.vertices.length);

// Find shortest path between two users
const path = await graph.shortestPath("users/alice", "users/bob", {
  direction: "any",
  edgeCollections: ["follows"]
});

if (path.paths.length > 0) {
  console.log("Shortest path distance:", path.paths[0].vertices.length - 1);
}

class Graph {
  readonly name: string;
  exists(): Promise<boolean>;
  get(): Promise<GraphDescription>;
  vertexCollection(name: string): GraphVertexCollection;
  edgeCollection(name: string): GraphEdgeCollection;
}

interface GraphVertexCollection<T = any, U = T> {
  readonly name: string;
  vertex(selector: DocumentSelector, options?: ReadGraphDocumentOptions): Promise<Document<T>>;
  save(data: DocumentData<U>, options?: InsertGraphDocumentOptions): Promise<DocumentOperationResult<T>>;
}

interface GraphEdgeCollection<T = any, U = T> {
  readonly name: string;
  edge(selector: DocumentSelector, options?: ReadGraphDocumentOptions): Promise<Edge<T>>;
  save(data: EdgeData<U>, options?: InsertGraphDocumentOptions): Promise<DocumentOperationResult<T>>;
}

interface EdgeDefinitionOptions {
  collection: string | ArangoCollection;
  from: string | ArangoCollection | (string | ArangoCollection)[];
  to: string | ArangoCollection | (string | ArangoCollection)[];
}

interface GraphDescription {
  name: string;
  edgeDefinitions: EdgeDefinition[];
  orphanCollections: string[];
  isSmart: boolean;
  isDisjoint: boolean;
  options: GraphOptions;
}

interface EdgeDefinition {
  collection: string;
  from: string[];
  to: string[];
}

interface CreateGraphOptions {
  waitForSync?: boolean;
  isSmart?: boolean;
  isDisjoint?: boolean;
  options?: GraphOptions;
  satellites?: string[];
}

interface GraphOptions {
  numberOfShards?: number;
  replicationFactor?: number | "satellite";
  writeConcern?: number;
  shardingStrategy?: string;
}

type EdgeData<T = any> = T & {
  _from: string;
  _to: string;
} & Partial<DocumentMetadata>;

interface Edge<T = any> extends Document<T> {
  _from: string;
  _to: string;
}

interface TraversalOptions {
  direction?: "inbound" | "outbound" | "any";
  minDepth?: number;
  maxDepth?: number;
  startVertex?: string;
  edgeCollections?: string[];
  vertexCollections?: string[];
  filter?: any;
  visitor?: any;
  sort?: any;
  init?: any;
  expander?: any;
  itemOrder?: "forward" | "backward";
  strategy?: "depthfirst" | "breadthfirst";
  order?: "preorder" | "postorder";
  graphName?: string;
  uniqueness?: any;
}

interface TraversalResult {
  vertices: Document[];
  edges: Edge[];
  paths: Array<{
    vertices: Document[];
    edges: Edge[];
  }>;
}