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.

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.

$3

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:

``sh
yarn add @flex-development/fst
`

Nodes (abstract)

$3

`ts
interface Node extends unist.Node {}
`

Node ([unist.Node][unist-node]) is a syntactic unit in fst syntax trees.

$3

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

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

$3

`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.

Nodes

$3

`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.

$3

`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].

$3

`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.

Content model

$3

`ts
type DirectoryContent = Directory | File
`

Directory content represents files and subdirectories in a parent directory.

$3

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

Helpers

$3

Union of nodes that can occur in fst.

See also: [InclusiveDescendant][inclusivedescendant]

`ts
type AnyNode = InclusiveDescendant
`

$3

Union of [parents][unist-parent] that are [inclusive descendants][descendant] of Root.

See also: [Parents][parents]

`ts
type AnyParent = Parents
`

$3

Union of [child][unist-child] nodes that can occur in fst.

See also: [Children][children]

`ts
type Child = Children[number]
`

Glossary

See the [unist glossary][unist-glossary] for more terms.

List of utilities

See the [unist list of utilities][unist-utilities] for more utilities.

- [fst-util-from-fs][fst-util-from-fs] — create trees from file systems
- [unist-util-builder][unist-util-builder] — build trees
- [unist-util-inspect][unist-util-inspect] — inspect trees
- [unist-util-visit][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][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