FM / get-uri

/usr/local/lib/node_modules/pm2/node_modules/get-uri/

/usr/local/lib/node_modules/pm2/node_modules/get-uri

Name	Size	Mode	Actions
dist/	-	0755	rm
LICENSE	1101	0644	edit dl rm
package.json	1282	0644	edit dl rm
README.md	3882	0644	edit dl rm

Edit: /usr/local/lib/node_modules/pm2/node_modules/get-uri/README.md (3882B)

get-uri
=======
### Returns a `stream.Readable` from a URI string

This high-level module accepts a URI string and returns a `Readable` stream
instance. There is built-in support for a variety of "protocols", and it's
easily extensible with more:

Example
-------

To simply get a `stream.Readable` instance from a `file:` URI, try something like:

```ts
import { getUri } from 'get-uri';

// `file:` maps to a `fs.ReadStream` instance…
const stream = await getUri('file:///Users/nrajlich/wat.json');
stream.pipe(process.stdout);
```

Missing Endpoints
-----------------

When you pass in a URI in which the resource referenced does not exist on the
destination server, then a `NotFoundError` will be thrown. The `code` of the
error instance is set to `"ENOTFOUND"`, so you can check for that value
to detect when a bad filename is requested:

```ts
try {
  await getUri('http://example.com/resource.json');
} catch (err) {
  if (err.code === 'ENOTFOUND') {
    // bad file path requested
  } else {
    // something else bad happened...
    throw err;
  }
}
```

Cacheability
------------

When calling `getUri()` with the same URI multiple times, the `get-uri` module
supports sending an indicator that the remote resource has not been modified
since the last time it has been retrieved from that node process.

To do this, define a `cache` property on the "options object" argument
with the value set to the `stream.Readable` instance that was previously
returned. If the remote resource has not been changed since the last call for
that same URI, then a `NotModifiedError` instance will be thrown with its
`code` property set to `"ENOTMODIFIED"`.

When the `"ENOTMODIFIED"` error occurs, then you can safely re-use the
results from the previous `getUri()` call for that same URI:

``` js
// First time fetches for real
const stream = await getUri('http://example.com/resource.json');

try {
  // … some time later, if you need to get this same URI again, pass in the
  // previous `stream.Readable` instance as `cache` option to potentially
  // have an "ENOTMODIFIED" error thrown:
  await getUri('http://example.com/resource.json', { cache: stream });
} catch (err) {
  if (err.code === 'ENOTMODIFIED') {
    // source file has not been modified since last time it was requested,
    // so you are expected to re-use results from a previous call to `getUri()`
  } else {
    // something else bad happened...
    throw err;
  }
}
```

API
---

### getUri(uri: string | URL, options?: Object]): Promise<Readable>

A `uri` is required. An optional `options` object may be passed in:

- `cache` - A `stream.Readable` instance from a previous call to `getUri()` with the same URI. If this option is passed in, and the destination endpoint has not been modified, then an `ENOTMODIFIED` error is thrown

Any other options passed in to the `options` object will be passed through
to the low-level connection creation functions (`http.get()`, `ftp.connect()`,
etc).

Returns a `stream.Readable` instance to read the resource at the given `uri`.

[data]: http://tools.ietf.org/html/rfc2397
[file]: http://tools.ietf.org/html/draft-hoffman-file-uri-03
[ftp]: http://www.w3.org/Protocols/rfc959/
[http]: http://www.w3.org/Protocols/rfc2616/rfc2616.html
[https]: http://wikipedia.org/wiki/HTTP_Secure

cmd: