@voxgig/sdkgen 4.34.1 → 4.34.2

package/project/.sdk/src/cmp/rb/ReadmeTopTest_rb.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, seededList, litPair } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,6 +10,7 @@ import {
 
 function rbLit(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 '[]'
@@ -28,13 +29,16 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   if (exampleEntity && primaryOp) {
     const eName = nom(exampleEntity, 'Name')
     const ename = eName.toLowerCase()
-    // Model-driven id key: null when the entity has no id-like field, so the
-    // seeded record carries no id and a match op takes no argument.
+    // Model-driven id key: null when the entity has no id-like field.
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
-    const recBody = idF ? `{ "${idF}" => "test01" }` : '{}'
+    const listed = 'list' === primaryOp ? seededList('rb', exampleEntity, idF, 'test01') : null
+    const recPairs = listed ? listed.record : idF ? [litPair('rb', idF, '"test01"')] : []
+    const recBody = 0 < recPairs.length ? `{ ${recPairs.join(', ')} }` : '{}'
     let callArg = ''
-    if (isMatchOp) {
+    if (listed) {
+      callArg = 0 < listed.call.length ? `{ ${listed.call.join(', ')} }` : ''
+    } else if (isMatchOp) {
       // Every REQUIRED match key (id first, then parent path params like
       // page_id) — the same shape the runtime resolves path params from.
       const items = opRequestShape(exampleEntity, primaryOp).items
@@ -43,24 +47,24 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       callArg = 0 < items.length
         ? `{ ${items.map((it: any) =>
-          `"${it.name}" => ${it.name === idF ? '"test01"' : rbLit(it.type)}`).join(', ')} }`
+          litPair('rb', it.name, it.name === idF ? '"test01"' : rbLit(it.type))).join(', ')} }`
         : ''
     } 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)
-      callArg = `{ ${chosen.map((it: any) => `"${it.name}" => ${rbLit(it.type)}`).join(', ')} }`
+      callArg = `{ ${chosen.map((it: any) => litPair('rb', it.name, rbLit(it.type))).join(', ')} }`
     }
     // A list result is an Array — name the variable accordingly. Sanitise the
     // base name — an entity whose lowercased name is a Ruby keyword (e.g.
-    // `self`) would otherwise emit uncompilable code. The fixture KEY (`ename`)
-    // stays raw so the mock lookup resolves.
+    // `self`) would otherwise emit uncompilable code. The fixture key is the
+    // model name, which the mock looks the entity up by.
     const eVar = exampleVarName(ename, 'rb') + ('list' === primaryOp ? 's' : '')
     Content(`\`\`\`ruby
 # Seed fixture data so offline calls resolve without a live server.
 client = ${model.const.Name}SDK.test({
-  "entity" => { "${ename}" => { "test01" => ${recBody} } },
+  "entity" => { "${exampleEntity.name}" => { "test01" => ${recBody} } },
 })
 ${eVar} = client.${eName}.${primaryOp}(${callArg})
 \`\`\`

package/project/.sdk/src/cmp/rb/fragment/EntityCreateOp.fragment.rb

@@ -7,7 +7,8 @@ require_relative '../core/helpers'
   #
   # @param reqdata [EntityNameCreateData, Hash, nil] body data
   # @param ctrl [Object, nil] optional per-call control
-  # @return [EntityName, Hash] the created EntityName; raises ProjectNameError on failure
+  # @return [EntyClass] the created EntityName entity (data_get reads its record);
+  #   raises ProjectNameError on failure
   def create(reqdata, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({

package/project/.sdk/src/cmp/rb/fragment/EntityListOp.fragment.rb

@@ -5,7 +5,7 @@
   # @param reqmatch [EntityNameListMatch, Hash, nil] match filter (any subset of
   #   EntityName fields); defaults to nil, treated as an empty match that lists all.
   # @param ctrl [Object, nil] optional per-call control
-  # @return [Array<EntityName>] the matching EntityName items, one entity per
+  # @return [Array<EntyClass>] the matching EntityName items, one entity per
   #   record (data_get reads the record); raises ProjectNameError on failure
   def list(reqmatch = nil, ctrl = nil)
     utility = @_utility

package/project/.sdk/src/cmp/rb/fragment/EntityLoadOp.fragment.rb

@@ -9,7 +9,8 @@ require_relative '../core/helpers'
   #   optional — an entity with no id-like key loads with no match (nil is treated
   #   as an empty match, so client.EntityName.load works with no args).
   # @param ctrl [Object, nil] optional per-call control
-  # @return [EntityName, Hash] the loaded EntityName; raises ProjectNameError on failure
+  # @return [EntyClass] the loaded EntityName entity (data_get reads its record);
+  #   raises ProjectNameError on failure
   def load(reqmatch = nil, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({

package/project/.sdk/src/cmp/rb/fragment/EntityPatchOp.fragment.rb

@@ -7,7 +7,8 @@ require_relative '../core/helpers'
   #
   # @param reqdata [EntityNamePatchData, Hash, nil] body data
   # @param ctrl [Object, nil] optional per-call control
-  # @return [EntityName, Hash] the patched EntityName; raises ProjectNameError on failure
+  # @return [EntyClass] the patched EntityName entity (data_get reads its record);
+  #   raises ProjectNameError on failure
   def patch(reqdata, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({

package/project/.sdk/src/cmp/rb/fragment/EntityRemoveOp.fragment.rb

@@ -7,7 +7,8 @@ require_relative '../core/helpers'
   #
   # @param reqmatch [EntityNameRemoveMatch, Hash, nil] match criteria (id/query fields)
   # @param ctrl [Object, nil] optional per-call control
-  # @return [EntityName, Hash] the removed EntityName; raises ProjectNameError on failure
+  # @return [EntyClass] the removed EntityName entity, marked as deleted; raises
+  #   ProjectNameError on failure
   def remove(reqmatch = nil, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({

package/project/.sdk/src/cmp/rb/fragment/EntityUpdateOp.fragment.rb

@@ -7,7 +7,8 @@ require_relative '../core/helpers'
   #
   # @param reqdata [EntityNameUpdateData, Hash, nil] body data
   # @param ctrl [Object, nil] optional per-call control
-  # @return [EntityName, Hash] the updated EntityName; raises ProjectNameError on failure
+  # @return [EntyClass] the updated EntityName entity (data_get reads its record);
+  #   raises ProjectNameError on failure
   def update(reqdata, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({

package/project/.sdk/src/cmp/rb/utility_rb.ts

@@ -6,6 +6,15 @@ import {
   walk,
 } from '@voxgig/struct'
 
+import { listMatchArg } from '@voxgig/sdkgen'
+
+
+// A list's required route and query parameters, as its call's arguments.
+function rbListArgs(entity: any): string {
+  const arg = listMatchArg('rb', entity)
+  return '' === arg ? '' : `(${arg})`
+}
+
 
 function projectPath(suffix?: string): string {
   return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
@@ -112,4 +121,5 @@ export {
   formatRubyHash,
   formatRubyValue,
   projectPath,
+  rbListArgs,
 }

package/project/.sdk/src/cmp/rust/ReadmeEntity_rust.ts

@@ -6,7 +6,7 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { rustVarName, rustMethodName } from './utility_rust'
+import { rustVarName, rustMethodName, rustListMatch } from './utility_rust'
 
 
 // Type names come from the shared canonToType 'rust' column (single source of truth).
@@ -14,6 +14,7 @@ import { rustVarName, rustMethodName } from './utility_rust'
 // A type-correct rust expression constructing a voxgig struct Value.
 function rustLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value::Null'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
   if ('BOOLEAN' === k) return 'Value::Bool(true)'
   if ('ARRAY' === k) return 'Value::empty_list()'
@@ -135,7 +136,7 @@ println!("{:?}", ${eVar}.data(None));
       Content(`#### Example: List
 
 \`\`\`rust
-let ${eVar}s = client.${method}(Value::Noval).list(Value::Noval, Value::Noval).unwrap();
+let ${eVar}s = client.${method}(Value::Noval).list(${rustListMatch(entity)}, Value::Noval).unwrap();
 for ${eVar} in &${eVar}s {
     println!("{:?}", ${eVar}.data(None));
 }

package/project/.sdk/src/cmp/rust/ReadmeHowto_rust.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,
@@ -13,6 +13,7 @@ import { crateIdent, rustVarName, rustMethodName } from './utility_rust'
 // A type-correct rust expression constructing a voxgig struct Value.
 function rustLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value::Null'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
   if ('BOOLEAN' === k) return 'Value::Bool(true)'
   if ('ARRAY' === k) return 'Value::empty_list()'
@@ -37,13 +38,16 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'Value::Noval'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `jo(vec![("${idF}", Value::str("test01"))])` : 'Value::Noval'
+  } else if (exampleEntity && 'list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length) {
+    const chosen = requiredItems(exampleEntity, 'list')
+    testArg = `jo(vec![${chosen.map((it: any) => `(${JSON.stringify(it.name)}, ${rustLit(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 = 0 < chosen.length
-      ? `jo(vec![${chosen.map((it: any) => `("${it.name}", ${rustLit(it.type)})`).join(', ')}])`
+      ? `jo(vec![${chosen.map((it: any) => `(${JSON.stringify(it.name)}, ${rustLit(it.type)})`).join(', ')}])`
       : 'Value::empty_map()'
   }
 

package/project/.sdk/src/cmp/rust/ReadmeQuick_rust.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { crateIdent, rustVarName, rustMethodName } from './utility_rust'
+import { crateIdent, rustVarName, rustMethodName, rustListMatch } from './utility_rust'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -37,6 +37,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   // A type-correct rust expression constructing a voxgig struct Value.
   const rustLit = (type: any, placeholder: string = 'example'): string => {
     const k = canonScalarKey(type)
+    if ('NULL' === k) return 'Value::Null'
     if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
     if ('BOOLEAN' === k) return 'Value::Bool(true)'
     if ('ARRAY' === k) return 'Value::empty_list()'
@@ -72,7 +73,7 @@ let client = ${ctor};
 the \`Result\`. \`data(None)\` reads an entity's record.
 
 \`\`\`rust
-match client.${method}(Value::Noval).list(Value::Noval, Value::Noval) {
+match client.${method}(Value::Noval).list(${rustListMatch(exampleEntity)}, Value::Noval) {
     Ok(${eVar}s) => {
         for ${eVar} in &${eVar}s {
             println!("{:?}", ${eVar}.data(None));

package/project/.sdk/src/cmp/rust/ReadmeRef_rust.ts

@@ -7,7 +7,7 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { crateIdent, rustVarName, rustMethodName } from './utility_rust'
+import { crateIdent, rustVarName, rustMethodName, rustListMatch } from './utility_rust'
 
 
 // Type names come from the shared canonToType 'rust' column (single source of truth).
@@ -15,6 +15,7 @@ import { crateIdent, rustVarName, rustMethodName } from './utility_rust'
 // A type-correct rust expression constructing a voxgig struct Value.
 function rustLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value::Null'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
   if ('BOOLEAN' === k) return 'Value::Bool(true)'
   if ('ARRAY' === k) return 'Value::empty_list()'
@@ -52,8 +53,8 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
       desc: 'Update an existing entity. The data must include the entity id. `Ok` is the updated entity.',
     },
     patch: {
-      sig: `patch(reqdata: Value, ctrl: Value) -> Result<Value, ${errType}>`,
-      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 on `Ok`.',
+      sig: `patch(reqdata: Value, ctrl: Value) -> Result<Rc<Self>, ${errType}>`,
+      desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity id. `Ok` is the patched entity.',
     },
     remove: {
       sig: `remove(reqmatch: Value, ctrl: Value) -> Result<Rc<Self>, ${errType}>`,
@@ -279,7 +280,7 @@ println!("{:?}", result.data(None));
           }
           else if ('list' === opname) {
             Content(`\`\`\`rust
-let results = client.${method}(Value::Noval).list(Value::Noval, Value::Noval).unwrap();
+let results = client.${method}(Value::Noval).list(${rustListMatch(ent)}, Value::Noval).unwrap();
 for ${eVar} in &results {
     println!("{:?}", ${eVar}.data(None));
 }

package/project/.sdk/src/cmp/rust/ReadmeTopQuick_rust.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { crateIdent, rustVarName, rustMethodName } from './utility_rust'
+import { crateIdent, rustVarName, rustMethodName, rustListMatch } from './utility_rust'
 
 
 // A type-correct rust expression constructing a voxgig struct Value for a
@@ -15,6 +15,7 @@ import { crateIdent, rustVarName, rustMethodName } from './utility_rust'
 // render a typed literal.
 function rustLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value::Null'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
   if ('BOOLEAN' === k) return 'Value::Bool(true)'
   if ('ARRAY' === k) return 'Value::empty_list()'
@@ -54,7 +55,7 @@ let client = ${ctor};
 
     if (opnames.includes('list')) {
       Content(`// List all ${eName.toLowerCase()}s (one entity per record, Err on failure)
-let ${eVar}s = client.${method}(Value::Noval).list(Value::Noval, Value::Noval).unwrap();
+let ${eVar}s = client.${method}(Value::Noval).list(${rustListMatch(exampleEntity)}, Value::Noval).unwrap();
 for ${eVar} in &${eVar}s {
     println!("{:?}", ${eVar}.data(None));
 }

package/project/.sdk/src/cmp/rust/ReadmeTopTest_rust.ts

@@ -1,5 +1,5 @@
 
-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,
@@ -14,6 +14,7 @@ import { crateIdent, rustVarName, rustMethodName } from './utility_rust'
 // field's canonical type.
 function rustLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value::Null'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
   if ('BOOLEAN' === k) return 'Value::Bool(true)'
   if ('ARRAY' === k) return 'Value::empty_list()'
@@ -44,16 +45,16 @@ let client = test_sdk(Value::Noval, Value::Noval);
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = 'Value::Noval'
-    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 request match.
-      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
         ? `jo(vec![${items.map((it: any) =>
-          `("${it.name}", ${it.name === idF ? 'Value::str("test01")' : rustLit(it.type)})`).join(', ')}])`
+          `(${JSON.stringify(it.name)}, ${isMatchOp && it.name === idF ? 'Value::str("test01")' : rustLit(it.type)})`).join(', ')}])`
         : 'Value::Noval'
     } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
@@ -61,7 +62,7 @@ let client = test_sdk(Value::Noval, Value::Noval);
       const required = items.filter((it: any) => !it.optional)
       const chosen = required.length ? required : items.slice(0, 3)
       arg = 0 < chosen.length
-        ? `jo(vec![${chosen.map((it: any) => `("${it.name}", ${rustLit(it.type)})`).join(', ')}])`
+        ? `jo(vec![${chosen.map((it: any) => `(${JSON.stringify(it.name)}, ${rustLit(it.type)})`).join(', ')}])`
         : 'Value::empty_map()'
     }
     const eVar = rustVarName(exampleEntity.name)

package/project/.sdk/src/cmp/rust/utility_rust.ts

@@ -4,7 +4,7 @@ import {
   walk,
 } from '@voxgig/struct'
 
-import { sdkName } from '@voxgig/sdkgen'
+import { sdkName, canonScalarKey, requiredItems } from '@voxgig/sdkgen'
 
 
 // Rust keywords (strict + reserved) that are illegal as an identifier.
@@ -150,7 +150,19 @@ function rustRawString(s: string): string {
   return 'r' + hashes + '"' + s + '"' + hashes
 }
 
+// A list's required route and query parameters, as the match it is called with.
+function rustListMatch(entity: any): string {
+  const lit = (type: any): string =>
+    (({ NULL: 'Value::Null', INTEGER: 'Value::Num(1.0)', NUMBER: 'Value::Num(1.0)', BOOLEAN: 'Value::Bool(true)', ARRAY: 'Value::empty_list()', OBJECT: 'Value::empty_map()' }) as any)[canonScalarKey(type)] ?? 'Value::str("example")'
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? `jo(vec![${items.map((it: any) => `(${JSON.stringify(it.name)}, ${lit(it.type)})`).join(', ')}])`
+    : 'Value::Noval'
+}
+
+
 export {
+  rustListMatch,
   rustMethodName,
   rustRawString,
   clean,

package/project/.sdk/src/cmp/scala/EntityTypes_scala.ts

@@ -30,8 +30,9 @@ const SCALA_KEYWORDS = new Set<string>([
 ])
 
 
+// A bare `_` is the wildcard, backquoted or not.
 function scalaIdent(name: string): boolean {
-  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !SCALA_KEYWORDS.has(name)
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !SCALA_KEYWORDS.has(name) && '_' !== name
 }
 
 
@@ -66,8 +67,10 @@ function emitCaseClass(typeName: string, items: any[], log?: any): void {
     return
   }
 
+  // A name ending in `_` lexes with the colon after it as one identifier.
   const params = usable
-    .map((it: any) => `${it.name}: ${canonToType(it.type, LANG)}`)
+    .map((it: any) => `${it.name.endsWith('_') ? '`' + it.name + '`' : it.name}: ` +
+      canonToType(it.type, LANG))
     .join(', ')
   Content(`  final case class ${typeName}(${params})
 

package/project/.sdk/src/cmp/scala/ReadmeEntity_scala.ts

@@ -1,27 +1,16 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, opNeedsAction } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape, opNeedsAction, javaMap, javaMapOf } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { scalaVarName } from './utility_scala'
+import { scalaVarName, scalaListMatch, scalaLit } from './utility_scala'
 
 
 // Type names come from the shared canonToType 'scala' column (single source of truth).
 
