monarch-orm
Advanced tools
Monarch ORM is a strong, type-safe Object Document Mapper (ODM) for MongoDB, designed to provide a seamless and efficient way to interact with your MongoDB database in a type-safe manner. Monarch ensures that your data models are strictly enforced, reducing the risk of runtime errors and enhancing code maintainability.
NPM:
npm install monarch-orm
Or Yarn:
yarn add monarch-orm
import { boolean, createDatabase, createSchema, number, string } from "monarch-orm";
const UserSchema = createSchema("users", {
name: string().nullable(),
email: string().lowercase().optional(),
age: number().optional().default(10),
isVerified: boolean(),
});
const { collections } = createDatabase(client, {
users: UserSchema,
});
const newUser = await collections.users
.insert()
.values({
name: "anon",
email: "anon@gmail.com",
age: 0,
isVerified: true,
})
.exec();
const users = await collections.users.find().where({}).exec();
Use the createSchema function to define the structure of your model. Specify the fields and their types, using the available types and modifiers.
const UserSchema = createSchema("users", {
name: string(),
isVerified: boolean(),
});
Create a database instance using any client you deem fit and drop it into the createDatabase function
Or you can use the built-in createClient function.
const { collections } = createDatabase(client, {
users: UserSchema,
});
You can insert new documents into your collection using the insert method. Ensure that the data conforms to the defined schema.
Example: Inserting a new user
const newUser = await collections.users
.insert()
.values({
name: "Alice",
email: "alice@example.com",
age: 25,
isVerified: true,
})
.exec();
Retrieve documents from your collection using the find or findOne methods.
Example: Querying all users
const users = await collections.users.find().where({}).exec();
console.log(users);
// Or just...
const users = await collections.users.find({}).exec();
console.log(users);
// For finding one
const user = await collections.users.find().where({
name: "Alice"
}).exec();
console.log(users);
// Or...
const user = await collections.users.findOne({
name: "Alice"
}).exec();
console.log(users);
Update documents in your collection using the update method. You can update a single document or multiple documents based on a filter.
Example: Updating a single user's email
const updatedUser = await collections.users
.updateOne()
.set({
email: "alice.updated@example.com",
})
.where({
name: "Alice",
})
.exec();
console.log(updatedUser);
Example: Updating multiple users' isVerified field
const updatedUsers = await collections.users
.updateMany()
.set({
isVerified: true,
})
.where({
isVerified: false,
})
.exec();
console.log(updatedUsers);
Note: The update method returns the number of documents updated.
Defines a field that accepts string values.
const UserSchema = createSchema("users", {
name: string().required(),
});
.lowercase(): Transforms the value to lowercase before storing..uppercase(): Transforms the value to uppercase before storing.const UserSchema = createSchema("users", {
name: string().lowercase(),
});
Defines a field that accepts numeric values.
const UserSchema = createSchema("users", {
age: number().optional(),
});
Defines a field that accepts boolean values (true or false).
const UserSchema = createSchema("users", {
isVerified: boolean(),
});
Defines a field that accepts JavaScript Date objects.
const UserSchema = createSchema("users", {
birthDate: date(),
});
Defines a field that accepts date strings in ISO format.
const UserSchema = createSchema("users", {
registrationDate: dateString(),
});
.nullable(): Allows the field to accept null values..default(): Sets a default value if none is provided..optional(): Makes the field optional, allowing it to be omitted.The literal() type allows you to define a schema with fixed possible values, similar to enums in TypeScript. This is useful for enforcing specific, predefined values for a field.
const UserRoleSchema = createSchema("userRoles", {
role: literal("admin", "moderator", "customer"),
});
const user = {
role: "admin", // Valid
};
// Invalid example will throw a type error
const invalidUser = {
role: "guest", // Error: Type '"guest"' is not assignable to type '"admin" | "moderator" | "customer"'
};
// all properties are required by default
const UserSchema = object({
name: string(),
age: number(),
});
// extract the inferred type like this
type User = InferSchemaInput<typeof UserSchema>;
// equivalent to:
type User = {
name: string;
age: number;
};
A record() allows you to define a flexible schema where each user can have a varying number of subjects and grades without needing to define a fixed schema for each subject.
// Define the User schema with a record for grades
const UserSchema = createSchema("users", {
name: string().required(),
email: string().required(),
grades: record(number()), // Each subject will have a numeric grade
});
// Example of inserting a user with grades
const { collections } = createDatabase(client, {
users: UserSchema,
});
// Inserting a new user with grades for different subjects
const newUser = await collections.users
.insert()
.values({
name: "Alice",
email: "alice@example.com",
grades: {
math: 90,
science: 85,
history: 88,
},
})
.exec();
// Querying the user to retrieve grades
const user = await collections.users.findOne().where({ email: "alice@example.com" }).exec();
console.log(user.grades);
// Output: { math: 90, science: 85, history: 88 }
// For Example
const ResultSchema = object({
name: string(),
scores: array(number()),
});
// extract the inferred type like this
type Result = InferSchemaInput<typeof ResultSchema>;
// equivalent to:
type Result = {
name: string;
scores: number[];
};
Unlike arrays, A tuple() has a fixed number of elements but each element can have a different type.
// all properties are required by default
const ControlSchema = object({
location: tuple([number(), number()]),
});
// extract the inferred type like this
type Control = InferSchemaInput<typeof ControlSchema>;
// equivalent to:
type Control = {
location: [number, number];
};
The taggedUnion() allows you to define a schema for related types, each with its own structure, distinguished by a common "tag" field. This is useful for representing variable types in a type-safe manner.
// You need:
// - a tag: A string identifying the type
// value: An object containing specific fields for that type.
const NotificationSchema = createSchema("notifications", {
notification: taggedUnion({
email: object({
subject: string(),
body: string(),
}),
sms: object({
phoneNumber: string(),
message: string(),
}),
push: object({
title: string(),
content: string(),
}),
}),
});
const notification = ;
await collections.notifications.insert().values({ notification: {
tag: "email",
value: {
subject: "Welcome!",
body: "Thank you for joining us.",
},
} }).exec();
Inserts a new document into the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the insert operation.Summary: Inserts a single document into the collection.
Inserts a single document into the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the insert operation.Summary: Inserts a single document into the collection.
Inserts multiple documents into the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the insert operation.Summary: Inserts multiple documents into the collection.
Retrieves documents from the collection.
Arguments:
Return Type:
Callable Methods:
where(): Filters the documents based on a specified condition.exec(): Executes the find operation.limit(): Limits the number of documents returned.skip(): Skips a specified number of documents.sort(): Sorts the documents by a specified field.Summary: Retrieves documents from the collection based on a filter.
Retrieves a single document from the collection.
Arguments:
Return Type:
Callable Methods:
where(): Filters the documents based on a specified condition.exec(): Executes the find operation.Summary: Retrieves a single document from the collection based on a filter.
Retrieves a single document from the collection and deletes it.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the find and delete operation.Summary: Retrieves a single document from the collection based on a filter and deletes it.
Retrieves a single document from the collection, updates it, and returns the updated document.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the find and update operation.Summary: Retrieves a single document from the collection based on a filter, updates it, and returns the updated document.
Retrieves a single document from the collection, replaces it, and returns the new document.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the find and replace operation.Summary: Retrieves a single document from the collection based on a filter, replaces it, and returns the new document.
Counts the number of documents in the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the count operation.Summary: Counts the number of documents in the collection based on a filter.
Updates a single document in the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the update operation.Summary: Updates a single document in the collection based on a filter.
Updates multiple documents in the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the update operation.Summary: Updates multiple documents in the collection based on a filter.
Deletes a single document from the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the delete operation.Summary: Deletes a single document from the collection based on a filter.
Deletes multiple documents from the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the delete operation.Summary: Deletes multiple documents from the collection based on a filter.
Replaces a single document in the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the replace operation.Summary: Replaces a single document in the collection based on a filter.
Performs aggregation operations on the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the aggregation operation.allowDiskUse(): Allows the aggregation operation to use disk storage.cursor(): Returns a cursor for the aggregation operation.Summary: Performs aggregation operations on the collection using a pipeline.
Watches for changes in the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the watch operation.on(): Attaches a listener to the change stream.Summary: Watches for changes in the collection using a pipeline.
Performs bulk write operations on the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the bulk write operation.Summary: Performs bulk write operations on the collection.
Finds the distinct values for a specified field in the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the distinct operation.Summary: Finds the distinct values for a specified field in the collection based on a filter.
Drops the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the drop operation.Summary: Drops the collection.
Estimates the number of documents in the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the estimated document count operation.Summary: Estimates the number of documents in the collection.
Checks if the collection is capped.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the is capped operation.Summary: Checks if the collection is capped.
Gets the options of the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the options operation.Summary: Gets the options of the collection.
Renames the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the rename operation.Summary: Renames the collection.
Returns the raw MongoDB collection.
Arguments:
Return Type:
Callable Methods:
Summary: Returns the raw MongoDB collection.
Creates an index on the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the create index operation.Summary: Creates an index on the collection.
Creates multiple indexes on the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the create indexes operation.Summary: Creates multiple indexes on the collection.
Drops an index from the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the drop index operation.Summary: Drops an index from the collection.
Drops all indexes from the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the drop indexes operation.Summary: Drops all indexes from the collection.
Lists all indexes on the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the list indexes operation.forEach(): Iterates over the index information.Summary: Lists all indexes on the collection.
Checks if an index exists on the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the index exists operation.Summary: Checks if an index exists on the collection.
Gets information about the indexes on the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the index information operation.forEach(): Iterates over the index information.Summary: Gets information about the indexes on the collection.
Creates a search index on the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the create search index operation.Summary: Creates a search index on the collection.
Creates multiple search indexes on the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the create search indexes operation.Summary: Creates multiple search indexes on the collection.
Drops a search index from the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the drop search index operation.Summary: Drops a search index from the collection.
Lists all search indexes on the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the list search indexes operation.forEach(): Iterates over the search index information.Summary: Lists all search indexes on the collection.
Updates a search index on the collection.
Arguments:
Return Type:
Callable Methods:
exec(): Executes the update search index operation.Summary: Updates a search index on the collection.
Contributions are always welcome!
See contributing.md for ways to get started.
Please adhere to this project's code of conduct.
0.1.2
FAQs
Type safe Object Document Mapper (ODM) for MongoDB
The npm package monarch-orm receives a total of 132 weekly downloads. As such, monarch-orm popularity was classified as not popular.
We found that monarch-orm demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.