@voxgig/apidef 1.4.0 → 1.5.0

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/apidef.ts","../src/parse.ts","../src/transform.ts","../src/transform/entity.ts","../src/transform/field.ts","../src/transform/manual.ts","../src/transform/operation.ts","../src/transform/top.ts"],"version":"5.7.2"}
+{"root":["../src/apidef.ts","../src/parse.ts","../src/transform.ts","../src/transform/entity.ts","../src/transform/field.ts","../src/transform/manual.ts","../src/transform/operation.ts","../src/transform/top.ts"],"version":"5.7.3"}

package/model/apidef.jsonic

@@ -1,9 +1,9 @@
 
-main: guide: control: transform: &: {
+main: api: guide: control: transform: &: {
   order: string
 }
 
-main: guide: control: transform: openapi: {
+main: api: guide: control: transform: openapi: {
   order: *`
 
   top,
@@ -16,12 +16,12 @@ main: guide: control: transform: openapi: {
 }
 
 
-main: guide: transform: &: {
+main: api: guide: transform: &: {
   name: .$KEY
   load: string
 }
 
-main: guide: transform: {
+main: api: guide: transform: {
   top: {}
   entity: {}
   operation: {}
@@ -30,12 +30,16 @@ main: guide: transform: {
 }
 
 
-main: guide: entity: &: {
+main: api: guide: entity: &: {
   name: .$KEY
   path: &: {
     op: &: {
       method: *'get' | string
-      place: *'' | string
+      transform: {
+        # TODO: make these work
+        # inward: *null | string | object
+        # outward: *null | string | object
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/apidef",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "main": "dist/apidef.js",
   "type": "commonjs",
   "types": "dist/apidef.d.ts",
@@ -24,7 +24,7 @@
     "test-some": "node --enable-source-maps --test-name-pattern=\"$npm_config_pattern\" --test dist-test",
     "watch": "tsc --build src test -w",
     "build": "tsc --build src test",
-    "clean": "rm -rf node_modules yarn.lock package-lock.json",
+    "clean": "rm -rf dist dist-test node_modules yarn.lock package-lock.json",
     "reset": "npm run clean && npm i && npm run build && npm test",
     "repo-tag": "REPO_VERSION=`node -e \"console.log(require('./package').version)\"` && echo TAG: v$REPO_VERSION && git commit -a -m v$REPO_VERSION && git push && git tag v$REPO_VERSION && git push --tags;",
     "repo-publish": "npm run clean && npm i && npm run repo-publish-quick",
@@ -41,20 +41,20 @@
   "devDependencies": {
     "@hapi/code": "^9.0.3",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "22.10.2",
-    "aontu": "^0.25.3",
-    "esbuild": "^0.24.1",
+    "@types/node": "22.13.4",
+    "aontu": "^0.28.0",
+    "esbuild": "^0.25.0",
     "json-schema-to-ts": "^3.1.1",
-    "memfs": "^4.15.0",
-    "typescript": "^5.7.2"
+    "memfs": "^4.17.0",
+    "typescript": "^5.7.3"
   },
   "dependencies": {
-    "@redocly/openapi-core": "^1.26.1",
+    "@redocly/openapi-core": "^1.30.0",
     "@voxgig/util": "^0.0.9",
     "chokidar": "^4.0.3",
     "gubu": "^9.0.0",
     "jostraca": "^0.15.1",
-    "pino": "^9.5.0",
+    "pino": "^9.6.0",
     "pino-pretty": "^13.0.0",
     "sonic-boom": "^4.2.0"
   }

package/src/apidef.ts

@@ -5,9 +5,8 @@ import Path from 'node:path'
 import { inspect } from 'node:util'
 
 import { bundleFromString, createConfig } from '@redocly/openapi-core'
-import { FSWatcher } from 'chokidar'
-import { Aontu, Context } from 'aontu'
 import { Gubu, Open, Any } from 'gubu'
+import { each } from 'jostraca'
 import { prettyPino, Pino } from '@voxgig/util'
 
 
@@ -29,10 +28,19 @@ type ApiDefOptions = {
 }
 
 
+type ApiModel = {
+  main: {
+    api: {
+      entity: Record<string, any>
+    }
+    def: Record<string, any>
+  }
+}
+
+
 const ModelShape = Gubu({
   def: String,
   main: {
-    guide: {},
     sdk: {},
     def: {},
     api: {},
@@ -130,7 +138,7 @@ function ApiDef(opts: ApiDefOptions) {
     }
 
 
-    const apimodel = {
+    const apimodel: ApiModel = {
       main: {
         api: {
           entity: {}
@@ -152,6 +160,24 @@ function ApiDef(opts: ApiDefOptions) {
       return { ok: false, name: 'apidef', processResult }
     }
 
+
+    const modelPath = Path.normalize(spec.config.model)
+
+    buildModel_api(apimodel, modelPath)
+    buildModel_def(apimodel, modelPath)
+    buildModel_entity(apimodel, modelPath)
+
+    log.info({ point: 'generate-end', note: 'success', break: true })
+
+    return {
+      ok: true,
+      name: 'apidef',
+      apimodel,
+    }
+  }
+
+
+  function buildModel_api(apimodel: ApiModel, modelPath: string) {
     const modelapi = { main: { api: apimodel.main.api } }
     let modelSrc = JSON.stringify(modelapi, null, 2)
 
@@ -159,14 +185,15 @@ function ApiDef(opts: ApiDefOptions) {
       '# GENERATED FILE - DO NOT EDIT\n\n' +
       modelSrc.substring(1, modelSrc.length - 1).replace(/\n  /g, '\n')
 
-    const modelPath = Path.normalize(spec.config.model)
-    // console.log('modelPath', modelPath)
     writeChanged('api-model', modelPath, modelSrc)
+    return modelPath
+  }
 
+
+  function buildModel_def(apimodel: ApiModel, modelPath: string) {
     const modelBasePath = Path.dirname(modelPath)
-    const defFilePath =
-      Path.join(modelBasePath,
-        (null == opts.outprefix ? '' : opts.outprefix) + 'def-generated.jsonic')
+    const defFilePath = Path.join(modelBasePath,
+      (null == opts.outprefix ? '' : opts.outprefix) + 'def-generated.jsonic')
 
     const modelDef = { main: { def: apimodel.main.def } }
     let modelDefSrc = JSON.stringify(modelDef, null, 2)
@@ -176,20 +203,73 @@ function ApiDef(opts: ApiDefOptions) {
       modelDefSrc.substring(1, modelDefSrc.length - 1).replace(/\n  /g, '\n')
 
     writeChanged('def-model', defFilePath, modelDefSrc)
+  }
 
-    log.info({ point: 'generate-end', note: 'success', break: true })
 
-    return {
-      ok: true,
-      name: 'apidef',
-      apimodel,
-    }
+  function buildModel_entity(apimodel: ApiModel, modelPath: string) {
+    const modelBasePath = Path.dirname(modelPath)
+
+    const entityIncludes: string[] = []
+
+    each(apimodel.main.api.entity, ((entity: any) => {
+      entityIncludes.push(entity.name)
+
+      // 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  ')
+
+      const entityFileSrc = `
+# Entity ${entity.name}
+
+main: sdk: entity: ${entity.name}: {
+  alias: field: ${fieldAliasesSrc}
+}
+
+`
+      const entityFilePath = Path.join(modelBasePath, 'entity',
+        (null == opts.outprefix ? '' : opts.outprefix) + entity.name + '.jsonic')
+
+      fs.mkdirSync(Path.dirname(entityFilePath), { recursive: true })
+
+      // TODO: diff merge
+      writeChanged('entity-model', entityFilePath, entityFileSrc, { update: false })
+    }))
+
+
+    modifyModel(
+      fs,
+      Path.join(
+        modelBasePath,
+        (null == opts.outprefix ? '' : opts.outprefix) + 'sdk.jsonic'),
+      entityIncludes
+    )
   }
 
 
-  function writeChanged(point: string, path: string, content: string) {
+  function writeChanged(
+    point: string, path: string, content: string,
+    flags?: { update?: boolean }
+  ) {
     let exists = false
     let changed = false
+
+    flags = flags || {}
+    flags.update = null == flags.update ? true : !!flags.update
+
     let action = ''
     try {
       let existingContent: string = ''
@@ -204,7 +284,7 @@ function ApiDef(opts: ApiDefOptions) {
 
       changed = existingContent !== content
 
-      // console.log('WC', changed, path, existingContent, content)
+      action = flags.update ? 'write' : 'skip'
 
       log.info({
         point: 'write-' + point,
@@ -213,8 +293,7 @@ function ApiDef(opts: ApiDefOptions) {
         contentLength: content.length, file: path
       })
 
-      if (changed) {
-        action = 'write'
+      if (!exists || (changed && flags.update)) {
         fs.writeFileSync(path, content)
       }
     }
@@ -267,6 +346,34 @@ ApiDef.makeBuild = async function(opts: ApiDefOptions) {
 
 
 
+async function modifyModel(fs: any, path: string, entityIncludes: string[]) {
+  // TODO: This is a kludge.
+  // Aontu should provide option for as-is AST so that can be used
+  // to find injection point more reliably
+
+
+  let src = fs.existsSync(path) ? fs.readFileSync(path, 'utf8') :
+    'main: sdk: entity: {}\n'
+
+  let newsrc = '' + src
+
+  // Inject target file references into model
+  entityIncludes.sort().map((entname: string) => {
+    const lineRE =
+      new RegExp(`@"entity/${entname}.jsonic"`)
+
+    if (!src.match(lineRE)) {
+      newsrc = newsrc.replace(/(main:\s+sdk:\s+entity:\s+\{\s*\}\n)/, '$1' +
+        `@"entity/${entname}.jsonic"\n`)
+    }
+  })
+
+  if (newsrc.length !== src.length) {
+    fs.writeFileSync(path, newsrc)
+  }
+}
+
+
 
 export type {
   ApiDefOptions,

package/src/parse.ts

@@ -23,8 +23,6 @@ async function parseOpenAPI(source: any) {
     dereference: true,
   })
 
-  // console.dir(bundle.bundle, { depth: 1 })
-
   const def = bundle.bundle.parsed
 
   return def

package/src/transform/entity.ts

@@ -16,9 +16,6 @@ const entityTransform: Transform = async function(
 ): Promise<TransformResult> {
   let msg = ''
 
-  // console.log('DEF', def)
-  // console.log('GUIDE', guide)
-
   each(guide.entity, (guideEntity: any) => {
     const entityName = guideEntity.key$
     ctx.log.debug({ point: 'guide-entity', note: entityName })
@@ -39,9 +36,6 @@ const entityTransform: Transform = async function(
       const path = guidePath.key$
       const pathdef = def.paths[path]
 
-      // console.log('APIDEF FIND PATH', guidePath.key$, Object.keys(def.paths),
-      //  Object.keys(def.paths).includes(guidePath.key$))
-
       if (null == pathdef) {
         throw new Error('path not found in OpenAPI: ' + path +
           ' (entity: ' + guideEntity.name + ')')

package/src/transform/field.ts

@@ -47,7 +47,6 @@ const fieldTransform: Transform = async function(
 function fieldbuild(
   entityModel: any, pathdef: any, op: any, path: any, entity: any, model: any
 ) {
-  // console.log('FB-A', op, pathdef)
   let fieldCount = 0
   let fieldSets = getx(pathdef.get, 'responses 200 content "application/json" schema')
 
@@ -60,12 +59,8 @@ function fieldbuild(
     }
   }
 
-  // console.log('TRANSFORM-FIELDSETS', fieldSets)
-
   each(fieldSets, (fieldSet: any) => {
     each(fieldSet.properties, (property: any) => {
-      // console.log(property)
-
       const field =
         (entityModel.field[property.key$] = entityModel.field[property.key$] || {})
 
@@ -78,7 +73,6 @@ function fieldbuild(
       field.short = property.description
 
       fieldCount++
-      // console.log('FB-ID', field.name, entityModel.param)
     })
   })
 

package/src/transform/manual.ts

@@ -1,5 +1,5 @@
 
-import { Jsonic } from '@jsonic/jsonic-next'
+import { Jsonic } from 'jsonic'
 
 import { each, getx } from 'jostraca'
 
@@ -16,7 +16,7 @@ const manualTransform = async function(
   def: any
 ): Promise<TransformResult> {
 
-  const { model: { main: { guide: { manual } } } } = ctx
+  const { manual } = guide
 
   deep(model, manual)
 

package/src/transform/operation.ts

@@ -45,58 +45,83 @@ const operationTransform = async function(
   }
 
 
-  // Resolve the JSON path to the data (the "place").
-  const resolvePlace = (op: any, kind: 'res' | 'req', pathdef: any) => {
-    const opname = op.key$
-    // console.log('RP', kind, op)
+  // Resolve the JSON structure of the request or response.
+  // NOTE: uses heuristics.
+  const resolveTransform = (
+    op: any,
+    kind: 'res' | 'req',
+    direction: 'inward' | 'outward',
+    pathdef: any
+  ) => {
+    let out
+
+    if (null != op.transform?.[direction]) {
+      out = op.transform[direction]
+    }
 
-    let place = null == op.place ? '' : op.place
+    else {
+      const method = op.method
+      const mdef = pathdef[method]
 
-    if (null != place && '' !== place) {
-      return place
-    }
+      // TODO: fix getx
+      const content = 'res' === kind ?
+        (getx(mdef, 'responses.200.content') ||
+          getx(mdef, 'responses.201.content')) :
+        getx(mdef, 'requestBody.content')
 
-    const method = op.method
-    const mdef = pathdef[method]
 
-    // TODO: fix getx
-    const content = 'res' === kind ?
-      (getx(mdef, 'responses.200.content') ||
-        getx(mdef, 'responses.201.content')) :
-      getx(mdef, 'requestBody.content')
+      const schema = content['application/json']?.schema
 
+      const propkeys = null == schema?.properties ? [] : Object.keys(schema.properties)
 
-    // console.log('RP', kind, op, 'content', null == content)
+      const resolveDirectionTransform =
+        'inward' === direction ? resolveInwardTransform : resolveOutwardTransform
 
-    if (null == content) {
-      return place
+      const transform = resolveDirectionTransform(
+        op,
+        kind,
+        method,
+        mdef,
+        content,
+        schema,
+        propkeys
+      )
+
+      // out = JSON.stringify(transform)
+      out = transform
     }
 
-    const schema = content['application/json']?.schema
+    return out
+  }
+
 
-    // console.log('RP', kind, op, 'schema', null == schema)
+  const resolveInwardTransform = (
+    op: any,
+    kind: 'res' | 'req',
+    method: string,
+    mdef: any,
+    content: any,
+    schema: any,
+    propkeys: any
+  ) => {
+    let transform: any = '`body`'
 
-    if (null == schema) {
-      return place
+    if (null == content || null == schema || null == propkeys) {
+      return transform
     }
 
+    const opname = op.key$
 
-    const propkeys = null == schema.properties ? [] : Object.keys(schema.properties)
-
-    // HEURISTIC: guess place
     if ('list' === opname) {
-      if ('array' === schema.type) {
-        place = ''
-      }
-      else {
+      if ('array' !== schema.type) {
         if (1 === propkeys.length) {
-          place = 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) {
-              place = pk
+              transform = '`body.' + pk + '`'
               break
             }
           }
@@ -105,18 +130,69 @@ const operationTransform = async function(
     }
     else {
       if ('object' === schema.type) {
-        if (schema.properties.id) {
-          place = '' // top level
+        if (null == schema.properties.id) {
+          if (1 === propkeys.length) {
+            transform = '`body.' + propkeys[0] + '`'
+          }
+          else {
+            for (let pk of propkeys) {
+              if (schema.properties[pk].properties?.id) {
+                transform = '`body.' + pk + '`'
+                break
+              }
+            }
+          }
+        }
+      }
+    }
+
+    return transform
+  }
+
+
+  const resolveOutwardTransform = (
+    op: any,
+    kind: 'res' | 'req',
+    method: string,
+    mdef: any,
+    content: any,
+    schema: any,
+    propkeys: any
+  ) => {
+    let transform: any = '`data`'
+
+    if (null == content || null == schema || null == propkeys) {
+      return transform
+    }
+
+    const opname = op.key$
+
+    if ('list' === opname) {
+      if ('array' !== schema.type) {
+        if (1 === propkeys.length) {
+          transform = { [propkeys[0]]: '`data`' }
         }
         else {
+          // Use sub property that is an array
+          for (let pk of propkeys) {
+            if ('array' === schema.properties[pk]?.type) {
+              transform = { [pk]: '`data`' }
+              break
+            }
+          }
+        }
+      }
+    }
+    else {
+      if ('object' === schema.type) {
+        if (null == schema.properties.id) {
           if (1 === propkeys.length) {
-            place = propkeys[0]
+            transform = { [propkeys[0]]: '`data`' }
           }
           else {
-            // Use sub property with an id
             for (let pk of propkeys) {
               if (schema.properties[pk].properties?.id) {
-                place = pk
+                transform = { [pk]: '`data`' }
                 break
               }
             }
@@ -125,27 +201,26 @@ const operationTransform = async function(
       }
     }
 
-    // console.log('PLACE', op, kind, schema.type, 'P=', place)
-    return place
+    return transform
   }
 
 
   const opBuilder: any = {
     any: (entityModel: any, pathdef: any, op: any, path: any, entity: any, model: any) => {
-      // console.log('OP', op, pathdef, path, entity)
       const opname = op.key$
-      const method = op.val$
+      const method = op.method
       const kind = OPKIND[opname]
 
-      // console.log('EM', entityModel.name)
-
       const em = entityModel.op[opname] = {
         path: path.key$,
-        method: op.val$,
+        method,
         kind,
         param: {},
         query: {},
-        place: resolvePlace(op, kind, pathdef)
+        transform: {
+          inward: resolveTransform(op, kind, 'inward', pathdef),
+          outward: resolveTransform(op, kind, 'outward', pathdef),
+        }
       }
 
       fixName(em, op.key$)

package/src/transform.ts

@@ -70,30 +70,17 @@ const OPKIND: any = {
 
 
 const GuideShape = Gubu({
-  /*
-  entity: Child({
-    key$: '',
-    name: String,
-    path: Child({
-      op: Child({
-        method: Exact('get', 'post', 'put', 'patch', 'delete'),
-        place: ''
-      })
-    })
-    }),
-  */
   entity: {},
   control: {},
   transform: {},
+  manual: {},
 })
 
 type Guide = ReturnType<typeof GuideShape>
 
 
 async function resolveTransforms(ctx: TransformCtx): Promise<TransformSpec> {
-  const { log, model: { main: { guide } } } = ctx
-
-  // console.dir(api, { depth: null })
+  const { log, model: { main: { api: { guide } } } } = ctx
 
   const tspec: TransformSpec = {
     transform: []
@@ -117,17 +104,15 @@ async function resolveTransforms(ctx: TransformCtx): Promise<TransformSpec> {
     tspec.transform.push(transform)
   }
 
-  // console.log('TSPEC', tspec)
   return tspec
 }
 
 
 async function resolveTransform(tn: string, ctx: TransformCtx) {
-  const { log, defpath, model: { guide } } = ctx
+  const { log, defpath, model: { main: { api: { guide } } } } = ctx
 
   let transform = TRANSFORM[tn]
   if (transform) {
-    // console.log('resolveTransform', tn, transform)
     return transform
   }
 
@@ -174,7 +159,7 @@ async function processTransforms(
     results: []
   }
 
-  const guide: Guide = GuideShape(ctx.model.main.guide)
+  const guide: Guide = GuideShape(ctx.model.main.api.guide)
 
 
   for (let tI = 0; tI < spec.transform.length; tI++) {
@@ -202,18 +187,6 @@ async function processTransforms(
 
 
 
-
-
-/*
-function extractFields(properties: any) {
-  const fieldMap = each(properties)
-    .reduce((a: any, p: any) => (a[p.key$] =
-      { name: p.key$, kind: camelify(p.type) }, a), {})
-  return fieldMap
-}
-*/
-
-
 function fixName(base: any, name: string, prop = 'name') {
   base[prop.toLowerCase()] = name.toLowerCase()
   base[camelify(prop)] = camelify(name)