fst

File System Tree.

fst is a specification for representing file systems as abstract syntax trees.

It implements the unist spec.

Contents

• Introduction
  • Where this specification fits
• Types
• Nodes (abstract)
  • Node
  • Literal
  • Parent
• Nodes
  • Directory
  • File
  • Root
• Content model
  • DirectoryContent
  • FstNode
• Helpers
  • AnyNode
  • AnyParent
  • Child
• Glossary
• List of utilities
• Contribute

Introduction

This document defines a format for representing file systems as abstract syntax trees. Development of fst started in January 2025. This specification is written in a TypeScript-like grammar.

Where this specification fits

fst extends unist, a format for syntax trees, to benefit from its ecosystem of utilities.

Types

TypeScript users can integrate fst type definitions into their project by installing the appropriate packages:

yarn add @flex-development/fst

Nodes (abstract)

Node

interface Node extends unist.Node {}

Node (unist.Node) is a syntactic unit in fst syntax trees.

Literal

interface Literal extends Node {
  value: string | null | undefined
}

Literal represents an abstract interface in fst containing the smallest possible value.

Parent

interface Parent extends unist.Parent {
  children: Child[]
}

Parent (unist.Parent) represents an abstract interface in fst containing other nodes (said to be children).

Its content is limited to file system content.

Nodes

Directory

interface Directory extends Parent {
  children: DirectoryContent[]
  data?: DirectoryData | undefined
  name: string
  type: 'directory'
}

Directory (Parent) represents a parent directory or subdirectory. Its name is relative to its parent directory.

Directory can be used in root nodes, as well as other directory nodes. Its content model is directory.

File

interface File extends Literal {
  data?: FileData | undefined
  name: string
  type: 'file'
  value: string | null | undefined
}

File (Literal) represents a file.

File names are relative to the parent directory. Unlike the name property of a ParsedPath, file names include file extensions.

File can be used in directory and root nodes. It cannot contain any children — it is a leaf.

Root

interface Root extends Parent {
  children: DirectoryContent[]
  data?: RootData | undefined
  path: string
  type: 'root'
}

Root (Parent) represents the root of a file system.

Root can be used as the root of a tree, never as a child. It can contain directory content.

Content model

DirectoryContent

type DirectoryContent = Directory | File

Directory content represents files and subdirectories in a parent directory.

FstNode

type FstNode = NodeMap[keyof NodeMap]

Registered fst nodes.

To register custom nodes, augment NodeMap:

declare module '@flex-development/fst' {
  interface NodeMap {
    customNode: CustomNode
  }
}

Helpers

AnyNode

Union of nodes that can occur in fst.

See also: InclusiveDescendant

type AnyNode = InclusiveDescendant<Root>

AnyParent

Union of parents that are inclusive descendants of Root.

See also: Parents

type AnyParent = Parents<Root>

Child

Union of child nodes that can occur in fst.

See also: Children

type Child = Children<AnyParent>[number]

Glossary

See the unist glossary for more terms.

List of utilities

See the unist list of utilities for more utilities.

• fst-util-from-fs — create trees from file systems
• unist-util-builder — build trees
• unist-util-inspect — inspect trees
• unist-util-visit — visit nodes using preorder or postorder traversal

Contribute

See CONTRIBUTING.md.

Ideas for new utilities and tools can be posted in fst/ideas.

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