File System

File System

The File System utilities offer a way to organize and query file-system data in renoun. It is a powerful tool that allows you to define a schema for file exports and query those exports using a simple API.

To get started with the File System API, instantiate the Directory class to target a set of files and directories from the file system. You can then use the getEntry / getDirectory / getFile methods to query a specific descendant file or directory:

import { Directory } from 'renoun/file-system'

const posts = new Directory({
  path: 'posts',
  loader: {
    mdx: (path) => import(`./posts/${path}.mdx`),
  },
})

Here we are creating a new Directory instance that targets the posts directory relative to the working directory. We are also specifying a loader for the mdx file extension that will be used to load the file contents using the bundler.

Querying file system entries

import { Directory } from 'renoun/file-system'

const posts = new Directory({
  path: 'posts',
  loader: {
    mdx: (path) => import(`./posts/${path}.mdx`),
  },
})

export default async function Page({ slug }: { slug: string }) {
  const post = await posts.getFile(slug, 'mdx')
  const Content = await post.getExportValue('default')

  return <Content />
}

You can query the entries within the directory to help with generating navigations and index pages. For example, we can include only mdx file extensions to generate an index page of links to all posts using the getEntries method:

import { Directory, withSchema } from 'renoun/file-system'

interface PostType {
  frontmatter: {
    title: string
    date: Date
  }
}

const posts = new Directory({
  path: 'posts',
  include: '*.mdx',
  loader: {
    mdx: withSchema<PostType>((path) => import(`./posts/${path}.mdx`)),
  },
})

export default async function Page() {
  const allPosts = await posts.getEntries()

  return (
    <>
      <h1>Blog</h1>
      <ul>
        {allPosts.map(async (post) => {
          const pathname = post.getPathname()
          const frontmatter = await post.getExportValue('frontmatter')

          return (
            <li key={pathname}>
              <a href={pathname}>{frontmatter.title}</a>
            </li>
          )
        })}
      </ul>
    </>
  )
}

Type checking file exports

To improve type safety, you can utilize the withSchema helper to specify the schema for the file’s exports:

import { Directory, withSchema } from 'renoun/file-system'

interface PostType {
  frontmatter: {
    title: string
    date: Date
  }
}

const posts = new Directory({
  path: 'posts',
  loader: {
    mdx: withSchema<PostType>((path) => import(`./posts/${path}.mdx`)),
  },
})

Now when we call JavaScript#getExportValue and JavaScriptExport#getRuntimeValue we will have stronger type checking and autocomplete.

Schema Validation

You can also apply schema validation using libraries that follow the Standard Schema Spec like Zod, Valibot, or Arktype to ensure file exports conform to a specific schema:

import { Directory, withSchema } from 'renoun/file-system'
import { z } from 'zod'

const posts = new Directory({
  path: 'posts',
  loader: {
    mdx: withSchema(
      {
        frontmatter: z.object({
          title: z.string(),
          date: z.date(),
        }),
      },
      (path) => import(`./posts/${path}.mdx`)
    ),
  },
})

Alternatively, you can define a schema yourself using both TypeScript types and custom validation functions:

import { Directory, withSchema } from 'renoun/file-system'

interface PostType {
  frontmatter: {
    title: string
    date: Date
  }
}

const posts = new Directory({
  path: 'posts',
  loader: {
    mdx: withSchema<PostType>(
      {
        frontmatter: (value) => {
          if (typeof value.title !== 'string') {
            throw new Error('Title is required')
          }

          if (!(value.date instanceof Date)) {
            throw new Error('Date is required')
          }

          return value
        },
      },
      (path) => import(`./posts/${path}.mdx`)
    ),
  },
})

The file system utilities are not limited to MDX files and can be used with any file type. By organizing content and source code into structured collections, you can easily generate static pages and manage complex routing and navigations.

API Reference

FileSystem

FileSystem

Constructors

(options: FileSystemOptions) => FileSystem

Methods

getProjectOptions

() => ProjectOptions

getAbsolutePath

(path: string) => string

getRelativePathToWorkspace

(path: string) => string

getPathname

(path: string, options?: { basePath?: string; rootPath?: string; }) => string

