Fs

Read, write, copy, move, and manage files and directories

Package: @robinpath/fs | Category: Utility | Type: Utility

Authentication

No authentication required. All functions are available immediately.

Use Cases

Use the fs module when you need to:

• Read the contents of a file as a string -- Use fs.read to perform this operation
• Write content to a file, creating or overwriting it -- Use fs.write to perform this operation
• Append content to the end of a file -- Use fs.append to perform this operation
• Check whether a file or directory exists at the given path -- Use fs.exists to perform this operation
• Delete a file -- Use fs.delete to perform this operation

Quick Reference

Function	Description	Returns
read	Read the contents of a file as a string	The file contents as a string
write	Write content to a file, creating or overwriting it	True if the write succeeded
append	Append content to the end of a file	True if the append succeeded
exists	Check whether a file or directory exists at the given path	True if the path exists, false otherwise
delete	Delete a file	True if the file was deleted
copy	Copy a file from source to destination	True if the copy succeeded
move	Move or rename a file from source to destination	True if the move succeeded
rename	Rename a file (alias for move)	True if the rename succeeded
list	List the contents of a directory	Array of filenames in the directory
mkdir	Create a directory (recursively creates parent directories)	True if the directory was created
rmdir	Remove a directory and its contents	True if the directory was removed
stat	Get file or directory statistics	Object with size, isFile, isDirectory, created, and modified properties
isFile	Check whether a path points to a regular file	True if the path is a regular file, false otherwise
isDir	Check whether a path points to a directory	True if the path is a directory, false otherwise

Functions

read

Read the contents of a file as a string

Module: fs | Returns: string -- The file contents as a string

any "/tmp/file.txt"

Parameter	Type	Required	Description
path	string	Yes	Absolute or relative path to the file
encoding	string	No	Character encoding (default: utf-8)

---

write

Write content to a file, creating or overwriting it

Module: fs | Returns: boolean -- True if the write succeeded

any "/tmp/file.txt" "hello world"

Parameter	Type	Required	Description
path	string	Yes	Absolute or relative path to the file
content	string	Yes	The content to write

---

append

Append content to the end of a file

Module: fs | Returns: boolean -- True if the append succeeded

any "/tmp/file.txt" "more text"

Parameter	Type	Required	Description
path	string	Yes	Absolute or relative path to the file
content	string	Yes	The content to append

---

exists

Check whether a file or directory exists at the given path

Module: fs | Returns: boolean -- True if the path exists, false otherwise

any "/tmp/file.txt"

Parameter	Type	Required	Description
path	string	Yes	Absolute or relative path to check

---

delete

Delete a file

Module: fs | Returns: boolean -- True if the file was deleted

any "/tmp/file.txt"

Parameter	Type	Required	Description
path	string	Yes	Absolute or relative path to the file to delete

---

copy

Copy a file from source to destination

Module: fs | Returns: boolean -- True if the copy succeeded

any "/tmp/a.txt" "/tmp/b.txt"

Parameter	Type	Required	Description
src	string	Yes	Path to the source file
dest	string	Yes	Path to the destination file

---

move

Move or rename a file from source to destination

Module: fs | Returns: boolean -- True if the move succeeded

any "/tmp/old.txt" "/tmp/new.txt"

Parameter	Type	Required	Description
src	string	Yes	Path to the source file
dest	string	Yes	Path to the destination file

---

rename

Rename a file (alias for move)

Module: fs | Returns: boolean -- True if the rename succeeded

any "/tmp/old.txt" "/tmp/new.txt"

Parameter	Type	Required	Description
oldPath	string	Yes	Current file path
newPath	string	Yes	New file path

---

list

List the contents of a directory

Module: fs | Returns: array -- Array of filenames in the directory

any "/tmp"

Parameter	Type	Required	Description
dir	string	Yes	Path to the directory to list

---

mkdir

Create a directory (recursively creates parent directories)

Module: fs | Returns: boolean -- True if the directory was created

any "/tmp/my/nested/dir"

Parameter	Type	Required	Description
path	string	Yes	Path of the directory to create

---

rmdir

Remove a directory and its contents

Module: fs | Returns: boolean -- True if the directory was removed

any "/tmp/my/dir"

Parameter	Type	Required	Description
path	string	Yes	Path of the directory to remove

---

stat

Get file or directory statistics

Module: fs | Returns: object -- Object with size, isFile, isDirectory, created, and modified properties

any "/tmp/file.txt"

Parameter	Type	Required	Description
path	string	Yes	Path to the file or directory

---

isFile

Check whether a path points to a regular file

Module: fs | Returns: boolean -- True if the path is a regular file, false otherwise

any "/tmp/file.txt"

Parameter	Type	Required	Description
path	string	Yes	Path to check

---

isDir

Check whether a path points to a directory

Module: fs | Returns: boolean -- True if the path is a directory, false otherwise

any "/tmp"

Parameter	Type	Required	Description
path	string	Yes	Path to check

---

Error Handling

All functions throw on failure. Common errors:

Error	Cause
(standard errors)	Check function parameters and authentication

@desc "Validate result"
do
  set $result as any "/tmp/file.txt"
  if $result != null
    print "Success"
  else
    print "No result"
  end
enddo

Recipes

1. List and iterate

Retrieve all items and loop through them.

@desc "Iterate results"
do
  set $result as any "/tmp"
  each $item in $result
    print $item
  end
enddo

2. Multi-step Fs workflow

Chain multiple fs operations together.

@desc "Execute operation"
do
  set $r_read as any "/tmp/file.txt"
  set $r_write as any "/tmp/file.txt" "hello world"
  set $r_append as any "/tmp/file.txt" "more text"
  print "All operations complete"
enddo

3. Safe read with validation

Check results before proceeding.

@desc "Validate result"
do
  set $result as any "/tmp/file.txt"
  if $result != null
    print "Success: " + $result
  else
    print "Operation returned no data"
  end
enddo

Related Modules

• json -- JSON module for complementary functionality