@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/scala/utility_scala.ts

@@ -4,6 +4,9 @@ import * as Path from 'node:path'
 
 import {
   camelify,
+  canonScalarKey,
+  requiredItems,
+  javaMapOf,
 } from '@voxgig/sdkgen'
 
 import {
@@ -108,8 +111,30 @@ function jsonAppendLines(value: any, bufname: string): string {
     .join('')
 }
 
+// Map.of and Map.entry reject a null value, so NULL keeps the placeholder.
+function scalaLit(type: any, placeholder: string = 'example'): string {
+  const k = canonScalarKey(type)
+  if ('INTEGER' === k) return '1L'
+  if ('NUMBER' === k) return '1.0'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return 'java.util.List.of()'
+  if ('OBJECT' === k) return 'java.util.Map.of()'
+  return `"${placeholder}"`
+}
+
+
+// A list's required parameters as its match.
+function scalaListMatch(entity: any): string {
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? javaMapOf(items.map((it: any) => `${JSON.stringify(it.name)}, ${scalaLit(it.type)}`), 'java.util.')
+    : 'null'
+}
+
 
 export {
+  scalaLit,
+  scalaListMatch,
   cleanModel,
   mavenGroupId,
   jsonAppendLines,

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

@@ -5,7 +5,7 @@ import {
   File, Content, Folder,
 } from '@voxgig/sdkgen'
 
-import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions , deriveEntityNames, swiftSafeTypeName } from '@voxgig/sdkgen'
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions , deriveEntityNames, swiftTypeName, entityCollection } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -36,7 +36,7 @@ public struct ${typeName} {
   items.forEach((it: any) => {
     if (null == it || null == it.name) return
     const ident = swiftVarName(it.name)
-    if (seen.has(ident)) return
+    if ('' === ident || seen.has(ident)) return
     seen.add(ident)
     Content(propLine(it.name, it.type, !!it.optional))
   })
@@ -84,7 +84,7 @@ import Foundation
             const fields = (ent.fields ? each(ent.fields) : [])
               .filter((f: any) => f.a !== false)
 
-            const TypeName = swiftSafeTypeName(Name)
+            const TypeName = swiftTypeName(ent, entityCollection(model))
             emitStruct(
               `/// ${TypeName} is the typed data model for the ${ent.name} entity.`,
               TypeName,
@@ -92,7 +92,7 @@ import Foundation
             )
 
             const ops = ent.op || {}
-              ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+              ;['load', 'list', 'create', 'update', 'patch', 'remove'].forEach((opname: string) => {
                 if (null == ops[opname]) {
                   return
                 }

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

@@ -46,7 +46,7 @@ const Entity = cmp(function Entity(props: any) {
           // implementation (an override). Otherwise leave the base-class
           // method, which throws unsupportedOp at runtime.
           const opfrags =
-            (['load', 'list', 'create', 'update', 'remove']
+            (['load', 'list', 'create', 'update', 'patch', 'remove']
               .reduce((a: any, opname: string) =>
               (a['#' + camelify(opname) + 'Op'] =
                 !opnames.includes(opname) ?

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

@@ -6,6 +6,7 @@ import { swiftSecretsActive, swiftTargetDir, swiftTestDir } from './utility_swif
 import {
   cmp, each,
   File, Content, Copy, Folder, Fragment,
+  inactiveFeatureExcludes,
   pluginExcludes,
 } from '@voxgig/sdkgen'
 
@@ -65,7 +66,9 @@ const Main = cmp(async function Main(props: any) {
     Copy({
       from: 'tm/' + target.name + '/Sources/ProjectNameSDK',
       to: swiftTargetDir(model),
-      exclude: [...secretsSourceExcludes, ...pluginExcludes(model)],
+      exclude: [...secretsSourceExcludes,
+        ...inactiveFeatureExcludes(props.ctx$, target, 'tm/' + target.name + '/Sources/ProjectNameSDK'),
+        ...pluginExcludes(model)],
       replace: {
         ...props.ctx$.stdrep,
         ProjectName: model.const.Name,
@@ -77,7 +80,8 @@ const Main = cmp(async function Main(props: any) {
     Copy({
       from: 'tm/' + target.name + '/Tests/ProjectNameSDKTests',
       to: swiftTestDir(model),
-      exclude: secretsTestExcludes,
+      exclude: [...secretsTestExcludes,
+        ...inactiveFeatureExcludes(props.ctx$, target, 'tm/' + target.name + '/Tests/ProjectNameSDKTests')],
       replace: {
         ...props.ctx$.stdrep,
         ProjectName: model.const.Name,

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

@@ -100,7 +100,7 @@ private let optionSecret = "secret"` : ''
 private let headerAuth = ${swiftString(spec.name)}
 private let optionApikey = "apikey"${basicConst}
 private let notFound = "__NOTFOUND__"
-
+${authName('headerAuth', true)}
 func prepareAuthUtil(_ ctx: Context) throws -> Spec {
   guard let spec = ctx.spec else {
     throw ctx.makeError("auth_no_spec", "Expected context spec property to be defined.")
@@ -116,6 +116,13 @@ func prepareAuthUtil(_ ctx: Context) throws -> Spec {
     return spec
   }
 
+  let name = prepareAuthName(options)
+
+  // A credential left under the declared name would travel beside the renamed one.
+  if name != headerAuth {
+    headers.entries.removeValue(forKey: headerAuth)
+  }
+
   let apikey = getprop(.map(options), .string(optionApikey), .string(notFound))
 
   var skip = isNil(apikey)
@@ -124,13 +131,13 @@ func prepareAuthUtil(_ ctx: Context) throws -> Spec {
   }
 ${basicBlock(spec)}
   if skip {
-    headers.entries.removeValue(forKey: headerAuth)
+    headers.entries.removeValue(forKey: name)
   } else {
     var authPrefix = ""
     if let ap = gpath(options, "auth", "prefix").asString { authPrefix = ap }
     let apikeyVal = apikey.asString ?? ""
     // Empty prefix (raw apiKey credential) must not add a leading space.
-    headers.entries[headerAuth] = .string(authPrefix == "" ? apikeyVal : authPrefix + " " + apikeyVal)
+    headers.entries[name] = .string(authPrefix == "" ? apikeyVal : authPrefix + " " + apikeyVal)
   }
 
   return spec
@@ -162,7 +169,7 @@ function basicBlock(spec: AuthSpec): string {
     }
 
     if skip {
-      headers.entries.removeValue(forKey: headerAuth)
+      headers.entries.removeValue(forKey: name)
     } else {
       var authPrefix = ""
       if let ap = gpath(options, "auth", "prefix").asString { authPrefix = ap }
@@ -172,7 +179,7 @@ function basicBlock(spec: AuthSpec): string {
       // registration covers.
       ctx.utility!.cleanAdd(ctx, .string(b64))
       // Empty prefix (raw credential) must not add a leading space.
-      headers.entries[headerAuth] = .string(authPrefix == "" ? b64 : authPrefix + " " + b64)
+      headers.entries[name] = .string(authPrefix == "" ? b64 : authPrefix + " " + b64)
     }
 
     return spec
@@ -186,7 +193,7 @@ function renderQuery(spec: AuthSpec): string {
 private let queryAuth = ${swiftString(spec.name)}
 private let optionApikey = "apikey"
 private let notFound = "__NOTFOUND__"
-
+${authName('queryAuth', false)}
 func prepareAuthUtil(_ ctx: Context) throws -> Spec {
   guard let spec = ctx.spec else {
     throw ctx.makeError("auth_no_spec", "Expected context spec property to be defined.")
@@ -202,6 +209,13 @@ func prepareAuthUtil(_ ctx: Context) throws -> Spec {
     return spec
   }
 
+  let name = prepareAuthName(options)
+
+  // A credential left under the declared name would travel beside the renamed one.
+  if name != queryAuth {
+    query.entries.removeValue(forKey: queryAuth)
+  }
+
   let apikey = getprop(.map(options), .string(optionApikey), .string(notFound))
 
   var skip = isNil(apikey)
@@ -210,13 +224,13 @@ func prepareAuthUtil(_ ctx: Context) throws -> Spec {
   }
 
   if skip {
-    query.entries.removeValue(forKey: queryAuth)
+    query.entries.removeValue(forKey: name)
   } else {
     let apikeyVal = apikey.asString ?? ""
     // NO PREFIX IN A QUERY STRING. \`?${spec.name}=Bearer%20abc\` is not a
     // thing any API reads: the prefix is a header convention, so it is
     // dropped here deliberately rather than silently concatenated.
-    query.entries[queryAuth] = .string(apikeyVal)
+    query.entries[name] = .string(apikeyVal)
   }
 
   return spec
@@ -231,30 +245,21 @@ private let cookieHeader = "cookie"
 private let cookieAuth = ${swiftString(spec.name)}
 private let optionApikey = "apikey"
 private let notFound = "__NOTFOUND__"
-
-// The cookie header minus our own pair, every other cookie untouched.
-private func cookiesWithoutCred(_ headers: VMap) -> String {
+${authName('cookieAuth', false)}
+// The cookie header minus the named pair, every other cookie untouched.
+private func cookiesWithoutCred(_ headers: VMap, _ name: String) -> String {
   guard let existing = headers.entries[cookieHeader]?.asString, existing != "" else {
     return ""
   }
 
-  var kept: [String] = []
-  for part in existing.split(separator: ";", omittingEmptySubsequences: false) {
-    let piece = part.trimmingCharacters(in: .whitespaces)
-    if piece == "" || piece == cookieAuth || piece.hasPrefix(cookieAuth + "=") {
-      continue
-    }
-    kept.append(piece)
-  }
-
-  return kept.joined(separator: "; ")
+  return cookieKeep(existing, [name]).joined(separator: "; ")
 }
 
-// Set (non-nil) or remove (nil) our pair, leaving every other cookie in
-// place. Deleting the whole header to remove one pair would drop cookies
+// Set (non-nil) or remove (nil) the named pair, leaving every other cookie
+// in place. Deleting the whole header to remove one pair would drop cookies
 // this SDK never set.
-private func applyCookie(_ headers: VMap, _ value: String?) {
-  let rest = cookiesWithoutCred(headers)
+private func applyCookie(_ headers: VMap, _ name: String, _ value: String?) {
+  let rest = cookiesWithoutCred(headers, name)
 
   guard let value = value else {
     if rest == "" {
@@ -265,7 +270,7 @@ private func applyCookie(_ headers: VMap, _ value: String?) {
     return
   }
 
-  let pair = cookieAuth + "=" + value
+  let pair = name + "=" + value
   headers.entries[cookieHeader] = .string(rest == "" ? pair : rest + "; " + pair)
 }
 
@@ -280,10 +285,17 @@ func prepareAuthUtil(_ ctx: Context) throws -> Spec {
   // Public APIs that need no auth omit the options.auth block entirely.
   let auth = getprop(.map(options), .string("auth"))
   if isNil(auth) {
-    applyCookie(headers, nil)
+    applyCookie(headers, cookieAuth, nil)
     return spec
   }
 
+  let name = prepareAuthName(options)
+
+  // A credential left under the declared name would travel beside the renamed one.
+  if name != cookieAuth {
+    applyCookie(headers, cookieAuth, nil)
+  }
+
   let apikey = getprop(.map(options), .string(optionApikey), .string(notFound))
 
   var skip = isNil(apikey)
@@ -292,11 +304,11 @@ func prepareAuthUtil(_ ctx: Context) throws -> Spec {
   }
 
   if skip {
-    applyCookie(headers, nil)
+    applyCookie(headers, name, nil)
   } else {
     // NO PREFIX IN A COOKIE either - a cookie carries a bare \`name=value\`
     // pair, not a header's scheme-prefixed credential.
-    applyCookie(headers, apikey.asString ?? "")
+    applyCookie(headers, name, apikey.asString ?? "")
   }
 
   return spec
@@ -305,6 +317,21 @@ func prepareAuthUtil(_ ctx: Context) throws -> Spec {
 }
 
 
+// The client's `auth.name` option, when set, replaces the declared name; a
+// header name travels lower-cased.
+function authName(declared: string, header: boolean): string {
+  return `
+// The client's auth.name option, when set, replaces the name the API declares.
+private func prepareAuthName(_ options: VMap) -> String {
+  if let name = gpath(options, "auth", "name").asString, name != "" {
+    return ${header ? 'name.lowercased()' : 'name'}
+  }
+  return ${declared}
+}
+`
+}
+
+
 export {
   PrepareAuth
 }

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

@@ -1,18 +1,19 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
   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).
 
 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)'
@@ -30,6 +31,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'list(nil, nil)',     desc: 'List entities, optionally matching the given criteria.' },
   create: { method: 'create(data, nil)',  desc: 'Create a new entity with the given data.' },
   update: { method: 'update(data, nil)',  desc: 'Update an existing entity.' },
+  patch:  { method: 'patch(data, nil)',   desc: 'Change part of an existing entity.' },
   remove: { method: 'remove(match, nil)', desc: 'Remove the matching entity.' },
 }
 
@@ -55,6 +57,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)
     // Sanitise the local variable name — a camelCased Swift keyword gets a
@@ -112,7 +116,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.
@@ -134,17 +138,17 @@ let ${eVar} = try client.${accessor}().load(${loadArg}, nil)
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`swift
-let ${eVar}List = try client.${accessor}().list(nil, nil)
+let ${eVar}List = try client.${accessor}().list(${swiftListMatch(entity)}, nil)
 \`\`\`
 
 `)
     }
 
-    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 literal.

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

@@ -1,17 +1,18 @@
 
-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,
   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)'
@@ -39,23 +40,36 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'nil'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `VMap([("${idF}", .string("test01"))])` : 'nil'
-  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+  } else if (exampleEntity && 'list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length) {
+    const chosen = requiredItems(exampleEntity, 'list')
+    testArg = `VMap([${chosen.map((it: any) =>
+      `(${swiftString(it.name)}, ${swiftLit(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 = `VMap([${chosen.map((it: any) =>
-      `("${it.name}", ${swiftLit(it.type)})`).join(', ')}])`
+      `(${swiftString(it.name)}, ${swiftLit(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 throws on error;
-// call data() for the record.
+  const testModeExample = 'list' === primaryOp
+    ? `// list returns a Value list of entities, one per mock record; it throws on error.
+let ${eVar}List = try client.${eName}().list(${testArg}, nil)
+for ${eVar}Item in ${eVar}List.asList?.items ?? [] {
+    if let ${eVar}Entity = ${eVar}Item.asNative as? Entity {
+        print(${eVar}Entity.data())
+    }
+}`
+    : primaryOp
+    ? `// Entity ops return the entity, wrapped in a Value; they throw on error.
 let ${eVar} = try client.${eName}().${primaryOp}(${testArg}, nil)
-// ${eVar} holds the mock response record
-print(${eVar})`
+// data() reads the entity's mock record
+if let ${eVar}Entity = ${eVar}.asNative as? Entity {
+    print(${eVar}Entity.data())
+}`
     : `let result = client.direct(VMap([
     ("path", .string("/api/resource")),
     ("method", .string("GET")),

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

@@ -29,11 +29,11 @@ cd swift && swift build
   // generated SDK is a dependency-free SwiftPM package (Foundation + the
   // vendored Voxgig Struct port), so install it from the git release tag or a
   // local source checkout and build with SwiftPM.
-  const { releasesUrl } = repoInfo(model)
+  const { hostName, tagsUrl } = repoInfo(model)
   Content(`This package is not yet published to a SwiftPM registry. The generated SDK
 is a dependency-free SwiftPM package (Foundation only, plus the vendored
-Voxgig Struct port). Depend on it from the GitHub release tag
-(\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})) by adding it to
+Voxgig Struct port). Depend on it from the ${hostName} release tag
+(\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})) by adding it to
 your \`Package.swift\`:
 
 \`\`\`swift

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -9,7 +9,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
@@ -34,7 +34,7 @@ The ${target.title} SDK for the ${model.Name} API — an entity-oriented client
   // 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/swift/ReadmeModel_swift.ts

@@ -23,13 +23,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) throws -> Value` | Load a single entity by match criteria. Throws on error. |',
-    list: '| `list` | `(reqmatch, ctrl) throws -> Value` | List entities matching the criteria (a Value list). Throws on error. |',
-    create: '| `create` | `(reqdata, ctrl) throws -> Value` | Create a new entity. Throws on error. |',
-    update: '| `update` | `(reqdata, ctrl) throws -> Value` | Update an existing entity. Throws on error. |',
-    remove: '| `remove` | `(reqmatch, ctrl) throws -> Value` | Remove an entity. Throws on error. |',
+    load: '| `load` | `(reqmatch, ctrl) throws -> Value` | Load a single entity by match criteria, and return it. Throws on error. |',
+    list: '| `list` | `(reqmatch, ctrl) throws -> Value` | List entities matching the criteria, one per record. Throws on error. |',
+    create: '| `create` | `(reqdata, ctrl) throws -> Value` | Create a new entity, and return it. Throws on error. |',
+    update: '| `update` | `(reqdata, ctrl) throws -> Value` | Update an existing entity, and return it. Throws on error. |',
+    patch: '| `patch` | `(reqdata, ctrl) throws -> Value` | Change part of an existing entity, and return it. Throws on error. |',
+    remove: '| `remove` | `(reqmatch, ctrl) throws -> Value` | Remove an entity, and return it marked as deleted. Throws 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)
@@ -92,9 +93,10 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the ENTITY (call data() for the record) (a \`Value\` map for
-single-entity ops, a \`Value\` list for \`list\`) and throw on error. Wrap
-calls in \`do\`/\`catch\` to handle failures.
+Entity operations return the entity, and \`list\` a \`Value\` list of entities,
+one per record; each entity comes wrapped in a native \`Value\`, which
+\`asNative as? Entity\` unwraps, and its \`data()\` reads the record. They
+throw on error, so wrap calls in \`do\`/\`catch\` to handle failures.
 
 The \`direct()\` escape hatch never throws — it returns a result \`VMap\` you
 branch on via \`result.entries["ok"]\`:

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

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { swiftVarName } from './utility_swift'
+import { swiftVarName, swiftListMatch } from './utility_swift'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -37,6 +37,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   // means all values live in a `VMap` of `Value`.
   const 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)'
@@ -84,14 +85,17 @@ let client = ${SDK}()
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list(nil, nil)\` returns a \`Value\` list of records and throws on error —
-iterate its items.
+\`list(nil, nil)\` returns a \`Value\` list of entities, one per record, and
+throws on error; \`asNative as? Entity\` unwraps an item, and its \`data()\`
+reads the record.
 
 \`\`\`swift
 do {
-    let ${eVar}List = try client.${accessor}().list(nil, nil)
-    for ${eVar} in ${eVar}List.asList?.items ?? [] {
-        print(${eVar})
+    let ${eVar}List = try client.${accessor}().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())
+        }
     }
 }
 catch {
@@ -130,7 +134,9 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 \`\`\`swift
 do {
     let ${neVar} = try client.${neAccessor}().load(VMap([${neMatch.join(', ')}]), nil)
-    print(${neVar})
+    if let ${neVar}Entity = ${neVar}.asNative as? Entity {
+        print(${neVar}Entity.data())
+    }
 }
 catch {
     print("load failed: \\(error)")
@@ -158,7 +164,9 @@ catch {
 \`\`\`swift
 do {
     let ${eVar} = try client.${accessor}().load(${loadArg}, nil)
-    print(${eVar})
+    if let ${eVar}Entity = ${eVar}.asNative as? Entity {
+        print(${eVar}Entity.data())
+    }
 }
 catch {
     print("load failed: \\(error)")
@@ -187,7 +195,8 @@ catch {
       return it && it.type
     }
 
-    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
 
 \`\`\`swift
@@ -204,6 +213,14 @@ let created = try client.${accessor}().create(VMap([${examplePairs('create').joi
         Content(`// Update — supply the id in the match/data
 _ = try client.${accessor}().update(VMap([${updatePairs.join(', ')}]), nil)
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`("${idF}", ${swiftLit(idParamType('patch'), 'example_id')})`] : [])
+          .concat(examplePairs('patch'))
+        Content(`// Patch — sends only the fields given
+_ = try client.${accessor}().patch(VMap([${patchPairs.join(', ')}]), nil)
+
 `)
       }
       if (opnames.includes('remove')) {