@voxgig/sdkgen 1.3.8 → 1.3.9

package/project/.sdk/src/cmp/kotlin/fragment/EntityBase.fragment.kt

@@ -0,0 +1,195 @@
+package KOTLINPACKAGE.entity
+
+import KOTLINPACKAGE.core.Context
+import KOTLINPACKAGE.core.Helpers
+import KOTLINPACKAGE.core.SdkClient
+import KOTLINPACKAGE.core.SdkEntity
+import KOTLINPACKAGE.core.Utility
+import KOTLINPACKAGE.utility.struct.Struct
+
+/**
+ * Shared entity runtime for the ProjectName SDK: accreting data/match state,
+ * the entity context, and the operation pipeline (runOp) with its feature
+ * hooks. Generated entity classes extend this.
+ */
+@Suppress("UNCHECKED_CAST")
+abstract class EntityBase(nm: String, clientIn: SdkClient, entoptsIn: MutableMap<String, Any?>?) : SdkEntity {
+
+  override var name: String = ""
+  protected var client: SdkClient
+  protected var utility: Utility
+  protected var entopts: MutableMap<String, Any?>
+  protected var data: MutableMap<String, Any?> = linkedMapOf()
+  protected var match: MutableMap<String, Any?> = linkedMapOf()
+  protected var entctx: Context
+
+  init {
+    val entopts = entoptsIn ?: linkedMapOf()
+    if (!entopts.containsKey("active")) {
+      entopts["active"] = true
+    } else if (entopts["active"] == false) {
+      // keep false
+    } else {
+      entopts["active"] = true
+    }
+
+    this.name = nm
+    this.client = clientIn
+    this.utility = clientIn.getUtility()
+    this.entopts = entopts
+
+    val ctxmap = linkedMapOf<String, Any?>()
+    ctxmap["entity"] = this
+    ctxmap["entopts"] = entopts
+    this.entctx = this.utility.makeContext(ctxmap, clientIn.getRootCtx())
+
+    this.utility.featureHook(this.entctx, "PostConstructEntity")
+  }
+
+  override fun data(vararg args: Any?): Any? {
+    if (args.isNotEmpty() && args[0] != null) {
+      val d = Helpers.toMapAny(Struct.clone(args[0]))
+      this.data = d ?: linkedMapOf()
+      this.utility.featureHook(this.entctx, "SetData")
+    }
+
+    this.utility.featureHook(this.entctx, "GetData")
+    return Struct.clone(this.data)
+  }
+
+  override fun match(vararg args: Any?): Any? {
+    if (args.isNotEmpty() && args[0] != null) {
+      val m = Helpers.toMapAny(Struct.clone(args[0]))
+      this.match = m ?: linkedMapOf()
+      this.utility.featureHook(this.entctx, "SetMatch")
+    }
+
+    this.utility.featureHook(this.entctx, "GetMatch")
+    return Struct.clone(this.match)
+  }
+
+  // runOp drives one operation through the pipeline: for each stage the
+  // feature hook fires, then the stage runs; a failing stage routes through
+  // makeError (which throws, or returns fallback data when ctrl.throw false).
+  protected fun runOp(ctx: Context, postDone: () -> Unit): Any? {
+    val utility = this.utility
+
+    try {
+// #PrePoint-Hook
+
+      val point = utility.makePoint(ctx)
+      ctx.out["point"] = point
+
+// #PreSpec-Hook
+
+      val spec = utility.makeSpec(ctx)
+      ctx.out["spec"] = spec
+
+// #PreRequest-Hook
+
+      val request = utility.makeRequest(ctx)
+      ctx.out["request"] = request
+
+// #PreResponse-Hook
+
+      val response = utility.makeResponse(ctx)
+      ctx.out["response"] = response
+
+// #PreResult-Hook
+
+      val result = utility.makeResult(ctx)
+      ctx.out["result"] = result
+
+// #PreDone-Hook
+
+      postDone()
+
+      return utility.done(ctx)
+    } catch (err: RuntimeException) {
+      // An error already finalised by makeError (e.g. via done) must not be
+      // wrapped a second time.
+      if (err === ctx.ctrl.err) {
+        throw err
+      }
+      return utility.makeError(ctx, err)
+    }
+  }
+
+  /**
+   * Streaming operations. Runs `action` through the full pipeline and returns
+   * a Sequence over result items, so the streaming feature's incremental
+   * output is reachable from a generated entity (a normal op call materialises
+   * the whole result). `callopts` parameterises the call:
+   *   - inbound (download): iterate the yielded items/chunks (from the
+   *     streaming feature when active, else the materialised items);
+   *   - outbound (upload): pass a streamable payload as callopts["body"] - it
+   *     is attached to the request so the transport can send it;
+   *   - callopts["ctrl"] threads pipeline control and callopts["signal"] (a
+   *     () -> Boolean that returns true when aborted) is honoured between
+   *     yields.
+   */
+  override fun stream(
+    action: String,
+    args: MutableMap<String, Any?>?,
+    callopts: MutableMap<String, Any?>?,
+  ): Sequence<Any?> {
+    val opts = callopts ?: linkedMapOf()
+
+    val signal = opts["signal"]
+
+    val ctrl = Helpers.toMapAny(opts["ctrl"]) ?: linkedMapOf()
+    ctrl["stream"] = opts
+
+    val ctxmap = linkedMapOf<String, Any?>()
+    ctxmap["opname"] = action
+    ctxmap["ctrl"] = ctrl
+    ctxmap["match"] = this.match
+    ctxmap["data"] = this.data
+    if (args != null) {
+      ctxmap.putAll(args)
+    }
+
+    val ctx = this.utility.makeContext(ctxmap, this.entctx)
+
+    // Outbound: expose the caller's streamable payload so the request builder
+    // / transport can stream it as the request body.
+    val body = opts["body"]
+    if (body != null) {
+      ctx.reqdata["body\$"] = body
+      ctx.ctrl.streamOut = body
+    }
+
+    // Run the same pipeline the op methods run.
+    val materialised = runOp(ctx) {}
+
+    // Inbound: prefer the streaming feature's incremental iterator; else fall
+    // back to the materialised items so `stream` always yields.
+    val source: Iterator<Any?> = ctx.result?.stream?.get()
+      ?: run {
+        val items: List<Any?> = when (materialised) {
+          is List<*> -> materialised
+          null -> emptyList()
+          else -> listOf(materialised)
+        }
+        items.iterator()
+      }
+
+    val aborted: () -> Boolean = when (signal) {
+      is Function0<*> -> {
+        { (signal as Function0<Any?>).invoke() == true }
+      }
+      else -> {
+        { false }
+      }
+    }
+
+    return sequence {
+      while (source.hasNext()) {
+        if (aborted()) {
+          return@sequence
+        }
+        yield(source.next())
+      }
+    }
+  }
+}

package/project/.sdk/src/cmp/kotlin/fragment/EntityCreateOp.fragment.kt

@@ -0,0 +1,37 @@
+package KOTLINPACKAGE.entity
+
+import KOTLINPACKAGE.core.Context
+import KOTLINPACKAGE.core.Helpers
+import KOTLINPACKAGE.core.SdkClient
+import KOTLINPACKAGE.utility.struct.Struct
+
+// Fragment carrier: only the section between the EJECT markers is spliced
+// into the generated entity class (which extends EntityBase).
+@Suppress("UNCHECKED_CAST")
+abstract class EntityCreateOpFragment(clientIn: SdkClient, entoptsIn: MutableMap<String, Any?>?) :
+  EntityBase("entityname", clientIn, entoptsIn) {
+
+// EJECT-START
+
+  override fun create(reqdata: MutableMap<String, Any?>?, ctrl: MutableMap<String, Any?>?): Any? {
+    val ctxmap = linkedMapOf<String, Any?>()
+    ctxmap["opname"] = "create"
+    ctxmap["ctrl"] = ctrl
+    ctxmap["match"] = this.match
+    ctxmap["data"] = this.data
+    ctxmap["reqdata"] = reqdata
+    val ctx = this.utility.makeContext(ctxmap, this.entctx)
+
+    return runOp(ctx) {
+      val result = ctx.result
+      if (result != null) {
+        if (result.resdata != null) {
+          val d = Helpers.toMapAny(Struct.clone(result.resdata))
+          this.data = d ?: linkedMapOf()
+        }
+      }
+    }
+  }
+
+// EJECT-END
+}

package/project/.sdk/src/cmp/kotlin/fragment/EntityListOp.fragment.kt

@@ -0,0 +1,34 @@
+package KOTLINPACKAGE.entity
+
+import KOTLINPACKAGE.core.Context
+import KOTLINPACKAGE.core.SdkClient
+
+// Fragment carrier: only the section between the EJECT markers is spliced
+// into the generated entity class (which extends EntityBase).
+@Suppress("UNCHECKED_CAST")
+abstract class EntityListOpFragment(clientIn: SdkClient, entoptsIn: MutableMap<String, Any?>?) :
+  EntityBase("entityname", clientIn, entoptsIn) {
+
+// EJECT-START
+
+  override fun list(reqmatch: MutableMap<String, Any?>?, ctrl: MutableMap<String, Any?>?): Any? {
+    val ctxmap = linkedMapOf<String, Any?>()
+    ctxmap["opname"] = "list"
+    ctxmap["ctrl"] = ctrl
+    ctxmap["match"] = this.match
+    ctxmap["data"] = this.data
+    ctxmap["reqmatch"] = reqmatch
+    val ctx = this.utility.makeContext(ctxmap, this.entctx)
+
+    return runOp(ctx) {
+      val result = ctx.result
+      if (result != null) {
+        if (result.resmatch != null) {
+          this.match = result.resmatch!!
+        }
+      }
+    }
+  }
+
+// EJECT-END
+}

package/project/.sdk/src/cmp/kotlin/fragment/EntityLoadOp.fragment.kt

@@ -0,0 +1,40 @@
+package KOTLINPACKAGE.entity
+
+import KOTLINPACKAGE.core.Context
+import KOTLINPACKAGE.core.Helpers
+import KOTLINPACKAGE.core.SdkClient
+import KOTLINPACKAGE.utility.struct.Struct
+
+// Fragment carrier: only the section between the EJECT markers is spliced
+// into the generated entity class (which extends EntityBase).
+@Suppress("UNCHECKED_CAST")
+abstract class EntityLoadOpFragment(clientIn: SdkClient, entoptsIn: MutableMap<String, Any?>?) :
+  EntityBase("entityname", clientIn, entoptsIn) {
+
+// EJECT-START
+
+  override fun load(reqmatch: MutableMap<String, Any?>?, ctrl: MutableMap<String, Any?>?): Any? {
+    val ctxmap = linkedMapOf<String, Any?>()
+    ctxmap["opname"] = "load"
+    ctxmap["ctrl"] = ctrl
+    ctxmap["match"] = this.match
+    ctxmap["data"] = this.data
+    ctxmap["reqmatch"] = reqmatch
+    val ctx = this.utility.makeContext(ctxmap, this.entctx)
+
+    return runOp(ctx) {
+      val result = ctx.result
+      if (result != null) {
+        if (result.resmatch != null) {
+          this.match = result.resmatch!!
+        }
+        if (result.resdata != null) {
+          val d = Helpers.toMapAny(Struct.clone(result.resdata))
+          this.data = d ?: linkedMapOf()
+        }
+      }
+    }
+  }
+
+// EJECT-END
+}

package/project/.sdk/src/cmp/kotlin/fragment/EntityRemoveOp.fragment.kt

