@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/kotlin/fragment/EntityBase.fragment.kt

@@ -186,7 +186,8 @@ abstract class EntityBase(nm: String, clientIn: SdkClient, entoptsIn: MutableMap
 
     val signal = opts["signal"]
 
-    val ctrl = Helpers.toMapAny(opts["ctrl"]) ?: linkedMapOf()
+    // A copy: the caller's ctrl gains no key, and explain stays its own record.
+    val ctrl: MutableMap<String, Any?> = LinkedHashMap(Helpers.toMapAny(opts["ctrl"]) ?: linkedMapOf())
     ctrl["stream"] = opts
 
     val ctxmap = linkedMapOf<String, Any?>()

package/project/.sdk/src/cmp/kotlin/fragment/EntityPatchOp.fragment.kt

@@ -0,0 +1,40 @@
+package KOTLINPACKAGE.entity
+
+import KOTLINPACKAGE.core.Context
+import KOTLINPACKAGE.core.Helpers
+import KOTLINPACKAGE.core.SdkClient
+import KOTLINPACKAGE.utility.struct.Struct
+
+// Fragment carrier: only the section between the EJECT markers is spliced
+// into the generated entity class (which extends EntityBase).
+@Suppress("UNCHECKED_CAST")
+abstract class EntityPatchOpFragment(clientIn: SdkClient, entoptsIn: MutableMap<String, Any?>?) :
+  EntityBase("entityname", clientIn, entoptsIn) {
+
+// EJECT-START
+
+  override fun patch(reqdata: MutableMap<String, Any?>?, ctrl: MutableMap<String, Any?>?): Any? {
+    val ctxmap = linkedMapOf<String, Any?>()
+    ctxmap["opname"] = "patch"
+    ctxmap["ctrl"] = ctrl
+    ctxmap["match"] = this.match
+    ctxmap["data"] = this.data
+    ctxmap["reqdata"] = reqdata
+    val ctx = this.utility.makeContext(ctxmap, this.entctx)
+
+    return runOp(ctx) {
+      val result = ctx.result
+      if (result != null) {
+        if (result.resmatch != null) {
+          this.match = result.resmatch!!
+        }
+        if (result.resdata != null) {
+          val d = Helpers.toMapAny(Struct.clone(result.resdata))
+          this.data = d ?: linkedMapOf()
+        }
+      }
+    }
+  }
+
+// EJECT-END
+}

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/EntityTypes_lua.ts

@@ -67,7 +67,7 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
 `)
 
       const ops = ent.op || {}
-      ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+      ;['load', 'list', 'create', 'update', 'patch', 'remove'].forEach((opname: string) => {
         if (null == ops[opname]) {
           return
         }

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

@@ -42,7 +42,7 @@ const Entity = cmp(function Entity(props: any) {
       const opnames = Object.keys(entity.op || {})
 
       const opfrags =
-        (['load', 'list', 'create', 'update', 'remove']
+        (['load', 'list', 'create', 'update', 'patch', 'remove']
           .reduce((a: any, opname: string) =>
           (a['-- #' + camelify(opname) + 'Op'] =
             !opnames.includes(opname) ? '' : ({ indent }: any) => {

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

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
+  inactiveFeatureExcludes,
   targetFeatures, pluginExcludes,
   TEST_CONTROL_EXCLUDE
 } from '@voxgig/sdkgen'
@@ -58,7 +59,7 @@ const Main = cmp(async function Main(props: any) {
   Copy({
     from: 'tm/' + target.name,
     exclude: [/src\//, TEST_CONTROL_EXCLUDE,
-      ...containerExcludes, ...pluginExcludes(model)],
+      ...containerExcludes, ...inactiveFeatureExcludes(props.ctx$, target), ...pluginExcludes(model)],
     replace: {
       ...props.ctx$.stdrep,
     }

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

@@ -83,8 +83,20 @@ return prepare_auth_util
 
   return head + `
 local vs = require("utility.struct.struct")
-
-` + consts + (basic ? BASE64 : '') + ('cookie' === where ? COOKIE_SET : '') + `
+` + ('cookie' === where ? `local helpers = require("core.helpers")
+` : '') + `
+` + consts + `
+
+-- The client's auth.name option, when set, replaces the name the API declares.
+local function auth_name(options)
+  local name = vs.getpath(options, "auth.name")
+  if type(name) == "string" and name ~= "" then${'header' === where ? `
+    -- ASCII rules, as a field name is ASCII: lower-casing in the string library follows the C locale.` : ''}
+    return ${'header' === where ? FOLD : 'name'}
+  end
+  return ${CRED}
+end
+` + (basic ? BASE64 : '') + ('cookie' === where ? COOKIE_SET : '') + `
 local function prepare_auth_util(ctx)
   local spec = ctx.spec
   if spec == nil then
@@ -96,16 +108,23 @@ ${bag(where)}  local options = ctx.client:options_map()
 
   -- Public APIs that need no auth omit the options.auth block entirely.
   if options.auth == nil then
-${clear(where, 4)}
+${clear(where, CRED, 4)}
     return spec, nil
   end
 
+  local name = auth_name(options)
+
+  -- A credential left under the declared name would travel beside the renamed one.
+  if name ~= ${CRED} then
+${clear(where, CRED, 4)}
+  end
+
   local apikey = vs.getprop(options, OPTION_APIKEY, NOT_FOUND)
 ` + (basic ? BASIC : '') + `
   if apikey == nil
     or (type(apikey) == "string" and (apikey == NOT_FOUND or apikey == ""))
   then
-${clear(where, 4)}
+${clear(where, 'name', 4)}
   else
 ${place(where)}
   end
@@ -118,6 +137,9 @@ return prepare_auth_util
 }
 
 
