feat: add readPackage helper (#106)

As stated in the comment above the new function, this is a new isolated
function for reading and parsing a given package.json file.  This will
allow things like npm which already requires this module to tap into the
exact same code this module would use to parse a package.json file, but
not have to require the whole module if it is not going to need
normalization or saving.

README.md

@@ -50,6 +50,15 @@ await pkgJson.save()
 // }
 ```
 
+There is also a helper function exported for opening a package.json file
+with no extra normalization or saving functionality.
+
+```js
+const { readPackage } = require('@npmcli/package-json/lib/read-package')
+const rawData = await readPackage('./package.json')
+// rawData will now have the package.json contents with no changes or normalizations
+```
+
 ## API:
 
 ### `constructor()`

lib/index.js

@@ -1,11 +1,12 @@
-const { readFile, writeFile } = require('fs/promises')
-const { resolve } = require('path')
+const { readFile, writeFile } = require('node:fs/promises')
+const { resolve } = require('node:path')
+const parseJSON = require('json-parse-even-better-errors')
+
 const updateDeps = require('./update-dependencies.js')
 const updateScripts = require('./update-scripts.js')
 const updateWorkspaces = require('./update-workspaces.js')
 const normalize = require('./normalize.js')
-
-const parseJSON = require('json-parse-even-better-errors')
+const { read, parse } = require('./read-package.js')
 
 // a list of handy specialized helper functions that take
 // care of special cases that are handled by the npm cli
@@ -126,9 +127,8 @@ class PackageJson {
  this.#path = path
  let parseErr
  try {
- this.#readFileContent = await readFile(this.filename, 'utf8')
+ this.#readFileContent = await read(this.filename)
  } catch (err) {
- err.message = `Could not read package.json: ${err}`
  if (!parseIndex) {
  throw err
  }
@@ -158,12 +158,7 @@ class PackageJson {
 
  // Load data from a JSON string/buffer
  fromJSON (data) {
- try {
- this.#manifest = parseJSON(data)
- } catch (err) {
- err.message = `Invalid package.json: ${err}`
- throw err
- }
+ this.#manifest = parse(data)
  return this
  }
 

lib/normalize.js

@@ -1,7 +1,7 @@
 const valid = require('semver/functions/valid')
 const clean = require('semver/functions/clean')
-const fs = require('fs/promises')
-const path = require('path')
+const fs = require('node:fs/promises')
+const path = require('node:path')
 const { log } = require('proc-log')
 
 /**

lib/read-package.js

@@ -0,0 +1,39 @@
+// This is JUST the code needed to open a package.json file and parse it.
+// It's isolated out so that code needing to parse a package.json file can do so in the same way as this module does, without needing to require the whole module, or needing to require the underlying parsing library.
+
+const { readFile } = require('fs/promises')
+const parseJSON = require('json-parse-even-better-errors')
+
+async function read (filename) {
+ try {
+ const data = await readFile(filename, 'utf8')
+ return data
+ } catch (err) {
+ err.message = `Could not read package.json: ${err}`
+ throw err
+ }
+}
+
+function parse (data) {
+ try {
+ const content = parseJSON(data)
+ return content
+ } catch (err) {
+ err.message = `Invalid package.json: ${err}`
+ throw err
+ }
+}
+
+// This is what most external libs will use.
+// PackageJson will call read and parse separately
+async function readPackage (filename) {
+ const data = await read(filename)
+ const content = parse(data)
+ return content
+}
+
+module.exports = {
+ read,
+ parse,
+ readPackage,
+}

tap-snapshots/test/index.js.test.cjs

@@ -527,3 +527,10 @@ exports[`test/index.js TAP load update long package.json > should properly write
 }
 
 `
+
+exports[`test/index.js TAP read package > must match snapshot 1`] = `
+Object {
+ "name": "foo",
+ "version": "1.0.0",
+}
+`

test/index.js

@@ -1,5 +1,5 @@
-const fs = require('fs')
-const { resolve } = require('path')
+const fs = require('node:fs')
+const { join, resolve } = require('node:path')
 const t = require('tap')
 const PackageJson = require('../lib/index.js')
 
@@ -233,3 +233,15 @@ t.test('can set data', async t => {
  message: /No package\.json to save to/,
  })
 })
+
+t.test('read package', async t => {
+ const { readPackage } = require('../lib/read-package')
+ const path = t.testdir({
+ 'package.json': JSON.stringify({
+ name: 'foo',
+ version: '1.0.0',
+ }),
+ })
+ const data = await readPackage(join(path, 'package.json'))
+ t.matchSnapshot(data)
+})

test/normalize.js

@@ -1,5 +1,5 @@
 const t = require('tap')
-const { join } = require('path')
+const { join } = require('node:path')
 const pkg = require('../')
 const rpj = require('read-package-json-fast')
 

test/prepare.js

@@ -1,6 +1,6 @@
 const t = require('tap')
 const pkg = require('../')
-const { join } = require('path')
+const { join } = require('node:path')
 
 const testMethods = {
  '@npmcli/package-json': async (t, testdir, { dir = (v) => v, ...opts } = {}) => {