datomic-flare 1.0.0

data/docs/api.md

@@ -0,0 +1,395 @@
+## 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
+client.api.create_database!({ name: 'fireball' })['data']
+```
+
+```ruby
+true
+```
+
+### Deleting a Database
+
+```ruby
+client.api.delete_database!({ name: 'fireball' })['data']
+```
+
+```ruby
+true
+```
+
+### 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
+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
+{
+  'db-before' => 'datomic.db.Db@3062d44c',
+  'db-after' => 'datomic.db.Db@7802aade',
+  'tx-data' =>
+  [[13194139534312, 50, '2024-09-29T13:52:52.435Z', 13194139534312, true],
+   [72, 10, ':book/title', 13194139534312, true],
+   [72, 40, 23, 13194139534312, true],
+   [72, 41, 35, 13194139534312, true],
+   [72, 62, 'The title of the book.', 13194139534312, true],
+   [73, 10, ':book/genre', 13194139534312, true],
+   [73, 40, 23, 13194139534312, true],
+   [73, 41, 35, 13194139534312, true],
+   [73, 62, 'The genre of the book.', 13194139534312, true],
+   [74, 10, ':book/published_at_year', 13194139534312, true],
+   [74, 40, 22, 13194139534312, true],
+   [74, 41, 35, 13194139534312, true],
+   [74, 62, 'The year the book was first published.', 13194139534312, true],
+   [0, 13, 72, 13194139534312, true],
+   [0, 13, 73, 13194139534312, true],
+   [0, 13, 74, 13194139534312, true]],
+  'tempids' =>
+  {
+    '-9223300668110558618' => 72,
+    '-9223300668110558617' => 73,
+    '-9223300668110558616' => 74
+  }
+}
+```
+
+### Checking Schema
+
+```ruby
+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
+[[74,
+  'book/published_at_year',
+  'db.type/long',
+  'db.cardinality/one',
+  'The year the book was first published.',
+  false,
+  false,
+  false],
+ [72,
+  'book/title',
+  'db.type/string',
+  'db.cardinality/one',
+  'The title of the book.',
+  false,
+  false,
+  false],
+ [73,
+  'book/genre',
+  'db.type/string',
+  'db.cardinality/one',
+  'The genre of the book.',
+  false,
+  false,
+  false]]
+```
+
+### Asserting Facts
+
+```ruby
+client.api.transact!(
+  { data: <<~EDN
+    [{:db/id      -1
+      :book/title "Pride and Prejudice"
+      :book/genre "Romance"
+      :book/published_at_year 1813}]
+  EDN
+  }
+)['data']
+```
+
+```ruby
+{
+  'db-before' => 'datomic.db.Db@5342ef1a',
+  'db-after' => 'datomic.db.Db@643ac781',
+  'tx-data' =>
+  [[13194139534313, 50, '2024-09-29T13:52:52.546Z', 13194139534313, true],
+   [4611681620380877802, 72, 'Pride and Prejudice', 13194139534313, true],
+   [4611681620380877802, 73, 'Romance', 13194139534313, true],
+   [4611681620380877802, 74, 1813, 13194139534313, true]],
+  'tempids' => { '-1' => 4611681620380877802 }
+}
+```
+
+```ruby
+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
+{
+  'db-before' => 'datomic.db.Db@6afd3576',
+  'db-after' => 'datomic.db.Db@73000a74',
+  'tx-data' =>
+  [[13194139534315, 50, '2024-09-29T13:52:52.599Z', 13194139534315, true],
+   [4611681620380877804, 72, 'Near to the Wild Heart', 13194139534315, true],
+   [4611681620380877804, 73, 'Novel', 13194139534315, true],
+   [4611681620380877804, 74, 1943, 13194139534315, true],
+   [4611681620380877805, 72, 'A Study in Scarlet', 13194139534315, true],
+   [4611681620380877805, 73, 'Detective', 13194139534315, true],
+   [4611681620380877805, 74, 1887, 13194139534315, true],
+   [4611681620380877806, 72, 'The Tell-Tale Heart', 13194139534315, true],
+   [4611681620380877806, 73, 'Horror', 13194139534315, true],
+   [4611681620380877806, 74, 1843, 13194139534315, true]],
+  'tempids' =>
+  {
+    '-1' => 4611681620380877804,
+    '-2' => 4611681620380877805,
+    '-3' => 4611681620380877806
+  }
+}
+```
+
+### Reading Data by Entity
+
+```ruby
+client.api.entity(
+  {
+    database: { latest: true },
+    id: 4611681620380877804
+  }
+)['data']
+```
+
+```ruby
+{
+  ':book/title' => 'Near to the Wild Heart',
+  ':book/genre' => 'Novel',
+  ':book/published_at_year' => 1943,
+  ':db/id' => 4611681620380877804
+}
+```
+
+### Reading Data by Querying
+
+```ruby
+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
+[[4611681620380877805, 'A Study in Scarlet', 'Detective', 1887],
+ [4611681620380877804, 'Near to the Wild Heart', 'Novel', 1943],
+ [4611681620380877806, 'The Tell-Tale Heart', 'Horror', 1843],
+ [4611681620380877802, 'Pride and Prejudice', 'Romance', 1813]]
+```
+
+```ruby
+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
+[[4611681620380877806, 'The Tell-Tale Heart', 'Horror', 1843]]
+```
+
+### Accumulating Facts
+
+```ruby
+client.api.transact!(
+  { data: <<~EDN
+    [{:db/id 4611681620380877806 :book/genre "Gothic"}]
+  EDN
+  }
+)['data']
+```
+
+```ruby
+{
+  'db-before' => 'datomic.db.Db@55e660ec',
+  'db-after' => 'datomic.db.Db@385f74d4',
+  'tx-data' =>
+  [[13194139534319, 50, '2024-09-29T13:52:52.817Z', 13194139534319, true],
+   [4611681620380877806, 73, 'Gothic', 13194139534319, true],
+   [4611681620380877806, 73, 'Horror', 13194139534319, false]],
+  'tempids' => {}
+}
+```
+
+### Retracting Facts
+
+Retract the value of an attribute:
+
+```ruby
+client.api.transact!(
+  { data: <<~EDN
+    [[:db/retract 4611681620380877806 :book/genre "Gothic"]]
+  EDN
+  }
+)['data']
+```
+
+```ruby
+{
+  'db-before' => 'datomic.db.Db@7c2176fa',
+  'db-after' => 'datomic.db.Db@6ec2acf1',
+  'tx-data' =>
+  [[13194139534320, 50, '2024-09-29T13:52:52.869Z', 13194139534320, true],
+   [4611681620380877806, 73, 'Gothic', 13194139534320, false]],
+  'tempids' => {}
+}
+```
+
+Retract an attribute:
+
+```ruby
+client.api.transact!(
+  { data: <<~EDN
+    [[:db/retract 4611681620380877804 :book/genre]]
+  EDN
+  }
+)['data']
+```
+
+```ruby
+{
+  'db-before' => 'datomic.db.Db@f8180a0',
+  'db-after' => 'datomic.db.Db@2bc03f4d',
+  'tx-data' =>
+  [[13194139534321, 50, '2024-09-29T13:52:52.913Z', 13194139534321, true],
+   [4611681620380877804, 73, 'Novel', 13194139534321, false]],
+  'tempids' => {}
+}
+```
+
+Retract an entity:
+
+```ruby
+client.api.transact!(
+  { data: <<~EDN
+    [[:db/retractEntity 4611681620380877805]]
+  EDN
+  }
+)['data']
+```
+
+```ruby
+{
+  'db-before' => 'datomic.db.Db@698670bc',
+  'db-after' => 'datomic.db.Db@2abc508c',
+  'tx-data' =>
+  [[13194139534322, 50, '2024-09-29T13:52:52.955Z', 13194139534322, true],
+   [4611681620380877805, 72, 'A Study in Scarlet', 13194139534322, false],
+   [4611681620380877805, 73, 'Detective', 13194139534322, false],
+   [4611681620380877805, 74, 1887, 13194139534322, false]],
+  'tempids' => {}
+}
+```

