@plugjs/plug/dist/paths.d.ts

PlugJS Build System ===================

/** A _branded_ `string` representing an _absolute_ path name */
export type AbsolutePath = string & {
    __brand_absolute_path: never;
};
/** Resolve a path into an {@link AbsolutePath} */
export declare function resolveAbsolutePath(directory: AbsolutePath, ...paths: string[]): AbsolutePath;
/**
 * Resolve a path as a relative path to the directory specified, returning the
 * relative child path or `undefined` if the specified path was not a child.
 *
 * The `path` specified here _could_ also be another {@link AbsolutePath}
 * therefore something like this will work:
 *
 * ```
 * resolveRelativeChildPath('/foo', '/foo/bar')
 * // will yield `bar`
 * ```
 */
export declare function resolveRelativeChildPath(directory: AbsolutePath, ...paths: string[]): string | undefined;
/**
 * Asserts that a path is a relative path to the directory specified, failing
 * the build if it's not (see also {@link resolveRelativeChildPath}).
 */
export declare function assertRelativeChildPath(directory: AbsolutePath, ...paths: string[]): string;
/** Checks that the specified path is an {@link AbsolutePath} */
export declare function isAbsolutePath(path: string): path is AbsolutePath;
/** Asserts that the specified path is an {@link AbsolutePath} */
export declare function assertAbsolutePath(p: string): asserts p is AbsolutePath;
/** Return the {@link AbsolutePath} parent of another */
export declare function getAbsoluteParent(path: AbsolutePath): AbsolutePath;
/**
 * Return the {@link process.cwd() | current working directory} as an
 * {@link AbsolutePath}.
 */
export declare function getCurrentWorkingDirectory(): AbsolutePath;
/**
 * Return the _common_ path amongst all specified paths.
 *
 * While the first `path` _must_ be an {@link AbsolutePath}, all other `paths`
 * can be _relative_ and will be resolved against the first `path`.
 */
export declare function commonPath(path: AbsolutePath, ...paths: string[]): AbsolutePath;
/** Return the equivalent of `__filename` from our `__fileurl` pseudo variable */
export declare function filenameFromUrl(__fileurl: string): AbsolutePath;
/** Return the equivalent of `__dirname` from our `__fileurl` pseudo variable */
export declare function dirnameFromUrl(__fileurl: string): AbsolutePath;
/**
 * Return the absolute path of a file relative to the given `__fileurl`, where
 * `__fileurl` is either CommonJS's own `__filename` variable, or EcmaScript's
 * `import.meta.url` (so either an absolute path name, or a `file:///...` url).
 *
 * If further `paths` are specified, those will be resolved as relative paths
 * to the original `__fileurl` so we can easily write something like this:
 *
 * ```
 * const dataFile = requireFilename(__fileurl, 'data.json')
 * // if we write this in "/foo/bar/baz.(ts|js|cjs|mjs)"
 * // `dataFile` will now be "/foo/bar/data.json"
 * ```
 */
export declare function requireFilename(__fileurl: string, ...paths: string[]): AbsolutePath;
/**
 * Return the absolute path of a file which can be _required_ or _imported_
 * by Node (or forked to via `child_process.fork`).
 *
 * This leverages {@link requireFilename} to figure out the starting point where
 * to look for files, and will _try_ to match the same extension of `__fileurl`
 * (so, `.ts` for `ts-node`, `.mjs` for ESM modules, ...).
 */
export declare function requireResolve(__fileurl: string, module: string): AbsolutePath;
/**
 * Resolves the specified path as an {@link AbsolutePath} and checks it is a
 * _file_, returning `undefined` if it is not.
 */
export declare function resolveFile(path: AbsolutePath, ...paths: string[]): AbsolutePath | undefined;
/**
 * Resolves the specified path as an {@link AbsolutePath} and checks it is a
 * _directory_, returning `undefined` if it is not.
 */
export declare function resolveDirectory(path: AbsolutePath, ...paths: string[]): AbsolutePath | undefined;