File system tree format
npm install @flex-development/fst







File System Tree.
---
fst is a specification for representing file systems as [abstract syntax trees][unist-syntax-tree].
It implements the [unist][unist] spec.
- 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
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.
fst extends [unist][], a format for syntax trees, to benefit from its ecosystem of utilities.
TypeScript users can integrate fst type definitions into their project by installing the appropriate packages:
``sh`
yarn add @flex-development/fst
`ts`
interface Node extends unist.Node {}
Node ([unist.Node][unist-node]) is a syntactic unit in fst syntax trees.
`ts`
interface Literal extends Node {
value: string | null | undefined
}
Literal represents an abstract interface in fst containing the smallest possible value.
`ts`
interface Parent extends unist.Parent {
children: Child[]
}
Parent ([unist.Parent][unist-parent]) represents an abstract interface in fst containing other nodes (said to
be [children][unist-child]).
Its content is limited to file system content.
`ts`
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.
`ts`
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][parsedpath], file names
include file extensions.
File can be used in directory and root nodes. It cannot contain any children — it is
a [leaf][unist-leaf].
`ts`
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][unist-root] of a [tree][unist-tree], never as a [child][unist-child]. It can
contain directory content.
`ts`
type DirectoryContent = Directory | File
Directory content represents files and subdirectories in a parent directory.
`ts`
type FstNode = NodeMap[keyof NodeMap]
Registered fst nodes.
To register custom nodes, augment NodeMap:
`ts`
declare module '@flex-development/fst' {
interface NodeMap {
customNode: CustomNode
}
}
Union of nodes that can occur in fst.
See also: [InclusiveDescendant][inclusivedescendant]
`ts`
type AnyNode = InclusiveDescendant
Union of [parents][unist-parent] that are [inclusive descendants][descendant] of Root.
See also: [Parents][parents]
`ts`
type AnyParent = Parents
Union of [child][unist-child] nodes that can occur in fst.
See also: [Children][children]
`ts`
type Child = Children
See the [unist glossary][unist-glossary] for more terms.
See the [unist list of utilities][unist-utilities] for more utilities.
- [fst-util-from-fs][fst-util-from-fs] — create trees from file systemsunist-util-builder
- [][unist-util-builder] — build treesunist-util-inspect
- [][unist-util-inspect] — inspect treesunist-util-visit
- [][unist-util-visit] — visit nodes using [preorder][] or [postorder][] traversal
See CONTRIBUTING.md`.
Ideas for new utilities and tools can be posted in [fst/ideas][fst-ideas].
This project has a code of conduct. By interacting with this repository, organization, or
community you agree to abide by its terms.
[children]: https://github.com/flex-development/unist-util-types#childrent
[descendant]: https://github.com/syntax-tree/unist#descendant
[fst-ideas]: https://github.com/flex-development/fst/discussions/new?category=idea
[fst-util-from-fs]: https://github.com/flex-development/fst-util-from-fs
[inclusivedescendant]: https://github.com/flex-development/unist-util-types#inclusivedescendanttree-max-depth
[parents]: https://github.com/flex-development/unist-util-types#parentstree-child
[parsedpath]: https://github.com/flex-development/pathe/blob/main/src/interfaces/parsed-path.mts
[postorder]: https://github.com/syntax-tree/unist#postorder
[preorder]: https://github.com/syntax-tree/unist#preorder
[typescript]: https://www.typescriptlang.org
[unist-child]: https://github.com/syntax-tree/unist#child
[unist-glossary]: https://github.com/syntax-tree/unist#glossary
[unist-leaf]: https://github.com/syntax-tree/unist#leaf
[unist-node]: https://github.com/syntax-tree/unist#node
[unist-parent]: https://github.com/syntax-tree/unist#parent
[unist-root]: https://github.com/syntax-tree/unist#root
[unist-syntax-tree]: https://github.com/syntax-tree/unist#syntax-tree
[unist-tree]: https://github.com/syntax-tree/unist#tree
[unist-util-builder]: https://github.com/flex-development/unist-util-builder
[unist-util-inspect]: https://github.com/flex-development/unist-util-inspect
[unist-util-visit]: https://github.com/flex-development/unist-util-visit
[unist-utilities]: https://github.com/syntax-tree/unist#list-of-utilities
[unist]: https://github.com/syntax-tree/unist