Class: FileURI

@divine/uri.FileURI

The file: protocol handler is used to access files and directories on the local computer.

File URIs may not have a hostname component (except if it is localhost), and no search or hash component. Futhermore, the path may not contain encoded slashes (that is, the sequence %2F is forbidden).

Hierarchy

• URI

  ↳ FileURI

Constructors

constructor

• new FileURI(uri)

Parameters

Name	Type
uri	URI

Overrides

URI.constructor

Defined in

uri/src/protocols/file.ts:59

Properties

href

• Readonly href: string

This URI's string representation. Unlike in URL, this property may not be changed/updated.

Inherited from

URI.href

Defined in

uri/src/uri.ts:211

---

origin

• Readonly origin: string

This URI's origin. Unlike in URL, this property may not be changed/updated.

Inherited from

URI.origin

Defined in

uri/src/uri.ts:214

---

protocol

• Readonly protocol: string

This URI's protocol. Unlike in URL, this property may not be changed/updated.

Inherited from

URI.protocol

Defined in

uri/src/uri.ts:217

---

selectors

• selectors: Object

All selectors that may apply to this URI. Use addSelector to modify this property.

Type declaration

Name	Type	Description
auth?	AuthSelector[]	Authentication/Credentials selectors. See AuthSelector.
headers?	HeadersSelector[]	Headers selectors. See HeadersSelector.
params?	ParamsSelector[]	Parameter selectos. See ParamsSelector.
session?	SessionSelector[]	Session selectors. Only used internally.

Inherited from

URI.selectors

Defined in

uri/src/uri.ts:196

---

FIELDS

▪ Static Readonly FIELDS: symbol = FIELDS

An alias for FIELDS.

Inherited from

URI.FIELDS

Defined in

uri/src/uri.ts:148

---

FINALIZE

▪ Static Readonly FINALIZE: symbol = FINALIZE

An alias for FIELDS.

Inherited from

URI.FINALIZE

Defined in

uri/src/uri.ts:151

---

HEADERS

▪ Static Readonly HEADERS: symbol = HEADERS

An alias for HEADERS.

Inherited from

URI.HEADERS

Defined in

uri/src/uri.ts:154

---

NULL

▪ Static Readonly NULL: symbol = NULL

An alias for NULL.

Inherited from

URI.NULL

Defined in

uri/src/uri.ts:145

---

STATUS

▪ Static Readonly STATUS: symbol = STATUS

An alias for STATUS.

Inherited from

URI.STATUS

Defined in

uri/src/uri.ts:157

---

STATUS_TEXT

▪ Static Readonly STATUS_TEXT: symbol = STATUS_TEXT

An alias for STATUS_TEXT.

Inherited from

URI.STATUS_TEXT

Defined in

uri/src/uri.ts:160

---

VOID

▪ Static Readonly VOID: symbol = VOID

An alias for VOID.

Inherited from

URI.VOID

Defined in

uri/src/uri.ts:142

Methods

$

▸ $(strings, ...values): URI

Constructs a new URI, relative to this URI, from a template string, percent-encoding all arguments.

Example:

const base = new URI('http://api.example.com/v1/');
const info = await base.$`items/${item}/info`.load();

Parameters

Name	Type	Description
strings	TemplateStringsArray	The template string array.
...values	unknown[]	The values to be encoded.

Returns

URI

A new URI subclass instance.

Inherited from

URI.$

Defined in

uri/src/uri.ts:289

---

[asyncIterator]

▸ [asyncIterator](): AsyncIterator<Buffer, any, undefined> & Metadata

All URIs are AsyncIterable<Buffer>. This method implements that interface by calling load(stream).

Returns

AsyncIterator<Buffer, any, undefined> & Metadata

An AsyncIterator<Buffer> stream.

Inherited from

URI.[asyncIterator]

Defined in

uri/src/uri.ts:535

---

_getAuthorization

▸ Protected _getAuthorization(req, payload?, challenges?): Promise<undefined | Authorization>

Parameters

Name	Type
req	AuthSchemeRequest
payload?	Buffer | AsyncIterable<Buffer>
challenges?	WWWAuthenticate[]

Returns

Promise<undefined | Authorization>

Inherited from

URI._getAuthorization

Defined in

uri/src/uri.ts:539

---

_getBestSelector

▸ Protected _getBestSelector<T>(sels, challenge?): null | T

Type parameters

Name	Type
T	extends SelectorBase

Parameters

Name	Type
sels	undefined | T[]
challenge?	WWWAuthenticate

Returns

