@voxgig/sdkgen 4.34.1 → 4.34.2

package/src/helpers/opExample.ts

@@ -1,9 +1,9 @@
 
 import { each } from 'jostraca'
-import { canonKey } from './canonType'
-import { opRequestShape, opParams, entityIdField } from './opShape'
+import { canonScalarKey } from './canonType'
+import { opRequestShape, opParams, selectablePoints, pointRequires } from './opShape'
 
-import { phpEntityAccessor } from './naming'
+import { phpEntityAccessor, jsKey, luaKey } from './naming'
 
 
 type ExampleLang = 'ts' | 'js' | 'py' | 'php' | 'rb' | 'lua' | 'go'
@@ -11,23 +11,35 @@ type ExampleLang = 'ts' | 'js' | 'py' | 'php' | 'rb' | 'lua' | 'go'
 // The languages a literal is written in: the call languages, and JSON.
 type LiteralLang = ExampleLang | 'json'
 
+// The call languages, in the order a reader is likeliest to want one.
+const EXAMPLE_LANGS: ExampleLang[] = ['ts', 'js', 'py', 'go', 'php', 'rb', 'lua']
+
+
+// The language of a section shared by every target: its own, else TypeScript.
+function helperLang(target: string): ExampleLang {
+  return EXAMPLE_LANGS.includes(target as ExampleLang) ? target as ExampleLang : 'ts'
+}
+
 
 function cap(s: string): string {
   return s.charAt(0).toUpperCase() + s.slice(1)
 }
 
 
+const NULL_LIT: Record<LiteralLang, string> = {
+  ts: 'null', js: 'null', py: 'None', php: 'null', rb: 'nil', lua: 'nil', go: 'nil', json: 'null',
+}
+
+
 // A type-correct literal for a canonical type sentinel, in the target language.
