feat: improve type declaration for errors (#147)

* sharedSchemaId type * re-export http error types * also re-export HttpErrorReplys * updated jsdoc * capitalized HttpError * removed empty line Signed-off-by: Arthur Fiorette <[email protected]> --------- Signed-off-by: Arthur Fiorette <[email protected]>
fastify · Oct 17, 2023 · 862cd28 · 862cd28
1 parent a2f544d
commit 862cd28
Show file tree

Hide file tree

Showing 4 changed files with 55 additions and 24 deletions.
diff --git a/README.md b/README.md
@@ -54,13 +54,13 @@ If you set the `sharedSchemaId` option, a shared JSON Schema is added and can be
 ```js
 const fastify = require('fastify')()
 fastify.register(require('@fastify/sensible'), {
-  sharedSchemaId: 'httpError'
+  sharedSchemaId: 'HttpError'
 })
 
 fastify.get('/async', {
   schema: {
     response: {
-      404: { $ref: 'httpError' }
+      404: { $ref: 'HttpError' }
     }
   }
   handler: async (req, reply) => {

diff --git a/lib/httpError.d.ts b/lib/httpError.d.ts
@@ -10,7 +10,7 @@ interface HttpError extends Error {
 
 type UnknownError = Error | string | number | { [key: string]: any };
 
-type HttpErrorCodes = 400 | '400' // BadRequest
+export type HttpErrorCodes = 400 | '400' // BadRequest
                     | 401 | '401' // Unauthorized
                     | 402 | '402' // PaymentRequired
                     | 403 | '403' // Forbidden
@@ -52,7 +52,7 @@ type HttpErrorCodes = 400 | '400' // BadRequest
                     | 510 | '510' // NotExtended
                     | 511 | '511' // NetworkAuthenticationRequire
 
-type HttpErrorNames = 'badRequest'
+export type HttpErrorNames = 'badRequest'
                     | 'unauthorized'
                     | 'paymentRequired'
                     | 'forbidden'

diff --git a/types/index.d.ts b/types/index.d.ts
@@ -1,28 +1,27 @@
 import { FastifyPluginCallback, FastifyReply  } from 'fastify'
 import { HttpErrors, HttpErrorCodes, HttpErrorNames } from "../lib/httpError"
+import * as Errors from '../lib/httpError'
 
 type FastifySensible = FastifyPluginCallback<fastifySensible.SensibleOptions>
 
-type singleValueTypes = 'must-revalidate' |
-  'no-cache' |
-  'no-store' |
-  'no-transform' |
-  'public' |
-  'private' |
-  'proxy-revalidate' |
-  'immutable'
+type singleValueTypes =
+  | 'must-revalidate'
+  | 'no-cache'
+  | 'no-store'
+  | 'no-transform'
+  | 'public'
+  | 'private'
+  | 'proxy-revalidate'
+  | 'immutable'
 
-type multiValueTypes = 'max-age' |
-  's-maxage' |
-  'stale-while-revalidate' |
-  'stale-if-error'
+type multiValueTypes =
+  | 'max-age'
+  | 's-maxage'
+  | 'stale-while-revalidate'
+  | 'stale-if-error'
 
 type staleTypes = 'while-revalidate' | 'if-error'
 
-type HttpErrorReplys = {
-  getHttpError: (code: HttpErrorCodes, message?: string) => FastifyReply;
-} & Record<HttpErrorNames, (msg?: string) => FastifyReply>;
-
 declare module 'fastify' {
   namespace SensibleTypes {
     type ToType<T> = [Error, T];
@@ -45,7 +44,7 @@ declare module 'fastify' {
     httpErrors: HttpErrors;
   }
 
-  interface FastifyReply extends HttpErrorReplys {
+  interface FastifyReply extends fastifySensible.HttpErrorReplys {
     vary: {
       (field: string | string[]): void;
       append: (header: string, field: string | string[]) => string;
@@ -68,11 +67,39 @@ declare module 'fastify' {
 
 declare namespace fastifySensible {
   export interface SensibleOptions {
+    /**
+     * This option registers a shared JSON Schema to be used by all response schemas.
+     * 
+     * @example
+     * ```js
+     * fastify.register(require('@fastify/sensible'), {
+     *   sharedSchemaId: 'HttpError'
+     * })
+     *
+     * fastify.get('/async', {
+     *   schema: {
+     *     response: { 404: { $ref: 'HttpError' } }
+     *   }
+     *   handler: async (req, reply) => {
+     *     return reply.notFound()
+     *   }
+     * })
+     * ```
+     */
+    sharedSchemaId?: string;
   }
 
+  export type HttpErrors = Errors.HttpErrors;
+  export type HttpErrorCodes = Errors.HttpErrorCodes;
+  export type HttpErrorNames = Errors.HttpErrorNames;
+
+  export type HttpErrorReplys = {
+    getHttpError: (code: HttpErrorCodes, message?: string) => FastifyReply;
+  } & Record<HttpErrorNames, (msg?: string) => FastifyReply>
+
   export const fastifySensible: FastifySensible
   export { fastifySensible as default }
 }
 
 declare function fastifySensible(...params: Parameters<FastifySensible>): ReturnType<FastifySensible>
-export = fastifySensible
+export = fastifySensible
diff --git a/types/index.test-d.ts b/types/index.test-d.ts
@@ -1,11 +1,15 @@
-import { expectType, expectAssignable, expectError } from 'tsd'
+import { expectType, expectAssignable, expectError, expectNotAssignable } from 'tsd'
 import fastify from 'fastify'
-import fastifySensible from '..'
+import fastifySensible, { SensibleOptions } from '..'
 
 const app = fastify()
 
 app.register(fastifySensible)
 
+expectAssignable<SensibleOptions>({});
+expectAssignable<SensibleOptions>({ sharedSchemaId: 'HttpError' });
+expectNotAssignable<SensibleOptions>({ notSharedSchemaId: 'HttpError' });
+
 app.get('/', (req, reply) => {
   expectAssignable<typeof reply>(reply.badRequest())
   expectAssignable<typeof reply>(reply.unauthorized())