@voxgig/sdkgen 4.34.1 → 4.34.2

package/project/.sdk/src/cmp/swift/ReadmeRef_swift.ts

@@ -7,7 +7,7 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { swiftVarName } from './utility_swift'
+import { swiftVarName, swiftListMatch } from './utility_swift'
 
 
 // Type names come from the shared canonToType 'swift' column (single source of truth).
@@ -15,6 +15,7 @@ import { swiftVarName } from './utility_swift'
 // A type-correct Swift `Value` literal for a field's canonical type.
 function swiftLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return '.null'
   if ('INTEGER' === k) return '.int(1)'
   if ('NUMBER' === k) return '.double(1.0)'
   if ('BOOLEAN' === k) return '.bool(true)'
@@ -27,33 +28,33 @@ function swiftLit(type: any, placeholder: string = 'example'): string {
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(reqmatch, ctrl) throws -> Value',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and throws on error.',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data()` reads, as a native `Value` that `asNative as? Entity` unwraps, and throws on error.',
   },
   list: {
     sig: 'list(reqmatch, ctrl) throws -> Value',
-    returns: 'a Value list of entities',
-    desc: 'List entities matching the given criteria. The match is optional — call `list(nil, nil)` to list all records. Returns a Value list and throws on error.',
+    returns: 'a `Value` list of entities, one per record',
+    desc: 'List entities matching the given criteria. The match is optional — call `list(nil, nil)` to list all records. Returns a `Value` list of entities, one per record, and throws on error.',
   },
   create: {
     sig: 'create(reqdata, ctrl) throws -> Value',
-    returns: 'the created entity data',
-    desc: 'Create a new entity with the given data. Returns the created entity data and throws on error.',
+    returns: 'the created entity',
+    desc: 'Create a new entity with the given data. Returns the created entity and throws on error.',
   },
   update: {
     sig: 'update(reqdata, ctrl) throws -> Value',
-    returns: 'the updated entity data',
-    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and throws on error.',
+    returns: 'the updated entity',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and throws on error.',
   },
   patch: {
     sig: 'patch(reqdata, ctrl) throws -> Value',
-    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 throws 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 throws on error.',
   },
   remove: {
     sig: 'remove(reqmatch, ctrl) throws -> Value',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Throws on error.',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and throws on error.',
   },
 }
 
@@ -284,8 +285,12 @@ let result = try client.${accessor}().${opname}(${arg}, nil)
           }
           else if ('list' === opname) {
             Content(`\`\`\`swift
-let results = try client.${accessor}().list(nil, nil)
-print(results)
+let results = try client.${accessor}().list(${swiftListMatch(ent)}, nil)
+for item in results.asList?.items ?? [] {
+    if let entity = item.asNative as? Entity {
+        print(entity.data())
+    }
+}
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/swift/ReadmeTopQuick_swift.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { swiftVarName } from './utility_swift'
+import { swiftVarName, swiftListMatch } from './utility_swift'
 
 
 // A type-correct Swift `Value` literal for a param: numeric/boolean/array/
@@ -15,6 +15,7 @@ import { swiftVarName } from './utility_swift'
 // The SDK's loose object model means every value is a `Value` inside a `VMap`.
 function swiftLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return '.null'
   if ('INTEGER' === k) return '.int(1)'
   if ('NUMBER' === k) return '.double(1.0)'
   if ('BOOLEAN' === k) return '.bool(true)'
@@ -65,10 +66,12 @@ let client = ${SDK}(options)
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eNameLower}s (returns a Value list, throws on error)
-let ${eVar}List = try client.${eName}().list(nil, nil)
-for ${eVar} in ${eVar}List.asList?.items ?? [] {
-    print(${eVar})
+      Content(`// List all ${eNameLower}s (a Value list of entities, one per record; throws on error)
+let ${eVar}List = try client.${eName}().list(${swiftListMatch(exampleEntity)}, nil)
+for ${eVar}Item in ${eVar}List.asList?.items ?? [] {
+    if let ${eVar}Entity = ${eVar}Item.asNative as? Entity {
+        print(${eVar}Entity.data())
+    }
 }
 `)
     }
@@ -87,9 +90,11 @@ for ${eVar} in ${eVar}List.asList?.items ?? [] {
             it.name === idF ? 'example_id' : 'example_' + it.name)})`).join(', ')}])`
         : 'nil'
       Content(`
