@acrool/rtk-query-codegen-openapi 0.0.1

package/src/generators/react-hooks.ts

@@ -0,0 +1,93 @@
+import ts from 'typescript';
+import { getOperationName } from 'oazapfts/generate';
+import { capitalize, isQuery } from '../utils';
+import type { OperationDefinition, EndpointOverrides, ConfigFile } from '../types';
+import { getOverrides } from '../generate';
+import { factory } from '../utils/factory';
+
+type HooksConfigOptions = NonNullable<ConfigFile['hooks']>;
+
+type GetReactHookNameParams = {
+  operationDefinition: OperationDefinition;
+  endpointOverrides: EndpointOverrides[] | undefined;
+  config: HooksConfigOptions;
+};
+
+type CreateBindingParams = {
+  operationDefinition: OperationDefinition;
+  overrides?: EndpointOverrides;
+  isLazy?: boolean;
+};
+
+const createBinding = ({
+  operationDefinition: { verb, path, operation },
+  overrides,
+  isLazy = false,
+}: CreateBindingParams) =>
+  factory.createBindingElement(
+    undefined,
+    undefined,
+    factory.createIdentifier(
+      `use${isLazy ? 'Lazy' : ''}${capitalize(getOperationName(verb, path, operation.operationId))}${
+        isQuery(verb, overrides) ? 'Query' : 'Mutation'
+      }`
+    ),
+    undefined
+  );
+
+const getReactHookName = ({ operationDefinition, endpointOverrides, config }: GetReactHookNameParams) => {
+  const overrides = getOverrides(operationDefinition, endpointOverrides);
+
+  const baseParams = {
+    operationDefinition,
+    overrides,
+  };
+
+  const _isQuery = isQuery(operationDefinition.verb, overrides);
+
+  // If `config` is true, just generate everything
+  if (typeof config === 'boolean') {
+    return createBinding(baseParams);
+  }
+
+  // `config` is an object and we need to check for the configuration of each property
+  if (_isQuery) {
+    return [
+      ...(config.queries ? [createBinding(baseParams)] : []),
+      ...(config.lazyQueries ? [createBinding({ ...baseParams, isLazy: true })] : []),
+    ];
+  }
+
+  return config.mutations ? createBinding(baseParams) : [];
+};
+
+type GenerateReactHooksParams = {
+  exportName: string;
+  operationDefinitions: OperationDefinition[];
+  endpointOverrides: EndpointOverrides[] | undefined;
+  config: HooksConfigOptions;
+};
+export const generateReactHooks = ({
+  exportName,
+  operationDefinitions,
+  endpointOverrides,
+  config,
+}: GenerateReactHooksParams) =>
+  factory.createVariableStatement(
+    [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    factory.createVariableDeclarationList(
+      [
+        factory.createVariableDeclaration(
+          factory.createObjectBindingPattern(
+            operationDefinitions
+              .map((operationDefinition) => getReactHookName({ operationDefinition, endpointOverrides, config }))
+              .flat()
+          ),
+          undefined,
+          undefined,
+          factory.createIdentifier(exportName)
+        ),
+      ],
+      ts.NodeFlags.Const
+    )
+  );

package/src/index.ts

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { generateApi } from './generate';
+import type { CommonOptions, ConfigFile, GenerationOptions, OutputFileOptions } from './types';
+import { isValidUrl, prettify } from './utils';
+export type { ConfigFile } from './types';
+
+const require = createRequire(__filename);
+
+export async function generateEndpoints(options: GenerationOptions): Promise<string | void> {
+  const schemaLocation = options.schemaFile;
+
+  const schemaAbsPath = isValidUrl(options.schemaFile)
+    ? options.schemaFile
+    : path.resolve(process.cwd(), schemaLocation);
+
+  const sourceCode = await enforceOazapftsTsVersion(async () => {
+    return generateApi(schemaAbsPath, options);
+  });
+  const { outputFile, prettierConfigFile } = options;
+  if (outputFile) {
+    fs.writeFileSync(
+      path.resolve(process.cwd(), outputFile),
+      await prettify(outputFile, sourceCode, prettierConfigFile)
+    );
+  } else {
+    return await prettify(null, sourceCode, prettierConfigFile);
+  }
+}
+
+export function parseConfig(fullConfig: ConfigFile) {
+  const outFiles: (CommonOptions & OutputFileOptions)[] = [];
+
+  if ('outputFiles' in fullConfig) {
+    const { outputFiles, ...commonConfig } = fullConfig;
+    for (const [outputFile, specificConfig] of Object.entries(outputFiles)) {
+      outFiles.push({
+        ...commonConfig,
+        ...specificConfig,
+        outputFile,
+      });
+    }
+  } else {
+    outFiles.push(fullConfig);
+  }
+  return outFiles;
+}
+
+/**
+ * Enforces `oazapfts` to use the same TypeScript version as this module itself uses.
+ * That should prevent enums from running out of sync if both libraries use different TS versions.
+ */
+function enforceOazapftsTsVersion<T>(cb: () => T): T {
+  const ozTsPath = require.resolve('typescript', { paths: [require.resolve('oazapfts')] });
+  const tsPath = require.resolve('typescript');
+  const originalEntry = require.cache[ozTsPath];
+  try {
+    require.cache[ozTsPath] = require.cache[tsPath];
+    return cb();
+  } finally {
+    if (originalEntry) {
+      require.cache[ozTsPath] = originalEntry;
+    } else {
+      delete require.cache[ozTsPath];
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,150 @@
+import type SwaggerParser from '@apidevtools/swagger-parser';
+import type { OpenAPIV3 } from 'openapi-types';
+
+export type OperationDefinition = {
+  path: string;
+  verb: (typeof operationKeys)[number];
+  pathItem: OpenAPIV3.PathItemObject;
+  operation: OpenAPIV3.OperationObject;
+};
+
+export type ParameterDefinition = OpenAPIV3.ParameterObject;
+
+type Require<T, K extends keyof T> = { [k in K]-?: NonNullable<T[k]> } & Omit<T, K>;
+type Optional<T, K extends keyof T> = { [k in K]?: NonNullable<T[k]> } & Omit<T, K>;
+type Id<T> = { [K in keyof T]: T[K] } & {};
+type AtLeastOneKey<T> = {
+  [K in keyof T]-?: Pick<T, K> & Partial<T>;
+}[keyof T];
+
+export const operationKeys = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'] as const;
+
+export type GenerationOptions = Id<
+  CommonOptions &
+    Optional<OutputFileOptions, 'outputFile'> & {
+      isDataResponse?(
+        code: string,
+        includeDefault: boolean,
+        response: OpenAPIV3.ResponseObject,
+        allResponses: OpenAPIV3.ResponsesObject
+      ): boolean;
+    }
+>;
+
+export interface CommonOptions {
+  apiFile: string;
+  /**
+   * filename or url
+   */
+  schemaFile: string;
+  /**
+   * defaults to "api"
+   */
+  apiImport?: string;
+  /**
+   * defaults to "enhancedApi"
+   */
+  exportName?: string;
+  /**
+   * defaults to "ApiArg"
+   */
+  argSuffix?: string;
+  /**
+   * defaults to "ApiResponse"
+   */
+  responseSuffix?: string;
+  /**
+   * defaults to empty
+   */
+  operationNameSuffix?: string;
+  /**
+   * defaults to `false`
+   * `true` will generate hooks for queries and mutations, but no lazyQueries
+   */
+  hooks?: boolean | { queries: boolean; lazyQueries: boolean; mutations: boolean };
+  /**
+   * defaults to false
+   * `true` will generate a union type for `undefined` properties like: `{ id?: string | undefined }` instead of `{ id?: string }`
+   */
+  unionUndefined?: boolean;
+  /**
+   * defaults to false
+   * `true` will result in all generated endpoints having `providesTags`/`invalidatesTags` declarations for the `tags` of their respective operation definition
+   * @see https://redux-toolkit.js.org/rtk-query/usage/code-generation for more information
+   */
+  tag?: boolean;
+  /**
+   * defaults to false
+   * `true` will add `encodeURIComponent` to the generated path parameters
+   */
+  encodePathParams?: boolean;
+  /**
+   * defaults to false
+   * `true` will add `encodeURIComponent` to the generated query parameters
+   */
+  encodeQueryParams?: boolean;
+  /**
+   * defaults to false
+   * `true` will "flatten" the arg so that you can do things like `useGetEntityById(1)` instead of `useGetEntityById({ entityId: 1 })`
+   */
+  flattenArg?: boolean;
+  /**
+   * default to false
+   * If set to `true`, the default response type will be included in the generated code for all endpoints.
+   * @see https://swagger.io/docs/specification/describing-responses/#default
+   */
+  includeDefault?: boolean;
+  /**
+   * default to false
+   * `true` will not generate separate types for read-only and write-only properties.
+   */
+  mergeReadWriteOnly?: boolean;
+  /**
+   *
+   * HTTPResolverOptions object that is passed to the SwaggerParser bundle function.
+   */
+  httpResolverOptions?: SwaggerParser.HTTPResolverOptions;
+
+  /**
+   * defaults to undefined
+   * If present the given file will be used as prettier config when formatting the generated code. If undefined the default prettier config
+   * resolution mechanism will be used.
+   */
+  prettierConfigFile?: string;
+}
+
+export type TextMatcher = string | RegExp | (string | RegExp)[];
+
+export type EndpointMatcherFunction = (operationName: string, operationDefinition: OperationDefinition) => boolean;
+
+export type EndpointMatcher = TextMatcher | EndpointMatcherFunction;
+
+export type ParameterMatcherFunction = (parameterName: string, parameterDefinition: ParameterDefinition) => boolean;
+
+export type ParameterMatcher = TextMatcher | ParameterMatcherFunction;
+
+export interface OutputFileOptions extends Partial<CommonOptions> {
+  outputFile: string;
+  filterEndpoints?: EndpointMatcher;
+  endpointOverrides?: EndpointOverrides[];
+  /**
+   * defaults to false
+   * If passed as true it will generate TS enums instead of union of strings
+   */
+  useEnumType?: boolean;
+}
+
+export type EndpointOverrides = {
+  pattern: EndpointMatcher;
+} & AtLeastOneKey<{
+  type: 'mutation' | 'query';
+  parameterFilter: ParameterMatcher;
+}>;
+
+export type ConfigFile =
+  | Id<Require<CommonOptions & OutputFileOptions, 'outputFile'>>
+  | Id<
+      Omit<CommonOptions, 'outputFile'> & {
+        outputFiles: { [outputFile: string]: Omit<OutputFileOptions, 'outputFile'> };
+      }
+    >;

package/src/utils/capitalize.ts

@@ -0,0 +1,3 @@
+export function capitalize(str: string) {
+  return str.replace(str[0], str[0].toUpperCase());
+}

package/src/utils/factory.ts

@@ -0,0 +1,29 @@
+import ts from 'typescript';
+import semver from 'semver';
+
+const originalFactory = ts.factory;
+
+function createImportSpecifier(propertyName: ts.Identifier | undefined, name: ts.Identifier): ts.ImportSpecifier {
+  if (semver.satisfies(ts.version, '>= 4.5'))
+    // @ts-ignore
+    return originalFactory.createImportSpecifier(false, propertyName, name);
+  // @ts-ignore
+  return originalFactory.createImportSpecifier(propertyName, name);
+}
+
+function createExportSpecifier(
+  propertyName: string | ts.Identifier | undefined,
+  name: string | ts.Identifier
+): ts.ExportSpecifier {
+  if (semver.satisfies(ts.version, '>= 4.5'))
+    // @ts-ignore
+    return originalFactory.createExportSpecifier(false, propertyName, name);
+  // @ts-ignore
+  return originalFactory.createExportSpecifier(propertyName, name);
+}
+
+export const factory = {
+  ...originalFactory,
+  createImportSpecifier,
+  createExportSpecifier,
+};

package/src/utils/getOperationDefinitions.ts

@@ -0,0 +1,20 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { OperationDefinition } from '../types';
+import { operationKeys } from '../types';
+
+export function getOperationDefinitions(v3Doc: OpenAPIV3.Document): OperationDefinition[] {
+  return Object.entries(v3Doc.paths).flatMap(([path, pathItem]) =>
+    !pathItem
+      ? []
+      : Object.entries(pathItem)
+          .filter((arg): arg is [(typeof operationKeys)[number], OpenAPIV3.OperationObject] =>
+            operationKeys.includes(arg[0] as any)
+          )
+          .map(([verb, operation]) => ({
+            path,
+            verb,
+            pathItem,
+            operation,
+          }))
+  );
+}

package/src/utils/getV3Doc.ts

@@ -0,0 +1,24 @@
+import SwaggerParser from '@apidevtools/swagger-parser';
+import type { OpenAPIV3 } from 'openapi-types';
+// @ts-ignore
+import converter from 'swagger2openapi';
+
+export async function getV3Doc(
+  spec: string,
+  httpResolverOptions?: SwaggerParser.HTTPResolverOptions
+): Promise<OpenAPIV3.Document> {
+  const doc = await SwaggerParser.bundle(spec, {
+    resolve: {
+      http: httpResolverOptions,
+    },
+  });
+
+  const isOpenApiV3 = 'openapi' in doc && doc.openapi.startsWith('3');
+
+  if (isOpenApiV3) {
+    return doc as OpenAPIV3.Document;
+  } else {
+    const result = await converter.convertObj(doc, {});
+    return result.openapi as OpenAPIV3.Document;
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+export * from './capitalize';
+export * from './getOperationDefinitions';
+export * from './getV3Doc';
+export * from './isQuery';
+export * from './isValidUrl';
+export * from './prettier';
+export * from './messages';
+export * from './removeUndefined';

package/src/utils/isQuery.ts

@@ -0,0 +1,8 @@
+import type { EndpointOverrides, operationKeys } from '../types';
+
+export function isQuery(verb: (typeof operationKeys)[number], overrides: EndpointOverrides | undefined) {
+  if (overrides?.type) {
+    return overrides.type === 'query';
+  }
+  return verb === 'get';
+}

package/src/utils/isValidUrl.ts

@@ -0,0 +1,9 @@
+export function isValidUrl(string: string) {
+  try {
+    new URL(string);
+  } catch (_) {
+    return false;
+  }
+
+  return true;
+}

package/src/utils/messages.ts

@@ -0,0 +1,7 @@
+export const MESSAGES = {
+  NAMED_EXPORT_MISSING: `You specified a named export that does not exist or was empty.`,
+  DEFAULT_EXPORT_MISSING: `Specified file exists, but no default export was found for the --baseQuery`,
+  FILE_NOT_FOUND: `Unable to locate the specified file provided to --baseQuery`,
+  TSCONFIG_FILE_NOT_FOUND: `Unable to locate the specified file provided to -c, --config`,
+  BASE_URL_IGNORED: `The url provided to --baseUrl is ignored when using --baseQuery`,
+};

package/src/utils/prettier.ts

@@ -0,0 +1,46 @@
+import path from 'node:path';
+import prettier from 'prettier';
+import type { BuiltInParserName } from 'prettier';
+
+const EXTENSION_TO_PARSER: Record<string, BuiltInParserName> = {
+  ts: 'typescript',
+  tsx: 'typescript',
+  js: 'babel',
+  jsx: 'babel',
+  'js.flow': 'flow',
+  flow: 'flow',
+  gql: 'graphql',
+  graphql: 'graphql',
+  css: 'scss',
+  scss: 'scss',
+  less: 'scss',
+  stylus: 'scss',
+  markdown: 'markdown',
+  md: 'markdown',
+  json: 'json',
+};
+
+export async function prettify(filePath: string | null, content: string, prettierConfigFile?: string): Promise<string> {
+  let config = null;
+  let parser = 'typescript';
+
+  if (filePath) {
+    const fileExtension = path.extname(filePath).slice(1);
+    parser = EXTENSION_TO_PARSER[fileExtension];
+    config = await prettier.resolveConfig(process.cwd(), {
+      useCache: true,
+      editorconfig: !prettierConfigFile,
+      config: prettierConfigFile,
+    });
+  } else if (prettierConfigFile) {
+    config = await prettier.resolveConfig(process.cwd(), {
+      useCache: true,
+      config: prettierConfigFile,
+    });
+  }
+
+  return prettier.format(content, {
+    parser,
+    ...config,
+  });
+}

package/src/utils/removeUndefined.ts

@@ -0,0 +1,3 @@
+export function removeUndefined<T>(t: T | undefined): t is T {
+  return typeof t !== 'undefined';
+}