Profiles·Public

fs-extra

semver>=9.0.0 <12.0.0postconditions26functions12last verified2026-04-06coverage score100%

Postconditions — what we check

readJson · file-not-found
error
WhenFile at path does not exist
ThrowsError with code ENOENT
Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOENT' to handle missing files. Consider using pathExists() first or providing a default value in the catch block.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[1]
readJson · invalid-json
error
WhenFile exists but contains invalid JSON
ThrowsSyntaxError
Required handlingCaller MUST wrap in try-catch. Invalid JSON throws a SyntaxError (not an Error with a code). Validate JSON structure after reading if schema compliance is required.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[1]
readJson · permission-denied
error
WhenProcess lacks read permission for the file
ThrowsError with code EACCES
Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' to handle permission errors. Ensure the process has appropriate filesystem permissions.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[1]
copy · source-not-found
error
WhenSource path does not exist
ThrowsError with code ENOENT
Required handlingCaller MUST wrap in try-catch. Verify source exists before copying, or handle ENOENT in the catch block. Consider using pathExists() to pre-check source existence.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[2]
copy · permission-denied
error
WhenProcess lacks read permission on source or write permission on destination
ThrowsError with code EACCES
Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' and handle appropriately. Ensure the process has read access to source and write access to destination parent.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[2]
move · source-not-found
error
WhenSource path does not exist
ThrowsError with code ENOENT
Required handlingCaller MUST wrap in try-catch. Handle ENOENT for missing source path. Consider using pathExists() to pre-check source existence.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[3]
move · destination-exists
error
WhenDestination already exists and overwrite option is not set to true
ThrowsError: dest already exists.
Required handlingCaller MUST either pass { overwrite: true } option to allow overwriting, or wrap in try-catch to handle the case where destination already exists. Note: the default for move (overwrite: false) differs from copy (overwrite: true) — a common footgun.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[3]
move · permission-denied
error
WhenProcess lacks write permission on source or destination
ThrowsError with code EACCES
Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' and handle appropriately.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[3]
outputFile · outputfile-permission-denied
error
WhenProcess lacks write permission on the target file or a parent directory component
ThrowsError with code EACCES
Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' to handle permission errors. SaaS apps often run as restricted users without write access to all paths. Particularly dangerous in background jobs where the error is silently discarded.
costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
Sources[4][5]
outputFile · outputfile-disk-full
error
WhenFilesystem has no remaining space when fs.writeFile is called
ThrowsError with code ENOSPC
Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOSPC' to detect disk-full conditions. Unlike EACCES (predictable at startup), disk-full is a runtime error. Monitoring disk space and handling ENOSPC is critical for any app writing user files.
costhighin prodimmediate exceptionusers seelost datavisibilitysilent
Sources[4][5]
writeJson · writejson-parent-not-found
error
WhenParent directory does not exist (writeJson does not create parent directories)
ThrowsError with code ENOENT
Required handlingCaller MUST wrap in try-catch. Unlike outputJson/outputFile, writeJson does NOT create missing parent directories. Use outputJson() if the parent directory may not exist. Handle ENOENT in the catch block to detect missing parent directories.
costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
Sources[6][7]
writeJson · writejson-permission-denied
error
WhenProcess lacks write permission on the target file or parent directory
ThrowsError with code EACCES
Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' to handle permission errors. Propagates directly from fs.writeFile.
costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
Sources[6][7]
writeJson · writejson-circular-reference
error
WhenData object contains circular references (e.g. ORM model, Express req/res object)
ThrowsTypeError: Converting circular structure to JSON
Required handlingCaller MUST wrap in try-catch. TypeError from circular references does not have a code property — check for TypeError or the message text. Avoid serializing ORM model instances, class objects with parent references, or Express req/res objects directly.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[7][8]
ensureDir · ensuredir-permission-denied
error
WhenProcess lacks write or execute permission on a parent directory component
ThrowsError with code EACCES
Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' to handle permission errors. Directory creation fails — subsequent file writes to that path will also fail with ENOENT. Ensure the process has write permission on all parent directory components.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
Sources[9][10]
ensureDir · ensuredir-path-component-is-file
error
WhenA component of the path that should be a directory is actually an existing file
ThrowsError with code ENOTDIR
Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOTDIR' to detect path conflicts. This occurs in misconfigured deployments where a directory path collides with an existing file (e.g. '/data/config' is a file but caller expects a directory).
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[9][10]
remove · remove-permission-denied
error
WhenProcess lacks write permission on the file or directory, or execute permission on a parent directory
ThrowsError with code EACCES (Unix) or EPERM (Windows)
Required handlingCaller MUST wrap in try-catch. The force: true option ONLY silences ENOENT — it does NOT silence permission errors. Check error.code === 'EACCES' || error.code === 'EPERM'. Failed cleanup leaves orphaned files on disk with no alert.
costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
Sources[11][12][13]
outputJson · outputjson-circular-reference
error
WhenData object contains circular references (e.g. ORM model instances, Express objects)
ThrowsTypeError: Converting circular structure to JSON
Required handlingCaller MUST wrap in try-catch. TypeError occurs before any file I/O — no file is created or modified. The error has no code property, making it harder to detect in generic catch blocks. Avoid serializing class instances or cyclic object graphs.
costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
Sources[14][7]
outputJson · outputjson-permission-denied
error
WhenProcess lacks write permission on the target file or any parent directory
ThrowsError with code EACCES
Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES'. Inherits from outputFile → fs.writeFile. Silent failure leaves system in stale state.
costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
Sources[14][5]
ensureFile · ensurefile-permission-denied
error
WhenProcess lacks write permission on the target directory or execute permission on a parent
ThrowsError with code EACCES
Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES'. Parent directory creation propagates EACCES unmodified. Common in init scripts that create log or pid files in permission-restricted paths.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
Sources[15][16]
ensureFile · ensurefile-path-component-is-file
error
WhenA component of the path that should be a directory is actually an existing file
ThrowsError with code ENOTDIR
Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOTDIR'. The source explicitly calls fs.readdir(dir) to trigger ENOTDIR when the parent stat shows it is not a directory. Common in misconfigured deployments where a path component is a file, not a directory.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[16]
mkdirp · mkdirp-permission-denied
error
WhenProcess lacks write or execute permission on a parent directory component
ThrowsError with code EACCES
Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' to handle permission errors. mkdirp() is identical to ensureDir() — both call fs.mkdir({recursive: true}) via makeDir. Directory creation fails — subsequent file writes to that path will also fail with ENOENT. Ensure the process has write permission on all parent directory components.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
Sources[9][10][17]
mkdirp · mkdirp-path-component-is-file
error
WhenA component of the path that should be a directory is actually an existing file
ThrowsError with code ENOTDIR
Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOTDIR' to detect path conflicts. Same behavior as ensureDir() — a path component that exists as a file instead of a directory causes ENOTDIR from the underlying fs.mkdir({recursive: true}) call.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[9][10]
mkdirs · mkdirs-permission-denied
error
WhenProcess lacks write or execute permission on a parent directory component
ThrowsError with code EACCES
Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' to handle permission errors. mkdirs() is identical to ensureDir() and mkdirp() — all call fs.mkdir({recursive: true}) via the same makeDir function. Directory creation failure will block all subsequent I/O at that path.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
Sources[9][10][17]
mkdirs · mkdirs-path-component-is-file
error
WhenA component of the path that should be a directory is actually an existing file
ThrowsError with code ENOTDIR
Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOTDIR' to detect path conflicts. mkdirs() is identical to ensureDir() — same underlying fs.mkdir({recursive: true}) behavior.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[9][10]
createFile · createfile-permission-denied
error
WhenProcess lacks write permission on the target directory or execute permission on a parent
ThrowsError with code EACCES
Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES'. createFile() is the same underlying function as ensureFile() — both are exported as the same reference. Parent directory creation propagates EACCES from mkdir.mkdirs() unmodified. Common in init scripts that create log or pid files in permission-restricted paths.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
Sources[15][16][18]
createFile · createfile-path-component-is-file
error
WhenA component of the path that should be a directory is actually an existing file
ThrowsError with code ENOTDIR
Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOTDIR'. The source explicitly calls fs.readdir(dir) to trigger ENOTDIR when the parent stat shows it is not a directory. createFile() is the same function as ensureFile() — identical ENOTDIR behavior.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[16]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

Need a different package?

Request a profile