smartfs/ts/interfaces/mod.types.ts

/**
 * Core type definitions for SmartFS
 */

/**
 * File encoding types
 */
export type TEncoding = 'utf8' | 'utf-8' | 'ascii' | 'base64' | 'hex' | 'binary' | 'buffer';

/**
 * File mode (permissions)
 */
export type TFileMode = number;

/**
 * File statistics interface
 */
export interface IFileStats {
  /**
   * File size in bytes
   */
  size: number;

  /**
   * Creation time
   */
  birthtime: Date;

  /**
   * Last modification time
   */
  mtime: Date;

  /**
   * Last access time
   */
  atime: Date;

  /**
   * Is this a file?
   */
  isFile: boolean;

  /**
   * Is this a directory?
   */
  isDirectory: boolean;

  /**
   * Is this a symbolic link?
   */
  isSymbolicLink: boolean;

  /**
   * File permissions/mode
   */
  mode: number;
}

/**
 * Directory entry interface
 */
export interface IDirectoryEntry {
  /**
   * Entry name (filename or directory name)
   */
  name: string;

  /**
   * Full path to the entry
   */
  path: string;

  /**
   * Is this entry a file?
   */
  isFile: boolean;

  /**
   * Is this entry a directory?
   */
  isDirectory: boolean;

  /**
   * Is this entry a symbolic link?
   */
  isSymbolicLink: boolean;

  /**
   * File statistics
   */
  stats?: IFileStats;
}

/**
 * Watch event types
 */
export type TWatchEventType = 'add' | 'change' | 'delete';

/**
 * Watch event interface
 */
export interface IWatchEvent {
  /**
   * Event type
   */
  type: TWatchEventType;

  /**
   * Path that triggered the event
   */
  path: string;

  /**
   * Timestamp of the event
   */
  timestamp: Date;

  /**
   * File statistics (if available)
   */
  stats?: IFileStats;
}

/**
 * Transaction operation types
 */
export type TTransactionOperationType = 'write' | 'delete' | 'copy' | 'move' | 'append';

/**
 * Transaction operation interface
 */
export interface ITransactionOperation {
  /**
   * Operation type
   */
  type: TTransactionOperationType;

  /**
   * Source path
   */
  path: string;

  /**
   * Target path (for copy/move operations)
   */
  targetPath?: string;

  /**
   * Content to write (for write/append operations)
   */
  content?: string | Buffer;

  /**
   * Encoding (for write/append operations)
   */
  encoding?: TEncoding;

  /**
   * Backup data for rollback
   */
  backup?: {
    existed: boolean;
    content?: Buffer;
    stats?: IFileStats;
  };
}

/**
 * Read options interface
 */
export interface IReadOptions {
  encoding?: TEncoding;
}

/**
 * Write options interface
 */
export interface IWriteOptions {
  encoding?: TEncoding;
  mode?: TFileMode;
  atomic?: boolean;
}

/**
 * Stream options interface
 */
export interface IStreamOptions {
  chunkSize?: number;
  highWaterMark?: number;
}

/**
 * Copy/Move options interface
 */
export interface ICopyOptions {
  preserveTimestamps?: boolean;
  overwrite?: boolean;
}

/**
 * List options interface
 */
export interface IListOptions {
  recursive?: boolean;
  filter?: string | RegExp | ((entry: IDirectoryEntry) => boolean);
  includeStats?: boolean;
}

/**
 * Watch options interface
 */
export interface IWatchOptions {
  recursive?: boolean;
  filter?: string | RegExp | ((path: string) => boolean);
  debounce?: number;
}