@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!

npm install --save @harperfast/schema-codegen

Drop this in your Harper application's config.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:

'@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.

Options

Option	Default	Description
globalTypes	—	Path to write the ambient module augmentation (.d.ts).
schemaTypes	—	Path to write the exported interfaces (.ts).
jsdoc	—	Path to write JSDoc types instead, for pure JavaScript projects.
module	harper	The runtime package to augment. Harper 5.x apps import from harper; set this to harperdb for Harper 4.x apps.
includeDatabases	(all)	List of database names to generate types for. When set, only matching databases are emitted. Supports * as a wildcard, e.g. metrics-*.
excludeDatabases	(none)	List of database names to skip. Useful on a shared instance to keep other applications' databases out of your generated types. Supports * as a wildcard.

includeDatabases/excludeDatabases scope generation to your application's own databases. On a shared local instance, codegen otherwise sees every database on the instance — including ones belonging to other projects — so scoping keeps your generated types focused:

'@harperfast/schema-codegen':
  package: '@harperfast/schema-codegen'
  globalTypes: 'schemas/globalTypes.d.ts'
  schemaTypes: 'schemas/types.ts'
  includeDatabases:
    - data
    - 'metrics-*'

Example

For example, here's a tracks.graphql schema:

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:

/**
 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:

/**
 Generated from your schema files
 Manual changes will be lost!
 > harper dev .
 */
import type { Table } from 'harper';
import type { Track } from './types.ts';

declare module 'harper' {
	export const tables: {
		Tracks: { new (...args: any[]): Table<Track> };
	};
	export const databases: {
		data: {
			Tracks: { new (...args: any[]): Table<Track> };
		};
	};
}

Development

To use this in an application, first link it:

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:

cd ~/my-awesome-app
npm link @harperfast/schema-codegen