@reliverse/pathkit 1.0.6 → 1.1.1

package/README.md

@@ -1,45 +1,41 @@
 # pathkit • cross‑platform path manipulation
 
-> @reliverse/pathkit is a slash‑consistent, cross‑platform path manipulation—drop‑in for node:path, always POSIX forward slash. @reliverse/pathkit-plus is a utility library which extends the core library with a set of functions for manipulating file paths.
+> @reliverse/pathkit is a slash‑consistent, cross‑platform path manipulation, with POSIX forward slash, drop‑in for node:path and unjs/pathe. This library extends the node:path module with a set of functions for manipulating file paths.
 
 [sponsor](https://github.com/sponsors/blefnk) • [discord](https://discord.gg/Pb8uKbwpsJ) • [npm](https://npmjs.com/package/@reliverse/pathkit) • [repo](https://github.com/reliverse/pathkit)
 
 ## Key Features
 
-- 🔹 **`node:path` on Steroids** – `@reliverse/pathkit`: drop in and replace `node:path` instantly.
-- ➕ **`unjs/pathe` on Steroids** – `@reliverse/pathkit-plus`: alias resolution, import parsing, and more.
-- 🌀 **Always `/`** – POSIX separators 100% of the time (buh‑bye `\\`).
-- ⚙️ **Node.js API compatible** – familiar methods, no learning curve.
-- 🚀 **Modern & Fast** – TypeScript, pure ESM, Bun & Node‑ready.
-- 🧠 **Predictable & Testable** – deterministic output across Windows / macOS / Linux.
+- 🔹 **drop in** and replace `node:path` and `unjs/pathe` instantly
+- ➕ **`unjs/pathe` on steroids** – alias resolution, import parsing, and more
+- 🌀 **always `/`** – posix separators 100% of the time (buh‑bye `\\`)
+- ⚙️ **node.js api compatible** – familiar methods, no learning curve
+- 🚀 **modern & fast** – typescript, pure esm, bun & node‑ready
+- 🧠 **predictable & testable** – deterministic output across windows / macos / linux
+- 🧼 **no dependencies** – just better path api + couple of cool utilities = [4.2 kB](https://bundlephobia.com/package/@reliverse/pathkit@latest)
 
 ## Installation
 
 ```bash
 # bun • pnpm • yarn • npm
 bun add @reliverse/pathkit
-bun add -D @reliverse/pathkit-plus
 ```
 
-_In most cases_ you may need to install `@reliverse/pathkit` as **regular dependency**.
-_In most cases_ you may need to install `@reliverse/pathkit-plus` as **dev dependency**.
-
 **Migrate**:
 
 ```bash
-bun rm pathe
 # soon:
 # bun add -D @reliverse/dler
-# bun dler pathkit path-to-pathkit
-# bun dler pathkit pathe-to-pathkit
+# bun dler migrate --lib path-to-pathkit
+# bun dler migrate --lib pathe-to-pathkit
 ```
 
-### `pathkit` vs `pathkit-plus`
+### `unjs/pathe` vs `@reliverse/pathkit`
 
 | Package | What you get | When to use |
 |---------|--------------|-------------|
-| **`@reliverse/pathkit`** | Core path API (POSIX everywhere) | You only need a drop‑in for `node:path` |
-| **`@reliverse/pathkit-plus`** | Everything in `pathkit` **+** advanced utilities | You need alias resolution, import transforms, etc. |
+| **`pathe`** | Path API only (with POSIX everywhere) | You only need a drop‑in for `node:path` |
+| **`pathkit`** | Everything in `pathe` **+** advanced utilities | You need alias resolution, import transforms, etc. |
 
 ## Why Pathkit? — The Problem with Native Paths
 
@@ -92,16 +88,16 @@ console.log(join("users", "blefnk"));    // → "users/blefnk"
 
 Say goodbye to `process.platform` conditionals 👋.
 
-## pathkit-plus Features
+## pathkit advanced features
 
-`@reliverse/pathkit-plus` extends the core functionality with powerful utilities for working with imports, aliases, and more.
+`@reliverse/pathkit` extends the core functionality of `node:path` with powerful utilities for working with imports, aliases, and more.
 
 ### Import/Export Analysis
 
 The `getFileImportsExports` function provides detailed analysis of ES module imports and exports:
 
 ```ts
-import { getFileImportsExports } from "@reliverse/pathkit-plus";
+import { getFileImportsExports } from "@reliverse/pathkit";
 
 const code = `
 import { ref } from "vue";
@@ -152,7 +148,7 @@ Features:
 Convert between different path formats:
 
 ```ts
-import { convertImportPaths } from "@reliverse/pathkit-plus";
+import { convertImportPaths } from "@reliverse/pathkit";
 
 await convertImportPaths({
   baseDir: "./src",
@@ -166,7 +162,7 @@ await convertImportPaths({
 ### Extension Conversion
 
 ```ts
-import { convertImportExtensionsJsToTs } from "@reliverse/pathkit-plus";
+import { convertImportExtensionsJsToTs } from "@reliverse/pathkit";
 
 await convertImportExtensionsJsToTs({
   dirPath: "./src",
@@ -181,7 +177,7 @@ import {
   normalizeAliases,
   resolveAlias,
   reverseResolveAlias
-} from "@reliverse/pathkit-plus";
+} from "@reliverse/pathkit";
 
 const aliases = { "@/": "/src/", "~/": "/home/user/" };
 
@@ -200,13 +196,11 @@ console.log(reverseResolveAlias("/src/utils", aliases));  // "@/utils"
 ```ts
 import {
   filename,               // Strip extension
-  extractPackageName,     // Get package name from import
   normalizeQuotes,        // Standardize quote style
   matchesGlob            // Test glob patterns
-} from "@reliverse/pathkit-plus";
+} from "@reliverse/pathkit";
 
 console.log(filename("/path/component.vue"));     // "component"
-console.log(extractPackageName("@scope/pkg"));    // "@scope/pkg"
 console.log(normalizeQuotes("import 'pkg'"));     // 'import "pkg"'
 console.log(matchesGlob("file.ts", "**/*.ts"));  // true
 ```

package/bin/mod.d.ts

@@ -1,44 +1,232 @@
 import type { PlatformPath } from "node:path";
-import { delimiter, posix, win32 } from "./pathkit-impl/impl.js";
-import { sep, normalize, join, resolve, normalizeString, isAbsolute, toNamespacedPath, extname, relative, dirname, format, basename, parse } from "./pathkit-impl/internal/path.js";
-import { normalizeWindowsPath } from "./pathkit-impl/internal/win.js";
-import { normalizeAliases, resolveAlias, reverseResolveAlias, filename } from "./pathkit-impl/utils.js";
-type ParsedPath = {
+declare const normalizedAliasSymbol: unique symbol;
+interface NormalizedRecord extends Record<string, string> {
+    [normalizedAliasSymbol]?: true;
+}
+export interface ParsedPath {
     root: string;
     dir: string;
     base: string;
     ext: string;
     name: string;
-};
-type FormatInputPathObject = {
+}
+export interface FormatInputPathObject {
     root?: string;
     dir?: string;
     base?: string;
     ext?: string;
     name?: string;
+}
+type PathExtFilter = "js" | "ts" | "none" | "js-ts-none";
+type ImportExtType = "js" | "ts" | "none";
+/**
+ * removes directories with recursive force option
+ */
+declare function cleanDirs(dirs: string[]): Promise<void>;
+/**
+ * recursively copies a directory and its contents
+ */
+declare function copyDir(src: string, dest: string): Promise<void>;
+/**
+ * normalizes windows paths to use forward slashes
+ */
+declare function normalizeWindowsPath(input?: string): string;
+declare const sep = "/";
+/**
+ * normalizes a path, resolving . and .. segments
+ */
+declare const normalize: (path: string) => string;
+/**
+ * joins path segments with proper normalization
+ */
+declare const join: (...segments: string[]) => string;
+/**
+ * resolves path to an absolute path
+ */
+declare const resolve: (...args: string[]) => string;
+/**
+ * checks if path is absolute
+ */
+declare const isAbsolute: (p: string) => boolean;
+/**
+ * converts path to namespaced path for windows
+ */
+declare const toNamespacedPath: (p: string) => string;
+/**
+ * gets file extension including the dot
+ */
+declare const extname: (p: string) => string;
+/**
+ * gets relative path from one path to another
+ */
+declare const relative: (from: string, to: string) => string;
+/**
+ * gets directory name from path
+ */
+declare const dirname: (p: string) => string;
+/**
+ * formats object parts into a path string
+ */
+declare const format: (p: FormatInputPathObject) => string;
+/**
+ * gets base filename from path
+ */
+declare const basename: (p: string, ext?: string) => string;
+/**
+ * parses a path into its components
+ */
+declare const parse: (p: string) => ParsedPath;
+/**
+ * gets filename without extension
+ */
+declare function filename(pathString: string): string | undefined;
+/**
+ * normalizes alias records and optimizes nested aliases
+ */
+declare function normalizeAliases(aliases: Record<string, string>): NormalizedRecord;
+/**
+ * resolves a path using aliases
+ */
+declare function resolveAlias(path: string, aliases: Record<string, string>): string;
+/**
+ * finds all alias paths that could resolve to the given path
+ */
+declare function reverseResolveAlias(path: string, aliases: Record<string, string>): string[];
+/**
+ * converts aliased path to relative path
+ */
+declare function convertStringAliasRelative({ importPath, importerFile, pathPattern, targetDir, }: {
+    importPath: string;
+    importerFile: string;
+    pathPattern: string;
+    targetDir: string;
+}): Promise<string>;
+/**
+ * main function to convert import paths from aliases to relative paths
+ */
+declare function convertImportsAliasToRelative({ targetDir, aliasToReplace, // e.g. @, ~, @/*, ~/*
+pathExtFilter, }: {
+    targetDir: string;
+    aliasToReplace: string;
+    pathExtFilter: PathExtFilter;
+}): Promise<{
+    file: string;
+    changes: {
+        from: string;
+        to: string;
+    }[];
+}[]>;
+/**
+ * converts extensions in import paths from one format to another
+ */
+declare function convertImportsExt({ targetDir, extFrom, extTo, }: {
+    targetDir: string;
+    extFrom: ImportExtType;
+    extTo: ImportExtType;
+}): Promise<{
+    file: string;
+    changes: {
+        from: string;
+        to: string;
+    }[];
+}[]>;
+/**
+ * strips a specified number of segments from the beginning of a path
+ * @param path - The path to strip segments from
+ * @param count - Number of segments to strip (default: 1)
+ * @param alias - Optional alias to preserve (e.g. "@", "~")
+ * @returns The path with the specified number of segments removed
+ */
+declare function stripPathSegments(path: string, count?: number, alias?: string): string;
+/**
+ * recursively processes files in a directory to strip path segments from their contents
+ * @param targetDir - The directory to process
+ * @param segmentsToStrip - Number of segments to strip from paths
+ * @param alias - Optional alias to preserve (e.g. "@", "~")
+ * @param extensionsToProcess - Array of file extensions to process (default: EXTENSIONS)
+ * @returns Array of processed files and their changes
+ */
+declare function stripPathSegmentsInDirectory({ targetDir, segmentsToStrip, alias, extensionsToProcess, }: {
+    targetDir: string;
+    segmentsToStrip: number;
+    alias?: string;
+    extensionsToProcess?: string[];
+}): Promise<{
+    file: string;
+    changes: {
+        from: string;
+        to: string;
+    }[];
+}[]>;
+/**
+ * attaches path segments to an existing path
+ * @param path - The base path to attach segments to
+ * @param segments - The segments to attach
+ * @param options - Configuration options
+ * @returns The path with segments attached
+ */
+declare function attachPathSegments(path: string, segments: string | string[], options?: {
+    position?: "before" | "after";
+    normalize?: boolean;
+    ensureSlash?: boolean;
+    preserveRoot?: boolean;
+    preserveAlias?: string;
+}): string;
+/**
+ * recursively processes files in a directory to attach path segments to import statements
+ * @param targetDir - The directory to process
+ * @param segments - The segments to attach
+ * @param options - Configuration options for path segment attachment
+ * @param extensionsToProcess - Array of file extensions to process (default: EXTENSIONS)
+ * @returns Array of processed files and their changes
+ */
+declare function attachPathSegmentsInDirectory({ targetDir, segments, options, extensionsToProcess, }: {
+    targetDir: string;
+    segments: string | string[];
+    options?: Parameters<typeof attachPathSegments>[2];
+    extensionsToProcess?: string[];
+}): Promise<{
+    file: string;
+    changes: {
+        from: string;
+        to: string;
+    }[];
+}[]>;
+declare const _pathBase: {
+    sep: string;
+    normalize: (path: string) => string;
+    join: (...segments: string[]) => string;
+    resolve: (...args: string[]) => string;
+    isAbsolute: (p: string) => boolean;
+    dirname: (p: string) => string;
+    basename: (p: string, ext?: string) => string;
+    extname: (p: string) => string;
+    format: (p: FormatInputPathObject) => string;
+    parse: (p: string) => ParsedPath;
+    toNamespacedPath: (p: string) => string;
+    relative: (from: string, to: string) => string;
+    filename: typeof filename;
 };
-export { basename, delimiter, dirname, extname, filename, format, isAbsolute, join, normalize, normalizeAliases, normalizeString, normalizeWindowsPath, parse, posix, relative, resolve, resolveAlias, reverseResolveAlias, sep, toNamespacedPath, win32, type ParsedPath, type FormatInputPathObject, type PlatformPath, };
-declare const pathObj: {
-    readonly basename: (path: string, ext?: string) => string;
-    readonly delimiter: ":" | ";";
-    readonly dirname: (path: string) => string;
-    readonly extname: (path: string) => string;
-    readonly filename: typeof filename;
-    readonly format: (pathObject: FormatInputPathObject) => string;
-    readonly isAbsolute: (path: string) => boolean;
-    readonly join: (...paths: string[]) => string;
-    readonly normalize: (path: string) => string;
-    readonly normalizeAliases: typeof normalizeAliases;
-    readonly normalizeString: typeof normalizeString;
-    readonly normalizeWindowsPath: typeof normalizeWindowsPath;
-    readonly parse: (path: string) => ParsedPath;
-    readonly posix: PlatformPath;
-    readonly relative: (from: string, to: string) => string;
-    readonly resolve: (...paths: string[]) => string;
-    readonly resolveAlias: typeof resolveAlias;
-    readonly reverseResolveAlias: typeof reverseResolveAlias;
-    readonly sep: "/";
-    readonly toNamespacedPath: (path: string) => string;
-    readonly win32: PlatformPath;
+declare const path: PlatformPath & {
+    sep: string;
+    normalize: (path: string) => string;
+    join: (...segments: string[]) => string;
+    resolve: (...args: string[]) => string;
+    isAbsolute: (p: string) => boolean;
+    dirname: (p: string) => string;
+    basename: (p: string, ext?: string) => string;
+    extname: (p: string) => string;
+    format: (p: FormatInputPathObject) => string;
+    parse: (p: string) => ParsedPath;
+    toNamespacedPath: (p: string) => string;
+    relative: (from: string, to: string) => string;
+    filename: typeof filename;
+} & {
+    posix: PlatformPath;
+    win32: PlatformPath;
 };
-export default pathObj;
+declare const win32: PlatformPath;
+declare const delimiter: string;
+export type { PlatformPath, PathExtFilter, ImportExtType };
+export { _pathBase as posix, win32, basename, delimiter, dirname, extname, filename, format, isAbsolute, join, normalize, parse, relative, resolve, sep, toNamespacedPath, normalizeAliases, resolveAlias, reverseResolveAlias, normalizeWindowsPath, cleanDirs, copyDir, convertStringAliasRelative, convertImportsAliasToRelative, convertImportsExt, stripPathSegments, stripPathSegmentsInDirectory, attachPathSegments, attachPathSegmentsInDirectory, };
+export default path;