@voxgig/apidef 1.9.0 → 2.0.2

package/src/builder/entity/apiEntity.ts

@@ -0,0 +1,88 @@
+/* Copyright (c) 2025 Voxgig, MIT License */
+
+import Path from 'node:path'
+
+import { each, File, Folder, Content } from 'jostraca'
+
+
+import type {
+  ApiDefOptions,
+} from '../../types'
+
+import {
+  formatJsonSrc,
+} from '../../utility'
+
+
+
+function resolveApiEntity(
+  apimodel: any,
+  opts: ApiDefOptions,
+) {
+  const barrel = [
+    '# Entity Models\n'
+  ]
+
+  const entityFiles: { name: string, src: string }[] = []
+
+  each(apimodel.main.api.entity, ((entity: any, entityName: string) => {
+    const entityFile = (null == opts.outprefix ? '' : opts.outprefix) + entityName + '.jsonic'
+
+    const entityJSON =
+      JSON.stringify(entity, null, 2)
+
+    const fieldAliasesSrc = fieldAliases(entity)
+
+    const entitySrc =
+      `# Entity: ${entity.name}\n\n` +
+      `main: api: entity: ${entity.name}: {\n\n` +
+      `  alias: field: ${fieldAliasesSrc}\n` +
+      formatJsonSrc(entityJSON.substring(1, entityJSON.length - 1)) +
+      '\n\n}\n'
+
+    entityFiles.push({ name: entityFile, src: entitySrc })
+
+    barrel.push(`@"${Path.basename(entityFile)}"`)
+  }))
+
+  const indexFile = (null == opts.outprefix ? '' : opts.outprefix) + 'api-entity-index.jsonic'
+
+  return function apiEntityBuilder() {
+    Folder({ name: 'api' }, () => {
+      each(entityFiles, (entityFile) => {
+        File({ name: entityFile.name }, () => Content(entityFile.src))
+      })
+
+      File({ name: indexFile }, () => Content(barrel.join('\n')))
+    })
+  }
+
+}
+
+function fieldAliases(entity: any) {
+  // HEURISTIC: id may be name_id or nameId
+  const fieldAliases =
+    each(entity.op, (op: any) =>
+      each(op.param))
+      .flat()
+      .reduce((a: any, p: any) =>
+
+      (entity.field[p.keys] ? null :
+        (p.key$.toLowerCase().includes(entity.name) ?
+          (a[p.key$] = 'id', a.id = p.key$) :
+          null)
+
+        , a), {})
+
+  const fieldAliasesSrc =
+    JSON.stringify(fieldAliases, null, 2)
+      .replace(/\n/g, '\n  ')
+
+  return fieldAliasesSrc
+}
+
+
+
+export {
+  resolveApiEntity
+}

package/src/builder/entity/def.ts

@@ -0,0 +1,44 @@
+/* Copyright (c) 2025 Voxgig, MIT License */
+
+import Path from 'node:path'
+
+
+import type {
+  ApiDefOptions,
+  ApiModel,
+} from '../../types'
+
+
+import {
+  File,
+  Folder,
+  Content
+} from 'jostraca'
+
+
+function resolveDef(
+  apimodel: ApiModel,
+  opts: ApiDefOptions,
+) {
+  const defFile =
+    (null == opts.outprefix ? '' : opts.outprefix) + 'api-def.jsonic'
+
+  const modelDef = { main: { def: apimodel.main.def } }
+  let modelDefSrc = JSON.stringify(modelDef, null, 2)
+
+  modelDefSrc =
+    '# API Definition\n\n' +
+    modelDefSrc.substring(1, modelDefSrc.length - 1).replace(/\n  /g, '\n')
+
+  return function defBuilder() {
+    Folder({ name: 'api' }, () => {
+      File({ name: defFile }, () => Content(modelDefSrc))
+    })
+  }
+
+}
+
+
+export {
+  resolveDef
+}

package/src/builder/entity.ts

