@voxgig/sdkgen 4.34.1 → 4.34.2

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

@@ -10,6 +10,7 @@ import {
   canonKey,
   canonScalarKey,
   canonToType,
+  requiredItems,
 } from '@voxgig/sdkgen'
 
 
@@ -25,6 +26,7 @@ function elixirType(sentinel: unknown): string {
 
 function elixirLit(sentinel: unknown, placeholder: string = 'example'): string {
   switch (canonScalarKey(sentinel)) {
+    case 'NULL': return 'nil'
     case 'INTEGER':
     case 'NUMBER': return '1'
     case 'BOOLEAN': return 'true'
@@ -35,6 +37,15 @@ function elixirLit(sentinel: unknown, placeholder: string = 'example'): string {
 }
 
 
+// A list's required route and query parameters, as the match argument after the entity.
+function elixirListArgs(entity: any, name: string): string {
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? `, ${name}.Helpers.deep(%{${items.map((it: any) => `${elixirString(it.name)} => ${elixirLit(it.type)}`).join(', ')}})`
+    : ''
+}
+
+
 function projectPath(suffix?: string): string {
   return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
 }
@@ -137,5 +148,6 @@ export {
   elixirString,
   elixirType,
   elixirLit,
+  elixirListArgs,
   projectPath,
 }

package/project/.sdk/src/cmp/go/ReadmeEntity_go.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, entityIdField, entityOps, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, entityOps, opRequestShape, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -117,7 +117,7 @@ ${eVar}, err := client.${entity.Name}(nil).Load(${loadArg}, nil)
 if err != nil {
     panic(err)
 }
-fmt.Println(${eVar}) // the loaded record
+fmt.Println(${eVar}.(sdk.Entity).Data()) // the loaded entity's record
 \`\`\`
 
 `)
@@ -127,11 +127,14 @@ fmt.Println(${eVar}) // the loaded record
       Content(`#### Example: List
 
 \`\`\`go
-${eVar}s, err := client.${entity.Name}(nil).List(nil, nil)
+${eVar}s, err := client.${entity.Name}(nil).List(${listMatchArg('go', entity)}, nil)
 if err != nil {
     panic(err)
 }
-fmt.Println(${eVar}s) // the array of records
+// A []any of entities, one per record.
+for _, item := range ${eVar}s.([]any) {
+    fmt.Println(item.(sdk.Entity).Data())
+}
 \`\`\`
 
 `)
@@ -158,7 +161,7 @@ result, err := client.${entity.Name}(nil).Create(map[string]any{
 if err != nil {
     panic(err)
 }
-fmt.Println(result)
+fmt.Println(result.(sdk.Entity).Data()) // the created entity's record
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/go/ReadmeExplanation_go.ts

@@ -14,7 +14,9 @@ The Go SDK uses \`map[string]any\` throughout rather than typed structs.
 This mirrors the dynamic nature of the API and keeps the SDK
 flexible \u2014 no code generation is needed when the API schema changes.
 
-Use \`core.ToMapAny()\` to safely cast results and nested data.
+An operation returns the entity, and its \`Data()\` returns the record. Use
+\`core.ToMapAny()\` to safely cast that record, or data nested in it, to
+\`map[string]any\`: it returns \`nil\` for anything else, an entity included.
 
 ### Package structure
 

package/project/.sdk/src/cmp/go/ReadmeHowto_go.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, goModule } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, goModule, requiredItems, litPair } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -12,6 +12,7 @@ import { goVarName } from './utility_go'
 
 function goLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'nil'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '[]any{}'
@@ -41,32 +42,43 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = 'nil'
-  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))
     testArg = 0 < items.length
-      ? `map[string]any{${items.map((it: any) => `"${it.name}": ${it.name === idF ? '"test01"' : goLit(it.type)}`).join(', ')}}`
+      ? `map[string]any{${items.map((it: any) => litPair('go', it.name, isMatchOp && it.name === idF ? '"test01"' : goLit(it.type))).join(', ')}}`
       : 'nil'
   } 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 = `map[string]any{${chosen.map((it: any) => `"${it.name}": ${goLit(it.type)}`).join(', ')}}`
+    testArg = `map[string]any{${chosen.map((it: any) => litPair('go', it.name, goLit(it.type))).join(', ')}}`
   }
 
   // The op-driven test-mode block, shown only when the SDK has an entity op.
   // A direct()-only SDK (no ops anywhere) shows a Direct() call instead — never
   // a fabricated method (`cap(primaryOp)` would also fail on a null op).
-  const testModeExample = primaryOp
+  const testModeExample = 'list' === primaryOp
+    ? `${eLower}s, err := client.${eName}(nil).List(
+    ${testArg}, nil,
+)
+if err != nil {
+    panic(err)
+}
+// A []any of entities, one per mock record.
+for _, item := range ${eLower}s.([]any) {
+    fmt.Println(item.(sdk.Entity).Data())
+}`
+    : primaryOp
     ? `${eLower}, err := client.${eName}(nil).${cap(primaryOp)}(
     ${testArg}, nil,
 )
 if err != nil {
     panic(err)
 }
-fmt.Println(${eLower}) // the returned mock data`
+fmt.Println(${eLower}.(sdk.Entity).Data()) // the entity's mock record`
     : `result, err := client.Direct(map[string]any{"path": "/api/resource", "method": "GET"})
 if err != nil {
     panic(err)

package/project/.sdk/src/cmp/go/ReadmeModel_go.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, entityIdField, entityPrimaryOp, goModule } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, entityIdField, entityPrimaryOp, goModule, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -24,12 +24,12 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   entityList.forEach((e: any) => Object.keys(e.op || {})
     .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
   const opRowDefs: Record<string, string> = {
-    load: '| `Load` | `(reqmatch, ctrl map[string]any) (any, error)` | Load a single entity by match criteria. |',
-    list: '| `List` | `(reqmatch, ctrl map[string]any) (any, error)` | List entities matching the criteria. |',
-    create: '| `Create` | `(reqdata, ctrl map[string]any) (any, error)` | Create a new entity. |',
-    update: '| `Update` | `(reqdata, ctrl map[string]any) (any, error)` | Update an existing entity. |',
-    patch: '| `Patch` | `(reqdata, ctrl map[string]any) (any, error)` | Change part of an existing entity. |',
-    remove: '| `Remove` | `(reqmatch, ctrl map[string]any) (any, error)` | Remove an entity. |',
+    load: '| `Load` | `(reqmatch, ctrl map[string]any) (any, error)` | Load a single entity by match criteria, and return it. |',
+    list: '| `List` | `(reqmatch, ctrl map[string]any) (any, error)` | List entities matching the criteria, one per record. |',
+    create: '| `Create` | `(reqdata, ctrl map[string]any) (any, error)` | Create a new entity, and return it. |',
+    update: '| `Update` | `(reqdata, ctrl map[string]any) (any, error)` | Update an existing entity, and return it. |',
+    patch: '| `Patch` | `(reqdata, ctrl map[string]any) (any, error)` | Change part of an existing entity, and return it. |',
+    remove: '| `Remove` | `(reqmatch, ctrl map[string]any) (any, error)` | 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')
@@ -37,8 +37,8 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const recordOps = ['load', 'create', 'update', 'patch', 'remove'].filter((o) => opUnion.has(o))
     .map((o) => '`' + o.charAt(0).toUpperCase() + o.slice(1) + '`')
   const resultRows: string[] = []
-  if (recordOps.length) resultRows.push('| ' + recordOps.join(' / ') + ' | the entity record (`map[string]any`) |')
-  if (opUnion.has('list')) resultRows.push('| `List` | a `[]any` of entity records |')
+  if (recordOps.length) resultRows.push('| ' + recordOps.join(' / ') + ' | the entity, whose `Data()` reads its record (`map[string]any`) |')
+  if (opUnion.has('list')) resultRows.push('| `List` | a `[]any` of entities, one per record |')
   const resultShapeRows = resultRows.join('\n')
 
   const gomodule = goModule(model, target.name)
@@ -62,7 +62,8 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const firstIsMatchOp = 'load' === firstPrimaryOp || 'remove' === firstPrimaryOp
   const firstOpArg = firstIsMatchOp
     ? (firstIdF ? `map[string]any{"${firstIdF}": "example_id"}` : 'nil')
-    : 'map[string]any{/* fields */}'
+    : 'list' === firstPrimaryOp ? listMatchArg('go', firstWithOp)
+      : 'map[string]any{/* fields */}'
 
   const resultCallExample = firstPrimaryOp
     ? `Check \`err\` first, then use the value directly (or the typed
@@ -71,7 +72,9 @@ slice):
 
     ${firstEntityVar}, err := client.${firstEntityName}(nil).${firstPrimaryMethod}(${firstOpArg}, nil)
     if err != nil { /* handle */ }
-    // ${firstEntityVar} is the returned record
+    // ${'list' === firstPrimaryOp
+    ? `${firstEntityVar} is a []any of entities, one per record`
+    : `${firstEntityVar} is the entity; ${firstEntityVar}.(sdk.Entity).Data() reads its record`}
 
 `
     : ''
@@ -132,8 +135,8 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return \`(value, error)\`. The \`value\` is the
-operation's data **directly** — there is no wrapper:
+Entity operations return \`(value, error)\`. The \`value\` is the entity
+itself — there is no wrapper:
 
 | Operation | \`value\` |
 | --- | --- |

package/project/.sdk/src/cmp/go/ReadmeQuick_go.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, opRequestShape, entityIdField, entityOps, goModule , serverVariables} from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, opRequestShape, entityIdField, entityOps, goModule, serverVariables, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -80,25 +80,25 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
     }
 
     if (opnames.includes('list')) {
-      body.push(`    // List ${eLower} records — the value is the array of records itself.`)
-      body.push(`    ${eLower}s, err := client.${eName}(nil).List(nil, nil)`)
+      body.push(`    // List ${eLower} records — the value is a []any of entities, one per record.`)
+      body.push(`    ${eLower}s, err := client.${eName}(nil).List(${listMatchArg('go', exampleEntity)}, nil)`)
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
       body.push(`    for _, item := range ${eLower}s.([]any) {`)
-      body.push(`        fmt.Println(item)`)
+      body.push(`        fmt.Println(item.(sdk.Entity).Data())`)
       body.push(`    }`)
       body.push(``)
       usesFmt = true
     }
 
     if (opnames.includes('load')) {
-      body.push(`    // Load a single ${eLower} — the value is the loaded record.`)
+      body.push(`    // Load a single ${eLower} — the value is the entity; Data() reads its record.`)
       body.push(`    ${eLower}, err := client.${eName}(nil).Load(${matchArg('load')}, nil)`)
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
-      body.push(`    fmt.Println(${eLower})`)
+      body.push(`    fmt.Println(${eLower}.(sdk.Entity).Data())`)
       body.push(``)
       usesFmt = true
     }
@@ -109,7 +109,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
-      body.push(`    fmt.Println(created)`)
+      body.push(`    fmt.Println(created.(sdk.Entity).Data())`)
       body.push(``)
       usesFmt = true
     }
@@ -125,7 +125,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
-      body.push(`    fmt.Println(updated)`)
+      body.push(`    fmt.Println(updated.(sdk.Entity).Data())`)
       body.push(``)
       usesFmt = true
     }
@@ -139,7 +139,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
-      body.push(`    fmt.Println(patched)`)
+      body.push(`    fmt.Println(patched.(sdk.Entity).Data())`)
       body.push(``)
       usesFmt = true
     }
