@nxcd/doctordeprecated

Tool to operate @nxcd/paradox and help with controling time

Usage no npm install needed!

<script type="module">
  import nxcdDoctor from 'https://cdn.skypack.dev/@nxcd/doctor';
</script>

README

Doctor

build-status stability-unstable

Simple yet useful library to avoid manually manipulating event sourcing databases and paradox / tardis events and entities.

Installation

The recommended way to install doctor is through npm:

npm i -g @irontitan/doctor

Usage

Configuration file

Doctor works based on a configuration file that defines your applications, with its entities and repositories. Besides that, this file provides all the information doctor needs to connect to your database.

The default filename is doctor.config.js. The CLI will look for this file in the current working directory every time you invoke it, unless you pass the -f or --file flag. See global params

Structure

This is the minimum structure of a valid doctor configuration file:

const Person = require('path/to/your/event-entity/class')
const PersonRepository = require('path/to/your/event-repository/class')

module.exports = {
  mongodb: {
    uri: process.env.DATABASE_MONGODB_URI,
    dbName: process.env.DATABASE_MONGODB_DBNAME
  },
  entities: {
    person: {
      entity: Person,
      collection: 'people',
      repository: (mongodbConnection) => new PersonRepository(mongodbConnection)
    }
  }
}

Breaking it down:

  • mongodb
    • uri:
      • Type: String
      • Description: Mongodb URI (including connection schema)
      • Example: mongodb://localhost:27017
      • Required: true
    • dbName:
      • Tyoe: String
      • Description: Mongodb database name
      • Example: my-app
      • Required: true
  • entities
    • [entity-name] : String
      • entity:
        • Type: EventEntity
        • Description: Constructor of the entity class
        • Required: true
      • collection
        • Type: String
        • Description: Name of the collection for this entity
        • Required: true
      • repository:
        • Type: Function
        • Description: Function that receives a connection to mongodb and returns a specific EventRepository instance that will be used for all operations for this entity
        • example:
        • required: false

Important concepts

During following commands documentation, some concepts will be refered to. They are:

  • Entity: The name of an entity, as described on the config file
  • Entity id: The unique ID of a document of given entity
  • Event: The unique id of an event inside an events array, or an event name
  • Timestamp: A date and, optionally, time, in the format YYYY-MM-DD.HH:mm, as momentjs format tokens

Commands

All following commands are invoked the same way:

doctor <command> [params]

Global params

All commands (except by help) accept the following params:

  • -f, --file: Config file path. Overrides default ./doctor.config.js
  • -f, --verbose: Enables verbose output

help

asciicast

doctor-help

Prints help about commands

Usage
doctor help [command]
Params

No params supported

reduce

asciicast

doctor-reduce

Reduces the events of a given entity and returns its resulting state.

Usage
doctor reduce <entity> <entity-id> [--ignore <event>] [--until <timestamp>] [--save]
Params
  • -i, --ignore: Ignores given event. Can be repeated to ignore more than one event.
  • -u, --until: Ignores all events that happened after given timestamp. Takes precedence over --ignore.
  • -s, --save: Saves the result to the database. This will ask for your confirmation before making any changes.

All global params are supported

check

asciicast

doctor-check

This command goes through you config file an tells you if it's ok and usable by doctor.

Usage
doctor check
Params

All global params are supported

diff

asciicast

doctor-diff

This command calculates the time difference (in hours) between the first occurence of an event and the last occurence of another event.

Usage
doctor diff <entity> <entity-id> <first-event> <last-event>
Params

All global params are supported

entitites

asciicast

doctor-entities

This command lists all entities described by the config file

Usage
doctor entities
Params

All global params are supported

rebuild

asciicast

doctor-rebuild

This command reduces and updates the states of a whole collection

Usage
doctor rebuild <collection>
Params

All global params are supported

TODO

  • Write tests
  • Add ability to reduce multiple entities and even collections at once
  • Add ability to use custom script to manipulate entities
  • Make mongodb connection not required
  • Improve documentation about custom repositories

Contributing

PRs are, as always, very welcome.

Just follow StandardJS, use pnpm, and make sure you code builds (pnpm run build) before submitting.