fst utility to create trees from file systems

• What is this?
• Install
• Use
• API
  • fromFileSystem([options])
  • Options
  • Dirent
  • Extensions
  • FileSystem
  • Filter
  • Filters
  • Handle<[T]>
  • Handles
  • Sort
• Syntax tree
• Types
• Contribute

This package is a utility to create file system trees.

This utility that uses file system adapters to recursively read a directory, and create a tree from its contents.

This package is ESM only.

In Node.js (version 18+) with yarn:

yarn add @flex-development/fst-util-from-fs

See Git - Protocols | Yarn  for details regarding installing from Git.

In Deno with esm.sh:

import { fromFileSystem } from 'https://esm.sh/@flex-development/fst-util-from-fs'

In browsers with esm.sh:

<script type="module">
  import { fromFileSystem } from 'https://esm.sh/@flex-development/fst-util-from-fs'
</script>

TODO: use

This package exports the following identifiers:

• fromFileSystem

There is no default export.

Create a file system tree.

• options (Options, optional) — tree options

(Root) file system tree

Options for creating a file system tree (TypeScript interface).

• content (boolean, optional) — include file content (populates the value field of each file node)
• depth (number, optional) — maximum search depth (inclusive). a search depth less than 0 will produce an empty tree
• extensions (Extensions, optional) — list of file extensions to filter matched files by
• filters (Filters, optional) — path filters to determine if nodes should be added to the tree
• fs (Partial<FileSystem>, optional) — file system adapter
• handles (Handles, optional) — node handlers
• root (URL | string, optional) — module id of root directory
  • default: pathe.cwd() + pathe.sep
• sort (Sort, optional) — function used to sort child nodes

Directory content entry (TypeScript interface).

This interface can be augmented to register custom methods and properties.

declare module '@flex-development/fst-util-from-fs' {
  interface Dirent {
    parentPath: string
  }
}

• isDirectory ((this: void) => boolean) — check if the dirent describes a directory
• name (string) — directory content name. if the dirent refers to a file, the file extension should be included

Union of options to filter matched files by file extension (TypeScript type).

type Extensions = Set<string> | readonly string[] | string

File system adapter (TypeScript interface).

• readFileSync ((this: void, path: string, encoding: 'utf8') => string, optional) — get the contents of the file at path
• readdirSync ((this: void, path: string, options: { withFileTypes: true }) => readonly Dirent[]) — read the contents of the directory at path

Determine if a node for x should be added to a file system tree.

• x (string) — path to directory or file

(boolean) true if node for x should be added, false otherwise

Path filters to determine if nodes should be added to the tree (TypeScript type).

• directory (Filter, optional) — determine if a directory node should be added to the tree
• file (Filter, optional) — determine if a file node should be added to the tree

Handle node.

• T (Child) — fst child node

• node (T) — directory or file node
• dirent (Dirent) — dirent object representing directory or file
• parent (Parent) — parent node
• tree (Root) — file system tree
• fs (FileSystem) — file system adapter

(null | undefined | void) nothing

Path filters to determine if nodes should be added to the tree (TypeScript type).

• directory (Handle<Directory>, optional) — directory node handler
• file (Handle<File>, optional) — file node handler

Compare node a to b.

• a (Child) — current child node
• b (Child) — next child node

(number) comparison result

The syntax tree is fst.

This package is fully typed with TypeScript.

See CONTRIBUTING.md.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.