@repka-kit/ts/index.d.ts

Next generation build tools for monorepo: lint, bundle and package your TypeScript projects

// Generated by dts-bundle-generator v8.0.1

import { ChildProcess, SpawnOptions } from 'child_process';
import fg from 'fast-glob';
import { InputPluginOption, Plugin, ResolveIdHook, RollupWatchOptions } from 'rollup';

export type PackageJsonExports = JsonPrimitive | {
	[keyOrCondition: string]: PackageJsonExports;
};
export type JsonPrimitive = boolean | number | string | null;
export type JsonObject = {
	[key: string]: JsonType | JsonPrimitive;
};
export type JsonType = JsonObject | JsonPrimitive;
export type PackageJson = {
	name?: string;
	version?: string;
	type?: string;
	types?: string;
	typings?: string;
	main?: string;
	scripts?: Record<string, string>;
	exports?: PackageJsonExports;
	bin?: string | Record<string, string>;
	dependencies?: Record<string, string>;
	devDependencies?: Record<string, string>;
	peerDependencies?: Record<string, string>;
} & Record<string, JsonType>;
/**
 * Normalized and validated config that is typically built
 * from package.json of the package being linted, bundled or
 * tested
 *
 * The config is designed for Node.js npm packages/libraries or CLI's
 */
export type NodePackageConfig = {
	/**
	 * Name of the package as specified in package.json
	 */
	name: string;
	/**
	 * Version of the package as specified in package.json
	 */
	version: string;
	/**
	 * Entry points of the package that can be imported/executed
	 * by the consumers. These are specified via "exports" value
	 * of the package.json. Entry points represents one or more
	 * chunks to be bundled and need to point to the TypeScript
	 * source code relative to the package root.
	 *
	 * After bundling, the entry points would be written to `./dist`
	 * directory and for every input entry point there is going to be
	 * an output entry point in `./dist/package.json` "exports" value
	 * and those would point to the bundled chunks in the published
	 * version of the package.
	 */
	entryPoints: Array<PackageExportsEntryPoint>;
	/**
	 * Entry points of the package that can be executed using
	 * command line and installed into node_modules/.bin. These
	 * are specified, as usual, via package.json "bin" value.
	 * The paths are relative to the package root and should
	 * point to the TypeScript source code of the bin with
	 * "shebang" at the top.
	 *
	 * The "shebang" is a special comment at the top of the file
	 * that tells the system how to execute the file.
	 *
	 * For example:
	 *
	 * ```TypeScript
	 * #!/usr/bin/env tsx
	 * ```
	 *
	 * The above shebang tells the environment to execute
	 * the file using "tsx" executable - which will transform
	 * the TypeScript source code into JavaScript and execute
	 * it via node.
	 *
	 * The shebang is optional and if not specified - the "bin"
	 * will not be executable at dev-time.
	 *
	 * After bundling, the bin entry points would be written to
	 * `./dist/bin` directory and for every input bin entry point
	 * there is going to be an output bin entry point in
	 * `./dist/package.json` "bin" value and those would point
	 * to the bundled chunks in the published version of the
	 * package.
	 *
	 * After building the package - the bundled version of the
	 * code will have the shebang added automatically and point
	 * to "node".
	 */
	binEntryPoints: Array<PackageBinEntryPoint>;
	/**
	 * Entry points of the package that couldn't be parsed and were
	 * ignored - they should be rendered out as is.
	 */
	ignoredEntryPoints?: Record<string, PackageJsonExports>;
	/**
	 * Bin entry points of the package that couldn't be parsed and were
	 * ignored - they should be rendered out as is.
	 */
	ignoredBinEntryPoints?: Record<string, string>;
	/**
	 * Package dependencies of the package where the key
	 * is package name and value is the version of the package.
	 *
	 * NOTE: Version is as is and can be dependency
	 * manager specific, ie "workspace:*" when pnpm is used
	 */
	dependencies: Record<string, string>;
	/**
	 * Dev-time only dependencies of the package
	 */
	devDependencies: Record<string, string>;
};
/**
 * Represents single bundled entry from package.json exports object
 *
 * ```json
 *   ".": "./src/index.ts",
 *   "./feature": "./src/feature/index.ts",
 *   "./configs/*": {
 *     "bundle": "./src/configs/*.ts",
 *     "default": "./dist/configs/*"
 *   }
 * ```
 * Contains at least 2 entries, where
 * `"."` and `"./feature"` - are entry points,
 * `"./src/index.ts"`, `"./src/feature/index.ts"` - are source paths, etc.
 *
 * This can also expand to more entries depending on the contents of the
 * "./src/configs" directory. The `*.ts` files are going to be bundled because
 * the "bundle" condition is present.
 */
