### Install mkdirp with npm

Source: https://github.com/isaacs/node-mkdirp/blob/main/readme.markdown

Instructions for installing the mkdirp package locally or globally using npm, or running it with npx.

```bash
npm install mkdirp
```

```bash
npm install -g mkdirp
```

```bash
npx mkdirp ...
```

--------------------------------

### mkdirp - Basic Usage

Source: https://github.com/isaacs/node-mkdirp/blob/main/readme.markdown

Demonstrates how to use the `mkdirp` function with Promises and synchronously.

```APIDOC
## mkdirp - Basic Usage

### Description
This section shows how to use the `mkdirp` function for creating directories recursively, both with Promises and synchronously.

### Example (Promise-based)
```javascript
// hybrid module, import or require() both work
import { mkdirp } from 'mkdirp'
// or:
const { mkdirp } = require('mkdirp')

// return value is a Promise resolving to the first directory created
mkdirp('/tmp/foo/bar/baz').then(made =>
  console.log(`made directories, starting with ${made}`)
)
```

### Example (Synchronous)
```javascript
import { mkdirp } from 'mkdirp'

// return value is the first directory created
const made = mkdirp.sync('/tmp/foo/bar/baz')
console.log(`made directories, starting with ${made}`)
```
```

--------------------------------

### mkdirp.manual and mkdirp.manualSync

Source: https://github.com/isaacs/node-mkdirp/blob/main/readme.markdown

Information on using the manual implementation of mkdirp.

```APIDOC
## mkdirp.manual, mkdirp.manualSync

### Description
Use the manual implementation (not the native one). This is the default when the native implementation is not available or the stat/mkdir implementation is overridden.
```

--------------------------------

### mkdirp.native and mkdirp.nativeSync

Source: https://github.com/isaacs/node-mkdirp/blob/main/readme.markdown

Information on using the native implementation of mkdirp.

```APIDOC
## mkdirp.native, mkdirp.nativeSync

### Description
Use the native implementation (not the manual one). This is the default when the native implementation is available and stat/mkdir are not overridden.
```

--------------------------------

### Create Directories Recursively (Async) with mkdirp

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

Use the main async function to create directories. It returns a promise resolving to the first created directory path or undefined if the path already exists.

```javascript
import { mkdirp } from 'mkdirp'

// Basic usage - create nested directories
const made = await mkdirp('/tmp/foo/bar/baz')
console.log(`Created directories starting from: ${made}`)
// Output: Created directories starting from: /tmp/foo/bar (if /tmp/foo already existed)

// With custom permissions (octal mode)
await mkdirp('/var/app/data', { mode: 0o755 })

// Mode can also be passed as a string or number
await mkdirp('/var/app/logs', '0755')
await mkdirp('/var/app/cache', 0o700)

// Handle results and errors properly
try {
  const firstCreated = await mkdirp('/projects/myapp/src/components')
  if (firstCreated) {
    console.log(`New directories created starting at: ${firstCreated}`)
  } else {
    console.log('All directories already existed')
  }
} catch (err) {
  console.error(`Failed to create directories: ${err.message}`)
  console.error(`Error code: ${err.code}`) // e.g., 'EACCES', 'EROFS'
}
```

--------------------------------

### Create directories recursively (sync)

Source: https://github.com/isaacs/node-mkdirp/blob/main/readme.markdown

Use this to create nested directories synchronously. Returns the first directory that was created.

```javascript
import { mkdirp } from 'mkdirp'

// return value is the first directory created
const made = mkdirp.sync('/tmp/foo/bar/baz')
console.log(`made directories, starting with ${made}`)
```

--------------------------------

### Create directories recursively (async)

Source: https://github.com/isaacs/node-mkdirp/blob/main/readme.markdown

Use this to create nested directories asynchronously. The Promise resolves with the first directory that was created.

```javascript
// hybrid module, import or require() both work
import { mkdirp } from 'mkdirp'
// or:
const { mkdirp } = require('mkdirp')

// return value is a Promise resolving to the first directory created
mkdirp('/tmp/foo/bar/baz').then(made =>
  console.log(`made directories, starting with ${made}`)
)
```

--------------------------------

### mkdirp.manual / mkdirp.manualSync - Force Manual Implementation

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

Explicitly uses the manual recursive implementation that creates directories one at a time. This is useful for consistent behavior across Node.js versions or with custom filesystem implementations.

