Interface changes

[jonchurch]

Based on #103

Users likely expect to be able to pass custom properties to errors when creating them via the shortcut methods such as createError.NotFound().

Proposed change would look something like:

const createError = require('http-errors')

createError.NotFound({message: "Aw shucks", data: { foo: "bar" } }) // does not work today

You need to use the createError({...}) form to pass custom properties to an error.

createError(404, {message: "Aw shucks", data: { foo: "bar" } })

There's a few caveats with the current implementation, namely you can't set status via properties.

createError({ status: 404, message: "Aw shucks", data: { foo: "bar" } })
// status is ignored, will create a 500 server error with provided message and data fields

There is also a very high arity for createError, which should be locked down into a stable interface.

(code)

for (var i = 0; i < arguments.length; i++) {
 var arg = arguments[i]
 var type = typeof arg
 if (type === 'object' && arg instanceof Error) {
 err = arg
 status = err.status || err.statusCode || status
 } else if (type === 'number' && i === 0) {
 status = arg
 } else if (type === 'string') {
 msg = arg
 } else if (type === 'object') {
 props = arg
 } else {
 throw new TypeError('argument #' + (i + 1) + ' unsupported type ' + type)
 }
 }

Any of these changes would be semver major. There aren't plans for a major release of http-errors yet, but these are things Im thinking about.

why did I put these both in one issue?

These are both topics related to the interfaces exposed by the library for accepting arguments, which can use some rethinking.

[jonchurch]

There's been prior discussions around the semantics of the inputs we accept, and how it impacts the outputs:

#58 #37 and likely more

[wesleytodd]

Any of these changes would be semver major.

I think it was mentioned in one of the issues that it would be right? FWIW I think there is nothing wrong with packages like this working ahead and doing major releases as long as we are clear on the minimum support from the LTS strat as mentioned in expressjs/discussions#210

[jonchurch]

Yes, Im saying that any of these changes would indeed be semver major.

Im in no rush to make this change or the subclassing change.

This is a tracking issue for a change which is...

related to the interfaces exposed by the library for accepting arguments, which can use some rethinking.

if we did want to land a change in this category, it would need to be in a major.

From reading issue history since posting this though, this seems to be incorrect:

There aren't plans for a major release of http-errors yet, but these are things Im thinking about.

@dougwilson mentioned in a comment that he was planning to make all properties nonenumerable in v3, but that's the only v3 ref Ive run into so far.

There aren't any plans for a new major at least in that it's not documented in the repo or issues so far as I can tell.

[jonchurch]

Related #96 #78

[mahmoodhamdi]

The current loose arity is convenient but definitely surprising in edge cases. I've seen this bite people when passing an error object that already has a status — the error's status silently wins over the explicit status argument (which is what #96 describes).

For v3, I think the named constructor approach would benefit from an options object pattern (as @jonchurch described), similar to how the native Error constructor accepts { cause } in newer Node.js:

// Current — message only
new createError.NotFound('Resource not found')

// Proposed — options object as second arg, aligned with Error(msg, { cause })
new createError.NotFound('Resource not found', {
 expose: true,
 headers: { 'retry-after': '30' },
 cause: originalError
})

This would:

1. Solve Add "expose" to "new createError.[code || name]([msg]))" syntax #78 (expose on named constructors)
2. Align with the native Error(message, options) pattern from ES2022
3. Keep backwards compatibility for the (message) signature
4. Avoid the ambiguity issues with the current createError() factory

For the factory function itself, locking down to explicit signatures instead of the current argument-type-sniffing would definitely reduce surprises. Something like:

createError(status)
createError(status, message)
createError(status, message, properties)
createError(status, error)
createError(status, error, properties)

Where status is always required as the first argument — no more defaulting to 500 based on argument types.