@trojs/openapi-dereference 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TroJS
+
+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,54 @@
+# OpenAPI dereference
+
+[![NPM version][npm-image]][npm-url] [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-dereference&metric=coverage)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-dereference) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-dereference&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-dereference) 
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-dereference&metric=bugs)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-dereference) [![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-dereference&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-dereference) [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-dereference&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-dereference) [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-dereference&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-dereference)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-dereference&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-dereference) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-dereference&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-dereference) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=hckrnews_openapi-dereference&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=hckrnews_openapi-dereference)
+
+Dereference $ref pointers in JSONSchema or OpenAPI documents.
+
+Zero dependencies. Synchronous core. Handles circular refs.
+
+## Installation
+
+`npm install @trojs/openapi-dereference`
+or
+`yarn add @trojs/openapi-dereference`
+
+## Test the package
+
+`npm run test`
+or
+`yarn test`
+
+## How to use
+
+
+```javascript
+npm i @trojs/openapi-dereference
+
+```
+
+```javascript
+import { dereferenceSync } from '@trojs/openapi-dereference';
+
+const schemaWithRefs = {
+  schemas: {
+    Person: {
+      type: 'object',
+      properties: {
+        name: {
+          $ref: '#/schemas/Name',
+        },
+      },
+    },
+    Name: {
+      type: 'string',
+    },
+  },
+};
+
+const schemaWithNoRefs = dereferenceSync(schemaWithRefs);
+```
+
+[npm-url]: https://www.npmjs.com/package/@trojs/openapi-dereference
+[npm-image]: https://img.shields.io/npm/v/@trojs/openapi-dereference.svg

package/package.json

@@ -0,0 +1,66 @@
+{
+    "name": "@trojs/openapi-dereference",
+    "description": "OpenAPI dereference",
+    "version": "0.2.0",
+    "author": {
+        "name": "Pieter Wigboldus",
+        "url": "https://trojs.org/"
+    },
+    "license": "MIT",
+    "scripts": {
+        "lint": "eslint src/*.js --config .eslintrc",
+        "lint:report": "eslint src/*.js --config .eslintrc -f json -o report.json",
+        "lint:fix": "eslint src/*.js --config .eslintrc --fix",
+        "lint:rules": "eslint --print-config file.js > eslintconfig.json",
+        "test": "c8 node --test src/*.test.js",
+        "test:watch": "c8 node --watch --test src/*.test.js",
+        "cpd": "node_modules/jscpd/bin/jscpd src",
+        "vulnerabilities": "npm audit --omit=dev"
+    },
+    "type": "module",
+    "files": [
+        "src/dereference.js",
+        "src/index.js",
+        "src/klona.js",
+        "src/resolveRef.js",
+        "src/types.d.ts"
+    ],
+    "main": "src/index.js",
+    "types": "src/types.d.ts",
+    "devDependencies": {
+        "@hckrnews/eslint-config": "^3.0.0",
+        "c8": "^9.0.0",
+        "eslint": "^8.23.0",
+        "eslint-config-standard": "^17.1.0",
+        "eslint-plugin-import": "^2.26.0",
+        "eslint-plugin-jsdoc": "^48.0.0",
+        "eslint-plugin-n": "^16.0.0",
+        "eslint-plugin-promise": "^6.0.1",
+        "eslint-plugin-sonarjs": "^0.24.0",
+        "jscpd": "^3.2.1",
+        "json-schema": "^0.4.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/hckrnews/openapi-dereference"
+    },
+    "engines": {
+        "node": ">= 18.13"
+    },
+    "keywords": [
+        "openapi",
+        "model",
+        "entity",
+        "schema",
+        "specification",
+        "api",
+        "ajv",
+        "dereference",
+        "reference",
+        "ref"
+    ],
+    "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/w3nl"
+    }
+}

package/src/dereference.js