```APIDOC
## mkdirp.manual / mkdirp.manual(path, opts?)

### Description
Explicitly uses the manual recursive implementation to create directories one at a time. This ensures consistent behavior across different Node.js versions and is useful when working with custom filesystem implementations.

### Method
`POST` (conceptual, as it modifies state)

### Endpoint
`/api/mkdirp/manual` (conceptual endpoint for manual async operation)

### Parameters
#### Path Parameters
- **path** (string) - Required - The path of the directory to create.

#### Query Parameters
- **opts** (object) - Optional - Options object.
  - **mode** (string | number | octal) - Optional - The permissions to set for the created directories.

### Request Example
```json
{
  "path": "/tmp/manual-test/nested/deep",
  "opts": {
    "mode": "0755"
  }
}
```

### Response
#### Success Response (200)
- **made** (string | undefined) - The path of the first directory that was created, or `undefined` if all directories already existed.

#### Response Example
```json
{
  "made": "/tmp/manual-test"
}
```

## mkdirp.manualSync / mkdirp.manualSync(path, opts?)

### Description
Synchronously uses the manual recursive implementation to create directories one at a time.

### Method
`POST` (conceptual, as it modifies state)

### Endpoint
`/api/mkdirp/manual/sync` (conceptual endpoint for manual sync operation)

### Parameters
#### Path Parameters
- **path** (string) - Required - The path of the directory to create.

#### Query Parameters
- **opts** (object) - Optional - Options object.
  - **mode** (string | number | octal) - Optional - The permissions to set for the created directories.

### Request Example
```json
{
  "path": "/tmp/manual-sync/nested/deep",
  "opts": {
    "mode": 0o755
  }
}
```

### Response
#### Success Response (200)
- **made** (string | undefined) - The path of the first directory that was created, or `undefined` if all directories already existed.

#### Response Example
```json
{
  "made": "/tmp/manual-sync"
}
```
```

--------------------------------

### mkdirp CLI Help

Source: https://github.com/isaacs/node-mkdirp/blob/main/readme.markdown

Displays the help message for the mkdirp command-line tool, outlining its usage and available options.

```bash
mkdirp -h
```

--------------------------------

### Define MkdirpOptions Interface and Usage

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

Configuration options for directory permissions and filesystem overrides, including shorthand modes for directory creation.

```typescript
interface MkdirpOptions {
  // Directory permission mode (default: 0o777)
  mode?: number | string

  // Custom filesystem implementation object
  fs?: {
    mkdir?: (path, opts, callback) => any
    stat?: (path, callback) => any
    mkdirSync?: (path, opts) => string | undefined
    statSync?: (path) => Stats
  }

  // Individual method overrides
  mkdir?: (path, opts, callback) => any
  stat?: (path, callback) => any
  mkdirSync?: (path, opts) => string | undefined
  statSync?: (path) => Stats

  // Promise-based overrides
  mkdirAsync?: (path, opts) => Promise<string | undefined>
  statAsync?: (path) => Promise<Stats>
}

// Usage examples
import { mkdirp } from 'mkdirp'

// Mode as number
await mkdirp('/path', { mode: 0o755 })

// Mode as octal string
await mkdirp('/path', { mode: '0755' })

// Mode shorthand (options can be just the mode)
await mkdirp('/path', 0o755)
await mkdirp('/path', '0755')
```

--------------------------------

### mkdirp.sync - Create Directories Recursively (Sync)

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

The synchronous version of mkdirp that blocks until directories are created. It returns the first directory that had to be created, or undefined if everything already exists. Useful for initialization scripts and build tools.

```APIDOC
## mkdirp.sync / mkdirp.sync(path, opts?)

### Description
Synchronously creates a directory and all necessary parent directories. Returns the first directory that had to be created, or `undefined` if all directories already existed.

### Method
`POST` (conceptual, as it modifies state)

### Endpoint
`/api/mkdirp/sync` (conceptual endpoint for sync operation)

### Parameters
#### Path Parameters
- **path** (string) - Required - The path of the directory to create.

#### Query Parameters
- **opts** (object) - Optional - Options object.
  - **mode** (string | number | octal) - Optional - The permissions to set for the created directories. Can be a string (e.g., '0755'), a number, or an octal number (e.g., 0o755).

### Request Example
```json
{
  "path": "/tmp/build/output/dist",
  "opts": {
    "mode": 0o700
  }
}
```

### Response
#### Success Response (200)
- **made** (string | undefined) - The path of the first directory that was created, or `undefined` if all directories already existed.

#### Response Example
```json
{
  "made": "/tmp/build/output"
}
```
```