@@ -150,7 +150,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
-      body.push(`    fmt.Println(removed)`)
+      body.push(`    fmt.Println(removed.(sdk.Entity).Data())`)
       body.push(``)
       usesFmt = true
     }
@@ -185,9 +185,10 @@ func main() {
   Content(`### Quickstart
 
 A complete program: create a client, then call the entity operations.
-Each operation returns \`(value, error)\` — the value is the data itself
-(there is no \`{ok, data}\` wrapper), so check \`err\` and use the value
-directly.
+Each operation returns \`(value, error)\` — the value is the entity, and for
+\`List\` a \`[]any\` of entities, one per record (there is no \`{ok, data}\`
+wrapper), so check \`err\` and read a record through the entity's
+\`Data()\`.
 
 \`\`\`go
 ${program}

package/project/.sdk/src/cmp/go/ReadmeRef_go.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, entityOps, opRequestShape , targetFeatures, bodyNote } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, entityOps, opRequestShape, targetFeatures, bodyNote, listMatchArg } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -14,33 +14,32 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
   load: {
     sig: 'Load(reqmatch, ctrl map[string]any) (any, error)',
     returns: '(any, error)',
-    desc: 'Load a single entity matching the given criteria.',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `Data()` reads; `err` is non-nil on failure.',
   },
   list: {
     sig: 'List(reqmatch, ctrl map[string]any) (any, error)',
     returns: '(any, error)',
-    desc: 'List entities matching the given criteria. Returns an array.',
+    desc: 'List entities matching the given criteria. Returns a `[]any` of entities, one per record; `err` is non-nil on failure.',
   },
   create: {
     sig: 'Create(reqdata, ctrl map[string]any) (any, error)',
     returns: '(any, error)',
-    desc: 'Create a new entity with the given data.',
+    desc: 'Create a new entity with the given data. Returns the created entity; `err` is non-nil on failure.',
   },
   update: {
     sig: 'Update(reqdata, ctrl map[string]any) (any, error)',
     returns: '(any, error)',
-    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; `err` is non-nil on failure.',
   },
   patch: {
     sig: 'Patch(reqdata, ctrl map[string]any) (any, error)',
     returns: '(any, error)',
-    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; `err` is non-nil on failure.',
   },
   remove: {
     sig: 'Remove(reqmatch, ctrl map[string]any) (any, error)',
     returns: '(any, error)',
-    desc: 'Remove the entity matching the given criteria.',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted; `err` is non-nil on failure.',
   },
 }
 
@@ -278,18 +277,20 @@ result, err := client.${ent.Name}(nil).${goOpName}(${arg}, nil)
 if err != nil {
     panic(err)
 }
-fmt.Println(result)
+fmt.Println(result.(sdk.Entity).Data())
 \`\`\`
 
 `)
           }
           else if ('list' === opname) {
             Content(`\`\`\`go
-results, err := client.${ent.Name}(nil).List(nil, nil)
+results, err := client.${ent.Name}(nil).List(${listMatchArg('go', ent)}, nil)
 if err != nil {
     panic(err)
 }
-fmt.Println(results)
+for _, item := range results.([]any) {
+    fmt.Println(item.(sdk.Entity).Data())
+}
 \`\`\`
 
 `)
@@ -313,7 +314,7 @@ result, err := client.${ent.Name}(nil).Create(map[string]any{
 if err != nil {
     panic(err)
 }
-fmt.Println(result)
+fmt.Println(result.(sdk.Entity).Data())
 \`\`\`
 
 `)
@@ -336,7 +337,7 @@ ${updateLines}    // ${'patch' === opname ? 'Only the fields to change' : 'Field
 if err != nil {
     panic(err)
 }
-fmt.Println(result)
+fmt.Println(result.(sdk.Entity).Data())
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/go/ReadmeTopQuick_go.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField, entityOps, opRequestShape, goModule , serverVariables} from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, entityOps, opRequestShape, goModule, serverVariables, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -51,12 +51,14 @@ client := ${ctor}
     let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s
-${eVar}s, err := client.${eName}(nil).List(nil, nil)
+      Content(`// List all ${eName.toLowerCase()}s (one entity per record; err is non-nil on failure)
+${eVar}s, err := client.${eName}(nil).List(${listMatchArg('go', exampleEntity)}, nil)
 if err != nil {
     panic(err)
 }
-fmt.Println(${eVar}s)
+for _, ${eVar} := range ${eVar}s.([]any) {
+    fmt.Println(${eVar}.(sdk.Entity).Data())
+}
 `)
       hasCall = true
     }
