OAS Kit Common Utilities

Common errors

• TypeError: common.sanitise is not a function

  cause Attempting to use `common.sanitise` after a default CommonJS import, or incorrect destructuring.
  fix For CommonJS, use `const { sanitise } = require('oas-kit-common');` if `sanitise` is a named export, or access it directly if `require('oas-kit-common')` returns an object with `sanitise` as a property. For ESM, ensure `import { sanitise } from 'oas-kit-common';`.

• Error: Cannot find module 'oas-kit-common'

  cause The package `oas-kit-common` is not installed in the project's `node_modules`.
  fix Run `npm install oas-kit-common` or `yarn add oas-kit-common` to install the package.

• Property 'mergeDeep' does not exist on type 'typeof import("oas-kit-common")'.

  cause TypeScript error indicating `mergeDeep` is not recognized as an export. This usually means a typo, or missing/incorrect type definitions, or that the function is not actually exported.
  fix Double-check the function name for typos. If the function name is correct, verify that `mergeDeep` is indeed an exported member of `oas-kit-common` by reviewing the library's documentation or source code. If using an older version, update to the latest stable release which might include new exports or improved types.

Warnings

• gotcha As a component of the `oas-kit` mono-repository, `oas-kit-common`'s behavior or compatibility can be implicitly affected by major version changes in sibling packages like `swagger2openapi` or `oas-resolver`. Ensure all `oas-kit` packages are kept to compatible versions to avoid unexpected issues, especially when core parsing or resolution logic is updated.
  Fix: Always install `oas-kit-common` alongside other `oas-kit` packages at their recommended or most recent compatible versions. Refer to the `Mermade/oas-kit` mono-repo changelog for cross-package compatibility notes.
• gotcha Older codebases or projects within the `oas-kit` ecosystem may still use CommonJS `require()`. While `oas-kit-common` generally supports both, inconsistent module syntax within a single project can lead to bundler or runtime errors. Prefer ES Modules (`import`) where possible.
  Fix: Standardize on ES Modules (`import ... from 'oas-kit-common'`) for new code. For existing CommonJS code, ensure `const { functionName } = require('oas-kit-common');` is used correctly for named exports, rather than attempting `require('oas-kit-common').default`.
• gotcha The `oas-kit-common` package provides generic utilities, but specific OpenAPI version compatibility (e.g., OpenAPI 2.0 vs. 3.0/3.1) is often handled by higher-level packages like `swagger2openapi`. Direct use of `oas-kit-common` utilities might not automatically enforce spec-specific rules.
  Fix: When dealing with version-specific OpenAPI definitions, combine `oas-kit-common` utilities with the appropriate validator (`oas-validator`) or converter (`swagger2openapi`) from the `oas-kit` suite to ensure full specification compliance and correct transformations.

Install

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

Imports

• sanitise
  wrong:

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

  correct:

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

  While CommonJS `require` is technically supported, ESM `import` is the recommended and modern approach. The `sanitise` function is a known export used for processing component names and references within OpenAPI documents.
• mergeDeep
  wrong:

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

  correct:

  import { mergeDeep } from 'oas-kit-common';

  This utility is inferred as a common helper for deeply merging JavaScript objects, a frequent operation when combining or transforming parts of an OpenAPI definition. Named imports are preferred for clarity.
• isObject
  wrong:

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

  correct:

  import { isObject } from 'oas-kit-common';

  A basic type-checking utility common in libraries dealing with complex data structures like OpenAPI specifications. Consistent named imports are recommended.

Quickstart

This quickstart demonstrates importing and using key utility functions like `sanitise` for cleaning strings for OpenAPI component names and `mergeDeep` for combining OpenAPI-like JavaScript objects, showing how `oas-kit-common` facilitates common manipulation tasks.

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

const originalObject = {
  paths: {
    '/users': { get: { operationId: 'getUsers' } },
  },
  components: {
    schemas: {
      'Foo Bar': { type: 'object' }
    }
  }
};

const updates = {
  paths: {
    '/users': { post: { operationId: 'createUser' } }
  }
};

// Example 1: Sanitizing a string for use as an OpenAPI component name
const dirtyName = 'My Awesome Component Name';
const cleanName = sanitise(dirtyName);
console.log(`Original: "${dirtyName}", Sanitized: "${cleanName}"`);

// Example 2: Deeply merging two OpenAPI-like objects
const mergedObject = mergeDeep({}, originalObject, updates);
console.log('Merged Object:', JSON.stringify(mergedObject, null, 2));

// Example 3: Demonstrate sanitization in context of object modification
const schemaName = 'Foo Bar';
const sanitizedSchemaName = sanitise(schemaName);
const modifiedObject = {
  ...originalObject,
  components: {
    schemas: {
      [sanitizedSchemaName]: originalObject.components.schemas[schemaName]
    }
  }
};
console.log('Modified Object with Sanitized Schema Name:', JSON.stringify(modifiedObject, null, 2));