--------------------------------

### Execute mkdirp via CLI

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

Command-line interface commands for creating directories, setting permissions, and managing special path characters.

```bash
# Install globally
npm install -g mkdirp

# Or use with npx
npx mkdirp /path/to/create

# Create multiple directories
mkdirp dir1/nested dir2/nested dir3/nested

# Set directory permissions (octal mode)
mkdirp -m 0755 /var/app/data
mkdirp --mode=0700 /secure/path

# Print the first directories created
mkdirp -p /tmp/new/path/here
# Output: /tmp/new

# Force manual implementation
mkdirp --manual /path/to/dir

# Show help
mkdirp --help

# Show version
mkdirp --version

# Handle paths with special characters (use --)
mkdirp -- --weird-dirname -another-weird-name
```

--------------------------------

### mkdirp.native / mkdirp.nativeSync - Force Native Implementation

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

Explicitly uses Node.js native `fs.mkdir` with `recursive: true`. This can be faster but may offer less informative error messages in some edge cases. The native implementation falls back to manual if an `ENOENT` error is encountered.

```APIDOC
## mkdirp.native / mkdirp.native(path, opts?)

### Description
Explicitly uses the Node.js native `fs.mkdir` function with the `recursive: true` option to create directories. This method can be faster but might provide less detailed error messages compared to the manual implementation.

### Method
`POST` (conceptual, as it modifies state)

### Endpoint
`/api/mkdirp/native` (conceptual endpoint for native async operation)

### Parameters
#### Path Parameters
- **path** (string) - Required - The path of the directory to create.

#### Query Parameters
- **opts** (object) - Optional - Options object.
  - **mode** (string | number | octal) - Optional - The permissions to set for the created directories.

### Request Example
```json
{
  "path": "/tmp/native-test/nested/deep",
  "opts": {
    "mode": "0755"
  }
}
```

### Response
#### Success Response (200)
- **made** (string | undefined) - The path of the first directory that was created, or `undefined` if all directories already existed.

#### Response Example
```json
{
  "made": "/tmp/native-test"
}
```

## mkdirp.nativeSync / mkdirp.nativeSync(path, opts?)

### Description
Synchronously uses the Node.js native `fs.mkdir` function with the `recursive: true` option to create directories.

### Method
`POST` (conceptual, as it modifies state)

### Endpoint
`/api/mkdirp/native/sync` (conceptual endpoint for native sync operation)

### Parameters
#### Path Parameters
- **path** (string) - Required - The path of the directory to create.

#### Query Parameters
- **opts** (object) - Optional - Options object.
  - **mode** (string | number | octal) - Optional - The permissions to set for the created directories.

### Request Example
```json
{
  "path": "/tmp/native-sync/nested/deep",
  "opts": {
    "mode": 0o755
  }
}
```

### Response
#### Success Response (200)
- **made** (string | undefined) - The path of the first directory that was created, or `undefined` if all directories already existed.

#### Response Example
```json
{
  "made": "/tmp/native-sync"
}
```
```

--------------------------------

### Implement Custom Filesystem with mkdirp

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

Configure mkdirp to use virtual or mocked filesystems by providing custom fs methods or overriding individual filesystem operations.

```javascript
import { mkdirp } from 'mkdirp'
import { Volume, createFsFromVolume } from 'memfs'

// Using a memory filesystem
const vol = new Volume()
const memfs = createFsFromVolume(vol)

await mkdirp('/virtual/path/to/dir', {
  fs: {
    mkdir: memfs.mkdir,
    stat: memfs.stat,
    mkdirSync: memfs.mkdirSync,
    statSync: memfs.statSync,
  }
})

// Override individual methods
await mkdirp('/path/to/dir', {
  mkdir: customMkdir,
  stat: customStat,
})

// Async method overrides with promises
await mkdirp('/path/to/dir', {
  mkdirAsync: async (path, opts) => {
    console.log(`Creating: ${path}`)
    return originalMkdir(path, opts)
  },
  statAsync: async (path) => {
    return originalStat(path)
  }
})

// Sync version with custom fs
mkdirp.sync('/virtual/sync/path', {
  fs: memfs,
  mode: 0o755
})
```

--------------------------------

### mkdirp - Create Directories Recursively (Async)

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

