0
# is-path-inside
1

2
is-path-inside provides a utility function to check if one file system path is inside another path. It performs path manipulation using Node.js's built-in path module to calculate relative paths and determine containment relationships without actually accessing the file system or resolving symlinks.
3

4
## Package Information
5

6
- **Package Name**: is-path-inside
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Requirements**: Node.js >=12
10
- **Installation**: `npm install is-path-inside`
11

12
## Core Imports
13

14
```javascript
15
import isPathInside from 'is-path-inside';
16
```
17

18
Note: This package is ES module only and requires Node.js 12 or later. It cannot be imported using `require()`.
19

20
## Basic Usage
21

22
```javascript
23
import isPathInside from 'is-path-inside';
24

25
// Check if path is inside another path
26
isPathInside('a/b/c', 'a/b');
27
//=> true
28

29
isPathInside('a/b/c', 'x/y');
30
//=> false
31

32
// A path is not inside itself
33
isPathInside('a/b/c', 'a/b/c');
34
//=> false
35

36
// Works with absolute paths
37
isPathInside('/Users/sindresorhus/dev/unicorn', '/Users/sindresorhus');
38
//=> true
39
```
40

41
## Capabilities
42

43
### Path Containment Check
44

45
Determines whether one path is contained within another path using relative path calculation.
46

47
```javascript { .api }
48
/**
49
 * Check if a path is inside another path.
50
 * Note that relative paths are resolved against process.cwd() to make them absolute.
51
 * 
52
 * Important: This package is meant for use with path manipulation. It does not 
53
 * check if the paths exist nor does it resolve symlinks. You should not use this 
54
 * as a security mechanism to guard against access to certain places on the file system.
55
 * 
56
 * @param childPath - The path that should be inside parentPath
57
 * @param parentPath - The path that should contain childPath
58
 * @returns true if childPath is inside parentPath, false otherwise
59
 */
60
function isPathInside(childPath: string, parentPath: string): boolean;
61
```
62

63
**Parameters:**
64
- `childPath` (string): The path that should be inside the parent path
65
- `parentPath` (string): The path that should contain the child path
66

67
**Returns:** boolean - Returns `true` if `childPath` is inside `parentPath`, `false` otherwise
68

69
**Behavior:**
70
- Relative paths are automatically resolved against `process.cwd()` to make them absolute
71
- Uses Node.js built-in `path` module for cross-platform compatibility
72
- Works on both POSIX (Unix/Linux/macOS) and Windows file systems
73
- A path is never considered inside itself (returns `false` for identical paths)
74
- Does not check if paths actually exist on the file system
75
- Does not resolve symbolic links
76
- Should not be used as a security mechanism for file system access control
77

78
**Usage Examples:**
79

80
```javascript
81
import isPathInside from 'is-path-inside';
82

83
// Basic containment check
84
console.log(isPathInside('a/b/c', 'a/b')); // true
85
console.log(isPathInside('a/b/c', 'x/y')); // false
86

87
// Self-containment check
88
console.log(isPathInside('a/b/c', 'a/b/c')); // false
89

90
// Absolute paths
91
console.log(isPathInside('/home/user/documents/file.txt', '/home/user')); // true
92
console.log(isPathInside('/home/user', '/home/user/documents')); // false
93

94
// Relative paths (resolved against process.cwd())
95
console.log(isPathInside('./subfolder/file.txt', '.')); // true
96
console.log(isPathInside('../sibling', '.')); // false
97

98
// Cross-platform path separators are handled automatically
99
console.log(isPathInside('a\\b\\c', 'a\\b')); // true (on Windows)
100
console.log(isPathInside('a/b/c', 'a/b')); // true (on Unix-like systems)
101
```