@voxgig/sdkgen 1.3.13 → 1.3.17

package/project/.sdk/src/cmp/haskell/ReadmeTopQuick_haskell.ts

@@ -0,0 +1,104 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { hsVarName } from './utility_haskell'
+
+
+// A type-correct Haskell `Value` literal for a param.
+function hsLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'VNum 1'
+  if ('BOOLEAN' === k) return 'VBool True'
+  if ('ARRAY' === k || 'OBJECT' === k) return 'VNoval'
+  return `VStr "${placeholder}"`
+}
+
+
+const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  const authActive = isAuthActive(model)
+
+  Content(`\`\`\`haskell
+`)
+  if (authActive) {
+    Content(`import System.Environment (lookupEnv)
+import qualified SdkClient as Sdk
+import VoxgigStruct (Value (..), emptyMap)
+import SdkHelpers (jo)
+
+main :: IO ()
+main = do
+  mkey <- lookupEnv "${envName(model)}_APIKEY"
+  opts <- jo [("apikey", maybe VNoval VStr mkey)]
+  sdk <- Sdk.newSdk opts
+`)
+  }
+  else {
+    Content(`import qualified SdkClient as Sdk
+import VoxgigStruct (Value (..), emptyMap)
+import SdkHelpers (jo)
+
+main :: IO ()
+main = do
+  sdk <- Sdk.newSdk0
+`)
+  }
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const eFn = hsVarName(exampleEntity.name)
+    const opnames = Object.keys(exampleEntity.op || {})
+    const idF = entityIdField(exampleEntity)
+
+    if (opnames.includes('list')) {
+      Content(`
+  -- List all ${eName.toLowerCase()}s (returns a list Value, raises on error)
+  ent <- Sdk.${eFn} sdk VNoval
+  match <- emptyMap
+  ctrl <- emptyMap
+  ${eFn}s <- Sdk.eList ent match ctrl
+  print ${eFn}s
+`)
+    }
+
+    if (opnames.includes('load')) {
+      const loadItems = opRequestShape(exampleEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `[${loadItems.map((it: any) =>
+          `("${it.name}", ${hsLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)})`).join(', ')}]`
+        : '[]'
+      Content(`
+  -- Load a specific ${eName.toLowerCase()} (returns the record, raises on error)
+  ent2 <- Sdk.${eFn} sdk VNoval
+  m <- jo ${loadArg}
+  ctrl2 <- emptyMap
+  ${eFn} <- Sdk.eLoad ent2 m ctrl2
+  print ${eFn}
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

package/project/.sdk/src/cmp/haskell/ReadmeTopTest_haskell.ts

@@ -0,0 +1,80 @@
+
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { hsVarName } from './utility_haskell'
+
+
+// A type-correct Haskell `Value` literal for a field's canonical type.
+function hsLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'VNum 1'
+  if ('BOOLEAN' === k) return 'VBool True'
+  if ('ARRAY' === k || 'OBJECT' === k) return 'VNoval'
+  return 'VStr "example"'
+}
+
+
+const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+
+  Content(`\`\`\`haskell
+import qualified SdkClient as Sdk
+import VoxgigStruct (Value (..), emptyMap)
+import SdkHelpers (jo)
+
+main :: IO ()
+main = do
+  sdk <- Sdk.testSdk0
+`)
+
+  if (exampleEntity && primaryOp) {
+    const eName = nom(exampleEntity, 'Name')
+    const eFn = hsVarName(exampleEntity.name)
+    const idF = entityIdField(exampleEntity)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let argExpr = 'emptyMap'
+    if (isMatchOp) {
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      argExpr = 0 < items.length
+        ? `jo [${items.map((it: any) =>
+          `("${it.name}", ${it.name === idF ? 'VStr "test01"' : hsLit(it.type)})`).join(', ')}]`
+        : 'emptyMap'
+    } else if ('create' === primaryOp || 'update' === primaryOp) {
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => it.name !== idF && it.name !== 'id')
+      const required = items.filter((it: any) => !it.optional)
+      const chosen = required.length ? required : items.slice(0, 3)
+      argExpr = `jo [${chosen.map((it: any) => `("${it.name}", ${hsLit(it.type)})`).join(', ')}]`
+    }
+    const opCap = 'e' + primaryOp.charAt(0).toUpperCase() + primaryOp.slice(1)
+    const resVar = hsVarName(exampleEntity.name) + ('list' === primaryOp ? 's' : '')
+    Content(`  ent <- Sdk.${eFn} sdk VNoval
+  arg <- ${argExpr}
+  ctrl <- emptyMap
+  ${resVar} <- Sdk.${opCap} ent arg ctrl
+  print ${resVar}
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

package/project/.sdk/src/cmp/haskell/Test_haskell.ts

@@ -10,6 +10,7 @@ import type {
 import { cmp, each, Folder, File, Content } from '@voxgig/sdkgen'
 
 import { hsVarName } from './utility_haskell'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_haskell'
 
 
 // test/SdkGenTests.hs — model-driven per-entity tests: an instance test, a
@@ -23,6 +24,12 @@ const Test = cmp(function Test(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
 
   Folder({ name: 'test' }, () => {
+
+    // Structural gate over the documented Haskell examples (emits
+    // test/TReadmeExamples.hs); wired into genTests below so it runs in the
+    // standard Runner.
+    ReadmeExamplesTest({ target })
+
     File({ name: 'SdkGenTests.' + target.ext }, () => {
 
       let calls = ''
@@ -131,6 +138,12 @@ ${basicFn} c = do
     pure True
 `
         }
+        // An op-less entity (no list/load/create — e.g. a bare path entity)
+        // appends no runTest, leaving the do-block ending on `opts <- jo [...]`
+        // (a bind), which is illegal as the final statement. Terminate it.
+        if (!hasList && !hasLoad && !hasCreate) {
+          defs += `  pure ()\n`
+        }
 
         // Direct call test (via injected system.fetch mock).
         defs += `
@@ -230,16 +243,27 @@ import SdkTypes
 import SdkHelpers
 import qualified SdkFeatures as F
 import qualified SdkClient as C
+import qualified TReadmeExamples
 import Testutil
 import TestJson (jsonRead)
 
 -- Load an entity fixture (../.sdk/test/entity/<name>/<Name>TestData.json).
 loadFixture :: String -> IO Value
 loadFixture entName = do
-  let lname = map toLowerCh entName
+  -- The fixture DIRECTORY is the snake_case entity name (create_result), so a
+  -- plain lowercase of the CamelCase entName (createresult) misses the
+  -- underscores for multi-word entities. Convert CamelCase -> snake_case.
+  let lname = camelToSnake entName
   raw <- readFile ("../.sdk/test/entity/" ++ lname ++ "/" ++ entName ++ "TestData.json")
   jsonRead raw
-  where toLowerCh ch = if ch >= 'A' && ch <= 'Z' then toEnum (fromEnum ch + 32) else ch
+  where
+    toLowerCh ch = if ch >= 'A' && ch <= 'Z' then toEnum (fromEnum ch + 32) else ch
+    camelToSnake [] = []
+    camelToSnake (c0 : rest) = toLowerCh c0 : go rest
+    go [] = []
+    go (c : cs)
+      | c >= 'A' && c <= 'Z' = '_' : toLowerCh c : go cs
+      | otherwise = c : go cs
 
 -- The first new-ref data map for an entity (fixture.new.<entity>.<ref0>).
 newRefData :: Value -> String -> IO Value
@@ -252,6 +276,7 @@ newRefData fixture entName = do
 
 genTests :: Counters -> IO ()
 genTests c = do
+  TReadmeExamples.tests c
 ${calls}${defs}`)
     })
   })

