Merge pull request #25 from SecJS/feat/len-add-unset-fn

feat: Add File and Folder class

Author: jlenon7

.gitignore

@@ -126,3 +126,9 @@ out
 *.d.ts
 dist
 build
+
+# testing files generated here
+file-class-test
+file-class-global-test
+folder-class-test
+folder-class-global-test

README.md

@@ -29,7 +29,7 @@ The intention behind this repository is to always maintain a `Utils` package wit
 > it keeps as dev dependency because one day `@secjs/core` will install everything once.
 
 ```bash
-npm install @secjs/contracts @secjs/exceptions
+npm install @secjs/logger @secjs/contracts @secjs/exceptions
 ```
 
 > Then you can install the package using:
@@ -40,6 +40,100 @@ npm install @secjs/utils
 
 ## Classes Usage
 
+### File
+
+> Use File to create an instance of a File, it's existing or not.
+
+```ts
+import { File } from '@secjs/utils'
+
+// With file you can manipulate an existing file, or create a new one
+
+const existentFile = new File('path/to/existent/file.txt')
+const nonExistentFile = new File('path/to/nonExistent/file.txt', Buffer.from('File content'))
+
+// Now existentFile and nonExistentFile instances are created, but not loaded/created
+
+// using load here because the file already exists, if using create, would generate an exception
+// property withContent if true, will save the file content in the instance, Be careful with big files
+existentFile.loadSync({ withContent: true })
+nonExistentFile.createSync().loadSync({ withContent: true })
+
+// now the files will have this properties
+console.log(existentFile.createdAt)
+console.log(existentFile.accessedAt)
+console.log(existentFile.modifiedAt)
+console.log(existentFile.fileSize)
+console.log(existentFile.content)
+
+// you can delete the file using remove method
+existentFile.removeSync() // void
+
+// you can get the content of the file with getContent method
+console.log(existentFile.getContentSync()) // Some Buffer instance
+
+// you can use toJSON method to get the instance informations in JSON
+console.log(existentFile.toJSON()) // { ...infos }
+
+// File uses readable streams in async methods to not block the event loop when handling huge files content
+await existentFile.load()
+await existentFile.remove()
+await existentFile.create()
+await existentFile.getContent()
+```
+
+---
+
+### Folder
+
+> Use Folder to create an instance of a Folder, it's existing or not.
+
+```ts
+import { Folder } from '@secjs/utils'
+
+// With folder you can manipulate an existing folder, or create a new one
+
+const existentFolder = new Folder('path/to/existent/folder')
+const nonExistentFolder = new Folder('path/to/nonExistent/folder')
+
+// Now existentFolder and nonExistentFolder instances are created, but not loaded/created
+
+// using load here because the file already exists, if using create, would generate an exception
+
+// property withSub if true, will load files and subFolders from the folder
+// property withFileContent if true, will get the content of all files in the folder, Be careful with big files
+
+existentFolder.loadSync({ withSub: true, withFileContent: false })
+nonExistentFolder.createSync().loadSync({ withSub: true, withFileContent: true })
+
+// now the folders will have this properties
+console.log(existentFolder.createdAt)
+console.log(existentFolder.accessedAt)
+console.log(existentFolder.modifiedAt)
+console.log(existentFolder.folderSize)
+
+// you can delete the folder using remove method
+existentFolder.removeSync() // void
+
+// you can use toJSON method to get the instance informations in JSON
+console.log(existentFolder.toJSON()) // { ...infos }
+
+// you can use getFilesByPattern method to get all files in the folder that match some pattern
+// if recursive is true, will go inside subFolders too
+const recursive = true
+console.log(existentFolder.getFilesByPattern('path/to/**/*.ts', recursive)) // [...files instance]
+
+// you can use getFoldersByPattern method to get all folders in the folder that match some pattern
+console.log(existentFolder.getFoldersByPattern('path/to/**/folder', recursive)) // [...folders instance]
+
+// Folder uses readable streams in async methods to not block the event loop when handling huge files content
+await existentFolder.load()
+await existentFolder.remove()
+await existentFolder.create()
+```
+
+---
+
 ### Path
 
 > Use Path to get the absolute path from project folders.
@@ -282,6 +376,21 @@ console.log(clean.cleanArraysInObject(object2)) // { number2: [{ number1: "numbe
 
 ## Functions Usage
 
+### formatBytes
+
+> Creates a string based on the bytes size.
+
+```ts
+import { formatBytes } from '@secjs/utils'
+
+const bytes = 1024*1024*1024 // 1GB
+const decimals = 4
+
+formatBytes(bytes, decimals) // Example: 1.0932 GB
+```
+
+---
+
 ### getBranch
 
 > Get the actual git branch that the project is running or not a repository.
