@voxgig/sdkgen 4.34.1 → 4.34.2

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

@@ -7,7 +7,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).
@@ -15,6 +15,7 @@ import { csVarName } from './utility_csharp'
 // A type-correct 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'
@@ -47,8 +48,8 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
   },
   patch: {
     sig: 'Patch(reqdata, ctrl = null) -> 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 = null) -> object?',
@@ -83,6 +84,7 @@ Complete API reference for the ${model.Name} ${target.title} SDK.
 
     Content(`\`\`\`csharp
 using ${model.const.Name}Sdk;
+using Voxgig.Struct;
 
 var client = new ${model.const.Name}SDK(options);
 \`\`\`
@@ -285,8 +287,11 @@ var result = client.${ent.Name}().${opname.charAt(0).toUpperCase() + opname.slic
           }
           else if ('list' === opname) {
             Content(`\`\`\`csharp
-var results = client.${ent.Name}().List(null);
-Console.WriteLine(results);
+var results = (List<object?>)client.${ent.Name}().List(${csListMatch(ent)})!;
+foreach (var item in results)
+{
+    Console.WriteLine(StructUtils.Jsonify(((IEntity)item!).Data()));
+}
 \`\`\`
 
 `)

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

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { csVarName } from './utility_csharp'
+import { csVarName, csListMatch } from './utility_csharp'
 
 
 // A type-correct C# literal for a param: numeric/boolean/array/object params
@@ -15,6 +15,7 @@ import { csVarName } from './utility_csharp'
 // loose object model means all values live in Dictionary<string, object?>.
 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'
@@ -36,9 +37,12 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
     ? `new ${model.const.Name}SDK(new Dictionary<string, object?>\n{\n    ["apikey"] = Environment.GetEnvironmentVariable("${envName(model)}_APIKEY"),\n})`
     : `new ${model.const.Name}SDK()`
 
+  const shown = null != exampleEntity &&
+    ['list', 'load'].some((op: string) => Object.keys(exampleEntity.op || {}).includes(op))
+
   Content(`\`\`\`csharp
 using ${model.const.Name}Sdk;
-
+${shown ? 'using Voxgig.Struct;\n' : ''}
 var client = ${ctor};
 
 `)
@@ -52,9 +56,12 @@ var client = ${ctor};
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s (returns object?, an aggregate list; raises on error)
-var ${eVar}List = client.${eName}().List(null);
-Console.WriteLine(${eVar}List);
+      Content(`// List all ${eName.toLowerCase()}s (a list of entities, one per record, as object?; raises on error)
+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()));
+}
 `)
     }
 
@@ -73,8 +80,8 @@ Console.WriteLine(${eVar}List);
         : 'null'
       Content(`
 // Load a specific ${eName.toLowerCase()} (returns the entity, raises on error)
-var ${eVar} = client.${eName}().Load(${loadArg});
-Console.WriteLine(${eVar});
+var ${eVar} = (IEntity)client.${eName}().Load(${loadArg})!;
+Console.WriteLine(StructUtils.Jsonify(${eVar}.Data()));
 `)
     }
   }

package/project/.sdk/src/cmp/csharp/ReadmeTopTest_csharp.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,
@@ -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'
@@ -41,16 +42,16 @@ var client = ${model.const.Name}SDK.TestSDK(null, null);
     const opMethod = primaryOp.charAt(0).toUpperCase() + primaryOp.slice(1)
     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
         ? `new Dictionary<string, object?> {${items.map((it: any) =>
-          ` ["${it.name}"] = ${it.name === idF ? '"test01"' : csLit(it.type)}`).join(',')} }`
+          ` [${csStringLiteral(it.name)}] = ${isMatchOp && it.name === idF ? '"test01"' : csLit(it.type)}`).join(',')} }`
         : 'null'
     } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
@@ -58,11 +59,18 @@ var client = ${model.const.Name}SDK.TestSDK(null, null);
       const required = items.filter((it: any) => !it.optional)
       const chosen = required.length ? required : items.slice(0, 3)
       arg = `new Dictionary<string, object?> {${chosen.map((it: any) =>
-        ` ["${it.name}"] = ${csLit(it.type)}`).join(',')} }`
+        ` [${csStringLiteral(it.name)}] = ${csLit(it.type)}`).join(',')} }`
     }