-function litFor(lang: LiteralLang, type: any): string {
-  const k = canonKey(type)
+function litFor(lang: LiteralLang, type: any, text: string = 'example'): string {
+  const k = canonScalarKey(type)
+  if ('NULL' === k) return NULL_LIT[lang]
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'py' === lang ? 'True' : ('rb' === lang ? 'true' : 'true')
   if ('ARRAY' === k) return ('lua' === lang) ? '{}' : ('go' === lang ? '[]any{}' : '[]')
-  // PHP has no `{}` literal — `["data" => {}]` is a parse error, which took
-  // the whole generated README down for any entity with an object-typed
-  // writable field (dymo-api-introduction, html-creator). Arrays serve as both
-  // list and map, so `[]` is the empty object too. Ruby and Lua likewise want
-  // their own empty-hash/table spelling rather than JS's.
+  // PHP has no `{}` literal (`["data" => {}]` does not parse) and its arrays
+  // serve as maps; Ruby and Lua spell an empty map their own way too.
   if ('OBJECT' === k) {
     if ('go' === lang) return 'map[string]any{}'
     if ('php' === lang) return '[]'
@@ -36,40 +48,51 @@ function litFor(lang: LiteralLang, type: any): string {
     if ('py' === lang) return '{}'
     return '{}'
   }
-  return '"example"'
+  return `"${text}"`
 }
 
 
 function idLiteral(ent: any, op: string, idF: string | null): string {
   if (null == idF) return '"example_id"'
   const item = opRequestShape(ent, op).items.find((it: any) => it.name === idF)
-  const k = canonKey(item && item.type)
+  const k = canonScalarKey(item && item.type)
   return ('INTEGER' === k || 'NUMBER' === k) ? '1' : '"example_id"'
 }
 
 
-const JS_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
-const LUA_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/
-
 function litPair(lang: LiteralLang, name: string, value: string): string {
   switch (lang) {
-    case 'py': return `"${name}": ${value}`
-    case 'php': return `"${name}" => ${value}`
-    case 'rb': return `"${name}" => ${value}`
-    case 'go': return `"${name}": ${value}`
+    case 'py': return `${JSON.stringify(name)}: ${value}`
+    case 'php': return `"${name.replace(/[\\"$]/g, '\\$&')}" => ${value}`
+    case 'rb': return `${JSON.stringify(name).replace(/#(?=[{$@])/g, '\\#')} => ${value}`
+    case 'go': return `${JSON.stringify(name)}: ${value}`
     case 'json': return `${JSON.stringify(name)}: ${value}`
-    case 'lua': return LUA_IDENT.test(name) ?
-      `${name} = ${value}` : `["${name}"] = ${value}`
-    default: return JS_IDENT.test(name) ?
-      `${name}: ${value}` : `'${name}': ${value}`
+    case 'lua': return `${luaKey(name)} = ${value}`
+    default: return `${jsKey(name)}: ${value}`
+  }
+}
+
+
+// The members an example call must give. Points of one route that each need
+// a selector of their own share none, so the example takes the point that
+// needs fewest when no point is reached by those every point needs.
+function requiredItems(ent: any, op: string): any[] {
+  const needed = (e: any) => opRequestShape(e, op).items.filter((it: any) => !it.optional)
+  const items = needed(ent)
+  const given = items.map((it: any) => it.name)
+  const points = selectablePoints(ent?.op?.[op])
+  if (points.length < 2 || points.some((pt: any) => pointRequires(pt).every((n) => given.includes(n)))) {
+    return items
   }
+  const fewest = points.reduce((a: any, b: any) => pointRequires(b).length < pointRequires(a).length ? b : a)
+  return needed({ ...ent, op: { ...ent.op, [op]: { ...ent.op[op], points: [fewest] } } })
 }
 
 
 function matchArg(
   lang: LiteralLang, ent: any, op: string, idF: string | null, idLit: string
 ): string {
-  const items = opRequestShape(ent, op).items.filter((it: any) => !it.optional)
+  const items = requiredItems(ent, op)
   if (0 === items.length) return 'go' === lang ? 'nil' : ('json' === lang ? '{}' : '')
   const pairs = items.map((it: any) =>
     litPair(lang, it.name, it.name === idF ? idLit : litFor(lang, it.type)))
@@ -82,6 +105,45 @@ function matchArg(
 }
 
 
+// Java's Map.of has an overload per pair count up to ten, and Map.ofEntries takes any.
+function javaMap(count: number, pkg = ''): { open: string, pair: (kv: string) => string } {
+  const many = 10 < count
+  return {
+    open: pkg + (many ? 'Map.ofEntries(' : 'Map.of('),
+    pair: (kv: string) => many ? pkg + 'Map.entry(' + kv + ')' : kv,
+  }
+}
+
+
+function javaMapOf(pairs: string[], pkg = ''): string {
+  const map = javaMap(pairs.length, pkg)
+  return map.open + pairs.map(map.pair).join(', ') + ')'
+}
+
+
+// A list's required route and query parameters.
+function listMatchArg(lang: LiteralLang, ent: any): string {
+  return matchArg(lang, ent, 'list', null, '')
+}
+
+
+// A test-mode list call's pairs and the record seeded for it: the mock gives a
+// seeded record its key as `id`, so `id` and the load key are sent as that key.
+function seededList(lang: LiteralLang, ent: any, idF: string | null, key: string):
+  { call: string[], record: string[] } {
+  const items = [...requiredItems(ent, 'list')]
+    .sort((a: any, b: any) => (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+  const lit = (it: any): string =>
+    litFor(lang, it.type, it.name === idF || 'id' === it.name ? key : 'example')
+  const record = new Map<string, string>(null == idF ? [] : [[idF, `"${key}"`]])
+  items.forEach((it: any) => record.set(it.name, 'id' === it.name ? `"${key}"` : lit(it)))
+  return {
+    call: items.map((it: any) => litPair(lang, it.name, lit(it))),
+    record: [...record].map(([name, value]) => litPair(lang, name, value)),
+  }
+}
+
+
 // An update or patch addressed only by id and route also changes a field.
 function dataArg(lang: LiteralLang, ent: any, op: string, idF: string | null): string {
   const routed = new Set(opParams(ent?.op?.[op]).map((p: any) => p.n))
@@ -140,7 +202,9 @@ function primaryOpCall(
   else { factory = `client.${eName}()`; sep = '.' }
 
   let arg: string
-  if (isList || isMatch) {
+  if (isList) {
+    arg = listMatchArg(lang, ent)
+  } else if (isMatch) {
     arg = matchArg(lang, ent, op, idF, idLit)
   } else if (isData) {
     arg = dataArg(lang, ent, op, idF)
@@ -158,11 +222,19 @@ function primaryOpCall(
 
 
 export {
+  EXAMPLE_LANGS,
+  helperLang,
   primaryOpCall,
   idLiteral,
+  requiredItems,
   matchArg,
+  listMatchArg,
+  seededList,
   dataArg,
+  javaMap,
+  javaMapOf,
   litFor,
+  litPair,
 }
 
 export type {

package/src/helpers/opShape.ts

@@ -179,17 +179,31 @@ function opNeedsAction(op: any): boolean {
 }
 
 
-function opParams(op: any): any[] {
-  let points: any[] = op && op.points ? each(op.points) : []
-
+// The points a call can select: an action's only where every point is one.
+function selectablePoints(op: any): any[] {
+  const points: any[] = op && op.points ? each(op.points) : []
   const canonical = points.filter((pt: any) =>
     null == (pt && pt.q && pt.q['$action']))
-  if (0 < canonical.length) {
-    points = canonical
-  }
+  return 0 < canonical.length ? canonical : points
+}
+
+
+// The route and query parameters a point requires.
+function pointRequires(pt: any): string[] {
+  const params = [
+    ...(pt && pt.g && pt.g.params ? each(pt.g.params) : []),
+    ...(pt && pt.g && pt.g.query ? each(pt.g.query) : []),
+  ]
+  return params.filter((p: any) => p && null != p.n && false !== p.r).map((p: any) => p.n)
+}
+
+
+function opParams(op: any): any[] {
+  const points = selectablePoints(op)
 
-  const seen: Record<string, any> = {}
-  const requiredOnAll: Record<string, boolean> = {}
+  // Keyed by parameter name, which may be `__proto__`.
+  const seen: Record<string, any> = Object.create(null)
+  const requiredOnAll: Record<string, boolean> = Object.create(null)
   const out: any[] = []
 
   points.forEach((pt: any, pointIndex: number) => {
@@ -198,7 +212,7 @@ function opParams(op: any): any[] {
     const pathParams = pt && pt.g && pt.g.params ? each(pt.g.params) : []
     const queryParams = pt && pt.g && pt.g.query ? each(pt.g.query) : []
     const params = [...pathParams, ...queryParams]
-    const requiredHere: Record<string, boolean> = {}
+    const requiredHere: Record<string, boolean> = Object.create(null)
     params.forEach((p: any) => {
       if (p && null != p.n) {
         requiredHere[p.n] = false !== p.r
@@ -679,6 +693,8 @@ export {
   entityCollection,
   opTypeName,
   opParams,
+  selectablePoints,
+  pointRequires,
   opReachable,
   opNeedsAction,
   ownPoint,

package/src/sdkgen.ts

@@ -17,7 +17,7 @@ import type {
   ActionResult,
 } from './types'
 
-import { SdkGenError, requirePath, isAuthActive, resolveAuthPrefix, resolveAuthIn, resolveAuthName, isAuthSuppressed, isHttpBasicAuth,
+import { SdkGenError, requirePath, isAuthActive, resolveAuthPrefix, resolveAuthIn, resolveAuthName, credentialPlacement, isAuthSuppressed, isHttpBasicAuth,
   CONFIG_DATA_THRESHOLD, CONFIG_REPR_VALUES, isConfigData, configRepr,
   configReprSetting, configDefinition, clean, rawStringLiteral } from './utility'
 
@@ -72,11 +72,14 @@ import { canonToType, canonToDtype, canonKey, canonScalarKey } from './helpers/c
 import { canonToSpec, entityDataSpec, entityOpSpec, entitySpecs } from './helpers/canonSpec'
 import { optionSpec, featureOptionSpec, entitySpecMap } from './helpers/optspec'
 import { OP_SUFFIX, opTypeName, opParams, opReachable, opNeedsAction, ownPoint, opActions, entityActions, entityPath, opRequestShape, entityIdField, entityDataIdField, entityOps, invalidRequest, entityPrimaryOp, pickExampleEntity, entityClassName, entityTypeCollisions, warnEntityTypeCollisions, ungeneratedOps, warnUngeneratedOps, deriveEntityNames, entityCollection } from './helpers/opShape'
-import { isReservedName, safeVarName, exampleVarName, phpEntityAccessor, entityCacheField, isRbCoreConstant, isRbSdkConstant, rbSafeTypeName, isSwiftSdkType, swiftSafeTypeName, isPhpReservedType, isPhpSdkClass, phpSafeTypeName, isTsReservedType, isTsSdkType, tsSafeTypeName, isElixirReservedType, elixirSafeTypeName, elixirTypeNames, elixirTypeName, elixirAccessorNames, elixirAccessor, tsTypeName, rbTypeName, phpTypeName, swiftTypeName, jsProp, jsOptProp, jsKey, luaKey, prefixLeadingDigit } from './helpers/naming'
+import { isReservedName, safeVarName, exampleVarName, phpEntityAccessor, entityCacheField, isRbCoreConstant, isRbSdkConstant, rbSafeTypeName, isSwiftSdkType, swiftSafeTypeName, isPhpReservedType, isPhpSdkClass, phpSafeTypeName, isTsReservedType, isTsSdkType, tsSafeTypeName, isElixirReservedType, elixirSafeTypeName, elixirTypeNames, elixirTypeName, elixirAccessorNames, elixirAccessor, tsTypeName, rbTypeName, phpTypeName, swiftTypeName, jsProp, jsOptProp, jsKey, jsQuote, luaKey, prefixLeadingDigit } from './helpers/naming'
 import { serverVariables, hasServerVariables, serverVarEnv } from './helpers/serverVars'
 import { mcpTools, MCP_READ_OPS, MCP_WRITE_OPS } from './helpers/mcpTools'
 import type { McpTool } from './helpers/mcpTools'
-import { primaryOpCall, idLiteral, matchArg, dataArg, litFor } from './helpers/opExample'
+import {
+  primaryOpCall, idLiteral, requiredItems, matchArg, listMatchArg, seededList, dataArg, javaMap, javaMapOf, litFor,
+  litPair,
+} from './helpers/opExample'
 import type { ExampleLang, LiteralLang } from './helpers/opExample'
 import { liveStrict, liveStrictNote, liveFlowNeeds } from './helpers/testPolicy'
 import type { LiveFlowNeeds } from './helpers/testPolicy'
@@ -1091,6 +1094,7 @@ export {
   resolveAuthPrefix,
   resolveAuthIn,
   resolveAuthName,
+  credentialPlacement,
   isAuthSuppressed,
   isHttpBasicAuth,
   CONFIG_DATA_THRESHOLD,
@@ -1191,9 +1195,15 @@ export {
   liveFlowNeeds,
   primaryOpCall,
   idLiteral,
+  requiredItems,
   matchArg,
+  listMatchArg,
+  seededList,
+  javaMap,
+  javaMapOf,
   dataArg,
   litFor,
+  litPair,
   featureOf,
   availableFeatures,
   findFeatureSources,
@@ -1223,6 +1233,7 @@ export {
   jsProp,
   jsOptProp,
   jsKey,
+  jsQuote,
   luaKey,
   prefixLeadingDigit,
 

package/src/utility.ts

@@ -84,6 +84,18 @@ function resolveAuthName(model: any): string {
 }
 
 
+// Where the client sends the API key, when that is not the Authorization header.
+function credentialPlacement(model: any): string {
+  if (!isAuthActive(model)) return ''
+  const where = resolveAuthIn(model)
+  const name = resolveAuthName(model)
+  if ('query' === where) return `The client sends the API key as the \`${name}\` query parameter.`
+  if ('cookie' === where) return `The client sends the API key as the \`${name}\` cookie.`
+  return 'authorization' === name.toLowerCase() ? '' :
+    `The client sends the API key in the \`${name}\` header.`
+}
+
+
 function isHttpBasicAuth(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })
@@ -161,6 +173,7 @@ export {
   resolveAuthPrefix,
   resolveAuthIn,
   resolveAuthName,
+  credentialPlacement,
   isAuthSuppressed,
   resolveAuthExchange,
   isHttpBasicAuth,
@@ -272,7 +285,21 @@ const SPEC_FACTS: Record<string, (model: any) => any> = {
 const ROUTED_KINDS = ['header', 'cookie', 'query']
 
 
-function withPointParts(op: any, fields: string[] = []): any {
+// The names a point's body keeps when a routed argument shares one: those its
+// JSON request body declares (`bf`), every active field where the model
+// records no `bf`, and never a field the entity marks read-only.
+function bodyFieldNames(pt: any, fields: any[]): string[] {
+  if (false === pt.bf) {
+    return []
+  }
+  const readOnly = fields.filter((f: any) => true === f.ro).map((f: any) => f.n)
+  const names: string[] = Array.isArray(pt.bf) ? pt.bf :
+    fields.filter((f: any) => false !== f.a).map((f: any) => f.n)
+  return names.filter((name) => !readOnly.includes(name))
+}
+
+
+function withPointParts(op: any, fields: any[] = []): any {
   if (null == op) {
     return op
   }
@@ -283,12 +310,12 @@ function withPointParts(op: any, fields: string[] = []): any {
       ...o,
       points: each(o.points).filter((pt: any) => false !== pt?.a).map((pt: any) => {
         if (null == pt) return pt
+        const kept = bodyFieldNames(pt, fields)
         const args = Object.fromEntries(Object.entries(pt.g || {}).map(([kind, values]) =>
           [kind, each(values as any).filter((arg: any) => false !== arg.a).map((arg: any) => ({
             name: arg.n, orig: arg.or, type: arg.t, kind: arg.k,
             reqd: arg.r, example: arg.ex,
-            // Also a field of the entity, so the body keeps it.
-            ...(ROUTED_KINDS.includes(kind) && fields.includes(arg.n) ? { field: true } : {}),
+            ...(ROUTED_KINDS.includes(kind) && kept.includes(arg.n) ? { field: true } : {}),
           }))]))
         // Runtime hooks expose descriptive names independently of the model schema.
         return {
@@ -332,7 +359,7 @@ function configDefinition(model: any, targetname?: string): { def: any, json: st
       })),
       id: e.id,
       name: e.name,
-      op: withPointParts(e.op, fields.map((f: any) => f.n)),
+      op: withPointParts(e.op, each(e.fields || {})),
       relations: e.relations,
     }, true)
     entityStubs[e.name] = {}