-function scalaLit(type: any, placeholder: string = 'example'): string {
-  const k = canonScalarKey(type)
-  if ('INTEGER' === k) return '1L'
-  if ('NUMBER' === k) return '1.0'
-  if ('BOOLEAN' === k) return 'true'
-  if ('ARRAY' === k) return 'java.util.List.of()'
-  if ('OBJECT' === k) return 'java.util.Map.of()'
-  return `"${placeholder}"`
-}
-
-
 // Operation method spelling for Scala: camelCase methods over the loose object
 // model. The op descriptions are language-agnostic.
 const OP_DESC: Record<string, { method: string, desc: string }> = {
@@ -58,7 +47,6 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     // An op that needs an action has no plain call to show.
     const callable = opnames.filter((o: string) => !opNeedsAction(entity.op[o]))
     const fields = Object.values(entity.fields || {})
-    // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
     // Sanitise the local variable name — a camelCased Scala keyword gets a
     // trailing underscore (scalaVarName) so the snippet compiles.
@@ -124,9 +112,9 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       const loadArg = 0 < loadItems.length
-        ? `java.util.Map.of(${loadItems.map((it: any) =>
+        ? javaMapOf(loadItems.map((it: any) =>
           `"${it.name}", ${scalaLit(it.type,
-            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')})`
+            it.name === idF ? entity.name + '_id' : it.name)}`), 'java.util.')
         : 'null'
       Content(`#### Example: Load
 
@@ -141,7 +129,7 @@ val ${eVar} = client.${accessor}(null).load(${loadArg}, null)
       Content(`#### Example: List
 
 \`\`\`scala
-val ${eVar}List = client.${accessor}(null).list(null, null)
+val ${eVar}List = client.${accessor}(null).list(${scalaListMatch(entity)}, null)
 \`\`\`
 
 `)
@@ -153,14 +141,15 @@ val ${eVar}List = client.${accessor}(null).list(null, null)
       // required id and parent keys like page_id — with a real literal.
       const createItems = opRequestShape(entity, 'create').items
         .filter((it: any) => !it.optional)
+      const createMap = javaMap(createItems.length, 'java.util.')
       Content(`#### Example: Create
 
 \`\`\`scala
-val ${eVar} = client.${accessor}(null).create(java.util.Map.of(
+val ${eVar} = client.${accessor}(null).create(${createMap.open}
 `)
       createItems.map((it: any, i: number) => {
         const comma = i < createItems.length - 1 ? ',' : ''
-        Content(`    "${it.name}", ${scalaLit(it.type, 'example_' + it.name)}${comma}  // ${canonToType(it.type, target.name)}
+        Content(`    ${createMap.pair(`"${it.name}", ${scalaLit(it.type, 'example_' + it.name)}`)}${comma}  // ${canonToType(it.type, target.name)}
 `)
       })
       Content(`), null)

package/project/.sdk/src/cmp/scala/ReadmeHowto_scala.ts

@@ -1,24 +1,12 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems, javaMapOf } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { scalaVarName } from './utility_scala'
-
-
-// A type-correct Scala literal for a field's canonical type.
-function scalaLit(type: any): string {
-  const k = canonScalarKey(type)
-  if ('INTEGER' === k) return '1L'
-  if ('NUMBER' === k) return '1.0'
-  if ('BOOLEAN' === k) return 'true'
-  if ('ARRAY' === k) return 'java.util.List.of()'
-  if ('OBJECT' === k) return 'java.util.Map.of()'
-  return '"example"'
-}
+import { scalaVarName, scalaLit } from './utility_scala'
 
 
 const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
@@ -39,23 +27,30 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'null'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `java.util.Map.of("${idF}", "test01")` : 'null'
+  } else if (exampleEntity && 'list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length) {
+    const chosen = requiredItems(exampleEntity, 'list')
+    testArg = javaMapOf(chosen.map((it: any) =>
+      `${JSON.stringify(it.name)}, ${scalaLit(it.type)}`), 'java.util.')
   } 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 = `java.util.Map.of(${chosen.map((it: any) =>
-      `"${it.name}", ${scalaLit(it.type)}`).join(', ')})`
+    testArg = javaMapOf(chosen.map((it: any) =>
+      `${JSON.stringify(it.name)}, ${scalaLit(it.type)}`), 'java.util.')
   }
 
   // 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 raises on error;