package/project/.sdk/src/cmp/java/EntityTypes_java.ts

@@ -0,0 +1,207 @@
+
+
+// Typed-model generator (Java target). Port of EntityTypes_py.ts /
+// EntityTypes_csharp.ts.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits ONE file, core/<Name>Types.java,
+// holding a container class with a nested `public record` per active entity
+// plus a request/match record per active op.
+//
+// WHY A CONTAINER CLASS: Java permits only ONE public top-level type per file
+// (the file name must match it), so — unlike C# which emits many top-level
+// records — every generated record is a nested (implicitly static) member of a
+// single `public final class <Name>Types`. This keeps the whole reference model
+// in one file whatever the entity count.
+//
+// TYPE CHOICE: reference `record` types with BOXED (nullable) component types,
+// NOT the wired runtime type. The generated ops take/return the loose object
+// model (`Map<String, Object>` / `Object`), so these records are NOT wired into
+// the op signatures — they are documentation/DX reference shapes a caller may
+// use to describe a payload before converting it to a map. This mirrors the JS
+// target's JSDoc typedefs (annotation only, no runtime effect). Emitting unused
+// records is harmless — they compile and have no runtime effect.
+//
+// OPTIONAL FIELDS: every component is a boxed reference type, hence inherently
+// nullable, so a `req:false` field/param needs no distinct rendering in Java.
+//
+// Sentinels map to Java types via the SHARED canonToType 'java' column (the
+// single source of truth per language — do not keep a local table here).
+//
+// Keep the SAME type-name scheme as every other language: <Name>,
+// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
+// <Name>RemoveMatch (via the shared opTypeName helper).
+
+import {
+  cmp, each, names,
+  File, Content,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { javaPackage } from './utility_java'
+
+
+// Java keywords + reserved literals that cannot be a record component name.
+const JAVA_KEYWORDS = new Set<string>([
+  'abstract', 'assert', 'boolean', 'break', 'byte', 'case', 'catch', 'char',
+  'class', 'const', 'continue', 'default', 'do', 'double', 'else', 'enum',
+  'extends', 'final', 'finally', 'float', 'for', 'goto', 'if', 'implements',
+  'import', 'instanceof', 'int', 'interface', 'long', 'native', 'new',
+  'package', 'private', 'protected', 'public', 'return', 'short', 'static',
+  'strictfp', 'super', 'switch', 'synchronized', 'this', 'throw', 'throws',
+  'transient', 'try', 'void', 'volatile', 'while',
+  'true', 'false', 'null', 'var', 'record', 'yield',
+])
+
+
+// A field/param name that has a safe Java identifier rendering. Names that are
+// not valid identifiers (hyphens, leading digits) have no clean component form
+// and are skipped — they remain reachable via the runtime map.
+function javaIdent(name: string): boolean {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) && !JAVA_KEYWORDS.has(name)
+}
+
+
+const LANG = 'java'
+
+
+// Emit a nested `public record <typeName>(...)` from {name, type} items. An
+// item whose name is not a legal identifier is skipped (WITH a warning — the
+// key stays reachable via the runtime map, but its absence from the typed
+// model should be visible, not silent); a duplicate component name (after the
+// identifier filter) is dropped. An empty record is a valid, zero-component
+// shape.
+function emitRecord(typeName: string, items: any[], log?: any): void {
+  const seen = new Set<string>()
+  const usable = items.filter((it: any) => {
+    if (!it || null == it.name) {
+      return false
+    }
+    if (!javaIdent(it.name)) {
+      if (log && log.warn) {
+        log.warn({
+          point: 'entity-types-skip-field', typeName, field: it.name,
+          note: `java: field "${it.name}" of ${typeName} has no legal Java ` +
+            `identifier form; omitted from the typed model (still reachable ` +
+            `via the runtime map)`,
+        })
+      }
+      return false
+    }
+    if (seen.has(it.name)) {
+      return false
+    }
+    seen.add(it.name)
+    return true
+  })
+
+  if (0 === usable.length) {
+    Content(`  public record ${typeName}() {}
+
+`)
+    return
+  }
+
+  const params = usable
+    .map((it: any) => `${canonToType(it.type, LANG)} ${it.name}`)
+    .join(', ')
+  Content(`  public record ${typeName}(${params}) {}
+
+`)
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { model, log } = props.ctx$
+  const target = props.target || {}
+  const ext = target.ext || 'java'
+
+  const javapackage = props.javapackage || javaPackage(model)
+
+  // only_active:false — getModelPath DROPS active:false entries by default,
+  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
+  // collection, so inactive entities still get generated entity code that
+  // references these typed names. The typed model must cover them too.
+  const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
+  // Emit for EVERY entity that gets generated entity code: the consumer
+  // scaffold (create-sdkgen Root.ts) iterates entities WITHOUT an active
+  // filter, so inactive entities still get class files referencing these
+  // typed names. Filter on `name` (always present), NOT `active` — parity
+  // with the go emitter's fix.
+  const entityList = each(entity).filter((e: any) => e && null != e.name)
+  // Derive the PascalCase Name up-front — it is set LAZILY by names(), so an
+  // entity not yet named (e.g. a fieldless placeholder) would otherwise read
+  // `Name = undefined` below. Parity with the go/py/csharp emitter's fix.
+  entityList.forEach((e: any) => { if (null == e.Name) names(e, e.name) })
+
+  // Surface duplicate generated type names (two entities with the same
+  // PascalCase Name) — they would redeclare a type in statically-typed
+  // targets. Detection only; renaming is a model-level decision.
+  warnEntityTypeCollisions(entity, log, LANG)
+
+  File({ name: model.const.Name + 'Types.' + ext }, () => {
+
+    Content(`package ${javapackage}.core;
+
+// Typed reference models for the ${model.const.Name} SDK.
+//
+// GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
+// params (op.<name>.points[].args.params[]). Field/param types come from the
+// canonical type sentinels (source of truth: @voxgig/apidef VALID_CANON). Do
+// not edit by hand.
+//
+// These records are documentation/DX reference shapes ONLY. The SDK ops take
+// and return the loose object model (Map<String, Object> / Object) at runtime,
+// so these types are not wired into the op signatures — use them to describe a
+// payload before converting it to a map. Every component is a boxed (nullable)
+// type, so an optional (req:false) key needs no distinct rendering.
+
+import java.util.List;
+import java.util.Map;
+
+public final class ${model.const.Name}Types {
+
+  private ${model.const.Name}Types() {}
+
+`)
+
+    entityList.forEach((ent: any) => {
+      const Name = ent.Name
+      const fields = (ent.fields ? each(ent.fields) : [])
+        .filter((f: any) => f.active !== false)
+
+      // Entity data model: one component per field.
+      emitRecord(Name, fields.map((f: any) => ({
+        name: f.name, type: f.type,
+      })), log)
+
+      // Per active op: a request/match record. Members come from the shared
+      // partiality policy (opRequestShape).
+      const ops = ent.op || {}
+      ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+        if (null == ops[opname]) {
+          return
+        }
+
+        const typeName = opTypeName(Name, opname)
+        const { items } = opRequestShape(ent, opname)
+
+        emitRecord(typeName, items, log)
+      })
+    })
+
+    Content(`}
+`)
+  })
+})
+
+
+export {
+  EntityTypes,
+}

