fastify / fastify-type-provider-json-schema-to-ts

A Type Provider for json-schema-to-ts

@fastify/type-provider-json-schema-to-ts

A Type Provider for json-schema-to-ts

Install

npm i @fastify/type-provider-json-schema-to-ts

TypeScript requirements

It is required to use [email protected] or above with strict mode enabled and noStrictGenericChecks disabled. You may take the below configuration (tsconfig.json) as an example.

{
  "compilerOptions": {
    "strict": true,
    "noStrictGenericChecks": false
  }
}

Plugin definition

Note When using plugin types, withTypeProvider is not required in order to register the plugin

const plugin: FastifyPluginAsyncJsonSchemaToTs = async function (
  fastify,
  _opts
) {
  fastify.get(
    "/",
    {
      schema: {
        body: {
          type: "object",
          properties: {
            x: { type: "string" },
            y: { type: "number" },
            z: { type: "boolean" },
          },
          required: ["x", "y", "z"],
        } as const,
      },
    },
    (req) => {
      /// The `x`, `y`, and `z` types are automatically inferred
      const { x, y, z } = req.body;
    }
  );
};

Using References from a Shared Schema

JsonSchemaToTsProvider takes a generic that can be passed in the Shared Schema as shown in the following example

const userSchema = {
  type: "object",
  additionalProperties: false,
  properties: {
    givenName: { type: "string" },
    familyName: { type: "string" },
  },
  required: ["givenName", "familyName"],
} as const;

const sharedSchema = {
  $id: "shared-schema",
  definitions: {
    user: userSchema,
  },
} as const;

// then when using JsonSchemaToTsProvider, the shared schema is passed through the generic
// references takes an array so can pass in multiple shared schema
const fastify =
  Fastify().withTypeProvider<
    JsonSchemaToTsProvider<{ references: [typeof sharedSchema] }>
  >();

// now reference the shared schema like the following
fastify.get(
  "/profile",
  {
    schema: {
      body: {
        type: "object",
        properties: {
          user: {
            $ref: "shared-schema#/definitions/user",
          },
        },
        required: ['user'],
      },
    } as const,
  },
  (req) => {
    // givenName and familyName will be correctly typed as strings!
    const { givenName, familyName } = req.body.user;
  }
);

fastify-type-provider-json-schema-to-ts's Issues

json-schema-to-ts provider does not infer types (always unknown)

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

^4.11.0

Plugin version

^2.2.2

Node.js version

18.12.1

Operating system

Windows

Operating system version (i.e. 20.04, 11.3, 10)

10

Description

There is the same thread already exists on stackoverflow. Types just does not get infered and remains 'unknown'.

Steps to Reproduce

Here is the stackblitz reproduce with direct copy-paste of the code from docs.

Expected Behavior

No response

Error `TS(2589): Type instantiation is excessively deep and possibly infinite`

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

4.25.1

Plugin version

2.2.2

Node.js version

20.10

Operating system

Linux

Operating system version (i.e. 20.04, 11.3, 10)

22.04.3 LTS

Description

I get error TS(2589): Type instantiation is excessively deep and possibly infinite whenever relying solely on this plugin. I have to manually create an interface or type per request(which defeats the whole purpose)

Steps to Reproduce

