Ship TypeScript declarations for the public API

[arashm]

Makes the package usable from TypeScript without converting it to TypeScript. The library stays JavaScript; the declarations are hand written in types/jdate.d.ts and emitted into lib/ by the build.

import JDate, { type JalaliDate, type JDateConfig } from 'jalali-date';

const jdate = new JDate([1396, 8, 26], { persianNumerical: true });
const formatted: string = jdate.format('dddd DD MMMM YYYY');

Why not generate them from the JSDoc

tsc --allowJs --emitDeclarationOnly was the obvious route and does not work here. The comments in src/ use @params, which tsc ignores, so every one would need rewriting; and the constructor is variadic, so constructor(...args) emits ...args: any[] and loses the four call forms — the most useful thing in the file to type. Hand writing costs a second source of truth, which is what the two checks below are for.

One declaration cannot describe both bundles

lib/jdate.cjs ends with module.exports = module.exports.default, so require() returns the class itself and its declaration must say export = JDate. lib/jdate.mjs exports the class as default and needs export default. A single shared export default file would type require('jalali-date') as { default: JDate } — wrong, and silently so.

So types/jdate.d.ts is a body with no export statement, and the build appends one of two footers, the same way it already appends footers to the JS bundles:

Emitted	Footer	Matches
lib/jdate.d.mts	export default JDate	lib/jdate.mjs
lib/jdate.d.cts	export = JDate	lib/jdate.cjs
lib/index.d.ts	export = JDate	the top-level "types" field

export = forbids any other top-level export, so the CJS side re-exports the type names through a namespace merged into the class (JDate.JDateConfig).

lib/index.d.ts looks redundant beside jdate.d.cts and is not: TypeScript did not learn the .d.cts extension until 4.7, so pointing "types" straight at that file leaves every older version with no types at all — 4.6 reports Could not find a declaration file for module 'jalali-date'.

Two checks, both in CI after the build

• npm run test:types — compiles tests/types/ against the shipped declarations under both resolution modes in common use: nodenext (which tells the .mts and .cts fixtures apart) and bundler.
• npm run test:exports — runs attw over the packed tarball.

Neither is redundant. attw checks that every entry point resolves to types and that no format masquerades as another, but it does not look at what those types export: swapping the CJS footer for the ESM one leaves attw fully green, while the .cts fixture fails immediately with This expression is not constructable. Verified by doing it.

API notes

The constructor is three overloads covering the four call forms. JalaliDate is a three-element tuple rather than number[] on purpose — new JDate([1396, 8]) throws nothing at runtime, it quietly builds an Invalid Date, so the arity is the only place that mistake can be caught. Config entry counts stay a runtime check, because a name list built elsewhere infers as string[] rather than as a tuple and should still be passable; the README's own example is that shape.

Reviewing the declarations against the runtime found one defect in them: the config-only overload had been given config?: JDateConfig | null, copied from the other two. A trailing null is dropped only when a whole date is left standing beside it, so new JDate(null) reaches no branch and throws Unexpected input — and new JDate(maybeConfig) on a nullable variable would have compiled clean and thrown in production. Fixed, with a fixture pinning it.

Verification

Packed the tarball, installed it into a scratch project and type-checked it as a real dependency: TS 6 (nodenext ESM, nodenext CJS, bundler), TS 5.9 (nodenext, legacy node), TS 4.6 (legacy node) — all clean. Runtime agrees with the declarations: require() yields function JDate with no .default, the ESM default import yields the class.

A fresh npm run build leaves the tree clean, so the checked-in lib/ declarations are exactly reproducible from source.

No runtime code changed. The 101 tests and the four JS bundles are byte for byte what they were.

Not included

Nothing asserts that the built bundles still have the export shapes the declarations claim — if a build footer changed, types and reality would drift silently. A smoke test importing lib/jdate.cjs and lib/jdate.mjs would close that, but it makes npm test depend on a prior build, so it is left out of this change.