-    const eVar = csVarName(exampleEntity.name) + ('list' === primaryOp ? 'List' : '')
-    Content(`var ${eVar} = client.${eName}().${opMethod}(${arg});
-Console.WriteLine(${eVar});
+    const eVar = csVarName(exampleEntity.name)
+    Content('list' === primaryOp
+      ? `var ${eVar}List = (List<object?>)client.${eName}().List(${arg})!;
+foreach (var ${eVar}Item in ${eVar}List)
+{
+    Console.WriteLine(StructUtils.Jsonify(((IEntity)${eVar}Item!).Data()));
+}
+`
+      : `var ${eVar} = (IEntity)client.${eName}().${opMethod}(${arg})!;
+Console.WriteLine(StructUtils.Jsonify(${eVar}.Data()));
 `)
   }
 

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

@@ -6,6 +6,8 @@ import {
   camelify,
   each,
   safeVarName,
+  canonScalarKey,
+  requiredItems,
 } from '@voxgig/sdkgen'
 
 import {
@@ -202,8 +204,19 @@ function clean(o: any, dropDefaults?: boolean): any {
   return prune(o, true === dropDefaults)
 }
 
+// A list's required route and query parameters, as the match it is called with.
+function csListMatch(entity: any): string {
+  const lit = (type: any): string =>
+    (({ NULL: 'null', INTEGER: '1L', NUMBER: '1.0', BOOLEAN: 'true', ARRAY: 'new List<object?>()', OBJECT: 'new Dictionary<string, object?>()' }) as any)[canonScalarKey(type)] ?? '"example"'
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? `new Dictionary<string, object?> {${items.map((it: any) => ` [${csStringLiteral(it.name)}] = ${lit(it.type)}`).join(',')} }`
+    : 'null'
+}
+
 
 export {
+  csListMatch,
   clean,
   csPascalName,
   csStringLiteral,

package/project/.sdk/src/cmp/elixir/ReadmeEntity_elixir.ts

@@ -7,7 +7,7 @@ import {
 } from '@voxgig/apidef'
 
 // Type names come from the shared canonToType 'elixir' column (single source of truth).
-import { elixirLit } from './utility_elixir'
+import { elixirLit, elixirListArgs } from './utility_elixir'
 
 
 // Operation method spelling for the Elixir target: each op is a function on
@@ -120,7 +120,7 @@ takes an entity handle built from the client:
 
 \`\`\`elixir
 ${eVar} = ${Name}.${eCall}(sdk)
-record = ${Name}.Entity.${EName}.load(${eVar}, ${loadArg})
+${eVar} = ${Name}.Entity.${EName}.load(${eVar}, ${loadArg})
 \`\`\`
 
 `)
@@ -131,7 +131,7 @@ record = ${Name}.Entity.${EName}.load(${eVar}, ${loadArg})
 
 \`\`\`elixir
 ${eVar} = ${Name}.${eCall}(sdk)
-records = ${Name}.Entity.${EName}.list(${eVar})
+${eVar}s = ${Name}.Entity.${EName}.list(${eVar}${elixirListArgs(entity, Name)})
 \`\`\`
 
 `)
