@voxgig/sdkgen 4.34.1 → 4.34.2

package/project/.sdk/src/cmp/py/ReadmeRef_py.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral, targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, targetFeatures, opNeedsAction, bodyNote, listMatchArg, entityClassName, entityCollection } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -13,6 +13,7 @@ import {
 // test. Strings render the quoted placeholder.
 function pyLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'None'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'True'
   if ('ARRAY' === k) return '[]'
@@ -21,42 +22,36 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 }
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
-    sig: 'load(reqmatch, ctrl=None) -> dict',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+    sig: 'load(reqmatch, ctrl=None) -> EntyClass',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data_get()` reads, and raises on error.',
   },
   list: {
-    sig: 'list(reqmatch=None, ctrl=None) -> list',
-    returns: 'a list of entities',
-    desc: 'List entities matching the given criteria. The match is optional — call `list()` with no argument to list all records. Returns a list and raises on error.',
+    sig: 'list(reqmatch=None, ctrl=None) -> list[EntyClass]',
+    returns: 'a list 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 a list of entities, one per record, and raises on error.',
   },
   create: {
-    sig: 'create(reqdata, ctrl=None) -> dict',
-    returns: 'the created entity data',
-    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
+    sig: 'create(reqdata, ctrl=None) -> EntyClass',
+    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=None) -> dict',
-    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.',
+    sig: 'update(reqdata, ctrl=None) -> EntyClass',
+    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=None) -> dict',
-    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.',
+    sig: 'patch(reqdata, ctrl=None) -> 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 raises on error.',
   },
   remove: {
-    sig: 'remove(reqmatch, ctrl=None) -> dict',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Raises on error.',
+    sig: 'remove(reqmatch, ctrl=None) -> EntyClass',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and raises on error.',
   },
 }
 
@@ -255,7 +250,7 @@ ${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}
 
@@ -288,9 +283,9 @@ result = client.${ent.Name}().${opname}(${arg})
           }
           else if ('list' === opname) {
             Content(`\`\`\`python
-results = client.${ent.Name}().list(${listMatchArg(ent)})
+results = client.${ent.Name}().list(${listMatchArg('py', ent)})
 for ${eVar} in results:
-    print(${eVar})
+    print(${eVar}.data_get())
 \`\`\`
 
 `)
@@ -417,8 +412,6 @@ client = ${model.const.Name}SDK({
 })
 
 
-
-
 export {
   ReadmeRef
 }

package/project/.sdk/src/cmp/py/ReadmeTopQuick_py.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral , serverVariables} from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, serverVariables, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,6 +14,7 @@ import {
 // would break it).
 function pyLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'None'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'True'
   if ('ARRAY' === k) return '[]'
@@ -22,12 +23,6 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 }
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -68,10 +63,10 @@ client = ${ctor}
     let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`# List all ${eName.toLowerCase()}s (returns a list, raises on error)
-${eVar}s = client.${eName}().list(${listMatchArg(exampleEntity)})
+      Content(`# List all ${eName.toLowerCase()}s (a list of entities, one per record; raises on error)
+${eVar}s = client.${eName}().list(${listMatchArg('py', exampleEntity)})
 for ${eVar} in ${eVar}s:
-    print(${eVar})
+    print(${eVar}.data_get())
 `)
       hasCall = true
     }
@@ -87,9 +82,9 @@ for ${eVar} in ${eVar}s:
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')}}`
         : ''
       Content(`
-# Load a specific ${eName.toLowerCase()} (returns the record, raises on error)
+# Load a specific ${eName.toLowerCase()} (returns the entity, raises on error)
 ${eVar} = client.${eName}().load(${loadArg})
-print(${eVar})
+print(${eVar}.data_get())
 `)
       hasCall = true
     }

