CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-mkdirp

Recursively mkdir, like `mkdir -p`

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

mkdirp

mkdirp provides recursive directory creation functionality, replicating the Unix mkdir -p command in Node.js environments. It offers both asynchronous (Promise-based) and synchronous APIs for creating nested directory structures, with automatic fallback between native Node.js fs.mkdir recursive implementation and a manual implementation for broader compatibility.

Package Information

  • Package Name: mkdirp
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install mkdirp

Core Imports

Required Node.js Types: fs.MakeDirectoryOptions, fs.Stats, NodeJS.ErrnoException

// ESM - Named imports (no default export)
import { mkdirp, mkdirpSync } from "mkdirp";
// mkdirp is a function with properties attached via Object.assign
const result = await mkdirp("/path"); 
const resultSync = mkdirp.sync("/path"); // or mkdirpSync directly

// Additional named imports
import { mkdirpNative, mkdirpManual, useNative } from "mkdirp";
// Types are available through TypeScript's module system
import type { MkdirpOptions } from "mkdirp";

For CommonJS:

// CommonJS - destructure named exports
const { mkdirp, mkdirpSync } = require("mkdirp");
// Or access all exports
const mkdirpLib = require("mkdirp");
const mkdirp = mkdirpLib.mkdirp;

Basic Usage

import { mkdirp, mkdirpSync } from "mkdirp";

// Async usage
const made = await mkdirp("/tmp/some/deep/path");
console.log(`Created directory: ${made}`); // First directory actually created

// Sync usage
const madeSync = mkdirpSync("/tmp/another/deep/path");
console.log(`Created directory: ${madeSync}`);

// With permissions
await mkdirp("/tmp/secure/path", { mode: 0o755 });

// With custom filesystem
await mkdirp("/tmp/custom/path", {
  fs: {
    mkdir: customMkdir,
    stat: customStat
  }
});

Architecture

mkdirp is built around several key components:

  • Automatic Implementation Selection: Chooses between native and manual based on Node.js version and options
  • Native Implementation: Uses Node.js fs.mkdir with recursive option for optimal performance
  • Manual Implementation: Creates directories one by one when native implementation is unavailable
  • Custom Filesystem Support: Allows injection of custom fs operations via FsProvider interface
  • Cross-Platform Compatibility: Handles Windows path restrictions and permissions properly

Capabilities

Primary Directory Creation

Core async directory creation function that automatically selects the best implementation. The mkdirp export is a function with attached utility methods via Object.assign.

/**
 * Creates directories recursively, like `mkdir -p`
 * Named export with attached utility methods via Object.assign
 */
const mkdirp: {
  (path: string, opts?: MkdirpOptions): Promise<string | undefined>;
  mkdirpSync: typeof mkdirpSync;
  mkdirpNative: typeof mkdirpNative;
  mkdirpNativeSync: typeof mkdirpNativeSync;
  mkdirpManual: typeof mkdirpManual;
  mkdirpManualSync: typeof mkdirpManualSync;
  sync: typeof mkdirpSync;
  native: typeof mkdirpNative;
  nativeSync: typeof mkdirpNativeSync;
  manual: typeof mkdirpManual;
  manualSync: typeof mkdirpManualSync;
  useNative: typeof useNative;
  useNativeSync: typeof useNativeSync;
};

/**
 * Synchronous version of mkdirp
 * @param path - The directory path to create  
 * @param opts - Options for directory creation
 * @returns The first directory created, or undefined if already exists
 */
function mkdirpSync(path: string, opts?: MkdirpOptions): string | undefined;

Implementation-Specific Functions

Functions that force specific implementation strategies.

/**
 * Creates directories using Node.js native fs.mkdir with recursive option
 * Falls back to manual implementation on ENOENT errors
 */
function mkdirpNative(path: string, options?: MkdirpOptions): Promise<string | undefined>;

/**
 * Synchronous version of mkdirpNative
 */
function mkdirpNativeSync(path: string, options?: MkdirpOptions): string | undefined;

/**
 * Creates directories manually, one by one
 * Used when native implementation is not available or fails
 */
function mkdirpManual(
  path: string, 
  options?: MkdirpOptions, 
  made?: string | undefined
): Promise<string | undefined>;

/**
 * Synchronous version of mkdirpManual
 */
function mkdirpManualSync(
  path: string, 
  options?: MkdirpOptions, 
  made?: string | undefined
): string | undefined;

Implementation Detection

Utilities to determine which implementation should be used.

/**
 * Determines if native implementation should be used
 * Checks Node.js version and options compatibility
 */
function useNative(opts?: MkdirpOptions): boolean;

/**
 * Synchronous version of useNative
 */
function useNativeSync(opts?: MkdirpOptions): boolean;

Convenience Aliases

Alternative names for core functions.

const sync: typeof mkdirpSync;
const manual: typeof mkdirpManual;
const manualSync: typeof mkdirpManualSync;
const native: typeof mkdirpNative;
const nativeSync: typeof mkdirpNativeSync;

Types and Options

MkdirpOptions

Configuration options for directory creation operations.

/**
 * Options for mkdirp operations
 * Can be an options object, numeric mode, or string mode
 */
type MkdirpOptions = Options | number | string;

/**
 * Base options interface
 */
interface Options extends FsProvider {
  /** Directory permissions mode (default: 0o777) */
  mode?: number | string;
  /** Custom filesystem provider */
  fs?: FsProvider;
  /** Custom async mkdir function */
  mkdirAsync?: (
    path: string,
    opts: MakeDirectoryOptions & { recursive?: boolean }
  ) => Promise<string | undefined>;
  /** Custom async stat function */
  statAsync?: (path: string) => Promise<Stats>;
}

