@voxgig/sdkgen 4.34.1 → 4.34.2

package/project/.sdk/src/cmp/clojure/ReadmeRef_clojure.ts

@@ -7,10 +7,13 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
+import { cljListMatch } from './utility_clojure'
+
 
 // A type-correct Clojure literal for a field's canonical type.
 function cljLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'nil'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '(vs/jt)'
@@ -34,34 +37,34 @@ function cljType(type: any): string {
 
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
-    sig: '(load ent reqmatch ctrl) -> map',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+    sig: '(load ent reqmatch ctrl) -> entity',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `((:data-get ent))` reads, and raises on error.',
   },
   list: {
     sig: '(list ent reqmatch ctrl) -> vector',
-    returns: 'a vector of entities',
-    desc: 'List entities matching the given criteria. The match is optional — call with `nil` to list all records. Returns a vector and raises on error.',
+    returns: 'a vector of entities, one per record',
+    desc: 'List entities matching the given criteria. The match is optional — call with `nil` to list all records. Returns a vector of entities, one per record, and raises on error.',
   },
   create: {
-    sig: '(create ent reqdata ctrl) -> map',
-    returns: 'the created entity data',
-    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
+    sig: '(create ent reqdata ctrl) -> entity',
+    returns: 'the created entity',
+    desc: 'Create a new entity with the given data. Returns the created entity and raises on error.',
   },
   update: {
-    sig: '(update ent reqdata ctrl) -> map',
-    returns: 'the updated entity data',
-    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and raises on error.',
+    sig: '(update ent reqdata ctrl) -> entity',
+    returns: 'the updated entity',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and raises on error.',
   },
   patch: {
-    sig: '(patch ent reqdata ctrl) -> map',
-    returns: 'the patched entity data',
-    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity data and raises on error.',
+    sig: '(patch ent reqdata ctrl) -> entity',
+    returns: 'the patched entity',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity and raises on error.',
   },
   remove: {
-    sig: '(remove ent reqmatch ctrl) -> map',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Raises on error.',
+    sig: '(remove ent reqmatch ctrl) -> entity',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and raises on error.',
   },
 }
 
@@ -289,7 +292,7 @@ ${info.desc}
           }
           else if ('list' === opname) {
             Content(`\`\`\`clojure
-(doseq [${eLow} (e-${eLow}/list (api/${eLow} client nil) nil nil)]
+(doseq [${eLow} (e-${eLow}/list (api/${eLow} client nil) ${cljListMatch(ent)} nil)]
   (println ((:data-get ${eLow}))))
 \`\`\`
 

package/project/.sdk/src/cmp/clojure/ReadmeTopQuick_clojure.ts

@@ -7,11 +7,14 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { cljListMatch } from './utility_clojure'
+
 
 // A type-correct Clojure literal for a param: numeric/boolean/array/object
 // params render a typed literal; strings render the quoted placeholder.
 function cljLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'nil'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '(vs/jt)'
@@ -52,7 +55,7 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
 
     if (opnames.includes('list')) {
       Content(`;; List all ${eLow}s (a vector of entities, one per record; raises on error)
-(doseq [${eLow} (e-${eLow}/list (api/${eLow} client nil) nil nil)]
+(doseq [${eLow} (e-${eLow}/list (api/${eLow} client nil) ${cljListMatch(exampleEntity)} nil)]
   (println ((:data-get ${eLow}))))
 `)
     }
@@ -71,9 +74,9 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(' ')})`
         : 'nil'
       Content(`
-;; Load a specific ${eLow} (returns the record, raises on error)
+;; Load a specific ${eLow} (returns the entity, raises on error)
 (def ${eLow} (e-${eLow}/load (api/${eLow} client nil) ${loadArg} nil))
-(println ${eLow})
+(println ((:data-get ${eLow})))
 `)
     }
 

package/project/.sdk/src/cmp/clojure/ReadmeTopTest_clojure.ts

@@ -1,15 +1,18 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
+import { cljString } from './utility_clojure'
+
 
 // A type-correct Clojure literal for a field's canonical type.
 function cljLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'nil'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '(vs/jt)'
@@ -43,27 +46,31 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = 'nil'
-    if (isMatchOp) {
+    if (isMatchOp || ('list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length)) {
       // Every REQUIRED match key (id first) — the same shape that generates
       // the op's match handling.
-      const items = opRequestShape(exampleEntity, primaryOp).items
-        .filter((it: any) => !it.optional || it.name === idF)
+      const items = (isMatchOp ? opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF) : requiredItems(exampleEntity, 'list'))
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       arg = 0 < items.length
         ? `(vs/jm ${items.map((it: any) =>
-          `"${it.name}" ${it.name === idF ? '"test01"' : cljLit(it.type)}`).join(' ')})`
+          `${cljString(it.name)} ${isMatchOp && it.name === idF ? '"test01"' : cljLit(it.type)}`).join(' ')})`
         : 'nil'
     } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
       const required = items.filter((it: any) => !it.optional)
       const chosen = required.length ? required : items.slice(0, 3)
-      arg = `(vs/jm ${chosen.map((it: any) => `"${it.name}" ${cljLit(it.type)}`).join(' ')})`
+      arg = `(vs/jm ${chosen.map((it: any) => `${cljString(it.name)} ${cljLit(it.type)}`).join(' ')})`
     }
-    const eVar = eLow + ('list' === primaryOp ? 's' : '')
-    Content(`(def ${eVar} (e-${eLow}/${primaryOp} (api/${eLow} client nil) ${arg} nil))
-(println ${eVar})
+    Content('list' === primaryOp
+      ? `(def ${eLow}s (e-${eLow}/list (api/${eLow} client nil) ${arg} nil))
+(doseq [item ${eLow}s]
+  (println ((:data-get item))))
+`
+      : `(def ${eLow} (e-${eLow}/${primaryOp} (api/${eLow} client nil) ${arg} nil))
+(println ((:data-get ${eLow})))
 `)
   }
 

