@voxgig/sdkgen 0.44.0 → 1.0.1

package/project/.sdk/src/cmp/js/TestEntity_js.ts

@@ -29,6 +29,7 @@ import {
   Slot,
   cmp,
   each,
+  isAuthActive,
 } from '@voxgig/sdkgen'
 
 
@@ -37,19 +38,36 @@ import {
 } from './utility_js'
 
 
-type OpGen = (model: any, entity: any, flow: any, step: any, index: { key$: number, val$: any }) => void
+// See TestEntity_ts.ts for the GenCtx/OpGen contract — this file mirrors
+// it exactly, the only difference being the language string emitted.
+type GenCtx = {
+  model: Model
+  entity: ModelEntity
+  flow: ModelEntityFlow
+  PROJUPPER: string
+}
+
+type OpGen = (ctx: GenCtx, step: ModelEntityFlowStep, index: number) => void
 
 
 const TestEntity = cmp(function TestEntity(props: any) {
   const ctx$ = props.ctx$
-  const model = ctx$.model
+  const model: Model = ctx$.model
   const stdrep = ctx$.stdrep
 
   const target = props.target
-  const entity = props.entity
+  const entity: ModelEntity = props.entity
 
   const PROJENVNAME = nom(model.const, 'NAME').replace(/[^A-Z_]/g, '_')
   const ENTENVNAME = nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')
+  const authActive = isAuthActive(model)
+  const apikeyEnvEntry = authActive
+    ? `\n    '${PROJENVNAME}_APIKEY': 'NONE',`
+    : ''
+  const apikeyLiveField = authActive
+    ? `
+        apikey: env.${PROJENVNAME}_APIKEY,`
+    : ''
 
   // TODO: should be a utility function
   const ff = projectPath('src/cmp/js/fragment/')
@@ -67,7 +85,7 @@ const TestEntity = cmp(function TestEntity(props: any) {
         }
       }, () => {
 
-        const basicflow = getModelPath(model, `main.${KIT}.flow.Basic${entity.Name}Flow`)
+        const basicflow = getModelPath(model, `main.${KIT}.flow.Basic${nom(entity, 'Name')}Flow`)
 
         const dobasic = basicflow && true === basicflow.active
 
@@ -123,16 +141,14 @@ function basicSetup(extra) {
   const env = envOverride({
     '${PROJENVNAME}_TEST_${ENTENVNAME}_ENTID': idmap,
     '${PROJENVNAME}_TEST_LIVE': 'FALSE',
-    '${PROJENVNAME}_TEST_EXPLAIN': 'FALSE',
-    '${PROJENVNAME}_APIKEY': 'NONE',
+    '${PROJENVNAME}_TEST_EXPLAIN': 'FALSE',${apikeyEnvEntry}
   })
 
   idmap = env['${PROJENVNAME}_TEST_${ENTENVNAME}_ENTID']
 
   if ('TRUE' === env.${PROJENVNAME}_TEST_LIVE) {
     client = new ${model.Name}SDK(merge([
-      {
-        apikey: env.${PROJENVNAME}_APIKEY,
+      {${apikeyLiveField}
       },
       extra
     ]))
@@ -179,10 +195,15 @@ function basicSetup(extra) {
 `)
           }
 
-          each(basicflow.step, (step: any, index: any) => {
-            const opgen: OpGen = GENERATE_OP[step.op]
-            opgen(model, entity, basicflow, step, index)
-            Content('\n')
+          const genCtx: GenCtx = {
+            model, entity, flow: basicflow, PROJUPPER: PROJENVNAME,
+          }
+          each(basicflow.step, (step: ModelEntityFlowStep, index: number) => {
+            const opgen = GENERATE_OP[step.op]
+            if (null != opgen) {
+              opgen(genCtx, step, index)
+              Content('\n')
+            }
           })
         })
       })
@@ -191,25 +212,20 @@ function basicSetup(extra) {
 })
 
 
-const generateCreate: OpGen = (
-  model: Model,
-  entity: ModelEntity,
-  flow: ModelEntityFlow,
-  step: ModelEntityFlowStep,
-  index: any
-) => {
+const generateCreate: OpGen = (ctx, step, index) => {
+  const { entity, flow } = ctx
   const ref = step.input.ref ?? entity.name + '_ref01'
   const entvar = step.input.entvar ?? ref + '_ent'
   const datavar = step.input.datavar ?? (ref + '_data' + (step.input.suffix ?? ''))
 
-  const priorSteps = Object.values(flow.step).slice(0, Number(index))
-  const needsEnt = !priorSteps.some((s: any) =>
+  const priorSteps = flow.step.slice(0, Number(index))
+  const needsEnt = !priorSteps.some(s =>
     ['create', 'list', 'load', 'update', 'remove'].includes(s.op))
 
-  const hasDatvar = priorSteps.some((s: any) => {
+  const hasDatvar = priorSteps.some(s => {
     if ('create' === s.op) {
-      const priorRef = s.input?.ref ?? entity.name + '_ref01'
-      const priorDatvar = s.input?.datavar ?? (priorRef + '_data' + (s.input?.suffix ?? ''))
+      const priorRef = s.input.ref ?? entity.name + '_ref01'
+      const priorDatvar = s.input.datavar ?? (priorRef + '_data' + (s.input.suffix ?? ''))
       return priorDatvar === datavar
     }
     return false
@@ -235,27 +251,31 @@ const generateCreate: OpGen = (
 `)
   })
 
+  const hasEntIdC = null != entity.id
+
   Content(`
     ${datavar} = await ${entvar}.create(${datavar})
-    assert(null != ${datavar}.id)
 `)
+  if (hasEntIdC) {
+    Content(`    assert(null != ${datavar}.id)
+`)
+  }
+  else {
+    Content(`    assert(null != ${datavar})
+`)
+  }
 }
 
 
-const generateList: OpGen = (
-  model: Model,
-  entity: ModelEntity,
-  flow: ModelEntityFlow,
-  step: ModelEntityFlowStep,
-  index: any
-) => {
+const generateList: OpGen = (ctx, step, index) => {
+  const { entity, flow } = ctx
   const ref = step.input.ref ?? entity.name + '_ref01'
   const entvar = step.input.entvar ?? ref + '_ent'
   const matchvar = step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? ''))
   const listvar = step.input.listvar ?? (ref + '_list' + (step.input.suffix ?? ''))
 
-  const priorSteps = Object.values(flow.step).slice(0, Number(index))
-  const needsEnt = !priorSteps.some((s: any) =>
+  const priorSteps = flow.step.slice(0, Number(index))
+  const needsEnt = !priorSteps.some(s =>
     ['create', 'list', 'load', 'update', 'remove'].includes(s.op))
 
   Content(`
@@ -276,12 +296,12 @@ const generateList: OpGen = (
   Content(`
     const ${listvar} = await ${entvar}.list(${matchvar})
 `)
-  const allSteps = Object.values(flow.step)
+  const allSteps = flow.step
   for (let vI = 0; vI < step.valid.length; vI++) {
     const validator = step.valid[vI]
     const validRef = validator.def?.ref
-    const hasRefData = validRef && allSteps.some((s: any) => 'create' === s.op &&
-      ((s.input?.ref ?? entity.name + '_ref01') === validRef))
+    const hasRefData = validRef && allSteps.some(s => 'create' === s.op &&
+      ((s.input.ref ?? entity.name + '_ref01') === validRef))
 
     if ('ItemExists' === validator.apply && hasRefData) {
       Content(`
@@ -297,13 +317,8 @@ const generateList: OpGen = (
 }
 
 
-const generateUpdate: OpGen = (
-  model: Model,
-  entity: ModelEntity,
-  flow: ModelEntityFlow,
-  step: ModelEntityFlowStep,
-  index: any
-) => {
+const generateUpdate: OpGen = (ctx, step, index) => {
+  const { entity, flow } = ctx
   const ref = step.input.ref ?? entity.name + '_ref01'
   const entvar = step.input.entvar ?? ref + '_ent'
   const datavar = step.input.datavar ?? (ref + '_data' + (step.input.suffix ?? ''))
@@ -311,10 +326,12 @@ const generateUpdate: OpGen = (
   const markdefvar = step.input.markdefvar ?? (ref + '_markdef' + (step.input.suffix ?? ''))
   const srcdatavar = step.input.srcdatavar ?? (ref + '_data' + (step.input.suffix ?? ''))
 
-  const priorSteps = Object.values(flow.step).slice(0, Number(index))
-  const needsEnt = !priorSteps.some((s: any) =>
+  const priorSteps = flow.step.slice(0, Number(index))
+  const needsEnt = !priorSteps.some(s =>
     ['create', 'list', 'load', 'update', 'remove'].includes(s.op))
 
+  const hasEntIdU = null != entity.id
+
   Content(`
     // UPDATE
 `)
@@ -323,8 +340,11 @@ const generateUpdate: OpGen = (
 `)
   }
   Content(`    const ${datavar} = {}
-    ${datavar}.id = ${srcdatavar}.id
 `)
+  if (hasEntIdU) {
+    Content(`    ${datavar}.id = ${srcdatavar}.id
+`)
+  }
 
   each(step.data, (mi: any) => {
     if ('id' !== mi.key$) {
@@ -348,8 +368,15 @@ const generateUpdate: OpGen = (
 
   Content(`
     const ${resdatavar} = await ${entvar}.update(${datavar})
-    assert(${resdatavar}.id === ${datavar}.id)
 `)
+  if (hasEntIdU) {
+    Content(`    assert(${resdatavar}.id === ${datavar}.id)
+`)
+  }
+  else {
+    Content(`    assert(null != ${resdatavar})
+`)
+  }
 
   for (let sI = 0; sI < step.spec.length; sI++) {
     const spec = step.spec[sI]
@@ -363,37 +390,34 @@ const generateUpdate: OpGen = (
 }
 
 
-const generateLoad: OpGen = (
-  model: Model,
-  entity: ModelEntity,
-  flow: ModelEntityFlow,
-  step: ModelEntityFlowStep,
-  index: any
-) => {
+const generateLoad: OpGen = (ctx, step, index) => {
+  const { entity, flow } = ctx
   const ref = step.input.ref ?? entity.name + '_ref01'
   const entvar = step.input.entvar ?? ref + '_ent'
   const matchvar = step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? ''))
   const datavar = step.input.datavar ?? (ref + '_data' + (step.input.suffix ?? ''))
   const srcdatavar = step.input.srcdatavar ?? (ref + '_data' + (step.input.suffix ?? ''))
 
-  const priorSteps = Object.values(flow.step).slice(0, Number(index))
-  const hasEntVar = priorSteps.some((s: any) =>
+  const priorSteps = flow.step.slice(0, Number(index))
+  const hasEntVar = priorSteps.some(s =>
     ['create', 'list', 'load', 'update', 'remove'].includes(s.op))
 
   // Check if srcdatavar was declared by a prior create step or by the
   // preamble bootstrap (which runs when the flow has no create step)
-  const flowHasCreate = Object.values(flow.step).some((s: any) => s.op === 'create')
+  const flowHasCreate = flow.step.some(s => s.op === 'create')
   const preambleRef = entity.name + '_ref01'
   const hasSrcData = (!flowHasCreate && srcdatavar === preambleRef + '_data') ||
-    priorSteps.some((s: any) => {
+    priorSteps.some(s => {
       if ('create' === s.op) {
-        const priorRef = s.input?.ref ?? entity.name + '_ref01'
-        const priorDatvar = s.input?.datavar ?? (priorRef + '_data' + (s.input?.suffix ?? ''))
+        const priorRef = s.input.ref ?? entity.name + '_ref01'
+        const priorDatvar = s.input.datavar ?? (priorRef + '_data' + (s.input.suffix ?? ''))
         return priorDatvar === srcdatavar
       }
       return false
     })
 
+  const hasEntId = null != entity.id
+
   Content(`
     // LOAD
 `)
@@ -401,34 +425,39 @@ const generateLoad: OpGen = (
     Content(`    const ${entvar} = client.${nom(entity, 'Name')}()
 `)
   }
-  if (!hasSrcData) {
+  if (!hasSrcData && hasEntId) {
     Content(`    const ${srcdatavar} = Object.values(setup.data.existing.${entity.name})[0]
 `)
   }
-  Content(`    const ${matchvar} = {}
+  if (hasEntId) {
+    Content(`    const ${matchvar} = {}
     ${matchvar}.id = ${srcdatavar}.id
     const ${datavar} = await ${entvar}.load(${matchvar})
     assert(${datavar}.id === ${srcdatavar}.id)
 `)
+  }
+  else {
+    Content(`    const ${matchvar} = {}
+    const ${datavar} = await ${entvar}.load(${matchvar})
+    assert(null != ${datavar})
+`)
+  }
 }
 
 
-const generateRemove: OpGen = (
-  model: Model,
-  entity: ModelEntity,
-  flow: ModelEntityFlow,
-  step: ModelEntityFlowStep,
-  index: any
-) => {
+const generateRemove: OpGen = (ctx, step, index) => {
+  const { entity, flow } = ctx
   const ref = step.input.ref ?? entity.name + '_ref01'
   const entvar = step.input.entvar ?? ref + '_ent'
   const matchvar = step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? ''))
   const srcdatavar = step.input.srcdatavar ?? (ref + '_data')
 
-  const priorSteps = Object.values(flow.step).slice(0, Number(index))
-  const needsEnt = !priorSteps.some((s: any) =>
+  const priorSteps = flow.step.slice(0, Number(index))
+  const needsEnt = !priorSteps.some(s =>
     ['create', 'list', 'load', 'update', 'remove'].includes(s.op))
 
+  const hasEntIdR = null != entity.id
+
   Content(`
     // REMOVE
 `)
@@ -437,8 +466,12 @@ const generateRemove: OpGen = (
 `)
   }
   Content(`    const ${matchvar} = {}
-    ${matchvar}.id = ${srcdatavar}.id
-    await ${entvar}.remove(${matchvar})
+`)
+  if (hasEntIdR) {
+    Content(`    ${matchvar}.id = ${srcdatavar}.id
+`)
+  }
+  Content(`    await ${entvar}.remove(${matchvar})
   `)
 }
 

package/project/.sdk/src/cmp/js/fragment/Config.fragment.js

@@ -31,11 +31,7 @@ class Config {
   options = {
     base: '$$main.kit.info.servers.0.url$$',
 
-    auth: {
-      prefix: '$$main.kit.config.auth.prefix$$',
-    },
-
-    headers: 'HEADERS',
+    'AUTHBLOCK'headers: 'HEADERS',
 
     entity: {
       // #EntityConfigs

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

@@ -9,6 +9,7 @@ import {
   Line,
   cmp,
   each,
+  isAuthActive,
 } from '@voxgig/sdkgen'
 
 
@@ -37,12 +38,19 @@ const Config = cmp(async function Config(props: any) {
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
+  const authActive = isAuthActive(model)
   let authPrefix = ''
   try { authPrefix = getModelPath(model, `main.${KIT}.config.auth.prefix`) } catch (_e) { }
 
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
 
+  const authBlock = authActive
+    ? `      auth = {
+        prefix = "${authPrefix}",
+      },\n`
+    : ''
+
   File({ name: 'config.' + target.ext }, () => {
 
     Content(`-- ProjectName SDK configuration
@@ -64,10 +72,7 @@ local function make_config()
     Content(`    },
     options = {
       base = "${baseUrl}",
-      auth = {
-        prefix = "${authPrefix}",
-      },
-      headers = ${formatLuaTable(headers, 3)},
+${authBlock}      headers = ${formatLuaTable(headers, 3)},
       entity = {
 `)
 

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

@@ -18,11 +18,18 @@ const Package = cmp(async function Package(props: any) {
 
   const model: Model = ctx$.model
 
+  // Rock name is namespaced to model.origin (e.g. "voxgig-sdk"). LuaRocks has
+  // no real namespaces, so the parts are hyphen-joined. The Lua module name
+  // (`${model.name}_sdk`) used by `require` is unchanged.
+  const ns = model.origin || 'voxgig-sdk'
+  const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
+  const rockName = `${ns}-${pkgBase}`
+
   File({ name: model.name + '.rockspec' }, () => {
-    Content(`package = "${model.name}-sdk"
+    Content(`package = "${rockName}"
 version = "0.0-1"
 source = {
-  url = "git://github.com/voxgig/${model.name}-sdk.git"
+  url = "git://github.com/${ns}/${model.name}-sdk.git"
 }
 description = {
   summary = "${model.const.Name} SDK for Lua",

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

@@ -0,0 +1,138 @@
+
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// Operation method spelling differs between Go and other languages — Go
+// uses PascalCase methods with explicit ctrl arg, others use lowercase
+// methods with optional ctrl. The op descriptions are language-agnostic.
+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 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 || []
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`const ${entity.name} = client.${entity.Name}()\`
+
+`)
+
+    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}\` | \`${field.type || 'any'}\` | ${desc} |
+`)
+      })
+
+      Content(`
+`)
+    }
+
+    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
+
+\`\`\`ts
+const ${entity.name}s = await client.${entity.Name}().list()
+\`\`\`
+
+`)
+    }
+
+    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'} */,
+`)
+        }
+      })
+      Content(`})
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}

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

@@ -1,10 +1,14 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
 
 
 const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
+  const apikeyEnvLine = isAuthActive(model)
+    ? `\n${model.NAME}_APIKEY=<your-key>`
+    : ''
+
   Content(`### Make a direct HTTP request
 
 For endpoints not covered by entity methods:
@@ -80,8 +84,7 @@ local client = sdk.new({
 Create a \`.env.local\` file at the project root:
 
 \`\`\`
-${model.NAME}_TEST_LIVE=TRUE
-${model.NAME}_APIKEY=<your-key>
+${model.NAME}_TEST_LIVE=TRUE${apikeyEnvLine}
 \`\`\`
 
 Then run:

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

@@ -0,0 +1,18 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`# ${model.Name} ${target.title} SDK
+
+The ${target.title} SDK for the ${model.Name} API. Provides an entity-oriented interface using Lua conventions.
+
+`)
+})
+
+
+export {
+  ReadmeIntro
+}

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,6 +13,10 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const entityList = each(entity).filter((e: any) => e.active !== false)
 
+  const apikeyOptionRow = isAuthActive(model)
+    ? '| `apikey` | `string` | API key for authentication. |\n'
+    : ''
+
   Content(`### ${model.const.Name}SDK
 
 \`\`\`lua
@@ -24,8 +28,7 @@ Creates a new SDK client.
 
 | Option | Type | Description |
 | --- | --- | --- |
-| \`apikey\` | \`string\` | API key for authentication. |
-| \`base\` | \`string\` | Base URL of the API server. |
+${apikeyOptionRow}| \`base\` | \`string\` | Base URL of the API server. |
 | \`prefix\` | \`string\` | URL path prefix prepended to all requests. |
 | \`suffix\` | \`string\` | URL path suffix appended to all requests. |
 | \`feature\` | \`table\` | Feature activation flags. |