-// Load a specific ${eNameLower} (returns the record, throws on error)
+// Load a specific ${eNameLower} (returns the entity, throws on error)
 let ${eVar} = try client.${eName}().load(${loadArg}, nil)
-print(${eVar})
+if let ${eVar}Entity = ${eVar}.asNative as? Entity {
+    print(${eVar}Entity.data())
+}
 `)
     }
   }

package/project/.sdk/src/cmp/swift/ReadmeTopTest_swift.ts

@@ -1,17 +1,18 @@
 
-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,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { swiftVarName } from './utility_swift'
+import { swiftVarName, swiftString } from './utility_swift'
 
 
 // A type-correct Swift `Value` literal for a field's canonical type.
 function swiftLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return '.null'
   if ('INTEGER' === k) return '.int(1)'
   if ('NUMBER' === k) return '.double(1.0)'
   if ('BOOLEAN' === k) return '.bool(true)'
@@ -41,16 +42,16 @@ let client = ${SDK}.testSDK(nil, nil)
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = 'nil'
-    if (isMatchOp) {
+    if (isMatchOp || ('list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length)) {
       // Every REQUIRED match key (id first) — the same shape that generates
       // the op's request type, so the block stays honest.
-      const items = opRequestShape(exampleEntity, primaryOp).items
-        .filter((it: any) => !it.optional || it.name === idF)
+      const items = (isMatchOp ? opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF) : requiredItems(exampleEntity, 'list'))
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       arg = 0 < items.length
         ? `VMap([${items.map((it: any) =>
-          `("${it.name}", ${it.name === idF ? '.string("test01")' : swiftLit(it.type)})`).join(', ')}])`
+          `(${swiftString(it.name)}, ${isMatchOp && it.name === idF ? '.string("test01")' : swiftLit(it.type)})`).join(', ')}])`
         : 'nil'
     } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
@@ -58,11 +59,21 @@ let client = ${SDK}.testSDK(nil, nil)
       const required = items.filter((it: any) => !it.optional)
       const chosen = required.length ? required : items.slice(0, 3)
       arg = `VMap([${chosen.map((it: any) =>
-        `("${it.name}", ${swiftLit(it.type)})`).join(', ')}])`
+        `(${swiftString(it.name)}, ${swiftLit(it.type)})`).join(', ')}])`
+    }
+    const eVar = swiftVarName(exampleEntity.name)
+    Content('list' === primaryOp
+      ? `let ${eVar}List = try client.${eName}().list(${arg}, nil)
+for ${eVar}Item in ${eVar}List.asList?.items ?? [] {
+    if let ${eVar}Entity = ${eVar}Item.asNative as? Entity {
+        print(${eVar}Entity.data())
     }
-    const eVar = swiftVarName(exampleEntity.name) + ('list' === primaryOp ? 'List' : '')
-    Content(`let ${eVar} = try client.${eName}().${primaryOp}(${arg}, nil)
-print(${eVar})
+}
+`
+      : `let ${eVar} = try client.${eName}().${primaryOp}(${arg}, nil)
+if let ${eVar}Entity = ${eVar}.asNative as? Entity {
+    print(${eVar}Entity.data())
+}
 `)
   }
 

package/project/.sdk/src/cmp/swift/utility_swift.ts

