rewrite readme, get tests online for rewrite

Author: joshday

README.md

@@ -8,132 +8,74 @@ A Graph Database for Julia, built on top of [SQLite.jl](https://github.com/Julia
 
 <br><br>
 
-## Quickstart
 
-### Definitions
+## Definitions
 
 SQLiteGraph.jl uses the [Property Graph Model of the Cypher Query Language (PDF)](https://s3.amazonaws.com/artifacts.opencypher.org/openCypher9.pdf).
 
-- A **Node** describes a discrete object in a domain.
-- Nodes can have 0+ **labels** that classify what kind of node they are.
-- An **Edge** describes a directional relationship between nodes.
-- An edge must have a **type** that classifies the relationship.
-- Both edges and nodes can have additional key-value **properties** that provide further information.
+- A **_Node_** describes a discrete object in a domain.
+- Nodes can have 0+ **_labels_** that classify what kind of node they are.
+- An **_Edge_** describes a directional relationship between nodes.
+- An edge must have a **_type_** that classifies the relationship.
+- Both edges and nodes can have additional key-value **_properties_** that provide further information.
 
-```julia
-using SQLiteGraph
-
-db = DB()
-# SQLiteGraph.DB(":memory:") (0 nodes, 0 edges)
-
-db[1] = Config(type="person", name="Fred")
-
-db[2] = Config(type="person", name="Robert Ford")
-
-db[2, 1] = Config(shot=true)
-```
-
-
-
--  Nodes and edges must have "properties" (something that is `JSON3.write`-able), even if its `nothing`.
-- Nodes must have an id (`Int`) in ascending order starting with `1`.
-- Add nodes and edges with `setindex!`
-  - E.g. Node 1: `db[1] = (x=1, y=2)`
-  - E.g. Edge 1 → 2: `db[1, 2] = (a=3, b=4)`
-- Query nodes and edges with `getindex` (as well as `find_nodes`/`find_edges`).
-  - E.g. Nodes 1, 2, and 3: `db[1:3]`
-  - E.g. Edges from 1 to 2 or 3: `db[1, 2:3]`
-  - Returned objects are `Node` or `Edge` (or generator if multiple objects queried):
-  - `Node` and `Edge` are simple structs.
-
-  ```julia
-  struct Node
-      id::Int
-      props::Config
-  end
+<br><br>
 
-  struct Edge
-      source::Int
-      target::Int
-      props::config
-  end
-  ```
+## Edges and Nodes
 
-### Creating a Graph Database
+- Nodes and Edges have a simple representation:
 
 ```julia
-using SQLiteGraph
+struct Node
+    id::Int
+    labels::Vector{String}
+    props::EasyConfig.Config
+end
 
-db = DB()
-# SQLiteGraph.DB(":memory:") (0 nodes, 0 edges)
+struct Edge
+    source::Int
+    target::Int
+    type::String
+    props::EasyConfig.Config
+end
 ```
 
-### Adding Nodes
+- With simple constructors:
 
 ```julia
-# properties must be `JSON3.write`-able (saved in the SQLite database as TEXT)
-db[1] = (x=1, y=2)
+Node(id, labels...; props...)
 
-db[2] = (x=1, y=10)
-
-db[1]
-# Node 1
-#     • y: 2
-#     • x: 1
+Edge(source_id, target_id, type; props...)
 ```
 
-### Adding Edges
-
-```julia
-db[1, 2] = (a=1, b=2)
-
-db[1, 2]
-# Edge 1 → 2
-#     • a: 1
-#     • b: 2
-```
+<br><br>
 
-## Iteration
+## Adding Elements to the Graph
 
 ```julia
-for node in eachnode(db)
-    println(getfield(node, :id))
-end
-```
+using SQLiteGraph
 
-### Querying Edges Based on Node ID
+db = DB()
 
-```julia
-db[1, :]  # all outgoing edges from node 1
+insert!(db, Node(1, "Person", "Actor"; name="Tom Hanks"))
 
-db[1, 2:5]  # outgoing edges from node 1 to any of nodes 2,3,4,5
+insert!(db, Node(2, "Movie"; title="Forest Gump"))
 
-db[:, 2]  # all incoming edges to node 2
+insert!(db, Edge(1, 2, "Acts In"))
 ```
 
-### Querying Based on Properties
-
-- multiple keyword args are a logical "AND"
+<br><br>
 
-```julia
-find_nodes(db, x=1)
+## Editing Elements
 
-find_edges(db, b=2)
-```
-
-- You can also query based on Regex matches of the `TEXT` properties:
+`insert!` will not replace an existing node or edge.  Instead, use `replace!`.
 
 ```julia
-find_nodes(db, r"x")
-
-find_edges(db, r"\"b\":2")
+replace!(db, Node(2, "Movie"; title="Forest Gump", genre="Drama"))
 ```
 
+<br><br>
+
 ## ✨ Attribution ✨
 
 SQLiteGraph is **STRONGLY** influenced (much has been copied verbatim) from [https://github.com/dpapathanasiou/simple-graph](https://github.com/dpapathanasiou/simple-graph).
-
-## TODOs
-
-- Prepare SQL into compiled `SQLite.Stmt`s.
-- traversal algorithms.

src/SQLiteGraph.jl

@@ -28,20 +28,14 @@ struct Node
     props::Config
 end
 Node(id::Int, labels::String...; props...) = Node(id, collect(labels), Config(props))
-Node(row::SQLite.Row) = Node(row.id, split(row.labels, ';'), JSON3.read(row.props, Config))
+Node(row::SQLite.Row) = Node(row.id, split(row.labels, ';', keepempty=false), JSON3.read(row.props, Config))
 function Base.show(io::IO, o::Node)
-    printstyled(io, "Node(", color=:light_cyan)
-    printstyled(io, join(repr.(o.labels), ", "), color=:light_yellow)
-    printstyled(io, ", ", o.id, color=:light_black)
-    printstyled(io, ")", color=:light_cyan)
-    if isempty(o.props)
-        printstyled(io, " with no props", color=:light_black)
-    else
-        printstyled(io, " with props: ", color=:light_black)
-        printstyled(io, join(keys(o.props), ", "), color=:light_green)
-    end
+    print(io, "Node($(o.id)")
+    !isempty(o.labels) && print(io, ", ", join(repr.(o.labels), ", "))
+    !isempty(o.props) && print(io, "; ", ("$k=$v" for (k,v) in pairs(o.props))...)
+    print(io, ')')
 end
-args(n::Node) = (n.id, join(n.labels, ';'), JSON3.write(n.props))
+args(n::Node) = (n.id, isempty(n.labels) ? "" : join(n.labels, ';'), JSON3.write(n.props))
 Base.:(==)(a::Node, b::Node) = all(getfield(a,f) == getfield(b,f) for f in fieldnames(Node))
 
 
@@ -54,16 +48,9 @@ end
 Edge(src::Int, tgt::Int, type::String; props...) = Edge(src, tgt, type, Config(props))
 Edge(row::SQLite.Row) = Edge(row.source, row.target, row.type, JSON3.read(row.props, Config))
 function Base.show(io::IO, o::Edge)
-    printstyled(io, "Edge(", color=:light_cyan)
-    printstyled(io, repr(o.type), color=:light_yellow)
-    printstyled(io, ", $(o.source) → $(o.target)", color=:light_black)
-    printstyled(io, ")", color=:light_cyan)
-    if isempty(o.props)
-        printstyled(io, " with no props", color=:light_black)
-    else
-        printstyled(io, " with props: ", color=:light_black)
-        printstyled(io, join(keys(o.props), ", "), color=:light_green)
-    end
+    print(io, "Edge($(o.source), $(o.target), ", repr(o.type))
+    !isempty(o.props) && print(io, "; ", ("$k=$v" for (k,v) in pairs(o.props))...)
+    print(io, ')')
 end
 args(e::Edge) = (e.source, e.target, e.type, JSON3.write(e.props))
 Base.:(==)(a::Edge, b::Edge) = all(getfield(a,f) == getfield(b,f) for f in fieldnames(Edge))
@@ -76,30 +63,25 @@ struct DB
     function DB(file::String = ":memory:")
         db = SQLite.DB(file)
         foreach(x -> execute(db, x), [
+            "PRAGMA foreign_keys = ON;",
             # nodes
             "CREATE TABLE IF NOT EXISTS nodes (
                 id INTEGER NOT NULL UNIQUE PRIMARY KEY,
-                labels TEXT,
-                props TEXT,
-                UNIQUE(id) ON CONFLICT REPLACE
+                labels TEXT NOT NULL,
+                props TEXT NOT NULL
             );",
-            "CREATE INDEX IF NOT EXISTS id_idx ON nodes(id);",
-            "CREATE INDEX IF NOT EXISTS labels_idx ON nodes(labels);",
 
             # edges
             "CREATE TABLE IF NOT EXISTS edges (
-                source INTEGER NOT NULL,
-                target INTEGER NOT NULL,
+                source INTEGER NOT NULL REFERENCES nodes(id),
+                target INTEGER NOT NULL REFERENCES nodes(id),
                 type TEXT NOT NULL,
-                props TEXT,
-                FOREIGN KEY(source) REFERENCES nodes(id),
-                FOREIGN KEY(target) REFERENCES nodes(id),
-                UNIQUE(source, target, type)
+                props TEXT NOT NULL,
+                PRIMARY KEY (source, target, type)
             );",
             "CREATE INDEX IF NOT EXISTS source_idx ON edges(source);",
             "CREATE INDEX IF NOT EXISTS target_idx ON edges(target);",
             "CREATE INDEX IF NOT EXISTS type_idx ON edges(type);",
-            "CREATE INDEX IF NOT EXISTS source_target_type_idx ON edges(source, target, type);"
         ])
         new(db)
     end
@@ -114,16 +96,33 @@ n_nodes(db::DB) = single_result_execute(db, "SELECT Count(*) FROM nodes")
 n_edges(db::DB) = single_result_execute(db, "SELECT Count(*) FROM edges")
 
 Base.length(db::DB) = n_nodes(db)
-Base.size(db::DB) = (n_nodes=n_nodes(db), n_edges=n_edges(db))
+Base.size(db::DB) = (nodes=n_nodes(db), edges=n_edges(db))
+Base.lastindex(db::DB) = length(db)
+Base.axes(db::DB, i) = size(db)[i]
+
+Broadcast.broadcastable(db::DB) = Ref(db)
+
+#-----------------------------------------------------------------------------# insert!
+function Base.insert!(db::DB, node::Node)
+    execute(db, "INSERT INTO nodes VALUES(?, ?, json(?))", args(node))
+    db
+end
+function Base.insert!(db::DB, edge::Edge)
+    execute(db, "INSERT INTO edges VALUES(?, ?, ?, json(?))", args(edge))
+    db
+end
 
-#-----------------------------------------------------------------------------# nodes
-function Base.push!(db::DB, node::Node; upsert=false)
-    upsert ?
-        execute(db, "INSERT INTO nodes VALUES(?, ?, json(?)) ON CONFLICT(id) DO UPDATE SET labels=excluded.labels, props=excluded.props", args(node)) :
-        execute(db, "INSERT INTO nodes VALUES(?, ?, json(?))", args(node))
+#-----------------------------------------------------------------------------# replace!
+function Base.replace!(db::DB, node::Node)
+    execute(db, "INSERT INTO nodes VALUES(?, ?, json(?)) ON CONFLICT(id) DO UPDATE SET labels=excluded.labels, props=excluded.props", args(node))
+    db
+end
+function Base.replace!(db::DB, edge::Edge)
+    execute(db, "INSERT INTO edges VALUES(?, ?, ?, json(?)) ON CONFLICT(source,target,type) DO UPDATE SET props=excluded.props", args(edge))
     db
 end
 
+#-----------------------------------------------------------------------------# getindex (Node)
 function Base.getindex(db::DB, id::Integer)
     res = execute(db, "SELECT * FROM nodes WHERE id = ?", (id,))
     isempty(res) ? error("Node $id does not exist.") : Node(first(res))
@@ -133,52 +132,45 @@ function Base.getindex(db::DB, ::Colon)
     isempty(res) ? error("No nodes exist yet.") : (Node(row) for row in res)
 end
 
-
-#-----------------------------------------------------------------------------# edges
-function Base.push!(db::DB, edge::Edge; upsert=false)
-    i, j = edge.source, edge.target
-    check = single_result_execute(db, "SELECT COUNT(*) FROM nodes WHERE id=? OR id=?", (i, j))
-    (isnothing(check) || check < 2) && error("Nodes $i and $j must exist in order for an edge to connect them.")
-    upsert ?
-        execute(db, "INSERT INTO edges VALUES(?, ?, ?, json(?)) ON CONFLICT(source,target,type) DO UPDATE SET props=excluded.props", args(edge)) :
-        execute(db, "INSERT INTO edges VALUES(?, ?, ?, json(?))", args(edge))
-    db
-end
-
+#-----------------------------------------------------------------------------# getindex (Edge)
+# all specified
 function Base.getindex(db::DB, i::Integer, j::Integer, type::AbstractString)
     res = execute(db, "SELECT * FROM edges WHERE source=? AND target=? AND type=?", (i,j,type))
     isempty(res) ? error("Edge $i → $type → $j does not exist.") : Edge(first(res))
 end
-function Base.getindex(db::DB, i::Integer, j::Integer, ::Colon = Colon())
+
+# one colon
+function Base.getindex(db::DB, i::Integer, j::Integer, ::Colon)
     res = execute(db, "SELECT * FROM edges WHERE source=? AND target=?", (i, j))
     isempty(res) ? error("No edges connect nodes $i → $j.") : (Edge(row) for row in res)
 end
-
+function Base.getindex(db::DB, i::Integer, ::Colon, type::AbstractString)
+    res = execute(db, "SELECT * FROM edges WHERE source=? AND type=?", (i,type))
+    isempty(res) ? error("No outgoing edges $type → $i") : (Edge(row) for row in res)
+end
 function Base.getindex(db::DB, ::Colon, j::Integer, type::AbstractString)
     res = execute(db, "SELECT * FROM edges WHERE target=? AND type=?", (j, type))
     isempty(res) ? error("No incoming edges $type → $j") : (Edge(row) for row in res)
 end
-function Base.getindex(db::DB, i::Colon, j::Integer, ::Colon=Colon())
-    res = execute(db, "SELECT * FROM edges WHERE target=?", (j,))
-    isempty(res) ? error("No incoming edges into node $j") : (Edge(row) for row in res)
-end
 
-function Base.getindex(db::DB, i::Integer, ::Colon, type::AbstractString)
-    res = execute(db, "SELECT * FROM edges WHERE source=? AND type=?", (i,type))
-    isempty(res) ? error("No outgoing edges $type → $i") : (Edge(row) for row in res)
-end
-function Base.getindex(db::DB, i::Integer, ::Colon, ::Colon=Colon())
+# two colons
+function Base.getindex(db::DB, i::Integer, ::Colon, ::Colon)
     res = execute(db, "SELECT * FROM edges WHERE source=?", (i,))
     isempty(res) ? error("No outgoing edges from node $i") : (Edge(row) for row in res)
 end
+function Base.getindex(db::DB, i::Colon, j::Integer, ::Colon)
+    res = execute(db, "SELECT * FROM edges WHERE target=?", (j,))
+    isempty(res) ? error("No incoming edges into node $j") : (Edge(row) for row in res)
+end
+function Base.getindex(db::DB, ::Colon, ::Colon, type::AbstractString)
+    res = execute(db, "SELECT * FROM edges WHERE type=?", (type,))
+    isempty(res) ? error("No edges with type $type") : (Edge(row) for row in res)
+end
 
-
-#-----------------------------------------------------------------------------# interfaces
-Base.length(db::DB) = n_nodes(db)
-Base.size(db::DB) = (nodes=n_nodes(db), edges=n_edges(db))
-Base.lastindex(db::DB) = length(db)
-Base.axes(db::DB, i) = size(db)[i]
-
-Broadcast.broadcastable(db::DB) = Ref(db)
+# all colons
+function Base.getindex(db::DB, ::Colon, ::Colon, ::Colon)
+    res = execute(db, "SELECT * FROM edges")
+    isempty(res) ? error("No edges exist yet.") : (Edge(row) for row in res)
+end
 
 end