@voxgig/sdkgen 0.35.2 → 0.36.0

package/project/.sdk/tm/rb/utility/transform_request.rb

@@ -0,0 +1,15 @@
+# ProjectName SDK utility: transform_request
+require_relative 'struct/voxgig_struct'
+require_relative '../core/helpers'
+module ProjectNameUtilities
+  TransformRequest = ->(ctx) {
+    spec = ctx.spec
+    point = ctx.point
+    spec.step = "reqform" if spec
+    transform = ProjectNameHelpers.to_map(VoxgigStruct.getprop(point, "transform"))
+    return ctx.reqdata unless transform
+    reqform = VoxgigStruct.getprop(transform, "req")
+    return ctx.reqdata unless reqform
+    VoxgigStruct.transform({ "reqdata" => ctx.reqdata }, reqform)
+  }
+end

package/project/.sdk/tm/rb/utility/transform_response.rb

@@ -0,0 +1,23 @@
+# ProjectName SDK utility: transform_response
+require_relative 'struct/voxgig_struct'
+require_relative '../core/helpers'
+module ProjectNameUtilities
+  TransformResponse = ->(ctx) {
+    spec = ctx.spec
+    result = ctx.result
+    point = ctx.point
+    spec.step = "resform" if spec
+    return nil if result.nil? || !result.ok
+    transform = ProjectNameHelpers.to_map(VoxgigStruct.getprop(point, "transform"))
+    return nil unless transform
+    resform = VoxgigStruct.getprop(transform, "res")
+    return nil unless resform
+    resdata = VoxgigStruct.transform({
+      "ok" => result.ok, "status" => result.status, "statusText" => result.status_text,
+      "headers" => result.headers, "body" => result.body, "err" => result.err,
+      "resdata" => result.resdata, "resmatch" => result.resmatch,
+    }, resform)
+    result.resdata = resdata
+    resdata
+  }
+end

package/src/cmp/Readme.ts

@@ -8,6 +8,8 @@ import { ReadmeQuick } from './ReadmeQuick'
 import { ReadmeModel } from './ReadmeModel'
 import { ReadmeOptions } from './ReadmeOptions'
 import { ReadmeEntity } from './ReadmeEntity'
+import { ReadmeHowto } from './ReadmeHowto'
+import { ReadmeExplanation } from './ReadmeExplanation'
 import { ReadmeRef } from './ReadmeRef'
 
 
