@ir-kit/spec-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,38 @@
+# `@ir-kit/spec-loader`
+
+Universal spec loader for OpenAPI, AsyncAPI, and TypeSpec. Detects format by extension + content sniff and dispatches to the matching per-format loader, returning a discriminated `{ kind, document }` result.
+
+Part of [ir-kit](https://github.com/ir-kit/ir-kit).
+
+## Install
+
+```sh
+npm install @ir-kit/spec-loader
+```
+
+## Usage
+
+```ts
+import { loadSpec } from "@ir-kit/spec-loader";
+
+const result = await loadSpec({ input: "./api.yaml" });
+//   result.kind:     "openapi" | "asyncapi"
+//   result.document: parsed OpenAPI object or AsyncAPIDocumentInterface
+```
+
+TypeSpec input (`.tsp`) compiles to OpenAPI 3 in-memory and returns as `{ kind: "openapi" }`. Pre-parsed objects pass through and are classified by their top-level `asyncapi` / `openapi` / `swagger` key.
+
+## API
+
+| Export                                                       | Description                                     |
+| ------------------------------------------------------------ | ----------------------------------------------- |
+| `loadSpec(opts)`                                             | Detect + dispatch + return `{ kind, document }` |
+| `loadOpenAPI`, `loadAsyncAPI`, `compileTypespec`             | Re-exports from each per-format loader          |
+| `resolveOpenAPIInput`, `isTypespecPath`                      | Utility helpers                                 |
+| `SpecKind`, `SpecInput`, `LoadSpecOptions`, `LoadSpecResult` | Public types                                    |
+
+Per-format loaders ship as separate packages — `@ir-kit/openapi-loader`, `@ir-kit/asyncapi-loader`, `@ir-kit/typespec-loader` — if you want a smaller dependency footprint and only need one format.
+
+## Why a wrapper
+
+Every consumer in ir-kit (codegen, docs, diff, recon) needs the same input-handling logic: paths vs URLs vs pre-parsed objects, format detection, `$ref` bundling. Centralizing it here removes that boilerplate from every downstream package.

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import type { AsyncAPIDocumentInterface } from "@asyncapi/parser";
+import { type AsyncAPIInput, type LoadAsyncAPIOptions, loadAsyncAPI } from "@ir-kit/asyncapi-loader";
+import { type LoadOpenAPIOptions, loadOpenAPI, type OpenAPIInput, resolveOpenAPIInput } from "@ir-kit/openapi-loader";
+import { type CompileTypespecOptions, compileTypespec, isTypespecPath } from "@ir-kit/typespec-loader";
+export type { AsyncAPIInput, LoadAsyncAPIOptions, LoadOpenAPIOptions, OpenAPIInput, };
+export { compileTypespec, isTypespecPath, loadAsyncAPI, loadOpenAPI, resolveOpenAPIInput, };
+export type SpecKind = "openapi" | "asyncapi" | "typespec";
+export type SpecInput = string | Record<string, unknown> | AsyncAPIDocumentInterface;
+export interface LoadSpecOptions extends CompileTypespecOptions {
+    input: SpecInput;
+    /** Force the spec kind, skipping detection. Useful when the file
+     *  extension is ambiguous (e.g. `api.json` that's actually AsyncAPI). */
+    kind?: SpecKind;
+    /** Forwarded to `loadOpenAPI` (and to TypeSpec after compile). */
+    normalize?: LoadOpenAPIOptions["normalize"];
+}
+export type LoadSpecResult = {
+    kind: "openapi";
+    document: Record<string, unknown>;
+} | {
+    kind: "asyncapi";
+    document: AsyncAPIDocumentInterface;
+};
+/**
+ * Detect the spec format and dispatch to the matching per-format loader.
+ * TypeSpec inputs compile to OpenAPI 3 in-memory and return as
+ * `{ kind: "openapi" }`. Pre-parsed objects are kept as-is and
+ * classified by the `asyncapi` / `openapi` / `swagger` top-level key.
+ */
+export declare function loadSpec(opts: LoadSpecOptions): Promise<LoadSpecResult>;
+//# 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":"AAGA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,YAAY,EACb,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,kBAAkB,EACvB,WAAW,EACX,KAAK,YAAY,EACjB,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,sBAAsB,EAC3B,eAAe,EACf,cAAc,EACf,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,GACb,CAAC;AACF,OAAO,EACL,eAAe,EACf,cAAc,EACd,YAAY,EACZ,WAAW,EACX,mBAAmB,GACpB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE3D,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvB,yBAAyB,CAAC;AAE9B,MAAM,WAAW,eAAgB,SAAQ,sBAAsB;IAC7D,KAAK,EAAE,SAAS,CAAC;IACjB;6EACyE;IACzE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,kEAAkE;IAClE,SAAS,CAAC,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC;CAC7C;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAE9D;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA0C7E"}

package/dist/index.js

@@ -0,0 +1,89 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { loadAsyncAPI, } from "@ir-kit/asyncapi-loader";
+import { loadOpenAPI, resolveOpenAPIInput, } from "@ir-kit/openapi-loader";
+import { compileTypespec, isTypespecPath, } from "@ir-kit/typespec-loader";
+export { compileTypespec, isTypespecPath, loadAsyncAPI, loadOpenAPI, resolveOpenAPIInput, };
+/**
+ * Detect the spec format and dispatch to the matching per-format loader.
+ * TypeSpec inputs compile to OpenAPI 3 in-memory and return as
+ * `{ kind: "openapi" }`. Pre-parsed objects are kept as-is and
+ * classified by the `asyncapi` / `openapi` / `swagger` top-level key.
+ */
+export async function loadSpec(opts) {
+    const kind = opts.kind ?? (await detectKind(opts.input, opts.cwd));
+    if (kind === "typespec") {
+        const path = typeof opts.input === "string" ? opts.input : "";
+        if (!path) {
+            throw new Error("TypeSpec input must be a file path ending in .tsp");
+        }
+        const { document } = await compileTypespec({ path }, opts);
+        return {
+            kind: "openapi",
+            document: document,
+        };
+    }
+    if (kind === "asyncapi") {
+        if (typeof opts.input !== "string" && !isAsyncAPIDocument(opts.input)) {
+            throw new Error("asyncapi input must be a string path/URL or an AsyncAPIDocumentInterface");
+        }
+        const document = await loadAsyncAPI({
+            input: opts.input,
+            cwd: opts.cwd,
+        });
+        return { kind: "asyncapi", document };
+    }
+    if (typeof opts.input !== "string" &&
+        !isPlainOpenAPIObject(opts.input)) {
+        throw new Error("openapi input must be a string path/URL or a plain object");
+    }
+    const document = await loadOpenAPI({
+        input: opts.input,
+        cwd: opts.cwd,
+        normalize: opts.normalize,
+    });
+    return { kind: "openapi", document };
+}
+async function detectKind(input, cwd) {
+    if (typeof input !== "string") {
+        return isAsyncAPIDocument(input) ? "asyncapi" : "openapi";
+    }
+    const str = input;
+    if (/\.tsp$/i.test(str.trim()))
+        return "typespec";
+    const trimmed = str.trim();
+    if (/^https?:\/\//i.test(trimmed)) {
+        return sniffKindFromString(await fetchHead(trimmed));
+    }
+    const path = isAbsolute(trimmed)
+        ? trimmed
+        : resolve(cwd ?? process.cwd(), trimmed);
+    return sniffKindFromString(await readFile(path, "utf8"));
+}
+function sniffKindFromString(text) {
+    const head = text.slice(0, 2048);
+    if (/(^|\n)\s*"?asyncapi"?\s*:/.test(head))
+        return "asyncapi";
+    if (/(^|\n)\s*"?openapi"?\s*:/.test(head))
+        return "openapi";
+    if (/(^|\n)\s*"?swagger"?\s*:/.test(head))
+        return "openapi";
+    return "openapi";
+}
+async function fetchHead(url) {
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
+    }
+    return res.text();
+}
+function isAsyncAPIDocument(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.json === "function" &&
+        typeof value.version === "function");
+}
+function isPlainOpenAPIObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@ir-kit/spec-loader",
+  "version": "0.2.0",
+  "description": "Universal spec loader for OpenAPI, AsyncAPI, and TypeSpec. Detects format by extension + content sniff and dispatches to the per-format loader, returning a discriminated `{ kind, document }` result.",
+  "keywords": [
+    "openapi",
+    "asyncapi",
+    "typespec",
+    "loader",
+    "spec",
+    "ir-kit"
+  ],
+  "homepage": "https://github.com/ir-kit/ir-kit/tree/main/packages/shared/spec-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/shared/spec-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
+  },
+  "peerDependencies": {
+    "@asyncapi/parser": "^3.6.0"
+  },
+  "dependencies": {
+    "@ir-kit/asyncapi-loader": "0.2.0",
+    "@ir-kit/openapi-loader": "0.2.0",
+    "@ir-kit/typespec-loader": "0.2.0"
+  },
+  "devDependencies": {
+    "@asyncapi/parser": "^3.6.0",
+    "@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"
+  }
+}