OAS Kit Common Utilities

Common errors

• TypeError: (0, _doOasKitCommon.sanitise) is not a function

  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.
  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.

• Schema 'MySchema' not found in spec.

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install do-oas-kit-common npm
• yarn add do-oas-kit-common yarn
• pnpm add do-oas-kit-common pnpm

Imports

• sanitise
  wrong:

  const { sanitise } = require('do-oas-kit-common');

  correct:

  import { sanitise } from 'do-oas-kit-common';

  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.
• throwOrWarn
  wrong:

  const throwOrWarn = require('do-oas-kit-common').throwOrWarn;

  correct:

  import { throwOrWarn } from 'do-oas-kit-common';

  This utility provides consistent error or warning handling across the `oas-kit` family, abstracting away conditional logging or exception throwing based on configuration.
• resolveRefPath
  wrong:

  import resolveRefPath from 'do-oas-kit-common/lib/resolveRefPath'; // Incorrect path, likely not a default export

  correct:

  import { resolveRefPath } from 'do-oas-kit-common';

  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.

Quickstart

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.

import { sanitise, throwOrWarn } from 'do-oas-kit-common';

const openApiSpec = {
  openapi: '3.0.0',
  info: { title: 'Example API', version: '1.0.0' },
  paths: {},
  components: {
    schemas: {
      'User-Profile': {
        type: 'object',
        properties: { id: { type: 'string' } },
      },
    },
  },
};

function processSchema(spec, schemaName) {
  const originalName = schemaName;
  const cleanName = sanitise(originalName);
  
  if (cleanName !== originalName) {
    console.warn(`Sanitized schema name from '${originalName}' to '${cleanName}'.`);
  }
  
  const schema = spec.components.schemas[cleanName];
  if (!schema) {
    throwOrWarn(`Schema '${cleanName}' not found in spec.`, spec, { severity: 'error' });
    return null;
  }
  console.log(`Successfully processed schema: ${cleanName}`);
  return schema;
}

try {
  const userProfileSchema = processSchema(openApiSpec, 'User-Profile');
  console.log('User Profile Schema:', userProfileSchema);

  // Example of a missing schema, triggering a warning/error
  processSchema(openApiSpec, 'NonExistentSchema');
} catch (e) {
  console.error('An error occurred:', e.message);
}

// For CommonJS environments:
// const { sanitise, throwOrWarn } = require('do-oas-kit-common');
// ... rest of the code as above ...