fs Stable WINMACLNX

File system access with per-path capability enforcement.

Requires capability: "fs" — with read/write glob lists enforced on every call:

{ "capabilities": { "fs": { "read": ["assets/**"], "write": ["data/**"] } } }

A call outside the declared globs rejects with the offending path. Relative patterns anchor at the app root; use "**" to allow everything (needed for OS file-picker results). See Capability scoping.

Requires capability: "fs" — with three independently-scoped glob arrays:

capabilities: {
  fs: {
    read:   ['public/**', 'data/**'],  // readFile, readFileBytes, listDir, stat
    write:  ['data/**'],               // writeFile, appendFile, mkdirp, rename, copy
    delete: ['data/trash/**'],         // deleteFile only; omit to inherit write globs
  },
}

delete is optional. When absent it falls back to write globs. Set to [] to allow writes but block all deletion.

Import

import { fs } from '@glyx-dev/react'

Reading files

// Read file as a UTF-8 string
const content = await fs.readFile('~/Documents/notes.txt')
 
// Read file as a base64-encoded string (NOT a Uint8Array — decode with
// atob() or a base64 library if you need raw bytes)
const base64 = await fs.readFileBytes('~/Downloads/image.png')

Writing files

// Write or overwrite a file
await fs.writeFile('~/output.txt', 'Hello, world!')
 
// Append to a file
await fs.appendFile('~/log.txt', `${new Date().toISOString()} — event\n`)

Directory operations

// List a directory — returns an array of entry objects
const entries = await fs.listDir('~/Documents')
// → [{ name: 'notes.txt', isDir: false }, { name: 'archive', isDir: true }]
 
// Create a directory (including intermediate dirs)
await fs.mkdirp('~/Documents/my-app/data')
 
// Delete a file
await fs.deleteFile('~/temp/file.txt')

File metadata and moves

// Stat a file or directory
const info = await fs.stat('data/notes.db')
// → { size: 4096, mtime: 1720473600000, isDir: false, isFile: true }
 
// Rename / move a file
await fs.rename('data/old-name.txt', 'data/new-name.txt')
 
// Copy a file
await fs.copy('assets/template.db', 'data/app.db')

Watching files

fs.watch subscribes to OS-level file system events (inotify / FSEvents / ReadDirectoryChangesW). Events are delivered frame-synced — not by polling the disk.

// Watch a file or directory
const id = await fs.watch('data/notes.db', (event) => {
  console.log(event.type, event.path) // 'modified' | 'created' | 'removed' | 'accessed'
})
 
// Stop watching
await fs.unwatch(id)

Requires fs.read permission on the target path. Watching a directory is recursive.

JSON helpers

// Read and parse JSON in one call
const config = await fs.readJSON('data/config.json')
 
// Serialize and write JSON
await fs.writeJSON('data/config.json', { theme: 'dark', fontSize: 14 })
// writeJSON accepts an optional indent arg (default 2):
await fs.writeJSON('data/compact.json', data, 0)

Example: read and write a config file

import { fs } from '@glyx-dev/react'
 
const CONFIG_PATH = 'data/config.json'
 
export async function loadConfig() {
  try {
    const raw = await fs.readFile(CONFIG_PATH)
    return JSON.parse(raw)
  } catch {
    return { theme: 'dark' }
  }
}
 
export async function saveConfig(config: object) {
  await fs.writeFile(CONFIG_PATH, JSON.stringify(config, null, 2))
}

API reference

Function	Signature	Description
`readFile`	`(path: string) → Promise<string>`	Read file as UTF-8 text
`readFileBytes`	`(path: string) → Promise<string>`	Read file as base64 bytes
`readJSON`	`(path: string) → Promise<unknown>`	Read + JSON.parse
`writeFile`	`(path: string, content: string) → Promise<void>`	Write (overwrite) a file
`writeJSON`	`(path: string, val: unknown, indent?: number) → Promise<void>`	JSON.stringify + write
`appendFile`	`(path: string, content: string) → Promise<void>`	Append to a file
`listDir`	`(path: string) → Promise<{name:string,isDir:boolean}[]>`	List directory entries
`stat`	`(path: string) → Promise<{size,mtime,isDir,isFile}>`	File metadata
`rename`	`(src: string, dst: string) → Promise<void>`	Rename / move a file
`copy`	`(src: string, dst: string) → Promise<void>`	Copy a file
`deleteFile`	`(path: string) → Promise<void>`	Delete a file (gated by `fs.delete` globs)
`mkdirp`	`(path: string) → Promise<void>`	Create directory tree
`watch`	`(path: string, cb: (e: FsEvent) → void) → Promise<number>`	Watch file or directory for changes
`unwatch`	`(id: number) → Promise<void>`	Stop a watcher

vectorDb network