api 4.4.0 → 5.0.0-beta.0

package/src/cli/commands/index.ts

@@ -0,0 +1,5 @@
+import installCommand from './install';
+
+export default {
+  install: installCommand,
+};

package/src/cli/commands/install.ts

@@ -0,0 +1,196 @@
+import type { SupportedLanguages } from '../codegen';
+
+import { Command, Option } from 'commander';
+import ora from 'ora';
+import Oas from 'oas';
+
+import codegen from '../codegen';
+import Fetcher from '../../fetcher';
+import Storage from '../storage';
+import logger from '../logger';
+
+import promptTerminal from '../lib/prompt';
+
+import figures from 'figures';
+import validateNPMPackageName from 'validate-npm-package-name';
+
+// @todo log logs to `.api/.logs` and have `.logs` ignored
+const cmd = new Command();
+cmd
+  .name('install')
+  .description('install an API SDK into your codebase')
+  .argument('<uri>', 'an API to install')
+  .addOption(
+    new Option('-l, --lang <language>', 'SDK language').choices([
+      'js', // User generally wants JS, we'll prompt if they want CJS or ESM files.
+      'js-cjs',
+      'js-esm',
+      'ts',
+    ])
+  )
+  .action(async (uri: string, options: { lang: string }) => {
+    let language: SupportedLanguages;
+    if (options.lang) {
+      language = options.lang as SupportedLanguages;
+    } else {
+      ({ value: language } = await promptTerminal({
+        type: 'select',
+        name: 'value',
+        message: 'What language would you like to generate an SDK for?',
+        choices: [
+          { title: 'TypeScript', value: 'ts' },
+          { title: 'JavaScript', value: 'js' },
+        ],
+        initial: 1,
+      }));
+    }
+
+    // Because our TS generation outputs raw TS source files we don't need to worry about CJS/ESM.
+    if (language === 'js') {
+      ({ value: language } = await promptTerminal({
+        type: 'select',
+        name: 'value',
+        message: 'How are your project imports and exports structured?',
+        choices: [
+          { title: 'CommonJS', description: 'require/exports', value: 'cjs' },
+          { title: 'ECMAScript Modules', description: 'import/export', value: 'esm' },
+        ],
+        initial: 0,
+        format: sel => (sel === 'cjs' ? 'js-cjs' : 'js-esm'),
+      }));
+    }
+
+    // @todo let them know that we're going to be creating a `.api/ directory
+    // @todo detect if they have a gitigore and .npmignore and if .api woudl be ignored by that
+    // @todo don't support swagger files without upconverting them
+
+    if (Storage.isInLockFile({ source: uri })) {
+      // @todo
+      // logger(`It looks like you already have this API installed. Would you like to update it?`);
+    }
+
+    let identifier;
+    if (Fetcher.isAPIRegistryUUID(uri)) {
+      identifier = Fetcher.getProjectPrefixFromRegistryUUID(uri);
+    } else {
+      ({ value: identifier } = await promptTerminal({
+        type: 'text',
+        name: 'value',
+        message:
+          'What would you like to identify this API as? This will be how you import the SDK. (e.g. entering `petstore` would result in `@api/petstore`)',
+        validate: value => {
+          if (!value) {
+            return false;
+          }
+
+          // Is this identifier already in storage?
+          if (Storage.isInLockFile({ identifier: value })) {
+            return `"${value}" is already taken in your \`.api/\` directory. Please enter another identifier.`;
+          }
+
+          const isValidForNPM = validateNPMPackageName(`@api/${value}`);
+          if (!isValidForNPM.validForNewPackages) {
+            // `prompts` doesn't support surfacing multiple errors in a `validate` call so we can
+            // only surface the first to the user.
+            return isValidForNPM.errors[0];
+          }
+
+          return true;
+        },
+      }));
+    }
+
+    if (!identifier) {
+      logger('You must tell us what you would like to identify this API as in order to install it.', true);
+      process.exit(1);
+    }
+
+    let spinner = ora('Fetching your API').start();
+    const storage = new Storage(uri, identifier);
+
+    const oas = await storage
+      .load()
+      .then(res => {
+        spinner.succeed(spinner.text);
+        return res;
+      })
+      .then(Oas.init)
+      .catch(err => {
+        // @todo cleanup installed files
+        spinner.fail(spinner.text);
+        logger(err.message, true);
+        process.exit(1);
+      });
+
+    // @todo look for a prettier config and if we find one ask them if we should use it
+    spinner = ora('Generating your SDK').start();
+    const generator = codegen(language, oas, './openapi.json', identifier);
+    const sdkSource = await generator
+      .generator()
+      .then(res => {
+        spinner.succeed(spinner.text);
+        return res;
+      })
+      .catch(err => {
+        // @todo cleanup installed files
+        spinner.fail(spinner.text);
+        logger(err.message, true);
+        process.exit(1);
+      });
+
+    spinner = ora('Saving your SDK into your codebase').start();
+    await storage
+      .saveSourceFiles(sdkSource)
+      .then(() => {
+        spinner.succeed(spinner.text);
+      })
+      .catch(err => {
+        // @todo cleanup installed files
+        spinner.fail(spinner.text);
+        logger(err.message, true);
+        process.exit(1);
+      });
+
+    if (generator.hasRequiredPackages()) {
+      logger(`${figures.warning} This generator requires some packages to be installed alongside it:`);
+      Object.entries(generator.requiredPackages).forEach(([pkg, pkgInfo]) => {
+        logger(`  ${figures.pointerSmall} ${pkg}: ${pkgInfo.reason} ${pkgInfo.url}`);
+      });
+
+      await promptTerminal({
+        type: 'confirm',
+        name: 'value',
+        message: 'OK to proceed with package installation?',
+        initial: true,
+      }).then(({ value }) => {
+        if (!value) {
+          // @todo cleanup installed files
+          logger('Installation cancelled.', true);
+          process.exit(1);
+        }
+      });
+
+      spinner = ora('Installing required packages').start();
+      try {
+        await generator.installer(storage);
+        spinner.succeed(spinner.text);
+      } catch (err) {
+        // @todo cleanup installed files
+        spinner.fail(spinner.text);
+        logger(err.message, true);
+        process.exit(1);
+      }
+    }
+
+    logger('🚀 All done!');
+  })
+  .addHelpText(
+    'after',
+    `
+Examples:
+  $ api install @developers/v2.0#nysezql0wwo236
+  $ api install https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore-simple.json
+  $ api install ./petstore.json`
+  );
+
+export default cmd;

