@voxgig/sdkgen 4.34.1 → 4.34.2

package/project/.sdk/src/cmp/kotlin/ReadmeTopTest_kotlin.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 { kotlinVarName } from './utility_kotlin'
+import { kotlinVarName, kotlinString } from './utility_kotlin'
 
 
 // A type-correct Kotlin literal for a field's canonical type.
 function kotlinLit(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'
@@ -40,16 +41,16 @@ 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
         ? `mutableMapOf<String, Any?>(${items.map((it: any) =>
-          `"${it.name}" to ${it.name === idF ? '"test01"' : kotlinLit(it.type)}`).join(', ')})`
+          `${kotlinString(it.name)} to ${isMatchOp && it.name === idF ? '"test01"' : kotlinLit(it.type)}`).join(', ')})`
         : 'null'
     } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
@@ -57,12 +58,18 @@ val client = ${SDK}.testSDK(null, null)
       const required = items.filter((it: any) => !it.optional)
       const chosen = required.length ? required : items.slice(0, 3)
       arg = `mutableMapOf<String, Any?>(${chosen.map((it: any) =>
-        `"${it.name}" to ${kotlinLit(it.type)}`).join(', ')})`
+        `${kotlinString(it.name)} to ${kotlinLit(it.type)}`).join(', ')})`
     }
-    const eVar = kotlinVarName(exampleEntity.name) + ('list' === primaryOp ? 'List' : '')
+    const eVar = kotlinVarName(exampleEntity.name)
     const accessor = kotlinVarName(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) as List<*>
+for (${eVar}Item in ${eVar}List) {
+    println((${eVar}Item as SdkEntity).data())
+}
+`
+      : `val ${eVar} = client.${accessor}(null).${primaryOp}(${arg}, null) as SdkEntity
+println(${eVar}.data())
 `)
   }
 

package/project/.sdk/src/cmp/kotlin/utility_kotlin.ts

@@ -4,6 +4,8 @@ import * as Path from 'node:path'
 
 import {
   camelify,
+  canonScalarKey,
+  requiredItems,
 } from '@voxgig/sdkgen'
 
 import {
@@ -102,14 +104,32 @@ function jsonAppendLines(value: any, bufname: string): string {
   return json
     .split('\n')
     .map((line) => {
-      const lit = JSON.stringify(line).replace(/\$/g, '\\$')
+      const lit = kotlinString(line)
       return `    ${bufname}.append(${lit})\n`
     })
     .join('')
 }
 
+// A list's required route and query parameters, as the match it is called with.
+// A Kotlin string literal, whose `$` would start a template.
+function kotlinString(s: string): string {
+  return JSON.stringify(s).replace(/\$/g, '\\$')
+}
+
+
+function kotlinListMatch(entity: any): string {
+  const lit = (type: any): string =>
+    (({ NULL: 'null', INTEGER: '1L', NUMBER: '1.0', BOOLEAN: 'true', ARRAY: 'listOf<Any?>()', OBJECT: 'mapOf<String, Any?>()' }) as any)[canonScalarKey(type)] ?? '"example"'
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? `mutableMapOf<String, Any?>(${items.map((it: any) => `${kotlinString(it.name)} to ${lit(it.type)}`).join(', ')})`
+    : 'null'
+}
+
 
 export {
+  kotlinString,
+  kotlinListMatch,
   cleanModel,
   gradleGroup,
   kotlinPackage,

package/project/.sdk/src/cmp/lua/ReadmeEntity_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey, opNeedsAction } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey, opNeedsAction, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,6 +13,7 @@ import {
 // parse).
 function luaLit(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 || 'OBJECT' === k) return '{}'
@@ -133,7 +134,7 @@ local ${eVar}, err = client:${entity.Name}():load(${loadArg})
       Content(`#### Example: List
 
 \`\`\`lua
-local ${eVar}s, err = client:${entity.Name}():list()
+local ${eVar}s, err = client:${entity.Name}():list(${listMatchArg('lua', entity)})
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/lua/ReadmeExamplesTest_lua.ts

@@ -35,7 +35,8 @@ const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
 --      network). Each client constructor is rewritten to the seeded
 --      test-mode form, and fragments that only use \`client\` get a seeded
 --      test client injected. A call to a method that does not exist raises
---      "call a nil value" and FAILS the test. A seeded-fixture miss surfaces
+--      "call a nil value" and FAILS the test, as does an SDK module that
+--      does not load. A seeded-fixture miss surfaces
 --      as a tolerated (nil, err) not-found domain error, not a raised error.
 --   3. Completeness: total == executed + illustration per doc. A block that
 --      is neither runnable nor an explicit comment-only placeholder FAILS
@@ -219,12 +220,14 @@ for _, doc in ipairs(DOCS) do
           if not ok then
             local msg = tostring(e)
             -- A nil accessor / missing method / bad index is a real doc bug:
-            -- the documented call does not exist.
+            -- the documented call does not exist. A module that does not
+            -- load is an SDK that does not load.
             if msg:find("nil value") or msg:find("attempt to call")
-              or msg:find("attempt to index") then
+              or msg:find("attempt to index") or msg:find("error loading module")
+              or msg:find("module '[^']*' not found") then
               assert.is_true(false,
                 doc.label .. " runnable block #" .. i .. " hit a runtime " ..
-                "error (missing method / nil call): " .. msg ..
+                "error (missing method / nil call / module load): " .. msg ..
                 "\\n----\\n" .. src .. "\\n----")
             end
             -- Other runtime errors (a seeded-fixture miss surfaces as a

package/project/.sdk/src/cmp/lua/ReadmeHowto_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, luaKey } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, luaKey, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,6 +11,7 @@ import {
 // A type-correct Lua literal for a field's canonical type.
 function luaLit(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 || 'OBJECT' === k) return '{}'
@@ -31,12 +32,12 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testCallArg = ''
-  if (exampleEntity && isMatchOp) {
-    const items = opRequestShape(exampleEntity, primaryOp).items
-      .filter((it: any) => !it.optional || it.name === idF)
+  if (exampleEntity && (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))
     testCallArg = 0 < items.length
-      ? `{ ${items.map((it: any) => `${luaKey(it.name)} = ${it.name === idF ? '"test01"' : luaLit(it.type)}`).join(', ')} }`
+      ? `{ ${items.map((it: any) => `${luaKey(it.name)} = ${isMatchOp && it.name === idF ? '"test01"' : luaLit(it.type)}`).join(', ')} }`
       : ''
   } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp)) {
     const items = opRequestShape(exampleEntity, primaryOp).items
@@ -50,9 +51,10 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // A direct()-only SDK (no ops anywhere) shows a direct() call instead.
   const testModeExample = primaryOp
     ? `local result, err = client:${eName}():${primaryOp}(${testCallArg})
