@voxgig/sdkgen 1.2.1 → 1.3.2

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

@@ -13,6 +13,43 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const entityList = each(entity).filter((e: any) => e.active !== false)
 
+  // Model-driven op rows for the shared entity interface: emit a
+  // load/list/create/update/remove row only for operations at least one active
+  // entity actually exposes (a read-only entity has just list+load) — never
+  // document an operation no entity has.
+  const opUnion = new Set<string>()
+  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. |',
+    remove: '| `remove` | `remove(reqmatch?, ctrl?): Promise<void>` | Remove an entity. |',
+  }
+  const opRows = ['load', 'list', 'create', 'update', 'remove']
+    .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
+
+  // Model-driven return-value bullets: describe only the operations that
+  // actually exist (single-object ops among load/create/update, plus
+  // list/remove) — never document return semantics for a missing op.
+  const singleOps = ['load', 'create', 'update'].filter((o) => opUnion.has(o))
+    .map((o) => '`' + o + '`')
+  const retBullets: string[] = []
+  if (singleOps.length) {
+    const joined = singleOps.length > 1
+      ? singleOps.slice(0, -1).join(', ') + ' and ' + singleOps[singleOps.length - 1]
+      : singleOps[0]
+    retBullets.push(`- ${joined} ${singleOps.length > 1 ? 'resolve' : 'resolves'} to a single entity object.`)
+  }
+  if (opUnion.has('list')) {
+    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`.')
+  }
+  const returnBullets = retBullets.join('\n')
+
   const apikeyOptionRow = isAuthActive(model)
     ? '| `apikey` | `string` | API key for authentication. |\n'
     : ''
@@ -44,7 +81,8 @@ ${apikeyOptionRow}| \`base\` | \`string\` | Base URL of the API server. |
 `)
 
   each(entityList, (ent: any) => {
-    Content(`| \`${ent.Name}(data?)\` | \`${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
+    const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
+    Content(`| \`${ent.Name}(data?)\` | \`${ent.Name}Entity\` | Create ${article} ${ent.Name} entity instance. |
 `)
   })
 
@@ -64,29 +102,23 @@ All entities share the same interface.
 
 | Method | Signature | Description |
 | --- | --- | --- |
