@graphty/algorithms 1.2.0 → 1.3.1

package/dist/src/utils/math-utilities.js

@@ -0,0 +1,123 @@
+/**
+ * Seeded random number generator for reproducible results
+ */
+export class SeededRandom {
+    constructor(seed) {
+        this.m = 0x80000000; // 2**31
+        this.a = 1103515245;
+        this.c = 12345;
+        // Handle negative seeds correctly
+        this.seed = ((seed % this.m) + this.m) % this.m;
+    }
+    /**
+     * Generate next random number between 0 and 1
+     */
+    next() {
+        this.seed = ((this.a * this.seed) + this.c) % this.m;
+        return this.seed / (this.m - 1);
+    }
+    /**
+     * Create a generator function for backward compatibility
+     */
+    static createGenerator(seed) {
+        const rng = new SeededRandom(seed);
+        return () => rng.next();
+    }
+}
+/**
+ * Fisher-Yates shuffle algorithm
+ * @param array - Array to shuffle (will be modified in place)
+ * @param rng - Optional random number generator (defaults to Math.random)
+ * @returns The shuffled array (same reference as input)
+ */
+export function shuffle(array, rng = Math.random) {
+    for (let i = array.length - 1; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        const temp = array[i];
+        const tempJ = array[j];
+        if (temp !== undefined && tempJ !== undefined) {
+            array[i] = tempJ;
+            array[j] = temp;
+        }
+    }
+    return array;
+}
+/**
+ * Calculate Euclidean distance between two vectors
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Euclidean distance
+ * @throws Error if vectors have different lengths
+ */
+export function euclideanDistance(a, b) {
+    if (a.length !== b.length) {
+        throw new Error("Vectors must have same length");
+    }
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+        const aVal = a[i];
+        const bVal = b[i];
+        if (aVal !== undefined && bVal !== undefined) {
+            const diff = aVal - bVal;
+            sum += diff * diff;
+        }
+    }
+    return Math.sqrt(sum);
+}
+export const normalize = {
+    /**
+     * Min-max normalization to [0, 1] range
+     */
+    minMax(values) {
+        const vals = Array.from(values.values());
+        const min = Math.min(...vals);
+        const max = Math.max(...vals);
+        const range = max - min;
+        if (range === 0) {
+            return;
+        }
+        for (const [key, value] of values) {
+            values.set(key, (value - min) / range);
+        }
+    },
+    /**
+     * Normalize by maximum value
+     */
+    byMax(values) {
+        const max = Math.max(...values.values());
+        if (max === 0) {
+            return;
+        }
+        for (const [key, value] of values) {
+            values.set(key, value / max);
+        }
+    },
+    /**
+     * L2 (Euclidean) normalization
+     */
+    l2Norm(values) {
+        const sumSquares = Array.from(values.values())
+            .reduce((sum, val) => sum + (val * val), 0);
+        const norm = Math.sqrt(sumSquares);
+        if (norm === 0) {
+            return;
+        }
+        for (const [key, value] of values) {
+            values.set(key, value / norm);
+        }
+    },
+    /**
+     * Normalize to sum to 1
+     */
+    sumToOne(values) {
+        const sum = Array.from(values.values())
+            .reduce((acc, val) => acc + val, 0);
+        if (sum === 0) {
+            return;
+        }
+        for (const [key, value] of values) {
+            values.set(key, value / sum);
+        }
+    },
+};
+//# sourceMappingURL=math-utilities.js.map