@@ -0,0 +1,54 @@
+/* Copyright (c) 2025 Voxgig, MIT License */
+
+import Path from 'node:path'
+
+// import { each } from 'jostraca'
+
+
+// import type {
+//   ApiDefOptions,
+//   Log,
+//   FsUtil,
+// } from '../types'
+
+
+// import {
+//   writeChanged
+// } from '../utility'
+
+
+import {
+  resolveApiEntity
+} from './entity/apiEntity'
+
+import {
+  resolveDef
+} from './entity/def'
+
+// import {
+//   resolveSdkEntity
+// } from './entity/sdkEntity'
+
+
+
+async function makeEntityBuilder(ctx: any) {
+  const { apimodel, opts } = ctx
+
+  const apiEntityBuilder = resolveApiEntity(apimodel, opts)
+  const defBuilder = resolveDef(apimodel, opts)
+  // const sdkEntityBuilder = resolveSdkEntity(apimodel, opts)
+
+  return function entityBuilder() {
+    apiEntityBuilder()
+    defBuilder()
+    // sdkEntityBuilder()
+  }
+}
+
+
+
+
+
+export {
+  makeEntityBuilder
+}

package/src/builder/flow/flowHeuristic01.ts

@@ -0,0 +1,200 @@
+
+import { size } from '@voxgig/struct'
+
+import { each, names } from 'jostraca'
+
+
+async function flowHeuristic01(ctx: any): Promise<any[]> {
+  let entity = ctx.model.main.api.guide.entity
+
+  const flows: any[] = []
+
+  each(entity, (entity: any) => {
+    flows.push(resolveBasicEntityFlow(ctx, entity))
+  })
+
+  return flows
+}
+
+
+
+
+function resolveBasicEntityFlow(ctx: any, entity: any) {
+  const { apimodel, model } = ctx
+  const apiEntity = apimodel.main.api.entity[entity.name]
+
+  const flow: any = {
+    name: 'Basic' + apiEntity.Name + 'Flow'
+  }
+
+  const refs = [
+    `${apiEntity.name}01`,
+    `${apiEntity.name}02`,
+    `${apiEntity.name}03`,
+  ]
+
+  const idmap = refs.reduce((a: any, ref) => (a[ref] = ref.toUpperCase(), a), {})
+
+  flow.model = ({
+    name: flow.name,
+    active: true,
+    param: {
+      [`${model.NAME}_TEST_${apiEntity.NAME}_ENTID`]: idmap,
+      [`${model.NAME}_TEST_LIVE`]: "FALSE",
+      [`${model.NAME}_TEST_EXPLAIN`]: "FALSE",
+    },
+    test: { entity: { [apiEntity.name]: {} } },
+    step: []
+  } as any)
+
+  names(flow, flow.name)
+
+
+  const data = flow.model.test.entity[apiEntity.name]
+
+  refs.map((ref, i) => {
+    const id = idmap[ref]
+    const ent: any = data[id] = {}
+
+    let num = (i * size(apiEntity.field) * 10)
+    each(apiEntity.field, (field) => {
+      ent[field.name] =
+        'number' === field.type ? num :
+          'boolean' === field.type ? 0 === num % 2 :
+            'object' === field.type ? {} :
+              'array' === field.type ? [] :
+                's' + (num.toString(16))
+      num++
+    })
+
+    ent.id = id
+  })
+
+
+  const steps = flow.model.step
+
+  let num = 0
+  let name
+
+  const am: any = {}
+
+  if (apiEntity.op.load) {
+
+    // Get additional required match properties
+    each(apiEntity.op.load.param, (param: any) => {
+      if (param.required) {
+        let ancestorName = param.name
+        let ancestorEntity = apimodel.main.api.entity[ancestorName]
+
+        if (null == ancestorEntity) {
+          ancestorName = ancestorName.replace('_id', '')
+          ancestorEntity = apimodel.main.api.entity[ancestorName]
+        }
+
+        if (ancestorEntity && ancestorName !== apiEntity.name) {
+          flow.model.param[`${model.NAME}_TEST_${ancestorEntity.NAME}_ENTID`] = {
+            [ancestorEntity.name + '01']: ancestorEntity.NAME + '01'
+          }
+          am[param.name] =
+            `\`dm$=p.${model.NAME}_TEST_${ancestorEntity.NAME}_ENTID.${ancestorEntity.name}01\``
+
+          data[`${apiEntity.NAME}01`][param.name] = ancestorEntity.NAME + '01'
+        }
+      }
+    })
+
+
+    name = `load_${apiEntity.name}${num}`
+    steps.push({
+      name,
+      kind: 'entity',
+      entity: `${apiEntity.name}`,
+      action: 'load',
+      match: {
+        id: `\`dm$=p.${model.NAME}_TEST_${apiEntity.NAME}_ENTID.${apiEntity.name}01\``,
+        ...am,
+      },
+      valid: {
+        '`$OPEN`': true,
+        id: `\`dm$=s.${name}.match.id\``,
+        ...am,
+      }
+    })
+  }
+
+  if (apiEntity.op.update && apiEntity.op.load) {
+    num++
+    name = `update_${apiEntity.name}${num}`
+    const id = idmap[`${apiEntity.name}01`]
+    const loadref = `load_${apiEntity.name}${num - 1}`
+    const reqdata = makeUpdateData(name, apiEntity, flow, id)
+    const valid = makeUpdateValid(name, apiEntity, flow, id, reqdata)
+    steps.push({
+      name,
+      ref: loadref,
+      action: 'update',
+      reqdata,
+      valid: {
+        '`$OPEN`': true,
+        id: `\`dm$=s.${loadref}.match.id\``,
+        ...am,
+        ...valid
+      }
+    })
+
+    num++
+    name = `load_${apiEntity.name}${num}`
+
+    steps.push({
+      name,
+      kind: 'entity',
+      entity: `${apiEntity.name}`,
+      action: 'load',
+      match: {
+        id: `\`dm$=p.${model.NAME}_TEST_${apiEntity.NAME}_ENTID.${apiEntity.name}01\``,
+        ...am,
+      },
+      valid: {
+        '`$OPEN`': true,
+        id: `\`dm$=s.${loadref}.match.id\``,
+        ...am,
+        ...valid
+      }
+    })
+
+  }
+
+
+  return flow
+}
+
+
+function makeUpdateData(name: string, apiEntity: any, flow: any, id: string) {
+  const ud: any = {}
+  const data = flow.model.test.entity[apiEntity.name]
+
+  const dataFields = each(apiEntity.field).filter(f => 'id' !== f.name && !f.name.includes('_id'))
+  const stringFields = each(dataFields).filter(f => 'string' === f.type)
+
+  if (0 < size(stringFields)) {
+    const f = stringFields[0]
+    ud[f.name] = data[id][f.name] + '-`$WHEN`'
+  }
+
+  return ud
+}
+
+
+function makeUpdateValid(name: string, apiEntity: any, flow: any, id: string, reqdata: any) {
+  const vd: any = {}
+
+  each(reqdata, (n) => {
+    vd[n.key$] = `\`dm$=s.${name}.reqdata.${n.key$}\``
+  })
+
+  return vd
+}
+
+export {
+  flowHeuristic01
+}

