parser.js (2)

352-361: Union return type string[] | number makes the API harder to consume in TypeScript.

getFilesOrder() returns the full order array when called without arguments, or an index number when called with a name. This overloaded behavior produces a union return type that forces callers to narrow. Consider whether this could use JSDoc @overload annotations, or document the two calling conventions more clearly for type consumers.

---

37-40: Consider using explicit type arguments for the ParserFn generic in return and parameter types for consistency.

The @template [T=any] syntax in the typedef is valid and will emit correctly via tsc --declaration. However, line 335 returns ParserFn | undefined and line 343 accepts ParserFn without type arguments, while the typedef itself defines a generic type. For clarity, explicitly specify the type argument (e.g., ParserFn<any> | undefined or ParserFn<object>) in these usages to match the generic definition.

test/30-types-test.js (1)

19-36: Consider adding a timeout to spawnSync to prevent the test from hanging.

If tsc encounters an issue that causes it to hang, the test runner will block indefinitely.

Proposed fix

   const result = spawnSync(process.execPath, [tscPath, '-p', tsconfigPath], {
     cwd: repoRoot,
-    encoding: 'utf8'
+    encoding: 'utf8',
+    timeout: 60_000
   });

lib/config.js (1)

416-418: loadFileConfigs return type Config may be misleading.

newLoad.config (line 432) is a plain object without ConfigClass prototype methods. Typing it as Config (alias for ConfigClass) implies it has .get(), .has(), etc. Consider typing the return as object or adding a note that the caller is responsible for calling attachProtoDeep.

lib/config.js (2)

92-95: Unbounded @template T on get() — TypeScript cannot infer it from parameters.

Since property is typed as string, there's no way for TS to infer T from JSDoc alone. Callers will get unknown unless they use a cast. This is acceptable for a config library (it's a common pattern in .d.ts files where users write config.get<string>('key')), but be aware that JSDoc-based consumers won't benefit from the generic — it will effectively be any/unknown.

---

404-406: loadFileConfigs return type Config may be misleading.

The method returns newLoad.config, which is a plain object ({}), not a ConfigClass instance. Typing it as Config (alias for ConfigClass) could confuse consumers expecting prototype methods like get() and has() on the returned object. Consider typing the return as object to be more accurate, or documenting that the return is a raw config data object.

lib/util.js (1)

7-7: Parser typedef is duplicated in both lib/config.js (line 10) and lib/util.js (line 7).

Both files define @typedef {typeof import('./../parser')} Parser. Consider defining it in one place and importing from there to keep a single source of truth, though this is minor given it's a type-only declaration.

lib/config.js (1)

92-94: @template T on get() won't provide type narrowing without a cast by the caller.

The generic T is unconstrained and not linked to any input parameter, so TypeScript will infer T as unknown unless the caller explicitly provides a type argument (e.g., config.get<string>('key')). This is a known limitation of JSDoc-based generics and is acceptable, but worth documenting for consumers or considering a typed overload in the .d.ts file.

package.json (1)

62-77: TypeScript is pinned to an exact version — consider using a caret range.

All other devDependencies use range specifiers (^ or ~), but typescript is pinned to 5.9.3. This means contributors won't automatically get patch fixes. Consider ^5.9.3 for consistency, unless the exact pin is intentional.

Proposed change

-    "typescript": "5.9.3",
+    "typescript": "^5.9.3",

lib/config.js (1)

92-95: Unconstrained @template T on get will infer as unknown in generated declarations.

Since there's no way to bind T to the config shape from JSDoc alone, the generated .d.ts will type the return as T which callers must narrow themselves. This is acceptable but worth noting — consumers will likely need type assertions like config.get<string>('key') or typed wrappers.

parser.js (1)

352-361: getFilesOrder return type union makes consuming code awkward.

string[] | number accurately reflects the overloaded behavior, but this is a pre-existing API design choice. For the generated .d.ts, consumers will need type narrowing on every call. This is fine to leave as-is for now.