The main asynchronous function to create a directory and all necessary parent directories. It returns a Promise that resolves to the first directory created, or undefined if all directories already existed. It automatically selects between native and manual implementations.

```APIDOC
## mkdirp / mkdirp(path, opts?)

### Description
Creates a directory and all necessary parent directories recursively. Returns a Promise that resolves to the first directory that was created, or `undefined` if all directories already existed.

### Method
`POST` (conceptual, as it modifies state)

### Endpoint
`/api/mkdirp` (conceptual endpoint for async operation)

### Parameters
#### Path Parameters
- **path** (string) - Required - The path of the directory to create.

#### Query Parameters
- **opts** (object) - Optional - Options object.
  - **mode** (string | number | octal) - Optional - The permissions to set for the created directories. Can be a string (e.g., '0755'), a number, or an octal number (e.g., 0o755).

### Request Example
```json
{
  "path": "/tmp/foo/bar/baz",
  "opts": {
    "mode": "0755"
  }
}
```

### Response
#### Success Response (200)
- **made** (string | undefined) - The path of the first directory that was created, or `undefined` if all directories already existed.

#### Response Example
```json
{
  "made": "/tmp/foo/bar"
}
```
```

--------------------------------

### Custom Filesystem Implementation

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

mkdirp allows for custom filesystem implementations, enabling integration with virtual or memory-based filesystems for testing or specialized use cases. You can provide a full `fs` object or override individual methods.

```APIDOC
## Custom Filesystem Implementation

### Description

mkdirp supports providing custom filesystem implementations, allowing it to work with virtual filesystems, memory filesystems, or mocked filesystems for testing. When custom `fs` methods are provided, the manual implementation is automatically used.

### Request Example

```javascript
import { mkdirp } from 'mkdirp'
import { Volume, createFsFromVolume } from 'memfs'

// Using a memory filesystem
const vol = new Volume()
const memfs = createFsFromVolume(vol)

await mkdirp('/virtual/path/to/dir', {
  fs: {
    mkdir: memfs.mkdir,
    stat: memfs.stat,
    mkdirSync: memfs.mkdirSync,
    statSync: memfs.statSync,
  }
})

// Override individual methods
await mkdirp('/path/to/dir', {
  mkdir: customMkdir,
  stat: customStat,
})

// Async method overrides with promises
await mkdirp('/path/to/dir', {
  mkdirAsync: async (path, opts) => {
    console.log(`Creating: ${path}`)
    return originalMkdir(path, opts)
  },
  statAsync: async (path) => {
    return originalStat(path)
  }
})

// Sync version with custom fs
mkdirp.sync('/virtual/sync/path', {
  fs: memfs,
  mode: 0o755
})
```
```

--------------------------------

### Create Directories Recursively (Sync) with mkdirp.sync

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

The synchronous version blocks execution until directories are created. Suitable for build scripts and initialization tasks.

```javascript
import { mkdirp } from 'mkdirp'

// Synchronous directory creation
const made = mkdirp.sync('/tmp/build/output/dist')
console.log(`Created: ${made}`)

// With mode option
mkdirp.sync('/var/log/myapp', { mode: 0o755 })

// In a build script context
function ensureBuildDirs() {
  mkdirp.sync('./dist/js')
  mkdirp.sync('./dist/css')
  mkdirp.sync('./dist/assets/images')
  console.log('Build directories ready')
}

// Error handling
try {
  mkdirp.sync('/root/protected-dir')
} catch (err) {
  if (err.code === 'EACCES') {
    console.error('Permission denied')
  } else {
    throw err
  }
}
```

--------------------------------

### CLI Usage

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

mkdirp provides a command-line interface for creating directories directly from the terminal, with options for setting modes and handling special characters.

```APIDOC
## CLI Usage

### Description

mkdirp includes a command-line interface that can be used directly or via npx. It supports creating multiple directories, setting permissions, and printing the first created directory.

### Usage Examples

```bash
# Install globally
npm install -g mkdirp

# Or use with npx
npx mkdirp /path/to/create

# Create multiple directories
mkdirp dir1/nested dir2/nested dir3/nested

# Set directory permissions (octal mode)
mkdirp -m 0755 /var/app/data
mkdirp --mode=0700 /secure/path

# Print the first directories created
mkdirp -p /tmp/new/path/here
# Output: /tmp/new

# Force manual implementation
mkdirp --manual /path/to/dir

# Show help
mkdirp --help

# Show version
mkdirp --version

