Skip to content

Commit c5afb00

Browse files
ImStillBlessedImStillBlessed
committed
feat: add fs/stat
1 parent a410628 commit c5afb00

19 files changed

Lines changed: 1851 additions & 0 deletions

File tree

‎lib/node_modules/@stdlib/fs/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ var f = fs;
5757
- <span class="signature">[`resolveParentPathBy( path[, options], predicate, clbk )`][@stdlib/fs/resolve-parent-path-by]</span><span class="delimiter">: </span><span class="description">resolve a path according to a predicate function by walking parent directories.</span>
5858
- <span class="signature">[`resolveParentPath( path[, options], clbk )`][@stdlib/fs/resolve-parent-path]</span><span class="delimiter">: </span><span class="description">resolve a path by walking parent directories.</span>
5959
- <span class="signature">[`resolveParentPaths( paths[, options], clbk )`][@stdlib/fs/resolve-parent-paths]</span><span class="delimiter">: </span><span class="description">resolve paths from a set of paths by walking parent directories.</span>
60+
- <span class="signature">[`stat( path[, options], clbk )`][@stdlib/fs/stat]</span><span class="delimiter">: </span><span class="description">show full details on the statistics of a file or directory.</span>
6061
- <span class="signature">[`unlink( path, clbk )`][@stdlib/fs/unlink]</span><span class="delimiter">: </span><span class="description">remove a directory entry.</span>
6162
- <span class="signature">[`writeFile( file, data[, options], clbk )`][@stdlib/fs/write-file]</span><span class="delimiter">: </span><span class="description">write data to a file.</span>
6263

@@ -129,6 +130,8 @@ console.log( objectKeys( fs ) );
129130

130131
[@stdlib/fs/resolve-parent-paths]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/fs/resolve-parent-paths
131132

133+
[@stdlib/fs/stat]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/fs/stat
134+
132135
[@stdlib/fs/unlink]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/fs/unlink
133136

134137
[@stdlib/fs/write-file]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/fs/write-file

‎lib/node_modules/@stdlib/fs/docs/types/index.d.ts‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ import rename = require( '@stdlib/fs/rename' );
3434
import resolveParentPath = require( '@stdlib/fs/resolve-parent-path' );
3535
import resolveParentPathBy = require( '@stdlib/fs/resolve-parent-path-by' );
3636
import resolveParentPaths = require( '@stdlib/fs/resolve-parent-paths' );
37+
import stat = require( '@stdlib/fs/stat' );
3738
import unlink = require( '@stdlib/fs/unlink' );
3839
import writeFile = require( '@stdlib/fs/write-file' );
3940

