graphwise 1.6.0 → 1.7.0

package/dist/expansion/base-core.d.ts

@@ -0,0 +1,24 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { GraphOp, GraphOpResponse } from '../async/protocol';
+import { Seed, ExpansionResult, ExpansionConfig } from './types';
+/**
+ * Generator core of the BASE expansion algorithm.
+ *
+ * Yields GraphOp objects to request graph data, allowing the caller to
+ * provide a sync or async runner. The optional `graphRef` parameter is
+ * required when the priority function accesses `context.graph` — it is
+ * populated in sync mode by `base()`. In async mode (Phase 4+), a proxy
+ * graph may be supplied instead.
+ *
+ * @param graphMeta - Immutable graph metadata (directed, nodeCount, edgeCount)
+ * @param seeds - Seed nodes for expansion
+ * @param config - Expansion configuration (priority, limits, debug)
+ * @param graphRef - Optional real graph reference for context.graph in priority functions
+ * @returns An ExpansionResult with all discovered paths and statistics
+ */
+export declare function baseCore<N extends NodeData, E extends EdgeData>(graphMeta: {
+    readonly directed: boolean;
+    readonly nodeCount: number;
+    readonly edgeCount: number;
+}, seeds: readonly Seed[], config?: ExpansionConfig<N, E>, graphRef?: ReadableGraph<N, E>): Generator<GraphOp, ExpansionResult, GraphOpResponse<N, E>>;
+//# sourceMappingURL=base-core.d.ts.map

package/dist/expansion/base-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-core.d.ts","sourceRoot":"","sources":["../../src/expansion/base-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAU,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE1E,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAElE,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EAGf,eAAe,EAEf,MAAM,SAAS,CAAC;AAqBjB;;;;;;;;;;;;;;GAcG;AACH,wBAAiB,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC/D,SAAS,EAAE;IACV,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B,EACD,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAC9B,QAAQ,CAAC,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CA6O5D"}

package/dist/expansion/base-core.unit.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Unit tests for the baseCore generator and baseAsync() entry point.
+ *
+ * Verifies that:
+ * - baseCore driven via runSync produces identical results to base()
+ * - baseAsync() produces identical results to base() on the standard fixtures
+ * - AbortSignal cancellation works in baseAsync()
+ */
+export {};
+//# sourceMappingURL=base-core.unit.test.d.ts.map

package/dist/expansion/base-core.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-core.unit.test.d.ts","sourceRoot":"","sources":["../../src/expansion/base-core.unit.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/expansion/base-helpers.d.ts

@@ -0,0 +1,57 @@
+import { NodeId } from '../graph';
+import { Seed, ExpansionPath, ExpansionResult, ExpansionStats } from './types';
+/**
+ * Internal queue entry for frontier expansion.
+ */
+export interface QueueEntry {
+    nodeId: NodeId;
+    frontierIndex: number;
+    predecessor: NodeId | null;
+}
+/**
+ * Limits structure used by continueExpansion.
+ */
+export interface ExpansionLimits {
+    readonly maxIterations: number;
+    readonly maxNodes: number;
+    readonly maxPaths: number;
+}
+/**
+ * Check whether expansion should continue given current progress.
+ *
+ * Returns shouldContinue=false as soon as any configured limit is reached,
+ * along with the appropriate termination reason.
+ *
+ * @param iterations - Number of iterations completed so far
+ * @param nodesVisited - Number of distinct nodes visited so far
+ * @param pathsFound - Number of paths discovered so far
+ * @param limits - Configured expansion limits (0 = unlimited)
+ * @returns Whether to continue and the termination reason if stopping
+ */
+export declare function continueExpansion(iterations: number, nodesVisited: number, pathsFound: number, limits: ExpansionLimits): {
+    shouldContinue: boolean;
+    termination: ExpansionStats["termination"];
+};
+/**
+ * Reconstruct path from collision point.
+ *
+ * Traces backwards through the predecessor maps of both frontiers from the
+ * collision node, then concatenates the two halves to form the full path.
+ *
+ * @param collisionNode - The node where the two frontiers met
+ * @param frontierA - Index of the first frontier
+ * @param frontierB - Index of the second frontier
+ * @param predecessors - Predecessor maps, one per frontier
+ * @param seeds - Seed nodes, one per frontier
+ * @returns The reconstructed path, or null if seeds are missing
+ */
+export declare function reconstructPath(collisionNode: NodeId, frontierA: number, frontierB: number, predecessors: readonly Map<NodeId, NodeId | null>[], seeds: readonly Seed[]): ExpansionPath | null;
+/**
+ * Create an empty expansion result for early termination (e.g. no seeds given).
+ *
+ * @param algorithm - Name of the algorithm producing this result
+ * @param startTime - performance.now() timestamp taken before the algorithm began
+ * @returns An ExpansionResult with zero paths and zero stats
+ */
+export declare function emptyResult(algorithm: string, startTime: number): ExpansionResult;
+//# sourceMappingURL=base-helpers.d.ts.map

