Class FileSystemFileHandleStream

A read/write IOStream backed by a FileSystemFileHandle from the browser's File System Access API.

Read-write mode (default): opens a FileSystemSyncAccessHandle and uses its read/write methods with explicit byte offsets (at option) so that the internal cursor stays in sync without extra round-trips.

Read-only mode: retrieves the underlying File blob from the handle and performs lazy slice-based reads — identical to BlobStream but named after the originating FileSystemFileHandle.

The constructor is private; always use the async factory:

const stream = await FileSystemFileHandleStream.open(fileHandle);

Example

// In a dedicated web worker:
const [fileHandle] = await window.showOpenFilePicker();
const stream = await FileSystemFileHandleStream.open(fileHandle);
const tag = await FileRef.open(stream);

Hierarchy (View Summary)

IOStream
- FileSystemFileHandleStream

Index

Methods

clear close insert isOpen length name readBlock readOnly removeBlock seek tell truncate writeBlock open

Methods

clear

clear(): Promise<void>
Resets the stream position to the beginning.

Returns Promise<void>
Overrides IOStream.clear
- Defined in toolkit/fileSystemFileHandleStream.ts:325

close

close(): Promise<void>
Flushes pending writes and closes the underlying sync access handle. This is a no-op in read-only mode (the blob requires no cleanup).

After calling close(), isOpen returns false and further I/O will produce undefined behaviour.

Returns Promise<void>
- Defined in toolkit/fileSystemFileHandleStream.ts:366

insert

insert(data: ByteVector, start: number, replace?: number): Promise<void>
Inserts data at byte offset start, optionally replacing replace bytes of existing content.

Because FileSystemSyncAccessHandle does not support in-place insertion, this method reads the tail of the file, writes the new data, then writes the tail back.
Parameters
- data: ByteVector
  The bytes to insert.
- start: number
  Byte offset at which to begin the insertion.
- replace: number = 0
  Number of existing bytes to overwrite. Defaults to 0.
Returns Promise<void>
Throws
If the stream is read-only.
Overrides IOStream.insert
- Defined in toolkit/fileSystemFileHandleStream.ts:219

isOpen

isOpen(): boolean
Returns true if the stream has not yet been closed.

Returns boolean
Overrides IOStream.isOpen
- Defined in toolkit/fileSystemFileHandleStream.ts:146

length

length(): Promise<number>
Returns the total length of the file in bytes.

Returns Promise<number>
Overrides IOStream.length
- Defined in toolkit/fileSystemFileHandleStream.ts:335

name

name(): string
Returns the name of the underlying file.

Returns string
Overrides IOStream.name
- Defined in toolkit/fileSystemFileHandleStream.ts:136

readBlock

readBlock(length: number): Promise<ByteVector>
Reads up to length bytes from the current position and advances the position by the number of bytes actually read.
Parameters
- length: number
  Maximum number of bytes to read.
Returns Promise<ByteVector>
Resolves with a ByteVector containing the bytes read.
Overrides IOStream.readBlock
- Defined in toolkit/fileSystemFileHandleStream.ts:157

readOnly

readOnly(): boolean
Returns true if this stream was opened in read-only mode.

Returns boolean
Overrides IOStream.readOnly
- Defined in toolkit/fileSystemFileHandleStream.ts:141

removeBlock

removeBlock(start: number, length: number): Promise<void>
Removes length bytes beginning at byte offset start, shifting all subsequent bytes towards the beginning of the file.
Parameters
- start: number
  Byte offset of the first byte to remove.
- length: number
  Number of bytes to remove.
Returns Promise<void>
Throws
If the stream is read-only.
Overrides IOStream.removeBlock
- Defined in toolkit/fileSystemFileHandleStream.ts:268

seek

seek(offset: number, position?: Position): Promise<void>
Moves the read/write position within the stream.
Parameters
- offset: number
  Number of bytes to move relative to position.
- position: Position = Position.Beginning
  Reference point for the seek. Defaults to Position.Beginning.
Returns Promise<void>
Overrides IOStream.seek
- Defined in toolkit/fileSystemFileHandleStream.ts:309

tell

tell(): Promise<number>
Returns the current read/write position in bytes.

Returns Promise<number>
Overrides IOStream.tell
- Defined in toolkit/fileSystemFileHandleStream.ts:330

truncate

truncate(length: number): Promise<void>
Truncates or zero-extends the file to exactly length bytes. If the current position exceeds the new length, it is clamped.
Parameters
- length: number
  The desired file length in bytes.
Returns Promise<void>
Throws
If the stream is read-only.
Overrides IOStream.truncate
- Defined in toolkit/fileSystemFileHandleStream.ts:349

writeBlock

writeBlock(data: ByteVector): Promise<void>
Writes data at the current position, extending the file if necessary, and advances the position by data.length.
Parameters
- data: ByteVector
  The bytes to write.
Returns Promise<void>
Throws
If the stream is read-only.
Overrides IOStream.writeBlock
- Defined in toolkit/fileSystemFileHandleStream.ts:195

`Static`open

open(
fileHandle: FileSystemFileHandle,
readOnly?: boolean,
): Promise<FileSystemFileHandleStream>
Opens a FileSystemFileHandle and wraps it in a stream.
Parameters
- fileHandle: FileSystemFileHandle
  The handle to open. Must be obtained via the File System Access API (e.g. window.showOpenFilePicker()).
- readOnly: boolean = false
  When true, the stream opens the handle's File blob for read-only slice-based access instead of creating a sync handle. Defaults to false.
Returns Promise<FileSystemFileHandleStream>
A fully initialised FileSystemFileHandleStream.
- Defined in toolkit/fileSystemFileHandleStream.ts:121

Class FileSystemFileHandleStream

Example

Hierarchy (View Summary)

Index

Methods

Methods

clear

Returns Promise<void>

close

Returns Promise<void>

insert

Parameters

Returns Promise<void>

Throws

isOpen

Returns boolean

length

Returns Promise<number>

name

Returns string

readBlock

Parameters

Returns Promise<ByteVector>

readOnly

Returns boolean

removeBlock

Parameters

Returns Promise<void>

Throws

seek

Parameters

Returns Promise<void>

tell

Returns Promise<number>

truncate

Parameters

Returns Promise<void>

Throws

writeBlock

Parameters

Returns Promise<void>

Throws

Staticopen

Parameters

Returns Promise<FileSystemFileHandleStream>

Settings

On This Page

`Static`open