diff --git a/packages/mongo/mongo.d.ts b/packages/mongo/mongo.d.ts new file mode 100644 index 0000000000..43e8e9c3e7 --- /dev/null +++ b/packages/mongo/mongo.d.ts @@ -0,0 +1,598 @@ +import * as MongoNpmModule from 'mongodb'; +import { + Collection as MongoCollection, + CreateIndexesOptions, + Db as MongoDb, + Hint, + IndexSpecification, + MongoClient, +} from 'mongodb'; +import { Meteor } from 'meteor/meteor'; + +// Based on https://github.com/microsoft/TypeScript/issues/28791#issuecomment-443520161 +export type UnionOmit = T extends T + ? Pick> + : never; + +export namespace Mongo { + // prettier-ignore + type BsonType = 1 | "double" | + 2 | "string" | + 3 | "object" | + 4 | "array" | + 5 | "binData" | + 6 | "undefined" | + 7 | "objectId" | + 8 | "bool" | + 9 | "date" | + 10 | "null" | + 11 | "regex" | + 12 | "dbPointer" | + 13 | "javascript" | + 14 | "symbol" | + 15 | "javascriptWithScope" | + 16 | "int" | + 17 | "timestamp" | + 18 | "long" | + 19 | "decimal" | + -1 | "minKey" | + 127 | "maxKey" | "number"; + + type FieldExpression = { + $eq?: T | undefined; + $gt?: T | undefined; + $gte?: T | undefined; + $lt?: T | undefined; + $lte?: T | undefined; + $in?: T[] | undefined; + $nin?: T[] | undefined; + $ne?: T | undefined; + $exists?: boolean | undefined; + $type?: BsonType[] | BsonType | undefined; + $not?: FieldExpression | undefined; + $expr?: FieldExpression | undefined; + $jsonSchema?: any; + $mod?: number[] | undefined; + $regex?: RegExp | string | undefined; + $options?: string | undefined; + $text?: + | { + $search: string; + $language?: string | undefined; + $caseSensitive?: boolean | undefined; + $diacriticSensitive?: boolean | undefined; + } + | undefined; + $where?: string | Function | undefined; + $geoIntersects?: any; + $geoWithin?: any; + $near?: any; + $nearSphere?: any; + $all?: T[] | undefined; + $elemMatch?: T extends {} ? Query : FieldExpression | undefined; + $size?: number | undefined; + $bitsAllClear?: any; + $bitsAllSet?: any; + $bitsAnyClear?: any; + $bitsAnySet?: any; + $comment?: string | undefined; + }; + + type Flatten = T extends any[] ? T[0] : T; + + type Query = { + [P in keyof T]?: Flatten | RegExp | FieldExpression>; + } & { + $or?: Query[] | undefined; + $and?: Query[] | undefined; + $nor?: Query[] | undefined; + } & Dictionary; + + type QueryWithModifiers = { + $query: Query; + $comment?: string | undefined; + $explain?: any; + $hint?: Hint; + $maxScan?: any; + $max?: any; + $maxTimeMS?: any; + $min?: any; + $orderby?: any; + $returnKey?: any; + $showDiskLoc?: any; + $natural?: any; + }; + + type Selector = Query | QueryWithModifiers; + + type Dictionary = { [key: string]: T }; + type PartialMapTo = Partial>; + type OnlyArrays = T extends any[] ? T : never; + type OnlyElementsOfArrays = T extends any[] ? Partial : never; + type ElementsOf = { + [P in keyof T]?: OnlyElementsOfArrays; + }; + type PushModifier = { + [P in keyof T]?: + | OnlyElementsOfArrays + | { + $each?: T[P] | undefined; + $position?: number | undefined; + $slice?: number | undefined; + $sort?: 1 | -1 | Dictionary | undefined; + }; + }; + type ArraysOrEach = { + [P in keyof T]?: OnlyElementsOfArrays | { $each: T[P] }; + }; + type CurrentDateModifier = { $type: 'timestamp' | 'date' } | true; + type Modifier = + | T + | { + $currentDate?: + | (Partial> & + Dictionary) + | undefined; + $inc?: (PartialMapTo & Dictionary) | undefined; + $min?: + | (PartialMapTo & Dictionary) + | undefined; + $max?: + | (PartialMapTo & Dictionary) + | undefined; + $mul?: (PartialMapTo & Dictionary) | undefined; + $rename?: (PartialMapTo & Dictionary) | undefined; + $set?: (Partial & Dictionary) | undefined; + $setOnInsert?: (Partial & Dictionary) | undefined; + $unset?: + | (PartialMapTo & Dictionary) + | undefined; + $addToSet?: (ArraysOrEach & Dictionary) | undefined; + $push?: (PushModifier & Dictionary) | undefined; + $pull?: (ElementsOf & Dictionary) | undefined; + $pullAll?: (Partial & Dictionary) | undefined; + $pop?: (PartialMapTo & Dictionary<1 | -1>) | undefined; + }; + + type OptionalId = UnionOmit & { _id?: any }; + + interface SortSpecifier {} + interface FieldSpecifier { + [id: string]: Number; + } + + type Transform = ((doc: T) => any) | null | undefined; + + type Options = { + /** Sort order (default: natural order) */ + sort?: SortSpecifier | undefined; + /** Number of results to skip at the beginning */ + skip?: number | undefined; + /** Maximum number of results to return */ + limit?: number | undefined; + /** Dictionary of fields to return or exclude. */ + fields?: FieldSpecifier | undefined; + /** (Server only) Overrides MongoDB's default index selection and query optimization process. Specify an index to force its use, either by its name or index specification. */ + hint?: Hint | undefined; + /** (Client only) Default `true`; pass `false` to disable reactivity */ + reactive?: boolean | undefined; + /** Overrides `transform` on the [`Collection`](#collections) for this cursor. Pass `null` to disable transformation. */ + transform?: Transform | undefined; + }; + + type DispatchTransform = Transform extends ( + ...args: any + ) => any + ? ReturnType + : Transform extends null + ? T + : U; + + var Collection: CollectionStatic; + interface CollectionStatic { + /** + * Constructor for a Collection + * @param name The name of the collection. If null, creates an unmanaged (unsynchronized) local collection. + */ + new ( + name: string | null, + options?: { + /** + * The server connection that will manage this collection. Uses the default connection if not specified. Pass the return value of calling `DDP.connect` to specify a different + * server. Pass `null` to specify no connection. Unmanaged (`name` is null) collections cannot specify a connection. + */ + connection?: Object | null | undefined; + /** The method of generating the `_id` fields of new documents in this collection. Possible values: + * - **`'STRING'`**: random strings + * - **`'MONGO'`**: random [`Mongo.ObjectID`](#mongo_object_id) values + * + * The default id generation technique is `'STRING'`. + */ + idGeneration?: string | undefined; + /** + * An optional transformation function. Documents will be passed through this function before being returned from `fetch` or `findOne`, and before being passed to callbacks of + * `observe`, `map`, `forEach`, `allow`, and `deny`. Transforms are *not* applied for the callbacks of `observeChanges` or to cursors returned from publish functions. + */ + transform?: (doc: T) => U; + /** Set to `false` to skip setting up the mutation methods that enable insert/update/remove from client code. Default `true`. */ + defineMutationMethods?: boolean | undefined; + } + ): Collection; + } + interface Collection { + allow = undefined>(options: { + insert?: + | ((userId: string, doc: DispatchTransform) => boolean) + | undefined; + update?: + | (( + userId: string, + doc: DispatchTransform, + fieldNames: string[], + modifier: any + ) => boolean) + | undefined; + remove?: + | ((userId: string, doc: DispatchTransform) => boolean) + | undefined; + fetch?: string[] | undefined; + transform?: Fn | undefined; + }): boolean; + createCappedCollectionAsync( + byteSize?: number, + maxDocuments?: number + ): Promise; + createIndex( + indexSpec: IndexSpecification, + options?: CreateIndexesOptions + ): void; + createIndexAsync( + indexSpec: IndexSpecification, + options?: CreateIndexesOptions + ): Promise; + deny = undefined>(options: { + insert?: + | ((userId: string, doc: DispatchTransform) => boolean) + | undefined; + update?: + | (( + userId: string, + doc: DispatchTransform, + fieldNames: string[], + modifier: any + ) => boolean) + | undefined; + remove?: + | ((userId: string, doc: DispatchTransform) => boolean) + | undefined; + fetch?: string[] | undefined; + transform?: Fn | undefined; + }): boolean; + dropCollectionAsync(): Promise; + dropIndexAsync(indexName: string): void; + /** + * Find the documents in a collection that match the selector. + * @param selector A query describing the documents to find + */ + find(selector?: Selector | ObjectID | string): Cursor; + /** + * Find the documents in a collection that match the selector. + * @param selector A query describing the documents to find + */ + find>( + selector?: Selector | ObjectID | string, + options?: O + ): Cursor>; + /** + * Finds the first document that matches the selector, as ordered by sort and skip options. Returns `undefined` if no matching document is found. + * @param selector A query describing the documents to find + */ + findOne(selector?: Selector | ObjectID | string): U | undefined; + /** + * Finds the first document that matches the selector, as ordered by sort and skip options. Returns `undefined` if no matching document is found. + * @param selector A query describing the documents to find + */ + findOne, 'limit'>>( + selector?: Selector | ObjectID | string, + options?: O + ): DispatchTransform | undefined; + /** + * Finds the first document that matches the selector, as ordered by sort and skip options. Returns `undefined` if no matching document is found. + * @param selector A query describing the documents to find + */ + findOneAsync( + selector?: Selector | ObjectID | string + ): Promise; + /** + * Finds the first document that matches the selector, as ordered by sort and skip options. Returns `undefined` if no matching document is found. + * @param selector A query describing the documents to find + */ + findOneAsync, 'limit'>>( + selector?: Selector | ObjectID | string, + options?: O + ): Promise | undefined>; + /** + * Insert a document in the collection. Returns its unique _id. + * @param doc The document to insert. May not yet have an _id attribute, in which case Meteor will generate one for you. + * @param callback If present, called with an error object as the first argument and, if no error, the _id as the second. + */ + insert(doc: OptionalId, callback?: Function): string; + /** + * Insert a document in the collection. Returns its unique _id. + * @param doc The document to insert. May not yet have an _id attribute, in which case Meteor will generate one for you. + * @param callback If present, called with an error object as the first argument and, if no error, the _id as the second. + */ + insertAsync(doc: OptionalId, callback?: Function): Promise; + /** + * Returns the [`Collection`](http://mongodb.github.io/node-mongodb-native/3.0/api/Collection.html) object corresponding to this collection from the + * [npm `mongodb` driver module](https://www.npmjs.com/package/mongodb) which is wrapped by `Mongo.Collection`. + */ + rawCollection(): MongoCollection; + /** + * Returns the [`Db`](http://mongodb.github.io/node-mongodb-native/3.0/api/Db.html) object corresponding to this collection's database connection from the + * [npm `mongodb` driver module](https://www.npmjs.com/package/mongodb) which is wrapped by `Mongo.Collection`. + */ + rawDatabase(): MongoDb; + /** + * Remove documents from the collection + * @param selector Specifies which documents to remove + * @param callback If present, called with an error object as its argument. + */ + remove( + selector: Selector | ObjectID | string, + callback?: Function + ): number; + /** + * Remove documents from the collection + * @param selector Specifies which documents to remove + * @param callback If present, called with an error object as its argument. + */ + removeAsync( + selector: Selector | ObjectID | string, + callback?: Function + ): Promise; + /** + * Modify one or more documents in the collection. Returns the number of matched documents. + * @param selector Specifies which documents to modify + * @param modifier Specifies how to modify the documents + * @param callback If present, called with an error object as the first argument and, if no error, the number of affected documents as the second. + */ + update( + selector: Selector | ObjectID | string, + modifier: Modifier, + options?: { + /** True to modify all matching documents; false to only modify one of the matching documents (the default). */ + multi?: boolean | undefined; + /** True to insert a document if no matching documents are found. */ + upsert?: boolean | undefined; + /** + * Used in combination with MongoDB [filtered positional operator](https://docs.mongodb.com/manual/reference/operator/update/positional-filtered/) to specify which elements to + * modify in an array field. + */ + arrayFilters?: { [identifier: string]: any }[] | undefined; + }, + callback?: Function + ): number; + /** + * Modify one or more documents in the collection. Returns the number of matched documents. + * @param selector Specifies which documents to modify + * @param modifier Specifies how to modify the documents + * @param callback If present, called with an error object as the first argument and, if no error, the number of affected documents as the second. + */ + updateAsync( + selector: Selector | ObjectID | string, + modifier: Modifier, + options?: { + /** True to modify all matching documents; false to only modify one of the matching documents (the default). */ + multi?: boolean | undefined; + /** True to insert a document if no matching documents are found. */ + upsert?: boolean | undefined; + /** + * Used in combination with MongoDB [filtered positional operator](https://docs.mongodb.com/manual/reference/operator/update/positional-filtered/) to specify which elements to + * modify in an array field. + */ + arrayFilters?: { [identifier: string]: any }[] | undefined; + }, + callback?: Function + ): Promise; + /** + * Modify one or more documents in the collection, or insert one if no matching documents were found. Returns an object with keys `numberAffected` (the number of documents modified) and + * `insertedId` (the unique _id of the document that was inserted, if any). + * @param selector Specifies which documents to modify + * @param modifier Specifies how to modify the documents + * @param callback If present, called with an error object as the first argument and, if no error, the number of affected documents as the second. + */ + upsert( + selector: Selector | ObjectID | string, + modifier: Modifier, + options?: { + /** True to modify all matching documents; false to only modify one of the matching documents (the default). */ + multi?: boolean | undefined; + }, + callback?: Function + ): { + numberAffected?: number | undefined; + insertedId?: string | undefined; + }; + /** + * Modify one or more documents in the collection, or insert one if no matching documents were found. Returns an object with keys `numberAffected` (the number of documents modified) and + * `insertedId` (the unique _id of the document that was inserted, if any). + * @param selector Specifies which documents to modify + * @param modifier Specifies how to modify the documents + * @param callback If present, called with an error object as the first argument and, if no error, the number of affected documents as the second. + */ + upsertAsync( + selector: Selector | ObjectID | string, + modifier: Modifier, + options?: { + /** True to modify all matching documents; false to only modify one of the matching documents (the default). */ + multi?: boolean | undefined; + }, + callback?: Function + ): Promise<{ + numberAffected?: number | undefined; + insertedId?: string | undefined; + }>; + _createCappedCollection(byteSize?: number, maxDocuments?: number): void; + /** @deprecated */ + _ensureIndex( + indexSpec: IndexSpecification, + options?: CreateIndexesOptions + ): void; + _dropCollection(): Promise; + _dropIndex(indexName: string): void; + } + + var Cursor: CursorStatic; + interface CursorStatic { + /** + * To create a cursor, use find. To access the documents in a cursor, use forEach, map, or fetch. + */ + new (): Cursor; + } + interface ObserveCallbacks { + added?(document: T): void; + addedAt?(document: T, atIndex: number, before: T | null): void; + changed?(newDocument: T, oldDocument: T): void; + changedAt?(newDocument: T, oldDocument: T, indexAt: number): void; + removed?(oldDocument: T): void; + removedAt?(oldDocument: T, atIndex: number): void; + movedTo?( + document: T, + fromIndex: number, + toIndex: number, + before: T | null + ): void; + } + interface ObserveChangesCallbacks { + added?(id: string, fields: Partial): void; + addedBefore?(id: string, fields: Partial, before: T | null): void; + changed?(id: string, fields: Partial): void; + movedBefore?(id: string, before: T | null): void; + removed?(id: string): void; + } + interface Cursor { + /** + * Returns the number of documents that match a query. + * @param applySkipLimit If set to `false`, the value returned will reflect the total number of matching documents, ignoring any value supplied for limit. (Default: true) + */ + count(applySkipLimit?: boolean): number; + /** + * Returns the number of documents that match a query. + * @param applySkipLimit If set to `false`, the value returned will reflect the total number of matching documents, ignoring any value supplied for limit. (Default: true) + */ + countAsync(applySkipLimit?: boolean): Promise; + /** + * Return all matching documents as an Array. + */ + fetch(): Array; + /** + * Return all matching documents as an Array. + */ + fetchAsync(): Promise>; + /** + * Call `callback` once for each matching document, sequentially and + * synchronously. + * @param callback Function to call. It will be called with three arguments: the document, a 0-based index, and cursor itself. + * @param thisArg An object which will be the value of `this` inside `callback`. + */ + forEach( + callback: (doc: U, index: number, cursor: Cursor) => void, + thisArg?: any + ): void; + /** + * Call `callback` once for each matching document, sequentially and + * synchronously. + * @param callback Function to call. It will be called with three arguments: the document, a 0-based index, and cursor itself. + * @param thisArg An object which will be the value of `this` inside `callback`. + */ + forEachAsync( + callback: (doc: U, index: number, cursor: Cursor) => void, + thisArg?: any + ): Promise; + /** + * Map callback over all matching documents. Returns an Array. + * @param callback Function to call. It will be called with three arguments: the document, a 0-based index, and cursor itself. + * @param thisArg An object which will be the value of `this` inside `callback`. + */ + map( + callback: (doc: U, index: number, cursor: Cursor) => M, + thisArg?: any + ): Array; + /** + * Map callback over all matching documents. Returns an Array. + * @param callback Function to call. It will be called with three arguments: the document, a 0-based index, and cursor itself. + * @param thisArg An object which will be the value of `this` inside `callback`. + */ + mapAsync( + callback: (doc: U, index: number, cursor: Cursor) => M, + thisArg?: any + ): Promise>; + /** + * Watch a query. Receive callbacks as the result set changes. + * @param callbacks Functions to call to deliver the result set as it changes + */ + observe(callbacks: ObserveCallbacks): Meteor.LiveQueryHandle; + /** + * Watch a query. Receive callbacks as the result set changes. Only the differences between the old and new documents are passed to the callbacks. + * @param callbacks Functions to call to deliver the result set as it changes + */ + observeChanges( + callbacks: ObserveChangesCallbacks, + options?: { nonMutatingCallbacks?: boolean | undefined } + ): Meteor.LiveQueryHandle; + [Symbol.iterator](): Iterator; + [Symbol.asyncIterator](): AsyncIterator; + } + + var ObjectID: ObjectIDStatic; + interface ObjectIDStatic { + /** + * Create a Mongo-style `ObjectID`. If you don't specify a `hexString`, the `ObjectID` will generated randomly (not using MongoDB's ID construction rules). + + * @param hexString The 24-character hexadecimal contents of the ObjectID to create + */ + new (hexString?: string): ObjectID; + } + interface ObjectID { + toHexString(): string; + equals(otherID: ObjectID): boolean; + } + + function setConnectionOptions(options: any): void; +} + +export namespace Mongo { + interface AllowDenyOptions { + insert?: ((userId: string, doc: any) => boolean) | undefined; + update?: + | (( + userId: string, + doc: any, + fieldNames: string[], + modifier: any + ) => boolean) + | undefined; + remove?: ((userId: string, doc: any) => boolean) | undefined; + fetch?: string[] | undefined; + transform?: Function | null | undefined; + } +} + +export declare module MongoInternals { + interface MongoConnection { + db: MongoDb; + client: MongoClient; + } + + function defaultRemoteCollectionDriver(): { + mongo: MongoConnection; + }; + + var NpmModules: { + mongodb: { + version: string; + module: typeof MongoNpmModule; + }; + }; +} diff --git a/packages/mongo/package.js b/packages/mongo/package.js index a6e1be4d70..39dd505837 100644 --- a/packages/mongo/package.js +++ b/packages/mongo/package.js @@ -82,6 +82,7 @@ Package.onUse(function (api) { api.addFiles('remote_collection_driver.js', 'server'); api.addFiles('collection.js', ['client', 'server']); api.addFiles('connection_options.js', 'server'); + api.addAssets('mongo.d.ts', ['client', 'server']); }); Package.onTest(function (api) { diff --git a/packages/mongo/package.types.json b/packages/mongo/package.types.json new file mode 100644 index 0000000000..97c9c11e61 --- /dev/null +++ b/packages/mongo/package.types.json @@ -0,0 +1,3 @@ +{ + "typesEntry": "mongo.d.ts" +}