@voxgig/sdkgen 0.35.1 → 0.36.0

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

@@ -0,0 +1,129 @@
+
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const ReadmeModel = cmp(function ReadmeModel(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
+
+  Content(`### ${model.const.Name}SDK
+
+\`\`\`lua
+local sdk = require("${model.name}_sdk")
+local client = sdk.new(options)
+\`\`\`
+
+Creates a new SDK client.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| \`apikey\` | \`string\` | API key for authentication. |
+| \`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. |
+| \`extend\` | \`table\` | Additional Feature instances to load. |
+| \`system\` | \`table\` | System overrides (e.g. custom \`fetch\` function). |
+
+### test
+
+\`\`\`lua
+local client = sdk.test(testopts, sdkopts)
+\`\`\`
+
+Creates a test-mode client with mock transport. Both arguments may be \`nil\`.
+
+### ${model.const.Name}SDK methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| \`options_map\` | \`() -> table\` | Deep copy of current SDK options. |
+| \`get_utility\` | \`() -> Utility\` | Copy of the SDK utility object. |
+| \`prepare\` | \`(fetchargs) -> table, err\` | Build an HTTP request definition without sending. |
+| \`direct\` | \`(fetchargs) -> table, err\` | Build and send an HTTP request. |
+`)
+
+  each(entityList, (ent: any) => {
+    Content(`| \`${ent.Name}\` | \`(data) -> ${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
+`)
+  })
+
+  Content(`
+### Entity interface
+
+All entities share the same interface.
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| \`load\` | \`(reqmatch, ctrl) -> any, err\` | Load a single entity by match criteria. |
+| \`list\` | \`(reqmatch, ctrl) -> any, err\` | List entities matching the criteria. |
+| \`create\` | \`(reqdata, ctrl) -> any, err\` | Create a new entity. |
+| \`update\` | \`(reqdata, ctrl) -> any, err\` | Update an existing entity. |
+| \`remove\` | \`(reqmatch, ctrl) -> any, err\` | Remove an entity. |
+| \`data_get\` | \`() -> table\` | Get entity data. |
+| \`data_set\` | \`(data)\` | Set entity data. |
+| \`match_get\` | \`() -> table\` | Get entity match criteria. |
+| \`match_set\` | \`(match)\` | Set entity match criteria. |
+| \`make\` | \`() -> Entity\` | Create a new instance with the same options. |
+| \`get_name\` | \`() -> string\` | Return the entity name. |
+
+### Result shape
+
+Entity operations return \`(any, err)\`. The first value is a
+\`table\` with these keys:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| \`ok\` | \`boolean\` | \`true\` if the HTTP status is 2xx. |
+| \`status\` | \`number\` | HTTP status code. |
+| \`headers\` | \`table\` | Response headers. |
+| \`data\` | \`any\` | Parsed JSON response body. |
+
+On error, \`ok\` is \`false\` and \`err\` contains the error value.
+
+`)
+
+  // Entities summary
+  Content(`### Entities
+
+`)
+  each(entityList, (ent: any) => {
+    const fields = ent.fields || []
+    const opnames = Object.keys(ent.op || {})
+    const ops = ent.op || {}
+    const points = each(ops).map((op: any) =>
+      op.points ? each(op.points) : []
+    ).flat()
+    const path = points.length > 0 ? (points[0] as any).orig || '' : ''
+
+    Content(`#### ${ent.Name}
+
+| Field | Description |
+| --- | --- |
+`)
+    each(fields, (field: any) => {
+      Content(`| \`${field.name}\` | ${field.short || ''} |
+`)
+    })
+
+    Content(`
+Operations: ${opnames.map((n: string) => n.charAt(0).toUpperCase() + n.slice(1)).join(', ')}.
+
+API path: \`${path}\`
+
+`)
+  })
+
+})
+
+
+export {
+  ReadmeModel
+}

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