package/project/.sdk/src/cmp/py/ReadmeTopTest_py.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, requiredItems, litPair } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,6 +11,7 @@ import {
 // A type-correct Python literal for a field's canonical type.
 function pyLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'None'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'True'
   if ('ARRAY' === k) return '[]'
@@ -37,30 +38,30 @@ client = ${model.const.Name}SDK.test()
     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 type, so the block also satisfies the mypy doc gate.
-      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"' : pyLit(it.type)}`).join(', ')}}`
+          litPair('py', it.name, isMatchOp && it.name === idF ? '"test01"' : pyLit(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}": ${pyLit(it.type)}`).join(', ')}}`
+      arg = `{${chosen.map((it: any) => litPair('py', it.name, pyLit(it.type))).join(', ')}}`
     }
     // A list() result is a list — name the variable accordingly (the root
     // README doc gate concatenates blocks, so reusing the singular name for
     // a different type is a mypy assignment error).
     const eVar = exampleVarName(eName.toLowerCase(), 'py') + ('list' === primaryOp ? 's' : '')
     Content(`${eVar} = client.${eName}().${primaryOp}(${arg})
-print(${eVar})
+print(${'list' === primaryOp ? '[item.data_get() for item in ' + eVar + ']' : eVar + '.data_get()'})
 `)
   }
 

package/project/.sdk/src/cmp/py/fragment/EntityCreateOp.fragment.py

@@ -5,7 +5,7 @@ entity_create_op = None
 
 # EJECT-START
 