@@ -0,0 +1,40 @@
+package KOTLINPACKAGE.entity
+
+import KOTLINPACKAGE.core.Context
+import KOTLINPACKAGE.core.Helpers
+import KOTLINPACKAGE.core.SdkClient
+import KOTLINPACKAGE.utility.struct.Struct
+
+// Fragment carrier: only the section between the EJECT markers is spliced
+// into the generated entity class (which extends EntityBase).
+@Suppress("UNCHECKED_CAST")
+abstract class EntityRemoveOpFragment(clientIn: SdkClient, entoptsIn: MutableMap<String, Any?>?) :
+  EntityBase("entityname", clientIn, entoptsIn) {
+
+// EJECT-START
+
+  override fun remove(reqmatch: MutableMap<String, Any?>?, ctrl: MutableMap<String, Any?>?): Any? {
+    val ctxmap = linkedMapOf<String, Any?>()
+    ctxmap["opname"] = "remove"
+    ctxmap["ctrl"] = ctrl
+    ctxmap["match"] = this.match
+    ctxmap["data"] = this.data
+    ctxmap["reqmatch"] = reqmatch
+    val ctx = this.utility.makeContext(ctxmap, this.entctx)
+
+    return runOp(ctx) {
+      val result = ctx.result
+      if (result != null) {
+        if (result.resmatch != null) {
+          this.match = result.resmatch!!
+        }
+        if (result.resdata != null) {
+          val d = Helpers.toMapAny(Struct.clone(result.resdata))
+          this.data = d ?: linkedMapOf()
+        }
+      }
+    }
+  }
+
+// EJECT-END
+}

package/project/.sdk/src/cmp/kotlin/fragment/EntityUpdateOp.fragment.kt

@@ -0,0 +1,40 @@
+package KOTLINPACKAGE.entity
+
+import KOTLINPACKAGE.core.Context
+import KOTLINPACKAGE.core.Helpers
+import KOTLINPACKAGE.core.SdkClient
+import KOTLINPACKAGE.utility.struct.Struct
+
+// Fragment carrier: only the section between the EJECT markers is spliced
+// into the generated entity class (which extends EntityBase).
+@Suppress("UNCHECKED_CAST")
+abstract class EntityUpdateOpFragment(clientIn: SdkClient, entoptsIn: MutableMap<String, Any?>?) :
+  EntityBase("entityname", clientIn, entoptsIn) {
+
+// EJECT-START
+
+  override fun update(reqdata: MutableMap<String, Any?>?, ctrl: MutableMap<String, Any?>?): Any? {
+    val ctxmap = linkedMapOf<String, Any?>()
+    ctxmap["opname"] = "update"
+    ctxmap["ctrl"] = ctrl
+    ctxmap["match"] = this.match
+    ctxmap["data"] = this.data
+    ctxmap["reqdata"] = reqdata
+    val ctx = this.utility.makeContext(ctxmap, this.entctx)
+
+    return runOp(ctx) {
+      val result = ctx.result
+      if (result != null) {
+        if (result.resmatch != null) {
+          this.match = result.resmatch!!
+        }
+        if (result.resdata != null) {
+          val d = Helpers.toMapAny(Struct.clone(result.resdata))
+          this.data = d ?: linkedMapOf()
+        }
+      }
+    }
+  }
+
+// EJECT-END
+}

package/project/.sdk/src/cmp/kotlin/fragment/Main.fragment.kt

@@ -0,0 +1,28 @@
+package KOTLINPACKAGE.core
+
+/**
+ * ProjectName SDK client. All transport and pipeline behaviour lives in the
+ * SdkClient base (core/SdkClient.kt); this class binds the API-specific
+ * entity accessors and the test-mode constructor.
+ */
+class ProjectNameSDK(options: MutableMap<String, Any?>?) : SdkClient(options) {
+
+  constructor() : this(null)
+
+  // <[SLOT]>
+
+  companion object {
+    // testSDK builds a client in test mode: the test feature is activated,
+    // installing the in-memory mock transport (no network activity).
+    fun testSDK(): ProjectNameSDK = testSDK(null, null)
+
+    fun testSDK(
+      testopts: MutableMap<String, Any?>?,
+      sdkopts: MutableMap<String, Any?>?,
+    ): ProjectNameSDK {
+      val sdk = ProjectNameSDK(testOptions(testopts, sdkopts))
+      sdk.mode = "test"
+      return sdk
+    }
+  }
+}

package/project/.sdk/src/cmp/kotlin/fragment/SdkError.fragment.kt

