@voxgig/apidef 1.9.0 → 2.0.2

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

@@ -1,38 +1,47 @@
 
 
-import { each } from 'jostraca'
+import { each, snakify } from 'jostraca'
 
-import type { TransformCtx, TransformSpec, TransformResult, Transform, Guide } from '../transform'
+import type { TransformResult, Transform } from '../transform'
 
 import { fixName } from '../transform'
 
+import { depluralize } from '../utility'
+
 
 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: {},
       id: {
         name: 'id',
         field: 'id',
-      }
+      },
+      ancestors: []
     }
 
     fixName(entityModel, guideEntity.key$)
 
-    each(guideEntity.path, (guidePath: any) => {
+    let ancestors: string[] = []
+    let ancestorsDone = false
+
+    each(guideEntity.path, (guidePath: any, pathStr: string) => {
       const path = guidePath.key$
       const pathdef = def.paths[path]
 
@@ -47,8 +56,25 @@ const entityTransform: Transform = async function(
         .filter((p: string) => p.startsWith('{'))
         .map((p: string) => p.substring(1, p.length - 1))
 
+      if (!ancestorsDone) {
+        // Find all path sections matching /foo/{..param..} and build ancestors array
+        const paramRegex = /\/([a-zA-Z0-9_-]+)\/\{[a-zA-Z0-9_-]+\}/g
+        let m
+        while ((m = paramRegex.exec(pathStr)) !== null) {
+          // Skip if this is the last section (the entity itself)
+          const remainingPath = pathStr.substring(m.index + m[0].length)
+          if (remainingPath.length > 0) {
+            const ancestorName = depluralize(snakify(m[1]))
+            ancestors.push(ancestorName)
+          }
+        }
+
+        ancestorsDone = true
+      }
     })
 
+    entityModel.ancestors = ancestors
+
     msg += guideEntity.name + ' '
   })
 

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,58 +2,85 @@
 
 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: '
 
-  const paramBuilder = (paramMap: any, paramDef: any,
-    entityModel: any, pathdef: any,
-    op: any, path: any, entity: any, model: any) => {
+  const paramBuilder = (
+    paramMap: any,
+    paramDef: any,
+    opModel: any,
+    entityModel: any,
+    pathdef: any,
+    op: any,
+    path: any,
+    entity: any,
+    model: any
+  ) => {
 
-    paramMap[paramDef.name] = {
+    const paramSpec: any = paramMap[paramDef.name] = {
       required: paramDef.required
     }
-    fixName(paramMap[paramDef.name], paramDef.name)
+    fixName(paramSpec, paramDef.name)
 
     const type = paramDef.schema ? paramDef.schema.type : paramDef.type
-    fixName(paramMap[paramDef.name], type, 'type')
+    fixName(paramSpec, type, 'type')
+
+    // Path params are always required.
+    opModel.validate.params[paramDef.name] = `\`$${paramSpec.TYPE}\``
   }
 
 
-  const queryBuilder = (queryMap: any, queryDef: any,
-    entityModel: any, pathdef: any,
-    op: any, path: any, entity: any, model: any) => {
-    queryMap[queryDef.name] = {
+  const queryBuilder = (
+    queryMap: any,
+    queryDef: any,
+    opModel: any,
+    entityModel: any,
+    pathdef: any,
+    op: any,
+    path: any,
+    entity: any,
+    model: any
+  ) => {
+    const querySpec: any = queryMap[queryDef.name] = {
       required: queryDef.required
     }
     fixName(queryMap[queryDef.name], queryDef.name)
 
     const type = queryDef.schema ? queryDef.schema.type : queryDef.type
     fixName(queryMap[queryDef.name], type, 'type')
+
+    if (queryDef.required) {
+      opModel.validate.params[queryDef.name] = `\`$${querySpec.TYPE}\``
+    }
   }
 
 
   // Resolve the JSON structure of the request or response.
   // NOTE: uses heuristics.
   const resolveTransform = (
+    entityModel: any,
     op: any,
     kind: 'res' | 'req',
     direction: 'resform' | 'reqform',
     pathdef: any
   ) => {
     let out
+    let why = 'none'
 
     if (null != op.transform?.[direction]) {
       out = op.transform[direction]
@@ -64,46 +91,60 @@ const operationTransform = async function(
       const mdef = pathdef[method]
 
       // TODO: fix getx
-      const content = 'res' === kind ?
+      // const content = 'res' === kind ?
+      const content = 'resform' === direction ?
         (getx(mdef, 'responses.200.content') ||
           getx(mdef, 'responses.201.content')) :
         getx(mdef, 'requestBody.content')
 
+      if (content) {
 
-      const schema = content['application/json']?.schema
+        const schema = content['application/json']?.schema
 
-      const propkeys = null == schema?.properties ? [] : Object.keys(schema.properties)
+        const propkeys = null == schema?.properties ? [] : Object.keys(schema.properties)
 
-      const resolveDirectionTransform =
-        'resform' === direction ? resolveResponseTransform : resolveRequestTransform
+        const resolveDirectionTransform =
+          'resform' === direction ? resolveResponseTransform : resolveRequestTransform
 
-      const transform = resolveDirectionTransform(
-        op,
-        kind,
-        method,
-        mdef,
-        content,
-        schema,
-        propkeys
-      )
-
-      // out = JSON.stringify(transform)
-      out = transform
+          //const [transform, why]
+          ;[out, why]
+            = resolveDirectionTransform(
+              entityModel,
+              op,
+              kind,
+              direction,
+              method,
+              mdef,
+              content,
+              schema,
+              propkeys
+            )
+
+        // out = JSON.stringify(transform)
+        // out = transform
+      }
+      else {
+        out = 'res' === kind ? '`body`' : '`reqdata`'
+      }
     }
 
-    return out
+
+    return [out, why]
   }
 
 
   const resolveResponseTransform = (
+    entityModel: any,
     op: any,
     kind: 'res' | 'req',
+    direction: 'resform' | 'reqform',
     method: string,
     mdef: any,
     content: any,
     schema: any,
     propkeys: any
   ) => {
+    let why = 'default'
     let transform: any = '`body`'
 
     if (null == content || null == schema || null == propkeys) {
@@ -115,12 +156,14 @@ const operationTransform = async function(
     if ('list' === opname) {
       if ('array' !== schema.type) {
         if (1 === propkeys.length) {
+          why = 'list-single-prop:' + propkeys[0]
           transform = '`body.' + propkeys[0] + '`'
         }
         else {
           // Use sub property that is an array
           for (let pk of propkeys) {
             if ('array' === schema.properties[pk]?.type) {
+              why = 'list-single-array:' + pk
               transform = '`body.' + pk + '`'
               break
             }
@@ -132,11 +175,13 @@ const operationTransform = async function(
       if ('object' === schema.type) {
         if (null == schema.properties.id) {
           if (1 === propkeys.length) {
+            why = 'map-single-prop:' + propkeys[0]
             transform = '`body.' + propkeys[0] + '`'
           }
           else {
             for (let pk of propkeys) {
               if (schema.properties[pk].properties?.id) {
+                why = 'map-sub-prop:' + pk
                 transform = '`body.' + pk + '`'
                 break
               }
@@ -146,13 +191,15 @@ const operationTransform = async function(
       }
     }
 
-    return transform
+    return [transform, why]
   }
 
 
   const resolveRequestTransform = (
+    entityModel: any,
     op: any,
     kind: 'res' | 'req',
+    direction: 'resform' | 'reqform',
     method: string,
     mdef: any,
     content: any,
@@ -160,6 +207,7 @@ const operationTransform = async function(
     propkeys: any
   ) => {
     let transform: any = '`data`'
+    let why = 'default'
 
     if (null == content || null == schema || null == propkeys) {
       return transform
@@ -170,12 +218,14 @@ const operationTransform = async function(
     if ('list' === opname) {
       if ('array' !== schema.type) {
         if (1 === propkeys.length) {
+          why = 'list-single-prop:' + propkeys[0]
           transform = { [propkeys[0]]: '`data`' }
         }
         else {
           // Use sub property that is an array
           for (let pk of propkeys) {
             if ('array' === schema.properties[pk]?.type) {
+              why = 'list-single-array:' + pk
               transform = { [pk]: '`data`' }
               break
             }
@@ -187,11 +237,13 @@ const operationTransform = async function(
       if ('object' === schema.type) {
         if (null == schema.properties.id) {
           if (1 === propkeys.length) {
+            why = 'map-single-prop:' + propkeys[0]
             transform = { [propkeys[0]]: '`data`' }
           }
           else {
             for (let pk of propkeys) {
               if (schema.properties[pk].properties?.id) {
+                why = 'map-sub-prop:' + pk
                 transform = { [pk]: '`data`' }
                 break
               }
@@ -201,7 +253,7 @@ const operationTransform = async function(
       }
     }
 
-    return transform
+    return [transform, why]
   }
 
 
@@ -211,26 +263,39 @@ const operationTransform = async function(
       const method = op.method
       const kind = OPKIND[opname]
 
-      const em = entityModel.op[opname] = {
+      const [resform, resform_COMMENT] =
+        resolveTransform(entityModel, op, kind, 'resform', pathdef)
+
+      const [reqform, reqform_COMMENT] =
+        resolveTransform(entityModel, op, kind, 'reqform', pathdef)
+
+      const opModel = entityModel.op[opname] = {
         path: path.key$,
         method,
         kind,
         param: {},
         query: {},
-        // transform: {
-        resform: resolveTransform(op, kind, 'resform', pathdef),
-        reqform: resolveTransform(op, kind, 'reqform', pathdef),
-        // }
+
+        resform_COMMENT: 'derivation: ' + resform_COMMENT,
+        resform,
+
+        reqform_COMMENT: 'derivation: ' + reqform_COMMENT,
+        reqform,
+
+        validate: {
+          params: { '`$OPEN`': true }
+        }
       }
 
-      fixName(em, op.key$)
+      fixName(opModel, op.key$)
 
       // Params are in the path
       if (0 < path.params$.length) {
         let params = getx(pathdef[method], 'parameters?in=path') || []
         if (Array.isArray(params)) {
           params.reduce((a: any, p: any) =>
-            (paramBuilder(a, p, entityModel, pathdef, op, path, entity, model), a), em.param)
+          (paramBuilder(a, p, opModel, entityModel,
+            pathdef, op, path, entity, model), a), opModel.param)
         }
       }
 
@@ -238,10 +303,11 @@ const operationTransform = async function(
       let queries = getx(pathdef[op.val$], 'parameters?in!=path') || []
       if (Array.isArray(queries)) {
         queries.reduce((a: any, p: any) =>
-          (queryBuilder(a, p, entityModel, pathdef, op, path, entity, model), a), em.query)
+        (queryBuilder(a, p, opModel, entityModel,
+          pathdef, op, path, entity, model), a), opModel.query)
       }
 
-      return em
+      return opModel
     },
 
 
@@ -270,7 +336,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' }
 }