Usage

This documentation provides comprehensive guidance on how to use the deta library, a Clojure library designed to interact with the Deta Base, a NoSQL database service.

It covers installation, getting started, example usage, and testing. The documentation is structured to ensure users can easily navigate through the content and understand how to integrate and utilize the library in their projects.

Table of Contents

1. Introduction
2. Installation
   • Leiningen/Boot
   • Clojure CLI/deps.edn
   • Gradle
   • Maven
3. Getting Started
4. Example Usage
   • Initializing the Database Connection
   • Using the put Function
     • Basic Usage
     • Handling Non-Map Values
     • Return Value and Exceptions
   • Using the get Function
     • Basic Usage
     • Return Value and Exceptions
   • Use Cases
     • Inserting Data
     • Retrieving Data
5. Testing

Introduction

This section provides an overview of the deta library and its purpose. It introduces the library as a tool for interacting with the Deta Base, a NoSQL database service, and outlines the benefits of using this library in Clojure projects.

Installation

Leiningen/Boot

Add the following to your project.clj dependencies:

[com.adaiasmagdiel/deta "0.0.1"]

Clojure CLI/deps.edn

Add the following to your deps.edn dependencies:

com.adaiasmagdiel/deta {:mvn/version "0.0.1"}

Gradle

Add the following to your build.gradle dependencies:

implementation("com.adaiasmagdiel:deta:0.0.1")

Maven

Add the following to your pom.xml dependencies:

<dependency>
 <groupId>com.adaiasmagdiel</groupId>
 <artifactId>deta</artifactId>
 <version>0.0.1</version>
</dependency>

Getting Started

To use the deta.base namespace, you need to include it in your project's dependencies and require it in your code. The namespace use clojure.string, clojure.data.json, and clj-http.client for its operations.

(ns your-namespace
 (:require [deta.base :as base]))

Example Usage

Initializing the Database Connection

(def db (base/base "a0abcyxzxsr_aSecretValue" "items"))

Using the put Function

Basic Usage

(base/put db {:a 1 :b 2} "item-key")
(base/put db {:a 1 :b 2}) ; The key is automatically generated on the server

Handling Non-Map Values

If the data passed to the put function is not a map, it is automatically wrapped in a map with the key "value". This allows for flexibility in the types of data that can be stored in the database.

Return Value and Exceptions

The put function returns a map containing the inserted data. If a key is not provided, the server automatically generates one. The returned map includes the data and the generated key.

The put function throws an Exception if the data type is not supported or if the deta-key is invalid or not provided.

Example with Non-Map Value

(base/put db "Hello, World!") ; Automatically wrapped in {"value" "Hello, World!"}

Using the get Function

Basic Usage

(base/get db "item-key")

Return Value and Exceptions

The get function returns a map containing the retrieved data if the key exists, or nil if the key does not exist or an error occurs.

The get function throws an Exception if the deta-key is invalid or not provided, or if the key is empty or not provided.

Use Cases

Inserting Data

The put function's ability to accept any data type makes it versatile for different use cases. Here are examples of inserting various data types:

(base/put db {:name "John Doe" :age 30}) ; Inserting a map
(base/put db "Hello, World!") ; Inserting a string
(base/put db 42) ; Inserting an integer
(base/put db 3.14) ; Inserting a float
(base/put db true) ; Inserting a boolean
(base/put db nil) ; Inserting nil

Retrieving Data

To retrieve data from the database, you can use the get function. Here's an example of how to retrieve an item by its key:

(base/get db "user-123")

Testing

The deta.base-test namespace includes tests for both the base and put functions. These tests cover various scenarios, including valid and invalid deta-key inputs, different data types for the put function, and the behavior of the put function when a key is provided.

Running Tests

To run the tests, execute the following command in your project directory:

lein test