From 007004c306395e67da0fb5df0321ddc237173ce9 Mon Sep 17 00:00:00 2001
From: Sven Slootweg <admin@cryto.net>
Date: Mon, 1 Jul 2024 23:38:33 +0200
Subject: [PATCH] Update documentation

---
 README.md | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index c31d519..239e439 100644
--- a/README.md
+++ b/README.md
@@ -151,7 +151,7 @@ The `generateModule` method generates a dlayer module and a number of root queri
 - Extensions for any other `dlayer-knex` types, that are necessary to generate inverse relations. You don't generally have to care about these.
 - A `dlayerKnexTable` value in the module's context, which is a DataLoader that fetches items from the table by its primary key. You don't generally have to care about this, *unless* you need to work around an API limitation; in that case, you can use dlayer's `$getModuleContext` utility function to access it, but keep in mind that this context value is not included in the semver guarantees for this library, and may break between releases.
 
-Separately, a set of root queries is also generated, which you can insert into your root schema where it fits your usecase. Often this will be in a top-level property with the same name as the table, but it doesn't *need* to be there. These root queries are:
+Separately, a static representation of the generated types' `structure` (for introspection, yet to be documented) and a set of root queries are also generated. You can insert the root queries into your root schema where it fits your usecase. Often this will be in a top-level property with the same name as the table, but it doesn't *need* to be there. These root queries are:
 
 ### list
 
@@ -162,8 +162,29 @@ Equivalent to a `SELECT` query, retrieves existing records from a table. Possibl
 - __skip:__ the amount of records to skip at the start; also known as an 'offset' or 'start'.
 - __limit:__ the amount of records to retrieve, counting from the first non-skipped record.
 - __first:__ when set to `true`, only return the first result (or `undefined`), rather than a list of results.
+- __count:__ when set to `true`, return the count of results instead of the results themselves.
 
-This query produces a list of records according to your criteria (or a single one, if `first` has been used).
+This query produces a list of records according to your criteria (or a single one or the total count, if respectively `first` or `count` has been used). When using the `count` argument, all other arguments except for `filter` are disabled, as they are not meaningful when counting results.
+
+Note that inverse relation functions generated on types are *also* list-type queries; you can provide the same set of arguments to them, to filter down the list of related objects. For example, this is a valid query to fetch the last 10 posts for a user named 'testuser':
+
+```js
+await api.query({
+	users: {
+		list: {
+			$arguments: { filter: { username: "testuser" } },
+			id: true,
+			posts: {
+				$arguments: { orderBy: "-postedAt", limit: 10 },
+				id: true,
+				title: true
+			}
+		}
+	}
+})
+```
+
+As before, if you need to specify a more complex relation query than these arguments permit, you should consider adding a custom property with `dlayer` directly instead, which will allow you to structure your query and construct your result objects however you wish.
 
 ### delete