package/src/builder/flow.ts

@@ -0,0 +1,61 @@
+
+import Path from 'node:path'
+
+import { File, Content, Folder, each } from 'jostraca'
+
+import {
+  formatJsonSrc,
+} from '../utility'
+
+
+import { flowHeuristic01 } from './flow/flowHeuristic01'
+
+
+async function makeFlowBuilder(ctx: any) {
+  let flows: any[] = []
+
+  if ('heuristic01' === ctx.opts.strategy) {
+    flows = await flowHeuristic01(ctx)
+  }
+  else {
+    throw new Error('Unknown guide strategy: ' + ctx.opts.strategy)
+  }
+
+
+  return function flowBuilder() {
+
+    Folder({ name: 'flow' }, () => {
+      const barrel = [
+        '# Flows\n'
+      ]
+
+      each(flows, (flow: any) => {
+        let flowfile =
+          Path.join(ctx.opts.folder, 'flow',
+            (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) +
+            flow.Name + '.jsonic')
+
+        let flowModelSrc = formatJsonSrc(JSON.stringify(flow.model, null, 2))
+
+        let flowsrc = `# ${flow.Name}
+
+main: sdk: flow: ${flow.Name}:
+` + flowModelSrc
+
+        barrel.push(`@"${Path.basename(flowfile)}"`)
+
+        File({ name: Path.basename(flowfile) }, () => Content(flowsrc))
+      })
+
+      File({
+        name: (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) + 'flow-index.jsonic'
+      }, () => Content(barrel.join('\n')))
+    })
+  }
+}
+
+
+
+export {
+  makeFlowBuilder
+}