package/src/cli/lib/prompt.ts

@@ -0,0 +1,29 @@
+import prompts from 'prompts';
+
+/**
+ * The `prompts` library doesn't always interpret CTRL+C and release the terminal back to the user
+ * so we need handle this ourselves. This function is just a simple overload of the main `prompts`
+ * import that we use.
+ *
+ * @see {@link https://github.com/terkelg/prompts/issues/252}
+ */
+export default async function promptTerminal<T extends string = string>(
+  question: prompts.PromptObject<T>,
+  options?: prompts.Options
+) {
+  const enableTerminalCursor = () => {
+    process.stdout.write('\x1B[?25h');
+  };
+
+  const onState = (state: { aborted: boolean }) => {
+    if (state.aborted) {
+      // If we don't re-enable the terminal cursor before exiting the program, the cursor will
+      // remain hidden.
+      enableTerminalCursor();
+      process.stdout.write('\n');
+      process.exit(1);
+    }
+  };
+
+  return prompts({ ...question, onState }, options);
+}

package/src/cli/logger.ts

@@ -0,0 +1,10 @@
+/* eslint-disable no-console */
+import chalk from 'chalk';
+
+export default function logger(log: string, error?: boolean) {
+  if (error) {
+    console.error(chalk.red(log));
+  } else {
+    console.log(log);
+  }
+}

package/src/cli/storage.ts

