@neoma/argos

NestJS-idiomatic audit trails. Argos (Odysseus's faithful dog -- waited twenty years and never forgot) tracks who changed your entities and when.

Installation

npm install @neoma/argos

Peer dependencies: @nestjs/common, @nestjs/core, typeorm

Quick Start

1. Register the module

import { ArgosModule } from "@neoma/argos"

@Module({
  imports: [
    ArgosModule.forRoot({
      resolveActor: (req) =>
        req.principal ? `principal:${req.principal.id}` : null,
    }),
  ],
})
export class AppModule {}

Or with async configuration:

ArgosModule.forRootAsync({
  useFactory: (config: ConfigService) => ({
    resolveActor: (req) =>
      req.principal ? `principal:${req.principal.id}` : null,
  }),
  inject: [ConfigService],
})

2. Decorate your entities

import { CreatedBy, UpdatedBy } from "@neoma/argos"

@Entity()
export class Invoice {
  @PrimaryGeneratedColumn("uuid")
  public id!: string

  @Column()
  public amount!: number

  @CreatedBy()
  public createdBy!: string

  @UpdatedBy()
  public updatedBy!: string
}

That's it. createdBy is set on insert, updatedBy is set on every save.

Configuration

ArgosOptions

Option	Type	Default	Description
resolveActor	(req: Request) => string | null | undefined | Promise<string | null | undefined>	undefined	Extracts the actor from the request. Return null or undefined to use the default.
defaultActor	string	"system"	Actor used when resolveActor is absent or returns null or undefined.

Actor format

Actors are prefixed strings -- not foreign keys:

• principal:uuid -- authenticated user
• api:name -- API key
• webhook:source -- webhook caller
• system -- unauthenticated or background

Known Constraints

• Must use repository.save() / repository.remove() -- manager.update(), QueryBuilder, etc. bypass entity listeners silently.
• @CreatedBy() sets on insert and is never overwritten on update.
• @UpdatedBy() sets on every save() -- both insert and update.