@voxgig/apidef 2.4.0 → 3.0.2

package/src/model.ts

@@ -0,0 +1,98 @@
+/* Copyright (c) 2024-2025 Voxgig, MIT License */
+
+// Consolidated model types for the API model derived from OpenAPI specifications
+
+import type { MethodName } from './types'
+
+
+// Operation names available on entities
+type OpName = 'load' | 'list' | 'create' | 'update' | 'delete' | 'patch' | 'head' | 'options'
+
+
+// Entity relationships information
+type ModelEntityRelations = {
+  ancestors: string[][]
+}
+
+
+// Map of operations available on an entity
+type ModelOpMap = Partial<Record<OpName, ModelOp | undefined>>
+
+
+// Field-specific operation configuration
+type ModelFieldOp = {
+  type: any // @voxgig/struct validation schema
+  req: boolean
+}
+
+
+// Entity field definition
+type ModelField = {
+  name: string
+  type: any // @voxgig/struct validation schema
+  req: boolean
+  op: Partial<Record<OpName, ModelFieldOp>>
+}
+
+
+// Operation argument/parameter definition
+type ModelArg = {
+  name: string
+  type: any // @voxgig/struct validation schema
+  kind: 'param' | 'query' | 'header' | 'cookie'
+  req: boolean
+}
+
+
+// Alternative implementation of an operation
+type ModelAlt = {
+  orig: string
+  method: MethodName
+  parts: string[]
+  args: Partial<{
+    param: ModelArg[]
+    query: ModelArg[]
+    header: ModelArg[]
+    cookie: ModelArg[]
+  }>
+  select: {
+    param?: Record<string, boolean | string>
+    query?: Record<string, boolean | string>
+    header?: Record<string, boolean | string>
+    cookie?: Record<string, boolean | string>
+    $action?: string
+  }
+}
+
+
+// Operation definition
+type ModelOp = {
+  name: OpName
+  alts: ModelAlt[]
+}
+
+
+// Entity definition - core model entity with operations and fields
+type ModelEntity = {
+  name: string,
+  op: ModelOpMap,
+  fields: ModelField[],
+  id: {
+    name: string,
+    field: string,
+  },
+  relations: ModelEntityRelations
+}
+
+
+export type {
+  OpName,
+  ModelEntityRelations,
+  ModelOpMap,
+  ModelFieldOp,
+  ModelField,
+  ModelArg,
+  ModelAlt,
+  ModelOp,
+  ModelEntity,
+}

package/src/parse.ts

@@ -1,11 +1,8 @@
-/* Copyright (c) 2024 Voxgig, MIT License */
+/* Copyright (c) 2024-2025 Voxgig, MIT License */
 
 import { bundleFromString, createConfig } from '@redocly/openapi-core'
 
-import { each, snakify } from 'jostraca'
-
-
-import { depluralize } from './utility'
+import decircular from 'decircular'
 
 
 // Parse an API definition source into a JSON sructure.
@@ -59,16 +56,17 @@ async function parseOpenAPI(source: any, meta?: any) {
   addXRefs(bundleWithRefs.bundle.parsed)
 
   // Serialize back to string with x-refs preserved
-  const sourceWithXRefs = JSON.stringify(bundleWithRefs.bundle.parsed)
+  const sourceWithXRefs = JSON.stringify(decircular(bundleWithRefs.bundle.parsed))
 
   // Second pass: parse with dereferencing
   const bundle = await bundleFromString({
     source: sourceWithXRefs,
+    // source,
     config,
     dereference: true,
   })
 
-  const def = bundle.bundle.parsed
+  const def = decircular(bundle.bundle.parsed)
 
   return def
 }
