@quokkaquery/graph 0.1.0 → 0.1.1

package/API.md

@@ -1,100 +1,100 @@
-# @quokkaquery/graph — API Reference
-
-Distilled API surface for agent prompts and quick reference. 7 exports from `src/index.ts`.
-
-## Types
-
-```typescript
-export type NodeId = string | number
-
-export interface GraphNode<T = unknown> {
-  id: NodeId
-  data: T
-}
-
-export interface Edge<E = unknown> {
-  from: NodeId
-  to: NodeId
-  weight: number
-  data: E
-}
-
-export interface GraphOptions {
-  directed?: boolean    // default: true
-}
-
-export type Visitor<T> = (node: GraphNode<T>, depth: number) => void | false
-export type NodePredicate<T> = (node: GraphNode<T>) => boolean
-```
-
-## Class
-
-```typescript
-export class Graph<T = unknown, E = unknown> {
-  readonly directed: boolean
-
-  constructor(opts?: GraphOptions)
-
-  // ── Nodes ──────────────────────────────────────────
-  addNode(id: NodeId, data: T): this
-  getNode(id: NodeId): GraphNode<T> | undefined
-  hasNode(id: NodeId): boolean
-  removeNode(id: NodeId): boolean
-  get nodeCount(): number
-  nodeIds(): NodeId[]
-  nodeEntries(): GraphNode<T>[]
-
-  // ── Edges ──────────────────────────────────────────
-  addEdge(from: NodeId, to: NodeId, weight?: number, data?: E): this
-  getEdge(from: NodeId, to: NodeId): Edge<E> | undefined
-  hasEdge(from: NodeId, to: NodeId): boolean
-  removeEdge(from: NodeId, to: NodeId): boolean
-  get edgeCount(): number
-  edges(): Edge<E>[]
-  neighbors(id: NodeId): NodeId[]
-  outEdges(id: NodeId): Edge<E>[]
-  inEdges(id: NodeId): Edge<E>[]
-  outDegree(id: NodeId): number
-  inDegree(id: NodeId): number
-  degree(id: NodeId): number
-
-  // ── Node helpers ───────────────────────────────────
-  predecessors(id: NodeId): NodeId[]
-  successors(id: NodeId): NodeId[]
-  connectedNodes(id: NodeId): NodeId[]
-  isSource(id: NodeId): boolean       // directed only
-  isSink(id: NodeId): boolean         // directed only
-  isIsolated(id: NodeId): boolean
-  sources(): NodeId[]                 // directed only
-  sinks(): NodeId[]                   // directed only
-  isolatedNodes(): NodeId[]
-
-  // ── Reachability ───────────────────────────────────
-  reachableFrom(id: NodeId): Set<NodeId>
-  reachableTo(id: NodeId): Set<NodeId>
-
-  // ── Traversals ─────────────────────────────────────
-  bfs(start: NodeId, visitor: Visitor<T>): void
-  dfs(start: NodeId, visitor: Visitor<T>): void
-  findBfs(start: NodeId, predicate: NodePredicate<T>): GraphNode<T> | undefined
-  findDfs(start: NodeId, predicate: NodePredicate<T>): GraphNode<T> | undefined
-
-  // ── Algorithms ─────────────────────────────────────
-  topologicalSort(): NodeId[]         // directed only, throws on cycle
-  hasCycle(): boolean
-  dijkstra(start: NodeId, end: NodeId): { distance: number; path: NodeId[] } | undefined
-  connectedComponents(): NodeId[][]   // weakly-connected for directed
-
-  // ── Transforms ─────────────────────────────────────
-  mapNodes<U>(fn: (node: GraphNode<T>) => U): Graph<U, E>
-  subgraph(ids: Set<NodeId>): Graph<T, E>
-}
-```
-
-## Notes
-
-- Adjacency-list representation. Directed by default.
-- `addEdge` auto-creates missing nodes. For undirected, both directions are stored internally.
-- `edges()` deduplicates for undirected graphs.
-- `reachableFrom` includes the start node only if a cycle leads back to it.
-- Visitor callbacks can return `false` to stop traversal early.
+# @quokkaquery/graph — API Reference
+
+Distilled API surface for agent prompts and quick reference. 7 exports from `src/index.ts`.
+
+## Types
+
+```typescript
+export type NodeId = string | number
+
+export interface GraphNode<T = unknown> {
+  id: NodeId
+  data: T
+}
+
+export interface Edge<E = unknown> {
+  from: NodeId
+  to: NodeId
+  weight: number
+  data: E
+}
+
+export interface GraphOptions {
+  directed?: boolean    // default: true
+}
+
+export type Visitor<T> = (node: GraphNode<T>, depth: number) => void | false
+export type NodePredicate<T> = (node: GraphNode<T>) => boolean
+```
+
+## Class
+
+```typescript
+export class Graph<T = unknown, E = unknown> {
+  readonly directed: boolean
+
+  constructor(opts?: GraphOptions)
+
+  // ── Nodes ──────────────────────────────────────────
+  addNode(id: NodeId, data: T): this
+  getNode(id: NodeId): GraphNode<T> | undefined
+  hasNode(id: NodeId): boolean
+  removeNode(id: NodeId): boolean
+  get nodeCount(): number
+  nodeIds(): NodeId[]
+  nodeEntries(): GraphNode<T>[]
+
+  // ── Edges ──────────────────────────────────────────
+  addEdge(from: NodeId, to: NodeId, weight?: number, data?: E): this
+  getEdge(from: NodeId, to: NodeId): Edge<E> | undefined
+  hasEdge(from: NodeId, to: NodeId): boolean
+  removeEdge(from: NodeId, to: NodeId): boolean
+  get edgeCount(): number
+  edges(): Edge<E>[]
+  neighbors(id: NodeId): NodeId[]
+  outEdges(id: NodeId): Edge<E>[]
+  inEdges(id: NodeId): Edge<E>[]
+  outDegree(id: NodeId): number
+  inDegree(id: NodeId): number
+  degree(id: NodeId): number
+
+  // ── Node helpers ───────────────────────────────────
+  predecessors(id: NodeId): NodeId[]
+  successors(id: NodeId): NodeId[]
+  connectedNodes(id: NodeId): NodeId[]
+  isSource(id: NodeId): boolean       // directed only
+  isSink(id: NodeId): boolean         // directed only
+  isIsolated(id: NodeId): boolean
+  sources(): NodeId[]                 // directed only
+  sinks(): NodeId[]                   // directed only
+  isolatedNodes(): NodeId[]
+
+  // ── Reachability ───────────────────────────────────
+  reachableFrom(id: NodeId): Set<NodeId>
+  reachableTo(id: NodeId): Set<NodeId>
+
+  // ── Traversals ─────────────────────────────────────
+  bfs(start: NodeId, visitor: Visitor<T>): void
+  dfs(start: NodeId, visitor: Visitor<T>): void
+  findBfs(start: NodeId, predicate: NodePredicate<T>): GraphNode<T> | undefined
+  findDfs(start: NodeId, predicate: NodePredicate<T>): GraphNode<T> | undefined
+
+  // ── Algorithms ─────────────────────────────────────
+  topologicalSort(): NodeId[]         // directed only, throws on cycle
+  hasCycle(): boolean
+  dijkstra(start: NodeId, end: NodeId): { distance: number; path: NodeId[] } | undefined
+  connectedComponents(): NodeId[][]   // weakly-connected for directed
+
+  // ── Transforms ─────────────────────────────────────
+  mapNodes<U>(fn: (node: GraphNode<T>) => U): Graph<U, E>
+  subgraph(ids: Set<NodeId>): Graph<T, E>
+}
+```
+
+## Notes
+
+- Adjacency-list representation. Directed by default.
+- `addEdge` auto-creates missing nodes. For undirected, both directions are stored internally.
+- `edges()` deduplicates for undirected graphs.
+- `reachableFrom` includes the start node only if a cycle leads back to it.
+- Visitor callbacks can return `false` to stop traversal early.