@@ -292,28 +401,7 @@ import { getBranch } from '@secjs/utils'
 await getBranch() // master || Not a repository
 ```
 
-### pathPattern
-
-> Transform all route paths to the same pattern.
-
-```js
-import { pathPattern } from '@secjs/utils'
-
-pathPattern('/users/:id/') // returns /users/:id
-pathPattern('clients/') // returns /clients
-pathPattern('/api/v2') // returns /api/v2
-pathPattern('/api/v3/') // returns /api/v3
-
-pathPattern(['/api/v1/', 'api/v2', 'api/v3/', '/api/v4'])
-
-// returns
-// [
-//  '/api/v1',
-//  '/api/v2',
-//  '/api/v3',
-//  '/api/v4'
-// ]
-```
+---
 
 ### download
 
@@ -334,53 +422,6 @@ import { download } from '@secjs/utils'
 
 ---
 
-### getFiles
-
-> Get all files inside a path and files inside folders if needed
-
-```js
-import { getFiles } from '@secjs/utils'
-
-const iterateFolders = false 
-for await (const file of getFiles('any/path', iterateFolders)) {
-  console.log(file) // /home/path/to/your/file
-}
-```
-
-### getFolders
-
-> Get all folders inside a path and files if needed.
-
-```js
-import { getFolders } from '@secjs/utils'
-
-const withFiles = true
-const directory = await getFolders('some/path', withFiles)
-
-// {
-//   path: '/home/some/path',
-//   files: ['/home/some/path/file.ts'],
-//   folders: [{
-//     path: '/home/some/path/folder',
-//     files: ['/home/some/path/file.ts'],
-//     folders: []
-//   }] as IDirectory[]
-// } as IDirectory
-```
-
-### fileExists
-
-> Return true if file exists or false
-
-```js
-import { fileExists } from '@secjs/utils'
-
-// Just abstracting the error that node throws 
-// if file does not exist
-
-console.log(fileExists('path/to/file')) // true or false
-```
-
 ### observeChanges
 
 > Use observeChanges to observe changes in the value of an object
@@ -405,6 +446,8 @@ data.name = 'João'
 // Name changed to: João { value: 'args are the same second parameter of doSomething function' }
 ```
 
+---
+
 ### removeDuplicated
 
 > Use removeDuplicated to remove duplicated values from an Array
@@ -417,6 +460,8 @@ const array = [1, 1, 2, 4, 4]
 console.log(removeDuplicated(array)) // [1, 2, 4]
 ```
 
+---
+
 ### randomColor
 
 > Use randomColor to generate a random Hexadecimal color
@@ -427,9 +472,11 @@ import { randomColor } from '@secjs/utils'
 console.log(randomColor()) // #7059c1
 ```
 
+---
+
 ### isArrayOfObjects
 
-> Use isArrayOfObjects to verify if all values inside of the array are objects
+> Use isArrayOfObjects to verify if all values inside the array are objects
 
 ```js
 import { isArrayOfObjects } from '@secjs/utils'
@@ -447,9 +494,11 @@ console.log(isArrayOfObjects(array3)) // true
 console.log(isArrayOfObjects(fakeArray)) // false
 ```
 
+---
+
 ### urlify
 
-> Use urlify to inject some URL of a string inside a HTML Link
+> Use urlify to inject some URL of a string inside an HTML Link
 
 ```js
 import { urlify } from '@secjs/utils'

index.ts

@@ -1,13 +1,16 @@
 export * from './src/Classes/Json'
 export * from './src/Classes/Path'
+export * from './src/Classes/File'
 export * from './src/Classes/Token'
 export * from './src/Classes/Clean'
 export * from './src/Classes/Route'
+export * from './src/Classes/Folder'
 export * from './src/Classes/Parser'
 export * from './src/Classes/Numbers'
 export * from './src/Classes/Blacklist'
 
 export * from './src/Functions/sort'
+export * from './src/Functions/unset'
 export * from './src/Functions/sleep'
 export * from './src/Functions/isCpf'
 export * from './src/Functions/isCnpj'
@@ -17,12 +20,8 @@ export * from './src/Functions/download'
 export * from './src/Functions/fillable'
 export * from './src/Functions/kmRadius'
 export * from './src/Functions/paginate'
-export * from './src/Functions/getFiles'
 export * from './src/Functions/scheduler'
 export * from './src/Functions/getBranch'
-export * from './src/Functions/getFolders'
-export * from './src/Functions/fileExists'
-export * from './src/Functions/pathPattern'
 export * from './src/Functions/getCommitId'
 export * from './src/Functions/randomColor'
 export * from './src/Functions/observeChanges'