{"id":14535,"library":"do-oas-kit-common","title":"OAS Kit Common Utilities","description":"The `do-oas-kit-common` package provides foundational utility functions intended to support operations within the broader `oas-kit` ecosystem, which focuses on converting, validating, resolving, and linting OpenAPI (OAS) and Swagger specifications. While the provided version is 1.0.10, the `oas-kit` monorepo and its constituent packages (including `oas-resolver` and `oas-linter`) appear to have had their last significant updates approximately five years ago. This suggests the library is in a maintenance state, with no active development or new feature releases to support the latest OpenAPI specification versions (e.g., OpenAPI 3.1.x) or modern JavaScript language features. It likely includes helpers for tasks such as sanitizing schema component names, resolving internal `$ref` paths, and common error handling within the context of OpenAPI document manipulation.","status":"maintenance","version":"1.0.10","language":"javascript","source_language":"en","source_url":"https://github.com/space-77/oas-kit","tags":["javascript","openapi","swagger","oas","utility"],"install":[{"cmd":"npm install do-oas-kit-common","lang":"bash","label":"npm"},{"cmd":"yarn add do-oas-kit-common","lang":"bash","label":"yarn"},{"cmd":"pnpm add do-oas-kit-common","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `oas-kit` project predates widespread ESM adoption. While ESM imports may work for modern environments via transpilation or bundlers, CJS `require` is likely the primary intended usage for stability given the project's age. This function is typically used for sanitizing strings, such as OpenAPI component names.","wrong":"const { sanitise } = require('do-oas-kit-common');","symbol":"sanitise","correct":"import { sanitise } from 'do-oas-kit-common';"},{"note":"This utility provides consistent error or warning handling across the `oas-kit` family, abstracting away conditional logging or exception throwing based on configuration.","wrong":"const throwOrWarn = require('do-oas-kit-common').throwOrWarn;","symbol":"throwOrWarn","correct":"import { throwOrWarn } from 'do-oas-kit-common';"},{"note":"Many internal utilities related to OpenAPI `$ref` resolution (e.g., manipulating JSON pointers or dereferencing paths) are likely exposed. This is an inferred name for such a common function.","wrong":"import resolveRefPath from 'do-oas-kit-common/lib/resolveRefPath'; // Incorrect path, likely not a default export","symbol":"resolveRefPath","correct":"import { resolveRefPath } from 'do-oas-kit-common';"}],"quickstart":{"code":"import { sanitise, throwOrWarn } from 'do-oas-kit-common';\n\nconst openApiSpec = {\n  openapi: '3.0.0',\n  info: { title: 'Example API', version: '1.0.0' },\n  paths: {},\n  components: {\n    schemas: {\n      'User-Profile': {\n        type: 'object',\n        properties: { id: { type: 'string' } },\n      },\n    },\n  },\n};\n\nfunction processSchema(spec, schemaName) {\n  const originalName = schemaName;\n  const cleanName = sanitise(originalName);\n  \n  if (cleanName !== originalName) {\n    console.warn(`Sanitized schema name from '${originalName}' to '${cleanName}'.`);\n  }\n  \n  const schema = spec.components.schemas[cleanName];\n  if (!schema) {\n    throwOrWarn(`Schema '${cleanName}' not found in spec.`, spec, { severity: 'error' });\n    return null;\n  }\n  console.log(`Successfully processed schema: ${cleanName}`);\n  return schema;\n}\n\ntry {\n  const userProfileSchema = processSchema(openApiSpec, 'User-Profile');\n  console.log('User Profile Schema:', userProfileSchema);\n\n  // Example of a missing schema, triggering a warning/error\n  processSchema(openApiSpec, 'NonExistentSchema');\n} catch (e) {\n  console.error('An error occurred:', e.message);\n}\n\n// For CommonJS environments:\n// const { sanitise, throwOrWarn } = require('do-oas-kit-common');\n// ... rest of the code as above ...\n","lang":"typescript","description":"This quickstart demonstrates sanitizing a schema name and using a unified error/warning utility, typical functions for an OpenAPI utility kit. It processes an example OpenAPI specification, sanitizes a component name, and handles potential missing schemas."},"warnings":[{"fix":"Evaluate compatibility with your target OpenAPI specification version and Node.js environment. Consider using more actively maintained alternatives if up-to-date specification support is critical.","message":"The `oas-kit` monorepo, which includes `do-oas-kit-common`, has not seen significant updates in approximately five years. This means it may lack support for newer OpenAPI specification versions (e.g., 3.1.x) and may not be compatible with the latest JavaScript language features or Node.js runtime versions.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Avoid Node.js 12.17.x-12.19.x; use a different LTS version of Node.js for running `oas-kit-common` or other `oas-kit` tools.","message":"The `oas-kit` documentation explicitly warns against using Node.js versions 12.17.x, 12.18.x, or 12.19.x due to a known `http2` bug. Although this applies to the broader `oas-kit` tools, it's a critical consideration for any package within the ecosystem.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For older Node.js versions or mixed environments, use `const { Name } = require('do-oas-kit-common');`. For modern ESM-only projects, ensure your build setup correctly handles CJS interop or consider if this library is suitable.","message":"As an older utility library, `do-oas-kit-common` likely relies primarily on CommonJS modules. Direct ESM imports might require bundler configuration or could lead to unexpected behavior in pure ESM environments without proper handling.","severity":"gotcha","affected_versions":"<=1.0.10"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"If running in a Node.js CJS environment, use `const { sanitise } = require('do-oas-kit-common');`. Ensure your build tools are correctly configured for CJS-ESM interop if using modern ESM syntax.","cause":"Attempting to use a named ESM import (`import { sanitise } from '...'`) in an environment that only recognizes CommonJS exports, or when a bundler fails to correctly transpile/resolve.","error":"TypeError: (0, _doOasKitCommon.sanitise) is not a function"},{"fix":"Verify the exact name and path of the schema in your OpenAPI document. Use `console.log` or `debugger` to inspect the `openApiSpec` object and confirm the expected structure and naming. Ensure any necessary sanitization (e.g., via `sanitise` function) is applied before lookup.","cause":"A utility function that expects a specific OpenAPI schema or component name could not locate it within the provided specification object. This might be due to a typo, incorrect path, or an un-sanitized name.","error":"Schema 'MySchema' not found in spec."}],"ecosystem":"npm"}