{"id":24309077,"url":"https://github.com/flex-development/fst","last_synced_at":"2025-04-09T16:13:50.050Z","repository":{"id":272527190,"uuid":"916898370","full_name":"flex-development/fst","owner":"flex-development","description":"File system tree format","archived":false,"fork":false,"pushed_at":"2025-04-07T14:16:22.000Z","size":2468,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T16:13:42.033Z","etag":null,"topics":["ast","file-system","fst","syntax-tree","unist","unist-spec"],"latest_commit_sha":null,"homepage":"https://github.com/flex-development/fst","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flex-development.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/funding.yml","license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["flex-development"]}},"created_at":"2025-01-15T00:53:18.000Z","updated_at":"2025-04-07T13:45:56.000Z","dependencies_parsed_at":"2025-02-17T14:28:13.518Z","dependency_job_id":"458576ee-f329-4292-8e4b-e105a20745da","html_url":"https://github.com/flex-development/fst","commit_stats":null,"previous_names":["flex-development/fst"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Ffst","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Ffst/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Ffst/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Ffst/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flex-development","download_url":"https://codeload.github.com/flex-development/fst/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248065282,"owners_count":21041872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","file-system","fst","syntax-tree","unist","unist-spec"],"created_at":"2025-01-17T05:12:42.916Z","updated_at":"2025-04-09T16:13:50.017Z","avatar_url":"https://github.com/flex-development.png","language":"JavaScript","funding_links":["https://github.com/sponsors/flex-development"],"categories":[],"sub_categories":[],"readme":"# fst\n\n[![github release](https://img.shields.io/github/v/release/flex-development/fst.svg?include_prereleases\\\u0026sort=semver)](https://github.com/flex-development/fst/releases/latest)\n[![npm](https://img.shields.io/npm/v/@flex-development/fst.svg)](https://npmjs.com/package/@flex-development/fst)\n[![module type: esm](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://github.com/voxpelli/badges-cjs-esm)\n[![license](https://img.shields.io/github/license/flex-development/fst.svg)](LICENSE.md)\n[![conventional commits](https://img.shields.io/badge/-conventional%20commits-fe5196?logo=conventional-commits\\\u0026logoColor=ffffff)](https://conventionalcommits.org)\n[![typescript](https://img.shields.io/badge/-typescript-3178c6?logo=typescript\\\u0026logoColor=ffffff)](https://typescriptlang.org)\n[![vitest](https://img.shields.io/badge/-vitest-6e9f18?style=flat\\\u0026logo=vitest\\\u0026logoColor=ffffff)](https://vitest.dev)\n[![yarn](https://img.shields.io/badge/-yarn-2c8ebb?style=flat\\\u0026logo=yarn\\\u0026logoColor=ffffff)](https://yarnpkg.com)\n\n**F**ile **S**ystem **T**ree.\n\n---\n\n**fst** is a specification for representing file systems as [abstract syntax trees][unist-syntax-tree].\n\nIt implements the [**unist**][unist] spec.\n\n## Contents\n\n- [Introduction](#introduction)\n  - [Where this specification fits](#where-this-specification-fits)\n- [Types](#types)\n- [Nodes (abstract)](#nodes-abstract)\n  - [`Node`](#node)\n  - [`Literal`](#literal)\n  - [`Parent`](#parent)\n- [Nodes](#nodes)\n  - [`Directory`](#directory)\n  - [`File`](#file)\n  - [`Root`](#root)\n- [Content model](#content-model)\n  - [`DirectoryContent`](#directorycontent)\n  - [`FstNode`](#fstnode)\n- [Helpers](#helpers)\n  - [`AnyNode`](#anynode)\n  - [`AnyParent`](#anyparent)\n  - [`Child`](#child)\n- [Glossary](#glossary)\n- [List of utilities](#list-of-utilities)\n- [Contribute](#contribute)\n\n## Introduction\n\nThis document defines a format for representing file systems as abstract syntax trees. Development of fst started in\nJanuary 2025. This specification is written in a [TypeScript][]-like grammar.\n\n### Where this specification fits\n\nfst extends [unist][], a format for syntax trees, to benefit from its [ecosystem of utilities](#list-of-utilities).\n\n## Types\n\nTypeScript users can integrate `fst` type definitions into their project by installing the appropriate packages:\n\n```sh\nyarn add @flex-development/fst\n```\n\n## Nodes (abstract)\n\n### `Node`\n\n```ts\ninterface Node extends unist.Node {}\n```\n\n**Node** ([**unist.Node**][unist-node]) is a syntactic unit in fst syntax trees.\n\n### `Literal`\n\n```ts\ninterface Literal extends Node {\n  value: string | null | undefined\n}\n```\n\n**Literal** represents an abstract interface in fst containing the smallest possible value.\n\n### `Parent`\n\n```ts\ninterface Parent extends unist.Parent {\n  children: Child[]\n}\n```\n\n**Parent** ([**unist.Parent**][unist-parent]) represents an abstract interface in fst containing other nodes (said to\nbe [*children*][unist-child]).\n\nIts content is limited to [file system content](#child).\n\n## Nodes\n\n### `Directory`\n\n```ts\ninterface Directory extends Parent {\n  children: DirectoryContent[]\n  data?: DirectoryData | undefined\n  name: string\n  type: 'directory'\n}\n```\n\n**Directory** ([**Parent**](#parent)) represents a parent directory or subdirectory. Its `name` is relative to its\nparent directory.\n\n**Directory** can be used in [**root**](#root) nodes, as well as other **directory** nodes. Its content model is\n[**directory**](#directorycontent).\n\n### `File`\n\n```ts\ninterface File extends Literal {\n  data?: FileData | undefined\n  name: string\n  type: 'file'\n  value: string | null | undefined\n}\n```\n\n**File** ([**Literal**](#literal)) represents a file.\n\nFile `name`s are relative to the parent directory. Unlike the name property of a [`ParsedPath`][parsedpath], file `name`s\ninclude file extensions.\n\n**File** can be used in [**directory**](#directory) and [**root**](#root) nodes. It cannot contain any children — it is\na [*leaf*][unist-leaf].\n\n### `Root`\n\n```ts\ninterface Root extends Parent {\n  children: DirectoryContent[]\n  data?: RootData | undefined\n  path: string\n  type: 'root'\n}\n```\n\n**Root** ([**Parent**](#parent)) represents the root of a file system.\n\n**Root** can be used as the [*root*][unist-root] of a [*tree*][unist-tree], never as a [*child*][unist-child]. It can\ncontain [**directory content**](#directorycontent).\n\n## Content model\n\n### `DirectoryContent`\n\n```ts\ntype DirectoryContent = Directory | File\n```\n\n**Directory** content represents files and subdirectories in a parent [**directory**](#directory).\n\n### `FstNode`\n\n```ts\ntype FstNode = NodeMap[keyof NodeMap]\n```\n\nRegistered fst nodes.\n\nTo register custom nodes, augment `NodeMap`:\n\n```ts\ndeclare module '@flex-development/fst' {\n  interface NodeMap {\n    customNode: CustomNode\n  }\n}\n```\n\n## Helpers\n\n### `AnyNode`\n\nUnion of nodes that can occur in fst.\n\n**See also**: [`InclusiveDescendant`][inclusivedescendant]\n\n```ts\ntype AnyNode = InclusiveDescendant\u003cRoot\u003e\n```\n\n### `AnyParent`\n\nUnion of [*parents*][unist-parent] that are [*inclusive descendants*][descendant] of [`Root`](#root).\n\n**See also**: [`Parents`][parents]\n\n```ts\ntype AnyParent = Parents\u003cRoot\u003e\n```\n\n### `Child`\n\nUnion of [*child*][unist-child] nodes that can occur in fst.\n\n**See also**: [`Children`][children]\n\n```ts\ntype Child = Children\u003cAnyParent\u003e[number]\n```\n\n## Glossary\n\nSee the [unist glossary][unist-glossary] for more terms.\n\n## List of utilities\n\nSee the [unist list of utilities][unist-utilities] for more utilities.\n\n- [`fst-util-from-fs`][fst-util-from-fs] — create trees from file systems\n- [`unist-util-builder`][unist-util-builder] — build trees\n- [`unist-util-inspect`][unist-util-inspect] — inspect trees\n- [`unist-util-visit`][unist-util-visit] — visit nodes using [preorder][] or [postorder][] traversal\n\n## Contribute\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\nIdeas for new utilities and tools can be posted in [fst/ideas][fst-ideas].\n\nThis project has a [code of conduct](CODE_OF_CONDUCT.md). By interacting with this repository, organization, or\ncommunity you agree to abide by its terms.\n\n[children]: https://github.com/flex-development/unist-util-types#childrent\n\n[descendant]: https://github.com/syntax-tree/unist#descendant\n\n[fst-ideas]: https://github.com/flex-development/fst/discussions/new?category=idea\n\n[fst-util-from-fs]: https://github.com/flex-development/fst-util-from-fs\n\n[inclusivedescendant]: https://github.com/flex-development/unist-util-types#inclusivedescendanttree-max-depth\n\n[parents]: https://github.com/flex-development/unist-util-types#parentstree-child\n\n[parsedpath]: https://github.com/flex-development/pathe/blob/main/src/interfaces/parsed-path.mts\n\n[postorder]: https://github.com/syntax-tree/unist#postorder\n\n[preorder]: https://github.com/syntax-tree/unist#preorder\n\n[typescript]: https://www.typescriptlang.org\n\n[unist-child]: https://github.com/syntax-tree/unist#child\n\n[unist-glossary]: https://github.com/syntax-tree/unist#glossary\n\n[unist-leaf]: https://github.com/syntax-tree/unist#leaf\n\n[unist-node]: https://github.com/syntax-tree/unist#node\n\n[unist-parent]: https://github.com/syntax-tree/unist#parent\n\n[unist-root]: https://github.com/syntax-tree/unist#root\n\n[unist-syntax-tree]: https://github.com/syntax-tree/unist#syntax-tree\n\n[unist-tree]: https://github.com/syntax-tree/unist#tree\n\n[unist-util-builder]: https://github.com/flex-development/unist-util-builder\n\n[unist-util-inspect]: https://github.com/flex-development/unist-util-inspect\n\n[unist-util-visit]: https://github.com/flex-development/unist-util-visit\n\n[unist-utilities]: https://github.com/syntax-tree/unist#list-of-utilities\n\n[unist]: https://github.com/syntax-tree/unist\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Ffst","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflex-development%2Ffst","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Ffst/lists"}