Node:FS

Read and write files in Edge Scripts using the Node.js-compatible file system API

No breaking changes are expected, but additional features will be implemented soon.

Overview

Edge Scripting supports the Node.js file system API through the node:fs and node:fs/promises modules, so you can read, write, and manipulate files and directories from inside an Edge Script.

The implementation sits on Deno’s sandboxed environment with Node.js compatibility. Both the Promise-based API (node:fs/promises) and the older callback-based API (node:fs) work. We recommend the Promise-based one for the cleaner async/await syntax.

Virtual file system

Every script gets a virtual file system for file operations. It lives in the virtual memory available to the worker.

The directory tree currently has two folders:

/ # Root directory
├── home/
│   └── user/ # Your current working directory, R/W access
└── tmp/ # Temporary directory, R/W access

You can create directories anywhere. Permissions are enforced for the owner (user) but not for group or others. All files are opened in w+.

Avoid creating directories in the root directory /. We plan to add folders there for other functions, such as /dev/* and other read only directories.

Paths in the virtual file system are limited to 4096 characters (foo/bar counts as 7) and to 48 segments (a/b/c is 3 segments).

Capacity checks for creating, copying and moving happen before the operation runs. Copying a large file can therefore fail with an out of memory error even though there is still space to create new files or directories.

Importing the module

EdgeScripting supports both the Promise-based API and the callback-based API.

Promise-based API (recommended)

import * as fs from "node:fs/promises";

// Use with async/await
const data = await fs.readFile("/tmp/file.txt", "utf-8");

Callback-based API

import * as fs from "node:fs";

// Use with callbacks
fs.readFile("/tmp/file.txt", "utf-8", (err, data) => {
  if (err) {
    console.error("Error:", err);
    return;
  }
  console.log("Data:", data);
});

Limitations

The file system runs in a sandbox, which constrains what it can do. The following sections cover where it differs from Node.js.

Always handle file system errors gracefully. The sandboxed environment may behave differently from traditional Node.js environments.

Symbolic links and hard links

Symbolic links are supported. symlink(), symlinkSync(), readlink(), readlinkSync(), and lstat() work as expected.

Hard links are not supported. link() and linkSync() will throw errors.

File statistics and timestamps

All Stats timestamp properties are supported and return correct values:

Reliable Stats properties:

• size - File size in bytes
• isFile() - Check if entry is a file
• isDirectory() - Check if entry is a directory
• atime - Last access time
• mtime - Last modification time
• ctime - Last status change time
• atimeMs, mtimeMs, ctimeMs - Millisecond timestamps
• birthtime - File creation time

File and directory permissions

File and directory permissions are supported for the owner (user) bits. chmod() and chmodSync() work, and Stats.mode reflects the permissions you set. access() respects owner-level read, write, and execute bits.

Group and others permission bits are accepted but have no effect: the sandboxed environment always runs as the file owner (uid=1000, gid=1000), so only the user/owner bits matter.

chown() and chownSync() are implemented for compatibility, but ownership is not enforced. Changing the uid or gid has no effect on file access or permissions.

File watching

File system watching is not supported.

The following operations are unavailable:

• watch() - Watch for file changes
• watchFile() - Poll for file changes
• unwatchFile() - Stop watching
• FSWatcher class

Workaround: Use polling with stat() if you need to detect changes, but be mindful of performance implications and CPU time limits.

Performance considerations

Memory limits: The whole Virtual FileSystem lives inside your script memory. The current file system limits of your script is set up to 64MB. Reading large files may cause memory exhaustion if you store it in memory. Leverage streaming to avoid allocating too much memory at a time.

CPU time: File I/O counts toward the 30-second CPU time limit per request.

Best practices:

• Stream large files instead of reading entirely into memory
• Clean up temporary files to avoid storage bloat
• See Limits for more details on resource constraints

Quickstart

Common file system patterns in EdgeScripting.

Example 1: Reading a file

import * as fs from "node:fs/promises";
import * as BunnySDK from "@bunny.net/edgescript-sdk";

BunnySDK.net.http.serve(async (request: Request) => {
  try {
    // Read file as UTF-8 string
    const content = await fs.readFile("/tmp/data.txt", "utf-8");

    return new Response(content, {
      headers: { "content-type": "text/plain" }
    });
  } catch (error) {
    return new Response(`Error reading file: ${error.message}`, {
      status: 500
    });
  }
});

Example 2: Writing a file

import * as fs from "node:fs/promises";
import * as BunnySDK from "@bunny.net/edgescript-sdk";

BunnySDK.net.http.serve(async (request: Request) => {
  const data = await request.json();

  try {
    // Write JSON data to file
    await fs.writeFile(
      "/tmp/output.json",
      JSON.stringify(data, null, 2),
      "utf-8"
    );

    return new Response("File written successfully", { status: 201 });
  } catch (error) {
    return new Response(`Error writing file: ${error.message}`, {
      status: 500
    });
  }
});

Example 3: Working with directories

import * as fs from "node:fs/promises";
import * as BunnySDK from "@bunny.net/edgescript-sdk";

BunnySDK.net.http.serve(async (request: Request) => {
  try {
    // Create directory (recursive option creates parent directories)
    await fs.mkdir("/tmp/myapp/data", { recursive: true });

    // Write a file in the new directory
    await fs.writeFile("/tmp/myapp/data/config.json", "{}", "utf-8");

    // List directory contents
    const files = await fs.readdir("/tmp/myapp/data");

    return new Response(JSON.stringify({ files }), {
      headers: { "content-type": "application/json" }
    });
  } catch (error) {
    return new Response(`Error: ${error.message}`, { status: 500 });
  }
});

Example 4: Error handling patterns

import * as fs from "node:fs/promises";
import * as BunnySDK from "@bunny.net/edgescript-sdk";

BunnySDK.net.http.serve(async (request: Request) => {
  const filepath = "/tmp/cache/data.txt";

  try {
    // Check if file exists by trying to access it
    await fs.access(filepath);

    // File exists, read it
    const content = await fs.readFile(filepath, "utf-8");
    return new Response(content, {
      headers: { "x-cache": "hit" }
    });
  } catch (error) {
    if (error.code === "ENOENT") {
      // File doesn't exist, create it
      const defaultContent = "Default cached data";
      await fs.writeFile(filepath, defaultContent, "utf-8");

      return new Response(defaultContent, {
        status: 201,
        headers: { "x-cache": "miss" }
      });
    }

    // Re-throw other errors
    throw error;
  }
});

Example 5: Using FileHandle for chunked reading

This script is not optimized. It shows how chunked reading works, so please don’t run anything like it in production.

import * as fs from "node:fs/promises";
import * as BunnySDK from "@bunny.net/edgescript-sdk";

// Global promise to track the download operation
let downloadPromise: Promise<void> | null = null;
const filePath = "/tmp/large-file.txt";

async function downloadLoremIpsum() {
  try {
    const response = await fetch('https://lorem-api.com/api/lorem', {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const content = await response.text();
    
    // Calculate how many times we need to repeat to reach ~10MB
    const targetSize = 10 * 1024 * 1024; // 10MB in bytes
    const contentSize = Buffer.byteLength(content, 'utf-8');
    const repeatCount = Math.ceil(targetSize / contentSize);
    
    // Create the repeated content
    let finalContent = '';
    for (let i = 0; i < repeatCount; i++) {
      finalContent += content;
    }
    
    // Write to file
    await fs.writeFile(filePath, finalContent, 'utf-8');
  } catch (error) {
    // Clear the promise on error so it can be retried
    downloadPromise = null;
    throw error;
  }
}

async function ensureFileExists() {
  try {
    // Check if file exists
    await fs.access(filePath);
  } catch (error) {
    // File doesn't exist, initiate download
    if (!downloadPromise) {
      // Start download and store the promise
      downloadPromise = downloadLoremIpsum();
    }
    // Wait for the download to complete (whether we started it or another request did)
    await downloadPromise;
  }
}

BunnySDK.net.http.serve(async (request: Request) => {
  try {
    // Ensure file exists (download if necessary, blocking until complete)
    await ensureFileExists();

    // Create SSE stream
    const stream = new ReadableStream({
      async start(controller) {
        const encoder = new TextEncoder();
        let fileHandle;
        
        try {
          // Open file for reading
          fileHandle = await fs.open(filePath, "r");
          
          // Get file stats to know the total size
          const stats = await fileHandle.stat();
          const totalSize = stats.size;
          
          // Send initial event with file info
          controller.enqueue(encoder.encode(`data: ${JSON.stringify({
            type: "start",
            totalSize,
            chunkSize: 1024,
            timestamp: new Date().toISOString()
          })}\n\n`));
          
          const buffer = new Uint8Array(1024);
          let position = 0;
          let chunkNumber = 0;
          
          // Read file 1KB at a time
          while (position < totalSize) {
            const { bytesRead } = await fileHandle.read(buffer, 0, 1024, position);
            
            if (bytesRead === 0) break; // End of file
            
            // Convert to string
            const content = new TextDecoder().decode(buffer.slice(0, bytesRead));
            
            // Send chunk as SSE event
            controller.enqueue(encoder.encode(`data: ${JSON.stringify({
              type: "chunk",
              chunkNumber,
              bytesRead,
              position,
              content,
              progress: ((position + bytesRead) / totalSize * 100).toFixed(2) + "%",
              timestamp: new Date().toISOString()
            })}\n\n`));
            
            position += bytesRead;
            chunkNumber++;
            
            // Small delay to prevent overwhelming the client
            await new Promise(resolve => setTimeout(resolve, 10));
          }
          
          // Send completion event
          controller.enqueue(encoder.encode(`data: ${JSON.stringify({
            type: "complete",
            totalChunks: chunkNumber,
            totalBytesRead: position,
            timestamp: new Date().toISOString()
          })}\n\n`));
          
        } catch (error) {
          // Send error event
          controller.enqueue(encoder.encode(`data: ${JSON.stringify({
            type: "error",
            message: error.message,
            timestamp: new Date().toISOString()
          })}\n\n`));
        } finally {
          // Close file handle
          await fileHandle?.close();
          controller.close();
        }
      }
    });
    
    return new Response(stream, {
      headers: {
        "Content-Type": "text/event-stream",
        "Cache-Control": "no-cache",
        "Connection": "keep-alive",
        "X-Accel-Buffering": "no"
      }
    });
    
  } catch (error) {
    return new Response(`Error: ${error.message}`, { status: 500 });
  }
});

Example 6: Symbolic links

import * as fs from "node:fs/promises";
import * as BunnySDK from "@bunny.net/edgescript-sdk";

BunnySDK.net.http.serve(async (request: Request) => {
  const original = "/tmp/original.txt";
  const link = "/tmp/link.txt";

  try {
    await fs.writeFile(original, "hello from original", "utf-8");

    // Create a symbolic link pointing to the original file
    await fs.symlink(original, link);

    // Reading through the symlink is transparent
    const content = await fs.readFile(link, "utf-8");

    // lstat inspects the link itself, not the target
    const linkStats = await fs.lstat(link);
    const target = await fs.readlink(link);

    return new Response(
      JSON.stringify({ content, isSymlink: linkStats.isSymbolicLink(), target }),
      { headers: { "content-type": "application/json" } }
    );
  } catch (error) {
    return new Response(`Error: ${error.message}`, { status: 500 });
  }
});

References

• Node.js File System Documentation - Complete Node.js fs module reference
• Node.js fs/promises API - Promise-based file system API
• Node.js FileHandle Class - Advanced file operations
• Node.js File System Flags - Available flags for file operations
• MDN File API - Web standard File interface
• MDN Blob - Binary data objects
• MDN TextEncoder - Encoding strings to bytes
• MDN TextDecoder - Decoding bytes to strings
• EdgeScripting Limits - Resource limits and quotas