@voxgig/apidef 1.9.0 → 2.0.0

package/src/guide.ts

@@ -0,0 +1,91 @@
+
+import Path from 'node:path'
+
+import { File, Content, each } from 'jostraca'
+
+
+import { heuristic01 } from './guide/heuristic01'
+
+
+async function resolveGuide(ctx: any) {
+  // console.log('GUIDE CTX', ctx)
+
+  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}: path: {`)
+
+    each(entity.path, (path, pathname) => {
+      guideBlocks.push(`  '${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')
+
+  // console.log(guideSrc)
+
+  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
+}

package/src/parse.ts

@@ -3,9 +3,11 @@
 import { bundleFromString, createConfig } from '@redocly/openapi-core'
 
 
-async function parse(kind: string, source: any) {
+
+// Parse an API definition source into a JSON sructure.
+async function parse(kind: string, source: any, meta?: any) {
   if ('OpenAPI' === kind) {
-    return parseOpenAPI(source)
+    return parseOpenAPI(source, meta)
   }
   else {
     throw new Error('@voxgig/apidef-parse: unknown kind: ' + kind)
@@ -13,8 +15,8 @@ async function parse(kind: string, source: any) {
 }
 
 
-async function parseOpenAPI(source: any) {
-  const config = await createConfig({})
+async function parseOpenAPI(source: any, meta?: any) {
+  const config = await createConfig(meta?.config || {})
   let bundle
 
   bundle = await bundleFromString({

package/src/resolver.ts

@@ -0,0 +1,91 @@
+/* Copyright (c) 2024-2025 Voxgig, MIT License */
+
+
+import Path from 'node:path'
+
+
+async function resolveElements(
+  ctx: any,
+  kind: string,
+  subkind: string,
+  standard: Record<string, any>
+) {
+
+  const { log, model } = ctx
+
+  // TODO: model access should be via a utility that generates
+  // useful errors when the target is missing
+  const control = model.main.api.guide.control[kind][subkind]
+
+  const target = kind + '.' + subkind
+
+  const elementNames = control.order
+    .split(/\s*,\s*/)
+    .map((t: string) => t.trim())
+    .filter((elem: string) => '' != elem)
+
+  log.info({
+    point: 'element', note: target + ': order: ' + elementNames.join(';'),
+    order: elementNames
+  })
+
+  const elementResults: any = []
+
+  for (const en of elementNames) {
+    log.debug({ point: 'element', note: target + ': ' + en })
+    const element = await resolveElement(en, control, target, standard, ctx)
+    const result = await element(ctx)
+    elementResults.push(result)
+  }
+
+  return elementResults
+}
+
+
+async function resolveElement(
+  en: string,
+  control: any,
+  target: string,
+  standard: Record<string, any>,
+  ctx: any
+) {
+  const { log } = ctx
+
+  let element = standard[en]
+  if (element) {
+    return element
+  }
+
+  const elemdef = control.element[en]
+  if (null == elemdef) {
+    const err = new Error('Unknown element: ' + en)
+    log.error({ what: 'element', element: target + ': ' + en, fail: 'unknown', err })
+    throw err
+  }
+
+  if (!en.startsWith('custom')) {
+    const err =
+      new Error('Custom element name must start with "custom": ' + en)
+    log.error({ what: 'element', element: target + ': ' + en, fail: 'prefix', err })
+    throw err
+  }
+
+  const customtpath = Path.join(ctx.defpath, elemdef.load)
+  try {
+    const elementModule = require(customtpath)
+    element = elementModule[en]
+  }
+  catch (e: any) {
+    const err = new Error('Custom element not found: ' +
+      customtpath + ': ' + e.message)
+    log.error({ what: 'element', element: target + ': ' + en, fail: 'require', err })
+    throw err
+  }
+
+  return element
+}
+
+
+export {
+  resolveElements,
+}

package/src/transform/entity.ts

@@ -2,25 +2,28 @@
 
 import { each } from 'jostraca'
 
-import type { TransformCtx, TransformSpec, TransformResult, Transform, Guide } from '../transform'
+import type { TransformResult, Transform } from '../transform'
 
 import { fixName } from '../transform'
 
 
 const entityTransform: Transform = async function(
-  ctx: TransformCtx,
-  guide: Guide,
-  tspec: TransformSpec,
-  model: any,
-  def: any
+  ctx: any,
+  // guide: Guide,
+  // // tspec: TransformSpec,
+  // model: any,
+  // def: any
 ): Promise<TransformResult> {
+  const { apimodel, model, def } = ctx
+  const guide = model.main.api.guide
+
   let msg = ''
 
   each(guide.entity, (guideEntity: any) => {
     const entityName = guideEntity.key$
     ctx.log.debug({ point: 'guide-entity', note: entityName })
 
-    const entityModel: any = model.main.api.entity[entityName] = {
+    const entityModel: any = apimodel.main.api.entity[entityName] = {
       op: {},
       field: {},
       cmd: {},

package/src/transform/field.ts

@@ -2,25 +2,27 @@
 
 import { each, getx } from 'jostraca'
 
-import type { TransformCtx, TransformSpec, TransformResult, Transform, Guide } from '../transform'
+import type { TransformResult, Transform } from '../transform'
 
 import { fixName } from '../transform'
 
 
 
 const fieldTransform: Transform = async function(
-  ctx: TransformCtx,
-  guide: Guide,
-  tspec: TransformSpec,
-  model: any,
-  def: any
+  ctx: any,
+  // guide: Guide,
+  // // tspec: TransformSpec,
+  // model: any,
+  // def: any
 ): Promise<TransformResult> {
+  const { apimodel, model, def } = ctx
+  const guide = model.main.api.guide
 
   let msg = 'fields: '
 
   each(guide.entity, (guideEntity: any) => {
     const entityName = guideEntity.key$
-    const entityModel = model.main.api.entity[entityName]
+    const entityModel = apimodel.main.api.entity[entityName]
 
     let fieldCount = 0
     each(guideEntity.path, (guidePath: any) => {
@@ -96,88 +98,3 @@ export {
   fieldTransform
 }
 
-
-
-
-/*
-
-# API Specification Transform Guide
-
-
-@"@voxgig/apidef/model/guide.jsonic"
-
-
-guide: control: transform: openapi: order: `
-
-  top,
-  entity,
-  operation,
-  field,
-  customField,
-  
-  `
-
-guide: transform: customField: {
-  load: 'customField.js'
-}
-
-
-guide: entity: {
-  pet: path: {
-    '/pet/{petId}': {
-      op:{ load: 'get', create: 'post', update: 'put' }
-    }
-  }
-  pet: test: {
-    quick: {
-      active: true,
-      create: { id: 1, name:'Rex' },
-      load: { id: 1 },
-    }
-  }
-
-  # direct custom definition
-  pet: def: {}
-}
-
-
-
-
-const { each, getx } = require('jostraca')
-
-
-async function customField(ctx, tspec, model, def) {
-  const { spec, util: {fixName} } = ctx
-
-  const nameField = {
-    name: 'name',
-    type: 'string',
-    short: 'Name of pet'
-  }
-  fixName(nameField, nameField.name)
-  fixName(nameField, nameField.type, 'type')
-  
-  const ageField = {
-    name: 'age',
-    type: 'number',
-    short: 'Age of pet'
-  }
-  fixName(ageField, ageField.name)
-  fixName(ageField, ageField.type, 'type')
-
-  
-  Object.assign(model.main.api.entity.pet.field, {
-    name: nameField,
-    age: ageField,
-  })
-  
-  return { ok: true }
-}
-
-
-module.exports = {
-  customField
-}
-
-  
-  */

package/src/transform/operation.ts

@@ -2,19 +2,21 @@
 
 import { each, getx } from 'jostraca'
 
-import type { TransformCtx, TransformSpec, TransformResult, Transform, Guide } from '../transform'
+import type { TransformResult } from '../transform'
 
 import { fixName, OPKIND } from '../transform'
 
 
 
 const operationTransform = async function(
-  ctx: TransformCtx,
-  guide: Guide,
-  tspec: TransformSpec,
-  model: any,
-  def: any
+  ctx: any,
+  // guide: Guide,
+  // // tspec: TransformSpec,
+  // model: any,
+  // def: any
 ): Promise<TransformResult> {
+  const { apimodel, model, def } = ctx
+  const guide = model.main.api.guide
 
   let msg = 'operations: '
 
@@ -48,6 +50,7 @@ const operationTransform = async function(
   // Resolve the JSON structure of the request or response.
   // NOTE: uses heuristics.
   const resolveTransform = (
+    entityModel: any,
     op: any,
     kind: 'res' | 'req',
     direction: 'resform' | 'reqform',
@@ -69,28 +72,39 @@ const operationTransform = async function(
           getx(mdef, 'responses.201.content')) :
         getx(mdef, 'requestBody.content')
 
+      // console.log(entityModel)
+      // console.log(mdef)
+      // console.log(getx(mdef, 'responses.200.content'))
+      // console.log(kind, method, pathdef, content)
 
-      const schema = content['application/json']?.schema
+      if (content) {
 
-      const propkeys = null == schema?.properties ? [] : Object.keys(schema.properties)
+        const schema = content['application/json']?.schema
 
-      const resolveDirectionTransform =
-        'resform' === direction ? resolveResponseTransform : resolveRequestTransform
+        const propkeys = null == schema?.properties ? [] : Object.keys(schema.properties)
 
-      const transform = resolveDirectionTransform(
-        op,
-        kind,
-        method,
-        mdef,
-        content,
-        schema,
-        propkeys
-      )
-
-      // out = JSON.stringify(transform)
-      out = transform
+        const resolveDirectionTransform =
+          'resform' === direction ? resolveResponseTransform : resolveRequestTransform
+
+        const transform = resolveDirectionTransform(
+          op,
+          kind,
+          method,
+          mdef,
+          content,
+          schema,
+          propkeys
+        )
+
+        // out = JSON.stringify(transform)
+        out = transform
+      }
+      else {
+        out = 'res' === kind ? '`body`' : '`reqdata`'
+      }
     }
 
+
     return out
   }
 
@@ -218,8 +232,8 @@ const operationTransform = async function(
         param: {},
         query: {},
         // transform: {
-        resform: resolveTransform(op, kind, 'resform', pathdef),
-        reqform: resolveTransform(op, kind, 'reqform', pathdef),
+        resform: resolveTransform(entityModel, op, kind, 'resform', pathdef),
+        reqform: resolveTransform(entityModel, op, kind, 'reqform', pathdef),
         // }
       }
 
@@ -270,7 +284,7 @@ const operationTransform = async function(
 
   each(guide.entity, (guideEntity: any) => {
     let opcount = 0
-    const entityModel = model.main.api.entity[guideEntity.key$]
+    const entityModel = apimodel.main.api.entity[guideEntity.key$]
     each(guideEntity.path, (guidePath: any) => {
       const pathdef = def.paths[guidePath.key$]
 

package/src/transform/top.ts

@@ -1,22 +1,24 @@
 
 import { each, getx } from 'jostraca'
 
-import type { TransformCtx, TransformSpec, TransformResult, Transform, Guide } from '../transform'
+import type { TransformResult } from '../transform'
 
 import { fixName } from '../transform'
 
 
 const topTransform = async function(
-  ctx: TransformCtx,
-  guide: Guide,
-  tspec: TransformSpec,
-  model: any,
-  def: any
+  ctx: any,
+  // guide: Guide,
+  // // tspec: TransformSpec,
+  // model: any,
+  // def: any
 ): Promise<TransformResult> {
-  const { spec } = ctx
+  const { apimodel, def } = ctx
 
-  model.main.def.info = def.info
-  model.main.def.servers = def.servers
+  // const { spec } = ctx
+
+  apimodel.main.def.info = def.info
+  apimodel.main.def.servers = def.servers
 
   return { ok: true, msg: 'top' }
 }

package/src/transform.ts

@@ -11,7 +11,7 @@ import { topTransform } from './transform/top'
 import { entityTransform } from './transform/entity'
 import { operationTransform } from './transform/operation'
 import { fieldTransform } from './transform/field'
-import { manualTransform } from './transform/manual'
+// import { manualTransform } from './transform/manual'
 
 
 
@@ -55,7 +55,7 @@ const TRANSFORM: Record<string, Transform> = {
   entity: entityTransform,
   operation: operationTransform,
   field: fieldTransform,
-  manual: manualTransform,
+  // manual: manualTransform,
 }
 
 
@@ -98,10 +98,16 @@ async function resolveTransforms(ctx: TransformCtx): Promise<TransformSpec> {
     order: transformNames
   })
 
-  for (const tn of transformNames) {
-    log.debug({ what: 'transform', transform: tn, note: tn })
-    const transform = await resolveTransform(tn, ctx)
-    tspec.transform.push(transform)
+  try {
+    for (const tn of transformNames) {
+      log.debug({ what: 'transform', transform: tn, note: tn })
+      const transform = await resolveTransform(tn, ctx)
+      tspec.transform.push(transform)
+    }
+  }
+  catch (err: any) {
+    console.log(err)
+    throw err
   }
 
   return tspec
@@ -146,10 +152,10 @@ async function resolveTransform(tn: string, ctx: TransformCtx) {
 }
 
 
-
 async function processTransforms(
   ctx: TransformCtx,
-  spec: TransformSpec,
+  // spec: TransformSpec,
+  transforms: any[],
   apimodel: any,
   def: any
 ): Promise<ProcessResult> {
@@ -162,15 +168,21 @@ async function processTransforms(
   const guide: Guide = GuideShape(ctx.model.main.api.guide)
 
 
-  for (let tI = 0; tI < spec.transform.length; tI++) {
-    const transform = spec.transform[tI]
+  // for (let tI = 0; tI < spec.transform.length; tI++) {
+  //  const transform = spec.transform[tI]
+
+  for (let tI = 0; tI < transforms.length; tI++) {
+    const transform = transforms[tI]
 
     try {
-      const tres = await transform(ctx, guide, spec, apimodel, def)
+      const tres = await transform(ctx, guide, apimodel, def)
       pres.ok = pres.ok && tres.ok
       pres.results.push(tres)
     }
     catch (err: any) {
+      // TODO: fix: this error does not get printed
+      console.log(err)
+
       pres.ok = false
       pres.msg += transform.name + ': ' + err.message + '\n'
       pres.results.push({

package/src/types.ts

@@ -0,0 +1,88 @@
+/* Copyright (c) 2025 Voxgig, MIT License */
+
+import * as Fs from 'node:fs'
+
+import { Pino, prettyPino } from '@voxgig/util'
+import { Gubu, Open, Any } from 'gubu'
+
+
+type FsUtil = typeof Fs
+type Log = ReturnType<typeof prettyPino>
+
+
+type ApiDefOptions = {
+  def?: string
+  fs?: any
+  pino?: ReturnType<typeof Pino>
+  debug?: boolean | string
+  folder?: string
+  meta?: Record<string, any>
+  outprefix?: string
+  strategy?: string
+}
+
+
+const ModelShape = Gubu({
+  name: String,
+  def: String,
+  main: {
+    sdk: {},
+    def: {},
+    api: {
+      guide: {}
+    },
+  }
+})
+const OpenModelShape = Gubu(Open(ModelShape))
+
+type Model = ReturnType<typeof ModelShape>
+
+
+const BuildShape = Gubu({
+  spec: {
+    base: '',
+    path: '',
+    debug: '',
+    use: {},
+    res: [],
+    require: '',
+    log: {},
+    fs: Any(),
+    watch: {
+      mod: true,
+      add: true,
+      rem: true,
+    }
+  }
+})
+const OpenBuildShape = Gubu(Open(BuildShape))
+
+type Build = ReturnType<typeof BuildShape>
+
+
+
+type ApiModel = {
+  main: {
+    api: {
+      entity: Record<string, any>
+    }
+    def: Record<string, any>
+  }
+}
+
+
+export {
+  OpenModelShape,
+  OpenBuildShape,
+}
+
+
+export type {
+  Log,
+  FsUtil,
+  ApiDefOptions,
+  Model,
+  Build,
+  ApiModel,
+}
+