@@ -0,0 +1,24 @@
+package KOTLINPACKAGE.core
+
+/**
+ * ProjectName SDK error. Carries the SDK error code, the operation context,
+ * and cleaned copies of the result and spec at failure time.
+ */
+class SdkError(code: String?, msg: String, ctx: Context?) : RuntimeException(msg) {
+
+  val sdk: String = "ProjectName"
+  var code: String = code ?: ""
+  var msg: String = msg
+
+  @Transient
+  var ctx: Context? = ctx
+
+  @Transient
+  var result: Any? = null
+
+  @Transient
+  var spec: Any? = null
+
+  override val message: String
+    get() = this.msg
+}

package/project/.sdk/src/cmp/kotlin/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "module": "nodenext",
+    "noEmitOnError": true,
+    "outDir":"../dist",
+    "rootDir":".",
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2022",
+    "declaration": true,
+    "declarationDir": "../dist"
+  }
+}

package/project/.sdk/src/cmp/kotlin/utility_kotlin.ts

@@ -0,0 +1,101 @@
+
+import * as Path from 'node:path'
+
+
+import {
+  camelify,
+} from '@voxgig/sdkgen'
+
+import {
+  clone,
+  walk,
+} from '@voxgig/struct'
+
+
+function projectPath(suffix?: string): string {
+  return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
+}
+
+
+// The Kotlin package root for the generated SDK, mirroring how the go target
+// derives GOMODULE: org segment from model.origin, name segment from the
+// model name (e.g. origin voxgig-sdk + name solardemo -> voxgig.solardemosdk).
+// Each runtime piece lives under it: <pkg>.core, <pkg>.utility,
+// <pkg>.utility.struct, <pkg>.feature, <pkg>.entity, <pkg>.sdktest.
+function kotlinPackage(model: any): string {
+  const org = String(model.origin || 'voxgig-sdk')
+    .replace(/-sdk$/, '')
+    .replace(/[^a-zA-Z0-9]/g, '')
+    .toLowerCase()
+  const name = String(model.name)
+    .replace(/[^a-zA-Z0-9]/g, '')
+    .toLowerCase()
+  return org + '.' + name + 'sdk'
+}
+
+
+// Maven/Gradle group coordinates for the generated SDK (used by Package_kotlin).
+function gradleGroup(model: any): string {
+  const org = String(model.origin || 'voxgig-sdk')
+    .replace(/-sdk$/, '')
+    .replace(/[^a-zA-Z0-9]/g, '')
+    .toLowerCase()
+  return 'com.' + org
+}
+
+
+const KOTLIN_KEYWORDS = new Set([
+  // hard keywords
+  'as', 'break', 'class', 'continue', 'do', 'else', 'false', 'for', 'fun',
+  'if', 'in', 'interface', 'is', 'null', 'object', 'package', 'return',
+  'super', 'this', 'throw', 'true', 'try', 'typealias', 'typeof', 'val',
+  'var', 'when', 'while',
+])
+
+
+// A camelCase Kotlin identifier for a snake_case model name
+// (`status_embed_config` -> `statusEmbedConfig`), with a reserved-word
+// guard (a `fun`/`class` entity must not bind a Kotlin keyword).
+function kotlinVarName(name: string): string {
+  const pascal = camelify(name)
+  const out = pascal.charAt(0).toLowerCase() + pascal.slice(1)
+  return KOTLIN_KEYWORDS.has(out) ? out + '_' : out
+}
+
+
+// Strip model bookkeeping keys (ending in $) from a config subtree.
+function cleanModel(o: any) {
+  return walk(clone(o), (k: any, v: any, p: any) => {
+    if (null != k && k.endsWith('$')) {
+      delete p[k]
+    }
+    return v
+  })
+}
+
+
+// Render a JSON-able value as Kotlin source that rebuilds it via a
+// StringBuilder of JSON chunks (parsed at runtime by utility/Json.kt). Each
+// line becomes its own append so no single string constant can approach the
+// 64KB class-file limit. `$` is escaped as `\$` because Kotlin string
+// literals treat `$` as a template-expression introducer.
+function jsonAppendLines(value: any, bufname: string): string {
+  const json = JSON.stringify(value, null, 1)
+  return json
+    .split('\n')
+    .map((line) => {
+      const lit = JSON.stringify(line).replace(/\$/g, '\\$')
+      return `    ${bufname}.append(${lit})\n`
+    })
+    .join('')
+}
+
+
+export {
+  cleanModel,
+  gradleGroup,
+  kotlinPackage,
+  kotlinVarName,
+  jsonAppendLines,
+  projectPath,
+}