package/src/guide/heuristic01.ts

@@ -0,0 +1,178 @@
+
+
+import { each, snakify, names } from 'jostraca'
+
+
+import { depluralize } from '../utility'
+
+
+type EntityDesc = {
+  name: string
+  origname: string
+  plural: string
+  path: Record<string, EntityPathDesc>
+  alias: Record<string, string>
+}
+
+
+type EntityPathDesc = {
+  op: Record<string, any>
+}
+
+async function heuristic01(ctx: any): Promise<Record<string, any>> {
+  let guide = ctx.model.main.api.guide
+
+
+  const entityDescs = resolveEntityDescs(ctx)
+
+  // console.log('entityDescs')
+  // console.dir(entityDescs, { depth: null })
+
+  guide = {
+    control: guide.control,
+    entity: entityDescs,
+  }
+
+  return guide
+}
+
+
+const METHOD_IDOP: Record<string, string> = {
+  get: 'load',
+  post: 'create',
+  put: 'update',
+  patch: 'update',
+  delete: 'remove',
+}
+
+
+function resolveEntityDescs(ctx: any) {
+  const entityDescs: Record<string, any> = {}
+  const paths = ctx.def.paths
+
+  // Analyze paths ending in .../foo/{foo}
+  each(paths, (pathdef, pathstr) => {
+
+    // Look for rightmmost /entname/{entid}.
+    const m = pathstr.match(/\/([a-zA-Z0-1_-]+)\/\{([a-zA-Z0-1_-]+)\}$/)
+    if (m) {
+      const entdesc = resolveEntity(entityDescs, pathstr, m[1], m[2])
+
+
+      each(pathdef, (mdef, method) => {
+        const opname = METHOD_IDOP[method]
+        if (null == opname) return;
+
+        const transform: Record<string, any> = {
+          // reqform: '`reqdata`',
+          // resform: '`body`',
+        }
+
+        const resokdef = mdef.responses[200] || mdef.responses[201]
+        const resbody = resokdef?.content?.['application/json']?.schema
+        if (resbody) {
+          if (resbody[entdesc.origname]) {
+            transform.resform = '`body.' + entdesc.origname + '`'
+          }
+          else if (resbody[entdesc.name]) {
+            transform.resform = '`body.' + entdesc.name + '`'
+          }
+        }
+
+        const reqdef = mdef.requestBody?.content?.['application/json']?.schema?.properties
+        if (reqdef) {
+          if (reqdef[entdesc.origname]) {
+            transform.reqform = { [entdesc.origname]: '`reqdata`' }
+          }
+          else if (reqdef[entdesc.origname]) {
+            transform.reqform = { [entdesc.origname]: '`reqdata`' }
+          }
+
+        }
+
+        const op = entdesc.path[pathstr].op
+
+        op[opname] = {
+          // TODO: in actual guide, remove "standard" method ops since redundant
+          method,
+        }
+
+        if (0 < Object.entries(transform).length) {
+          op[opname].transform = transform
+        }
+      })
+    }
+  })
+
+  // Analyze paths ending in .../foo
+  each(paths, (pathdef, pathstr) => {
+
+    // Look for rightmmost /entname.
+    const m = pathstr.match(/\/([a-zA-Z0-1_-]+)$/)
+    if (m) {
+      const entdesc = resolveEntity(entityDescs, pathstr, m[1])
+
+      if (pathdef.get) {
+        const op: Record<string, any> = { list: { method: 'get' } }
+        entdesc.path[pathstr] = { op }
+
+        const transform: Record<string, any> = {}
+        const mdef = pathdef.get
+        const resokdef = mdef.responses[200] || mdef.responses[201]
+        const resbody = resokdef?.content?.['application/json']?.schema
+        if (resbody) {
+          if (resbody[entdesc.origname]) {
+            transform.resform = '`body.' + entdesc.origname + '`'
+          }
+          else if (resbody[entdesc.name]) {
+            transform.resform = '`body.' + entdesc.name + '`'
+          }
+        }
+
+        if (0 < Object.entries(transform).length) {
+          op.transform = transform
+        }
+      }
+    }
+  })
+
+  return entityDescs
+}
+
+
+function resolveEntity(
+  entityDescs: Record<string, EntityDesc>,
+  pathStr: string,
+  pathName: string,
+  pathParam?: string
+)
+  : EntityDesc {
+  let origentname = snakify(pathName)
+  let entname = depluralize(origentname)
+
+  let entdesc = (entityDescs[entname] = entityDescs[entname] || { name: entname })
+  entdesc.plural = origentname
+  entdesc.origname = origentname
+
+  names(entdesc, entname)
+
+  entdesc.alias = entdesc.alias || {}
+
+  if (null != pathParam) {
+    const pathParamCanon = snakify(pathParam)
+    if ('id' != pathParamCanon) {
+      entdesc.alias.id = pathParamCanon
+      entdesc.alias[pathParamCanon] = 'id'
+    }
+  }
+
+  entdesc.path = (entdesc.path || {})
+  entdesc.path[pathStr] = { op: {} }
+
+  return entdesc
+}
+
+
+export {
+  heuristic01
+}

