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

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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
+
+* **core:** collect [@ref](https://github.com/ref) declared on an array field ([6f9e2fe](https://github.com/ReventlessDev/reventless-core/commit/6f9e2fef2568ad57a8bf2efbaa9cd4830a947f26))
+
+
 # 3.0.0-alpha.106 (2026-08-09)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.106",
+  "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 => ({

package/src/components/Reference.res

@@ -46,6 +46,35 @@ let getTarget = (schema: S.t<unknown>): option<target> =>
   | _ => None
   }
 
+/**
+The entity a *field* references, wherever inside the field's type the marker sits.
+
+`to_` returns an element schema — a `S.t<string>` — so on `@ref("E") ids:
+array<string>` the ppx annotates the `string` *inside* the array and the field's
+own schema carries nothing. `getTarget` answers `None` there, which is not the
+same as the field declaring no reference: a consumer that finds no declared
+reference falls back to a naming heuristic and resolves the field to whatever
+entity the name suggests, so a dropped `@ref` is a *different* resolution rather
+than a missing one. Any walk collecting a command's or event's references must
+ask this question, not `getTarget`.
+
+Only wrappers around the field's own value are followed — the optional union and
+the array element, to any depth. Object properties are not: a reference declared
+on a nested record's field belongs to that field, and attributing it to the
+enclosing one would name the wrong field.
+*/
+let rec getFieldTarget = (schema: S.t<unknown>): option<target> =>
+  switch getTarget(schema) {
+  | Some(_) as found => found
+  | None =>
+    // `getTarget` already reads through the optional wrapper; the *shape* inside
+    // it still has to be unwrapped here to reach an optional array's element.
+    switch schema->Semantic.unwrapOptional->Option.getOr(schema) {
+    | Array({additionalItems: Schema(item)}) => getFieldTarget(item)
+    | _ => None
+    }
+  }
+
 /**
 Like `to_` but does not imply DCB tag semantics.
 Use with `@ref("Entity") @noDcbTag` when the field references another entity

package/src/components/Reference.res.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as DcbTag$Reventless from "./DcbTag.res.mjs";
 import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
 
@@ -32,6 +33,26 @@ function getTarget(schema) {
   }
 }
 
+function getFieldTarget(_schema) {
+  while (true) {
+    let schema = _schema;
+    let found = getTarget(schema);
+    if (found !== undefined) {
+      return found;
+    }
+    let match = Stdlib_Option.getOr(Semantic$Reventless.unwrapOptional(schema), schema);
+    if (match.type !== "array") {
+      return;
+    }
+    let item = match.additionalItems;
+    if (item === "strip" || item === "strict") {
+      return;
+    }
+    _schema = item;
+    continue;
+  };
+}
+
 function toWithoutDcbTag(plugin, entity) {
   return Semantic$Reventless.mark(S.string, Semantic$Reventless.Id.reference, {
     TAG: "ReferenceTo",
@@ -45,6 +66,7 @@ function toWithoutDcbTag(plugin, entity) {
 export {
   to_,
   getTarget,
+  getFieldTarget,
   toWithoutDcbTag,
 }
 /* S Not a pure module */

package/src/semantic/Semantic.res