package/project/.sdk/src/cmp/lua/Entity_lua.ts

@@ -62,15 +62,13 @@ const Entity = cmp(function Entity(props: any) {
           // Entity.fragment.lua so the class can be renamed independently.
           EntyClass: cls,
 
-          // Fill the six per-op pipeline hook markers with real feature_hook
-          // calls. jostraca's `//`-based `#Name` slot pattern does not fire for
-          // Lua's `-- #`-comment markers, so substitute them as literal keys
-          // (exactly like the op fragments above).
-          ...Object.fromEntries(
-            ['PrePoint', 'PreSpec', 'PreRequest', 'PreResponse', 'PreResult', 'PreDone']
-              .map((h: string) => [`-- #${h}-Hook`,
-              ({ indent }: any) => Content({ indent }, `utility.feature_hook(ctx, "${h}")`)])
-          ),
+          // Feature-hook wiring: the built-in `#Name-Hook` tag replacement
+          // is hardwired to `//` line comments, so Lua's `-- #PrePoint-Hook`
+          // markers were never matched and no pipeline hooks fired in
+          // generated code. Match the Lua-comment hook tags explicitly.
+          '/(?<indent>[ \\t]*)-- #(?<name>[A-Za-z0-9]+)-Hook[ \\t]*\\n?/':
+            ({ name, indent }: any) =>
+              `${indent}utility.feature_hook(ctx, "${name}")\n`,
 
           ...opfrags,
         }

package/project/.sdk/src/cmp/lua/TestEntity_lua.ts

@@ -45,6 +45,12 @@ const TestEntity = cmp(function TestEntity(props: any) {
   const target = props.target
   const entity: ModelEntity = props.entity
 
+  // The stream test streams the "list" op and asserts a 3-item collection, so
+  // it only applies to entities that declare a list op. Others (e.g. Batch =
+  // create/load) have no list endpoint — make_point errors and the stream
+  // yields nothing — so skip the stream test for them.
+  const hasList = !!(entity.op && (entity.op as any).list)
+
   const basicflow: ModelEntityFlow | undefined =
     getModelPath(model, `main.${KIT}.flow.Basic${nom(entity, 'Name')}Flow`)
   if (null == basicflow || true !== basicflow.active) {
@@ -91,7 +97,48 @@ describe("${entity.Name}Entity", function()
     local ent = testsdk:${entity.Name}(nil)
     assert.is_not_nil(ent)
   end)
+${hasList ? `
+  -- Feature #4: the entity stream(action, ...) method runs the op pipeline and
+  -- returns an iterator over result items. With the streaming feature active it
+  -- yields the feature's incremental output; otherwise it falls back to the
+  -- materialised list so stream always yields.
+  it("should stream", function()
+    local seed = {
+      entity = {
+        ["${entity.name}"] = {
+          s1 = { id = "s1" },
+          s2 = { id = "s2" },
+          s3 = { id = "s3" },
+        },
+      },
+    }
 
+    -- Fallback: streaming inactive -> yields the materialised list items.
+    local base = sdk.test(seed, nil)
+    local seen = {}
+    for item in base:${entity.Name}(nil):stream("list", nil, nil) do
+      table.insert(seen, item)
+    end
+    assert.are.equal(3, #seen)
+
+    -- Inbound: streaming active -> yields each item from the feature.
+    local config = require("config")()
+    if type(config.feature) == "table" and config.feature.streaming ~= nil then
+      local streamsdk = sdk.test(seed, { feature = { streaming = { active = true } } })
+      local got = {}
+      for item in streamsdk:${entity.Name}(nil):stream("list", nil, nil) do
+        if vs.islist(item) then
+          for _, sub in ipairs(item) do
+            table.insert(got, sub)
+          end
+        else
+          table.insert(got, item)
+        end
+      end
+      assert.are.equal(3, #got)
+    end
+  end)
+` : ''}
   it("should run basic flow", function()
     local setup = ${entity.name}_basic_setup(nil)
     -- Per-op sdk-test-control.json skip.