Skip to content

Commit f300497

Browse files
unicornwareunicornware
committed
docs: use
Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>
1 parent b2b25f3 commit f300497

File tree

7 files changed

+489
-15
lines changed

7 files changed

+489
-15
lines changed

‎README.md‎

Lines changed: 282 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,278 @@ In browsers with [`esm.sh`][esmsh]:
9090

9191
## Use
9292

93-
**TODO**: use
93+
```ts
94+
import type {
95+
File,
96+
AnyParent as Parent,
97+
Root
98+
} from '@flex-development/fst'
99+
import {
100+
fromFileSystem,
101+
type Dirent,
102+
type FileSystem,
103+
type Stats
104+
} from '@flex-development/fst-util-from-fs'
105+
import pathe from '@flex-development/pathe'
106+
import { inspect } from '@flex-development/unist-util-inspect'
107+
import { ok } from 'devlop'
108+
import fs from 'node:fs'
109+
import { size } from 'unist-util-size'
110+
111+
declare module '@flex-development/fst' {
112+
interface File {
113+
/**
114+
* The size of the file.
115+
*/
116+
size?: bigint | number | undefined
117+
}
118+
}
119+
120+
declare module '@flex-development/fst-util-from-fs' {
121+
interface Stats {
122+
/**
123+
* The size of the entry.
124+
*/
125+
size: bigint | number
126+
}
127+
}
128+
129+
/**
130+
* A glob pattern matching directories to search
131+
* and files to include in the tree.
132+
*
133+
* @const {string} pattern
134+
*/
135+
const pattern: string = 'src/**/**'
136+
137+
/**
138+
* The file system tree.
139+
*
140+
* @const {Root} tree
141+
*/
142+
const tree: Root = await fromFileSystem({
143+
extensions: '.mts',
144+
filters: {
145+
/**
146+
* @this {void}
147+
*
148+
* @param {string} path
149+
* The path to the directory, relative to `tree.path`
150+
* @param {number | null | undefined} depth
151+
* The current search depth
152+
* @param {Dirent} dirent
153+
* The dirent representing the file system entry
154+
* @param {Parent} parent
155+
* The parent node
156+
* @param {Root} tree
157+
* The file system tree
158+
* @return {boolean}
159+
* `true` if node for `path` should be added, `false` otherwise
160+
*/
161+
directory(
162+
this: void,
163+
path: string,
164+
depth: number | null | undefined,
165+
dirent: Dirent,
166+
parent: Parent,
167+
tree: Root
168+
): boolean {
169+
return pathe.matchesGlob(path, pattern, {
170+
cwd: tree.path,
171+
dot: false,
172+
ignore: ['**/__mocks__/**', '**/__snapshots__/**', '**/__tests__/**'],
173+
noglobstar: false
174+
})
175+
},
176+
177+
/**
178+
* @this {void}
179+
*
180+
* @param {string} path
181+
* The path to the file, relative to `tree.path`
182+
* @param {number | null | undefined} depth
183+
* The current search depth
184+
* @param {Dirent} dirent
185+
* The dirent representing the file system entry
186+
* @param {Parent} parent
187+
* The parent node
188+
* @param {Root} tree
189+
* The file system tree
190+
* @return {boolean}
191+
* `true` if node for `path` should be added, `false` otherwise
192+
*/
193+
file(
194+
this: void,
195+
path: string,
196+
depth: number | null | undefined,
197+
dirent: Dirent,
198+
parent: Parent,
199+
tree: Root
200+
): boolean {
201+
return pathe.matchesGlob(path, pattern, {
202+
cwd: tree.path,
203+
dot: true,
204+
ignore: ['**/.DS_Store'],
205+
noglobstar: false
206+
})
207+
}
208+
},
209+
fs: fs.promises,
210+
handles: {
211+
/**
212+
* @async
213+
*
214+
* @this {void}
215+
*
216+
* @param {File} node
217+
* The node representing the file
218+
* @param {Dirent} dirent
219+
* The dirent representing the file
220+
* @param {Parent} parent
221+
* The parent of `node`
222+
* @param {Root} tree
223+
* The current file system tree
224+
* @param {Parent[]} ancestors
225+
* The ancestors of `node`, with the last node being `parent`
226+
* @param {FileSystem} fs
227+
* The file system API
228+
* @return {Promise<undefined>}
229+
*/
230+
async file(
231+
this: void,
232+
node: File,
233+
dirent: Dirent,
234+
parent: Parent,
235+
tree: Root,
236+
ancestors: Parent[],
237+
fs: FileSystem
238+
): Promise<undefined> {
239+
/**
240+
* The list of relative ancestor paths.
241+
*
242+
* @const {string[]} paths
243+
*/
244+
const paths: string[] = [...ancestors.slice(1), node].map(n => {
245+
ok(n.type !== 'root', 'did not expect tree')
246+
return n.name
247+
})
248+
249+
/**
250+
* Info about the file.
251+
*
252+
* @const {Stats} stats
253+
*/
254+
const stats: Stats = await fs.stat(pathe.join(tree.path, ...paths))
255+
256+
return node.size = stats.size, void node
257+
}
258+
}
259+
})
260+
261+
console.log(inspect(tree))
262+
console.dir(size(tree))
263+
console.dir(size(tree, node => node.type === 'directory'))
264+
console.dir(size(tree, node => node.type === 'file'))
265+
```
266+
267+
...yields
268+
269+
```sh
270+
root[1]
271+
│ path: "/Users/lex/Projects/flex-development/fst-util-from-fs/"
272+
└─0 directory<src>[6]
273+
├─0 directory<interfaces>[16]
274+
│ ├─0 file<dirent.mts> null
275+
│ │ size: 950
276+
│ ├─1 file<file-system-entries.mts> null
277+
│ │ size: 559
278+
│ ├─2 file<file-system.mts> null
279+
│ │ size: 643
280+
│ ├─3 file<filters.mts> null
281+
│ │ size: 583
282+
│ ├─4 file<handles.mts> null
283+
│ │ size: 640
284+
│ ├─5 file<index.mts> null
285+
│ │ size: 1102
286+
│ ├─6 file<is-directory.mts> null
287+
│ │ size: 345
288+
│ ├─7 file<is-file.mts> null
289+
│ │ size: 315
290+
│ ├─8 file<is-symbolic-link.mts> null
291+
│ │ size: 365
292+
│ ├─9 file<options.mts> null
293+
│ │ size: 2052
294+
│ ├─10 file<readdir-dirent-options.mts> null
295+
│ │ size: 744
296+
│ ├─11 file<readdir-options.mts> null
297+
│ │ size: 594
298+
│ ├─12 file<readdir.mts> null
299+
│ │ size: 798
300+
│ ├─13 file<realpath.mts> null
301+
│ │ size: 743
302+
│ ├─14 file<stat.mts> null
303+
│ │ size: 566
304+
│ └─15 file<stats.mts> null
305+
│ size: 704
306+
├─1 directory<internal>[12]
307+
│ ├─0 file<chain-or-call.mts> null
308+
│ │ size: 2656
309+
│ ├─1 file<combine-paths.mts> null
310+
│ │ size: 1579
311+
│ ├─2 file<constant.mts> null
312+
│ │ size: 413
313+
│ ├─3 file<empty-array.mts> null
314+
│ │ size: 260
315+
│ ├─4 file<empty-file-system-entries.mts> null
316+
│ │ size: 524
317+
│ ├─5 file<fs.browser.mts> null
318+
│ │ size: 973
319+
│ ├─6 file<fs.d.mts> null
320+
│ │ size: 241
321+
│ ├─7 file<fs.node.mts> null
322+
│ │ size: 414
323+
│ ├─8 file<identity.mts> null
324+
│ │ size: 351
325+
│ ├─9 file<is-promise.mts> null
326+
│ │ size: 640
327+
│ ├─10 file<visit-directory.mts> null
328+
│ │ size: 10232
329+
│ └─11 file<with-trailing-slash.mts> null
330+
│ size: 1357
331+
├─2 directory<types>[10]
332+
│ ├─0 file<awaitable.mts> null
333+
│ │ size: 269
334+
│ ├─1 file<extensions.mts> null
335+
│ │ size: 323
336+
│ ├─2 file<filter.mts> null
337+
│ │ size: 1006
338+
│ ├─3 file<get-file-system-entries.mts> null
339+
│ │ size: 847
340+
│ ├─4 file<handle.mts> null
341+
│ │ size: 1347
342+
│ ├─5 file<index.mts> null
343+
│ │ size: 628
344+
│ ├─6 file<list.mts> null
345+
│ │ size: 241
346+
│ ├─7 file<sort.mts> null
347+
│ │ size: 455
348+
│ ├─8 file<to-visit-key.mts> null
349+
│ │ size: 1083
350+
│ └─9 file<visit-map.mts> null
351+
│ size: 321
352+
├─3 directory<utils>[2]
353+
│ ├─0 file<get-file-system-entries.mts> null
354+
│ │ size: 5805
355+
│ └─1 file<index.mts> null
356+
│ size: 157
357+
├─4 file<index.mts> null
358+
│ size: 189
359+
└─5 file<util.mts> null
360+
size: 2055
361+
47 # total number of nodes
362+
5 # total number of directory nodes
363+
42 # total number of file nodes
364+
```
94365

