openapi-remote-codegen 0.1.0

package/dist/parser.js

@@ -0,0 +1,236 @@
+export function parseOpenApiSpec(spec) {
+    const operations = [];
+    const tagsSet = new Set();
+    for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {
+        if (!pathItem)
+            continue;
+        const methods = ['get', 'post', 'put', 'patch', 'delete'];
+        for (const method of methods) {
+            const operation = pathItem[method];
+            if (!operation)
+                continue;
+            const remoteType = operation['x-remote-type'];
+            if (!remoteType)
+                continue;
+            const tag = operation.tags?.[0] ?? 'Default';
+            tagsSet.add(tag);
+            const invalidates = operation['x-remote-invalidates'] ?? [];
+            const parameters = parseParameters(operation.parameters ?? [], pathItem.parameters ?? [], spec.components);
+            const requestBodyResult = parseRequestBody(operation.requestBody);
+            const requestBodySchema = requestBodyResult?.schema;
+            const isArrayBody = requestBodyResult?.isArray ?? false;
+            // Check success response codes in priority order (200, 201, 202)
+            const responseSchema = parseResponse(operation.responses?.['200']) ??
+                parseResponse(operation.responses?.['201']) ??
+                parseResponse(operation.responses?.['202']);
+            // Detect void response: commands with no JSON response body (204 No Content, or 200 with no body)
+            const isVoidResponse = !responseSchema && (remoteType === 'command' || remoteType === 'form');
+            const isBatch = remoteType === 'query' && (operation['x-remote-batch'] === true);
+            operations.push({
+                operationId: operation.operationId ?? `${method}_${path}`,
+                tag,
+                method,
+                path,
+                remoteType,
+                invalidates,
+                parameters,
+                requestBodySchema,
+                requestBodyRequired: requestBodyResult?.required,
+                isArrayBody,
+                inlineRequestBody: requestBodyResult?.inline,
+                responseSchema,
+                isVoidResponse,
+                isBatch,
+                summary: operation.summary,
+                clientPropertyName: operation['x-client-property'],
+            });
+        }
+    }
+    return {
+        operations,
+        tags: Array.from(tagsSet),
+    };
+}
+function parseParameters(opParams, pathParams, components) {
+    const allParams = [...pathParams, ...opParams];
+    const result = [];
+    for (const param of allParams) {
+        if ('$ref' in param)
+            continue;
+        const schema = param.schema;
+        const resolved = resolveSchema(schema, components);
+        const paramInfo = {
+            name: param.name,
+            in: param.in,
+            required: param.required ?? false,
+            type: getSchemaType(resolved),
+        };
+        // Check if the resolved schema is an enum
+        if (resolved?.enum) {
+            const enumName = findEnumName(schema, components);
+            if (enumName) {
+                paramInfo.enumName = enumName;
+            }
+        }
+        // For array parameters, capture the item type
+        if (resolved?.type === 'array' && resolved.items) {
+            const itemSchema = resolveSchema(resolved.items, components);
+            paramInfo.itemType = getSchemaType(itemSchema);
+        }
+        result.push(paramInfo);
+    }
+    return result;
+}
+/**
+ * Resolve a schema through $ref and oneOf to get the underlying schema object.
+ */
+function resolveSchema(schema, components) {
+    if (!schema)
+        return undefined;
+    if ('$ref' in schema) {
+        const refName = schema.$ref.split('/').pop();
+        if (refName && components?.schemas?.[refName]) {
+            return components.schemas[refName];
+        }
+        return undefined;
+    }
+    // Handle oneOf wrapping (NSwag nullable enums)
+    const schemaObj = schema;
+    if (schemaObj.oneOf) {
+        for (const item of schemaObj.oneOf) {
+            const resolved = resolveSchema(item, components);
+            if (resolved?.type || resolved?.enum)
+                return resolved;
+        }
+    }
+    return schemaObj;
+}
+/**
+ * Find the enum type name from a schema that may be wrapped in oneOf/$ref.
+ */
+function findEnumName(schema, components) {
+    if (!schema)
+        return undefined;
+    if ('$ref' in schema) {
+        const refName = schema.$ref.split('/').pop();
+        if (refName && components?.schemas?.[refName]) {
+            const resolved = components.schemas[refName];
+            if (resolved.enum)
+                return refName;
+        }
+        return undefined;
+    }
+    const schemaObj = schema;
+    if (schemaObj.oneOf) {
+        for (const item of schemaObj.oneOf) {
+            const name = findEnumName(item, components);
+            if (name)
+                return name;
+        }
+    }
+    return undefined;
+}
+function parseRequestBody(body) {
+    if (!body?.content?.['application/json']?.schema)
+        return undefined;
+    const required = body.required ?? false;
+    const schema = body.content['application/json'].schema;
+    if ('$ref' in schema) {
+        const refName = schema.$ref.split('/').pop();
+        return refName ? { schema: `${refName}Schema`, isArray: false, required } : undefined;
+    }
+    // Handle array request bodies (e.g., Treatment[])
+    const schemaObj = schema;
+    if (schemaObj.type === 'array' && schemaObj.items) {
+        const items = schemaObj.items;
+        if ('$ref' in items) {
+            const itemName = items.$ref.split('/').pop();
+            return itemName ? { schema: `${itemName}Schema`, isArray: true, required } : undefined;
+        }
+    }
+    // Handle inline object schemas (e.g., Dictionary<string, string> -> { type: "object", additionalProperties: ... })
+    if (schemaObj.type === 'object' && schemaObj.additionalProperties) {
+        const inline = resolveInlineObjectSchema(schemaObj);
+        if (inline) {
+            return { schema: '', isArray: false, required, inline };
+        }
+    }
+    return undefined;
+}
+/**
+ * Convert an inline OpenAPI object schema with additionalProperties to a Zod schema and TS type.
+ * Handles Dictionary<TKey, TValue> patterns from C#.
+ */
+function resolveInlineObjectSchema(schema) {
+    const additionalProps = schema.additionalProperties;
+    if (!additionalProps || additionalProps === true) {
+        // additionalProperties: true or {} -> Record<string, unknown>
+        return {
+            zodSchema: 'z.record(z.string(), z.unknown())',
+            tsType: '{ [key: string]: any; }',
+        };
+    }
+    if (typeof additionalProps === 'object' && !('$ref' in additionalProps)) {
+        const valueSchema = additionalProps;
+        switch (valueSchema.type) {
+            case 'string':
+                return {
+                    zodSchema: 'z.record(z.string(), z.string())',
+                    tsType: '{ [key: string]: string; }',
+                };
+            case 'number':
+            case 'integer':
+                return {
+                    zodSchema: 'z.record(z.string(), z.number())',
+                    tsType: '{ [key: string]: number; }',
+                };
+            case 'boolean':
+                return {
+                    zodSchema: 'z.record(z.string(), z.boolean())',
+                    tsType: '{ [key: string]: boolean; }',
+                };
+            default:
+                return {
+                    zodSchema: 'z.record(z.string(), z.unknown())',
+                    tsType: '{ [key: string]: any; }',
+                };
+        }
+    }
+    return undefined;
+}
+function parseResponse(response) {
+    if (!response?.content?.['application/json']?.schema)
+        return undefined;
+    const schema = response.content['application/json'].schema;
+    if ('$ref' in schema) {
+        return schema.$ref.split('/').pop();
+    }
+    // Handle array responses (e.g., TrackerDefinitionDto[])
+    const schemaObj = schema;
+    if (schemaObj.type === 'array' && schemaObj.items) {
+        const items = schemaObj.items;
+        if ('$ref' in items) {
+            const itemName = items.$ref.split('/').pop();
+            return itemName ? `${itemName}[]` : undefined;
+        }
+    }
+    return undefined;
+}
+function getSchemaType(schema) {
+    if (!schema)
+        return 'unknown';
+    if (schema.type === 'string') {
+        if (schema.format === 'uuid')
+            return 'string';
+        if (schema.format === 'date-time')
+            return 'Date';
+        return 'string';
+    }
+    if (schema.type === 'integer' || schema.type === 'number')
+        return 'number';
+    if (schema.type === 'boolean')
+        return 'boolean';
+    if (schema.type === 'array')
+        return 'array';
+    return 'unknown';
+}

