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
TypeScript
/**
* 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