@harperfast/schema-codegen 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# @HarperFast/Schema-Codegen
+
+Schema Codegen will generate TypeScript types for your GraphQL schemas, making it easier to work with your data in TypeScript and JavaScript applications.
+
+## Installation
+
+Install this with your favorite package manager!
+
+**Warning**: I haven't actually published this yet. :)
+
+```bash
+npm install --save @harperfast/schema-codegen
+```
+
+Drop this in your Harper application's config.yaml:
+
+```yaml
+'@harperfast/schema-codegen':
+  package: '@harperfast/schema-codegen'
+  globalTypes: 'schemas/globalTypes.d.ts'
+  schemaTypes: 'schemas/types.ts'
+```
+
+Alternatively, if you are using pure JavaScript, you can generate JSDoc instead:
+
+```yaml
+'@harperfast/schema-codegen':
+  package: '@harperfast/schema-codegen'
+  jsdoc: 'schemas/jsdocTypes.js'
+```
+
+When you `harper dev`, it will generate types based on the schema that's actually in your Harper database. If you change the schema, we will automatically regenerate the types for you.
+
+## Example
+
+For example, here's a tracks.graphql schema:
+
+```graphql
+type Tracks @table @sealed {
+	id: ID @primaryKey
+	name: String! @indexed
+	mp3: Blob
+}
+```
+
+Next to it, a schemas/types.ts file will get generated with this:
+
+```typescript
+/**
+ Generated from HarperDB schema
+ Manual changes will be lost!
+ > harper dev .
+ */
+export interface Track {
+	id: string;
+	name: string;
+	mp3?: any;
+}
+
+export type NewTrack = Omit<Track, 'id'>;
+export type Tracks = Track[];
+export type { Track as TrackRecord };
+export type TrackRecords = Track[];
+export type NewTrackRecord = Omit<Track, 'id'>;
+```
+
+An ambient declaration will also be generated in globalTypes.d.ts to enhance the global `tables` and `databases` from Harper:
+
+```typescript
+/**
+ Generated from your schema files
+ Manual changes will be lost!
+ > harper dev .
+ */
+import type { Table } from 'harperdb';
+import type { Track } from './types.ts';
+
+declare module 'harperdb' {
+	export const tables: {
+		Tracks: { new(...args: any[]): Table<Track> };
+	};
+	export const databases: {
+		data: {
+			Tracks: { new(...args: any[]): Table<Track> };
+		};
+	};
+}
+```
+
+## Development
+
+This code uses type stripping, so as long as you use a compatible version of Node, nothing needs to be compiled.
+
+To use this in an application, first link it:
+
+```bash
+git clone git@github.com:HarperFast/schema-codegen.git
+cd schema-codegen
+npm link
+```
+
+Then cd to your awesome application you want to test this with:
+
+```bash
+cd ~/my-awesome-app
+npm link @harperfast/schema-codegen
+```

package/config.yaml

@@ -0,0 +1 @@
+extensionModule: ./extensionModule.ts

package/extensionModule.ts

