UNPKG

edgevector-db-sdk

Version:

Official TypeScript/JavaScript SDK for EdgeVector DB - A globally distributed, edge-native database platform combining document storage, vector search, time series, and real-time streaming

473 lines 13.4 kB
/** * Collection class with MongoDB-compatible API */ import { EventEmitter } from 'eventemitter3'; import { HttpClient } from './http-client'; import { QueryBuilder } from './query-builder'; import { VectorOperations } from './vector-operations'; import { TimeSeriesOperations } from './timeseries-operations'; import { EdgeVectorConfig, MongoFilter, MongoUpdateOperators, FindOptions, InsertResult, InsertManyResult, UpdateResult, DeleteResult, BulkWriteResult, BulkWriteOperation, Document, WithId, OptionalId, CollectionStats, IndexSpec, IndexOptions, IndexInfo, ChangeEvent, SubscriptionOptions, Subscription } from '../types'; /** * Collection class providing MongoDB-compatible operations * * @example * ```typescript * const users = db.collection('users'); * * // Insert documents * await users.insertOne({ name: 'John', email: 'john@example.com' }); * * // Find documents * const results = await users.find({ age: { $gte: 18 } }).toArray(); * * // Update documents * await users.updateMany({ status: 'pending' }, { $set: { status: 'active' } }); * ``` */ export declare class Collection<TSchema extends Document = Document> extends EventEmitter { private httpClient; private config; private databaseName; private collectionName; private baseUrl; private _vectors?; private _timeseries?; private _realtime?; constructor(databaseName: string, collectionName: string, httpClient: HttpClient, config: EdgeVectorConfig); /** * Insert a single document * * @param document - Document to insert * @returns Insert result with generated ID * * @example * ```typescript * const result = await users.insertOne({ * name: 'Alice', * email: 'alice@example.com', * age: 25 * }); * console.log('Inserted ID:', result.insertedId); * ``` */ insertOne(document: OptionalId<TSchema>): Promise<InsertResult>; /** * Insert multiple documents * * @param documents - Array of documents to insert * @param options - Insert options * @returns Insert result with generated IDs * * @example * ```typescript * const result = await users.insertMany([ * { name: 'Bob', email: 'bob@example.com' }, * { name: 'Carol', email: 'carol@example.com' } * ]); * console.log('Inserted count:', result.insertedCount); * ``` */ insertMany(documents: OptionalId<TSchema>[], options?: { ordered?: boolean; }): Promise<InsertManyResult>; /** * Find documents matching a filter * * @param filter - Query filter * @param options - Find options * @returns Query builder for chaining * * @example * ```typescript * // Find all adult users * const adults = await users.find({ age: { $gte: 18 } }).toArray(); * * // Find with pagination and sorting * const recent = await users * .find({ status: 'active' }) * .sort({ createdAt: -1 }) * .limit(10) * .toArray(); * ``` */ find(filter?: MongoFilter<TSchema>, options?: FindOptions): QueryBuilder<TSchema>; /** * Find a single document * * @param filter - Query filter * @param options - Find options * @returns Single document or null * * @example * ```typescript * const user = await users.findOne({ email: 'john@example.com' }); * if (user) { * console.log('Found user:', user.name); * } * ``` */ findOne(filter?: MongoFilter<TSchema>, options?: FindOptions): Promise<WithId<TSchema> | null>; /** * Find a document by ID * * @param id - Document ID * @param options - Find options * @returns Document or null * * @example * ```typescript * const user = await users.findById('user_123'); * ``` */ findById(id: string, options?: FindOptions): Promise<WithId<TSchema> | null>; /** * Update a single document * * @param filter - Query filter * @param update - Update operations * @param options - Update options * @returns Update result * * @example * ```typescript * const result = await users.updateOne( * { email: 'john@example.com' }, * { $set: { lastLogin: new Date() } } * ); * console.log('Modified count:', result.modifiedCount); * ``` */ updateOne(filter: MongoFilter<TSchema>, update: MongoUpdateOperators<TSchema>, options?: { upsert?: boolean; }): Promise<UpdateResult>; /** * Update multiple documents * * @param filter - Query filter * @param update - Update operations * @param options - Update options * @returns Update result * * @example * ```typescript * const result = await users.updateMany( * { status: 'pending' }, * { $set: { status: 'active', updatedAt: new Date() } } * ); * ``` */ updateMany(filter: MongoFilter<TSchema>, update: MongoUpdateOperators<TSchema>, options?: { upsert?: boolean; }): Promise<UpdateResult>; /** * Update a document by ID * * @param id - Document ID * @param update - Update operations * @param options - Update options * @returns Update result * * @example * ```typescript * await users.updateById('user_123', { * $set: { name: 'John Smith' } * }); * ``` */ updateById(id: string, update: MongoUpdateOperators<TSchema>, options?: { upsert?: boolean; }): Promise<UpdateResult>; /** * Replace a single document * * @param filter - Query filter * @param replacement - Replacement document * @param options - Replace options * @returns Update result * * @example * ```typescript * await users.replaceOne( * { _id: 'user_123' }, * { name: 'John Doe', email: 'john.doe@example.com', age: 30 } * ); * ``` */ replaceOne(filter: MongoFilter<TSchema>, replacement: OptionalId<TSchema>, options?: { upsert?: boolean; }): Promise<UpdateResult>; /** * Delete a single document * * @param filter - Query filter * @returns Delete result * * @example * ```typescript * const result = await users.deleteOne({ email: 'old@example.com' }); * console.log('Deleted count:', result.deletedCount); * ``` */ deleteOne(filter: MongoFilter<TSchema>): Promise<DeleteResult>; /** * Delete multiple documents * * @param filter - Query filter * @returns Delete result * * @example * ```typescript * const result = await users.deleteMany({ status: 'inactive' }); * console.log('Deleted count:', result.deletedCount); * ``` */ deleteMany(filter: MongoFilter<TSchema>): Promise<DeleteResult>; /** * Delete a document by ID * * @param id - Document ID * @returns Delete result * * @example * ```typescript * await users.deleteById('user_123'); * ``` */ deleteById(id: string): Promise<DeleteResult>; /** * Execute bulk write operations * * @param operations - Array of bulk operations * @param options - Bulk write options * @returns Bulk write result * * @example * ```typescript * const result = await users.bulkWrite([ * { insertOne: { document: { name: 'Alice' } } }, * { updateOne: { filter: { name: 'Bob' }, update: { $set: { age: 30 } } } }, * { deleteOne: { filter: { name: 'Charlie' } } } * ]); * ``` */ bulkWrite(operations: BulkWriteOperation<TSchema>[], options?: { ordered?: boolean; }): Promise<BulkWriteResult>; /** * Count documents matching a filter * * @param filter - Query filter * @returns Document count * * @example * ```typescript * const activeUsers = await users.countDocuments({ status: 'active' }); * const totalUsers = await users.countDocuments(); * ``` */ countDocuments(filter?: MongoFilter<TSchema>): Promise<number>; /** * Get estimated document count (faster but less accurate) * * @returns Estimated document count * * @example * ```typescript * const estimate = await users.estimatedDocumentCount(); * ``` */ estimatedDocumentCount(): Promise<number>; /** * Get distinct values for a field * * @param field - Field name * @param filter - Query filter * @returns Array of distinct values * * @example * ```typescript * const countries = await users.distinct('country'); * const activeCountries = await users.distinct('country', { status: 'active' }); * ``` */ distinct<K extends keyof TSchema>(field: K, filter?: MongoFilter<TSchema>): Promise<TSchema[K][]>; /** * Create an index * * @param spec - Index specification * @param options - Index options * @returns Index name * * @example * ```typescript * // Create single field index * await users.createIndex({ email: 1 }, { unique: true }); * * // Create compound index * await users.createIndex({ status: 1, createdAt: -1 }); * * // Create text index * await users.createIndex({ name: 'text', bio: 'text' }); * ``` */ createIndex(spec: IndexSpec, options?: IndexOptions): Promise<string>; /** * Create multiple indexes * * @param indexes - Array of index specifications * @returns Array of index names * * @example * ```typescript * const indexNames = await users.createIndexes([ * { spec: { email: 1 }, options: { unique: true } }, * { spec: { status: 1, createdAt: -1 } } * ]); * ``` */ createIndexes(indexes: Array<{ spec: IndexSpec; options?: IndexOptions; }>): Promise<string[]>; /** * Drop an index * * @param indexName - Index name to drop * * @example * ```typescript * await users.dropIndex('email_1'); * ``` */ dropIndex(indexName: string): Promise<void>; /** * Drop all indexes * * @example * ```typescript * await users.dropIndexes(); * ``` */ dropIndexes(): Promise<void>; /** * List all indexes * * @returns Array of index information * * @example * ```typescript * const indexes = await users.listIndexes(); * indexes.forEach(index => { * console.log(`Index: ${index.name}, Size: ${index.size}`); * }); * ``` */ listIndexes(): Promise<IndexInfo[]>; /** * Get collection statistics * * @returns Collection statistics * * @example * ```typescript * const stats = await users.stats(); * console.log(`Documents: ${stats.documentCount}, Size: ${stats.totalSize}`); * ``` */ stats(): Promise<CollectionStats>; /** * Drop the collection * * @example * ```typescript * await users.drop(); * ``` */ drop(): Promise<void>; /** * Rename the collection * * @param newName - New collection name * * @example * ```typescript * await users.rename('customers'); * ``` */ rename(newName: string): Promise<void>; /** * Get vector operations interface * * @returns Vector operations instance * * @example * ```typescript * const similar = await users.vectors().search(queryVector, { * limit: 10, * threshold: 0.8 * }); * ``` */ vectors(): VectorOperations<TSchema>; /** * Get time series operations interface * * @returns Time series operations instance * * @example * ```typescript * await users.timeseries().write({ * metric: 'user_logins', * timestamp: Date.now(), * value: 1, * tags: { region: 'us-east' } * }); * ``` */ timeseries(): TimeSeriesOperations; /** * Watch for changes in the collection * * @param options - Subscription options * @param callback - Change event callback * @returns Subscription instance * * @example * ```typescript * const subscription = await users.watch({ * filter: { status: 'active' }, * events: ['insert', 'update'] * }, (event) => { * console.log('Change detected:', event.operationType); * }); * ``` */ watch(options: SubscriptionOptions | undefined, callback: (event: ChangeEvent<TSchema>) => void): Promise<Subscription>; /** * Get real-time operations interface * * @returns Real-time operations instance */ private realtime; /** * Get collection name * * @returns Collection name */ getName(): string; /** * Get database name * * @returns Database name */ getDatabaseName(): string; /** * Clear collection cache */ clearCache(): void; /** * Validate document against schema (if configured) */ private validateDocument; } //# sourceMappingURL=collection.d.ts.map