readDirectorySync

(path?: string) => DirectoryEntry[]

readDirectory

(path?: string) => Promise<DirectoryEntry[]>

readFileSync

(path: string) => string

readFile

(path: string) => Promise<string>

isFilePathExcludedFromTsConfig

(filePath: string, isDirectory?: boolean) => boolean

isFilePathGitIgnored

(filePath: string) => boolean

getFileExports

(filePath: string) => Promise<Array<FileExport>>

getFileExportMetadata

(name: string, filePath: string, position: number, kind: SyntaxKind) => Promise<{ name: string; environment: string; jsDocMetadata: { description?: string; tags?: { tagName: string; text?: string; }[]; } | undefined; location: DeclarationLocation; }>

getFileExportText

(filePath: string, position: number, kind: SyntaxKind, includeDependencies?: boolean) => Promise<string>

resolveTypeAtLocation

(filePath: string, position: number, kind: SyntaxKind, filter?: SymbolFilter) => Promise<ResolvedType | undefined>

InferModuleExports

InferModuleExports<Exports>

Utility type that infers the schema output from validator functions or a Standard Schema.

withSchema

{ <Types extends ModuleExports>(): ModuleLoaderWithSchema<Types>; <Types extends ModuleExports>(runtime: ModuleRuntimeLoader<NoInfer<Types>>): ModuleLoaderWithSchema<Types, true>; <Types extends ModuleExports = never, Schema extends ModuleExports = ModuleExports<any>>(schema: IsNever<Types> extends true ? Schema : Partial<ModuleExportValidators<NoInfer<Types>>>, runtime: ModuleRuntimeLoader<IsNever<Types> extends true ? NoInfer<Schema> : NoInfer<Types>>): ModuleLoaderWithSchema<IsNever<Types> extends true ? Schema : ModuleExportValidators<NoInfer<Types>>>; }

Overloads

Provides type inference for the module loader.

Returns
ModuleLoaderWithSchema<Types, false>

A function that resolves the module runtime.

Parameters

runtime *

ModuleRuntimeLoader<NoInfer<Types>>

path *

string

file *

File<any, string, string> | JavaScriptFile<any, Record<string, any>, string, string> | MDXFile<any, Record<string, any>, string, string>
Returns
ModuleLoaderWithSchema<Types, true>

A schema that follows the Standard Schema Spec like Zod, Valibot, and Arktype or custom validation functions to ensure file exports conform to a specific schema.

Parameters

schema *

ModuleExports<any> | Partial<ModuleExportValidators<NoInfer<Types>>>

runtime *

ModuleRuntimeLoader<IsNever<Types> extends true ? NoInfer<Schema> : NoInfer<Types>>

path *

string

file *

File<any, string, string> | JavaScriptFile<any, Record<string, any>, string, string> | MDXFile<any, Record<string, any>, string, string>
Returns
ModuleLoaderWithSchema<IsNever<Types> extends true ? Schema : ModuleExportValidators<NoInfer<Types>>, false>

DefaultModuleTypes

DefaultModuleTypes

Default module types for common file extensions.

Properties

mdx *

{ default: MDXContent; }

default *

MDXContent

InferModuleLoadersTypes

InferModuleLoadersTypes<Loaders>

Infer extension types for all loaders in a module.

LoadersWithRuntimeKeys

LoadersWithRuntimeKeys<Loaders>

Extract keys from runtime‑capable loaders.

"js"

"jsx"

"ts"

"tsx"

"mdx"

LoaderExportNames

LoaderExportNames<Loaders>

All export names made available by a set of runtime‑capable loaders.

Properties

string

string | number | symbol

All export names made available by a set of runtime‑capable loaders.

LoaderExportValue

LoaderExportValue<Loaders, Name>

The value type for a given export name coming from any runtime‑capable loaders.

FileNotFoundError

FileNotFoundError

Error for when a file is not found.

Constructors

(path: string | Array<string>, extension?: any) => FileNotFoundError

FileSystemEntry

FileSystemEntry<DirectoryTypes, Extension>

A directory or file entry.

Directory<DirectoryTypes>FileWithExtension<DirectoryTypes, Extension>

FilePathnameOptions

