@tscircuit/capacity-autorouter 0.0.62 → 0.0.63

package/dist/index.d.ts

@@ -1247,6 +1247,8 @@ interface CacheProvider {
     isSyncCache: boolean;
     cacheHits: number;
     cacheMisses: number;
+    cacheHitsByPrefix: Record<string, number>;
+    cacheMissesByPrefix: Record<string, number>;
     getCachedSolutionSync(cacheKey: string): any;
     getCachedSolution(cacheKey: string): Promise<any>;
     setCachedSolutionSync(cacheKey: string, cachedSolution: any): void;
@@ -1254,6 +1256,29 @@ interface CacheProvider {
     getAllCacheKeys(): string[];
     clearCache(): void;
 }
+interface CachableSolver<CacheToSolveSpaceTransform = any, CachedSolution = any> {
+    cacheHit: boolean;
+    hasAttemptedToUseCache: boolean;
+    cacheProvider: CacheProvider | null;
+    cacheKey?: string;
+    cacheToSolveSpaceTransform?: CacheToSolveSpaceTransform;
+    /**
+     * Processes solver inputs and constructs a cacheKey and a cacheToSolveSpaceTransform
+     * which gives the necessary information to convert a cached solution into a valid
+     * solution for this solver. For example, the cacheKey may be translation-invariant, so
+     * any cachedSolution would not be translated properly for this solver. The cacheToSolveSpaceTransform
+     * tells you how to convert from the cache space (translation-invarant) to the correct
+     * space for this solver. It can also contain information about how cache ids map to
+     * ids for the solver
+     **/
+    computeCacheKeyAndTransform(): {
+        cacheKey: string;
+        cacheToSolveSpaceTransform: CacheToSolveSpaceTransform;
+    };
+    applyCachedSolution(cachedSolution: CachedSolution): void;
+    attemptToUseCacheSync(): boolean;
+    saveToCacheSync(): void;
+}
 
 declare class UnravelMultiSectionSolver extends BaseSolver {
     nodeMap: Map<CapacityMeshNodeId, CapacityMeshNode>;
@@ -1416,6 +1441,7 @@ interface CapacityPathingSingleSectionPathingSolverParams {
     }>;
     colorMap?: Record<string, string>;
     centerNodeId: string;
+    nodeMap?: Map<CapacityMeshNodeId, CapacityMeshNode>;
     nodeEdgeMap?: Map<CapacityMeshNodeId, CapacityMeshEdge[]>;
     hyperParameters?: CpssPathingSolverHyperParameters;
 }
@@ -1433,7 +1459,9 @@ declare class CapacityPathingSingleSectionSolver extends BaseSolver {
     nodeEdgeMap: Map<CapacityMeshNodeId, CapacityMeshEdge[]>;
     colorMap: Record<string, string>;
     usedNodeCapacityMap: Map<CapacityMeshNodeId, number>;
+    totalNodeCapacityMap: Map<CapacityMeshNodeId, number>;
     centerNodeId: string;
+    private currentSectionScore;
     MAX_CANDIDATES_IN_MEMORY: number;
     currentConnectionIndex: number;
     candidates?: Array<Candidate> | null;
@@ -1458,6 +1486,7 @@ declare class CapacityPathingSingleSectionSolver extends BaseSolver {
     isConnectedToEndGoal(node: CapacityMeshNode, endGoal: CapacityMeshNode): boolean;
     doesNodeHaveCapacityForTrace(node: CapacityMeshNode, prevNode: CapacityMeshNode | null): boolean;
     reduceCapacityAlongPath(path: CapacityMeshNode[]): void;
+    getSolvedSectionScore(): number;
     _step(): void;
     computeProgress(): number;
     private _setupAStar;
@@ -1516,8 +1545,10 @@ declare class CapacityPathingMultiSectionSolver extends BaseSolver {
     connectionsWithNodes: Array<ConnectionPathWithNodes>;
     colorMap: Record<string, string>;
     initialSolver: CapacityPathingGreedySolver;
+    cacheProvider?: CacheProvider | null;
     stage: "initialization" | "section-optimization";
     nodeMap: Map<CapacityMeshNodeId, CapacityMeshNode>;
+    allNodeIdsSet: Set<CapacityMeshNodeId>;
     usedNodeCapacityMap: Map<CapacityMeshNodeId, number>;
     totalNodeCapacityMap: Map<CapacityMeshNodeId, number>;
     nodeCapacityPercentMap: Map<CapacityMeshNodeId, number>;
@@ -1529,6 +1560,7 @@ declare class CapacityPathingMultiSectionSolver extends BaseSolver {
         successfulOptimizations: number;
         failedOptimizations: number;
         failedSectionSolvers: number;
+        startingScore: number;
         scheduleScores: Array<{
             maxExpansionDegrees: number;
             sectionAttempts: number;
@@ -1548,6 +1580,7 @@ declare class CapacityPathingMultiSectionSolver extends BaseSolver {
     };
     constructor(params: ConstructorParameters<typeof CapacityPathingSolver>[0] & {
         initialPathingSolver?: CapacityPathingGreedySolver;
+        cacheProvider?: CacheProvider | null;
     });
     _stepInitialization(): void;
     _getNextNodeToOptimize(): CapacityMeshNodeId | null;
@@ -1893,4 +1926,105 @@ declare const getTunedTotalCapacity1: (nodeOrWidth: CapacityMeshNode | {
  */
 declare const calculateOptimalCapacityDepth: (initialWidth: number, targetMinCapacity?: number, maxDepth?: number) => number;
 
-export { CapacityMeshSolver, calculateOptimalCapacityDepth, getTunedTotalCapacity1 };
+/**
+ * An in-memory implementation of the CacheProvider interface.
+ * Useful for testing or scenarios where persistence is not required.
+ */
+declare class InMemoryCache implements CacheProvider {
+    cacheHitsByPrefix: Record<string, number>;
+    cacheMissesByPrefix: Record<string, number>;
+    isSyncCache: boolean;
+    cacheHits: number;
+    cacheMisses: number;
+    cache: Map<string, any>;
+    /**
+     * Retrieves a cached solution synchronously based on the cache key.
+     * Increments cache hit/miss counters.
+     * @param cacheKey The key to look up in the cache.
+     * @returns The cached solution if found, otherwise undefined.
+     */
+    getCachedSolutionSync(cacheKey: string): any;
+    /**
+     * Retrieves a cached solution asynchronously. Wraps the synchronous method.
+     * @param cacheKey The key to look up in the cache.
+     * @returns A promise that resolves with the cached solution or undefined.
+     */
+    getCachedSolution(cacheKey: string): Promise<any>;
+    /**
+     * Stores a solution in the cache synchronously.
+     * Uses structured cloning to store a copy, preventing external modifications.
+     * @param cacheKey The key under which to store the solution.
+     * @param cachedSolution The solution data to cache.
+     */
+    setCachedSolutionSync(cacheKey: string, cachedSolution: any): void;
+    /**
+     * Stores a solution in the cache asynchronously. Wraps the synchronous method.
+     * @param cacheKey The key under which to store the solution.
+     * @param cachedSolution The solution data to cache.
+     * @returns A promise that resolves when the solution is cached.
+     */
+    setCachedSolution(cacheKey: string, cachedSolution: any): Promise<void>;
+    /**
+     * Clears the entire cache and resets hit/miss counters.
+     */
+    clearCache(): void;
+    getAllCacheKeys(): string[];
+}
+
+/**
+ * A CacheProvider implementation using the browser's localStorage.
+ * Note: localStorage has size limits (typically 5-10MB) and stores data as strings.
+ * Complex objects will be JSON serialized/deserialized.
+ */
+declare class LocalStorageCache implements CacheProvider {
+    isSyncCache: boolean;
+    cacheHits: number;
+    cacheMisses: number;
+    cacheHitsByPrefix: Record<string, number>;
+    cacheMissesByPrefix: Record<string, number>;
+    constructor();
+    private getKey;
+    /**
+     * Retrieves a cached solution synchronously from localStorage.
+     * Increments cache hit/miss counters.
+     * @param cacheKey The key to look up in the cache.
+     * @returns The cached solution if found and parsed correctly, otherwise undefined.
+     */
+    getCachedSolutionSync(cacheKey: string): any;
+    /**
+     * Retrieves a cached solution asynchronously. Wraps the synchronous method.
+     * @param cacheKey The key to look up in the cache.
+     * @returns A promise that resolves with the cached solution or undefined.
+     */
+    getCachedSolution(cacheKey: string): Promise<any>;
+    /**
+     * Stores a solution in localStorage synchronously.
+     * The solution is JSON stringified before storing.
+     * @param cacheKey The key under which to store the solution.
+     * @param cachedSolution The solution data to cache.
+     */
+    setCachedSolutionSync(cacheKey: string, cachedSolution: any): void;
+    /**
+     * Stores a solution in the cache asynchronously. Wraps the synchronous method.
+     * @param cacheKey The key under which to store the solution.
+     * @param cachedSolution The solution data to cache.
+     * @returns A promise that resolves when the solution is cached.
+     */
+    setCachedSolution(cacheKey: string, cachedSolution: any): Promise<void>;
+    /**
+     * Clears all cache entries created by this instance from localStorage
+     * and resets hit/miss counters.
+     */
+    clearCache(): void;
+    getAllCacheKeys(): string[];
+}
+
+declare global {
+    var TSCIRCUIT_AUTOROUTER_LOCAL_STORAGE_CACHE: LocalStorageCache;
+    var TSCIRCUIT_AUTOROUTER_IN_MEMORY_CACHE: InMemoryCache;
+}
+declare function getGlobalLocalStorageCache(): LocalStorageCache;
+declare function getGlobalInMemoryCache(): InMemoryCache;
+declare function setupGlobalCaches(): void;
+
+export { type CachableSolver, type CacheProvider, CapacityMeshSolver, InMemoryCache, LocalStorageCache, calculateOptimalCapacityDepth, getGlobalInMemoryCache, getGlobalLocalStorageCache, getTunedTotalCapacity1, setupGlobalCaches };