@@ -117,39 +117,49 @@ let refined = (base: S.t<'a>, ~id: string, ~check: 'a => result<'a, string>): S.
 let showString = (raw: string): string => raw->JSON.Encode.string->JSON.stringify
 
 /**
-The semantic a field's schema carries, if any.
+The schema an optional field's wrapper stands for, if it is one.
 
-An **optional** field keeps its marker one level down. The ppx annotates the
-field's `string`, and sury-ppx then wraps that schema in a union with
-`Undefined`/`Null`; the wrapper is a new schema and carries no metadata of its
-own. So a walk that reads only the outer schema sees `imageUrl?: string` as
-carrying no semantic at all — the store goes undeclared, the reference goes
-uncollected, the branded scalar loses its brand. Every reader converges here, so
-following the wrapper once here is what keeps "optional" a statement about
-presence rather than a way to lose the field's type.
+sury-ppx compiles `f?: X` to a union of `X`'s schema with `Undefined`/`Null`, and
+that wrapper is a new schema carrying no metadata of its own. Every reader that
+looks *through* a field — for its semantic, or for the element type inside it —
+needs the same one-level unwrap, so it lives here once rather than once per
+reader.
 
-The outer schema is read first, so a marker set on the wrapper itself still wins.
 Only a union with exactly one non-null variant is followed: that is the shape an
 optional field has, and a genuine multi-variant union has no single inner schema
-whose semantic could stand for the whole.
+that could stand for the whole.
 */
-let rec getFrom = (schema: S.t<unknown>): option<t> =>
-  switch S.Metadata.get(schema, ~id=semanticId) {
-  | Some(_) as found => found
-  | None =>
-    switch schema {
-    | Union({anyOf}) =>
-      switch anyOf->Array.filter(v =>
-        switch v {
-        | Null(_) | Undefined(_) => false
-        | _ => true
-        }
-      ) {
-      | [inner] => getFrom(inner)
-      | _ => None
+let unwrapOptional = (schema: S.t<unknown>): option<S.t<unknown>> =>
+  switch schema {
+  | Union({anyOf}) =>
+    switch anyOf->Array.filter(v =>
+      switch v {
+      | Null(_) | Undefined(_) => false
+      | _ => true
       }
+    ) {
+    | [inner] => Some(inner)
     | _ => None
     }
+  | _ => None
+  }
+
+/**
+The semantic a field's schema carries, if any.
+
+An **optional** field keeps its marker one level down, inside the wrapper
+`unwrapOptional` describes. So a walk that reads only the outer schema sees
+`imageUrl?: string` as carrying no semantic at all — the store goes undeclared,
+the reference goes uncollected, the branded scalar loses its brand. Every reader
+converges here, so following the wrapper once here is what keeps "optional" a
+statement about presence rather than a way to lose the field's type.
+
+The outer schema is read first, so a marker set on the wrapper itself still wins.
+*/
+let rec getFrom = (schema: S.t<unknown>): option<t> =>
+  switch S.Metadata.get(schema, ~id=semanticId) {
+  | Some(_) as found => found
+  | None => schema->unwrapOptional->Option.flatMap(getFrom)
   }
 
 let get = (fieldSchema: S.t<'a>): option<t> => fieldSchema->S.castToUnknown->getFrom

package/src/semantic/Semantic.res.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 
 let Id = {
   dateTime: "dateTime",
@@ -44,31 +45,33 @@ function showString(raw) {
   return JSON.stringify(raw);
 }
 
-function getFrom(_schema) {
-  while (true) {
-    let schema = _schema;
-    let found = S.Metadata.get(schema, semanticId);
-    if (found !== undefined) {
-      return found;
-    }
-    if (schema.type !== "union") {
-      return;
-    }
-    let match = schema.anyOf.filter(v => {
-      switch (v.type) {
-        case "null" :
-        case "undefined" :
-          return false;
-        default:
-          return true;
-      }
-    });
-    if (match.length !== 1) {
-      return;
+function unwrapOptional(schema) {
+  if (schema.type !== "union") {
+    return;
+  }
+  let match = schema.anyOf.filter(v => {
+    switch (v.type) {
+      case "null" :
+      case "undefined" :
+        return false;
+      default:
+        return true;
     }
-    _schema = match[0];
-    continue;
-  };
+  });
+  if (match.length !== 1) {
+    return;
+  } else {
+    return match[0];
+  }
+}
+
+function getFrom(schema) {
+  let found = S.Metadata.get(schema, semanticId);
+  if (found !== undefined) {
+    return found;
+  } else {
+    return Stdlib_Option.flatMap(unwrapOptional(schema), getFrom);
+  }
 }
 
 let get = getFrom;
@@ -88,6 +91,7 @@ export {
   mark,
   refined,
   showString,
+  unwrapOptional,
   getFrom,
   get,
   has,