initial

ts/classes/smartfs.file.ts

@@ -0,0 +1,209 @@
+/**
+ * File builder for fluent file operations
+ */
+
+import type { ISmartFsProvider } from '../interfaces/mod.provider.js';
+import type {
+  TEncoding,
+  TFileMode,
+  IFileStats,
+  IReadOptions,
+  IWriteOptions,
+  IStreamOptions,
+  ICopyOptions,
+} from '../interfaces/mod.types.js';
+
+/**
+ * File builder class for fluent file operations
+ * Configuration methods return `this` for chaining
+ * Action methods return Promises for execution
+ */
+export class SmartFsFile {
+  private provider: ISmartFsProvider;
+  private path: string;
+
+  // Configuration options
+  private options: {
+    encoding?: TEncoding;
+    mode?: TFileMode;
+    atomic?: boolean;
+    chunkSize?: number;
+    preserveTimestamps?: boolean;
+    overwrite?: boolean;
+  } = {};
+
+  constructor(provider: ISmartFsProvider, path: string) {
+    this.provider = provider;
+    this.path = this.provider.normalizePath(path);
+  }
+
+  // --- Configuration Methods (return this for chaining) ---
+
+  /**
+   * Set encoding for read/write operations
+   * @param encoding - File encoding
+   */
+  public encoding(encoding: TEncoding): this {
+    this.options.encoding = encoding;
+    return this;
+  }
+
+  /**
+   * Set file permissions/mode
+   * @param mode - File mode (e.g., 0o644)
+   */
+  public mode(mode: TFileMode): this {
+    this.options.mode = mode;
+    return this;
+  }
+
+  /**
+   * Enable atomic write operations
+   * Writes to a temporary file first, then renames
+   */
+  public atomic(): this {
+    this.options.atomic = true;
+    return this;
+  }
+
+  /**
+   * Set chunk size for streaming operations
+   * @param size - Chunk size in bytes
+   */
+  public chunkSize(size: number): this {
+    this.options.chunkSize = size;
+    return this;
+  }
+
+  /**
+   * Preserve timestamps when copying/moving
+   */
+  public preserveTimestamps(): this {
+    this.options.preserveTimestamps = true;
+    return this;
+  }
+
+  /**
+   * Allow overwriting existing files
+   */
+  public overwrite(): this {
+    this.options.overwrite = true;
+    return this;
+  }
+
+  // --- Action Methods (return Promises) ---
+
+  /**
+   * Read the file
+   * @returns File content as Buffer or string (if encoding is set)
+   */
+  public async read(): Promise<Buffer | string> {
+    const readOptions: IReadOptions = {
+      encoding: this.options.encoding,
+    };
+    return this.provider.readFile(this.path, readOptions);
+  }
+
+  /**
+   * Write content to the file
+   * @param content - Content to write
+   */
+  public async write(content: string | Buffer): Promise<void> {
+    const writeOptions: IWriteOptions = {
+      encoding: this.options.encoding,
+      mode: this.options.mode,
+      atomic: this.options.atomic,
+    };
+    return this.provider.writeFile(this.path, content, writeOptions);
+  }
+
+  /**
+   * Append content to the file
+   * @param content - Content to append
+   */
+  public async append(content: string | Buffer): Promise<void> {
+    const writeOptions: IWriteOptions = {
+      encoding: this.options.encoding,
+      mode: this.options.mode,
+    };
+    return this.provider.appendFile(this.path, content, writeOptions);
+  }
+
+  /**
+   * Get a readable stream for the file
+   * @returns ReadableStream of Uint8Array
+   */
+  public async readStream(): Promise<ReadableStream<Uint8Array>> {
+    const streamOptions: IStreamOptions = {
+      chunkSize: this.options.chunkSize,
+    };
+    return this.provider.createReadStream(this.path, streamOptions);
+  }
+
+  /**
+   * Get a writable stream for the file
+   * @returns WritableStream of Uint8Array
+   */
+  public async writeStream(): Promise<WritableStream<Uint8Array>> {
+    const streamOptions: IStreamOptions = {
+      chunkSize: this.options.chunkSize,
+    };
+    return this.provider.createWriteStream(this.path, streamOptions);
+  }
+
+  /**
+   * Copy the file to a new location
+   * @param targetPath - Destination path
+   */
+  public async copy(targetPath: string): Promise<void> {
+    const normalizedTarget = this.provider.normalizePath(targetPath);
+    const copyOptions: ICopyOptions = {
+      preserveTimestamps: this.options.preserveTimestamps,
+      overwrite: this.options.overwrite,
+    };
+    return this.provider.copyFile(this.path, normalizedTarget, copyOptions);
+  }
+
+  /**
+   * Move the file to a new location
+   * @param targetPath - Destination path
+   */
+  public async move(targetPath: string): Promise<void> {
+    const normalizedTarget = this.provider.normalizePath(targetPath);
+    const copyOptions: ICopyOptions = {
+      preserveTimestamps: this.options.preserveTimestamps,
+      overwrite: this.options.overwrite,
+    };
+    return this.provider.moveFile(this.path, normalizedTarget, copyOptions);
+  }
+
+  /**
+   * Delete the file
+   */
+  public async delete(): Promise<void> {
+    return this.provider.deleteFile(this.path);
+  }
+
+  /**
+   * Check if the file exists
+   * @returns True if file exists
+   */
+  public async exists(): Promise<boolean> {
+    return this.provider.fileExists(this.path);
+  }
+
+  /**
+   * Get file statistics
+   * @returns File stats
+   */
+  public async stat(): Promise<IFileStats> {
+    return this.provider.fileStat(this.path);
+  }
+
+  /**
+   * Get the file path
+   */
+  public getPath(): string {
+    return this.path;
+  }
+}