datahike-browser-tests 1.0.0

package/examples/basic/src/examples/time_travel.clj

@@ -0,0 +1,185 @@
+(ns examples.time-travel
+  (:require [datahike.api :as d]))
+
+;; define schema
+(def schema [{:db/ident       :name
+              :db/valueType   :db.type/string
+              :db/unique      :db.unique/identity
+              :db/index       true
+              :db/cardinality :db.cardinality/one}
+             {:db/ident       :age
+              :db/valueType   :db.type/long
+              :db/cardinality :db.cardinality/one}])
+
+;; define base configuration we can connect to
+(def cfg {:store {:backend :mem
+                  :id "time-travel"}
+          :keep-history? true})
+
+;; cleanup any previous data
+(d/delete-database cfg)
+
+;; create the database with default configuration and above schema
+(d/create-database cfg)
+
+;; connect to the database
+(def conn (d/connect cfg))
+
+;; add the schema
+(d/transact conn schema)
+
+;; add age and name data
+(d/transact conn [{:name "Alice" :age 25} {:name "Bob" :age 30}])
+
+;; let's find name and age of all data
+(def query '[:find ?n ?a :where [?e :name ?n] [?e :age ?a]])
+
+;; search current data without any new data
+(d/q query @conn);; => #{["Alice" 25] ["Bob" 30]}
+
+(def first-date (java.util.Date.))
+
+;; let's change something
+(d/transact conn [{:db/id [:name "Alice"] :age 30}])
+
+;; search for current data of Alice
+(d/q query @conn);; => #{["Alice" 30] ["Bob" 30]}
+
+;; now we search within historical data
+(d/q query (d/history @conn));; => #{["Alice" 30] ["Alice" 25] ["Bob" 30]}
+
+;; let's find the dates for each attribute additions.
+;; :db/txInstant is an attribute of the meta entity added to each transaction
+;; and can be treated just as any other data
+(d/q '[:find ?a ?v ?t ?op
+       :in $ [?a ...]
+       :where
+       [?e ?a ?v ?tx ?op]
+       [?tx :db/txInstant ?t]]
+     (d/history @conn )
+     [:name :age]);; => #{[:age 25 #inst "2021-11-04T13:46:54.972-00:00" false]
+;;      [:age 25 #inst "2021-11-04T13:46:38.223-00:00" true]
+;;      [:name "Alice" #inst "2021-11-04T13:46:38.223-00:00" true]
+;;      [:age 30 #inst "2021-11-04T13:46:38.223-00:00" true]
+;;      [:name "Bob" #inst "2021-11-04T13:46:38.223-00:00" true]
+;;      [:age 30 #inst "2021-11-04T13:46:54.972-00:00" true]}
+
+
+;; next let's get the current data of a specific time
+(d/q query (d/as-of @conn first-date));; => #{["Alice" 25] ["Bob" 30]}
+
+;; pull is also supported
+(d/pull (d/as-of @conn first-date) '[*] [:name "Alice"]);; => {:db/id 3, :age 25, :name "Alice"}
+
+;; now we want to know any additions after a specific time
+(d/q query (d/since @conn first-date))
+;; => {}, because :name was transacted before the first date
+
+;; let's build a query where we use the latest db to find the name and the since db to find out who's age changed
+(d/q '[:find ?n ?a
+       :in $ $since
+       :where
+       [$ ?e :name ?n]
+       [$since ?e :age ?a]]
+     @conn
+     (d/since @conn first-date));; => #{["Alice" 30]}
+
+;; let's retract Bob from the current view
+(d/transact conn [[:db/retractEntity [:name "Bob"]]])
+
+;; Only Alice remains
+(d/q query @conn);; => #{["Alice" 30]}
+
+;; Let's have a look at the history, Bob should be there
+(d/q query (d/history @conn));; => #{["Alice" 30] ["Alice" 25] ["Bob" 30]}
+
+;; now we can find when Bob was added and when he was removed
+(d/q '[:find ?d ?op
+       :in $ ?e
+       :where
+       [?e _ _ ?t ?op]
+       [?t :db/txInstant ?d]]
+     (d/history @conn)
+     [:name "Bob"])
+;; => #{[#inst "2021-11-04T13:49:35.353-00:00" false]
+;;      [#inst "2021-11-04T13:46:38.223-00:00" true]}
+
+;; let's see who else was added with Bob
+(d/q '[:find ?n
+       :in $ ?e
+       :where
+       [?e _ _ ?t true]
+       [?e2 :name ?n]] (d/history @conn) [:name "Bob"]);; => #{["Alice"] ["Bob"]}
+
+;; let's find the retracted entity ID, its attribute, value, and the date of the changes
+(d/q '[:find ?e ?a ?v ?tx
+       :where
+       [?e ?a ?v ?r false]
+       [?r :db/txInstant ?tx]]
+     (d/history @conn))
+;; => #{[4 :age 30 #inst "2021-11-04T13:49:35.353-00:00"]
+;;      [3 :age 25 #inst "2021-11-04T13:46:54.972-00:00"]
+;;      [4 :name "Bob" #inst "2021-11-04T13:49:35.353-00:00"]}
+
+;; you can use db fns to compare dates within datalog: `before?` and `after?`.
+;; let's find all transactions after the first date:
+(d/q '[:find ?e ?a ?v
+       :in $ ?fd
+       :where
+       [?e ?a ?v ?t]
+       [?t :db/txInstant ?tx]
+       [(after? ?tx ?fd)]]
+     @conn
+     first-date)
+;; => #{[536870916 :db/txInstant #inst "2021-11-04T13:49:35.353-00:00"]
+;;      [3 :age 30]
+;;      [536870915 :db/txInstant #inst "2021-11-04T13:46:54.972-00:00"]}
+
+;; for convenience you may also use the `<`, `>`, `<=`, `>=` functions
+(d/q '[:find ?e ?a ?v
+       :in $ ?fd
+       :where
+       [?e ?a ?v ?t]
+       [?t :db/txInstant ?tx]
+       [(> ?tx ?fd)]]
+     @conn
+     first-date)
+;; => #{[536870916 :db/txInstant #inst "2021-11-04T13:49:35.353-00:00"]
+;;      [3 :age 30]
+;;      [536870915 :db/txInstant #inst "2021-11-04T13:46:54.972-00:00"]}
+
+;; since retraction only removes data from the current view of the data, you may use `purge` to completely remove data
+(d/transact conn [[:db/purge [:name "Alice"] :age 30]])
+
+;; Alice's age 30 is not there anymore
+(d/q query (d/history @conn));; => #{["Alice" 25] ["Bob" 30]}
+
+;; let's remove Alice's entity completely from our database
+(d/transact conn [[:db.purge/entity [:name "Alice"]]])
+
+;; Only Bob remains in the history
+(d/q query (d/history @conn));; => #{["Bob" 30]}
+
+;; let's add some more data
+(d/transact conn [{:name "Charlie" :age 45}])
+
+(d/q query @conn);; => #{["Charlie" 45]}
+
+;; store the current date
+(def before-date (java.util.Date.))
+
+;; update Charlie's age
+(d/transact conn [{:db/id [:name "Charlie"] :age 50}])
+
+(d/transact conn [{:db/id [:name "Charlie"] :age 55}])
+
+(d/q query @conn);; => #{["Charlie" 55]}
+(d/q query (d/history @conn));; => #{["Bob" 30] ["Charlie" 50] ["Charlie" 45] ["Charlie" 55]}
+
+;; now let's purge data from temporal index that was added to the temporal index before a specific date
+(d/transact conn [[:db.history.purge/before before-date]])
+
+;; Charlie's current age should remain since it is not in the temporal index
+(d/q query @conn);; => #{["Charlie" 55]}
+;; Only the latest data after before-date should be in the history, Charlie with age 45 because it was removed after before-date
+(d/q query (d/history @conn));; => #{["Charlie" 50] ["Charlie" 45] ["Charlie" 55]}

package/examples/java/.settings/org.eclipse.core.resources.prefs

@@ -0,0 +1,3 @@
+eclipse.preferences.version=1
+encoding//src/main/java=UTF-8
+encoding/<project>=UTF-8

package/examples/java/.settings/org.eclipse.jdt.apt.core.prefs

@@ -0,0 +1,2 @@
+eclipse.preferences.version=1
+org.eclipse.jdt.apt.aptEnabled=false

package/examples/java/.settings/org.eclipse.jdt.core.prefs

@@ -0,0 +1,9 @@
+eclipse.preferences.version=1
+org.eclipse.jdt.core.compiler.codegen.targetPlatform=17
+org.eclipse.jdt.core.compiler.compliance=17
+org.eclipse.jdt.core.compiler.problem.enablePreviewFeatures=disabled
+org.eclipse.jdt.core.compiler.problem.forbiddenReference=warning
+org.eclipse.jdt.core.compiler.problem.reportPreviewFeatures=ignore
+org.eclipse.jdt.core.compiler.processAnnotations=disabled
+org.eclipse.jdt.core.compiler.release=disabled
+org.eclipse.jdt.core.compiler.source=17

package/examples/java/.settings/org.eclipse.m2e.core.prefs

@@ -0,0 +1,4 @@
+activeProfiles=
+eclipse.preferences.version=1
+resolveWorkspaceProjects=true
+version=1

package/examples/java/README.md

@@ -0,0 +1,162 @@
+# Datahike Java Examples
+
+This directory contains example applications demonstrating the Datahike Java API.
+
+## Prerequisites
+
+- Java 17 or higher (required for text blocks and modern Java features)
+- Maven 3.6+
+
+## Running the Examples
+
+### Option 1: Maven Exec (Recommended)
+
+Run examples directly with Maven:
+
+```bash
+# Quick Start
+mvn compile exec:java -Dexec.mainClass="examples.QuickStart"
+
+# Schema Example
+mvn compile exec:java -Dexec.mainClass="examples.SchemaExample"
+
+# Time Travel Example
+mvn compile exec:java -Dexec.mainClass="examples.TimeTravelExample"
+```
+
+### Option 2: Build and Run JAR
+
+Build the project and run the JAR:
+
+```bash
+# Build
+mvn clean package
+
+# Run (using QuickStart as main class from pom.xml)
+java -jar target/datahike-java-examples-1.0.0-SNAPSHOT.jar
+
+# Or run specific examples
+java -cp target/datahike-java-examples-1.0.0-SNAPSHOT.jar examples.SchemaExample
+```
+
+### Option 3: IDE
+
+Import the Maven project into your IDE (IntelliJ IDEA, Eclipse, VSCode) and run the main classes directly.
+
+## Examples
+
+### QuickStart.java
+
+Basic introduction to Datahike:
+- Database configuration with builder pattern
+- Creating and connecting to databases
+- Transacting data with Java Maps
+- Querying with Datalog
+- Updates and cleanup
+
+**Key concepts:** Builder pattern, basic queries, CRUD operations
+
+### SchemaExample.java
+
+Schema definition and validation:
+- Defining attributes with type constraints
+- Unique constraints (identity vs value)
+- Reference types for relationships
+- Cardinality (one vs many)
+- Using Keywords constants
+
+**Key concepts:** Schema definition, relationships, data validation
+
+### TimeTravelExample.java
+
+Historical queries and time travel:
+- Querying database state at specific points in time
+- Using `asOf` for point-in-time queries
+- Using `since` for change tracking
+- Querying full history
+- Transaction metadata
+
+**Key concepts:** Immutability, history, audit trails
+
+## Project Structure
+
+```
+examples/java/
+├── pom.xml                                 # Maven configuration
+├── README.md                               # This file
+└── src/main/java/examples/
+    ├── QuickStart.java                     # Basic usage
+    ├── SchemaExample.java                  # Schema definition
+    └── TimeTravelExample.java              # Time travel queries
+```
+
+## Using Datahike in Your Project
+
+To use Datahike in your own Maven project, add to your `pom.xml`:
+
+```xml
+<repositories>
+    <repository>
+        <id>clojars</id>
+        <url>https://repo.clojars.org/</url>
+    </repository>
+</repositories>
+
+<dependencies>
+    <dependency>
+        <groupId>io.replikativ</groupId>
+        <artifactId>datahike</artifactId>
+        <version>LATEST_VERSION</version>
+    </dependency>
+</dependencies>
+```
+
+For Gradle:
+
+```gradle
+repositories {
+    maven { url "https://repo.clojars.org/" }
+}
+
+dependencies {
+    implementation 'io.replikativ:datahike:LATEST_VERSION'
+}
+```
+
+**Note:** Replace `LATEST_VERSION` with the latest published version from [Clojars](https://clojars.org/io.replikativ/datahike).
+
+## Key Java API Classes
+
+- **`Datahike`** - Main API with all database operations
+- **`Database`** - Fluent builder for configuration
+- **`Keywords`** - Pre-defined constants for schema
+- **`SchemaFlexibility`** - Enum for schema modes
+- **`Util`** - Low-level utilities (map, vec, kwd)
+- **`EDN`** - EDN data type constructors
+
+## Further Reading
+
+- [Java API Documentation](../../doc/java-api.md) - Comprehensive API guide
+- [Main README](../../README.md) - Project overview
+- [Schema Guide](../../doc/schema.md) - Detailed schema documentation
+- [Storage Backends](../../doc/storage-backends.md) - Backend configuration
+- [Datalog Tutorial](https://docs.datomic.com/on-prem/query.html) - Query language
+
+## Troubleshooting
+
+**Build fails with "Could not find artifact"**
+- Ensure Clojars repository is configured
+- Check internet connection
+- Try `mvn clean install -U` to force update
+
+**Runtime errors about Clojure**
+- Datahike includes Clojure as a dependency
+- Check for dependency conflicts with `mvn dependency:tree`
+
+**ClassCastException in query results**
+- Query results are Clojure collections (Set, List, Map)
+- Cast appropriately: `(Set<?>) Datahike.q(...)`
+
+## License
+
+Eclipse Public License 1.0 (EPL-1.0)

package/examples/java/pom.xml

@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>org.replikativ.datahike</groupId>
+    <artifactId>datahike-java-examples</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <packaging>jar</packaging>
+
+    <name>Datahike Java Examples</name>
+    <description>Example applications demonstrating Datahike Java API usage</description>
+
+    <properties>
+        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.target>17</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <datahike.version>0.7.1663</datahike.version>
+    </properties>
+
+    <repositories>
+        <repository>
+            <id>clojars</id>
+            <name>Clojars</name>
+            <url>https://repo.clojars.org/</url>
+        </repository>
+    </repositories>
+
+    <dependencies>
+        <!-- Datahike -->
+        <dependency>
+            <groupId>org.replikativ</groupId>
+            <artifactId>datahike</artifactId>
+            <version>${datahike.version}</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.11.0</version>
+            </plugin>
+
+            <!-- Create executable JAR -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-jar-plugin</artifactId>
+                <version>3.3.0</version>
+                <configuration>
+                    <archive>
+                        <manifest>
+                            <mainClass>examples.QuickStart</mainClass>
+                        </manifest>
+                    </archive>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>

package/examples/java/src/main/java/examples/QuickStart.java

@@ -0,0 +1,115 @@
+package examples;
+
+import datahike.java.Datahike;
+import datahike.java.Database;
+import datahike.java.SchemaFlexibility;
+
+import java.util.*;
+
+/**
+ * Quick start example demonstrating basic Datahike usage.
+ *
+ * This example shows:
+ * - Database configuration with builder pattern
+ * - Creating and connecting to a database
+ * - Transacting data
+ * - Querying with Datalog
+ * - Cleanup
+ */
+public class QuickStart {
+    public static void main(String[] args) {
+        System.out.println("=== Datahike Java Quick Start ===\n");
+
+        // 1. Configure database with builder pattern
+        System.out.println("1. Configuring database...");
+        Map<String, Object> config = Database.memory(UUID.randomUUID())
+            .schemaFlexibility(SchemaFlexibility.READ)
+            .keepHistory(true)
+            .name("quickstart-example")
+            .build();
+
+        // 2. Create and connect to database
+        System.out.println("2. Creating database...");
+        Datahike.createDatabase(config);
+
+        System.out.println("3. Connecting to database...");
+        Object conn = Datahike.connect(config);
+
+        // 3. Transact data using Java Maps
+        System.out.println("4. Adding data...");
+        Datahike.transact(conn, List.of(
+            Map.of("name", "Alice", "age", 30, "city", "Berlin"),
+            Map.of("name", "Bob", "age", 25, "city", "London"),
+            Map.of("name", "Charlie", "age", 35, "city", "Berlin")
+        ));
+
+        // 4. Query data with Datalog
+        System.out.println("5. Querying data...");
+
+        // Find all people
+        Set<?> allPeople = (Set<?>) Datahike.q(
+            "[:find ?name ?age :where [?e :name ?name] [?e :age ?age]]",
+            Datahike.deref(conn)
+        );
+        System.out.println("All people: " + allPeople);
+
+        // Find people in Berlin
+        Set<?> berliners = (Set<?>) Datahike.q(
+            """
+            [:find ?name ?age
+             :where
+             [?e :name ?name]
+             [?e :age ?age]
+             [?e :city "Berlin"]]
+            """,
+            Datahike.deref(conn)
+        );
+        System.out.println("People in Berlin: " + berliners);
+
+        // Find people over 30
+        Set<?> over30 = (Set<?>) Datahike.q(
+            """
+            [:find ?name
+             :where
+             [?e :name ?name]
+             [?e :age ?age]
+             [(>= ?age 30)]]
+            """,
+            Datahike.deref(conn)
+        );
+        System.out.println("People over 30: " + over30);
+
+        // 5. Update data
+        System.out.println("\n6. Updating data...");
+        // Find Alice's entity ID first
+        Set<?> aliceResult = (Set<?>) Datahike.q(
+            "[:find ?e :where [?e :name \"Alice\"]]",
+            Datahike.deref(conn)
+        );
+
+        if (!aliceResult.isEmpty()) {
+            Object aliceId = ((List<?>) aliceResult.iterator().next()).get(0);
+
+            // Update Alice's age
+            Datahike.transact(conn, List.of(
+                Map.of(":db/id", aliceId, "age", 31)
+            ));
+
+            System.out.println("Updated Alice's age to 31");
+        }
+
+        // Query again to see the update
+        Set<?> updated = (Set<?>) Datahike.q(
+            "[:find ?name ?age :where [?e :name \"Alice\"] [?e :age ?age] [?e :name ?name]]",
+            Datahike.deref(conn)
+        );
+        System.out.println("Alice after update: " + updated);
+
+        // 6. Cleanup
+        System.out.println("\n7. Cleaning up...");
+        Datahike.deleteDatabase(config);
+
+        System.out.println("\n=== Example completed successfully! ===");
+        System.exit(0);
+    }
+}

package/examples/java/src/main/java/examples/SchemaExample.java

@@ -0,0 +1,148 @@
+package examples;
+
+import datahike.java.Datahike;
+import datahike.java.Database;
+import datahike.java.SchemaFlexibility;
+
+import java.util.*;
+
+import static datahike.java.Keywords.*;
+import static datahike.java.Util.*;
+
+/**
+ * Example demonstrating schema definition and validation.
+ *
+ * Shows:
+ * - Defining schema attributes with Keywords constants
+ * - Using unique constraints
+ * - Reference types for relationships
+ * - Cardinality (one vs many)
+ */
+public class SchemaExample {
+    public static void main(String[] args) {
+        System.out.println("=== Schema Definition Example ===\n");
+
+        // Define schema using Keywords constants
+        System.out.println("1. Defining schema...");
+        Object schema = vec(
+            // Person name - unique identity
+            map(
+                DB_IDENT, kwd(":person/name"),
+                DB_VALUE_TYPE, STRING,
+                DB_CARDINALITY, ONE,
+                DB_UNIQUE, UNIQUE_IDENTITY,
+                DB_DOC, "Person's full name (unique)"
+            ),
+            // Person email - unique value
+            map(
+                DB_IDENT, kwd(":person/email"),
+                DB_VALUE_TYPE, STRING,
+                DB_CARDINALITY, ONE,
+                DB_UNIQUE, UNIQUE_VALUE,
+                DB_DOC, "Person's email address (unique)"
+            ),
+            // Person age
+            map(
+                DB_IDENT, kwd(":person/age"),
+                DB_VALUE_TYPE, LONG,
+                DB_CARDINALITY, ONE,
+                DB_DOC, "Person's age in years"
+            ),
+            // Person friends - many references
+            map(
+                DB_IDENT, kwd(":person/friends"),
+                DB_VALUE_TYPE, REF,
+                DB_CARDINALITY, MANY,
+                DB_DOC, "Person's friends (entity references)"
+            ),
+            // Person skills - many strings
+            map(
+                DB_IDENT, kwd(":person/skills"),
+                DB_VALUE_TYPE, STRING,
+                DB_CARDINALITY, MANY,
+                DB_DOC, "Person's skills"
+            )
+        );
+
+        // Create database with initial schema
+        Map<String, Object> config = Database.memory(UUID.randomUUID())
+            .initialTx(schema)
+            .build();
+
+        Datahike.createDatabase(config);
+        Object conn = Datahike.connect(config);
+
+        // 2. Add data respecting the schema
+        System.out.println("2. Adding people with relationships...");
+
+        // Using modern Java API - strings auto-convert to keywords
+        Datahike.transact(conn, List.of(
+            // Alice
+            Map.of(
+                "person/name", "Alice",
+                "person/email", "alice@example.com",
+                "person/age", 30L,
+                "person/skills", List.of("Java", "Clojure", "Datalog")
+            ),
+            // Bob
+            Map.of(
+                "person/name", "Bob",
+                "person/email", "bob@example.com",
+                "person/age", 25L,
+                "person/skills", List.of("Python", "SQL")
+            )
+        ));
+
+        // 3. Use unique identity to reference and update
+        System.out.println("3. Using unique identity for upsert...");
+
+        Datahike.transact(conn, List.of(
+            Map.of(
+                "person/name", "Alice",  // Upsert by unique identity
+                "person/age", 31L        // Update age
+            )
+        ));
+
+        // 4. Query relationships
+        System.out.println("4. Querying people and skills...");
+
+        Set<?> peopleWithSkills = (Set<?>) Datahike.q(
+            """
+            [:find ?name ?skill
+             :where
+             [?e :person/name ?name]
+             [?e :person/skills ?skill]]
+            """,
+            Datahike.deref(conn)
+        );
+
+        System.out.println("People and their skills:");
+        peopleWithSkills.forEach(System.out::println);
+
+        // 5. Count aggregates
+        Object skillCounts = Datahike.q(
+            """
+            [:find ?name (count ?skill)
+             :where
+             [?e :person/name ?name]
+             [?e :person/skills ?skill]]
+            """,
+            Datahike.deref(conn)
+        );
+
+        System.out.println("\nSkill counts per person:");
+        System.out.println(skillCounts);
+
+        // 6. Verify schema
+        System.out.println("\n5. Retrieving schema...");
+        Map<?, ?> dbSchema = (Map<?, ?>) Datahike.schema(Datahike.deref(conn));
+
+        System.out.println("Schema has " + dbSchema.size() + " attributes defined");
+
+        // Cleanup
+        Datahike.deleteDatabase(config);
+
+        System.out.println("\n=== Example completed successfully! ===");
+        System.exit(0);
+    }
+}