Managing Folders in Kawkab

Folder is a specialized class in the Kawkab framework that allows you to efficiently manage folders. In this guide, we will explore how to use all available operations on folders.

Importing

Before using any of the operations, you must import the class:

import { folder } from 'kawkab';

Available Operations on Folders

1. Check if Folder Exists (exists)

Check if a folder exists before performing any operation on it.

const exists = await folder.exists('storage/public/uploads');
if (exists) {
    console.log('The folder exists');
} else {
    console.log('The folder does not exist');
}

2. Create a Folder (create)

Create a new folder, with the ability to automatically create parent folders.

await folder.create('storage/public/components/users');

3. Remove a Folder (remove)

Safely remove a folder and all its contents.

await folder.remove('storage/public/temp');

4. List Folder Contents (list)

Get a list of all files and folders inside a specific folder.

const contents = await folder.list('storage/public');
contents.forEach(item => {
    console.log(`${item.name} - ${item.isDirectory ? 'Folder' : 'File'}`);
});

5. Calculate Folder Size (size)

Calculate the total size of a folder and all its contents.

const totalSize = await folder.size('storage/public/uploads');
console.log(`Folder size: ${totalSize} bytes`);

6. Copy a Folder (copy)

Copy a folder and all its contents to a new location.

await folder.copy('storage/public/old-components', 'storage/public/new-components');

7. Move a Folder (move)

Move a folder from one location to another.

await folder.move('storage/public/old-location', 'storage/public/new-location');

8. Find in Folder (find)

Search for files in the folder that match a specific pattern.

const files = await folder.find('storage/public', '.test.ts');
files.forEach(file => console.log(`Found test file: ${file}`));

Error Handling

All operations throw exceptions if an error occurs. It is recommended to use try-catch for error handling:

try {
    await folder.remove('storage/public/non-existent-folder');
} catch (error) {
    console.error('An error occurred:', error.message);
}

Advanced Examples

Example 1: Creating a Project Structure

async function createProjectStructure(projectName: string) {
    try {
        // Check if the folder exists first
        const exists = await folder.exists(`storage/public/${projectName}`);
        if (exists) {
            throw new Error('The project already exists');
        }
 
        await folder.create(`storage/public/${projectName}/src`);
        await folder.create(`storage/public/${projectName}/tests`);
        await folder.create(`storage/public/${projectName}/docs`);
        await folder.create(`storage/public/${projectName}/assets`);
        console.log('Project structure created successfully');
    } catch (error) {
        console.error('Failed to create project structure:', error.message);
    }
}

Example 2: Moving and Archiving Old Folders

async function archiveOldFolders(threshold: number) {
    try {
        const contents = await folder.list('storage/public');
        const now = Date.now();
        
        for (const item of contents) {
            if (item.isDirectory) {
                const stats = await fs.stat(`storage/public/${item.name}`);
                const age = now - stats.mtimeMs;
                
                if (age > threshold) {
                    const archiveName = `storage/public/archives/${item.name}-${new Date().toISOString()}`;
                    await folder.move(`storage/public/${item.name}`, archiveName);
                    console.log(`Archived folder: ${item.name}`);
                }
            }
        }
    } catch (error) {
        console.error('Failed to archive folders:', error.message);
    }
}

Example 3: Cleaning Empty Folders

async function cleanEmptyFolders(directory: string = 'storage/public') {
    try {
        const contents = await folder.list(directory);
        for (const item of contents) {
            if (item.isDirectory) {
                const subContents = await folder.list(`${directory}/${item.name}`);
                if (subContents.length === 0) {
                    await folder.remove(`${directory}/${item.name}`);
                    console.log(`Deleted empty folder: ${item.name}`);
                }
            }
        }
    } catch (error) {
        console.error('Failed to clean empty folders:', error.message);
    }
}

Important Notes

All operations are asynchronous (use Promises)
Paths are automatically handled using path.join
You can check if a folder exists before performing any operation using exists
The remove operation is safe and ignores errors if the folder does not exist
The copy operation recursively copies all contents
The find operation supports simple patterns using includes
All operations are performed in the storage/public folder by default for your application

Conclusion

The Folder class in Kawkab provides a comprehensive set of tools for managing folders in your application. With this simple yet powerful API, you can handle folders efficiently and securely. All operations are designed to work by default in the storage/public folder to ensure your files are organized and safe in your application.

Files Strategies