@voxgig/sdkgen 4.34.1 → 4.34.2

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityOps } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityOps, javaMapOf } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { scalaVarName, scalaPackage } from './utility_scala'
+import { scalaVarName, scalaPackage, scalaListMatch, scalaLit } from './utility_scala'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -32,23 +32,12 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const authActive = isAuthActive(model)
 
-  // A type-correct Scala literal for a param — the loose object model means
-  // all values live in a java.util.Map[String, Object].
-  const 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}"`
-  }
-
   if (authActive) {
     Content(`### 1. Create a client
 
 \`\`\`scala
 import ${scalaPackage(model)}.core.${SDK}
+import ${scalaPackage(model)}.core.SdkEntity
 
 val options = new java.util.LinkedHashMap[String, Object]()
 options.put("apikey", System.getenv("${envName(model)}_APIKEY"))
@@ -62,6 +51,7 @@ val client = new ${SDK}(options)
 
 \`\`\`scala
 import ${scalaPackage(model)}.core.${SDK}
+import ${scalaPackage(model)}.core.SdkEntity
 
 val client = new ${SDK}()
 \`\`\`
@@ -84,13 +74,13 @@ val client = new ${SDK}()
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list(null, null)\` returns an aggregate list of records (as \`Object\`, an
-aggregate list) and raises on error.
+\`list(null, null)\` returns a list of entities, one per record (as \`Object\`),
+and raises on error; an entity's \`data()\` reads its record.
 
 \`\`\`scala
 try {
-    val ${eVar}List = client.${accessor}(null).list(null, null)
-    println(${eVar}List)
+    val ${eVar}List = client.${accessor}(null).list(${scalaListMatch(exampleEntity)}, null).asInstanceOf[java.util.List[SdkEntity]]
+    ${eVar}List.forEach(${eVar}Item => println(${eVar}Item.data()))
 }
 catch {
     case err: RuntimeException => println("list failed: " + err.getMessage)
@@ -127,8 +117,8 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 
 \`\`\`scala
 try {
-    val ${neVar} = client.${neAccessor}(null).load(java.util.Map.of(${neMatch.join(', ')}), null)
-    println(${neVar})
+    val ${neVar} = client.${neAccessor}(null).load(${javaMapOf(neMatch, 'java.util.')}, null).asInstanceOf[SdkEntity]
+    println(${neVar}.data())
 }
 catch {
     case err: RuntimeException => println("load failed: " + err.getMessage)
@@ -144,9 +134,9 @@ catch {
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       const loadArg = 0 < loadRequired.length
-        ? `java.util.Map.of(${loadRequired.map((it: any) =>
+        ? javaMapOf(loadRequired.map((it: any) =>
           `"${it.name}", ${scalaLit(it.type,
-            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')})`
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`), 'java.util.')
         : 'null'
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
@@ -155,8 +145,8 @@ catch {
 
 \`\`\`scala
 try {
-    val ${eVar} = client.${accessor}(null).load(${loadArg}, null)
-    println(${eVar})
+    val ${eVar} = client.${accessor}(null).load(${loadArg}, null).asInstanceOf[SdkEntity]
+    println(${eVar}.data())
 }
 catch {
     case err: RuntimeException => println("load failed: " + err.getMessage)
@@ -193,7 +183,7 @@ catch {
 `)
       if (opnames.includes('create')) {
         Content(`// Create — returns the ENTITY (call data() for the record)
-val created = client.${accessor}(null).create(java.util.Map.of(${examplePairs('create').join(', ')}), null)
+val created = client.${accessor}(null).create(${javaMapOf(examplePairs('create'), 'java.util.')}, null)
 
 `)
       }
@@ -201,7 +191,7 @@ val created = client.${accessor}(null).create(java.util.Map.of(${examplePairs('c
         const updatePairs = (idF ? [`"${idF}", ${scalaLit(idParamType('update'), 'example_id')}`] : [])
           .concat(examplePairs('update'))
         Content(`// Update — supply the id in the match/data
-client.${accessor}(null).update(java.util.Map.of(${updatePairs.join(', ')}), null)
+client.${accessor}(null).update(${javaMapOf(updatePairs, 'java.util.')}, null)
 
 `)
       }
@@ -209,7 +199,7 @@ client.${accessor}(null).update(java.util.Map.of(${updatePairs.join(', ')}), nul
         const patchPairs = (idF ? [`"${idF}", ${scalaLit(idParamType('patch'), 'example_id')}`] : [])
           .concat(examplePairs('patch'))
         Content(`// Patch — sends only the fields given
-client.${accessor}(null).patch(java.util.Map.of(${patchPairs.join(', ')}), null)
+client.${accessor}(null).patch(${javaMapOf(patchPairs, 'java.util.')}, null)
 
 `)
       }
@@ -223,7 +213,7 @@ client.${accessor}(null).patch(java.util.Map.of(${patchPairs.join(', ')}), null)
             ? `"${it.name}", ${scalaLit(idParamType('remove'), 'example_id')}`
             : `"${it.name}", ${scalaLit(it.type, 'example_' + it.name)}`)
         Content(`// Remove
-client.${accessor}(null).remove(${removePairs.length ? `java.util.Map.of(${removePairs.join(', ')})` : 'null'}, null)
+client.${accessor}(null).remove(${removePairs.length ? javaMapOf(removePairs, 'java.util.') : 'null'}, null)
 `)
       }
       Content(`\`\`\`

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote, javaMap, javaMapOf } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -7,53 +7,41 @@ import {
   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).
 
-// A type-correct Scala literal for a field's canonical type.
-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}"`
-}
-
-
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(reqmatch, ctrl) -> Object',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data()` reads, and raises on error.',
   },
   list: {
     sig: 'list(reqmatch, ctrl) -> Object',
-    returns: 'an aggregate list of entities',
-    desc: 'List entities matching the given criteria. The match is optional — call `list(null, null)` to list all records. Returns an aggregate list and raises on error.',
+    returns: 'a list of entities, one per record',
+    desc: 'List entities matching the given criteria. The match is optional — call `list(null, null)` to list all records. Returns a list of entities, one per record, and raises on error.',
   },
   create: {
     sig: 'create(reqdata, ctrl) -> Object',
-    returns: 'the created entity data',
-    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
+    returns: 'the created entity',
+    desc: 'Create a new entity with the given data. Returns the created entity and raises on error.',
   },
   update: {
     sig: 'update(reqdata, ctrl) -> Object',
-    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.',
+    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(reqdata, ctrl) -> Object',
-    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.',
+    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(reqmatch, ctrl) -> Object',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Raises on error.',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and raises on error.',
   },
 }
 
@@ -273,9 +261,9 @@ ${info.desc}
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
             const arg = 0 < matchItems.length
-              ? `java.util.Map.of(${matchItems.map((it: any) =>
+              ? javaMapOf(matchItems.map((it: any) =>
                 `"${it.name}", ${scalaLit(it.type,
-                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')})`
+                  it.name === idF ? ent.name + '_id' : it.name)}`), 'java.util.')
               : 'null'
             Content(`\`\`\`scala
 val result = client.${accessor}(null).${opname}(${arg}, null)
@@ -285,8 +273,8 @@ val result = client.${accessor}(null).${opname}(${arg}, null)
           }
           else if ('list' === opname) {
             Content(`\`\`\`scala
-val results = client.${accessor}(null).list(null, null)
-println(results)
+val results = client.${accessor}(null).list(${scalaListMatch(ent)}, null).asInstanceOf[java.util.List[SdkEntity]]
+results.forEach(item => println(item.data()))
 \`\`\`
 
 `)
@@ -294,12 +282,13 @@ println(results)
           else if ('create' === opname) {
             const createItems = opRequestShape(ent, 'create').items
               .filter((it: any) => !it.optional)
+            const createMap = javaMap(createItems.length, 'java.util.')
             Content(`\`\`\`scala
-val result = client.${accessor}(null).create(java.util.Map.of(
+val result = 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)
@@ -312,13 +301,14 @@ val result = client.${accessor}(null).create(java.util.Map.of(
               .filter((it: any) => !it.optional || it.name === idF)
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const updateMap = javaMap(updateItems.length, 'java.util.')
             const updateLines = updateItems.map((it: any, i: number) => {
               const comma = i < updateItems.length - 1 ? ',' : ''
-              return `    "${it.name}", ${scalaLit(it.type,
-                it.name === idF ? ent.name + '_id' : it.name)}${comma}\n`
+              return `    ${updateMap.pair(`"${it.name}", ${scalaLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)}`)}${comma}\n`
             }).join('')
             Content(`\`\`\`scala
-val result = client.${accessor}(null).${opname}(java.util.Map.of(
+val result = client.${accessor}(null).${opname}(${updateMap.open}
 ${updateLines}), null)
 \`\`\`
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape, javaMapOf } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,21 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { scalaVarName, scalaPackage } from './utility_scala'
-
-
-// A type-correct Scala literal for a param: numeric/boolean/array/object params
-// render a typed literal; strings render the quoted placeholder. The SDK's
-// loose object model means all values live in java.util.Map[String, Object].
-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}"`
-}
+import { scalaVarName, scalaPackage, scalaListMatch, scalaLit } from './utility_scala'
 
 
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
@@ -35,9 +21,12 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
 
   const authActive = isAuthActive(model)
 
+  const shown = null != exampleEntity &&
+    ['list', 'load'].some((op: string) => Object.keys(exampleEntity.op || {}).includes(op))
+
   Content(`\`\`\`scala
 import ${scalaPackage(model)}.core.${SDK}
-
+${shown ? `import ${scalaPackage(model)}.core.SdkEntity\n` : ''}
 `)
 
   if (authActive) {
@@ -61,9 +50,9 @@ val client = new ${SDK}(options)
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eNameLower}s (returns Object, an aggregate list; raises on error)
-val ${eVar}List = client.${accessor}(null).list(null, null)
-println(${eVar}List)
+      Content(`// List all ${eNameLower}s (a list of entities, one per record; raises on error)
+val ${eVar}List = client.${accessor}(null).list(${scalaListMatch(exampleEntity)}, null).asInstanceOf[java.util.List[SdkEntity]]
+${eVar}List.forEach(${eVar}Item => println(${eVar}Item.data()))
 `)
     }
 
@@ -76,14 +65,14 @@ println(${eVar}List)
         .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 ? 'example_id' : 'example_' + it.name)}`).join(', ')})`
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`), 'java.util.')
         : 'null'
       Content(`
-// Load a specific ${eNameLower} (returns the record, raises on error)
-val ${eVar} = client.${accessor}(null).load(${loadArg}, null)
-println(${eVar})
+// Load a specific ${eNameLower} (returns the entity, raises on error)
+val ${eVar} = client.${accessor}(null).load(${loadArg}, null).asInstanceOf[SdkEntity]
+println(${eVar}.data())
 `)
     }
   }

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

@@ -1,24 +1,12 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, 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 ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
@@ -40,29 +28,33 @@ val client = ${SDK}.testSDK(null, null)
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = 'null'
-    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 type, so the block stays honest.
-      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
-        ? `java.util.Map.of(${items.map((it: any) =>
-          `"${it.name}", ${it.name === idF ? '"test01"' : scalaLit(it.type)}`).join(', ')})`
+        ? javaMapOf(items.map((it: any) =>
+          `${JSON.stringify(it.name)}, ${isMatchOp && it.name === idF ? '"test01"' : scalaLit(it.type)}`), 'java.util.')
         : 'null'
     } 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 = `java.util.Map.of(${chosen.map((it: any) =>
-        `"${it.name}", ${scalaLit(it.type)}`).join(', ')})`
+      arg = javaMapOf(chosen.map((it: any) =>
+        `${JSON.stringify(it.name)}, ${scalaLit(it.type)}`), 'java.util.')
     }
-    const eVar = scalaVarName(exampleEntity.name) + ('list' === primaryOp ? 'List' : '')
+    const eVar = scalaVarName(exampleEntity.name)
     const accessor = scalaVarName(exampleEntity.name)
-    Content(`val ${eVar} = client.${accessor}(null).${primaryOp}(${arg}, null)
-println(${eVar})
+    Content('list' === primaryOp
+      ? `val ${eVar}List = client.${accessor}(null).list(${arg}, null).asInstanceOf[java.util.List[SdkEntity]]
+${eVar}List.forEach(${eVar}Item => println(${eVar}Item.data()))
+`
+      : `val ${eVar} = client.${accessor}(null).${primaryOp}(${arg}, null).asInstanceOf[SdkEntity]
+println(${eVar}.data())
 `)
   }
 

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

@@ -4,6 +4,9 @@ import * as Path from 'node:path'
 
 import {
   camelify,
+  canonScalarKey,
+  requiredItems,
+  javaMapOf,
 } from '@voxgig/sdkgen'
 
 import {
@@ -108,8 +111,30 @@ function jsonAppendLines(value: any, bufname: string): string {
     .join('')
 }
 
+// Map.of and Map.entry reject a null value, so NULL keeps the placeholder.
+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}"`
+}
+
+
+// A list's required parameters as its match.
+function scalaListMatch(entity: any): string {
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? javaMapOf(items.map((it: any) => `${JSON.stringify(it.name)}, ${scalaLit(it.type)}`), 'java.util.')
+    : 'null'
+}
+
 
 export {
+  scalaLit,
+  scalaListMatch,
   cleanModel,
   mavenGroupId,
   jsonAppendLines,

package/project/.sdk/src/cmp/swift/EntityTypes_swift.ts

@@ -36,7 +36,7 @@ public struct ${typeName} {
   items.forEach((it: any) => {
     if (null == it || null == it.name) return
     const ident = swiftVarName(it.name)
-    if (seen.has(ident)) return
+    if ('' === ident || seen.has(ident)) return
     seen.add(ident)
     Content(propLine(it.name, it.type, !!it.optional))
   })

package/project/.sdk/src/cmp/swift/ReadmeEntity_swift.ts

@@ -6,13 +6,14 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { swiftVarName } from './utility_swift'
+import { swiftVarName, swiftListMatch } from './utility_swift'
 
 
 // Type names come from the shared canonToType 'swift' column (single source of truth).
 
 function swiftLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return '.null'
   if ('INTEGER' === k) return '.int(1)'
   if ('NUMBER' === k) return '.double(1.0)'
   if ('BOOLEAN' === k) return '.bool(true)'
@@ -141,7 +142,7 @@ let ${eVar} = try client.${accessor}().load(${loadArg}, nil)
       Content(`#### Example: List
 
 \`\`\`swift
-let ${eVar}List = try client.${accessor}().list(nil, nil)
+let ${eVar}List = try client.${accessor}().list(${swiftListMatch(entity)}, nil)
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/swift/ReadmeHowto_swift.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 { swiftVarName } from './utility_swift'
+import { swiftVarName, swiftString } from './utility_swift'
 
 
 // A type-correct Swift `Value` literal for a field's canonical type.
 function swiftLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return '.null'
   if ('INTEGER' === k) return '.int(1)'
   if ('NUMBER' === k) return '.double(1.0)'
   if ('BOOLEAN' === k) return '.bool(true)'
@@ -39,23 +40,36 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'nil'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `VMap([("${idF}", .string("test01"))])` : 'nil'
+  } else if (exampleEntity && 'list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length) {
+    const chosen = requiredItems(exampleEntity, 'list')
+    testArg = `VMap([${chosen.map((it: any) =>
+      `(${swiftString(it.name)}, ${swiftLit(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}", ${swiftLit(it.type)})`).join(', ')}])`
+      `(${swiftString(it.name)}, ${swiftLit(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 throws on error;
-// call data() for the record.
+  const testModeExample = 'list' === primaryOp
+    ? `// list returns a Value list of entities, one per mock record; it throws on error.
+let ${eVar}List = try client.${eName}().list(${testArg}, nil)
+for ${eVar}Item in ${eVar}List.asList?.items ?? [] {
+    if let ${eVar}Entity = ${eVar}Item.asNative as? Entity {
+        print(${eVar}Entity.data())
+    }
+}`
+    : primaryOp
+    ? `// Entity ops return the entity, wrapped in a Value; they throw on error.
 let ${eVar} = try client.${eName}().${primaryOp}(${testArg}, nil)
-// ${eVar} holds the mock response record
-print(${eVar})`
+// data() reads the entity's mock record
+if let ${eVar}Entity = ${eVar}.asNative as? Entity {
+    print(${eVar}Entity.data())
+}`
     : `let result = client.direct(VMap([
     ("path", .string("/api/resource")),
     ("method", .string("GET")),

package/project/.sdk/src/cmp/swift/ReadmeModel_swift.ts

@@ -23,12 +23,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) throws -> Value` | Load a single entity by match criteria. Throws on error. |',
-    list: '| `list` | `(reqmatch, ctrl) throws -> Value` | List entities matching the criteria (a Value list). Throws on error. |',
-    create: '| `create` | `(reqdata, ctrl) throws -> Value` | Create a new entity. Throws on error. |',
-    update: '| `update` | `(reqdata, ctrl) throws -> Value` | Update an existing entity. Throws on error. |',
-    patch: '| `patch` | `(reqdata, ctrl) throws -> Value` | Change part of an existing entity. Throws on error. |',
-    remove: '| `remove` | `(reqmatch, ctrl) throws -> Value` | Remove an entity. Throws on error. |',
+    load: '| `load` | `(reqmatch, ctrl) throws -> Value` | Load a single entity by match criteria, and return it. Throws on error. |',
+    list: '| `list` | `(reqmatch, ctrl) throws -> Value` | List entities matching the criteria, one per record. Throws on error. |',
+    create: '| `create` | `(reqdata, ctrl) throws -> Value` | Create a new entity, and return it. Throws on error. |',
+    update: '| `update` | `(reqdata, ctrl) throws -> Value` | Update an existing entity, and return it. Throws on error. |',
+    patch: '| `patch` | `(reqdata, ctrl) throws -> Value` | Change part of an existing entity, and return it. Throws on error. |',
+    remove: '| `remove` | `(reqmatch, ctrl) throws -> Value` | Remove an entity, and return it marked as deleted. Throws on error. |',
   }
   const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
@@ -93,9 +93,10 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the ENTITY (call data() for the record) (a \`Value\` map for
-single-entity ops, a \`Value\` list for \`list\`) and throw on error. Wrap
-calls in \`do\`/\`catch\` to handle failures.
+Entity operations return the entity, and \`list\` a \`Value\` list of entities,
+one per record; each entity comes wrapped in a native \`Value\`, which
+\`asNative as? Entity\` unwraps, and its \`data()\` reads the record. They
+throw on error, so wrap calls in \`do\`/\`catch\` to handle failures.
 
 The \`direct()\` escape hatch never throws — it returns a result \`VMap\` you
 branch on via \`result.entries["ok"]\`:

package/project/.sdk/src/cmp/swift/ReadmeQuick_swift.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { swiftVarName } from './utility_swift'
+import { swiftVarName, swiftListMatch } from './utility_swift'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -37,6 +37,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   // means all values live in a `VMap` of `Value`.
   const swiftLit = (type: any, placeholder: string = 'example'): string => {
     const k = canonScalarKey(type)
+    if ('NULL' === k) return '.null'
     if ('INTEGER' === k) return '.int(1)'
     if ('NUMBER' === k) return '.double(1.0)'
     if ('BOOLEAN' === k) return '.bool(true)'
@@ -84,14 +85,17 @@ let client = ${SDK}()
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list(nil, nil)\` returns a \`Value\` list of records and throws on error —
-iterate its items.
+\`list(nil, nil)\` returns a \`Value\` list of entities, one per record, and
+throws on error; \`asNative as? Entity\` unwraps an item, and its \`data()\`
+reads the record.
 
 \`\`\`swift
 do {
-    let ${eVar}List = try client.${accessor}().list(nil, nil)
-    for ${eVar} in ${eVar}List.asList?.items ?? [] {
-        print(${eVar})
+    let ${eVar}List = try client.${accessor}().list(${swiftListMatch(exampleEntity)}, nil)
+    for ${eVar}Item in ${eVar}List.asList?.items ?? [] {
+        if let ${eVar}Entity = ${eVar}Item.asNative as? Entity {
+            print(${eVar}Entity.data())
+        }
     }
 }
 catch {
@@ -130,7 +134,9 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 \`\`\`swift
 do {
     let ${neVar} = try client.${neAccessor}().load(VMap([${neMatch.join(', ')}]), nil)
-    print(${neVar})
+    if let ${neVar}Entity = ${neVar}.asNative as? Entity {
+        print(${neVar}Entity.data())
+    }
 }
 catch {
     print("load failed: \\(error)")
@@ -158,7 +164,9 @@ catch {
 \`\`\`swift
 do {
     let ${eVar} = try client.${accessor}().load(${loadArg}, nil)
-    print(${eVar})
+    if let ${eVar}Entity = ${eVar}.asNative as? Entity {
+        print(${eVar}Entity.data())
+    }
 }
 catch {
     print("load failed: \\(error)")