-241

client.ts

··· 1 1 - import { 2 2 - type Db, 3 3 - type MongoClientOptions, 4 4 - type ClientSession, 5 5 - type TransactionOptions, 6 6 - MongoClient 7 7 - } from "mongodb"; 8 8 - import { ConnectionError } from "./errors.ts"; 9 9 - 10 10 - interface Connection { 11 11 - client: MongoClient; 12 12 - db: Db; 13 13 - } 14 14 - 15 15 - let connection: Connection | null = null; 16 16 - 17 17 - export interface ConnectOptions extends MongoClientOptions {}; 18 18 - 19 19 - /** 20 20 - * Health check details of the MongoDB connection 21 21 - * 22 22 - * @property healthy - Overall health status of the connection 23 23 - * @property connected - Whether a connection is established 24 24 - * @property responseTimeMs - Response time in milliseconds (if connection is healthy) 25 25 - * @property error - Error message if health check failed 26 26 - * @property timestamp - Timestamp when health check was performed 27 27 - */ 28 28 - export interface HealthCheckResult { 29 29 - healthy: boolean; 30 30 - connected: boolean; 31 31 - responseTimeMs?: number; 32 32 - error?: string; 33 33 - timestamp: Date; 34 34 - } 35 35 - 36 36 - /** 37 37 - * Connect to MongoDB with connection pooling, retry logic, and resilience options 38 38 - * 39 39 - * The MongoDB driver handles connection pooling and automatic retries. 40 40 - * Retry logic is enabled by default for both reads and writes in MongoDB 4.2+. 41 41 - * 42 42 - * @param uri - MongoDB connection string 43 43 - * @param dbName - Name of the database to connect to 44 44 - * @param options - Connection options (pooling, retries, timeouts, etc.) 45 45 - * 46 46 - * @example 47 47 - * Basic connection with pooling: 48 48 - * ```ts 49 49 - * await connect("mongodb://localhost:27017", "mydb", { 50 50 - * maxPoolSize: 10, 51 51 - * minPoolSize: 2, 52 52 - * maxIdleTimeMS: 30000, 53 53 - * connectTimeoutMS: 10000, 54 54 - * socketTimeoutMS: 45000, 55 55 - * }); 56 56 - * ``` 57 57 - * 58 58 - * @example 59 59 - * Production-ready connection with retry logic and resilience: 60 60 - * ```ts 61 61 - * await connect("mongodb://localhost:27017", "mydb", { 62 62 - * // Connection pooling 63 63 - * maxPoolSize: 10, 64 64 - * minPoolSize: 2, 65 65 - * 66 66 - * // Automatic retry logic (enabled by default) 67 67 - * retryReads: true, // Retry failed read operations 68 68 - * retryWrites: true, // Retry failed write operations 69 69 - * 70 70 - * // Timeouts 71 71 - * connectTimeoutMS: 10000, // Initial connection timeout 72 72 - * socketTimeoutMS: 45000, // Socket operation timeout 73 73 - * serverSelectionTimeoutMS: 10000, // Server selection timeout 74 74 - * 75 75 - * // Connection resilience 76 76 - * maxIdleTimeMS: 30000, // Close idle connections 77 77 - * heartbeatFrequencyMS: 10000, // Server health check interval 78 78 - * 79 79 - * // Optional: Compression for reduced bandwidth 80 80 - * compressors: ['snappy', 'zlib'], 81 81 - * }); 82 82 - * ``` 83 83 - */ 84 84 - export async function connect( 85 85 - uri: string, 86 86 - dbName: string, 87 87 - options?: ConnectOptions, 88 88 - ): Promise<Connection> { 89 89 - if (connection) { 90 90 - return connection; 91 91 - } 92 92 - 93 93 - try { 94 94 - const client = new MongoClient(uri, options); 95 95 - await client.connect(); 96 96 - const db = client.db(dbName); 97 97 - 98 98 - connection = { client, db }; 99 99 - return connection; 100 100 - } catch (error) { 101 101 - throw new ConnectionError( 102 102 - `Failed to connect to MongoDB: ${error instanceof Error ? error.message : String(error)}`, 103 103 - uri 104 104 - ); 105 105 - } 106 106 - } 107 107 - 108 108 - export async function disconnect(): Promise<void> { 109 109 - if (connection) { 110 110 - await connection.client.close(); 111 111 - connection = null; 112 112 - } 113 113 - } 114 114 - 115 115 - /** 116 116 - * Start a new client session for transactions 117 117 - * 118 118 - * Sessions must be ended when done using `endSession()` 119 119 - * 120 120 - * @example 121 121 - * ```ts 122 122 - * const session = await startSession(); 123 123 - * try { 124 124 - * // use session 125 125 - * } finally { 126 126 - * await endSession(session); 127 127 - * } 128 128 - * ``` 129 129 - */ 130 130 - export function startSession(): ClientSession { 131 131 - if (!connection) { 132 132 - throw new ConnectionError("MongoDB not connected. Call connect() first."); 133 133 - } 134 134 - return connection.client.startSession(); 135 135 - } 136 136 - 137 137 - /** 138 138 - * End a client session 139 139 - * 140 140 - * @param session - The session to end 141 141 - */ 142 142 - export async function endSession(session: ClientSession): Promise<void> { 143 143 - await session.endSession(); 144 144 - } 145 145 - 146 146 - /** 147 147 - * Execute a function within a transaction 148 148 - * 149 149 - * Automatically handles session creation, transaction start/commit/abort, and cleanup. 150 150 - * If the callback throws an error, the transaction is automatically aborted. 151 151 - * 152 152 - * @param callback - Async function to execute within the transaction. Receives the session as parameter. 153 153 - * @param options - Optional transaction options (read/write concern, etc.) 154 154 - * @returns The result from the callback function 155 155 - * 156 156 - * @example 157 157 - * ```ts 158 158 - * const result = await withTransaction(async (session) => { 159 159 - * await UserModel.insertOne({ name: "Alice" }, { session }); 160 160 - * await OrderModel.insertOne({ userId: "123", total: 100 }, { session }); 161 161 - * return { success: true }; 162 162 - * }); 163 163 - * ``` 164 164 - */ 165 165 - export async function withTransaction<T>( 166 166 - callback: (session: ClientSession) => Promise<T>, 167 167 - options?: TransactionOptions 168 168 - ): Promise<T> { 169 169 - const session = await startSession(); 170 170 - 171 171 - try { 172 172 - let result: T; 173 173 - 174 174 - await session.withTransaction(async () => { 175 175 - result = await callback(session); 176 176 - }, options); 177 177 - 178 178 - return result!; 179 179 - } finally { 180 180 - await endSession(session); 181 181 - } 182 182 - } 183 183 - 184 184 - export function getDb(): Db { 185 185 - if (!connection) { 186 186 - throw new ConnectionError("MongoDB not connected. Call connect() first."); 187 187 - } 188 188 - return connection.db; 189 189 - } 190 190 - 191 191 - /** 192 192 - * Check the health of the MongoDB connection 193 193 - * 194 194 - * Performs a ping operation to verify the database is responsive 195 195 - * and returns detailed health information including response time. 196 196 - * 197 197 - * @example 198 198 - * ```ts 199 199 - * const health = await healthCheck(); 200 200 - * if (health.healthy) { 201 201 - * console.log(`Database healthy (${health.responseTimeMs}ms)`); 202 202 - * } else { 203 203 - * console.error(`Database unhealthy: ${health.error}`); 204 204 - * } 205 205 - * ``` 206 206 - */ 207 207 - export async function healthCheck(): Promise<HealthCheckResult> { 208 208 - const timestamp = new Date(); 209 209 - 210 210 - // Check if connection exists 211 211 - if (!connection) { 212 212 - return { 213 213 - healthy: false, 214 214 - connected: false, 215 215 - error: "No active connection. Call connect() first.", 216 216 - timestamp, 217 217 - }; 218 218 - } 219 219 - 220 220 - try { 221 221 - // Measure ping response time 222 222 - const startTime = performance.now(); 223 223 - await connection.db.admin().ping(); 224 224 - const endTime = performance.now(); 225 225 - const responseTimeMs = Math.round(endTime - startTime); 226 226 - 227 227 - return { 228 228 - healthy: true, 229 229 - connected: true, 230 230 - responseTimeMs, 231 231 - timestamp, 232 232 - }; 233 233 - } catch (error) { 234 234 - return { 235 235 - healthy: false, 236 236 - connected: true, 237 237 - error: error instanceof Error ? error.message : String(error), 238 238 - timestamp, 239 239 - }; 240 240 - } 241 241 - }

+126

client/connection.ts

··· 1 1 + import { type Db, type MongoClientOptions, MongoClient } from "mongodb"; 2 2 + import { ConnectionError } from "../errors.ts"; 3 3 + 4 4 + /** 5 5 + * Connection management module 6 6 + * 7 7 + * Handles MongoDB connection lifecycle including connect, disconnect, 8 8 + * and connection state management. 9 9 + */ 10 10 + 11 11 + export interface Connection { 12 12 + client: MongoClient; 13 13 + db: Db; 14 14 + } 15 15 + 16 16 + export interface ConnectOptions extends MongoClientOptions {} 17 17 + 18 18 + // Singleton connection state 19 19 + let connection: Connection | null = null; 20 20 + 21 21 + /** 22 22 + * Connect to MongoDB with connection pooling, retry logic, and resilience options 23 23 + * 24 24 + * The MongoDB driver handles connection pooling and automatic retries. 25 25 + * Retry logic is enabled by default for both reads and writes in MongoDB 4.2+. 26 26 + * 27 27 + * @param uri - MongoDB connection string 28 28 + * @param dbName - Name of the database to connect to 29 29 + * @param options - Connection options (pooling, retries, timeouts, etc.) 30 30 + * @returns Connection object with client and db 31 31 + * 32 32 + * @example 33 33 + * Basic connection with pooling: 34 34 + * ```ts 35 35 + * await connect("mongodb://localhost:27017", "mydb", { 36 36 + * maxPoolSize: 10, 37 37 + * minPoolSize: 2, 38 38 + * maxIdleTimeMS: 30000, 39 39 + * connectTimeoutMS: 10000, 40 40 + * socketTimeoutMS: 45000, 41 41 + * }); 42 42 + * ``` 43 43 + * 44 44 + * @example 45 45 + * Production-ready connection with retry logic and resilience: 46 46 + * ```ts 47 47 + * await connect("mongodb://localhost:27017", "mydb", { 48 48 + * // Connection pooling 49 49 + * maxPoolSize: 10, 50 50 + * minPoolSize: 2, 51 51 + * 52 52 + * // Automatic retry logic (enabled by default) 53 53 + * retryReads: true, // Retry failed read operations 54 54 + * retryWrites: true, // Retry failed write operations 55 55 + * 56 56 + * // Timeouts 57 57 + * connectTimeoutMS: 10000, // Initial connection timeout 58 58 + * socketTimeoutMS: 45000, // Socket operation timeout 59 59 + * serverSelectionTimeoutMS: 10000, // Server selection timeout 60 60 + * 61 61 + * // Connection resilience 62 62 + * maxIdleTimeMS: 30000, // Close idle connections 63 63 + * heartbeatFrequencyMS: 10000, // Server health check interval 64 64 + * 65 65 + * // Optional: Compression for reduced bandwidth 66 66 + * compressors: ['snappy', 'zlib'], 67 67 + * }); 68 68 + * ``` 69 69 + */ 70 70 + export async function connect( 71 71 + uri: string, 72 72 + dbName: string, 73 73 + options?: ConnectOptions, 74 74 + ): Promise<Connection> { 75 75 + if (connection) { 76 76 + return connection; 77 77 + } 78 78 + 79 79 + try { 80 80 + const client = new MongoClient(uri, options); 81 81 + await client.connect(); 82 82 + const db = client.db(dbName); 83 83 + 84 84 + connection = { client, db }; 85 85 + return connection; 86 86 + } catch (error) { 87 87 + throw new ConnectionError( 88 88 + `Failed to connect to MongoDB: ${error instanceof Error ? error.message : String(error)}`, 89 89 + uri 90 90 + ); 91 91 + } 92 92 + } 93 93 + 94 94 + /** 95 95 + * Disconnect from MongoDB and clean up resources 96 96 + */ 97 97 + export async function disconnect(): Promise<void> { 98 98 + if (connection) { 99 99 + await connection.client.close(); 100 100 + connection = null; 101 101 + } 102 102 + } 103 103 + 104 104 + /** 105 105 + * Get the current database connection 106 106 + * 107 107 + * @returns MongoDB Db instance 108 108 + * @throws {ConnectionError} If not connected 109 109 + * @internal 110 110 + */ 111 111 + export function getDb(): Db { 112 112 + if (!connection) { 113 113 + throw new ConnectionError("MongoDB not connected. Call connect() first."); 114 114 + } 115 115 + return connection.db; 116 116 + } 117 117 + 118 118 + /** 119 119 + * Get the current connection state 120 120 + * 121 121 + * @returns Connection object or null if not connected 122 122 + * @internal 123 123 + */ 124 124 + export function getConnection(): Connection | null { 125 125 + return connection; 126 126 + }

+80

client/health.ts

··· 1 1 + import { getConnection } from "./connection.ts"; 2 2 + 3 3 + /** 4 4 + * Health check module 5 5 + * 6 6 + * Provides functionality for monitoring MongoDB connection health 7 7 + * including ping operations and response time measurement. 8 8 + */ 9 9 + 10 10 + /** 11 11 + * Health check details of the MongoDB connection 12 12 + * 13 13 + * @property healthy - Overall health status of the connection 14 14 + * @property connected - Whether a connection is established 15 15 + * @property responseTimeMs - Response time in milliseconds (if connection is healthy) 16 16 + * @property error - Error message if health check failed 17 17 + * @property timestamp - Timestamp when health check was performed 18 18 + */ 19 19 + export interface HealthCheckResult { 20 20 + healthy: boolean; 21 21 + connected: boolean; 22 22 + responseTimeMs?: number; 23 23 + error?: string; 24 24 + timestamp: Date; 25 25 + } 26 26 + 27 27 + /** 28 28 + * Check the health of the MongoDB connection 29 29 + * 30 30 + * Performs a ping operation to verify the database is responsive 31 31 + * and returns detailed health information including response time. 32 32 + * 33 33 + * @returns Health check result with status and metrics 34 34 + * 35 35 + * @example 36 36 + * ```ts 37 37 + * const health = await healthCheck(); 38 38 + * if (health.healthy) { 39 39 + * console.log(`Database healthy (${health.responseTimeMs}ms)`); 40 40 + * } else { 41 41 + * console.error(`Database unhealthy: ${health.error}`); 42 42 + * } 43 43 + * ``` 44 44 + */ 45 45 + export async function healthCheck(): Promise<HealthCheckResult> { 46 46 + const timestamp = new Date(); 47 47 + const connection = getConnection(); 48 48 + 49 49 + // Check if connection exists 50 50 + if (!connection) { 51 51 + return { 52 52 + healthy: false, 53 53 + connected: false, 54 54 + error: "No active connection. Call connect() first.", 55 55 + timestamp, 56 56 + }; 57 57 + } 58 58 + 59 59 + try { 60 60 + // Measure ping response time 61 61 + const startTime = performance.now(); 62 62 + await connection.db.admin().ping(); 63 63 + const endTime = performance.now(); 64 64 + const responseTimeMs = Math.round(endTime - startTime); 65 65 + 66 66 + return { 67 67 + healthy: true, 68 68 + connected: true, 69 69 + responseTimeMs, 70 70 + timestamp, 71 71 + }; 72 72 + } catch (error) { 73 73 + return { 74 74 + healthy: false, 75 75 + connected: true, 76 76 + error: error instanceof Error ? error.message : String(error), 77 77 + timestamp, 78 78 + }; 79 79 + } 80 80 + }

+30

client/index.ts

··· 1 1 + /** 2 2 + * Client module - MongoDB connection and session management 3 3 + * 4 4 + * This module provides all client-level functionality including: 5 5 + * - Connection management (connect, disconnect) 6 6 + * - Health monitoring (healthCheck) 7 7 + * - Transaction support (startSession, endSession, withTransaction) 8 8 + */ 9 9 + 10 10 + // Re-export connection management 11 11 + export { 12 12 + connect, 13 13 + disconnect, 14 14 + getDb, 15 15 + type ConnectOptions, 16 16 + type Connection, 17 17 + } from "./connection.ts"; 18 18 + 19 19 + // Re-export health monitoring 20 20 + export { 21 21 + healthCheck, 22 22 + type HealthCheckResult, 23 23 + } from "./health.ts"; 24 24 + 25 25 + // Re-export transaction management 26 26 + export { 27 27 + startSession, 28 28 + endSession, 29 29 + withTransaction, 30 30 + } from "./transactions.ts";

+83

client/transactions.ts

··· 1 1 + import type { ClientSession, TransactionOptions } from "mongodb"; 2 2 + import { getConnection } from "./connection.ts"; 3 3 + import { ConnectionError } from "../errors.ts"; 4 4 + 5 5 + /** 6 6 + * Transaction management module 7 7 + * 8 8 + * Provides session and transaction management functionality including 9 9 + * automatic transaction handling and manual session control. 10 10 + */ 11 11 + 12 12 + /** 13 13 + * Start a new client session for transactions 14 14 + * 15 15 + * Sessions must be ended when done using `endSession()` 16 16 + * 17 17 + * @returns New MongoDB ClientSession 18 18 + * @throws {ConnectionError} If not connected 19 19 + * 20 20 + * @example 21 21 + * ```ts 22 22 + * const session = startSession(); 23 23 + * try { 24 24 + * // use session 25 25 + * } finally { 26 26 + * await endSession(session); 27 27 + * } 28 28 + * ``` 29 29 + */ 30 30 + export function startSession(): ClientSession { 31 31 + const connection = getConnection(); 32 32 + if (!connection) { 33 33 + throw new ConnectionError("MongoDB not connected. Call connect() first."); 34 34 + } 35 35 + return connection.client.startSession(); 36 36 + } 37 37 + 38 38 + /** 39 39 + * End a client session 40 40 + * 41 41 + * @param session - The session to end 42 42 + */ 43 43 + export async function endSession(session: ClientSession): Promise<void> { 44 44 + await session.endSession(); 45 45 + } 46 46 + 47 47 + /** 48 48 + * Execute a function within a transaction 49 49 + * 50 50 + * Automatically handles session creation, transaction start/commit/abort, and cleanup. 51 51 + * If the callback throws an error, the transaction is automatically aborted. 52 52 + * 53 53 + * @param callback - Async function to execute within the transaction. Receives the session as parameter. 54 54 + * @param options - Optional transaction options (read/write concern, etc.) 55 55 + * @returns The result from the callback function 56 56 + * 57 57 + * @example 58 58 + * ```ts 59 59 + * const result = await withTransaction(async (session) => { 60 60 + * await UserModel.insertOne({ name: "Alice" }, { session }); 61 61 + * await OrderModel.insertOne({ userId: "123", total: 100 }, { session }); 62 62 + * return { success: true }; 63 63 + * }); 64 64 + * ``` 65 65 + */ 66 66 + export async function withTransaction<T>( 67 67 + callback: (session: ClientSession) => Promise<T>, 68 68 + options?: TransactionOptions 69 69 + ): Promise<T> { 70 70 + const session = startSession(); 71 71 + 72 72 + try { 73 73 + let result: T; 74 74 + 75 75 + await session.withTransaction(async () => { 76 76 + result = await callback(session); 77 77 + }, options); 78 78 + 79 79 + return result!; 80 80 + } finally { 81 81 + await endSession(session); 82 82 + } 83 83 + }

+3 -3

mod.ts

··· 1 1 - export { type InferModel, type Input } from "./schema.ts"; 1 1 + export type { Schema, Infer, Input } from "./types.ts"; 2 2 export { 3 3 connect, 4 4 disconnect, ··· 8 8 withTransaction, 9 9 type ConnectOptions, 10 10 type HealthCheckResult 11 11 - } from "./client.ts"; 12 12 - export { Model } from "./model.ts"; 11 11 + } from "./client/index.ts"; 12 12 + export { Model } from "./model/index.ts"; 13 13 export { 14 14 NozzleError, 15 15 ValidationError,

-350

model.ts

··· 1 1 - import type { z } from "@zod/zod"; 2 2 - import type { 3 3 - Collection, 4 4 - CreateIndexesOptions, 5 5 - DeleteResult, 6 6 - Document, 7 7 - DropIndexesOptions, 8 8 - Filter, 9 9 - IndexDescription, 10 10 - IndexSpecification, 11 11 - InsertManyResult, 12 12 - InsertOneResult, 13 13 - InsertOneOptions, 14 14 - FindOptions, 15 15 - UpdateOptions, 16 16 - ReplaceOptions, 17 17 - DeleteOptions, 18 18 - CountDocumentsOptions, 19 19 - AggregateOptions, 20 20 - ListIndexesOptions, 21 21 - OptionalUnlessRequiredId, 22 22 - UpdateResult, 23 23 - WithId, 24 24 - BulkWriteOptions, 25 25 - } from "mongodb"; 26 26 - import { ObjectId } from "mongodb"; 27 27 - import { getDb } from "./client.ts"; 28 28 - import { ValidationError, AsyncValidationError } from "./errors.ts"; 29 29 - 30 30 - // Type alias for cleaner code - Zod schema 31 31 - type Schema = z.ZodObject; 32 32 - type Infer<T extends Schema> = z.infer<T> & Document; 33 33 - type Input<T extends Schema> = z.input<T>; 34 34 - 35 35 - // Helper function to validate data using Zod 36 36 - function parse<T extends Schema>(schema: T, data: Input<T>): Infer<T> { 37 37 - const result = schema.safeParse(data); 38 38 - 39 39 - // Check for async validation 40 40 - if (result instanceof Promise) { 41 41 - throw new AsyncValidationError(); 42 42 - } 43 43 - 44 44 - if (!result.success) { 45 45 - throw new ValidationError(result.error.issues, "insert"); 46 46 - } 47 47 - return result.data as Infer<T>; 48 48 - } 49 49 - 50 50 - // Helper function to validate partial update data using Zod's partial() 51 51 - function parsePartial<T extends Schema>( 52 52 - schema: T, 53 53 - data: Partial<z.infer<T>>, 54 54 - ): Partial<z.infer<T>> { 55 55 - const result = schema.partial().safeParse(data); 56 56 - 57 57 - // Check for async validation 58 58 - if (result instanceof Promise) { 59 59 - throw new AsyncValidationError(); 60 60 - } 61 61 - 62 62 - if (!result.success) { 63 63 - throw new ValidationError(result.error.issues, "update"); 64 64 - } 65 65 - return result.data as Partial<z.infer<T>>; 66 66 - } 67 67 - 68 68 - // Helper function to validate replace data using Zod 69 69 - function parseReplace<T extends Schema>(schema: T, data: Input<T>): Infer<T> { 70 70 - const result = schema.safeParse(data); 71 71 - 72 72 - // Check for async validation 73 73 - if (result instanceof Promise) { 74 74 - throw new AsyncValidationError(); 75 75 - } 76 76 - 77 77 - if (!result.success) { 78 78 - throw new ValidationError(result.error.issues, "replace"); 79 79 - } 80 80 - return result.data as Infer<T>; 81 81 - } 82 82 - 83 83 - export class Model<T extends Schema> { 84 84 - private collection: Collection<Infer<T>>; 85 85 - private schema: T; 86 86 - 87 87 - constructor(collectionName: string, schema: T) { 88 88 - this.collection = getDb().collection<Infer<T>>(collectionName); 89 89 - this.schema = schema; 90 90 - } 91 91 - 92 92 - async insertOne( 93 93 - data: Input<T>, 94 94 - options?: InsertOneOptions 95 95 - ): Promise<InsertOneResult<Infer<T>>> { 96 96 - const validatedData = parse(this.schema, data); 97 97 - return await this.collection.insertOne( 98 98 - validatedData as OptionalUnlessRequiredId<Infer<T>>, 99 99 - options 100 100 - ); 101 101 - } 102 102 - 103 103 - async insertMany( 104 104 - data: Input<T>[], 105 105 - options?: BulkWriteOptions 106 106 - ): Promise<InsertManyResult<Infer<T>>> { 107 107 - const validatedData = data.map((item) => parse(this.schema, item)); 108 108 - return await this.collection.insertMany( 109 109 - validatedData as OptionalUnlessRequiredId<Infer<T>>[], 110 110 - options 111 111 - ); 112 112 - } 113 113 - 114 114 - async find( 115 115 - query: Filter<Infer<T>>, 116 116 - options?: FindOptions 117 117 - ): Promise<(WithId<Infer<T>>)[]> { 118 118 - return await this.collection.find(query, options).toArray(); 119 119 - } 120 120 - 121 121 - async findOne( 122 122 - query: Filter<Infer<T>>, 123 123 - options?: FindOptions 124 124 - ): Promise<WithId<Infer<T>> | null> { 125 125 - return await this.collection.findOne(query, options); 126 126 - } 127 127 - 128 128 - async findById( 129 129 - id: string | ObjectId, 130 130 - options?: FindOptions 131 131 - ): Promise<WithId<Infer<T>> | null> { 132 132 - const objectId = typeof id === "string" ? new ObjectId(id) : id; 133 133 - return await this.findOne({ _id: objectId } as Filter<Infer<T>>, options); 134 134 - } 135 135 - 136 136 - async update( 137 137 - query: Filter<Infer<T>>, 138 138 - data: Partial<z.infer<T>>, 139 139 - options?: UpdateOptions 140 140 - ): Promise<UpdateResult<Infer<T>>> { 141 141 - const validatedData = parsePartial(this.schema, data); 142 142 - return await this.collection.updateMany( 143 143 - query, 144 144 - { $set: validatedData as Partial<Infer<T>> }, 145 145 - options 146 146 - ); 147 147 - } 148 148 - 149 149 - async updateOne( 150 150 - query: Filter<Infer<T>>, 151 151 - data: Partial<z.infer<T>>, 152 152 - options?: UpdateOptions 153 153 - ): Promise<UpdateResult<Infer<T>>> { 154 154 - const validatedData = parsePartial(this.schema, data); 155 155 - return await this.collection.updateOne( 156 156 - query, 157 157 - { $set: validatedData as Partial<Infer<T>> }, 158 158 - options 159 159 - ); 160 160 - } 161 161 - 162 162 - async replaceOne( 163 163 - query: Filter<Infer<T>>, 164 164 - data: Input<T>, 165 165 - options?: ReplaceOptions 166 166 - ): Promise<UpdateResult<Infer<T>>> { 167 167 - const validatedData = parseReplace(this.schema, data); 168 168 - // Remove _id from validatedData for replaceOne (it will use the query's _id) 169 169 - const { _id, ...withoutId } = validatedData as Infer<T> & { _id?: unknown }; 170 170 - return await this.collection.replaceOne( 171 171 - query, 172 172 - withoutId as Infer<T>, 173 173 - options 174 174 - ); 175 175 - } 176 176 - 177 177 - async delete( 178 178 - query: Filter<Infer<T>>, 179 179 - options?: DeleteOptions 180 180 - ): Promise<DeleteResult> { 181 181 - return await this.collection.deleteMany(query, options); 182 182 - } 183 183 - 184 184 - async deleteOne( 185 185 - query: Filter<Infer<T>>, 186 186 - options?: DeleteOptions 187 187 - ): Promise<DeleteResult> { 188 188 - return await this.collection.deleteOne(query, options); 189 189 - } 190 190 - 191 191 - async count( 192 192 - query: Filter<Infer<T>>, 193 193 - options?: CountDocumentsOptions 194 194 - ): Promise<number> { 195 195 - return await this.collection.countDocuments(query, options); 196 196 - } 197 197 - 198 198 - async aggregate( 199 199 - pipeline: Document[], 200 200 - options?: AggregateOptions 201 201 - ): Promise<Document[]> { 202 202 - return await this.collection.aggregate(pipeline, options).toArray(); 203 203 - } 204 204 - 205 205 - // Pagination support for find 206 206 - async findPaginated( 207 207 - query: Filter<Infer<T>>, 208 208 - options: { skip?: number; limit?: number; sort?: Document } = {}, 209 209 - ): Promise<(WithId<Infer<T>>)[]> { 210 210 - return await this.collection 211 211 - .find(query) 212 212 - .skip(options.skip ?? 0) 213 213 - .limit(options.limit ?? 10) 214 214 - .sort(options.sort ?? {}) 215 215 - .toArray(); 216 216 - } 217 217 - 218 218 - // Index Management Methods 219 219 - 220 220 - /** 221 221 - * Create a single index on the collection 222 222 - * @param keys - Index specification (e.g., { email: 1 } or { name: "text" }) 223 223 - * @param options - Index creation options (unique, sparse, expireAfterSeconds, etc.) 224 224 - * @returns The name of the created index 225 225 - */ 226 226 - async createIndex( 227 227 - keys: IndexSpecification, 228 228 - options?: CreateIndexesOptions, 229 229 - ): Promise<string> { 230 230 - return await this.collection.createIndex(keys, options); 231 231 - } 232 232 - 233 233 - /** 234 234 - * Create multiple indexes on the collection 235 235 - * @param indexes - Array of index descriptions 236 236 - * @param options - Index creation options 237 237 - * @returns Array of index names created 238 238 - */ 239 239 - async createIndexes( 240 240 - indexes: IndexDescription[], 241 241 - options?: CreateIndexesOptions, 242 242 - ): Promise<string[]> { 243 243 - return await this.collection.createIndexes(indexes, options); 244 244 - } 245 245 - 246 246 - /** 247 247 - * Drop a single index from the collection 248 248 - * @param index - Index name or specification 249 249 - * @param options - Drop index options 250 250 - */ 251 251 - async dropIndex( 252 252 - index: string | IndexSpecification, 253 253 - options?: DropIndexesOptions, 254 254 - ): Promise<void> { 255 255 - // MongoDB driver accepts string or IndexSpecification 256 256 - await this.collection.dropIndex(index as string, options); 257 257 - } 258 258 - 259 259 - /** 260 260 - * Drop all indexes from the collection (except _id index) 261 261 - * @param options - Drop index options 262 262 - */ 263 263 - async dropIndexes(options?: DropIndexesOptions): Promise<void> { 264 264 - await this.collection.dropIndexes(options); 265 265 - } 266 266 - 267 267 - /** 268 268 - * List all indexes on the collection 269 269 - * @param options - List indexes options 270 270 - * @returns Array of index information 271 271 - */ 272 272 - async listIndexes( 273 273 - options?: ListIndexesOptions, 274 274 - ): Promise<IndexDescription[]> { 275 275 - const indexes = await this.collection.listIndexes(options).toArray(); 276 276 - return indexes as IndexDescription[]; 277 277 - } 278 278 - 279 279 - /** 280 280 - * Get index information by name 281 281 - * @param indexName - Name of the index 282 282 - * @returns Index description or null if not found 283 283 - */ 284 284 - async getIndex(indexName: string): Promise<IndexDescription | null> { 285 285 - const indexes = await this.listIndexes(); 286 286 - return indexes.find((idx) => idx.name === indexName) || null; 287 287 - } 288 288 - 289 289 - /** 290 290 - * Check if an index exists 291 291 - * @param indexName - Name of the index 292 292 - * @returns True if index exists, false otherwise 293 293 - */ 294 294 - async indexExists(indexName: string): Promise<boolean> { 295 295 - const index = await this.getIndex(indexName); 296 296 - return index !== null; 297 297 - } 298 298 - 299 299 - /** 300 300 - * Synchronize indexes - create indexes if they don't exist, update if they differ 301 301 - * This is useful for ensuring indexes match your schema definition 302 302 - * @param indexes - Array of index descriptions to synchronize 303 303 - * @param options - Options for index creation 304 304 - */ 305 305 - async syncIndexes( 306 306 - indexes: IndexDescription[], 307 307 - options?: CreateIndexesOptions, 308 308 - ): Promise<string[]> { 309 309 - const existingIndexes = await this.listIndexes(); 310 310 - 311 311 - const indexesToCreate: IndexDescription[] = []; 312 312 - 313 313 - for (const index of indexes) { 314 314 - const indexName = index.name || this._generateIndexName(index.key); 315 315 - const existingIndex = existingIndexes.find( 316 316 - (idx) => idx.name === indexName, 317 317 - ); 318 318 - 319 319 - if (!existingIndex) { 320 320 - indexesToCreate.push(index); 321 321 - } else if ( 322 322 - JSON.stringify(existingIndex.key) !== JSON.stringify(index.key) 323 323 - ) { 324 324 - // Index exists but keys differ - drop and recreate 325 325 - await this.dropIndex(indexName); 326 326 - indexesToCreate.push(index); 327 327 - } 328 328 - // If index exists and matches, skip it 329 329 - } 330 330 - 331 331 - const created: string[] = []; 332 332 - if (indexesToCreate.length > 0) { 333 333 - const names = await this.createIndexes(indexesToCreate, options); 334 334 - created.push(...names); 335 335 - } 336 336 - 337 337 - return created; 338 338 - } 339 339 - 340 340 - /** 341 341 - * Helper method to generate index name from key specification 342 342 - */ 343 343 - private _generateIndexName(keys: IndexSpecification): string { 344 344 - if (typeof keys === "string") { 345 345 - return keys; 346 346 - } 347 347 - const entries = Object.entries(keys as Record<string, number | string>); 348 348 - return entries.map(([field, direction]) => `${field}_${direction}`).join("_"); 349 349 - } 350 350 - }

+264

model/core.ts

··· 1 1 + import type { z } from "@zod/zod"; 2 2 + import type { 3 3 + Collection, 4 4 + DeleteResult, 5 5 + Document, 6 6 + Filter, 7 7 + InsertManyResult, 8 8 + InsertOneResult, 9 9 + InsertOneOptions, 10 10 + FindOptions, 11 11 + UpdateOptions, 12 12 + ReplaceOptions, 13 13 + DeleteOptions, 14 14 + CountDocumentsOptions, 15 15 + AggregateOptions, 16 16 + OptionalUnlessRequiredId, 17 17 + UpdateResult, 18 18 + WithId, 19 19 + BulkWriteOptions, 20 20 + } from "mongodb"; 21 21 + import { ObjectId } from "mongodb"; 22 22 + import type { Schema, Infer, Input } from "../types.ts"; 23 23 + import { parse, parsePartial, parseReplace } from "./validation.ts"; 24 24 + 25 25 + /** 26 26 + * Core CRUD operations for the Model class 27 27 + * 28 28 + * This module contains all basic create, read, update, and delete operations 29 29 + * with automatic Zod validation and transaction support. 30 30 + */ 31 31 + 32 32 + /** 33 33 + * Insert a single document into the collection 34 34 + * 35 35 + * @param collection - MongoDB collection 36 36 + * @param schema - Zod schema for validation 37 37 + * @param data - Document data to insert 38 38 + * @param options - Insert options (including session for transactions) 39 39 + * @returns Insert result with insertedId 40 40 + */ 41 41 + export async function insertOne<T extends Schema>( 42 42 + collection: Collection<Infer<T>>, 43 43 + schema: T, 44 44 + data: Input<T>, 45 45 + options?: InsertOneOptions 46 46 + ): Promise<InsertOneResult<Infer<T>>> { 47 47 + const validatedData = parse(schema, data); 48 48 + return await collection.insertOne( 49 49 + validatedData as OptionalUnlessRequiredId<Infer<T>>, 50 50 + options 51 51 + ); 52 52 + } 53 53 + 54 54 + /** 55 55 + * Insert multiple documents into the collection 56 56 + * 57 57 + * @param collection - MongoDB collection 58 58 + * @param schema - Zod schema for validation 59 59 + * @param data - Array of document data to insert 60 60 + * @param options - Insert options (including session for transactions) 61 61 + * @returns Insert result with insertedIds 62 62 + */ 63 63 + export async function insertMany<T extends Schema>( 64 64 + collection: Collection<Infer<T>>, 65 65 + schema: T, 66 66 + data: Input<T>[], 67 67 + options?: BulkWriteOptions 68 68 + ): Promise<InsertManyResult<Infer<T>>> { 69 69 + const validatedData = data.map((item) => parse(schema, item)); 70 70 + return await collection.insertMany( 71 71 + validatedData as OptionalUnlessRequiredId<Infer<T>>[], 72 72 + options 73 73 + ); 74 74 + } 75 75 + 76 76 + /** 77 77 + * Find multiple documents matching the query 78 78 + * 79 79 + * @param collection - MongoDB collection 80 80 + * @param query - MongoDB query filter 81 81 + * @param options - Find options (including session for transactions) 82 82 + * @returns Array of matching documents 83 83 + */ 84 84 + export async function find<T extends Schema>( 85 85 + collection: Collection<Infer<T>>, 86 86 + query: Filter<Infer<T>>, 87 87 + options?: FindOptions 88 88 + ): Promise<(WithId<Infer<T>>)[]> { 89 89 + return await collection.find(query, options).toArray(); 90 90 + } 91 91 + 92 92 + /** 93 93 + * Find a single document matching the query 94 94 + * 95 95 + * @param collection - MongoDB collection 96 96 + * @param query - MongoDB query filter 97 97 + * @param options - Find options (including session for transactions) 98 98 + * @returns Matching document or null if not found 99 99 + */ 100 100 + export async function findOne<T extends Schema>( 101 101 + collection: Collection<Infer<T>>, 102 102 + query: Filter<Infer<T>>, 103 103 + options?: FindOptions 104 104 + ): Promise<WithId<Infer<T>> | null> { 105 105 + return await collection.findOne(query, options); 106 106 + } 107 107 + 108 108 + /** 109 109 + * Find a document by its MongoDB ObjectId 110 110 + * 111 111 + * @param collection - MongoDB collection 112 112 + * @param id - Document ID (string or ObjectId) 113 113 + * @param options - Find options (including session for transactions) 114 114 + * @returns Matching document or null if not found 115 115 + */ 116 116 + export async function findById<T extends Schema>( 117 117 + collection: Collection<Infer<T>>, 118 118 + id: string | ObjectId, 119 119 + options?: FindOptions 120 120 + ): Promise<WithId<Infer<T>> | null> { 121 121 + const objectId = typeof id === "string" ? new ObjectId(id) : id; 122 122 + return await findOne(collection, { _id: objectId } as Filter<Infer<T>>, options); 123 123 + } 124 124 + 125 125 + /** 126 126 + * Update multiple documents matching the query 127 127 + * 128 128 + * @param collection - MongoDB collection 129 129 + * @param schema - Zod schema for validation 130 130 + * @param query - MongoDB query filter 131 131 + * @param data - Partial data to update 132 132 + * @param options - Update options (including session for transactions) 133 133 + * @returns Update result 134 134 + */ 135 135 + export async function update<T extends Schema>( 136 136 + collection: Collection<Infer<T>>, 137 137 + schema: T, 138 138 + query: Filter<Infer<T>>, 139 139 + data: Partial<z.infer<T>>, 140 140 + options?: UpdateOptions 141 141 + ): Promise<UpdateResult<Infer<T>>> { 142 142 + const validatedData = parsePartial(schema, data); 143 143 + return await collection.updateMany( 144 144 + query, 145 145 + { $set: validatedData as Partial<Infer<T>> }, 146 146 + options 147 147 + ); 148 148 + } 149 149 + 150 150 + /** 151 151 + * Update a single document matching the query 152 152 + * 153 153 + * @param collection - MongoDB collection 154 154 + * @param schema - Zod schema for validation 155 155 + * @param query - MongoDB query filter 156 156 + * @param data - Partial data to update 157 157 + * @param options - Update options (including session for transactions) 158 158 + * @returns Update result 159 159 + */ 160 160 + export async function updateOne<T extends Schema>( 161 161 + collection: Collection<Infer<T>>, 162 162 + schema: T, 163 163 + query: Filter<Infer<T>>, 164 164 + data: Partial<z.infer<T>>, 165 165 + options?: UpdateOptions 166 166 + ): Promise<UpdateResult<Infer<T>>> { 167 167 + const validatedData = parsePartial(schema, data); 168 168 + return await collection.updateOne( 169 169 + query, 170 170 + { $set: validatedData as Partial<Infer<T>> }, 171 171 + options 172 172 + ); 173 173 + } 174 174 + 175 175 + /** 176 176 + * Replace a single document matching the query 177 177 + * 178 178 + * @param collection - MongoDB collection 179 179 + * @param schema - Zod schema for validation 180 180 + * @param query - MongoDB query filter 181 181 + * @param data - Complete document data for replacement 182 182 + * @param options - Replace options (including session for transactions) 183 183 + * @returns Update result 184 184 + */ 185 185 + export async function replaceOne<T extends Schema>( 186 186 + collection: Collection<Infer<T>>, 187 187 + schema: T, 188 188 + query: Filter<Infer<T>>, 189 189 + data: Input<T>, 190 190 + options?: ReplaceOptions 191 191 + ): Promise<UpdateResult<Infer<T>>> { 192 192 + const validatedData = parseReplace(schema, data); 193 193 + // Remove _id from validatedData for replaceOne (it will use the query's _id) 194 194 + const { _id, ...withoutId } = validatedData as Infer<T> & { _id?: unknown }; 195 195 + return await collection.replaceOne( 196 196 + query, 197 197 + withoutId as Infer<T>, 198 198 + options 199 199 + ); 200 200 + } 201 201 + 202 202 + /** 203 203 + * Delete multiple documents matching the query 204 204 + * 205 205 + * @param collection - MongoDB collection 206 206 + * @param query - MongoDB query filter 207 207 + * @param options - Delete options (including session for transactions) 208 208 + * @returns Delete result 209 209 + */ 210 210 + export async function deleteMany<T extends Schema>( 211 211 + collection: Collection<Infer<T>>, 212 212 + query: Filter<Infer<T>>, 213 213 + options?: DeleteOptions 214 214 + ): Promise<DeleteResult> { 215 215 + return await collection.deleteMany(query, options); 216 216 + } 217 217 + 218 218 + /** 219 219 + * Delete a single document matching the query 220 220 + * 221 221 + * @param collection - MongoDB collection 222 222 + * @param query - MongoDB query filter 223 223 + * @param options - Delete options (including session for transactions) 224 224 + * @returns Delete result 225 225 + */ 226 226 + export async function deleteOne<T extends Schema>( 227 227 + collection: Collection<Infer<T>>, 228 228 + query: Filter<Infer<T>>, 229 229 + options?: DeleteOptions 230 230 + ): Promise<DeleteResult> { 231 231 + return await collection.deleteOne(query, options); 232 232 + } 233 233 + 234 234 + /** 235 235 + * Count documents matching the query 236 236 + * 237 237 + * @param collection - MongoDB collection 238 238 + * @param query - MongoDB query filter 239 239 + * @param options - Count options (including session for transactions) 240 240 + * @returns Number of matching documents 241 241 + */ 242 242 + export async function count<T extends Schema>( 243 243 + collection: Collection<Infer<T>>, 244 244 + query: Filter<Infer<T>>, 245 245 + options?: CountDocumentsOptions 246 246 + ): Promise<number> { 247 247 + return await collection.countDocuments(query, options); 248 248 + } 249 249 + 250 250 + /** 251 251 + * Execute an aggregation pipeline 252 252 + * 253 253 + * @param collection - MongoDB collection 254 254 + * @param pipeline - MongoDB aggregation pipeline 255 255 + * @param options - Aggregate options (including session for transactions) 256 256 + * @returns Array of aggregation results 257 257 + */ 258 258 + export async function aggregate<T extends Schema>( 259 259 + collection: Collection<Infer<T>>, 260 260 + pipeline: Document[], 261 261 + options?: AggregateOptions 262 262 + ): Promise<Document[]> { 263 263 + return await collection.aggregate(pipeline, options).toArray(); 264 264 + }

+355

model/index.ts

··· 1 1 + import type { z } from "@zod/zod"; 2 2 + import type { 3 3 + Collection, 4 4 + CreateIndexesOptions, 5 5 + DeleteResult, 6 6 + Document, 7 7 + DropIndexesOptions, 8 8 + Filter, 9 9 + IndexDescription, 10 10 + IndexSpecification, 11 11 + InsertManyResult, 12 12 + InsertOneResult, 13 13 + InsertOneOptions, 14 14 + FindOptions, 15 15 + UpdateOptions, 16 16 + ReplaceOptions, 17 17 + DeleteOptions, 18 18 + CountDocumentsOptions, 19 19 + AggregateOptions, 20 20 + ListIndexesOptions, 21 21 + UpdateResult, 22 22 + WithId, 23 23 + BulkWriteOptions, 24 24 + } from "mongodb"; 25 25 + import type { ObjectId } from "mongodb"; 26 26 + import { getDb } from "../client/connection.ts"; 27 27 + import type { Schema, Infer, Input } from "../types.ts"; 28 28 + import * as core from "./core.ts"; 29 29 + import * as indexes from "./indexes.ts"; 30 30 + import * as pagination from "./pagination.ts"; 31 31 + 32 32 + /** 33 33 + * Model class for type-safe MongoDB operations 34 34 + * 35 35 + * Provides a clean API for CRUD operations, pagination, and index management 36 36 + * with automatic Zod validation and TypeScript type safety. 37 37 + * 38 38 + * @example 39 39 + * ```ts 40 40 + * const userSchema = z.object({ 41 41 + * name: z.string(), 42 42 + * email: z.string().email(), 43 43 + * }); 44 44 + * 45 45 + * const UserModel = new Model("users", userSchema); 46 46 + * await UserModel.insertOne({ name: "Alice", email: "alice@example.com" }); 47 47 + * ``` 48 48 + */ 49 49 + export class Model<T extends Schema> { 50 50 + private collection: Collection<Infer<T>>; 51 51 + private schema: T; 52 52 + 53 53 + constructor(collectionName: string, schema: T) { 54 54 + this.collection = getDb().collection<Infer<T>>(collectionName); 55 55 + this.schema = schema; 56 56 + } 57 57 + 58 58 + // ============================================================================ 59 59 + // CRUD Operations (delegated to core.ts) 60 60 + // ============================================================================ 61 61 + 62 62 + /** 63 63 + * Insert a single document into the collection 64 64 + * 65 65 + * @param data - Document data to insert 66 66 + * @param options - Insert options (including session for transactions) 67 67 + * @returns Insert result with insertedId 68 68 + */ 69 69 + async insertOne( 70 70 + data: Input<T>, 71 71 + options?: InsertOneOptions 72 72 + ): Promise<InsertOneResult<Infer<T>>> { 73 73 + return await core.insertOne(this.collection, this.schema, data, options); 74 74 + } 75 75 + 76 76 + /** 77 77 + * Insert multiple documents into the collection 78 78 + * 79 79 + * @param data - Array of document data to insert 80 80 + * @param options - Insert options (including session for transactions) 81 81 + * @returns Insert result with insertedIds 82 82 + */ 83 83 + async insertMany( 84 84 + data: Input<T>[], 85 85 + options?: BulkWriteOptions 86 86 + ): Promise<InsertManyResult<Infer<T>>> { 87 87 + return await core.insertMany(this.collection, this.schema, data, options); 88 88 + } 89 89 + 90 90 + /** 91 91 + * Find multiple documents matching the query 92 92 + * 93 93 + * @param query - MongoDB query filter 94 94 + * @param options - Find options (including session for transactions) 95 95 + * @returns Array of matching documents 96 96 + */ 97 97 + async find( 98 98 + query: Filter<Infer<T>>, 99 99 + options?: FindOptions 100 100 + ): Promise<(WithId<Infer<T>>)[]> { 101 101 + return await core.find(this.collection, query, options); 102 102 + } 103 103 + 104 104 + /** 105 105 + * Find a single document matching the query 106 106 + * 107 107 + * @param query - MongoDB query filter 108 108 + * @param options - Find options (including session for transactions) 109 109 + * @returns Matching document or null if not found 110 110 + */ 111 111 + async findOne( 112 112 + query: Filter<Infer<T>>, 113 113 + options?: FindOptions 114 114 + ): Promise<WithId<Infer<T>> | null> { 115 115 + return await core.findOne(this.collection, query, options); 116 116 + } 117 117 + 118 118 + /** 119 119 + * Find a document by its MongoDB ObjectId 120 120 + * 121 121 + * @param id - Document ID (string or ObjectId) 122 122 + * @param options - Find options (including session for transactions) 123 123 + * @returns Matching document or null if not found 124 124 + */ 125 125 + async findById( 126 126 + id: string | ObjectId, 127 127 + options?: FindOptions 128 128 + ): Promise<WithId<Infer<T>> | null> { 129 129 + return await core.findById(this.collection, id, options); 130 130 + } 131 131 + 132 132 + /** 133 133 + * Update multiple documents matching the query 134 134 + * 135 135 + * @param query - MongoDB query filter 136 136 + * @param data - Partial data to update 137 137 + * @param options - Update options (including session for transactions) 138 138 + * @returns Update result 139 139 + */ 140 140 + async update( 141 141 + query: Filter<Infer<T>>, 142 142 + data: Partial<z.infer<T>>, 143 143 + options?: UpdateOptions 144 144 + ): Promise<UpdateResult<Infer<T>>> { 145 145 + return await core.update(this.collection, this.schema, query, data, options); 146 146 + } 147 147 + 148 148 + /** 149 149 + * Update a single document matching the query 150 150 + * 151 151 + * @param query - MongoDB query filter 152 152 + * @param data - Partial data to update 153 153 + * @param options - Update options (including session for transactions) 154 154 + * @returns Update result 155 155 + */ 156 156 + async updateOne( 157 157 + query: Filter<Infer<T>>, 158 158 + data: Partial<z.infer<T>>, 159 159 + options?: UpdateOptions 160 160 + ): Promise<UpdateResult<Infer<T>>> { 161 161 + return await core.updateOne(this.collection, this.schema, query, data, options); 162 162 + } 163 163 + 164 164 + /** 165 165 + * Replace a single document matching the query 166 166 + * 167 167 + * @param query - MongoDB query filter 168 168 + * @param data - Complete document data for replacement 169 169 + * @param options - Replace options (including session for transactions) 170 170 + * @returns Update result 171 171 + */ 172 172 + async replaceOne( 173 173 + query: Filter<Infer<T>>, 174 174 + data: Input<T>, 175 175 + options?: ReplaceOptions 176 176 + ): Promise<UpdateResult<Infer<T>>> { 177 177 + return await core.replaceOne(this.collection, this.schema, query, data, options); 178 178 + } 179 179 + 180 180 + /** 181 181 + * Delete multiple documents matching the query 182 182 + * 183 183 + * @param query - MongoDB query filter 184 184 + * @param options - Delete options (including session for transactions) 185 185 + * @returns Delete result 186 186 + */ 187 187 + async delete( 188 188 + query: Filter<Infer<T>>, 189 189 + options?: DeleteOptions 190 190 + ): Promise<DeleteResult> { 191 191 + return await core.deleteMany(this.collection, query, options); 192 192 + } 193 193 + 194 194 + /** 195 195 + * Delete a single document matching the query 196 196 + * 197 197 + * @param query - MongoDB query filter 198 198 + * @param options - Delete options (including session for transactions) 199 199 + * @returns Delete result 200 200 + */ 201 201 + async deleteOne( 202 202 + query: Filter<Infer<T>>, 203 203 + options?: DeleteOptions 204 204 + ): Promise<DeleteResult> { 205 205 + return await core.deleteOne(this.collection, query, options); 206 206 + } 207 207 + 208 208 + /** 209 209 + * Count documents matching the query 210 210 + * 211 211 + * @param query - MongoDB query filter 212 212 + * @param options - Count options (including session for transactions) 213 213 + * @returns Number of matching documents 214 214 + */ 215 215 + async count( 216 216 + query: Filter<Infer<T>>, 217 217 + options?: CountDocumentsOptions 218 218 + ): Promise<number> { 219 219 + return await core.count(this.collection, query, options); 220 220 + } 221 221 + 222 222 + /** 223 223 + * Execute an aggregation pipeline 224 224 + * 225 225 + * @param pipeline - MongoDB aggregation pipeline 226 226 + * @param options - Aggregate options (including session for transactions) 227 227 + * @returns Array of aggregation results 228 228 + */ 229 229 + async aggregate( 230 230 + pipeline: Document[], 231 231 + options?: AggregateOptions 232 232 + ): Promise<Document[]> { 233 233 + return await core.aggregate(this.collection, pipeline, options); 234 234 + } 235 235 + 236 236 + // ============================================================================ 237 237 + // Pagination (delegated to pagination.ts) 238 238 + // ============================================================================ 239 239 + 240 240 + /** 241 241 + * Find documents with pagination support 242 242 + * 243 243 + * @param query - MongoDB query filter 244 244 + * @param options - Pagination options (skip, limit, sort) 245 245 + * @returns Array of matching documents 246 246 + */ 247 247 + async findPaginated( 248 248 + query: Filter<Infer<T>>, 249 249 + options: { skip?: number; limit?: number; sort?: Document } = {}, 250 250 + ): Promise<(WithId<Infer<T>>)[]> { 251 251 + return await pagination.findPaginated(this.collection, query, options); 252 252 + } 253 253 + 254 254 + // ============================================================================ 255 255 + // Index Management (delegated to indexes.ts) 256 256 + // ============================================================================ 257 257 + 258 258 + /** 259 259 + * Create a single index on the collection 260 260 + * 261 261 + * @param keys - Index specification (e.g., { email: 1 } or { name: "text" }) 262 262 + * @param options - Index creation options (unique, sparse, expireAfterSeconds, etc.) 263 263 + * @returns The name of the created index 264 264 + */ 265 265 + async createIndex( 266 266 + keys: IndexSpecification, 267 267 + options?: CreateIndexesOptions, 268 268 + ): Promise<string> { 269 269 + return await indexes.createIndex(this.collection, keys, options); 270 270 + } 271 271 + 272 272 + /** 273 273 + * Create multiple indexes on the collection 274 274 + * 275 275 + * @param indexes - Array of index descriptions 276 276 + * @param options - Index creation options 277 277 + * @returns Array of index names created 278 278 + */ 279 279 + async createIndexes( 280 280 + indexList: IndexDescription[], 281 281 + options?: CreateIndexesOptions, 282 282 + ): Promise<string[]> { 283 283 + return await indexes.createIndexes(this.collection, indexList, options); 284 284 + } 285 285 + 286 286 + /** 287 287 + * Drop a single index from the collection 288 288 + * 289 289 + * @param index - Index name or specification 290 290 + * @param options - Drop index options 291 291 + */ 292 292 + async dropIndex( 293 293 + index: string | IndexSpecification, 294 294 + options?: DropIndexesOptions, 295 295 + ): Promise<void> { 296 296 + return await indexes.dropIndex(this.collection, index, options); 297 297 + } 298 298 + 299 299 + /** 300 300 + * Drop all indexes from the collection (except _id index) 301 301 + * 302 302 + * @param options - Drop index options 303 303 + */ 304 304 + async dropIndexes(options?: DropIndexesOptions): Promise<void> { 305 305 + return await indexes.dropIndexes(this.collection, options); 306 306 + } 307 307 + 308 308 + /** 309 309 + * List all indexes on the collection 310 310 + * 311 311 + * @param options - List indexes options 312 312 + * @returns Array of index information 313 313 + */ 314 314 + async listIndexes( 315 315 + options?: ListIndexesOptions, 316 316 + ): Promise<IndexDescription[]> { 317 317 + return await indexes.listIndexes(this.collection, options); 318 318 + } 319 319 + 320 320 + /** 321 321 + * Get index information by name 322 322 + * 323 323 + * @param indexName - Name of the index 324 324 + * @returns Index description or null if not found 325 325 + */ 326 326 + async getIndex(indexName: string): Promise<IndexDescription | null> { 327 327 + return await indexes.getIndex(this.collection, indexName); 328 328 + } 329 329 + 330 330 + /** 331 331 + * Check if an index exists 332 332 + * 333 333 + * @param indexName - Name of the index 334 334 + * @returns True if index exists, false otherwise 335 335 + */ 336 336 + async indexExists(indexName: string): Promise<boolean> { 337 337 + return await indexes.indexExists(this.collection, indexName); 338 338 + } 339 339 + 340 340 + /** 341 341 + * Synchronize indexes - create indexes if they don't exist, update if they differ 342 342 + * 343 343 + * This is useful for ensuring indexes match your schema definition 344 344 + * 345 345 + * @param indexes - Array of index descriptions to synchronize 346 346 + * @param options - Options for index creation 347 347 + * @returns Array of index names that were created 348 348 + */ 349 349 + async syncIndexes( 350 350 + indexList: IndexDescription[], 351 351 + options?: CreateIndexesOptions, 352 352 + ): Promise<string[]> { 353 353 + return await indexes.syncIndexes(this.collection, indexList, options); 354 354 + } 355 355 + }

+180

model/indexes.ts

··· 1 1 + import type { 2 2 + Collection, 3 3 + CreateIndexesOptions, 4 4 + DropIndexesOptions, 5 5 + IndexDescription, 6 6 + IndexSpecification, 7 7 + ListIndexesOptions, 8 8 + } from "mongodb"; 9 9 + import type { Schema, Infer } from "../types.ts"; 10 10 + 11 11 + /** 12 12 + * Index management operations for the Model class 13 13 + * 14 14 + * This module contains all index-related operations including creation, 15 15 + * deletion, listing, and synchronization of indexes. 16 16 + */ 17 17 + 18 18 + /** 19 19 + * Create a single index on the collection 20 20 + * 21 21 + * @param collection - MongoDB collection 22 22 + * @param keys - Index specification (e.g., { email: 1 } or { name: "text" }) 23 23 + * @param options - Index creation options (unique, sparse, expireAfterSeconds, etc.) 24 24 + * @returns The name of the created index 25 25 + */ 26 26 + export async function createIndex<T extends Schema>( 27 27 + collection: Collection<Infer<T>>, 28 28 + keys: IndexSpecification, 29 29 + options?: CreateIndexesOptions, 30 30 + ): Promise<string> { 31 31 + return await collection.createIndex(keys, options); 32 32 + } 33 33 + 34 34 + /** 35 35 + * Create multiple indexes on the collection 36 36 + * 37 37 + * @param collection - MongoDB collection 38 38 + * @param indexes - Array of index descriptions 39 39 + * @param options - Index creation options 40 40 + * @returns Array of index names created 41 41 + */ 42 42 + export async function createIndexes<T extends Schema>( 43 43 + collection: Collection<Infer<T>>, 44 44 + indexes: IndexDescription[], 45 45 + options?: CreateIndexesOptions, 46 46 + ): Promise<string[]> { 47 47 + return await collection.createIndexes(indexes, options); 48 48 + } 49 49 + 50 50 + /** 51 51 + * Drop a single index from the collection 52 52 + * 53 53 + * @param collection - MongoDB collection 54 54 + * @param index - Index name or specification 55 55 + * @param options - Drop index options 56 56 + */ 57 57 + export async function dropIndex<T extends Schema>( 58 58 + collection: Collection<Infer<T>>, 59 59 + index: string | IndexSpecification, 60 60 + options?: DropIndexesOptions, 61 61 + ): Promise<void> { 62 62 + await collection.dropIndex(index as string, options); 63 63 + } 64 64 + 65 65 + /** 66 66 + * Drop all indexes from the collection (except _id index) 67 67 + * 68 68 + * @param collection - MongoDB collection 69 69 + * @param options - Drop index options 70 70 + */ 71 71 + export async function dropIndexes<T extends Schema>( 72 72 + collection: Collection<Infer<T>>, 73 73 + options?: DropIndexesOptions 74 74 + ): Promise<void> { 75 75 + await collection.dropIndexes(options); 76 76 + } 77 77 + 78 78 + /** 79 79 + * List all indexes on the collection 80 80 + * 81 81 + * @param collection - MongoDB collection 82 82 + * @param options - List indexes options 83 83 + * @returns Array of index information 84 84 + */ 85 85 + export async function listIndexes<T extends Schema>( 86 86 + collection: Collection<Infer<T>>, 87 87 + options?: ListIndexesOptions, 88 88 + ): Promise<IndexDescription[]> { 89 89 + const indexes = await collection.listIndexes(options).toArray(); 90 90 + return indexes as IndexDescription[]; 91 91 + } 92 92 + 93 93 + /** 94 94 + * Get index information by name 95 95 + * 96 96 + * @param collection - MongoDB collection 97 97 + * @param indexName - Name of the index 98 98 + * @returns Index description or null if not found 99 99 + */ 100 100 + export async function getIndex<T extends Schema>( 101 101 + collection: Collection<Infer<T>>, 102 102 + indexName: string 103 103 + ): Promise<IndexDescription | null> { 104 104 + const indexes = await listIndexes(collection); 105 105 + return indexes.find((idx) => idx.name === indexName) || null; 106 106 + } 107 107 + 108 108 + /** 109 109 + * Check if an index exists 110 110 + * 111 111 + * @param collection - MongoDB collection 112 112 + * @param indexName - Name of the index 113 113 + * @returns True if index exists, false otherwise 114 114 + */ 115 115 + export async function indexExists<T extends Schema>( 116 116 + collection: Collection<Infer<T>>, 117 117 + indexName: string 118 118 + ): Promise<boolean> { 119 119 + const index = await getIndex(collection, indexName); 120 120 + return index !== null; 121 121 + } 122 122 + 123 123 + /** 124 124 + * Synchronize indexes - create indexes if they don't exist, update if they differ 125 125 + * 126 126 + * This is useful for ensuring indexes match your schema definition 127 127 + * 128 128 + * @param collection - MongoDB collection 129 129 + * @param indexes - Array of index descriptions to synchronize 130 130 + * @param options - Options for index creation 131 131 + * @returns Array of index names that were created 132 132 + */ 133 133 + export async function syncIndexes<T extends Schema>( 134 134 + collection: Collection<Infer<T>>, 135 135 + indexes: IndexDescription[], 136 136 + options?: CreateIndexesOptions, 137 137 + ): Promise<string[]> { 138 138 + const existingIndexes = await listIndexes(collection); 139 139 + const indexesToCreate: IndexDescription[] = []; 140 140 + 141 141 + for (const index of indexes) { 142 142 + const indexName = index.name || generateIndexName(index.key); 143 143 + const existingIndex = existingIndexes.find( 144 144 + (idx) => idx.name === indexName, 145 145 + ); 146 146 + 147 147 + if (!existingIndex) { 148 148 + indexesToCreate.push(index); 149 149 + } else if ( 150 150 + JSON.stringify(existingIndex.key) !== JSON.stringify(index.key) 151 151 + ) { 152 152 + // Index exists but keys differ - drop and recreate 153 153 + await dropIndex(collection, indexName); 154 154 + indexesToCreate.push(index); 155 155 + } 156 156 + // If index exists and matches, skip it 157 157 + } 158 158 + 159 159 + const created: string[] = []; 160 160 + if (indexesToCreate.length > 0) { 161 161 + const names = await createIndexes(collection, indexesToCreate, options); 162 162 + created.push(...names); 163 163 + } 164 164 + 165 165 + return created; 166 166 + } 167 167 + 168 168 + /** 169 169 + * Generate index name from key specification 170 170 + * 171 171 + * @param keys - Index specification 172 172 + * @returns Generated index name 173 173 + */ 174 174 + export function generateIndexName(keys: IndexSpecification): string { 175 175 + if (typeof keys === "string") { 176 176 + return keys; 177 177 + } 178 178 + const entries = Object.entries(keys as Record<string, number | string>); 179 179 + return entries.map(([field, direction]) => `${field}_${direction}`).join("_"); 180 180 + }

+43

model/pagination.ts

··· 1 1 + import type { 2 2 + Collection, 3 3 + Document, 4 4 + Filter, 5 5 + WithId, 6 6 + } from "mongodb"; 7 7 + import type { Schema, Infer } from "../types.ts"; 8 8 + 9 9 + /** 10 10 + * Pagination operations for the Model class 11 11 + * 12 12 + * This module contains pagination-related functionality for finding documents 13 13 + * with skip, limit, and sort options. 14 14 + */ 15 15 + 16 16 + /** 17 17 + * Find documents with pagination support 18 18 + * 19 19 + * @param collection - MongoDB collection 20 20 + * @param query - MongoDB query filter 21 21 + * @param options - Pagination options (skip, limit, sort) 22 22 + * @returns Array of matching documents 23 23 + * 24 24 + * @example 25 25 + * ```ts 26 26 + * const users = await findPaginated(collection, 27 27 + * { age: { $gte: 18 } }, 28 28 + * { skip: 0, limit: 10, sort: { createdAt: -1 } } 29 29 + * ); 30 30 + * ``` 31 31 + */ 32 32 + export async function findPaginated<T extends Schema>( 33 33 + collection: Collection<Infer<T>>, 34 34 + query: Filter<Infer<T>>, 35 35 + options: { skip?: number; limit?: number; sort?: Document } = {}, 36 36 + ): Promise<(WithId<Infer<T>>)[]> { 37 37 + return await collection 38 38 + .find(query) 39 39 + .skip(options.skip ?? 0) 40 40 + .limit(options.limit ?? 10) 41 41 + .sort(options.sort ?? {}) 42 42 + .toArray(); 43 43 + }

+75

model/validation.ts

··· 1 1 + import type { z } from "@zod/zod"; 2 2 + import type { Schema, Infer, Input } from "../types.ts"; 3 3 + import { ValidationError, AsyncValidationError } from "../errors.ts"; 4 4 + 5 5 + /** 6 6 + * Validate data for insert operations using Zod schema 7 7 + * 8 8 + * @param schema - Zod schema to validate against 9 9 + * @param data - Data to validate 10 10 + * @returns Validated and typed data 11 11 + * @throws {ValidationError} If validation fails 12 12 + * @throws {AsyncValidationError} If async validation is detected 13 13 + */ 14 14 + export function parse<T extends Schema>(schema: T, data: Input<T>): Infer<T> { 15 15 + const result = schema.safeParse(data); 16 16 + 17 17 + // Check for async validation 18 18 + if (result instanceof Promise) { 19 19 + throw new AsyncValidationError(); 20 20 + } 21 21 + 22 22 + if (!result.success) { 23 23 + throw new ValidationError(result.error.issues, "insert"); 24 24 + } 25 25 + return result.data as Infer<T>; 26 26 + } 27 27 + 28 28 + /** 29 29 + * Validate partial data for update operations using Zod schema 30 30 + * 31 31 + * @param schema - Zod schema to validate against 32 32 + * @param data - Partial data to validate 33 33 + * @returns Validated and typed partial data 34 34 + * @throws {ValidationError} If validation fails 35 35 + * @throws {AsyncValidationError} If async validation is detected 36 36 + */ 37 37 + export function parsePartial<T extends Schema>( 38 38 + schema: T, 39 39 + data: Partial<z.infer<T>>, 40 40 + ): Partial<z.infer<T>> { 41 41 + const result = schema.partial().safeParse(data); 42 42 + 43 43 + // Check for async validation 44 44 + if (result instanceof Promise) { 45 45 + throw new AsyncValidationError(); 46 46 + } 47 47 + 48 48 + if (!result.success) { 49 49 + throw new ValidationError(result.error.issues, "update"); 50 50 + } 51 51 + return result.data as Partial<z.infer<T>>; 52 52 + } 53 53 + 54 54 + /** 55 55 + * Validate data for replace operations using Zod schema 56 56 + * 57 57 + * @param schema - Zod schema to validate against 58 58 + * @param data - Data to validate 59 59 + * @returns Validated and typed data 60 60 + * @throws {ValidationError} If validation fails 61 61 + * @throws {AsyncValidationError} If async validation is detected 62 62 + */ 63 63 + export function parseReplace<T extends Schema>(schema: T, data: Input<T>): Infer<T> { 64 64 + const result = schema.safeParse(data); 65 65 + 66 66 + // Check for async validation 67 67 + if (result instanceof Promise) { 68 68 + throw new AsyncValidationError(); 69 69 + } 70 70 + 71 71 + if (!result.success) { 72 72 + throw new ValidationError(result.error.issues, "replace"); 73 73 + } 74 74 + return result.data as Infer<T>; 75 75 + }

-11

schema.ts

··· 1 1 - import type { z } from "@zod/zod"; 2 2 - import type { ObjectId } from "mongodb"; 3 3 - 4 4 - type Schema = z.ZodObject; 5 5 - type Infer<T extends Schema> = z.infer<T>; 6 6 - 7 7 - export type InferModel<T extends Schema> = Infer<T> & { 8 8 - _id?: ObjectId; 9 9 - }; 10 10 - 11 11 - export type Input<T extends Schema> = z.input<T>;

+6 -6

tests/errors_test.ts

··· 46 46 47 47 await assertRejects( 48 48 async () => { 49 49 - await UserModel.insertOne({ name: "", email: "invalid" } as any); 49 49 + await UserModel.insertOne({ name: "", email: "invalid" }); 50 50 }, 51 51 ValidationError, 52 52 "Validation failed on insert" ··· 65 65 const UserModel = new Model("users", userSchema); 66 66 67 67 try { 68 68 - await UserModel.insertOne({ name: "", email: "invalid" } as any); 68 68 + await UserModel.insertOne({ name: "", email: "invalid" }); 69 69 throw new Error("Should have thrown ValidationError"); 70 70 } catch (error) { 71 71 assert(error instanceof ValidationError); ··· 116 116 117 117 await assertRejects( 118 118 async () => { 119 119 - await UserModel.replaceOne({ name: "Test" }, { name: "", email: "invalid" } as any); 119 119 + await UserModel.replaceOne({ name: "Test" }, { name: "", email: "invalid" }); 120 120 }, 121 121 ValidationError, 122 122 "Validation failed on replace" ··· 191 191 // Make sure not connected 192 192 await disconnect(); 193 193 194 194 - const { getDb } = await import("../client.ts"); 194 194 + const { getDb } = await import("../client/connection.ts"); 195 195 196 196 try { 197 197 getDb(); ··· 218 218 name: "", 219 219 email: "not-an-email", 220 220 age: -10, 221 221 - } as any); 221 221 + }); 222 222 throw new Error("Should have thrown ValidationError"); 223 223 } catch (error) { 224 224 assert(error instanceof ValidationError); ··· 249 249 const UserModel = new Model("users", userSchema); 250 250 251 251 try { 252 252 - await UserModel.insertOne({ name: "", email: "invalid" } as any); 252 252 + await UserModel.insertOne({ name: "", email: "invalid" }); 253 253 } catch (error) { 254 254 assert(error instanceof ValidationError); 255 255 assertEquals(error.name, "ValidationError");

+1 -1

tests/transactions_test.ts

··· 28 28 // Clean up database 29 29 if (replSet) { 30 30 try { 31 31 - const { getDb } = await import("../client.ts"); 31 31 + const { getDb } = await import("../client/connection.ts"); 32 32 const db = getDb(); 33 33 await db.dropDatabase(); 34 34 } catch {

+25

types.ts

··· 1 1 + import type { z } from "@zod/zod"; 2 2 + import type { Document, ObjectId } from "mongodb"; 3 3 + 4 4 + /** 5 5 + * Type alias for Zod schema objects 6 6 + */ 7 7 + export type Schema = z.ZodObject<z.ZodRawShape>; 8 8 + 9 9 + /** 10 10 + * Infer the TypeScript type from a Zod schema, including MongoDB Document 11 11 + */ 12 12 + export type Infer<T extends Schema> = z.infer<T> & Document; 13 13 + 14 14 + 15 15 + /** 16 16 + * Infer the model type from a Zod schema, including MongoDB Document and ObjectId 17 17 + */ 18 18 + export type InferModel<T extends Schema> = Infer<T> & { 19 19 + _id?: ObjectId; 20 20 + }; 21 21 + 22 22 + /** 23 23 + * Infer the input type for a Zod schema (handles defaults) 24 24 + */ 25 25 + export type Input<T extends Schema> = z.input<T>;