@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;
/**
 * Asserts that `fileurl` (a path or a `file:...` URL) resolves to an
 * existing file.
 */
export declare function filenameFromUrl(fileurl: string): AbsolutePath;
/**
 * Asserts that the _parent_ path of `fileurl` (a path or a `file:...` URL)
 * resolves to an existing directory.
 */
export declare function dirnameFromUrl(fileurl: string): AbsolutePath;
/**
 * Return the absolute path of of `fileurl` (a path or a `file:...` URL) or
 * (if further `paths` are specified) the absolute path of a file relative to
 * it.
 *
 * If no `paths` are specified, this will simply return the {@link AbsolutePath}
 * of `fileurl`:
 *
 * ```ts
 * const thisFile = requireFilename(import.meta.url)
 * // if we write this in "/foo/bar/baz.(ts|js|cjs|mjs)"
 * // `thisFile` will now be "/foo/bar/baz.(ts|js|cjs|mjs)"
 * ```
 *
 * If further `paths` are specified, those will be resolved as relative paths
 * to the original `fileurl` so we can easily write something like this:
 *
 * ```ts
 * const dataFile = requireFilename(import.meta.url, '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, ...).
 *
 * Extension matching is performed that the same instruction can be used in
 * various scenarions (e.g. `.ts` when running dynamically, `.js`, `.mjs` or
 * `.cjs` after transpilation)
 */
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;
//# sourceMappingURL=paths.d.ts.map