/**
 * Resolved options with all defaults applied
 */
interface MkdirpOptionsResolved {
  mode: number;
  fs: FsProvider;
  mkdirAsync: (path: string, opts: MakeDirectoryOptions & { recursive?: boolean }) => Promise<string | undefined>;
  statAsync: (path: string) => Promise<Stats>;
  stat: (path: string, callback: (err: NodeJS.ErrnoException | null, stats: Stats) => any) => any;
  mkdir: (path: string, opts: MakeDirectoryOptions & { recursive?: boolean }, callback: (err: NodeJS.ErrnoException | null, made?: string) => any) => any;
  statSync: (path: string) => Stats;
  mkdirSync: (path: string, opts: MakeDirectoryOptions & { recursive?: boolean }) => string | undefined;
  recursive?: boolean;
}

FsProvider

Interface for custom filesystem implementations.

/**
 * Interface for providing custom filesystem operations
 */
interface FsProvider {
  /** Custom stat function */
  stat?: (
    path: string,
    callback: (err: NodeJS.ErrnoException | null, stats: Stats) => any
  ) => any;
  /** Custom mkdir function */
  mkdir?: (
    path: string,
    opts: MakeDirectoryOptions & { recursive?: boolean },
    callback: (err: NodeJS.ErrnoException | null, made?: string) => any
  ) => any;
  /** Custom statSync function */
  statSync?: (path: string) => Stats;
  /** Custom mkdirSync function */
  mkdirSync?: (
    path: string,
    opts: MakeDirectoryOptions & { recursive?: boolean }
  ) => string | undefined;
}

Internal Utility Functions

Internal utilities used by mkdirp implementations. Some of these are exported from their respective modules.

/**
 * Normalizes and resolves options with defaults
 * @param opts - Raw options input
 * @returns Resolved options object
 */
function optsArg(opts?: MkdirpOptions): MkdirpOptionsResolved;

/**
 * Validates and resolves path arguments
 * @param path - Path string to validate
 * @returns Absolute path
 * @throws TypeError for paths with null bytes
 * @throws Error for illegal characters on Windows
 */
function pathArg(path: string): string;

Directory Detection Utilities\n\nUtilities for finding the first directory that needs to be created during recursive mkdir operations. These are exported from the find-made module.\n\ntypescript { .api }\n/**\n * Finds the first directory that needs to be created (async)\n * @param opts - Resolved options object with fs methods\n * @param parent - Parent directory path to check\n * @param path - Target path being created\n * @returns Promise resolving to first directory to create, or undefined\n */\nfunction findMade(\n opts: MkdirpOptionsResolved,\n parent: string,\n path?: string\n): Promise<undefined | string>;\n\n/**\n * Synchronous version of findMade\n * @param opts - Resolved options object with fs methods\n * @param parent - Parent directory path to check \n * @param path - Target path being created\n * @returns First directory to create, or undefined\n */\nfunction findMadeSync(\n opts: MkdirpOptionsResolved,\n parent: string,\n path?: string\n): undefined | string;\n\n\n## Command Line Interface

mkdirp includes a command-line tool for directory creation.

Binary Path: ./dist/cjs/src/bin.js (configured in package.json bin field)

# Install globally to use CLI
npm install -g mkdirp

# Basic usage
mkdirp /path/to/create

# Multiple directories  
mkdirp /path/one /path/two /path/three

# With permissions
mkdirp -m755 /path/to/create
mkdirp --mode=755 /path/to/create

# Print created directories
mkdirp -p /path/to/create
mkdirp --print /path/to/create

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

# Help and version
mkdirp --help
mkdirp --version

Error Handling

mkdirp handles various filesystem error conditions:

  • ENOENT: Missing parent directories - falls back to manual creation
  • EEXIST: Directory already exists - returns undefined (not an error)
  • EROFS: Read-only filesystem - returns undefined for existing directories
  • EISDIR: Path exists as directory - returns undefined (success)
  • Path validation errors: Throws TypeError for null bytes, Error for illegal Windows characters
  • Invalid options: Throws TypeError for invalid options argument

Usage Examples

Basic Directory Creation

import { mkdirp } from "mkdirp";

// Create nested directories
const created = await mkdirp("/tmp/foo/bar/baz");
if (created) {
  console.log(`Created: ${created}`); // "/tmp/foo" if foo didn't exist
}

// Synchronous version
const createdSync = mkdirp.sync("/tmp/another/nested/path");

Custom Permissions

import { mkdirp } from "mkdirp";

// Using numeric mode
await mkdirp("/tmp/secure", 0o750);

// Using string mode  
await mkdirp("/tmp/public", "755");

// Using options object
await mkdirp("/tmp/private", { mode: 0o700 });

Custom Filesystem

import { mkdirp } from "mkdirp";
import { promises as fs } from "fs";

const customFs = {
  mkdir: fs.mkdir,
  stat: fs.stat,
  mkdirSync: require("fs").mkdirSync,
  statSync: require("fs").statSync
};

await mkdirp("/custom/path", { fs: customFs });

Implementation Selection

import { mkdirp } from "mkdirp";

// Force native implementation
const native = await mkdirp.native("/tmp/native");

// Force manual implementation
const manual = await mkdirp.manual("/tmp/manual");

// Check which implementation would be used
const shouldUseNative = mkdirp.useNative({ mode: 0o755 });
console.log(`Using native: ${shouldUseNative}`);

docs

index.md

tile.json