@@ -0,0 +1,297 @@
+import type { OASDocument } from 'oas/@types/rmoas.types';
+
+import ssri from 'ssri';
+import fs from 'fs';
+import path from 'path';
+import makeDir from 'make-dir';
+
+import { PACKAGE_VERSION } from '../packageInfo';
+
+import Fetcher from '../fetcher';
+
+export default class Storage {
+  static dir: string;
+
+  static lockfile: false | Lockfile;
+
+  /**
+   * This is the original source that the file came from (relative/absolute file path, URL, ReadMe
+   * registry UUID, etc.).
+   */
+  source: string;
+
+  identifier: string;
+
+  fetcher: Fetcher;
+
+  constructor(source: string, identifier?: string) {
+    Storage.setStorageDir();
+
+    this.fetcher = new Fetcher(source);
+
+    this.source = source;
+    this.identifier = identifier;
+
+    // This should default to false so we have awareness if we've looked at the lockfile yet.
+    Storage.lockfile = false;
+  }
+
+  static getLockfilePath() {
+    return path.join(Storage.dir, 'api.json');
+  }
+
+  static getAPIsDir() {
+    return path.join(Storage.dir, 'apis');
+  }
+
+  static setStorageDir(dir?: string) {
+    if (dir) {
+      Storage.dir = dir;
+      return;
+    } else if (Storage.dir) {
+      // If we already have a storage dir set and aren't explicitly it to something new then we
+      // shouldn't overwrite what we've already got.
+      return;
+    }
+
+    Storage.dir = makeDir.sync(path.join(process.cwd(), '.api'));
+
+    makeDir.sync(Storage.getAPIsDir());
+  }
+
+  /**
+   * Reset the state of the entire storage system.
+   *
+   * This will completely destroy the contents of the `.api/` directory!
+   */
+  static async reset() {
+    if (Storage.getLockfilePath()) {
+      await fs.promises.writeFile(Storage.getLockfilePath(), JSON.stringify(Storage.getDefaultLockfile(), null, 2));
+    }
+
+    if (Storage.getAPIsDir()) {
+      await fs.promises.rm(Storage.getAPIsDir(), { recursive: true });
+      await fs.promises.mkdir(Storage.getAPIsDir(), { recursive: true });
+    }
+  }
+
+  static getDefaultLockfile(): Lockfile {
+    return {
+      version: '1.0',
+      apis: [],
+    };
+  }
+
+  static generateIntegrityHash(definition: OASDocument) {
+    return ssri
+      .fromData(JSON.stringify(definition), {
+        algorithms: ['sha512'],
+      })
+      .toString();
+  }
+
+  static getLockfile() {
+    if (typeof Storage.lockfile === 'object') {
+      return Storage.lockfile;
+    }
+
+    if (fs.existsSync(Storage.getLockfilePath())) {
+      const file = fs.readFileSync(Storage.getLockfilePath(), 'utf8');
+      Storage.lockfile = JSON.parse(file) as Lockfile;
+    } else {
+      Storage.lockfile = Storage.getDefaultLockfile();
+    }
+
+    return Storage.lockfile;
+  }
+
+  static isInLockFile(search: { identifier?: string; source?: string }) {
+    // Because this method may run before we initialize a new storage object we should make sure
+    // that we have a storage directory present.
+    Storage.setStorageDir();
+
+    if (!search.identifier && !search.source) {
+      throw new TypeError('An `identifier` or `source` must be supplied to this method to search in the lockfile.');
+    }
+
+    const lockfile = Storage.getLockfile();
+    if (typeof lockfile !== 'object' || lockfile === null || !lockfile.apis) {
+      return false;
+    }
+
+    const res = lockfile.apis.find(a => {
+      if (search.identifier) {
+        return a.identifier === search.identifier;
+      }
+
+      return a.source === search.source;
+    });
+
+    return res === undefined ? false : res;
+  }
+
+  setIdentifier(identifier: string) {
+    this.identifier = identifier;
+  }
+
+  /**
+   * Determine if the current spec + identifier we're working with is already in the lockfile.
+   */
+  isInLockfile() {
+    return Boolean(this.getFromLockfile());
+  }
+
+  /**
+   * Retrieve the lockfile record for the current spec + identifier if it exists in the lockfile.
+   */
+  getFromLockfile() {
+    const lockfile = Storage.getLockfile();
+    return lockfile.apis.find(a => a.identifier === this.identifier);
+  }
+
+  getIdentifierStorageDir() {
+    if (!this.isInLockfile()) {
+      throw new Error(`${this.source} has not been saved to storage yet and must do so before being retrieved.`);
+    }
+
+    return path.join(Storage.getAPIsDir(), this.identifier);
+  }
+
+  getAPIDefinition() {
+    const file = fs.readFileSync(path.join(this.getIdentifierStorageDir(), 'openapi.json'), 'utf8');
+
+    return JSON.parse(file);
+  }
+
+  saveSourceFiles(files: Record<string, string>) {
+    if (!this.isInLockfile()) {
+      throw new Error(`${this.source} has not been saved to storage yet and must do so before being retrieved.`);
+    }
+
+    return new Promise(resolve => {
+      const savedSource: string[] = [];
+      Object.entries(files).forEach(([fileName, contents]) => {
+        const sourceFilePath = path.join(this.getIdentifierStorageDir(), fileName);
+
+        fs.writeFileSync(sourceFilePath, contents);
+
+        savedSource.push(sourceFilePath);
+      });
+
+      resolve(savedSource);
+    });
+  }
+
+  async load() {
+    return this.fetcher.load().then(async spec => this.save(spec));
+  }
+
+  /**
+   * @example <caption>Storage directory structure</caption>
+   * .api/
+   * ├── api.json             // The `package-lock.json` equivalent that records everything that's
+   * |                        // installed, when it was installed, what the original source was,
+   * |                        // and what version of `api` was used.
+   * └── apis/
+   *     ├── readme/
+   *     |   ├── node_modules/
+   *     │   ├── index.js     // We may offer the option to export a raw TS file for folks who want
+   *     |   |                // that, but for now it'll be a compiled JS file.
+   *     │   ├── index.d.ts   // All types for their SDK, ready to use in an IDE.
+   *     │   |── openapi.json
+   *     │   └── package.json
+   *     └── petstore/
+   *         ├── node_modules/
+   *         ├── index.js
+   *         ├── index.d.ts
+   *         ├── openapi.json
+   *         └── package.json
+   *
+   * @param spec
+   */
+  save(spec: OASDocument) {
+    if (!this.identifier) {
+      throw new TypeError('An identifier must be set before saving the API definition into storage.');
+    }
+
+    // Create our main `.api/` directory.
+    if (!fs.existsSync(Storage.dir)) {
+      fs.mkdirSync(Storage.dir, { recursive: true });
+    }
+
+    // Create the `.api/apis/` diretory where we'll be storing API definitions.
+    if (!fs.existsSync(Storage.getAPIsDir())) {
+      fs.mkdirSync(Storage.getAPIsDir(), { recursive: true });
+    }
+
+    if (!this.isInLockfile()) {
+      // This API doesn't exist within our storage system yet so we need to record it in the
+      // lockfile.
+      const identifierStorageDir = path.join(Storage.getAPIsDir(), this.identifier);
+      const saved = JSON.stringify(spec, null, 2);
+
+      // Create the `.api/apis/<identifier>` directory where we'll be storing this API definition
+      // and eventually its codegen'd SDK.
+      if (!fs.existsSync(identifierStorageDir)) {
+        fs.mkdirSync(identifierStorageDir, { recursive: true });
+      }
+
+      (Storage.lockfile as Lockfile).apis.push({
+        identifier: this.identifier,
+        source: this.source,
+        integrity: Storage.generateIntegrityHash(spec),
+        installerVersion: PACKAGE_VERSION,
+      } as LockfileAPI);
+
+      fs.writeFileSync(path.join(identifierStorageDir, 'openapi.json'), saved);
+      fs.writeFileSync(Storage.getLockfilePath(), JSON.stringify(Storage.lockfile, null, 2));
+    } else {
+      // Is this the same spec that we already have? Should we update it? // @todo
+    }
+
+    return spec;
+  }
+}
+
+export type Lockfile = {
+  /**
+   * The `api.json` schema version. This will only ever change if we introduce breaking changes to
+   * this store.
+   */
+  version: '1.0';
+  apis: LockfileAPI[];
+};
+
+export type LockfileAPI = {
+  /**
+   * A unique identifier of the API. This'll be used to do requires on `@api/<identifier>` and also
+   * where the SDK code will be located in `.api/apis/<identifier>`.
+   *
+   * @example petstore
+   */
+  identifier: string;
+
+  /**
+   * The original source that was used to generate the SDK with.
+   *
+   * @example https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore-simple.json
+   * @example ./petstore.json
+   * @example @developers/v2.0#nysezql0wwo236
+   */
+  source: string;
+
+  /**
+   * An integrity hash that will be used to determine on `npx api update` calls if the API has
+   * changed since the SDK was last generated.
+   *
+   * @example sha512-ld+djZk8uRWmzXC+JYla1PTBScg0NjP/8x9vOOKRW+DuJ3NNMRjrpfbY7T77Jgnc87dZZsU49robbQfYe3ukug==
+   */
+  integrity: string;
+
+  /**
+   * The version of `api` that was used to install this SDK.
+   *
+   * @example 5.0.0
+   */
+  installerVersion: string;
+};

