Skip to content

Latest commit

 

History

History
125 lines (97 loc) · 4.18 KB

DEVGUIDE.md

File metadata and controls

125 lines (97 loc) · 4.18 KB

Contents

  1. Build & Run tests locally
  2. Update Stargate and Data API versions
  3. Build API Reference Documentation
  4. Debug Mode
  5. Creating a release
  6. Contributing

Build & Test

Prerequisites:

Build

npm install
npm run build

Test

  • Start Docker
  • Start Data API
bin/start_data_api.sh
  • Copy the .env.example file and create a new .env file that should have all the connection details as shown below.
DATA_API_URI=http://localhost:8181/v1/testks1
DATA_API_USERNAME=cassandra
DATA_API_PASSWORD=cassandra
  • Run the tests
npm run test

Lint

Run npm run lint to run oxlint. oxlint will point out code quality issues it finds. oxlint can automatically fix some issues: run npm run lint -- --fix to tell oxlint to automatically fix what issues it can. You should try to run npm run lint before committing to minimize risk of regressions.

Update Stargate and Data API versions

Stargate and the Data API versions are maintained in the file api-compatibility.versions. Update the versions accordingly, submit a PR and make sure that the GitHub Actions that verify the new versions run fine.

Debug Mode

Astra-mongoose supports Mongoose's debug mode for logging calls at the Mongoose driver layer. Note that Mongoose debug mode logs function calls as they come in to astra-mongoose Collection instances as defined in src/drivers/collection.ts, not the requests sent to Data API.

import mongoose from 'mongoose';
import { driver } from 'astra-mongoose';

mongoose.set('debug', true); // Log to console
// Can also log to a custom function as follows:
// mongoose.set('debug', (collectionName: string, fnName: string, ...args: unknown[]) => { /* handle logging here */ });
mongoose.setDriver(driver);

Astra-mongoose also supports astra-db-ts' logging to enable logging requests sent to Data API.

import mongoose from 'mongoose';
import { driver } from 'astra-mongoose';

mongoose.setDriver(driver);
mongoose.connect(process.env.ASTRA_URI, {
  logging: 'all' // astra-db-ts logging config
});

const TestModel = mongoose.model('Test', mongoose.Schema({ name: String }), 'test');

// Astra-mongoose bubbles up events from astra-mongoose collections and dbs to the connection object
mongoose.connection.on('commandStarted', ev => {
  console.log(ev);
});


await TestModel.findOne(); // Prints "CommandStartedEvent { ... }"

// Alternatively, can listen to astra-db-ts events directly on the raw astra-db-ts collection
mongoose.connection.collection('test').collection.on('commandStarted', ev => {
  console.log(ev);
});

Astra-mongoose's tests use the above pattern to log requests sent to Data API. To debug commands sent to Data API in astra-mongoose's tests, you can enable test debug mode as follows:

env D=1 npm test

Build API Reference Documentation

API Documentation of this library is generated using jsdoc-to-markdown

Run below to generate API documentation. This takes the APIReference.hbs and the library code as input and generates APIReference.md file.

npm run build:docs

Publishing to npm registry

We are using npm-publish to handle publishing. So to publish a release to NPM, we need to

  • Create a branch out of 'main' and change version in the package.json as needed.
  • Run npm install (this will update src/version.ts file).
  • Run npm run build
  • Submit a PR and get that merged into main branch
  • Check out 'main' branch & pull the latest
 git checkout main
 git pull origin main
  • Then create a tag with the required version, prefixed with 'rel-'. This will trigger a workflow that publishes the current version to npm. For example: rel-0.2.0-ALPHA
git tag rel-x.y.z
git push origin rel-x.y.z