Registry / serialization / oas-kit-common

oas-kit-common

library1.0.8jsnpmunverified

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.

serialization

npm install oas-kit-common

github ↗package ↗

INSTALL

IMPORT

SIG · OAS-KIT-COMMON

oas-kit-common

serializationjavascriptv1.0.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sanitise

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

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

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

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

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

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

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

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

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

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));

Debug

Known issues

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

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: common.sanitise is not a function

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'

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")'.

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.

Upgrade

Version history

1.0.8latest on npm

Audit

Dependencies

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

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/Mermade/oas-kit ↗

packagehttps://www.npmjs.com/package/oas-kit-common ↗