initial
This commit is contained in:
139
ts/classes/smartfs.directory.ts
Normal file
139
ts/classes/smartfs.directory.ts
Normal file
@@ -0,0 +1,139 @@
|
||||
/**
|
||||
* Directory builder for fluent directory operations
|
||||
*/
|
||||
|
||||
import type { ISmartFsProvider } from '../interfaces/mod.provider.js';
|
||||
import type {
|
||||
TFileMode,
|
||||
IFileStats,
|
||||
IDirectoryEntry,
|
||||
IListOptions,
|
||||
} 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;
|
||||
}
|
||||
}
|
||||
209
ts/classes/smartfs.file.ts
Normal file
209
ts/classes/smartfs.file.ts
Normal file
@@ -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;
|
||||
}
|
||||
}
|
||||
207
ts/classes/smartfs.transaction.ts
Normal file
207
ts/classes/smartfs.transaction.ts
Normal file
@@ -0,0 +1,207 @@
|
||||
/**
|
||||
* Transaction builder for atomic multi-file operations
|
||||
*/
|
||||
|
||||
import type { ISmartFsProvider } from '../interfaces/mod.provider.js';
|
||||
import type { ITransactionOperation, TEncoding } from '../interfaces/mod.types.js';
|
||||
|
||||
/**
|
||||
* Transaction file operation builder
|
||||
* Allows chaining file operations within a transaction
|
||||
*/
|
||||
class TransactionFileBuilder {
|
||||
constructor(
|
||||
private transaction: SmartFsTransaction,
|
||||
private path: string,
|
||||
) {}
|
||||
|
||||
/**
|
||||
* Write content to the file in this transaction
|
||||
* @param content - Content to write
|
||||
* @param encoding - Optional encoding
|
||||
*/
|
||||
public write(content: string | Buffer, encoding?: TEncoding): SmartFsTransaction {
|
||||
this.transaction.addOperation({
|
||||
type: 'write',
|
||||
path: this.path,
|
||||
content,
|
||||
encoding,
|
||||
});
|
||||
return this.transaction;
|
||||
}
|
||||
|
||||
/**
|
||||
* Append content to the file in this transaction
|
||||
* @param content - Content to append
|
||||
* @param encoding - Optional encoding
|
||||
*/
|
||||
public append(content: string | Buffer, encoding?: TEncoding): SmartFsTransaction {
|
||||
this.transaction.addOperation({
|
||||
type: 'append',
|
||||
path: this.path,
|
||||
content,
|
||||
encoding,
|
||||
});
|
||||
return this.transaction;
|
||||
}
|
||||
|
||||
/**
|
||||
* Delete the file in this transaction
|
||||
*/
|
||||
public delete(): SmartFsTransaction {
|
||||
this.transaction.addOperation({
|
||||
type: 'delete',
|
||||
path: this.path,
|
||||
});
|
||||
return this.transaction;
|
||||
}
|
||||
|
||||
/**
|
||||
* Copy the file to a new location in this transaction
|
||||
* @param targetPath - Destination path
|
||||
*/
|
||||
public copy(targetPath: string): SmartFsTransaction {
|
||||
this.transaction.addOperation({
|
||||
type: 'copy',
|
||||
path: this.path,
|
||||
targetPath,
|
||||
});
|
||||
return this.transaction;
|
||||
}
|
||||
|
||||
/**
|
||||
* Move the file to a new location in this transaction
|
||||
* @param targetPath - Destination path
|
||||
*/
|
||||
public move(targetPath: string): SmartFsTransaction {
|
||||
this.transaction.addOperation({
|
||||
type: 'move',
|
||||
path: this.path,
|
||||
targetPath,
|
||||
});
|
||||
return this.transaction;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Transaction builder class for atomic multi-file operations
|
||||
* Build up a set of operations, then commit atomically
|
||||
* Supports rollback on failure
|
||||
*/
|
||||
export class SmartFsTransaction {
|
||||
private provider: ISmartFsProvider;
|
||||
private operations: ITransactionOperation[] = [];
|
||||
private committed = false;
|
||||
private rolledBack = false;
|
||||
|
||||
constructor(provider: ISmartFsProvider) {
|
||||
this.provider = provider;
|
||||
}
|
||||
|
||||
/**
|
||||
* Add a file operation to the transaction
|
||||
* @param path - Path to the file
|
||||
* @returns TransactionFileBuilder for chaining operations
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* await fs.transaction()
|
||||
* .file('/file1.txt').write('content1')
|
||||
* .file('/file2.txt').delete()
|
||||
* .commit()
|
||||
* ```
|
||||
*/
|
||||
public file(path: string): TransactionFileBuilder {
|
||||
const normalizedPath = this.provider.normalizePath(path);
|
||||
return new TransactionFileBuilder(this, normalizedPath);
|
||||
}
|
||||
|
||||
/**
|
||||
* Add an operation to the transaction (internal)
|
||||
*/
|
||||
public addOperation(operation: ITransactionOperation): void {
|
||||
if (this.committed) {
|
||||
throw new Error('Cannot add operations to a committed transaction');
|
||||
}
|
||||
if (this.rolledBack) {
|
||||
throw new Error('Cannot add operations to a rolled back transaction');
|
||||
}
|
||||
this.operations.push(operation);
|
||||
}
|
||||
|
||||
/**
|
||||
* Commit the transaction
|
||||
* All operations are executed atomically
|
||||
* If any operation fails, all operations are rolled back
|
||||
*/
|
||||
public async commit(): Promise<void> {
|
||||
if (this.committed) {
|
||||
throw new Error('Transaction already committed');
|
||||
}
|
||||
if (this.rolledBack) {
|
||||
throw new Error('Cannot commit a rolled back transaction');
|
||||
}
|
||||
|
||||
if (this.operations.length === 0) {
|
||||
this.committed = true;
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
// Prepare transaction (create backups for rollback)
|
||||
const preparedOperations = await this.provider.prepareTransaction(this.operations);
|
||||
this.operations = preparedOperations;
|
||||
|
||||
// Execute the transaction
|
||||
await this.provider.executeTransaction(this.operations);
|
||||
|
||||
this.committed = true;
|
||||
} catch (error) {
|
||||
// Rollback on error
|
||||
await this.rollback();
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Rollback the transaction
|
||||
* Reverts all operations that have been executed
|
||||
*/
|
||||
public async rollback(): Promise<void> {
|
||||
if (this.committed) {
|
||||
throw new Error('Cannot rollback a committed transaction');
|
||||
}
|
||||
if (this.rolledBack) {
|
||||
throw new Error('Transaction already rolled back');
|
||||
}
|
||||
|
||||
if (this.operations.length === 0) {
|
||||
this.rolledBack = true;
|
||||
return;
|
||||
}
|
||||
|
||||
await this.provider.rollbackTransaction(this.operations);
|
||||
this.rolledBack = true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all operations in the transaction
|
||||
*/
|
||||
public getOperations(): readonly ITransactionOperation[] {
|
||||
return this.operations;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if the transaction has been committed
|
||||
*/
|
||||
public isCommitted(): boolean {
|
||||
return this.committed;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if the transaction has been rolled back
|
||||
*/
|
||||
public isRolledBack(): boolean {
|
||||
return this.rolledBack;
|
||||
}
|
||||
}
|
||||
108
ts/classes/smartfs.ts
Normal file
108
ts/classes/smartfs.ts
Normal file
@@ -0,0 +1,108 @@
|
||||
/**
|
||||
* SmartFS - Modern pluggable filesystem module
|
||||
* Main entry point for filesystem operations
|
||||
*/
|
||||
|
||||
import type { ISmartFsProvider } from '../interfaces/mod.provider.js';
|
||||
import { SmartFsFile } from './smartfs.file.js';
|
||||
import { SmartFsDirectory } from './smartfs.directory.js';
|
||||
import { SmartFsTransaction } from './smartfs.transaction.js';
|
||||
import { SmartFsWatcher } from './smartfs.watcher.js';
|
||||
|
||||
/**
|
||||
* SmartFS main class
|
||||
* Creates builder instances for fluent filesystem operations
|
||||
*/
|
||||
export class SmartFs {
|
||||
/**
|
||||
* The filesystem provider
|
||||
*/
|
||||
public provider: ISmartFsProvider;
|
||||
|
||||
/**
|
||||
* Create a new SmartFS instance with a provider
|
||||
* @param provider - Filesystem provider to use
|
||||
*/
|
||||
constructor(provider: ISmartFsProvider) {
|
||||
this.provider = provider;
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a file builder for fluent file operations
|
||||
* @param path - Path to the file
|
||||
* @returns FileBuilder instance
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const content = await fs.file('/path/to/file.txt')
|
||||
* .encoding('utf8')
|
||||
* .read()
|
||||
* ```
|
||||
*/
|
||||
public file(path: string): SmartFsFile {
|
||||
return new SmartFsFile(this.provider, path);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a directory builder for fluent directory operations
|
||||
* @param path - Path to the directory
|
||||
* @returns DirectoryBuilder instance
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const files = await fs.directory('/path')
|
||||
* .recursive()
|
||||
* .list()
|
||||
* ```
|
||||
*/
|
||||
public directory(path: string): SmartFsDirectory {
|
||||
return new SmartFsDirectory(this.provider, path);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a transaction builder for atomic multi-file operations
|
||||
* @returns TransactionBuilder instance
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* await fs.transaction()
|
||||
* .file('/file1.txt').write('content1')
|
||||
* .file('/file2.txt').delete()
|
||||
* .commit()
|
||||
* ```
|
||||
*/
|
||||
public transaction(): SmartFsTransaction {
|
||||
return new SmartFsTransaction(this.provider);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a watcher builder for file system watching
|
||||
* @param path - Path to watch
|
||||
* @returns WatcherBuilder instance
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const watcher = await fs.watch('/path')
|
||||
* .recursive()
|
||||
* .onChange(event => console.log(event))
|
||||
* .start()
|
||||
* ```
|
||||
*/
|
||||
public watch(path: string): SmartFsWatcher {
|
||||
return new SmartFsWatcher(this.provider, path);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get provider capabilities
|
||||
*/
|
||||
public getCapabilities() {
|
||||
return this.provider.capabilities;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get provider name
|
||||
*/
|
||||
public getProviderName(): string {
|
||||
return this.provider.name;
|
||||
}
|
||||
}
|
||||
229
ts/classes/smartfs.watcher.ts
Normal file
229
ts/classes/smartfs.watcher.ts
Normal file
@@ -0,0 +1,229 @@
|
||||
/**
|
||||
* Watcher builder for file system watching
|
||||
*/
|
||||
|
||||
import type { ISmartFsProvider, IWatcherHandle } from '../interfaces/mod.provider.js';
|
||||
import type { IWatchEvent, IWatchOptions, TWatchEventType } from '../interfaces/mod.types.js';
|
||||
|
||||
/**
|
||||
* Event handler type
|
||||
*/
|
||||
type TEventHandler = (event: IWatchEvent) => void | Promise<void>;
|
||||
|
||||
/**
|
||||
* Active watcher handle that allows stopping the watcher
|
||||
*/
|
||||
export class SmartFsActiveWatcher {
|
||||
constructor(private handle: IWatcherHandle) {}
|
||||
|
||||
/**
|
||||
* Stop watching for file system changes
|
||||
*/
|
||||
public async stop(): Promise<void> {
|
||||
return this.handle.stop();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Watcher builder class for file system watching
|
||||
* Configuration methods return `this` for chaining
|
||||
* Call `.start()` to begin watching
|
||||
*/
|
||||
export class SmartFsWatcher {
|
||||
private provider: ISmartFsProvider;
|
||||
private path: string;
|
||||
|
||||
// Configuration options
|
||||
private options: {
|
||||
recursive?: boolean;
|
||||
filter?: string | RegExp | ((path: string) => boolean);
|
||||
debounce?: number;
|
||||
} = {};
|
||||
|
||||
// Event handlers
|
||||
private handlers: {
|
||||
change?: TEventHandler[];
|
||||
add?: TEventHandler[];
|
||||
delete?: TEventHandler[];
|
||||
all?: TEventHandler[];
|
||||
} = {};
|
||||
|
||||
// Debounce state
|
||||
private debounceTimers: Map<string, NodeJS.Timeout> = new Map();
|
||||
|
||||
constructor(provider: ISmartFsProvider, path: string) {
|
||||
this.provider = provider;
|
||||
this.path = this.provider.normalizePath(path);
|
||||
|
||||
if (!this.provider.capabilities.supportsWatch) {
|
||||
throw new Error(`Provider '${this.provider.name}' does not support file watching`);
|
||||
}
|
||||
}
|
||||
|
||||
// --- Configuration Methods (return this for chaining) ---
|
||||
|
||||
/**
|
||||
* Enable recursive watching (watch subdirectories)
|
||||
*/
|
||||
public recursive(): this {
|
||||
this.options.recursive = true;
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Filter watched paths
|
||||
* @param filter - String pattern, RegExp, or filter function
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // String pattern (glob-like)
|
||||
* .filter('*.ts')
|
||||
*
|
||||
* // RegExp
|
||||
* .filter(/\.ts$/)
|
||||
*
|
||||
* // Function
|
||||
* .filter(path => path.endsWith('.ts'))
|
||||
* ```
|
||||
*/
|
||||
public filter(filter: string | RegExp | ((path: string) => boolean)): this {
|
||||
this.options.filter = filter;
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Debounce events (wait N milliseconds before firing)
|
||||
* Useful for avoiding rapid-fire events
|
||||
* @param ms - Debounce delay in milliseconds
|
||||
*/
|
||||
public debounce(ms: number): this {
|
||||
this.options.debounce = ms;
|
||||
return this;
|
||||
}
|
||||
|
||||
// --- Event Handler Registration (return this for chaining) ---
|
||||
|
||||
/**
|
||||
* Register handler for 'change' events (file modified)
|
||||
* @param handler - Event handler function
|
||||
*/
|
||||
public onChange(handler: TEventHandler): this {
|
||||
if (!this.handlers.change) {
|
||||
this.handlers.change = [];
|
||||
}
|
||||
this.handlers.change.push(handler);
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Register handler for 'add' events (file created)
|
||||
* @param handler - Event handler function
|
||||
*/
|
||||
public onAdd(handler: TEventHandler): this {
|
||||
if (!this.handlers.add) {
|
||||
this.handlers.add = [];
|
||||
}
|
||||
this.handlers.add.push(handler);
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Register handler for 'delete' events (file deleted)
|
||||
* @param handler - Event handler function
|
||||
*/
|
||||
public onDelete(handler: TEventHandler): this {
|
||||
if (!this.handlers.delete) {
|
||||
this.handlers.delete = [];
|
||||
}
|
||||
this.handlers.delete.push(handler);
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Register handler for all events
|
||||
* @param handler - Event handler function
|
||||
*/
|
||||
public onAll(handler: TEventHandler): this {
|
||||
if (!this.handlers.all) {
|
||||
this.handlers.all = [];
|
||||
}
|
||||
this.handlers.all.push(handler);
|
||||
return this;
|
||||
}
|
||||
|
||||
// --- Action Method ---
|
||||
|
||||
/**
|
||||
* Start watching for file system changes
|
||||
* @returns Active watcher handle that can be stopped
|
||||
*/
|
||||
public async start(): Promise<SmartFsActiveWatcher> {
|
||||
const watchOptions: IWatchOptions = {
|
||||
recursive: this.options.recursive,
|
||||
filter: this.options.filter,
|
||||
debounce: this.options.debounce,
|
||||
};
|
||||
|
||||
// Create the callback that dispatches to handlers
|
||||
const callback = async (event: IWatchEvent) => {
|
||||
await this.handleEvent(event);
|
||||
};
|
||||
|
||||
const handle = await this.provider.watch(this.path, callback, watchOptions);
|
||||
return new SmartFsActiveWatcher(handle);
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle incoming watch events (internal)
|
||||
*/
|
||||
private async handleEvent(event: IWatchEvent): Promise<void> {
|
||||
// Apply debouncing if configured
|
||||
if (this.options.debounce && this.options.debounce > 0) {
|
||||
const key = `${event.type}:${event.path}`;
|
||||
|
||||
// Clear existing timer
|
||||
const existingTimer = this.debounceTimers.get(key);
|
||||
if (existingTimer) {
|
||||
clearTimeout(existingTimer);
|
||||
}
|
||||
|
||||
// Set new timer
|
||||
const timer = setTimeout(async () => {
|
||||
this.debounceTimers.delete(key);
|
||||
await this.dispatchEvent(event);
|
||||
}, this.options.debounce);
|
||||
|
||||
this.debounceTimers.set(key, timer);
|
||||
} else {
|
||||
// No debouncing, dispatch immediately
|
||||
await this.dispatchEvent(event);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Dispatch event to registered handlers (internal)
|
||||
*/
|
||||
private async dispatchEvent(event: IWatchEvent): Promise<void> {
|
||||
// Dispatch to type-specific handlers
|
||||
const typeHandlers = this.handlers[event.type];
|
||||
if (typeHandlers) {
|
||||
for (const handler of typeHandlers) {
|
||||
await handler(event);
|
||||
}
|
||||
}
|
||||
|
||||
// Dispatch to 'all' handlers
|
||||
if (this.handlers.all) {
|
||||
for (const handler of this.handlers.all) {
|
||||
await handler(event);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the watched path
|
||||
*/
|
||||
public getPath(): string {
|
||||
return this.path;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user