api 7.0.0-alpha.0 → 7.0.0-alpha.2

package/dist/bin.d.ts

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

package/dist/bin.js

@@ -0,0 +1,45 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const commands_1 = __importDefault(require("./commands"));
+const pkg = __importStar(require("./packageInfo"));
+(async () => {
+    const program = new commander_1.Command();
+    program.name(pkg.PACKAGE_NAME);
+    program.version(pkg.PACKAGE_VERSION);
+    /**
+     * Instead of using Commander's `executableDir` API for loading in external command files we're
+     * programatically doing it like this because it's cleaner for us to let Commander manage option
+     * and argument parsing within this file than having each command  manage that itself.
+     */
+    Object.entries(commands_1.default).forEach(([, cmd]) => {
+        program.addCommand(cmd);
+    });
+    await program.parseAsync(process.argv);
+})();

package/dist/codegen/index.d.ts

@@ -0,0 +1,4 @@
+import type CodeGeneratorLanguage from './language';
+import type Oas from 'oas';
+export type SupportedLanguages = 'js' | 'js-cjs' | 'js-esm' | 'ts';
+export default function codegen(language: SupportedLanguages, spec: Oas, specPath: string, identifier: string): CodeGeneratorLanguage;

package/dist/codegen/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const typescript_1 = __importDefault(require("./languages/typescript"));
+function codegen(language, spec, specPath, identifier) {
+    switch (language) {
+        case 'js':
+            throw new TypeError('An export format of CommonJS or ECMAScript is required for JavaScript compilation.');
+        case 'js-cjs':
+        case 'js-esm':
+        case 'ts':
+            return new typescript_1.default(spec, specPath, identifier, {
+                outputJS: ['js-cjs', 'js-esm'].includes(language),
+                // TS will always generate with ESM-like exports.
+                compilerTarget: language === 'js-cjs' ? 'cjs' : 'esm',
+            });
+        default:
+            throw new TypeError(`Unsupported language supplied: ${language}`);
+    }
+}
+exports.default = codegen;

package/dist/codegen/language.d.ts

@@ -0,0 +1,27 @@
+import type Storage from '../storage';
+import type Oas from 'oas';
+export interface InstallerOptions {
+    /**
+     * Will initiate a dry run install process. Used for simulating installations within a unit test.
+     */
+    dryRun?: boolean;
+    /**
+     * Used for stubbing out the logger that we use within the installation process so it can be
+     * easily introspected without having to mock out `console.*`.
+     */
+    logger?: (msg: string) => void;
+}
+export default abstract class CodeGeneratorLanguage {
+    spec: Oas;
+    specPath: string;
+    identifier: string;
+    userAgent: string;
+    requiredPackages: Record<string, {
+        reason: string;
+        url: string;
+    }>;
+    constructor(spec: Oas, specPath: string, identifier: string);
+    abstract generator(): Promise<Record<string, string>>;
+    abstract installer(storage: Storage, opts?: InstallerOptions): Promise<void>;
+    hasRequiredPackages(): boolean;
+}

package/dist/codegen/language.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const packageInfo_1 = require("../packageInfo");
+class CodeGeneratorLanguage {
+    spec;
+    specPath;
+    identifier;
+    userAgent;
+    requiredPackages;
+    constructor(spec, specPath, identifier) {
+        this.spec = spec;
+        this.specPath = specPath;
+        this.identifier = identifier;
+        // User agents should be contextual to the spec in question and the version of `api` that was
+        // used to generate the SDK. For example, this'll look like `petstore/1.0.0 (api/4.2.0)` for
+        // a `petstore` spec installed on api@4.2.0.
+        const info = spec.getDefinition().info;
+        this.userAgent = `${identifier}/${info.version} (${packageInfo_1.PACKAGE_NAME}/${packageInfo_1.PACKAGE_VERSION})`;
+        /**
+         * This check is barbaric but there are a number of issues with how the `transformer` work we
+         * have in `oas` and in `.getParametersAsJSONSchema()` and `.getResponseAsJSONSchema()` that
+         * are fully crashing when attempting to codegen an SDK for an API definition that has a
+         * circular reference.
+         *
+         * In order to get v5 out the door we're not going to support this case initialy.
+         *
+         * @see {@link https://github.com/readmeio/api/issues/549}
+         */
+        if (JSON.stringify(spec.api).includes('"$ref":"#/')) {
+            throw new Error('Sorry, this library does not yet support generating an SDK for an OpenAPI definition that contains circular references.');
+        }
+    }
+    hasRequiredPackages() {
+        return Boolean(Object.keys(this.requiredPackages));
+    }
+}
+exports.default = CodeGeneratorLanguage;

