@voxgig/apidef 1.8.0 → 2.0.0

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,165 @@
+
+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
+  }
+
+  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,
+    param: {
+      [`${model.NAME}_TEST_${apiEntity.NAME}_ENTID`]: idmap
+    },
+    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
+
+  if (apiEntity.op.load) {
+    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\``
+      },
+      valid: {
+        '`$OPEN`': true,
+        id: `\`dm$=s.${name}.match.id\``
+      }
+    })
+  }
+
+  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\``,
+        ...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\``
+      },
+      valid: {
+        '`$OPEN`': true,
+        id: `\`dm$=s.${loadref}.match.id\``,
+        ...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/flowHeuristic01.ts~

@@ -0,0 +1,45 @@
+
+
+import { each, snakify, 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 apiEntity = ctx.apimodel.main.api.entity[entity.name]
+
+  const flow: any = {
+    name: 'Basic' + apiEntity.Name
+  }
+
+  flow.model = ({
+    name: flow.Name,
+    param: {},
+    test: { entity: { [apiEntity.Name]: {} } },
+    step: []
+  } as any)
+
+  names(flow, flow.name)
+
+  return flow
+}
+
+
+
+export {
+  flowHeuristic01
+}

package/src/builder/flow.ts

@@ -0,0 +1,60 @@
+
+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 + 'Flow.jsonic')
+
+        let flowModelSrc = formatJsonSrc(JSON.stringify(flow.model, null, 2))
+
+        let flowsrc = `# ${flow.Name}Flow
+
+main: sdk: flow: ${flow.Name}Flow:
+` + 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,225 @@
+
+
+import { each, snakify, names } from 'jostraca'
+
+
+
+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
+
+  each(paths, (pathdef, pathname) => {
+    // look for rightmmost /entname/{entid}
+    const m = pathname.match(/\/([a-zA-Z0-1_-]+)\/\{([a-zA-Z0-1_-]+)\}$/)
+    if (m) {
+      let origentname = snakify(m[1])
+      let entname = depluralize(origentname)
+
+      let entdesc = (entityDescs[entname] = entityDescs[entname] || { name: entname })
+      entdesc.plural = origentname
+
+      names(entdesc, entname)
+
+      entdesc.alias = entdesc.alias || {}
+
+      if ('id' != m[2]) {
+        entdesc.alias.id = m[2]
+        entdesc.alias[m[2]] = 'id'
+      }
+
+      entdesc.path = (entdesc.path || {})
+
+      const op: Record<string, any> = {}
+      entdesc.path[pathname] = { op }
+
+      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[origentname]) {
+            // TODO: use quotes when @voxgig/struct updated to support them
+            // transform.resform = '`body."'+origentname+'"`'
+            transform.resform = '`body.' + origentname + '`'
+          }
+          else if (resbody[entname]) {
+            transform.resform = '`body.' + entname + '`'
+          }
+        }
+
+        const reqdef = mdef.requestBody?.content?.['application/json']?.schema?.properties
+        if (reqdef) {
+          if (reqdef[origentname]) {
+            transform.reqform = { [origentname]: '`reqdata`' }
+          }
+          else if (reqdef[entname]) {
+            transform.reqform = { [entname]: '`reqdata`' }
+          }
+
+        }
+
+        op[opname] = {
+          // TODO: in actual guide, remove "standard" method ops since redundant
+          method,
+        }
+
+        if (0 < Object.entries(transform).length) {
+          op[opname].transform = transform
+        }
+      })
+    }
+  })
+
+
+  each(paths, (pathdef, pathname) => {
+    // look for rightmmost /entname/{entid}
+    const m = pathname.match(/\/([a-zA-Z0-1_-]+)$/)
+    if (m) {
+      let origentname = snakify(m[1])
+      let entname = depluralize(origentname)
+
+      let entdesc = entityDescs[entname]
+
+      if (entdesc) {
+        entdesc.path = (entdesc.path || {})
+
+        if (pathdef.get) {
+          const op: Record<string, any> = { list: { method: 'get' } }
+          entdesc.path[pathname] = { 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[origentname]) {
+              // TODO: use quotes when @voxgig/struct updated to support them
+              // transform.resform = '`body."'+origentname+'"`'
+              transform.resform = '`body.' + origentname + '`'
+            }
+            else if (resbody[entname]) {
+              transform.resform = '`body.' + entname + '`'
+            }
+          }
+
+          if (0 < Object.entries(transform).length) {
+            op.transform = transform
+          }
+        }
+      }
+    }
+  })
+
+  return entityDescs
+}
+
+
+function depluralize(word: string): string {
+  if (!word || word.length === 0) {
+    return word
+  }
+
+  // Common irregular plurals
+  const irregulars: Record<string, string> = {
+    'children': 'child',
+    'men': 'man',
+    'women': 'woman',
+    'teeth': 'tooth',
+    'feet': 'foot',
+    'geese': 'goose',
+    'mice': 'mouse',
+    'people': 'person',
+    'data': 'datum',
+    'criteria': 'criterion',
+    'phenomena': 'phenomenon',
+    'indices': 'index',
+    'matrices': 'matrix',
+    'vertices': 'vertex',
+    'analyses': 'analysis',
+    'axes': 'axis',
+    'crises': 'crisis',
+    'diagnoses': 'diagnosis',
+    'oases': 'oasis',
+    'theses': 'thesis',
+    'appendices': 'appendix'
+  }
+
+  if (irregulars[word]) {
+    return irregulars[word]
+  }
+
+  // Rules for regular plurals (applied in order)
+
+  // -ies -> -y (cities -> city)
+  if (word.endsWith('ies') && word.length > 3) {
+    return word.slice(0, -3) + 'y'
+  }
+
+  // -ves -> -f or -fe (wolves -> wolf, knives -> knife)
+  if (word.endsWith('ves')) {
+    const stem = word.slice(0, -3)
+    // Check if it should be -fe (like knife, wife, life)
+    if (['kni', 'wi', 'li'].includes(stem)) {
+      return stem + 'fe'
+    }
+    return stem + 'f'
+  }
+
+  // -oes -> -o (potatoes -> potato)
+  if (word.endsWith('oes')) {
+    return word.slice(0, -2)
+  }
+
+  // -ses, -xes, -zes, -shes, -ches -> remove -es (boxes -> box)
+  if (word.endsWith('ses') || word.endsWith('xes') || word.endsWith('zes') ||
+    word.endsWith('shes') || word.endsWith('ches')) {
+    return word.slice(0, -2)
+  }
+
+  // -s -> remove -s (cats -> cat)
+  if (word.endsWith('s') && !word.endsWith('ss')) {
+    return word.slice(0, -1)
+  }
+
+  // If none of the rules apply, return as is
+  return word
+}
+
+
+export {
+  heuristic01
+}