--- result is the returned data; err is set on failure`
+-- ${'list' === primaryOp ? 'result is an array of entities, one per mock record'
+    : 'result is the entity; data_get() reads its mock record'}; err is set on failure`
     : `local result, err = client:direct({ path = "/api/resource", method = "GET" })
--- result is the returned data; err is set on failure`
+-- result holds ok, status, headers and data; err is set on failure`
 
   const apikeyEnvLine = isAuthActive(model)
     ? `\n${envName(model)}_APIKEY=<your-key>`

package/project/.sdk/src/cmp/lua/ReadmeModel_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, entityIdField } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, entityIdField, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -17,12 +17,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) -> any, err` | Load a single entity by match criteria. |',
-    list: '| `list` | `(reqmatch, ctrl) -> any, err` | List entities matching the criteria. |',
-    create: '| `create` | `(reqdata, ctrl) -> any, err` | Create a new entity. |',
-    update: '| `update` | `(reqdata, ctrl) -> any, err` | Update an existing entity. |',
-    patch: '| `patch` | `(reqdata, ctrl) -> any, err` | Change part of an existing entity. |',
-    remove: '| `remove` | `(reqmatch, ctrl) -> any, err` | Remove an entity. |',
+    load: '| `load` | `(reqmatch, ctrl) -> any, err` | Load a single entity by match criteria, and return it. |',
+    list: '| `list` | `(reqmatch, ctrl) -> any, err` | List entities matching the criteria, one per record. |',
+    create: '| `create` | `(reqdata, ctrl) -> any, err` | Create a new entity, and return it. |',
+    update: '| `update` | `(reqdata, ctrl) -> any, err` | Update an existing entity, and return it. |',
+    patch: '| `patch` | `(reqdata, ctrl) -> any, err` | Change part of an existing entity, and return it. |',
+    remove: '| `remove` | `(reqmatch, ctrl) -> any, err` | Remove an entity, and return it marked as deleted. |',
   }
   const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
@@ -30,8 +30,8 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const recordOps = ['load', 'create', 'update', 'patch', 'remove'].filter((o) => opUnion.has(o))
     .map((o) => '`' + o + '`')
   const resultRows: string[] = []
