Make the prepublish and postpublish logic available from the API

[ggrossetie]

I'm using downdoc API in a release script and I want to use the prepublish/postpublish logic:

with an input file

const { prepublish, postpublish } = require('downdoc/npm')

const outputReadme = await prepublish('/path/to/README.adoc')
await postpublish(outputReadme)

with empty argument (i.e., default values)

const { prepublish, postpublish } = require('downdoc/npm')

await prepublish() // use process.cwd() + README.adoc
await postpublish() // use process.cwd() + README.md

[mojavelinux]

It's not a ton of logic to have to implement without this, but I could see how it would be a nice thing to have.

To keep it simple, we could just export it from the CLI (since only the CLI deals with files).

const { prepublish, postpublish } = require('downdoc/cli')

Though I'm not necessarily against a dedicated npm export.

[ggrossetie]

To keep it simple, we could just export it from the CLI (since only the CLI deals with files).

I'm fine with that 👍🏻

[mojavelinux]

I looked closer into this and I was reminded that it's not a simple as exporting two functions. The prepublish operation is, in fact, two steps that wrap the call to the downdoc function. And both prepublish and postpublish rely on multiple arguments that are passed to the CLI.

However, I believe there's already a better way to accomplish what we want. If we export the CLI function, it can be called through the API. It was set up this way to make it easy to test, but it works well for this purpose too.

Here's how that would look:

const downdoc = require('downdoc/cli')

;(async () => {
  await downdoc({ args: ['/path/to/README.adoc', '--prepublish'] })
  // ...do other work
  await downdoc({ args: ['/path/to/README.adoc', '--postpublish'] })
})()

What we're missing is the computed output path. I think we can fix that by returning the parsed object from parseArgs (or perhaps just the values object), which would reveal the output path in the output property.

{
  prepublish: true,
  input: 'README.adoc',
  output: 'README.md',
  attribute: [ 'env=npm', 'env-npm'],
}

(It's a little strange that attribute is singular, but that's how the parseArgs options are defined...though we could remap it to plural).

A slightly simpler option would be to return the output path when the --prepublish option is present.

const outputPath = await downdoc({ args: ['/path/to/README.adoc', '--prepublish'] })

However, I'm not as much a fan of that as I think it limits what can be done with the CLI.

I think we can get this right, but we probably need to do it after the 1.0.0 release so it isn't rushed.

[mojavelinux]

Btw, it's also possible to capture the output to a string by passing in an object that has the write method to the stdout option.

const io = // object with write method
await downdoc({ args: ['README.adoc', '-o', '-'], stdout: io)