# Handle paths with special characters (use --)
mkdirp -- --weird-dirname -another-weird-name
```
```

--------------------------------

### mkdirp.sync(dir, opts) - Synchronous API

Source: https://github.com/isaacs/node-mkdirp/blob/main/readme.markdown

Details on the synchronous `mkdirp.sync` function, including its parameters and return value.

```APIDOC
## mkdirp.sync(dir, opts) => string | undefined

### Description
Synchronously create a new directory and any necessary subdirectories at `dir` with octal permission string `opts.mode`. If `opts` is a string or number, it will be treated as the `opts.mode`.

If `opts.mode` isn't specified, it defaults to `0o777`.

Returns the first directory that had to be created, or undefined if everything already exists.

You can optionally pass in an alternate `fs` implementation by passing in `opts.fs`. Your implementation should have `opts.fs.mkdirSync(path, mode)` and `opts.fs.statSync(path)`.

You can also override just one or the other of `mkdirSync` and `statSync` by passing in `opts.statSync` or `opts.mkdirSync`, or providing an `fs` option that only overrides one of these.

### Parameters
#### Path Parameters
- **dir** (string) - Required - The directory path to create.
- **opts** (MkdirpOptions | string | number) - Optional - Options object or mode.
  - **mode** (string | number) - Optional - Octal permission string for the directories. Defaults to `0o777`.
  - **fs** (object) - Optional - Alternate file system implementation.
    - **mkdirSync** (function) - Function for synchronously creating directories.
    - **statSync** (function) - Function for synchronously getting file status.

### Response
#### Success Response
- **made** (string | undefined) - The first directory that had to be created, or `undefined` if everything already existed.

#### Error Response
- Throws an error if any issues are encountered during directory creation.
```

--------------------------------

### Force Manual Implementation with mkdirp.manual

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

Uses a manual recursive implementation. Useful for consistent behavior across Node.js versions or when using custom filesystem implementations.

```javascript
import { mkdirp } from 'mkdirp'

// Force manual implementation (async)
const made = await mkdirp.manual('/tmp/manual-test/nested/deep')
console.log(`First directory created: ${made}`)

// Force manual implementation (sync)
const madeSync = mkdirp.manualSync('/tmp/manual-sync/nested/deep')
console.log(`First directory created: ${madeSync}`)

// Alternative import style
import { mkdirpManual, mkdirpManualSync } from 'mkdirp'

await mkdirpManual('/tmp/another/manual/path')
mkdirpManualSync('/tmp/sync/manual/path')
```

--------------------------------

### Check Implementation Selection with useNative

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

Helper functions to verify if the native recursive mkdir implementation is being used based on current configuration.

```javascript
import { mkdirp } from 'mkdirp'

// Check if native will be used with default options
console.log(mkdirp.useNative()) // true on Node.js >= 10.12.0

// Check if native will be used for sync operations
console.log(mkdirp.useNativeSync()) // true on Node.js >= 10.12.0

// Custom fs disables native
const customOpts = { mkdir: customMkdir }
console.log(mkdirp.useNative(customOpts)) // false

// Alternative import
import { useNative, useNativeSync } from 'mkdirp'

if (useNative()) {
  console.log('Using native recursive mkdir')
} else {
  console.log('Using manual implementation')
}
```

--------------------------------

### useNative / useNativeSync - Check Implementation Selection

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

Helper functions to determine if the native `fs.mkdir` recursive mode will be used based on the Node.js version and provided options.

```APIDOC
## useNative / useNativeSync

### Description

Helper functions to determine whether the native implementation will be used for a given set of options. Returns `true` if native `fs.mkdir` recursive mode is available and no custom filesystem methods override the defaults.

### Usage Examples

```javascript
import { mkdirp } from 'mkdirp'

// Check if native will be used with default options
console.log(mkdirp.useNative()) // true on Node.js >= 10.12.0

// Check if native will be used for sync operations
console.log(mkdirp.useNativeSync()) // true on Node.js >= 10.12.0

// Custom fs disables native
const customOpts = { mkdir: customMkdir }
console.log(mkdirp.useNative(customOpts)) // false

// Alternative import
import { useNative, useNativeSync } from 'mkdirp'

if (useNative()) {
  console.log('Using native recursive mkdir')
} else {
  console.log('Using manual implementation')
}
```
```

--------------------------------

### Force Native Implementation with mkdirp.native

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