export const SampleController: FastifyPluginAsyncJsonSchemaToTs = async (fastify, _opts) => {
  fastify.post(
  "/test",
  {
    schema: {
      body: {
        type: "object",
        properties: {
                dateFrom: { type: "string", format: "date-time" },
        },
        required: ["dateFrom"],
      },
      response: {
        200: {
          type: "object",
          properties: {
            message: { type: "string" },
          },
        },
        400: {
          type: "object",
          properties: {
            error: { type: "string" },
            message: { type: "string" },
          },
        },
      },
    },
  },
  async (request, reply): Promise<void> => {
	  const {dateFrom: dateString} = request.body; // Error
  };

But if I do

fastify.post<{ Body: { dateFrom: string } }>(...)

it works just fine. Issue is I don't want to have to manually define schemas and types, hence why I use this plugin.

Expected Behavior

I would expect the types to be successfully generated from the schema, with no manual definition from my side

TypeScript only evaluating to `any` when using @fastify/type-provider-json-schema-to-ts

Hi there,

migrating to fastify v4 I was very excited for better TS support on JSON schemas. So I went ahead and tried the example provided on the docs site: https://www.fastify.io/docs/latest/Reference/Type-Providers/#json-schema-to-ts

However, if I do that, foo and bar will always be of type any. Am I holding it wrong? I was expecting the types to be number and string respectively.

import { JsonSchemaToTsProvider } from '@fastify/type-provider-json-schema-to-ts'

import fastify from 'fastify'

const server = fastify().withTypeProvider<JsonSchemaToTsProvider>()

server.get(
  '/route',
  {
    schema: {
      querystring: {
        type: 'object',
        properties: {
          foo: { type: 'number' },
          bar: { type: 'string' },
        },
        required: ['foo', 'bar'],
      },
    } as const
  },
  request => {
    const { bar } = request.query
    bar.push('foo') // I'd expect this to fail with `error TS2339: Property 'push' does not exist on type string`
  }
)

Thank you for your help already!

Your Environment

• node version: 18
• fastify version: >=4.0.0
• typescript version: 4.7.4

Failed to handle multiple response codes in schema

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

^4.9.2

Plugin version

^2.1.1

Node.js version

18

Operating system

Windows

Operating system version (i.e. 20.04, 11.3, 10)

10

Description

It doesn't convert to the intended typing when comes to defining multiple response code in the schema like this:

schema: {
  response: {
    200: ObjectData,
    404: {
        type: 'object',
        properties: {
          statusCode: 'number',
          error: 'string',
          message: 'string',
        }
     }
  }
}

Above will throw TS error like this:
Type 'Document<unknown, any, ObjectData> & ObjectData & Required<{ _id: string; }>' is missing the following properties from type '{ [x: string]: unknown; error?: string | undefined; statusCode: number; message: string; }': statusCode, message

When using 'oneOf' in the response like this:

schema: {
  response: {
    oneOf: [
      { 200: ObjectData },
      { 
        404: {
          type: 'object',
          properties: {
            statusCode: 'number',
            error: 'string',
            message: 'string',
          }
        }
      }
    ]
  }
}

It seems to be correctly parsed by schema-to-ts, but the fastify wouldn't allow it by throwing this error:
"Failed building the serialization schema for POST: /xxx, due to error response schemas should be nested under a valid status code, e.g { 2xx: { type: \"object\" } }"

Steps to Reproduce

schema: {
  response: {
    200: ObjectData,
    404: {
        type: 'object',
        properties: {
          statusCode: 'number',
          error: 'string',
          message: 'string',
        }
     }
  }
}

Expected Behavior

I don't know how to sort this out. Maybe treat response types differently by using oneOf logic?

Property bar does not exist on type in the docs example using TS4.8.4

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

4.9.2

Plugin version

2.1.1

Node.js version

16.13.0

Operating system

Linux

Operating system version (i.e. 20.04, 11.3, 10)

22.04

Description

Hi.

I stumbled over the example code of the fastify docs, similar to the closed issue #12. There is a TypeScript Playground Link given where everything is expected to be properly configured. As I were unable to extract all desired information, I moved to codesandbox with the given code I had to add the dependencies there.

Final the setup is:

package.json

{
  "dependencies": {
    "typescript": "4.8.4",
    "fastify": "^4.9.2",
    "@fastify/type-provider-json-schema-to-ts": "^2.1.1"
  },
  "description": "TypeScript playground exported Sandbox",
  "name": "TypeScript Playground Export",
  "version": "0.0.0"
}

tsconfig.json

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictPropertyInitialization": true,
    "strictBindCallApply": true,
    "noImplicitThis": true,
    "noImplicitReturns": true,
    "alwaysStrict": true,
    "esModuleInterop": true,
    "declaration": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES2017",
    "jsx": "react",
    "module": "ESNext",
    "moduleResolution": "node"
  }
}

and index.ts

import { JsonSchemaToTsProvider } from "@fastify/type-provider-json-schema-to-ts";

import fastify from "fastify";

const server = fastify().withTypeProvider<JsonSchemaToTsProvider>();

server.get(
  "/route",
  {
    schema: {
      querystring: {
        type: "object",
        properties: {
          foo: { type: "number" },
          bar: { type: "string" }
        },
        required: ["foo", "bar"]
      }
    } as const
  },
  (request) => {
    const { bar } = request.query;
    bar.push("foo"); // I'd expect this to fail with `error TS2339: Property 'push' does not exist on type string`
  }
);

as you can see, the desired unwrapping does not take place. Instead it says: "property bar does not exist on type unkndown" What am I doing wrong? Or did it break with the new TS version that has been released (our assumption)?

Steps to Reproduce

Use code outlined above. Ensure to use Typescript Version 4.8.4.
Or see the live example at codesandbox

