genoc 0.4.2 → 0.4.3

package/README.md

@@ -12,6 +12,7 @@ Generated code depends only on the tiny `genoc/runtime` module. Full type safety
 
 - Full OpenAPI 3.0 and 3.1 specification support with automatic version detection
 - End-to-end type safety: requests, responses, and errors are fully typed
+- Typed path parameters: values are typed from their schema and accept `T | string` — pass a pre-formatted string for custom wire formatting; serialization is inline `String()`
 - Works with any HTTP client: plug in fetch, axios, or anything else
 - Shared runtime contract: `genoc/runtime` exports the `Requester` type and response and error classes, so one requester implementation works with every generated client
 - Error types with per-status-code narrowing and type guards
@@ -115,7 +116,7 @@ For the full example of catching and narrowing errors, see [Error handling](./do
 ## Documentation
 
 - [Configuration](./docs/configuration.md): CLI flags, `.genocrc` config files, method naming strategies, and proxy support
-- [Usage](./docs/usage.md): the `Requester` contract, shared runtime, binary and file responses, and JSDoc output
+- [Usage](./docs/usage.md): the `Requester` contract, `createClient` options, shared runtime, binary and file responses, and JSDoc output
 - [Error handling](./docs/error-handling.md): typed errors, `isDefinedError`, and the catching example
 - [OpenAPI 3.0 support](./docs/openapi-3.0-support.md): data types, schema keywords, parameters, bodies, uploads, responses, errors, `$ref`, components, security, servers, and operations
 - [OpenAPI 3.1 support](./docs/openapi-3.1-support.md): all 3.0 features plus webhooks and JSON Schema 2020-12 alignment, with a diff against 3.0

package/dist/analyzer/analyze.js

@@ -41,6 +41,34 @@ function attachTypeJsDoc(jsDoc, definition) {
 function indentJsDocBlock(jsDoc) {
     return jsDoc.split('\n').map((line) => `${INDENT_UNIT}${line}`);
 }
+/** Schema used for parameters declared without a `schema` (typed as `string`). */
+function defaultedParamSchema(param) {
+    return param.schema ?? { type: 'string' };
+}
+const STRING_SERIALIZABLE_MEMBER = /^(string|number|boolean|null|true|false|'[^']*'|-?\d+(?:\.\d+)?)$/;
+/**
+ * Whether a finished path-param type can be serialized inline with `String()`:
+ * every union member must be a primitive with a defined string form, or a
+ * string/number literal (literal unions like `'fast' | 'slow'` are kept).
+ * Named component types count when their own mapped definition resolves
+ * (transitively, cycle-safe) to such members — so `$ref` path params to
+ * primitive aliases keep their named type. Anything else — objects, arrays,
+ * named non-primitive `$ref` types — falls back to a `string` signature (the
+ * pre-typed-path-params behavior), because there is no defined string
+ * serialization for such values.
+ */
+function isInlineSerializableType(tsType, namedMappedTypes, seen = new Set()) {
+    return tsType.split('|').every((member) => {
+        const token = member.trim();
+        if (STRING_SERIALIZABLE_MEMBER.test(token))
+            return true;
+        const namedDefinition = namedMappedTypes.get(token);
+        if (namedDefinition === undefined || seen.has(token))
+            return false;
+        const nextSeen = new Set(seen).add(token);
+        return isInlineSerializableType(namedDefinition, namedMappedTypes, nextSeen);
+    });
+}
 /**
  * Build the JSDoc block for a query/header parameter property using the
  * pinned parameter merge rule: parameter-level description / deprecated /
@@ -62,7 +90,7 @@ function buildParamPropertyJsDoc(param, schema) {
 function buildParamTypeBody(params, mapper) {
     const lines = [];
     for (const param of params) {
-        const paramSchema = param.schema ?? { type: 'string' };
+        const paramSchema = defaultedParamSchema(param);
         const result = mapper.mapSchema(paramSchema);
         const optional = param.required ? '' : '?';
         const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param.name) ? param.name : `"${param.name}"`;
@@ -301,10 +329,14 @@ export function analyze(doc, opts = {}) {
     });
     // Section 1: Schema types
     const schemaEntries = [];
+    // Mapped definition text per renamed component name — lets the path-param
+    // inline-serializability check resolve named types to their primitives.
+    const namedMappedTypes = new Map();
     if (doc.components?.schemas) {
         for (const [name, schema] of Object.entries(doc.components.schemas)) {
             const renamedName = renameMap.get(name) ?? sanitizeTypeName(name);
             const result = mapper.mapSchema(schema, renamedName);
+            namedMappedTypes.set(renamedName, result.tsType);
             const resolved = resolver.resolve(schema);
             const definition = `export type ${renamedName} = ${result.tsType};`;
             schemaEntries.push({
@@ -337,6 +369,43 @@ export function analyze(doc, opts = {}) {
     const { operations: analyzedOperations, requestBodySchemas } = analyzePathsDetailed(doc, resolver, strategy);
     const operations = [];
     for (const op of analyzedOperations) {
+        // Path params render as flat method arguments, so each carries its
+        // finished signature type. A raw `$ref` schema maps to the named contract
+        // type (the same raw-schema travel pattern as request bodies and
+        // responses — the contracts renderer emits the named type from the
+        // component table); the mapper's import facts feed the client file's
+        // `import type` list. Inline schemas map the resolved schema with
+        // `format` stripped: path params are typed by their base primitive
+        // (boolean, number, literal unions) and format brands don't flow into
+        // signatures.
+        const pathParamTypeNames = new Set();
+        for (const param of op.pathParams) {
+            const raw = param.rawSchema;
+            if (raw !== undefined && '$ref' in raw) {
+                const result = mapper.mapSchema(raw);
+                if (isInlineSerializableType(result.tsType, namedMappedTypes)) {
+                    param.finishedType = result.tsType;
+                    for (const name of result.imports) {
+                        pathParamTypeNames.add(name);
+                    }
+                }
+                else {
+                    // Inline-serialization constraint: a `$ref` to an object/array
+                    // schema (or any non-primitive named type) has no defined string
+                    // form, so the parameter falls back to `string` and the named
+                    // type is not imported into the client file.
+                    param.finishedType = 'string';
+                }
+                continue;
+            }
+            const schema = defaultedParamSchema(param);
+            const tracerSchema = schema.format === undefined ? schema : { ...schema, format: undefined };
+            const mapped = mapper.mapSchema(tracerSchema).tsType;
+            param.finishedType = isInlineSerializableType(mapped, namedMappedTypes) ? mapped : 'string';
+        }
+        if (pathParamTypeNames.size > 0) {
+            op.pathParamTypeNames = [...pathParamTypeNames];
+        }
         operations.push({
             ...op,
             contractsLines: [],

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

@@ -7,9 +7,21 @@ export interface AnalyzedParameter {
     required: boolean;
     /** Resolved param schema — analyzer-internal translation input for `analyze()`; renderers must not read it. */
     schema: SchemaObject | undefined;
+    /**
+     * Raw (possibly `$ref`) param schema — analyzer-internal translation input
+     * for `analyze()`; renderers must not read it. Kept beside the resolved
+     * schema so `$ref` sites translate to the named contract type (the same
+     * raw-schema travel pattern as request bodies and responses).
+     */
+    rawSchema: SchemaObject | ReferenceObject | undefined;
     description?: string;
     deprecated?: boolean;
     example?: unknown;
+    /**
+     * Finished (real-mapper) TS type text for the method signature — set by
+     * `analyze()` for path params, the only params rendered as flat args.
+     */
+    finishedType?: string;
 }
 export interface AnalyzedRequestBody {
     required: boolean;
@@ -59,6 +71,12 @@ export interface AnalyzedOperation {
     queryParams: AnalyzedParameter[];
     headerParams: AnalyzedParameter[];
     cookieParams: AnalyzedParameter[];
+    /**
+     * Named contract types referenced by path-param finished types (`$ref`
+     * path params). Set by `analyze()` from the mapper's import facts; drives
+     * the client file's `import type` list for method signatures.
+     */
+    pathParamTypeNames?: string[];
     requestBody: AnalyzedRequestBody | undefined;
     responses: AnalyzedResponse[];
 }

package/dist/analyzer/path-analyzer.js

@@ -28,6 +28,7 @@ function analyzeParameter(param, resolver) {
         in: param.in,
         required: param.required ?? param.in === 'path',
         schema,
+        rawSchema: param.schema,
         description: param.description,
         deprecated: param.deprecated,
         example: param.example,

package/dist/generator/client-generator.js

@@ -17,7 +17,7 @@ function buildClientMethodBody(op) {
     const emissions = operationEmissions(op);
     let urlTemplate = op.path;
     for (const param of op.pathParams) {
-        urlTemplate = urlTemplate.replace(`{${param.name}}`, `\${encodeURIComponent(${param.name})}`);
+        urlTemplate = urlTemplate.replace(`{${param.name}}`, `\${encodeURIComponent(String(${param.name}))}`);
     }
     const urlExpr = `\`${urlTemplate}\``;
     const errorCheckLines = [];

package/dist/generator/method-generator.js

@@ -25,7 +25,18 @@ function buildParameters(op) {
     const emissions = operationEmissions(op);
     const specs = [];
     for (const param of op.pathParams) {
-        specs.push({ name: param.name, type: 'string', isOptional: false });
+        // Finished signature type text arrives from the analyzer's translation
+        // layer; `?? 'string'` only guards hand-built `AnalyzedOperation` inputs.
+        const finished = param.finishedType ?? 'string';
+        // `T | string` is the caller escape hatch for custom wire formatting:
+        // pass a pre-formatted string instead of the schema type. When T is
+        // already `string` the union is skipped, and string-literal unions
+        // deliberately widen to `string` (flexibility over strictness here).
+        specs.push({
+            name: param.name,
+            type: finished === 'string' ? 'string' : `${finished} | string`,
+            isOptional: false,
+        });
     }
     if (emissions.query !== undefined) {
         const allOptional = op.queryParams.every((p) => !p.required);

package/dist/utils/operation-naming.js

@@ -151,6 +151,11 @@ export function clientImportedNames(op) {
         names.push(emissions.headers);
     if (emissions.body !== undefined)
         names.push(emissions.body);
+    // `$ref` path params reference named contract types directly in the method
+    // signature, so the client file must import them (fact collected by
+    // `analyze()` from the mapper's import list).
+    if (op.pathParamTypeNames !== undefined)
+        names.push(...op.pathParamTypeNames);
     if (emissions.response !== undefined) {
         const successType = getSuccessType(op);
         if (successType !== 'void' && successType !== 'unknown' && /^[A-Z]/.test(successType)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genoc",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Generate typed HTTP clients from OpenAPI 3.0 / 3.1 specifications",
   "keywords": [
     "client",