@@ -0,0 +1,58 @@
+import type { Scope } from 'harperdb';
+import { setLogger } from './utils/logger.ts';
+import { regenerateAll } from './utils/regenerateAll.ts';
+import { sleep } from './utils/sleep.ts';
+
+export const suppressHandleApplicationWarning = true;
+
+export async function handleApplication(scope: Scope) {
+	setLogger(scope.logger);
+
+	if (!process.env.DEV_MODE) {
+		scope.logger.trace?.('@harperfast/schema-codegen skipping execution outside of dev mode');
+		return;
+	}
+
+	const watchConfig = scope.options.get(['watch']);
+	const shouldWatch = watchConfig === true || watchConfig === undefined;
+	const globalTypes = (scope.options.get(['globalTypes']) as string) || './schema.globalTypes.d.ts';
+	const schemaTypes = (scope.options.get(['schemaTypes']) as string) || './schema.types.ts';
+	const jsdoc = scope.options.get(['jsdoc']) as string | undefined;
+
+	if (shouldWatch) {
+		scope.on('close', scopeClosed);
+	}
+
+	// Do not await this.
+	sleep(500)
+		.then(() => {
+			// Initial generation
+			regenerateAll(globalTypes, schemaTypes, jsdoc);
+
+			if (shouldWatch) {
+				// Watch for schema/database changes via events
+				scope.databaseEvents.on('updateTable', updateTable);
+				scope.databaseEvents.on('dropTable', dropTable);
+				scope.databaseEvents.on('dropDatabase', dropDatabase);
+			}
+		});
+
+	function updateTable() {
+		regenerateAll(globalTypes, schemaTypes, jsdoc);
+	}
+
+	function dropTable() {
+		regenerateAll(globalTypes, schemaTypes, jsdoc);
+	}
+
+	function dropDatabase() {
+		regenerateAll(globalTypes, schemaTypes, jsdoc);
+	}
+
+	function scopeClosed() {
+		scope.databaseEvents.off('updateTable', updateTable);
+		scope.databaseEvents.off('dropTable', dropTable);
+		scope.databaseEvents.off('dropDatabase', dropDatabase);
+		scope.off('close', scopeClosed);
+	}
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@harperfast/schema-codegen",
+	"version": "1.0.0",
+	"type": "module",
+	"scripts": {
+		"commitlint": "commitlint --edit",
+		"format:check": "dprint check",
+		"format:fix": "dprint fmt",
+		"format:staged": "dprint check --staged --allow-no-files",
+		"lint:check": "oxlint .",
+		"lint:fix": "oxlint . --fix",
+		"test": "vitest run",
+		"test:coverage": "vitest run --coverage",
+		"test:watch": "vitest"
+	},
+	"files": [
+		"extensionModule.ts",
+		"config.yaml",
+		"utils/",
+		"!utils/**/*.test.ts"
+	],
+	"devDependencies": {
+		"@commitlint/cli": "^20.0.0",
+		"@commitlint/config-conventional": "^20.0.0",
+		"@semantic-release/commit-analyzer": "^13.0.1",
+		"@semantic-release/git": "^10.0.1",
+		"@semantic-release/github": "^12.0.2",
+		"@semantic-release/npm": "^13.1.1",
+		"@semantic-release/release-notes-generator": "^14.1.0",
+		"@types/node": "^24.10.11",
+		"@types/react": "^19.2.10",
+		"@vitest/coverage-v8": "^4.0.18",
+		"conventional-changelog-conventionalcommits": "^9.1.0",
+		"dprint": "^0.52.0",
+		"harperdb": "^4.7.20",
+		"oxlint": "^1.51.0",
+		"semantic-release": "^25.0.2",
+		"vitest": "^4.0.18"
+	}
+}

package/utils/collectTables.ts

@@ -0,0 +1,16 @@
+import type { Table } from 'harperdb';
+import { databases as hdbDatabases } from 'harperdb';
+
+export function collectTables() {
+	const tablesList: (Table & { databaseName: string })[] = [];
+	for (const dbName of Object.keys(hdbDatabases || {})) {
+		const tables = (hdbDatabases as any)[dbName];
+		for (const tableName of Object.keys(tables || {})) {
+			const TableClass = tables[tableName];
+			if (!TableClass?.attributes) { continue; }
+			(TableClass as any).databaseName = dbName;
+			tablesList.push(TableClass as Table & { databaseName: string });
+		}
+	}
+	return tablesList;
+}

package/utils/generateInterface.ts

@@ -0,0 +1,48 @@
+import type { Table } from 'harperdb';
+import { isNullable } from './isNullable.ts';
+import { mapType } from './mapType.ts';
+import { singularize } from './singularize.ts';
+
+export function generateInterface(table: Table & { databaseName?: string }) {
+	const pluralRaw = table.tableName;
+	const singularRaw = singularize(pluralRaw);
+	const dbPrefix = table.databaseName && table.databaseName !== 'data' ? `${table.databaseName}_` : '';
+	const plural = `${dbPrefix}${pluralRaw}`;
+	const singular = `${dbPrefix}${singularRaw}`;
+	const isDifferent = plural !== singular;
+
+	let code = `\nexport interface ${singular} {\n`;
+	const primaryKeys: string[] = [];
+	for (const attribute of table.attributes || []) {
+		const type = mapType(attribute);
+		const primaryKey = !!attribute.isPrimaryKey;
+		const nullable = !primaryKey && isNullable(attribute);
+		code += `\t${attribute.name}${nullable ? '?' : ''}: ${type};\n`;
+		if (primaryKey) {
+			primaryKeys.push(attribute.name!);
+		}
+	}
+	code += `}\n\n`;
+
+	const hasPks = primaryKeys.length > 0;
+	const pks = hasPks ? primaryKeys.map((pk) => `'${pk}'`).join(' | ') : null;
+
+	if (hasPks) {
+		code += `export type ${dbPrefix}New${singularRaw} = Omit<${singular}, ${pks}>;\n`;
+	}
+
+	if (isDifferent) {
+		code += `export type ${plural} = ${singular}[];\n`;
+	}
+
+	// Regardless
+	if (singular !== `${singular}Record`) {
+		code += `export type { ${singular} as ${singular}Record };\n`;
+	}
+	code += `export type ${singular}Records = ${singular}[];\n`;
+	if (hasPks) {
+		code += `export type ${dbPrefix}New${singularRaw}Record = Omit<${singular}, ${pks}>;\n`;
+	}
+
+	return code;
+}

