@ladybugmem/icebug 0.1.0

package/lib/index.d.ts

@@ -0,0 +1,361 @@
+// TypeScript declarations for the icebug Node.js bindings.
+
+/** A node identifier (non-negative integer, safe range 0 – 2^53−1). */
+export type NodeId = number;
+
+/** An edge weight. */
+export type EdgeWeight = number;
+
+/** Pair representing an unweighted edge. */
+export type Edge = [NodeId, NodeId];
+
+/** Triple representing a weighted edge. */
+export type WeightedEdge = [NodeId, NodeId, EdgeWeight];
+
+/** Entry in a centrality ranking. */
+export interface RankingEntry {
+  node:  NodeId;
+  score: number;
+}
+
+// ── Graph (mutable, vector-backed) ───────────────────────────────────────────
+
+export class Graph {
+  /**
+   * Create a mutable graph.
+   * @param n        - Initial number of nodes (default 0).
+   * @param weighted - Enable edge weights (default false).
+   * @param directed - Create a directed graph (default false).
+   */
+  constructor(n?: number, weighted?: boolean, directed?: boolean);
+
+  // Metadata
+  numberOfNodes(): number;
+  numberOfEdges(): number;
+  upperNodeIdBound(): number;
+  isWeighted(): boolean;
+  isDirected(): boolean;
+  isEmpty(): boolean;
+
+  // Mutation
+  addNode(): NodeId;
+  addEdge(u: NodeId, v: NodeId, weight?: EdgeWeight): boolean;
+  removeNode(u: NodeId): void;
+  removeEdge(u: NodeId, v: NodeId): void;
+  setWeight(u: NodeId, v: NodeId, w: EdgeWeight): void;
+
+  // Queries
+  hasNode(u: NodeId): boolean;
+  hasEdge(u: NodeId, v: NodeId): boolean;
+  degree(u: NodeId): number;
+  degreeIn(u: NodeId): number;
+  weight(u: NodeId, v: NodeId): EdgeWeight;
+
+  // Iteration
+  nodes(): NodeId[];
+  neighbors(u: NodeId): NodeId[];
+  edges(): Edge[];
+  weightedEdges(): WeightedEdge[];
+}
+
+// ── GraphR (read-only, Arrow CSR-backed) ─────────────────────────────────────
+
+export class GraphR {
+  /**
+   * Create a read-only CSR graph.
+   *
+   * @param n          - Number of nodes.
+   * @param directed   - Directed graph?
+   * @param outIndices - CSR neighbour indices for outgoing edges.
+   * @param outIndptr  - CSR offset array for outgoing edges (length n+1).
+   * @param inIndices  - CSR neighbour indices for incoming edges (directed only).
+   * @param inIndptr   - CSR offset array for incoming edges (directed only, length n+1).
+   */
+  constructor(
+    n: number,
+    directed: boolean,
+    outIndices: number[] | Uint32Array | BigUint64Array,
+    outIndptr:  number[] | Uint32Array | BigUint64Array,
+    inIndices?: number[] | Uint32Array | BigUint64Array,
+    inIndptr?:  number[] | Uint32Array | BigUint64Array,
+  );
+
+  // Metadata
+  numberOfNodes(): number;
+  numberOfEdges(): number;
+  upperNodeIdBound(): number;
+  isWeighted(): boolean;
+  isDirected(): boolean;
+  isEmpty(): boolean;
+
+  // Queries
+  hasNode(u: NodeId): boolean;
+  hasEdge(u: NodeId, v: NodeId): boolean;
+  degree(u: NodeId): number;
+  degreeIn(u: NodeId): number;
+  weight(u: NodeId, v: NodeId): EdgeWeight;
+
+  // Iteration
+  nodes(): NodeId[];
+  neighbors(u: NodeId): NodeId[];
+  edges(): Edge[];
+}
+
+// ── Betweenness centrality ───────────────────────────────────────────────────
+
+export class Betweenness {
+  /**
+   * @param graph                  - The input graph.
+   * @param normalized             - Normalize scores to [0, 1] (default false).
+   * @param computeEdgeCentrality  - Also compute edge betweenness (default false).
+   */
+  constructor(graph: Graph | GraphR, normalized?: boolean, computeEdgeCentrality?: boolean);
+
+  run(): void;
+  hasFinished(): boolean;
+  scores(): Float64Array;
+  score(v: NodeId): number;
+  ranking(): RankingEntry[];
+  maximum(): number;
+}
+
+// ── PageRank ─────────────────────────────────────────────────────────────────
+
+export class PageRank {
+  /**
+   * @param graph      - The input graph.
+   * @param damp       - Damping factor (default 0.85).
+   * @param tol        - Convergence tolerance (default 1e-8).
+   * @param normalized - Normalize scores (default false).
+   */
+  constructor(graph: Graph | GraphR, damp?: number, tol?: number, normalized?: boolean);
+
+  run(): void;
+  hasFinished(): boolean;
+  scores(): Float64Array;
+  score(v: NodeId): number;
+  ranking(): RankingEntry[];
+  numberOfIterations(): number;
+}
+
+// ── DegreeCentrality ─────────────────────────────────────────────────────────
+
+export class DegreeCentrality {
+  /**
+   * @param graph           - The input graph.
+   * @param normalized      - Normalize scores (default false).
+   * @param outDeg          - Use out-degree (default true); false = in-degree.
+   * @param ignoreSelfLoops - Ignore self-loops (default true).
+   */
+  constructor(
+    graph: Graph | GraphR,
+    normalized?: boolean,
+    outDeg?: boolean,
+    ignoreSelfLoops?: boolean,
+  );
+
+  run(): void;
+  hasFinished(): boolean;
+  scores(): Float64Array;
+  score(v: NodeId): number;
+  ranking(): RankingEntry[];
+}
+
+// ── ConnectedComponents ───────────────────────────────────────────────────────
+
+export class ConnectedComponents {
+  /** @param graph - An undirected graph. */
+  constructor(graph: Graph | GraphR);
+
+  run(): void;
+  hasFinished(): boolean;
+  numberOfComponents(): number;
+  componentOfNode(u: NodeId): number;
+  getComponents(): NodeId[][];
+  getComponentSizes(): Record<string, number>;
+}
+
+// ── Clustering / community detection ─────────────────────────────────────────
+
+/**
+ * The result of a community detection algorithm.
+ *
+ * `membership[i]` is the internal community id assigned to node `i`.
+ * Community ids are **not** guaranteed to be consecutive starting at 0 —
+ * use `count` to know how many distinct communities exist.
+ */
+export interface PartitionResult {
+  /** Float64Array of length `numberOfNodes()`: node i → community id. */
+  membership: Float64Array;
+  /** Number of distinct (non-empty) communities. */
+  count: number;
+}
+
+/**
+ * Louvain community detection (NetworKit PLM — Parallel Louvain Method).
+ *
+ * Maximises modularity via a greedy, multi-level approach.
+ * Operates on **undirected** graphs; weights are respected when present.
+ */
+export class Louvain {
+  /**
+   * @param graph    An undirected Graph or GraphR.
+   * @param refine   Add a second refinement pass (default false).
+   * @param gamma    Resolution parameter — 1.0 is standard modularity (default 1.0).
+   *                 Lower values yield fewer, larger communities; higher values more,
+   *                 smaller ones.
+   * @param maxIter  Maximum move-phase iterations per level (default 32).
+   * @param turbo    Faster mode using O(n) extra memory per thread (default true).
+   * @param recurse  Use recursive coarsening (default true).
+   */
+  constructor(
+    graph:    Graph | GraphR,
+    refine?:  boolean,
+    gamma?:   number,
+    maxIter?: number,
+    turbo?:   boolean,
+    recurse?: boolean,
+  );
+
+  /** Run the algorithm. */
+  run(): void;
+
+  /** Returns true once `run()` has completed successfully. */
+  hasFinished(): boolean;
+
+  /** Number of communities in the detected partition. */
+  numberOfCommunities(): number;
+
+  /**
+   * Community id of node `u`.
+   * The id is an opaque integer meaningful only relative to other nodes'
+   * community ids (i.e. same id ⟺ same community).
+   */
+  communityOfNode(u: NodeId): number;
+
+  /**
+   * Full partition as a typed array.
+   * `membership[i]` is the community id of node `i`.
+   */
+  getPartition(): PartitionResult;
+
+  /**
+   * Communities as an array of node-id arrays.
+   * Each inner array contains the ids of all nodes in one community.
+   * Communities are returned in ascending order of their internal id.
+   */
+  getCommunities(): NodeId[][];
+
+  /**
+   * Modularity Q ∈ [−0.5, 1.0] of the detected partition.
+   * Higher values indicate a stronger community structure.
+   */
+  modularity(): number;
+}
+
+/**
+ * Leiden community detection (NetworKit ParallelLeiden).
+ *
+ * A refined version of Louvain that guarantees (in the sequential reference
+ * implementation) that all communities are internally connected.
+ *
+ * **Note:** The NetworKit parallel implementation may produce a small fraction
+ * of internally disconnected communities in some cases.
+ *
+ * Operates on **undirected** graphs; weights are respected when present.
+ */
+export class Leiden {
+  /**
+   * @param graph      An undirected Graph or GraphR.
+   * @param iterations Number of full Leiden iterations to run (default 3).
+   * @param randomize  Randomise node order each iteration (default true).
+   * @param gamma      Resolution parameter — 1.0 is standard modularity (default 1.0).
+   */
+  constructor(
+    graph:       Graph | GraphR,
+    iterations?: number,
+    randomize?:  boolean,
+    gamma?:      number,
+  );
+
+  /** Run the algorithm. */
+  run(): void;
+
+  /** Returns true once `run()` has completed successfully. */
+  hasFinished(): boolean;
+
+  /** Number of communities in the detected partition. */
+  numberOfCommunities(): number;
+
+  /**
+   * Community id of node `u`.
+   * The id is an opaque integer meaningful only relative to other nodes'
+   * community ids (i.e. same id ⟺ same community).
+   */
+  communityOfNode(u: NodeId): number;
+
+  /**
+   * Full partition as a typed array.
+   * `membership[i]` is the community id of node `i`.
+   */
+  getPartition(): PartitionResult;
+
+  /**
+   * Communities as an array of node-id arrays.
+   * Each inner array contains the ids of all nodes in one community.
+   * Communities are returned in ascending order of their internal id.
+   */
+  getCommunities(): NodeId[][];
+
+  /**
+   * Modularity Q ∈ [−0.5, 1.0] of the detected partition.
+   * Higher values indicate a stronger community structure.
+   */
+  modularity(): number;
+}
+
+// ── I/O functions ────────────────────────────────────────────────────────────
+
+/**
+ * Read a graph in METIS format.
+ * @param path - Path to the .graph file.
+ * @returns A mutable Graph.
+ */
+export function readMETIS(path: string): Graph;
+
+/**
+ * Read a graph from an edge list file.
+ * @param path          - Path to the edge list file.
+ * @param separator     - Column separator character (default ' ').
+ * @param firstNode     - Index of the first node in the file (default 0).
+ * @param directed      - Treat as directed graph (default false).
+ * @param commentPrefix - Prefix for comment lines (default '#').
+ * @returns A mutable Graph.
+ */
+export function readEdgeList(
+  path:          string,
+  separator?:    string,
+  firstNode?:    number,
+  directed?:     boolean,
+  commentPrefix?: string,
+): Graph;
+
+// ── JS helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Convenience: build an unweighted Graph from n and an edge list.
+ */
+export function graphFromEdges(
+  n: number,
+  edges: Edge[],
+  opts?: { weighted?: boolean; directed?: boolean },
+): Graph;
+
+/**
+ * Convenience: build a weighted Graph from n and a weighted edge list.
+ */
+export function weightedGraphFromEdges(
+  n: number,
+  edges: WeightedEdge[],
+  opts?: { directed?: boolean },
+): Graph;