Explicitly uses the native Node.js fs.mkdir recursive option. This may be faster but can result in less informative error messages.

```javascript
import { mkdirp } from 'mkdirp'

// Force native implementation (async)
const made = await mkdirp.native('/tmp/native-test/nested/deep')
console.log(`First directory created: ${made}`)

// Force native implementation (sync)
const madeSync = mkdirp.nativeSync('/tmp/native-sync/nested/deep')
console.log(`First directory created: ${madeSync}`)

// Alternative import style
import { mkdirpNative, mkdirpNativeSync } from 'mkdirp'

await mkdirpNative('/tmp/another/path')
mkdirpNativeSync('/tmp/sync/path')
```

--------------------------------

### Importing mkdirp

Source: https://github.com/isaacs/node-mkdirp/blob/main/readme.markdown

Standard import statement for using the mkdirp module in your project.

```javascript
import { mkdirp } from 'mkdirp'
```

--------------------------------

### MkdirpOptions Interface

Source: https://context7.com/isaacs/node-mkdirp/llms.txt

Configuration options for mkdirp functions, including directory permissions (`mode`) and custom filesystem implementations (`fs`).

```APIDOC
## MkdirpOptions Interface

### Description

Configuration options that can be passed to any mkdirp function. The mode option specifies directory permissions, while fs-related options allow for custom filesystem implementations.

### Parameters

#### Request Body

- **mode** (number | string) - Optional - Directory permission mode (default: 0o777)
- **fs** (object) - Optional - Custom filesystem implementation object
  - **mkdir** (function) - Optional - `(path, opts, callback) => any`
  - **stat** (function) - Optional - `(path, callback) => any`
  - **mkdirSync** (function) - Optional - `(path, opts) => string | undefined`
  - **statSync** (function) - Optional - `(path) => Stats`
- **mkdir** (function) - Optional - Individual method override: `(path, opts, callback) => any`
- **stat** (function) - Optional - Individual method override: `(path, callback) => any`
- **mkdirSync** (function) - Optional - Individual method override: `(path, opts) => string | undefined`
- **statSync** (function) - Optional - Individual method override: `(path) => Stats`
- **mkdirAsync** (function) - Optional - Promise-based override: `(path, opts) => Promise<string | undefined>`
- **statAsync** (function) - Optional - Promise-based override: `(path) => Promise<Stats>`

### Request Example

```javascript
import { mkdirp } from 'mkdirp'

// Mode as number
await mkdirp('/path', { mode: 0o755 })

// Mode as octal string
await mkdirp('/path', { mode: '0755' })

// Mode shorthand (options can be just the mode)
await mkdirp('/path', 0o755)
await mkdirp('/path', '0755')
```
```

--------------------------------

### mkdirp(dir, opts) - Promise API

Source: https://github.com/isaacs/node-mkdirp/blob/main/readme.markdown

Details on the asynchronous `mkdirp` function, including its parameters and return value.

```APIDOC
## mkdirp(dir, opts) => Promise<string | undefined>

### Description
Create a new directory and any necessary subdirectories at `dir` with octal permission string `opts.mode`. If `opts` is a string or number, it will be treated as the `opts.mode`.

If `opts.mode` isn't specified, it defaults to `0o777`.

Promise resolves to first directory `made` that had to be created, or `undefined` if everything already exists. Promise rejects if any errors are encountered. Note that, in the case of promise rejection, some directories _may_ have been created, as recursive directory creation is not an atomic operation.

You can optionally pass in an alternate `fs` implementation by passing in `opts.fs`. Your implementation should have `opts.fs.mkdir(path, opts, cb)` and `opts.fs.stat(path, cb)`.

You can also override just one or the other of `mkdir` and `stat` by passing in `opts.stat` or `opts.mkdir`, or providing an `fs` option that only overrides one of these.

### Parameters
#### Path Parameters
- **dir** (string) - Required - The directory path to create.
- **opts** (MkdirpOptions | string | number) - Optional - Options object or mode.
  - **mode** (string | number) - Optional - Octal permission string for the directories. Defaults to `0o777`.
  - **fs** (object) - Optional - Alternate file system implementation.
    - **mkdir** (function) - Function for creating directories.
    - **stat** (function) - Function for getting file status.

### Response
#### Success Response (Promise resolves)
- **made** (string | undefined) - The first directory that had to be created, or `undefined` if everything already existed.

#### Error Response (Promise rejects)
- Rejects with an error if any issues are encountered during directory creation.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.