Harper 5.x: generated types invalid for hyphenated database names + augments 'harperdb' instead of 'harper'

[kylebernhardy]

Summary

When generating types for a Harper 5.x application whose schema places tables in databases whose names contain hyphens, the generated globalTypes.d.ts and types.ts are invalid TypeScript and do not augment the module the app actually imports. The output produces hundreds of tsc errors and provides no usable typing for databases.

I hit three distinct problems (the first two are hard blockers).

Environment

• Harper: 5.1.9
• @harperfast/schema-codegen: reproduced on both 1.1.1 and 2.0.0-beta.1
• TypeScript: 5.9.x, tsc --noEmit
• App imports Harper via the harper package (Harper 5.x), not harperdb.

Issue 1 — Generated module augmentation targets harperdb, not harper

generateTablesDTS.js hardcodes the module name:

// utils/generateTablesDTS.js
content += `import type { Table } from 'harperdb';\n`;   // line 18
content += `declare module 'harperdb' {\n`;               // line 42

In Harper 5.x the runtime package is harper. Apps do import { databases } from "harper", so a declare module 'harperdb' augmentation never attaches — databases stays untyped (or falls back to the base type), defeating the purpose of the generated .d.ts.

Expected: emit declare module 'harper' (or make the target package configurable) for Harper 5.x projects.

Issue 2 — Invalid TypeScript identifiers for tables in hyphenated databases

Type names are built by concatenating the database name and table name without sanitizing the result into a valid identifier:

// utils/generateTS.js (lines 22–25)
const dbPrefix =
  table.databaseName && table.databaseName !== 'data' ? `${table.databaseName}_` : '';
const plural = `${dbPrefix}${table.tableName}`;
const singular = `${dbPrefix}${singularize(table.tableName)}`;

For a database named metrics-github, this emits identifiers like metrics-github_Repository. A hyphen is not a legal identifier character, so TypeScript parses metrics-github_Repository as the subtraction metrics - github_Repository. Every interface in types.ts and every reference in globalTypes.d.ts for a hyphenated database is invalid:

// generated types.ts
export interface metrics-github_Repository { ... }   // ❌ invalid identifier
// generated globalTypes.d.ts
Repository: { new(...args: any[]): Table<metrics-github_Repository> };  // ❌

This alone produced ~1100 tsc errors in our project.

Expected: sanitize the prefix into a valid identifier (e.g. metrics-github → metrics_github or metricsGithub) consistently in both the declaration site and all reference sites.

Issue 3 — Codegen emits types for every database on the connected instance (no scoping)

collectTables() iterates the entire live databases object, so the output includes every database present on the Harper instance, not just the ones belonging to this application. On a shared local instance, unrelated databases/tables (from other projects) get written into the app's types.ts/globalTypes.d.ts.

Expected (enhancement): a way to scope generation to the application's own databases (e.g. those declared in the project's schema.graphql), or at least an include/exclude option.

Reproduction

1. Harper 5.1.9 app importing from the harper package.
2. Schema with a table in a hyphenated database:

   type Repository @table(database: "metrics-github") @export {
     id: ID @primaryKey
     name: String
   }

3. Enable the extension in config.yaml:

   "@harperfast/schema-codegen":
     package: "@harperfast/schema-codegen"
     globalTypes: "schemas/globalTypes.d.ts"
     schemaTypes: "schemas/types.ts"

4. Run harper dev . and let it generate.
5. Inspect the output:
   • globalTypes.d.ts contains declare module 'harperdb' (Issue 1)
   • types.ts contains export interface metrics-github_Repository { ... } (Issue 2)
   • extra unrelated databases appear if the instance hosts more than this app (Issue 3)
6. tsc --noEmit over the generated files → hundreds of errors.

Impact

With hyphenated multi-database schemas on Harper 5.x, the generated types are unusable; we had to hand-write a module augmentation as a workaround. Issues 1 and 2 look like small, well-scoped fixes (module string + identifier sanitization).

[dawsontoth]

Thanks for the detailed writeup, @kylebernhardy — the hyphenated-database case was the same class of bug as our earlier table-name sanitization, just on the database-name axis it never reached.

Opened #44 to fix all three:

• Issue 2 (name safety): database names are now run through the identifier sanitizer, so metrics-github yields metricsGithub_Repository instead of the invalid metrics-github_Repository. Runtime keys (databases['metrics-github'].Repository) stay verbatim and are quoted.
• Issue 1 (module): the augmentation now targets harper by default, with a new module config option so Harper 4.x apps can set module: harperdb.
• Issue 3 (scoping): new includeDatabases / excludeDatabases options (with * wildcards) keep other projects' databases out of your generated types on a shared instance.

⚠️ Defaulting to harper is a breaking change, so it'll ship as a major version — 4.x apps override with module: harperdb.

Would appreciate a sanity check against your metrics-github schema if you get a chance.

[github-actions]

🎉 This issue has been resolved in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