json-lint-d-ts

1.2.2 verified Fri May 01 auth: no javascript

Lint JSON files against TypeScript declaration files. Current stable version is 1.2.2, released optionally. It validates JSON files by comparing them to .d.ts definitions, ensuring type safety without running TypeScript. Supports generation of .d.ts files from JSON samples (via quicktype) and from HTTP endpoints. Key differentiator: unlike JSON Schema validators, it uses TypeScript type definitions directly as the schema source.

Common errors

error TypeError: Cannot read properties of undefined (reading 'Symbol(quick-type)') ↓

cause Missing or incompatible quicktype version when using generate.

fix

Install quicktype as a peer dependency: yarn add -D quicktype

error Error: No type Root found in declaration file. ↓

cause The .d.ts file does not define a type named Root.

fix

Add type Root = YourMainType; to the declaration file.

error TypeError: validate(...).then is not a function ↓

cause Treating validate as async when it is synchronous.

fix

Use result = validate([...]) without await; validate returns an array directly.

Warnings

gotcha .d.ts file must define a 'type Root' for validation to work; otherwise validation may silently succeed or fail unexpectedly. ↓

fix Ensure your .d.ts file exports a type named Root. For example: type Root = YourInterface;

deprecated generate function uses quicktype under the hood and may have breaking changes when quicktype updates. ↓

fix Monitor quicktype changelog for breaking changes, or pin quicktype version if needed.

gotcha Validation errors are returned as strings, not structured objects. Parsing error messages for programmatic use is brittle. ↓

fix Use string matching or regex to extract error details; consider wrapping validate in a custom parser.

gotcha generateAsync does not support Bearer tokens or custom headers for HTTP endpoints; only raw URL fetch without authentication. ↓

fix Pre-fetch data with your own fetch() and pass the JSON body directly to generate.

Install

npm install json-lint-d-ts

yarn add json-lint-d-ts

pnpm add json-lint-d-ts

Imports

validate

wrong

const validate = require("json-lint-d-ts").validate;

correct

import { validate } from "json-lint-d-ts";

ESM default; CommonJS require works but destructuring is not supported directly.

generate

wrong

import { generate } from "json-lint-d-ts/generate";

correct

import { generate } from "json-lint-d-ts";

Both validate and generate are top-level exports.

generateAsync

wrong

import { generateAsync } from "json-lint-d-ts/src/generateAsync";

correct

import { generateAsync } from "json-lint-d-ts";

Available since v1.2.0 for HTTP-based generation.

Quickstart

Validates a JSON file against a TypeScript declaration file using the validate function.

import { validate } from "json-lint-d-ts";

const result = validate([
  ["./hello.json", "./hello.d.ts"],
]);

// Result shows any type errors
console.log(result);