Skip to content

Add v0.2.0 APIs (Document, Schema, Branch, Streaming), docs, and guides - #16

Merged
thanos merged 4 commits into
mainfrom
v0.2.0
Jun 24, 2026
Merged

thanos merged 4 commits into
mainfrom
v0.2.0

Conversation

@thanos

@thanos thanos commented Jun 24, 2026

Copy link
Copy Markdown
Collaborator

Implement the first v0.2 slice: document CRUD with streaming, schema frame retrieval, branch management, and an incremental concatenated-JSON decoder. Add comprehensive documentation, guides, and a Livebook demo.

New modules:

  • TerminusDB.Document: insert/get/query/replace/delete/stream (plus !/ variants) with graph_type, author/message commit metadata, pagination, and all document query params.
  • TerminusDB.Schema: frame/all (plus !/ variants) for class frame retrieval with compress_ids and expand_abstract options.
  • TerminusDB.Branch: create/delete/exists? (plus !/ variants) with :from, :organization, :repo overrides.
  • TerminusDB.Streaming: split_concatenated/1 (bracket/depth-aware JSON splitter) and document_stream/1 (Stream.resource over Req async responses). Fixed a bug where the stream never halted on :done; added Jason decoding so the stream yields maps, not binaries.

Documentation:

  • Added hermetic doctest examples to every public function across all modules (27 doctests total, all using the fake Req adapter pattern).
  • Rewrote README Quick Start as a full 11-step walkthrough (create DB, insert schema, insert/query/replace/delete documents, schema frames, branches, streaming, cleanup).
  • guides/introduction.md: TerminusDB concepts (documents, schema, branches, queries, indexes/storage).
  • guides/migrating-from-sql.md: SQL-to-TerminusDB migration by example.
  • guides/overview.md: feature-by-feature walkthrough with runnable examples.
  • guides/terminusdb_ex_livebook.livemd: full Livebook demoing every API.
  • Updated mix.exs docs extras with all guides under a "Guides" group.

Tests:

  • 151 unit tests + 6 properties + 27 doctests, 0 failures (8 integration excluded). 99.2% coverage.
  • Streaming tests mock Req.Response.Async with a custom stream_fun to test single-chunk, multi-chunk, split-document, error, trailer, and unknown message scenarios.
  • Integration tests for Document, Schema, and Branch lifecycle.

Other:

  • Added AGENTS.md
  • Updated CHANGELOG with v0.2 Unreleased section.
  • Updated .sobelow-conf to ignore SQL.Query false positive on Document.query.
  • Updated mix.exs: source_url, description, quality alias (sobelow --exit Low), docs extras, coveralls.json for minimum coverage enforcement.

thanos added 2 commits June 24, 2026 09:35
Implement the first v0.2 slice: document CRUD with streaming, schema frame
retrieval, branch management, and an incremental concatenated-JSON decoder.
Add comprehensive documentation, guides, and a Livebook demo.

New modules:
- TerminusDB.Document: insert/get/query/replace/delete/stream (plus !/ variants)
  with graph_type, author/message commit metadata, pagination, and all document
  query params.
- TerminusDB.Schema: frame/all (plus !/ variants) for class frame retrieval
  with compress_ids and expand_abstract options.
- TerminusDB.Branch: create/delete/exists? (plus !/ variants) with :from,
  :organization, :repo overrides.
- TerminusDB.Streaming: split_concatenated/1 (bracket/depth-aware JSON splitter)
  and document_stream/1 (Stream.resource over Req async responses). Fixed a
  bug where the stream never halted on :done; added Jason decoding so the
  stream yields maps, not binaries.

Documentation:
- Added hermetic doctest examples to every public function across all modules
  (27 doctests total, all using the fake Req adapter pattern).
- Rewrote README Quick Start as a full 11-step walkthrough (create DB, insert
  schema, insert/query/replace/delete documents, schema frames, branches,
  streaming, cleanup).