FilePathnameOptions

Options for the File#getPathname and File#getPathnameSegments methods.

Properties

includeBasePathname

boolean

Whether to include the configured Directory:options.basePathname in the pathname.

includeDirectoryNamedSegment

boolean

Whether to include the directory named segment in the pathname segments e.g. button/button for Button/Button.tsx.

FileOptions

FileOptions<Types, Path>

Options for a file in the file system.

Properties

path *

Path

basePathname

string | null

slugCasing

SlugCasings

depth

number

directory

Directory<Types, WithDefaultTypes<Types>, ModuleLoaders, DirectoryInclude<FileSystemEntry<Types, undefined>, Types>>

File

File<DirectoryTypes, Path, Extension>

A file in the file system.

Constructors

<DirectoryTypes extends Record<string, any>, Path extends string, Extension extends string>(options: FileOptions<DirectoryTypes, Path>) => File<DirectoryTypes, Path, Extension>

Methods

getName

() => string

The intrinsic name of the file.

getBaseName

() => string

The base name of the file e.g. index in index.ts.

getModifierName

() => string | undefined

The modifier name of the file if defined e.g. test in index.test.ts.

getTitle

() => string

The base file name formatted as a title.

getOrder

() => string | undefined

The order of the file if defined.

getExtension

() => Extension

The extension of the file if defined.

getDepth

() => number

Get the depth of the file starting from the root directory.

getSlug

() => string

Get the slug of the file.

getPathname

(options?: FilePathnameOptions) => string

Get the path of this file formatted for routes. The configured slugCasing option will be used to format each segment.

getPathnameSegments

(options?: FilePathnameOptions) => Array<string>

Get the route path segments for this file.

getRelativePathToRoot

() => string

Get the file path relative to the root directory.

getRelativePathToWorkspace

() => string

Get the file path relative to the workspace root.

getAbsolutePath

() => string

Get the absolute file system path.

getBlameUrl

(options?: Pick<GetFileUrlOptions, "ref">) => string

Get the URL to the file git blame for the configured git repository.

getEditUrl

(options?: Pick<GetFileUrlOptions, "ref" | "line">) => string

Get the edit URL to the file source for the configured git repository.

getHistoryUrl

(options?: Pick<GetFileUrlOptions, "ref">) => string

Get the URL to the file history for the configured git repository.

getRawUrl

(options?: Pick<GetFileUrlOptions, "ref">) => string

Get the URL to the raw file contents for the configured git repository.

getSourceUrl

(options?: Pick<GetFileUrlOptions, "ref" | "line">) => string

Get the URL to the file source for the configured git repository.

getEditorUri

() => string

Get the URI to the file source code for the configured editor.

getFirstCommitDate

() => Promise<Date | undefined>

Get the first local git commit date of the file.

getLastCommitDate

() => Promise<Date | undefined>

Get the last local git commit date of the file.

getAuthors

() => Promise<Array<GitAuthor>>

Get the local git authors of the file.

getParent

() => Directory<DirectoryTypes, WithDefaultTypes<DirectoryTypes>, ModuleLoaders, DirectoryInclude<FileSystemEntry<WithDefaultTypes<DirectoryTypes>, undefined>, WithDefaultTypes<DirectoryTypes>>>

Get the parent directory containing this file.

getSiblings

<GroupTypes extends Record<string, any> = DirectoryTypes>(options?: { entryGroup?: EntryGroup<GroupTypes, FileSystemEntry<any>[]>; includeDirectoryNamedSegment?: boolean; }) => Promise<[FileSystemEntry<DirectoryTypes> | undefined, FileSystemEntry<DirectoryTypes> | undefined]>

Get the previous and next sibling entries (files or directories) of the parent directory. If the file is an index or readme file, the siblings will be retrieved from the parent directory.

getText

() => Promise<string>

Get the source text of this file.

FileExportNotFoundError

FileExportNotFoundError

Error for when a file export is not found.

Constructors

(path: string, name: string, className: string) => FileExportNotFoundError

JavaScriptFileExport

JavaScriptFileExport<Value>

A JavaScript file export.

Constructors

<Value>(name: string, file: JavaScriptFile<any, Record<string, any>, string, string>, loader?: ModuleRuntimeLoader<Exports> | WithSchema<Exports> | ModuleLoaderWithSchema<Exports, false>, slugCasing?: SlugCasings) => JavaScriptFileExport<Value>

Methods

init

<Value>(name: string, file: JavaScriptFile<any>, loader?: ModuleLoader<any>, slugCasing?: SlugCasings) => Promise<JavaScriptFileExport<Value>>

getStaticMetadata

() => Promise<{ name: string; environment: string; jsDocMetadata: { description?: string; tags?: { tagName: string; text?: string; }[]; } | undefined; location: DeclarationLocation; } | undefined>

getSlug

() => string

Get the slug of the file export.

getName

() => string

Get the name of the export. Default exports will use the file name or declaration name if available.

getTitle

() => string

The export name formatted as a title.

getDescription

() => string | undefined

Get the JS Doc description of the export.

getTags

() => Array<{ tagName: string; text?: string; }> | undefined

Get the JS Doc tags of the export.

getEnvironment

() => string | undefined

Get the environment of the export.

getText

({ includeDependencies, }?: { includeDependencies?: boolean; }) => Promise<string>

Get the source text of the export, optionally including dependencies.

Note, including dependencies can be expensive to calculate, only use when necessary.

getPosition

() => DeclarationPosition | undefined

Get the start and end position of the export in the file system.

getEditUrl

(options?: Pick<GetFileUrlOptions, "ref">) => string

Get the edit URL to the file export source for the configured git repository.

getSourceUrl

(options?: Pick<GetFileUrlOptions, "ref">) => string

Get the URL to the file export source for the configured git repository.

getEditorUri

() => string

Get the URI to the file export source code for the configured editor.

getType

(filter?: SymbolFilter) => Promise<ResolvedType | undefined>

Get the resolved type of the export.

getRuntimeValue

() => Promise<Value>

Get the runtime value of the export. An error will be thrown if the export is not found or the configured schema validation for this file extension fails.

JavaScriptFileOptions

JavaScriptFileOptions<Types, DirectoryTypes, Path>

Options for a JavaScript file in the file system.

Properties

loader

ModuleRuntimeLoader<Types> | WithSchema<Types> | ModuleLoaderWithSchema<Types, false>

path *

Path

basePathname

string | null

slugCasing

SlugCasings

depth

number

directory

Directory<DirectoryTypes, WithDefaultTypes<DirectoryTypes>, ModuleLoaders, DirectoryInclude<FileSystemEntry<DirectoryTypes, undefined>, DirectoryTypes>>

JavaScriptFile

JavaScriptFile<Types, DirectoryTypes, Path, Extension>

A JavaScript file in the file system.

Constructors

<Types extends ModuleExports<any> | { default: MDXContent; }, DirectoryTypes extends Record<string, any>, Path extends string, Extension extends string>(JavaScriptFileOptions<Types, DirectoryTypes, Path>) => JavaScriptFile<Types, DirectoryTypes, Path, Extension>

Methods

parseExportValue

(name: string, value: any) => any

Parse and validate an export value using the configured schema if available.

getExports

() => Promise<Array<JavaScriptFileExport<Types[Extract<keyof Types, string>]>>>

Get all exports from the JavaScript file.

getExport

<ExportName extends Extract<keyof Types, string>>(name: ExportName) => Promise<JavaScriptFileExport<Types[ExportName]>>

Get a JavaScript file export by name.

getNamedExport

<ExportName extends Extract<keyof Types, string>>(name: ExportName) => Promise<JavaScriptFileExport<Types[ExportName]>>

Get a named export from the JavaScript file.

getDefaultExport

(this: Types extends { default: infer _DefaultType; } ? JavaScriptFile<Types, DirectoryTypes, Path, Extension> : never) => Promise<JavaScriptFileExport<Types extends { default: infer DefaultType; } ? DefaultType : never>>

Get the default export from the JavaScript file.

getExportLocation

(name: string) => Promise<FileExport | undefined>

Get the start position of an export in the JavaScript file.

getExportValue

<ExportName extends Extract<keyof Types, string>>(name: ExportName) => Promise<Types[ExportName]>

