Rearrange, add ToC, type mappings and more examples

Author: nsauk

README.md

@@ -5,6 +5,43 @@ This repository contains 2 implementation of a Neo4j driver for Ruby:
 - based on official Java implementation. It provides a thin wrapper over the Java driver (only on jruby).
 - pure Ruby implementation. Available on all Ruby versions >= 3.1.
 
+Network communication is handled using [Bolt Protocol](https://7687.org/).
+
+<details>
+<summary>Table of Contents</summary>
+
+* [Getting started](#getting-started)
+    * [Installation](#installation)
+    * [Getting a Neo4j instance](#getting-a-neo4j-instance)
+    * [Quick start example](#quick-start-example)
+* [Server Compatibility](#server-compatibility)
+* [Usage](#usage)
+    * [Connecting to a database](#connecting-to-a-database)
+        * [URI schemes](#uri-schemes)
+        * [Authentication](#authentication)
+        * [Configuration](#configuration)
+        * [Connectivity check](#connectivity-check)
+    * [Sessions & transactions](#sessions--transactions)
+        * [Session](#session)
+        * [Auto-commit transactions](#auto-commit-transactions)
+        * [Explicit transactions](#explicit-transactions)
+        * [Read transactions](#read-transactions)
+        * [Write transactions](#write-transactions)
+    * [Working with results](#working-with-results)
+        * [Accessing Node and Relationship data](#accessing-node-and-relationship-data)
+        * [Working with Paths](#working-with-paths)
+        * [Working with temporal types](#working-with-temporal-types)
+    * [Type mapping](#type-mapping)
+    * [Advanced](#advanced)
+        * [Connection pooling](#connection-pooling)
+        * [Logging](#logging)
+* [For Driver Engineers](#for-driver-engineers)
+    * [Testing](#testing)
+* [Contributing](#contributing)
+* [License](#license)
+
+</details>
+
 ## Getting started
 
 ### Installation
@@ -29,9 +66,11 @@ gem install neo4j-ruby-driver
 
 ### Getting a Neo4j instance
 
-You need a running Neo4j database in order to use the driver with it. The easiest way to spin up a **local instance** is through a Docker container.
+You need a running Neo4j database in order to use the driver with it. The easiest way to spin up a **local instance** is
+through a Docker container.
 
-The command below runs the latest Neo4j version in Docker, setting the admin username and password to `neo4j` and `password` respectively:
+The command below runs the latest Neo4j version in Docker, setting the admin username and password to `neo4j` and
+`password` respectively:
 
 ```bash
 docker run \
@@ -52,22 +91,27 @@ Neo4j::Driver::GraphDatabase.driver(
   Neo4j::Driver::AuthTokens.basic('neo4j', 'password')
 ) do |driver|
   driver.session(database: 'neo4j') do |session|
-    result = session.run('CREATE (n)').consume
-    puts "Nodes created: #{result.counters.nodes_created}"
+    query_result = session.run('RETURN 2+2 AS value')
+    puts "2+2 equals #{query_result.single['value']}"
+
+    # consume gives the execution summary
+    create_result = session.run('CREATE (n)').consume
+    puts "Nodes created: #{create_result.counters.nodes_created}"
   end
 end
 ```
 
 ## Server Compatibility
 
-The compatibility with Neo4j Server versions is documented in the [Neo4j Knowledge Base](https://neo4j.com/developer/kb/neo4j-supported-versions/).
+The compatibility with Neo4j Server versions is documented in
+the [Neo4j Knowledge Base](https://neo4j.com/developer/kb/neo4j-supported-versions/).
 
 ## Usage
 
-The API is to highest possible degree consistent with the official Java driver.
-Please refer to the [Neo4j Java Driver Manual](https://neo4j.com/docs/java-manual/current/),
-[examples in Ruby](https://github.com/neo4jrb/neo4j-ruby-driver/blob/master/docs/dev_manual_examples.rb),
+The API is to highest possible degree consistent with the official Java driver. Please refer to
+the [Neo4j Java Driver Manual](https://neo4j.com/docs/java-manual/current/), [examples in Ruby](https://github.com/neo4jrb/neo4j-ruby-driver/blob/master/docs/dev_manual_examples.rb),
 and code snippets below to understand how to use it.
+[Neo4j Java Driver API Docs](https://neo4j.com/docs/api/java-driver/current/) can be helpful as well.
 
 ### Connecting to a database
 
@@ -76,7 +120,7 @@ and code snippets below to understand how to use it.
 The driver supports the following URI schemes:
 
 | URI Scheme     | Description                                                                     |
-| -------------- | ------------------------------------------------------------------------------- |
+|----------------|---------------------------------------------------------------------------------|
 | `neo4j://`     | Connect using routing to a cluster/causal cluster.                              |
 | `neo4j+s://`   | Same as `neo4j://` but with full TLS encryption.                                |
 | `neo4j+ssc://` | Same as `neo4j://` but with full TLS encryption, without hostname verification. |
@@ -130,11 +174,11 @@ You can configure the driver with additional options:
 
 ```ruby
 config = {
-  connection_timeout: 5000,                # timeout in ms
-  connection_acquisition_timeout: 60_000,  # timeout in ms
-  max_transaction_retry_time: 30_000,      # timeout in ms
-  encryption: true,                        # enable encryption
-  trust_strategy: :trust_all_certificates  # trust strategy
+  connection_timeout: 15.seconds,
+  connection_acquisition_timeout: 1.minute,
+  max_transaction_retry_time: 30.seconds,
+  encryption: true,
+  trust_strategy: :trust_all_certificates
 }
 
 driver = Neo4j::Driver::GraphDatabase.driver(
@@ -144,6 +188,16 @@ driver = Neo4j::Driver::GraphDatabase.driver(
 )
 ```
 
+#### Connectivity check
+
+```ruby
+if driver.verify_connectivity
+  puts "Driver is connected to the database"
+else
+  puts "Driver cannot connect to the database"
+end
+```
+
 ### Sessions & transactions
 
 The driver provides sessions to interact with the database and to execute queries.
@@ -159,8 +213,11 @@ begin
 ensure
   session.close
 end
+```
+
+Or use a block that automatically closes the session:
 
-# Or use a block that automatically closes the session
+```ruby
 driver.session(database: 'neo4j') do |session|
   session.run('MATCH (n) RETURN n LIMIT 10')
 end
@@ -310,45 +367,85 @@ result.each do |record|
 end
 ```
 
-### Connection pooling
+#### Working with temporal types
+
+Creating a node with properties of temporal types:
+
+```ruby
+session.run(
+  'CREATE (e:Event {datetime: $datetime, duration: $duration})',
+  datetime: DateTime.new(2025, 5, 5, 5, 55, 55), duration: 1.hour
+)
+```
+
+Querying temporal values:
+
+```ruby
+session.run('MATCH (e:Event) LIMIT 1 RETURN e.datetime, e.duration').single.to_h
+# => {"e.datetime": 2025-05-05 05:55:55 +0000, "e.duration": 3600 seconds}
+```
+
+### Type mapping
+
+The Neo4j Ruby Driver maps Cypher types to Ruby types:
+
+| Cypher Type    | Ruby Type                                     |
+|----------------|-----------------------------------------------|
+| null           | nil                                           |
+| List           | Enumerable                                    |
+| Map            | Hash (symbolized keys)                        |
+| Boolean        | TrueClass/FalseClass                          |
+| Integer        | Integer/String[^1]                            |
+| Float          | Float                                         |
+| String         | String/Symbol[^2] (encoding: UTF-8)           |
+| ByteArray      | String (encoding: BINARY)                     |
+| Date           | Date                                          |
+| Zoned Time     | Neo4j::Driver::Types::OffsetTime              |
+| Local Time     | Neo4j::Driver::Types::LocalTime               |
+| Zoned DateTime | Time/ActiveSupport::TimeWithZone/DateTime[^3] |
+| Local DateTime | Neo4j::Driver::Types::LocalDateTime           |
+| Duration       | ActiveSupport::Duration                       |
+| Point          | Neo4j::Driver::Types::Point                   |
+| Node           | Neo4j::Driver::Types::Node                    |
+| Relationship   | Neo4j::Driver::Types::Relationship            |
+| Path           | Neo4j::Driver::Types::Path                    |
+
+[^1]: An Integer smaller than -2 ** 63 or larger than 2 ** 63 will always be implicitly converted to String
+[^2]: A Symbol passed as a parameter will always be implicitly converted to String. All Strings other than BINARY
+encoded are converted to UTF-8 when stored in Neo4j
+[^3]: A Ruby DateTime passed as a parameter will always be implicitly converted to Time
+
+### Advanced
+
+#### Connection pooling
 
 The driver handles connection pooling automatically. Configure the connection pool:
 
 ```ruby
 config = {
   max_connection_pool_size: 100,
-  max_connection_lifetime: 3_600_000 # 1 hour in milliseconds
+  max_connection_lifetime: 1.hour
 }
 
 driver = Neo4j::Driver::GraphDatabase.driver('neo4j://localhost:7687', auth, **config)
 ```
 
-### Logging
+#### Logging
 
 Configure logging for the driver:
 
 ```ruby
 config = {
-  logger: Logger.new(STDOUT),
-  logging_level: Logger::DEBUG
+  logger: Logger.new(STDOUT).tap { |log| log.level = Logger::DEBUG }
 }
 
 driver = Neo4j::Driver::GraphDatabase.driver('neo4j://localhost:7687', auth, **config)
 ```
 
-### Connectivity check
-
-```ruby
-if driver.verify_connectivity
-  puts "Driver is connected to the database"
-else
-  puts "Driver cannot connect to the database"
-end
-```
-
 ## For Driver Engineers
 
-This gem includes 2 different implementations: a Java driver wrapper and a pure Ruby driver, so you will have to run this command every time you switch the Ruby engine:
+This gem includes 2 different implementations: a Java driver wrapper and a pure Ruby driver, so you will have to run
+this command every time you switch the Ruby engine:
 
 ```bash
 bin/setup
@@ -362,7 +459,8 @@ There are two sets of tests for the driver. To run the specs placed in this repo
 rspec spec
 ```
 
-To run the [Testkit](https://github.com/neo4j-drivers/testkit) that is used to test all Neo4j driver implementations, use the following:
+To run the [Testkit](https://github.com/neo4j-drivers/testkit) that is used to test all Neo4j driver implementations,
+use the following:
 
 ```bash
 git clone [email protected]:neo4j-drivers/testkit.git
@@ -377,7 +475,8 @@ Please refer to the [Testkit](https://github.com/neo4j-drivers/testkit) document
 
 ## Contributing
 
-Suggestions, improvements, bug reports and pull requests are welcome on GitHub at https://github.com/neo4jrb/neo4j-ruby-driver.
+Suggestions, improvements, bug reports and pull requests are welcome on GitHub
+at https://github.com/neo4jrb/neo4j-ruby-driver.
 
 ## License