package/lib/index.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * icebug – Node.js bindings for NetworKit graph analytics
+ *
+ * This module re-exports the native N-API addon and adds lightweight
+ * JavaScript conveniences on top.
+ */
+
+const path = require('path');
+
+// Load the compiled native addon.
+let native;
+try {
+  native = require(path.join(__dirname, '..', 'build', 'Release', 'icebug.node'));
+} catch (releaseErr) {
+  try {
+    native = require(path.join(__dirname, '..', 'build', 'Debug', 'icebug.node'));
+  } catch (debugErr) {
+    throw new Error(
+      `Failed to load icebug native addon.\n` +
+      `  Release error: ${releaseErr.message}\n` +
+      `  Debug error:   ${debugErr.message}\n` +
+      `Run 'npm install' or 'npm run build' first.`
+    );
+  }
+}
+
+// ── Re-export all native classes and functions ──────────────────────────────
+
+const {
+  Graph,
+  GraphR,
+  Betweenness,
+  PageRank,
+  DegreeCentrality,
+  ConnectedComponents,
+  Louvain,
+  Leiden,
+  readMETIS,
+  readEdgeList,
+} = native;
+
+// ── Higher-level helpers ────────────────────────────────────────────────────
+
+/**
+ * Build a Graph from a plain edge list.
+ *
+ * @param {number}            n        - Number of nodes.
+ * @param {[number,number][]} edges    - Array of [u, v] pairs.
+ * @param {object}            [opts]
+ * @param {boolean}           [opts.weighted=false]
+ * @param {boolean}           [opts.directed=false]
+ * @returns {Graph}
+ */
+function graphFromEdges(n, edges, { weighted = false, directed = false } = {}) {
+  const g = new Graph(n, weighted, directed);
+  for (const [u, v] of edges) g.addEdge(u, v);
+  return g;
+}
+
+/**
+ * Build a Graph from a plain edge list with weights.
+ *
+ * @param {number}                      n
+ * @param {[number,number,number][]}    edges  - Array of [u, v, weight] triples.
+ * @param {object}                      [opts]
+ * @param {boolean}                     [opts.directed=false]
+ * @returns {Graph}
+ */
+function weightedGraphFromEdges(n, edges, { directed = false } = {}) {
+  const g = new Graph(n, true, directed);
+  for (const [u, v, w] of edges) g.addEdge(u, v, w);
+  return g;
+}
+
+module.exports = {
+  // Native classes
+  // GraphR accepts: (n, directed, outIndices: BigUint64Array, outIndptr: BigUint64Array
+  //                 [, inIndices: BigUint64Array, inIndptr: BigUint64Array])
+  // The ArrayBuffers are pinned (zero-copy) until the GraphR instance is GC'd.
+  Graph,
+  GraphR,
+
+  // Algorithm classes
+  Betweenness,
+  PageRank,
+  DegreeCentrality,
+  ConnectedComponents,
+
+  // Clustering / community detection
+  Louvain,
+  Leiden,
+
+  // I/O functions
+  readMETIS,
+  readEdgeList,
+
+  // JS helpers
+  graphFromEdges,
+  weightedGraphFromEdges,
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ladybugmem/icebug",
+  "version": "0.1.0",
+  "description": "Node.js bindings for icebug – high-performance graph analytics (NetworKit fork with Arrow CSR support)",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/",
+    "src/",
+    "build/Release/",
+    "vendor/",
+    "binding.gyp"
+  ],
+  "scripts": {
+    "download":  "bash scripts/download-icebug.sh",
+    "install":   "npm run download && node-gyp rebuild",
+    "build":     "npm run download && node-gyp rebuild",
+    "build:debug": "npm run download && node-gyp rebuild --debug",
+    "clean":     "node-gyp clean",
+    "test":      "node test/basic.test.js"
+  },
+  "keywords": ["graph", "network", "analytics", "networkit", "icebug", "betweenness", "pagerank"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ladybug-Memory/icebug-nodejs"
+  },
+  "dependencies": {
+    "node-addon-api": "^8.0.0"
+  },
+  "devDependencies": {
+    "node-gyp": "^10.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "binary": {
+    "module_name": "icebug",
+    "module_path": "./build/Release"
+  },
+  "gypfile": true
+}