Get the runtime value of an export in the JavaScript file.

hasExport

(name: string) => Promise<boolean>

Check if an export exists in the JavaScript file statically or at runtime.

MDXFileExport

MDXFileExport<Value>

An MDX file export.

Constructors

<Value>(name: string, file: MDXFile<any, Record<string, any>, string, string>, loader?: ModuleRuntimeLoader<Exports> | WithSchema<Exports> | ModuleLoaderWithSchema<Exports, false>, slugCasing?: SlugCasings) => MDXFileExport<Value>

Methods

getName

() => string

getTitle

() => string

getSlug

() => string

getEditorUri

() => string

getEditUrl

(options?: Pick<GetFileUrlOptions, "ref">) => string

getSourceUrl

(options?: Pick<GetFileUrlOptions, "ref">) => string

parseExportValue

(name: string, value: any) => any

Parse and validate an export value using the configured schema if available.

getRuntimeValue

() => Promise<Value>

Get the runtime value of the export. An error will be thrown if the export is not found or the configured schema validation for the MDX file fails.

MDXFileOptions

MDXFileOptions<Types, DirectoryTypes, Path>

Options for an MDX file in the file system.

Properties

loader

ModuleRuntimeLoader<Exports> | WithSchema<Exports> | ModuleLoaderWithSchema<Exports, false>

Union of all possible loader types:

  • A direct loader function (path) => Promise<...>
  • An already-invoked withSchema(...) object { schema?: ..., runtime?: ... }
  • The raw withSchema<...> factory function

path *

Path

basePathname

string | null

slugCasing

SlugCasings

depth

number

directory

Directory<DirectoryTypes, WithDefaultTypes<DirectoryTypes>, ModuleLoaders, DirectoryInclude<FileSystemEntry<DirectoryTypes, undefined>, DirectoryTypes>>

MDXFile

MDXFile<Types, DirectoryTypes, Path, Extension>

An MDX file in the file system.

Constructors

<Types extends Record<string, any>, DirectoryTypes extends Record<string, any>, Path extends string, Extension extends string>(MDXFileOptions<{ default: MDXContent; } & Types, DirectoryTypes, Path>) => MDXFile<Types, DirectoryTypes, Path, Extension>

Methods

getExports

() => Promise<Array<MDXFileExport<any>>>

getExport

<ExportName extends "default" | Extract<keyof Types, string>>(name: ExportName) => Promise<MDXFileExport<({ default: MDXContent; } & Types)[ExportName]>>

getNamedExport

<ExportName extends Extract<keyof Types, string>>(name: ExportName) => Promise<MDXFileExport<Types[ExportName]>>

Get a named export from the MDX file.

getDefaultExport

() => Promise<MDXContent>

Get the default export from the MDX file.

hasExport

(name: string) => Promise<boolean>

getExportValue

<ExportName extends "default" | Extract<keyof Types, string>>(name: ExportName) => Promise<({ default: MDXContent; } & Types)[ExportName]>

DirectoryInclude

DirectoryInclude<Entry, Types>

(entry: FileSystemEntry<Types>) => entry is Entry

entry *

FileSystemEntry<Types, undefined>

(entry: FileSystemEntry<Types>) => Promise<boolean> | boolean

entry *

FileSystemEntry<Types, undefined>

string

DirectoryOptions

DirectoryOptions<Types, LoaderTypes, Loaders, Include>
Properties

path

string

Directory path in the workspace.

include

Include

Filter entries with a minimatch pattern or predicate.

loader

Loaders

Extension loaders with or without withSchema.

basePathname

string | null

Base route prepended to descendant getPathname() results.

tsConfigPath

string

Uses the closest tsconfig.json path for static analysis and type-checking.

slugCasing

SlugCasings

Slug casing applied to route segments.

fileSystem

FileSystem

Custom file‑system adapter.

sort

unknown | SortKeyExtractor<ResolveDirectoryIncludeEntries<Include, LoaderTypes>> | SortDescriptorObject<EntryTypes<ResolveDirectoryIncludeEntries<Include, LoaderTypes>>, ResolveDirectoryIncludeEntries<Include, LoaderTypes>, ValidSortKey<EntryTypes<ResolveDirectoryIncludeEntries<Include, LoaderTypes>>> | SortKeyExtractor<ResolveDirectoryIncludeEntries<Include, LoaderTypes>>>