export type PackageExportsEntryPoint = {
	/**
	 * Package entry point, when the "exports" field is a string this
	 * will be "." otherwise it will be the key of the entry point
	 * in the "exports" object.
	 */
	entryPoint: string;
	/**
	 * Path to the module this entry point represents
	 */
	sourcePath: string;
	/**
	 * Path to the output module where the entry point chunk will be written
	 */
	outputPath: string;
	/**
	 * Chunk name generated from the entry point and source path
	 * that can be used to identify the chunk in the bundle when
	 * it's being built by rollup.
	 */
	chunkName: string;
};
/**
 * Represents single entry from package.json bin object
 *
 * ```json
 *   "jest": "./src/bin/jest.ts",
 *   "prettier": "./src/bin/prettier.ts",
 * ```
 */
export type PackageBinEntryPoint = {
	/**
	 * Name of the bin file
	 */
	binName: string;
	/**
	 * Path to the source file of the bin
	 */
	sourceFilePath: string;
	/**
	 * Output format
	 */
	format: "cjs" | "esm";
};
export type BuildEntryPointsResult = {
	entryPoints: PackageExportsEntryPoint[];
	ignoredEntryPoints?: Record<string, PackageJsonExports>;
};
export type BuildBinEntryPointsResult = {
	binEntryPoints: PackageBinEntryPoint[];
	ignoredBinEntryPoints?: Record<string, string>;
};
export type BuilderDeps = {
	buildConfig: () => NodePackageConfig | Promise<NodePackageConfig>;
	readPackageJson: () => PackageJson | Promise<PackageJson>;
	buildEntryPoints: () => BuildEntryPointsResult | Promise<BuildEntryPointsResult>;
	buildBinEntryPoints: () => BuildBinEntryPointsResult | Promise<BuildBinEntryPointsResult>;
};
export type PackageConfigBuilder = (opts: BuilderDeps) => BuilderDeps;
export type CopyOptsExtra = Pick<fg.Options, "cwd" | "deep" | "dot" | "onlyDirectories">;
export type CopyGlobOpts = {
	/**
	 * Source directory
	 */
	source?: string;
	/**
	 * One or more patterns inside directory.
	 *
	 * NOTE: the directory structure of the matched files/directories is going to be retained
	 * relative to the source directory
	 */
	include: string[];
	exclude?: string[];
	destination: string;
	accessError?: "ignore" | "throw" | "overwrite";
	existsError?: "ignore" | "throw" | "overwrite";
	options?: CopyOptsExtra & {
		dryRun?: boolean;
		verbose?: boolean;
	};
};
export type CopyOpts = CopyGlobOpts;
export declare function copyFiles(opts: CopyOpts): Promise<void>;
export type DefaultRollupConfigBuildOpts = {
	external?: string[];
	resolveId?: ResolveIdHook;
	plugins?: InputPluginOption;
	/**
	 * https://esbuild.github.io/api/#minify
	 */
	minify?: boolean;
	analyze?: boolean;
};
export type RollupOptionsBuilder = (opts: RollupOptionsBuilderOpts) => Promise<RollupWatchOptions[]> | RollupWatchOptions[];
export type RollupOptionsBuilderOpts = {
	config: NodePackageConfig;
	defaultRollupConfig: (opts?: DefaultRollupConfigBuildOpts) => RollupWatchOptions;
};
export type TaskOpts<Key extends string, Args, State> = {
	/**
	 * A key identifying task options
	 */
	name: Key;
	/**
	 * Arguments passed by user to task options function
	 */
	args: Args;
	/**
	 * Function that executes the task
	 */
	execute?: TaskExecuteFn<State>;
	/**
	 * Function that executes the task in watch mode
	 */
	watch?: TaskWatchFn<State>;
};
export type TaskExecuteFn<State> = () => Promise<State>;
export type TaskWatchFn<State> = (state: State) => Promise<unknown>;
export type BuiltTaskOpts<Key extends string, Args, State> = TaskOpts<Key, Args, State>;
export type BuildOpts = {
	/**
	 * Extra externals which are not listed in dependencies or those
	 * listed which are not explicitly referenced in the code
	 */
	externals?: string[];
	/**
	 * Module resolution function, in case you have weird dependencies
	 * that do not resolve on their own, have them setup here
	 */
	resolveId?: ResolveIdHook;
	/**
	 * Entries in package.json "exports" represent inputs for Rollup.
	 *
	 * If you have a need fine tune configuration for entries defined
	 * in package.json "exports" prop - you can do that in this callback.
	 */
	buildExportsConfig?: RollupOptionsBuilder;
	/**
	 * Entries in package.json "bin" represent extra inputs for Rollup.
	 * Unlike "exports" - these entries require special handling, because
	 * they can be used as CLI commands during dev-time as well by
	 * consumers.
	 *
	 * If you have a need to fine-tune configuration entries defined
	 * in package.json "bin" prop - you can do that in this callback.
	 */
	buildBinsConfig?: RollupOptionsBuilder;
	/**
	 * If you have a need to create extra bundles with different
	 * non-standard parameters, have a function here return those
	 * configs
	 */
	extraRollupConfigs?: RollupOptionsBuilder;
	/**
	 * Rollup plugins to inject into every bundle config
	 */
	plugins?: Plugin[];
	/**
	 * Override core configuration options that are normally read from package.json
	 */
	packageConfig?: PackageConfigBuilder;
	/**
	 * Override output package.json - the output package.json is built from your
	 * regular package.json, but written to the `./dist` directory. This
	 * package.json should be used to publish your package.
	 *
	 * This eliminates dependencies that were already bundled up to the output
	 * by rollup, but you might want to override some extra details.
	 */
	outputPackageJson?: (packageJson: Record<string, JsonType>) => Record<string, JsonType>;
	/**
	 * One or more copy operations to perform after the build is complete
	 * and the output package.json is written. This will also watch files
	 * for changes and copy them over as they change.
	 */
	copy?: Array<Pick<CopyOpts, "source" | "include" | "exclude" | "destination">>;
};
export declare function buildForNode(opts?: BuildOpts): BuiltTaskOpts<"build", BuildOpts | undefined, RollupWatchOptions[]>;
export type TextFilter = {
	text: string;
	replaceWith?: string;
} | {
	regExp: RegExp;
	extractGroup: number;
} | {
	regExp: RegExp;
	replaceWith?: string;
};
export type TextFilters = TextFilter[];
export declare function createFilter(filters: TextFilters): ((data: string) => string | undefined) | undefined;
export declare function filterAndPrint(childProcess: ChildProcess, filters: TextFilters): ChildProcess;
/**
 * SetDifference (same as Exclude)
 * @desc Set difference of given union types `A` and `B`
 * @example
 *   // Expect: "1"
 *   SetDifference<'1' | '2' | '3', '2' | '3' | '4'>;
 *
 *   // Expect: string | number
 *   SetDifference<string | number | (() => void), Function>;
 */