package/dist/codegen/languages/typescript/util.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @see {@link https://www.30secondsofcode.org/js/s/word-wrap}
+ */
+export declare function wordWrap(str: string, max?: number): string;
+/**
+ * Safely escape some string characters that may break a docblock.
+ *
+ */
+export declare function docblockEscape(str: string): string;
+export declare function generateTypeName(...parts: string[]): string;

package/dist/codegen/languages/typescript/util.js

@@ -0,0 +1,170 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateTypeName = exports.docblockEscape = exports.wordWrap = void 0;
+const lodash_camelcase_1 = __importDefault(require("lodash.camelcase"));
+const lodash_deburr_1 = __importDefault(require("lodash.deburr"));
+const lodash_startcase_1 = __importDefault(require("lodash.startcase"));
+/**
+ * This is a mix of reserved JS words and keywords in TypeScript that might be reserved or
+ * allowable but functionally confusing (like `let any = 'buster';`)
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar}
+ */
+const RESERVED_WORDS = [
+    'abstract',
+    'any',
+    'arguments',
+    'as',
+    'async',
+    'await',
+    'boolean',
+    'break',
+    'byte',
+    'case',
+    'catch',
+    'char',
+    'class',
+    'const',
+    'continue',
+    'constructor',
+    'debugger',
+    'default',
+    'delete',
+    'do',
+    'double',
+    'else',
+    'enum',
+    'eval',
+    'export',
+    'extends',
+    'false',
+    'final',
+    'finally',
+    'float',
+    'for',
+    'from',
+    'function',
+    'get',
+    'goto',
+    'if',
+    'implements',
+    'import',
+    'interface',
+    'in',
+    'instanceof',
+    'int',
+    'let',
+    'long',
+    'native',
+    'new',
+    'null',
+    'number',
+    'of',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'module',
+    'namespace',
+    'return',
+    'set',
+    'short',
+    'static',
+    'string',
+    'super',
+    'switch',
+    'synchronized',
+    'this',
+    'throw',
+    'throws',
+    'transient',
+    'true',
+    'try',
+    'type',
+    'typeof',
+    'var',
+    'void',
+    'while',
+    'with',
+    'volatile',
+    'yield',
+    // These aren't reserved keywords but because we maybe codegen'ing an SDK to be used in the
+    // browser it'd be very bad if we overwrote these. This obviously doesn't account for browser APIs
+    // you can access outside of the `Window` API (like `alert()`), but we can add checks for those
+    // later if we need to.
+    'frames',
+    'global',
+    'globalThis',
+    'navigator',
+    'self',
+    'window',
+];
+/**
+ * @see {@link https://www.30secondsofcode.org/js/s/word-wrap}
+ */
+function wordWrap(str, max = 88) {
+    return str.replace(new RegExp(`(?![^\\n]{1,${max}}$)([^\\n]{1,${max}})\\s`, 'g'), '$1\n');
+}
+exports.wordWrap = wordWrap;
+/**
+ * Safely escape some string characters that may break a docblock.
+ *
+ */
+function docblockEscape(str) {
+    return str.replace(/\/\*/g, '/\\*').replace(/\*\//g, '*\\/');
+}
+exports.docblockEscape = docblockEscape;
+/**
+ * Convert a string that might contain spaces or special characters to one that can safely be used
+ * as a TypeScript interface or enum name.
+ *
+ * This function has been adapted and slighty modified from `json-schema-to-typescript`.
+ *
+ * @license MIT
+ * @see {@link https://github.com/bcherny/json-schema-to-typescript}
+ */
+function toSafeString(str) {
+    // identifiers in javaScript/ts:
+    // First character: a-zA-Z | _ | $
+    // Rest: a-zA-Z | _ | $ | 0-9
+    // remove accents, umlauts, ... by their basic latin letters
+    return ((0, lodash_deburr_1.default)(str)
+        // if the string starts with a number, prefix it with character that typescript can accept
+        // https://github.com/bcherny/json-schema-to-typescript/issues/489
+        .replace(/^(\d){1}/, '$$1')
+        // replace chars which are not valid for typescript identifiers with whitespace
+        .replace(/(^\s*[^a-zA-Z_$])|([^a-zA-Z_$\d])/g, ' ')
+        // uppercase leading underscores followed by lowercase
+        .replace(/^_[a-z]/g, (match) => match.toUpperCase())
+        // remove non-leading underscores followed by lowercase (convert snake_case)
+        .replace(/_[a-z]/g, (match) => match.substr(1, match.length).toUpperCase())
+        // uppercase letters after digits, dollars
+        .replace(/([\d$]+[a-zA-Z])/g, (match) => match.toUpperCase())
+        // uppercase first letter after whitespace
+        .replace(/\s+([a-zA-Z])/g, (match) => match.toUpperCase().trim())
+        // remove remaining whitespace
+        .replace(/\s/g, ''));
+}
+function generateTypeName(...parts) {
+    let str;
+    // If the end of our string ends with something like `2XX`, the combination of `startCase` and
+    // `camelCase` will transform it into `2Xx`.
+    if (parts.length > 1) {
+        const last = parts[parts.length - 1];
+        if (last.match(/^(\d)XX$/)) {
+            str = (0, lodash_startcase_1.default)((0, lodash_camelcase_1.default)(parts.slice(0, -1).join(' ')));
+            str += ` ${last}`;
+        }
+    }
+    if (!str) {
+        str = (0, lodash_startcase_1.default)((0, lodash_camelcase_1.default)(parts.join(' ')));
+    }
+    if (RESERVED_WORDS.includes(str.toLowerCase())) {
+        str = `$${str}`;
+    }
+    return toSafeString(str);
+}
+exports.generateTypeName = generateTypeName;

package/dist/codegen/languages/typescript.d.ts

@@ -0,0 +1,111 @@
+import type Storage from '../../storage';
+import type { InstallerOptions } from '../language';
+import type Oas from 'oas';
+import type Operation from 'oas/operation';
+import type { HttpMethods, SchemaObject } from 'oas/rmoas.types';
+import type { ClassDeclaration, JSDocStructure, JSDocTagStructure, OptionalKind } from 'ts-morph';
+import { Project } from 'ts-morph';
+import CodeGeneratorLanguage from '../language';
+export interface TSGeneratorOptions {
+    compilerTarget?: 'cjs' | 'esm';
+    outputJS?: boolean;
+}
+interface OperationTypeHousing {
+    operation: Operation;
+    types: {
+        params?: false | Record<'body' | 'formData' | 'metadata', string>;
+        responses?: Record<string | number, {
+            description?: string;
+            type: string;
+        }>;
+    };
+}
+export default class TSGenerator extends CodeGeneratorLanguage {
+    project: Project;
+    outputJS: boolean;
+    compilerTarget: 'cjs' | 'esm';
+    types: Map<string, string>;
+    sdk: ClassDeclaration;
+    schemas: Record<string, {
+        body?: unknown;
+        metadata?: unknown;
+        response?: Record<string, unknown>;
+    } | Record<string, unknown>>;
+    usesHTTPMethodRangeInterface: boolean;
+    constructor(spec: Oas, specPath: string, identifier: string, opts?: TSGeneratorOptions);
+    installer(storage: Storage, opts?: InstallerOptions): Promise<void>;
+    /**
+     * Compile the current OpenAPI definition into a TypeScript library.
+     *
+     */
+    generator(): Promise<{
+        [x: string]: string;
+    }>;
+    /**
+     * Create our main SDK source file.
+     *
+     */
+    createSourceFile(): import("ts-morph").SourceFile;
+    /**
+     * Create our main schemas file. This is where all of the JSON Schema that our TypeScript typing
+     * infrastructure sources its data from. Without this there are no types.
+     *
+     */
+    createSchemasFile(): import("ts-morph").SourceFile;
+    /**
+     * Create our main types file. This sources its data from the JSON Schema `schemas.ts` file and
+     * will re-export types to be used in TypeScript implementations and IDE intellisense. This
+     * typing work is functional with the `json-schema-to-ts` library.
+     *
+     * @see {@link https://npm.im/json-schema-to-ts}
+     */
+    createTypesFile(): import("ts-morph").SourceFile;
+    /**
+     * Add a new JSDoc `@tag` to an existing docblock.
+     *
+     */
+    static addTagToDocblock(docblock: OptionalKind<JSDocStructure>, tag: OptionalKind<JSDocTagStructure>): {
+        tags: OptionalKind<JSDocTagStructure>[];
+        description?: string | import("ts-morph").WriterFunction | undefined;
+        leadingTrivia?: string | import("ts-morph").WriterFunction | (string | import("ts-morph").WriterFunction)[] | undefined;
+        trailingTrivia?: string | import("ts-morph").WriterFunction | (string | import("ts-morph").WriterFunction)[] | undefined;
+        kind?: import("ts-morph").StructureKind.JSDoc | undefined;
+    };
+    /**
+     * Create operation accessors on the SDK.
+     *
+     */
+    createOperationAccessor(operation: Operation, operationId: string, paramTypes?: OperationTypeHousing['types']['params'], responseTypes?: OperationTypeHousing['types']['responses']): void;
+    /**
+     * Scour through the current OpenAPI definition and compile a store of every operation, along
+     * with every HTTP method that's in use, and their available TypeScript types that we can use,
+     * along with every HTTP method that's in use.
+     *
+     */
+    loadOperationsAndMethods(): {
+        operations: Record<string, OperationTypeHousing>;
+        methods: Set<HttpMethods>;
+    };
+    /**
+     * Compile the parameter (path, query, cookie, and header) schemas for an API operation into
+     * usable TypeScript types.
+     *
+     */
+    prepareParameterTypesForOperation(operation: Operation, operationId: string): false | Record<"body" | "formData" | "metadata", string>;
+    /**
+     * Compile the response schemas for an API operation into usable TypeScript types.
+     *
+     */
+    prepareResponseTypesForOperation(operation: Operation, operationId: string): {
+        [x: string]: {
+            type: string;
+            description: any;
+        };
+    } | undefined;
+    /**
+     * Add a given schema into our schema dataset that we'll be be exporting as types.
+     *
+     */
+    addSchemaToExport(schema: SchemaObject, typeName: string, pointer: string): void;
+}
+export {};