@voxgig/apidef 0.2.0 → 1.0.0

package/src/transform/field.ts

@@ -0,0 +1,185 @@
+
+
+import { each, getx } from 'jostraca'
+
+import type { TransformCtx, TransformSpec } from '../transform'
+
+import { fixName } from '../transform'
+
+
+
+async function fieldTransform(
+  ctx: TransformCtx,
+  tspec: TransformSpec,
+  model: any,
+  def: any
+) {
+  const { guide: { guide } } = ctx
+  let msg = 'fields: '
+
+  each(guide.entity, (guideEntity: any) => {
+
+    const entityModel = model.main.api.entity[guideEntity.key$]
+    let fieldCount = 0
+    each(guideEntity.path, (guidePath: any) => {
+      const pathdef = def.paths[guidePath.key$]
+
+      each(guidePath.op, (op: any) => {
+
+        if ('load' === op.key$) {
+          fieldCount = fieldbuild(entityModel, pathdef, op, guidePath, guideEntity, model)
+        }
+
+      })
+    })
+
+    msg += guideEntity.name + '=' + fieldCount + ' '
+  })
+
+  return { ok: true, msg }
+}
+
+
+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')
+
+  if (fieldSets) {
+    if (Array.isArray(fieldSets.allOf)) {
+      fieldSets = fieldSets.allOf
+    }
+    else if (fieldSets.properties) {
+      fieldSets = [fieldSets]
+    }
+  }
+
+  // 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$] || {})
+
+      field.name = property.key$
+      fixName(field, field.name)
+
+      field.type = property.type
+      fixName(field, field.type, 'type')
+
+      field.short = property.description
+
+      fieldCount++
+      // console.log('FB-ID', field.name, entityModel.param)
+    })
+  })
+
+  // Guess id field name using GET path param
+  if ('load' === op.key$) {
+    const getdef = pathdef.get
+    const getparams = getdef.parameters || []
+    if (1 === getparams.length) {
+      if (entityModel.op.load.path.match(RegExp('\\{' + getdef.parameters[0].name + '\\}$'))) {
+        entityModel.id.field = getdef.parameters[0].name
+      }
+    }
+  }
+
+  return fieldCount
+}
+
+
+
+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', save: '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/manual.ts

@@ -0,0 +1,22 @@
+
+import { Jsonic } from '@jsonic/jsonic-next'
+
+import { each, getx } from 'jostraca'
+
+import type { TransformCtx, TransformSpec } from '../transform'
+
+
+const { deep } = Jsonic.util
+
+async function manualTransform(ctx: TransformCtx, tspec: TransformSpec, model: any, def: any) {
+  const { guide: { guide: { manual } } } = ctx
+
+  deep(model, manual)
+
+  return { ok: true, msg: 'manual' }
+}
+
+
+export {
+  manualTransform
+}

package/src/transform/operation.ts

@@ -0,0 +1,125 @@
+
+
+import { each, getx } from 'jostraca'
+
+import type { TransformCtx, TransformSpec } from '../transform'
+
+import { fixName } from '../transform'
+
+
+
+async function operationTransform(
+  ctx: TransformCtx,
+  tspec: TransformSpec,
+  model: any,
+  def: any
+) {
+  const { guide: { guide } } = ctx
+  let msg = 'operations: '
+
+  const paramBuilder = (paramMap: any, paramDef: any,
+    entityModel: any, pathdef: any,
+    op: any, path: any, entity: any, model: any) => {
+
+    paramMap[paramDef.name] = {
+      required: paramDef.required
+    }
+    fixName(paramMap[paramDef.name], paramDef.name)
+
+    const type = paramDef.schema ? paramDef.schema.type : paramDef.type
+    fixName(paramMap[paramDef.name], type, 'type')
+  }
+
+
+  const queryBuilder = (queryMap: any, queryDef: any,
+    entityModel: any, pathdef: any,
+    op: any, path: any, entity: any, model: 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')
+  }
+
+  const opBuilder: any = {
+    any: (entityModel: any, pathdef: any, op: any, path: any, entity: any, model: any) => {
+      const em = entityModel.op[op.key$] = {
+        path: path.key$,
+        method: op.val$,
+        param: {},
+        query: {},
+      }
+      fixName(em, op.key$)
+
+      // Params are in the path
+      if (0 < path.params$.length) {
+        let params = getx(pathdef[op.val$], '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)
+        }
+      }
+
+      // Queries are after the ?
+      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)
+      }
+
+      return em
+    },
+
+
+    list: (entityModel: any, pathdef: any, op: any, path: any, entity: any, model: any) => {
+      return opBuilder.any(entityModel, pathdef, op, path, entity, model)
+    },
+
+    load: (entityModel: any, pathdef: any, op: any, path: any, entity: any, model: any) => {
+      return opBuilder.any(entityModel, pathdef, op, path, entity, model)
+    },
+
+    create: (entityModel: any, pathdef: any, op: any, path: any, entity: any, model: any) => {
+      return opBuilder.any(entityModel, pathdef, op, path, entity, model)
+    },
+
+    save: (entityModel: any, pathdef: any, op: any, path: any, entity: any, model: any) => {
+      return opBuilder.any(entityModel, pathdef, op, path, entity, model)
+    },
+
+    remove: (entityModel: any, pathdef: any, op: any, path: any, entity: any, model: any) => {
+      return opBuilder.any(entityModel, pathdef, op, path, entity, model)
+    },
+
+  }
+
+
+
+  each(guide.entity, (guideEntity: any) => {
+    let opcount = 0
+    const entityModel = model.main.api.entity[guideEntity.key$]
+    each(guideEntity.path, (guidePath: any) => {
+      const pathdef = def.paths[guidePath.key$]
+
+      each(guidePath.op, (op: any) => {
+        const opbuild = opBuilder[op.key$]
+
+        if (opbuild) {
+          opbuild(entityModel, pathdef, op, guidePath, guideEntity, model)
+          opcount++
+        }
+      })
+    })
+
+    msg += guideEntity.name + '=' + opcount + ' '
+  })
+
+  return { ok: true, msg }
+}
+
+
+export {
+  operationTransform
+}

package/src/transform/top.ts

@@ -0,0 +1,21 @@
+
+import { each, getx } from 'jostraca'
+
+import type { TransformCtx, TransformSpec } from '../transform'
+
+import { fixName } from '../transform'
+
+
+async function topTransform(ctx: TransformCtx, tspec: TransformSpec, model: any, def: any) {
+  const { spec } = ctx
+
+  fixName(model.main.api, spec.meta.name)
+  model.main.def.desc = def.info.description
+
+  return { ok: true, msg: spec.meta.name }
+}
+
+
+export {
+  topTransform
+}

package/src/transform.ts

@@ -0,0 +1,193 @@
+/* Copyright (c) 2024 Voxgig, MIT License */
+
+
+import Path from 'node:path'
+
+import { getx, each, camelify } from 'jostraca'
+
+
+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'
+
+
+
+type TransformCtx = {
+  log: any,
+  spec: any,
+  guide: any,
+  opts: any,
+  util: any,
+  defpath: string,
+}
+
+type TransformSpec = {
+  transform: Transform[]
+}
+
+type TransformResult = {
+  ok: boolean
+  msg: string
+}
+
+type Transform = (
+  ctx: TransformCtx,
+  tspec: TransformSpec,
+  model: any,
+  def: any,
+) => Promise<TransformResult>
+
+type ProcessResult = {
+  ok: boolean
+  msg: string,
+  results: TransformResult[]
+}
+
+
+const TRANSFORM: Record<string, Transform> = {
+  top: topTransform,
+  entity: entityTransform,
+  operation: operationTransform,
+  field: fieldTransform,
+  manual: manualTransform,
+}
+
+
+
+
+async function resolveTransforms(ctx: TransformCtx): Promise<TransformSpec> {
+  const { log, guide: { guide } } = ctx
+
+  const tspec: TransformSpec = {
+    transform: []
+  }
+
+  // TODO: parameterize
+  const defkind = 'openapi'
+  const transformNames = guide.control.transform[defkind].order
+    .split(/\s*,\s*/)
+    .map((t: string) => t.trim())
+    .filter((t: string) => '' != t)
+
+  log.info({ point: 'transform', note: 'order', order: transformNames })
+
+  for (const tn of transformNames) {
+    log.debug({ what: 'transform', transform: tn })
+    const transform = await resolveTransform(tn, ctx)
+    tspec.transform.push(transform)
+  }
+
+  return tspec
+}
+
+
+async function resolveTransform(tn: string, ctx: TransformCtx) {
+  const { log, defpath, guide: { guide } } = ctx
+
+  let transform = TRANSFORM[tn]
+  if (transform) {
+    return transform
+  }
+
+  const tdef = guide.transform[tn]
+  if (null == tdef) {
+    const err = new Error('Unknown transform: ' + tn)
+    log.error({ what: 'transform', transform: tn, fail: 'unknown', err })
+    throw err
+  }
+
+  if (!tn.startsWith('custom')) {
+    const err =
+      new Error('Custom transform name must start with "custom": ' + tn)
+    log.error({ what: 'transform', transform: tn, fail: 'prefix', err })
+    throw err
+  }
+
+  const customtpath = Path.join(defpath, tdef.load)
+  try {
+    const transformModule = require(customtpath)
+    transform = transformModule[tn]
+  }
+  catch (e: any) {
+    const err = new Error('Custom transform not found: ' +
+      customtpath + ': ' + e.message)
+    log.error({ what: 'transform', transform: tn, fail: 'require', err })
+    throw err
+  }
+
+  return transform
+}
+
+
+
+async function processTransforms(
+  ctx: TransformCtx,
+  spec: TransformSpec,
+  model: any,
+  def: any
+): Promise<ProcessResult> {
+  const pres: ProcessResult = {
+    ok: true,
+    msg: '',
+    results: []
+  }
+
+  for (let tI = 0; tI < spec.transform.length; tI++) {
+    const transform = spec.transform[tI]
+
+    try {
+      const tres = await transform(ctx, spec, model, def)
+      pres.ok = pres.ok && tres.ok
+      pres.msg += tres.msg + '\n'
+      pres.results.push(tres)
+    }
+    catch (err: any) {
+      pres.ok = false
+      pres.msg += err.message + '\n'
+      pres.results.push({
+        ok: false,
+        msg: err.message
+      })
+    }
+  }
+
+  return pres
+}
+
+
+
+
+
+/*
+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)
+  base[prop.toUpperCase()] = name.toUpperCase()
+}
+
+
+
+
+
+export type {
+  TransformCtx,
+  TransformSpec,
+}
+
+
+export {
+  fixName,
+  resolveTransforms,
+  processTransforms,
+}

package/model/guide.jsonic~

@@ -1,14 +0,0 @@
-
-guide: entity: &: {
-  name: .$KEY
-  path: &: {
-    op: {}
-  }
-}
-
-
-guide: feature: &: {
-  name: .$KEY
-  active: *false | boolean
-}
-