@@ -17,19 +19,17 @@ const Readme = cmp(function Readme(props: any) {
 
   File({ name: 'README.md' }, () => {
 
-    Content(`
-# ${model.Name} ${target.title} SDK
-`)
-    // Sections
     ReadmeIntro({ target })
     ReadmeInstall({ target })
     ReadmeQuick({ target })
+    ReadmeHowto({ target })
     ReadmeModel({ target })
     ReadmeOptions({ target })
     ReadmeEntity({ target })
+    ReadmeExplanation({ target })
 
     Content(`
-## Reference
+## Full Reference
 
 See [REFERENCE.md](REFERENCE.md) for complete API reference
 documentation including all method signatures, entity field schemas,

package/src/cmp/ReadmeEntity.ts

@@ -7,22 +7,25 @@ import {
 } from '../types'
 
 
-const OP_DESC: Record<string, { method: string, desc: string }> = {
-  load: { method: 'load(match)', desc: 'Load a single entity by match criteria.' },
-  list: { method: 'list(match)', desc: 'List entities matching the criteria.' },
-  create: { method: 'create(data)', desc: 'Create a new entity with the given data.' },
-  update: { method: 'update(data)', desc: 'Update an existing entity.' },
-  remove: { method: 'remove(match)', desc: 'Remove the matching entity.' },
+const OP_DESC: Record<string, { method: string, goMethod: string, desc: string }> = {
+  load: { method: 'load(match)', goMethod: 'Load(match, ctrl)', desc: 'Load a single entity by match criteria.' },
+  list: { method: 'list(match)', goMethod: 'List(match, ctrl)', desc: 'List entities matching the criteria.' },
+  create: { method: 'create(data)', goMethod: 'Create(data, ctrl)', desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(data)', goMethod: 'Update(data, ctrl)', desc: 'Update an existing entity.' },
+  remove: { method: 'remove(match)', goMethod: 'Remove(match, ctrl)', desc: 'Remove the matching entity.' },
 }
 
 
 const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
-  const { ctx$: { model } } = props
+  const { target } = props
+  const { model } = props.ctx$
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
+  const isGo = target.name === 'go'
+  const lang = isGo ? 'go' : 'ts'
 
   const publishedEntities = each(entity)
-    .filter((entity: any) => entity.publish)
+    .filter((entity: any) => entity.active !== false)
 
   if (0 === publishedEntities.length) {
     return
@@ -36,7 +39,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
-    const fields = entity.field || []
+    const fields = entity.fields || []
 
     Content(`
 ### ${entity.Name}
@@ -49,9 +52,16 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`const ${entity.name} = client.${entity.Name}()\`
+    if (isGo) {
+      Content(`Create an instance: \`${entity.name} := client.${entity.Name}(nil)\`
 
 `)
+    }
+    else {
+      Content(`Create an instance: \`const ${entity.name} = client.${entity.Name}()\`
+
+`)
+    }
 
     // Operations table
     if (opnames.length > 0) {
@@ -63,7 +73,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
       opnames.map((opname: string) => {
         const info = OP_DESC[opname]
         if (info) {
-          Content(`| \`${info.method}\` | ${info.desc} |
+          const method = isGo ? info.goMethod : info.method
+          Content(`| \`${method}\` | ${info.desc} |
 `)
         }
       })
@@ -91,42 +102,83 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     // Example usage
-    if (opnames.includes('load')) {
-      Content(`#### Example: Load
+    if (isGo) {
+      if (opnames.includes('load')) {
+        Content(`#### Example: Load
+
+\`\`\`go
+result, err := client.${entity.Name}(nil).Load(map[string]any{"id": "${entity.name}_id"}, nil)
+\`\`\`
+
+`)
+      }
+
+      if (opnames.includes('list')) {
+        Content(`#### Example: List
+
+\`\`\`go
+results, err := client.${entity.Name}(nil).List(nil, nil)
+\`\`\`
+
+`)
+      }
+
+      if (opnames.includes('create')) {
+        Content(`#### Example: Create
+
+\`\`\`go
+result, err := client.${entity.Name}(nil).Create(map[string]any{
+`)
+        each(fields, (field: any) => {
+          if ('id' !== field.name && field.req) {
+            Content(`    "${field.name}": /* ${field.type || 'value'} */,
+`)
+          }
+        })
+        Content(`}, nil)
+\`\`\`
+
+`)
+      }
+    }
+    else {
+      if (opnames.includes('load')) {
+        Content(`#### Example: Load
 
 \`\`\`ts
 const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_id' })
 \`\`\`
 
 `)
-    }
+      }
 
-    if (opnames.includes('list')) {
-      Content(`#### Example: List
+      if (opnames.includes('list')) {
+        Content(`#### Example: List
 
 \`\`\`ts
 const ${entity.name}s = await client.${entity.Name}().list()
 \`\`\`
 
 `)
-    }
+      }
 
-    if (opnames.includes('create')) {
-      Content(`#### Example: Create
+      if (opnames.includes('create')) {
+        Content(`#### Example: Create
 
 \`\`\`ts
 const ${entity.name} = await client.${entity.Name}().create({
 `)
-      each(fields, (field: any) => {
-        if ('id' !== field.name && field.req) {
-          Content(`  ${field.name}: /* ${field.type || 'value'} */,
+        each(fields, (field: any) => {
+          if ('id' !== field.name && field.req) {
+            Content(`  ${field.name}: /* ${field.type || 'value'} */,
 `)
-        }
-      })
-      Content(`})
+          }
+        })
+        Content(`})
 \`\`\`
 
 `)
+      }
     }
 
   })

package/src/cmp/ReadmeExplanation.ts

