nuxt-openapi-hyperfetch 0.1.7-alpha.1 → 0.2.7-alpha.1

package/dist/generators/components/schema-analyzer/openapi-reader.js

@@ -0,0 +1,76 @@
+import { readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { load as loadYaml } from 'js-yaml';
+/**
+ * Read an OpenAPI spec from a YAML or JSON file.
+ * Returns the parsed spec with all $ref values resolved inline.
+ */
+export function readOpenApiSpec(filePath) {
+    const absPath = path.resolve(filePath);
+    const content = readFileSync(absPath, 'utf-8');
+    const raw = filePath.endsWith('.json')
+        ? JSON.parse(content)
+        : loadYaml(content);
+    if (!raw || typeof raw !== 'object' || !raw.openapi || !raw.paths) {
+        throw new Error(`Invalid OpenAPI spec: ${absPath}`);
+    }
+    return resolveRefs(raw, raw);
+}
+// ─── $ref resolver ────────────────────────────────────────────────────────────
+/**
+ * Recursively walk the document and replace every { $ref: '#/...' } with the
+ * referenced value (deep-cloned to avoid circular references).
+ * Only local JSON Pointer refs (#/...) are supported.
+ */
+function resolveRefs(node, root, visited = new Set()) {
+    if (node === null || typeof node !== 'object') {
+        return node;
+    }
+    if (Array.isArray(node)) {
+        return node.map((item) => resolveRefs(item, root, visited));
+    }
+    const obj = node;
+    if (typeof obj['$ref'] === 'string') {
+        const ref = obj['$ref'];
+        if (visited.has(ref)) {
+            // Circular ref protection — return empty object rather than infinite loop
+            return {};
+        }
+        const resolved = resolvePointer(root, ref);
+        const newVisited = new Set(visited);
+        newVisited.add(ref);
+        return resolveRefs(resolved, root, newVisited);
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        result[key] = resolveRefs(value, root, visited);
+    }
+    return result;
+}
+/**
+ * Resolve a JSON Pointer like '#/components/schemas/Pet' against the root doc.
+ */
+function resolvePointer(root, ref) {
+    if (!ref.startsWith('#/')) {
+        throw new Error(`Only local $ref values are supported (got: ${ref})`);
+    }
+    const parts = ref
+        .slice(2)
+        .split('/')
+        .map((p) => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+    let current = root;
+    for (const part of parts) {
+        if (current === null || typeof current !== 'object' || !(part in current)) {
+            throw new Error(`Cannot resolve $ref: ${ref}`);
+        }
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Resolve a single inline schema that may still have $ref (convenience helper
+ * used by other modules that receive already-partially-resolved specs).
+ */
+export function resolveSchema(schema, root) {
+    return resolveRefs(schema, root);
+}

package/dist/generators/components/schema-analyzer/resource-grouper.d.ts

@@ -0,0 +1,6 @@
+import type { OpenApiSpec, ResourceMap } from './types.js';
+/**
+ * Parse the entire OpenAPI spec and produce one ResourceInfo per resource.
+ * A resource is a group of endpoints that share the same tag (or path prefix).
+ */
+export declare function buildResourceMap(spec: OpenApiSpec): ResourceMap;

package/dist/generators/components/schema-analyzer/resource-grouper.js

@@ -0,0 +1,132 @@
+import { pascalCase, camelCase } from 'change-case';
+import { extractEndpoints } from './intent-detector.js';
+import { mapFieldsFromSchema, buildZodSchema, mapColumnsFromSchema, } from './schema-field-mapper.js';
+// ─── Naming helpers ───────────────────────────────────────────────────────────
+/**
+ * Derive a plural connector composable name from a tag.
+ * 'pet' → 'usePetsConnector'
+ * 'store' → 'useStoreConnector'   (already ends in e, avoid double-s)
+ */
+function toConnectorName(tag) {
+    const pascal = pascalCase(tag);
+    // Simple English plural: if ends in 's', 'x', 'z', 'ch', 'sh' → +es
+    // otherwise → +s. Good enough for API resource names.
+    const plural = /(?:s|x|z|ch|sh)$/i.test(pascal) ? `${pascal}es` : `${pascal}s`;
+    return `use${plural}Connector`;
+}
+/**
+ * Primary grouping key for an endpoint: first tag, or path prefix as fallback.
+ * '/pets/{id}' → 'pets'
+ */
+function tagOrPrefix(endpoint) {
+    if (endpoint.tags.length > 0) {
+        return endpoint.tags[0];
+    }
+    // Path prefix: first non-empty segment, lower-cased
+    const segment = endpoint.path.split('/').find((s) => s && !s.startsWith('{'));
+    return segment ?? 'unknown';
+}
+// ─── Pick the "best" endpoint for each intent ─────────────────────────────────
+/**
+ * When a resource has multiple endpoints with the same intent, pick the
+ * simplest one (fewest path params, then shortest path).
+ *
+ * Example: if both GET /pets and GET /users/{id}/pets detect as 'list',
+ * we prefer GET /pets (0 path params, shorter path).
+ */
+function pickBest(endpoints) {
+    return endpoints.sort((a, b) => a.pathParams.length - b.pathParams.length || a.path.length - b.path.length)[0];
+}
+// ─── Main grouper ─────────────────────────────────────────────────────────────
+/**
+ * Parse the entire OpenAPI spec and produce one ResourceInfo per resource.
+ * A resource is a group of endpoints that share the same tag (or path prefix).
+ */
+export function buildResourceMap(spec) {
+    // 1. Collect all endpoints
+    const allEndpoints = [];
+    for (const [path, pathItem] of Object.entries(spec.paths)) {
+        // pathItem is already $ref-resolved at this point
+        const endpoints = extractEndpoints(path, pathItem);
+        allEndpoints.push(...endpoints);
+    }
+    // 2. Group by tag / prefix
+    const groups = new Map();
+    for (const ep of allEndpoints) {
+        const key = tagOrPrefix(ep);
+        if (!groups.has(key)) {
+            groups.set(key, []);
+        }
+        groups.get(key).push(ep);
+    }
+    // 3. Build one ResourceInfo per group
+    const resourceMap = new Map();
+    for (const [tag, endpoints] of groups) {
+        const byIntent = groupByIntent(endpoints);
+        const listEp = byIntent.list ? pickBest(byIntent.list) : undefined;
+        const detailEp = byIntent.detail ? pickBest(byIntent.detail) : undefined;
+        const createEp = byIntent.create ? pickBest(byIntent.create) : undefined;
+        const updateEp = byIntent.update ? pickBest(byIntent.update) : undefined;
+        const deleteEp = byIntent.delete ? pickBest(byIntent.delete) : undefined;
+        // Infer columns from list > detail response schema
+        const schemaForColumns = listEp?.responseSchema ?? detailEp?.responseSchema;
+        const columns = schemaForColumns ? mapColumnsFromSchema(schemaForColumns) : [];
+        // Form fields + Zod schemas
+        const createFields = createEp?.requestBodySchema
+            ? mapFieldsFromSchema(createEp.requestBodySchema)
+            : undefined;
+        const updateFields = updateEp?.requestBodySchema
+            ? mapFieldsFromSchema(updateEp.requestBodySchema)
+            : undefined;
+        const createZod = createEp?.requestBodySchema
+            ? buildZodSchema(createEp.requestBodySchema)
+            : undefined;
+        const updateZod = updateEp?.requestBodySchema
+            ? buildZodSchema(updateEp.requestBodySchema)
+            : undefined;
+        const resourceName = pascalCase(tag);
+        const info = {
+            name: resourceName,
+            tag,
+            composableName: toConnectorName(tag),
+            endpoints,
+            listEndpoint: listEp,
+            detailEndpoint: detailEp,
+            createEndpoint: createEp,
+            updateEndpoint: updateEp,
+            deleteEndpoint: deleteEp,
+            columns,
+            formFields: {
+                ...(createFields ? { create: createFields } : {}),
+                ...(updateFields ? { update: updateFields } : {}),
+            },
+            zodSchemas: {
+                ...(createZod ? { create: createZod } : {}),
+                ...(updateZod ? { update: updateZod } : {}),
+            },
+        };
+        // Map key uses camelCase of the tag (e.g. 'petStore') to be a valid JS identifier.
+        // resource.name uses PascalCase ('PetStore') for use in type/class names.
+        // resource.tag preserves the original casing from the spec ('petStore' or 'pet_store').
+        resourceMap.set(camelCase(tag), info);
+    }
+    return resourceMap;
+}
+/**
+ * Group endpoints by their detected intent.
+ * Endpoints with intent 'unknown' (e.g. custom actions like POST /pets/{id}/upload)
+ * are silently skipped — they do not map to a standard CRUD connector.
+ */
+function groupByIntent(endpoints) {
+    const result = {};
+    for (const ep of endpoints) {
+        if (ep.intent === 'unknown') {
+            continue;
+        }
+        if (!result[ep.intent]) {
+            result[ep.intent] = [];
+        }
+        result[ep.intent].push(ep);
+    }
+    return result;
+}

package/dist/generators/components/schema-analyzer/schema-field-mapper.d.ts

@@ -0,0 +1,35 @@
+import type { ColumnDef, FormFieldDef, OpenApiPropertySchema, OpenApiSchema } from './types.js';
+/**
+ * Derive table ColumnDef[] from a response schema (list or detail).
+ * When the response schema is an array, we read the items schema.
+ */
+export declare function mapColumnsFromSchema(schema: OpenApiSchema): ColumnDef[];
+/**
+ * Derive FormFieldDef[] from a request body schema.
+ * readOnly fields are included as hidden: true (developer can override).
+ */
+export declare function mapFieldsFromSchema(schema: OpenApiSchema): FormFieldDef[];
+/**
+ * Generate a Zod expression string for a single OpenAPI property.
+ *
+ * Returns a SOURCE CODE STRING (e.g. 'z.string().min(3)') that will be
+ * embedded inside the generated connector file, not evaluated here.
+ *
+ * Validation constraints (minLength, maximum, enum…) are read directly
+ * from the OpenAPI property schema and chained onto the Zod expression.
+ */
+export declare function zodExpressionFromProp(prop: OpenApiPropertySchema, isRequired: boolean): string;
+/**
+ * Build a complete z.object({...}) string from a request body schema.
+ *
+ * ⚠️  This returns a SOURCE CODE STRING, not a real Zod object.
+ * It is embedded verbatim inside the generated connector file so that
+ * the user's project (which has zod installed) can evaluate it at runtime.
+ *
+ * Example output:
+ *   z.object({
+ *     name: z.string().min(1),
+ *     status: z.enum(['available','pending','sold']).optional(),
+ *   })
+ */
+export declare function buildZodSchema(schema: OpenApiSchema): string;

package/dist/generators/components/schema-analyzer/schema-field-mapper.js

@@ -0,0 +1,220 @@
+import { pascalCase } from 'change-case';
+// ─── Column mapping ───────────────────────────────────────────────────────────
+/**
+ * Derive table ColumnDef[] from a response schema (list or detail).
+ * When the response schema is an array, we read the items schema.
+ */
+export function mapColumnsFromSchema(schema) {
+    // If the response is an array, inspect the items object schema
+    const objectSchema = schema.type === 'array' && schema.items ? schema.items : schema;
+    if (!objectSchema.properties) {
+        return [];
+    }
+    return Object.entries(objectSchema.properties).map(([key, prop]) => ({
+        key,
+        label: pascalCase(key)
+            .replace(/([A-Z])/g, ' $1')
+            .trim(),
+        type: columnTypeFromProp(prop),
+    }));
+}
+function columnTypeFromProp(prop) {
+    if (prop.enum) {
+        return 'badge';
+    }
+    if (prop.type === 'boolean') {
+        return 'boolean';
+    }
+    if (prop.type === 'integer' || prop.type === 'number') {
+        return 'number';
+    }
+    if (prop.format === 'date' || prop.format === 'date-time') {
+        return 'date';
+    }
+    return 'text';
+}
+// ─── Form field mapping ───────────────────────────────────────────────────────
+/**
+ * Derive FormFieldDef[] from a request body schema.
+ * readOnly fields are included as hidden: true (developer can override).
+ */
+export function mapFieldsFromSchema(schema) {
+    if (!schema.properties) {
+        return [];
+    }
+    const required = new Set(schema.required ?? []);
+    return Object.entries(schema.properties).map(([key, prop]) => {
+        const isRequired = required.has(key);
+        const fieldType = fieldTypeFromProp(prop);
+        return {
+            key,
+            label: labelFromKey(key),
+            type: fieldType,
+            required: isRequired,
+            hidden: prop.readOnly === true,
+            options: optionsFromProp(prop),
+            placeholder: undefined,
+            zodExpression: zodExpressionFromProp(prop, isRequired),
+        };
+    });
+}
+function labelFromKey(key) {
+    // Split camelCase/PascalCase into words and capitalise the first letter.
+    // 'photoUrls' → 'Photo Urls',  'firstName' → 'First Name'
+    return key
+        .replace(/([A-Z])/g, ' $1')
+        .replace(/^./, (c) => c.toUpperCase())
+        .trim();
+}
+function fieldTypeFromProp(prop) {
+    if (prop.readOnly) {
+        return 'input'; // will be hidden anyway
+    }
+    if (prop.enum) {
+        return 'select';
+    }
+    if (prop.type === 'boolean') {
+        return 'checkbox';
+    }
+    if (prop.type === 'integer' || prop.type === 'number') {
+        return 'number';
+    }
+    if (prop.type === 'string') {
+        if (prop.format === 'date' || prop.format === 'date-time') {
+            return 'datepicker';
+        }
+        if (typeof prop.maxLength === 'number' && prop.maxLength > 200) {
+            return 'textarea';
+        }
+        return 'input';
+    }
+    // array, object → input as fallback
+    return 'input';
+}
+function optionsFromProp(prop) {
+    if (!prop.enum) {
+        return undefined;
+    }
+    return prop.enum.map((v) => ({ label: String(v), value: v }));
+}
+// ─── Zod expression generation ────────────────────────────────────────────────
+/**
+ * Generate a Zod expression string for a single OpenAPI property.
+ *
+ * Returns a SOURCE CODE STRING (e.g. 'z.string().min(3)') that will be
+ * embedded inside the generated connector file, not evaluated here.
+ *
+ * Validation constraints (minLength, maximum, enum…) are read directly
+ * from the OpenAPI property schema and chained onto the Zod expression.
+ */
+export function zodExpressionFromProp(prop, isRequired) {
+    let expr = baseZodExpr(prop);
+    if (!isRequired) {
+        expr += '.optional()';
+    }
+    return expr;
+}
+function baseZodExpr(prop) {
+    // Enum
+    if (prop.enum && prop.enum.length > 0) {
+        const values = prop.enum.map((v) => JSON.stringify(v)).join(', ');
+        return `z.enum([${values}])`;
+    }
+    switch (prop.type) {
+        case 'string':
+            return stringZodExpr(prop);
+        case 'integer':
+            return integerZodExpr(prop);
+        case 'number':
+            return numberZodExpr(prop);
+        case 'boolean':
+            return 'z.boolean()';
+        case 'array':
+            return arrayZodExpr(prop);
+        case 'object':
+            return 'z.record(z.unknown())';
+        default:
+            // $ref already resolved, unknown type → permissive
+            return 'z.unknown()';
+    }
+}
+function stringZodExpr(prop) {
+    const expr = 'z.string()';
+    if (prop.format === 'email') {
+        return `${expr}.email()`;
+    }
+    if (prop.format === 'uri' || prop.format === 'url') {
+        return `${expr}.url()`;
+    }
+    if (prop.format === 'uuid') {
+        return `${expr}.uuid()`;
+    }
+    if (prop.format === 'date' || prop.format === 'date-time') {
+        return `${expr}.datetime()`;
+    }
+    let chained = expr;
+    if (typeof prop.minLength === 'number') {
+        chained += `.min(${prop.minLength})`;
+    }
+    if (typeof prop.maxLength === 'number') {
+        chained += `.max(${prop.maxLength})`;
+    }
+    return chained;
+}
+function integerZodExpr(prop) {
+    let expr = 'z.number().int()';
+    if (typeof prop.minimum === 'number') {
+        expr += `.min(${prop.minimum})`;
+    }
+    if (typeof prop.maximum === 'number') {
+        expr += `.max(${prop.maximum})`;
+    }
+    return expr;
+}
+function numberZodExpr(prop) {
+    let expr = 'z.number()';
+    if (typeof prop.minimum === 'number') {
+        expr += `.min(${prop.minimum})`;
+    }
+    if (typeof prop.maximum === 'number') {
+        expr += `.max(${prop.maximum})`;
+    }
+    return expr;
+}
+function arrayZodExpr(prop) {
+    const itemExpr = prop.items ? baseZodExpr(prop.items) : 'z.unknown()';
+    let expr = `z.array(${itemExpr})`;
+    if (typeof prop.minItems === 'number') {
+        expr += `.min(${prop.minItems})`;
+    }
+    if (typeof prop.maxItems === 'number') {
+        expr += `.max(${prop.maxItems})`;
+    }
+    return expr;
+}
+// ─── Full Zod object schema string ───────────────────────────────────────────
+/**
+ * Build a complete z.object({...}) string from a request body schema.
+ *
+ * ⚠️  This returns a SOURCE CODE STRING, not a real Zod object.
+ * It is embedded verbatim inside the generated connector file so that
+ * the user's project (which has zod installed) can evaluate it at runtime.
+ *
+ * Example output:
+ *   z.object({
+ *     name: z.string().min(1),
+ *     status: z.enum(['available','pending','sold']).optional(),
+ *   })
+ */
+export function buildZodSchema(schema) {
+    if (!schema.properties) {
+        return 'z.object({})';
+    }
+    const required = new Set(schema.required ?? []);
+    const lines = Object.entries(schema.properties).map(([key, prop]) => {
+        const expr = zodExpressionFromProp(prop, required.has(key));
+        const readOnly = prop.readOnly ? ' // readOnly — excluded from form' : '';
+        return `  ${key}: ${expr},${readOnly}`;
+    });
+    return `z.object({\n${lines.join('\n')}\n})`;
+}

package/dist/generators/components/schema-analyzer/types.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Types for the Schema Analyzer — Fase 1 of the Connector Generator.
+ *
+ * The Schema Analyzer reads an OpenAPI YAML/JSON spec directly and produces
+ * a ResourceMap: one ResourceInfo per tag/path-prefix group of endpoints.
+ */
+export type Intent = 'list' | 'detail' | 'create' | 'update' | 'delete' | 'unknown';
+export interface OpenApiPropertySchema {
+    type?: string;
+    format?: string;
+    enum?: string[];
+    items?: OpenApiPropertySchema;
+    $ref?: string;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+    properties?: Record<string, OpenApiPropertySchema>;
+    required?: string[];
+    description?: string;
+    example?: unknown;
+    additionalProperties?: OpenApiPropertySchema | boolean;
+    allOf?: OpenApiPropertySchema[];
+    oneOf?: OpenApiPropertySchema[];
+    anyOf?: OpenApiPropertySchema[];
+}
+export interface OpenApiSchema extends OpenApiPropertySchema {
+    required?: string[];
+    properties?: Record<string, OpenApiPropertySchema>;
+}
+export interface OpenApiParameter {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    required?: boolean;
+    schema?: OpenApiPropertySchema;
+    description?: string;
+}
+export interface OpenApiOperation {
+    operationId?: string;
+    tags?: string[];
+    summary?: string;
+    description?: string;
+    parameters?: OpenApiParameter[];
+    requestBody?: {
+        required?: boolean;
+        content?: Record<string, {
+            schema?: OpenApiPropertySchema;
+        }>;
+    };
+    responses?: Record<string, {
+        description?: string;
+        content?: Record<string, {
+            schema?: OpenApiPropertySchema;
+        }>;
+    }>;
+    /** Developer override — detected intent for this endpoint */
+    'x-nxh-intent'?: Intent;
+}
+export interface OpenApiPathItem {
+    get?: OpenApiOperation;
+    post?: OpenApiOperation;
+    put?: OpenApiOperation;
+    patch?: OpenApiOperation;
+    delete?: OpenApiOperation;
+}
+export interface OpenApiSpec {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+    };
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    paths: Record<string, OpenApiPathItem>;
+    components?: {
+        schemas?: Record<string, OpenApiPropertySchema>;
+    };
+}
+export interface EndpointInfo {
+    operationId: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    tags: string[];
+    summary?: string;
+    description?: string;
+    intent: Intent;
+    /** Resolved (no $ref) request body schema for POST/PUT/PATCH */
+    requestBodySchema?: OpenApiSchema;
+    /** Resolved (no $ref) successful response schema (first 2xx) */
+    responseSchema?: OpenApiSchema;
+    hasPathParams: boolean;
+    pathParams: string[];
+}
+export type FieldType = 'input' | 'textarea' | 'select' | 'checkbox' | 'datepicker' | 'number';
+export interface FormFieldDef {
+    key: string;
+    label: string;
+    type: FieldType;
+    required: boolean;
+    options?: {
+        label: string;
+        value: string;
+    }[];
+    placeholder?: string;
+    hidden?: boolean;
+    /** Zod expression string, e.g. 'z.string().min(1)' */
+    zodExpression: string;
+}
+export type ColumnType = 'text' | 'number' | 'date' | 'boolean' | 'badge';
+export interface ColumnDef {
+    key: string;
+    label: string;
+    type: ColumnType;
+}
+export interface ResourceInfo {
+    /** Normalized resource name, PascalCase. E.g. 'Pet', 'Store' */
+    name: string;
+    /** Tag name as it appears in the spec. E.g. 'pet', 'store' */
+    tag: string;
+    /** Generated connector composable name. E.g. 'usePetsConnector' */
+    composableName: string;
+    endpoints: EndpointInfo[];
+    /** The one endpoint detected as list (GET array) */
+    listEndpoint?: EndpointInfo;
+    /** The one endpoint detected as detail (GET single object) */
+    detailEndpoint?: EndpointInfo;
+    /** The one endpoint detected as create (POST) */
+    createEndpoint?: EndpointInfo;
+    /** The one endpoint detected as update (PUT/PATCH) */
+    updateEndpoint?: EndpointInfo;
+    /** The one endpoint detected as delete (DELETE) */
+    deleteEndpoint?: EndpointInfo;
+    /** Columns inferred from the list/detail response schema */
+    columns: ColumnDef[];
+    /** Form fields inferred from the request body schema */
+    formFields: {
+        create?: FormFieldDef[];
+        update?: FormFieldDef[];
+    };
+    /**
+     * Zod schema object expression strings, ready to embed in generated code.
+     * E.g. "z.object({\n  name: z.string().min(1),\n  ....\n})"
+     */
+    zodSchemas: {
+        create?: string;
+        update?: string;
+    };
+}
+/** One entry per tag (or path-prefix fallback) */
+export type ResourceMap = Map<string, ResourceInfo>;

package/dist/generators/components/schema-analyzer/types.js

@@ -0,0 +1,7 @@
+/**
+ * Types for the Schema Analyzer — Fase 1 of the Connector Generator.
+ *
+ * The Schema Analyzer reads an OpenAPI YAML/JSON spec directly and produces
+ * a ResourceMap: one ResourceInfo per tag/path-prefix group of endpoints.
+ */
+export {};

package/dist/generators/nuxt-server/generator.d.ts

@@ -1,7 +1,8 @@
+import { type Logger } from '../../cli/logger.js';
 /**
  * Main function to generate Nuxt Server Routes
  */
 export declare function generateNuxtServerRoutes(inputDir: string, serverRoutePath: string, options?: {
     enableBff?: boolean;
     backend?: string;
-}): Promise<void>;
+}, logger?: Logger): Promise<void>;