Sort callback applied at each directory depth.

Directory

Directory<Types, LoaderTypes, Loaders, Include>

A directory containing files and subdirectories in the file system.

Constructors

<Types extends InferModuleLoadersTypes<Loaders>, LoaderTypes extends WithDefaultTypes<Types>, Loaders extends ModuleLoaders, Include extends DirectoryInclude<FileSystemEntry<LoaderTypes, undefined>, LoaderTypes>>(options?: DirectoryOptions<Types, LoaderTypes, Loaders, Include>) => Directory<Types, LoaderTypes, Loaders, Include>

Methods

getFileSystem

() => FileSystem

Get the file system for this directory.

getRepository

() => Repository

Get the Repository for this directory.

getDepth

() => number

Get the depth of the directory starting from the root directory.

getFile

{ <const Path extends string, Extension extends ExtractFileExtension<Path> = ExtractFileExtension<Path>>(path: Path): Promise<Extension extends string ? IsJavaScriptLikeExtension<Extension> extends true ? JavaScriptFile<LoaderTypes[Extension], LoaderTypes, string, Extension> : Extension extends "mdx" ? MDXFile<LoaderTypes["mdx"], LoaderTypes, string, Extension> : File<LoaderTypes, Path, Extension> : File<LoaderTypes>>; <ExtensionType extends keyof LoaderTypes | string, const Extension extends ExtensionType | Extension[]>(path: string | string[], extension?: Extension | Extension[]): Promise<Extension extends string ? IsJavaScriptLikeExtension<Extension> extends true ? JavaScriptFile<LoaderTypes[Extension], LoaderTypes, string, Extension> : Extension extends "mdx" ? MDXFile<LoaderTypes["mdx"], LoaderTypes, string, Extension> : File<LoaderTypes, Extension> : File<LoaderTypes>>; }

getDirectory

(path: string | string[]) => Promise<Directory<LoaderTypes>>

Get a directory at the specified path.

getEntry

(path: string | string[]) => Promise<FileSystemEntry<LoaderTypes>>

Get a file or directory at the specified path. Files will be prioritized over directories.

getEntries

(options?: { recursive?: Include extends string ? Include extends `**${string}` ? boolean : undefined : boolean; includeDirectoryNamedFiles?: boolean; includeIndexAndReadmeFiles?: boolean; includeGitIgnoredFiles?: boolean; includeTsConfigExcludedFiles?: boolean; }) => Promise<Array<Include extends string ? Include extends `**${string}` ? Directory<LoaderTypes> | FileWithExtension<LoaderTypes, ExtractFileExtension<Include>> : FileWithExtension<LoaderTypes, ExtractFileExtension<Include>> : Include extends DirectoryInclude<infer FilteredEntry, LoaderTypes> ? FilteredEntry : FileSystemEntry<LoaderTypes>>>

Retrieves all entries (files and directories) within the current directory that are not excluded by Git ignore rules or the closest tsconfig file. Additionally, index and readme files are excluded by default.

getRootPath

() => string

Get the root directory path.

getParent

() => Directory<any, any, any, DirectoryInclude<FileSystemEntry<any, undefined>, any>>

Get the parent directory containing this directory.

getSiblings

<GroupTypes extends Record<string, any> = LoaderTypes>(options?: { entryGroup?: EntryGroup<GroupTypes, FileSystemEntry<any>[]>; }) => Promise<[FileSystemEntry<LoaderTypes> | undefined, FileSystemEntry<LoaderTypes> | undefined]>

Get the previous and next sibling entries (files or directories) of the parent directory.

getSlug

() => string

Get the slug of this directory.

getName

() => string

Get the base name of this directory.

getBaseName

() => string

Get the base name of this directory.

getTitle

() => string

The directory name formatted as a title.

getPathname

(options?: { includeBasePathname?: boolean; }) => string

Get a URL-friendly path to this directory.

getPathnameSegments