@@ -4,6 +4,8 @@ import * as Path from 'node:path'
 import {
   camelify,
   targetFeatures,
+  canonScalarKey,
+  requiredItems,
 } from '@voxgig/sdkgen'
 
 import {
@@ -18,7 +20,7 @@ function projectPath(suffix?: string): string {
 
 
 function swiftVarName(name: string): string {
-  const pascal = camelify(name)
+  const pascal = camelify(name.replace(/[^\p{L}\p{N}_]/gu, '_'))
   const lower = pascal.charAt(0).toLowerCase() + pascal.slice(1)
   if (SWIFT_RESERVED.has(lower)) {
     return lower + '_'
@@ -115,8 +117,19 @@ function swiftSecretsActive(model: any, target: any): boolean {
   return null != targetFeatures(model, target)['secrets']
 }
 
+// A list's required route and query parameters, as the match it is called with.
+function swiftListMatch(entity: any): string {
+  const lit = (type: any): string =>
+    (({ NULL: '.null', INTEGER: '.int(1)', NUMBER: '.double(1.0)', BOOLEAN: '.bool(true)', ARRAY: '.list([])', OBJECT: '.map(VMap())' }) as any)[canonScalarKey(type)] ?? '.string("example")'
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? `VMap([${items.map((it: any) => `(${swiftString(it.name)}, ${lit(it.type)})`).join(', ')}])`
+    : 'nil'
+}
+
 
 export {
+  swiftListMatch,
   clean,
   projectPath,
   swiftPascalName,

package/project/.sdk/src/cmp/ts/ReadmeEntity_ts.ts

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

package/project/.sdk/src/cmp/ts/ReadmeHowto_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, isHttpBasicAuth, envName, entityIdField, entityDataIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, isHttpBasicAuth, envName, entityIdField, entityDataIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, jsKey, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -28,13 +28,12 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
 
   const primaryArg = (idPlaceholder: string): string => {
     if (!exampleEntity || !primaryOp) return ''
-    if ('list' === primaryOp) return ''
-    if (isMatchOp) {
+    if (isMatchOp || 'list' === primaryOp) {
       // Every REQUIRED match key (id first), not just idF — a composite-match
       // entity (e.g. Umbrella's FlatPermission, database_id + id) needs them all
       // to satisfy the typed <Name>LoadMatch. Mirrors ReadmeTopTest.
-      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))
       if (0 === items.length) return ''
       const pairs = items.map((it: any) =>
@@ -60,11 +59,14 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
 
   // The op-driven example lines, shown only when the SDK has an entity op.
   // A direct()-only SDK (no ops anywhere) shows a direct() test call instead.
-  const testModeExample = primaryOp
+  const testModeExample = 'list' === primaryOp
+    ? `const ${eVar}s = await client.${eName}().list(${testCallArg})
+// ${eVar}s is an array of ${eName} entities, one per mock record
+console.log(${eVar}s.map((${eVar}) => ${eVar}.data()))`
+    : primaryOp
     ? `const ${eVar} = await client.${eName}().${primaryOp}(${testCallArg})
-// ${eVar} is the entity, populated with mock response data
-// — call ${eVar}.data() for the record itself
-console.log(${eVar})`
+// ${eVar} is the ${eName} entity; .data() reads its mock record
+console.log(${eVar}.data())`
     : `const result = await client.direct({ path: '/api/resource', method: 'GET' })
 console.log(result)`
   const stateSection = primaryOp

package/project/.sdk/src/cmp/ts/ReadmeModel_ts.ts

@@ -21,12 +21,12 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   entityList.forEach((e: any) => Object.keys(e.op || {})
     .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
   const opRowDefs: Record<string, string> = {
-    load: '| `load` | `load(reqmatch?, ctrl?): Promise<Entity>` | Load a single entity by match criteria. |',
-    list: '| `list` | `list(reqmatch?, ctrl?): Promise<Entity[]>` | List entities matching the criteria. |',
-    create: '| `create` | `create(reqdata?, ctrl?): Promise<Entity>` | Create a new entity. |',
-    update: '| `update` | `update(reqdata?, ctrl?): Promise<Entity>` | Update an existing entity. |',
-    patch: '| `patch` | `patch(reqdata?, ctrl?): Promise<Entity>` | Change part of an existing entity. |',
-    remove: '| `remove` | `remove(reqmatch?, ctrl?): Promise<void>` | Remove an entity. |',
+    load: '| `load` | `load(reqmatch?, ctrl?): Promise<Entity>` | Load a single entity by match criteria, and return it. |',
+    list: '| `list` | `list(reqmatch?, ctrl?): Promise<Entity[]>` | List entities matching the criteria, one per record. |',
+    create: '| `create` | `create(reqdata?, ctrl?): Promise<Entity>` | Create a new entity, and return it. |',
+    update: '| `update` | `update(reqdata?, ctrl?): Promise<Entity>` | Update an existing entity, and return it. |',
+    patch: '| `patch` | `patch(reqdata?, ctrl?): Promise<Entity>` | Change part of an existing entity, and return it. |',
+    remove: '| `remove` | `remove(reqmatch?, ctrl?): Promise<Entity>` | Remove an entity, and return it marked as deleted. |',
   }
   const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
@@ -44,7 +44,7 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     retBullets.push('- `list` resolves to an **array** of entity objects (iterate it directly;\n  there is no `.data` and no `.ok`).')
   }
   if (opUnion.has('remove')) {
-    retBullets.push('- `remove` resolves to `void`.')
+    retBullets.push('- `remove` resolves to the entity, marked as deleted.')
   }
   const returnBullets = retBullets.join('\n')
 
@@ -134,8 +134,8 @@ ${opRows}
 
 #### Return values
 
-Entity operations resolve to the entity data directly — there is no
-result envelope:
+Entity operations resolve to the entity itself — there is no result
+envelope, and an entity's \`data()\` reads its record:
 
 ${returnBullets}
 

package/project/.sdk/src/cmp/ts/ReadmeQuick_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, isHttpBasicAuth, packageName, envName, serverVariables, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, isHttpBasicAuth, packageName, envName, serverVariables, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, jsKey, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,12 +10,6 @@ import {
 import { exampleValue } from './utility_ts'
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -80,10 +74,10 @@ resolves to entities, not raw records. Iterate them directly, and call
 \`.data()\` on one for the record it holds:
 
 \`\`\`ts
-const ${eVar}s = await client.${eName}().list(${listMatchArg(exampleEntity)})
+const ${eVar}s = await client.${eName}().list(${listMatchArg('ts', exampleEntity)})
 
 for (const ${eVar} of ${eVar}s) {
-  console.log(${eVar})
+  console.log(${eVar}.data())
 }
 \`\`\`
 
@@ -111,14 +105,14 @@ for (const ${eVar} of ${eVar}s) {
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\` returns the entity directly and throws on failure:
+\`load()\` returns the entity and throws on failure; \`.data()\` reads its record:
 
 \`\`\`ts
 try {
   const ${neVar} = await client.${neName}().load({
 ${neMatchLines.join('\n')}
   })
-  console.log(${neVar})
+  console.log(${neVar}.data())
 } catch (err) {
   console.error('load failed:', err)
 }
@@ -139,12 +133,12 @@ ${neMatchLines.join('\n')}
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load()\` returns the entity directly and throws on failure:
+\`load()\` returns the entity and throws on failure; \`.data()\` reads its record:
 
 \`\`\`ts
 try {
   const ${eVar} = await client.${eName}().load(${loadArg})
-  console.log(${eVar})
+  console.log(${eVar}.data())
 } catch (err) {
   console.error('load failed:', err)
 }

package/project/.sdk/src/cmp/ts/ReadmeRef_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, File, isAuthActive, isHttpBasicAuth, entityIdField, entityActions, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral, targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, isHttpBasicAuth, entityIdField, entityActions, opRequestShape, safeVarName, exampleVarName, jsKey, targetFeatures, opNeedsAction, bodyNote, listMatchArg } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -10,43 +10,36 @@ import {
 import { exampleValue } from './utility_ts'
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(match: object, ctrl?: object)',
-    returns: 'Promise<object>',
-    desc: 'Load a single entity matching the given criteria.',
+    returns: 'Promise<Entity>',
+    desc: 'Load a single entity matching the given criteria. Resolves to the entity, whose record `data()` reads.',
   },
   list: {
     sig: 'list(match: object, ctrl?: object)',
-    returns: 'Promise<object[]>',
-    desc: 'List entities matching the given criteria. Returns an array.',
+    returns: 'Promise<Entity[]>',
+    desc: 'List entities matching the given criteria. Resolves to an array of entities, one per record.',
   },
   create: {
     sig: 'create(data: object, ctrl?: object)',
-    returns: 'Promise<object>',
-    desc: 'Create a new entity with the given data.',
+    returns: 'Promise<Entity>',
+    desc: 'Create a new entity with the given data. Resolves to the created entity.',
   },
   update: {
     sig: 'update(data: object, ctrl?: object)',
-    returns: 'Promise<object>',
-    desc: 'Update an existing entity. The data must include the entity `id`.',
+    returns: 'Promise<Entity>',
+    desc: 'Update an existing entity. The data must include the entity `id`. Resolves to the updated entity.',
   },
   patch: {
     sig: 'patch(data: object, ctrl?: object)',
-    returns: 'Promise<object>',
-    desc: 'Change part of an existing entity: only the fields given are sent. ' +
-      'The data must include the entity `id`.',
+    returns: 'Promise<Entity>',
+    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.',
   },
   remove: {
     sig: 'remove(match: object, ctrl?: object)',
-    returns: 'Promise<void>',
-    desc: 'Remove the entity matching the given criteria.',
+    returns: 'Promise<Entity>',
+    desc: 'Remove the entity matching the given criteria. Resolves to the entity, marked as deleted.',
   },
 }
 
@@ -349,7 +342,7 @@ const result = await client.${ent.Name}().${opname}(${arg})
           }
           else if ('list' === opname) {
             Content(`\`\`\`ts
-const results = await client.${ent.Name}().${opname}(${listMatchArg(ent)})
+const results = await client.${ent.Name}().${opname}(${listMatchArg('ts', ent)})
 \`\`\`
 
 `)
@@ -476,8 +469,6 @@ const client = new ${model.Name}SDK({
 })
 
 
-
-
 export {
   ReadmeRef
 }

package/project/.sdk/src/cmp/ts/ReadmeTopQuick_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, isHttpBasicAuth, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral , serverVariables} from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, isHttpBasicAuth, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName, exampleVarName, jsKey, serverVariables, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,12 +10,6 @@ import {
 import { exampleValue } from './utility_ts'
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -57,10 +51,10 @@ const client = ${ctor}
     let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s (returns ${eName}Entity[] — .data() for the record)
-const ${eVar}s = await client.${eName}().list(${listMatchArg(exampleEntity)})
+      Content(`// List all ${eName.toLowerCase()}s (returns ${eName}Entity[], one entity per record)
+const ${eVar}s = await client.${eName}().list(${listMatchArg('ts', exampleEntity)})
 for (const ${eVar} of ${eVar}s) {
-  console.log(${eVar})
+  console.log(${eVar}.data())
 }
 `)
       hasCall = true
@@ -92,19 +86,19 @@ for (const ${eVar} of ${eVar}s) {
             it.name === neIdF ? 'example_id' : 'example_' + it.name)},`)
 
       Content(`
-// Load a specific ${neName.toLowerCase()} (returns a ${neName})
+// Load a specific ${neName.toLowerCase()} (returns the entity, ${/^[aeiou]/i.test(neName) ? 'an' : 'a'} ${neName}Entity)
 const ${neVar} = await client.${neName}().load({
 ${neMatchLines.join('\n')}
 })
-console.log(${neVar})
+console.log(${neVar}.data())
 `)
       hasCall = true
     }
 
     if (!hasCall && opnames.includes('load')) {
-      Content(`// Load ${eName.toLowerCase()} data (returns a ${eName})
+      Content(`// Load a specific ${eName.toLowerCase()} (returns the entity, ${/^[aeiou]/i.test(eName) ? 'an' : 'a'} ${eName}Entity)
 const ${eVar} = await client.${eName}().load()
-console.log(${eVar})
+console.log(${eVar}.data())
 `)
       hasCall = true
     }

package/project/.sdk/src/cmp/ts/ReadmeTopTest_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
+import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape, requiredItems, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -25,11 +25,22 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
       .slice(0, 3) : []
 
   const seedId = 'test01'
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  const isIdField = (it: any) => it.name === idF || it.name === 'id'
+
+  // A list matches its required parameters against the record, so the seed
+  // carries the values the call below sends, and an id is the record's key.
+  const listItems = 'list' === primaryOp ? requiredItems(exampleEntity, 'list') : []
+  const listed = (it: any) => listItems.some((li: any) => li.name === it.name)
+  const listLit = (it: any): string => exampleValue(exampleEntity, exampleEntity.op.list,
+    it.name, isIdField(it) ? seedId : 'example_' + it.name)
+
   const seedBody = [
     `${jsKey('id')}: '${seedId}'`,
-    ...seedFields
+    ...[...seedFields, ...listItems.filter((it: any) =>
+      !seedFields.some((sf: any) => sf.name === it.name))]
       .filter((it: any) => 'id' !== it.name)
-      .map((it: any) => `${jsKey(it.name)}: ${exampleValue(
+      .map((it: any) => `${jsKey(it.name)}: ${listed(it) ? listLit(it) : exampleValue(
         exampleEntity, exampleEntity.op && exampleEntity.op.create, it.name,
         'example_' + it.name)}`),
   ].join(', ')
@@ -52,22 +63,23 @@ const client = ${model.const.Name}SDK.test({
     const eVar = exampleVarName(eName.toLowerCase(), 'ts') +
       ('list' === primaryOp ? 's' : '')
     const primaryOpDef = exampleEntity.op && exampleEntity.op[primaryOp]
-    const idF = entityIdField(exampleEntity)
     let arg = ''
-    if ('load' === primaryOp || 'remove' === primaryOp) {
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    if (isMatchOp || 'list' === primaryOp) {
       // Every REQUIRED match key (id first) — the same shape that generates
       // the op's Match type, so the block type-checks.
-      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) : [...listItems])
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const lit = (it: any): string => isMatchOp
+        ? exampleValue(exampleEntity, primaryOpDef, it.name,
+          it.name === idF ? 'test01' : 'example_' + it.name)
+        : listLit(it)
       arg = 0 < items.length
-        ? `{ ${items.map((it: any) =>
-          `${jsKey(it.name)}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
-            it.name === idF ? 'test01' : 'example_' + it.name)}`).join(', ')} }`
+        ? `{ ${items.map((it: any) => `${jsKey(it.name)}: ${lit(it)}`).join(', ')} }`
         : ''
     } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
-      const isIdField = (it: any) => it.name === idF || it.name === 'id'
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => !isIdField(it) || !it.optional)
       const required = items.filter((it: any) => !it.optional)
@@ -78,10 +90,13 @@ const client = ${model.const.Name}SDK.test({
         `${jsKey(it.name)}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
           isIdField(it) ? seedId : 'example_' + it.name)}`).join(', ')} }`
     }
+    const one = exampleVarName(eName.toLowerCase(), 'ts')
     Content(`const ${eVar} = await client.${eName}().${primaryOp}(${arg})
-// ${eVar} is ${'list' === primaryOp ? `an array of ${eName} entities` : `the ${eName} entity`}, populated with mock data
-// — call ${eVar}${'list' === primaryOp ? '[0]' : ''}.data() for the record itself
-console.log(${eVar})
+${'list' === primaryOp
+    ? `// ${eVar} is an array of ${eName} entities, one per mock record
+console.log(${eVar}.map((${one}) => ${one}.data()))`
+    : `// ${eVar} is the ${eName} entity; .data() reads its mock record
+console.log(${eVar}.data())`}
 `)
   }
 

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

@@ -105,7 +105,7 @@ class EntityOperation {
       }
       else {
         // Off-happy-path (throw disabled): typed as any so the method's
-        // Promise<EntityName> return stays clean under strict null checks.
+        // Promise<EntyClass> return stays clean under strict null checks.
         return undefined as any
       }
     }

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

@@ -104,7 +104,7 @@ class EntityOperation {
       }
       else {
         // Off-happy-path (throw disabled): typed as any so the method's
-        // Promise<EntityName[]> return stays clean under strict null checks.
+        // Promise<EntyClass[]> return stays clean under strict null checks.
         return undefined as any
       }
     }