core-types ↔ TypeScript Interface Conversion

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use `import` syntax in a CommonJS environment, or trying to `require()` this ESM-only package.
  fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import` statements. If trying to `require()`, switch to `import`.

• TypeError: (0, _core_types_ts.convertCoreTypesToTypeScript) is not a function

  cause This error often occurs in mixed CommonJS/ESM environments when a CommonJS file attempts to import an ESM module, or when incorrect destructuring is applied in transpiled code.
  fix Verify that both your consuming code and `core-types-ts` are consistently treated as ESM modules. Check transpilation settings if using Babel or similar tools. Ensure named imports are correctly destructured.

• Error: Not able to resolve type for ...

  cause When converting TypeScript to core-types, the parser might encounter TypeScript features or syntax it cannot currently map to the generic `core-types` model.
  fix Review the TypeScript source for complex types, conditional types, or advanced Mapped Types that might not have direct `core-types` equivalents. Simplify the TypeScript declaration or use the `unsupported` option in `FromTsOptions` to `warn` or `ignore` (default is `error`).

Warnings

• breaking Version 4.0.0 removed CommonJS support, making the package pure ESM. Direct `require()` statements will fail.
  Fix: Migrate all imports to ESM `import` statements. Ensure your project is configured for ESM, e.g., by setting `"type": "module"` in `package.json` or using `.mjs` file extensions.
• breaking Version 3.0.0 dropped support for Node.js 12.
  Fix: Upgrade your Node.js runtime to version 14.13.1 or newer (or 16.0.0 or newer). The package explicitly requires `'>=14.13.1 || >=16.0.0'`.
• breaking Version 2.0.0 introduced breaking API signature changes related to TypeScript 4.6, potentially affecting consumers directly interacting with internal TypeScript AST representations or helper functions.
  Fix: Review the `core-types-ts` v2.0.0 release notes and your code for compatibility with TypeScript 4.6. Update API calls as necessary according to the new signatures.
• gotcha This package is generally intended as a dependency for higher-level type conversion tools like `typeconv` and `core-types-suretype`. Direct usage might indicate a need for more comprehensive type management solutions.
  Fix: Consider if `typeconv` (for broader schema conversions) or other specialized tools better fit your use case, as they abstract away direct interaction with `core-types-ts`.

Install

• npm install core-types-ts npm
• yarn add core-types-ts yarn
• pnpm add core-types-ts pnpm

Imports

• convertCoreTypesToTypeScript
  wrong:

  const { convertCoreTypesToTypeScript } = require('core-types-ts')

  correct:

  import { convertCoreTypesToTypeScript } from 'core-types-ts'

  ESM-only since v4.0.0; CommonJS `require` is no longer supported.
• convertTypeScriptToCoreTypes
  wrong:

  const convertTypeScriptToCoreTypes = require('core-types-ts').convertTypeScriptToCoreTypes

  correct:

  import { convertTypeScriptToCoreTypes } from 'core-types-ts'

  ESM-only since v4.0.0; CommonJS `require` is no longer supported.
• ToTsOptions

  import type { ToTsOptions } from 'core-types-ts'

  This is a type import for configuring the core-types to TypeScript conversion.

Quickstart

Demonstrates converting both from a `core-types` document to TypeScript source code and vice-versa, showcasing basic usage and option passing for each direction.

import { convertCoreTypesToTypeScript, convertTypeScriptToCoreTypes } from 'core-types-ts';
import type { NodeType } from 'core-types';

// Example: Convert core-types document to TypeScript source code
const coreTypeDoc: NodeType = {
  type: 'object',
  properties: {
    id: { node: { type: 'string' }, required: true },
    name: { node: { type: 'string' }, required: false },
    age: { node: { type: 'number' }, required: false }
  },
  additionalProperties: false
};

const { data: tsSourceCode } = convertCoreTypesToTypeScript(coreTypeDoc, {
  filename: 'example.ts',
  useUnknown: true,
  declaration: true
});
console.log('--- Converted to TypeScript ---\n', tsSourceCode);

// Example: Convert TypeScript source code to core-types document
const tsSource = `
  /** @core-types-name User */
  export interface MyUser {
    id: string;
    name?: string;
    age?: number;
  }
`;

const { data: convertedCoreTypeDoc } = convertTypeScriptToCoreTypes(tsSource, {
  namespaces: 'join-dot'
});
console.log('\n--- Converted to core-types ---\n', JSON.stringify(convertedCoreTypeDoc, null, 2));