package/src/guide.ts

@@ -0,0 +1,87 @@
+
+import Path from 'node:path'
+
+import { File, Content, each } from 'jostraca'
+
+
+import { heuristic01 } from './guide/heuristic01'
+
+
+async function resolveGuide(ctx: any) {
+  let guide: Record<string, any> = ctx.model.main.api.guide
+
+  if ('heuristic01' === ctx.opts.strategy) {
+    guide = await heuristic01(ctx)
+  }
+  else {
+    throw new Error('Unknown guide strategy: ' + ctx.opts.strategy)
+  }
+
+  guide = cleanGuide(guide)
+
+  ctx.model.main.api.guide = guide
+
+  const guideFile =
+    Path.join(ctx.opts.folder,
+      (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) + 'guide.jsonic')
+
+  const guideBlocks = [
+    '# Guide',
+    '',
+    'main: api: guide: { ',
+    '',
+  ]
+
+
+  guideBlocks.push(...each(guide.entity, (entity, entityname) => {
+    guideBlocks.push(`\nentity: ${entityname}: {`)
+
+    each(entity.path, (path, pathname) => {
+      guideBlocks.push(`  path: '${pathname}': op: {`)
+
+      each(path.op, (op, opname) => {
+        guideBlocks.push(`    '${opname}': method: ${op.method}`)
+        if (op.transform?.reqform) {
+          guideBlocks.push(
+            `    '${opname}': transform: reqform: ${JSON.stringify(op.transform.reqform)}`)
+        }
+      })
+
+      guideBlocks.push(`  }`)
+    })
+
+    guideBlocks.push(`}`)
+  }))
+
+  guideBlocks.push('}')
+
+  const guideSrc = guideBlocks.join('\n')
+
+  return () => {
+    File({ name: Path.basename(guideFile) }, () => Content(guideSrc))
+
+  }
+}
+
+
+function cleanGuide(guide: Record<string, any>): Record<string, any> {
+  const clean: Record<string, any> = {
+    control: guide.control,
+    entity: {}
+  }
+
+  each(guide.entity, (entity: any, name: string) => {
+    let ent: any = clean.entity[name] = clean.entity[name] = { name, path: {} }
+
+    each(entity.path, (path: any, pathname: string) => {
+      ent.path[pathname] = path
+    })
+  })
+
+  return clean
+}
+
+
+export {
+  resolveGuide
+}