package/dist/graph.d.ts

@@ -1,7 +1,14 @@
+/**
+ * In-memory `Graph` class: node and edge storage, degree and reachability
+ * queries, BFS/DFS traversal, and topological sort, cycle detection,
+ * Dijkstra, connected components, mapping and subgraph extraction.
+ */
 import type { NodeId, GraphNode, Edge, GraphOptions, Visitor, NodePredicate } from "./types.js";
 /**
  * Generic graph with adjacency-list representation.
  * Supports directed and undirected graphs, weighted edges, and common traversals.
+ * Undirected edges are stored as a pair of mirrored directed edges, so
+ * per-node edge lists contain both directions.
  *
  * @typeParam T - Node data type
  * @typeParam E - Edge data type
@@ -11,19 +18,43 @@ export declare class Graph<T = unknown, E = unknown> {
     private nodes;
     private adjOut;
     private adjIn;
+    /** Graphs are directed unless `opts.directed` is explicitly `false`. */
     constructor(opts?: GraphOptions);
+    /** Adds or replaces a node's data; existing edges on `id` are kept. Chainable. */
     addNode(id: NodeId, data: T): this;
     getNode(id: NodeId): GraphNode<T> | undefined;
     hasNode(id: NodeId): boolean;
+    /**
+     * Deletes a node and its edges; returns false if `id` was not a registered node.
+     * Only the first edge between `id` and each other node is removed from that
+     * node's lists, so parallel edges leave dangling entries behind.
+     */
     removeNode(id: NodeId): boolean;
     get nodeCount(): number;
     nodeIds(): NodeId[];
     nodeEntries(): GraphNode<T>[];
