{"id":14956905,"url":"https://github.com/euberdeveloper/mongo-scanner","last_synced_at":"2025-07-29T00:34:08.976Z","repository":{"id":36933837,"uuid":"230916593","full_name":"euberdeveloper/mongo-scanner","owner":"euberdeveloper","description":"An npm module to retrieve the databases and the collections of a mongodb.","archived":false,"fork":false,"pushed_at":"2023-03-14T23:58:37.000Z","size":1144,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-19T10:15:49.197Z","etag":null,"topics":["database-schema","listing-database","mongodb","npm","typescript"],"latest_commit_sha":null,"homepage":"https://mongo-scanner.euber.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/euberdeveloper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-30T13:00:07.000Z","updated_at":"2022-04-21T15:29:53.000Z","dependencies_parsed_at":"2024-06-20T21:58:59.109Z","dependency_job_id":"86645b68-3fb7-4390-83b8-2a232d7744dc","html_url":"https://github.com/euberdeveloper/mongo-scanner","commit_stats":{"total_commits":85,"total_committers":2,"mean_commits":42.5,"dds":0.02352941176470591,"last_synced_commit":"ac3984707d4363fba313f75a97a21561585b8f77"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/euberdeveloper/mongo-scanner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/euberdeveloper%2Fmongo-scanner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/euberdeveloper%2Fmongo-scanner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/euberdeveloper%2Fmongo-scanner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/euberdeveloper%2Fmongo-scanner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/euberdeveloper","download_url":"https://codeload.github.com/euberdeveloper/mongo-scanner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/euberdeveloper%2Fmongo-scanner/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266646099,"owners_count":23961883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database-schema","listing-database","mongodb","npm","typescript"],"created_at":"2024-09-24T13:13:42.587Z","updated_at":"2025-07-29T00:34:08.930Z","avatar_url":"https://github.com/euberdeveloper.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Test](https://github.com/euberdeveloper/mongo-scanner/workflows/Test/badge.svg)\n![Lint](https://github.com/euberdeveloper/mongo-scanner/workflows/Lint/badge.svg)\n![Build](https://github.com/euberdeveloper/mongo-scanner/workflows/Build/badge.svg)\n[![Coverage Status](https://coveralls.io/repos/github/euberdeveloper/mongo-scanner/badge.svg?branch=master)](https://coveralls.io/github/euberdeveloper/mongo-scanner?branch=master)\n[![Codecov Status](https://codecov.io/gh/euberdeveloper/mongo-scanner/branch/master/graph/badge.svg)](https://codecov.io/gh/euberdeveloper/mongo-scanner)\n[![Known Vulnerabilities](https://snyk.io/test/github/euberdeveloper/mongo-scanner/badge.svg?targetFile=package.json)](https://snyk.io/test/github/euberdeveloper/mongo-scanner?targetFile=package.json)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n[![GitHub issues](https://img.shields.io/github/issues/euberdeveloper/mongo-scanner.svg)](https://github.com/euberdeveloper/mongo-scanner/issues)\n[![Types](https://img.shields.io/npm/types/mongo-scanner.svg)](https://www.npmjs.com/package/mongo-scanner)\n[![License](https://img.shields.io/npm/l/mongo-scanner.svg?color=blue)](https://github.com/euberdeveloper/mongo-scanner/blob/master/LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/euberdeveloper/mongo-scanner.svg)](https://github.com/euberdeveloper/mongo-scanner/stargazers)\n![npm](https://img.shields.io/npm/v/mongo-scanner.svg)\n[![Maintainability](https://api.codeclimate.com/v1/badges/529f6967d2bb067049f7/maintainability)](https://codeclimate.com/github/euberdeveloper/mongo-scanner/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/529f6967d2bb067049f7/test_coverage)](https://codeclimate.com/github/euberdeveloper/mongo-scanner/test_coverage)\n\n# mongo-scanner\nAn npm module to retrieve the databases and the collections of a mongodb.\n\n## Install\n\nTo install mongo-scanner as a local module:\n\n```bash\n$ npm install mongo-scanner\n```\n\n## Usage\n\n### Listing databases\n\nWith default connection and configurations:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst scanner = new MongoScanner();\n\nconst databases = await scanner.listDatabases();\n```\n\nWith custom connection:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst uri = 'mongodb://localhost:27017';\nconst connectionOptions = { numberOfRetries: 3 };\nconst scanner = new MongoScanner(uri, connectionOptions);\n\nconst databases = await scanner.listDatabases();\n```\n\nExcluding databases:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst scanner = new MongoScanner();\n\nconst options = { excludeDatabases: [ 'people', /^test/i ]};\nconst databases = await scanner.listDatabases(options);\n```\n\nUsing cache:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst scanner = new MongoScanner();\n\n// Will use connection\nlet databases = await scanner.listDatabases();\n// Will use another connection\ndatabases = await scanner.listDatabases();\n// Will use precedent cached result\ndatabases = await scanner.listDatabases({ useCache: true });\n```\n\n### Listing collections\n\nWith default connection and configurations:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst scanner = new MongoScanner();\n\nconst collections = await scanner.listCollections('myDatabase');\n```\n\nWith custom connection:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst uri = 'mongodb://localhost:27017';\nconst connectionOptions = { numberOfRetries: 3 };\nconst scanner = new MongoScanner(uri, connectionOptions);\n\nconst collections = await scanner.listCollections('myDatabase');\n```\n\nExcluding collections:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst scanner = new MongoScanner();\n\nconst options = { excludeCollections: [ 'students', /^test/i ]};\nconst collections = await scanner.listCollections('myDatabase', options);\n```\n\nExcluding system collections:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst scanner = new MongoScanner();\n\nconst options = { excludeSystem: true };\nconst collections = await scanner.listCollections('myDatabase', options);\n```\n\nUsing cache:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst scanner = new MongoScanner();\n\n// Will use connection\nlet collections = await scanner.listCollections('myDatabase');\n// Will use another connection\ncollections = await scanner.listCollections('myDatabase');\n// Will use precedent cached result\ncollections = await scanner.listCollections('myDatabase', { useCache: true });\n```\n\n### Getting database schema\n\nWith default connection and configurations:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst scanner = new MongoScanner();\n\nconst schema = await scanner.getSchema();\n```\n\nWith custom connection:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst uri = 'mongodb://localhost:27017';\nconst connectionOptions = { numberOfRetries: 3 };\nconst scanner = new MongoScanner(uri, connectionOptions);\n\nconst schema = await scanner.getSchema();\n```\n\nExcluding databases and collections:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst scanner = new MongoScanner();\n\nconst options = { \n    excludeDatabases: [ 'fruits', /^[0-9]/i ],\n    excludeCollections: [ 'students' ],\n    excludeSystem: true,\n    excludeEmptyDatabases: true\n};\nconst schema = await scanner.getSchema(options);\n```\n\nUsing cache:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst scanner = new MongoScanner();\n\n// Will use connection\nlet schema = await scanner.getSchema();\n// Will use another connection\nschema = await scanner.getSchema();\n// Will use precedent cached result\nschema = await scanner.getSchema({ useCache: true });\n```\n\n### Other features\n\nChanging default option values:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst defaultOptions = { useCache: true };\nconst scanner = new MongoScanner(null, null, defaultOptions);\n```\n\nUsing a persistent connection:\n\n```js\nconst { MongoScanner } = require('mongo-scanner');\nconst scanner = new MongoScanner();\n\nawait scanner.startConnection();\nconst databases = await scanner.listDatabases();\nconst collections = await scanner.listCollections('myDatabase');\nconst schema = await scanner.getSchema();\nawait scanner.endConnection();\n```\n\n## Result\n\nThe `listDatabases` method returns a result like this:\n\n```json\n[ \"admin\", \"people\", \"animals\", \"fruits\" ]\n```\n\nThe `listCollections` method returns a result like this:\n\n```json\n[ \"dogs\", \"cats\", \"rabbits\", \"mouses\" ]\n```\n\nThe `getSchema` method returns a result like this:\n\n```json\n{\n    \"admin\": [ \"system.versions\" ],\n    \"animals\": [ \"dogs\", \"cats\", \"rabbits\", \"mouses\" ],\n    \"people\": [ \"students\", \"teachers\", \"musicians\" ]\n}\n```\n\n## API\n\nDocumentation's sites:\n\n- [For users of the module](https://mongo-scanner.euberdeveloper.vercel.app)\n- [For development](https://mongo-scanner-dev.euberdeveloper.vercel.app)\n\n### MongoScanner\n\nThe MongoScanner class, to retrieve the database schema or to list databases and collections of a MongoDB database.\n\n### MongoScanner.constructor\n\n**Syntax:**\n\n`new MongoScanner(uri, connectionOptions, options)`\n\n**Description:**\n\nThe constructor of the `MongoScanner` class. The params are the uri and options for the database connections. The connection is not established by the constructor, the connection parameters are only saved in the `MongoScanner` instance.\n\n**Parameters:**\n\n* __uri__: Optional. The `string` uri of the mongodb connection. Default: `mongodb://localhost:27017`.\n* __connectionOptions__: Optional. The options object of the mongodb connection. The npm mongodb module is used under the hood and this is the object provided to MongoClient. Default: `{ }`.\n* __options__: Optional. The `ScanOptions` object options that will be used as a fallback for the `ScanOptions`. For all the keys that will not be present in the options provided to a method that retrieves database or collections, the values provided here will be used instead of the default ones. Default: `{ }`.\n\n**ScanOptions parameters:**\n\n* __useCache__: Default value: `false`. If you want to use the cache before starting a database connection. When true, all the previous executions of the `MongoScanner` instance will be checked before establishing a new database connection. The cache is update every time an execution retrieves data form the database connection.\n* __excludeDatabases__: Default value: `undefined`. Databases that you want to exclude from the result. You can provide a `string`, a `Regexp` or an `array` of both. A database will be removed from the result if it is equal to a string or matches a Regexp.\n* __excludeCollections__: Default value: `undefined`. Collections that you want to exclude from the result. You can provide a `string`, a `Regexp` or an `array` of both. A collection will be removed from the result if it is equal to a string or matches a Regexp.\n* __excludeSystem__: Default value: `false`. If you want system collections to be excluded by the result.\n* __excludeEmptyDatabases__: Default value: `false`. If you want to exclude empty databases from the result of the method \"getSchema()\". NB: Database that are not empty but whose collections are excluded by other options such as excludeSystem or excludeCollections will be considered as empty.\n* __ignoreLackOfPermissions__: Default value: `false`. If you want to ignore and not throw an error occurred when trying to list databases or collections but the connection had not permission to do it. NB: Actually, this will ignore all the errors that will occur when listing database or collections.\n* __throwIfNotTotal__: Default value: `() =\u003e { }`. The `LackOfpermissionsCallback` callback called if an error occurred when trying to list databases or collectionsbut the connection had not permission to do it. NB: Actually, this will be called for all the errors that will occur when listing database or collections. \n\n**LackOfpermissionsCallback**\n\nParameters:\n\n* __db__: Type: `string`. If the error happened when listing collections, the db is the database whose collections  were tried to be provided\n* __error__: The error that happened. It is of type `ListDatabasesError` if it happened when listing databases and it is of type `ListCollectionsError` if it happened when listing collections.\n\n### MongoScanner.listDatabases\n\n**Syntax:**\n\n`listDatabases(options)`\n\n**Description:**\n\nRetrieves the databases of a mongodb as a promise to an array of strings.\n\n**Parameters:**\n\n* __options__: Optional. The `ScanOptions` options. See above to find more details about `ScanOptions`.\n\n**Result:**\n\nA promise to an array of strings containing the retrieved databases.\n\n### MongoScanner.listCollections\n\n**Syntax:**\n\n`listCollections(database, options)`\n\n**Description:**\n\nRetrieves the collections of the specified database as a promise to an array of strings.\n\n**Parameters:**\n\n* __database__: The database whose collections will be exported.\n* __options__: Optional. The `ScanOptions` options. See above to find more details about `ScanOptions`.\n\n**Result:**\n\nA promise to an array of strings containing the retrieved collections.\n\n### MongoScanner.getSchema\n\n**Syntax:**\n\n`getSchema(options)`\n\n**Description:**\n\nRetrieves the schema of a mongodb database as a promise to a `DatabaseSchema` object.\n\n**Parameters:**\n\n* __options__: Optional. The `ScanOptions` options. See above to find more details about `ScanOptions`.\n\n**Result:**\n\nA promise to a `DatabaseSchema` object representing the database schema. The keys are the databases and their values the collections of the database as an array of strings\n\n### MongoScanner.startConnection\n\n**Syntax:**\n\n`startConnection()`\n\n**Description:**\n\nStarts a persistent connection to mongodb. By default, all methods that retrieve databases or collections from the mongodb open a connection before beginning and close it after finishing. This method allows you to have a persistent connection instead and is useful if you need to perform more than an operation and do not want to open and close connections for each of them.\n\n**Result:**\n\nA `void Promise`.\n\n### MongoScanner.endConnection\n\n**Syntax:**\n\n`endConnection()`\n\n**Description:**\n\nCloses an already open persistent connection.\n\n**Result:**\n\nA `void Promise`.\n\n**Result:**\n\nA `void Promise`.\n\n### MongoScanner.clearCache\n\n**Syntax:**\n\n`clearCache()`\n\n**Description:**\n\nClears the cache, which contains the results of the previous executions of the `MongoScanner` instance. It is a synchronous method and returns nothing.\n\n## Project structure\n\nMade with **[dree](https://www.npmjs.com/package/dree)**.\n\n```\nmongo-scanner\n ├─\u003e dist\n │   ├─\u003e source\n │   └─\u003e test\n ├─\u003e source\n │   ├─\u003e errors\n │   │   ├── connectionError.ts\n │   │   ├── disconnectionError.ts\n │   │   ├── index.ts\n │   │   ├── listCollectionsError.ts\n │   │   ├── listDatabasesError.ts\n │   │   └── mongoScannerError.ts\n │   ├── index.ts\n │   ├── tsconfig.json\n │   └─\u003e utils\n │       ├── cache.ts\n │       └── database.ts\n ├─\u003e test\n │   ├─\u003e clearCache\n │   │   ├── clearCache.test.ts\n │   │   └── database-schema.test.json\n │   ├─\u003e getSchema\n │   │   ├─\u003e expected\n │   │   │   ├── first.test.json\n │   │   │   ├── second.test.json\n │   │   │   └── third.test.json\n │   │   └── getSchema.test.ts\n │   ├─\u003e listCollections\n │   │   └── listCollections.test.ts\n │   ├─\u003e listDatabases\n │   │   └── listDatabases.test.ts\n │   ├─\u003e mock\n │   ├─\u003e persistentConnection\n │   │   ├── database-schema.test.json\n │   │   └── persistentConnection.test.ts\n │   ├── test.ts\n │   ├── tsconfig.json\n │   └─\u003e utils\n │       ├── benchmark.ts\n │       └── orderObject.ts\n ├─\u003e docs\n │   └─\u003e tree\n │       ├── dree.config.json\n │       └── tree.txt\n ├── LICENSE\n ├── README.md\n ├── package-lock.json\n └── package.json\n```\n\n## Build\n\nTo build the module make sure you have Typescript installed or install the dev dependencies. After this, run:\n\n```bash\n$ npm run transpile\n```\n\nThe `source` folder will be compiled in the `dist` folder.\n\n## Dev\n\nMake sure you have the dev dependencies installed.\n\nTo lint the code go to the package root in your CLI and run\n\n```bash\n$ npm run lint\n```\n\nTo run tests go to the package root in your CLI and run\n\n```bash\n$ npm run db:populate\n$ npm test\n```\n\n**Note: Running tests will delete permanently your MongoDB data. Do not do it if you have important data on it.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feuberdeveloper%2Fmongo-scanner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feuberdeveloper%2Fmongo-scanner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feuberdeveloper%2Fmongo-scanner/lists"}