@quokkaquery/graph 0.0.0-stage → 0.1.1

package/API.md

@@ -0,0 +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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuokkaQuery (https://quokkaquery.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,187 @@
-# Temporary Holding Version
+# @quokkaquery/graph
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Built and maintained by [QuokkaQuery](https://quokkaquery.com). Source on [GitHub](https://github.com/Nodlume/graph).
+
+Generic TypeScript graph library with adjacency-list representation. Supports directed and undirected graphs, weighted edges, traversals, and common graph algorithms.
+
+## Install
+
+```bash
+npm install @quokkaquery/graph
+```
+
+## Quick Start
+
+```ts
+import { Graph } from "@quokkaquery/graph";
+
+const g = new Graph<string>({ directed: true });
+
+g.addNode("a", "Alice")
+ .addNode("b", "Bob")
+ .addNode("c", "Carol");
+
+g.addEdge("a", "b", 1);
+g.addEdge("b", "c", 2);
+g.addEdge("a", "c", 10);
+
+// Shortest path
+const result = g.dijkstra("a", "c");
+// { distance: 3, path: ["a", "b", "c"] }
+```
+
+## API
+
+### Constructor
+
+```ts
+new Graph<T, E>(opts?: { directed?: boolean })
+```
+
+- `T` — node data type (default `unknown`)
+- `E` — edge data type (default `unknown`)
+- `directed` — defaults to `true`
+
+### Node Operations
+
+| Method | Returns | Description |
+|---|---|---|
+| `addNode(id, data)` | `this` | Add a node (chainable) |
+| `getNode(id)` | `GraphNode<T> \| undefined` | Get node by id |
+| `hasNode(id)` | `boolean` | Check if node exists |
+| `removeNode(id)` | `boolean` | Remove node and all its edges |
+| `nodeCount` | `number` | Number of nodes |
+| `nodeIds()` | `NodeId[]` | All node ids |
+| `nodeEntries()` | `GraphNode<T>[]` | All nodes |
+
+### Edge Operations
+
+| Method | Returns | Description |
+|---|---|---|
+| `addEdge(from, to, weight?, data?)` | `this` | Add an edge (chainable, default weight 1) |
+| `getEdge(from, to)` | `Edge<E> \| undefined` | Get edge between two nodes |
+| `hasEdge(from, to)` | `boolean` | Check if edge exists |
+| `removeEdge(from, to)` | `boolean` | Remove an edge |
+| `edgeCount` | `number` | Number of edges |
+| `edges()` | `Edge<E>[]` | All edges (deduplicated for undirected) |
+
+### Neighbors & Degree
+
+| Method | Returns | Description |
+|---|---|---|
+| `neighbors(id)` | `NodeId[]` | Outgoing neighbor ids |
+| `outEdges(id)` | `Edge<E>[]` | Outgoing edges |
+| `inEdges(id)` | `Edge<E>[]` | Incoming edges |
+| `outDegree(id)` | `number` | Number of outgoing edges |
+| `inDegree(id)` | `number` | Number of incoming edges |
+| `degree(id)` | `number` | Total degree |
+| `predecessors(id)` | `NodeId[]` | Nodes with edges pointing to this node |
+| `successors(id)` | `NodeId[]` | Nodes this node points to |
+| `connectedNodes(id)` | `NodeId[]` | Union of predecessors and successors |
+
+### Node Classification
+
+| Method | Returns | Description |
+|---|---|---|
+| `isSource(id)` | `boolean` | In-degree 0 (directed only) |
+| `isSink(id)` | `boolean` | Out-degree 0 (directed only) |
+| `isIsolated(id)` | `boolean` | Degree 0 |
+| `sources()` | `NodeId[]` | All source nodes |
+| `sinks()` | `NodeId[]` | All sink nodes |
+| `isolatedNodes()` | `NodeId[]` | All isolated nodes |
+
+### Reachability
+
+| Method | Returns | Description |
+|---|---|---|
+| `reachableFrom(id)` | `Set<NodeId>` | All nodes reachable via outgoing edges |
+| `reachableTo(id)` | `Set<NodeId>` | All nodes that can reach this node |
+
+### Traversals
+
+| Method | Description |
+|---|---|
+| `bfs(start, visitor)` | Breadth-first traversal. Return `false` from visitor to stop early. |
+| `dfs(start, visitor)` | Depth-first traversal. Return `false` from visitor to stop early. |
+| `findBfs(start, predicate)` | Find first node matching predicate via BFS |
+| `findDfs(start, predicate)` | Find first node matching predicate via DFS |
+
+### Algorithms
+
+| Method | Description |
+|---|---|
+| `topologicalSort()` | Kahn's algorithm. Throws if graph has a cycle. Directed only. |
+| `hasCycle()` | Cycle detection (DFS for directed, Union-Find for undirected) |
+| `dijkstra(start, end)` | Shortest path. Returns `{ distance, path }` or `undefined`. |
+| `connectedComponents()` | Connected (undirected) or weakly-connected (directed) components |
+
+### Utilities
+
+| Method | Description |
+|---|---|
+| `mapNodes(fn)` | Transform node data, producing a new graph |
+| `subgraph(ids)` | Extract a subgraph containing only the given node ids |
+
+## Types
+
+```ts
+type NodeId = string | number;
+
+interface GraphNode<T> { id: NodeId; data: T }
+
+interface Edge<E> { from: NodeId; to: NodeId; weight: number; data: E }
+
+type Visitor<T> = (node: GraphNode<T>, depth: number) => void | false;
+
+type NodePredicate<T> = (node: GraphNode<T>) => boolean;
+```
+
+## Development
+
+```bash
+npm test          # run tests
+npm run test:watch # watch mode
+npm run build      # compile TypeScript
+```
+
+## Gotchas
+
+- **addEdge auto-creates nodes** with `undefined` data. If you need typed data, call `addNode` first.
+- **Undirected edges** are stored as two directed entries internally. `edges()` deduplicates but `outEdges()`/`inEdges()` do not.
+- **topologicalSort** throws `"Graph contains a cycle"` — catch it or check `hasCycle()` first.
+- **dijkstra** uses an array-based priority queue — fine for moderate sizes, not for 100k+ node graphs.
+- **reachableFrom** excludes the start node itself unless a cycle leads back to it.
+
+## Common Patterns
+
+### Dependency ordering
+
+```ts
+const deps = new Graph<string>();
+deps.addEdge("build", "lint");
+deps.addEdge("test", "build");
+const order = deps.topologicalSort(); // ["test", "build", "lint"]
+```
+
+### Shortest path
+
+```ts
+const g = new Graph<string>();
+g.addEdge("a", "b", 4).addEdge("b", "c", 2).addEdge("a", "c", 7);
+const result = g.dijkstra("a", "c"); // { distance: 6, path: ["a", "b", "c"] }
+```
+
+### Filtering to a subgraph
+
+```ts
+const important = new Set(g.nodeIds().filter(id => g.degree(id) > 3));
+const sub = g.subgraph(important);
+```
+
+## License
+
+MIT © [QuokkaQuery](https://quokkaquery.com)
+
+---
+
+Part of the open-source tooling behind [QuokkaQuery](https://quokkaquery.com).

package/dist/graph.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 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
+ */
+export declare class Graph<T = unknown, E = unknown> {
+    readonly directed: boolean;
+    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[];
+    /** Outgoing edges from a node. */
+    outEdges(id: NodeId): Edge<E>[];
+    /** Incoming edges to a node (always available, even for undirected). */
+    inEdges(id: NodeId): Edge<E>[];
+    /** Out-degree of a node. */
+    outDegree(id: NodeId): number;
+    /** In-degree of a node. */
+    inDegree(id: NodeId): number;
+    /** Total degree: in + out (for undirected, equals the number of incident edges). */
+    degree(id: NodeId): number;
+    /** Predecessor node ids — nodes with an edge pointing *to* this node. */
+    predecessors(id: NodeId): NodeId[];
+    /** Successor node ids — same as `neighbors`, nodes this node points *to*. */
+    successors(id: NodeId): NodeId[];
+    /**
+     * All directly connected node ids (union of predecessors and successors).
+     * For undirected graphs this equals `neighbors`. For directed graphs it
+     * includes both incoming and outgoing connections, deduplicated.
+     */
+    connectedNodes(id: NodeId): NodeId[];
+    /** Whether `id` is a source (no incoming edges). Directed only — always false for undirected. */
+    isSource(id: NodeId): boolean;
+    /** Whether `id` is a sink (no outgoing edges). Directed only — always false for undirected. */
+    isSink(id: NodeId): boolean;
+    /** Whether `id` has no edges at all. */
+    isIsolated(id: NodeId): boolean;
+    /** All source nodes (in-degree 0). Directed graphs only. */
+    sources(): NodeId[];
+    /** All sink nodes (out-degree 0). Directed graphs only. */
+    sinks(): NodeId[];
+    /** All isolated nodes (degree 0). */
+    isolatedNodes(): NodeId[];
+    /**
+     * All nodes reachable from `id` (transitive closure of successors).
+     * Does not include `id` itself unless there is a cycle back to it.
+     */
+    reachableFrom(id: NodeId): Set<NodeId>;
+    /**
+     * All nodes that can reach `id` (transitive closure of predecessors).
+     * Does not include `id` itself unless there is a cycle.
+     */
+    reachableTo(id: NodeId): Set<NodeId>;
+    /** Breadth-first traversal from a start node. */
+    bfs(start: NodeId, visitor: Visitor<T>): void;
+    /** Depth-first traversal from a start node (iterative). */
+    dfs(start: NodeId, visitor: Visitor<T>): void;
+    /** Find a node matching a predicate via BFS. */
+    findBfs(start: NodeId, predicate: NodePredicate<T>): GraphNode<T> | undefined;
+    /** Find a node matching a predicate via DFS. */
+    findDfs(start: NodeId, predicate: NodePredicate<T>): GraphNode<T> | undefined;
+    /**
+     * Topological sort (Kahn's algorithm). Returns node ids in topological order.
+     * Throws if the graph is undirected or has a cycle.
+     */
+    topologicalSort(): NodeId[];
+    /** Detect whether the graph contains a cycle. */
+    hasCycle(): boolean;
+    /**
+     * Dijkstra's shortest path from `start` to `end`.
+     * Returns `{ distance, path }` or `undefined` if unreachable.
+     * 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;
+        path: NodeId[];
+    } | undefined;
+    /**
+     * Connected components (undirected) or weakly-connected components (directed).
+     * Returns an array of node-id arrays, one per component.
+     */
+    connectedComponents(): NodeId[][];
+    /**
+     * Map over node data, producing a new graph with transformed data.
+     * Edges and structure are preserved.
+     */
+    mapNodes<U>(fn: (node: GraphNode<T>) => U): Graph<U, E>;
+    /** Create a subgraph containing only the given node ids. */
+    subgraph(ids: Set<NodeId>): Graph<T, E>;
+    private ensureNode;
+}

package/dist/graph.js

@@ -0,0 +1,535 @@
+/**
+ * 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
+ */
+export class Graph {
+    directed;
+    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))
+            this.adjOut.set(id, []);
+        if (!this.adjIn.has(id))
+            this.adjIn.set(id, []);
+        return this;
+    }
+    getNode(id) {
+        return this.nodes.get(id);
+    }
+    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;
+        this.nodes.delete(id);
+        // Remove all edges touching this node
+        this.adjOut.delete(id);
+        this.adjIn.delete(id);
+        for (const [, edges] of this.adjOut) {
+            const idx = edges.findIndex((e) => e.to === id);
+            if (idx !== -1)
+                edges.splice(idx, 1);
+        }
+        for (const [, edges] of this.adjIn) {
+            const idx = edges.findIndex((e) => e.from === id);
+            if (idx !== -1)
+                edges.splice(idx, 1);
+        }
+        return true;
+    }
+    get nodeCount() {
+        return this.nodes.size;
+    }
+    nodeIds() {
+        return [...this.nodes.keys()];
+    }
+    nodeEntries() {
+        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);
+        const edge = { from, to, weight, data: data };
+        this.adjOut.get(from).push(edge);
+        this.adjIn.get(to).push(edge);
+        if (!this.directed) {
+            const reverse = { from: to, to: from, weight, data: data };
+            this.adjOut.get(to).push(reverse);
+            this.adjIn.get(from).push(reverse);
+        }
+        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)
+            return false;
+        const idx = out.findIndex((e) => e.to === to);
+        if (idx === -1)
+            return false;
+        out.splice(idx, 1);
+        const inEdges = this.adjIn.get(to);
+        if (inEdges) {
+            const iIdx = inEdges.findIndex((e) => e.from === from);
+            if (iIdx !== -1)
+                inEdges.splice(iIdx, 1);
+        }
+        if (!this.directed) {
+            const revOut = this.adjOut.get(to);
+            if (revOut) {
+                const rIdx = revOut.findIndex((e) => e.to === from);
+                if (rIdx !== -1)
+                    revOut.splice(rIdx, 1);
+            }
+            const revIn = this.adjIn.get(from);
+            if (revIn) {
+                const rIdx = revIn.findIndex((e) => e.from === to);
+                if (rIdx !== -1)
+                    revIn.splice(rIdx, 1);
+            }
+        }
+        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 the first-seen direction of each node pair
+            const seen = new Set();
+            return all.filter((e) => {
+                const key = `${e.from}->${e.to}`;
+                const rev = `${e.to}->${e.from}`;
+                if (seen.has(key) || seen.has(rev))
+                    return false;
+                seen.add(key);
+                return true;
+            });
+        }
+        return all;
+    }
+    /** Outgoing neighbors of a node. */
+    neighbors(id) {
+        return (this.adjOut.get(id) ?? []).map((e) => e.to);
+    }
+    /** Outgoing edges from a node. */
+    outEdges(id) {
+        return this.adjOut.get(id) ?? [];
+    }
+    /** Incoming edges to a node (always available, even for undirected). */
+    inEdges(id) {
+        return this.adjIn.get(id) ?? [];
+    }
+    /** Out-degree of a node. */
+    outDegree(id) {
+        return (this.adjOut.get(id) ?? []).length;
+    }
+    /** In-degree of a node. */
+    inDegree(id) {
+        return (this.adjIn.get(id) ?? []).length;
+    }
+    /** Total degree: in + out (for undirected, equals the number of incident edges). */
+    degree(id) {
+        return this.directed
+            ? this.inDegree(id) + this.outDegree(id)
+            : this.outDegree(id); // undirected stores both directions, so outDegree already counts all
+    }
+    // ── Node-level helpers (for custom traversals) ───────────────────
+    /** Predecessor node ids — nodes with an edge pointing *to* this node. */
+    predecessors(id) {
+        return (this.adjIn.get(id) ?? []).map((e) => e.from);
+    }
+    /** Successor node ids — same as `neighbors`, nodes this node points *to*. */
+    successors(id) {
+        return this.neighbors(id);
+    }
+    /**
+     * All directly connected node ids (union of predecessors and successors).
+     * For undirected graphs this equals `neighbors`. For directed graphs it
+     * includes both incoming and outgoing connections, deduplicated.
+     */
+    connectedNodes(id) {
+        if (!this.directed)
+            return this.neighbors(id);
+        const set = new Set();
+        for (const e of this.adjOut.get(id) ?? [])
+            set.add(e.to);
+        for (const e of this.adjIn.get(id) ?? [])
+            set.add(e.from);
+        return [...set];
+    }
+    /** Whether `id` is a source (no incoming edges). Directed only — always false for undirected. */
+    isSource(id) {
+        return this.directed && this.inDegree(id) === 0 && this.hasNode(id);
+    }
+    /** Whether `id` is a sink (no outgoing edges). Directed only — always false for undirected. */
+    isSink(id) {
+        return this.directed && this.outDegree(id) === 0 && this.hasNode(id);
+    }
+    /** Whether `id` has no edges at all. */
+    isIsolated(id) {
+        return this.degree(id) === 0 && this.hasNode(id);
+    }
+    /** All source nodes (in-degree 0). Directed graphs only. */
+    sources() {
+        if (!this.directed)
+            return [];
+        return this.nodeIds().filter((id) => this.inDegree(id) === 0);
+    }
+    /** All sink nodes (out-degree 0). Directed graphs only. */
+    sinks() {
+        if (!this.directed)
+            return [];
+        return this.nodeIds().filter((id) => this.outDegree(id) === 0);
+    }
+    /** All isolated nodes (degree 0). */
+    isolatedNodes() {
+        return this.nodeIds().filter((id) => this.degree(id) === 0);
+    }
+    /**
+     * All nodes reachable from `id` (transitive closure of successors).
+     * Does not include `id` itself unless there is a cycle back to it.
+     */
+    reachableFrom(id) {
+        const reached = new Set();
+        const stack = [...this.neighbors(id)];
+        while (stack.length > 0) {
+            const cur = stack.pop();
+            if (reached.has(cur))
+                continue;
+            reached.add(cur);
+            for (const next of this.neighbors(cur)) {
+                if (!reached.has(next))
+                    stack.push(next);
+            }
+        }
+        return reached;
+    }
+    /**
+     * All nodes that can reach `id` (transitive closure of predecessors).
+     * Does not include `id` itself unless there is a cycle.
+     */
+    reachableTo(id) {
+        const reached = new Set();
+        const stack = [...this.predecessors(id)];
+        while (stack.length > 0) {
+            const cur = stack.pop();
+            if (reached.has(cur))
+                continue;
+            reached.add(cur);
+            for (const prev of this.predecessors(cur)) {
+                if (!reached.has(prev))
+                    stack.push(prev);
+            }
+        }
+        return reached;
+    }
+    // ── Traversals ───────────────────────────────────────────────────
+    /** Breadth-first traversal from a start node. */
+    bfs(start, visitor) {
+        const visited = new Set();
+        const queue = [{ id: start, depth: 0 }];
+        visited.add(start);
+        while (queue.length > 0) {
+            const { id, depth } = queue.shift();
+            const node = this.nodes.get(id);
+            if (!node)
+                continue;
+            if (visitor(node, depth) === false)
+                return;
+            for (const nId of this.neighbors(id)) {
+                if (!visited.has(nId)) {
+                    visited.add(nId);
+                    queue.push({ id: nId, depth: depth + 1 });
+                }
+            }
+        }
+    }
+    /** Depth-first traversal from a start node (iterative). */
+    dfs(start, visitor) {
+        const visited = new Set();
+        const stack = [{ id: start, depth: 0 }];
+        while (stack.length > 0) {
+            const { id, depth } = stack.pop();
+            if (visited.has(id))
+                continue;
+            visited.add(id);
+            const node = this.nodes.get(id);
+            if (!node)
+                continue;
+            if (visitor(node, depth) === false)
+                return;
+            // Push neighbors in reverse so the first neighbor is visited first
+            const nbrs = this.neighbors(id);
+            for (let i = nbrs.length - 1; i >= 0; i--) {
+                if (!visited.has(nbrs[i]))
+                    stack.push({ id: nbrs[i], depth: depth + 1 });
+            }
+        }
+    }
+    /** Find a node matching a predicate via BFS. */
+    findBfs(start, predicate) {
+        let found;
+        this.bfs(start, (node) => {
+            if (predicate(node)) {
+                found = node;
+                return false;
+            }
+        });
+        return found;
+    }
+    /** Find a node matching a predicate via DFS. */
+    findDfs(start, predicate) {
+        let found;
+        this.dfs(start, (node) => {
+            if (predicate(node)) {
+                found = node;
+                return false;
+            }
+        });
+        return found;
+    }
+    // ── Algorithms ───────────────────────────────────────────────────
+    /**
+     * Topological sort (Kahn's algorithm). Returns node ids in topological order.
+     * Throws if the graph is undirected or has a cycle.
+     */
+    topologicalSort() {
+        if (!this.directed)
+            throw new Error("Topological sort requires a directed graph");
+        const inDeg = new Map();
+        for (const id of this.nodes.keys())
+            inDeg.set(id, 0);
+        for (const [, edges] of this.adjOut) {
+            for (const e of edges)
+                inDeg.set(e.to, (inDeg.get(e.to) ?? 0) + 1);
+        }
+        const queue = [];
+        for (const [id, deg] of inDeg)
+            if (deg === 0)
+                queue.push(id);
+        const result = [];
+        while (queue.length > 0) {
+            const id = queue.shift();
+            result.push(id);
+            for (const e of this.adjOut.get(id) ?? []) {
+                const newDeg = inDeg.get(e.to) - 1;
+                inDeg.set(e.to, newDeg);
+                if (newDeg === 0)
+                    queue.push(e.to);
+            }
+        }
+        if (result.length !== this.nodes.size)
+            throw new Error("Graph contains a cycle");
+        return result;
+    }
+    /** Detect whether the graph contains a cycle. */
+    hasCycle() {
+        if (this.directed) {
+            // DFS-based: white(0)/gray(1)/black(2)
+            const color = new Map();
+            for (const id of this.nodes.keys())
+                color.set(id, 0);
+            const dfs = (id) => {
+                color.set(id, 1);
+                for (const e of this.adjOut.get(id) ?? []) {
+                    if (color.get(e.to) === 1)
+                        return true;
+                    if (color.get(e.to) === 0 && dfs(e.to))
+                        return true;
+                }
+                color.set(id, 2);
+                return false;
+            };
+            for (const id of this.nodes.keys()) {
+                if (color.get(id) === 0 && dfs(id))
+                    return true;
+            }
+            return false;
+        }
+        else {
+            // Union-Find for undirected
+            const parent = new Map();
+            const find = (x) => {
+                while (parent.get(x) !== x) {
+                    parent.set(x, parent.get(parent.get(x)));
+                    x = parent.get(x);
+                }
+                return x;
+            };
+            for (const id of this.nodes.keys())
+                parent.set(id, id);
+            for (const edge of this.edges()) {
+                const rootA = find(edge.from);
+                const rootB = find(edge.to);
+                if (rootA === rootB)
+                    return true;
+                parent.set(rootA, rootB);
+            }
+            return false;
+        }
+    }
+    /**
+     * Dijkstra's shortest path from `start` to `end`.
+     * Returns `{ distance, path }` or `undefined` if unreachable.
+     * 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();
+        const prev = new Map();
+        const visited = new Set();
+        // Simple priority queue (array-based — fine for moderate graph sizes)
+        const pq = [];
+        for (const id of this.nodes.keys())
+            dist.set(id, Infinity);
+        dist.set(start, 0);
+        prev.set(start, null);
+        pq.push({ id: start, d: 0 });
+        while (pq.length > 0) {
+            pq.sort((a, b) => a.d - b.d);
+            const { id } = pq.shift();
+            if (visited.has(id))
+                continue;
+            visited.add(id);
+            if (id === end)
+                break;
+            for (const e of this.adjOut.get(id) ?? []) {
+                const alt = dist.get(id) + e.weight;
+                if (alt < dist.get(e.to)) {
+                    dist.set(e.to, alt);
+                    prev.set(e.to, id);
+                    pq.push({ id: e.to, d: alt });
+                }
+            }
+        }
+        if (dist.get(end) === Infinity)
+            return undefined;
+        const path = [];
+        let cur = end;
+        while (cur !== null) {
+            path.unshift(cur);
+            cur = prev.get(cur) ?? null;
+        }
+        return { distance: dist.get(end), path };
+    }
+    /**
+     * Connected components (undirected) or weakly-connected components (directed).
+     * Returns an array of node-id arrays, one per component.
+     */
+    connectedComponents() {
+        const visited = new Set();
+        const components = [];
+        for (const id of this.nodes.keys()) {
+            if (visited.has(id))
+                continue;
+            const component = [];
+            // BFS ignoring direction
+            const queue = [id];
+            visited.add(id);
+            while (queue.length > 0) {
+                const cur = queue.shift();
+                component.push(cur);
+                for (const e of this.adjOut.get(cur) ?? []) {
+                    if (!visited.has(e.to)) {
+                        visited.add(e.to);
+                        queue.push(e.to);
+                    }
+                }
+                if (this.directed) {
+                    for (const e of this.adjIn.get(cur) ?? []) {
+                        if (!visited.has(e.from)) {
+                            visited.add(e.from);
+                            queue.push(e.from);
+                        }
+                    }
+                }
+            }
+            components.push(component);
+        }
+        return components;
+    }
+    /**
+     * Map over node data, producing a new graph with transformed data.
+     * Edges and structure are preserved.
+     */
+    mapNodes(fn) {
+        const g = new Graph({ directed: this.directed });
+        for (const node of this.nodes.values())
+            g.addNode(node.id, fn(node));
+        for (const edge of this.edges())
+            g.addEdge(edge.from, edge.to, edge.weight, edge.data);
+        return g;
+    }
+    /** Create a subgraph containing only the given node ids. */
+    subgraph(ids) {
+        const g = new Graph({ directed: this.directed });
+        for (const id of ids) {
+            const node = this.nodes.get(id);
+            if (node)
+                g.addNode(id, node.data);
+        }
+        for (const edge of this.edges()) {
+            if (ids.has(edge.from) && ids.has(edge.to)) {
+                g.addEdge(edge.from, edge.to, edge.weight, edge.data);
+            }
+        }
+        return g;
+    }
+    // ── Internal ─────────────────────────────────────────────────────
+    ensureNode(id) {
+        if (!this.adjOut.has(id)) {
+            this.adjOut.set(id, []);
+            this.adjIn.set(id, []);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +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

@@ -0,0 +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/dist/types.d.ts

@@ -0,0 +1,22 @@
+/** Unique identifier for a node — typically a string or number. */
+export type NodeId = string | number;
+/** A node in the graph, holding an id and arbitrary data. */
+export interface GraphNode<T = unknown> {
+    id: NodeId;
+    data: T;
+}
+/** An edge connecting two nodes, with optional weight and metadata. */
+export interface Edge<E = unknown> {
+    from: NodeId;
+    to: NodeId;
+    weight: number;
+    data: E;
+}
+/** Options when constructing a graph. */
+export interface GraphOptions {
+    directed?: boolean;
+}
+/** Visitor callback for traversals. Return `false` to stop early. */
+export type Visitor<T> = (node: GraphNode<T>, depth: number) => void | false;
+/** Filter predicate for search methods. */
+export type NodePredicate<T> = (node: GraphNode<T>) => boolean;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@quokkaquery/graph",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Generic reusable graph library with structure representation and traversal methods",
+  "keywords": [
+    "graph",
+    "data-structure",
+    "traversal",
+    "bfs",
+    "dfs",
+    "topological-sort",
+    "typescript"
+  ],
+  "homepage": "https://quokkaquery.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nodlume/graph.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Nodlume/graph/issues"
+  },
+  "author": {
+    "name": "QuokkaQuery",
+    "url": "https://quokkaquery.com"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "API.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}