package/src/core/getJSONSchemaDefaults.ts

@@ -0,0 +1,74 @@
+import type { SchemaObject } from 'oas/@types/rmoas.types';
+import type { SchemaWrapper } from 'oas/@types/operation/get-parameters-as-json-schema';
+import traverse from 'json-schema-traverse';
+
+/**
+ * Run through a JSON Schema object and compose up an object containing default data for any schema
+ * property that is required and also has a defined default.
+ *
+ * Code partially adapted from the `json-schema-default` package but modified to only return
+ * defaults of required properties.
+ *
+ * @todo This is a good candidate to be moved into a core `oas` library method.
+ * @see {@link https://github.com/mdornseif/json-schema-default}
+ * @param jsonSchemas
+ */
+export default function getJSONSchemaDefaults(jsonSchemas: SchemaWrapper[]) {
+  return jsonSchemas
+    .map(({ type: payloadType, schema: jsonSchema }) => {
+      const defaults: Record<string, unknown> = {};
+      traverse(
+        jsonSchema,
+        (
+          schema: SchemaObject,
+          pointer: string,
+          rootSchema: SchemaObject,
+          parentPointer: string,
+          parentKeyword: string,
+          parentSchema: SchemaObject,
+          indexProperty: string
+        ) => {
+          if (!pointer.startsWith('/properties/')) {
+            return;
+          }
+
+          if (Array.isArray(parentSchema?.required) && parentSchema.required.includes(indexProperty)) {
+            if (schema.type === 'object' && indexProperty) {
+              defaults[indexProperty] = {};
+            }
+
+            let destination = defaults;
+            if (parentPointer) {
+              // To map nested objects correct we need to pick apart the parent pointer.
+              parentPointer
+                .replace(/\/properties/g, '')
+                .split('/')
+                .forEach((subSchema: string) => {
+                  if (subSchema === '') {
+                    return;
+                  }
+
+                  destination = (destination?.[subSchema] as Record<string, unknown>) || {};
+                });
+            }
+
+            if (schema.default !== undefined) {
+              if (indexProperty !== undefined) {
+                destination[indexProperty] = schema.default;
+              }
+            }
+          }
+        }
+      );
+
+      if (!Object.keys(defaults).length) {
+        return {};
+      }
+
+      return {
+        // @todo should we filter out empty and undefined objects from here with `remove-undefined-objects`?
+        [payloadType]: defaults,
+      };
+    })
+    .reduce((prev, next) => Object.assign(prev, next));
+}