@fnndsc/salsa 4.5.2 → 4.5.4

package/dist/files/pathMapper.d.ts

@@ -0,0 +1,237 @@
+/**
+ * @file Singleton path mapper for logical-to-physical ChRIS path resolution.
+ *
+ * Maintains a cached mapping of logical paths to physical locations,
+ * enabling incremental resolution by reusing cached path prefixes.
+ *
+ * Example:
+ *   - First call: '/home/user/public/feed_4' → Full resolution, cache prefix
+ *   - Second call: '/home/user/public/feed_5' → Reuse '/home/user/public', resolve only 'feed_5'
+ *
+ * This eliminates redundant tree walking and API calls for paths with common prefixes.
+ *
+ * It is CUBE's own mechanics (a `.chrislink` is a file CUBE lists among a
+ * folder's links), so it lives with the file reads. The kernel asks it
+ * through one door: the ChRIS backend's link walk, which brasa's
+ * `storePath_resolve` calls for every file command.
+ *
+ * @module
+ */
+import { Result } from '@fnndsc/cumin';
+/**
+ * Statistics for cache performance monitoring.
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    size: number;
+    hitRate: number;
+}
+/**
+ * Singleton PathMapper class for logical-to-physical path resolution.
+ *
+ * Maintains hierarchical cache of path mappings to minimize repeated
+ * link resolution operations.
+ *
+ * @example
+ * ```typescript
+ * const mapper = PathMapper.instance_get();
+ *
+ * // First resolution
+ * const result1 = await mapper.logicalPath_resolve('/home/user/public/feed_4');
+ * // → Resolves /home/user/public → /SHARED, then feed_4
+ * // → Caches intermediate mappings
+ *
+ * // Second resolution - prefix reuse
+ * const result2 = await mapper.logicalPath_resolve('/home/user/public/feed_5');
+ * // → Reuses cached '/home/user/public' → '/SHARED'
+ * // → Resolves only 'feed_5'
+ * ```
+ */
+export declare class PathMapper {
+    private static instance;
+    private cache;
+    private readonly defaultTTL;
+    private stats;
+    /** Walked paths whose parent could not be asked for links, by the parent. */
+    private blind;
+    /** Parents found blind by resolutions since the last {@link blindParents_take}. */
+    private blindSeen;
+    /**
+     * Private constructor enforces singleton pattern.
+     */
+    private constructor();
+    /**
+     * Gets the singleton PathMapper instance.
+     *
+     * @returns The singleton PathMapper instance.
+     */
+    static instance_get(): PathMapper;
+    /**
+     * Resets the singleton instance (for testing).
+     *
+     * @internal
+     */
+    static instance_reset(): void;
+    /**
+     * Resolves a logical path to its physical location.
+     *
+     * Uses cached path prefixes when available, resolving only the
+     * uncached suffix to minimize API calls.
+     *
+     * @param logicalPath - The logical path to resolve.
+     * @returns Result containing the physical path, or Err on failure.
+     *
+     * @example
+     * ```typescript
+     * const mapper = PathMapper.instance_get();
+     *
+     * // First call: full resolution
+     * const result1 = await mapper.logicalPath_resolve('/home/user/public/feed_4');
+     * // → Resolves /home/user/public → /SHARED, then feed_4
+     * // → Caches: '/home/user/public' → '/SHARED'
+     * // → Caches: '/home/user/public/feed_4' → '/SHARED/feed_4'
+     *
+     * // Second call: prefix reuse
+     * const result2 = await mapper.logicalPath_resolve('/home/user/public/feed_5');
+     * // → Reuses cached '/home/user/public' → '/SHARED'
+     * // → Resolves only 'feed_5'
+     * ```
+     */
+    logicalPath_resolve(logicalPath: string): Promise<Result<string>>;
+    /**
+     * Finds the longest cached prefix of a logical path.
+     *
+     * Walks up the path hierarchy to find the deepest cached mapping,
+     * returning the cached physical prefix and remaining suffix.
+     *
+     * @param logicalPath - The full logical path.
+     * @returns Object with cached prefix and remaining suffix.
+     *
+     * @example
+     * ```typescript
+     * // Cache contains: '/home/user/public' → '/SHARED'
+     * const result = mapper.longestCachedPrefix_find('/home/user/public/feed_4/files');
+     * // Returns:
+     * // {
+     * //   prefixLogical: '/home/user/public',
+     * //   prefixPhysical: '/SHARED',
+     * //   suffix: 'feed_4/files'
+     * // }
+     * ```
+     */
+    private longestCachedPrefix_find;
+    /**
+     * Resolves a path suffix by checking each component for links.
+     *
+     * Walks the suffix path, checking each component to see if it's a link.
+     * Caches intermediate mappings along the way for future prefix reuse.
+     *
+     * @param suffix - The path suffix to resolve (e.g., 'feed_4/files').
+     * @param physicalBase - The physical base path to build upon.
+     * @param logicalBase - The logical base path (for caching intermediate results).
+     * @returns Result containing the resolved physical path.
+     */
+    private suffix_resolve;
+    /**
+     * Checks if a path is a link and returns its target.
+     *
+     * Optimizes resolution by checking ListCache first. If the parent directory
+     * is cached, we can determine if the candidate is a link without an API call.
+     * Falls back to API (fetching all links in parent) if not cached.
+     *
+     * @param candidatePhysical - The physical path to check.
+     * @param candidateLogical - The logical path (used for cache lookup).
+     * @returns The link target if it's a link, null otherwise.
+     */
+    private link_checkAndResolve;
+    /**
+     * Records the parents a resolution of this path walked past without
+     * seeing their links.
+     *
+     * @param logicalPath - The path just resolved.
+     */
+    private blind_note;
+    /**
+     * The parents whose links could not be read by the resolutions since the
+     * last call, emptied by the call. A command whose answer failed reports
+     * them: a link in one of them, had it been seen, would have led elsewhere.
+     *
+     * @returns The parents, in the order first met.
+     */
+    blindParents_take(): string[];
+    /**
+     * Gets a cached mapping if it exists and hasn't expired.
+     *
+     * @param logicalPath - The logical path to look up.
+     * @returns The cached physical path, or null if not cached or expired.
+     */
+    private cache_get;
+    /**
+     * Caches a logical-to-physical path mapping.
+     *
+     * @param logicalPath - The logical path.
+     * @param physicalPath - The corresponding physical path.
+     * @param ttl - Optional TTL in milliseconds (defaults to 30s).
+     */
+    private cache_set;
+    /**
+     * Invalidates all cached mappings with a given logical path prefix.
+     *
+     * Call this when links are created/deleted/modified.
+     *
+     * @param logicalPathPrefix - The logical path prefix to invalidate.
+     *
+     * @example
+     * ```typescript
+     * // Link changed: /home/user/public → /SHARED becomes → /PUBLIC
+     * mapper.cache_invalidate('/home/user/public');
+     * // Invalidates:
+     * //   - /home/user/public
+     * //   - /home/user/public/feed_4
+     * //   - /home/user/public/feed_5
+     * //   - ... etc
+     * ```
+     */
+    cache_invalidate(logicalPathPrefix: string): void;
+    /**
+     * Clears all cached mappings.
+     */
+    cache_clear(): void;
+    /**
+     * Gets cache statistics.
+     *
+     * @returns Cache statistics including hit rate and size.
+     */
+    stats_get(): CacheStats;
+}
+/**
+ * Convenience function to get the singleton PathMapper instance.
+ *
+ * @returns The singleton PathMapper instance.
+ */
+export declare function pathMapper_get(): PathMapper;
+/**
+ * Resolves a logical path to its physical path by following links.
+ *
+ * Delegates to the PathMapper singleton, which uses hierarchical caching to
+ * optimize repeated resolutions with common prefixes.
+ *
+ * @param logicalPath - The logical (apparent) path the user sees/navigates.
+ * @returns A Result containing the physical path, or Err if path is invalid.
+ *
+ * @example
+ * ```ts
+ * await logicalPath_resolve('/home/user/public/data'); // Ok('/PUBLIC/data') where public -> /PUBLIC
+ * ```
+ */
+export declare function logicalPath_resolve(logicalPath: string): Promise<Result<string>>;
+/**
+ * Clears the path mapping cache. Useful when links are created/deleted.
+ *
+ * @example
+ * ```ts
+ * linkCache_clear();
+ * ```
+ */
+export declare function linkCache_clear(): void;