PersistentAI API Documentation / @persistentai/fireflow-types / IVFSWriteContextService

Interface: IVFSWriteContextService

Defined in: packages/fireflow-types/src/execution/services/vfs-write-context-service.ts:91

VFS Write Context Service Interface

Extends IVFSContextService with write, search, and git operations. Write operations are STAGED (not auto-committed). Use commit() to persist.

Extends

• IVFSContextService

Properties

commit()

commit: (workspaceId, branch, message) => Promise<ICommitResult>

Defined in: packages/fireflow-types/src/execution/services/vfs-write-context-service.ts:98

Parameters

workspaceId

string

branch

string

message

string

Returns

Promise<ICommitResult>

---

createFolder()

createFolder: (workspaceId, branch, path) => Promise<IWriteResult>

Defined in: packages/fireflow-types/src/execution/services/vfs-write-context-service.ts:95

Parameters

workspaceId

string

branch

string

path

string

Returns

Promise<IWriteResult>

---

deleteFile()

deleteFile: (workspaceId, branch, path) => Promise<void>

Defined in: packages/fireflow-types/src/execution/services/vfs-write-context-service.ts:94

Parameters

workspaceId

string

branch

string

path

string

Returns

Promise<void>

---

editFile()

editFile: (workspaceId, branch, path, edits) => Promise<IEditResult>

Defined in: packages/fireflow-types/src/execution/services/vfs-write-context-service.ts:93

Parameters

workspaceId

string

branch

string

path

string

edits

IFileEdit[]

Returns

Promise<IEditResult>

---

exists()

exists: (workspaceId, ref, path) => Promise<boolean>

Defined in: packages/fireflow-types/src/execution/services/vfs-context-service.ts:205

Check if a file or directory exists.

Parameters

workspaceId

string

The workspace (lakeFS repository) ID

ref

string

Branch, tag, or commit ID

path

string

Path within the workspace

Returns

Promise<boolean>

true if exists AND user has read permission

Example

if (await vfs.exists('ws-123', 'main', 'config/optional.json')) {
  const config = await vfs.readFile('ws-123', 'main', 'config/optional.json');
}

Inherited from

IVFSContextService.exists

---

getPresignedUrl()

getPresignedUrl: (workspaceId, ref, path) => Promise<IPresignedUrlResult>

Defined in: packages/fireflow-types/src/execution/services/vfs-context-service.ts:188

Get a pre-signed URL for direct file access.

Use this for:

• Binary files (images, PDFs, audio, video)
• Large files that shouldn't be loaded into memory
• Passing URLs to external services

Parameters

workspaceId

string

The workspace (lakeFS repository) ID

ref

string

Branch, tag, or commit ID

path

string

Path within the workspace

Returns

Promise<IPresignedUrlResult>

Pre-signed URL info with expiration

Throws

Error if permission denied

Example

const { url } = await vfs.getPresignedUrl('ws-123', 'main', 'images/photo.jpg');
// Pass URL to image processing service
await processImage(url);

Inherited from

IVFSContextService.getPresignedUrl

---

getStatus()

getStatus: (workspaceId, branch) => Promise<IStatusEntry[]>

Defined in: packages/fireflow-types/src/execution/services/vfs-write-context-service.ts:99

Parameters

workspaceId

string

branch

string

Returns

Promise<IStatusEntry[]>

---

glob()

glob: (workspaceId, ref, pattern, options?) => Promise<string[]>

Defined in: packages/fireflow-types/src/execution/services/vfs-write-context-service.ts:96

Parameters

workspaceId

string

ref

string

pattern

string

options?

IGlobOptions

Returns

Promise<string[]>

---

grep()

grep: (workspaceId, ref, pattern, options?) => Promise<IGrepMatch[]>

Defined in: packages/fireflow-types/src/execution/services/vfs-write-context-service.ts:97

Parameters

workspaceId

string

ref

string

pattern

string

options?

IGrepOptions

Returns

Promise<IGrepMatch[]>

---

listDirectory()

listDirectory: (workspaceId, ref, path) => Promise<ITreeNode[]>

Defined in: packages/fireflow-types/src/execution/services/vfs-context-service.ts:222

List contents of a directory.

Parameters

workspaceId

string

The workspace (lakeFS repository) ID

ref

string

Branch, tag, or commit ID

path

string

Directory path (use "" for root)

Returns

Promise<ITreeNode[]>

Array of file/directory entries

Throws

Error if permission denied or path is not a directory

Example

const entries = await vfs.listDirectory('ws-123', 'main', 'flows/');
const flowFiles = entries.filter(e => e.name.endsWith('.fflow'));

Inherited from

IVFSContextService.listDirectory

---

readFile()

readFile: (workspaceId, ref, path) => Promise<string>

Defined in: packages/fireflow-types/src/execution/services/vfs-context-service.ts:165

Read a text file's contents as a UTF-8 string.

ONLY works for text-based content types (JSON, YAML, Markdown, etc.). For binary files, use getPresignedUrl() instead.

Parameters

workspaceId

string

The workspace (lakeFS repository) ID

ref

string

Branch, tag, or commit ID

path

string

Path within the workspace (e.g., "config/settings.json")

Returns

Promise<string>

File contents as string

Throws

Error if permission denied or file is binary

Example

const json = await vfs.readFile('ws-123', 'main', 'flows/calc.fflow');
const flowDef = JSON.parse(json);

Inherited from

IVFSContextService.readFile

---

stat()

stat: (workspaceId, ref, path) => Promise<IFileStat | null>

Defined in: packages/fireflow-types/src/execution/services/vfs-context-service.ts:242

Get metadata about a file or directory.

Parameters

workspaceId

string

The workspace (lakeFS repository) ID

ref

string

Branch, tag, or commit ID

path

string

Path within the workspace

Returns

Promise<IFileStat | null>

File metadata, or null if not found

Throws

Error if permission denied

Example

const stats = await vfs.stat('ws-123', 'main', 'data/large-file.csv');
if (stats && stats.size > 10_000_000) {
  // File is > 10MB, use presigned URL instead
  const { url } = await vfs.getPresignedUrl(...);
}

Inherited from

IVFSContextService.stat

---

writeFile()

writeFile: (workspaceId, branch, path, content) => Promise<IWriteResult>

Defined in: packages/fireflow-types/src/execution/services/vfs-write-context-service.ts:92

Parameters

workspaceId

string

branch

string

path

string

content

string

Returns

Promise<IWriteResult>