DocumentRevisionService

reference

1 min readUpdated 2026-07-29

Kind: Service

Source: atloria-monorepo/apps/api/src/document/services/document-revision.service.ts

DocumentRevisionService manages historical snapshots of documents in the backend. It creates, retrieves, restores, counts, and removes revisions, enabling version history and recovery workflows for document updates.

Methods

Method	Signature	Returns	Description
`createRevision`	`createRevision(documentId: string, snapshot: RevisionSnapshot, userId: string, changeType: ChangeType)`	`Promise<DocumentRevision>`	Create a revision snapshot of a document
`getRevisions`	`getRevisions(documentId: string, limit: number, offset: number)`	`Promise<DocumentRevision[]>`	Get all revisions for a document with pagination
`getRevision`	`getRevision(revisionId: string)`	`Promise<DocumentRevision>`	Get a specific revision by ID
`restoreFromRevision`	`restoreFromRevision(documentId: string, revisionId: string, userId: string)`	`Promise<any>`	Restore a document from a specific revision
`getRevisionCount`	`getRevisionCount(documentId: string)`	`Promise<number>`	Get count of revisions for a document
`cleanupOldRevisions`	`cleanupOldRevisions(documentId: string, keepLast: number)`	`Promise<number>`	Cleanup old revisions beyond retention limit
`deleteAllRevisions`	`deleteAllRevisions(documentId: string)`	`Promise<number>`	Delete all revisions for a document (use with caution)

Dependencies

PrismaService

Where it refuses work

DocumentRevisionService stops the work with NotFoundException when !revision — “Revision not found”.
DocumentRevisionService stops the work with BadRequestException when revision.documentId !== documentId — “Revision does not belong to this document”.
DocumentRevisionService stops the work with NotFoundException when !document — “Document not found”.
DocumentRevisionService stops the work with an early return when allRevisions.length <= keepLast.

Diagram

mermaid
sequenceDiagram
  participant Client
  participant DocumentService
  participant RevisionService as DocumentRevisionService
  participant Database

  Client->>DocumentService: Update document
  DocumentService->>RevisionService: createRevision(document)
  RevisionService->>Database: Persist revision snapshot
  Database-->>RevisionService: DocumentRevision
  RevisionService-->>DocumentService: Created revision

  Client->>RevisionService: getRevisions(documentId)
  RevisionService->>Database: Query revisions by document
  Database-->>RevisionService: DocumentRevision[]
  RevisionService-->>Client: Revision history

  Client->>RevisionService: restoreFromRevision(revisionId)
  RevisionService->>Database: Load revision and update document
  Database-->>RevisionService: Restored document
  RevisionService-->>Client: Restored result

Usage

ts
import { Injectable } from '@nestjs/common';
import { DocumentRevisionService } from './document-revision.service';

@Injectable()
export class DocumentHistoryController {
  constructor(
    private readonly documentRevisionService: DocumentRevisionService,
  ) {}

  async getHistory(documentId: string) {
    return this.documentRevisionService.getRevisions(documentId);
  }

  async restore(documentId: string, revisionId: string) {
    return this.documentRevisionService.restoreFromRevision(
      documentId,
      revisionId,
    );
  }

  async pruneHistory(documentId: string) {
    const deletedCount =
      await this.documentRevisionService.cleanupOldRevisions(documentId);

    return { deletedCount };
  }
}

AI Coding Instructions

Create a revision before applying destructive or meaningful document updates so the previous document state remains recoverable.
Scope revision queries, counts, cleanup, and deletion operations to the correct document identifier; never delete revisions globally unless explicitly intended.
Preserve document ownership and authorization checks in the calling controller or service before exposing revision history or restore operations.
Use restoreFromRevision() as the canonical restoration path rather than manually copying revision fields into a document.
Run cleanupOldRevisions() according to the configured retention policy and verify that the newest required revisions are retained.

Relationships

DEPENDS_ON → PrismaService

Referenced By

DocumentController (DEPENDS_ON)
DocumentModule (MODULE_PROVIDES)
DocumentService (DEPENDS_ON)

Was this page helpful?

Download as PDF

ADocs generated by Atloria — from the code, always in sync →