{"id":24309074,"url":"https://github.com/flex-development/fst-util-from-fs","last_synced_at":"2025-04-09T16:13:44.186Z","repository":{"id":272661608,"uuid":"917368331","full_name":"flex-development/fst-util-from-fs","owner":"flex-development","description":"fst utility to create trees from a file system","archived":false,"fork":false,"pushed_at":"2025-04-08T22:21:04.000Z","size":2734,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T16:13:35.481Z","etag":null,"topics":["ast","file-system","fs","fst","unist"],"latest_commit_sha":null,"homepage":"https://github.com/flex-development/fst-util-from-fs","language":"TypeScript","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-15T21:10:01.000Z","updated_at":"2025-04-08T00:01:58.000Z","dependencies_parsed_at":"2025-01-15T22:59:10.698Z","dependency_job_id":"81e70fc5-8936-4d5e-bc0c-3550289c8865","html_url":"https://github.com/flex-development/fst-util-from-fs","commit_stats":null,"previous_names":["flex-development/fst-util-from-fs"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Ffst-util-from-fs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Ffst-util-from-fs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Ffst-util-from-fs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Ffst-util-from-fs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flex-development","download_url":"https://codeload.github.com/flex-development/fst-util-from-fs/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","fs","fst","unist"],"created_at":"2025-01-17T05:12:41.500Z","updated_at":"2025-04-09T16:13:44.166Z","avatar_url":"https://github.com/flex-development.png","language":"TypeScript","funding_links":["https://github.com/sponsors/flex-development"],"categories":[],"sub_categories":[],"readme":"# fst-util-from-fs\n\n[![github release](https://img.shields.io/github/v/release/flex-development/fst-util-from-fs.svg?include_prereleases\\\u0026sort=semver)](https://github.com/flex-development/fst-util-from-fs/releases/latest)\n[![npm](https://img.shields.io/npm/v/@flex-development/fst-util-from-fs.svg)](https://npmjs.com/package/@flex-development/fst-util-from-fs)\n[![codecov](https://codecov.io/gh/flex-development/fst-util-from-fs/branch/main/graph/badge.svg?token=c7gDtTlaw3)](https://codecov.io/gh/flex-development/fst-util-from-fs)\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-util-from-fs.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**[fst][]** utility to create trees from file systems\n\n## Contents\n\n- [What is this?](#what-is-this)\n- [Install](#install)\n- [Use](#use)\n- [API](#api)\n  - [`fromFileSystem([options])`](#fromfilesystemoptions)\n  - [`Options`](#options)\n  - [`Dirent`](#dirent)\n  - [`Extensions`](#extensions)\n  - [`FileSystem`](#filesystem)\n  - [`Filter`](#filter)\n  - [`Filters`](#filters)\n  - [`Handle\u003c[T]\u003e`](#handlet)\n  - [`Handles`](#handles)\n  - [`Sort`](#sort)\n- [Syntax tree](#syntax-tree)\n- [Types](#types)\n- [Contribute](#contribute)\n\n## What is this?\n\nThis package is a utility to create [file system trees][fst].\n\nThis utility that uses file system adapters to recursively read a directory, and create a tree from its contents.\n\n## Install\n\nThis package is [ESM only][esm].\n\nIn Node.js (version 18+) with [yarn][]:\n\n```sh\nyarn add @flex-development/fst-util-from-fs\n```\n\n\u003cblockquote\u003e\n  \u003csmall\u003e\n    See \u003ca href='https://yarnpkg.com/protocol/git'\u003eGit - Protocols | Yarn\u003c/a\u003e\n    \u0026nbsp;for details regarding installing from Git.\n  \u003c/small\u003e\n\u003c/blockquote\u003e\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```ts\nimport { fromFileSystem } from 'https://esm.sh/@flex-development/fst-util-from-fs'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import { fromFileSystem } from 'https://esm.sh/@flex-development/fst-util-from-fs'\n\u003c/script\u003e\n```\n\n## Use\n\n**TODO**: use\n\n## API\n\nThis package exports the following identifiers:\n\n- [`fromFileSystem`](#fromfilesystemoptions)\n\nThere is no default export.\n\n### `fromFileSystem([options])`\n\nCreate a file system tree.\n\n#### Parameters\n\n- `options` ([`Options`](#options), optional) — tree options\n\n#### Returns\n\n([`Root`][fst-root]) file system tree\n\n### `Options`\n\nOptions for creating a file system tree (TypeScript interface).\n\n#### Properties\n\n- `content` (`boolean`, optional) —\n  include file content (populates the `value` field of each [`file` node][fst-file])\n- `depth` (`number`, optional) —\n  maximum search depth (inclusive). a search depth less than `0` will produce an empty tree\n- `extensions` ([`Extensions`](#extensions), optional) —\n  list of file extensions to filter matched files by\n- `filters` ([`Filters`](#filters), optional) —\n  path filters to determine if nodes should be added to the tree\n- `fs` ([`Partial\u003cFileSystem\u003e`](#filesystem), optional) —\n  file system adapter\n- `handles` ([`Handles`](#handles), optional) —\n  node handlers\n- `root` (`URL | string`, optional) —\n  module id of root directory\n  - **default**: [`pathe.cwd() + pathe.sep`][pathe]\n- `sort` ([`Sort`](#sort), optional) —\n  function used to sort child nodes\n\n### `Dirent`\n\nDirectory content entry (TypeScript interface).\n\nThis interface can be augmented to register custom methods and properties.\n\n```ts\ndeclare module '@flex-development/fst-util-from-fs' {\n  interface Dirent {\n    parentPath: string\n  }\n}\n```\n\n#### Properties\n\n- `isDirectory` (`(this: void) =\u003e boolean`) — check if the dirent describes a directory\n- `name` (`string`) — directory content name. if the dirent refers to a file, the file extension should be included\n\n### `Extensions`\n\nUnion of options to filter matched files by file extension (TypeScript type).\n\n```ts\ntype Extensions = Set\u003cstring\u003e | readonly string[] | string\n```\n\n### `FileSystem`\n\nFile system adapter (TypeScript interface).\n\n#### Properties\n\n- `readFileSync` (`(this: void, path: string, encoding: 'utf8') =\u003e string`, optional) —\n  get the contents of the file at `path`\n- `readdirSync` (`(this: void, path: string, options: { withFileTypes: true }) =\u003e readonly Dirent[]`) —\n  read the contents of the directory at `path`\n\n### `Filter`\n\nDetermine if a node for `x` should be added to a file system tree.\n\n#### Parameters\n\n- `x` (`string`) — path to directory or file\n\n#### Returns\n\n(`boolean`) `true` if node for `x` should be added, `false` otherwise\n\n### `Filters`\n\nPath filters to determine if nodes should be added to the tree (TypeScript type).\n\n#### Properties\n\n- `directory` ([`Filter`](#filter), optional) — determine if a `directory` node should be added to the tree\n- `file` ([`Filter`](#filter), optional) — determine if a `file` node should be added to the tree\n\n### `Handle\u003c[T]\u003e`\n\nHandle `node`.\n\n#### Type Parameters\n\n- `T` ([`Child`][fst-child]) — [fst][] child node\n\n#### Parameters\n\n- `node` (`T`) — directory or file node\n- `dirent` ([`Dirent`](#dirent)) — dirent object representing directory or file\n- `parent` ([`Parent`][fst-parent]) — parent node\n- `tree` ([`Root`][fst-root]) — file system tree\n- `fs` ([`FileSystem`](#filesystem)) — file system adapter\n\n#### Returns\n\n(`null | undefined | void`) nothing\n\n### `Handles`\n\nPath filters to determine if nodes should be added to the tree (TypeScript type).\n\n#### Properties\n\n- `directory` ([`Handle\u003cDirectory\u003e`](#handlet), optional) — [directory node][fst-directory] handler\n- `file` ([`Handle\u003cFile\u003e`](#handlet), optional) — [file node][fst-file] handler\n\n### `Sort`\n\nCompare node `a` to `b`.\n\n#### Parameters\n\n- `a` ([`Child`][fst-child]) — current child node\n- `b` ([`Child`][fst-child]) — next child node\n\n#### Returns\n\n(`number`) comparison result\n\n## Syntax tree\n\nThe syntax tree is [fst][].\n\n## Types\n\nThis package is fully typed with [TypeScript][].\n\n## Contribute\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\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[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n\n[esmsh]: https://esm.sh\n\n[fst-child]: https://github.com/flex-development/fst#child\n\n[fst-directory]: https://github.com/flex-development/fst#directory\n\n[fst-file]: https://github.com/flex-development/fst#file\n\n[fst-parent]: https://github.com/flex-development/fst#parent\n\n[fst-root]: https://github.com/flex-development/fst#root\n\n[fst]: https://github.com/flex-development/fst\n\n[pathe]: https://github.com/flex-development/pathe\n\n[typescript]: https://www.typescriptlang.org\n\n[yarn]: https://yarnpkg.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Ffst-util-from-fs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflex-development%2Ffst-util-from-fs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Ffst-util-from-fs/lists"}