package/dist/src/utils/math-utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"math-utilities.js","sourceRoot":"","sources":["../../../src/utils/math-utilities.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/matrix-utilities.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=matrix-utilities.d.ts.map

package/dist/src/utils/matrix-utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix-utilities.d.ts","sourceRoot":"","sources":["../../../src/utils/matrix-utilities.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC"}

package/dist/src/utils/matrix-utilities.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=matrix-utilities.js.map

package/dist/src/utils/matrix-utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix-utilities.js","sourceRoot":"","sources":["../../../src/utils/matrix-utilities.ts"],"names":[],"mappings":""}

package/dist/src/utils/optimization-helpers.d.ts

@@ -0,0 +1,33 @@
+import type { Graph } from "../core/graph.js";
+/**
+ * Common interface for algorithm options with optimization support
+ */
+export interface OptimizableOptions {
+    /**
+     * Whether to use optimized implementations
+     * - true: Force use of optimizations
+     * - false: Disable optimizations
+     * - "auto": Automatically decide based on graph size (default)
+     */
+    optimized?: boolean | "auto";
+}
+/**
+ * Determine if optimizations should be used for a given graph
+ */
+export declare function shouldOptimize(graph: Graph, options?: OptimizableOptions): boolean;
+/**
+ * Merge optimization options with algorithm-specific options
+ */
+export declare function mergeOptimizationOptions<T extends Record<string, unknown>>(graph: Graph, options: T & OptimizableOptions): T & {
+    optimized?: boolean;
+};
+/**
+ * Create an optimized version of an algorithm
+ * @example
+ * const optimizedBetweenness = createOptimizedAlgorithm(
+ *     betweennessCentrality,
+ *     (graph, options) => ({...options, optimized: true})
+ * );
+ */
+export declare function createOptimizedAlgorithm<TArgs extends [Graph, ...unknown[]], TResult>(algorithm: (...args: TArgs) => TResult, optionsTransformer?: (graph: Graph, options: unknown) => unknown): (...args: TArgs) => TResult;
+//# sourceMappingURL=optimization-helpers.d.ts.map

package/dist/src/utils/optimization-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimization-helpers.d.ts","sourceRoot":"","sources":["../../../src/utils/optimization-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,kBAAkB,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAChC;AAUD;;GAEG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAST;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtE,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,CAAC,GAAG,kBAAkB,GAChC,CAAC,GAAG;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAC,CAO3B;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACpC,KAAK,SAAS,CAAC,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,EACnC,OAAO,EAEP,SAAS,EAAE,CAAC,GAAI,IAAI,EAAE,KAAK,KAAK,OAAO,EACvC,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,GACjE,CAAC,GAAI,IAAI,EAAE,KAAK,KAAK,OAAO,CAW9B"}

package/dist/src/utils/optimization-helpers.js

@@ -0,0 +1,47 @@
+/**
+ * Check if a graph should use optimizations based on its size
+ */
+function shouldUseOptimizations(nodeCount, edgeCount) {
+    // Use optimizations for graphs with more than 10k nodes or 100k edges
+    return nodeCount > 10000 || edgeCount > 100000;
+}
+/**
+ * Determine if optimizations should be used for a given graph
+ */
+export function shouldOptimize(graph, options = {}) {
+    const { optimized = "auto" } = options;
+    if (optimized === "auto") {
+        // Check graph size
+        return shouldUseOptimizations(graph.nodeCount, graph.totalEdgeCount);
+    }
+    return optimized;
+}
+/**
+ * Merge optimization options with algorithm-specific options
+ */
+export function mergeOptimizationOptions(graph, options) {
+    const { optimized: userOptimized, ...rest } = options;
+    return {
+        ...rest,
+        optimized: shouldOptimize(graph, userOptimized !== undefined ? { optimized: userOptimized } : {}),
+    };
+}
+/**
+ * Create an optimized version of an algorithm
+ * @example
+ * const optimizedBetweenness = createOptimizedAlgorithm(
+ *     betweennessCentrality,
+ *     (graph, options) => ({...options, optimized: true})
+ * );
+ */
+export function createOptimizedAlgorithm(algorithm, optionsTransformer) {
+    return (...args) => {
+        const [graph, options, ...rest] = args;
+        if (optionsTransformer && options !== undefined) {
+            const transformedOptions = optionsTransformer(graph, options);
+            return algorithm(...[graph, transformedOptions, ...rest]);
+        }
+        return algorithm(...args);
+    };
+}
+//# sourceMappingURL=optimization-helpers.js.map

package/dist/src/utils/optimization-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimization-helpers.js","sourceRoot":"","sources":["../../../src/utils/optimization-helpers.ts"],"names":[],"mappings":"AAeA;;GAEG;AACH,SAAS,sBAAsB,CAAC,SAAiB,EAAE,SAAiB;IAChE,sEAAsE;IACtE,OAAO,SAAS,GAAG,KAAK,IAAI,SAAS,GAAG,MAAM,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAC1B,KAAY,EACZ,UAA8B,EAAE;IAEhC,MAAM,EAAC,SAAS,GAAG,MAAM,EAAC,GAAG,OAAO,CAAC;IAErC,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QACvB,mBAAmB;QACnB,OAAO,sBAAsB,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IACzE,CAAC;IAED,OAAO,SAAS,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CACpC,KAAY,EACZ,OAA+B;IAE/B,MAAM,EAAC,SAAS,EAAE,aAAa,EAAE,GAAI,IAAI,EAAC,GAAG,OAAO,CAAC;IAErD,OAAO;QACH,GAAI,IAAI;QACR,SAAS,EAAE,cAAc,CAAC,KAAK,EAAE,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAC,SAAS,EAAE,aAAa,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KACrE,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAIpC,SAAuC,EACvC,kBAAgE;IAEhE,OAAO,CAAC,GAAI,IAAW,EAAW,EAAE;QAChC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,GAAI,IAAI,CAAC,GAAG,IAAI,CAAC;QAExC,IAAI,kBAAkB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC9C,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAC9D,OAAO,SAAS,CAAC,GAAK,CAAC,KAAK,EAAE,kBAAkB,EAAE,GAAI,IAAI,CAAsB,CAAC,CAAC;QACtF,CAAC;QAED,OAAO,SAAS,CAAC,GAAI,IAAI,CAAC,CAAC;IAC/B,CAAC,CAAC;AACN,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/algorithms",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Graph algorithms library for browser environments implemented in TypeScript",
   "author": "Adam Powers <apowers@ato.ms>",
   "main": "dist/algorithms.js",
@@ -28,6 +28,14 @@
     "test:coverage": "vitest run --coverage",
     "test:browser": "vitest --project=browser",
     "test:all": "vitest run --project=default --project=browser",
+    "test:performance": "tsx test/helpers/run-performance-regression.ts",
+    "test:performance:update": "tsx test/helpers/run-performance-regression.ts --update-baselines",
+    "benchmark": "tsx src/benchmark-all-algorithms.ts",
+    "benchmark:quick": "tsx src/benchmark-all-algorithms.ts --quick",
+    "benchmark:report": "tsx scripts/generate-performance-report.ts",
+    "benchmark:validation": "tsx src/optimized/benchmark-validation.ts",
+    "benchmark:comprehensive": "tsx src/optimized/benchmark-comprehensive.ts",
+    "memory:profile": "tsx test/helpers/memory-profiler.ts",
     "lint": "eslint && tsc --noEmit",
     "lint:fix": "eslint --fix",
     "lint:pkg": "knip",
@@ -88,24 +96,31 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@stylistic/eslint-plugin": "^4.4.1",
-    "@types/node": "^20.19.2",
+    "@types/benchmark": "^2.1.5",
+    "@types/node": "^20.19.9",
     "@vitest/browser": "^3.2.4",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
+    "benchmark": "^2.1.4",
     "cz-conventional-changelog": "^3.3.0",
     "eslint": "^9.29.0",
     "eslint-plugin-simple-import-sort": "^12.1.1",
+    "gh-pages": "^6.3.0",
     "globals": "^15.12.0",
     "happy-dom": "^18.0.1",
     "husky": "^9.1.7",
     "knip": "^5.61.3",
     "playwright": "^1.53.0",
-    "semantic-release": "^24.2.7",
+    "semantic-release": "^25.0.2",
     "ts-node": "^10.9.2",
     "tsx": "^4.20.3",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.34.1",
     "vite": "^7.0.5",
     "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "pupt": "^1.3.2",
+    "typedfastbitset": "^0.6.1"
   }
 }