@voxgig/sdkgen 4.34.1 → 4.34.2

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

@@ -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) -> Object` | Load a single entity by match criteria. Raises on error. |',
-    list: '| `list` | `(reqmatch, ctrl) -> Object` | List entities matching the criteria (an aggregate list). Raises on error. |',
-    create: '| `create` | `(reqdata, ctrl) -> Object` | Create a new entity. Raises on error. |',
-    update: '| `update` | `(reqdata, ctrl) -> Object` | Update an existing entity. Raises on error. |',
-    patch: '| `patch` | `(reqdata, ctrl) -> Object` | Change part of an existing entity. Raises on error. |',
-    remove: '| `remove` | `(reqmatch, ctrl) -> Object` | Remove an entity. Raises on error. |',
+    load: '| `load` | `(reqmatch, ctrl) -> Object` | Load a single entity by match criteria, and return it. Raises on error. |',
+    list: '| `list` | `(reqmatch, ctrl) -> Object` | List entities matching the criteria, one per record. Raises on error. |',
+    create: '| `create` | `(reqdata, ctrl) -> Object` | Create a new entity, and return it. Raises on error. |',
+    update: '| `update` | `(reqdata, ctrl) -> Object` | Update an existing entity, and return it. Raises on error. |',
+    patch: '| `patch` | `(reqdata, ctrl) -> Object` | Change part of an existing entity, and return it. Raises on error. |',
+    remove: '| `remove` | `(reqmatch, ctrl) -> Object` | 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')
@@ -94,9 +94,10 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the ENTITY (call data() for the record) (a \`Map\` for single-entity
-ops, an aggregate \`List\` for \`list\`) as \`Object\` and raise on error. Wrap
-calls in \`try\`/\`catch\` to handle failures.
+Entity operations return the entity, and \`list\` a list of entities, one per
+record, as \`Object\`; an entity is an \`SdkEntity\`, whose \`data()\` reads its
+record. They raise on error, so wrap calls in \`try\`/\`catch\` to handle
+failures.
 
 The \`direct()\` escape hatch never raises — it returns a result
 \`Map<String, Object>\` you branch on via \`result.get("ok")\`:

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityOps , serverVariables} from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityOps , serverVariables, javaMapOf } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { javaVarName, javaPackage } from './utility_java'
+import { javaVarName, javaPackage, javaListMatch, javaLit } from './utility_java'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -44,23 +44,14 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
     'options.put("server", server);\n'
 
 
-  // A type-correct Java literal for a param — the loose object model means
-  // all values live in a Map<String, Object>.
-  const 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}"`
-  }
-
   if (authActive) {
     Content(`### 1. Create a client
 
 \`\`\`java
+import java.util.List;
+import java.util.Map;
 import ${javaPackage(model)}.core.${SDK};
+import ${javaPackage(model)}.core.SdkEntity;
 
 Map<String, Object> options = new java.util.LinkedHashMap<>();
 options.put("apikey", System.getenv("${envName(model)}_APIKEY"));
@@ -73,7 +64,10 @@ ${javaServerLines}${SDK} client = new ${SDK}(options);
     Content(`### 1. Create a client
 
 \`\`\`java
+import java.util.List;
+import java.util.Map;
 import ${javaPackage(model)}.core.${SDK};
+import ${javaPackage(model)}.core.SdkEntity;
 
 ${'' === javaServerLines
       ? `${SDK} client = new ${SDK}();`
@@ -96,13 +90,15 @@ ${'' === javaServerLines
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list(null, null)\` returns an aggregate list of records (as \`Object\`, an
-aggregate list) and raises on error.
+\`list(null, null)\` returns a list of entities, one per record (as \`Object\`),
+and raises on error; an entity's \`data()\` reads its record.
 
 \`\`\`java
 try {
-    Object ${eVar}List = client.${accessor}(null).list(null, null);
-    System.out.println(${eVar}List);
+    List<?> ${eVar}List = (List<?>) client.${accessor}(null).list(${javaListMatch(exampleEntity)}, null);
+    for (Object ${eVar}Item : ${eVar}List) {
+        System.out.println(((SdkEntity) ${eVar}Item).data());
+    }
 }
 catch (RuntimeException err) {
     System.out.println("list failed: " + err.getMessage());
@@ -139,8 +135,8 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 
 \`\`\`java
 try {
-    Object ${neVar} = client.${neAccessor}(null).load(Map.of(${neMatch.join(', ')}), null);
-    System.out.println(${neVar});
+    SdkEntity ${neVar} = (SdkEntity) client.${neAccessor}(null).load(${javaMapOf(neMatch)}, null);
+    System.out.println(${neVar}.data());
 }
 catch (RuntimeException err) {
     System.out.println("load failed: " + err.getMessage());
@@ -155,9 +151,9 @@ catch (RuntimeException err) {
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       const loadArg = 0 < loadRequired.length
-        ? `Map.of(${loadRequired.map((it: any) =>
+        ? javaMapOf(loadRequired.map((it: any) =>
           `"${it.name}", ${javaLit(it.type,
-            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')})`
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`))
         : 'null'
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
@@ -166,8 +162,8 @@ catch (RuntimeException err) {
 
 \`\`\`java
 try {
-    Object ${eVar} = client.${accessor}(null).load(${loadArg}, null);
-    System.out.println(${eVar});
+    SdkEntity ${eVar} = (SdkEntity) client.${accessor}(null).load(${loadArg}, null);
+    System.out.println(${eVar}.data());
 }
 catch (RuntimeException err) {
     System.out.println("load failed: " + err.getMessage());
@@ -204,7 +200,7 @@ catch (RuntimeException err) {
 `)
       if (opnames.includes('create')) {
         Content(`// Create — returns the ENTITY (call data() for the record)
-Object created = client.${accessor}(null).create(Map.of(${examplePairs('create').join(', ')}), null);
+Object created = client.${accessor}(null).create(${javaMapOf(examplePairs('create'))}, null);
 
 `)
       }
@@ -212,7 +208,7 @@ Object created = client.${accessor}(null).create(Map.of(${examplePairs('create')
         const updatePairs = (idF ? [`"${idF}", ${javaLit(idParamType('update'), 'example_id')}`] : [])
           .concat(examplePairs('update'))
         Content(`// Update — supply the id in the match/data
-client.${accessor}(null).update(Map.of(${updatePairs.join(', ')}), null);
+client.${accessor}(null).update(${javaMapOf(updatePairs)}, null);
 
 `)
       }
@@ -220,7 +216,7 @@ client.${accessor}(null).update(Map.of(${updatePairs.join(', ')}), null);
         const patchPairs = (idF ? [`"${idF}", ${javaLit(idParamType('patch'), 'example_id')}`] : [])
           .concat(examplePairs('patch'))
         Content(`// Patch — sends only the fields given
-client.${accessor}(null).patch(Map.of(${patchPairs.join(', ')}), null);
+client.${accessor}(null).patch(${javaMapOf(patchPairs)}, null);
 
 `)
       }
@@ -233,7 +229,7 @@ client.${accessor}(null).patch(Map.of(${patchPairs.join(', ')}), null);
             ? `"${it.name}", ${javaLit(idParamType('remove'), 'example_id')}`
             : `"${it.name}", ${javaLit(it.type, 'example_' + it.name)}`)
         Content(`// Remove
-client.${accessor}(null).remove(${removePairs.length ? `Map.of(${removePairs.join(', ')})` : 'null'}, null);
+client.${accessor}(null).remove(${removePairs.length ? javaMapOf(removePairs) : 'null'}, null);
 `)
       }
       Content(`\`\`\`

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote, javaMap, javaMapOf } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -7,53 +7,41 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { 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 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}"`
-}
-
-
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(reqmatch, ctrl) -> Object',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data()` reads, and raises on error.',
   },
   list: {
     sig: 'list(reqmatch, ctrl) -> Object',
-    returns: 'an aggregate list of entities',
-    desc: 'List entities matching the given criteria. The match is optional — call `list(null, null)` to list all records. Returns an aggregate list and raises on error.',
+    returns: 'a list of entities, one per record',
+    desc: 'List entities matching the given criteria. The match is optional — call `list(null, null)` to list all records. Returns a list of entities, one per record, and raises on error.',
   },
   create: {
     sig: 'create(reqdata, ctrl) -> Object',
-    returns: 'the created entity data',
-    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
+    returns: 'the created entity',
+    desc: 'Create a new entity with the given data. Returns the created entity and raises on error.',
   },
   update: {
     sig: 'update(reqdata, ctrl) -> Object',
-    returns: 'the updated entity data',
-    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and raises on error.',
+    returns: 'the updated entity',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and raises on error.',
   },
   patch: {
     sig: 'patch(reqdata, ctrl) -> Object',
-    returns: 'the patched entity data',
-    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity data and raises on error.',
+    returns: 'the patched entity',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity and raises on error.',
   },
   remove: {
     sig: 'remove(reqmatch, ctrl) -> Object',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Raises on error.',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and raises on error.',
   },
 }
 
@@ -273,9 +261,9 @@ ${info.desc}
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
             const arg = 0 < matchItems.length
-              ? `Map.of(${matchItems.map((it: any) =>
+              ? javaMapOf(matchItems.map((it: any) =>
                 `"${it.name}", ${javaLit(it.type,
-                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')})`
+                  it.name === idF ? ent.name + '_id' : it.name)}`))
               : 'null'
             Content(`\`\`\`java
 Object result = client.${accessor}(null).${opname}(${arg}, null);
@@ -285,8 +273,10 @@ Object result = client.${accessor}(null).${opname}(${arg}, null);
           }
           else if ('list' === opname) {
             Content(`\`\`\`java
-Object results = client.${accessor}(null).list(null, null);
-System.out.println(results);
+List<?> results = (List<?>) client.${accessor}(null).list(${javaListMatch(ent)}, null);
+for (Object item : results) {
+    System.out.println(((SdkEntity) item).data());
+}
 \`\`\`
 
 `)
@@ -294,12 +284,13 @@ System.out.println(results);
           else if ('create' === opname) {
             const createItems = opRequestShape(ent, 'create').items
               .filter((it: any) => !it.optional)
+            const createMap = javaMap(createItems.length)
             Content(`\`\`\`java
-Object result = client.${accessor}(null).create(Map.of(
+Object result = 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);
@@ -312,13 +303,14 @@ Object result = client.${accessor}(null).create(Map.of(
               .filter((it: any) => !it.optional || it.name === idF)
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const updateMap = javaMap(updateItems.length)
             const updateLines = updateItems.map((it: any, i: number) => {
               const comma = i < updateItems.length - 1 ? ',' : ''
-              return `    "${it.name}", ${javaLit(it.type,
-                it.name === idF ? ent.name + '_id' : it.name)}${comma}\n`
+              return `    ${updateMap.pair(`"${it.name}", ${javaLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)}`)}${comma}\n`
             }).join('')
             Content(`\`\`\`java
-Object result = client.${accessor}(null).${opname}(Map.of(
+Object result = client.${accessor}(null).${opname}(${updateMap.open}
 ${updateLines}), null);
 \`\`\`
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape , serverVariables} from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape , serverVariables, javaMapOf } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,21 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { javaVarName, javaPackage } from './utility_java'
-
-
-// A type-correct Java literal for a param: numeric/boolean/array/object params
-// render a typed literal; strings render the quoted placeholder. The SDK's
-// loose object model means all values live in Map<String, Object>.
-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}"`
-}
+import { javaVarName, javaPackage, javaListMatch, javaLit } from './utility_java'
 
 
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
@@ -47,8 +33,17 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
     'options.put("server", server);\n'
 
 
+  const shown = null == exampleEntity ? [] :
+    ['list', 'load'].filter((op: string) => Object.keys(exampleEntity.op || {}).includes(op))
+  const imports = [
+    ...(shown.includes('list') ? ['java.util.List'] : []),
+    ...(authActive || '' !== javaServerLines || shown.includes('load') ? ['java.util.Map'] : []),
+    `${javaPackage(model)}.core.${SDK}`,
+    ...(0 < shown.length ? [`${javaPackage(model)}.core.SdkEntity`] : []),
+  ]
+
   Content(`\`\`\`java
-import ${javaPackage(model)}.core.${SDK};
+${imports.map((i: string) => 'import ' + i + ';').join('\n')}
 
 `)
 
@@ -75,9 +70,11 @@ ${javaServerLines}${SDK} client = new ${SDK}(options);
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eNameLower}s (returns Object, an aggregate list; raises on error)
-Object ${eVar}List = client.${accessor}(null).list(null, null);
-System.out.println(${eVar}List);
+      Content(`// List all ${eNameLower}s (a list of entities, one per record; raises on error)
+List<?> ${eVar}List = (List<?>) client.${accessor}(null).list(${javaListMatch(exampleEntity)}, null);
+for (Object ${eVar}Item : ${eVar}List) {
+    System.out.println(((SdkEntity) ${eVar}Item).data());
+}
 `)
     }
 
@@ -87,14 +84,14 @@ System.out.println(${eVar}List);
         .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 ? 'example_id' : 'example_' + it.name)}`).join(', ')})`
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`))
         : 'null'
       Content(`
-// Load a specific ${eNameLower} (returns the record, raises on error)
-Object ${eVar} = client.${accessor}(null).load(${loadArg}, null);
-System.out.println(${eVar});
+// Load a specific ${eNameLower} (returns the entity, raises on error)
+SdkEntity ${eVar} = (SdkEntity) client.${accessor}(null).load(${loadArg}, null);
+System.out.println(${eVar}.data());
 `)
     }
   }

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

@@ -1,24 +1,12 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems, javaMapOf } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { 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 ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
@@ -40,29 +28,35 @@ ${SDK} 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
-        ? `Map.of(${items.map((it: any) =>
-          `"${it.name}", ${it.name === idF ? '"test01"' : javaLit(it.type)}`).join(', ')})`
+        ? javaMapOf(items.map((it: any) =>
+          `${JSON.stringify(it.name)}, ${isMatchOp && it.name === idF ? '"test01"' : javaLit(it.type)}`))
         : 'null'
     } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
       const required = items.filter((it: any) => !it.optional)
       const chosen = required.length ? required : items.slice(0, 3)
-      arg = `Map.of(${chosen.map((it: any) =>
-        `"${it.name}", ${javaLit(it.type)}`).join(', ')})`
+      arg = javaMapOf(chosen.map((it: any) =>
+        `${JSON.stringify(it.name)}, ${javaLit(it.type)}`))
     }
-    const eVar = javaVarName(exampleEntity.name) + ('list' === primaryOp ? 'List' : '')
+    const eVar = javaVarName(exampleEntity.name)
     const accessor = javaVarName(exampleEntity.name)
-    Content(`Object ${eVar} = client.${accessor}(null).${primaryOp}(${arg}, null);
-System.out.println(${eVar});
+    Content('list' === primaryOp
+      ? `List<?> ${eVar}List = (List<?>) client.${accessor}(null).list(${arg}, null);
+for (Object ${eVar}Item : ${eVar}List) {
+    System.out.println(((SdkEntity) ${eVar}Item).data());
+}
+`
+      : `SdkEntity ${eVar} = (SdkEntity) client.${accessor}(null).${primaryOp}(${arg}, null);
+System.out.println(${eVar}.data());
 `)
   }
 

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

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

package/project/.sdk/src/cmp/js/EntityOperation_js.ts

@@ -1,7 +1,8 @@
 
 import {
   cmp, camelify,
-  Content, Fragment
+  Content, Fragment,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 
@@ -32,6 +33,7 @@ const EntityOperation = cmp(function Operation(props: any) {
       SdkName: model.const.Name,
       EntityName: entity.Name,
       entityname: entity.name,
+      EntyClass: entityClassName(entity, entityCollection(model)),
       "['POINTS']": formatJson(entop.points, { margin: 6 }).trim(),
       '#Feature-Hook': ({ name, indent }: any) =>
         Content({ indent }, `

package/project/.sdk/src/cmp/js/ReadmeEntity_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral, opNeedsAction } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey, opNeedsAction, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -9,12 +9,6 @@ import {
 import { exampleValue } from './utility_js'
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const OP_DESC: Record<string, { method: string, desc: string }> = {
   load:   { method: 'load(match)',   desc: 'Load a single entity by match criteria.' },
   list:   { method: 'list(match)',   desc: 'List entities matching the criteria.' },
@@ -129,7 +123,7 @@ const ${eVar} = await client.${entity.Name}().load(${loadArg})
       Content(`#### Example: List
 
 \`\`\`ts
-const ${eVar}s = await client.${entity.Name}().list(${listMatchArg(entity)})
+const ${eVar}s = await client.${entity.Name}().list(${listMatchArg('js', entity)})
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/js/ReadmeHowto_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField, entityDataIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, entityDataIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, jsKey, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -30,10 +30,9 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
 
   const primaryArg = (idPlaceholder: string): string => {
     if (!exampleEntity || !primaryOp) return ''
-    if ('list' === primaryOp) return ''
-    if (isMatchOp) {
-      const items = opRequestShape(exampleEntity, primaryOp).items
-        .filter((it: any) => !it.optional || it.name === idF)
+    if (isMatchOp || 'list' === primaryOp) {
+      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))
       if (0 === items.length) return ''
       const pairs = items.map((it: any) =>
@@ -58,11 +57,14 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // The op-driven example lines, shown only when the SDK has an entity op.
   // A direct()-only SDK (no ops anywhere) shows a direct() test call instead
   // and omits the stateful section (there is no op to retain state across).
-  const testModeExample = primaryOp
+  const testModeExample = 'list' === primaryOp
+    ? `const ${eVar}s = await client.${eName}().list(${testCallArg})
+// ${eVar}s is an array of ${eName} entities, one per mock record
+console.log(${eVar}s.map((${eVar}) => ${eVar}.data()))`
+    : primaryOp
     ? `const ${eVar} = await client.${eName}().${primaryOp}(${testCallArg})
-// ${eVar} is the entity, populated with mock response data
-// — call ${eVar}.data() for the record itself
-console.log(${eVar})`
+// ${eVar} is the ${eName} entity; .data() reads its mock record
+console.log(${eVar}.data())`
     : `const result = await client.direct({ path: '/api/resource', method: 'GET' })
 console.log(result)`
   const stateSection = primaryOp

package/project/.sdk/src/cmp/js/ReadmeModel_js.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` | `load(reqmatch?, ctrl?): Promise<Entity>` | Load a single entity by match criteria. |',
-    list: '| `list` | `list(reqmatch?, ctrl?): Promise<Entity[]>` | List entities matching the criteria. |',
-    create: '| `create` | `create(reqdata?, ctrl?): Promise<Entity>` | Create a new entity. |',
-    update: '| `update` | `update(reqdata?, ctrl?): Promise<Entity>` | Update an existing entity. |',
-    patch: '| `patch` | `patch(reqdata?, ctrl?): Promise<Entity>` | Change part of an existing entity. |',
-    remove: '| `remove` | `remove(reqmatch?, ctrl?): Promise<void>` | Remove an entity. |',
+    load: '| `load` | `load(reqmatch?, ctrl?): Promise<Entity>` | Load a single entity by match criteria, and return it. |',
+    list: '| `list` | `list(reqmatch?, ctrl?): Promise<Entity[]>` | List entities matching the criteria, one per record. |',
+    create: '| `create` | `create(reqdata?, ctrl?): Promise<Entity>` | Create a new entity, and return it. |',
+    update: '| `update` | `update(reqdata?, ctrl?): Promise<Entity>` | Update an existing entity, and return it. |',
+    patch: '| `patch` | `patch(reqdata?, ctrl?): Promise<Entity>` | Change part of an existing entity, and return it. |',
+    remove: '| `remove` | `remove(reqmatch?, ctrl?): Promise<Entity>` | 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')
@@ -47,7 +47,7 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     retBullets.push('- `list` resolves to an **array** of entity objects (iterate it directly;\n  there is no `.data` and no `.ok`).')
   }
   if (opUnion.has('remove')) {
-    retBullets.push('- `remove` resolves to `undefined`.')
+    retBullets.push('- `remove` resolves to the entity, marked as deleted.')
   }
   const returnBullets = retBullets.join('\n')
 
@@ -112,8 +112,8 @@ ${opRows}
 
 #### Return values
 
-Entity operations resolve to the entity data directly — there is no
-result envelope:
+Entity operations resolve to the entity itself — there is no result
+envelope, and an entity's \`data()\` reads its record:
 
 ${returnBullets}