Skip to content

Latest commit

 

History

History
228 lines (158 loc) · 4.27 KB

api.md

File metadata and controls

228 lines (158 loc) · 4.27 KB

ChronDB API Reference

This document provides detailed information about the ChronDB API.

Core API

Creating a Database

(require '[chrondb.core :as chrondb])

;; Create with default configuration
(def db (chrondb/create-chrondb))

;; Create with custom configuration
(def db (chrondb/create-chrondb config))

Document Operations

Save Document

(chrondb/save db "key" value)

Parameters:

  • db: ChronDB instance
  • key: String identifier for the document
  • value: Document data (will be stored as JSON)

Returns: The saved document

Get Document

(chrondb/get db "key")

Parameters:

  • db: ChronDB instance
  • key: String identifier for the document

Returns: The document if found, nil otherwise

Delete Document

(chrondb/delete db "key")

Parameters:

  • db: ChronDB instance
  • key: String identifier for the document

Returns: true if document was deleted, false otherwise

Search Operations

Search Documents

(chrondb/search db query)
(chrondb/search db query {:limit 10 :offset 0})

Parameters:

  • db: ChronDB instance
  • query: Lucene query string
  • options: Optional map with:
    • :limit: Maximum number of results (default: 10)
    • :offset: Number of results to skip (default: 0)

Returns: Sequence of matching documents

Version Control Operations

Get Document History

(chrondb/history db "key")

Parameters:

  • db: ChronDB instance
  • key: String identifier for the document

Returns: Sequence of document versions with timestamps

Get Document at Point in Time

(chrondb/get-at db "key" timestamp)

Parameters:

  • db: ChronDB instance
  • key: String identifier for the document
  • timestamp: ISO-8601 timestamp string or java.time.Instant

Returns: The document as it existed at the specified time

Compare Document Versions

(chrondb/diff db "key" timestamp1 timestamp2)

Parameters:

  • db: ChronDB instance
  • key: String identifier for the document
  • timestamp1: First timestamp
  • timestamp2: Second timestamp

Returns: Differences between versions

Branch Operations

Create Branch

(chrondb/create-branch db "branch-name")

Parameters:

  • db: ChronDB instance
  • branch-name: Name of the new branch

Returns: Updated ChronDB instance

Switch Branch

(chrondb/switch-branch db "branch-name")

Parameters:

  • db: ChronDB instance
  • branch-name: Name of the branch to switch to

Returns: Updated ChronDB instance

Merge Branches

(chrondb/merge-branch db "source-branch" "target-branch")

Parameters:

  • db: ChronDB instance
  • source-branch: Branch to merge from
  • target-branch: Branch to merge into

Returns: Updated ChronDB instance

Transaction Operations

(chrondb/with-transaction [db]
  (chrondb/save db "key1" value1)
  (chrondb/save db "key2" value2))

All operations within the transaction block are atomic:

  • Either all succeed or all fail
  • Changes are only visible after successful commit
  • Automatic rollback on failure

Event Hooks

Register Hook

(chrondb/register-hook db :pre-save 
  (fn [doc] 
    ;; Hook logic here
    doc))

Available hook points:

  • :pre-save: Before saving a document
  • :post-save: After saving a document
  • :pre-delete: Before deleting a document
  • :post-delete: After deleting a document

Utility Functions

Health Check

(chrondb/health-check db)

Returns: Map with health status information

Backup

(chrondb/backup db "backup-path")

Creates a complete backup of the database

Statistics

(chrondb/stats db)

Returns: Map with database statistics

Error Handling

All API functions may throw the following exceptions:

  • ChronDBException: Base exception class
  • StorageException: Storage-related errors
  • IndexException: Index-related errors
  • ConfigurationException: Configuration errors
  • ValidationException: Data validation errors

Example error handling:

(try
  (chrondb/save db "key" value)
  (catch chrondb.exceptions.StorageException e
    (log/error "Storage error:" (.getMessage e)))
  (catch chrondb.exceptions.ValidationException e
    (log/error "Validation error:" (.getMessage e))))