@@ -0,0 +1,99 @@
+
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+const ReadmeQuick = cmp(function ReadmeQuick(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 nestedEntity = Object.values(entity).find((e: any) =>
+    e.active !== false && e.ancestors && e.ancestors.length > 0
+  ) as any
+
+  Content(`### 1. Create a client
+
+\`\`\`lua
+local sdk = require("${model.name}_sdk")
+
+local client = sdk.new({
+  apikey = os.getenv("${model.NAME}_APIKEY"),
+})
+\`\`\`
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const opnames = Object.keys(exampleEntity.op || {})
+
+    if (opnames.includes('list')) {
+      Content(`### 2. List ${eName.toLowerCase()}s
+
+\`\`\`lua
+local result, err = client:${eName}(nil):list(nil, nil)
+if err then error(err) end
+
+if type(result) == "table" then
+  for _, item in ipairs(result) do
+    local d = item:data_get()
+    print(d["id"], d["name"])
+  end
+end
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('load')) {
+      Content(`### 3. Load a ${eName.toLowerCase()}
+
+\`\`\`lua
+local result, err = client:${eName}(nil):load({ id = "example_id" }, nil)
+if err then error(err) end
+print(result)
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+      Content(`### 4. Create, update, and remove
+
+\`\`\`lua
+`)
+      if (opnames.includes('create')) {
+        Content(`-- Create
+local created, _ = client:${eName}(nil):create({ name = "Example" }, nil)
+
+`)
+      }
+      if (opnames.includes('update')) {
+        Content(`-- Update
+client:${eName}(nil):update({ id = created["id"], name = "Example-Renamed" }, nil)
+
+`)
+      }
+      if (opnames.includes('remove')) {
+        Content(`-- Remove
+client:${eName}(nil):remove({ id = created["id"] }, nil)
+`)
+      }
+      Content(`\`\`\`
+
+`)
+    }
+  }
+})
+
+
+export {
+  ReadmeQuick
+}

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

@@ -0,0 +1,24 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
+  const { target } = props
+
+  Content(`**Lua:**
+\`\`\`lua
+local result, err = client:direct({
+  path = "/api/resource/{id}",
+  method = "GET",
+  params = { id = "example" },
+})
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeTopHowto
+}

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

@@ -0,0 +1,55 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+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
+
+  Content(`\`\`\`lua
+local sdk = require("${model.name}_sdk")
+
+local client = sdk.new({
+  apikey = os.getenv("${model.NAME}_APIKEY"),
+})
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const opnames = Object.keys(exampleEntity.op || {})
+
+    if (opnames.includes('list')) {
+      Content(`-- List all ${eName.toLowerCase()}s
+local ${eName.toLowerCase()}s, err = client:${eName}(nil):list(nil, nil)
+`)
+    }
+
+    if (opnames.includes('load')) {
+      Content(`
+-- Load a specific ${eName.toLowerCase()}
+local ${eName.toLowerCase()}, err = client:${eName}(nil):load(
+  { id = "example_id" }, nil
+)
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

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

@@ -0,0 +1,38 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+const ReadmeTopTest = cmp(function ReadmeTopTest(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
+
+  Content(`\`\`\`lua
+local client = sdk.test(nil, nil)
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    Content(`local result, err = client:${eName}(nil):load(
+  { id = "test01" }, nil
+)
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

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

@@ -0,0 +1,261 @@
+
+import {
+  depluralize,
+} from '@voxgig/apidef'
+
+import {
+  Content,
+  File,
+  cmp,
+  snakify,
+} from '@voxgig/sdkgen'
+
+
+function normalizePathParams(
+  parts: string[],
+  params: any[],
+  rename?: Record<string, string>
+): string {
+  return parts.map((part: string) => {
+    return part.replace(/\{([^}]+)\}/g, (match: string, rawName: string) => {
+      const snaked = snakify(rawName)
+      const depluralized = depluralize(snaked)
+      const param = params.find((p: any) =>
+        p.orig === snaked || p.name === snaked ||
+        p.orig === depluralized || p.name === depluralized
+      )
+      if (param) return '{' + param.name + '}'
+
+      if (rename) {
+        for (const [origCamel, renamedTo] of Object.entries(rename)) {
+          if (renamedTo === rawName) {
+            const origSnaked = snakify(origCamel)
+            const origDepluralized = depluralize(origSnaked)
+            const renamedParam = params.find(
+              (p: any) => p.orig === origSnaked || p.name === origSnaked ||
+                p.orig === origDepluralized || p.name === origDepluralized
+            )
+            if (renamedParam) return '{' + renamedParam.name + '}'
+          }
+        }
+      }
+
+      return match
+    })
+  }).join('/')
+}
+
+
+const TestDirect = cmp(function TestDirect(props: any) {
+  const ctx$ = props.ctx$
+  const model = ctx$.model
+
+  const target = props.target
+  const entity = props.entity
+
+  const PROJECTNAME = model.Name.toUpperCase().replace(/[^A-Z_]/g, '_')
+
+  const opnames = Object.keys(entity.op)
+  const hasLoad = opnames.includes('load')
+  const hasList = opnames.includes('list')
+
+  if (!hasLoad && !hasList) {
+    return
+  }
+
+  const loadOp = entity.op.load
+  const listOp = entity.op.list
+
+  const loadPoint = loadOp?.points?.[0]
+  const loadPath = loadPoint ? normalizePathParams(loadPoint.parts || [], loadPoint?.args?.params || [], loadPoint?.rename?.param) : ''
+  const loadParams = loadPoint?.args?.params || []
+
+  const listPoint = listOp?.points?.[0]
+  const listPath = listPoint ? normalizePathParams(listPoint.parts || [], listPoint?.args?.params || [], listPoint?.rename?.param) : ''
+  const listParams = listPoint?.args?.params || []
+
+  const entidEnvVar = `${PROJECTNAME}_TEST_${entity.Name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID`
+
+  File({ name: entity.name + '_direct_test.' + target.ext }, () => {
+
+    Content(`-- ${entity.Name} direct test
+
+local json = require("dkjson")
+local vs = require("utility.struct.struct")
+local sdk = require("${model.name}_sdk")
+local helpers = require("core.helpers")
+local runner = require("test.runner")
+
+describe("${entity.Name}Direct", function()
+`)
+
+    if (hasList && listPoint) {
+      Content(`  it("should direct-list-${entity.name}", function()
+    local setup = ${entity.name}_direct_setup({
+      { id = "direct01" },
+      { id = "direct02" },
+    })
+    local client = setup.client
+
+`)
+
+      if (listParams.length > 0) {
+        Content(`    local params = {}
+`)
+        for (const lp of listParams) {
+          const key = lp.name === 'id'
+            ? entity.name + '01'
+            : lp.name.replace(/_id$/, '') + '01'
+          Content(`    if setup.live then
+      params["${lp.name}"] = setup.idmap["${key}"]
+    else
+      params["${lp.name}"] = "direct01"
+    end
+`)
+        }
+        Content(`
+    local result, err = client:direct({
+      path = "${listPath}",
+      method = "GET",
+      params = params,
+    })
+`)
+      } else {
+        Content(`
+    local result, err = client:direct({
+      path = "${listPath}",
+      method = "GET",
+      params = {},
+    })
+`)
+      }
+
+      Content(`    assert.is_nil(err)
+    assert.is_true(result["ok"])
+    assert.are.equal(200, helpers.to_int(result["status"]))
+
+    if not setup.live then
+      assert.is_table(result["data"])
+      assert.are.equal(2, #result["data"])
+      assert.are.equal(1, #setup.calls)
+    end
+  end)
+
+`)
+    }
+
+    if (hasLoad && loadPoint) {
+      Content(`  it("should direct-load-${entity.name}", function()
+    local setup = ${entity.name}_direct_setup({ id = "direct01" })
+    local client = setup.client
+
+`)
+
+      if (loadParams.length > 0) {
+        Content(`    local params = {}
+    if not setup.live then
+`)
+        for (let i = 0; i < loadParams.length; i++) {
+          Content(`      params["${loadParams[i].name}"] = "direct0${i + 1}"
+`)
+        }
+        Content(`    end
+`)
+      }
+
+      Content(`
+    local result, err = client:direct({
+      path = "${loadPath}",
+      method = "GET",
+`)
+      if (loadParams.length > 0) {
+        Content(`      params = params,
+`)
+      } else {
+        Content(`      params = {},
+`)
+      }
+      Content(`    })
+    assert.is_nil(err)
+    assert.is_true(result["ok"])
+    assert.are.equal(200, helpers.to_int(result["status"]))
+    assert.is_not_nil(result["data"])
+
+    if not setup.live then
+      if type(result["data"]) == "table" then
+        assert.are.equal("direct01", result["data"]["id"])
+      end
+      assert.are.equal(1, #setup.calls)
+    end
+  end)
+
+`)
+    }
+
+    Content(`end)
+
+
+function ${entity.name}_direct_setup(mockres)
+  runner.load_env_local()
+
+  local calls = {}
+
+  local env = runner.env_override({
+    ["${entidEnvVar}"] = {},
+    ["${PROJECTNAME}_TEST_LIVE"] = "FALSE",
+    ["${PROJECTNAME}_APIKEY"] = "NONE",
+  })
+
+  local live = env["${PROJECTNAME}_TEST_LIVE"] == "TRUE"
+
+  if live then
+    local merged_opts = {
+      apikey = env["${PROJECTNAME}_APIKEY"],
+    }
+    local client = sdk.new(merged_opts)
+    return {
+      client = client,
+      calls = calls,
+      live = true,
+      idmap = {},
+    }
+  end
+
+  local function mock_fetch(url, init)
+    table.insert(calls, { url = url, init = init })
+    return {
+      status = 200,
+      statusText = "OK",
+      headers = {},
+      json = function()
+        if mockres ~= nil then
+          return mockres
+        end
+        return { id = "direct01" }
+      end,
+      body = "mock",
+    }, nil
+  end
+
+  local client = sdk.new({
+    base = "http://localhost:8080",
+    system = {
+      fetch = mock_fetch,
+    },
+  })
+
+  return {
+    client = client,
+    calls = calls,
+    live = false,
+    idmap = {},
+  }
+end
+`)
+  })
+})
+
+
+export {
+  TestDirect
+}