@@ -0,0 +1,333 @@
+
+import { cmp, each, names, Content } from 'jostraca'
+
+import {
+  KIT,
+  getModelPath
+} from '../types'
+
+import { requirePath } from '../utility'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  Content(`
+## Explanation
+
+### The operation pipeline
+
+Every entity operation (load, list, create, update, remove) follows a
+six-stage pipeline. Each stage fires a feature hook before executing:
+
+\`\`\`
+PrePoint \u2192 PreSpec \u2192 PreRequest \u2192 PreResponse \u2192 PreResult \u2192 PreDone
+\`\`\`
+
+- **PrePoint**: Resolves which API endpoint to call based on the
+  operation name and entity configuration.
+- **PreSpec**: Builds the HTTP spec \u2014 URL, method, headers, body \u2014
+  from the resolved point and the caller's parameters.
+- **PreRequest**: Sends the HTTP request. Features can intercept here
+  to replace the transport (as TestFeature does with mocks).
+- **PreResponse**: Parses the raw HTTP response.
+- **PreResult**: Extracts the business data from the parsed response.
+- **PreDone**: Final stage before returning to the caller. Entity
+  state (match, data) is updated here.
+
+`)
+
+  // Target-specific error description
+  if (target.name === 'py') {
+    Content(`If any stage returns an error, the pipeline short-circuits and the
+error is returned to the caller as the second element in the return tuple.
+
+`)
+  }
+  else if (target.name === 'php') {
+    Content(`If any stage returns an error, the pipeline short-circuits and the
+error is returned to the caller as the second element in the return array.
+
+`)
+  }
+  else if (target.name === 'rb') {
+    Content(`If any stage returns an error, the pipeline short-circuits and the
+error is returned to the caller as a second return value.
+
+`)
+  }
+  else if (target.name === 'lua') {
+    Content(`If any stage returns an error, the pipeline short-circuits and the
+error is returned to the caller as a second return value.
+
+`)
+  }
+  else if (target.name === 'go') {
+    Content(`If any stage returns an error, the pipeline short-circuits and the
+error is returned to the caller. An unexpected panic triggers the
+\`PreUnexpected\` hook.
+
+`)
+  }
+  else {
+    Content(`If any stage returns an error, the pipeline short-circuits and the
+error is returned to the caller.
+
+An unexpected exception triggers the \`PreUnexpected\` hook before
+propagating.
+
+`)
+  }
+
+
+  // Features and hooks
+  Content(`### Features and hooks
+
+`)
+
+  if (target.name === 'py') {
+    Content(`Features are the extension mechanism. A feature is a Python class
+with hook methods named after pipeline stages (e.g. \`PrePoint\`,
+\`PreSpec\`). Each method receives the context.
+
+`)
+  }
+  else if (target.name === 'php') {
+    Content(`Features are the extension mechanism. A feature is a PHP class
+with hook methods named after pipeline stages (e.g. \`PrePoint\`,
+\`PreSpec\`). Each method receives the context.
+
+`)
+  }
+  else if (target.name === 'rb') {
+    Content(`Features are the extension mechanism. A feature is a Ruby class
+with hook methods named after pipeline stages (e.g. \`PrePoint\`,
+\`PreSpec\`). Each method receives the context.
+
+`)
+  }
+  else if (target.name === 'lua') {
+    Content(`Features are the extension mechanism. A feature is a Lua table
+with hook methods named after pipeline stages (e.g. \`PrePoint\`,
+\`PreSpec\`). Each method receives the context.
+
+`)
+  }
+  else if (target.name === 'go') {
+    Content(`Features are the extension mechanism. A feature implements the
+\`Feature\` interface and provides hooks \u2014 functions keyed by pipeline
+stage names.
+
+`)
+  }
+  else {
+    Content(`Features are the extension mechanism. A feature is an object with a
+\`hooks\` map. Each hook key is a pipeline stage name, and the value is
+a function that receives the context.
+
+`)
+  }
+
+  Content(`The SDK ships with built-in features:
+
+`)
+  each(feature, (feat: any) => {
+    if (!feat.active) return
+    if (!feat.Name) names(feat, feat.name)
+    const purpose = feat.title || feat.Name || feat.name
+    Content(`- **${feat.Name}Feature**: ${purpose}
+`)
+  })
+
+  Content(`
+Features are initialized in order. Hooks fire in the order features
+were added, so later features can override earlier ones.
+
+`)
+
+
+  // Target-specific explanation
+  const ReadmeExplanation_sdk =
+    requirePath(ctx$, `./cmp/${target.name}/ReadmeExplanation_${target.name}`, { ignore: true })
+
+  if (ReadmeExplanation_sdk) {
+    ReadmeExplanation_sdk['ReadmeExplanation']({ target })
+  }
+
+
+  // Entity state
+  Content(`### Entity state
+
+`)
+
+  if (target.name === 'py') {
+    Content(`Entity instances are stateful. After a successful \`load\`, the entity
+stores the returned data and match criteria internally.
+
+\`\`\`python
+moon = client.Moon()
+moon.load({"planet_id": "earth", "id": "luna"})
+
+# moon.data_get() now returns the loaded moon data
+# moon.match_get() returns the last match criteria
+\`\`\`
+
+Call \`make()\` to create a fresh instance with the same configuration
+but no stored state.
+
+`)
+  }
+  else if (target.name === 'php') {
+    Content(`Entity instances are stateful. After a successful \`load\`, the entity
+stores the returned data and match criteria internally.
+
+\`\`\`php
+$moon = $client->Moon();
+[$result, $err] = $moon->load(["planet_id" => "earth", "id" => "luna"]);
+
+// $moon->dataGet() now returns the loaded moon data
+// $moon->matchGet() returns the last match criteria
+\`\`\`
+
+Call \`make()\` to create a fresh instance with the same configuration
+but no stored state.
+
+`)
+  }
+  else if (target.name === 'rb') {
+    Content(`Entity instances are stateful. After a successful \`load\`, the entity
+stores the returned data and match criteria internally.
+
+\`\`\`ruby
+moon = client.Moon
+moon.load({ "planet_id" => "earth", "id" => "luna" })
+
+# moon.data_get now returns the loaded moon data
+# moon.match_get returns the last match criteria
+\`\`\`
+
+Call \`make\` to create a fresh instance with the same configuration
+but no stored state.
+
+`)
+  }
+  else if (target.name === 'lua') {
+    Content(`Entity instances are stateful. After a successful \`load\`, the entity
+stores the returned data and match criteria internally.
+
+\`\`\`lua
+local moon = client:Moon(nil)
+moon:load({ planet_id = "earth", id = "luna" }, nil)
+
+-- moon:data_get() now returns the loaded moon data
+-- moon:match_get() returns the last match criteria
+\`\`\`
+
+Call \`make()\` to create a fresh instance with the same configuration
+but no stored state.
+
+`)
+  }
+  else if (target.name === 'go') {
+    Content(`Entity instances are stateful. After a successful \`Load\`, the entity
+stores the returned data and match criteria internally.
+
+\`\`\`go
+moon := client.Moon(nil)
+moon.Load(map[string]any{"planet_id": "earth", "id": "luna"}, nil)
+
+// moon.Data() now returns the loaded moon data
+// moon.Match() returns the last match criteria
+\`\`\`
+
+Call \`Make()\` to create a fresh instance with the same configuration
+but no stored state.
+
+`)
+  }
+  else {
+    Content(`Entity instances are stateful. After a successful \`load\`, the entity
+stores the returned data and match criteria internally. Subsequent
+calls on the same instance can rely on this state.
+
+\`\`\`ts
+const moon = client.Moon()
+await moon.load({ planet_id: 'earth', id: 'luna' })
+
+// moon.data() now returns the loaded moon data
+// moon.match() returns { planet_id: 'earth', id: 'luna' }
+\`\`\`
+
+Call \`make()\` to create a fresh instance with the same configuration
+but no stored state.
+
+`)
+  }
+
+
+  // Direct vs entity access
+  Content(`### Direct vs entity access
+
+The entity interface handles URL construction, parameter placement,
+and response parsing automatically. Use it for standard CRUD operations.
+
+`)
+
+  if (target.name === 'py') {
+    Content(`\`direct()\` gives full control over the HTTP request. Use it for
+non-standard endpoints, bulk operations, or any path not modelled as
+an entity. \`prepare()\` builds the request without sending it \u2014 useful
+for debugging or custom transport.
+
+`)
+  }
+  else if (target.name === 'php') {
+    Content(`\`direct()\` gives full control over the HTTP request. Use it for
+non-standard endpoints, bulk operations, or any path not modelled as
+an entity. \`prepare()\` builds the request without sending it \u2014 useful
+for debugging or custom transport.
+
+`)
+  }
+  else if (target.name === 'rb') {
+    Content(`\`direct\` gives full control over the HTTP request. Use it for
+non-standard endpoints, bulk operations, or any path not modelled as
+an entity. \`prepare\` builds the request without sending it \u2014 useful
+for debugging or custom transport.
+
+`)
+  }
+  else if (target.name === 'lua') {
+    Content(`\`direct()\` gives full control over the HTTP request. Use it for
+non-standard endpoints, bulk operations, or any path not modelled as
+an entity. \`prepare()\` builds the request without sending it \u2014 useful
+for debugging or custom transport.
+
+`)
+  }
+  else if (target.name === 'go') {
+    Content(`\`Direct()\` gives full control over the HTTP request. Use it for
+non-standard endpoints, bulk operations, or any path not modelled as
+an entity. \`Prepare()\` builds the request without sending it \u2014 useful
+for debugging or custom transport.
+
+`)
+  }
+  else {
+    Content(`The \`direct\` method gives full control over the HTTP request. Use it
+for non-standard endpoints, bulk operations, or any path not modelled
+as an entity. The \`prepare\` method is useful for debugging \u2014 it
+shows exactly what \`direct\` would send.
+
+`)
+  }
+
+})
+
+
+export {
+  ReadmeExplanation
+}

package/src/cmp/ReadmeHowto.ts

@@ -0,0 +1,28 @@
+
+import { cmp, Content } from 'jostraca'
+
+import { requirePath } from '../utility'
+
+
+const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
+  const { target, ctx$ } = props
+
+  Content(`
+## How-to guides
+
+`)
+
+  const ReadmeHowto_sdk =
+    requirePath(ctx$, `./cmp/${target.name}/ReadmeHowto_${target.name}`, { ignore: true })
+
+  if (ReadmeHowto_sdk) {
+    ReadmeHowto_sdk['ReadmeHowto']({ target })
+  }
+})
+
+
+
+
+export {
+  ReadmeHowto
+}

package/src/cmp/ReadmeIntro.ts

@@ -7,38 +7,24 @@ import {
 } from '../types'
 
 
+const TARGET_INTRO: Record<string, string> = {
+  ts: 'Provides a type-safe,\nentity-oriented interface with full async/await support.',
+  go: 'Provides an entity-oriented interface\nusing standard Go conventions \u2014 no generics required, data flows as\n`map[string]any`.',
+  js: 'Provides an entity-oriented\ninterface with full async/await support.',
+}
+
+
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
   const desc = model.main.def.desc || ''
-  const entity = getModelPath(model, `main.${KIT}.entity`)
-
-  const entityNames = Object.values(entity)
-    .filter((e: any) => e.publish)
-    .map((e: any) => `\`${e.Name}\``)
-
-  Content(`
-## Introduction
 
-${desc}
-`)
-
-  if (entityNames.length > 0) {
-    Content(`
-This SDK provides an entity-oriented interface for the ${model.Name} API.
-The following entities are available: ${entityNames.join(', ')}.
-
-`)
-  }
+  const targetIntro = TARGET_INTRO[target.name] || 'Provides an entity-oriented interface.'
 
-  Content(`
-### Features
+  Content(`# ${model.Name} ${target.title} SDK
 
-- Entity-based API: work with business objects directly.
-- Type safe: full TypeScript definitions included.
-- Direct HTTP access: call any API endpoint using \`client.direct()\`.
-- Testable: built-in test mode with mock support.
+The ${target.title} SDK for the ${model.Name} API. ${targetIntro}
 
 `)