PersistentAI API Documentation / @persistentai/fireflow-vfs / server / VfsUri

Class: VfsUri

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:43

Immutable VFS URI with ff:// scheme.

VfsUri wraps a VfsPath and adds URI semantics:

• Always has the ff:// scheme prefix
• Can optionally include workspace and branch context

Supported formats:

• ff:///path/to/file - Simple path
• ff://path/to/file - Also valid (leading slash optional after scheme)
• ff://workspace@branch/path - With workspace and branch context (future)

Example

// Parse from URI string
const uri = VfsUri.parse('ff:///foo/bar.txt')
uri.path.name    // 'bar.txt'
uri.toString()   // 'ff:///foo/bar.txt'

// Create from path
const uri2 = VfsUri.fromPath('/foo/bar.txt')
uri2.toString()  // 'ff:///foo/bar.txt'

// Operations
uri.join('child.txt').toString() // 'ff:///foo/bar.txt/child.txt'

Accessors

branch

Get Signature

get branch(): string | undefined

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:160

Branch name if present.

Returns

string | undefined

---

extension

Get Signature

get extension(): string

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:183

Get the file extension from the path.

Returns

string

---

hasContext

Get Signature

get hasContext(): boolean

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:167

Whether this URI has workspace context.

Returns

boolean

---

isDirectory

Get Signature

get isDirectory(): boolean

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:197

Whether the path represents a directory.

Returns

boolean

---

isRoot

Get Signature

get isRoot(): boolean

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:204

Whether this is the root path.

Returns

boolean

---

name

Get Signature

get name(): string

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:176

Get the filename from the path.

Returns

string

---

path

Get Signature

get path(): VfsPath

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:146

The path component.

Returns

VfsPath

---

scheme

Get Signature

get scheme(): string

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:139

The URI scheme (always 'ff').

Returns

string

---

stem

Get Signature

get stem(): string

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:190

Get the stem (filename without extension) from the path.

Returns

string

---

workspace

Get Signature

get workspace(): string | undefined

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:153

Workspace ID if present.

Returns

string | undefined

Methods

equals()

equals(other): boolean

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:269

Check equality with another VfsUri.

Parameters

other

VfsUri

URI to compare

Returns

boolean

True if URIs are equal (including context)

---

join()

join(child): VfsUri

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:227

Join a child path to this URI.

Parameters

child

Child path to join

string | VfsPath

Returns

VfsUri

New VfsUri with joined path

---

parent()

parent(): VfsUri

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:237

Get the parent URI.

Returns

VfsUri

Parent URI (root returns itself)

---

pathEquals()

pathEquals(other): boolean

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:283

Check if paths are equal (ignoring context).

Parameters

other

VfsUri

URI to compare

Returns

boolean

True if paths are equal

---

toJSON()

toJSON(): object

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:316

Create a JSON-serializable representation.

Returns

object

branch?

optional branch: string

path

path: string

uri

uri: string

workspace?

optional workspace: string

---

toPathString()

toPathString(): string

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:309

Extract just the path string (without scheme or context).

Returns

string

Example

VfsUri.parse('ff:///foo/bar').toPathString() // '/foo/bar'

---

toString()

toString(): string

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:296

Convert to full URI string.

Returns

string

Example

VfsUri.fromPath('/foo/bar').toString()                    // 'ff:///foo/bar'
VfsUri.create('/foo', 'ws-123', 'main').toString()        // 'ff://ws-123@main/foo'

---

withContext()

withContext(workspace, branch): VfsUri

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:248

Create a new URI with different context.

Parameters

workspace

string

New workspace ID

branch

string

New branch name

Returns

VfsUri

New VfsUri with updated context

---

withoutContext()

withoutContext(): VfsUri

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:257

Remove context from this URI.

Returns

VfsUri

New VfsUri without workspace/branch context

---

withPath()

withPath(path): VfsUri

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:216

Create a new URI with a different path.

Parameters

path

New path

string | VfsPath

Returns

VfsUri

New VfsUri with the path, keeping context

---

create()

static create(path, workspace?, branch?): VfsUri

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:122

Create a VfsUri with workspace context.

Parameters

path

VfsPath instance or path string

string | VfsPath

workspace?

string

Workspace ID

branch?

string

Branch name

Returns

VfsUri

A new VfsUri instance with context

---

fromPath()

static fromPath(path): VfsUri

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:107

Create a VfsUri from a path.

Parameters

path

VfsPath instance or path string

string | VfsPath

Returns

VfsUri

A new VfsUri instance

---

parse()

static parse(uri): VfsUri

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:75

Parse a VFS URI string.

Accepts:

• ff:///path - Standard URI with absolute path
• ff://path - URI without leading slash (normalized)
• ff://workspace@branch/path - URI with context (future support)

Parameters

uri

string

The URI string to parse

Returns

VfsUri

A new VfsUri instance

Throws

Error if the URI is invalid

---

root()

static root(): VfsUri

Defined in: packages/fireflow-vfs/src/path/vfs-uri.ts:130

Create a URI for the root path.

Returns

VfsUri