Standardize errors for Directus and extensions by exporting from @api/errors

[Zehir]

Summary

Currently isDirectusError() method accept a generic argument for the kind of errors but there is no way to import the extension from the errors source.

It's will also provide the extension creator to throw errors with the same format of the directus ones. Like if an auth extension need to throw an MethodNotAllowedError error.

It's a way to standardise errors for extensions and not having errors that is almost identical but not excatly the same.

Basic Example

The ability to import api errors to be used in extension

With current namming of the const in @directus/api if they are exported we could do :

import { ErrorCode } from '@directus/api'
import type { RecordNotUniqueErrorExtensions } from '@directus/api'

if (isDirectusError<RecordNotUniqueErrorExtensions>(error, ErrorCode.RecordNotUnique)) {
  switch (error.extensions.collection) {
    case 'bundles':
      switch (error.extensions.field) {
        case 'id':
          return 'Bundle with same id already exists'
  }
}

But maybe it's worth reworking isDirectusError to accept a createError return instead of a string;

import { RecordNotUnique } from '@directus/errors'
// RecordNotUnique is createError<RecordNotUniqueErrorExtensions>(...)

if (isDirectusError(error, RecordNotUnique)) {
  switch (error.extensions.collection) {
    case 'bundles':
      switch (error.extensions.field) {
        case 'id':
          return 'Bundle with same id already exists'
  }
}

Motivation

I am using a custom endpoint to insert data into the database. It's an uploaded "zip" file with many data inside that need to be splited up to multiple tables with some extended validation. So for that case I was not able to use the included validator.

So I need to insert data into multiple collections with some uniques constraint so I may get errors from multiple sources.

And to give clear errors message I need to read from it to determine what to do.

Detailed Design

The @directus/errors package will need to have any errors used by directus from the createError() call. Any errors that is used should be migrated to that package to be referenced from the api package.

I think it's worth exporting both string codes like the ErrorCode enum here :

directus/api/src/errors/codes.ts

Lines 1 to 29 in 01f0a18

	export enum ErrorCode {
	ContainsNullValues = 'CONTAINS_NULL_VALUES',
	ContentTooLarge = 'CONTENT_TOO_LARGE',
	Forbidden = 'FORBIDDEN',
	IllegalAssetTransformation = 'ILLEGAL_ASSET_TRANSFORMATION',
	InvalidCredentials = 'INVALID_CREDENTIALS',
	InvalidForeignKey = 'INVALID_FOREIGN_KEY',
	InvalidIp = 'INVALID_IP',
	InvalidOtp = 'INVALID_OTP',
	InvalidPayload = 'INVALID_PAYLOAD',
	InvalidProvider = 'INVALID_PROVIDER',
	InvalidProviderConfig = 'INVALID_PROVIDER_CONFIG',
	InvalidQuery = 'INVALID_QUERY',
	InvalidToken = 'INVALID_TOKEN',
	MethodNotAllowed = 'METHOD_NOT_ALLOWED',
	NotNullViolation = 'NOT_NULL_VIOLATION',
	RangeNotSatisfiable = 'RANGE_NOT_SATISFIABLE',
	RecordNotUnique = 'RECORD_NOT_UNIQUE',
	RequestsExceeded = 'REQUESTS_EXCEEDED',
	RouteNotFound = 'ROUTE_NOT_FOUND',
	ServiceUnavailable = 'SERVICE_UNAVAILABLE',
	TokenExpired = 'TOKEN_EXPIRED',
	UnexpectedResponse = 'UNEXPECTED_RESPONSE',
	UnprocessableContent = 'UNPROCESSABLE_CONTENT',
	UnsupportedMediaType = 'UNSUPPORTED_MEDIA_TYPE',
	UserSuspended = 'USER_SUSPENDED',
	ValueOutOfRange = 'VALUE_OUT_OF_RANGE',
	ValueTooLong = 'VALUE_TOO_LONG',
	}

Migrate any createError that could be without side effects in the @directus/errors package.
For example :

directus/api/src/errors/record-not-unique.ts

Lines 25 to 29 in 01f0a18

	export const RecordNotUniqueError = createError<RecordNotUniqueErrorExtensions>(
	ErrorCode.RecordNotUnique,
	messageConstructor,
	400
	);

Requirements List

Must Have:

• Exported errors codes
• Exported errors extension types

Could Have:

• Exported errors created with createError
• Refactor isDirectusError to accept createError response
• Limit createError to not accept codes that are defined in the well-known errors.

Drawbacks

If we limit createError code param to exclude any codes defined in the well-known codes, users will get a typescript errors, they will need to use the exported one instead of making a new one.

Alternatives

As an alternative I was able to make it work with :

import type { RecordNotUniqueErrorExtensions } from '@directus/api/dist/errors/record-not-unique'

const result = isDirectusError<RecordNotUniqueErrorExtensions>(error, 'RECORD_NOT_UNIQUE')

And in tsconfig.json

    "include": [
        "./src/**/*.ts",
        "@directus/api/dist/errors/record-not-unique.d.ts"
    ]

But not really a good idea to do that.

Adoption Strategy

No kreaking change as you just add exports and you can check typeof code for the isDirectusError method

Unresolved Questions

No response

[rijkvanzanten]

I'm a little hesitant to expose the ones directly exported from /api. I think I'd prefer moving the system-used ones into /errors, so you can just import them directly from there (and keep all the error stuff nice and in the same scope 🙂 )

[Zehir]

Yes that was I was thinking too, any errors in the errors package and imported back when needed like in the api package.

Migrate any createError that could be without side effects in the @directus/errors package

[rijkvanzanten]

@paescuj Any hesitations with doing this? Feels like a small codebase optimization rather than a big new feature to me. I'm down to just refactor this through and get it done if we can't think of any good reasons why not to do this 🙂

[paescuj]

Nope, I don't see an issue with this! Sounds like a good plan 👍

[rijkvanzanten]

This feature request has been accepted and is queued to be implemented! You can follow along with the progress here: #19906

[rijkvanzanten]

This was completed!