path-info-stats

Read, keep, import, export path information and statistics:

• read path stats both asynchronously (default) and synchronously
• safe information (paths must exist and be correct)
• cross-os path management
• fast json import/export

Install

npm i path-info-stats

Create an object and read path info

The method set({ absolutePath, relRootPath })

Arguments:

1. absolutePath is a required parameter with the absolute path we need to read information for (and it must exist);
2. relRootPath is an optional parameter which states what is the root path for this object; this data is quite important, for example, if we want to handle groups of paths which belong to different root directories;
3. absolutePath must exist otherwise a PathInfoError will be thrown;
4. if present, relRootPath must exist otherwise a PathInfoError will be thrown.

This is the main difference between PathInfo and PathInfoSync because it is the only sync/async method in the library.

The set method it is not just a setter, but it makes some strict checks in order to have reliable path information. So, after running this method (successfully), PathInfo will have:

• valid and normalized absolutePath
• valid and normalized relRootPath (if present)
• verified existent absolutePath
• verified existent relRootPath (if present)

Is fromJson() an alternative to set()? Methods fromJson and toJson have been created for importing/exporting purposes, and for that reason they should be fast. Therefore, fromJson will not run the same checks of set(). So, no, it is not an alternative!

The following examples:

1. create an empty object;
2. read and set the path information:
3. if something goes wrong, a PathInfoError will be thrown.

Default class (async)

const { PathInfo } = require('path-info-stats')
const myPath = new PathInfo()
await myPath.set({
    absolutePath: '/user/example012/documents/file1.txt',
    relRootPath: '/user/example012/documents/' /* optional */
})

Sync class

const { PathInfoSync } = require('path-info-stats')
const myPath = new PathInfoSync()
myPath.set({
    absolutePath: '/user/example012/documents/file1.txt',
    relRootPath: '/user/example012/documents/' /* optional */
})

N.B. documentation below will refer to PathInfo only. However, getter, setters, and other methods are not async and are the same for both PathInfo and PathInfoSync.

Getters

After being instantiated a PathInfo object, we can finally get all the information.

// Let's take the following as example object
const myPath = new PathInfo()
await myPath.set({
    absolutePath: '/user/example012/documents/file1.txt',
    relRootPath: '/user/example012'
})

// getter usage examples
console.log('File name =', myPath.name) // output: 'File name = file1'
console.log('File size =', myPath.sizeString) // output: 'File size = 43 KB'

Name	Description	Output
base	File name with extension (or directory name)	"file1.txt"
createdAt	Timestamp for creation date	1602568566563
dir	Absolute path of parent directory	"/user/example012/documents/"
ext	File extension	"txt"
isDirectory	True if it is a directory	false
isFile	True if it is a file	true
level	Level of nesting (0 for the root)	3
modifiedAt	Timestamp for modification date	1602568577594
name	File or directory name	"file1"
path	Full path (basically the same of absolutePath argument)	"/user/example012/documents/file1.txt"
relPath	Relative path (in according to relRoot)	"documents/file1.txt"
relRoot	Relative root path (see relRootPath argument)	"/user/example012"
root	System root for the path	"/"
size	File size in bytes	43008
sizeString	File size in human-readable string	"43 KB"

Setters

// new PathInfo object without relative root
const myPath = new PathInfo()
await myPath.set({
    absolutePath: '/user/example012/documents/file1.txt'
})

// ...after some operations, we set the relative root path
myPath.relRoot('/user/example012')
myPath.size(8612548) // bytes

Name	Description
relRoot(root)	Set the relative root for the path. It does not change anything but the internal reference about the root which the path we want to belong to. In other words, this would be useful if we want to handle groups of paths which belong to different root directories.
size(value)	Set the size for the path, in bytes.

Other methods

isEqualTo(PathInfo obj): boolean

Returns true if the objects have the same paths and roots.

const myPath1 = new PathInfo()
const myPath2 = new PathInfo()
await myPath1.set({
    absolutePath: '/user/example012/documents/file1.txt',
    relRootPath: '/user/example012'
})
await myPath2.set({
    absolutePath: '/user/example012/documents/file1.txt',
    relRootPath: '/user/example012'
})

console.log('path1 == path2:', myPath1.isEqualTo(myPath2)) // output: 'path1 == path2: true'

myPath2.relRoot('/user/example012/documents/')
console.log('path1 == path2:', myPath1.isEqualTo(myPath2)) // output: 'path1 == path2: false'

isSet(): boolean

Returns true if the object has been initialized and set without errors.

const myPath = new PathInfo()
try {
  await myPath.set({
    absolutePath: '/wrong-path'
  })
  console.log('Is myPath set?', myPath.isSet()) // output: 'Is myPath set? true'
} catch(e) {
  console.log('Is myPath set?', myPath.isSet()) // output: 'Is myPath set? false'
}

clone(): PathInfo

Return a new object with same data.

const myPath1 = new PathInfo()
let myPath2
await myPath1.set({
    absolutePath: '/user/example012/documents/file1.txt',
    relRootPath: '/user/example012'
})
myPath2 = myPath1.clone()
console.log('path1 == path2:', myPath1.isEqualTo(myPath2)) // output: 'path1 == path2: true'

toJson(): object

Return a json object for any exporting operation.

const myPath1 = new PathInfo()
await myPath1.set({
    absolutePath: '/user/example012/documents/directory1/directory2',
    relRootPath: '/user/example012/documents'
})
console.log(myPath1.toJson())
/* 
  OUTPUT:
  {
     root: '/',
     dir: '/user/example012/documents/directory1',
     base: 'directory2',
     ext: '',
     name: 'directory2',
     path: '/user/example012/documents/directory1/directory2',
     level: 3,
     size: 4096,
     createdAt: 1602568566563,
     modifiedAt: 1602568566563,
     isFile: false,
     isDirectory: true,
     relPath: 'directory1/directory2',
     relRoot: '/user/example012/documents'
  }
*/

fromJson(object): undefined

Set path info from a json object.

Is fromJson() an alternative to set()? Methods fromJson and toJson have been created for importing/exporting purposes, and for that reason they should be fast. Therefore, fromJson will not run the same checks of set(). So, no, it is not an alternative!

const myPath1 = new PathInfo()
console.log('Is myPath1 set?', myPath1.isSet()) // output: 'Is myPath1 set? false'
myPath1.fromJson({
   root: '/',
   dir: '/user/example012/documents/directory1',
   base: 'directory2',
   ext: '',
   name: 'directory2',
   path: '/user/example012/documents/directory1/directory2',
   level: 3,
   size: 4096,
   createdAt: 1602568566563,
   modifiedAt: 1602568566563,
   isFile: false,
   isDirectory: true,
   relPath: 'directory1/directory2',
   relRoot: '/user/example012/documents'
})
console.log('Is myPath1 set?', myPath1.isSet()) // output: 'Is myPath1 set? true'