null | T

Inherited from

URI._getBestSelector

Defined in

uri/src/uri.ts:581

---

_guessContentType

▸ Protected _guessContentType(knownContentType?): undefined | ContentType

Parameters

Name	Type
knownContentType?	string | ContentType

Returns

undefined | ContentType

Inherited from

URI._guessContentType

Defined in

uri/src/uri.ts:573

---

_makeIOError

▸ Protected _makeIOError(err): IOError

Parameters

Name	Type
err	unknown

Returns

IOError

Inherited from

URI._makeIOError

Defined in

uri/src/uri.ts:577

---

addSelector

▸ addSelector<T>(selector): FileURI

Adds a new selector to this URI.

Selectors is a way to specify in what situations some kind of parameters or configuration is valid. When some kind of configuration is required (such as authentication of connection parameters), all registered selectors are evaluated and based on the matching score, the best selector is chosen. The more specific a selector is, the higher the score it will receive if it matches.

Based on this, it's possible to limit the scope of credentials or to configure certain HTTP headers to be sent to a specific set of servers.

It's also perfectly valid not to specify a selector for some kind of parameters. As long as there is only one kind of this configuration, it will apply unconditionally.

Throws

TypeError If the selector to add is invalid.

Type parameters

Name	Type
T	extends AuthSelector | HeadersSelector | ParamsSelector | SessionSelector

Parameters

Name	Type	Description
selector	T	The selector to add.

Returns

FileURI

This URI.

Inherited from

URI.addSelector

Defined in

uri/src/uri.ts:311

---

append

▸ append<T, D>(data, sendCT?, recvCT?): Promise<T & Metadata>

Serializes and appends data to the file this URI references, creating the file if it does not exist.

Throws

IOError On I/O errors or if this resource is not a file.

Throws

ParserError If the media type is unsupported or ig the parser fails to serialize the data.

Type parameters

Name	Type	Description
T	extends object	Object.
D	unknown	The type of data to append.

Parameters

Name	Type	Description
data	D	The data to append.
sendCT?	string | ContentType	Override the default data serializer.
recvCT?	undefined	Must not be used.

Returns

Promise<T & Metadata>

Object(VOID).

Overrides

URI.append

Defined in

uri/src/protocols/file.ts:184

---

close

▸ close(): Promise<void>

Closes this URI and frees any temporary resources in use.

URIs are usually stateless, but some protocols may use a connection pool, and this method can be used to shut down the pool and all remaining connections that may otherwise prevent the process from exiting.

Returns

Promise<void>

Inherited from

URI.close

Defined in

uri/src/uri.ts:525

---

info

▸ info<T>(): Promise<T & Metadata>

Calls fs.stat() on the file resourcce and constructs a DirectoryEntry.

Directories will have its type set to ContentType.dir and the media type of files will be guessed based on the file name extension.

Throws

IOError On I/O errors or if this file/directory does not exist.

Type parameters

Name	Type
T	extends DirectoryEntry

Returns

Promise<T & Metadata>

Information about this file resource.

Overrides

URI.info

Defined in

uri/src/protocols/file.ts:87

---

list

▸ list<T>(): Promise<T[] & Metadata>

Calls fs.readdir() to list all resources inside this directory.

Throws

IOError On I/O errors or if this resource is not a directory or does not exist.

Type parameters

Name	Type
T	extends DirectoryEntry

Returns

Promise<T[] & Metadata>

A list with information about the files and subdirectories.

Overrides

URI.list

Defined in

uri/src/protocols/file.ts:113

---

load

▸ load<T>(recvCT?): Promise<T & Metadata>

Loads and parses this file resource.

Throws

IOError On I/O errors or if this resource is not a file or does not exist.

Throws

ParserError If the media type is unsupported or if the parser fails to parse the resource.

Type parameters

Name	Type	Description
T	extends object	The actual type returned.

Parameters

Name	Type	Description
recvCT?	string | ContentType	Override the default response parser.

Returns

Promise<T & Metadata>

The file resource parsed as recvCT into an object, including Metadata.

Overrides

URI.load

Defined in

uri/src/protocols/file.ts:134

---

modify

▸ modify<T, D>(data, sendCT?, recvCT?): Promise<T & Metadata>

Modifies/patches data the resource this URI references, if the subclass supports it.

The actual operation depends on what kind of URI this is. See modify or modify for two common examples.

See parse for details about the returned object (never a primitive). You may always set recvCT to ContentType.bytes to receive a Node.js Buffer and ContentType.stream for an AsyncIterable<Buffer> stream, if you prefer raw data.