export declare type SetDifference<A, B> = A extends B ? never : A;
/**
 * Intersection
 * @desc From `T` pick properties that exist in `U`
 * @example
 *   type Props = { name: string; age: number; visible: boolean };
 *   type DefaultProps = { age: number };
 *
 *   // Expect: { age: number; }
 *   type DuplicateProps = Intersection<Props, DefaultProps>;
 */
export declare type Intersection<T extends object, U extends object> = Pick<T, Extract<keyof T, keyof U> & Extract<keyof U, keyof T>>;
/**
 * Diff
 * @desc From `T` remove properties that exist in `U`
 * @example
 *   type Props = { name: string; age: number; visible: boolean };
 *   type DefaultProps = { age: number };
 *
 *   // Expect: { name: string; visible: boolean; }
 *   type DiffProps = Diff<Props, DefaultProps>;
 */
export declare type Diff<T extends object, U extends object> = Pick<T, SetDifference<keyof T, keyof U>>;
/**
 * Assign
 * @desc From `U` assign properties to `T` (just like object assign)
 * @example
 *   type Props = { name: string; age: number; visible: boolean };
 *   type NewProps = { age: string; other: string };
 *
 *   // Expect: { name: string; age: number; visible: boolean; other: string; }
 *   type ExtendedProps = Assign<Props, NewProps>;
 */