package/project/.sdk/src/cmp/java/Main_java.ts

@@ -23,6 +23,7 @@ import { Config } from './Config_java'
 import { Gitignore } from './Gitignore_java'
 import { MainEntity } from './MainEntity_java'
 import { EntityBase } from './EntityBase_java'
+import { EntityTypes } from './EntityTypes_java'
 import { SdkError } from './SdkError_java'
 import { javaPackage } from './utility_java'
 
@@ -90,6 +91,11 @@ this.utility.featureHook.apply(this.rootctx, "${name}");
     })
 
     Config({ target })
+
+    // Generate the typed reference-model file (<Name>Types.java) beside the
+    // other generated core files. Documentation/DX shapes only — not wired
+    // into the loose-object-model op signatures.
+    EntityTypes({ target, javapackage })
   })
 
 })

package/project/.sdk/src/cmp/java/ReadmeEntity_java.ts

@@ -0,0 +1,175 @@
+
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { javaVarName } from './utility_java'
+
+
+// Type names come from the shared canonToType 'java' column (single source of truth).
+
+// A type-correct, JSON-serialisable Java literal for a field's canonical type.
+function javaLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k) return '1L'
+  if ('NUMBER' === k) return '1.0'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return 'List.of()'
+  if ('OBJECT' === k) return 'Map.of()'
+  return `"${placeholder}"`
+}
+
+
+// Operation method spelling for Java: camelCase methods over the loose object
+// model. The op descriptions are language-agnostic.
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'load(match, null)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'list(null, null)',    desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: 'create(data, null)',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(data, null)',  desc: 'Update an existing entity.' },
+  remove: { method: 'remove(match, null)', desc: 'Remove the matching entity.' },
+}
+
+
+const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const publishedEntities = each(entity)
+    .filter((entity: any) => entity.active !== false)
+
+  if (0 === publishedEntities.length) {
+    return
+  }
+
+  Content(`
+
+## Entities
+
+`)
+
+  publishedEntities.map((entity: any) => {
+    const opnames = Object.keys(entity.op || {})
+    const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
+    // Sanitise the local variable name — a camelCased Java keyword gets a
+    // trailing underscore (javaVarName) so the snippet compiles.
+    const eVar = javaVarName(entity.name)
+    const accessor = javaVarName(entity.name)
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`SdkEntity ${eVar} = client.${accessor}(null);\`
+
+`)
+
+    if (opnames.length > 0) {
+      Content(`#### Operations
+
+| Method | Description |
+| --- | --- |
+`)
+      opnames.map((opname: string) => {
+        const info = OP_DESC[opname]
+        if (info) {
+          Content(`| \`${info.method}\` | ${info.desc} |
+`)
+        }
+      })
+
+      Content(`
+`)
+    }
+
+    if (fields.length > 0) {
+      Content(`#### Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+`)
+
+      each(fields, (field: any) => {
+        const desc = field.short || ''
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+`)
+      })
+
+      Content(`
+`)
+    }
+
+    if (opnames.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.
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `Map.of(${loadItems.map((it: any) =>
+          `"${it.name}", ${javaLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')})`
+        : 'null'
+      Content(`#### Example: Load
+
+\`\`\`java
+Object ${eVar} = client.${accessor}(null).load(${loadArg}, null);
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`java
+Object ${eVar}List = client.${accessor}(null).list(null, null);
+\`\`\`
+
+`)
+    }
+
+    if (opnames.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.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`java
+Object ${eVar} = client.${accessor}(null).create(Map.of(
+`)
+      createItems.map((it: any, i: number) => {
+        const comma = i < createItems.length - 1 ? ',' : ''
+        Content(`    "${it.name}", ${javaLit(it.type, 'example_' + it.name)}${comma}  // ${canonToType(it.type, target.name)}
+`)
+      })
+      Content(`), null);
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}