-| \`load\` | \`load(reqmatch?, ctrl?): Promise<Result>\` | Load a single entity by match criteria. |
-| \`list\` | \`list(reqmatch?, ctrl?): Promise<Result>\` | List entities matching the criteria. |
-| \`create\` | \`create(reqdata?, ctrl?): Promise<Result>\` | Create a new entity. |
-| \`update\` | \`update(reqdata?, ctrl?): Promise<Result>\` | Update an existing entity. |
-| \`remove\` | \`remove(reqmatch?, ctrl?): Promise<Result>\` | Remove an entity. |
-| \`data\` | \`data(data?): any\` | Get or set entity data. |
-| \`match\` | \`match(match?): any\` | Get or set entity match criteria. |
+${opRows}
+| \`data\` | \`data(data?: Partial<Entity>): Entity\` | Get or set entity data. |
+| \`match\` | \`match(match?: Partial<Entity>): Partial<Entity>\` | Get or set entity match criteria. |
 | \`make\` | \`make(): Entity\` | Create a new instance with the same options. |
 | \`client\` | \`client(): ${model.const.Name}SDK\` | Return the parent SDK client. |
 | \`entopts\` | \`entopts(): object\` | Return a copy of the entity options. |
 
-#### Result shape
+#### Return values
 
-All entity operations return a Result object:
+Entity operations resolve to the entity data directly — there is no
+result envelope:
 
-\`\`\`js
-{
-  ok: true,       // true if the HTTP status is 2xx
-  status: 200,    // HTTP status code
-  headers: {},    // response headers
-  data: {}        // parsed JSON response body
-}
-\`\`\`
+${returnBullets}
+
+On a failed request these methods **throw**, so wrap calls in
+\`try\`/\`catch\` to handle errors. Only \`direct()\` returns the result
+envelope described below.
 
 ### DirectResult shape
 

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

@@ -1,12 +1,13 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, envName, isAuthActive } from '@voxgig/sdkgen'
 
 
 const ReadmeOptions = cmp(function ReadmeOptions(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
-  const publishedOptions = each(target.options).filter((option: any) => option.publish)
+  const publishedOptions = each(target.options).filter((option: any) =>
+    option.publish && ('apikey' !== option.name || isAuthActive(model)))
   if (0 === publishedOptions.length) {
     return
   }
@@ -25,7 +26,7 @@ const client = new ${model.Name}SDK({
 
   publishedOptions.map((option: any) => {
     if ('apikey' === option.name) {
-      Content(`  ${option.name}: process.env.${model.NAME}_APIKEY,
+      Content(`  ${option.name}: process.env.${envName(model)}_APIKEY,
 `)
     }
     else {

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, entityOps, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_js'
+
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
@@ -16,32 +18,77 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   // Find the first published entity for examples
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n  apikey: process.env.${model.NAME}_APIKEY,\n`
-    : ''
+  const ctor = isAuthActive(model)
+    ? `new ${model.const.Name}SDK({\n  apikey: process.env.${envName(model)}_APIKEY,\n})`
+    : `new ${model.const.Name}SDK()`
 
   Content(`
 ### Create a Client
 
 \`\`\`js
-const { ${model.const.Name}SDK } = require('${target.module.name}')
+const { ${model.const.Name}SDK } = require('${packageName(model, target.name)}')
 
-const client = new ${model.const.Name}SDK({${apikeyArg}})
+const client = ${ctor}
 \`\`\`
 `)
 
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    const opnames = Object.keys(exampleEntity.op || {})
+    const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
+    // ACTIVE ops only — an inactive op generates no method, so an example
+    // calling it would be wrong.
+    const opnames = entityOps(exampleEntity)
+
+    // Model-driven example fields, in parity with the ts target: derive the
+    // create/update body from the op shape (opRequestShape) so the docs show
+    // REAL writable fields, not a hardcoded field the entity may not have.
+    // `idF` is the entity's id-like field name, or null when it has none —
+    // then load/remove match on no argument and update omits the id.
+    const idF = entityIdField(exampleEntity)
+    // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
+    const eVar = safeVarName(exampleEntity.name, 'js')
+    const exampleFields = (opname: string): string[] => {
+      // ids are rendered separately as the match key for update/remove; a
+      // REQUIRED id stays for create (dropping it makes the payload
+      // incomplete).
+      const items = opRequestShape(exampleEntity, opname).items
+        .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
+          ('create' === opname && !it.optional))
+      const required = items.filter((it: any) => !it.optional)
+      const optional = items.filter((it: any) => it.optional)
+      // create needs ALL required fields for parity with the typed ts target;
+      // update is a patch, so the required members plus a sample optional
+      // field or two suffice.
+      const chosen = 'create' === opname
+        ? (required.length ? required : items.slice(0, 2))
+        : required.concat(optional).slice(0, Math.max(2, required.length))
+      return chosen.map((it: any) =>
+        `  ${it.name}: ${exampleValue(exampleEntity, exampleEntity.op[opname], it.name, 'example_' + it.name)},`)
+    }
+
+    // The full REQUIRED match for load/remove (id first, then parent path
+    // params like page_id) — the same shape the runtime resolves path params
+    // from, so the example always carries the keys the route needs.
+    const matchArg = (opname: string): string => {
+      const matchItems = opRequestShape(exampleEntity, 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))
+      return 0 < matchItems.length
+        ? `{ ${matchItems.map((it: any) =>
+          `${it.name}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op[opname], it.name,
+            it.name === idF ? exampleEntity.name + '_id' : 'example_' + it.name)}`).join(', ')} }`
+        : ''
+    }
 
     if (opnames.includes('load')) {
       Content(`
-### Load a ${eName}
+### Load ${article} ${eName}
 
 \`\`\`js
-const ${exampleEntity.name} = await client.${eName}().load({ id: '${exampleEntity.name}_id' })
-console.log(${exampleEntity.name})
+const ${eVar} = await client.${eName}().load(${matchArg('load')})
+console.log(${eVar})
 \`\`\`
 `)
     }
