api 7.0.0-beta.0 → 7.0.0-beta.2

package/src/codegen/languages/typescript/util.ts

@@ -1,174 +0,0 @@
-import camelCase from 'lodash.camelcase';
-import deburr from 'lodash.deburr';
-import startCase from '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}
- */
-export function wordWrap(str: string, max = 88) {
-  return str.replace(new RegExp(`(?![^\\n]{1,${max}}$)([^\\n]{1,${max}})\\s`, 'g'), '$1\n');
-}
-
-/**
- * Safely escape some string characters that may break a docblock.
- *
- */
-export function docblockEscape(str: string) {
-  return str.replace(/\/\*/g, '/\\*').replace(/\*\//g, '*\\/');
-}
-
-/**
- * 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: string) {
-  // identifiers in javaScript/ts:
-  // First character: a-zA-Z | _ | $
-  // Rest: a-zA-Z | _ | $ | 0-9
-
-  // remove accents, umlauts, ... by their basic latin letters
-  return (
-    deburr(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: string) => match.toUpperCase())
-      // remove non-leading underscores followed by lowercase (convert snake_case)
-      .replace(/_[a-z]/g, (match: string) => match.substr(1, match.length).toUpperCase())
-      // uppercase letters after digits, dollars
-      .replace(/([\d$]+[a-zA-Z])/g, (match: string) => match.toUpperCase())
-      // uppercase first letter after whitespace
-      .replace(/\s+([a-zA-Z])/g, (match: string) => match.toUpperCase().trim())
-      // remove remaining whitespace
-      .replace(/\s/g, '')
-  );
-}
-
-export function generateTypeName(...parts: string[]) {
-  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 = startCase(camelCase(parts.slice(0, -1).join(' ')));
-      str += ` ${last}`;
-    }
-  }
-
-  if (!str) {
-    str = startCase(camelCase(parts.join(' ')));
-  }
-
-  if (RESERVED_WORDS.includes(str.toLowerCase())) {
-    str = `$${str}`;
-  }
-
-  return toSafeString(str);
-}

package/src/commands/index.ts

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

package/src/commands/install.ts

@@ -1,196 +0,0 @@
-import { Command, Option } from 'commander';
-import figures from 'figures';
-import Oas from 'oas';
-import ora from 'ora';
-import uslug from 'uslug';
-
-import codegenFactory, { SupportedLanguages } from '../codegen/factory.js';
-import Fetcher from '../fetcher.js';
-import promptTerminal from '../lib/prompt.js';
-import logger from '../logger.js';
-import Storage from '../storage.js';
-
-// @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')
-  .option('-i, --identifier <identifier>', 'API identifier (eg. `@api/petstore`)')
-  .addOption(
-    new Option('-l, --lang <language>', 'SDK language').default(SupportedLanguages.JS).choices([SupportedLanguages.JS]),
-  )
-  .addOption(new Option('-y, --yes', 'Automatically answer "yes" to any prompts printed'))
-  .action(async (uri: string, options: { identifier?: string; lang: string; yes?: boolean }) => {
-    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: 'JavaScript', value: SupportedLanguages.JS }],
-        initial: 1,
-      }));
-    }
-
-    // @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 spinner = ora('Fetching your API definition').start();
-    const storage = new Storage(uri);
-
-    const oas = await storage
-      .load(false)
-      .then(res => {
-        spinner.succeed(spinner.text);
-        return res;
-      })
-      .then(Oas.init)
-      .then(async spec => {
-        await spec.dereference({ preserveRefAsJSONSchemaTitle: true });
-        return spec;
-      })
-      .catch(err => {
-        // @todo cleanup installed files
-        spinner.fail(spinner.text);
-        logger(err.message, true);
-        process.exit(1);
-      });
-
-    let identifier;
-    if (options.identifier) {
-      // `Storage.isIdentifierValid` will throw an exception if an identifier is invalid.
-      if (Storage.isIdentifierValid(options.identifier)) {
-        identifier = options.identifier;
-      }
-    } else if (Fetcher.isAPIRegistryUUID(uri)) {
-      identifier = Fetcher.getProjectPrefixFromRegistryUUID(uri);
-    } else {
-      ({ value: identifier } = await promptTerminal({
-        type: 'text',
-        name: 'value',
-        initial: oas.api?.info?.title ? uslug(oas.api.info.title, { lower: true }) : undefined,
-        message:
-          'What would you like to identify this API as? This will be how you use the SDK. (e.g. entering `petstore` would result in `@api/petstore`)',
-        validate: value => {
-          if (!value) {
-            return false;
-          }
-
-          try {
-            return Storage.isIdentifierValid(value, true);
-          } catch (err) {
-            return err.message;
-          }
-        },
-      }));
-    }
-
-    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);
-    }
-
-    // Now that we've got an identifier we can save their spec and generate the directory structure
-    // for their SDK.
-    storage.setIdentifier(identifier);
-    await storage.save(oas.api);
-
-    // @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 = codegenFactory(language, oas, '../openapi.json', identifier);
-    const sdkSource = await generator
-      .generate()
-      .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]) => {
-        let msg = `  ${figures.pointerSmall} ${pkg}: ${pkgInfo.reason}`;
-        if (pkgInfo.url) {
-          msg += ` ${pkgInfo.url}`;
-        }
-
-        logger(msg);
-      });
-
-      if (!options.yes) {
-        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.install(storage);
-        spinner.succeed(spinner.text);
-      } catch (err) {
-        // @todo cleanup installed files
-        spinner.fail(spinner.text);
-        logger(err.message, true);
-        process.exit(1);
-      }
-    }
-
-    spinner = ora('Compiling your SDK').start();
-    try {
-      await generator.compile(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/fetcher.ts

@@ -1,145 +0,0 @@
-import type { OASDocument } from 'oas/rmoas.types';
-
-import fs from 'node:fs';
-import path from 'node:path';
-
-import OpenAPIParser from '@readme/openapi-parser';
-import yaml from 'js-yaml';
-
-export default class Fetcher {
-  uri: string | OASDocument;
-
-  /**
-   * @note This regex also exists in `httpsnippet-client-api`.
-   *
-   * @example @petstore/v1.0#n6kvf10vakpemvplx
-   * @example @petstore#n6kvf10vakpemvplx
-   */
-  static registryUUIDRegex = /^@(?<project>[a-zA-Z0-9-_]+)(\/?(?<version>.+))?#(?<uuid>[a-z0-9]+)$/;
-
-  constructor(uri: string | OASDocument) {
-    if (typeof uri === 'string') {
-      if (Fetcher.isAPIRegistryUUID(uri)) {
-        // Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
-        this.uri = uri.replace(Fetcher.registryUUIDRegex, 'https://dash.readme.com/api/v1/api-registry/$4');
-      } else if (Fetcher.isGitHubBlobURL(uri)) {
-        /**
-         * People may try to use a public repository URL to the source viewer on GitHub not knowing
-         * that this page actually serves HTML. In this case we want to rewrite these to the "raw"
-         * version of this page that'll allow us to access the API definition.
-         *
-         * @example https://github.com/readmeio/oas-examples/blob/main/3.1/json/petstore.json
-         */
-        this.uri = uri.replace(/\/\/github.com/, '//raw.githubusercontent.com').replace(/\/blob\//, '/');
-      } else {
-        this.uri = uri;
-      }
-    } else {
-      this.uri = uri;
-    }
-  }
-
-  static isAPIRegistryUUID(uri: string) {
-    return Fetcher.registryUUIDRegex.test(uri);
-  }
-
-  static isGitHubBlobURL(uri: string) {
-    return /\/\/github.com\/[-_a-zA-Z0-9]+\/[-_a-zA-Z0-9]+\/blob\/(.*).(yaml|json|yml)/.test(uri);
-  }
-
-  /**
-   * @note This function also exists in `httpsnippet-client-api`.
-   */
-  static getProjectPrefixFromRegistryUUID(uri: string) {
-    const matches = uri.match(Fetcher.registryUUIDRegex);
-    if (!matches) {
-      return undefined;
-    }
-
-    return matches.groups?.project;
-  }
-
-  async load() {
-    if (typeof this.uri !== 'string') {
-      throw new TypeError(
-        "Something disastrous occurred and a non-string URI was supplied to the Fetcher library. This shouldn't have happened!",
-      );
-    }
-
-    return Promise.resolve(this.uri)
-      .then(uri => {
-        let url;
-        try {
-          url = new URL(uri);
-        } catch (err) {
-          // If that try fails for whatever reason than the URI that we have isn't a real URL and
-          // we can safely attempt to look for it on the filesystem.
-          return Fetcher.getFile(uri);
-        }
-
-        return Fetcher.getURL(url.href);
-      })
-      .then(res => Fetcher.validate(res))
-      .then(res => res as OASDocument);
-  }
-
-  static getURL(url: string) {
-    // @todo maybe include our user-agent here to identify our request
-    return fetch(url).then(res => {
-      if (!res.ok) {
-        throw new Error(`Unable to retrieve URL (${url}). Reason: ${res.statusText}`);
-      }
-
-      if (res.headers.get('content-type') === 'application/yaml' || /\.(yaml|yml)/.test(url)) {
-        return res.text().then(text => {
-          return yaml.load(text);
-        });
-      }
-
-      return res.json();
-    });
-  }
-
-  static getFile(uri: string) {
-    // Support relative paths by resolving them against the cwd.
-    const file = path.resolve(process.cwd(), uri);
-
-    if (!fs.existsSync(file)) {
-      throw new Error(
-        `Sorry, we were unable to load an API definition from ${file}. Please either supply a URL or a path on your filesystem.`,
-      );
-    }
-
-    return Promise.resolve(fs.readFileSync(file, 'utf8')).then((res: string) => {
-      if (/\.(yaml|yml)/.test(file)) {
-        return yaml.load(res);
-      }
-
-      return JSON.parse(res);
-    });
-  }
-
-  static validate(json: OASDocument) {
-    if (json.swagger) {
-      throw new Error('Sorry, this module only supports OpenAPI definitions.');
-    }
-
-    // The `validate` method handles dereferencing for us.
-    return OpenAPIParser.validate(json, {
-      dereference: {
-        /**
-         * If circular `$refs` are ignored they'll remain in the API definition as `$ref: String`.
-         * This allows us to not only do easy circular reference detection but also stringify and
-         * save dereferenced API definitions back into the cache directory.
-         */
-        circular: 'ignore',
-      },
-    }).catch(err => {
-      if (/is not a valid openapi definition/i.test(err.message)) {
-        throw new Error("Sorry, that doesn't look like a valid OpenAPI definition.");
-      }
-
-      throw err;
-    });
-  }
-}

package/src/lib/prompt.ts

@@ -1,29 +0,0 @@
-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/logger.ts

@@ -1,10 +0,0 @@
-/* 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/packageInfo.ts

@@ -1,3 +0,0 @@
-// This file is automatically updated by the build script.
-export const PACKAGE_NAME = 'api';
-export const PACKAGE_VERSION = '7.0.0-beta.0';