(options?: { includeBasePathname?: boolean; }) => Array<string>

Get the route path segments to this directory.

getRelativePathToRoot

() => string

Get the relative path of this directory to the root directory.

getRelativePathToWorkspace

() => string

Get the relative path of the directory to the workspace.

getAbsolutePath

() => string

Get the absolute path of this directory.

getHistoryUrl

(options?: Pick<GetFileUrlOptions, "ref">) => string

Get the URL to the directory history for the configured git repository.

getSourceUrl

(options?: Pick<GetFileUrlOptions, "ref">) => string

Get the URL to the directory source for the configured git repository.

getEditorUri

() => string

Get the URI to the directory source code for the configured editor.

getFirstCommitDate

() => Promise<Date | undefined>

Get the first local git commit date of this directory.

getLastCommitDate

() => Promise<Date | undefined>

Get the last local git commit date of this directory.

getAuthors

() => Promise<Array<GitAuthor>>

Get the local git authors of this directory.

hasEntry

(entry: FileSystemEntry<any> | undefined) => entry is FileSystemEntry<LoaderTypes>

Checks if this directory contains the provided entry.

hasFile

<ExtensionType extends keyof LoaderTypes | string, const Extension extends ExtensionType | Extension[]>(entry: FileSystemEntry<any> | undefined, extension?: Extension | Extension[]) => entry is FileWithExtension<LoaderTypes, Extension>

Checks if this directory contains the provided file.

EntryGroupOptions

EntryGroupOptions<Entries>

Options for an EntryGroup.

Properties

entries *

Entries

EntryGroup

EntryGroup<Types, Entries, Loaders>

A group of file system entries.

Constructors

<Types extends InferModuleLoadersTypes<Loaders>, Entries extends Array<FileSystemEntry<any, undefined>>, Loaders extends ModuleLoaders>(options: EntryGroupOptions<Entries>) => EntryGroup<Types, Entries, Loaders>

Methods

getEntries

(options?: { recursive?: boolean; includeIndexAndReadmeFiles?: boolean; }) => Promise<Entries>

Get all entries in the group.

getEntry

(path: string | string[]) => Promise<FileSystemEntry<Types>>

Get an entry in the group by its path.

getFile

<const Extension extends string | undefined = undefined>(path: string | string[], extension?: Extension | Extension[]) => Promise<Extension extends string ? IsJavaScriptLikeExtension<Extension> extends true ? JavaScriptFile<Types[Extension]> : Extension extends "mdx" ? MDXFile<Types["mdx"]> : File<Types> : File<Types>>

Get a file at the specified path and optional extension(s).

getDirectory

(path: string | string[]) => Promise<Directory<Types>>

Get a directory at the specified path.

isDirectory

<Types extends Record<string, any>>(entry: FileSystemEntry<Types> | undefined) => entry is Directory<Types>

Determines if a FileSystemEntry is a Directory.

Parameters

entry *

FileSystemEntry<Types, undefined> | undefined
Returns
boolean

FileWithExtension

FileWithExtension<Types, Extension>

Determines the type of a FileSystemEntry based on its extension.

File<Types, string, string>JavaScriptFile<Types[Extension], Types, any, Extension>MDXFile<Types["mdx"], Types, any, Extension>JavaScriptFile<Types[Extension[number]], Types, any, Extension[number]>MDXFile<Types["mdx"], Types, any, Extension[number]>

isFile

<Types extends Record<string, any>, const Extension extends StringUnion<keyof Types> | StringUnion<keyof Types>[]>(entry: FileSystemEntry<Types> | undefined, extension?: Extension) => entry is FileWithExtension<Types, Extension>

Determines if a FileSystemEntry is a File and optionally narrows the result based on the provided extensions.

Parameters

entry *

FileSystemEntry<Types, undefined> | undefined

extension

Extension
Returns
boolean

isJavaScriptFile

<FileTypes extends Record<string, any>, DirectoryTypes extends Record<string, any> = Record<string, any>>(entry: FileSystemEntry<DirectoryTypes> | undefined) => entry is JavaScriptFile<FileTypes, DirectoryTypes>

Determines if a FileSystemEntry is a JavaScriptFile.