Expected Behavior

No response

this package adds non-existing props to the generated type

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

4.24.0

Plugin version

2.2.2

Node.js version

18.x

Operating system

Linux

Operating system version (i.e. 20.04, 11.3, 10)

22

Description

following your example:

const plugin: FastifyPluginAsyncJsonSchemaToTs = async function (
  fastify,
  _opts
) {
  fastify.get(
    "/",
    {
      schema: {
        body: {
          type: "object",
          properties: {
            x: { type: "string" },
            y: { type: "number" },
            z: { type: "boolean" },
          },
          required: ["x", "y", "z"],
        } as const,
      },
    },
    (req) => {
      /// The `x`, `y`, and `z` types are automatically inferred
      const { x, y, z } = req.body;
    }
  );
};

now req.body has the following type

{
  // extra property that allows arbitrary props that don't exist in the original schema
  [x: string]: unknown;
  x: string;
  y: string;
  z: string;
}

remove the extra prop, and you may add an option to allow arbitrary props

Steps to Reproduce

.

Expected Behavior

No response

Build wasn't ran before the last release of 2.2.0

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

3.x

Plugin version

No response

Node.js version

18.x

Operating system

Linux

Operating system version (i.e. 20.04, 11.3, 10)

using custom gentoo

Description

Updated to latest version than saw TS error complaining about no generic, but there is one in the root/index..ts. I then realized root/dist/index.d.ts doesn't have the generic I added to root/index.ts.

Can look at adding a prepublish script to force build to be ran before every publish.

Steps to Reproduce

install as a package in another repo, then can see the index.d.ts in dist that the package.json points to does not match the index.ts file at the root of this repo.

Expected Behavior

No response

Schemas fail to convert to types with json-schema-to-ts 2.9+

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

4.17.0

Plugin version

2.2.2

Node.js version

18.16.0

Operating system

Linux

Operating system version (i.e. 20.04, 11.3, 10)

11

Description

With [email protected] the simple example fails to infer types from the schema:

import { JsonSchemaToTsProvider } from '@fastify/type-provider-json-schema-to-ts'

import fastify from 'fastify'

const server = fastify().withTypeProvider<JsonSchemaToTsProvider>()

server.get(
  '/route',
  {
    schema: {
      querystring: {
        type: 'object',
        properties: {
          foo: { type: 'number' },
          bar: { type: 'string' },
        },
        required: ['foo', 'bar'],
      },
    } as const
  },
  request => {
    const { bar } = request.query
    bar.push('foo') // I'd expect this to fail with `error TS2339: Property 'push' does not exist on type string`
  }
)

Works (or fails) as expected with [email protected]

But fails on [email protected] with:

server.ts:22:13 - error TS2339: Property 'bar' does not exist on type 'unknown'.

22     const { bar } = request.query
               ~~~

server.ts:22:21 - error TS2589: Type instantiation is excessively deep and possibly infinite.

22     const { bar } = request.query
                       ~~~~~~~~~~~~~


Found 2 errors in the same file, starting at: src/server.ts:22

Interestingly [email protected] looks to be an update in release process rather than functional changes, so I will raise over there as well.

Steps to Reproduce

in sample fastify-type-provider-json-schema-to-ts project
yarn add json-schema-to-ts@~2.8.0
tsc # expected
yarn add json-schema-to-ts@~2.9.0
tsc # no schema types

Expected Behavior

Same as [email protected]

There appears to be a similar issue in [email protected] that was resolved, but I can't reproduce that issue in fastify-type-provider-json-schema-to-ts with [email protected]

Array item should be possibly 'undefined'

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

4.11.0

Plugin version

2.2.1

Node.js version

16.15.1

Operating system

macOS

Operating system version (i.e. 20.04, 11.3, 10)

12.5

Description

Given a body of type: 'array' with items of type Item the type output currently is Item[], but it should actually be (Item | undefined)[]

Steps to Reproduce

Given a route description:

server.put('/', {
    schema: {
        body: {
            type: 'array',
            items: {
                type: 'object',
                properties: {
                    id: { type: 'number' },
                }
            },
        }
    } as const
}, async (req) => {
    req.body[0].id
})

Though no type errors are present, when given a body of an empty array [] the empty array will pass validation, but this route will fail at runtime, as req.body[0] is undefined, resulting in the response:

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Cannot read properties of undefined (reading 'id')"
}

Expected Behavior

The expected behavior is that the type of the array should be (Item | undefined)[]. This should cause a proper type hint:

}, async (req) => {
    req.body[0].id
//  ^ Object is possibly 'undefined'
})

