TypeBox extensions (typebox-x) is a utility library based around the sinclairzx81/typebox schema builder and validation library.
Features
t.UUID
.date
, email
, uri
.pnpm add @jcwillox/typebox-x @sinclair/typebox
First import the createEnv
function, then pass it a typebox schema.
The createEnv
function uses the clean, convert, default and decode function from typebox to parse you environment variables.
This means that it will strip extra keys, set default values, attempt to convert values to the destination type, e.g. "true" -> true
, and then decode/check the value.
import { createEnv } from "@jcwillox/typebox-x";
const env = createEnv(
t.Object({
APP_ENV: t.Optional(t.String()),
NODE_ENV: t.String({ default: "development" }),
BOOL_FLAG: t.Boolean(),
}),
);
console.log(env.BOOL_FLAG === true); // -> true
Nullable
t.Nullable(t.String());
// t.Union([t.String(), t.Null()]);
Nullish
t.Nullish(t.String());
// t.Optional(t.Union([t.String(), t.Null()]));
UUID
uuid
.
t.UUID();
// t.String({ format: "uuid" })
DateString
Transform
to convert a string to a Date
object when decoding and from a Date
object to a string when encoding.
t.DateString();
RecordString
t.Record
that uses t.String
as the key type, and adds the additionalProperties
property, for backwards compatibility with OpenAPI 3.0.
t.RecordString(t.Object({ one: t.String() }));
// Record<string, {a: string}>
Equivalent to:
t.Record(t.String(), schema, {
additionalProperties: schema,
});
StringEnum
enum
schema representation
t.StringEnum(["one", "two"]);
LiteralEnum
t.Literal
that adds the type
and enum
properties, for backwards compatibility with OpenAPI 3.0.Literal
with this function, for OpenAPI 3.0 compatibility.
t.LiteralEnum("one");
Simply import @jcwillox/typebox-x/formats
before you perform any validations, usually you'll want to do this in you entrypoint. If a format is already defined with the same name, it will not be overwritten.
import "@jcwillox/typebox-x/formats";
Use the typebox prefixed method decorators and provide the corresponding schemas.
import { Controller } from "@nestjs/common";
import { t } from "@jcwillox/typebox-x";
import { TypeboxGet } from "@jcwillox/typebox-x/nestjs";
// or if you prefer we also export non-prefixed methods
// import { Get } from "@jcwillox/typebox-x/nestjs";
@Controller()
export class AppController {
@TypeboxGet(":my_id", {
query: t.Object({
limit: t.Optional(t.Integer({ default: 10 })),
}),
params: {
my_id: t.UUID(),
},
response: t.Object({
message: t.String(),
}),
})
getHello() {
return { message: "Hello World!" };
}
}
You'll likely want to define your schemas outside the @TypeboxGet
decorator, so you can also infer types from them,
using Static<typeof schema>
.
import { Controller, Param, Query } from "@nestjs/common";
import { t } from "@jcwillox/typebox-x";
import { TypeboxGet } from "@jcwillox/typebox-x/nestjs";
import { Static } from "@sinclair/typebox";
type Query = Static<typeof QuerySchema>;
const QuerySchema = t.Object({
limit: t.Optional(t.Integer({ default: 10 })),
});
type Response = Static<typeof ResponseSchema>;
const ResponseSchema = t.Object({
message: t.String(),
});
@Controller()
export class AppController {
@TypeboxGet(":my_id", {
query: QuerySchema,
params: { my_id: t.UUID() },
response: ResponseSchema,
})
getHello(@Param("my_id") myId: string, @Query() query: Query): Response {
return { message: "Hello World!" };
}
}