export declare type Assign<T extends object, U extends object, I = Diff<T, U> & Intersection<U, T> & Diff<U, T>> = Pick<I, keyof I>;
export type SpawnToPromiseOpts = {
	/**
	 * Specify exit codes which should not result in throwing an error when
	 * the process has finished, e.g. specifying `[0]` means if process finished
	 * with zero exit code then the promise will resolve instead of rejecting.
	 *
	 * Alternatively, specify `inherit` to save status code to the current `process.exitCode`
	 *
	 * Alternatively, completely ignore the exit code (e.g. you follow up and interrogate
	 * the process code manually afterwards)
	 */
	exitCodes: number[] | "inherit" | "any";
};
export type SharedOpts = Pick<SpawnOptions, "cwd">;
export type SpawnArgs<E extends object> = [
	command: string,
	args: ReadonlyArray<string>,
	options: Assign<SpawnOptions, E>
];
export type SpawnOptionsWithExtra<E extends object = SpawnToPromiseOpts> = Assign<SpawnOptions, E>;
export type SpawnParameterMix<E extends object = SpawnToPromiseOpts> = [
	cp: ChildProcess,
	extraOpts: Assign<E, SharedOpts>
] | SpawnArgs<E>;
export declare function isSpawnArgs<E extends object>(args: SpawnParameterMix<E>): args is SpawnArgs<E>;
export declare function spawnWithSpawnParameters<E extends object>(parameters: SpawnParameterMix<E>): {
	child: ChildProcess;
	command: string;
	args: readonly string[];
	opts: Assign<SpawnOptions, E>;
};
export declare function spawnToPromise(...parameters: SpawnParameterMix): Promise<void>;
export type SpawnResultOpts = {
	output?: Array<"stdout" | "stderr"> | [
		"stdout" | "stderr",
		...Array<"stdout" | "stderr">
	];
	buffers?: {
		combined?: string[];
		stdout?: string[];
		stderr?: string[];
	};
} & SpawnToPromiseOpts;
export type SpawnResultReturn = {
	pid?: number;
	output: string[];
	stdout: string;
	stderr: string;
	status: number | null;
	signal: NodeJS.Signals | null;
	error?: Error | undefined;
};
export declare function spawnResult(...parameters: SpawnParameterMix<SpawnResultOpts>): Promise<SpawnResultReturn>;
export declare function spawnOutput(...parameters: SpawnParameterMix<SpawnResultOpts>): Promise<string>;
export declare function spawnOutputConditional(...parameters: SpawnParameterMix<SpawnResultOpts & {
	/**
	 * By default will output to `stderr` when spawn result failed with an error, when
	 * status code is not zero or when `Logger.logLevel` is `debug`
	 */
	shouldOutput?: (result: SpawnResultReturn) => boolean;
}>): Promise<SpawnResultReturn>;
export declare const copy: (opts: {
	source?: string;
	include: string[];
	exclude?: string[];
	destination: string;
}) => BuiltTaskOpts<"copy", {
	source?: string | undefined;
	include: string[];
	exclude?: string[] | undefined;
	destination: string;
}, void>;
export type DeclarationsOpts = {
	/**
	 * Override core configuration options that are normally read from package.json
	 */
	packageConfig?: PackageConfigBuilder;
	/**
	 * Ignore TypeScript errors in dependencies when generating declarations
	 */
	unstable_ignoreTypeScriptErrors?: boolean;
	/**
	 * Skip TypeScript type checking for dependencies
	 */
	unstable_skipDependencies?: string[];
};
export declare function declarations(opts?: DeclarationsOpts): BuiltTaskOpts<"declarations", undefined, void>;
export declare function integrationTest(opts?: {
	processArgs?: string[];
}): BuiltTaskOpts<"integration", undefined, void>;
/**
 * Lint using eslint, no customizations possible, other than
 * via creating custom `eslint.config.mjs` in a directory.
 *
 * `Status: Minimum implemented`
 *
 * TODO: Allow specifying type of package: web app requires
 * different linting compared to a published npm package.
 */