+    /**
+     * Appends an edge (weight defaults to 1); parallel edges are allowed. Endpoints
+     * not added via `addNode` get adjacency lists but are not registered nodes:
+     * they are absent from `nodeIds`/`getNode` and skipped by traversal visitors
+     * and `dijkstra`. Chainable.
+     */
     addEdge(from: NodeId, to: NodeId, weight?: number, data?: E): this;
+    /** First stored edge from `from` to `to`; with parallel edges the others are not returned. */
     getEdge(from: NodeId, to: NodeId): Edge<E> | undefined;
     hasEdge(from: NodeId, to: NodeId): boolean;
+    /**
+     * Removes one `from`→`to` edge (and its mirror when undirected); returns false
+     * if none exists. Parallel edges must be removed one call at a time.
+     */
     removeEdge(from: NodeId, to: NodeId): boolean;
+    /** Number of edges; undirected edges count once despite being stored twice. */
     get edgeCount(): number;
+    /**
+     * All edges. For undirected graphs, one edge per node pair is returned in
+     * whichever direction was seen first, which also collapses parallel edges —
+     * so `mapNodes` and `subgraph` drop undirected parallel edges.
+     */
     edges(): Edge<E>[];
     /** Outgoing neighbors of a node. */
     neighbors(id: NodeId): NodeId[];
