📃 Table of Contents

• Features
• Usage
• API
• Changelog
• Support
• License
• Related
• Author

🤖 Features

• 🍃 Type‑safe file path handling via the FilePath<ext> template literal type
• 🚀 Extension validation with isMyFilePath() for case‑insensitive file path checks
• 🛡️ Assertion with error handling using assertMyFilePath(), supporting custom error messages
• 🌿 Conditional file path creation through createMyFilePath(), returning a typed path or empty string
• 🎨 Customisable error formatting powered by the external zing utility

🕵🏼 Usage

Install it by executing any of the following, depending on your preferred package manager:

pnpm add @igorskyflyer/my-file-path
yarn add @igorskyflyer/my-file-path
npm i @igorskyflyer/my-file-path

🤹🏼 API

The module exposes a generic type and 3 generic functions.

Type

type FilePath<ext extends string>

Use this type for compile-time safety.

index.ts

type JsonFile = FilePath<'json'>

const filePathJson: JsonFile = 'abc.json' // works in the IDE
const filePathTxt: JsonFile = 'abc.txt' // will not work in the IDE

Functions

• isMyFilePath()
• createMyFilePath()
• assertMyFilePath

isMyFilePath

function isMyFilePath<Ext extends string>(
  filePath: string,
  extension: Ext
): boolean

Checks whether the provided filepath conforms with the provided file extension.

Generic parameter:

Ext - the file extension to use with the generic, without a leading dot.

Function parameters:

filePath - the filepath to check. extension - the file extension to perform the check with.

Will not throw. Returns a boolean.

createMyFilePath

function createMyFilePath<Ext extends string>(
  filePath: string,
  extension: Ext
): FilePath<Ext>

Checks whether the provided filepath conforms with the provided file extension and returns it if true. Otherwise it returns an empty string.

Generic parameter:

Ext - the file extension to use with the generic, without a leading dot.

Function parameters:

filePath - the filepath to check. extension - the file extension to perform the check with.

Will not throw. Returns a FilePath<Ext>.

assertMyFilePath

function assertMyFilePath<Ext extends string>(
  filePath: string,
  extension: Ext,
  errorMessage?: string
): void

Asserts whether the provided filepath conforms with the provided file extension.

Generic parameter:

Ext - the file extension to use with the generic, without a leading dot.

Function parameters:

filePath - the filepath to check. extension - the file extension to perform the check with. errorMessage - the error message to throw.

Will throw if the filepath doesn't conform the provided extension. Returns a void.

📝 Changelog

📑 The changelog is available here, CHANGELOG.md.

🪪 License

Licensed under the MIT license which is available here, MIT license.

💖 Support

🧬 Related

@igorskyflyer/upath

🎍 Provides a universal way of formatting file-paths in Unix-like and Windows operating systems as an alternative to the built-in path.normalize(). 🧬

@igorskyflyer/windev

🍃 Provides ways of checking whether a path is a legacy Windows device. 💾

@igorskyflyer/my-file-path

🌟 A package that strongly types file paths! 🥊

@igorskyflyer/recursive-readdir

📖 Provides recursive readdir() and readdirSync() functions. 📁

@igorskyflyer/open-resource

📂 Opens a given resource (URL, file, etc.) via the default OS handler. 🔎

👨🏻‍💻 Author

Created by Igor Dimitrijević (@igorskyflyer).