-    def create(self, reqdata: EntityNameCreateData, ctrl=None) -> EntityName:
+    def create(self, reqdata: EntityNameCreateData, ctrl=None) -> EntyClass:
         utility = self._utility
         ctx = utility.make_context({
             "opname": "create",

package/project/.sdk/src/cmp/py/fragment/EntityListOp.fragment.py

@@ -2,7 +2,7 @@ entity_list_op = None
 
 # EJECT-START
 
-    def list(self, reqmatch=None, ctrl=None) -> list[EntityName]:
+    def list(self, reqmatch=None, ctrl=None) -> list[EntyClass]:
         utility = self._utility
         # reqmatch is optional: an omitted match lists all records. Treat None
         # as an empty match so client.EntityName().list() works with no args.

package/project/.sdk/src/cmp/py/fragment/EntityLoadOp.fragment.py

@@ -5,7 +5,7 @@ entity_load_op = None
 
 # EJECT-START
 
-    def load(self, reqmatch=None, ctrl=None) -> EntityName:
+    def load(self, reqmatch=None, ctrl=None) -> EntyClass:
         utility = self._utility
         # reqmatch is optional: an entity with no id-like key loads with no
         # match. Treat None as an empty match so client.EntityName().load()

package/project/.sdk/src/cmp/py/fragment/EntityPatchOp.fragment.py

@@ -5,7 +5,7 @@ entity_patch_op = None
 
 # EJECT-START
 
-    def patch(self, reqdata: EntityNamePatchData, ctrl=None) -> EntityName:
+    def patch(self, reqdata: EntityNamePatchData, ctrl=None) -> EntyClass:
         utility = self._utility
         ctx = utility.make_context({
             "opname": "patch",

package/project/.sdk/src/cmp/py/fragment/EntityRemoveOp.fragment.py

@@ -5,7 +5,7 @@ entity_remove_op = None
 
 # EJECT-START
 
-    def remove(self, reqmatch=None, ctrl=None) -> EntityName:
+    def remove(self, reqmatch=None, ctrl=None) -> EntyClass:
         utility = self._utility
         # reqmatch is optional: an entity with no id-like key removes with no
         # match. Treat None as an empty match so client.EntityName().remove()

package/project/.sdk/src/cmp/py/fragment/EntityUpdateOp.fragment.py

@@ -5,7 +5,7 @@ entity_update_op = None
 
 # EJECT-START
 
-    def update(self, reqdata: EntityNameUpdateData, ctrl=None) -> EntityName:
+    def update(self, reqdata: EntityNameUpdateData, ctrl=None) -> EntyClass:
         utility = self._utility
         ctx = utility.make_context({
             "opname": "update",

package/project/.sdk/src/cmp/rb/EntityOperation_rb.ts

@@ -1,7 +1,8 @@
 
 import {
   cmp, camelify,
-  Content, Fragment
+  Content, Fragment,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 
@@ -29,6 +30,7 @@ const EntityOperation = cmp(function Operation(props: any) {
       ProjectName: model.const.Name,
       EntityName: entity.Name,
       entityname: entity.name,
+      EntyClass: entityClassName(entity, entityCollection(model)),
       '#Feature-Hook': ({ name, indent }: any) =>
         Content({ indent }, `
 u.feature_hook.call(ctx, "${name}")

package/project/.sdk/src/cmp/rb/EntityTypes_rb.ts

@@ -19,7 +19,8 @@ const LANG = 'rb'
 
 // A Ruby symbol literal for a member name: bare for identifiers, quoted otherwise.
 function symName(name: string): string {
-  return /^[A-Za-z_][A-Za-z0-9_]*[?!=]?$/.test(name) ? ':' + name : ':"' + name + '"'
+  return /^[A-Za-z_][A-Za-z0-9_]*[?!=]?$/.test(name) ? ':' + name
+    : ':' + JSON.stringify(name).replace(/#(?=[{$@])/g, '\\#')
 }
 
 

package/project/.sdk/src/cmp/rb/ReadmeEntity_rb.ts

@@ -6,9 +6,12 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
+import { rbListArgs } from './utility_rb'
+
 
 function rbLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'nil'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '[]'
@@ -134,7 +137,7 @@ ${eVar} = client.${entity.Name}.load(${loadArg})
 
 \`\`\`ruby
 # list returns an Array of ${entity.Name} entities, one per record (raises on error).
-${eVar}s = client.${entity.Name}.list
+${eVar}s = client.${entity.Name}.list${rbListArgs(entity)}
 ${eVar}s.each { |item| puts item.data_get }
 \`\`\`
 

package/project/.sdk/src/cmp/rb/ReadmeExamplesTest_rb.ts

@@ -80,8 +80,9 @@ ${entityLines}
   CLIENT = /(?<![\\w\\-.\\/"'])client(?![\\w\\-\\/"'])/
 
   # Ruby-level errors that indicate a real bug in a documented example (as
-  # opposed to an expected not-found / domain error, which is tolerated).
-  FATAL = /NoMethodError|NameError|ArgumentError|undefined method|undefined local variable|uninitialized constant|wrong number of arguments/
+  # opposed to an expected not-found / domain error, which is tolerated), and
+  # the ScriptError classes an SDK that does not load raises.
+  FATAL = /NoMethodError|NameError|ArgumentError|SyntaxError|LoadError|NotImplementedError|undefined method|undefined local variable|uninitialized constant|wrong number of arguments/
 
   # Extract every fenced ruby block from all three docs, each tagged with its
   # source doc label and its index within that doc.

package/project/.sdk/src/cmp/rb/ReadmeHowto_rb.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, seededList, litPair } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,6 +10,7 @@ import {
 
 function rbLit(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 '[]'
@@ -26,40 +27,49 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
   // Sanitise the local variable name — an entity whose lowercased name is a
   // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code. The
-  // fixture KEY (`"${eName.toLowerCase()}"`) stays raw — it must match the
-  // entity's registered name for the mock lookup to resolve.
+  // fixture key is the model name, which the mock looks the entity up by.
   const eVar = exampleVarName(eName.toLowerCase(), 'rb')
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  const listed = exampleEntity && 'list' === primaryOp
+    ? seededList('rb', exampleEntity, idF, 'test01') : null
   const seedSentence = idF
     ? '. Seed fixture\ndata via the `entity` option so offline calls resolve without a live server'
     : ''
+  const record = idF ? (listed ? listed.record : [litPair('rb', idF, '"test01"')]).join(', ') : ''
   const testCtor = idF
-    ? `${model.const.Name}SDK.test({\n  "entity" => { "${eName.toLowerCase()}" => { "test01" => { "${idF}" => "test01" } } },\n})`
+    ? `${model.const.Name}SDK.test({\n  "entity" => { "${exampleEntity.name}" => { "test01" => { ${record} } } },\n})`
     : `${model.const.Name}SDK.test`
   let testCallArg = ''
-  if (exampleEntity && isMatchOp) {
+  if (listed) {
+    testCallArg = 0 < listed.call.length ? `{ ${listed.call.join(', ')} }` : ''
+  } else if (exampleEntity && isMatchOp) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => !it.optional || it.name === idF)
       .sort((a: any, b: any) => (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
     testCallArg = 0 < items.length
-      ? `{ ${items.map((it: any) => `"${it.name}" => ${it.name === idF ? '"test01"' : rbLit(it.type)}`).join(', ')} }`
+      ? `{ ${items.map((it: any) => litPair('rb', it.name, it.name === idF ? '"test01"' : rbLit(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)
-    testCallArg = `{ ${chosen.map((it: any) => `"${it.name}" => ${rbLit(it.type)}`).join(', ')} }`
+    testCallArg = `{ ${chosen.map((it: any) => litPair('rb', it.name, rbLit(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
+  const testModeExample = 'list' === primaryOp
+    ? `# list returns an Array of ${eName} entities, one per mock record (raises on
+# error); data_get reads each record.
+${eVar}s = client.${eName}.list(${testCallArg})
+${eVar}s.each { |item| puts item.data_get }`
+    : primaryOp
     ? `# Entity ops return the ENTITY (raises on error);
-# call data_get for the mock record.
+# data_get reads its mock record.
 ${eVar} = client.${eName}.${primaryOp}(${testCallArg})
-puts ${eVar}`
+puts ${eVar}.data_get`
     : `result = client.direct({ "path" => "/api/resource", "method" => "GET" })
 puts result`
 

package/project/.sdk/src/cmp/rb/ReadmeModel_rb.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` | `(reqmatch, ctrl) -> any` | Load a single entity by match criteria. Raises on error. |',
-    list: '| `list` | `(reqmatch = nil, ctrl) -> Array` | List entities matching the criteria (call with no argument to list all). Resolves to one entity per record. Raises on error. |',
-    create: '| `create` | `(reqdata, ctrl) -> any` | Create a new entity. Raises on error. |',
-    update: '| `update` | `(reqdata, ctrl) -> any` | Update an existing entity. Raises on error. |',
-    patch: '| `patch` | `(reqdata, ctrl) -> any` | Change part of an existing entity. Raises on error. |',
-    remove: '| `remove` | `(reqmatch, ctrl) -> any` | Remove an entity. Raises on error. |',
+    load: '| `load` | `(reqmatch, ctrl) -> any` | Load a single entity by match criteria, and return it. Raises on error. |',
+    list: '| `list` | `(reqmatch = nil, ctrl) -> Array` | List entities matching the criteria (call with no argument to list all), one per record. Raises on error. |',
+    create: '| `create` | `(reqdata, ctrl) -> any` | Create a new entity, and return it. Raises on error. |',
+    update: '| `update` | `(reqdata, ctrl) -> any` | Update an existing entity, and return it. Raises on error. |',
+    patch: '| `patch` | `(reqdata, ctrl) -> any` | Change part of an existing entity, and return it. Raises on error. |',
+    remove: '| `remove` | `(reqmatch, ctrl) -> any` | 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 result data directly. On failure they
-raise a \`${model.const.Name}Error\` (a \`StandardError\` subclass), so wrap
-calls in \`begin\`/\`rescue\` where you need to handle errors.
+Entity operations return the entity, and \`list\` an \`Array\` of entities, one
+per record; an entity's \`data_get\` reads its record. On failure they raise a
+\`${model.const.Name}Error\` (a \`StandardError\` subclass), so wrap calls in
+\`begin\`/\`rescue\` where you need to handle errors.
 
 The \`direct\` escape hatch is the exception: it never raises and instead
 returns a result \`Hash\` with these keys:

package/project/.sdk/src/cmp/rb/ReadmeQuick_rb.ts

@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { rbListArgs } from './utility_rb'
+
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
@@ -56,6 +58,7 @@ client = ${ctor}
     // placeholder would not parse).
     const rbLit = (type: any, placeholder: string = 'example'): string => {
       const k = canonScalarKey(type)
+      if ('NULL' === k) return 'nil'
       if ('INTEGER' === k || 'NUMBER' === k) return '1'
       if ('BOOLEAN' === k) return 'true'
       if ('ARRAY' === k) return '[]'
@@ -81,7 +84,7 @@ client = ${ctor}
 \`\`\`ruby
 begin
   # list returns an Array of ${eName} entities, one per record; data_get reads the record.
-  ${eVar}s = client.${eName}.list
+  ${eVar}s = client.${eName}.list${rbListArgs(exampleEntity)}
   ${eVar}s.each do |item|
     record = item.data_get
     puts "${itemPrint}"
@@ -122,7 +125,7 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 begin
   # load returns the ENTITY — call data_get for the ${neName} record (raises on error).
   ${neVar} = client.${neName}.load({ ${neMatch.join(', ')} })
-  puts ${neVar}
+  puts ${neVar}.data_get
 rescue => err
   warn "load failed: #{err}"
 end
@@ -147,7 +150,7 @@ end
 begin
   # load returns the ENTITY — call data_get for the ${eName} record (raises on error).
   ${eVar} = client.${eName}.load(${loadArg})
-  puts ${eVar}
+  puts ${eVar}.data_get
 rescue => err
   warn "load failed: #{err}"
 end

package/project/.sdk/src/cmp/rb/ReadmeRef_rb.ts

@@ -7,12 +7,15 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
+import { rbListArgs } from './utility_rb'
+
 
 // A type-correct Ruby literal for a field's canonical type — the create body
 // is EXECUTED by the doc test, so it must carry a real value per field.
 // Strings render the quoted placeholder.
 function rbLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'nil'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '[]'
@@ -24,8 +27,8 @@ function rbLit(type: any, placeholder: string = 'example'): string {
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(reqmatch, ctrl = nil) -> result',
-    returns: 'result',
-    desc: 'Load a single entity matching the given criteria. Raises on error.',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data_get` reads, and raises on error.',
   },
   list: {
     sig: 'list(reqmatch = nil, ctrl = nil) -> Array',
@@ -34,23 +37,23 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
   },
   create: {
     sig: 'create(reqdata, ctrl = nil) -> result',
-    returns: 'result',
-    desc: 'Create a new entity with the given data. 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 = nil) -> result',
-    returns: 'result',
-    desc: 'Update an existing entity. The data must include the entity `id`. 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 = nil) -> result',
-    returns: 'result',
-    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. 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 = nil) -> result',
-    returns: 'result',
-    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.',
   },
 }
 
@@ -288,7 +291,7 @@ result = client.${ent.Name}.${opname}(${arg})
           }
           else if ('list' === opname) {
             Content(`\`\`\`ruby
-results = client.${ent.Name}.list
+results = client.${ent.Name}.list${rbListArgs(ent)}
 results.each { |item| puts item.data_get }
 \`\`\`
 

package/project/.sdk/src/cmp/rb/ReadmeTopQuick_rb.ts

@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { rbListArgs } from './utility_rb'
+
 
 // A type-correct, executable Ruby 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 rbLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'nil'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '[]'
@@ -53,7 +56,7 @@ client = ${ctor}
 
     if (opnames.includes('list')) {
       Content(`# List all ${eName.toLowerCase()}s (an Array of entities, one per record; raises on error)
-${eVar}s = client.${eName}.list
+${eVar}s = client.${eName}.list${rbListArgs(exampleEntity)}
 ${eVar}s.each { |item| puts item.data_get }
 `)
       hasCall = true
@@ -70,9 +73,9 @@ ${eVar}s.each { |item| puts item.data_get }
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')} }`
         : ''
       Content(`
-# Load a specific ${eName.toLowerCase()} (returns the ENTITY; call data_get for the record)
+# Load a specific ${eName.toLowerCase()} (returns the entity; data_get reads its record; raises on error)
 ${eVar} = client.${eName}.load(${loadArg})
-puts ${eVar}
+puts ${eVar}.data_get
 `)
       hasCall = true
     }