Contributing
Welcome, we really appreciate if you’re considering to contribute to effect-mongodb!
Found a Bug?
If you find a bug in the source code, you can help us by submitting an issue to our GitHub Repository. Even better, you can submit a Pull Request with a fix.
Missing a Feature?
You can request a new feature by submitting a discussion to our GitHub Repository. If you would like to implement a new feature, please consider the size of the change and reach out to better coordinate our efforts and prevent duplication of work.
Initial setup
Install the following tools to set up your environment:
Then, you can fork the repository and install the dependencies:
- Fork this repository on GitHub
- Clone your forked repo:
Terminal window git clone https://github.com/<username>/effect-mongodb && cd effect-mongodb - Install dependencies:
Terminal window pnpm install - Optionally, verify that everything is working correctly:
Terminal window pnpm checkpnpm test
Making changes
Create a new branch for your changes
git checkout -b my-branchMake the changes you propose to the codebase. If your changes impact functionality, please add corresponding tests to validate your updates.
Validate your changes
Run the following commands to ensure your changes do not introduce any issues:
pnpm codegen(optional): Re-generate the package entrypoints in case you have changed the structure of a package or introduced a new module.pnpm check: Confirm that the code compiles without errors.pnpm test: Execute all unit tests to ensure your changes haven’t broken existing functionality.pnpm circular: Check for any circular dependencies in imports.pnpm lint: Ensure the code adheres to our coding standards.- If you encounter style issues, use
pnpm lint-fixto automatically correct some of these.
- If you encounter style issues, use
pnpm dtslint: Run type-level tests.
Website
The documentation website lives in website/, a standalone project outside the pnpm workspace with its own
dependencies. It needs Node.js 22.23.4 or newer.
cd websitepnpm installpnpm devValidate website changes with pnpm check, pnpm lint, pnpm test and pnpm build, run from website/.
The website has no content of its own: website/src/content/publishedContent.ts lists the repository files it
publishes. Every ## section of a published README becomes a page, so renaming or removing a ## heading renames or
removes a page; a few files, like this one, and the root README Compatibility section are published as single pages.
Relative links point to the site page when their target is published, otherwise to the file on GitHub;
a relative link to a missing file, or to a missing heading of a published file, fails the website tests and build.
Links to headings of other files, such as the root README outside its Compatibility section, go to GitHub unchecked.
Each .ts file of a package examples folder becomes a page, so it must be listed in
website/src/content/publishedContent.ts and start, after its imports, with a JSDoc block holding its title and, under
Highlights:, its introduction.
Document your changes
Before committing your changes, document them with a changeset. This process helps in tracking modifications and effectively communicating them to the project team and users:
pnpm changesetDuring the changeset creation process, you will be prompted to select the appropriate level for your changes:
- patch: Opt for this if you are making small fixes or minor changes that do not affect the library’s overall functionality.
- minor: Choose this for new features that enhance functionality but do not disrupt existing features.
- major: Select this for any changes that result in backward-incompatible modifications to the library.
Commit your changes
Once you have documented your changes, commit them to the repository:
git commit -am "Add some feature"Linking to issues
If your commit addresses an open issue, reference the issue number directly in your commit message. This helps to link your contribution clearly to specific tasks or bug reports.
For example:
# Reference issue #123git commit -am "Add some feature (#123)"
# Close the issue #123git commit -am "Add some feature (close #123)"Push to your fork
Push the changes to your GitHub fork:
git push origin my-branchCreate a pull request
Open a pull request against the main branch on the original repository.
Please be patient! We will do our best to review your pull request as soon as possible.
Tests
We use @testcontainers/mongodb to run MongoDB in a Docker container during tests.
Write a test
In the test directory of a package, like packages/effect-mongodb/test, create a
new file <test suite name>.test.ts.
Use the describeMongo function to automatically setup your test suite with a MongoDB connection.
import * as Db from "effect-mongodb/Db"import * as DocumentCollection from "effect-mongodb/DocumentCollection"import * as Effect from "effect/Effect"import * as O from "effect/Option"import { ObjectId } from "mongodb"import { expect, test } from "vitest"import { describeMongo } from "./support/describe-mongo.js"
describeMongo("My tests", (ctx) => { test("find one", async () => { const program = Effect.gen(function*() { const db = yield* ctx.database const collection = Db.documentCollection(db, "find-one")
yield* DocumentCollection.insertMany(collection, [{ name: "john" }, { name: "alfred" }])
return yield* DocumentCollection.findOne(collection, { name: "john" }) })
const result = await Effect.runPromise(program)
expect(result).toEqual(O.some({ _id: expect.any(ObjectId), name: "john" })) })})Inspect MongoDB test instance
- Export
EFFECT_MONGODB_DEBUG=trueenvironment variable - Run the tests (by default in watch mode) and you will see the connection string in the console output
[EFFECT_MONGODB_DEBUG] MongoDB connection string with direct connection: 'mongodb://localhost:32775'
- Copy the connection string
mongodb://localhost:32775 - Open MongoDB Compass
- Click Add new connection
- Paste the copied connection string in the URI field
- Click Advanced Connection Options
- Enable Direct Connection
- Click Save & Connect
Released under the MIT License.