@voxgig/apidef 6.3.7 → 6.3.8

package/src/utility.ts

@@ -6,7 +6,7 @@ import { snakify, camelify, kebabify, each } from 'jostraca'
 import { decircular } from '@voxgig/util'
 
 import {
-  slice, merge, inject, clone, isnode, walk, transform, select,
+  slice, merge, inject, clone, isnode, walk, transform, select, keysof,
   Injection,
   M_VAL,
   M_KEYPRE,
@@ -134,7 +134,12 @@ function formatJsonSrc(jsonsrc: string) {
 //
 // Keys are lowercase; depluralize() does a case-insensitive lookup
 // and reapplies the caller's casing on the way out.
-const IRREGULARS: Record<string, string> = {
+//
+// Null-prototype: these tables are indexed by spec-derived names, so a
+// schema or path segment called `constructor` / `__proto__` / `toString`
+// would otherwise resolve to the inherited Object member and be returned
+// as a "match" — crashing matchCase() on a function. See NULL_PROTO_NOTE.
+const IRREGULARS: Record<string, string> = Object.assign(Object.create(null), {
   'analytics': 'analytics',
   'analyses': 'analysis',
   'appendices': 'appendix',
@@ -198,7 +203,18 @@ const IRREGULARS: Record<string, string> = {
   'vertices': 'vertex',
   'women': 'woman',
   'yes': 'yes',
-}
+})
+
+// NULL_PROTO_NOTE: every plain-object lookup table in this module whose keys
+// come from an API spec is built with a null prototype
+// (`Object.assign(Object.create(null), {...})`). Without it, `TABLE[name]`
+// inherits from Object.prototype, so `TABLE['constructor']` yields the Object
+// constructor (truthy, a function) and `TABLE['__proto__']` yields
+// Object.prototype (truthy, an object). Both then flow into code expecting a
+// string. A spec with `components.schemas.Constructor` is enough to reach
+// this: canonize -> depluralize -> matchCase -> `.toLowerCase is not a
+// function`, failing the whole build at the guide stage. Keep new tables
+// null-prototype, or use a Map (CANONIZE_CACHE already does).
 
 // Sorted longest-first so the most specific IRREGULARS suffix wins.
 // Without this, 'women' would be shadowed by 'men' (3 < 5) under
@@ -235,12 +251,13 @@ function matchCase(source: string, target: string): string {
 // inherit the override without signature churn. apidef is
 // single-model-per-process; if that ever changes, switch this to a
 // per-context map.
-let CUSTOM_PLURALS: Record<string, string> = {}
+// Null-prototype: see NULL_PROTO_NOTE above.
+let CUSTOM_PLURALS: Record<string, string> = Object.create(null)
 let CUSTOM_PLURAL_KEYS: string[] = []
 
 
 function setCustomPlurals(plurals: Record<string, string> | undefined | null) {
-  CUSTOM_PLURALS = {}
+  CUSTOM_PLURALS = Object.create(null)
   if (plurals) {
     for (const k of Object.keys(plurals)) {
       // Skip null/undefined values so a partially-typed model entry
@@ -905,7 +922,17 @@ function renderJSONIC(
 }
 
 
-const VALID_CANON: Record<string, string> = {
+// Canonical type-sentinel vocabulary. VALID_CANON maps an OpenAPI type NAME
+// to its `$SENTINEL` form; CANON_ONE is the union sentinel produced by
+// `validator` for a multi-type (`['`$ONE`', [member, ...]]`). Both are part
+// of the public API so downstream consumers (e.g. @voxgig/sdkgen's
+// sentinel -> language-type table) can verify they cover the full set
+// instead of hand-syncing against this file.
+//
+// Null-prototype (see NULL_PROTO_NOTE): `type` values come from the spec, so
+// a schema declaring `type: constructor` would otherwise return the Object
+// constructor here rather than falling through to the 'Any' default.
+const VALID_CANON: Record<string, string> = Object.assign(Object.create(null), {
   'string': '`$STRING`',
   'number': '`$NUMBER`',
   'integer': '`$INTEGER`',
@@ -914,7 +941,9 @@ const VALID_CANON: Record<string, string> = {
   'array': '`$ARRAY`',
   'object': '`$OBJECT`',
   'any': '`$ANY`',
-}
+})
+
+const CANON_ONE = '`$ONE`'
 
 
 function validator(torig: undefined | string | string[]): any {
@@ -924,7 +953,7 @@ function validator(torig: undefined | string | string[]): any {
     return canon
   }
   else if (Array.isArray(torig)) {
-    return ['`$ONE`', torig.map((t: string) => validator(t))]
+    return [CANON_ONE, torig.map((t: string) => validator(t))]
   }
   else {
     return '`$ANY`'
@@ -1376,6 +1405,150 @@ export type {
   PathMatch
 }
 
+
+// A response property only "wraps" the entity when it is itself a structured
+// value that could contain the entity: an object, an array, a $ref, or a
+// composed (allOf/oneOf/anyOf) schema. A scalar property (string, integer,
+// number, boolean) that merely shares the entity's name is a field of the
+// entity, not a wrapper, so the response must not be unwrapped down to it.
+function isEntityWrapperProp(propSchema: any): boolean {
+  if (null == propSchema || 'object' !== typeof propSchema) {
+    return false
+  }
+  if (null != propSchema.$ref) {
+    return true
+  }
+  if (null != propSchema.properties ||
+    null != propSchema.items ||
+    null != propSchema.allOf ||
+    null != propSchema.oneOf ||
+    null != propSchema.anyOf) {
+    return true
+  }
+  const t = propSchema.type
+  return 'object' === t || 'array' === t
+}
+
+
+// A response body that is nothing but a single wrapper property is an
+// ENVELOPE around the result: `{item: {...}}`, `{data: {...}}`,
+// `{items: [...]}`, `{results: [...]}`. Return that property's name so the
+// caller can unwrap to it, or null when the body is the result itself.
+//
+// Two conditions keep this from firing on a response that IS the entity:
+//
+//   1. EXACTLY ONE property. A body with siblings is a structure in its own
+//      right, not a wrapper — `{ok, id}` from a delete, or any paged
+//      `{results, next}`, must be handed over whole.
+//   2. The property's SHAPE matches the operation's cardinality. A `list`
+//      unwraps only to an array, every other op only to a non-array. So a
+//      single-entity op facing `{items: [...]}` is left alone rather than
+//      silently yielding a list, and vice versa.
+//
+// A one-field entity whose sole field is itself structured can still be
+// unwrapped wrongly; that is the residual cost of the spec not saying which
+// it means. Naming the wrapper after the entity remains the unambiguous
+// signal, and is still checked first.
+function envelopeProp(resprops: any, opname: string): string | null {
+  const keys = keysof(resprops)
+  if (1 !== keys.length) {
+    return null
+  }
+
+  const key = keys[0]
+  const prop = resprops[key]
+  if (!isEntityWrapperProp(prop)) {
+    return null
+  }
+
+  const islist = propIsList(prop)
+  if (null == islist || islist !== ('list' === opname)) {
+    return null
+  }
+
+  return key
+}
+
+
+// Is this schema a collection? null when the schema does not say.
+//
+// `isEntityWrapperProp` accepts a composed schema (allOf/oneOf/anyOf) as
+// structured, but a composed schema carries no outer `type` or `items` — so
+// reading those alone silently called it a non-list. A `list` then kept its
+// envelope, and worse, a single-entity op unwrapped to an array-valued
+// property. Composed branches are inspected instead, and unanimity required:
+// a union that is an array in one branch and an object in another does not
+// say what the caller will get, and an envelope is not worth guessing at.
+function propIsList(schema: any): boolean | null {
+  if (null == schema || 'object' !== typeof schema) {
+    return null
+  }
+
+  const branches = schema.allOf ?? schema.oneOf ?? schema.anyOf
+  if (Array.isArray(branches)) {
+    if (0 === branches.length) {
+      return null
+    }
+    const first = propIsList(branches[0])
+    if (null == first) {
+      return null
+    }
+    for (const branch of branches) {
+      if (propIsList(branch) !== first) {
+        return null
+      }
+    }
+    return first
+  }
+
+  return 'array' === schema.type || null != schema.items
+}
+
+
+// The request BODY a closed schema permits, as a transform mapping.
+//
+// `additionalProperties: false` is the spec saying the server rejects any
+// property it did not declare. When a body says that, sending the caller's
+// whole request payload is wrong: an op's payload also carries its PATH
+// params (`id` for `PUT /item/{id}`), and a closed shape 400s the entire
+// request over that one extra key. Restricting the body to the declared
+// properties is then not a heuristic — it is what the spec asked for.
+//
+// Returns null for an open or property-less schema, where `reqdata` (send
+// everything) remains the right default: an open body accepts extras, and
+// with no declared properties there is nothing to restrict to.
+//
+// The KEY is the property's wire name — that is what goes on the wire and
+// what the server matches against. The SOURCE is read by the field's
+// CANONICAL name, because that is the only name the caller ever sees:
+// findFieldDefs runs every property through `canonize(normalizeFieldName())`,
+// so a spec property `UserName` reaches the generated request type as
+// `user_name`. Reading `reqdata.UserName` would find nothing and send
+// undefined.
+function closedBodyTransform(schema: any): Record<string, string> | null {
+  if (null == schema || 'object' !== typeof schema) {
+    return null
+  }
+  if (false !== schema.additionalProperties) {
+    return null
+  }
+
+  const names = keysof(schema.properties)
+  if (0 === names.length) {
+    return null
+  }
+
+  // Null prototype: a spec is free to declare a property called `__proto__`,
+  // and on an ordinary object that assignment sets the prototype instead of
+  // creating an own property — the mapping would vanish, and with it the
+  // whole body restriction if it were the only one.
+  const out: Record<string, string> = Object.create(null)
+  for (const name of names) {
+    out[name] = '`reqdata.' + canonize(normalizeFieldName(name)) + '`'
+  }
+  return out
+}
+
 export {
   nom,
   getdlog,
@@ -1390,6 +1563,8 @@ export {
   makeWarner,
   formatJSONIC,
   validator,
+  VALID_CANON,
+  CANON_ONE,
   canonize,
   canonizeCmpName,
   stripSchemaNamespace,
@@ -1408,5 +1583,8 @@ export {
   getModelPath,
   sortedKeys,
   sortedEntries,
+  isEntityWrapperProp,
+  envelopeProp,
+  closedBodyTransform,
 
 }