@ir-kit/openapi-loader 0.2.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ahmed Rowaihi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# `@ir-kit/openapi-loader`
+
+Load an OpenAPI 3.x spec from a file path, URL, or pre-parsed object. Bundles `$ref`s via `@hey-api/json-schema-ref-parser` and runs optional hey-api-aware normalization.
+
+Part of [ir-kit](https://github.com/ir-kit/ir-kit). For multi-format input (OpenAPI + AsyncAPI + TypeSpec under one API), reach for [`@ir-kit/spec-loader`](../../shared/spec-loader) instead.
+
+## Install
+
+```sh
+npm install @ir-kit/openapi-loader
+```
+
+## Usage
+
+```ts
+import { loadOpenAPI } from "@ir-kit/openapi-loader";
+
+const spec = await loadOpenAPI({
+  input: "./petstore.yaml", // path, URL, or pre-parsed object
+  normalize: true, // optional hey-api normalization
+});
+```
+
+## API
+
+| Export                               | Description                                                  |
+| ------------------------------------ | ------------------------------------------------------------ |
+| `loadOpenAPI(opts)`                  | Bundle `$ref`s, optionally normalize, return the spec        |
+| `resolveOpenAPIInput(input, cwd?)`   | Resolve a string input to an absolute path / URL passthrough |
+| `OpenAPIInput`, `LoadOpenAPIOptions` | Public types                                                 |
+
+`normalize: true` applies the safe preset (`SAFE_NORMALIZE` from `@ir-kit/openapi`). Pass a `NormalizeOptions` object to customize.

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { type NormalizeOptions } from "@ir-kit/openapi";
+export type OpenAPIInput = string | Record<string, unknown>;
+export interface LoadOpenAPIOptions {
+    input: OpenAPIInput;
+    cwd?: string;
+    /** Apply hey-api-aware normalization after bundling. `true` enables
+     *  the safe preset; pass an object for custom rules. */
+    normalize?: boolean | NormalizeOptions;
+}
+export declare function loadOpenAPI(opts: LoadOpenAPIOptions): Promise<Record<string, unknown>>;
+export declare function resolveOpenAPIInput(input: OpenAPIInput, cwd?: string): OpenAPIInput;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,YAAY,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;4DACwD;IACxD,SAAS,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;CACxC;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAalC;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EACnB,GAAG,GAAE,MAAsB,GAC1B,YAAY,CASd"}

package/dist/index.js

@@ -0,0 +1,26 @@
+import { isAbsolute, resolve } from "node:path";
+import { $RefParser } from "@hey-api/json-schema-ref-parser";
+import { normalizeSpec, SAFE_NORMALIZE, } from "@ir-kit/openapi";
+export async function loadOpenAPI(opts) {
+    const bundled = (await new $RefParser().bundle({
+        pathOrUrlOrSchema: resolveOpenAPIInput(opts.input, opts.cwd),
+    }));
+    if (opts.normalize) {
+        normalizeSpec(bundled, opts.normalize === true ? SAFE_NORMALIZE : opts.normalize);
+    }
+    return bundled;
+}
+export function resolveOpenAPIInput(input, cwd = process.cwd()) {
+    if (typeof input !== "string")
+        return input;
+    const trimmed = input.trim();
+    if (trimmed === "") {
+        throw new Error("OpenAPI spec input is empty or only whitespace.");
+    }
+    if (/^https?:\/\//i.test(trimmed))
+        return trimmed;
+    if (isAbsolute(trimmed))
+        return trimmed;
+    return resolve(cwd, trimmed);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EAEL,aAAa,EACb,cAAc,GACf,MAAM,iBAAiB,CAAC;AAYzB,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAwB;IAExB,MAAM,OAAO,GAAG,CAAC,MAAM,IAAI,UAAU,EAAE,CAAC,MAAM,CAAC;QAC7C,iBAAiB,EAAE,mBAAmB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC;KAC7D,CAAC,CAA4B,CAAC;IAE/B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,aAAa,CACX,OAAO,EACP,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAC1D,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,KAAmB,EACnB,MAAc,OAAO,CAAC,GAAG,EAAE;IAE3B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAClD,IAAI,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IACxC,OAAO,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@ir-kit/openapi-loader",
+  "version": "0.2.0",
+  "description": "Load an OpenAPI 3.x spec from a file path, URL, or pre-parsed object. Bundles `$ref`s via `@hey-api/json-schema-ref-parser` and runs optional hey-api-aware normalization.",
+  "keywords": [
+    "openapi",
+    "loader",
+    "ref-parser",
+    "spec",
+    "ir-kit"
+  ],
+  "homepage": "https://github.com/ir-kit/ir-kit/tree/main/packages/openapi/loader",
+  "bugs": {
+    "url": "https://github.com/ir-kit/ir-kit/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Ahmed Rowaihi",
+    "email": "ahmedrowaihi@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ir-kit/ir-kit.git",
+    "directory": "packages/openapi/loader"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@hey-api/json-schema-ref-parser": "^1.4.1",
+    "@ir-kit/openapi": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "vitest": "^4.0.0",
+    "@ir-kit/tsconfig": "0.0.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}