package/utils/generateJSDoc.ts

@@ -0,0 +1,59 @@
+import type { Table } from 'harperdb';
+import { isNullable } from './isNullable.ts';
+import { mapType } from './mapType.ts';
+import { singularize } from './singularize.ts';
+
+/**
+ * Generates JSDoc types for a given HarperDB table.
+ *
+ * Example output:
+ * /**
+ *  * @typedef {Object} Track
+ *  * @property {string} id
+ *  * @property {string} name
+ *  * @property {any} [mp3]
+ *  *\/
+ */
+export function generateJSDoc(table: Table & { databaseName?: string }) {
+	const pluralRaw = table.tableName;
+	const singularRaw = singularize(pluralRaw);
+	const dbPrefix = table.databaseName && table.databaseName !== 'data' ? `${table.databaseName}_` : '';
+	const plural = `${dbPrefix}${pluralRaw}`;
+	const singular = `${dbPrefix}${singularRaw}`;
+	const isDifferent = plural !== singular;
+
+	let code = `\n/**\n * @typedef {Object} ${singular}\n`;
+	const primaryKeys: string[] = [];
+	for (const attribute of table.attributes || []) {
+		const type = mapType(attribute);
+		const primaryKey = !!attribute.isPrimaryKey;
+		const nullable = !primaryKey && isNullable(attribute);
+		code += ` * @property {${type}} ${nullable ? '[' : ''}${attribute.name}${nullable ? ']' : ''}\n`;
+		if (primaryKey) {
+			primaryKeys.push(attribute.name!);
+		}
+	}
+	code += ` */\n\n`;
+
+	const hasPks = primaryKeys.length > 0;
+	const pks = hasPks ? primaryKeys.map((pk) => `'${pk}'`).join(' | ') : null;
+
+	if (hasPks) {
+		code += `/** @typedef {Omit<${singular}, ${pks}>} ${dbPrefix}New${singularRaw} */\n`;
+	}
+
+	if (isDifferent) {
+		code += `/** @typedef {${singular}[]} ${plural} */\n`;
+	}
+
+	// Regardless
+	if (singular !== `${singular}Record`) {
+		code += `/** @typedef {${singular}} ${singular}Record */\n`;
+	}
+	code += `/** @typedef {${singular}[]} ${singular}Records */\n`;
+	if (hasPks) {
+		code += `/** @typedef {Omit<${singular}, ${pks}>} ${dbPrefix}New${singularRaw}Record */\n`;
+	}
+
+	return code;
+}

package/utils/generateJSDocFromTables.ts

@@ -0,0 +1,26 @@
+import type { Table } from 'harperdb';
+import { generateJSDoc } from './generateJSDoc.ts';
+import { singularize } from './singularize.ts';
+import type { TableMeta } from './tableMeta.ts';
+
+export function generateJSDocFromTables(
+	tablesInput: (Table & { databaseName: string })[],
+	label: string = 'HarperDB schemas',
+) {
+	let jsCode = `/**
+ Generated from ${label}
+ Manual changes will be lost!
+ > harper dev .
+ */`;
+	const tables: TableMeta[] = [];
+
+	for (const table of tablesInput) {
+		jsCode += generateJSDoc(table);
+		const dbPrefix = table.databaseName && table.databaseName !== 'data' ? `${table.databaseName}_` : '';
+		const plural = `${dbPrefix}${table.tableName}`;
+		const singular = `${dbPrefix}${singularize(table.tableName)}`;
+		tables.push({ plural, singular, databaseName: table.databaseName });
+	}
+
+	return { jsCode, tables };
+}

package/utils/generateTS.ts

@@ -0,0 +1,26 @@
+import type { Table } from 'harperdb';
+import { generateInterface } from './generateInterface.ts';
+import { singularize } from './singularize.ts';
+import type { TableMeta } from './tableMeta.ts';
+
+export function generateTSFromTables(
+	tablesInput: (Table & { databaseName: string })[],
+	label: string = 'HarperDB schemas',
+) {
+	let tsCode = `/**
+ Generated from ${label}
+ Manual changes will be lost!
+ > harper dev .
+ */`;
+	const tables: TableMeta[] = [];
+
+	for (const table of tablesInput) {
+		tsCode += generateInterface(table);
+		const dbPrefix = table.databaseName && table.databaseName !== 'data' ? `${table.databaseName}_` : '';
+		const plural = `${dbPrefix}${table.tableName}`;
+		const singular = `${dbPrefix}${singularize(table.tableName)}`;
+		tables.push({ plural, singular, databaseName: table.databaseName });
+	}
+
+	return { tsCode, tables };
+}

