datomic-flare 1.0.0

data/docs/templates/README.md

@@ -0,0 +1,319 @@
+# 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:runnable
+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:placeholder
+```
+
+{{ index }}
+
+## Flare
+
+### Creating a Client
+
+```ruby
+require '{{ gem.name }}'
+
+client = Flare.new(credentials: { address: 'http://localhost:3042' })
+```
+
+### Meta
+
+```ruby:runnable
+client.meta
+```
+
+```ruby:placeholder
+```
+
+{{ 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
+```

data/docs/templates/api.md

@@ -0,0 +1,267 @@
+## Flare API
+
+It provides methods that mirror [Datomic's APIs](https://docs.datomic.com/clojure/index.html). Most interactions use EDN, closely following [Datomic’s documentation](https://docs.datomic.com).
+
+This approach should be familiar to those who know Datomic concepts and APIs.
+
+Learn more about Clojure and Datomic:
+
+- [Clojure Rationale](https://clojure.org/about/rationale)
+- [Datomic Introduction](https://docs.datomic.com/datomic-overview.html)
+
+### Creating a Database
+
+```ruby:runnable
+client.api.create_database!({ name: 'fireball' })['data']
+```
+
+```ruby:placeholder
+```
+
+### Deleting a Database
+
+```ruby:runnable
+client.api.delete_database!({ name: 'fireball' })['data']
+```
+
+```ruby:placeholder
+```
+
+### Listing Databases
+
+```ruby
+# Flare on Peer Mode
+client.api.get_database_names['data']
+
+# Flare on Client Mode
+client.api.list_databases['data']
+```
+
+```ruby
+['my-datomic-database']
+```
+
+### Transacting Schema
+
+```ruby:runnable
+client.api.transact!(
+  { data: <<~EDN
+    [{:db/ident       :book/title
+      :db/valueType   :db.type/string
+      :db/cardinality :db.cardinality/one
+      :db/doc         "The title of the book."}
+
+     {:db/ident       :book/genre
+      :db/valueType   :db.type/string
+      :db/cardinality :db.cardinality/one
+      :db/doc         "The genre of the book."}
+
+     {:db/ident       :book/published_at_year
+      :db/valueType   :db.type/long
+      :db/cardinality :db.cardinality/one
+      :db/doc         "The year the book was first published."}]
+  EDN
+  }
+)['data']
+```
+
+```ruby:placeholder
+```
+
+### Checking Schema
+
+```ruby:runnable
+client.api.q(
+  { inputs: [{ database: { latest: true } }],
+    query: <<~EDN
+      [:find
+          ?e ?ident ?value_type ?cardinality ?doc
+          ?unique ?index ?no_history
+       :in $
+       :where
+         [?e :db/ident ?ident]
+
+         [?e :db/valueType ?value_type_id]
+         [?value_type_id :db/ident ?value_type]
+
+         [?e :db/cardinality ?cardinality_id]
+         [?cardinality_id :db/ident ?cardinality]
+
+         [(get-else $ ?e :db/doc "") ?doc]
+
+         [(get-else $ ?e :db/unique -1) ?unique_id]
+         [(get-else $ ?unique_id :db/ident false) ?unique]
+
+         [(get-else $ ?e :db/index false) ?index]
+         [(get-else $ ?e :db/noHistory false) ?no_history]]
+    EDN
+  }
+)['data'].filter do |datom|
+  !%w[
+    db
+    db.alter db.attr db.bootstrap db.cardinality db.entity db.excise
+    db.fn db.install db.lang db.part db.sys db.type db.unique
+    fressian
+  ].include?(datom[1].split('/').first)
+end
+```
+
+```ruby:placeholder
+```
+
+### Asserting Facts
+
+```ruby:runnable
+client.api.transact!(
+  { data: <<~EDN
+    [{:db/id      -1
+      :book/title "Pride and Prejudice"
+      :book/genre "Romance"
+      :book/published_at_year 1813}]
+  EDN
+  }
+)['data']
+```
+
+```ruby:placeholder
+```
+
+```ruby:runnable
+client.api.transact!(
+  { data: <<~EDN
+    [{:db/id      -1
+      :book/title "Near to the Wild Heart"
+      :book/genre "Novel"
+      :book/published_at_year 1943}
+     {:db/id      -2
+      :book/title "A Study in Scarlet"
+      :book/genre "Detective"
+      :book/published_at_year 1887}
+     {:db/id      -3
+      :book/title "The Tell-Tale Heart"
+      :book/genre "Horror"
+      :book/published_at_year 1843}]
+  EDN
+  }
+)['data']
+```
+
+```ruby:state
+state[:wild_heart_entity_id] = result['tempids']['-1']
+state[:scarlet_entity_id] = result['tempids']['-2']
+```
+
+```ruby:placeholder
+```
+
+### Reading Data by Entity
+
+```ruby:runnable/render
+client.api.entity(
+  { database: { latest: true },
+    id: {{ state.wild_heart_entity_id }} }
+)['data']
+```
+
+```ruby:placeholder
+```
+
+### Reading Data by Querying
+
+```ruby:runnable
+client.api.q(
+  { inputs: [{ database: { latest: true } }],
+    query: <<~EDN
+      [:find ?e ?title ?genre ?year
+       :where [?e :book/title ?title]
+              [?e :book/genre ?genre]
+              [?e :book/published_at_year ?year]]
+    EDN
+  }
+)['data']
+```
+
+```ruby:placeholder
+```
+
+```ruby:runnable
+client.api.q(
+  { inputs: [
+      { database: { latest: true } },
+      'The Tell-Tale Heart'
+    ],
+    query: <<~EDN
+      [:find ?e ?title ?genre ?year
+       :in $ ?title
+       :where [?e :book/title ?title]
+              [?e :book/genre ?genre]
+              [?e :book/published_at_year ?year]]
+    EDN
+  }
+)['data']
+```
+
+```ruby:state
+state[:tale_heart_entity_id] = result[0][0]
+```
+
+```ruby:placeholder
+```
+
+### Accumulating Facts
+
+```ruby:runnable/render
+client.api.transact!(
+  { data: <<~EDN
+    [{:db/id {{ state.tale_heart_entity_id }} :book/genre "Gothic"}]
+  EDN
+  }
+)['data']
+```
+
+```ruby:placeholder
+```
+
+### Retracting Facts
+
+Retract the value of an attribute:
+
+```ruby:runnable/render
+client.api.transact!(
+  { data: <<~EDN
+    [[:db/retract {{ state.tale_heart_entity_id }} :book/genre "Gothic"]]
+  EDN
+  }
+)['data']
+```
+
+```ruby:placeholder
+```
+
+Retract an attribute:
+
+```ruby:runnable/render
+client.api.transact!(
+  { data: <<~EDN
+    [[:db/retract {{ state.wild_heart_entity_id }} :book/genre]]
+  EDN
+  }
+)['data']
+```
+
+```ruby:placeholder
+```
+
+Retract an entity:
+
+```ruby:runnable/render
+client.api.transact!(
+  { data: <<~EDN
+    [[:db/retractEntity {{ state.scarlet_entity_id }}]]
+  EDN
+  }
+)['data']
+```
+
+```ruby:placeholder
+```