126 lines
2.8 KiB
TypeScript
126 lines
2.8 KiB
TypeScript
import {
|
|
type ExecFileOptionsWithStringEncoding,
|
|
type ExecFileSyncOptionsWithStringEncoding,
|
|
type PromiseWithChild,
|
|
} from 'node:child_process';
|
|
|
|
/**
|
|
Converts a `URL` or path to a path.
|
|
|
|
__Not available in browsers.__
|
|
|
|
@example
|
|
```
|
|
import path from 'node:path';
|
|
import {toPath} from 'unicorn-magic';
|
|
|
|
// `cwd` can be `URL` or a path string.
|
|
const getUnicornPath = cwd => path.join(toPath(cwd), 'unicorn');
|
|
```
|
|
*/
|
|
export function toPath(urlOrPath: URL | string): string;
|
|
|
|
/**
|
|
Finds the root directory of the given path.
|
|
|
|
__Not available in browsers.__
|
|
|
|
On Unix-based systems, the root is always `'/'`.
|
|
On Windows, the root varies and includes the drive letter (e.g., `'C:\\'`).
|
|
|
|
This function operates purely on paths and does not interact with the file system.
|
|
|
|
@param path - The path or URL to check.
|
|
@returns The root directory of the path.
|
|
|
|
@example
|
|
```
|
|
import {rootDirectory} from 'unicorn-magic';
|
|
|
|
console.log(rootDirectory('/Users/x/y/z'));
|
|
//=> '/'
|
|
|
|
console.log(rootDirectory('C:\\Users\\x\\y\\z'));
|
|
//=> 'C:\\'
|
|
```
|
|
*/
|
|
export function rootDirectory(path: string | URL): string;
|
|
|
|
/**
|
|
Creates an iterable for traversing from a given start path up to the root directory.
|
|
|
|
__Not available in browsers.__
|
|
|
|
This function operates purely on paths and does not interact with the file system.
|
|
|
|
@param startPath - The starting path. Can be relative.
|
|
@returns An iterable that iterates over each parent directory up to the root.
|
|
|
|
Tip: To stop iteration before reaching the root, use a `break` statement within a conditional check.
|
|
|
|
@example
|
|
```
|
|
import {traversePathUp} from 'unicorn-magic';
|
|
|
|
for (const directory of traversePathUp('/Users/x/y/z')) {
|
|
console.log(directory);
|
|
//=> '/Users/x/y/z'
|
|
//=> '/Users/x/y'
|
|
//=> '/Users/x'
|
|
//=> '/Users'
|
|
//=> '/'
|
|
}
|
|
```
|
|
*/
|
|
export function traversePathUp(startPath: string | URL): Iterable<string>;
|
|
|
|
/**
|
|
Executes a file.
|
|
|
|
Same as the built-in `execFile` but with:
|
|
- Promise API
|
|
- 10 MB `maxBuffer` instead of 1 MB
|
|
|
|
@example
|
|
```
|
|
import {execFile} from 'unicorn-magic';
|
|
|
|
console.log(await execFile('ls', ['-l']));
|
|
```
|
|
|
|
__Not available in browsers.__
|
|
*/
|
|
export function execFile(
|
|
file: string,
|
|
arguments_: readonly string[],
|
|
options?: ExecFileOptionsWithStringEncoding
|
|
): PromiseWithChild<{
|
|
stdout: string;
|
|
stderr: string;
|
|
}>;
|
|
|
|
/**
|
|
Executes a file synchronously.
|
|
|
|
Same as the built-in `execFileSync` but with:
|
|
- String output instead of buffer (same as `execFile`)
|
|
- Does not output `stderr` to the terminal by default (same as `execFile`)
|
|
- 10 MB `maxBuffer` instead of 1 MB
|
|
|
|
@example
|
|
```
|
|
import {execFileSync} from 'unicorn-magic';
|
|
|
|
console.log(execFileSync('ls', ['-l']));
|
|
```
|
|
|
|
__Not available in browsers.__
|
|
*/
|
|
export function execFileSync(
|
|
file: string,
|
|
arguments_?: readonly string[],
|
|
options?: ExecFileSyncOptionsWithStringEncoding
|
|
): string;
|
|
|
|
export * from './default.js';
|