@@ -51,34 +98,37 @@ console.log(${exampleEntity.name})
 ### List ${eName} Records
 
 \`\`\`js
-const ${exampleEntity.name}s = await client.${eName}().list()
-console.log(${exampleEntity.name}s)
+const ${eVar}s = await client.${eName}().list()
+for (const ${eVar} of ${eVar}s) {
+  console.log(${eVar})
+}
 \`\`\`
 `)
     }
 
     if (opnames.includes('create')) {
+      const createLines = exampleFields('create')
+      const createBody = createLines.length ? '\n' + createLines.join('\n') + '\n' : ''
       Content(`
 ### Create a ${eName}
 
 \`\`\`js
-const created = await client.${eName}().create({
-  // Provide ${exampleEntity.name} fields
-})
+const created = await client.${eName}().create({${createBody}})
 console.log(created)
 \`\`\`
 `)
     }
 
     if (opnames.includes('update')) {
+      const updateLines = (idF
+        ? [`  ${idF}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op.update, idF, exampleEntity.name + '_id')},`]
+        : []).concat(exampleFields('update'))
+      const updateBody = updateLines.length ? '\n' + updateLines.join('\n') + '\n' : ''
       Content(`
 ### Update a ${eName}
 
 \`\`\`js
-const updated = await client.${eName}().update({
-  id: '${exampleEntity.name}_id',
-  // Fields to update
-})
+const updated = await client.${eName}().update({${updateBody}})
 console.log(updated)
 \`\`\`
 `)
@@ -89,7 +139,7 @@ console.log(updated)
 ### Remove a ${eName}
 
 \`\`\`js
-await client.${eName}().remove({ id: '${exampleEntity.name}_id' })
+await client.${eName}().remove(${matchArg('remove')})
 \`\`\`
 `)
     }

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

@@ -1,11 +1,13 @@
 
-import { cmp, each, Content, File, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_js'
+
 
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
@@ -70,8 +72,7 @@ Create a new SDK client instance.
 | Name | Type | Description |
 | --- | --- | --- |
 | \`options\` | \`object\` | SDK configuration options. |
-| \`options.apikey\` | \`string\` | API key for authentication. |
-| \`options.base\` | \`string\` | Base URL for API requests. |
+${isAuthActive(model) ? '| \`options.apikey\` | \`string\` | API key for authentication. |\n' : ''}| \`options.base\` | \`string\` | Base URL for API requests. |
 | \`options.prefix\` | \`string\` | URL prefix appended after base. |
 | \`options.suffix\` | \`string\` | URL suffix appended after path. |
 | \`options.headers\` | \`object\` | Custom headers for all requests. |
@@ -180,6 +181,11 @@ Alias for \`${model.Name}SDK.test()\`.
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
       const fields = ent.fields || []
+      // Model-driven id key: null when this entity has no id-like field, in
+      // which case load/remove match on no argument and update omits the id.
+      const idF = entityIdField(ent)
+      // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
+      const eVar = safeVarName(ent.name, 'js')
 
       Content(`
 ---
@@ -195,7 +201,7 @@ Alias for \`${model.Name}SDK.test()\`.
       }
 
       Content(`\`\`\`ts
-const ${ent.name} = client.${ent.Name}()
+const ${eVar} = client.${ent.Name}()
 \`\`\`
 
 `)
