@anvailabs/proximadb-client 0.4.1 → 0.5.0

package/dist/esm/graph.js

@@ -1,685 +0,0 @@
-/**
- * ProximaDB TypeScript SDK - Graph Operations
- *
- * Provides a fluent API for graph database operations including
- * node and edge management, traversal queries, and graph analytics.
- *
- * Copyright 2025 ProximaDB Contributors
- * Licensed under the Apache License, Version 2.0
- */
-import { TraversalDirection, } from "./types";
-// ============================================================================
-// NODE BUILDER
-// ============================================================================
-/**
- * Builder for creating graph nodes
- */
-export class NodeBuilder {
-    handle;
-    nodeId = null;
-    nodeLabel = null;
-    nodeProperties = {};
-    nodeVector = null;
-    constructor(handle) {
-        this.handle = handle;
-    }
-    /**
-     * Set the node ID
-     */
-    id(nodeId) {
-        this.nodeId = nodeId;
-        return this;
-    }
-    /**
-     * Set the node label (type)
-     */
-    label(nodeLabel) {
-        this.nodeLabel = nodeLabel;
-        return this;
-    }
-    /**
-     * Add a property to the node
-     */
-    property(key, value) {
-        this.nodeProperties[key] = value;
-        return this;
-    }
-    /**
-     * Add multiple properties at once
-     */
-    properties(props) {
-        Object.assign(this.nodeProperties, props);
-        return this;
-    }
-    /**
-     * Set the embedding vector for semantic operations
-     */
-    vector(vec) {
-        this.nodeVector = vec;
-        return this;
-    }
-    /**
-     * Execute the node addition.
-     *
-     * Wire endpoint: POST /api/v2/graphs/{graph_id}/nodes
-     * OpenAPI operationId: createNode
-     *
-     * Body shape (server-true, per `CreateNodeRequest`):
-     *   `{ node: NodeInput }` — NodeInput = `{ id, labels?, properties?, embedding? }`.
-     */
-    async execute() {
-        if (this.nodeId === null) {
-            throw new Error("Node ID is required");
-        }
-        const node = { id: this.nodeId };
-        if (this.nodeLabel !== null) {
-            node.labels = [this.nodeLabel];
-        }
-        if (Object.keys(this.nodeProperties).length > 0) {
-            node.properties = this.nodeProperties;
-        }
-        if (this.nodeVector !== null) {
-            const embedding = { vector: this.nodeVector };
-            node.embedding = embedding;
-        }
-        const request = { node };
-        await this.handle.getClient().createNodeRequest(this.handle.getName(), request);
-    }
-    /**
-     * Build the node without executing
-     */
-    build() {
-        if (this.nodeId === null) {
-            throw new Error("Node ID is required");
-        }
-        return {
-            id: this.nodeId,
-            label: this.nodeLabel ?? undefined,
-            properties: this.nodeProperties,
-            vector: this.nodeVector ?? undefined,
-        };
-    }
-}
-// ============================================================================
-// EDGE BUILDER
-// ============================================================================
-/**
- * Builder for creating graph edges
- */
-export class EdgeBuilder {
-    handle;
-    edgeId = null;
-    sourceNode = null;
-    targetNode = null;
-    relationshipType = null;
-    edgeProperties = {};
-    edgeWeight = null;
-    constructor(handle) {
-        this.handle = handle;
-    }
-    /**
-     * Set the edge ID (required by server `EdgeInput.id`).
-     */
-    id(edgeId) {
-        this.edgeId = edgeId;
-        return this;
-    }
-    /**
-     * Set the source node ID
-     */
-    from(nodeId) {
-        this.sourceNode = nodeId;
-        return this;
-    }
-    /**
-     * Set the target node ID
-     */
-    to(nodeId) {
-        this.targetNode = nodeId;
-        return this;
-    }
-    /**
-     * Set the relationship / edge type (server field: `edge_type`).
-     */
-    relationship(relType) {
-        this.relationshipType = relType;
-        return this;
-    }
-    /**
-     * Alias for `relationship(...)` matching the server-side field name.
-     */
-    edgeType(edgeType) {
-        this.relationshipType = edgeType;
-        return this;
-    }
-    /**
-     * Add a property to the edge
-     */
-    property(key, value) {
-        this.edgeProperties[key] = value;
-        return this;
-    }
-    /**
-     * Add multiple properties at once
-     */
-    properties(props) {
-        Object.assign(this.edgeProperties, props);
-        return this;
-    }
-    /**
-     * Set the edge weight
-     */
-    weight(w) {
-        this.edgeWeight = w;
-        return this;
-    }
-    /**
-     * Execute the edge addition.
-     *
-     * Wire endpoint: POST /api/v2/graphs/{graph_id}/edges
-     * OpenAPI operationId: createEdge
-     *
-     * Body shape (server-true, per `CreateEdgeRequest`):
-     *   `{ edge: EdgeInput }` — EdgeInput = `{ id, from_node_id, to_node_id,
-     *   edge_type, properties?, weight? }`.
-     */
-    async execute() {
-        if (this.edgeId === null) {
-            throw new Error("Edge ID is required (call .id(...))");
-        }
-        if (this.sourceNode === null) {
-            throw new Error("Source node ID is required");
-        }
-        if (this.targetNode === null) {
-            throw new Error("Target node ID is required");
-        }
-        if (this.relationshipType === null) {
-            throw new Error("Edge type / relationship is required");
-        }
-        const edge = {
-            id: this.edgeId,
-            from_node_id: this.sourceNode,
-            to_node_id: this.targetNode,
-            edge_type: this.relationshipType,
-        };
-        if (Object.keys(this.edgeProperties).length > 0) {
-            edge.properties = this.edgeProperties;
-        }
-        if (this.edgeWeight !== null) {
-            edge.weight = this.edgeWeight;
-        }
-        const request = { edge };
-        await this.handle.getClient().createEdgeRequest(this.handle.getName(), request);
-    }
-    /**
-     * Build the edge without executing
-     */
-    build() {
-        if (this.sourceNode === null) {
-            throw new Error("Source node ID is required");
-        }
-        if (this.targetNode === null) {
-            throw new Error("Target node ID is required");
-        }
-        if (this.relationshipType === null) {
-            throw new Error("Relationship type is required");
-        }
-        return {
-            source: this.sourceNode,
-            target: this.targetNode,
-            relationship: this.relationshipType,
-            properties: this.edgeProperties,
-            weight: this.edgeWeight ?? undefined,
-        };
-    }
-}
-// ============================================================================
-// TRAVERSAL BUILDER
-// ============================================================================
-/**
- * Builder for graph traversal queries
- */
-export class TraversalBuilder {
-    handle;
-    startNodeId = null;
-    relationshipTypes = [];
-    nodeLabelsList = [];
-    traversalDirection = TraversalDirection.Outgoing;
-    maxDepthValue = 3;
-    limitValue = null;
-    algorithmValue = null;
-    filterExpr = null;
-    constructor(handle) {
-        this.handle = handle;
-    }
-    /**
-     * Set the starting node
-     */
-    start(nodeId) {
-        this.startNodeId = nodeId;
-        return this;
-    }
-    /**
-     * Add a relationship type to follow
-     */
-    relationship(relType) {
-        this.relationshipTypes.push(relType);
-        return this;
-    }
-    /**
-     * Add multiple relationship types
-     */
-    relationships(relTypes) {
-        this.relationshipTypes.push(...relTypes);
-        return this;
-    }
-    /**
-     * Set the traversal direction
-     */
-    direction(dir) {
-        this.traversalDirection = dir;
-        return this;
-    }
-    /**
-     * Traverse outgoing edges only
-     */
-    outgoing() {
-        this.traversalDirection = TraversalDirection.Outgoing;
-        return this;
-    }
-    /**
-     * Traverse incoming edges only
-     */
-    incoming() {
-        this.traversalDirection = TraversalDirection.Incoming;
-        return this;
-    }
-    /**
-     * Traverse both directions
-     */
-    both() {
-        this.traversalDirection = TraversalDirection.Both;
-        return this;
-    }
-    /**
-     * Set the maximum traversal depth
-     */
-    maxDepth(depth) {
-        this.maxDepthValue = depth;
-        return this;
-    }
-    /**
-     * Set the maximum number of results
-     */
-    limit(lim) {
-        this.limitValue = lim;
-        return this;
-    }
-    /**
-     * Add a label to filter visited nodes by.
-     */
-    nodeLabel(label) {
-        this.nodeLabelsList.push(label);
-        return this;
-    }
-    /**
-     * Replace the set of node-label filters.
-     */
-    nodeLabels(labels) {
-        this.nodeLabelsList = [...labels];
-        return this;
-    }
-    /**
-     * Select traversal algorithm (server accepts `bfs`, `dfs`, or `shortest_path`).
-     */
-    algorithm(name) {
-        this.algorithmValue = name;
-        return this;
-    }
-    /**
-     * Add a filter expression for nodes (client-side helper, not sent on wire).
-     */
-    filter(filterStr) {
-        this.filterExpr = filterStr;
-        return this;
-    }
-    /**
-     * Execute the traversal.
-     *
-     * Wire endpoint: POST /api/v2/graphs/{graph_id}/traverse
-     * OpenAPI operationId: traverseGraph
-     *
-     * Body shape (server-true, per `TraverseRequest`):
-     *   `{ start_node_id, max_depth, edge_types?, node_labels?, algorithm?, limit? }`.
-     *   Note: spec is flat (no `graph` wrapper — `graph_id` is the URL path
-     *   parameter) and has no `direction` field; legacy `direction` /
-     *   `start_node` / `relationships` keys are intentionally not sent.
-     */
-    async execute() {
-        if (this.startNodeId === null) {
-            throw new Error("Start node is required for traversal");
-        }
-        const request = {
-            start_node_id: this.startNodeId,
-            max_depth: this.maxDepthValue,
-        };
-        if (this.relationshipTypes.length > 0) {
-            request.edge_types = this.relationshipTypes;
-        }
-        if (this.nodeLabelsList.length > 0) {
-            request.node_labels = this.nodeLabelsList;
-        }
-        if (this.algorithmValue !== null) {
-            request.algorithm = this.algorithmValue;
-        }
-        if (this.limitValue !== null) {
-            request.limit = this.limitValue;
-        }
-        // Note: direction (this.traversalDirection) and filter (this.filterExpr)
-        // are intentionally NOT sent — the server `TraverseRequest` does not
-        // accept them. The setters remain for SDK ergonomic continuity.
-        void this.traversalDirection;
-        void this.filterExpr;
-        return this.handle.getClient().traverseGraphRequest(this.handle.getName(), request);
-    }
-}
-// ============================================================================
-// GRAPH HANDLE
-// ============================================================================
-/**
- * Handle to a graph for fluent operations
- */
-export class GraphHandle {
-    client;
-    graphName;
-    constructor(client, name) {
-        this.client = client;
-        this.graphName = name;
-    }
-    /**
-     * Get the graph name
-     */
-    getName() {
-        return this.graphName;
-    }
-    /**
-     * Get the HTTP client (internal use)
-     */
-    getClient() {
-        return this.client;
-    }
-    /**
-     * Start building a node addition
-     */
-    addNode() {
-        return new NodeBuilder(this);
-    }
-    /**
-     * Start building an edge addition
-     */
-    addEdge() {
-        return new EdgeBuilder(this);
-    }
-    /**
-     * Start building a traversal query
-     */
-    traverse() {
-        return new TraversalBuilder(this);
-    }
-    /**
-     * Add a batch of nodes.
-     *
-     * Wire endpoint: POST /api/v2/graphs/{graph_id}/nodes/batch
-     * OpenAPI operationId: batchCreateNodes
-     *
-     * Body shape (server-true, per `BatchCreateNodesRequest`):
-     *   `{ nodes: [NodeInput, ...] }`. `graph_id` lives in the URL path.
-     *
-     * Accepts either spec-true `NodeInput[]` or legacy `GraphNode[]`; the
-     * latter is normalized (singular `label` → `labels: [label]`,
-     * `vector` → `embedding.vector`).
-     */
-    async addNodes(nodes) {
-        const normalized = nodes.map(n => normalizeNodeInput(n));
-        const request = { nodes: normalized };
-        const response = (await this.client.batchCreateNodesRequest(this.graphName, request));
-        return (response?.data?.created_count ??
-            response?.data?.count ??
-            response?.created_count ??
-            response?.count ??
-            response?.added_count ??
-            0);
-    }
-    /**
-     * Add a batch of edges.
-     *
-     * Wire endpoint: POST /api/v2/graphs/{graph_id}/edges/batch
-     * OpenAPI operationId: batchCreateEdges
-     *
-     * Body shape (server-true, per `BatchCreateEdgesRequest`):
-     *   `{ edges: [EdgeInput, ...] }`. `graph_id` lives in the URL path.
-     *
-     * Accepts either spec-true `EdgeInput[]` or legacy `GraphEdge[]`; the
-     * latter is normalized (`source` → `from_node_id`, `target` →
-     * `to_node_id`, `relationship` → `edge_type`). Legacy `GraphEdge` has no
-     * `id` field; callers MUST upgrade to `EdgeInput` for batch use (the
-     * normalizer throws if `id` is missing).
-     */
-    async addEdges(edges) {
-        const normalized = edges.map(e => normalizeEdgeInput(e));
-        const request = { edges: normalized };
-        const response = (await this.client.batchCreateEdgesRequest(this.graphName, request));
-        return (response?.data?.created_count ??
-            response?.data?.count ??
-            response?.created_count ??
-            response?.count ??
-            response?.added_count ??
-            0);
-    }
-    /**
-     * Get a node by ID
-     */
-    async getNode(nodeId) {
-        try {
-            return await this.client.getNodeRequest(this.graphName, nodeId);
-        }
-        catch (e) {
-            // The facade maps a 404 to a ProximaDBError (statusCode 404, message =
-            // server body). Treat "not found" as a null result, preserving the
-            // pre-rebase behavior; match on status or the body text.
-            const status = e.statusCode;
-            if (status === 404) {
-                return null;
-            }
-            if (e instanceof Error && e.message.includes("404")) {
-                return null;
-            }
-            throw e;
-        }
-    }
-    /**
-     * Delete a node by ID
-     */
-    async deleteNode(nodeId) {
-        await this.client.deleteNodeRequest(this.graphName, nodeId);
-    }
-    // deleteEdge is intentionally LEFT facade-built (generic URL path): the
-    // generated REST client has no matching typed op for this 3-segment route
-    // shape. The OpenAPI spec / generated client model edge deletion as
-    // `DELETE /api/v2/graphs/{graph_id}/edges/{edge_id}` (single `edge_id`),
-    // whereas this SDK's public signature is `(source, target, relationship)` →
-    // `/edges/{source}/{target}/{relationship}`. Until the SDK signature is
-    // reconciled to `{edge_id}` (separate change), this cannot route through the
-    // generated client. Tracked separately.
-    /**
-     * Delete an edge
-     */
-    async deleteEdge(source, target, relationship) {
-        const url = this.client.url() + "/api/v2/graphs/" + this.graphName + "/edges/" + source + "/" + target + "/" + relationship;
-        await this.client.delete(url);
-    }
-    /**
-     * Get graph statistics.
-     *
-     * Routed through the generated typed transport (TD-126 Phase 4).
-     * Wire endpoint: GET /api/v2/graphs/{graph_id} (getGraph)
-     */
-    async info() {
-        return this.client.getGraphRequest(this.graphName);
-    }
-}
-// ============================================================================
-// GRAPH BUILDER
-// ============================================================================
-/**
- * Builder for creating graphs
- */
-export class GraphBuilder {
-    client;
-    graphId;
-    graphDisplayName = null;
-    graphDescription = null;
-    constructor(client, graphId) {
-        this.client = client;
-        this.graphId = graphId;
-    }
-    /**
-     * Set an optional human-readable name (defaults server-side to graph_id).
-     */
-    name(displayName) {
-        this.graphDisplayName = displayName;
-        return this;
-    }
-    /**
-     * Set the graph description
-     */
-    description(desc) {
-        this.graphDescription = desc;
-        return this;
-    }
-    /**
-     * Execute the graph creation.
-     *
-     * Wire endpoint: POST /api/v2/graphs
-     * OpenAPI operationId: createGraph
-     *
-     * Body shape (server-true, per `CreateGraphRequest`):
-     *   `{ graph_id, name?, description? }`.
-     */
-    async execute() {
-        const request = { graph_id: this.graphId };
-        if (this.graphDisplayName !== null) {
-            request.name = this.graphDisplayName;
-        }
-        if (this.graphDescription !== null) {
-            request.description = this.graphDescription;
-        }
-        await this.client.createGraphRequest(request);
-    }
-}
-// ============================================================================
-// INTERNAL: legacy -> spec normalizers
-// ============================================================================
-function normalizeNodeInput(input) {
-    // Distinguish legacy `GraphNode` (has singular `label` and/or `vector`) from
-    // spec-true `NodeInput` (has `labels[]` / `embedding`). Field absence is
-    // fine — `NodeInput` only requires `id`.
-    const out = { id: input.id };
-    // Inline structural check avoids a hard cross-cast.
-    const legacy = input;
-    const spec = input;
-    if (spec.labels !== undefined) {
-        out.labels = spec.labels;
-    }
-    else if (legacy.label !== undefined) {
-        out.labels = [legacy.label];
-    }
-    if (spec.properties !== undefined) {
-        out.properties = spec.properties;
-    }
-    else if (legacy.properties !== undefined) {
-        out.properties = legacy.properties;
-    }
-    if (spec.embedding !== undefined) {
-        out.embedding = spec.embedding;
-    }
-    else if (legacy.vector !== undefined) {
-        out.embedding = { vector: legacy.vector };
-    }
-    return out;
-}
-function normalizeEdgeInput(input) {
-    const spec = input;
-    const legacy = input;
-    // Spec edge has `id` (required), legacy has none. If absent on a legacy
-    // value, surface a hard error — server `EdgeInput.id` is required.
-    if (spec.id === undefined) {
-        throw new Error("addEdges: edge.id is required by EdgeInput (legacy GraphEdge has no id; pass an EdgeInput)");
-    }
-    const out = {
-        id: spec.id,
-        from_node_id: spec.from_node_id ?? legacy.source,
-        to_node_id: spec.to_node_id ?? legacy.target,
-        edge_type: spec.edge_type ?? legacy.relationship,
-    };
-    if (spec.properties !== undefined) {
-        out.properties = spec.properties;
-    }
-    else if (legacy.properties !== undefined) {
-        out.properties = legacy.properties;
-    }
-    if (spec.weight !== undefined) {
-        out.weight = spec.weight;
-    }
-    else if (legacy.weight !== undefined) {
-        out.weight = legacy.weight;
-    }
-    return out;
-}
-// ============================================================================
-// CONVENIENCE FUNCTIONS
-// ============================================================================
-/**
- * Create a new GraphNode
- */
-export function createNode(id) {
-    return {
-        id,
-        properties: {},
-    };
-}
-/**
- * Create a new GraphNode with builder pattern
- */
-export function node(id) {
-    const n = { id, properties: {} };
-    return {
-        label: (l) => { n.label = l; return node(id); },
-        property: (k, v) => { n.properties[k] = v; return node(id); },
-        vector: (v) => { n.vector = v; return node(id); },
-        build: () => n,
-    };
-}
-/**
- * Create a new GraphEdge
- */
-export function createEdge(source, target, relationship) {
-    return {
-        source,
-        target,
-        relationship,
-        properties: {},
-    };
-}
-/**
- * Create a new GraphEdge with builder pattern
- */
-export function edge(source, target, relationship) {
-    const e = { source, target, relationship, properties: {} };
-    return {
-        property: (k, v) => { e.properties[k] = v; return edge(source, target, relationship); },
-        weight: (w) => { e.weight = w; return edge(source, target, relationship); },
-        build: () => e,
-    };
-}
-//# sourceMappingURL=graph.js.map