Model your data with Borg and get run-time type validation, TypeScript types, (de)serialization, and MongoDB niceties such as BSON type conversion and auto-generated validation schemas - for free.
npm install @alecvision/borg
Borg is TypeSafety as code. Borg Schemas are "Write Once, Use Everywhere" - you can use Borg to parse, validate, assert, ~serialize, deserialize,~ (coming soon) and even generate BSON or ~JSON schemas~ (coming soon). Pair Borg with tRPC for a complete end-to-end solution for your API.
- Borg
- Getting Started
- Installation
- Creating a Schema
- Type Inference
- Parsing
- Validating
- Error Handling
- API
- .parse()
- .try()
- .is()
- .serialize()
- Common Chainable Methods
- .copy()
- .optional()
- .required()
- .nullable()
- .notNull()
- .Nullish()
- .notNullish()
- .private()
- .public()
- Chainable String Schema Instance Methods
- .minLength(), .maxLength(), .length()
- .pattern()
- Chainable Number Schema Instance Methods
- .min(), .max(), .range()
- Chainable Array Schema Instance Methods
- .minItems(), .maxLength(), .length()
- Chaining
``bash`
npm install @alecvision/borg
Borg uses a fluent API to define schemas:
`ts
import b from "@alecvision/borg";
const userSchema = b.object({
name: b.string().minLength(1).required(),
age: b.number().min(0).required(),
isAdmin: b.boolean().optional()
});
`
You can use Borg to infer types from your schema, or to infer the type of the object after conversion to BSON:
`ts
import b from "@alecvision/borg";
const userSchema = b.object({
id: b.id(),
name: b.string().minLength(1).required(),
age: b.number().min(0).required(),
isAdmin: b.boolean().optional()
});
type User = b.Type
type UserBson = b.bsonType
`
Parsing produces a new reference, which is strongly typed:
`ts
const user = {
name: "John Doe",
age: 30,
isAdmin: true
};
const parsedUser = userSchema.parse(user);
type ParsedUser = typeof parsedUser; // { name: string; age: number; isAdmin: boolean; }
console.log(User Name: ${parsedUser.name}); // User Name: John DoeUser Age: ${parsedUser.age}
console.log(); // User Age: 30User Is Admin: ${parsedUser.isAdmin}
console.log(); // User Is Admin: true`
console.log(parsedUser === user); // false
You can validate an object in place using the is method:
`tsUser Name: ${user.name}
if (userSchema.is(user)) {
type User = typeof user; // { name: string; age: number; isAdmin: boolean; }
console.log(); // User Name: John DoeUser Age: ${user.age}
console.log(); // User Age: 30User Is Admin: ${user.isAdmin}
console.log(); // User Is Admin: true`
}
When .parse() fails, it throws an instance of BorgError. When .try() fails, it returns an object of the shape { ok: false, error: BorgError }. You can use the try() method to handle errors gracefully:
`ts`
const result = userSchema.try(user);
if (!result.ok) console.log("Validation failed with errors:", result.error);
Or, you can use an error boundary and an instanceof check to handle errors:
`ts`
try {
const parsedUser = userSchema.parse(user);
} catch (error) {
if (error instanceof BorgError) {
console.log("Validation failed with errors:", error.errors);
} else {
throw error;
}
}
Parses the input and returns a new reference that is strongly typed. Throws BorgError if validation fails.
Parses an object and returns a result object with the following shape:
`ts`
{ ok: false, error: BorgError } | { ok: true, value: T, meta: TMeta }
A type guard that returns true if the object matches the schema. It asserts that the object is of the correct type.
Serializes an object to JSON that includes metadata for deserialization with a separate library (coming soon)
Returns a copy of the schema. (This is used under the hood to create new instances of the schema when chaining methods. Because Borg schemas are immutable, you can safely chain methods without mutating the original schema, likely obviating the need for this method.)
Returns an instance of the schema that permits undefined or missing values.
Returns an instance of the schema that must be present and not undefined.
Returns an instance of the schema that permits null values.
Returns an instance of the schema that does not permit null values.
Short for .nullable().optional()
Short for .notNull().required()
Returns an instance of the schema that parses as normal, but fails serialization. If part of an object, the property is removed from the serialized object. If part of an array, the item is removed from the serialized array.
Returns an instance of the schema that parses and serializes as normal.
- #### .minLength(), .maxLength(), .length()
Returns an instance of the schema that validates the length of the string.
`ts`
b.string().length(5); // string must be exactly 5 characters long
b.string().minLength(5); // string must be at least 5 characters long
b.string().maxLength(5); // string must be at most 5 characters long
b.string().length(5, 10); // string must be between 5 and 10 characters long, inclusive
b.string().minLength(4).length(null); // string may be any length
- #### .pattern() (_default_: null [shows as . in type hint*])
Returns an instance of the schema that validates the string against a regular expression, supplied as a string.
`ts`
b.string().pattern("^[a-z]+$"); // string must contain only lowercase letters
NOTE: Special characters in the regular expression must be double-escaped. The typescript inference will display the correct string in all cases EXCEPT when the regular expression includes backslashes. When using backslashes, the type hint will show _the incorrect number of slashes_. To work around this, Borg will parse a regex correctly when an additional backslash is used in the backslash escape sequence. i.e. \\\\ will parse the same as \\\, however will show 4 slashes in the type hint.
`ts
b.string().pattern("^[a-z\\\\]+$"); // string must contain only lowercase letters and backslashes
// ?^
// BorgString<["required", "notNull", "public"], [null, null], "^[a-z\\\\]+$">
b.string().pattern("^[a-z\\]+$"); // string must contain only lowercase letters and backslashes
// ?^
// BorgString<["required", "notNull", "public"], [null, null], "^[a-z\\]+$"> <-- (incorrect)
`
- #### .min(), .max(), .range()
Returns an instance of the schema that validates the number against a range.
`ts`
b.number().range(5, 10); // number must be between 5 and 10, inclusive
b.number().min(5); // number must be at least 5
b.number().max(10); // number must be at most 10
b.number().min(5).max(10).range(5, null); // number must be at least 5
- #### .minItems(), .maxLength(), .length()
Returns an instance of the schema that validates the length of the array.
`ts`
b.array(b.number()).length(5); // array must be exactly 5 items long
b.array(b.number()).minItems(5); // array must be at least 5 items long
b.array(b.number()).maxItems(5); // array must be at most 5 items long
b.array(b.number()).length(5, 10); // array must be at least 5 and at most 10 items long
b.array(b.number()).minItems(4).minItems(null); // array may be any length
Borg schemas are immutable, so you can chain methods to create new instances of the schema. The effects are applied in the order that they are called, making them reversible and composable.
`ts`
const nameSchema = b.string().minLength(5).maxLength(10).notNull().private();
is exactly the same as
`ts``
const nameSchema = b
.string()
.private()
.public()
.minLength(10)
.nullable()
.notNull()
.optional()
.required()
.nullish()
.notNullish()
.nullish()
.required()
.maxLength(15)
.private()
.minLength(null)
.length(5, 10);