package/dist/expansion/base-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-helpers.d.ts","sourceRoot":"","sources":["../../src/expansion/base-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EACX,IAAI,EACJ,aAAa,EACb,eAAe,EACf,cAAc,EACd,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAChC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,eAAe,GACrB;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,cAAc,CAAC,aAAa,CAAC,CAAA;CAAE,CAWzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC9B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,EAAE,EACnD,KAAK,EAAE,SAAS,IAAI,EAAE,GACpB,aAAa,GAAG,IAAI,CAuCtB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAC1B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GACf,eAAe,CAgBjB"}

package/dist/expansion/base.d.ts

@@ -1,7 +1,20 @@
 import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { AsyncReadableGraph } from '../graph/async-interfaces';
+import { AsyncRunnerOptions } from '../async/types';
 import { Seed, ExpansionResult, ExpansionConfig } from './types';
 /**
- * Run BASE expansion algorithm.
+ * Configuration for the async BASE expansion algorithm.
+ *
+ * Extends ExpansionConfig with async runner options (cancellation, progress,
+ * yield strategy).
+ */
+export interface AsyncExpansionConfig<N extends NodeData = NodeData, E extends EdgeData = EdgeData> extends ExpansionConfig<N, E>, AsyncRunnerOptions {
+}
+/**
+ * Run BASE expansion synchronously.
+ *
+ * Delegates to baseCore + runSync. Behaviour is identical to the previous
+ * direct implementation — all existing callers are unaffected.
  *
  * @param graph - Source graph
  * @param seeds - Seed nodes for expansion
@@ -9,4 +22,22 @@ import { Seed, ExpansionResult, ExpansionConfig } from './types';
  * @returns Expansion result with discovered paths
  */
 export declare function base<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: ExpansionConfig<N, E>): ExpansionResult;
+/**
+ * Run BASE expansion asynchronously.
+ *
+ * Delegates to baseCore + runAsync. Supports:
+ * - Cancellation via AbortSignal (config.signal)
+ * - Progress callbacks (config.onProgress)
+ * - Custom cooperative yield strategies (config.yieldStrategy)
+ *
+ * Note: priority functions that access `context.graph` are not supported in
+ * async mode without a graph proxy (Phase 4b). The default degree-based
+ * priority (DOME) does not access context.graph and works correctly.
+ *
+ * @param graph - Async source graph
+ * @param seeds - Seed nodes for expansion
+ * @param config - Expansion and async runner configuration
+ * @returns Promise resolving to the expansion result
+ */
+export declare function baseAsync<N extends NodeData, E extends EdgeData>(graph: AsyncReadableGraph<N, E>, seeds: readonly Seed[], config?: AsyncExpansionConfig<N, E>): Promise<ExpansionResult>;
 //# sourceMappingURL=base.d.ts.map

package/dist/expansion/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/expansion/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAU,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EAGf,eAAe,EAEf,MAAM,SAAS,CAAC;AAqBjB;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAwOjB"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/expansion/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,OAAO,KAAK,EAAE,kBAAkB,EAAiB,MAAM,gBAAgB,CAAC;AAGxE,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB,CACpC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,CAE7B,SAAQ,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,kBAAkB;CAAG;AAErD;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAYjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EACrE,KAAK,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,EAC/B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GACjC,OAAO,CAAC,eAAe,CAAC,CA8B1B"}