@voxgig/sdkgen 1.3.14 → 1.3.17

package/project/.sdk/src/cmp/ocaml/ReadmeTopQuick_ocaml.ts

@@ -0,0 +1,86 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { ocamlVarName } from './utility_ocaml'
+
+
+// A type-correct OCaml `value` literal for a param: numeric/boolean/array/
+// object params render a typed literal; strings render the quoted placeholder.
+function ocamlLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
+  if ('BOOLEAN' === k) return '(Bool true)'
+  if ('ARRAY' === k) return '(empty_list ())'
+  if ('OBJECT' === k) return '(empty_map ())'
+  return `(Str "${placeholder}")`
+}
+
+
+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
+
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `Sdk_client.make (jo [("apikey", Str (Sys.getenv "${envName(model)}_APIKEY"))])`
+    : `Sdk_client.make0 ()`
+
+  Content(`\`\`\`ocaml
+open Voxgig_struct
+open Sdk_helpers
+
+let () =
+  let client = ${ctor} in
+`)
+
+  if (exampleEntity) {
+    const fn = ocamlVarName(exampleEntity.name)
+    const opnames = Object.keys(exampleEntity.op || {})
+    // Model-driven id key: null when the entity has no id-like field, in which
+    // case the load example takes no match argument.
+    const idF = entityIdField(exampleEntity)
+
+    if (opnames.includes('list')) {
+      Content(`  (* List all ${fn} records (returns a List value; raises on error) *)
+  let ${fn}s = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval in
+  (match ${fn}s with List items -> List.iter (fun r -> print_endline (stringify r)) !items | _ -> ());
+`)
+    }
+
+    if (opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first, then parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(exampleEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `jo [${loadItems.map((it: any) =>
+          `("${it.name}", ${ocamlLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)})`).join('; ')}]`
+        : 'Noval'
+      Content(`  (* Load a specific ${fn} (returns the record; raises on error) *)
+  let ${fn} = (Sdk_client.${fn} client Noval).e_load (${loadArg}) Noval in
+  print_endline (stringify ${fn})
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

package/project/.sdk/src/cmp/ocaml/ReadmeTopTest_ocaml.ts

@@ -0,0 +1,79 @@
+
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { ocamlVarName } from './utility_ocaml'
+
+
+// A type-correct OCaml `value` literal for a field's canonical type.
+function ocamlLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
+  if ('BOOLEAN' === k) return '(Bool true)'
+  if ('ARRAY' === k) return '(empty_list ())'
+  if ('OBJECT' === k) return '(empty_map ())'
+  return '(Str "example")'
+}
+
+
+const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity.
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+
+  Content(`\`\`\`ocaml
+let () =
+  let client = Sdk_client.test () in
+`)
+
+  if (exampleEntity && primaryOp) {
+    const fn = ocamlVarName(exampleEntity.name)
+    const idF = entityIdField(exampleEntity)
+    const field =
+      'load' === primaryOp ? 'e_load' :
+        'list' === primaryOp ? 'e_list' :
+          'create' === primaryOp ? 'e_create' :
+            'update' === primaryOp ? 'e_update' : 'e_remove'
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let arg = 'Noval'
+    if ('list' === primaryOp) {
+      arg = '(empty_map ())'
+    } else if (isMatchOp) {
+      // Every REQUIRED match key (id first).
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      arg = 0 < items.length
+        ? `(jo [${items.map((it: any) =>
+          `("${it.name}", ${it.name === idF ? '(Str "test01")' : ocamlLit(it.type)})`).join('; ')}])`
+        : '(empty_map ())'
+    } else if ('create' === primaryOp || 'update' === primaryOp) {
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => it.name !== idF && it.name !== 'id')
+      const required = items.filter((it: any) => !it.optional)
+      const chosen = required.length ? required : items.slice(0, 3)
+      arg = `(jo [${chosen.map((it: any) => `("${it.name}", ${ocamlLit(it.type)})`).join('; ')}])`
+    }
+    Content(`  let result = (Sdk_client.${fn} client Noval).${field} ${arg} Noval in
+  print_endline (stringify result)
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

package/project/.sdk/src/cmp/ocaml/Test_ocaml.ts

@@ -13,6 +13,7 @@ import { cmp, each, Folder } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_ocaml'
 import { TestDirect } from './TestDirect_ocaml'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_ocaml'
 
 
 const Test = cmp(function Test(props: any) {
@@ -26,6 +27,9 @@ const Test = cmp(function Test(props: any) {
       TestEntity({ target, entity })
       TestDirect({ target, entity })
     })
+
+    // Structural gate over the ```ocaml blocks in the generated docs.
+    ReadmeExamplesTest({ target })
   })
 })
 

package/project/.sdk/src/cmp/perl/ReadmeEntity_perl.ts

@@ -0,0 +1,181 @@
+
+import { cmp, each, Content, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// A type-correct, executable Perl literal for a field's canonical type. The
+// create example is EXECUTED by the doc test, so a placeholder must be a real
+// value. Strings render the quoted placeholder.
+function perlLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return '1'
+  if ('ARRAY' === k) return '[]'
+  if ('OBJECT' === k) return '{}'
+  return `'${placeholder}'`
+}
+
+
+// Perl has no static types; describe a field's shape with idiomatic Perl
+// terms (scalar / arrayref / hashref) derived from the canonical sentinel.
+function perlType(type: any): string {
+  const k = canonKey(type)
+  const m: Record<string, string> = {
+    STRING: 'string', INTEGER: 'integer', NUMBER: 'number',
+    BOOLEAN: 'boolean', ARRAY: 'arrayref', OBJECT: 'hashref', NULL: 'undef',
+  }
+  return m[k] || 'scalar'
+}
+
+
+// Operation method spelling for Perl: lowercase methods called on the entity
+// instance, taking a hashref match/data argument.
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'load($match)',  desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'list()',        desc: 'List entities, optionally matching the given 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 || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
+    const eVar = entity.name
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`my $${eVar} = $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}\` | \`${perlType(field.type)}\` | ${desc} |
+`)
+      })
+
+      Content(`
+`)
+    }
+
+    if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `{ ${loadItems.map((it: any) =>
+          `'${it.name}' => ${perlLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')} }`
+        : ''
+      Content(`#### Example: Load
+
+\`\`\`perl
+my $${eVar} = $client->${entity.Name}->load(${loadArg});
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`perl
+my $${eVar}s = $client->${entity.Name}->list;
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      // Members come from the SAME shape the runtime validates
+      // (opRequestShape): every required member must appear — including a
+      // required id and parent keys like page_id — with a real, executable
+      // literal.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`perl
+my $${eVar} = $client->${entity.Name}->create({
+`)
+      createItems.map((it: any) => {
+        Content(`    '${it.name}' => ${perlLit(it.type, 'example_' + it.name)},  # ${perlType(it.type)}
+`)
+      })
+      Content(`});
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}