@voxgig/sdkgen 4.2.0 → 4.2.1

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -61,7 +61,7 @@ client = ${ctor}
     // placeholder (the doc test EXECUTES these blocks, so a comment
     // placeholder would not parse).
     const rbLit = (type: any, placeholder: string = 'example'): string => {
-      const k = canonKey(type)
+      const k = canonScalarKey(type)
       if ('INTEGER' === k || 'NUMBER' === k) return '1'
       if ('BOOLEAN' === k) return 'true'
       if ('ARRAY' === k) return '[]'

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,7 +11,7 @@ import {
 // is EXECUTED by the doc test, so it must carry a real value per field.
 // Strings render the quoted placeholder.
 function rbLit(type: any, placeholder: string = 'example'): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '[]'

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,7 +13,7 @@ import {
 // placeholder (the doc test EXECUTES this block, so a comment placeholder
 // would break it).
 function rbLit(type: any, placeholder: string = 'example'): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '[]'

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,7 +10,7 @@ import {
 
 // A type-correct Ruby literal for a field's canonical type.
 function rbLit(type: any): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '[]'

package/project/.sdk/src/cmp/rust/ReadmeEntity_rust.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,7 +13,7 @@ import { rustVarName } from './utility_rust'
 
 // A type-correct rust expression constructing a voxgig struct Value.
 function rustLit(type: any, placeholder: string = 'example'): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
   if ('BOOLEAN' === k) return 'Value::Bool(true)'
   if ('ARRAY' === k) return 'Value::empty_list()'

package/project/.sdk/src/cmp/rust/ReadmeHowto_rust.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -12,7 +12,7 @@ import { crateIdent, rustVarName } from './utility_rust'
 
 // A type-correct rust expression constructing a voxgig struct Value.
 function rustLit(type: any): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
   if ('BOOLEAN' === k) return 'Value::Bool(true)'
   if ('ARRAY' === k) return 'Value::empty_list()'

package/project/.sdk/src/cmp/rust/ReadmeQuick_rust.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityDataIdField, entityOps } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -36,7 +36,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   // A type-correct rust expression constructing a voxgig struct Value.
   const rustLit = (type: any, placeholder: string = 'example'): string => {
-    const k = canonKey(type)
+    const k = canonScalarKey(type)
     if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
     if ('BOOLEAN' === k) return 'Value::Bool(true)'
     if ('ARRAY' === k) return 'Value::empty_list()'

package/project/.sdk/src/cmp/rust/ReadmeRef_rust.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,7 +13,7 @@ import { crateIdent, rustVarName } from './utility_rust'
 
 // A type-correct rust expression constructing a voxgig struct Value.
 function rustLit(type: any, placeholder: string = 'example'): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
   if ('BOOLEAN' === k) return 'Value::Bool(true)'
   if ('ARRAY' === k) return 'Value::empty_list()'

package/project/.sdk/src/cmp/rust/ReadmeTopQuick_rust.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,7 +14,7 @@ import { crateIdent, rustVarName } from './utility_rust'
 // param. Strings render the quoted placeholder; numeric/boolean/array/object
 // render a typed literal.
 function rustLit(type: any, placeholder: string = 'example'): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
   if ('BOOLEAN' === k) return 'Value::Bool(true)'
   if ('ARRAY' === k) return 'Value::empty_list()'

package/project/.sdk/src/cmp/rust/ReadmeTopTest_rust.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,7 +13,7 @@ import { crateIdent, rustVarName } from './utility_rust'
 // A type-correct rust expression constructing a voxgig struct Value for a
 // field's canonical type.
 function rustLit(type: any): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
   if ('BOOLEAN' === k) return 'Value::Bool(true)'
   if ('ARRAY' === k) return 'Value::empty_list()'

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,7 +13,7 @@ import { scalaVarName } from './utility_scala'
 
 // A type-correct Scala literal for a field's canonical type.
 function scalaLit(type: any, placeholder: string = 'example'): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k) return '1L'
   if ('NUMBER' === k) return '1.0'
   if ('BOOLEAN' === k) return 'true'

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,7 +11,7 @@ import { scalaVarName } from './utility_scala'
 
 // A type-correct Scala literal for a field's canonical type.
 function scalaLit(type: any): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k) return '1L'
   if ('NUMBER' === k) return '1.0'
   if ('BOOLEAN' === k) return 'true'

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityOps } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityOps } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -35,7 +35,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   // A type-correct Scala literal for a param — the loose object model means
   // all values live in a java.util.Map[String, Object].
   const scalaLit = (type: any, placeholder: string = 'example'): string => {
-    const k = canonKey(type)
+    const k = canonScalarKey(type)
     if ('INTEGER' === k) return '1L'
     if ('NUMBER' === k) return '1.0'
     if ('BOOLEAN' === k) return 'true'

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,7 +13,7 @@ import { scalaVarName } from './utility_scala'
 
 // A type-correct Scala literal for a field's canonical type.
 function scalaLit(type: any, placeholder: string = 'example'): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k) return '1L'
   if ('NUMBER' === k) return '1.0'
   if ('BOOLEAN' === k) return 'true'

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,7 +14,7 @@ import { scalaVarName, scalaPackage } from './utility_scala'
 // render a typed literal; strings render the quoted placeholder. The SDK's
 // loose object model means all values live in java.util.Map[String, Object].
 function scalaLit(type: any, placeholder: string = 'example'): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k) return '1L'
   if ('NUMBER' === k) return '1.0'
   if ('BOOLEAN' === k) return 'true'

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,7 +11,7 @@ import { scalaVarName } from './utility_scala'
 
 // A type-correct Scala literal for a field's canonical type.
 function scalaLit(type: any): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k) return '1L'
   if ('NUMBER' === k) return '1.0'
   if ('BOOLEAN' === k) return 'true'

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,7 +13,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 = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k) return '.int(1)'
   if ('NUMBER' === k) return '.double(1.0)'
   if ('BOOLEAN' === k) return '.bool(true)'

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,7 +11,7 @@ import { swiftVarName } from './utility_swift'
 
 // A type-correct Swift `Value` literal for a field's canonical type.
 function swiftLit(type: any): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k) return '.int(1)'
   if ('NUMBER' === k) return '.double(1.0)'
   if ('BOOLEAN' === k) return '.bool(true)'

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityOps } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityOps } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -36,7 +36,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   // A type-correct Swift `Value` literal for a param — the loose object model
   // means all values live in a `VMap` of `Value`.
   const swiftLit = (type: any, placeholder: string = 'example'): string => {
-    const k = canonKey(type)
+    const k = canonScalarKey(type)
     if ('INTEGER' === k) return '.int(1)'
     if ('NUMBER' === k) return '.double(1.0)'
     if ('BOOLEAN' === k) return '.bool(true)'

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,7 +13,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 = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k) return '.int(1)'
   if ('NUMBER' === k) return '.double(1.0)'
   if ('BOOLEAN' === k) return '.bool(true)'

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,7 +14,7 @@ import { swiftVarName } from './utility_swift'
 // object params render a typed literal; strings render the quoted placeholder.
 // 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 = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k) return '.int(1)'
   if ('NUMBER' === k) return '.double(1.0)'
   if ('BOOLEAN' === k) return '.bool(true)'

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,7 +11,7 @@ import { swiftVarName } from './utility_swift'
 
 // A type-correct Swift `Value` literal for a field's canonical type.
 function swiftLit(type: any): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k) return '.int(1)'
   if ('NUMBER' === k) return '.double(1.0)'
   if ('BOOLEAN' === k) return '.bool(true)'

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

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 
 import {
   canonKey,
+  canonScalarKey,
   each,
 } from '@voxgig/sdkgen'
 
