@voxgig/sdkgen 4.34.1 → 4.34.2

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

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { ocamlVarName } from './utility_ocaml'
+import { ocamlVarName, ocamlListMatch } from './utility_ocaml'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -37,6 +37,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 \`\`\`ocaml
 open Voxgig_struct
 open Sdk_helpers
+open Sdk_types
 
 let client = ${ctor}
 \`\`\`
@@ -56,6 +57,7 @@ let client = ${ctor}
     // A type-correct OCaml `value` literal for a param.
     const 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 ())'
@@ -71,7 +73,7 @@ record with \`e_data_get\`.
 
 \`\`\`ocaml
 (try
-   let ${fn}s = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval in
+   let ${fn}s = (Sdk_client.${fn} client Noval).e_list ${ocamlListMatch(exampleEntity)} Noval in
    List.iter (fun e -> print_endline (stringify (e.e_data_get ()))) ${fn}s
  with Sdk_error.E err -> Printf.eprintf "list failed: %s\\n" (Sdk_error.message err))
 \`\`\`
@@ -158,7 +160,7 @@ record.
       return it && it.type
     }
     const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
-      ? `(getp created "${dataIdF}")`
+      ? `(getp (created.e_data_get ()) "${dataIdF}")`
       : ocamlLit(idParamType(opname), 'example_id')
 
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('patch') ||

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

@@ -7,12 +7,13 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { ocamlVarName } from './utility_ocaml'
+import { ocamlVarName, ocamlListMatch } from './utility_ocaml'
 
 
 // A type-correct OCaml `value` literal. 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 ())'
@@ -39,32 +40,32 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
   load: {
     sig: 'e_load reqmatch ctrl : entity_obj',
     returns: 'the entity',
-    desc: 'Load a single entity matching the given criteria. Resolves to the ENTITY (read the record with `e_data_get`) and raises on error.',
+    desc: 'Load a single entity matching the given criteria. Resolves to the entity, whose record `e_data_get` reads, and raises on error.',
   },
   list: {
     sig: 'e_list reqmatch ctrl : entity_obj list',
     returns: 'one entity per record',
-    desc: 'List entities matching the given criteria. The match is optional \u2014 pass `(empty_map ())` to list all records. Resolves to one ENTITY per record and raises on error.',
+    desc: 'List entities matching the given criteria. The match is optional \u2014 pass `(empty_map ())` to list all records. Resolves to one entity per record and raises on error.',
   },
   create: {
     sig: 'e_create reqdata ctrl : entity_obj',
     returns: 'the created entity',
-    desc: 'Create a new entity with the given data. Resolves to the ENTITY (read the record with `e_data_get`) and raises on error.',
+    desc: 'Create a new entity with the given data. Resolves to the created entity and raises on error.',
   },
   update: {
     sig: 'e_update reqdata ctrl : entity_obj',
     returns: 'the updated entity',
-    desc: 'Update an existing entity. The data must include the entity `id`. Resolves to the ENTITY (read the record with `e_data_get`) and raises on error.',
+    desc: 'Update an existing entity. The data must include the entity `id`. Resolves to the updated entity and raises on error.',
   },
   patch: {
     sig: 'e_patch reqdata ctrl : entity_obj',
     returns: 'the patched entity',
-    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Resolves to the ENTITY (read the record with `e_data_get`) and raises on error.',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Resolves to the patched entity and raises on error.',
   },
   remove: {
     sig: 'e_remove reqmatch ctrl : entity_obj',
     returns: 'the removed entity',
-    desc: 'Remove the entity matching the given criteria. Resolves to the ENTITY, marked deleted (`e_deleted`); it keeps the data it held. Raises on error.',
+    desc: 'Remove the entity matching the given criteria. Resolves to the entity, marked as deleted (`e_deleted`); it keeps the data it held. Raises on error.',
   },
 }
 
@@ -95,6 +96,7 @@ Complete API reference for the ${model.Name} ${target.title} SDK.
     Content(`\`\`\`ocaml
 open Voxgig_struct
 open Sdk_helpers
+open Sdk_types
 
 let client = Sdk_client.make options
 \`\`\`
@@ -291,7 +293,7 @@ let result_data = result.e_data_get ()
           else if ('list' === opname) {
             Content(`\`\`\`ocaml
 (* One ENTITY per record; the record is reached with e_data_get. *)
-let results = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval in
+let results = (Sdk_client.${fn} client Noval).e_list ${ocamlListMatch(ent)} Noval in
 List.iter (fun e -> print_endline (stringify (e.e_data_get ()))) results
 \`\`\`
 

package/project/.sdk/src/cmp/ocaml/ReadmeTopQuick_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 param: numeric/boolean/array/
 // object params render a typed literal; 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 ())'
@@ -36,6 +37,7 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   Content(`\`\`\`ocaml
 open Voxgig_struct
 open Sdk_helpers
+open Sdk_types
 
 let () =
   let client = ${ctor} in
@@ -50,7 +52,7 @@ let () =
 
     if (opnames.includes('list')) {
       Content(`  (* List all ${fn} records (one ENTITY per record; raises on error) *)
-  let ${fn}s = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval in
+  let ${fn}s = (Sdk_client.${fn} client Noval).e_list ${ocamlListMatch(exampleEntity)} Noval in
   List.iter (fun e -> print_endline (stringify (e.e_data_get ()))) ${fn}s;
 `)
     }

package/project/.sdk/src/cmp/ocaml/ReadmeTopTest_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 ())'
@@ -41,7 +42,7 @@ let () =
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = 'Noval'
     if ('list' === primaryOp) {
-      arg = '(empty_map ())'
+      arg = ocamlListMatch(exampleEntity)
     } else if (isMatchOp) {
       // Every REQUIRED match key (id first).
       const items = opRequestShape(exampleEntity, primaryOp).items

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

@@ -4,7 +4,7 @@ import {
   walk,
 } from '@voxgig/struct'
 
-import { sdkName } from '@voxgig/sdkgen'
+import { sdkName, canonScalarKey, requiredItems } from '@voxgig/sdkgen'
 
 
 // OCaml keywords that are illegal as a lowercase identifier. sdkgen's shared
@@ -151,10 +151,22 @@ function clean(o: any, dropDefaults?: boolean): any {
 }
 
 
+// A list's required route and query parameters, as the match it is called with.
+function ocamlListMatch(entity: any): string {
+  const lit = (type: any): string =>
+    (({ NULL: 'Null', INTEGER: '(Num 1.)', NUMBER: '(Num 1.)', BOOLEAN: '(Bool true)', ARRAY: '(empty_list ())', OBJECT: '(empty_map ())' }) as any)[canonScalarKey(type)] ?? '(Str "example")'
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? `(jo [${items.map((it: any) => `("${ocamlString(it.name)}", ${lit(it.type)})`).join('; ')}])`
+    : '(empty_map ())'
+}
+
+
 export {
   clean,
   entityModule,
   formatOcamlValue,
+  ocamlListMatch,
   ocamlOpField,
   ocamlString,
   ocamlVarName,

package/project/.sdk/src/cmp/perl/ReadmeEntity_perl.ts

@@ -6,12 +6,15 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
+import { perlListArgs } from './utility_perl'
+
 
 // A type-correct, executable Perl literal for a field's canonical type. The
 // create example is EXECUTED by the doc test, so a placeholder must be a real
 // value. Strings render the quoted placeholder.
 function perlLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'undef'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return '1'
   if ('ARRAY' === k) return '[]'
@@ -146,7 +149,7 @@ my $${eVar} = $client->${entity.Name}->load(${loadArg});
 
 \`\`\`perl
 # an arrayref of entities, one per record; data_get reads each record
-my $${eVar}s = $client->${entity.Name}->list;
+my $${eVar}s = $client->${entity.Name}->list${perlListArgs(entity)};
 print $_->data_get->{id}, "\\n" for @$${eVar}s;
 \`\`\`
 

package/project/.sdk/src/cmp/perl/ReadmeHowto_perl.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,10 +7,13 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { perlStringLiteral } from './utility_perl'
+
 
 // A type-correct Perl literal for a field's canonical type.
 function perlLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'undef'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return '1'
   if ('ARRAY' === k) return '[]'
@@ -35,21 +38,23 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = ''
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `{ '${idF}' => 'test01' }` : ''
+  } else if (exampleEntity && 'list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length) {
+    const chosen = requiredItems(exampleEntity, 'list')
+    testArg = `{ ${chosen.map((it: any) => `${perlStringLiteral(it.name)} => ${perlLit(it.type)}`).join(', ')} }`
   } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp)) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => it.name !== idF && it.name !== 'id')
     const required = items.filter((it: any) => !it.optional)
     const chosen = required.length ? required : items.slice(0, 3)
-    testArg = `{ ${chosen.map((it: any) => `'${it.name}' => ${perlLit(it.type)}`).join(', ')} }`
+    testArg = `{ ${chosen.map((it: any) => `${perlStringLiteral(it.name)} => ${perlLit(it.type)}`).join(', ')} }`
   }
 
   // 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 dies on error;
-# call data_get for the record.
+    ? `# Entity ops return the entity, and list one per record; they die on error.
 my $${eVar} = $client->${eName}->${primaryOp}(${testArg});
-# $${eVar} contains the mock response record`
+# data_get on an entity reads its mock response record`
     : `my $result = $client->direct({ 'path' => '/api/resource', 'method' => 'GET' });
 print $result->{ok}, "\\n";`
 

package/project/.sdk/src/cmp/perl/ReadmeModel_perl.ts

@@ -19,12 +19,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) -> hashref` | Load a single entity by match criteria. Dies on error. |',
-    list: '| `list` | `($reqmatch, $ctrl) -> arrayref` | List entities matching the criteria. Resolves to one entity per record. Dies on error. |',
-    create: '| `create` | `($reqdata, $ctrl) -> hashref` | Create a new entity. Dies on error. |',
-    update: '| `update` | `($reqdata, $ctrl) -> hashref` | Update an existing entity. Dies on error. |',
-    patch: '| `patch` | `($reqdata, $ctrl) -> hashref` | Change part of an existing entity. Dies on error. |',
-    remove: '| `remove` | `($reqmatch, $ctrl) -> hashref` | Remove an entity. Dies on error. |',
+    load: '| `load` | `($reqmatch, $ctrl) -> entity` | Load a single entity by match criteria, and return it. Dies on error. |',
+    list: '| `list` | `($reqmatch, $ctrl) -> arrayref` | List entities matching the criteria, one per record. Dies on error. |',
+    create: '| `create` | `($reqdata, $ctrl) -> entity` | Create a new entity, and return it. Dies on error. |',
+    update: '| `update` | `($reqdata, $ctrl) -> entity` | Update an existing entity, and return it. Dies on error. |',
+    patch: '| `patch` | `($reqdata, $ctrl) -> entity` | Change part of an existing entity, and return it. Dies on error. |',
+    remove: '| `remove` | `($reqmatch, $ctrl) -> entity` | Remove an entity, and return it marked as deleted. Dies on error. |',
   }
   const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')

package/project/.sdk/src/cmp/perl/ReadmeQuick_perl.ts

@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { perlListArgs } from './utility_perl'
+
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
@@ -56,6 +58,7 @@ my $client = ${ctor};
     // A type-correct, executable Perl literal for a param.
     const perlLit = (type: any, placeholder: string = 'example'): string => {
       const k = canonScalarKey(type)
+      if ('NULL' === k) return 'undef'
       if ('INTEGER' === k || 'NUMBER' === k) return '1'
       if ('BOOLEAN' === k) return '1'
       if ('ARRAY' === k) return '[]'
@@ -70,7 +73,7 @@ my $client = ${ctor};
 error; \`data_get\` reads each record.
 
 \`\`\`perl
-my $${eVar}s = eval { $client->${eName}->list };
+my $${eVar}s = eval { $client->${eName}->list${perlListArgs(exampleEntity)} };
 if (my $err = $@) {
     print "list failed: $err\\n";
 }
@@ -114,7 +117,7 @@ if (my $err = $@) {
     print "load failed: $err\\n";
 }
 else {
-    print "$${neVar}->{id}\\n";
+    print $${neVar}->data_get->{id}, "\\n";
 }
 \`\`\`
 
@@ -141,7 +144,7 @@ if (my $err = $@) {
     print "load failed: $err\\n";
 }
 else {
-    print "$${eVar}->{id}\\n";
+    print $${eVar}->data_get->{id}, "\\n";
 }
 \`\`\`
 
@@ -169,7 +172,7 @@ else {
       return it && it.type
     }
     const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
-      ? `$created->{${dataIdF}}`
+      ? `$created->data_get->{${dataIdF}}`
       : perlLit(idParamType(opname), 'example_id')
 
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('patch') ||
@@ -187,7 +190,7 @@ my $created = $client->${eName}->create({ ${examplePairs('create').join(', ')} }
       if (opnames.includes('update')) {
         const updatePairs = (idF ? [`'${idF}' => ${idValueFor('update')}`] : []).concat(examplePairs('update'))
         const fromCreated = null != dataIdF && opnames.includes('create')
-        Content(`# Update${fromCreated ? " — the created record's id is a plain hash key" : ''}
+        Content(`# Update${fromCreated ? " — the created entity's record holds its id" : ''}
 $client->${eName}->update({ ${updatePairs.join(', ')} });
 
 `)

package/project/.sdk/src/cmp/perl/ReadmeRef_perl.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote, entityClassName, entityCollection } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -7,10 +7,13 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
+import { perlListArgs } from './utility_perl'
+
 
 // A type-correct, executable Perl literal for a field's canonical type.
 function perlLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'undef'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return '1'
   if ('ARRAY' === k) return '[]'
@@ -32,9 +35,9 @@ function perlType(type: any): string {
 
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
-    sig: 'load($reqmatch, $ctrl) -> hashref',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and dies on error.',
+    sig: 'load($reqmatch, $ctrl) -> EntyClass',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data_get` reads, and dies on error.',
   },
   list: {
     sig: 'list($reqmatch, $ctrl) -> arrayref',
@@ -42,24 +45,24 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
     desc: 'List entities matching the given criteria. The match is optional — call `list` with no argument to list all records. Returns an arrayref of entities, one per record (`data_get` reads each record), and dies on error.',
   },
   create: {
-    sig: 'create($reqdata, $ctrl) -> hashref',
-    returns: 'the created entity data',
-    desc: 'Create a new entity with the given data. Returns the created entity data and dies on error.',
+    sig: 'create($reqdata, $ctrl) -> EntyClass',
+    returns: 'the created entity',
+    desc: 'Create a new entity with the given data. Returns the created entity and dies on error.',
   },
   update: {
-    sig: 'update($reqdata, $ctrl) -> hashref',
-    returns: 'the updated entity data',
-    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and dies on error.',
+    sig: 'update($reqdata, $ctrl) -> EntyClass',
+    returns: 'the updated entity',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and dies on error.',
   },
   patch: {
-    sig: 'patch($reqdata, $ctrl) -> hashref',
-    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 dies on error.',
+    sig: 'patch($reqdata, $ctrl) -> EntyClass',
+    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 dies on error.',
   },
   remove: {
-    sig: 'remove($reqmatch, $ctrl) -> hashref',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Dies on error.',
+    sig: 'remove($reqmatch, $ctrl) -> EntyClass',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and dies on error.',
   },
 }
 
@@ -258,7 +261,7 @@ my $${eVar} = $client->${ent.Name};
           const info = OP_SIGNATURES[opname]
           if (!info) return
 
-          Content(`#### \`${info.sig}\`
+          Content(`#### \`${info.sig.replace('EntyClass', entityClassName(ent, entityCollection(model)))}\`
 
 ${info.desc}
 
@@ -286,7 +289,7 @@ my $result = $client->${ent.Name}->${opname}(${arg});
           }
           else if ('list' === opname) {
             Content(`\`\`\`perl
-my $results = $client->${ent.Name}->list;
+my $results = $client->${ent.Name}->list${perlListArgs(ent)};
 for my $${eVar} (@$results) {
     print $${eVar}->data_get->{id}, "\\n";
 }

package/project/.sdk/src/cmp/perl/ReadmeTopQuick_perl.ts

@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { perlListArgs } from './utility_perl'
+
 
 // A type-correct, executable Perl literal for a param: numeric/boolean/
 // array/hash params render a typed literal; strings render the quoted
@@ -14,6 +16,7 @@ import {
 // would break it).
 function perlLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'undef'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return '1'
   if ('ARRAY' === k) return '[]'
@@ -50,7 +53,7 @@ my $client = ${ctor};
 
     if (opnames.includes('list')) {
       Content(`# List all ${eName.toLowerCase()}s (an arrayref of entities, one per record; dies on error)
-my $${eVar}s = $client->${eName}->list;
+my $${eVar}s = $client->${eName}->list${perlListArgs(exampleEntity)};
 for my $${eVar} (@$${eVar}s) {
     print $${eVar}->data_get->{id}, "\\n";
 }
@@ -71,9 +74,9 @@ for my $${eVar} (@$${eVar}s) {
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')} }`
         : ''
       Content(`
-# Load a specific ${eName.toLowerCase()} (returns the ENTITY; call data_get for the record; dies on error)
+# Load a specific ${eName.toLowerCase()} (returns the entity; data_get reads its record; dies on error)
 my $${eVar} = $client->${eName}->load(${loadArg});
-print "$${eVar}->{id}\\n";
+print $${eVar}->data_get->{id}, "\\n";
 `)
     }
   }

package/project/.sdk/src/cmp/perl/ReadmeTopTest_perl.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,10 +7,13 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { perlStringLiteral } from './utility_perl'
+
 
 // A type-correct Perl literal for a field's canonical type.
 function perlLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'undef'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return '1'
   if ('ARRAY' === k) return '[]'
@@ -40,34 +43,34 @@ my $client = ${model.const.Name}SDK->test(undef, undef);
     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) — the same shape that generates
       // the op's match resolution, so the block runs offline against a seeded
       // fixture.
-      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) =>
-          `'${it.name}' => ${it.name === idF ? "'test01'" : perlLit(it.type)}`).join(', ')} }`
+          `${perlStringLiteral(it.name)} => ${isMatchOp && it.name === idF ? "'test01'" : perlLit(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 = `{ ${chosen.map((it: any) => `'${it.name}' => ${perlLit(it.type)}`).join(', ')} }`
+      arg = `{ ${chosen.map((it: any) => `${perlStringLiteral(it.name)} => ${perlLit(it.type)}`).join(', ')} }`
     }
     // A list() result is an arrayref — name the variable accordingly.
     const eVar = eName.toLowerCase() + ('list' === primaryOp ? 's' : '')
     Content(`my $${eVar} = $client->${eName}->${primaryOp}(${arg});
 `)
     if ('list' === primaryOp) {
-      Content(`print scalar(@$${eVar}), " records\\n";
+      Content(`print $_->data_get->{id}, "\\n" for @$${eVar};
 `)
     } else {
-      Content(`print "$${eVar}->{id}\\n";
+      Content(`print $${eVar}->data_get->{id}, "\\n";
 `)
     }
   }

package/project/.sdk/src/cmp/perl/fragment/Entity.fragment.pm

@@ -138,7 +138,7 @@ sub match_get {
 # result). When the streaming feature is active the result carries a `stream`
 # coderef and this yields from it (honouring chunkSize / chunkDelay); else it
 # falls back to yielding the materialised items so stream() always yields.
-# Yielded records are unwrapped to bare hashrefs (matching list()).
+# An entity is yielded as its record, the hashref its data_get returns.
 #
 # $callopts parameterises the call:
 #   - ctrl:   per-call pipeline control (threaded onto the op ctx);

package/project/.sdk/src/cmp/perl/fragment/EntityCreateOp.fragment.pm

@@ -3,8 +3,8 @@
 # Create a new EntityName.
 #
 # reqdata: body data hashref (EntityNameCreateData shape). ctrl: optional
-# per-call control. Returns the created EntityName data (hashref); dies
-# with ProjectNameError on failure.
+# per-call control. Returns the created EntityName entity (data_get reads
+# its record); dies with ProjectNameError on failure.
 sub create {
   my ($self, $reqdata, $ctrl) = @_;
   my $utility = $self->{_utility};

package/project/.sdk/src/cmp/perl/fragment/EntityLoadOp.fragment.pm

@@ -5,8 +5,8 @@
 # reqmatch: match criteria hashref (id/query fields; EntityNameLoadMatch
 # shape); optional - an entity with no id-like key loads with no match
 # (undef is treated as an empty match). ctrl: optional per-call control.
-# Returns the loaded EntityName data (hashref); dies with ProjectNameError
-# on failure.
+# Returns the loaded EntityName entity (data_get reads its record); dies
+# with ProjectNameError on failure.
 sub load {
   my ($self, $reqmatch, $ctrl) = @_;
   my $utility = $self->{_utility};

package/project/.sdk/src/cmp/perl/fragment/EntityPatchOp.fragment.pm

@@ -3,8 +3,8 @@
 # Change part of an existing EntityName: only the fields given are sent.
 #
 # reqdata: body data hashref (EntityNamePatchData shape). ctrl: optional
-# per-call control. Returns the patched EntityName data (hashref); dies
-# with ProjectNameError on failure.
+# per-call control. Returns the patched EntityName entity (data_get reads
+# its record); dies with ProjectNameError on failure.
 sub patch {
   my ($self, $reqdata, $ctrl) = @_;
   my $utility = $self->{_utility};

package/project/.sdk/src/cmp/perl/fragment/EntityRemoveOp.fragment.pm

@@ -4,7 +4,7 @@
 #
 # reqmatch: match criteria hashref (id/query fields; EntityNameRemoveMatch
 # shape). ctrl: optional per-call control. Returns the removed EntityName
-# data (hashref); dies with ProjectNameError on failure.
+# entity, marked as deleted; dies with ProjectNameError on failure.
 sub remove {
   my ($self, $reqmatch, $ctrl) = @_;
   my $utility = $self->{_utility};

package/project/.sdk/src/cmp/perl/fragment/EntityUpdateOp.fragment.pm

@@ -3,8 +3,8 @@
 # Update an existing EntityName.
 #
 # reqdata: body data hashref (EntityNameUpdateData shape). ctrl: optional
-# per-call control. Returns the updated EntityName data (hashref); dies
-# with ProjectNameError on failure.
+# per-call control. Returns the updated EntityName entity (data_get reads
+# its record); dies with ProjectNameError on failure.
 sub update {
   my ($self, $reqdata, $ctrl) = @_;
   my $utility = $self->{_utility};

package/project/.sdk/src/cmp/perl/utility_perl.ts

@@ -6,7 +6,7 @@ import {
   walk,
 } from '@voxgig/struct'
 
-import { targetFeatures } from '@voxgig/sdkgen'
+import { targetFeatures, canonScalarKey, requiredItems } from '@voxgig/sdkgen'
 
 
 function projectPath(suffix?: string): string {
@@ -71,8 +71,18 @@ function perlVersionLabel(version: string): string {
   return major + '.' + Number(minor.slice(0, 3))
 }
 
+function perlListArgs(entity: any): string {
+  const lit = (type: any): string =>
+    (({ NULL: 'undef', INTEGER: '1', NUMBER: '1', BOOLEAN: '1', ARRAY: '[]', OBJECT: '{}' }) as any)[canonScalarKey(type)] ?? "'example'"
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? `({ ${items.map((it: any) => `${perlStringLiteral(it.name)} => ${lit(it.type)}`).join(', ')} })`
+    : ''
+}
+
 
 export {
+  perlListArgs,
   perlStringLiteral,
   clean,
   projectPath,