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

package/dist/storage.js

@@ -0,0 +1,226 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const make_dir_1 = __importDefault(require("make-dir"));
+const ssri_1 = __importDefault(require("ssri"));
+const validate_npm_package_name_1 = __importDefault(require("validate-npm-package-name"));
+const fetcher_1 = __importDefault(require("./fetcher"));
+const packageInfo_1 = require("./packageInfo");
+class Storage {
+    static dir;
+    static lockfile;
+    /**
+     * This is the original source that the file came from (relative/absolute file path, URL, ReadMe
+     * registry UUID, etc.).
+     */
+    source;
+    identifier;
+    fetcher;
+    constructor(source, identifier) {
+        Storage.setStorageDir();
+        this.fetcher = new fetcher_1.default(source);
+        this.source = source;
+        if (identifier) {
+            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 node_path_1.default.join(Storage.dir, 'api.json');
+    }
+    static getAPIsDir() {
+        return node_path_1.default.join(Storage.dir, 'apis');
+    }
+    static setStorageDir(dir) {
+        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 = make_dir_1.default.sync(node_path_1.default.join(process.cwd(), '.api'));
+        make_dir_1.default.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 node_fs_1.default.promises.writeFile(Storage.getLockfilePath(), JSON.stringify(Storage.getDefaultLockfile(), null, 2));
+        }
+        if (Storage.getAPIsDir()) {
+            await node_fs_1.default.promises.rm(Storage.getAPIsDir(), { recursive: true });
+            await node_fs_1.default.promises.mkdir(Storage.getAPIsDir(), { recursive: true });
+        }
+    }
+    static getDefaultLockfile() {
+        return {
+            version: '1.0',
+            apis: [],
+        };
+    }
+    static generateIntegrityHash(definition) {
+        return ssri_1.default
+            .fromData(JSON.stringify(definition), {
+            algorithms: ['sha512'],
+        })
+            .toString();
+    }
+    static getLockfile() {
+        if (typeof Storage.lockfile === 'object') {
+            return Storage.lockfile;
+        }
+        if (node_fs_1.default.existsSync(Storage.getLockfilePath())) {
+            const file = node_fs_1.default.readFileSync(Storage.getLockfilePath(), 'utf8');
+            Storage.lockfile = JSON.parse(file);
+        }
+        else {
+            Storage.lockfile = Storage.getDefaultLockfile();
+        }
+        return Storage.lockfile;
+    }
+    static isIdentifierValid(identifier, prefixWithAPINamespace) {
+        // Is this identifier already in storage?
+        if (Storage.isInLockFile({ identifier })) {
+            throw new Error(`"${identifier}" is already taken in your \`.api/\` directory. Please try another identifier.`);
+        }
+        const isValidForNPM = (0, validate_npm_package_name_1.default)(prefixWithAPINamespace ? `@api/${identifier}` : identifier);
+        if (!isValidForNPM.validForNewPackages) {
+            // `prompts` doesn't support surfacing multiple errors in a `validate` call so we can only
+            // surface the first to the user.
+            throw new Error(`Identifier cannot be used for an NPM package: ${isValidForNPM?.errors?.[0] || '[error unavailable]'}`);
+        }
+        return true;
+    }
+    static isInLockFile(search) {
+        // 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) {
+        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 node_path_1.default.join(Storage.getAPIsDir(), this.identifier);
+    }
+    getAPIDefinition() {
+        const file = node_fs_1.default.readFileSync(node_path_1.default.join(this.getIdentifierStorageDir(), 'openapi.json'), 'utf8');
+        return JSON.parse(file);
+    }
+    saveSourceFiles(files) {
+        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 = [];
+            Object.entries(files).forEach(([fileName, contents]) => {
+                const sourceFilePath = node_path_1.default.join(this.getIdentifierStorageDir(), fileName);
+                node_fs_1.default.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
+     *
+     */
+    save(spec) {
+        if (!this.identifier) {
+            throw new TypeError('An identifier must be set before saving the API definition into storage.');
+        }
+        // Create our main `.api/` directory.
+        if (!node_fs_1.default.existsSync(Storage.dir)) {
+            node_fs_1.default.mkdirSync(Storage.dir, { recursive: true });
+        }
+        // Create the `.api/apis/` diretory where we'll be storing API definitions.
+        if (!node_fs_1.default.existsSync(Storage.getAPIsDir())) {
+            node_fs_1.default.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 = node_path_1.default.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 (!node_fs_1.default.existsSync(identifierStorageDir)) {
+                node_fs_1.default.mkdirSync(identifierStorageDir, { recursive: true });
+            }
+            Storage.lockfile.apis.push({
+                identifier: this.identifier,
+                source: this.source,
+                integrity: Storage.generateIntegrityHash(spec),
+                installerVersion: packageInfo_1.PACKAGE_VERSION,
+            });
+            node_fs_1.default.writeFileSync(node_path_1.default.join(identifierStorageDir, 'openapi.json'), saved);
+            node_fs_1.default.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;
+    }
+}
+exports.default = Storage;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api",
-  "version": "7.0.0-alpha.0",
+  "version": "7.0.0-alpha.2",
   "description": "Magical SDK generation from an OpenAPI definition 🪄",
   "bin": {
     "api": "./bin/api"
@@ -47,8 +47,8 @@
     "lodash.deburr": "^4.1.0",
     "lodash.setwith": "^4.3.2",
     "lodash.startcase": "^4.4.0",
-    "make-dir": "^3.1.0",
-    "oas": "^20.4.0",
+    "make-dir": "^4.0.0",
+    "oas": "^22.0.0",
     "ora": "^5.4.1",
     "prompts": "^2.4.2",
     "semver": "^7.3.8",
@@ -57,7 +57,8 @@
     "validate-npm-package-name": "^5.0.0"
   },
   "devDependencies": {
-    "@api/test-utils": "file:../test-utils",
+    "@api/test-utils": "^7.0.0-alpha.2",
+    "@readme/api-core": "^7.0.0-alpha.2",
     "@readme/oas-examples": "^5.12.0",
     "@types/js-yaml": "^4.0.5",
     "@types/lodash.camelcase": "^4.3.7",
@@ -69,13 +70,13 @@
     "@types/ssri": "^7.1.1",
     "@types/validate-npm-package-name": "^4.0.0",
     "@vitest/coverage-v8": "^0.34.4",
-    "api.core": "file:../core",
     "fetch-mock": "^9.11.0",
-    "oas-normalize": "^8.3.2",
+    "oas-normalize": "^11.0.0",
     "type-fest": "^4.3.1",
     "typescript": "^5.2.2",
     "unique-temp-dir": "^1.0.0",
-    "vitest": "^0.34.1"
+    "vitest": "^0.34.5"
   },
-  "prettier": "@readme/eslint-config/prettier"
+  "prettier": "@readme/eslint-config/prettier",
+  "gitHead": "fae2070b68d3f73bad20c92e112d41b4d5875ede"
 }

package/src/codegen/languages/typescript.ts

@@ -1,8 +1,8 @@
 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 Operation from 'oas/operation';
+import type { HttpMethods, SchemaObject } from 'oas/rmoas.types';
 import type { SemVer } from 'semver';
 import type {
   ClassDeclaration,
@@ -86,7 +86,7 @@ export default class TSGenerator extends CodeGeneratorLanguage {
 
     this.requiredPackages = {
       api: {
-        reason: "Required for the `api.core` library that the codegen'd SDK uses for making requests.",
+        reason: "Required for the `@readme/api-core` library that the codegen'd SDK uses for making requests.",
         url: 'https://npm.im/api',
       },
       'json-schema-to-ts': {
@@ -94,7 +94,7 @@ export default class TSGenerator extends CodeGeneratorLanguage {
         url: 'https://npm.im/json-schema-to-ts',
       },
       oas: {
-        reason: 'Used within `api.core` and is also loaded for TypeScript types.',
+        reason: 'Used within `@readme/api-core` and is also loaded for TypeScript types.',
         url: 'https://npm.im/oas',
       },
     };
@@ -229,7 +229,7 @@ export default class TSGenerator extends CodeGeneratorLanguage {
       sdkSource
         .getImportDeclarations()
         .find(id => id.getText().includes('HTTPMethodRange'))
-        ?.replaceWithText("import type { ConfigOptions, FetchResponse } from 'api.core';");
+        ?.replaceWithText("import type { ConfigOptions, FetchResponse } from '@readme/api-core';");
     }
 
     if (this.outputJS) {
@@ -300,10 +300,10 @@ export default class TSGenerator extends CodeGeneratorLanguage {
       {
         // `HTTPMethodRange` will be conditionally removed later if it ends up not being used.
         defaultImport: 'type { ConfigOptions, FetchResponse, HTTPMethodRange }',
-        moduleSpecifier: 'api.core',
+        moduleSpecifier: '@readme/api-core',
       },
       { defaultImport: 'Oas', moduleSpecifier: 'oas' },
-      { defaultImport: 'APICore', moduleSpecifier: 'api.core' },
+      { defaultImport: 'APICore', moduleSpecifier: '@readme/api-core' },
       { defaultImport: 'definition', moduleSpecifier: this.specPath },
     ]);
 
@@ -710,7 +710,7 @@ sdk.server('https://eu.api.example.com/v14');`),
       // our `metadata` parameter is actually required for this operation this is the only way we're
       // able to have an optional `body` parameter be present before `metadata`.
       //
-      // Thankfully our core fetch work in `api.core` is able to do the proper determination to
+      // Thankfully our core fetch work in `@readme/api-core` is able to do the proper determination to
       // see if what the user is supplying is `metadata` or `body` content when they supply one or
       // both.
       operationIdAccessor.addParameters([

package/src/fetcher.ts

@@ -1,4 +1,4 @@
-import type { OASDocument } from 'oas/dist/rmoas.types';
+import type { OASDocument } from 'oas/rmoas.types';
 
 import fs from 'node:fs';
 import path from 'node:path';

package/src/packageInfo.ts

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

package/src/storage.ts

@@ -1,4 +1,4 @@
-import type { OASDocument } from 'oas/dist/rmoas.types';
+import type { OASDocument } from 'oas/rmoas.types';
 
 import fs from 'node:fs';
 import path from 'node:path';

package/tsconfig.json

@@ -5,8 +5,10 @@
     "declaration": true,
     "esModuleInterop": true,
     "lib": ["DOM", "DOM.Iterable", "ES2020"],
+    "module": "NodeNext",
     "noImplicitAny": true,
     "outDir": "dist/",
+    "skipLibCheck": true,
     "strict": true,
     "useUnknownInCatchVariables": false
   },