@@ -49,7 +50,12 @@ function paramCanonType(entity: any, op: any, paramName: string): unknown {
 // string is not assignable to `any[]` / `Record<string, any>`), everything
 // else (STRING, unknown, missing) as the quoted `placeholder`.
 function exampleValue(entity: any, op: any, paramName: string, placeholder: string): string {
-  const key = canonKey(paramCanonType(entity, op, paramName))
+  // canonScalarKey, not canonKey: a nullable field's sentinel is the union
+  // ['`$ONE`', ['`$NUMBER`','`$NULL`']], which canonKey stringifies into
+  // nothing recognizable — so a `number | null` id fell through to the
+  // quoted placeholder and the example failed to compile against the type
+  // generated from that very sentinel.
+  const key = canonScalarKey(paramCanonType(entity, op, paramName))
   if ('INTEGER' === key || 'NUMBER' === key) {
     return '1'
   }
@@ -62,6 +68,9 @@ function exampleValue(entity: any, op: any, paramName: string, placeholder: stri
   if ('OBJECT' === key) {
     return '{}'
   }
+  if ('NULL' === key) {
+    return 'null'
+  }
   return `'${placeholder}'`
 }
 

package/project/.sdk/src/cmp/zig/ReadmeEntity_zig.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -26,7 +26,7 @@ function zigType(type: any): string {
 
 // A type-correct zig expression constructing a voxgig struct Value.
 function zigLit(type: any, placeholder: string = 'example'): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return 'h.vnum(1)'
   if ('BOOLEAN' === k) return 'h.vbool(true)'
   if ('ARRAY' === k) return 'h.olist()'

package/project/.sdk/src/cmp/zig/ReadmeHowto_zig.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -12,7 +12,7 @@ import { zigVarName } from './utility_zig'
 
 // A type-correct zig expression constructing a voxgig struct Value.
 function zigLit(type: any): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return 'h.vnum(1)'
   if ('BOOLEAN' === k) return 'h.vbool(true)'
   if ('ARRAY' === k) return 'h.olist()'

package/project/.sdk/src/cmp/zig/ReadmeQuick_zig.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityOps } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityOps } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -35,7 +35,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   // A type-correct zig expression constructing a voxgig struct Value.
   const zigLit = (type: any, placeholder: string = 'example'): string => {
-    const k = canonKey(type)
+    const k = canonScalarKey(type)
     if ('INTEGER' === k || 'NUMBER' === k) return 'h.vnum(1)'
     if ('BOOLEAN' === k) return 'h.vbool(true)'
     if ('ARRAY' === k) return 'h.olist()'

package/project/.sdk/src/cmp/zig/ReadmeRef_zig.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -24,7 +24,7 @@ function zigType(type: any): string {
 
 // A type-correct zig expression constructing a voxgig struct Value.
 function zigLit(type: any, placeholder: string = 'example'): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return 'h.vnum(1)'
   if ('BOOLEAN' === k) return 'h.vbool(true)'
   if ('ARRAY' === k) return 'h.olist()'

package/project/.sdk/src/cmp/zig/ReadmeTopQuick_zig.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,7 +14,7 @@ import { zigVarName } from './utility_zig'
 // param. Strings render the quoted placeholder; numeric/boolean/array/object
 // render a typed literal.
 function zigLit(type: any, placeholder: string = 'example'): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return 'h.vnum(1)'
   if ('BOOLEAN' === k) return 'h.vbool(true)'
   if ('ARRAY' === k) return 'h.olist()'

package/project/.sdk/src/cmp/zig/ReadmeTopTest_zig.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -12,7 +12,7 @@ import { zigVarName } from './utility_zig'
 
 // A type-correct zig expression constructing a voxgig struct Value.
 function zigLit(type: any): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return 'h.vnum(1)'
   if ('BOOLEAN' === k) return 'h.vbool(true)'
   if ('ARRAY' === k) return 'h.olist()'

package/project/sdkgen-package.json

@@ -3,7 +3,7 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen",
-  "version": "4.2.0",
+  "version": "4.2.1",
   "provides": {
     "target": [
       "c",

package/src/helpers/canonType.ts

@@ -182,6 +182,43 @@ function canonKey(sentinel: unknown): string {
 }
 
 
+// The bare key of the sentinel a VALUE of this type must satisfy, resolving
+// the union sentinel `['`$ONE`', [member, ...]]` to its first non-NULL member
+// (recursively — a member may itself be a union).
+//
+// canonKey alone cannot do this: given an array it stringifies it, so a
+// nullable `['`$ONE`', ['`$NUMBER`','`$NULL`']]` field yields neither NUMBER
+// nor anything else recognizable and every caller falls through to its
+// "unknown, use a string" branch. canonToType meanwhile renders that same
+// sentinel as `number | null`, so the doc example said `'..._id'` while the
+// generated type said `number` — a TS2322 in the SDK's own README, which is
+// exactly the disagreement the example helpers exist to prevent.
+//
+// A union of nothing but NULL resolves to NULL; an unrecognized array shape,
+// or an empty member list, resolves to '' (unknown) like any missing
+// sentinel.
+function canonScalarKey(sentinel: unknown): string {
+  if (Array.isArray(sentinel)) {
+    if ('ONE' !== canonKey(sentinel[0]) || !Array.isArray(sentinel[1])) {
+      return ''
+    }
+    let sawNull = false
+    for (const member of sentinel[1]) {
+      const key = canonScalarKey(member)
+      if ('NULL' === key) {
+        sawNull = true
+        continue
+      }
+      if ('' !== key) {
+        return key
+      }
+    }
+    return sawNull ? 'NULL' : ''
+  }
+  return canonKey(sentinel)
+}
+
+
 // Map a field/param type sentinel to a target-language primitive type.
 // Unknown or missing sentinel -> that language's "any" (never throws).
 //
@@ -220,6 +257,7 @@ export {
   canonToType,
   canonToDtype,
   canonKey,
+  canonScalarKey,
   CANON_TYPE,
   CANON_ANY,
   CANON_UNION_JOIN,

package/src/sdkgen.ts

@@ -57,7 +57,7 @@ import { buildIdNames } from './helpers/buildIdNames'
 import { getMatchEntries } from './helpers/getMatchEntries'
 import { collectDeps } from './helpers/collectDeps'
 import type { DepEntry } from './helpers/collectDeps'
-import { canonToType, canonToDtype, canonKey } from './helpers/canonType'
+import { canonToType, canonToDtype, canonKey, canonScalarKey } from './helpers/canonType'
 import { OP_SUFFIX, opTypeName, opParams, ownPoint, opActions, entityActions, entityPath, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp, pickExampleEntity, entityClassName, entityTypeCollisions, warnEntityTypeCollisions, deriveEntityNames, entityCollection } from './helpers/opShape'
 import { isReservedName, safeVarName, exampleVarName, phpEntityAccessor, entityCacheField, isRbCoreConstant, isRbSdkConstant, rbSafeTypeName, isSwiftSdkType, swiftSafeTypeName, isPhpReservedType, phpSafeTypeName, isTsReservedType, tsSafeTypeName, jsProp, jsOptProp, jsKey } from './helpers/naming'
 import { serverVariables, hasServerVariables } from './helpers/serverVars'
@@ -1059,6 +1059,7 @@ export {
   canonToType,
   canonToDtype,
   canonKey,
+  canonScalarKey,
 
   OP_SUFFIX,
   opTypeName,