@@ -211,7 +217,7 @@ const ${ent.name} = client.${ent.Name}()
         each(fields, (field: any) => {
           const req = field.req ? 'Yes' : 'No'
           const desc = field.short || ''
-          Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${req} | ${desc} |
+          Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${req} | ${desc} |
 `)
         })
 
@@ -221,15 +227,18 @@ const ${ent.name} = client.${ent.Name}()
         // Field operations breakdown
         const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
         if (hasFieldOps) {
+          // Only emit columns for operations this entity actually exposes —
+          // never advertise a create/update/remove column the entity lacks.
+          const opcols = ['load', 'list', 'create', 'update', 'remove']
+            .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
-| Field | load | list | create | update | remove |
-| --- | --- | --- | --- | --- | --- |
+| Field | ${opcols.join(' | ')} |
+| --- | ${opcols.map(() => '---').join(' | ')} |
 `)
           each(fields, (field: any) => {
             const fops = field.op || {}
-            const cols = ['load', 'list', 'create', 'update', 'remove'].map((op: string) => {
-              if (!opnames.includes(op)) return '-'
+            const cols = opcols.map((op: string) => {
               const fop = fops[op]
               if (null == fop) return '-'
               if (fop.active === false) return '-'
@@ -263,8 +272,20 @@ ${info.desc}
 
           // Show example
           if ('load' === opname || 'remove' === opname) {
+            // 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.
+            const matchItems = 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))
+            const arg = 0 < matchItems.length
+              ? `{ ${matchItems.map((it: any) =>
+                `${it.name}: ${exampleValue(ent, ent.op && ent.op[opname], it.name,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')} }`
+              : ''
             Content(`\`\`\`ts
-const result = await client.${ent.Name}().${opname}({ id: '${ent.name}_id' })
+const result = await client.${ent.Name}().${opname}(${arg})
 \`\`\`
 
 `)
@@ -277,14 +298,19 @@ const results = await client.${ent.Name}().${opname}()
 `)
           }
           else if ('create' === opname) {
+            // 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 (the /* type */
+            // placeholders mark the block as an illustration); an
+            // all-optional create renders an empty — still valid — literal.
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
             Content(`\`\`\`ts
 const result = await client.${ent.Name}().create({
 `)
-            each(fields, (field: any) => {
-              if ('id' !== field.name && field.req) {
-                Content(`  ${field.name}: /* ${field.type || 'value'} */,
+            createItems.map((it: any) => {
+              Content(`  ${it.name}: /* ${canonToType(it.type, target.name)} */,
 `)
-              }
             })
             Content(`})
 \`\`\`
@@ -292,10 +318,18 @@ const result = await client.${ent.Name}().create({
 `)
           }
           else if ('update' === opname) {
+            // The id key plus every REQUIRED data member — the same shape the
+            // runtime validates — then the patch-fields note.
+            const updateItems = opRequestShape(ent, 'update').items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const updateLines = updateItems.map((it: any) =>
+              `  ${it.name}: ${exampleValue(ent, ent.op && ent.op.update, it.name,
+                it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`ts
 const result = await client.${ent.Name}().update({
-  id: '${ent.name}_id',
-  // Fields to update
+${updateLines}  // Fields to update
 })
 \`\`\`
 

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

@@ -12,6 +12,9 @@ const result = await client.direct({
   method: 'GET',
   params: { id: 'example' },
 })
+if (result instanceof Error) {
+  throw result
+}
 console.log(result.data)
 \`\`\`
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_js'
+
 
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
@@ -14,44 +16,68 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n  apikey: process.env.${model.NAME}_APIKEY,\n`
-    : ''
+  const ctor = isAuthActive(model)
+    ? `new ${model.const.Name}SDK({\n  apikey: process.env.${envName(model)}_APIKEY,\n})`
+    : `new ${model.const.Name}SDK()`
 
   Content(`\`\`\`js
-const { ${model.const.Name}SDK } = require('${target.module.name}')
+const { ${model.const.Name}SDK } = require('${packageName(model, target.name)}')
 
-const client = new ${model.const.Name}SDK({${apikeyArg}})
+const client = ${ctor}
 
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    const opnames = Object.keys(exampleEntity.op || {})
+    const eVar = safeVarName(eName.toLowerCase(), 'js')
+    // ACTIVE ops only — an inactive op generates no method, so an example
+    // calling it would be wrong.
+    const opnames = entityOps(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s
-const ${eName.toLowerCase()}s = await client.${eName}().list()
+      Content(`// List all ${eName.toLowerCase()}s (returns an array)
+const ${eVar}s = await client.${eName}().list()
+for (const ${eVar} of ${eVar}s) {
+  console.log(${eVar})
+}
 `)
     }
 
-    // Find a nested entity for a more interesting example
+    // Find a nested entity for a more interesting example: one with a parent
+    // chain (relations.ancestors), an active load op of its OWN, and a
+    // required non-id load param to demonstrate (the parent key, e.g.
+    // page_id).
     const nestedEntity = Object.values(entity).find((e: any) =>
-      e.active !== false && e.ancestors && e.ancestors.length > 0
+      e.active !== false &&
+      e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
+      entityOps(e).includes('load') &&
+      opRequestShape(e, 'load').items.some((it: any) =>
+        !it.optional && it.name !== entityIdField(e))
     ) as any
 
-    if (nestedEntity && opnames.includes('load')) {
+    if (nestedEntity) {
       const neName = nom(nestedEntity, 'Name')
-      const parentFields = (nestedEntity.fields || [])
-        .filter((f: any) => f.name !== 'id' && f.name.endsWith('_id'))
-      const parentParam = parentFields.length > 0 ? parentFields[0].name : 'parent_id'
+      const neVar = safeVarName(neName.toLowerCase(), 'js')
+      const loadOp = nestedEntity.op && nestedEntity.op.load
+
+      // Every REQUIRED load-match key (parent keys like page_id first, the
+      // entity's own id last) — the same shape the runtime resolves path
+      // params from, so the example always works.
+      const neIdF = entityIdField(nestedEntity)
+      const neMatchLines = opRequestShape(nestedEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === neIdF)
+        .sort((a: any, b: any) =>
+          (a.name === neIdF ? 1 : 0) - (b.name === neIdF ? 1 : 0))
+        .map((it: any) =>
+          `  ${it.name}: ${exampleValue(nestedEntity, loadOp, it.name,
+            it.name === neIdF ? 'example_id' : 'example_' + it.name)},`)
 
       Content(`
-// Load a specific ${neName.toLowerCase()}
-const ${neName.toLowerCase()} = await client.${neName}().load({
-  ${parentParam}: 'example',
-  id: 'example_id',
+// Load a specific ${neName.toLowerCase()} (returns the entity)
+const ${neVar} = await client.${neName}().load({
+${neMatchLines.join('\n')}
 })
+console.log(${neVar})
 `)
     }
   }

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, entityIdField, entityPrimaryOp, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_js'
+
 
 const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   const { target, ctx$: { model } } = props
@@ -20,8 +22,38 @@ const client = ${model.const.Name}SDK.test()
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    Content(`const result = await client.${eName}().load({ id: 'test01' })
-// result.ok === true, result.data contains mock data
+    // Drive the test-mode example off the entity's PRIMARY op (never a
+    // hardcoded `load` a create-only entity lacks).
+    const primaryOp = entityPrimaryOp(exampleEntity) || 'load'
+    // A list() result is an array — name the variable accordingly.
+    const eVar = safeVarName(eName.toLowerCase(), 'js') +
+      ('list' === primaryOp ? 's' : '')
+    const primaryOpDef = exampleEntity.op && exampleEntity.op[primaryOp]
+    const idF = entityIdField(exampleEntity)
+    let arg = ''
+    if ('load' === primaryOp || 'remove' === primaryOp) {
+      // Every REQUIRED match key (id first, then parent path params like
+      // page_id) — the same shape the runtime resolves path params from.
+      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))
+      arg = 0 < items.length
+        ? `{ ${items.map((it: any) =>
+          `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
+            it.name === idF ? 'test01' : 'example_' + it.name)}`).join(', ')} }`
+        : ''
+    } else if ('create' === primaryOp || 'update' === 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}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`).join(', ')} }`
+    }
+    Content(`const ${eVar} = await client.${eName}().${primaryOp}(${arg})
+// ${eVar} is ${'list' === primaryOp ? 'an array of bare entities' : 'a bare entity'} populated with mock data
+console.log(${eVar})
 `)
   }
 

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

@@ -4,6 +4,11 @@ class EntityOperation {
 
   // EJECT-START
 
+  /**
+   * @param {EntityNameCreateData} [reqdata]
+   * @param {Object} [ctrl]
+   * @returns {Promise<EntityName>}
+   */
   async create(reqdata, ctrl) {
 
     const utility = this._utility

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

@@ -4,6 +4,11 @@ class EntityOperation {
 
   // EJECT-START
 
+  /**
+   * @param {EntityNameListMatch} [reqmatch]
+   * @param {Object} [ctrl]
+   * @returns {Promise<EntityName[]>}
+   */
   async list(reqmatch, ctrl) {
 
     const utility = this._utility

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

@@ -4,6 +4,11 @@ class EntityOperation {
 
   // EJECT-START
 
+  /**
+   * @param {EntityNameLoadMatch} [reqmatch]
+   * @param {Object} [ctrl]
+   * @returns {Promise<EntityName>}
+   */
   async load(reqmatch, ctrl) {
 
     const utility = this._utility

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

@@ -4,6 +4,11 @@ class EntityOperation {
 
   // EJECT-START
 
+  /**
+   * @param {EntityNameRemoveMatch} [reqmatch]
+   * @param {Object} [ctrl]
+   * @returns {Promise<EntityName>}
+   */
   async remove(reqmatch, ctrl) {
 
     const utility = this._utility

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

@@ -4,6 +4,11 @@ class EntityOperation {
 
   // EJECT-START
 
+  /**
+   * @param {EntityNameUpdateData} [reqdata]
+   * @param {Object} [ctrl]
+   * @returns {Promise<EntityName>}
+   */
   async update(reqdata, ctrl) {
 
     const utility = this._utility