tempy/index.d.ts

Get a random temporary file or directory path

import {type Buffer} from 'node:buffer';
import {type MergeExclusive, type TypedArray} from 'type-fest';

export type BaseOptions = {
	/**
	The name of a directory inside the OS temporary directory to create the temporary file or directory in. The directory is created automatically if it doesn't exist.

	By default, temporary files and directories are created directly inside the OS temporary directory. This option lets you group related temporary files into a subdirectory.

	Useful for organizing temporary files by app or task, making cleanup and debugging easier.

	@example
	```
	import {temporaryFile} from 'tempy';

	temporaryFile({parentDirectory: 'my-app'});
	//=> '/private/var/folders/3x/jf5977fn79jbglr7rk0tq4d00000gn/T/my-app/4f504b9edb5ba0e89451617bf9f971dd'
	```
	*/
	readonly parentDirectory?: string;

	/**
	An absolute path to use as the base directory for temporary files and directories, instead of the OS temporary directory.

	_You usually won't need this option. Prefer the `parentDirectory` option instead._

	This is useful for niche use-cases like different filesystem mounts or journaling filesystems.

	The directory is created automatically if it doesn't exist.

	@example
	```
	import {temporaryFile} from 'tempy';

	temporaryFile({rootDirectory: '/mnt/fast-storage/tmp'});
	//=> '/mnt/fast-storage/tmp/4f504b9edb5ba0e89451617bf9f971dd'
	```
	*/
	readonly rootDirectory?: string;
};

export type FileOptions = MergeExclusive<
{
	/**
	File extension.

	Mutually exclusive with the `name` option.

	_You usually won't need this option. Specify it only when actually needed._
	*/
	readonly extension?: string;
},
{
	/**
	Filename.

	Mutually exclusive with the `extension` option.

	_You usually won't need this option. Specify it only when actually needed._
	*/
	readonly name?: string;
}
> & BaseOptions;

export type DirectoryOptions = {
	/**
	Directory prefix.

	_You usually won't need this option. Specify it only when actually needed._

	Useful for testing by making it easier to identify cache directories that are created.
	*/
	readonly prefix?: string;
} & BaseOptions;

/**
The temporary path created by the function. Can be asynchronous.
*/
export type TaskCallback<ReturnValueType> = (temporaryPath: string) => Promise<ReturnValueType> | ReturnValueType;

/**
Get a temporary file path you can write to.

@example
```
import {temporaryFile, temporaryDirectory} from 'tempy';

temporaryFile();
//=> '/private/var/folders/3x/jf5977fn79jbglr7rk0tq4d00000gn/T/4f504b9edb5ba0e89451617bf9f971dd'

temporaryFile({extension: 'png'});
//=> '/private/var/folders/3x/jf5977fn79jbglr7rk0tq4d00000gn/T/a9fb0decd08179eb6cf4691568aa2018.png'

temporaryFile({name: 'unicorn.png'});
//=> '/private/var/folders/3x/jf5977fn79jbglr7rk0tq4d00000gn/T/f7f62bfd4e2a05f1589947647ed3f9ec/unicorn.png'

temporaryDirectory();
//=> '/private/var/folders/3x/jf5977fn79jbglr7rk0tq4d00000gn/T/2f3d094aec2cb1b93bb0f4cffce5ebd6'
```
*/
export function temporaryFile(options?: FileOptions): string;

/**
The `callback` resolves with a temporary file path you can write to. The file is automatically cleaned up after the callback is executed.

@returns A promise that resolves after the callback is executed and the file is cleaned up.

@example
```
import {temporaryFileTask} from 'tempy';

await temporaryFileTask(tempFile => {
	console.log(tempFile);
	//=> '/private/var/folders/3x/jf5977fn79jbglr7rk0tq4d00000gn/T/4f504b9edb5ba0e89451617bf9f971dd'
});
```
*/
export function temporaryFileTask<ReturnValueType>(callback: TaskCallback<ReturnValueType>, options?: FileOptions): Promise <ReturnValueType>;

/**
Get a temporary directory path. The directory is created for you.

@example
```
import {temporaryDirectory} from 'tempy';

temporaryDirectory();
//=> '/private/var/folders/3x/jf5977fn79jbglr7rk0tq4d00000gn/T/2f3d094aec2cb1b93bb0f4cffce5ebd6'

temporaryDirectory({prefix: 'name'});
//=> '/private/var/folders/3x/jf5977fn79jbglr7rk0tq4d00000gn/T/name_3c085674ad31223b9653c88f725d6b41'
```
*/
export function temporaryDirectory(options?: DirectoryOptions): string;

/**
The `callback` resolves with a temporary directory path you can write to. The directory is automatically cleaned up after the callback is executed.

@returns A promise that resolves after the callback is executed and the directory is cleaned up.

@example
```
import {temporaryDirectoryTask} from 'tempy';

await temporaryDirectoryTask(tempDirectory => {
	//=> '/private/var/folders/3x/jf5977fn79jbglr7rk0tq4d00000gn/T/2f3d094aec2cb1b93bb0f4cffce5ebd6'
})
```
*/
export function temporaryDirectoryTask<ReturnValueType>(callback: TaskCallback<ReturnValueType>, options?: DirectoryOptions): Promise<ReturnValueType>;

/**
Write data to a random temp file.

@example
```
import {temporaryWrite} from 'tempy';

await temporaryWrite('🦄');
//=> '/private/var/folders/3x/jf5977fn79jbglr7rk0tq4d00000gn/T/2f3d094aec2cb1b93bb0f4cffce5ebd6'
```
*/
export function temporaryWrite(fileContent: string | Buffer | TypedArray | DataView | NodeJS.ReadableStream, options?: FileOptions): Promise<string>;

/**
Write data to a random temp file. The file is automatically cleaned up after the callback is executed.

@returns A promise that resolves after the callback is executed and the file is cleaned up.

@example
```
import {temporaryWriteTask} from 'tempy';

await temporaryWriteTask('🦄', tempFile => {
	//=> '/private/var/folders/3x/jf5977fn79jbglr7rk0tq4d00000gn/T/4f504b9edb5ba0e89451617bf9f971dd'
});
```
*/
export function temporaryWriteTask<ReturnValueType>(fileContent: string | Buffer | TypedArray | DataView | NodeJS.ReadableStream, callback: TaskCallback<ReturnValueType>, options?: FileOptions): Promise<ReturnValueType>;

/**
Synchronously write data to a random temp file.

@example
```
import {temporaryWriteSync} from 'tempy';

temporaryWriteSync('🦄');
//=> '/private/var/folders/3x/jf5977fn79jbglr7rk0tq4d00000gn/T/2f3d094aec2cb1b93bb0f4cffce5ebd6'
```
*/
export function temporaryWriteSync(fileContent: string | Buffer | TypedArray | DataView, options?: FileOptions): string;

export {default as rootTemporaryDirectory} from 'temp-dir';