data/docs/dsl.md

@@ -0,0 +1,257 @@
+## Flare DSL
+
+It provides a Ruby-familiar approach to working with Datomic. It brings Ruby’s conventions and idioms while preserving Datomic’s data-first principles and terminology.
+
+This approach should be cozy to those who are familiar with Ruby.
+
+Learn more about Ruby and The Rails Doctrine:
+
+- [About Ruby](https://www.ruby-lang.org/en/about/)
+- [The Rails Doctrine](https://rubyonrails.org/doctrine)
+
+### Creating a Database
+
+```ruby
+client.dsl.create_database!('radioactive')
+```
+
+```ruby
+true
+```
+
+### Deleting a Database
+
+```ruby
+client.dsl.destroy_database!('radioactive')
+```
+
+```ruby
+true
+```
+
+### Listing Databases
+
+```ruby
+client.dsl.databases
+```
+
+```ruby
+['my-datomic-database']
+```
+
+### Transacting Schema
+
+Like `CREATE TABLE` in SQL databases or defining document or record structures in other databases.
+
+```ruby
+client.dsl.transact_schema!(
+  {
+    book: {
+      title: { type: :string, doc: 'The title of the book.' },
+      genre: { type: :string, doc: 'The genre of the book.' },
+      published_at_year: { type: :long, doc: 'The year the book was first published.' }
+    }
+  }
+)
+```
+
+```ruby
+true
+```
+
+### Checking Schema
+
+Like `SHOW COLUMNS FROM` in SQL databases or checking document or record structures in other databases.
+
+```ruby
+client.dsl.schema
+```
+
+```ruby
+{
+  book: {
+    published_at_year: {
+      type: :long,
+      cardinality: :one,
+      doc: 'The year the book was first published.',
+      unique: false,
+      index: false,
+      history: true
+    },
+    title: {
+      type: :string,
+      cardinality: :one,
+      doc: 'The title of the book.',
+      unique: false,
+      index: false,
+      history: true
+    },
+    genre: {
+      type: :string,
+      cardinality: :one,
+      doc: 'The genre of the book.',
+      unique: false,
+      index: false,
+      history: true
+    }
+  }
+}
+```
+
+### Asserting Facts
+
+Like `INSERT INTO` in SQL databases or creating a new document or record in other databases.
+
+```ruby
+client.dsl.assert_into!(
+  :book,
+  {
+    title: 'Pride and Prejudice',
+    genre: 'Romance',
+    published_at_year: 1813
+  }
+)
+```
+
+```ruby
+4611681620380877802
+```
+
+```ruby
+client.dsl.assert_into!(
+  :book,
+  [{
+    title: 'Near to the Wild Heart',
+    genre: 'Novel',
+    published_at_year: 1943
+  },
+   {
+     title: 'A Study in Scarlet',
+     genre: 'Detective',
+     published_at_year: 1887
+   },
+   {
+     title: 'The Tell-Tale Heart',
+     genre: 'Horror',
+     published_at_year: 1843
+   }]
+)
+```
+
+
+```ruby
+[4611681620380877804, 4611681620380877805, 4611681620380877806]
+```
+
+### Reading Data by Entity
+
+Like `SELECT` in SQL databases or querying documents or records in other databases.
+
+```ruby
+client.dsl.find_by_entity_id(4611681620380877804)
+```
+
+```ruby
+{
+  book: {
+    title: 'Near to the Wild Heart',
+    genre: 'Novel',
+    published_at_year: 1943,
+    _id: 4611681620380877804
+  }
+}
+```
+
+### Reading Data by Querying
+
+Like `SELECT` in SQL databases or querying documents or records in other databases.
+
+```ruby
+client.dsl.query(
+  datalog: <<~EDN
+    [:find ?e ?title ?genre ?year
+     :where [?e :book/title ?title]
+            [?e :book/genre ?genre]
+            [?e :book/published_at_year ?year]]
+  EDN
+)
+```
+
+```ruby
+[[4611681620380877805, 'A Study in Scarlet', 'Detective', 1887],
+ [4611681620380877804, 'Near to the Wild Heart', 'Novel', 1943],
+ [4611681620380877806, 'The Tell-Tale Heart', 'Horror', 1843],
+ [4611681620380877802, 'Pride and Prejudice', 'Romance', 1813]]
+```
+
+```ruby
+client.dsl.query(
+  params: ['The Tell-Tale Heart'],
+  datalog: <<~EDN
+    [:find ?e ?title ?genre ?year
+     :in $ ?title
+     :where [?e :book/title ?title]
+            [?e :book/genre ?genre]
+            [?e :book/published_at_year ?year]]
+  EDN
+)
+```
+
+
+```ruby
+[[4611681620380877806, 'The Tell-Tale Heart', 'Horror', 1843]]
+```
+
+### Accumulating Facts
+
+Like `UPDATE` in SQL databases or updating documents or records in other databases. However, Datomic never updates data. It is an immutable database that only accumulates new facts or retracts past facts.
+
+```ruby
+client.dsl.assert_into!(
+  :book, { _id: 4611681620380877806, genre: 'Gothic' }
+)
+```
+
+```ruby
+4611681620380877806
+```
+
+### Retracting Facts
+
+Like `DELETE` in SQL databases or deleting documents or records in other databases. However, Datomic never deletes data. It is an immutable database that only accumulates new facts or retracts past facts.
+
+Retract the value of an attribute:
+
+```ruby
+client.dsl.retract_from!(
+  :book, { _id: 4611681620380877806, genre: 'Gothic' }
+)
+```
+
+```ruby
+true
+```
+
+Retract an attribute:
+
+```ruby
+client.dsl.retract_from!(
+  :book, { _id: 4611681620380877804, genre: nil }
+)
+```
+
+```ruby
+true
+```
+
+Retract an entity:
+
+```ruby
+client.dsl.retract_from!(
+  :book, { _id: 4611681620380877805 }
+)
+```
+
+```ruby
+true
+```

data/docs/templates/.rubocop.yml

@@ -0,0 +1,15 @@
+AllCops:
+  TargetRubyVersion: 3.1.0
+  NewCops: enable
+
+Style/NumericLiterals:
+  Enabled: false
+
+Layout/FirstHashElementLineBreak:
+  Enabled: true
+
+Lint/UselessAssignment:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false