-  if (recordOps.length) resultRows.push('| ' + recordOps.join(' / ') + ' | the entity record (a `table`) |')
-  if (opUnion.has('list')) resultRows.push('| `list` | an array (`table`) of entity records |')
+  if (recordOps.length) resultRows.push('| ' + recordOps.join(' / ') + ' | the entity, whose `data_get()` reads its record (a `table`) |')
+  if (opUnion.has('list')) resultRows.push('| `list` | an array (`table`) of entities, one per record |')
   const resultShapeRows = resultRows.join('\n')
 
   // The Result-shape illustration calls `load`, so the example entity must
@@ -109,8 +109,8 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return \`(value, err)\`. The \`value\` is the operation's
-data **directly** — there is no wrapper:
+Entity operations return \`(value, err)\`. The \`value\` is the entity
+itself — there is no wrapper:
 
 | Operation | \`value\` |
 | --- | --- |
@@ -119,9 +119,9 @@ ${resultShapeRows}
 Check \`err\` first (it is non-\`nil\` on failure), then use \`value\`:
 
     local ${eLower}, err = client:${eName}():${hasLoad ? 'load' : 'list'}(${
-      hasLoad && idF ? `{ ${idF} = "example_id" }` : ''})
+      hasLoad ? (idF ? `{ ${idF} = "example_id" }` : '') : listMatchArg('lua', exEnt)})
     if err then error(err) end
-    -- ${eLower} is the ${hasLoad ? 'loaded record' : 'record list'}
+    -- ${eLower} is ${hasLoad ? 'the loaded entity' : 'an array of entities, one per record'}
 
 Only \`direct()\` returns a response envelope — a \`table\` with \`ok\`,
 \`status\`, \`headers\`, and \`data\` keys.

package/project/.sdk/src/cmp/lua/ReadmeQuick_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, luaKey } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, luaKey, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -57,6 +57,7 @@ local client = ${ctor}
     // placeholder would not parse). Non-identifier keys use bracket syntax.
     const luaLit = (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 || 'OBJECT' === k) return '{}'
@@ -77,19 +78,24 @@ local client = ${ctor}
       fields.find((f: any) => f && !idNames.has(f.n) && isStringField(f)) ||
       fields.find((f: any) => f && !idNames.has(f.n))
     const displayField = displayFieldObj ? displayFieldObj.name : null
-    const idCol = dataIdF ? `item["${dataIdF}"]` : null
-    const dispCol = displayField ? `item["${displayField}"]` : null
+    const idCol = dataIdF ? `rec["${dataIdF}"]` : null
+    const dispCol = displayField ? `rec["${displayField}"]` : null
     const printCols = [idCol, dispCol].filter(Boolean).join(', ')
-    const printLine = printCols ? `  print(${printCols})` : `  print(item)`
+    // A record with neither column prints every field it holds.
+    const printRecord = (v: string, cols: string, pad: string): string => cols
+      ? `${pad}local rec = ${v}:data_get()\n${pad}print(${cols})`
+      : `${pad}for k, val in pairs(${v}:data_get()) do print(k, val) end`
+    const printLine = printRecord('item', printCols, '  ')
 
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-Entity operations return \`(value, err)\`. For \`list\`, \`value\` is the
-array of records itself — iterate it directly (there is no wrapper).
+Entity operations return \`(value, err)\`. For \`list\`, \`value\` is an
+array of entities, one per record — iterate it directly (there is no
+wrapper), and read each record with \`data_get()\`.
 
 \`\`\`lua
-local ${eVar}s, err = client:${eName}():list()
+local ${eVar}s, err = client:${eName}():list(${listMatchArg('lua', exampleEntity)})
 if err then error(err) end
 
 for _, item in ipairs(${eVar}s) do
@@ -104,6 +110,7 @@ end
       const neName = nom(nestedEntity, 'Name')
       const neArticle = /^[aeiou]/i.test(neName) ? "an" : "a"
       const neVar = exampleVarName(neName.toLowerCase(), 'lua')
+      const neDataIdF = entityDataIdField(nestedEntity)
 
       const neIdF = entityIdField(nestedEntity)
       const neRequired = opRequestShape(nestedEntity, 'load').items
@@ -121,10 +128,12 @@ end
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 
+\`load\` returns the entity; \`data_get()\` reads its record.
+
 \`\`\`lua
 local ${neVar}, err = client:${neName}():load({ ${neMatch.join(', ')} })
 if err then error(err) end
-print(${neVar})
+${printRecord(neVar, neDataIdF ? `rec["${neDataIdF}"]` : '', '')}
 \`\`\`
 
 `)