@@ -0,0 +1,58 @@
+/* eslint-disable sonarjs/cognitive-complexity */
+/* eslint-disable no-param-reassign */
+/* eslint-disable no-restricted-syntax */
+import { klona } from './klona.js'
+import { resolveRefSync } from './resolveRef.js'
+
+/**
+ * @typedef {import('./types').JSONSchema} JSONSchema
+ * @typedef {import('./types').DereferencedJSONSchema} DereferencedJSONSchema
+ */
+
+const cache = new Map()
+
+/**
+ * Resolves all $ref pointers in a schema and returns a new schema without any $ref pointers.
+ * @param {JSONSchema} schema
+ * @returns {DereferencedJSONSchema}
+ */
+export const dereferenceSync = (schema) => {
+  if (cache.has(schema)) {
+    return cache.get(schema)
+  }
+
+  const visitedNodes = new Set()
+  const cloned = klona(schema)
+
+  const resolve = (current, path) => {
+    if (typeof current === 'object' && current !== null) {
+      // make sure we don't visit the same node twice
+      if (visitedNodes.has(current)) {
+        return current
+      }
+      visitedNodes.add(current)
+
+      if (Array.isArray(current)) {
+        // array
+        for (let index = 0; index < current.length; index++) {
+          current[index] = resolve(current[index], `${path}/${index}`)
+        }
+      } else {
+        // object
+        if ('$ref' in current && typeof current.$ref === 'string') {
+          return resolveRefSync(cloned, current.$ref)
+        }
+
+        for (const key in current) {
+          current[key] = resolve(current[key], `${path}/${key}`)
+        }
+      }
+    }
+
+    return current
+  }
+
+  const result = resolve(cloned, '#')
+  cache.set(schema, result)
+  return result
+}

package/src/index.js

@@ -0,0 +1,6 @@
+/**
+ * @typedef {import('./types').JSONSchema} JSONSchema
+ * @typedef {import('./types').DereferencedJSONSchema} DereferencedJSONSchema
+ */
+export * from './dereference.js'
+export * from './resolveRef.js'

package/src/klona.js

@@ -0,0 +1,37 @@
+/* eslint-disable sonarjs/cognitive-complexity */
+/* eslint-disable no-restricted-syntax */
+/**
+ * klona/json - MIT License
+ *
+ * https://github.com/lukeed/klona/blob/master/license
+ * @param {any} val
+ * @returns {any}
+ */
+export function klona (val) {
+  let index, out, tmp
+
+  if (Array.isArray(val)) {
+    out = Array((index = val.length))
+    while (index--) out[index] = (tmp = val[index]) && typeof tmp === 'object' ? klona(tmp) : tmp
+    return out
+  }
+
+  if (Object.prototype.toString.call(val) === '[object Object]') {
+    out = {} // null
+    for (index in val) {
+      if (index === '__proto__') {
+        Object.defineProperty(out, index, {
+          value: klona(val[index]),
+          configurable: true,
+          enumerable: true,
+          writable: true
+        })
+      } else {
+        out[index] = (tmp = val[index]) && typeof tmp === 'object' ? klona(tmp) : tmp
+      }
+    }
+    return out
+  }
+
+  return val
+}

package/src/resolveRef.js

@@ -0,0 +1,37 @@
+/**
+ * @typedef {import('./types').JSONSchema} JSONSchema
+ * @typedef {import('./types').DereferencedJSONSchema} DereferencedJSONSchema
+ */
+
+const cache = new Map()
+
+/**
+ * Resolves a $ref pointer in a schema and returns the referenced value.
+ * @param {JSONSchema} schema
+ * @param {string} ref
+ * @returns {unknown}
+ */
+export const resolveRefSync = (schema, ref) => {
+  if (!cache.has(schema)) {
+    cache.set(schema, new Map())
+  }
+  const schemaCache = cache.get(schema)
+
+  if (schemaCache.has(ref)) {
+    return schemaCache.get(ref)
+  }
+
+  const path = ref.split('/').slice(1)
+
+  let current = schema
+  for (const segment of path) {
+    if (!current || typeof current !== 'object') {
+      // we've reached a dead end
+      current = null
+    }
+    current = current[segment] ?? null
+  }
+
+  schemaCache.set(ref, current)
+  return current
+}

package/src/types.d.ts

@@ -0,0 +1,29 @@
+import { JSONSchema4, JSONSchema4Type, JSONSchema6, JSONSchema6Type } from 'json-schema';
+
+export type JSONSchema = Prettify<JSONSchema4 | JSONSchema6>;
+export type JSONSchemaType = Prettify<JSONSchema4Type | JSONSchema6Type>;
+export type DereferencedJSONSchema = Prettify<DeepOmit<JSONSchema, '$ref'>>;
+
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+};
+
+type Primitive = string | Function | number | boolean | Symbol | undefined | null;
+
+type DeepOmitArray<T extends any[], K> = {
+    [P in keyof T]: DeepOmit<T[P], K>;
+};
+
+type DeepOmit<T, K> = T extends Primitive
+    ? T
+    : {
+        [P in Exclude<keyof T, K>]: T[P] extends infer TP
+        ? TP extends Primitive
+        ? TP // leave primitives and functions alone
+        : TP extends any[]
+        ? DeepOmitArray<TP, K> // Array special handling
+        : DeepOmit<TP, K>
+        : never;
+    };
+
+export const dereferenceSync: (schema: JSONSchema) => DereferencedJSONSchema