package/project/.sdk/src/cmp/clojure/TestClean_clojure.ts

@@ -479,11 +479,11 @@ ${candidates(entity)}
     (fn []
       (let [cfg (core/make-clean-config (vs/jm "keys" "key,secret,token"))
             ctx (atom {:options (vs/jm "__derived__" (vs/jm "clean" cfg))})
+            _ (core/u-clean-add-sensitive ctx (vs/jm "apikey" (vs/jm "value" "NESTED-SECRET-1")
+                                                     "headers" (vs/jm "X-Api-Token" (vs/jt "LISTED-SECRET-2"))
+                                                     "secret" 123456789
+                                                     "name" "not-a-secret"))
             values (vs/getprop cfg "values")]
-        (core/u-clean-add-sensitive ctx (vs/jm "apikey" (vs/jm "value" "NESTED-SECRET-1")
-                                               "headers" (vs/jm "X-Api-Token" (vs/jt "LISTED-SECRET-2"))
-                                               "secret" 123456789
-                                               "name" "not-a-secret"))
         (t/is-true (.contains ^java.util.List values "NESTED-SECRET-1") "nested under apikey")
         (t/is-true (.contains ^java.util.List values "LISTED-SECRET-2") "listed under a token header")
         (t/is-true (.contains ^java.util.List values "123456789") "a number, as its text")

package/project/.sdk/src/cmp/clojure/fragment/Entity.fragment.clj

@@ -132,7 +132,8 @@
 ;; materialises the whole result). When the streaming feature is active the
 ;; result carries a `stream` thunk and this yields from it (honouring
 ;; chunkSize); otherwise it falls back to the materialised items, so stream
-;; always yields. Records are unwrapped to bare struct maps (matching list).
+;; always yields. An entity is yielded as its record, the struct map its
+;; data-get returns.
 ;; `callopts` parameterises the call:
 ;;   - ctrl:   per-call pipeline control (threaded onto the op ctx);
 ;;   - body:   an async-iterable/list payload for outbound (upload) streaming,

package/project/.sdk/src/cmp/clojure/utility_clojure.ts

@@ -6,6 +6,8 @@ import {
   walk,
 } from '@voxgig/struct'
 
+import { canonScalarKey, requiredItems } from '@voxgig/sdkgen'
+
 
 function projectPath(suffix?: string): string {
   return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
@@ -119,7 +121,19 @@ function cljStringChunks(json: string, maxBytes: number = 20000): string[] {
   return 0 === chunks.length ? [''] : chunks
 }
 
+// A list's required route and query parameters, as the match it is called with.
+function cljListMatch(entity: any): string {
+  const lit = (type: any): string =>
+    (({ NULL: 'nil', INTEGER: '1', NUMBER: '1', BOOLEAN: 'true', ARRAY: '(vs/jt)', OBJECT: '(vs/jm)' }) as any)[canonScalarKey(type)] ?? '"example"'
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? `(vs/jm ${items.map((it: any) => `${cljString(it.name)} ${lit(it.type)}`).join(' ')})`
+    : 'nil'
+}
+
+
 export {
+  cljListMatch,
   cljStringChunks,
   clean,
   formatCljValue,

package/project/.sdk/src/cmp/cpp/ReadmeEntity_cpp.ts

@@ -6,7 +6,7 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { cppVarName } from './utility_cpp'
+import { cppVarName, cppListMatch } from './utility_cpp'
 
 
 // Type names come from the shared canonToType 'cpp' column (single source of truth).
@@ -14,6 +14,7 @@ import { cppVarName } from './utility_cpp'
 // A type-correct C++ literal for a field's canonical type.
 function cppLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value(nullptr)'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
   if ('BOOLEAN' === k) return 'Value(true)'
   if ('ARRAY' === k) return 'vlist()'
@@ -140,7 +141,7 @@ std::cout << Struct::jsonify(${eVar}->data()) << std::endl;
       Content(`#### Example: List
 
 \`\`\`cpp
-std::vector<SdkEntityPtr> ${eVar}s = client->${acc}()->list(Value::undef(), Value::undef());
+std::vector<SdkEntityPtr> ${eVar}s = client->${acc}()->list(${cppListMatch(entity)}, Value::undef());
 for (const auto& ${eVar} : ${eVar}s) {
   std::cout << Struct::jsonify(${eVar}->data()) << std::endl;
 }

package/project/.sdk/src/cmp/cpp/ReadmeHowto_cpp.ts

@@ -1,17 +1,18 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { cppVarName } from './utility_cpp'
+import { cppVarName, cppEscape } from './utility_cpp'
 
 
 // A type-correct C++ literal for a field's canonical type.
 function cppLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value(nullptr)'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
   if ('BOOLEAN' === k) return 'Value(true)'
   if ('ARRAY' === k) return 'vlist()'
@@ -36,12 +37,15 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'Value::undef()'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `vmap({{"${idF}", Value("test01")}})` : 'Value::undef()'
+  } else if (exampleEntity && 'list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length) {
+    const chosen = requiredItems(exampleEntity, 'list')
+    testArg = `vmap({${chosen.map((it: any) => `{"${cppEscape(it.name)}", ${cppLit(it.type)}}`).join(', ')}})`
   } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp)) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => it.name !== idF && it.name !== 'id')
     const required = items.filter((it: any) => !it.optional)
     const chosen = required.length ? required : items.slice(0, 3)
-    testArg = `vmap({${chosen.map((it: any) => `{"${it.name}", ${cppLit(it.type)}}`).join(', ')}})`
+    testArg = `vmap({${chosen.map((it: any) => `{"${cppEscape(it.name)}", ${cppLit(it.type)}}`).join(', ')}})`
   }
 
   // The op-driven test-mode line, shown only when the SDK has an entity op.

package/project/.sdk/src/cmp/cpp/ReadmeQuick_cpp.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { cppVarName } from './utility_cpp'
+import { cppVarName, cppListMatch } from './utility_cpp'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -57,6 +57,7 @@ ${ctor}
   // params render a typed sdk::Value; strings render the quoted placeholder.
   const cppLit = (type: any, placeholder: string = 'example'): string => {
     const k = canonScalarKey(type)
+    if ('NULL' === k) return 'Value(nullptr)'
     if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
     if ('BOOLEAN' === k) return 'Value(true)'
     if ('ARRAY' === k) return 'vlist()'
@@ -84,7 +85,7 @@ ${ctor}
 
 \`\`\`cpp
 try {
-  std::vector<SdkEntityPtr> ${eVar}s = client->${acc}()->list(Value::undef(), Value::undef());
+  std::vector<SdkEntityPtr> ${eVar}s = client->${acc}()->list(${cppListMatch(exampleEntity)}, Value::undef());
   for (const auto& ${eVar} : ${eVar}s) {
     std::cout << Struct::jsonify(${eVar}->data()) << std::endl;
   }

package/project/.sdk/src/cmp/cpp/ReadmeRef_cpp.ts

@@ -7,7 +7,7 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { cppVarName } from './utility_cpp'
+import { cppVarName, cppListMatch } from './utility_cpp'
 
 
 // Type names come from the shared canonToType 'cpp' column (single source of truth).
@@ -15,6 +15,7 @@ import { cppVarName } from './utility_cpp'
 // A type-correct C++ literal for a field's canonical type.
 function cppLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value(nullptr)'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
   if ('BOOLEAN' === k) return 'Value(true)'
   if ('ARRAY' === k) return 'vlist()'
@@ -45,9 +46,9 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
     desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and throws on error.',
   },
   patch: {
-    sig: 'patch(reqdata, ctrl) -> Value',
-    returns: 'the patched entity data',
-    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity data and throws on error.',
+    sig: 'patch(reqdata, ctrl) -> SdkEntityPtr',
+    returns: 'the patched entity',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity and throws on error.',
   },
   remove: {
     sig: 'remove(reqmatch, ctrl) -> SdkEntityPtr',
@@ -283,7 +284,7 @@ std::cout << Struct::jsonify(result->data()) << std::endl;
           }
           else if ('list' === opname) {
             Content(`\`\`\`cpp
-std::vector<SdkEntityPtr> results = client->${acc}()->list(Value::undef(), Value::undef());
+std::vector<SdkEntityPtr> results = client->${acc}()->list(${cppListMatch(ent)}, Value::undef());
 for (const auto& ${acc} : results) {
   std::cout << Struct::jsonify(${acc}->data()) << std::endl;
 }

package/project/.sdk/src/cmp/cpp/ReadmeTopQuick_cpp.ts

@@ -6,12 +6,13 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { cppVarName } from './utility_cpp'
+import { cppVarName, cppListMatch } from './utility_cpp'
 
 
 // A type-correct C++ literal for a param.
 function cppLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value(nullptr)'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
   if ('BOOLEAN' === k) return 'Value(true)'
   if ('ARRAY' === k) return 'vlist()'
@@ -58,7 +59,7 @@ ${ctor}
 
     if (opnames.includes('list')) {
       Content(`// List all ${acc}s (one entity per record, throws on error)
-std::vector<SdkEntityPtr> ${eVar}s = client->${acc}()->list(Value::undef(), Value::undef());
+std::vector<SdkEntityPtr> ${eVar}s = client->${acc}()->list(${cppListMatch(exampleEntity)}, Value::undef());
 for (const auto& ${eVar} : ${eVar}s) {
   std::cout << Struct::jsonify(${eVar}->data()) << std::endl;
 }

package/project/.sdk/src/cmp/cpp/ReadmeTopTest_cpp.ts

@@ -1,17 +1,18 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { cppVarName } from './utility_cpp'
+import { cppVarName, cppEscape } from './utility_cpp'
 
 
 // A type-correct C++ literal for a field's canonical type.
 function cppLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value(nullptr)'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
   if ('BOOLEAN' === k) return 'Value(true)'
   if ('ARRAY' === k) return 'vlist()'
@@ -37,21 +38,21 @@ auto client = ${model.const.Name}SDK::testSDK();
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = 'Value::undef()'
-    if (isMatchOp) {
-      const items = opRequestShape(exampleEntity, primaryOp).items
-        .filter((it: any) => !it.optional || it.name === idF)
+    if (isMatchOp || ('list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length)) {
+      const items = (isMatchOp ? opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF) : requiredItems(exampleEntity, 'list'))
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       arg = 0 < items.length
         ? `vmap({${items.map((it: any) =>
-          `{"${it.name}", ${it.name === idF ? 'Value("test01")' : cppLit(it.type)}}`).join(', ')}})`
+          `{"${cppEscape(it.name)}", ${isMatchOp && it.name === idF ? 'Value("test01")' : cppLit(it.type)}}`).join(', ')}})`
         : 'Value::undef()'
     } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
       const required = items.filter((it: any) => !it.optional)
       const chosen = required.length ? required : items.slice(0, 3)
-      arg = `vmap({${chosen.map((it: any) => `{"${it.name}", ${cppLit(it.type)}}`).join(', ')}})`
+      arg = `vmap({${chosen.map((it: any) => `{"${cppEscape(it.name)}", ${cppLit(it.type)}}`).join(', ')}})`
     }
     if ('list' === primaryOp) {
       Content(`for (const auto& ${acc} : client->${acc}()->list(${arg}, Value::undef())) {

package/project/.sdk/src/cmp/cpp/utility_cpp.ts

@@ -4,6 +4,8 @@ import {
   walk,
 } from '@voxgig/struct'
 
+import { canonScalarKey, requiredItems } from '@voxgig/sdkgen'
+
 
 const CPP_RESERVED = new Set<string>([
   'alignas', 'alignof', 'and', 'and_eq', 'asm', 'auto', 'bitand', 'bitor',
@@ -97,8 +99,19 @@ function cppConfigLiterals(value: any): string {
   return parts.join('\n')
 }
 
+// A list's required route and query parameters, as the match it is called with.
+function cppListMatch(entity: any): string {
+  const lit = (type: any): string =>
+    (({ NULL: 'Value(nullptr)', INTEGER: 'Value(1)', NUMBER: 'Value(1)', BOOLEAN: 'Value(true)', ARRAY: 'vlist()', OBJECT: 'vmap()' }) as any)[canonScalarKey(type)] ?? 'Value("example")'
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? `vmap({${items.map((it: any) => `{"${cppEscape(it.name)}", ${lit(it.type)}}`).join(', ')}})`
+    : 'Value::undef()'
+}
+
 
 export {
+  cppListMatch,
   cleanModel,
   cppConfigLiterals,
   cppEscape,

package/project/.sdk/src/cmp/csharp/ReadmeEntity_csharp.ts

@@ -6,7 +6,7 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { csVarName } from './utility_csharp'
+import { csVarName, csListMatch } from './utility_csharp'
 
 
 // Type names come from the shared canonToType 'csharp' column (single source of truth).
@@ -14,6 +14,7 @@ import { csVarName } from './utility_csharp'
 // A type-correct, JSON-serialisable C# literal for a field's canonical type.
 function csLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k) return '1L'
   if ('NUMBER' === k) return '1.0'
   if ('BOOLEAN' === k) return 'true'
@@ -140,7 +141,7 @@ var ${eVar} = client.${entity.Name}().Load(${loadArg});
       Content(`#### Example: List
 
 \`\`\`csharp
-var ${eVar}List = client.${entity.Name}().List(null);
+var ${eVar}List = client.${entity.Name}().List(${csListMatch(entity)});
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/csharp/ReadmeHowto_csharp.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,12 +7,13 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { csVarName } from './utility_csharp'
+import { csVarName, csStringLiteral } from './utility_csharp'
 
 
 // A type-correct C# literal for a field's canonical type.
 function csLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k) return '1L'
   if ('NUMBER' === k) return '1.0'
   if ('BOOLEAN' === k) return 'true'
@@ -39,22 +40,33 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'null'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `new Dictionary<string, object?> { ["${idF}"] = "test01" }` : 'null'
+  } else if (exampleEntity && 'list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length) {
+    const chosen = requiredItems(exampleEntity, 'list')
+    testArg = `new Dictionary<string, object?> {${chosen.map((it: any) =>
+      ` [${csStringLiteral(it.name)}] = ${csLit(it.type)}`).join(',')} }`
   } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp)) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => it.name !== idF && it.name !== 'id')
     const required = items.filter((it: any) => !it.optional)
     const chosen = required.length ? required : items.slice(0, 3)
     testArg = `new Dictionary<string, object?> {${chosen.map((it: any) =>
-      ` ["${it.name}"] = ${csLit(it.type)}`).join(',')} }`
+      ` [${csStringLiteral(it.name)}] = ${csLit(it.type)}`).join(',')} }`
   }
 
   // The op-driven test-mode line, shown only when the SDK has an entity op.
   // A direct()-only SDK (no ops anywhere) shows a direct() call instead.
-  const testModeExample = primaryOp
-    ? `// Entity ops return the entity, and List one per record; they raise on error.
-var ${eVar} = client.${eName}().${opMethod}(${testArg});
-// Data() on an entity reads its mock response record
-Console.WriteLine(${eVar});`
+  const testModeExample = 'list' === primaryOp
+    ? `// List returns a list of entities, one per mock record; it raises on error.
+var ${eVar}List = (List<object?>)client.${eName}().List(${testArg})!;
+foreach (var ${eVar}Item in ${eVar}List)
+{
+    Console.WriteLine(StructUtils.Jsonify(((IEntity)${eVar}Item!).Data()));
+}`
+    : primaryOp
+    ? `// Entity ops return the entity; they raise on error.
+var ${eVar} = (IEntity)client.${eName}().${opMethod}(${testArg})!;
+// Data() reads the entity's mock record
+Console.WriteLine(StructUtils.Jsonify(${eVar}.Data()));`
     : `var result = client.Direct(new Dictionary<string, object?>
 {
     ["path"] = "/api/resource",

package/project/.sdk/src/cmp/csharp/ReadmeQuick_csharp.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { csVarName } from './utility_csharp'
+import { csVarName, csListMatch } from './utility_csharp'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -37,6 +37,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
 \`\`\`csharp
 using ${model.const.Name}Sdk;
+using Voxgig.Struct;
 
 var client = ${ctor};
 \`\`\`
@@ -57,6 +58,7 @@ var client = ${ctor};
     // A type-correct C# literal for a param.
     const csLit = (type: any, placeholder: string = 'example'): string => {
       const k = canonScalarKey(type)
+      if ('NULL' === k) return 'null'
       if ('INTEGER' === k) return '1L'
       if ('NUMBER' === k) return '1.0'
       if ('BOOLEAN' === k) return 'true'
@@ -69,13 +71,16 @@ var client = ${ctor};
       Content(`### 2. List ${eName.toLowerCase()} records
 
 \`List(null)\` returns a list of entities, one per record (as \`object?\`), and
-raises on error.
+raises on error; an entity's \`Data()\` reads its record.
 
 \`\`\`csharp
 try
 {
-    var ${eVar}List = client.${eName}().List(null);
-    Console.WriteLine(${eVar}List);
+    var ${eVar}List = (List<object?>)client.${eName}().List(${csListMatch(exampleEntity)})!;
+    foreach (var ${eVar}Item in ${eVar}List)
+    {
+        Console.WriteLine(StructUtils.Jsonify(((IEntity)${eVar}Item!).Data()));
+    }
 }
 catch (Exception err)
 {
@@ -114,8 +119,8 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 \`\`\`csharp
 try
 {
-    var ${neVar} = client.${neName}().Load(new Dictionary<string, object?> { ${neMatch.join(', ')} });
-    Console.WriteLine(${neVar});
+    var ${neVar} = (IEntity)client.${neName}().Load(new Dictionary<string, object?> { ${neMatch.join(', ')} })!;
+    Console.WriteLine(StructUtils.Jsonify(${neVar}.Data()));
 }
 catch (Exception err)
 {
@@ -145,8 +150,8 @@ catch (Exception err)
 \`\`\`csharp
 try
 {
-    var ${eVar} = client.${eName}().Load(${loadArg});
-    Console.WriteLine(${eVar});
+    var ${eVar} = (IEntity)client.${eName}().Load(${loadArg})!;
+    Console.WriteLine(StructUtils.Jsonify(${eVar}.Data()));
 }
 catch (Exception err)
 {