smartfs/ts/classes/smartfs.directory.ts

/**
 * Directory builder for fluent directory operations
 */

import * as crypto from 'crypto';
import type { ISmartFsProvider } from '../interfaces/mod.provider.js';
import type {
  TFileMode,
  IFileStats,
  IDirectoryEntry,
  IListOptions,
  ITreeHashOptions,
} from '../interfaces/mod.types.js';

/**
 * Directory builder class for fluent directory operations
 * Configuration methods return `this` for chaining
 * Action methods return Promises for execution
 */
export class SmartFsDirectory {
  private provider: ISmartFsProvider;
  private path: string;

  // Configuration options
  private options: {
    recursive?: boolean;
    mode?: TFileMode;
    filter?: string | RegExp | ((entry: IDirectoryEntry) => boolean);
    includeStats?: boolean;
  } = {};

  constructor(provider: ISmartFsProvider, path: string) {
    this.provider = provider;
    this.path = this.provider.normalizePath(path);
  }

  // --- Configuration Methods (return this for chaining) ---

  /**
   * Enable recursive operations (for list, create, delete)
   */
  public recursive(): this {
    this.options.recursive = true;
    return this;
  }

  /**
   * Set directory permissions/mode
   * @param mode - Directory mode (e.g., 0o755)
   */
  public mode(mode: TFileMode): this {
    this.options.mode = mode;
    return this;
  }

  /**
   * Filter directory entries
   * @param filter - String pattern, RegExp, or filter function
   *
   * @example
   * ```typescript
   * // String pattern (glob-like)
   * .filter('*.ts')
   *
   * // RegExp
   * .filter(/\.ts$/)
   *
   * // Function
   * .filter(entry => entry.isFile && entry.name.endsWith('.ts'))
   * ```
   */
  public filter(filter: string | RegExp | ((entry: IDirectoryEntry) => boolean)): this {
    this.options.filter = filter;
    return this;
  }

  /**
   * Include file statistics in directory listings
   */
  public includeStats(): this {
    this.options.includeStats = true;
    return this;
  }

  // --- Action Methods (return Promises) ---

  /**
   * List directory contents
   * @returns Array of directory entries
   */
  public async list(): Promise<IDirectoryEntry[]> {
    const listOptions: IListOptions = {
      recursive: this.options.recursive,
      filter: this.options.filter,
      includeStats: this.options.includeStats,
    };
    return this.provider.listDirectory(this.path, listOptions);
  }

  /**
   * Create the directory
   */
  public async create(): Promise<void> {
    return this.provider.createDirectory(this.path, {
      recursive: this.options.recursive,
      mode: this.options.mode,
    });
  }

  /**
   * Delete the directory
   */
  public async delete(): Promise<void> {
    return this.provider.deleteDirectory(this.path, {
      recursive: this.options.recursive,
    });
  }

  /**
   * Check if the directory exists
   * @returns True if directory exists
   */
  public async exists(): Promise<boolean> {
    return this.provider.directoryExists(this.path);
  }

  /**
   * Get directory statistics
   * @returns Directory stats
   */
  public async stat(): Promise<IFileStats> {
    return this.provider.directoryStat(this.path);
  }

  /**
   * Get the directory path
   */
  public getPath(): string {
    return this.path;
  }

  /**
   * Compute a hash of all files in the directory tree
   * Uses configured filter and recursive options
   * @param options - Hash options (algorithm defaults to 'sha256')
   * @returns Hex-encoded hash string
   *
   * @example
   * ```typescript
   * // Hash all files recursively
   * const hash = await fs.directory('/assets').recursive().treeHash();
   *
   * // Hash only TypeScript files
   * const hash = await fs.directory('/src').filter('*.ts').recursive().treeHash();
   *
   * // Use different algorithm
   * const hash = await fs.directory('/data').recursive().treeHash({ algorithm: 'sha512' });
   * ```
   */
  public async treeHash(options?: ITreeHashOptions): Promise<string> {
    const { algorithm = 'sha256' } = options ?? {};
    const hash = crypto.createHash(algorithm);

    // Get all entries using existing filter/recursive configuration
    const entries = await this.list();

    // Filter to files only and sort by path for deterministic ordering
    const files = entries
      .filter((entry) => entry.isFile)
      .sort((a, b) => a.path.localeCompare(b.path));

    // Hash each file's relative path and contents
    for (const file of files) {
      // Compute relative path from directory root
      const relativePath = file.path.slice(this.path.length + 1);

      // Hash the relative path (with null separator)
      hash.update(relativePath + '\0');

      // Stream file contents and update hash incrementally
      const stream = await this.provider.createReadStream(file.path);
      const reader = stream.getReader();
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        hash.update(value);
      }
    }

    return hash.digest('hex');
  }
}