@@ -87,14 +89,14 @@ fmt.Println(${eVar}s)
             it.name === neIdF ? 'example_id' : 'example_' + it.name)}`)
 
       Content(`
-// Load a specific ${neName.toLowerCase()}
+// Load a specific ${neName.toLowerCase()} (returns the entity; err is non-nil on failure)
 ${neVar}, err := client.${neName}(nil).Load(
     map[string]any{${neMatchPairs.join(', ')}}, nil,
 )
 if err != nil {
     panic(err)
 }
-fmt.Println(${neVar})
+fmt.Println(${neVar}.(sdk.Entity).Data())
 `)
       hasCall = true
     }
@@ -110,12 +112,12 @@ fmt.Println(${neVar})
           `"${it.name}": ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op.load, it.name,
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')}}`
         : 'nil'
-      Content(`// Load ${eName.toLowerCase()} data
+      Content(`// Load a specific ${eName.toLowerCase()} (returns the entity; err is non-nil on failure)
 ${eVar}, err := client.${eName}(nil).Load(${loadArg}, nil)
 if err != nil {
     panic(err)
 }
-fmt.Println(${eVar})
+fmt.Println(${eVar}.(sdk.Entity).Data())
 `)
       hasCall = true
     }

package/project/.sdk/src/cmp/go/ReadmeTopTest_go.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, goModule } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, goModule, requiredItems, litPair } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,6 +11,7 @@ import {
 // A type-correct Go literal for a field's canonical type.
 function goLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'nil'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '[]any{}'
@@ -45,12 +46,15 @@ client := sdk.Test()
     let arg = 'nil'
     if (isMatchOp) {
       arg = idF ? `map[string]any{"${idF}": "test01"}` : 'nil'
+    } else if ('list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length) {
+      const chosen = requiredItems(exampleEntity, 'list')
+      arg = `map[string]any{${chosen.map((it: any) => litPair('go', it.name, goLit(it.type))).join(', ')}}`
     } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
       const required = items.filter((it: any) => !it.optional)
       const chosen = required.length ? required : items.slice(0, 3)
-      arg = `map[string]any{${chosen.map((it: any) => `"${it.name}": ${goLit(it.type)}`).join(', ')}}`
+      arg = `map[string]any{${chosen.map((it: any) => litPair('go', it.name, goLit(it.type))).join(', ')}}`
     }
     Content(`result, err := client.${eName}(nil).${cap(primaryOp)}(
     ${arg}, nil,

package/project/.sdk/src/cmp/go/utility_go.ts

@@ -68,7 +68,7 @@ function exampleValue(entity: any, op: any, paramName: string, placeholder: stri
   if ('NULL' === key) {
     return 'nil'
   }
-  return `"${placeholder}"`
+  return formatGoString(placeholder)
 }
 
 

package/project/.sdk/src/cmp/java/ReadmeEntity_java.ts

@@ -1,28 +1,16 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, opNeedsAction } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape, opNeedsAction, javaMap, javaMapOf } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { javaVarName } from './utility_java'
+import { javaVarName, javaListMatch, javaLit } from './utility_java'
 
 
 // Type names come from the shared canonToType 'java' column (single source of truth).
 
-// A type-correct, JSON-serialisable Java literal for a field's canonical type.
-function javaLit(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 'List.of()'
-  if ('OBJECT' === k) return 'Map.of()'
-  return `"${placeholder}"`
-}
-
-
 // Operation method spelling for Java: camelCase methods over the loose object
 // model. The op descriptions are language-agnostic.
 const OP_DESC: Record<string, { method: string, desc: string }> = {
@@ -124,9 +112,9 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       const loadArg = 0 < loadItems.length
-        ? `Map.of(${loadItems.map((it: any) =>
+        ? javaMapOf(loadItems.map((it: any) =>
           `"${it.name}", ${javaLit(it.type,
-            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')})`
+            it.name === idF ? entity.name + '_id' : it.name)}`))
         : 'null'
       Content(`#### Example: Load
 
@@ -141,7 +129,7 @@ Object ${eVar} = client.${accessor}(null).load(${loadArg}, null);
       Content(`#### Example: List
 
 \`\`\`java
-Object ${eVar}List = client.${accessor}(null).list(null, null);
+Object ${eVar}List = client.${accessor}(null).list(${javaListMatch(entity)}, null);
 \`\`\`
 
 `)
@@ -153,14 +141,15 @@ Object ${eVar}List = client.${accessor}(null).list(null, null);
       // required id and parent keys like page_id — with a real literal.
       const createItems = opRequestShape(entity, 'create').items
         .filter((it: any) => !it.optional)
+      const createMap = javaMap(createItems.length)
       Content(`#### Example: Create
 
 \`\`\`java
-Object ${eVar} = client.${accessor}(null).create(Map.of(
+Object ${eVar} = client.${accessor}(null).create(${createMap.open}
 `)
       createItems.map((it: any, i: number) => {
         const comma = i < createItems.length - 1 ? ',' : ''
-        Content(`    "${it.name}", ${javaLit(it.type, 'example_' + it.name)}${comma}  // ${canonToType(it.type, target.name)}
+        Content(`    ${createMap.pair(`"${it.name}", ${javaLit(it.type, 'example_' + it.name)}`)}${comma}  // ${canonToType(it.type, target.name)}
 `)
       })
       Content(`), null);

package/project/.sdk/src/cmp/java/ReadmeHowto_java.ts

@@ -1,24 +1,12 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems, javaMapOf } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { javaVarName } from './utility_java'
-
-
-// A type-correct Java literal for a field's canonical type.
-function javaLit(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 'List.of()'
-  if ('OBJECT' === k) return 'Map.of()'
-  return '"example"'
-}
+import { javaVarName, javaLit } from './utility_java'
 
 
 const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
@@ -39,23 +27,32 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'null'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `Map.of("${idF}", "test01")` : 'null'
+  } else if (exampleEntity && 'list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length) {
+    const chosen = requiredItems(exampleEntity, 'list')
+    testArg = javaMapOf(chosen.map((it: any) =>
+      `${JSON.stringify(it.name)}, ${javaLit(it.type)}`))
   } 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 = `Map.of(${chosen.map((it: any) =>
-      `"${it.name}", ${javaLit(it.type)}`).join(', ')})`
+    testArg = javaMapOf(chosen.map((it: any) =>
+      `${JSON.stringify(it.name)}, ${javaLit(it.type)}`))
   }
 
   // The op-driven test-mode line, shown only when the SDK has an entity op.
   // A direct()-only SDK (no ops anywhere) shows a direct() call instead.
-  const testModeExample = primaryOp
-    ? `// Entity ops return the ENTITY and raises on error;
-// call data() for the record.
-Object ${eVar} = client.${accessor}(null).${primaryOp}(${testArg}, null);
-// ${eVar} holds the mock response record
-System.out.println(${eVar});`
+  const testModeExample = 'list' === primaryOp
+    ? `// list returns a list of entities, one per mock record; it raises on error.
+List<?> ${eVar}List = (List<?>) client.${accessor}(null).list(${testArg}, null);
+for (Object ${eVar}Item : ${eVar}List) {
+    System.out.println(((SdkEntity) ${eVar}Item).data());
+}`
+    : primaryOp
+    ? `// Entity ops return the entity; they raise on error.
+SdkEntity ${eVar} = (SdkEntity) client.${accessor}(null).${primaryOp}(${testArg}, null);
+// data() reads the entity's mock record
+System.out.println(${eVar}.data());`
     : `Map<String, Object> result = client.direct(Map.of(
     "path", "/api/resource",
     "method", "GET"));