JSON-typescript Basic Type Definitions

Common errors

• SyntaxError: Unexpected token {

  cause Using the incorrect import syntax `import * as { ... } from 'json-typescript';` shown in the package's README, which is not valid JavaScript or TypeScript for named imports.
  fix For named type imports, use `import type { Value, Object } from 'json-typescript';` or `import type { Value as JSONValue, Object as JSONObject } from 'json-typescript';`.

• Cannot find module 'json-typescript' or its corresponding type declarations.

  cause Attempting to import the package in a CommonJS context or without proper `tsconfig.json` setup for module resolution, especially with older TypeScript versions or when `esModuleInterop` is not enabled.
  fix Ensure `tsconfig.json` has `"module": "esnext"` (or compatible), `"moduleResolution": "node"`, and `"esModuleInterop": true`. If using CommonJS, direct `require` might not provide type inference and `import` should still be preferred for type safety. Reinstall `@types/json-typescript` if it were a separate types package (not applicable here as it ships its own types).

Warnings

• gotcha The `json-typescript` package has not been updated since March 2019. Its type definitions may not be fully compatible with newer TypeScript versions (e.g., TypeScript 4.x, 5.x) or may lack support for modern ECMAScript/JSON features and stricter type-checking configurations. This could lead to unexpected type errors or less precise type inference compared to actively maintained alternatives.
  Fix: For new projects or those requiring robust JSON schema validation or runtime type checking, consider actively maintained alternatives like `json-schema-to-typescript`, `typescript-json-schema` for schema generation, or `json2typescript` for runtime deserialization. If continuing to use this package, thoroughly test compatibility with your TypeScript version.
• deprecated The README contains an incorrect import syntax example: `import * as { Value as JSONValue, Object as JSONObject } from 'json-typescript';`. This is syntactically invalid for named type imports in TypeScript.
  Fix: Always use `import type { Value, Object } from 'json-typescript';` for named type imports, or `import type { Value as JSONValue, Object as JSONObject } from 'json-typescript';` if aliasing. The `import * as ...` syntax is for namespace imports, not for destructuring named exports.

Install

• npm install json-typescript npm
• yarn add json-typescript yarn
• pnpm add json-typescript pnpm

Imports

• All types as namespace
  wrong:

  const _JSON = require('json-typescript');

  correct:

  import * as _JSON from 'json-typescript';

  This imports all type definitions under the `_JSON` namespace. Ensure your TypeScript project is configured for ESM if encountering issues with CommonJS `require`.
• Value
  wrong:

  import { Value } from 'json-typescript'; // Older TS or mixing type and value imports
  import * as { Value } from 'json-typescript'; // Incorrect syntax

  correct:

  import type { Value } from 'json-typescript';

  Use the `import type` syntax for explicitly importing only type definitions, which is a best practice in modern TypeScript to avoid bundling unnecessary runtime code.
• Object
  wrong:

  import { Object as JSONObject } from 'json-typescript'; // Older TS or mixing type and value imports
  import * as { Object as JSONObject } from 'json-typescript'; // Incorrect syntax

  correct:

  import type { Object as JSONObject } from 'json-typescript';

  Aliasing types like `Object` to `JSONObject` is common to prevent naming conflicts with JavaScript's global `Object`. Use `import type` for explicit type-only imports.

Quickstart

Demonstrates installation and basic usage of JSON-typescript for compile-time validation of JSON structures, highlighting correct and incorrect type assignments.

npm install --save-dev json-typescript

// tsconfig.json might need:
// {
//   "compilerOptions": {
//     "moduleResolution": "node",
//     "esModuleInterop": true
//   }
// }

import type { Value as JSONValue, Object as JSONObject } from 'json-typescript';

// ✅ This should be OK: a valid JSON structure
let validDoc: JSONValue = {
  data: {
    type: 'articles',
    id: '1',
    attributes: {
      title: 'My Article',
      content: 'Hello World!'
    }
  },
  meta: {
    timestamp: new Date().toISOString()
  }
};

// ⛔️ This should NOT be OK (functions are not allowed in JSONValue)
// let invalidDocWithFunction: JSONValue = {
//   foo() { return 'bar'; }
// };

// ⛔️ This should NOT be OK (Array is not a JSONObject, it's a JSONValue)
// let invalidDocAsArray: JSONObject = [];

// Correct usage of JSONObject:
let myJsonObject: JSONObject = {
  key1: 'value1',
  key2: 123,
  key3: true,
  key4: null,
  key5: { nested: 'object' },
  key6: ['array', 456]
};

console.log('Valid JSON Document:', validDoc);
console.log('My JSON Object:', myJsonObject);