- guides/introduction.md: TerminusDB concepts (documents, schema, branches,
  queries, indexes/storage).
- guides/migrating-from-sql.md: SQL-to-TerminusDB migration by example.
- guides/overview.md: feature-by-feature walkthrough with runnable examples.
- guides/terminusdb_ex_livebook.livemd: full Livebook demoing every API.
- Updated mix.exs docs extras with all guides under a "Guides" group.

Tests:
- 151 unit tests + 6 properties + 27 doctests, 0 failures (8 integration
  excluded). 99.2% coverage.
- Streaming tests mock Req.Response.Async with a custom stream_fun to test
  single-chunk, multi-chunk, split-document, error, trailer, and unknown
  message scenarios.
- Integration tests for Document, Schema, and Branch lifecycle.

Other:
- Added AGENTS.md
- Updated CHANGELOG with v0.2 Unreleased section.
- Updated .sobelow-conf to ignore SQL.Query false positive on Document.query.
- Updated mix.exs: source_url, description, quality alias (sobelow --exit Low),
  docs extras, coveralls.json for minimum coverage enforcement.
High
- F1 — Flaky telemetry test fixed: uses a unique path ("telemetry/noop-<unique>") and filters refute_receive by %{path: ^unique} so it can't catch leaked events from concurrent tests. Verified: 0 failures in 50 runs with different seeds.
- F2 — unfold/minimized/compress_ids/as_list now use Params.bool_param/2 (sends false explicitly) instead of maybe_param (which dropped false). Added a regression test asserting unfold=false, minimized=false, compress_ids=false, as_list=false all appear in the query string.
Medium
- F3 — Document.stream/2 now uses a case to handle {:error, error} and raise error (raising TerminusDB.Error), instead of {:ok, resp} = ... which raised MatchError. Added two tests (404 error + transport error).
- F4 — Removed the false "JSON array" claim from the Streaming moduledoc and document_stream/1 doc. Now correctly documents that only concatenated JSON is supported and warns not to use as_list with streaming.
- F5 — Branch.create/3 now builds the origin body from the resolved org/repo (honoring :organization/:repo overrides) instead of config.* defaults. Added a test asserting the origin body reflects the overrides.
- F6 — Replaced all 15 occurrences of :ok = ...delete(...) with {:ok, _} = ...delete(...) across README, all 3 guides, Livebook, Database/Branch moduledocs, and the integration test.
- F7/F8 — Added integration tests for query/3 (inserts two docs with different ages, queries by template, asserts only matching docs returned), stream/2 (inserts 3 docs, streams them, asserts all labels), and Schema.frame/3 (retrieves a specific class frame after inserting a schema).
Low
- F9 — Extracted TerminusDB.Client.Params module with flag_param/2 (omit false) and bool_param/2 (always send non-nil). Replaced the 3 duplicated maybe_param definitions in Document, Schema, and Database.
- F10 — Added a receive ... after timeout to next_document so the stream halts if no chunk arrives within the timeout window (defaults to 15s, threaded from config.receive_timeout).
- F11 — Added a clause for a lone trailing \ inside a string at end-of-buffer: it's retained in the buffer so the next chunk can complete the escape sequence.
- F12 — Bumped @Version to "0.2.0-dev" so source_ref and user-agent reflect the current development version. Updated version-dependent tests to use Mix.Project.config()[:version].
- F13 — Fixed the Branch.create doctest: {:ok, resp} = ... then resp["api:status"] instead of {:ok, _} = ... expecting :ok.
@thanos thanos changed the title Add v0.2 APIs (Document, Schema, Branch, Streaming), docs, and guides Add v0.2.0 APIs (Document, Schema, Branch, Streaming), docs, and guides Jun 24, 2026
@thanos
thanos merged commit 93eb9de into main Jun 24, 2026
6 checks passed
@thanos
thanos deleted the v0.2.0 branch June 24, 2026 15:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant