@voxgig/sdkgen 0.44.0 → 1.0.1

package/src/cmp/ReadmeEntity.ts

@@ -1,192 +1,25 @@
 
-import { cmp, each, Content } from 'jostraca'
+import { cmp } from 'jostraca'
 
-import {
-  KIT,
-  getModelPath
-} from '../types'
-
-
-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.' },
-}
+import { requirePath } from '../utility'
 
 
+// Per-language Entities section lives in
+// `project/.sdk/src/cmp/<lang>/ReadmeEntity_<lang>.ts`.
+// Each language emits its own create-instance call style and
+// op-method spelling (Go's `Load(match, ctrl)` vs TS's `load(match)`).
 const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
-  const { target } = props
-  const { model } = props.ctx$
+  const { target, ctx$ } = props
 
-  const entity = getModelPath(model, `main.${KIT}.entity`)
-  const isGo = target.name === 'go'
-  const lang = isGo ? 'go' : 'ts'
+  const ReadmeEntity_sdk =
+    requirePath(ctx$, `./cmp/${target.name}/ReadmeEntity_${target.name}`, { ignore: true })
 
-  const publishedEntities = each(entity)
-    .filter((entity: any) => entity.active !== false)
-
-  if (0 === publishedEntities.length) {
-    return
+  if (ReadmeEntity_sdk) {
+    ReadmeEntity_sdk['ReadmeEntity']({ target })
   }
-
-  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}
-
-`)
-    }
-
-    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) {
-      Content(`#### Operations
-
-| Method | Description |
-| --- | --- |
-`)
-      opnames.map((opname: string) => {
-        const info = OP_DESC[opname]
-        if (info) {
-          const method = isGo ? info.goMethod : info.method
-          Content(`| \`${method}\` | ${info.desc} |
-`)
-        }
-      })
-
-      Content(`
-`)
-    }
-
-    // Fields table
-    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(`
-`)
-    }
-
-    // Example usage
-    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
-
-\`\`\`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/src/cmp/ReadmeIntro.ts

@@ -1,38 +1,24 @@
 
-import { cmp, Content } from 'jostraca'
+import { cmp } from 'jostraca'
 
-import {
-  KIT,
-  getModelPath
-} 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.',
-}
+import { requirePath } from '../utility'
 
 
+// Per-language intro lives in `project/.sdk/src/cmp/<lang>/ReadmeIntro_<lang>.ts`.
+// Each language declares its own tagline and stylistic emphasis (Go's
+// `map[string]any` data-flow note, TS's async/await emphasis, etc.).
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
-  const { target } = props
-  const { model } = props.ctx$
-
-  const desc = model.main.def.desc || ''
-
-  const targetIntro = TARGET_INTRO[target.name] || 'Provides an entity-oriented interface.'
+  const { target, ctx$ } = props
 
-  Content(`# ${model.Name} ${target.title} SDK
-
-The ${target.title} SDK for the ${model.Name} API. ${targetIntro}
-
-`)
+  const ReadmeIntro_sdk =
+    requirePath(ctx$, `./cmp/${target.name}/ReadmeIntro_${target.name}`, { ignore: true })
 
+  if (ReadmeIntro_sdk) {
+    ReadmeIntro_sdk['ReadmeIntro']({ target })
+  }
 })
 
 
-
-
 export {
   ReadmeIntro
 }

package/src/cmp/ReadmeModel.ts

@@ -6,7 +6,7 @@ import {
   getModelPath
 } from '../types'
 
-import { requirePath } from '../utility'
+import { requirePath, isAuthActive } from '../utility'
 
 
 const ReadmeModel = cmp(function ReadmeModel(props: any) {
@@ -30,13 +30,16 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   }
   else {
     // Fallback: generic reference summary
-    ReadmeModelGeneric({ target, model, entityList })
+    ReadmeModelGeneric({ target, model, entityList, authActive: isAuthActive(model) })
   }
 })
 
 
 const ReadmeModelGeneric = cmp(function ReadmeModelGeneric(props: any) {
-  const { target, model, entityList } = props
+  const { target, model, entityList, authActive } = props
+  const apikeyRow = authActive
+    ? '| `apikey` | `string` | API key for authentication. |\n'
+    : ''
 
   Content(`### ${model.Name}SDK
 
@@ -44,8 +47,7 @@ const ReadmeModelGeneric = cmp(function ReadmeModelGeneric(props: any) {
 
 | Option | Type | Description |
 | --- | --- | --- |
-| \`apikey\` | \`string\` | API key for authentication. |
-| \`base\` | \`string\` | Base URL of the API server. |
+${apikeyRow}| \`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\` | \`object\` | Feature activation flags. |

package/src/cmp/ReadmeOptions.ts

@@ -1,87 +1,25 @@
 
-import { cmp, each, Content } from 'jostraca'
+import { cmp } from 'jostraca'
 
+import { requirePath } from '../utility'
 
-const ReadmeOptions = cmp(function ReadmeOptions(props: any) {
-  const { target } = props
-  const { model } = props.ctx$
-
-  const isGo = target.name === 'go'
-
-  const publishedOptions = each(target.options)
-    .filter((option: any) => option.publish)
-
-  if (0 === publishedOptions.length) {
-    return
-  }
-
-  Content(`
-
-## Options
-
-Pass options when creating a client instance:
-
-`)
-
-  if (isGo) {
-    Content(`\`\`\`go
-client := sdk.New${model.const.Name}SDK(map[string]any{
-`)
 
-    publishedOptions.map((option: any) => {
-      if ('apikey' === option.name) {
-        Content(`    "${option.name}": os.Getenv("${model.NAME}_APIKEY"),
-`)
-      }
-      else {
-        Content(`    // "${option.name}": ${option.kind === 'string' ? '"..."' : '...'},
-`)
-      }
-    })
-
-    Content(`})
-\`\`\`
-
-`)
-  }
-  else {
-    Content(`\`\`\`ts
-const client = new ${model.Name}SDK({
-`)
-
-    publishedOptions.map((option: any) => {
-      if ('apikey' === option.name) {
-        Content(`  ${option.name}: process.env.${model.NAME}_APIKEY,
-`)
-      }
-      else {
-        Content(`  // ${option.name}: ${option.kind === 'string' ? "'...'" : '...'},
-`)
-      }
-    })
+// Per-language Options block lives in
+// `project/.sdk/src/cmp/<lang>/ReadmeOptions_<lang>.ts`.
+// Each language emits its own constructor-call shape and option-table
+// formatting; they share the data source (target.options).
+const ReadmeOptions = cmp(function ReadmeOptions(props: any) {
+  const { target, ctx$ } = props
 
-    Content(`})
-\`\`\`
+  const ReadmeOptions_sdk =
+    requirePath(ctx$, `./cmp/${target.name}/ReadmeOptions_${target.name}`, { ignore: true })
 
-`)
+  if (ReadmeOptions_sdk) {
+    ReadmeOptions_sdk['ReadmeOptions']({ target })
   }
-
-  Content(`| Option | Type | Description |
-| --- | --- | --- |
-`)
-
-  publishedOptions.map((option: any) => {
-    Content(`| \`${option.name}\` | \`${option.kind}\` | ${option.short} |
-`)
-  })
-
-  Content(`
-`)
-
 })
 
 
-
 export {
   ReadmeOptions
 }