@@ -142,10 +151,12 @@ print(${neVar})
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
+\`load\` returns the entity; \`data_get()\` reads its record.
+
 \`\`\`lua
 local ${eVar}, err = client:${eName}():load(${loadArg})
 if err then error(err) end
-print(${eVar})
+${printRecord(eVar, printCols, '')}
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/lua/ReadmeRef_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey, targetFeatures, opNeedsAction, bodyNote, listMatchArg } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -14,6 +14,7 @@ import {
 // parse).
 function luaLit(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 || 'OBJECT' === k) return '{}'
@@ -27,32 +28,32 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
   load: {
     sig: 'load(reqmatch, ctrl) -> any, err',
     returns: 'any, err',
-    desc: 'Load a single entity matching the given criteria.',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data_get()` reads, or `nil` and an error on failure.',
   },
   list: {
     sig: 'list(reqmatch, ctrl) -> any, err',
     returns: 'any, err',
-    desc: 'List entities matching the given criteria. Returns an array.',
+    desc: 'List entities matching the given criteria. Returns an array of entities, one per record, or `nil` and an error on failure.',
   },
   create: {
     sig: 'create(reqdata, ctrl) -> any, err',
     returns: 'any, err',
-    desc: 'Create a new entity with the given data.',
+    desc: 'Create a new entity with the given data. Returns the created entity, or `nil` and an error on failure.',
   },
   update: {
     sig: 'update(reqdata, ctrl) -> any, err',
     returns: 'any, err',
-    desc: 'Update an existing entity. The data must include the entity `id`.',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity, or `nil` and an error on failure.',
   },
   patch: {
     sig: 'patch(reqdata, ctrl) -> any, err',
     returns: 'any, err',
-    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`.',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity, or `nil` and an error on failure.',
   },
   remove: {
     sig: 'remove(reqmatch, ctrl) -> any, err',
     returns: 'any, err',
-    desc: 'Remove the entity matching the given criteria.',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, or `nil` and an error on failure.',
   },
 }
 
@@ -285,7 +286,7 @@ local result, err = client:${ent.Name}():${opname}(${arg})
           }
           else if ('list' === opname) {
             Content(`\`\`\`lua
-local results, err = client:${ent.Name}():list()
+local results, err = client:${ent.Name}():list(${listMatchArg('lua', ent)})
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/lua/ReadmeTopQuick_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,6 +13,7 @@ import {
 // doc test EXECUTES this block, so a comment placeholder would break it).
 function luaLit(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 || 'OBJECT' === k) return '{}'
@@ -33,9 +34,12 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
     ? `sdk.new({\n  apikey = os.getenv("${envName(model)}_APIKEY"),\n})`
     : `sdk.new()`
 
+  const shown = null != exampleEntity &&
+    ['list', 'load'].some((op: string) => Object.keys(exampleEntity.op || {}).includes(op))
+
   Content(`\`\`\`lua
 local sdk = require("${model.name}_sdk")
-
+${shown ? 'local json = require("dkjson")\n' : ''}
 local client = ${ctor}
 
 `)
@@ -51,9 +55,12 @@ local client = ${ctor}
     let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`-- List all ${eName.toLowerCase()}s
-local ${eVar}s, err = client:${eName}():list()
-print(${eVar}s)
+      Content(`-- List all ${eName.toLowerCase()}s (an array of entities, one per record; err on failure)
+local ${eVar}s, err = client:${eName}():list(${listMatchArg('lua', exampleEntity)})
+if err then error(err) end
+for _, ${eVar} in ipairs(${eVar}s) do
+  print(json.encode(${eVar}:data_get()))
+end
 `)
       hasCall = true
     }
@@ -72,9 +79,10 @@ print(${eVar}s)
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')} }`
         : ''
       Content(`
--- Load a specific ${eName.toLowerCase()}
+-- Load a specific ${eName.toLowerCase()} (returns the entity; err on failure)
 local ${eVar}, err = client:${eName}():load(${loadArg})
-print(${eVar})
+if err then error(err) end
+print(json.encode(${eVar}:data_get()))
 `)
       hasCall = true
     }

