npm package: @ryniaubenpm/magnam-dolorum-tempora
Description: [![build status](https://img.shields.io/github/actions/workflow/status/bergos/@ryniaubenpm/magnam-dolorum-tempora/test.yaml?branch=master)](https://github.com/ryniaubenpm/magnam-dolorum-tempora/actions/workflows/test.yaml) [![npm version](https://img.shie
Author: ryniaube
Latest version: 1.0.0

# @ryniaubenpm/magnam-dolorum-tempora

[![build status](https://img.shields.io/github/actions/workflow/status/bergos/@ryniaubenpm/magnam-dolorum-tempora/test.yaml?branch=master)](https://github.com/ryniaubenpm/magnam-dolorum-tempora/actions/workflows/test.yaml)
[![npm version](https://img.shields.io/npm/v/@ryniaubenpm/magnam-dolorum-tempora.svg)](https://www.npmjs.com/package/@ryniaubenpm/magnam-dolorum-tempora)

`@ryniaubenpm/magnam-dolorum-tempora` is a [nodeify-fetch](https://www.npmjs.com/package/nodeify-fetch) compatible fetch for read and write access to the local file system using `file:` URLs and URIs (including
implicit ones using relative paths).

## Usage

### Read

Reading a file from the file system is as easy as fetching it on the Web.
Call `fetch` with the URL, and the content is provided as `Readable` stream in `res.body`.
The example below uses an absolute URL, but relative paths are also supported.
See the [Supported URLs and URIs](#supported-urls-and-uris) section for more details.

```js
import fetch from '@ryniaubenpm/magnam-dolorum-tempora'

const res = await fetch(new URL('example.js', import.meta.url))

res.body.pipe(process.stdout)
```

It's also possible to handle the content without streams.
The async `res.text()` method returns the whole content as a string.

```js
import fetch from '@ryniaubenpm/magnam-dolorum-tempora'

const res = await fetch(new URL('example.js', import.meta.url))

console.log(await res.text())
```

A similar method `res.json()` is available to parse JSON content and return the parsed result.

```js
import fetch from '@ryniaubenpm/magnam-dolorum-tempora'

const res = await fetch(new URL('example.js', import.meta.url))

console.log(await res.json())
```

### Write

Writing content to a file is done with the same function but with the `PUT` method.
The content must be provided as a `string` or a `Readable` stream object.

```js
import fetch from '@ryniaubenpm/magnam-dolorum-tempora'

await fetch('file:///tmp/example.log', {
  method: 'PUT',
  body: 'test'
})
```

```js
import fetch from '@ryniaubenpm/magnam-dolorum-tempora'
import { Readable } from 'readable-stream'

await fetch('file:///tmp/example.log', {
  method: 'PUT',
  body: Readable.from(['test'])
})
```

## Options

`@ryniaubenpm/magnam-dolorum-tempora` supports the following non-standard options:

- `baseURL`: A `string` or `URL` used to resolve relative paths and URIs.
- `contentType`: A `string` or `function` to determine the media type based on the file extension or a fixed value.
  It can be useful if file extensions or media types not covered by [mime-db](https://www.npmjs.com/package/mime-db) are required.

## Custom fetch with fixed baseURL or contentType lookup

Custom fetch instances can be useful if requests should be processed with relative paths to a directory that is not the current working directory.
The `contentType` argument can also be predefined for the instance.
The example below shows how to set the `baseURL` to a relative path of the current script and how to use a custom `contentType` function: 

```js
import { factory as fetchFactory } from '@ryniaubenpm/magnam-dolorum-tempora'

const baseURL = new URL('examples', import.meta.url)
const contentType = ext => ext === 'json' ? 'application/ld+json' : 'application/octet-stream'

const fetch = fetchFactory({ baseURL, contentType })

const res = await fetch('example.js')
const text = await res.text()
```

## Supported URLs and URIs

Different styles of URLs and URIs are supported.

### Absolute URLs

An absolute URL for a `file` schema must start with `file:///`.
No further resolve logic is used.

Example:

```
file:///home/user/tmp/content.txt
```

### URIs

URIs are supported for use cases where a `file` scheme is required to distinguish identifiers by scheme and if relative paths are required.
The [relative paths](#relative-paths) logic is used to resolve the full URL.

Example:

```
file:tmp/content.txt
```

### Relative paths

Relative paths are resolved with the given `baseURL` or, if not given, with the working directory.

Example:

```
tmp/content.txt
```