@@ -147,7 +147,7 @@ records = ${Name}.Entity.${EName}.list(${eVar})
 
 \`\`\`elixir
 ${eVar} = ${Name}.${eCall}(sdk)
-record = ${Name}.Entity.${EName}.create(${eVar}, ${Name}.Helpers.deep(%{
+${eVar} = ${Name}.Entity.${EName}.create(${eVar}, ${Name}.Helpers.deep(%{
 `)
       createItems.map((it: any) => {
         Content(`  "${it.name}" => ${elixirLit(it.type, 'example_' + it.name)},  # ${canonToType(it.type, target.name)}

package/project/.sdk/src/cmp/elixir/ReadmeExplanation_elixir.ts

@@ -17,7 +17,8 @@ that every later pipeline stage observes — the immutable-Elixir way to honour
 the shared-mutable hook contract.
 
 Build inputs from native Elixir maps with \`${model.Name}.Helpers.deep/1\`,
-and read fields off results with \`Voxgig.Struct.getprop/2\`.
+and read fields off a record, which an entity's \`data_get/1\` returns, with
+\`Voxgig.Struct.getprop/2\`.
 
 ### Module structure
 

package/project/.sdk/src/cmp/elixir/ReadmeHowto_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField, pickExampleEntity, opRequestShape, elixirAccessor, entityCollection, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, pickExampleEntity, opRequestShape, elixirAccessor, entityCollection, exampleVarName, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { elixirLit } from './utility_elixir'
+import { elixirLit, elixirString } from './utility_elixir'
 
 
 const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
@@ -27,20 +27,27 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'H.deep(%{})'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `H.deep(%{"${idF}" => "test01"})` : 'H.deep(%{})'
+  } else if (exampleEntity && 'list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length) {
+    const chosen = requiredItems(exampleEntity, 'list')
+    testArg = `H.deep(%{${chosen.map((it: any) => `${elixirString(it.name)} => ${elixirLit(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 = `H.deep(%{${chosen.map((it: any) => `"${it.name}" => ${elixirLit(it.type)}`).join(', ')}})`
+    testArg = `H.deep(%{${chosen.map((it: any) => `${elixirString(it.name)} => ${elixirLit(it.type)}`).join(', ')}})`
   }
 
-  const resVar = 'list' === primaryOp ? 'records' : 'record'
   const testModeExample = primaryOp
     ? `# Entity ops return the entity, and list one per record (raise on error).
 ${eVar} = ${Name}.${eCall}(sdk)
-${resVar} = ${Name}.Entity.${eName}.${primaryOp}(${eVar}, ${testArg})
-IO.inspect(${resVar})`
+${'list' === primaryOp
+  ? `${eVar}s = ${Name}.Entity.${eName}.list(${eVar}, ${testArg})
+for i <- 0..(Voxgig.Struct.size(${eVar}s) - 1)//1 do
+  IO.puts(Voxgig.Struct.jsonify(${Name}.Entity.${eName}.data_get(Voxgig.Struct.getelem(${eVar}s, i))))
+end`
+  : `${eVar} = ${Name}.Entity.${eName}.${primaryOp}(${eVar}, ${testArg})
+IO.puts(Voxgig.Struct.jsonify(${Name}.Entity.${eName}.data_get(${eVar})))`}`
     : `result = ${Name}.direct(sdk, H.deep(%{"path" => "/api/resource", "method" => "GET"}))
 IO.inspect(result)`
 

package/project/.sdk/src/cmp/elixir/ReadmeModel_elixir.ts

@@ -21,12 +21,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` | `(entity, reqmatch, ctrl \\\\ nil) :: map()` | Load a single entity by match criteria, and return it. Raises on error. |',
+    load: '| `load` | `(entity, reqmatch, ctrl \\\\ nil) :: entity` | Load a single entity by match criteria, and return it. Raises on error. |',
     list: '| `list` | `(entity, reqmatch \\\\ nil, ctrl \\\\ nil) :: list()` | List entities matching the criteria, one per record. Raises on error. |',
-    create: '| `create` | `(entity, reqdata, ctrl \\\\ nil) :: map()` | Create a new entity, and return it. Raises on error. |',
-    update: '| `update` | `(entity, reqdata, ctrl \\\\ nil) :: map()` | Update an existing entity, and return it. Raises on error. |',
-    patch: '| `patch` | `(entity, reqdata, ctrl \\\\ nil) :: map()` | Change part of an existing entity, and return it. Raises on error. |',
-    remove: '| `remove` | `(entity, reqmatch \\\\ nil, ctrl \\\\ nil) :: map()` | Remove an entity, and return it marked as deleted. Raises on error. |',
+    create: '| `create` | `(entity, reqdata, ctrl \\\\ nil) :: entity` | Create a new entity, and return it. Raises on error. |',
+    update: '| `update` | `(entity, reqdata, ctrl \\\\ nil) :: entity` | Update an existing entity, and return it. Raises on error. |',
+    patch: '| `patch` | `(entity, reqdata, ctrl \\\\ nil) :: entity` | Change part of an existing entity, and return it. Raises on error. |',
+    remove: '| `remove` | `(entity, reqmatch \\\\ nil, ctrl \\\\ nil) :: entity` | 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')

package/project/.sdk/src/cmp/elixir/ReadmeQuick_elixir.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { elixirLit } from './utility_elixir'
+import { elixirLit, elixirListArgs } from './utility_elixir'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -55,14 +55,17 @@ sdk = ${ctor}
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list/2\` returns a list of entities, one per record, and raises on error;
-\`data_get/1\` reads an entity's record.
+\`list/2\` returns a \`Voxgig.Struct\` list of entities, one per record, and
+raises on error; \`Voxgig.Struct.getelem/2\` reads an item, and \`data_get/1\`
+an entity's record.
 
 \`\`\`elixir
 try do
   ${eVar} = ${Name}.${eCall}(sdk)
-  records = ${Name}.Entity.${eName}.list(${eVar})
-  IO.inspect(records)
+  ${eVar}s = ${Name}.Entity.${eName}.list(${eVar}${elixirListArgs(exampleEntity, Name)})
+  for i <- 0..(Voxgig.Struct.size(${eVar}s) - 1)//1 do
+    IO.puts(Voxgig.Struct.jsonify(${Name}.Entity.${eName}.data_get(Voxgig.Struct.getelem(${eVar}s, i))))
+  end
 rescue
   err -> IO.puts("list failed: " <> inspect(err))
 end
@@ -98,8 +101,8 @@ record.
 \`\`\`elixir
 try do
   ${neVar} = ${Name}.${neCall}(sdk)
-  record = ${Name}.Entity.${neName}.load(${neVar}, H.deep(%{${neMatch.join(', ')}}))
-  IO.inspect(record)
+  ${neVar} = ${Name}.Entity.${neName}.load(${neVar}, H.deep(%{${neMatch.join(', ')}}))
+  IO.puts(Voxgig.Struct.jsonify(${Name}.Entity.${neName}.data_get(${neVar})))
 rescue
   err -> IO.puts("load failed: " <> inspect(err))
 end
@@ -126,8 +129,8 @@ record.
 \`\`\`elixir
 try do
   ${eVar} = ${Name}.${eCall}(sdk)
-  record = ${Name}.Entity.${eName}.load(${eVar}, ${loadArg})
-  IO.inspect(record)
+  ${eVar} = ${Name}.Entity.${eName}.load(${eVar}, ${loadArg})
+  IO.puts(Voxgig.Struct.jsonify(${Name}.Entity.${eName}.data_get(${eVar})))
 rescue
   err -> IO.puts("load failed: " <> inspect(err))
 end
@@ -155,7 +158,7 @@ end
       return it && it.type
     }
     const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
-      ? `Voxgig.Struct.getprop(created, "${dataIdF}")`
+      ? `Voxgig.Struct.getprop(${Name}.Entity.${eName}.data_get(created), "${dataIdF}")`
       : elixirLit(idParamType(opname), 'example_id')
 
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('patch') ||

package/project/.sdk/src/cmp/elixir/ReadmeRef_elixir.ts

@@ -8,12 +8,12 @@ import {
 } from '@voxgig/apidef'
 
 // Type names come from the shared canonToType 'elixir' column (single source of truth).
-import { elixirLit } from './utility_elixir'
+import { elixirLit, elixirListArgs } from './utility_elixir'
 
 
 const OP_SIGNATURES: Record<string, { sig: string, desc: string }> = {
   load: {
-    sig: 'load(entity, reqmatch, ctrl \\\\ nil) :: map()',
+    sig: 'load(entity, reqmatch, ctrl \\\\ nil) :: entity',
     desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data_get/1` reads, and raises on error.',
   },
   list: {
@@ -21,19 +21,19 @@ const OP_SIGNATURES: Record<string, { sig: string, desc: string }> = {
     desc: 'List entities matching the given criteria. The match is optional — call `list(entity)` to list all records. Returns a list of entities, one per record, and raises on error.',
   },
   create: {
-    sig: 'create(entity, reqdata, ctrl \\\\ nil) :: map()',
+    sig: 'create(entity, reqdata, ctrl \\\\ nil) :: entity',
     desc: 'Create a new entity with the given data. Returns the created entity and raises on error.',
   },
   update: {
-    sig: 'update(entity, reqdata, ctrl \\\\ nil) :: map()',
+    sig: 'update(entity, reqdata, ctrl \\\\ nil) :: entity',
     desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and raises on error.',
   },
   patch: {
-    sig: 'patch(entity, reqdata, ctrl \\\\ nil) :: map()',
-    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(entity, reqdata, ctrl \\\\ nil) :: 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(entity, reqmatch, ctrl \\\\ nil) :: map()',
+    sig: 'remove(entity, reqmatch, ctrl \\\\ nil) :: entity',
     desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and raises on error.',
   },
 }
@@ -218,14 +218,14 @@ ${info.desc}
                   it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')}})`
               : `${Name}.Helpers.deep(%{})`
             Content(`\`\`\`elixir
-record = ${Name}.Entity.${EName}.${opname}(${eVar}, ${arg})
+${eVar} = ${Name}.Entity.${EName}.${opname}(${eVar}, ${arg})
 \`\`\`
 
 `)
           }
           else if ('list' === opname) {
             Content(`\`\`\`elixir
-records = ${Name}.Entity.${EName}.list(${eVar})
+${eVar}s = ${Name}.Entity.${EName}.list(${eVar}${elixirListArgs(ent, Name)})
 \`\`\`
 
 `)
@@ -234,7 +234,7 @@ records = ${Name}.Entity.${EName}.list(${eVar})
             const createItems = opRequestShape(ent, 'create').items
               .filter((it: any) => !it.optional)
             Content(`\`\`\`elixir
-record = ${Name}.Entity.${EName}.create(${eVar}, ${Name}.Helpers.deep(%{
+${eVar} = ${Name}.Entity.${EName}.create(${eVar}, ${Name}.Helpers.deep(%{
 `)
             createItems.map((it: any) => {
               Content(`  "${it.name}" => ${elixirLit(it.type, 'example_' + it.name)},  # ${canonToType(it.type, target.name)}
@@ -254,7 +254,7 @@ record = ${Name}.Entity.${EName}.create(${eVar}, ${Name}.Helpers.deep(%{
               `  "${it.name}" => ${elixirLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`elixir
-record = ${Name}.Entity.${EName}.${opname}(${eVar}, ${Name}.Helpers.deep(%{
+${eVar} = ${Name}.Entity.${EName}.${opname}(${eVar}, ${Name}.Helpers.deep(%{
 ${updateLines}  # ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
 }))
 \`\`\`

package/project/.sdk/src/cmp/elixir/ReadmeTopQuick_elixir.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { elixirLit } from './utility_elixir'
+import { elixirLit, elixirListArgs } from './utility_elixir'
 
 
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
@@ -42,9 +42,11 @@ sdk = ${ctor}
 
     if (opnames.includes('list')) {
       Content(`
-# List all ${eName.toLowerCase()} records (raises on error)
-records = ${Name}.Entity.${eName}.list(${eVar})
-IO.inspect(records)
+# List all ${eName.toLowerCase()}s (a list of entities, one per record; raises on error)
+${eVar}s = ${Name}.Entity.${eName}.list(${eVar}${elixirListArgs(exampleEntity, Name)})
+for i <- 0..(Voxgig.Struct.size(${eVar}s) - 1)//1 do
+  IO.puts(Voxgig.Struct.jsonify(${Name}.Entity.${eName}.data_get(Voxgig.Struct.getelem(${eVar}s, i))))
+end
 `)
     }
 
@@ -66,8 +68,8 @@ IO.inspect(records)
         : eVar
       Content(`
 # Load a specific ${eName.toLowerCase()} (returns the entity, raises on error)
-record = ${Name}.Entity.${eName}.load(${loadArgs})
-IO.inspect(record)
+${eVar} = ${Name}.Entity.${eName}.load(${loadArgs})
+IO.puts(Voxgig.Struct.jsonify(${Name}.Entity.${eName}.data_get(${eVar})))
 `)
     }
   }

package/project/.sdk/src/cmp/elixir/ReadmeTopTest_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape, elixirAccessor, entityCollection, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape, elixirAccessor, entityCollection, exampleVarName, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { elixirLit } from './utility_elixir'
+import { elixirLit, elixirString } from './utility_elixir'
 
 
 const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
@@ -33,28 +33,32 @@ sdk = ${Name}.test()
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = ''
-    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
         ? `H.deep(%{${items.map((it: any) =>
-          `"${it.name}" => ${it.name === idF ? '"test01"' : elixirLit(it.type)}`).join(', ')}})`
+          `${elixirString(it.name)} => ${isMatchOp && it.name === idF ? '"test01"' : elixirLit(it.type)}`).join(', ')}})`
         : 'H.deep(%{})'
     } 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 = `H.deep(%{${chosen.map((it: any) => `"${it.name}" => ${elixirLit(it.type)}`).join(', ')}})`
+      arg = `H.deep(%{${chosen.map((it: any) => `${elixirString(it.name)} => ${elixirLit(it.type)}`).join(', ')}})`
     } else {
       arg = 'H.deep(%{})'
     }
-    const resVar = 'list' === primaryOp ? 'records' : 'record'
     Content(`${eVar} = ${Name}.${eCall}(sdk)
-${resVar} = ${Name}.Entity.${eName}.${primaryOp}(${eVar}, ${arg})
-IO.inspect(${resVar})
+${'list' === primaryOp
+  ? `${eVar}s = ${Name}.Entity.${eName}.list(${eVar}, ${arg})
+for i <- 0..(Voxgig.Struct.size(${eVar}s) - 1)//1 do
+  IO.puts(Voxgig.Struct.jsonify(${Name}.Entity.${eName}.data_get(Voxgig.Struct.getelem(${eVar}s, i))))
+end`
+  : `${eVar} = ${Name}.Entity.${eName}.${primaryOp}(${eVar}, ${arg})
+IO.puts(Voxgig.Struct.jsonify(${Name}.Entity.${eName}.data_get(${eVar})))`}
 `)
   }
 

package/project/.sdk/src/cmp/elixir/fragment/EntityCreateOp.fragment.ex

@@ -1,8 +1,9 @@
 # EJECT-START
 
-  # Returns the created entityname entity map (ProjectName.Types.entityname/0)
-  # on success; pipeline errors surface as the error value built by
-  # Utility.make_error (shape is utility-configurable), hence term().
+  # Returns the created entityname entity, whose data_get/1 reads its record
+  # (ProjectName.Types.entityname/0), on success; pipeline errors surface as
+  # the error value built by Utility.make_error (shape is
+  # utility-configurable), hence term().
   @spec create(map(), ProjectName.Types.entityname_create_data() | nil, map() | nil) :: term()
   def create(ent, reqdata, ctrl \\ nil) do
     ctx =

package/project/.sdk/src/cmp/elixir/fragment/EntityListOp.fragment.ex

@@ -1,8 +1,9 @@
 # EJECT-START
 
-  # Returns a list of entityname entity maps (ProjectName.Types.entityname/0)
-  # on success; pipeline errors surface as the error value built by
-  # Utility.make_error (shape is utility-configurable), hence term().
+  # Returns a list of entityname entities, one per record, whose data_get/1
+  # reads each record (ProjectName.Types.entityname/0), on success; pipeline
+  # errors surface as the error value built by Utility.make_error (shape is
+  # utility-configurable), hence term().
   @spec list(map(), ProjectName.Types.entityname_list_match() | nil, map() | nil) :: term()
   def list(ent, reqmatch \\ nil, ctrl \\ nil) do
     reqmatch = if reqmatch == nil, do: S.jm([]), else: reqmatch

package/project/.sdk/src/cmp/elixir/fragment/EntityLoadOp.fragment.ex

@@ -1,8 +1,9 @@
 # EJECT-START
 
-  # Returns the entityname entity map (ProjectName.Types.entityname/0) on
-  # success; pipeline errors surface as the error value built by
-  # Utility.make_error (shape is utility-configurable), hence term().
+  # Returns the entityname entity, whose data_get/1 reads its record
+  # (ProjectName.Types.entityname/0), on success; pipeline errors surface as
+  # the error value built by Utility.make_error (shape is
+  # utility-configurable), hence term().
   @spec load(map(), ProjectName.Types.entityname_load_match() | nil, map() | nil) :: term()
   def load(ent, reqmatch \\ nil, ctrl \\ nil) do
     reqmatch = if reqmatch == nil, do: S.jm([]), else: reqmatch

package/project/.sdk/src/cmp/elixir/fragment/EntityPatchOp.fragment.ex

@@ -1,8 +1,9 @@
 # EJECT-START
 
-  # Returns the patched entityname entity map (ProjectName.Types.entityname/0)
-  # on success; pipeline errors surface as the error value built by
-  # Utility.make_error (shape is utility-configurable), hence term().
+  # Returns the patched entityname entity, whose data_get/1 reads its record
+  # (ProjectName.Types.entityname/0), on success; pipeline errors surface as
+  # the error value built by Utility.make_error (shape is
+  # utility-configurable), hence term().
   @spec patch(map(), ProjectName.Types.entityname_patch_data() | nil, map() | nil) :: term()
   def patch(ent, reqdata, ctrl \\ nil) do
     ctx =

package/project/.sdk/src/cmp/elixir/fragment/EntityRemoveOp.fragment.ex

@@ -1,8 +1,9 @@
 # EJECT-START
 
-  # Returns the removed entityname entity map (ProjectName.Types.entityname/0)
-  # on success; pipeline errors surface as the error value built by
-  # Utility.make_error (shape is utility-configurable), hence term().
+  # Returns the removed entityname entity, marked as deleted, whose data_get/1
+  # reads the record it held (ProjectName.Types.entityname/0), on success;
+  # pipeline errors surface as the error value built by Utility.make_error
+  # (shape is utility-configurable), hence term().
   @spec remove(map(), ProjectName.Types.entityname_remove_match() | nil, map() | nil) :: term()
   def remove(ent, reqmatch \\ nil, ctrl \\ nil) do
     reqmatch = if reqmatch == nil, do: S.jm([]), else: reqmatch

package/project/.sdk/src/cmp/elixir/fragment/EntityUpdateOp.fragment.ex

@@ -1,8 +1,9 @@
 # EJECT-START
 
-  # Returns the updated entityname entity map (ProjectName.Types.entityname/0)
-  # on success; pipeline errors surface as the error value built by
-  # Utility.make_error (shape is utility-configurable), hence term().
+  # Returns the updated entityname entity, whose data_get/1 reads its record
+  # (ProjectName.Types.entityname/0), on success; pipeline errors surface as
+  # the error value built by Utility.make_error (shape is
+  # utility-configurable), hence term().
   @spec update(map(), ProjectName.Types.entityname_update_data() | nil, map() | nil) :: term()
   def update(ent, reqdata, ctrl \\ nil) do
     ctx =