@@ -449,6 +450,44 @@ interface Namespace {
449450
*/
450451
resolveParentPaths: typeof resolveParentPaths;
451452

453+
/**
454+
* Asynchronously returns file system statistics for a file or directory.
455+
*
456+
* @param path - file path
457+
* @param clbk - callback to invoke after retrieving file statistics
458+
*
459+
* @example
460+
* var stat = require( '@stdlib/fs/stat' );
461+
*
462+
* stat( __filename, onStat );
463+
* stat( __dirname, onStat );
464+
*
465+
* function onStat( error, stats ) {
466+
* if ( error ) {
467+
* throw error;
468+
* }
469+
* console.log( stats.isFile() );
470+
* console.log( stats.isDirectory() );
471+
* console.log( stats );
472+
* }
473+
*
474+
* @example
475+
* var out = stat.sync( __filename );
476+
* if ( out instanceof Error ) {
477+
* throw out;
478+
* }
479+
* console.log( out.isFile() );
480+
* console.log( out );
481+
*
482+
* out = stat.sync( __dirname );
483+
* if ( out instanceof Error ) {
484+
* throw out;
485+
* }
486+
* console.log( out.isDirectory() );
487+
* console.log( out );
488+
*/
489+
stat: typeof stat;
490+
452491
/**
453492
* Asynchronously removes a directory entry.
454493
*

‎lib/node_modules/@stdlib/fs/lib/index.js‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,15 @@ setReadOnly( fs, 'resolveParentPathBy', require( '@stdlib/fs/resolve-parent-path
162162
*/
163163
setReadOnly( fs, 'resolveParentPaths', require( '@stdlib/fs/resolve-parent-paths' ) );
164164

165+
/**
166+
* @name stat
167+
* @memberof fs
168+
* @readonly
169+
* @type {Function}
170+
* @see {@link module:@stdlib/fs/stat}
171+
*/
172+
setReadOnly( fs, 'stat', require( '@stdlib/fs/stat' ) );
173+
165174
/**
166175
* @name unlink
167176
* @memberof fs

‎lib/node_modules/@stdlib/fs/stat/README.md‎

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2018 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# Stat
22+
23+
> Get full details on a file or directory.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var stat = require( '@stdlib/fs/stat' );
31+
```
32+
33+
#### stat( path, clbk )
34+
35+
Asynchronously returns file system statistics for a file or directory.
36+
37+
The callback is invoked with an `fs.Stats` object containing methods and values describing the target path.
38+
39+
```javascript
40+
stat( __filename, onStat );
41+
42+
function onStat( error, stats ) {
43+
if ( error ) {
44+
throw error;
45+
}
46+
console.log( stats.isFile() );
47+
console.log( stats.isDirectory() );
48+
console.log( stats.isSymbolicLink() );
49+
console.log( stats.size );
50+
console.log( stats.mode );
51+
console.log( stats.atime );
52+
}
53+
```
54+
55+
#### stat( path, options, clbk )
56+
57+
Asynchronously returns file system statistics for a file or directory with options.
58+
59+
```javascript
60+
stat( __filename, {
61+
'bigint': true
62+
}, onStat );
63+
64+
function onStat( error, stats ) {
65+
if ( error ) {
66+
throw error;
67+
}
68+
console.log( stats.size );
69+
console.log( stats.atimeNs );
70+
}
71+
```
72+
73+
Options:
74+
75+
- **bigint**: `boolean` flag indicating whether numeric values should be returned as `bigint`. Default: `false`.
76+
77+
```javascript
78+
stat( __filename, onStat );
79+
80+
function onStat( error, stats ) {
81+
if ( error ) {
82+
throw error;
83+
}
84+
console.log( stats.isFile() );
85+
}
86+
```
87+
88+
#### stat.sync( path )
89+
90+
Synchronously returns file system statistics for a file or directory.
91+
92+
```javascript
93+
var out = stat.sync( __filename );
94+
if ( out instanceof Error ) {
95+
throw out;
96+
}
97+
console.log( out.isFile() );
98+
console.log( out.isSocket() );
99+
console.log( out.size );
100+
console.log( out.mtimeMs );
101+
```
102+
103+
#### stat.sync( path, options )
104+
105+
Synchronously returns file system statistics for a file or directory with options.
106+
107+
```javascript
108+
var out = stat.sync( __filename, {
109+
'bigint': true
110+
});
111+
if ( out instanceof Error ) {
112+
throw out;
113+
}
114+
console.log( out.size );
115+
console.log( out.birthtimeNs );
116+
```
117+
118+
The returned `fs.Stats` instance provides these type-check methods:
119+
120+
- `isFile()`
121+
- `isDirectory()`
122+
- `isBlockDevice()`
123+
- `isCharacterDevice()`
124+
- `isFIFO()`
125+
- `isSocket()`
126+
- `isSymbolicLink()`
127+
128+
The returned `fs.Stats` instance also provides values such as:
129+
130+
- `dev`, `ino`, `mode`, `nlink`, `uid`, `gid`, `rdev`, `size`, `blksize`, `blocks`
131+
- `atime`, `mtime`, `ctime`, `birthtime`
132+
- `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs`
133+
- `atimeNs`, `mtimeNs`, `ctimeNs`, `birthtimeNs` (available when `bigint: true`)
134+
135+
```javascript
136+
var out = stat.sync( __filename );
137+
if ( out instanceof Error ) {
138+
throw out;
139+
}
140+
console.log( out.isFile() );
141+
```
142+
143+
</section>
144+
145+
<!-- /.usage -->
146+
147+
<section class="examples">
148+
149+
## Examples
150+
151+
<!-- eslint no-undef: "error" -->
152+
153+
```javascript
154+
var stat = require( '@stdlib/fs/stat' );
155+
156+
var out = stat.sync( __filename );
157+
if ( out instanceof Error ) {
158+
throw out;
159+
}
160+
console.log( out.isFile() );
161+
162+
stat( __filename, onStat );
163+
164+
function onStat( error, stats ) {
165+
if ( error ) {
166+
throw error;
167+
}
168+
console.log( stats.isFile() );
169+
console.log( stats.isDirectory() );
170+
console.log( stats.isBlockDevice() );
171+
console.log( stats.isCharacterDevice() );
172+
console.log( stats.isFIFO() );
173+
console.log( stats.isSocket() );
174+
console.log( stats.isSymbolicLink() );
175+
console.log( stats.size );
176+
console.log( stats.mode );
177+
console.log( stats.uid );
178+
console.log( stats.gid );
179+
console.log( stats.atimeMs );
180+
console.log( stats.mtimeMs );
181+
console.log( stats.ctimeMs );
182+
console.log( stats.birthtimeMs );
183+
}
184+
```
185+
186+
</section>
187+
188+
<!-- /.examples -->
189+
190+
* * *
191+
192+
<section class="cli">
193+
194+
## CLI
195+
196+
<section class="usage">
197+
198+
### Usage
199+
200+
```text
201+
Usage: stat [options] <path>
202+
203+
Options:
204+
205+
-h, --help Print this message.
206+
-V, --version Print the package version.
207+
```
208+
209+
</section>
210+
211+
<!-- /.usage -->
212+
213+
<section class="notes">
214+
215+
### Notes
216+
217+
- Relative paths are resolved relative to the current working directory.
218+
- Errors are written to `stderr`.
219+
- Results are written to `stdout` as JSON.
220+
221+
</section>
222+
223+
<!-- /.notes -->
224+
225+
</section>
226+
227+
<!-- /.cli -->
228+
229+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
230+
231+
<section class="related">
232+
233+
* * *
234+
235+
## See Also
236+
237+
- <span class="package-name">[`@stdlib/fs/read-file`][@stdlib/fs/read-file]</span><span class="delimiter">: </span><span class="description">read the entire contents of a file.</span>
238+
- <span class="package-name">[`node-fs-stats`][node-fs-stats]</span><span class="delimiter">: </span><span class="description">Official Node.js fs.Stats class.</span>
239+
240+
</section>
241+
242+
<!-- /.related -->
243+
244+
<section class="links">
245+
246+
[node-fs-stats]: https://nodejs.org/api/fs.html#class-fsstats
247+
248+
<!-- <related-links> -->
249+
250+
[@stdlib/fs/read-file]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/fs/read-file
251+
252+
<!-- </related-links> -->
253+
254+
</section>
255+
256+
<!-- /.links -->

‎lib/node_modules/@stdlib/fs/stat/benchmark/benchmark.js‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2018 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
var bench = require( '@stdlib/bench' );
22+
var stat = require( './../lib' ).sync;
23+
24+
bench( 'stat.sync', function benchmark( b ) {
25+
var out;
26+
var i;
27+
28+
b.tic();
29+
for ( i = 0; i < b.iterations; i++ ) {
30+
out = stat( __filename );
31+
if ( out instanceof Error ) {
32+
b.fail( out.message );
33+
}
34+
if ( typeof out.isFile !== 'function' ) {
35+
b.fail( 'unexpected return value' );
36+
}
37+
}
38+
b.toc();
39+
if ( out instanceof Error ) {
40+
b.fail( out.message );
41+
}
42+
b.pass( 'benchmark finished' );
43+
b.end();
44+
});

0 commit comments

Comments
 (0)