genoc 0.5.2 → 0.5.3

package/README.md

@@ -58,10 +58,11 @@ import type { Requester } from 'genoc/runtime';
 For the full `Requester` type signature and binary and stream handling, see [Usage](./docs/usage.md).
 
 ```typescript
-import { createClient } from './client.js';
 import type { Requester } from 'genoc/runtime';
 import { RequesterFailError, ErrorResponse } from 'genoc/runtime';
 
+import { createClient } from './client.js';
+
 const baseUrl = 'https://api.example.com';
 
 const requester: Requester = async (method, path, options) => {

package/dist/analyzer/analyze.js

@@ -3,7 +3,7 @@ import { buildSchemaRenameMap, buildTypeJsDoc, sanitizeJsDocText, sanitizeTypeNa
 import { operationEmissions, RESERVED_TYPE_NAMES } from '../utils/operation-naming.js';
 import { escapeStringLiteral } from '../utils/string.js';
 import { buildDiscriminatorRegistry, renameAwareTypeName } from './discriminator-registry.js';
-import { analyzePathsDetailed } from './path-analyzer.js';
+import { analyzePathsDetailed, collectFormProperties, findBinaryFieldNames, schemaContainsBinary, } from './path-analyzer.js';
 import { SchemaMapper } from './schema-mapper.js';
 /**
  * Indent unit matching `INDENT_UNIT` in schema-mapper.ts (2 spaces, pinned by
@@ -338,6 +338,7 @@ function analyzeServers(servers) {
 export function analyze(doc, opts = {}) {
     const resolver = opts.resolver ?? new RefResolver(doc);
     const strategy = opts.strategy ?? 'path-based';
+    const warn = opts.warnSink ?? writeWarning;
     const schemaNameList = doc.components?.schemas ? Object.keys(doc.components.schemas) : [];
     const renameMap = buildSchemaRenameMap(schemaNameList, RESERVED_TYPE_NAMES);
     for (const [original, renamed] of renameMap) {
@@ -360,7 +361,7 @@ export function analyze(doc, opts = {}) {
     // source for discriminator translation: the mapper's ref-translation seam
     // consumes it, and the always-emitted `{Base}Variant` unions below are
     // emitted from it.
-    const discriminatorRegistry = buildDiscriminatorRegistry(doc.components?.schemas, resolver, renameMap, allSchemaNames, writeWarning);
+    const discriminatorRegistry = buildDiscriminatorRegistry(doc.components?.schemas, resolver, renameMap, allSchemaNames, warn);
     const mapper = new SchemaMapper(resolver, {
         typeNameGenerator: renamingTypeGenerator,
         emittedNames: allSchemaNames,
@@ -472,14 +473,28 @@ export function analyze(doc, opts = {}) {
         if (emissions.headers) {
             opLines.push(`export type ${emissions.headers} = ${buildParamTypeBody(op.headerParams, mapper)};`);
         }
+        // A urlencoded body declaring `format: binary` fields cannot transport
+        // them — the generated client would silently type the files as plain
+        // strings. Warn and name the offending fields (merged through allOf).
+        if (op.requestBody?.contentTypes[0] === 'application/x-www-form-urlencoded' &&
+            rawBodySchema !== undefined &&
+            schemaContainsBinary(rawBodySchema, resolver)) {
+            const fieldNames = findBinaryFieldNames(rawBodySchema, resolver);
+            const fieldList = fieldNames.length > 0
+                ? ` declaring binary fields (${fieldNames.map((n) => `"${n}"`).join(', ')})`
+                : ' declaring binary data';
+            warn(`Warning: the request body of ${op.method.toUpperCase()} ${op.path} uses content type "application/x-www-form-urlencoded"${fieldList}, but urlencoded form data cannot transport binary files. File uploads require "multipart/form-data"; the generated client types these fields as plain strings.\n`);
+        }
         // Section 3: Request body types
         const bodyJsDoc = op.requestBody ? buildDescriptionJsDoc(op.requestBody.description) : '';
         if (op.requestBody?.isMultipart && rawBodySchema !== undefined) {
-            const schema = resolver.resolveSchema(rawBodySchema);
-            const requiredSet = new Set(schema.required ?? []);
+            // Form fields come from the allOf-merged walk: a body declaring its
+            // fields via `allOf` members (resolving `$ref`s) previously produced an
+            // empty property walk — `Record<string, never>` and dropped appends.
+            const { properties, required: requiredSet } = collectFormProperties(rawBodySchema, resolver);
             const propLines = [];
             const fileUploadProperties = [];
-            for (const [name, propSchema] of Object.entries(schema.properties ?? {})) {
+            for (const [name, propSchema] of properties) {
                 const resolved = resolver.resolveSchema(propSchema);
                 const optional = requiredSet.has(name) ? '' : '?';
                 let tsType;

package/dist/analyzer/path-analyzer.d.ts

@@ -82,6 +82,37 @@ export interface AnalyzedOperation {
     /** Raw operation-level `security`; `undefined` = inherit the document default. */
     security?: SecurityRequirementObject[];
 }
+/**
+ * Deep, ref-resolving, cycle-safe check: does any schema node reachable from
+ * `schema` (through `properties`, `items`, `allOf`/`oneOf`/`anyOf` members and
+ * schema-valued `additionalProperties`) declare `format: binary`? Unlike
+ * {@link isBinarySchema} this catches binary data buried in composed schemas —
+ * e.g. a `files` array of binary strings hidden inside an `allOf` member.
+ */
+export declare function schemaContainsBinary(schema: SchemaObject | ReferenceObject | undefined, resolver: RefResolver): boolean;
+/**
+ * The flattened form fields of a request body schema: the root object's own
+ * `properties`/`required` merged with those of every `allOf` member,
+ * recursively, resolving `$ref`s. Later same-named members do not override
+ * earlier ones (first-write wins, matching the mapper's `allOf` array-order
+ * rendering); member `required` lists are unioned.
+ *
+ * Motivation: multipart bodies declaring their fields via `allOf` (a common
+ * upstream-spec shape) previously produced an empty property walk — the
+ * generated body type collapsed to `Record<string, never>` and every FormData
+ * append was silently dropped.
+ */
+export declare function collectFormProperties(schema: SchemaObject | ReferenceObject | undefined, resolver: RefResolver, properties?: Map<string, SchemaObject | ReferenceObject>, required?: Set<string>, visited?: Set<SchemaObject>): {
+    properties: Map<string, SchemaObject | ReferenceObject>;
+    required: Set<string>;
+};
+/**
+ * Names of the (allOf-merged) top-level form fields whose subtree contains
+ * `format: binary` — for warnings that name the offending fields. Empty when
+ * the binary data sits outside any named field (e.g. the whole body schema
+ * is a binary string) or there is no binary data at all.
+ */
+export declare function findBinaryFieldNames(schema: SchemaObject | ReferenceObject | undefined, resolver: RefResolver): string[];
 /**
  * Analyzer-internal analysis result: the analyzed operations plus the raw
  * request body schemas in a PARALLEL ARRAY (same length and order as

package/dist/analyzer/path-analyzer.js

@@ -12,6 +12,103 @@ function isBinarySchema(schema, resolver) {
         return false;
     return resolver.resolveSchema(schema).format === 'binary';
 }
+/**
+ * Deep, ref-resolving, cycle-safe check: does any schema node reachable from
+ * `schema` (through `properties`, `items`, `allOf`/`oneOf`/`anyOf` members and
+ * schema-valued `additionalProperties`) declare `format: binary`? Unlike
+ * {@link isBinarySchema} this catches binary data buried in composed schemas —
+ * e.g. a `files` array of binary strings hidden inside an `allOf` member.
+ */
+export function schemaContainsBinary(schema, resolver) {
+    return containsBinary(schema, resolver, new Set());
+}
+function containsBinary(schema, resolver, visited) {
+    if (!schema)
+        return false;
+    const resolved = resolver.resolveSchema(schema);
+    // Cycle guard on resolved object identity (a self-referencing $ref chain
+    // would otherwise recurse forever; schema-mapper uses the same pattern).
+    if (visited.has(resolved))
+        return false;
+    visited.add(resolved);
+    if (resolved.format === 'binary')
+        return true;
+    if (resolved.items !== undefined) {
+        if (containsBinary(resolved.items, resolver, visited))
+            return true;
+    }
+    for (const member of resolved.allOf ?? []) {
+        if (containsBinary(member, resolver, visited))
+            return true;
+    }
+    for (const member of resolved.oneOf ?? []) {
+        if (containsBinary(member, resolver, visited))
+            return true;
+    }
+    for (const member of resolved.anyOf ?? []) {
+        if (containsBinary(member, resolver, visited))
+            return true;
+    }
+    for (const propSchema of Object.values(resolved.properties ?? {})) {
+        if (containsBinary(propSchema, resolver, visited))
+            return true;
+    }
+    if (typeof resolved.additionalProperties === 'object' && resolved.additionalProperties !== null) {
+        if (containsBinary(resolved.additionalProperties, resolver, visited))
+            return true;
+    }
+    return false;
+}
+/**
+ * The flattened form fields of a request body schema: the root object's own
+ * `properties`/`required` merged with those of every `allOf` member,
+ * recursively, resolving `$ref`s. Later same-named members do not override
+ * earlier ones (first-write wins, matching the mapper's `allOf` array-order
+ * rendering); member `required` lists are unioned.
+ *
+ * Motivation: multipart bodies declaring their fields via `allOf` (a common
+ * upstream-spec shape) previously produced an empty property walk — the
+ * generated body type collapsed to `Record<string, never>` and every FormData
+ * append was silently dropped.
+ */
+export function collectFormProperties(schema, resolver, properties = new Map(), required = new Set(), visited = new Set()) {
+    if (!schema)
+        return { properties, required };
+    const resolved = resolver.resolveSchema(schema);
+    // Cycle guard on resolved identity (same pattern as containsBinary above).
+    if (visited.has(resolved))
+        return { properties, required };
+    visited.add(resolved);
+    // allOf members come first, mirroring the mapper's `A & B` member order.
+    for (const member of resolved.allOf ?? []) {
+        collectFormProperties(member, resolver, properties, required, visited);
+    }
+    for (const name of resolved.required ?? []) {
+        required.add(name);
+    }
+    for (const [name, propSchema] of Object.entries(resolved.properties ?? {})) {
+        if (!properties.has(name)) {
+            properties.set(name, propSchema);
+        }
+    }
+    return { properties, required };
+}
+/**
+ * Names of the (allOf-merged) top-level form fields whose subtree contains
+ * `format: binary` — for warnings that name the offending fields. Empty when
+ * the binary data sits outside any named field (e.g. the whole body schema
+ * is a binary string) or there is no binary data at all.
+ */
+export function findBinaryFieldNames(schema, resolver) {
+    const { properties } = collectFormProperties(schema, resolver);
+    const names = [];
+    for (const [name, propSchema] of properties) {
+        if (containsBinary(propSchema, resolver, new Set())) {
+            names.push(name);
+        }
+    }
+    return names;
+}
 function resolveParameter(param, resolver) {
     return resolver.resolve(param);
 }

package/dist/analyzer/schema-mapper.js

@@ -267,6 +267,14 @@ export class SchemaMapper {
             return result;
         }
         if (s.type === undefined) {
+            // OpenAPI permits omitting `type`: a schema carrying `properties`
+            // and/or `additionalProperties` is an object schema regardless. Map it
+            // through the object branch instead of degrading to `unknown`; a
+            // genuinely unconstrained schema (no keywords to infer from) stays
+            // `unknown` (any JSON value).
+            if (s.properties !== undefined || s.additionalProperties !== undefined) {
+                return this.mapObject(s, name, context, visited, indent, spine);
+            }
             return { tsType: 'unknown', imports: [] };
         }
         if (Array.isArray(s.type)) {

package/dist/analyzer/types.d.ts

@@ -148,4 +148,6 @@ export interface AnalyzeOptions {
      * Omitted is treated as `'3.1'`.
      */
     effectiveVersion?: '3.0' | '3.1';
+    /** Warning sink; defaults to `process.stderr.write`. Mirrors the mapper's `warnSink`. */
+    warnSink?: (message: string) => void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genoc",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Generate typed HTTP clients from OpenAPI 3.0 / 3.1 specifications",
   "keywords": [
     "client",
@@ -48,12 +48,12 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
-    "@types/node": "^26.6.2",
-    "oxfmt": "^0.70.0",
-    "oxlint": "^1.85.0",
+    "@types/node": "^26.6.5",
+    "oxfmt": "^0.75.0",
+    "oxlint": "^1.90.0",
     "typescript": "^6.0.3",
-    "undici": "^8",
-    "vitest": "^5.0.1"
+    "undici": "^8.12.3",
+    "vitest": "^5.0.5"
   },
   "peerDependencies": {
     "undici": "^6.13.0 || ^7 || ^8"