api 7.0.0-alpha.0 → 7.0.0-alpha.1

package/dist/bin.d.ts

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

package/dist/bin.js

@@ -0,0 +1,91 @@
+"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 __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var commander_1 = require("commander");
+var commands_1 = __importDefault(require("./commands"));
+var pkg = __importStar(require("./packageInfo"));
+(function () { return __awaiter(void 0, void 0, void 0, function () {
+    var program;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                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(function (_a) {
+                    var cmd = _a[1];
+                    program.addCommand(cmd);
+                });
+                return [4 /*yield*/, program.parseAsync(process.argv)];
+            case 1:
+                _a.sent();
+                return [2 /*return*/];
+        }
+    });
+}); })();

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 });
+var 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: ".concat(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,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var packageInfo_1 = require("../packageInfo");
+var CodeGeneratorLanguage = /** @class */ (function () {
+    function CodeGeneratorLanguage(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.
+        var info = spec.getDefinition().info;
+        this.userAgent = "".concat(identifier, "/").concat(info.version, " (").concat(packageInfo_1.PACKAGE_NAME, "/").concat(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.');
+        }
+    }
+    CodeGeneratorLanguage.prototype.hasRequiredPackages = function () {
+        return Boolean(Object.keys(this.requiredPackages));
+    };
+    return CodeGeneratorLanguage;
+}());
+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,175 @@
+"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;
+var lodash_camelcase_1 = __importDefault(require("lodash.camelcase"));
+var lodash_deburr_1 = __importDefault(require("lodash.deburr"));
+var 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}
+ */
+var 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) {
+    if (max === void 0) { max = 88; }
+    return str.replace(new RegExp("(?![^\\n]{1,".concat(max, "}$)([^\\n]{1,").concat(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, function (match) { return match.toUpperCase(); })
+        // remove non-leading underscores followed by lowercase (convert snake_case)
+        .replace(/_[a-z]/g, function (match) { return match.substr(1, match.length).toUpperCase(); })
+        // uppercase letters after digits, dollars
+        .replace(/([\d$]+[a-zA-Z])/g, function (match) { return match.toUpperCase(); })
+        // uppercase first letter after whitespace
+        .replace(/\s+([a-zA-Z])/g, function (match) { return match.toUpperCase().trim(); })
+        // remove remaining whitespace
+        .replace(/\s/g, ''));
+}
+function generateTypeName() {
+    var parts = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        parts[_i] = arguments[_i];
+    }
+    var 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) {
+        var 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 += " ".concat(last);
+        }
+    }
+    if (!str) {
+        str = (0, lodash_startcase_1.default)((0, lodash_camelcase_1.default)(parts.join(' ')));
+    }
+    if (RESERVED_WORDS.includes(str.toLowerCase())) {
+        str = "$".concat(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';
+import type { HttpMethods, SchemaObject } from 'oas/dist/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<"formData" | "body" | "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 {};