@@ -79,7 +110,7 @@ export declare class Graph<T = unknown, E = unknown> {
     findDfs(start: NodeId, predicate: NodePredicate<T>): GraphNode<T> | undefined;
     /**
      * Topological sort (Kahn's algorithm). Returns node ids in topological order.
-     * Throws if the graph has a cycle. Only meaningful for directed graphs.
+     * Throws if the graph is undirected or has a cycle.
      */
     topologicalSort(): NodeId[];
     /** Detect whether the graph contains a cycle. */
@@ -87,7 +118,9 @@ export declare class Graph<T = unknown, E = unknown> {
     /**
      * Dijkstra's shortest path from `start` to `end`.
      * Returns `{ distance, path }` or `undefined` if unreachable.
-     * Edges must have non-negative weights.
+     * Edges must have non-negative weights. `end` must be a registered node;
+     * otherwise the result is a one-element path with an undefined distance
+     * rather than `undefined`.
      */
     dijkstra(start: NodeId, end: NodeId): {
         distance: number;

package/dist/graph.js

@@ -1,6 +1,8 @@
 /**
  * Generic graph with adjacency-list representation.
  * Supports directed and undirected graphs, weighted edges, and common traversals.
+ * Undirected edges are stored as a pair of mirrored directed edges, so
+ * per-node edge lists contain both directions.
  *
  * @typeParam T - Node data type
  * @typeParam E - Edge data type
@@ -10,10 +12,12 @@ export class Graph {
     nodes = new Map();
     adjOut = new Map(); // outgoing edges
     adjIn = new Map(); // incoming edges (directed only, for convenience)
+    /** Graphs are directed unless `opts.directed` is explicitly `false`. */
     constructor(opts = {}) {
         this.directed = opts.directed ?? true;
     }
     // ── Node operations ──────────────────────────────────────────────
+    /** Adds or replaces a node's data; existing edges on `id` are kept. Chainable. */
     addNode(id, data) {
         this.nodes.set(id, { id, data });
         if (!this.adjOut.has(id))
@@ -28,6 +32,11 @@ export class Graph {
     hasNode(id) {
         return this.nodes.has(id);
     }
+    /**
+     * Deletes a node and its edges; returns false if `id` was not a registered node.
+     * Only the first edge between `id` and each other node is removed from that
+     * node's lists, so parallel edges leave dangling entries behind.
+     */
     removeNode(id) {
         if (!this.nodes.has(id))
             return false;
@@ -57,6 +66,12 @@ export class Graph {
         return [...this.nodes.values()];
     }
     // ── Edge operations ──────────────────────────────────────────────
+    /**
+     * Appends an edge (weight defaults to 1); parallel edges are allowed. Endpoints
+     * not added via `addNode` get adjacency lists but are not registered nodes:
+     * they are absent from `nodeIds`/`getNode` and skipped by traversal visitors
+     * and `dijkstra`. Chainable.
+     */
     addEdge(from, to, weight = 1, data) {
         this.ensureNode(from);
         this.ensureNode(to);
@@ -70,12 +85,17 @@ export class Graph {
         }
         return this;
     }
+    /** First stored edge from `from` to `to`; with parallel edges the others are not returned. */
     getEdge(from, to) {
         return this.adjOut.get(from)?.find((e) => e.to === to);
     }
     hasEdge(from, to) {
         return this.getEdge(from, to) !== undefined;
     }
+    /**
+     * Removes one `from`→`to` edge (and its mirror when undirected); returns false
+     * if none exists. Parallel edges must be removed one call at a time.
+     */
     removeEdge(from, to) {
         const out = this.adjOut.get(from);
         if (!out)
@@ -106,18 +126,24 @@ export class Graph {
         }
         return true;
     }
+    /** Number of edges; undirected edges count once despite being stored twice. */
     get edgeCount() {
         let count = 0;
         for (const [, edges] of this.adjOut)
             count += edges.length;
         return this.directed ? count : count / 2;
     }
+    /**
+     * All edges. For undirected graphs, one edge per node pair is returned in
+     * whichever direction was seen first, which also collapses parallel edges —
+     * so `mapNodes` and `subgraph` drop undirected parallel edges.
+     */
     edges() {
         const all = [];
         for (const [, edges] of this.adjOut)
             all.push(...edges);
         if (!this.directed) {
-            // Deduplicate: keep only where from <= to (by string comparison)
+            // Deduplicate: keep the first-seen direction of each node pair
             const seen = new Set();
             return all.filter((e) => {
                 const key = `${e.from}->${e.to}`;
@@ -314,7 +340,7 @@ export class Graph {
     // ── Algorithms ───────────────────────────────────────────────────
     /**
      * Topological sort (Kahn's algorithm). Returns node ids in topological order.
-     * Throws if the graph has a cycle. Only meaningful for directed graphs.
+     * Throws if the graph is undirected or has a cycle.
      */
     topologicalSort() {
         if (!this.directed)
@@ -394,7 +420,9 @@ export class Graph {
     /**
      * Dijkstra's shortest path from `start` to `end`.
      * Returns `{ distance, path }` or `undefined` if unreachable.
-     * Edges must have non-negative weights.
+     * Edges must have non-negative weights. `end` must be a registered node;
+     * otherwise the result is a one-element path with an undefined distance
+     * rather than `undefined`.
      */
     dijkstra(start, end) {
         const dist = new Map();

package/dist/index.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Public entry point for the graph package: re-exports the `Graph` class and
+ * its supporting types, so consumers never import from internal module paths.
+ * The types are exported with `export type`, so they disappear at compile time
+ * and only `Graph` remains as a runtime export.
+ */
 export { Graph } from "./graph.js";
 export type { NodeId, GraphNode, Edge, GraphOptions, Visitor, NodePredicate, } from "./types.js";

package/dist/index.js

@@ -1 +1,7 @@
+/**
+ * Public entry point for the graph package: re-exports the `Graph` class and
+ * its supporting types, so consumers never import from internal module paths.
+ * The types are exported with `export type`, so they disappear at compile time
+ * and only `Graph` remains as a runtime export.
+ */
 export { Graph } from "./graph.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quokkaquery/graph",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Generic reusable graph library with structure representation and traversal methods",
   "keywords": [
     "graph",