+const FOLD = '(string.gsub(name, "[A-Z]", function(c) return string.char(c:byte() + 32) end))'
+
+
 function credConst(where: string): string {
   return 'query' === where ? 'QUERY_AUTH' :
     'cookie' === where ? 'COOKIE_AUTH' : 'HEADER_AUTH'
@@ -133,18 +155,20 @@ function bag(where: string): string {
 }
 
 
-function clear(where: string, indent: number): string {
+// A cookie has no header of its own: place() writes it into `cookie` as
+// `name=value`, so clear() frees that pair, not a header of that name.
+function clear(where: string, name: string, indent: number): string {
   const pad = ' '.repeat(indent)
 
   if ('query' === where) {
-    return pad + 'query[QUERY_AUTH] = nil'
+    return pad + `query[${name}] = nil`
   }
 
   if ('cookie' === where) {
-    return pad + 'cookie_set(headers, nil)'
+    return pad + `cookie_set(headers, ${name}, nil)`
   }
 
-  return pad + 'headers[HEADER_AUTH] = nil'
+  return pad + `headers[${name}] = nil`
 }
 
 
@@ -157,7 +181,7 @@ function place(where: string): string {
     if type(apikey) == "string" then
       apikey_val = apikey
     end
-    query[QUERY_AUTH] = apikey_val`
+    query[name] = apikey_val`
   }
 
   if ('cookie' === where) {
@@ -167,7 +191,7 @@ function place(where: string): string {
     end
     -- The prefix is a header-value convention and has no meaning in a
     -- cookie pair, so it is dropped the way a query placement drops it.
-    cookie_set(headers, apikey_val)`
+    cookie_set(headers, name, apikey_val)`
   }
 
   return `    local auth_prefix = ""
@@ -181,9 +205,9 @@ function place(where: string): string {
     end
     -- Empty prefix (raw apiKey credential) must not add a leading space.
     if auth_prefix == "" then
-      headers[HEADER_AUTH] = apikey_val
+      headers[name] = apikey_val
     else
-      headers[HEADER_AUTH] = auth_prefix .. " " .. apikey_val
+      headers[name] = auth_prefix .. " " .. apikey_val
     end`
 }
 
@@ -203,7 +227,7 @@ const BASIC = `
     if apikey == nil
       or (type(apikey) == "string" and (apikey == NOT_FOUND or apikey == ""))
     then
-      headers[HEADER_AUTH] = nil
+      headers[name] = nil
     else
       local auth_prefix = ""
       local ap = vs.getpath(options, "auth.prefix")
@@ -215,9 +239,9 @@ const BASIC = `
       -- registration covers.
       ctx.utility.clean_add(ctx, joined)
       if auth_prefix == "" then
-        headers[HEADER_AUTH] = joined
+        headers[name] = joined
       else
-        headers[HEADER_AUTH] = auth_prefix .. " " .. joined
+        headers[name] = auth_prefix .. " " .. joined
       end
     end
 
@@ -273,21 +297,16 @@ end
 
 
 const COOKIE_SET = `
-local function cookie_set(headers, value)
+local function cookie_set(headers, name, value)
   local kept = {}
   local existing = headers[HEADER_COOKIE]
 
   if type(existing) == "string" then
-    for pair in string.gmatch(existing, "[^;]+") do
-      local one = string.match(pair, "^%s*(.-)%s*$")
-      if one ~= "" and string.match(one, "^[^=]*") ~= COOKIE_AUTH then
-        kept[#kept + 1] = one
-      end
-    end
+    kept = helpers.cookie_keep(existing, { [name] = true })
   end
 
   if value ~= nil then
-    kept[#kept + 1] = COOKIE_AUTH .. "=" .. value
+    kept[#kept + 1] = name .. "=" .. value
   end
 
   if #kept == 0 then

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 } 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 '{}'
@@ -26,6 +27,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'list(match)',   desc: 'List entities matching the criteria.' },
   create: { method: 'create(data)',  desc: 'Create a new entity with the given data.' },
   update: { method: 'update(data)',  desc: 'Update an existing entity.' },
+  patch:  { method: 'patch(data)',   desc: 'Change part of an existing entity.' },
   remove: { method: 'remove(match)', desc: 'Remove the matching entity.' },
 }
 
@@ -51,6 +53,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
+    // 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 || {})
     const idF = entityIdField(entity)
     // Sanitise the local variable name — an entity whose lowercased name is a
@@ -107,7 +111,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       const loadItems = opRequestShape(entity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -126,17 +130,17 @@ local ${eVar}, err = client:${entity.Name}():load(${loadArg})
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`lua
-local ${eVar}s, err = client:${entity.Name}():list()
+local ${eVar}s, err = client:${entity.Name}():list(${listMatchArg('lua', entity)})
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       // Members come from the SAME shape the runtime validates
       // (opRequestShape): every required member must appear — including a
       // required id and parent keys like page_id — with a real, executable

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
@@ -102,12 +103,18 @@ local function extract_blocks(md, lang)
   return blocks
 end
 
+-- The client VARIABLE, not the word: a module name carries the word between
+-- hyphens (multifon-client_sdk).
+local function uses_client(src)
+  return (" " .. src .. " "):find("[^%w_%-%./\\"']client[^%w_%-/\\"']") ~= nil
+end
+
 -- A block is runnable if it builds a client (sdk.new / sdk.test) or uses one
 -- (references \`client\`). These are the blocks we EXECUTE offline.
 local function is_runnable(block)
   return block:find("sdk%s*%.%s*new") ~= nil
     or block:find("sdk%s*%.%s*test") ~= nil
-    or block:find("client") ~= nil
+    or uses_client(block)
 end
 
 -- NARROW illustration class:
@@ -149,7 +156,7 @@ local function make_runnable(block)
   if not src:find("require%s*%(") then
     table.insert(prelude, 'local sdk = require("' .. SDK_MODULE .. '")')
   end
-  if not constructs and src:find("client") then
+  if not constructs and uses_client(src) then
     table.insert(prelude, "local client = " .. TEST_CTOR)
   end
 
@@ -213,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,14 +32,14 @@ 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)) {
+  } 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)
@@ -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/ReadmeInstall_lua.ts

@@ -24,9 +24,9 @@ export LUA_PATH="path/to/lua/?.lua;path/to/lua/?/init.lua;;"
 
   // Publish pending: not yet on LuaRocks. Install from the git release tag,
   // or add the source directory to LUA_PATH.
-  const { releasesUrl } = repoInfo(model)
+  const { hostName, tagsUrl } = repoInfo(model)
   Content(`This package is not yet published to LuaRocks. Install it from the
-GitHub release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})),
+${hostName} release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})),
 or add the source directory to your \`LUA_PATH\`:
 
 \`\`\`bash

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,7 +10,7 @@ import {
 
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const { target, ctx$: { model } } = props
-  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const info = modelText(model)
   const tagline = info.tagline || ''
 
   // Derive a real entity accessor from the model for the semantic-entity
@@ -22,7 +22,7 @@ const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   // Model-driven op list — only the operations the active entities actually
   // expose (a read-only entity has just list+load); never claim
   // create/update/remove exist when no entity has them.
-  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'patch', 'remove']
   const opSet = new Set<string>()
   Object.values(entity || {}).forEach((e: any) => {
     if (!e || e.active === false) return

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,20 +17,21 @@ 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. |',
-    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', 'remove']
+  const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
-  const recordOps = ['load', 'create', 'update', 'remove'].filter((o) => opUnion.has(o))
+  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
@@ -108,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\` |
 | --- | --- |
@@ -118,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, '')}
 \`\`\`
 
 `)
@@ -172,7 +183,8 @@ print(${eVar})
       ? `created:data_get()["${dataIdF}"]`
       : luaLit(idParamType(opname), 'example_id')
 
-    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('patch') ||
+      opnames.includes('remove')) {
       Content(`### 4. Create, update, and remove
 
 \`\`\`lua
@@ -189,6 +201,13 @@ if err then error(err) end
         Content(`-- Update
 client:${eName}():update({ ${updatePairs.join(', ')} })
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`${idF} = ${idValueFor('patch')}`] : []).concat(examplePairs('patch'))
+        Content(`-- Patch — sends only the fields given
+client:${eName}():patch({ ${patchPairs.join(', ')} })
+
 `)
       }
       if (opnames.includes('remove')) {