PersistentAI

Appearance

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

Class: VfsPath ​

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

Immutable, validated VFS path (without ff:// scheme).

VfsPath represents an absolute path within the VFS. It is:

  • Immutable: All operations return new instances
  • Validated: Invalid paths are rejected at construction
  • Normalized: No double slashes, consistent trailing slash handling

Example ​

typescript
// Parse from string
const path = VfsPath.parse('/foo/bar.txt')
path.name        // 'bar.txt'
path.extension   // '.txt'
path.stem        // 'bar'
path.parent()    // VfsPath('/foo')

// Operations return new instances
const newPath = path.parent().join('baz.json')
newPath.toString() // '/foo/baz.json'

// Directory paths
const dir = VfsPath.parse('/foo/bar/').asDirectory()
dir.isDirectory  // true

Accessors ​

depth ​

Get Signature ​

get depth(): number

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

Get the depth (number of segments).

Example ​
ts
VfsPath.parse('/').depth           // 0
VfsPath.parse('/foo').depth        // 1
VfsPath.parse('/foo/bar').depth    // 2
Returns ​

number

extension ​

Get Signature ​

get extension(): string

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

Get the file extension (with dot) or empty string.

Example ​
ts
VfsPath.parse('/foo/bar.txt').extension   // '.txt'
VfsPath.parse('/foo/bar.tar.gz').extension // '.gz'
VfsPath.parse('/foo/bar').extension       // ''
VfsPath.parse('/foo/.gitignore').extension // '' (dotfiles have no extension)
Returns ​

string

isDirectory ​

Get Signature ​

get isDirectory(): boolean

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

Whether this path represents a directory.

Note: This is a hint based on how the path was created. The actual file system may have different semantics.

Returns ​

boolean

isRoot ​

Get Signature ​

get isRoot(): boolean

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

Whether this is the root path.

Returns ​

boolean

name ​

Get Signature ​

get name(): string

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

Get the filename (last segment) or empty string for root.

Example ​
ts
VfsPath.parse('/foo/bar.txt').name  // 'bar.txt'
VfsPath.parse('/foo/bar/').name     // 'bar'
VfsPath.parse('/').name             // ''
Returns ​

string

segments ​

Get Signature ​

get segments(): readonly string[]

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

Get the path segments (readonly).

Example ​
ts
VfsPath.parse('/foo/bar/baz.txt').segments // ['foo', 'bar', 'baz.txt']
Returns ​

readonly string[]

stem ​

Get Signature ​

get stem(): string

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

Get the filename without extension.

Example ​
ts
VfsPath.parse('/foo/bar.txt').stem     // 'bar'
VfsPath.parse('/foo/bar.tar.gz').stem  // 'bar.tar'
VfsPath.parse('/foo/.gitignore').stem  // '.gitignore'
Returns ​

string

Methods ​

asDirectory() ​

asDirectory(): VfsPath

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

Mark this path as a directory.

Returns ​

VfsPath

New VfsPath marked as directory

asFile() ​

asFile(): VfsPath

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

Mark this path as a file (not directory).

Returns ​

VfsPath

New VfsPath marked as file

equals() ​

equals(other): boolean

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

Check equality with another VfsPath.

Parameters ​

other ​

VfsPath

Path to compare

Returns ​

boolean

True if paths are equal

isChildOf() ​

isChildOf(other): boolean

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

Check if this path is a child of another path.

Unlike startsWith, this returns false for the same path.

Parameters ​

other ​

VfsPath

Potential parent path

Returns ​

boolean

True if this is a child of other

join() ​

join(child): VfsPath

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

Join this path with a child path or segment.

Parameters ​

child ​

Child path string or VfsPath

string | VfsPath

Returns ​

VfsPath

New path with child appended

Example ​

ts
VfsPath.parse('/foo').join('bar/baz.txt').toString() // '/foo/bar/baz.txt'
VfsPath.parse('/foo').join(VfsPath.parse('/bar')).toString() // '/foo/bar'

parent() ​

parent(): VfsPath

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

Get the parent directory path.

Returns ​

VfsPath

Parent directory (root returns itself)

Example ​

ts
VfsPath.parse('/foo/bar.txt').parent().toString() // '/foo'
VfsPath.parse('/foo').parent().toString()         // '/'
VfsPath.parse('/').parent().toString()            // '/'

relativeTo() ​

relativeTo(base): VfsPath

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

Get the relative path from a base path.

Parameters ​

base ​

VfsPath

Base path to calculate relative from

Returns ​

VfsPath

Relative path

Throws ​

Error if this path doesn't start with base

Example ​

ts
VfsPath.parse('/foo/bar/baz').relativeTo(VfsPath.parse('/foo')).toString() // 'bar/baz'

startsWith() ​

startsWith(other): boolean

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

Check if this path starts with another path.

Parameters ​

other ​

VfsPath

Path to check against

Returns ​

boolean

True if this path starts with other

Example ​

ts
VfsPath.parse('/foo/bar').startsWith(VfsPath.parse('/foo'))  // true
VfsPath.parse('/foo/bar').startsWith(VfsPath.parse('/baz'))  // false

toJSON() ​

toJSON(): object

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

Create a JSON-serializable representation.

Returns ​

object

isDirectory ​

isDirectory: boolean

path ​

path: string

toLakeFSPath() ​

toLakeFSPath(): string

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

Convert to a lakeFS-compatible path (NO leading slash).

lakeFS treats '/foo/bar' and 'foo/bar' as DIFFERENT paths. This method returns the path WITHOUT the leading slash, which is the correct format for lakeFS API operations.

Returns ​

string

Example ​

ts
VfsPath.parse('/foo/bar').toLakeFSPath()       // 'foo/bar'
VfsPath.parse('ff:///foo/bar').toLakeFSPath()  // 'foo/bar'
VfsPath.parse('/').toLakeFSPath()              // ''

toPathString() ​

toPathString(): string

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

Convert to a path string with trailing slash for directories.

Use this when the trailing slash matters (e.g., for lakeFS).

Returns ​

string

Example ​

ts
VfsPath.parse('/foo/bar').asDirectory().toPathString()  // '/foo/bar/'
VfsPath.parse('/foo/bar.txt').toPathString()            // '/foo/bar.txt'

toString() ​

toString(): string

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

Convert to a normalized path string.

Root returns '/'. Other paths return '/segment1/segment2/...' without trailing slash.

Returns ​

string

Example ​

ts
VfsPath.parse('/foo/bar').toString()  // '/foo/bar'
VfsPath.parse('/foo/bar/').toString() // '/foo/bar'
VfsPath.parse('/').toString()         // '/'

toUri() ​

toUri(): string

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

Convert to a VFS URI string.

Returns ​

string

Example ​

ts
VfsPath.parse('/foo/bar').toUri() // 'ff:///foo/bar'

withExtension() ​

withExtension(ext): VfsPath

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

Create a new path with a different extension.

Parameters ​

ext ​

string

New extension (with or without dot)

Returns ​

VfsPath

New path with changed extension

Example ​

ts
VfsPath.parse('/foo/bar.txt').withExtension('.md').toString()  // '/foo/bar.md'
VfsPath.parse('/foo/bar.txt').withExtension('md').toString()   // '/foo/bar.md'
VfsPath.parse('/foo/bar.txt').withExtension('').toString()     // '/foo/bar'

withName() ​

withName(name): VfsPath

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

Create a new path with a different filename.

Parameters ​

name ​

string

New filename

Returns ​

VfsPath

New path with changed filename

Example ​

ts
VfsPath.parse('/foo/bar.txt').withName('baz.json').toString() // '/foo/baz.json'

fromSegments() ​

static fromSegments(segments, isDirectory?): VfsPath

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

Create a VfsPath from an array of segments.

Parameters ​

segments ​

string[]

Path segments (without slashes)

isDirectory? ​

boolean = false

Whether this represents a directory

Returns ​

VfsPath

A new VfsPath instance

parse() ​

static parse(path): VfsPath

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

Parse a path string into a VfsPath.

Accepts:

  • Absolute paths: '/foo/bar.txt'
  • Root: '/', ''
  • With or without trailing slash: '/foo/' or '/foo'
  • VFS URIs are stripped: 'ff:///foo' → '/foo'

Parameters ​

path ​

string

The path string to parse

Returns ​

VfsPath

A new VfsPath instance

Throws ​

Error if the path is invalid

root() ​

static root(): VfsPath

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

Create the root path ('/').

Returns ​

VfsPath

Licensed under BUSL-1.1

Copyright © 2026 PersistentAI