# Read JSON

> Read a file as [JSON][json].

<section class="usage">

## Usage

```javascript
var readJSON = require( '@stdlib/fs/read-json' );
```

<a name="read-json"></a>

#### readJSON( file, \[options,] clbk )

Asynchronously reads a file as [JSON][json].

```javascript
var join = require( 'path' ).join;

readJSON( join( __dirname, 'package.json' ), onJSON );

function onJSON( error, data ) {
    if ( error ) {
        throw error;
    }
    console.dir( data );
}
```

The function accepts the following `options`:

-   **encoding**: file encoding.
-   **flag**: file status flag.
-   **reviver**: [JSON][json] transformation `function`.

The `options` parameter may also be a `string` specifying the file `encoding`.

```javascript
var join = require( 'path' ).join;

readJSON( join( __dirname, 'package.json' ), 'utf8', onJSON );

function onJSON( error, data ) {
    if ( error ) {
        throw error;
    }
    console.dir( data );
}
```

#### readJSON.sync( file\[, options] )

Synchronously reads a file as [JSON][json].

```javascript
var join = require( 'path' ).join;
var instanceOf = require( '@stdlib/assert/instance-of' );

var out = readJSON.sync( join( __dirname, 'package.json' ) );
if ( instanceOf( out, Error ) ) {
    throw out;
}
console.dir( out );
```

The function accepts the same `options` as [`readJSON()`](#read-json) above.

</section>

<!-- /.usage -->

<section class="notes">

## Notes

-   If the `encoding` option is set to `utf8` and the file has a UTF-8 [byte order mark][bom] (BOM), the byte order mark is **removed** before attempting to parse as [JSON][json].

</section>

<!-- /.notes -->

<section class="examples">

## Examples

<!-- eslint no-undef: "error" -->

```javascript
var join = require( 'path' ).join;
var readJSON = require( '@stdlib/fs/read-json' );

var file = join( __dirname, 'package.json' );

// Synchronously read file contents...
var data = readJSON.sync( file, 'utf8' );
// returns <Object>

data = readJSON.sync( 'beepboop', {
    'encoding': 'utf8'
});
// returns <Error>

// Asynchronously read file contents...
readJSON( file, onJSON );
readJSON( 'beepboop', onJSON );

function onJSON( error, data ) {
    if ( error ) {
        if ( error.code === 'ENOENT' ) {
            console.error( 'JSON file does not exist.' );
        } else {
            throw error;
        }
    } else {
        console.log( 'Package description: %s', data.description );
    }
}
```

</section>

<!-- /.examples -->

<section class="links">

[json]: http://www.json.org/

[bom]: https://en.wikipedia.org/wiki/Byte_order_mark

</section>

<!-- /.links -->
