fst-util-from-fs

fst utility to create trees from file systems

Contents

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

What is this?

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.

Install

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>

Use

TODO: use

API

This package exports the following identifiers:

• fromFileSystem

There is no default export.

fromFileSystem([options])

Create a file system tree.

Parameters

• options (Options, optional) — tree options

Returns

(Root) file system tree

Options

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

Properties

• 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

Dirent

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
  }
}

Properties

• 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

Extensions

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

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

FileSystem

File system adapter (TypeScript interface).

Properties

• 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

Filter

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

Parameters

• x (string) — path to directory or file

Returns

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

Filters

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

Properties

• 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<[T]>

Handle node.

Type Parameters

• T (Child) — fst child node

Parameters

• 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

Returns

(null | undefined | void) nothing

Handles

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

Properties

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

Sort

Compare node a to b.

Parameters

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

Returns

(number) comparison result

Syntax tree

The syntax tree is fst.

Types

This package is fully typed with TypeScript.

Contribute

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.