Throws

IOError On I/O errors or if the subclass does not support this method.

Throws

ParserError If the media type is unsupported or the parser fails to parse the response.

Type parameters

Name	Type	Description
T	extends object	The actual type returned.
D	unknown	The type of patch data to apply.

Parameters

Name	Type	Description
data	D	The patch data to apply.
sendCT?	string | ContentType	Override the default data serializer.
recvCT?	string | ContentType	Override the default response parser.

Returns

Promise<T & Metadata>

If the operation produced a result, it will be parsed as recvCT into an object, including MetaData.

Inherited from

URI.modify

Defined in

uri/src/uri.ts:460

---

query

▸ query<T>(...args): Promise<T & Metadata>

A generic method that sends/applies some kind of query to the resource and returns a response.

The actual operation depends on what kind of URI this is. See query or query for two common examples.

Throws

IOError On I/O errors or if the subclass does not support this method.

Throws

ParserError If the media type is unsupported or the parser fails to parse the response.

Type parameters

Name	Type	Description
T	extends object	The actual type returned.

Parameters

Name	Type	Description
...args	unknown[]	Depends on the subclass.

Returns

Promise<T & Metadata>

If the operation produced a result, it will returned together with MetaData.

Inherited from

URI.query

Defined in

uri/src/uri.ts:499

---

remove

▸ remove<T>(recvCT?): Promise<T & Metadata>

Removes the file or (the empty) directory this URI references.

Throws

IOError On I/O errors.

Type parameters

Name	Type	Description
T	extends object	Object.

Parameters

Name	Type	Description
recvCT?	undefined	Must not be used.

Returns

Promise<T & Metadata>

Object(true) if the file was removed, or Object(true) if the resource did not exist in the first place.

Overrides

URI.remove

Defined in

uri/src/protocols/file.ts:207

---

save

▸ save<T, D>(data, sendCT?, recvCT?): Promise<T & Metadata>

Serializes and stores data to the file this URI references, overwriting the file if it exists.

Throws

IOError On I/O errors or if this resource is not a file.

Throws

ParserError If the media type is unsupported or if the parser fails to serialize the data.

Type parameters

Name	Type	Description
T	extends object	Object.
D	unknown	The type of data to store.

Parameters

Name	Type	Description
data	D	The data to store.
sendCT?	string | ContentType	Override the default data serializer.
recvCT?	undefined	Must not be used.

Returns

Promise<T & Metadata>

Object(VOID).

Overrides

URI.save

Defined in

uri/src/protocols/file.ts:158

---

watch

▸ watch(): AsyncIterable<FileWatchEvent & Metadata>

Watches the file or directory (recusively) this URI references for changes.

Each modification to the file or the filesystem below the directory will emit a FileWatchEvent. Use for await (...) to read the events, propagate errors and to ensure the stream is closed correctly when you are done.

Example usage:

for await (const event of FileURI.create('./src').watch()) {
    console.log(event.type, await event.uri.info());
}

Throws

IOError On I/O errors.

Returns

AsyncIterable<FileWatchEvent & Metadata>

A stream of change events.

Overrides

URI.watch

Defined in

uri/src/protocols/file.ts:249

---

$

▸ Static $(strings, ...values): URI

Creates a new URI from a template string, percent-encoding all arguments.

Example:

const href = URI.$`http://${host}/blobs/${blob}?as=${ct}

Parameters

Name	Type	Description
strings	TemplateStringsArray	The template string array.
...values	unknown[]	The values to be encoded.

Returns

URI

A new URI subclass instance.

Inherited from

URI.$

Defined in

uri/src/uri.ts:187

---

create

▸ Static create(path, base?): FileURI

Creates a new FileURI by encoding the file path using encodeFilePath.

Throws

TypeError If the resulting URI is not actually a FileURI.

Parameters

Name	Type	Description
path	string	The a Windows or POSIX style file path, depending on current operating system.
base?	FileURI	An optional URI to use when resolving relative paths.

Returns

FileURI

A new FileURI instance.

Defined in

uri/src/protocols/file.ts:45

---

register

▸ Static register(protocol, uri): typeof URI

Registers a new URI protocol. All subclasses must register their URL protocol support with this method.

Parameters

Name	Type	Description
protocol	string	The URL protocol to register. Must include the trailing colon.
uri	typeof URI	The URI subclass.

Returns

typeof URI

The URI baseclass (for chaining).

Inherited from

URI.register

Defined in

uri/src/uri.ts:169