libgio-node

libgio-node is a native Node addon (N-API + GLib/GIO) focused on Linux file and mount operations.

Platform and Safety

• Linux only.
• Designed for Electron and Node.
• This module can modify and delete files. Use with care.

Install

npm i libgio-node

Import

For Electron (CommonJS)

const gio = require('libgio-node');

For ESM

import gio from 'libgio-node';

Current Exported Functions

The addon currently exports:

1. ls(pathOrUri, callback)
2. get_file(pathOrUri)
3. get_file_icon(pathOrUri)
4. get_file_icon_path(pathOrUri)
5. cp(src, dest, overwriteFlag?)
6. cp_async(src, dest, callback)
7. cp_cancel(handle)
8. mkdir(pathOrUri)
9. mv(src, dest, progressCallback?)
10. rm(pathOrUri)
11. rm_async(pathOrUri, callback)
12. rm_cancel(handle)
13. mount(driveName, callback)
14. umount(target, callback)
15. monitor(callback)
16. open_with(pathOrUri)
17. du(pathOrUri)
18. count(pathOrUri)
19. disk_stats(pathOrUri)
20. watch(pathOrUri, callback)
21. stop_watch(pathOrUri)
22. exec(command, callback)
23. set_execute(pathOrUri)
24. clear_execute(pathOrUri)
25. exists(pathOrUri)
26. get_drives(callback)
27. get_mounts(callback)
28. connect_network_drive(host, port, username, password, ssh_key, type, callback)
29. find(query, callback)
30. find(query, sourcePath, callback)
31. find(query, options, callback)
32. find(query, sourcePath, options, callback)

Usage

List files

gio.ls("/tmp", (err, files) => {
    if (err) {
        console.error("ls error:", err);
        return;
    }
    console.log(files);
});

Get one file metadata

try {
    const file = gio.get_file("/tmp/example.txt");
    console.log(file.name, file.size, file.is_dir);
} catch (err) {
    console.error(err);
}

try {
    const icon = gio.get_file_icon("/tmp/example.txt");
    console.log(icon.icon, icon.names);
} catch (err) {
    console.error(err);
}

try {
    const iconPath = gio.get_file_icon_path("/tmp/example.txt");
    console.log(iconPath.icon_path, iconPath.symbolic_icon_path);
} catch (err) {
    console.error(err);
}

Copy (sync)

try {
    gio.cp("/tmp/a.txt", "/tmp/b.txt", 1); // overwriteFlag=1
} catch (err) {
    console.error(err);
}

Copy (async + cancel)

const copyHandle = gio.cp_async("/tmp/a.bin", "/tmp/b.bin", (err, data) => {
    if (err) {
        console.error("copy failed/cancelled:", err);
        return;
    }

    // Progress callback payload
    if (!data.completed) {
        console.log("progress", data.current_num_bytes, data.total_bytes);
        return;
    }

    // Completion payload
    console.log("copy completed");
});

// Later:
// gio.cp_cancel(copyHandle);

Remove (sync)

try {
    gio.rm("/tmp/b.txt");
} catch (err) {
    console.error(err);
}

Remove (async + cancel)

const rmHandle = gio.rm_async("/tmp/big-file.bin", (err, ok) => {
    if (err) {
        console.error("rm failed/cancelled:", err);
        return;
    }
    console.log("removed:", ok);
});

// Later:
// gio.rm_cancel(rmHandle);

Move

try {
    gio.mv("/tmp/src.txt", "/tmp/dst.txt", (err, data) => {
        if (!err) console.log("mv progress", data);
    });
} catch (err) {
    console.error(err);
}

Directory monitor

gio.watch("/tmp", (event) => {
    console.log(event.event, event.filename);
});

// Later:
// gio.stop_watch("/tmp");

Device/mount monitor

gio.monitor((name) => {
    console.log("device/mount event:", name);
});

Drives and mounts

gio.get_drives((err, drives) => {
    if (!err) console.log(drives);
});

gio.get_mounts((err, mounts) => {
    if (!err) console.log(mounts);
});

Mount and unmount

gio.mount("MyDriveName", (err, msg) => {
    if (err) console.error(err);
    else console.log(msg);
});

gio.umount("/run/user/1000/gvfs/smb-share:server=host,share=data", (err, msg) => {
    if (err) console.error(err);
    else console.log(msg);
});

Connect network drive

gio.connect_network_drive(
    "server.local", // host
    22,             // port
    "user",        // username
    "pass",        // password
    0,              // ssh_key flag
    "smb",         // type: smb or ssh
    (err, data) => {
        if (err) {
            console.error(err);
            return;
        }
        console.log(data);
    }
);

Utility calls

console.log(gio.exists("/tmp"));
console.log(gio.du("/tmp"));
console.log(gio.count("/tmp"));
console.log(gio.disk_stats("/tmp"));

gio.exec("ls -la /tmp", (err, lines) => {
    if (!err) console.log(lines);
});

gio.open_with("/tmp/example.pdf");
gio.set_execute("/tmp/script.sh");
gio.clear_execute("/tmp/script.sh");

Find

gio.find("report", (err, results) => {
    if (!err) console.log(results);
});

gio.find("report", "/home/user/Documents", (err, results) => {
    if (!err) console.log(results);
});

gio.find("report", "/home/user/Documents", {
    minSize: 1024,
    maxSize: 10 * 1024 * 1024,
    dateFrom: "2026-01-01T00:00:00Z",
    dateTo: new Date(),
}, (err, results) => {
    if (!err) console.log(results);
});

find uses Tracker when available and falls back to recursive GIO filesystem search when Tracker is unavailable or returns no matches.

Callback Notes

• Error style is mixed in the current native implementation.
• Some APIs pass string errors ("..."), while others may pass Error objects.
• Most success callbacks follow (null, data).

Build From Source

npm run build

---

Version: 1.0.7

---