export declare function lint(opts?: {
	processArgs: string[];
}): BuiltTaskOpts<"lint", undefined, void>;
declare const levels: readonly [
	"debug",
	"info",
	"warn",
	"error",
	"fatal"
];
export type LogLevel = typeof levels[number];
export type Params = Parameters<typeof console.log>;
export type Logger = {
	logLevel: LogLevel;
	debug(...params: Params): void;
	info(...params: Params): void;
	log(...params: Params): void;
	tip(...params: Params): void;
	warn(...params: Params): void;
	error(...params: Params): void;
	fatal(...params: Params): void;
};
export declare const createLogger: (deps?: {
	getVerbosityConfig: () => "debug" | "info" | "warn" | "error" | "fatal" | "off";
	log: (message?: any, ...optionalParams: any[]) => void;
	error: (message?: any, ...optionalParams: any[]) => void;
	shouldEnableTip: () => boolean;
}) => Logger;
export declare const configureDefaultLogger: (factory: () => Logger) => void;
/**
 * Default logger instance can be configured once at startup
 */
export declare const logger: Logger;
export type BivarianceHack<Args extends unknown[], Result> = {
	bivarianceHack(...args: Args): Result;
}["bivarianceHack"];
export declare function unitTest(opts?: {
	processArgs: string[];
}): BuiltTaskOpts<"test", undefined, void>;
export type TaskOf<T extends BivarianceHack<unknown[], TaskOpts<string, unknown, any>>> = ReturnType<T>;
export type LintTask = TaskOf<typeof lint>;
export type BuildForNodeTask = TaskOf<typeof buildForNode>;
export type UnitTestTask = TaskOf<typeof unitTest>;
export type IntegrationTestTask = TaskOf<typeof integrationTest>;
export type DeclarationsTask = TaskOf<typeof declarations>;
export type CopyTask = TaskOf<typeof copy>;
export type AllTaskTypes = LintTask | BuildForNodeTask | UnitTestTask | IntegrationTestTask | DeclarationsTask | CopyTask;
export type Task = AllTaskTypes | TaskExecuteFn<unknown>;
/**
 * Declare how your package is linted, built, bundled and published
 * by specifying task parameters specific to your package.
 *
 * The order of execution of tasks is bespoke and depends on the task.
 *
 * Some tasks also accept parameters from process.argv, for example
 * `lint` or `test` allow you to specify which files need linting or
 * testing. Use `--help` parameter to determine what is possible.
 */
export declare function pipeline<Args extends [
	Task,
	...Task[]
]>(...tasks: Args): Promise<void>;
export declare function runTsScript(opts: {
	location: string;
	importMetaUrl?: URL;
	args?: string[];
}): Promise<SpawnResultReturn>;

export {};