@reventlessdev/reventless-spec 3.0.0-alpha.107 → 3.0.0-alpha.108

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.108 (2026-08-11)
+
+### Features
+
+* **api:** infer a queryable's key field and publish its provenance ([c835a42](https://github.com/ReventlessDev/reventless-core/commit/c835a42a0da07cdc4a3f010212e1f340a4a0ca27))
+* **plugin:** publish singleQueryField on queryableDef ([a724ab5](https://github.com/ReventlessDev/reventless-core/commit/a724ab573614792c0615d68b6486b94da14f9f82))
+
+
 # 3.0.0-alpha.107 (2026-08-10)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.107",
+  "version": "3.0.0-alpha.108",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {
@@ -21,7 +21,7 @@
     "sury": "11.0.0-alpha.4",
     "sury-ppx": "11.0.0-alpha.2",
     "yaml": "^2.8.3",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.3"
+    "@reventlessdev/rescript-node": "2.0.0-alpha.4"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/components/Plugin.res

@@ -269,6 +269,51 @@ type queryableDef = {
   before this field existed must be reset/re-emitted. See [[deployed-chapter-grouping]].
   */
   chapter: @s.matches(stringOptionSchema) option<string>,
+  /**
+  The singular counterpart of `queryField`: the generated single-entity query
+  (`Plugin_Order(id: ID!)` beside the list field `Plugin_Orders`), and — because
+  `Api_Naming` returns the same string for both — the prefix of the queryable's
+  generated input types (`Plugin_OrderFilter`, `Plugin_OrderOrderBy`). One field
+  rather than two, so the two uses cannot drift apart.
+
+  Published because it is not derivable from `queryField` without re-implementing
+  `Api_Naming.singularize`: a consumer that strips a trailing `s` turns
+  `Plugin_Categories` into `Plugin_Categorie`, a name the schema does not serve,
+  and fails at query time against that one view. Sourced from the naming module
+  itself, never re-derived.
+
+  `None` means not stated — defs persisted before this field existed, and
+  hand-rolled defs that decline to say; a consumer falls back to its own
+  derivation there. js_nullable for the same JSON-safety reason as `statusField`.
+  */
+  singleQueryField: @s.matches(stringOptionSchema) option<string>,
+  /**
+  The state field that identifies a row — the queryable's own key, as opposed to
+  a reference to some other entity. `Products` carries `productId` and
+  `categoryId`; this says which of the two the row is about.
+
+  `None` means unresolved: a state with several `*Id` fields and no name match,
+  or with none at all. Such a component gets no key-derived filter or sort until
+  its spec declares `@id`. Also `None` on defs persisted before this field
+  existed. js_nullable for the same JSON-safety reason as `statusField`.
+  */
+  idField: @s.matches(stringOptionSchema) option<string>,
+  /**
+  Which rung produced `idField`, so a consumer can tell a declaration from a
+  guess — the same reason `labelFieldSource` exists:
+
+  - `"annotation"` — the state declares `@id`. The author said which field keys
+    the row; nothing inferred outranks it.
+  - `"convention"` — a field named `<singular component name>Id` exists
+    (`Products` → `productId`). A guess, and the one guess a client can make for
+    itself.
+  - `"sole"` — the state has exactly one `*Id` field, so there is nothing else
+    the key could be (`AvailableProducts` → `productId`). A guess, and one that
+    needs the state's full field list to make.
+
+  `None` whenever `idField` is `None`, and on defs that predate the field.
+  */
+  idFieldSource: @s.matches(stringOptionSchema) option<string>,
 }
 
 /**

package/src/components/Plugin.res.mjs

@@ -118,7 +118,10 @@ let queryableDefSchema = S.schema(s => ({
   labelFieldSource: s.m(stringOptionSchema),
   statusField: s.m(stringOptionSchema),
   visibility: s.m(stringOptionSchema),
-  chapter: s.m(stringOptionSchema)
+  chapter: s.m(stringOptionSchema),
+  singleQueryField: s.m(stringOptionSchema),
+  idField: s.m(stringOptionSchema),
+  idFieldSource: s.m(stringOptionSchema)
 }));
 
 let eventDefSchema = S.schema(s => ({