Add support for $ref/references

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

The type provider currently does not support $ref or the references prop of FromSchema. So any schema using $ref will end up with undefined

import { JsonSchemaToTsProvider } from "@fastify/type-provider-json-schema-to-ts";
import { FastifyPluginAsync } from "fastify";
import { FromSchema } from "json-schema-to-ts";

const root: FastifyPluginAsync = async (fastify, opts): Promise<void> => {
  const server = fastify.withTypeProvider<JsonSchemaToTsProvider>();

  const Foo = {
    $id: "Foo",
    title: "Foo",
    type: "object",
    properties: {
      foo: { type: "string" },
    },
  } as const;
  fastify.addSchema(Foo);

  const Bar = {
    type: "object",
    properties: {
      stuff: { $ref: "Foo" },
    },
  } as const;
  type BarType = FromSchema<typeof Bar, { references: [typeof Foo] }>;
  let x: BarType; // Has type for `stuff` by virtue of specifying references

  server.get("/", async function (request, reply) {
    return { root: true };
  });

  server.post(
    "/",
    {
      schema: {
        body: Bar,
      },
    },
    async function (request, reply) {
      const x = request.body; // No type for `stuff`, it's just `undefined` :(
    }
  );
};

export default root;

Motivation

Being able to use the type provider even with schema that use $ref without having to resort to manual FromSchema which is the whole point of the type provider to begin with.

Example

No response

Circular reference types when used with @fastify/multipart

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

4.22.0

Plugin version

2.2.2

Node.js version

18.16.0

Operating system

macOS

Operating system version (i.e. 20.04, 11.3, 10)

12.6.8

Description

Using FastifyPluginAsyncJsonSchemaToTs along with the shared schema from @fastify/multipart generates a circular type error:

[TypeScript] src/routes/indexes/index.ts:104:40 - error TS2615: Type of property 'file' circularly references itself in mapped type '{ file: Never; }'.
[TypeScript] 
[TypeScript] 104       const { file } = request.body;
[TypeScript]                            ~~~~~~~~~~~~

Steps to Reproduce

1. Configure @fastify/multipart in a test project with these options:

import fp from 'fastify-plugin';
import multipart from '@fastify/multipart';

export default fp(async (fastify) => {
  fastify.register(multipart, {
    attachFieldsToBody: true,
    sharedSchemaId: '#multipartField',
  });
});

2. Create a route that references the shared schema:

import { FastifyPluginAsyncJsonSchemaToTs } from '@fastify/type-provider-json-schema-to-ts';

const root: FastifyPluginAsyncJsonSchemaToTs = async (fastify, opts): Promise<void> => {

  fastify.post('/upload', {
    schema: {
      body: {
        type: 'object',
        properties: {
          file: { $ref: '#multipartField' },
        },
        required: ['file'],
      },
    } as const,
    handler: async function (request, reply) {
      const { file } = request.body;
    }
  });
});

Expected Behavior

No error

Unknown request body when using onRequest hook

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

When using a hook like onRequest, the schema validation doesn't work anymore. If e.g. a body schema is specified in MySchema, the request body will be of type unknown:

const appWithTypeProvider = app.withTypeProvider<JsonSchemaToTsProvider>();
appWithTypeProvider.post('/', {schema: MySchema, onRequest: randomMethod}, async (request) => {
  request.body // unknown
});

Is this wanted behaviour?

Cannot import FastifyPluginAsyncJsonSchemaToTs

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

4.2.0

Plugin version

2.1.0

Node.js version

18.4.0

Operating system

Windows

Operating system version (i.e. 20.04, 11.3, 10)

21H2

Description

The FastifyPluginAsyncJsonSchemaToTs and FastifyPluginCallbackJsonSchemaToTs types added in v2.1.0 are missing in dist/index.d.ts file.

Steps to Reproduce

1. pnpm i @fastify/type-provider-json-schema-to-ts

2. import type { FastifyPluginAsyncJsonSchemaToTs } from '@fastify/type-provider-json-schema-to-ts'

=> Module '"@fastify/type-provider-json-schema-to-ts"' has no exported member 'FastifyPluginAsyncJsonSchemaToTs'.

Expected Behavior

No response

v3 released but not available on NPM

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

4.25.2

Plugin version

2.2.2

Node.js version

18.19

Operating system

macOS

Operating system version (i.e. 20.04, 11.3, 10)

14.2.1

Description

I have the issue #68 in my project, which is fixed by v3 of this package, but the latest NPM version is still 2.2.2.

Steps to Reproduce

npm i @fastify/type-provider-json-schema-to-ts@3

Expected Behavior

v3 to be published on NPM :)

Not showing type error for status codes not in schema

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

4.25.2

Plugin version

3.0.0

Node.js version

20.10.0

Operating system

macOS

Operating system version (i.e. 20.04, 11.3, 10)

14.3

Description

In my schema, I've specified that the only response code is 201. However, if I write my handler as returning a 200, I don't get a type error:

Steps to Reproduce

import { FastifyPluginAsyncJsonSchemaToTs } from "@fastify/type-provider-json-schema-to-ts"

const plugin: FastifyPluginAsyncJsonSchemaToTs = async function (
    fastify,
    _opts
) {
    fastify.post(
        "/sign-up",
        {
            schema: {
                response: {
                    201: {
                        type: "object",
                        properties: {
                            email: { type: "string" },
                        },
                        required: ["email"],
                    },
                },
            },
        },
        async (_, reply) => {
            return reply.status(200).send() // This should show a type error on status 200 because not in schema
        }
    )
}

export default plugin

Expected Behavior

When using generics, it'll show a type error on 200 which I believe is the desired behaviour.

Documentation nitpick: possibly add minimum node engine version

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

Very nice library!

With this issue, I only want to raise a minor awareness issue (which could be addressed by a small doc note or other possibly more "invasive" solutions).

I (and other people from what I've witnessed on Reddit and StackOverflow) found it difficult to understand why the library wasn't working like it was supposed to.

The main problem comes from something other than the code we write but from one's dev environment.

TLDR: a peer dependency requires Node 16, but since it's not enforced by npm (at least not by default), you can run into "silent breakages" when you use an older version of Node (example 14).

You can also experience this issue when cloning this repository and trying to npm install && npm test with Node < 16.

Reproduction on a small example

Setup environment first (nvm required)

nvm install 14
nvm  use 14
node -v
# should output "v14.xx.xx"

Basic example:

import fastify from 'fastify'

import { FastifyPluginAsyncJsonSchemaToTs } from "@fastify/type-provider-json-schema-to-ts"

const server = fastify()

const pingPlugin: FastifyPluginAsyncJsonSchemaToTs = async function (fastify, opts) {

	fastify.get('/ping/:times?', {
		schema: {
			params: {
				type: 'object',
				properties: {
					times: { 
						default: 1,
						type: 'number'
					}
				}
			} as const
		}
	}, async (request) => {
		const {times = 1} = request.params

		if (times > 1 && times < 10) {
			const oCount = 'o'.repeat(times)
			return `p${oCount}ng`
		}

		return 'pong!'
	})
}

server.register(pingPlugin)

server.listen({ port: 8080 }, (err, address) => {
	if (err) {
		console.error(err)
		process.exit(1)
	}
	console.log(`Server listening at ${address}`)
})

Project setup:

npm init -y
npm i fastify
npm i -D @fastify/type-provider-json-schema-to-ts @types/node typescript

If you use an older version of Node (example 14 LTS), you might notice the following warnings raised by npm:

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '[email protected]',
npm WARN EBADENGINE   required: { node: '>=16' },
npm WARN EBADENGINE   current: { node: 'v14.21.2', npm: '9.5.0' }
npm WARN EBADENGINE }

And this is where the issue lies: these warnings effectively hinder this lib's ability to function properly since the required dependency is not installed. And since they are warnings, people might not notice them (or, at least, that's what happened to me).

You might ask: what solved it?
Just run nvm use 18 or nvm use 16 (if you use nvm) and reinstall dependencies.

Just FYI:

• the change in json-schema-to-ts that introduced the first requirement on the Node core version (effectively min Node is 16) is ThomasAribart/json-schema-to-ts@688087b
• this change is pulled in automatically since the semver range specified on this lib's peerDependencies allows it:

  fastify-type-provider-json-schema-to-ts/package.json

  Line 31 in c85b141

  "json-schema-to-ts": "^2.0.0"

What I propose to acknowledge this issue

1. Add a small note in the README that mentions this possible breakage on older Node.js version (my preferred approach to at least acknowledge this issue)
2. Do nothing since Node.js 14 LTS is due by 2023-04-30
3. "Fix" the semver version declared in package.json for json-schema-to-ts (how? depends on this lib's support policy over Node core versions)
4. Add the required node engine version to this lib, too (maybe it will be enforced by npm if dependencies are "direct" vs. "indirect", needs testing)