sappsdb is a TypeScript library that enables you to interact with your MongoDB API easily. It provides methods for common database operations such as find, findOne, insert, insertMany, update, and updateMany. The library is designed with TypeScript generics so that you can enforce strong typing for your documents and queries.
- Type-Safe Methods: Use TypeScript generics to type your documents and queries.
- Simple API: Intuitive methods for performing common MongoDB operations.
-
Bun Compatible: Uses
fetchfor HTTP requests, which works out of the box with Bun. - Modular Design: Easily extendable with support for additional operations like aggregate, transactions, and geo queries.
Install the package via npm:
npm install sappsdbor using yarn:
yarn add sappsdbor using bun:
bun add sappsdbFirst, import and initialize the SappsDB client with your API endpoint:
import { SappsDB } from 'sappsdb';
interface User {
name: string;
email: string;
}
interface UserQuery {
email: string;
}
// Initialize the client with the API endpoint.
const dbClient = new SappsDB('https://api.yourdomain.com', 'token');
async function example() {
// Find users with a specific email.
const users = await dbClient.find<User, UserQuery>('users', { email: 'example@example.com' });
console.log('Found Users:', users);
// Insert a new user.
const newUser: User = { name: 'John Doe', email: 'john@example.com' };
const insertResult = await dbClient.insert<User>('users', newUser);
console.log('Insert Result:', insertResult);
}
example().catch(console.error);Searches for documents in the specified collection using the provided query.
Retrieves a single document matching the query.
Inserts a new document into the specified collection.
Inserts multiple documents into the specified collection.
Updates a single document matching the filter criteria.
Updates multiple documents matching the filter criteria.
First, import and initialize the SappsDB client with your API endpoint:
import { SappsDB } from 'sappsdb';
interface User {
name: string;
email: string;
}
interface UserQuery {
email: string;
}
// Initialize the client with the API endpoint.
const dbClient = new SappsDB('https://api.yourdomain.com');
async function example() {
// Find users with a specific email.
const users = await dbClient.find<User, UserQuery>('users', { email: 'example@example.com' });
console.log('Found Users:', users);
// Insert a new user.
const newUser: User = { name: 'John Doe', email: 'john@example.com' };
const insertResult = await dbClient.insert<User>('users', newUser);
console.log('Insert Result:', insertResult);
}
example().catch(console.error);To insert a document that includes a geolocation field, format the location using GeoJSON. For example:
interface Place {
name: string;
location: {
type: 'Point';
coordinates: number[];
};
}
async function insertPlace() {
const place: Place = {
name: 'Central Park',
location: {
type: 'Point',
coordinates: [-73.965355, 40.782865]
}
};
const result = await dbClient.insert<Place>('places', place);
console.log('Place Inserted:', result);
}
insertPlace().catch(console.error);The geo method allows you to perform advanced geo queries by constructing a valid MongoDB geo query object. Here are a few examples:
Find documents within a specific polygon:
async function findPlacesInPolygon() {
const polygonQuery = {
location: {
$geoWithin: {
$geometry: {
type: 'Polygon',
coordinates: [
[
[-73.99756, 40.73083],
[-73.99756, 40.741404],
[-73.988135, 40.741404],
[-73.988135, 40.73083],
[-73.99756, 40.73083]
]
]
}
}
}
};
const places = await dbClient.geo('places', polygonQuery);
console.log('Places within polygon:', places);
}
findPlacesInPolygon().catch(console.error);Find documents near a point with minimum and maximum distances:
async function findPlacesNearby() {
const nearQuery = {
location: {
$near: {
$geometry: {
type: 'Point',
coordinates: [-73.99279, 40.719296]
},
$minDistance: 100,
$maxDistance: 1000
}
}
};
const nearbyPlaces = await dbClient.geo('places', nearQuery);
console.log('Nearby Places:', nearbyPlaces);
}
findPlacesNearby().catch(console.error);You can create an index on a collection. For example, to create a unique index on the email field or a 2dsphere index on the location field:
async function createIndexes() {
// Create a unique index on the "email" field
const uniqueIndexName = await dbClient.createIndex('users', { email: 1 }, { unique: true });
console.log('Unique index created:', uniqueIndexName);
// Create a 2dsphere index on the "location" field
const geoIndexName = await dbClient.createIndex('places', { location: "2dsphere" });
console.log('Geo index created:', geoIndexName);
}
createIndexes().catch(console.error);To list all indexes on a collection:
async function listIndexes() {
const indexes = await dbClient.listIndexes('users');
console.log('Indexes on users collection:', indexes);
}
listIndexes().catch(console.error);To drop an index by its name:
async function dropIndex() {
const result = await dbClient.dropIndex('users', 'email_1'); // e.g., index name "email_1"
console.log('Index dropped:', result);
}
dropIndex().catch(console.error);The library is designed to be modular and can be extended with additional methods such as aggregate queries, transactions, and geo queries following the same pattern as the existing methods.
Contributions are welcome! Please feel free to submit issues or pull requests for improvements.