package/project/.sdk/src/cmp/lua/ReadmeTopTest_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, luaKey } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, luaKey, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,6 +11,7 @@ import {
 // A type-correct Lua literal for a field's canonical type.
 function luaLit(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 || 'OBJECT' === k) return '{}'
@@ -36,16 +37,16 @@ local client = sdk.test()
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = ''
-    if (isMatchOp) {
+    if (isMatchOp || ('list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length)) {
       // 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
-        .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
         ? `{ ${items.map((it: any) =>
-          `${luaKey(it.name)} = ${it.name === idF ? '"test01"' : luaLit(it.type)}`).join(', ')} }`
+          `${luaKey(it.name)} = ${isMatchOp && it.name === idF ? '"test01"' : luaLit(it.type)}`).join(', ')} }`
         : ''
     } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items

package/project/.sdk/src/cmp/lua/fragment/Entity.fragment.lua

@@ -4,6 +4,7 @@ local json = require("dkjson")
 local vs = require("utility.struct.struct")
 local helpers = require("core.helpers")
 
+---@class EntyClass
 local EntyClass = {}
 EntyClass.__index = EntyClass
 

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

@@ -7,7 +7,7 @@ local entityCreateOp = {}
 
 ---@param reqdata EntityNameCreateData
 ---@param ctrl? table
----@return EntityName
+---@return EntyClass
 ---@return string? err
 function EntyClass:create(reqdata, ctrl)
   local utility = self._utility

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

@@ -4,7 +4,7 @@ local entityListOp = {}
 
 ---@param reqmatch EntityNameListMatch
 ---@param ctrl? table
----@return EntityName[]
+---@return EntyClass[]
 ---@return string? err
 function EntyClass:list(reqmatch, ctrl)
   local utility = self._utility

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

@@ -7,7 +7,7 @@ local entityLoadOp = {}
 
 ---@param reqmatch EntityNameLoadMatch
 ---@param ctrl? table
----@return EntityName
+---@return EntyClass
 ---@return string? err
 function EntyClass:load(reqmatch, ctrl)
   local utility = self._utility

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

@@ -7,7 +7,7 @@ local entityPatchOp = {}
 
 ---@param reqdata EntityNamePatchData
 ---@param ctrl? table
----@return EntityName
+---@return EntyClass
 ---@return string? err
 function EntyClass:patch(reqdata, ctrl)
   local utility = self._utility

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

@@ -7,7 +7,7 @@ local entityRemoveOp = {}
 
 ---@param reqmatch EntityNameRemoveMatch
 ---@param ctrl? table
----@return EntityName
+---@return EntyClass
 ---@return string? err
 function EntyClass:remove(reqmatch, ctrl)
   local utility = self._utility

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

@@ -7,7 +7,7 @@ local entityUpdateOp = {}
 
 ---@param reqdata EntityNameUpdateData
 ---@param ctrl? table
----@return EntityName
+---@return EntyClass
 ---@return string? err
 function EntyClass:update(reqdata, ctrl)
   local utility = self._utility

package/project/.sdk/src/cmp/ocaml/ReadmeEntity_ocaml.ts

@@ -6,13 +6,14 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { ocamlVarName } from './utility_ocaml'
+import { ocamlVarName, ocamlListMatch } from './utility_ocaml'
 
 
 // A type-correct OCaml `value` literal for a field's canonical type. Strings
 // render the quoted placeholder.
 function ocamlLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Null'
   if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
   if ('BOOLEAN' === k) return '(Bool true)'
   if ('ARRAY' === k) return '(empty_list ())'
@@ -154,7 +155,7 @@ let ${fn}_data = ${fn}.e_data_get ()
 
 \`\`\`ocaml
 (* One ENTITY per record. *)
-let ${fn}s = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval
+let ${fn}s = (Sdk_client.${fn} client Noval).e_list ${ocamlListMatch(entity)} Noval
 let ${fn}_datas = List.map (fun e -> e.e_data_get ()) ${fn}s
 \`\`\`
 

package/project/.sdk/src/cmp/ocaml/ReadmeHowto_ocaml.ts

@@ -6,12 +6,13 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { ocamlOpField, ocamlVarName } from './utility_ocaml'
+import { ocamlListMatch, ocamlOpField, ocamlVarName } from './utility_ocaml'
 
 
 // A type-correct OCaml `value` literal for a field's canonical type.
 function ocamlLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Null'
   if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
   if ('BOOLEAN' === k) return '(Bool true)'
   if ('ARRAY' === k) return '(empty_list ())'
@@ -34,7 +35,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = 'Noval'
   if (exampleEntity && 'list' === primaryOp) {
-    testArg = '(empty_map ())'
+    testArg = ocamlListMatch(exampleEntity)
   } else if (exampleEntity && isMatchOp) {
     testArg = idF ? `(jo [("${idF}", Str "test01")])` : '(empty_map ())'
   } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp)) {

package/project/.sdk/src/cmp/ocaml/ReadmeModel_ocaml.ts

@@ -40,6 +40,7 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
 \`\`\`ocaml
 open Voxgig_struct
 open Sdk_helpers
+open Sdk_types
 
 let client = Sdk_client.make options
 \`\`\`