@@ -79,60 +77,6 @@ async function parseOpenAPI(source: any, meta?: any) {
 
 
 
-// Make consistent changes to support semantic entities.
-function rewrite(def: any) {
-  const paths = def.paths
-  each(paths, (path) => {
-    each(path.parameters, (param: any) => {
-
-      let new_param = param.name
-      let new_path = path.key$
-
-      // Rename param if nane is "id", and not the final param.
-      // Rewrite /foo/{id}/bar as /foo/{foo_id}/bar.
-      // Avoids ambiguity with bar id.
-      if (param.name.match(/^id$/i)) {
-        let m = path.key$.match(/\/([^\/]+)\/{id\}\/[^\/]/)
-
-        if (m) {
-          const parent = depluralize(snakify(m[1]))
-          new_param = `${parent}_id`
-          new_path = path.key$.replace('{id}', '{' + new_param + '}')
-        }
-      }
-      else {
-        new_param = depluralize(snakify(param.name))
-        new_path = path.key$.replace('{' + param.name + '}', '{' + new_param + '}')
-      }
-
-      let pathdef = paths[path.key$]
-      delete paths[path.key$]
-
-      paths[new_path] = pathdef
-      path.key$ = new_path
-
-      param.name = new_param
-    })
-  })
-
-
-  sortkeys(def, 'paths')
-  sortkeys(def, 'components')
-
-  return def
-}
-
-
-function sortkeys(obj: any, prop: string) {
-  const sorted: any = {}
-  const sorted_keys = Object.keys(obj[prop]).sort()
-  for (let sk of sorted_keys) {
-    sorted[sk] = obj[prop][sk]
-  }
-  obj[prop] = sorted
-}
-
 export {
   parse,
-  rewrite,
 }

package/src/schematron.ts.off

@@ -0,0 +1,317 @@
+type JSONSchema = Record<string, any>;
+
+type ConvertOptions = {
+  /** Where to resolve $ref from. Use your OpenAPI doc’s components.schemas, or JSON Schema $defs. */
+  refRoots?: Array<Record<string, JSONSchema>>;
+  /** Optional: pass the entire root doc; only used if your $ref are absolute like #/components/schemas/X */
+  rootDoc?: Record<string, any>;
+};
+
+const TYPE_TOKEN: Record<string, string> = {
+  string: "$STRING",
+  number: "$NUMBER",
+  integer: "$INTEGER",
+  boolean: "$BOOLEAN",
+  null: "$NULL",
+};
+
+export function convert(
+  schema: JSONSchema | undefined,
+  opts: ConvertOptions = {}
+): any {
+  const seen = new Set<object>();
+  const resolvingRefs = new Set<string>();
+
+
+  const resolveRef = ($ref: string): JSONSchema | undefined => {
+    if (!$ref.startsWith("#/")) return undefined; // non-local refs not supported per spec; return undefined to fallback
+    const parts = $ref.slice(2).split("/").map(unescapeRefToken);
+    let node: any = opts.rootDoc ?? {};
+    for (const p of parts) node = node?.[p];
+    if (node) return node;
+
+    // Try common roots passed in refRoots (e.g., components.schemas, $defs)
+    for (const root of opts.refRoots ?? []) {
+      let probe: any = root;
+      for (const p of parts) probe = probe?.[p];
+      if (probe) return probe;
+    }
+    return undefined;
+  };
+
+  const expandRef = (sch: JSONSchema): JSONSchema => {
+    if (typeof sch?.$ref === "string") {
+      const target = resolveRef(sch.$ref);
+      if (target) return target;
+      // Not supported → per rule 10, “just expand the reference”; if we cannot, fall back to ANY.
+      return {};
+    }
+    return sch;
+  };
+
+  function convert(s: JSONSchema | undefined): any {
+    if (!s || Object.keys(s).length === 0) {
+      // Rule 13 – empty schema accepts anything
+      return "$ANY";
+    }
+
+    // Prevent cycles from blowing the stack on malformed docs
+    if (seen.has(s)) return "$ANY";
+    seen.add(s);
+
+    // // // Expand $ref immediately (Rule 10)
+    // // if (s.$ref) {
+    // //   const tgt = expandRef(s);
+    // //   // Merge local decorations on top of the ref target (common in OAS)
+    // //   const merged = { ...tgt, ...without(s, ["$ref"]) };
+    // //   const out = convert(merged);
+    // //   seen.delete(s);
+    // //   return out;
+    // // }
+
+
+    // // Expand $ref immediately (Rule 10)
+    // if (s.$ref) {
+    //   const target = expandRef(s);
+    //   const localDecor = without(s, ["$ref"]); // local fields that decorate the ref
+    //   // Use the same semantics as allOf merging to deep-merge properties/openness/etc.
+    //   const merged = mergeAllOf([target, localDecor]);
+    //   const out = convert(merged);
+    //   seen.delete(s);
+    //   return out;
+    // }
+
+    if (s.$ref) {
+      const ref = String(s.$ref);
+      if (resolvingRefs.has(ref)) {
+        // cycle detected -> cannot expand, fall back to ANY
+        seen.delete(s);
+        return "$ANY";
+      }
+      resolvingRefs.add(ref);
+
+      const target = expandRef(s); // returns referenced schema or {}
+      const localDecor = without(s, ["$ref"]);
+      // merge like allOf so local decorations augment target
+      const merged = mergeAllOf([target, localDecor]);
+
+      const out = convert(merged);
+
+      resolvingRefs.delete(ref);
+      seen.delete(s);
+      return out;
+    }
+
+
+    // Composition
+    if (Array.isArray(s.allOf) && s.allOf.length > 0) {
+      const merged = mergeAllOf(s.allOf.map((x) => expandRef(x)));
+      // Carry over top-level decorations (e.g., nullable, annotations)
+      const mergedWithTop = { ...merged, ...without(s, ["allOf"]) };
+      const out = convert(mergedWithTop);
+      seen.delete(s);
+      return out;
+    }
+
+    if (Array.isArray(s.oneOf) && s.oneOf.length > 0) {
+      const alts = s.oneOf.map((x) => convert(expandRef(x)));
+      const out = ["$ONE", ...alts];
+      seen.delete(s);
+      return out;
+    }
+
+    if (Array.isArray(s.anyOf) && s.anyOf.length > 0) {
+      const alts = s.anyOf.map((x) => convert(expandRef(x)));
+      const out = ["$ANY", ...alts]; // Rule 3 – anyOf uses "$ANY" in the same directive position
+      seen.delete(s);
+      return out;
+    }
+
+    // Enum / const → $EXACT
+    if (Array.isArray(s.enum) && s.enum.length > 0) {
+      const out = ["$EXACT", ...s.enum];
+      seen.delete(s);
+      return out;
+    }
+    if (Object.prototype.hasOwnProperty.call(s, "const")) {
+      const out = ["$EXACT", s.const];
+      seen.delete(s);
+      return out;
+    }
+
+    // Handle OpenAPI nullable at this level by wrapping the base type later
+    const nullable = s.nullable === true;
+
+    // Type handling (could be string or array)
+    const t = s.type;
+    if (Array.isArray(t) && t.length > 0) {
+      // Union of primitives (and possibly null)
+      const tokens = t.map((tt) => TYPE_TOKEN[tt] ?? "$ANY");
+      const out = ["$ONE", ...tokens];
+      seen.delete(s);
+      return out;
+    }
+
+    // Objects
+    if (t === "object" || s.properties || s.additionalProperties !== undefined) {
+      const obj: Record<string, any> = {};
+
+      // $OPEN
+      if (s.additionalProperties === true) {
+        obj["$OPEN"] = true;
+      } else if (s.additionalProperties && typeof s.additionalProperties === "object") {
+        // We cannot express typed extras (Rule 6). Keep it open but untyped.
+        obj["$OPEN"] = true;
+      }
+      // $NOTE annotations (Rule 11)
+      const note: Record<string, any> = {};
+      if (s.readOnly === true) note.readOnly = true;
+      if (s.writeOnly === true) note.writeOnly = true;
+      if (s.deprecated === true) note.deprecated = true;
+      if (Object.keys(note).length > 0) obj["$NOTE"] = note;
+
+      const props = s.properties ?? {};
+      for (const [key, sub] of Object.entries<JSONSchema>(props)) {
+        const converted = convert(expandRef(sub));
+        const isNullable =
+          sub?.nullable === true ||
+          (Array.isArray(sub?.type) && sub.type.includes("null")) ||
+          includesNullViaOneAnyOf(sub);
+
+        obj[key] = isNullable ? wrapNullable(converted) : converted;
+      }
+
+      seen.delete(s);
+      return obj;
+    }
+
+    // Arrays
+    if (t === "array" || s.items) {
+      const items = s.items;
+      if (Array.isArray(items)) {
+        // Tuple validation → positional sub-schemas
+        const out = items.map((it) => convert(expandRef(it)));
+        seen.delete(s);
+        return out;
+      } else if (items && typeof items === "object") {
+        // Homogeneous array → ["$CHILD", sub]
+        const out = ["$CHILD", convert(expandRef(items))];
+        seen.delete(s);
+        return out;
+      } else {
+        // No items → accept any child element
+        seen.delete(s);
+        return [];
+      }
+    }
+
+    // Primitives
+    if (typeof t === "string" && TYPE_TOKEN[t]) {
+      const token = TYPE_TOKEN[t];
+      const base = token;
+
+      const out = nullable ? wrapNullable(base) : base;
+      seen.delete(s);
+      return out;
+    }
+
+    // No explicit type, but we might still infer:
+    if (s.properties || s.additionalProperties !== undefined) {
+      // already handled in object branch, but keep a guard
+      const out = convert({ ...s, type: "object" });
+      seen.delete(s);
+      return out;
+    }
+    if (s.items) {
+      const out = convert({ ...s, type: "array" });
+      seen.delete(s);
+      return out;
+    }
+
+    // Fallback
+    seen.delete(s);
+    return "$ANY";
+  }
+
+  const result = convert(schema);
+  return result;
+}
+
+/* -------------------------- helpers -------------------------- */
+
+function unescapeRefToken(s: string) {
+  // JSON Pointer ~0 -> ~, ~1 -> /
+  return s.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+function without<T extends Record<string, any>>(obj: T, keys: string[]): T {
+  const copy: any = {};
+  for (const k of Object.keys(obj)) if (!keys.includes(k)) copy[k] = obj[k];
+  return copy;
+}
+
+function includesNullViaOneAnyOf(s: JSONSchema): boolean {
+  const hasNullIn = (arr?: any[]) =>
+    Array.isArray(arr) &&
+    arr.some((x) => x?.type === "null" || (Array.isArray(x?.type) && x.type.includes("null")));
+  return hasNullIn(s.oneOf) || hasNullIn(s.anyOf);
+}
+
+function wrapNullable(inner: any) {
+  // Rule 1/4 – nullable → ["$ONE", inner, "$NULL"]
+  return Array.isArray(inner) && inner[0] === "$ONE"
+    ? inner.includes("$NULL")
+      ? inner
+      : ["$ONE", ...inner.slice(1), "$NULL"]
+    : ["$ONE", inner, "$NULL"];
+}
+
+function mergeAllOf(schemas: JSONSchema[]): JSONSchema {
+  const out: JSONSchema = {};
+  let anyObject = false;
+
+  for (const s of schemas) {
+    const schema = s || {};
+
+    if (schema.type === "object" || schema.properties || schema.additionalProperties !== undefined) {
+      anyObject = true;
+      out.type = "object";
+
+      // --- properties: merge without losing earlier branches ---
+      const srcProps = schema.properties ?? {};
+      const dstProps = (out.properties = out.properties ?? {});
+      for (const [k, v] of Object.entries(srcProps)) {
+        if (k in dstProps) {
+          // Combine the two property schemas using allOf semantics.
+          // This preserves earlier constraints like {type:'number'} and
+          // later decorations like {nullable:true}.
+          dstProps[k] = { allOf: [dstProps[k], v] };
+        } else {
+          dstProps[k] = v;
+        }
+      }
+
+      // --- additionalProperties: openness is "true if any true/object" ---
+      const ap = schema.additionalProperties;
+      if (ap === true || (ap && typeof ap === "object")) {
+        out.additionalProperties = true;
+      } else if (out.additionalProperties === undefined) {
+        out.additionalProperties = ap;
+      }
+
+      // --- required: union (not used in voxgig/struct but harmless to keep) ---
+      if (Array.isArray(schema.required)) {
+        const req = new Set([...(out.required ?? []), ...schema.required]);
+        out.required = Array.from(req);
+      }
+    } else {
+      // For non-object shapes in allOf, a shallow merge is the best we can do.
+      Object.assign(out, schema);
+    }
+  }
+
+  // If nothing was objecty, return a shallow merge across all schemas.
+  return anyObject
+    ? out
+    : (schemas.reduce((a, b) => ({ ...a, ...(b || {}) }), {}) as JSONSchema);
+}

package/src/transform/args.ts

@@ -0,0 +1,102 @@
+
+
+import { each, snakify } from 'jostraca'
+
+import type { TransformResult, Transform } from '../transform'
+
+import { formatJSONIC, depluralize, validator } from '../utility'
+
+
+import { KIT } from '../types'
+
+import type { KitModel } from '../types'
+
+import type {
+  PathDef,
+  ParameterDef,
+  MethodDef,
+} from '../def'
+
+import type {
+  OpName,
+  ModelOp,
+  ModelEntity,
+  ModelAlt,
+  ModelArg,
+} from '../model'
+
+
+
+const argsTransform = async function(
+  ctx: any,
+): Promise<TransformResult> {
+  const { apimodel, def } = ctx
+  const kit: KitModel = apimodel.main[KIT]
+
+  let msg = 'args '
+
+
+  each(kit.entity, (ment: ModelEntity, entname: string) => {
+    each(ment.op, (mop: ModelOp, opname: OpName) => {
+      each(mop.alts, (malt: ModelAlt) => {
+        const argdefs: ParameterDef[] = []
+
+        const pathdef: PathDef = def.paths[malt.orig]
+        argdefs.push(...(pathdef.parameters ?? []))
+
+        const opdef: MethodDef = (pathdef as any)[malt.method.toLowerCase()]
+        argdefs.push(...(opdef.parameters ?? []))
+
+        resolveArgs(ment, mop, malt, argdefs)
+      })
+    })
+
+    msg += ment.name + ' '
+  })
+
+  return { ok: true, msg }
+}
+
+
+const ARG_KIND: Record<string, ModelArg["kind"]> = {
+  'query': 'query',
+  'header': 'header',
+  'path': 'param',
+  'cookie': 'cookie',
+}
+
+
+function resolveArgs(ment: ModelEntity, mop: ModelOp, malt: ModelAlt, argdefs: ParameterDef[]) {
+  each(argdefs, (argdef: ParameterDef) => {
+    const marg: ModelArg = {
+      name: depluralize(snakify(argdef.name)),
+      type: validator(argdef.schema?.type),
+      kind: ARG_KIND[argdef.in] ?? 'query',
+      req: !!argdef.required
+    }
+
+    if (argdef.nullable) {
+      marg.type = ['`$ONE`', '`$NULL`', marg.type]
+    }
+
+    // insert sorted by name
+    let kindargs = (malt.args[marg.kind] = malt.args[marg.kind] ?? [])
+
+    let kalen = kindargs.length
+    for (let ka, i = 0; i <= kalen; i++) {
+      ka = kindargs[i]
+      if (ka && ka.name > marg.name) {
+        kindargs = [...kindargs.slice(0, i), marg, ...kindargs.slice(i + 1)]
+      }
+      else {
+        kindargs.push(marg)
+      }
+    }
+  })
+}
+
+
+
+export {
+  argsTransform,
+}

package/src/transform/clean.ts

@@ -1,10 +1,9 @@
 
-import { each, getx } from 'jostraca'
-
 import type { TransformResult } from '../transform'
 
-import { walk } from '@voxgig/struct'
+import { walk, isempty, isnode, ismap, islist } from '@voxgig/struct'
 
+import { formatJSONIC } from '../utility'
 
 
 const cleanTransform = async function(
@@ -12,12 +11,48 @@ const cleanTransform = async function(
 ): Promise<TransformResult> {
   const { apimodel } = ctx
 
-  walk(apimodel, (k: any, v: any) => {
-    if ('string' === typeof k && k.includes('$')) {
-      return undefined
+  let cur: any[] = []
+
+  // Remove empty nodes and undefined values
+  walk(
+    apimodel,
+    (k: any, v: any, _p: any, ancestors: any) => {
+      if (undefined === k) {
+        cur[ancestors.length] = ismap(v) ? {} : islist(v) ? [] : v
+        return v
+      }
+
+      let vi = v
+
+      if (isnode(v)) {
+        if (isempty(v)) {
+          vi = undefined
+        }
+        else {
+          vi = cur[ancestors.length] = ismap(v) ? {} : []
+        }
+
+      }
+
+      if (undefined !== vi && !k.endsWith('$')) {
+        cur[ancestors.length - 1][k] = vi
+      }
+
+      return v
+    },
+
+    (k: any, _v: any, _p: any, ancestors: any) => {
+      const pi = cur[ancestors.length - 1]
+      if (undefined !== pi) {
+        const vi = pi[k]
+        if (isnode(vi) && isempty(vi)) {
+          delete pi[k]
+        }
+      }
     }
-    return v
-  })
+  )
+
+  ctx.apimodel = cur[0]
 
   return { ok: true, msg: 'clean' }
 }