datomic-flare 1.0.0

data/docs/README.md

@@ -0,0 +1,360 @@
+# Datomic Flare for Ruby
+
+A Ruby gem for interacting with [Datomic](https://www.datomic.com) through [Datomic Flare](https://github.com/gbaptista/datomic-flare).
+
+![The image features a logo with curved lines forming a ruby, suggesting distortion and movement like space-time.](https://media.githubusercontent.com/media/gbaptista/assets/refs/heads/main/ruby-datomic-flare/ruby-datomic-flare-canvas.png)
+
+_This is not an official Datomic project or documentation and it is not affiliated with Datomic in any way._
+
+## TL;DR and Quick Start
+
+```ruby
+gem '{{ gem.name }}', '~> {{ gem.version }}'
+```
+
+```ruby
+require '{{ gem.name }}'
+
+client = Flare.new(credentials: { address: 'http://localhost:3042' })
+```
+
+```ruby
+client.dsl.transact_schema!(
+  {
+    book: {
+      title: { type: :string, doc: 'The title of the book.' },
+      genre: { type: :string, doc: 'The genre of the book.' }
+    }
+  }
+)
+
+client.dsl.assert_into!(
+  :book,
+  {
+    title: 'The Tell-Tale Heart',
+    genre: 'Horror'
+  }
+)
+
+client.dsl.query(
+  datalog: <<~EDN
+    [:find ?e ?title ?genre
+     :where [?e :book/title ?title]
+            [?e :book/genre ?genre]]
+  EDN
+)
+```
+
+```ruby
+[[4611681620380877802, 'The Tell-Tale Heart', 'Horror']]
+```
+
+{{ index }}
+
+## Flare
+
+### Creating a Client
+
+```ruby
+require '{{ gem.name }}'
+
+client = Flare.new(credentials: { address: 'http://localhost:3042' })
+```
+
+### Meta
+
+```ruby
+client.meta
+```
+
+```ruby
+{
+  'meta' =>
+    {
+      'at' => '2024-09-29T13:52:52.252882446Z',
+      'mode' => 'peer',
+      'took' => { 'milliseconds' => 0.377446 }
+    },
+  'data' =>
+  {
+    'mode' => 'peer',
+    'datomic-flare' => '1.0.0',
+    'org.clojure/clojure' => '1.12.0',
+    'com.datomic/peer' => '1.0.7187',
+    'com.datomic/client-pro' => '1.0.81'
+  }
+}
+```
+
+{{ dsl }}
+
+{{ api }}
+
+## Development
+
+```bash
+bundle
+rubocop -A
+
+```
+
+### Publish to RubyGems
+
+```bash
+gem build {{ gem.name }}.gemspec
+
+gem signin
+
+gem push {{ gem.name }}-{{ gem.version }}.gem
+
+```
+
+### Setup for Tests and Documentation
+
+Tests run against real Datomic databases, and documentation (README) is generated by interacting with real Datomic databases.
+
+To accomplish that, we need to have [Datomic](https://github.com/gbaptista/datomic-pro-docker) and [Flare](https://github.com/gbaptista/datomic-flare) running.
+
+**TL;DR:**
+
+```bash
+git clone https://github.com/gbaptista/datomic-pro-docker.git
+
+cd datomic-pro-docker
+
+cp compose/flare-dev.yml docker-compose.yml
+
+docker compose up -d datomic-storage
+
+docker compose run datomic-tools psql \
+  -f bin/sql/postgres-table.sql \
+  -h datomic-storage \
+  -U datomic-user \
+  -d my-datomic-storage
+
+docker compose up -d datomic-transactor
+
+docker compose run datomic-tools clojure -M -e "$(cat <<'CLOJURE'
+  (require '[datomic.api :as d])
+  
+  (d/create-database "datomic:sql://my-datomic-database?jdbc:postgresql://datomic-storage:5432/my-datomic-storage?user=datomic-user&password=unsafe")
+
+  (d/create-database "datomic:sql://my-datomic-database-test?jdbc:postgresql://datomic-storage:5432/my-datomic-storage?user=datomic-user&password=unsafe")
+
+  (d/create-database "datomic:sql://my-datomic-database-test-green?jdbc:postgresql://datomic-storage:5432/my-datomic-storage?user=datomic-user&password=unsafe")
+
+  (System/exit 0)
+CLOJURE
+)"
+
+docker compose up -d datomic-peer-server
+
+docker compose up -d datomic-flare-peer datomic-flare-client
+
+```
+
+```bash
+curl -s http://localhost:3042/meta \
+  -X GET \
+  -H "Content-Type: application/json"  \
+| jq
+
+```
+
+```json
+{
+  "data": {
+    "mode": "peer"
+  }
+}
+
+```
+
+```bash
+curl -s http://localhost:3043/meta \
+  -X GET \
+  -H "Content-Type: application/json"  \
+| jq
+
+```
+
+```json
+{
+  "data": {
+    "mode": "client"
+  }
+}
+
+```
+
+You are ready to run tests and generate documentation.
+
+**Detailed instructions:**
+
+Clone the [datomic-pro-docker](https://github.com/gbaptista/datomic-pro-docker) repository and copy the Docker Compose template:
+
+```bash
+git clone https://github.com/gbaptista/datomic-pro-docker.git
+
+cd datomic-pro-docker
+
+cp compose/flare-dev.yml docker-compose.yml
+
+```
+
+Start PostgreSQL as Datomic's storage service:
+
+```bash
+docker compose up -d datomic-storage
+
+docker compose logs -f datomic-storage
+
+```
+
+Create the table for Datomic databases:
+
+```bash
+docker compose run datomic-tools psql \
+  -f bin/sql/postgres-table.sql \
+  -h datomic-storage \
+  -U datomic-user \
+  -d my-datomic-storage
+
+```
+
+You will be prompted for a password, which is `unsafe`.
+
+Start the Datomic Transactor:
+
+```bash
+docker compose up -d datomic-transactor
+
+docker compose logs -f datomic-transactor
+
+```
+
+Create the following databases:
+
+- `my-datomic-database`
+- `my-datomic-database-test`
+- `my-datomic-database-test-green`
+
+```bash
+docker compose run datomic-tools clojure -M -e "$(cat <<'CLOJURE'
+  (require '[datomic.api :as d])
+  
+  (d/create-database "datomic:sql://my-datomic-database?jdbc:postgresql://datomic-storage:5432/my-datomic-storage?user=datomic-user&password=unsafe")
+
+  (d/create-database "datomic:sql://my-datomic-database-test?jdbc:postgresql://datomic-storage:5432/my-datomic-storage?user=datomic-user&password=unsafe")
+
+  (d/create-database "datomic:sql://my-datomic-database-test-green?jdbc:postgresql://datomic-storage:5432/my-datomic-storage?user=datomic-user&password=unsafe")
+
+  (System/exit 0)
+CLOJURE
+)"
+
+```
+
+Start the Peer Server:
+
+```bash
+docker compose up -d datomic-peer-server
+
+docker compose logs -f datomic-peer-server
+
+```
+
+Start 2 instances of Flare, one in Peer Mode and another in Client Mode:
+
+```bash
+docker compose up -d datomic-flare-peer datomic-flare-client
+
+docker compose logs -f datomic-flare-peer
+docker compose logs -f datomic-flare-client
+
+```
+
+You should be able to request both:
+
+Datomic Flare in Peer Mode:
+```bash
+curl -s http://localhost:3042/meta \
+  -X GET \
+  -H "Content-Type: application/json"  \
+| jq
+
+```
+
+```json
+{
+  "data": {
+    "mode": "peer"
+  }
+}
+
+```
+
+Datomic Flare in Client Mode:
+```bash
+curl -s http://localhost:3043/meta \
+  -X GET \
+  -H "Content-Type: application/json"  \
+| jq
+
+```
+
+```json
+{
+  "data": {
+    "mode": "client"
+  }
+}
+
+```
+
+You are ready to run tests and generate documentation.
+
+### Running Tests
+
+Tests run against real Datomic databases, so complete the [Setup for Tests and Documentation](#setup-for-tests-and-documentation) first.
+
+```bash
+cp .env.example .env
+
+bundle exec rspec
+
+```
+
+### Updating the README
+
+Documentation (README) is generated by interacting with real Datomic databases, so complete the [Setup for Tests and Documentation](#setup-for-tests-and-documentation) first.
+
+Update the `docs/templates/*.md` files, and then:
+
+```sh
+cp .env.example .env
+
+bundle exec ruby ports/cli.rb docs:generate
+
+```
+
+Trick for automatically updating the `README.md` when `docs/templates/*.md` files change:
+
+```sh
+sudo pacman -S inotify-tools # Arch / Manjaro
+sudo apt-get install inotify-tools # Debian / Ubuntu / Raspberry Pi OS
+sudo dnf install inotify-tools # Fedora / CentOS / RHEL
+
+while inotifywait -e modify docs/templates/*; \
+  do bundle exec ruby ports/cli.rb docs:generate; \
+  done
+
+```
+
+Trick for Markdown Live Preview:
+```sh
+pip install -U markdown_live_preview
+
+mlp README.md -p 8042 --no-follow
+
+```