Skip to main content

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

Constructors

constructor

new FileURI(uri)

Parameters

NameType
uriURI

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

NameTypeDescription
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

NameTypeDescription
stringsTemplateStringsArrayThe template string array.
...valuesunknown[]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

NameType
reqAuthSchemeRequest
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

NameType
Textends SelectorBase

Parameters

NameType
selsundefined | T[]
challenge?WWWAuthenticate

Returns

null | T

Inherited from

URI._getBestSelector

Defined in

uri/src/uri.ts:581


_guessContentType

Protected _guessContentType(knownContentType?): undefined | ContentType

Parameters

NameType
knownContentType?string | ContentType

Returns

undefined | ContentType

Inherited from

URI._guessContentType

Defined in

uri/src/uri.ts:573


_makeIOError

Protected _makeIOError(err): IOError

Parameters

NameType
errunknown

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

NameType
Textends AuthSelector | HeadersSelector | ParamsSelector | SessionSelector

Parameters

NameTypeDescription
selectorTThe 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

NameTypeDescription
Textends objectObject.
DunknownThe type of data to append.

Parameters

NameTypeDescription
dataDThe data to append.
sendCT?string | ContentTypeOverride the default data serializer.
recvCT?undefinedMust 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

NameType
Textends 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

NameType
Textends 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

NameTypeDescription
Textends objectThe actual type returned.

Parameters

NameTypeDescription
recvCT?string | ContentTypeOverride 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

NameTypeDescription
Textends objectThe actual type returned.
DunknownThe type of patch data to apply.

Parameters

NameTypeDescription
dataDThe patch data to apply.
sendCT?string | ContentTypeOverride the default data serializer.
recvCT?string | ContentTypeOverride 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

NameTypeDescription
Textends objectThe actual type returned.

Parameters

NameTypeDescription
...argsunknown[]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

NameTypeDescription
Textends objectObject.

Parameters

NameTypeDescription
recvCT?undefinedMust 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

NameTypeDescription
Textends objectObject.
DunknownThe type of data to store.

Parameters

NameTypeDescription
dataDThe data to store.
sendCT?string | ContentTypeOverride the default data serializer.
recvCT?undefinedMust 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

NameTypeDescription
stringsTemplateStringsArrayThe template string array.
...valuesunknown[]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

NameTypeDescription
pathstringThe a Windows or POSIX style file path, depending on current operating system.
base?FileURIAn 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

NameTypeDescription
protocolstringThe URL protocol to register. Must include the trailing colon.
uritypeof URIThe URI subclass.

Returns

typeof URI

The URI baseclass (for chaining).

Inherited from

URI.register

Defined in

uri/src/uri.ts:169