95366
## API
96367

@@ -102,6 +373,10 @@ There is no default export.
102373

103374
Create a file system tree.
104375

376+
> 👉 **Note**: Returns a promise if one of the following methods returns a promise:
377+
> [`fs.realpath`](#realpath), [`options.getFileSystemEntries`](#getfilesystementriestparent-fs),
378+
> [`options.handles.directory`](#handlet-result), [`options.handlers.file`](#handlet-result).
379+
105380
#### Type Parameters
106381

107382
- `T` ([`Awaitable<Root>`][fst-root])
@@ -128,7 +403,10 @@ There is no default export.
128403

129404
Get a record of accessible file system entries.
130405

131-
> 👉 **Note**: Entries are relative to `parent`.
406+
Entries are relative to `parent`.
407+
408+
> 👉 **Note**: Returns a promise if [`fs.readdir`](#readdir) returns a promise,
409+
> or any symbolic links are encountered and [`fs.stat`](#stat) returns a promise.
132410
133411
#### Type Parameters
134412

@@ -202,9 +480,9 @@ Information about directories and files (`interface`).
202480
203481
#### Properties
204482
205-
- `directories` ([`readonly Dirent[]`](#dirent))
483+
- `directories` ([`List<Dirent>`](#dirent))
206484
— the list of directories
207-
- `files` ([`readonly Dirent[]`](#dirent))
485+
- `files` ([`List<Dirent>`](#dirent))
208486
— the list of files
209487
210488
### `FileSystem`

0 commit comments

Comments
 (0)