Parameters

entry *

FileSystemEntry<DirectoryTypes, undefined> | undefined
Returns
boolean

isMDXFile

<FileTypes extends Record<string, any>, DirectoryTypes extends Record<string, any> = Record<string, any>>(entry: FileSystemEntry<DirectoryTypes> | undefined) => entry is MDXFile<FileTypes, DirectoryTypes>

Determines if a FileSystemEntry is an MDXFile.

Parameters

entry *

FileSystemEntry<DirectoryTypes, undefined> | undefined
Returns
boolean

resolveFileFromEntry

<Types extends Record<string, any>, const Extension extends keyof Types & string = string>(entry: FileSystemEntry<Types>, extension?: Extension | readonly Extension[]) => Promise<FileWithExtension<Types, Extension> | undefined>

Attempts to resolve a file from a FileSystemEntry, preferring index and readme for directories. The result can be optionally narrowed by extension.

Parameters

entry *

FileSystemEntry<Types, undefined>

extension

Extension | ReadonlyArray<Extension>
Returns
Promise<FileWithExtension<Types, Extension> | undefined>

SortDescriptor

SortDescriptor<Entry>

unknown

SortKeyExtractor

SortKeyExtractor<Entry>

entry *

Entry
Properties

key *

ValidSortKey<EntryTypes<Entry>> | SortKeyExtractor<Entry>

compare

(a: ExtractComparable<Key>, b: ExtractComparable<Key>) => number

a *

unknown

b *

unknown

direction

"ascending" | "descending"

sortEntries

<ExtensionTypes extends Record<string, any>>(entries: FileSystemEntry<ExtensionTypes>[], descriptor: SortDescriptor<any>) => Promise<void>

Compiles a set of sort descriptors into a sort function.

Parameters

entries *

Array<FileSystemEntry<ExtensionTypes, undefined>>

descriptor *

SortDescriptor<any>
Returns
Promise<void>

createSort

<Entry extends FileSystemEntry<any>, Key extends SortKeyExtractor<Entry> = SortKeyExtractor<Entry>>(key: Key, compare?: (a: ExtractComparable<Key>, b: ExtractComparable<Key>) => number) => SortDescriptorObject<any, Entry, Key>
Parameters

key *

Key

compare

(a: ExtractComparable<Key>, b: ExtractComparable<Key>) => number

a *

string | number | bigint | boolean | Date

b *

string | number | bigint | boolean | Date
Returns
SortDescriptorObject<any, Entry, Key>

MemoryFileSystem

MemoryFileSystem

A file system that stores files in memory.

Constructors

(files: { [path: string]: string; }) => MemoryFileSystem

Methods

createFile

(path: string, content: string) => void

getProjectOptions

() => ProjectOptions

transpileFile

(path: string) => Promise<string>

getAbsolutePath

(path: string) => string

getRelativePathToWorkspace

(path: string) => string

getFiles

() => Map<string, string>

readDirectorySync

(path?: string) => DirectoryEntry[]

readDirectory

(path?: string) => Promise<DirectoryEntry[]>

readFileSync

(path: string) => string

readFile

(path: string) => Promise<string>

isFilePathGitIgnored

(filePath: string) => boolean

NodeFileSystem

NodeFileSystem

Constructors

(options: FileSystemOptions) => NodeFileSystem

Methods

getProjectOptions

() => { tsConfigFilePath: string; }

getAbsolutePath

(path: string) => string

getRelativePathToWorkspace

(path: string) => string

readDirectorySync

(path?: string) => DirectoryEntry[]

readDirectory

(path?: string) => Promise<DirectoryEntry[]>

readFileSync

(path: string) => string

readFile

(path: string) => Promise<string>

isFilePathGitIgnored

(filePath: string) => boolean

Repository

Repository

Constructors

(repository: string | RepositoryConfig) => Repository

Methods

getIssueUrl

(options: GetIssueUrlOptions) => string

Constructs a new issue URL for the repository.

getFileUrl

(options: GetFileUrlOptions) => string

Constructs a URL for a file in the repository.

getDirectoryUrl

(options: GetDirectoryUrlOptions) => string

Constructs a URL for a directory in the repository.