{"id":11474,"library":"oas-kit-common","title":"OAS Kit Common Utilities","description":"oas-kit-common is a foundational utility library within the larger `Mermade/oas-kit` mono-repository, providing a collection of reusable helper functions essential for working with OpenAPI (formerly Swagger) specifications. It serves as a dependency for other `oas-kit` packages such as `swagger2openapi`, `oas-validator`, and `oas-resolver`, offering core utilities for tasks like data sanitization, object manipulation, and type checking pertinent to OpenAPI document processing. The current stable version is `1.0.8`. As part of an actively maintained ecosystem, its release cadence is tied to the broader `oas-kit` project, which sees continuous development and updates across its components, ensuring compatibility with evolving OpenAPI standards and practices. Key differentiators include its tight integration with other `oas-kit` tools and its focus on robust, tested utilities for spec transformation and validation workflows.","status":"active","version":"1.0.8","language":"javascript","source_language":"en","source_url":"https://github.com/Mermade/oas-kit","tags":["javascript","openapi","swagger","oas","utility"],"install":[{"cmd":"npm install oas-kit-common","lang":"bash","label":"npm"},{"cmd":"yarn add oas-kit-common","lang":"bash","label":"yarn"},{"cmd":"pnpm add oas-kit-common","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used within the oas-kit ecosystem for JSON Pointer and reference resolution operations, which are fundamental to OpenAPI document manipulation. Likely an indirect dependency or a closely related sibling library that provides low-level utilities.","package":"reftools","optional":true}],"imports":[{"note":"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.","wrong":"const common = require('oas-kit-common'); const sanitise = common.sanitise;","symbol":"sanitise","correct":"import { sanitise } from 'oas-kit-common';"},{"note":"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.","wrong":"const mergeDeep = require('oas-kit-common').mergeDeep;","symbol":"mergeDeep","correct":"import { mergeDeep } from 'oas-kit-common';"},{"note":"A basic type-checking utility common in libraries dealing with complex data structures like OpenAPI specifications. Consistent named imports are recommended.","wrong":"const isObject = require('oas-kit-common').isObject;","symbol":"isObject","correct":"import { isObject } from 'oas-kit-common';"}],"quickstart":{"code":"import { sanitise, mergeDeep } from 'oas-kit-common';\n\nconst originalObject = {\n  paths: {\n    '/users': { get: { operationId: 'getUsers' } },\n  },\n  components: {\n    schemas: {\n      'Foo Bar': { type: 'object' }\n    }\n  }\n};\n\nconst updates = {\n  paths: {\n    '/users': { post: { operationId: 'createUser' } }\n  }\n};\n\n// Example 1: Sanitizing a string for use as an OpenAPI component name\nconst dirtyName = 'My Awesome Component Name';\nconst cleanName = sanitise(dirtyName);\nconsole.log(`Original: \"${dirtyName}\", Sanitized: \"${cleanName}\"`);\n\n// Example 2: Deeply merging two OpenAPI-like objects\nconst mergedObject = mergeDeep({}, originalObject, updates);\nconsole.log('Merged Object:', JSON.stringify(mergedObject, null, 2));\n\n// Example 3: Demonstrate sanitization in context of object modification\nconst schemaName = 'Foo Bar';\nconst sanitizedSchemaName = sanitise(schemaName);\nconst modifiedObject = {\n  ...originalObject,\n  components: {\n    schemas: {\n      [sanitizedSchemaName]: originalObject.components.schemas[schemaName]\n    }\n  }\n};\nconsole.log('Modified Object with Sanitized Schema Name:', JSON.stringify(modifiedObject, null, 2));","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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';`.","cause":"Attempting to use `common.sanitise` after a default CommonJS import, or incorrect destructuring.","error":"TypeError: common.sanitise is not a function"},{"fix":"Run `npm install oas-kit-common` or `yarn add oas-kit-common` to install the package.","cause":"The package `oas-kit-common` is not installed in the project's `node_modules`.","error":"Error: Cannot find module 'oas-kit-common'"},{"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.","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.","error":"Property 'mergeDeep' does not exist on type 'typeof import(\"oas-kit-common\")'."}],"ecosystem":"npm"}