path-ts extends Node's path module with type safety.
import{join,ext,parse,basename,dirname}from"path-ts"constpath=join("foo","bar","baz")// 'foo/bar/baz'constdir=dirname("foo/bar/baz.txt")// 'foo/bar'constbase=basename("foo/bar/baz.txt")// 'baz.txt'constext=extname("foo/bar/baz.txt")// '.txt'constparsed=parse("/foo/bar/baz.txt")parsed.root// '/'parsed.dir// '/foo/bar'parsed.base// 'baz.txt'parsed.ext// '.txt'parsed.name// 'baz'
yarn add path-ts
# or
npm install path-tsWhen configuring TypeScript, you'll have better results if you enable strict mode in your tsconfig.json:
{
"compilerOptions": {
"strict": true
}
}path-ts uses POSIX path semantics (the / separator) on every platform, including Windows and the browser. This is what lets the literal types — which are always /-based — match the runtime everywhere. If you need Windows (\) semantics, use Node's built-in path.win32 directly.
path-ts depends on Node's built-in path module, however it can be polyfilled in a browser in ESBuild or Webpack allowing you to use the same type-safe path utilities in both the browser and Node.
path-ts provides a fluent API for building absolute paths. This is useful when you want to build paths dynamically.
import{PathBuilder}from"path-ts"constbuilder=PathBuilder.from("/foo")// Builders act like immutable strings that can be appended by calling them like functions...constchildBuilder=builder("bar")console.log(childBuilder.toString())// '/foo/bar'Path Builders can be used to create type-safe path aliases relative to the root of your project:
import{PathBuilder,Join}from"path-ts"import{fileURLToPath}from"node:url"import{resolve}from"node:path"/** * Aliased path to the root of the repository. */exporttypeRepoRootAlias="@your-namespace/repo-root"/** * Compiled directory name for TS output files. */exportconstOutDirectoryName="out"exporttypeOutDirectoryName=typeofOutDirectoryName/** * The directory path of the current file, post-compilation. */const__dirname=dirname(fileURLToPath(import.meta.url))asJoin<[RepoRootAlias, ...OutDirectoryName],"/">/** * The absolute path to the root of the repository. */constRepoRootAbsolutePath=resolve(__dirname, ...PathReflection.map(()=>".."))typeRepoRootAbsolutePath=RepoRootAlias/** * Path builder relative to the repo root. */exportconstrepoRootPathBuilder=createPathBuilderResolver<RepoRootAlias>(RepoRootAbsolutePath)You can then build paths relative to the root of your project in a type-safe way:
import{repoRootPathBuilder}from"@your-namespace/repo-root"constpath=repoRootPathBuilder("src","index.ts")// `@your-namespace/repo-root/src/index.ts`You can create higher-order path builders that are specific to a certain directory in a monorepo:
typeMonoRepoPackageName="package-1"|"package-2"/** * Path builder relative to a specific package's output directory. */exportfunctionpackageOutPathBuilder<PextendsMonoRepoPackageName,Sextendsstring[]>(packageName: P,
...pathSegments: S): PathBuilder<Join<[RepoRootAlias,P,OutDirectoryName, ...S],"/">>&string{returnpackagePathBuilder(packageName,OutDirectoryName, ...pathSegments)}path-ts is honest about where the type-level model and the runtime can drift:
- POSIX only. Types and runtime both assume
/. Windows (\) paths are treated as ordinary characters, not separators. Usenode:path.win32if you need Windows semantics. PathBuilder.fromdoes not model the current working directory. At runtime it resolves relative inputs againstprocess.cwd(), but the type cannot know the cwd, so the type ofPathBuilder.from("relative")stays relative. To get a sound absolute type, start from an absolute path or usecreatePathBuilderResolverwith a bound root.- Very long paths. The recursive normalization types are bounded by the TypeScript instantiation-depth limit. Realistic paths are fine; pathological inputs fall back to
string. parse().namefor dotfiles.extnamecorrectly returns""for dotfiles like.gitignore, but thenamefield ofparse()does not yet special-case the leading dot.
path-ts is licensed under the MIT license. See LICENSE.md for the full text.