package/utils/generateTablesDTS.ts

@@ -0,0 +1,65 @@
+import fs from 'fs';
+import path from 'path';
+import { getLogger } from './logger.ts';
+import type { TableMeta } from './tableMeta.ts';
+
+export function generateTablesDTS(globalTypesPath: string, schemaTypesPath: string, tables: TableMeta[]) {
+	let content = `/**
+ Generated from your schema files
+ Manual changes will be lost!
+ > harper dev .
+ */
+`;
+	content += `import type { Table } from 'harperdb';\n`;
+	// Build a single import of all relevant types from schemaTypesPath
+	const namesToImport = new Set<string>();
+	for (const table of tables) {
+		namesToImport.add(table.singular);
+	}
+	if (namesToImport.size > 0) {
+		const fromPathRaw = path.relative(path.dirname(globalTypesPath), schemaTypesPath);
+		const fromPath = fromPathRaw.startsWith('.') ? fromPathRaw : './' + fromPathRaw;
+		content += `import type { ${Array.from(namesToImport).join(', ')} } from '${fromPath}';\n`;
+	}
+	content += '\n';
+
+	const dbMap = new Map<string, TableMeta[]>();
+	for (const table of tables) {
+		if (!dbMap.has(table.databaseName)) {
+			dbMap.set(table.databaseName, []);
+		}
+		dbMap.get(table.databaseName)!.push(table);
+	}
+
+	content += `declare module 'harperdb' {\n`;
+
+	// Export top-level tables for 'data' database
+	const dataTables = dbMap.get('data') || [];
+	content += `\texport const tables: {\n`;
+	for (const table of dataTables) {
+		content += `\t\t${table.plural}: { new(...args: any[]): Table<${table.singular}> };\n`;
+	}
+	content += `\t};\n\n`;
+
+	// Export namespaced databases
+	content += `\texport const databases: {\n`;
+	for (const [dbName, dbTables] of dbMap.entries()) {
+		content += `\t\t${dbName}: {\n`;
+		for (const table of dbTables) {
+			const pluralRaw = table.plural.startsWith(`${dbName}_`) ? table.plural.slice(dbName.length + 1) : table.plural;
+			content += `\t\t\t${pluralRaw}: { new(...args: any[]): Table<${table.singular}> };\n`;
+		}
+		content += `\t\t};\n`;
+	}
+	content += `\t};\n`;
+
+	content += `}\n`;
+	const outPath = globalTypesPath;
+	const dir = path.dirname(outPath);
+	if (!fs.existsSync(dir)) { fs.mkdirSync(dir, { recursive: true }); }
+	const existingContent = fs.existsSync(outPath) && fs.readFileSync(outPath, 'utf8');
+	if (existingContent !== content) {
+		fs.writeFileSync(outPath, content, 'utf8');
+		getLogger().debug?.(`Updated types in ${outPath}`);
+	}
+}

package/utils/isNullable.ts

@@ -0,0 +1,7 @@
+import type { Attribute } from 'harperdb';
+
+export function isNullable(attribute: Attribute) {
+	// Primary keys are always required
+	if (attribute.isPrimaryKey) { return false; }
+	return !!attribute.nullable || attribute.nullable === undefined;
+}

package/utils/logger.ts

@@ -0,0 +1,11 @@
+import type { Logger } from 'harperdb';
+
+let logger: Logger | null = null;
+
+export function setLogger(newLogger: Logger) {
+	logger = newLogger;
+}
+
+export function getLogger(): Logger {
+	return logger!;
+}

package/utils/mapType.ts

@@ -0,0 +1,51 @@
+import type { Attribute } from 'harperdb';
+import { singularize } from './singularize.ts';
+
+function mapObjectType(properties: Attribute[] | undefined): string {
+	if (!properties || properties.length === 0) { return 'Record<string, any>'; }
+	const fields = properties
+		.map((prop) => {
+			const optional = prop.isPrimaryKey ? false : !!prop.nullable;
+			return `${prop.name}${optional ? '?' : ''}: ${mapType(prop)};`;
+		})
+		.join(' ');
+	return `{ ${fields} }`;
+}
+
+export function mapType(attribute: Attribute): string {
+	const name = attribute?.type || 'Any';
+	switch (name) {
+		case 'String':
+		case 'ID':
+			return 'string';
+		case 'Int':
+		case 'Float':
+		case 'Long':
+			return 'number';
+		case 'BigInt':
+			return 'bigint';
+		case 'Boolean':
+			return 'boolean';
+		case 'Date':
+			return 'string';
+		case 'Bytes':
+		case 'Blob':
+		case 'Any':
+			return 'any';
+		case 'array':
+		case 'Array':
+			if (attribute.elements) {
+				return `${mapType(attribute.elements)}[]`;
+			}
+			return 'any[]';
+		case 'object':
+		case 'Object':
+			if (attribute.properties && attribute.properties.length) {
+				return mapObjectType(attribute.properties);
+			}
+			return 'Record<string, any>';
+		default:
+			// Fallback to using the type name (singularized) as an interface reference
+			return singularize(name);
+	}
+}

package/utils/regenerateAll.ts

@@ -0,0 +1,20 @@
+import path from 'path';
+import { collectTables } from './collectTables.ts';
+import { generateJSDocFromTables } from './generateJSDocFromTables.ts';
+import { generateTablesDTS } from './generateTablesDTS.ts';
+import { generateTSFromTables } from './generateTS.ts';
+import type { TableMeta } from './tableMeta.ts';
+import { writeIfChanged } from './writeIfChanged.ts';
+
+export function regenerateAll(globalTypes: string, schemaTypes: string, jsdoc?: string) {
+	const list = collectTables();
+
+	if (jsdoc) {
+		const { jsCode } = generateJSDocFromTables(list, 'HarperDB schema');
+		writeIfChanged(path.resolve(jsdoc), jsCode);
+	} else {
+		const { tsCode, tables } = generateTSFromTables(list, 'HarperDB schema');
+		writeIfChanged(path.resolve(schemaTypes), tsCode);
+		generateTablesDTS(path.resolve(globalTypes), path.resolve(schemaTypes), tables as TableMeta[]);
+	}
+}

package/utils/singularize.ts

@@ -0,0 +1,61 @@
+export function singularize(word: string): string {
+	const lower = word.toLowerCase();
+
+	// Nouns that are the same in singular and plural or should be treated as unchanged here
+	const noChange = new Set([
+		'moose',
+		'series',
+		'species',
+		'sheep',
+		'fish',
+		'deer',
+		'news',
+		'chassis',
+		'aircraft',
+		'bison',
+		'salmon',
+		'trout',
+		'swine',
+		'media',
+	]);
+	if (noChange.has(lower)) {
+		return word;
+	}
+
+	// Irregular plurals not covered by suffix rules
+	const irregular: Record<string, string> = {
+		people: 'person',
+		men: 'man',
+		women: 'woman',
+		children: 'child',
+		geese: 'goose',
+		mice: 'mouse',
+		teeth: 'tooth',
+		feet: 'foot',
+		oxen: 'ox',
+		indices: 'index',
+		matrices: 'matrix',
+		vertices: 'vertex',
+	};
+	if (Object.prototype.hasOwnProperty.call(irregular, lower)) {
+		const singular = irregular[lower];
+		// Preserve capitalization of the first letter
+		if (word[0] === word[0].toUpperCase()) {
+			return singular.charAt(0).toUpperCase() + singular.slice(1);
+		}
+		return singular;
+	}
+
+	if (word.endsWith('ies')) {
+		return word.slice(0, -3) + 'y';
+	}
+	if (word.endsWith('es')) {
+		if (word.endsWith('xes') || word.endsWith('ses') || word.endsWith('ches') || word.endsWith('shes')) {
+			return word.slice(0, -2);
+		}
+	}
+	if (word.endsWith('s') && !word.endsWith('ss')) {
+		return word.slice(0, -1);
+	}
+	return word;
+}

package/utils/sleep.ts

@@ -0,0 +1,3 @@
+export function sleep(ms: number) {
+	return new Promise(resolve => setTimeout(resolve, ms));
+}

package/utils/tableMeta.ts

@@ -0,0 +1,5 @@
+export interface TableMeta {
+	singular: string;
+	plural: string;
+	databaseName: string;
+}

package/utils/writeIfChanged.ts

@@ -0,0 +1,13 @@
+import fs from 'fs';
+import path from 'path';
+import { getLogger } from './logger.ts';
+
+export function writeIfChanged(filePath: string, content: string) {
+	const dir = path.dirname(filePath);
+	if (!fs.existsSync(dir)) { fs.mkdirSync(dir, { recursive: true }); }
+	const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : undefined;
+	if (existing !== content) {
+		fs.writeFileSync(filePath, content, 'utf8');
+		getLogger().debug?.(`Updated types in ${filePath}`);
+	}
+}