-// call data() for the record.
-val ${eVar} = client.${accessor}(null).${primaryOp}(${testArg}, null)
-// ${eVar} holds the mock response record
-println(${eVar})`
+  const testModeExample = 'list' === primaryOp
+    ? `// list returns a list of entities, one per mock record; it raises on error.
+val ${eVar}List = client.${accessor}(null).list(${testArg}, null).asInstanceOf[java.util.List[SdkEntity]]
+${eVar}List.forEach(${eVar}Item => println(${eVar}Item.data()))`
+    : primaryOp
+    ? `// Entity ops return the entity; they raise on error.
+val ${eVar} = client.${accessor}(null).${primaryOp}(${testArg}, null).asInstanceOf[SdkEntity]
+// data() reads the entity's mock record
+println(${eVar}.data())`
     : `val result = client.direct(java.util.Map.of(
     "path", "/api/resource",
     "method", "GET"))

package/project/.sdk/src/cmp/scala/ReadmeModel_scala.ts

@@ -24,12 +24,12 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   entityList.forEach((e: any) => Object.keys(e.op || {})
     .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
   const opRowDefs: Record<string, string> = {
-    load: '| `load` | `(reqmatch, ctrl) -> Object` | Load a single entity by match criteria. Raises on error. |',
-    list: '| `list` | `(reqmatch, ctrl) -> Object` | List entities matching the criteria (an aggregate list). Raises on error. |',
-    create: '| `create` | `(reqdata, ctrl) -> Object` | Create a new entity. Raises on error. |',
-    update: '| `update` | `(reqdata, ctrl) -> Object` | Update an existing entity. Raises on error. |',
-    patch: '| `patch` | `(reqdata, ctrl) -> Object` | Change part of an existing entity. Raises on error. |',
-    remove: '| `remove` | `(reqmatch, ctrl) -> Object` | Remove an entity. Raises on error. |',
+    load: '| `load` | `(reqmatch, ctrl) -> Object` | Load a single entity by match criteria, and return it. Raises on error. |',
+    list: '| `list` | `(reqmatch, ctrl) -> Object` | List entities matching the criteria, one per record. Raises on error. |',
+    create: '| `create` | `(reqdata, ctrl) -> Object` | Create a new entity, and return it. Raises on error. |',
+    update: '| `update` | `(reqdata, ctrl) -> Object` | Update an existing entity, and return it. Raises on error. |',
+    patch: '| `patch` | `(reqdata, ctrl) -> Object` | Change part of an existing entity, and return it. Raises on error. |',
+    remove: '| `remove` | `(reqmatch, ctrl) -> Object` | Remove an entity, and return it marked as deleted. Raises on error. |',
   }
   const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
@@ -94,9 +94,10 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the ENTITY (call data() for the record) (a \`Map\` for single-entity
-ops, an aggregate \`List\` for \`list\`) as \`Object\` and raise on error. Wrap
-calls in \`try\`/\`catch\` to handle failures.
+Entity operations return the entity, and \`list\` a list of entities, one per
+record, as \`Object\`; an entity is an \`SdkEntity\`, whose \`data()\` reads its
+record. They raise on error, so wrap calls in \`try\`/\`catch\` to handle
+failures.
 
 The \`direct()\` escape hatch never raises — it returns a result
 \`java.util.Map[String, Object]\` you branch on via \`result.get("ok")\`: