@voxgig/sdkgen 4.34.0 → 4.34.2

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

@@ -1,17 +1,20 @@
 
-import { cmp, each, Content, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonKey, canonScalarKey, entityIdField, opRequestShape, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
   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 '[]'
@@ -37,6 +40,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'list()',        desc: 'List entities, optionally matching the given 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.' },
 }
 
@@ -62,6 +66,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)
     const eVar = entity.name
@@ -116,7 +122,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       // The id key plus every REQUIRED match key (parent path params like
       // page_id) — the same shape the runtime resolves path params from, so
       // the example always works.
@@ -138,17 +144,19 @@ my $${eVar} = $client->${entity.Name}->load(${loadArg});
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`perl
-my $${eVar}s = $client->${entity.Name}->list;
+# an arrayref of entities, one per record; data_get reads each record
+my $${eVar}s = $client->${entity.Name}->list${perlListArgs(entity)};
+print $_->data_get->{id}, "\\n" for @$${eVar}s;
 \`\`\`
 
 `)
     }
 
-    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/perl/ReadmeExamplesTest_perl.ts

@@ -144,7 +144,7 @@ sub runnable {
   my ($b) = @_;
   return 1 if $b =~ /\\Q$SDK_CLASS\\E->(?:new|test)\\b/;
   return 1 if $b =~ /\\\$client\\b/;
-  return 1 if $b =~ /->(?:load|list|create|update|remove)\\b/;
+  return 1 if $b =~ /->(?:load|list|create|update|patch|remove)\\b/;
   return 0;
 }
 
@@ -155,7 +155,7 @@ sub looks_sdk {
   my ($b) = @_;
   return 1 if $b =~ /\\\$client\\b/;
   return 1 if $b =~ /\\b\\Q$SDK_CLASS\\E\\b/;
-  return 1 if $b =~ /->(?:load|list|create|update|remove)\\b/;
+  return 1 if $b =~ /->(?:load|list|create|update|patch|remove)\\b/;
   for my $name (keys %ENTITIES) {
     return 1 if $b =~ /->\\Q$name\\E\\b/;
   }

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 && ('create' === primaryOp || 'update' === primaryOp)) {
+  } 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/ReadmeInstall_perl.ts

@@ -1,11 +1,17 @@
 
 import { cmp, Content, installCommand, isPublished, repoInfo } from '@voxgig/sdkgen'
 
+import { minPerl, perlVersionLabel } from './utility_perl'
+
 
 const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
   const { target, ctx$ } = props
   const { model } = ctx$
 
+  Content(`The SDK needs perl ${perlVersionLabel(minPerl(model, target))} or later.
+
+`)
+
   if (isPublished(model, target.name)) {
     Content(`\`\`\`bash
 ${installCommand(model, target.name)}
@@ -25,9 +31,9 @@ cpanm .
   // Publish pending: not yet on CPAN. This is a pure-Perl SDK with zero
   // non-core runtime deps, so the simplest install is to add the SDK's
   // \`lib\` directory to Perl's module search path (\`@INC\`).
-  const { releasesUrl } = repoInfo(model)
-  Content(`This package is not yet published to CPAN. Install it from the GitHub
-release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})) or
+  const { hostName, tagsUrl } = repoInfo(model)
+  Content(`This package is not yet published to CPAN. Install it from the ${hostName}
+release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})) or
 from a source checkout.
 
 The SDK is pure Perl with zero non-core runtime dependencies, so no build

package/project/.sdk/src/cmp/perl/ReadmeIntro_perl.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 || ''
 
   Content(`# ${model.Name} ${target.title} SDK
@@ -36,7 +36,7 @@ following idiomatic Perl conventions.
   // 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/perl/ReadmeModel_perl.ts

@@ -19,13 +19,14 @@ 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. 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. |',
-    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', 'remove']
+  const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
   const apikeyOptionRow = isAuthActive(model)
@@ -93,9 +94,10 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the ENTITY (call data_get for the record) (a \`hashref\` for single-entity
-ops, an \`arrayref\` for \`list\`) and die on error. Wrap calls in
-\`eval { ... }\` and inspect \`$@\` to handle failures.
+Entity operations return the entity, and \`list\` an \`arrayref\` of
+entities, one per record; \`data_get\` reads an entity's record (a
+\`hashref\`). They die on error, so wrap calls in \`eval { ... }\` and
+inspect \`$@\` to handle failures.
 
 The \`direct()\` escape hatch never dies — it returns a result \`hashref\`
 you branch on via \`$result->{ok}\`:

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 '[]'
@@ -66,17 +69,17 @@ my $client = ${ctor};
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list()\` returns an \`arrayref\` of records (each a \`hashref\`) and dies on
-error — iterate it directly.
+\`list()\` returns an \`arrayref\` of entities, one per record, and dies on
+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";
 }
 else {
     for my $${eVar} (@$${eVar}s) {
-        print "$${eVar}->{id}\\n";
+        print $${eVar}->data_get->{id}, "\\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,10 +172,11 @@ 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('remove')) {
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('patch') ||
+      opnames.includes('remove')) {
       Content(`### 4. Create, update, and remove
 
 \`\`\`perl
@@ -186,9 +190,16 @@ 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(', ')} });
 
+`)
+      }
+      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')) {

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } 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,29 +35,34 @@ 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',
-    returns: 'an arrayref of entities',
-    desc: 'List entities matching the given criteria. The match is optional — call `list` with no argument to list all records. Returns an arrayref and dies on error.',
+    returns: 'an arrayref of entities, one per record',
+    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) -> 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.',
   },
 }
 
@@ -218,7 +226,7 @@ my $${eVar} = $client->${ent.Name};
         // Field operations breakdown
         const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
         if (hasFieldOps) {
-          const opcols = ['load', 'list', 'create', 'update', 'remove']
+          const opcols = ['load', 'list', 'create', 'update', 'patch', 'remove']
             .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
@@ -253,12 +261,16 @@ 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}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           if ('load' === opname || 'remove' === opname) {
             const matchItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
@@ -277,9 +289,9 @@ 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}->{id}\\n";
+    print $${eVar}->data_get->{id}, "\\n";
 }
 \`\`\`
 
@@ -300,8 +312,8 @@ my $result = $client->${ent.Name}->create({
 
 `)
           }
-          else if ('update' === opname) {
-            const updateItems = opRequestShape(ent, 'update').items
+          else if ('update' === opname || 'patch' === opname) {
+            const updateItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
@@ -309,13 +321,21 @@ my $result = $client->${ent.Name}->create({
               `    '${it.name}' => ${perlLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`perl
-my $result = $client->${ent.Name}->update({
-${updateLines}    # Fields to update
+my $result = $client->${ent.Name}->${opname}({
+${updateLines}    # ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
 });
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a byte string, a character string, sent as UTF-8, or a filehandle',
+              once: 'a filehandle',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

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 '[]'
@@ -49,10 +52,10 @@ my $client = ${ctor};
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`# List all ${eName.toLowerCase()}s (returns an arrayref; dies on error)
-my $${eVar}s = $client->${eName}->list;
+      Content(`# List all ${eName.toLowerCase()}s (an arrayref of entities, one per record; dies on error)
+my $${eVar}s = $client->${eName}->list${perlListArgs(exampleEntity)};
 for my $${eVar} (@$${eVar}s) {
-    print "$${eVar}->{id}\\n";
+    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) {
+    } 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";
 `)
     }
   }