Document History

Retrieve the history of changes for a document.

Definition

await zkdb.db(databaseName: string)
          .collection(collectionName: string)
          .findOne(filter: Record<string, any>)
          .history(pagination?: TPagination): Promise<TPaginationReturn<TDocumentHistory[]>>;

Parameters

• pagination (TPagination, optional): { limit: number; offset: number }.

Returns

• Promise<TPaginationReturn<TDocumentHistory[]>>: Returns a chronological audit trail of all changes made to the document, including creation, updates, and deletion. Each history entry contains the operation type, timestamp, field changes, and the user who performed the action. This provides complete traceability for compliance and debugging purposes.

type TDocumentHistory = {
  docId: string;
  operation: string;
  timestamp: string;
  data: Record<string, any>;
};

Example

import { ZkDatabase } from 'zkdb';

const zkdb = await ZkDatabase.connect({
  userName: "chiro-user",
  privateKey: "EKFTciRxyxshZjimay9sktsn7v5PvmC5zPq7q4JnitHUytxUVnFP",
  environment: "node",
  // This URL is for test environment
  url: "https://api.zkdatabase.org/graphql",
});

await zkdb.auth.signIn();

const dbTest = zkdb.db('zkdb_test');
const collection = dbTest.collection('Shirt');
const doc = await collection.findOne({ name: 'Shirt 1' });
const history = await doc.history({ limit: 5, offset: 0 });
console.log('Document history:', history);

await zkdb.auth.signOut();

Result:

Document history: {
  "total": 3,
  "offset": 0,
  "data": [
    {
      "docId": "6t7...",
      "operation": "INSERT",
      "timestamp": "2025-01-01T00:00:00.000Z",
      "data": { "name": "Shirt 1", "price": 15 }
    },
    {
      "docId": "6t7...",
      "operation": "UPDATE",
      "timestamp": "2025-01-02T00:00:00.000Z",
      "data": { "price": 25 }
    }
  ]
}