package/dist/public.d.ts

@@ -0,0 +1,6 @@
+export { defineConfig, resolveConfig } from './config.js';
+export type { GeneratorConfig, UserConfig, ImportPaths, ErrorHandling } from './config.js';
+export { parseOpenApiSpec } from './parser.js';
+export type { ParsedSpec, OperationInfo, ParameterInfo, RemoteType, InlineRequestBody } from './types.js';
+export { generateRemoteFunctions } from './generators/remote-functions.js';
+export { generateApiClient } from './generators/api-client.js';

package/dist/public.js

@@ -0,0 +1,5 @@
+// Public API for openapi-remote-codegen
+export { defineConfig, resolveConfig } from './config.js';
+export { parseOpenApiSpec } from './parser.js';
+export { generateRemoteFunctions } from './generators/remote-functions.js';
+export { generateApiClient } from './generators/api-client.js';

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+export type RemoteType = 'query' | 'command' | 'form';
+export interface ParameterInfo {
+    name: string;
+    in: 'query' | 'path' | 'header';
+    required: boolean;
+    type: string;
+    enumName?: string;
+    /** For array-type parameters, the type of each item (e.g., 'string', 'number') */
+    itemType?: string;
+}
+/**
+ * Represents an inline request body that doesn't have a named $ref schema.
+ * Used for types like Dictionary<string, string> which become { type: "object", additionalProperties: ... }.
+ */
+export interface InlineRequestBody {
+    /** Zod schema expression (e.g., "z.record(z.string(), z.string())") */
+    zodSchema: string;
+    /** TypeScript type for the NSwag client cast (e.g., "{ [key: string]: string; }") */
+    tsType: string;
+}
+export interface OperationInfo {
+    operationId: string;
+    tag: string;
+    method: string;
+    path: string;
+    remoteType: RemoteType;
+    invalidates: string[];
+    parameters: ParameterInfo[];
+    requestBodySchema?: string;
+    requestBodyRequired?: boolean;
+    isArrayBody?: boolean;
+    /** Inline request body for schemas that don't have a named $ref (e.g., Dictionary<string, string>) */
+    inlineRequestBody?: InlineRequestBody;
+    responseSchema?: string;
+    isVoidResponse: boolean;
+    /** Whether this query should use query.batch() for N+1 prevention */
+    isBatch?: boolean;
+    summary?: string;
+    clientPropertyName?: string;
+}
+export interface ParsedSpec {
+    operations: OperationInfo[];
+    tags: string[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/client-mapping.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Get the apiClient property name for an OpenAPI tag using camelCase fallback.
+ * Strips version prefixes (e.g., "V4 Trackers" -> "Trackers") and converts to camelCase.
+ * Used as fallback when no [ClientPropertyName] attribute is set on the controller.
+ */
+export declare function getClientPropertyName(tag: string): string;

package/dist/utils/client-mapping.js

@@ -0,0 +1,9 @@
+/**
+ * Get the apiClient property name for an OpenAPI tag using camelCase fallback.
+ * Strips version prefixes (e.g., "V4 Trackers" -> "Trackers") and converts to camelCase.
+ * Used as fallback when no [ClientPropertyName] attribute is set on the controller.
+ */
+export function getClientPropertyName(tag) {
+    const cleaned = tag.replace(/^V\d+\s*/i, '').replace(/\s+/g, '');
+    return cleaned.charAt(0).toLowerCase() + cleaned.slice(1);
+}

package/dist/utils/naming.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Convert operationId to function name.
+ * "Note_GetNotes" -> "getNotes"
+ * "Note_CreateNote" -> "createNote"
+ * "ClockFaces_Delete" -> "remove" (reserved keyword handling)
+ */
+export declare function operationIdToFunctionName(operationId: string): string;
+/**
+ * Convert tag to camelCase file name with proper pluralization.
+ * "Note" -> "notes"
+ * "V4 Notes" -> "notes"
+ * "V4 Compression Lows" -> "compressionLows"
+ * "V1 Connector Status" -> "connectorStatus"
+ * "Battery" -> "batteries"
+ */
+export declare function tagToFileName(tag: string): string;
+/**
+ * Resolve invalidation targets.
+ * Short names resolve within same tag, full operationIds are used as-is.
+ * "GetNotes" with currentTag "Note" -> "getNotes"
+ * "Trackers_GetActiveInstances" -> "getActiveInstances" (from trackers)
+ */
+export declare function resolveInvalidation(invalidate: string, currentTag: string): {
+    functionName: string;
+    fromTag: string;
+};

package/dist/utils/naming.js

@@ -0,0 +1,89 @@
+/**
+ * JavaScript reserved keywords that cannot be used as export names.
+ * Maps known API method names to safe alternatives.
+ */
+const RESERVED_KEYWORD_MAP = {
+    delete: 'remove',
+};
+const JS_RESERVED_KEYWORDS = new Set([
+    'delete', 'new', 'return', 'switch', 'throw', 'try', 'catch', 'finally',
+    'class', 'const', 'let', 'var', 'function', 'import', 'export', 'default',
+    'void', 'typeof', 'instanceof', 'in', 'of', 'if', 'else', 'for', 'while',
+    'do', 'break', 'continue', 'with', 'yield', 'await', 'async', 'super',
+    'this', 'null', 'undefined', 'true', 'false', 'enum', 'implements',
+    'interface', 'package', 'private', 'protected', 'public', 'static',
+]);
+/**
+ * Ensure a function name is not a JavaScript reserved keyword.
+ * Uses explicit mapping for common cases (delete -> remove),
+ * falls back to underscore prefix for others.
+ */
+function safeExportName(name) {
+    if (!JS_RESERVED_KEYWORDS.has(name))
+        return name;
+    return RESERVED_KEYWORD_MAP[name] ?? `_${name}`;
+}
+/**
+ * Convert operationId to function name.
+ * "Note_GetNotes" -> "getNotes"
+ * "Note_CreateNote" -> "createNote"
+ * "ClockFaces_Delete" -> "remove" (reserved keyword handling)
+ */
+export function operationIdToFunctionName(operationId) {
+    const parts = operationId.split('_');
+    const name = parts.length > 1 ? parts.slice(1).join('_') : parts[0];
+    const functionName = name.charAt(0).toLowerCase() + name.slice(1);
+    return safeExportName(functionName);
+}
+/**
+ * Pluralize a single word.
+ */
+function pluralize(word) {
+    const lower = word.toLowerCase();
+    if (lower.endsWith('s'))
+        return lower;
+    if (lower.endsWith('y') && !/[aeiou]y$/.test(lower)) {
+        return lower.slice(0, -1) + 'ies';
+    }
+    if (/(?:sh|ch|x|z)$/.test(lower)) {
+        return lower + 'es';
+    }
+    return lower + 's';
+}
+/**
+ * Convert tag to camelCase file name with proper pluralization.
+ * "Note" -> "notes"
+ * "V4 Notes" -> "notes"
+ * "V4 Compression Lows" -> "compressionLows"
+ * "V1 Connector Status" -> "connectorStatus"
+ * "Battery" -> "batteries"
+ */
+export function tagToFileName(tag) {
+    const cleaned = tag.replace(/^V\d+\s*/i, '').trim();
+    const words = cleaned.split(/\s+/);
+    // Pluralize the last word
+    const lastWord = pluralize(words[words.length - 1]);
+    const prefix = words.slice(0, -1);
+    // Build camelCase: first word lowercase, rest capitalized
+    const parts = [...prefix.map(w => w.toLowerCase()), lastWord];
+    return parts[0] + parts.slice(1).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+}
+/**
+ * Resolve invalidation targets.
+ * Short names resolve within same tag, full operationIds are used as-is.
+ * "GetNotes" with currentTag "Note" -> "getNotes"
+ * "Trackers_GetActiveInstances" -> "getActiveInstances" (from trackers)
+ */
+export function resolveInvalidation(invalidate, currentTag) {
+    if (invalidate.includes('_')) {
+        const [tag, ...rest] = invalidate.split('_');
+        return {
+            functionName: operationIdToFunctionName(invalidate),
+            fromTag: tag,
+        };
+    }
+    return {
+        functionName: invalidate.charAt(0).toLowerCase() + invalidate.slice(1),
+        fromTag: currentTag,
+    };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "openapi-remote-codegen",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Generate type-safe SvelteKit remote functions from OpenAPI specs with x-remote-* extensions",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "openapi-remote-codegen": "dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/public.d.ts",
+      "import": "./dist/public.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": ["openapi", "sveltekit", "remote-functions", "codegen", "typescript"],
+  "license": "MIT",
+  "dependencies": {
+    "openapi-types": "^12.1.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.0.0"
+  }
+}

package/src/__tests__/client-mapping.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest';
+import { getClientPropertyName } from '../utils/client-mapping.js';
+
+describe('getClientPropertyName', () => {
+  it('maps standard tags to camelCase', () => {
+    expect(getClientPropertyName('Trackers')).toBe('trackers');
+    expect(getClientPropertyName('Entries')).toBe('entries');
+    expect(getClientPropertyName('Treatments')).toBe('treatments');
+    expect(getClientPropertyName('StateSpans')).toBe('stateSpans');
+  });
+
+  it('strips version prefix and camelCases', () => {
+    expect(getClientPropertyName('V4 Trackers')).toBe('trackers');
+    expect(getClientPropertyName('V2 Notifications')).toBe('notifications');
+    expect(getClientPropertyName('V1 Entries')).toBe('entries');
+  });
+
+  it('strips spaces from multi-word tags', () => {
+    expect(getClientPropertyName('Loop Notifications')).toBe('loopNotifications');
+    expect(getClientPropertyName('Chart Data')).toBe('chartData');
+    expect(getClientPropertyName('V4 Device Age')).toBe('deviceAge');
+    expect(getClientPropertyName('V4 Connector Settings')).toBe('connectorSettings');
+  });
+
+  it('applies pure camelCase without overrides', () => {
+    // These tags now rely on [ClientPropertyName] for non-standard names
+    expect(getClientPropertyName('Foods')).toBe('foods');
+    expect(getClientPropertyName('DData')).toBe('dData');
+    expect(getClientPropertyName('Prediction')).toBe('prediction');
+    expect(getClientPropertyName('IOB')).toBe('iOB');
+    expect(getClientPropertyName('UI Settings')).toBe('uISettings');
+  });
+
+  it('falls back to camelCase for unknown tags', () => {
+    expect(getClientPropertyName('NewFeature')).toBe('newFeature');
+    expect(getClientPropertyName('SomeThing')).toBe('someThing');
+  });
+});

package/src/__tests__/config.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { defineConfig, resolveConfig } from '../config.js';
+
+describe('defineConfig', () => {
+  it('returns the config object as-is (identity helper for type inference)', () => {
+    const config = defineConfig({ openApiPath: './spec.json' });
+    expect(config.openApiPath).toBe('./spec.json');
+  });
+});
+
+describe('resolveConfig', () => {
+  it('fills in all defaults when given empty partial', () => {
+    const config = resolveConfig({});
+    expect(config.openApiPath).toBe('./openapi.json');
+    expect(config.outputDir).toBe('./src/lib');
+    expect(config.remoteFunctionsOutput).toBe('api/generated');
+    expect(config.apiClientOutput).toBe('api/api-client.generated.ts');
+    expect(config.imports.server).toBe('$app/server');
+    expect(config.imports.kit).toBe('@sveltejs/kit');
+    expect(config.imports.schemas).toBe('$lib/api/generated/schemas');
+    expect(config.imports.apiTypes).toBe('$api');
+    expect(config.imports.zod).toBe('zod');
+    expect(config.clientAccess).toBe('getRequestEvent().locals.apiClient');
+    expect(config.nswagClientPath).toBe('./generated/api-client');
+  });
+
+  it('merges partial imports with defaults', () => {
+    const config = resolveConfig({
+      imports: { schemas: '$lib/schemas' },
+    });
+    expect(config.imports.schemas).toBe('$lib/schemas');
+    expect(config.imports.server).toBe('$app/server');
+  });
+
+  it('provides default error handling functions', () => {
+    const config = resolveConfig({});
+    expect(config.errorHandling.on401).toContain('redirect');
+    expect(config.errorHandling.on403).toContain('Forbidden');
+    expect(typeof config.errorHandling.on500).toBe('function');
+    expect(config.errorHandling.on500('doThing')).toContain('doThing');
+  });
+
+  it('allows overriding error handling', () => {
+    const config = resolveConfig({
+      errorHandling: {
+        on401: 'throw error(401, "Unauthorized")',
+        on403: 'throw error(403, "Nope")',
+        on500: (fn) => `throw error(500, "${fn} failed")`,
+      },
+    });
+    expect(config.errorHandling.on401).toBe('throw error(401, "Unauthorized")');
+    expect(config.errorHandling.on500('test')).toBe('throw error(500, "test failed")');
+  });
+
+  it('allows overriding nswagClientPath', () => {
+    const config = resolveConfig({ nswagClientPath: './generated/my-api' });
+    expect(config.nswagClientPath).toBe('./generated/my-api');
+  });
+});

package/src/__tests__/naming.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import { operationIdToFunctionName, tagToFileName, resolveInvalidation } from '../utils/naming.js';
+
+describe('operationIdToFunctionName', () => {
+  it('strips tag prefix and camelCases', () => {
+    expect(operationIdToFunctionName('Trackers_GetDefinitions')).toBe('getDefinitions');
+  });
+
+  it('handles single-segment operationId', () => {
+    expect(operationIdToFunctionName('getDefinitions')).toBe('getDefinitions');
+  });
+
+  it('handles operationId starting with uppercase', () => {
+    expect(operationIdToFunctionName('CreateNote')).toBe('createNote');
+  });
+
+  it('handles multi-underscore operationId', () => {
+    expect(operationIdToFunctionName('Trackers_Get_All')).toBe('get_All');
+  });
+});
+
+describe('tagToFileName', () => {
+  it('lowercases already-plural tag', () => {
+    expect(tagToFileName('Trackers')).toBe('trackers');
+  });
+
+  it('pluralizes singular tag', () => {
+    expect(tagToFileName('Note')).toBe('notes');
+  });
+
+  it('strips version prefix', () => {
+    expect(tagToFileName('V4 Trackers')).toBe('trackers');
+  });
+
+  it('handles consonant + y -> ies', () => {
+    expect(tagToFileName('Battery')).toBe('batteries');
+  });
+
+  it('handles vowel + y -> ys', () => {
+    expect(tagToFileName('Key')).toBe('keys');
+  });
+
+  it('handles sibilant ending (ch)', () => {
+    expect(tagToFileName('Match')).toBe('matches');
+  });
+
+  it('preserves words already ending in s', () => {
+    expect(tagToFileName('Status')).toBe('status');
+  });
+
+  it('handles sibilant ending (x)', () => {
+    expect(tagToFileName('Box')).toBe('boxes');
+  });
+});
+
+describe('resolveInvalidation', () => {
+  it('resolves simple name within current tag', () => {
+    const result = resolveInvalidation('GetDefinitions', 'Trackers');
+    expect(result.functionName).toBe('getDefinitions');
+    expect(result.fromTag).toBe('Trackers');
+  });
+
+  it('resolves cross-tag operationId', () => {
+    const result = resolveInvalidation('Trackers_GetActiveInstances', 'Notes');
+    expect(result.functionName).toBe('getActiveInstances');
+    expect(result.fromTag).toBe('Trackers');
+  });
+});