joi-to-typescript

joi-to-typescript on GitHub

Convert Joi Schemas to TypeScript interfaces

This will allow you to reuse a Joi Schema that validates your Hapi API to generate TypeScript interfaces so you don't have to manually create the same structure again saving you time.

Installation Notes

This package is intended as a development time tool so is installed in the devDependencies

yarn add joi-to-typescript --dev
# or
npm install joi-to-typescript --save-dev

• This has been built for "joi": "^17.2.1" and will probaly not work for older versions, mainly due to package name changes
• Minimum node version 12 as Joi requries node 12

Suggested Usage

1. Create a Schemas Folder eg. src/schemas
2. Create a interfaces Folder eg. src/interfaces
3. Create Joi Schemas in the Schemas folder with a file name suffix of Schemas eg. AddressSchema.ts
   • The file name suffix ensures that type file and schema file imports are not confusing

Example

Example Project

Explore the Example Project for recommended setup, it allows the use of yarn types or npm run types to run this package

Example Schema

This example can be found in src/__tests__/readme

import Joi from 'joi';

// Input
export const JobSchema = Joi.object({
  businessName: Joi.string().required(),
  jobTitle: Joi.string().required()
}).label('Job');

export const PersonSchema = Joi.object({
  firstName: Joi.string().required(),
  lastName: Joi.string()
    .required()
    .description('Last Name'),
  job: JobSchema
}).label('Person');

export const PeopleSchema = Joi.array()
  .items(PersonSchema)
  .required()
  .label('People')
  .description('A list of People');

// Output
/**
 * This file was automatically generated by joi-to-typescript
 * Do not modify this file manually
 */

export interface Job {
  businessName: string;
  jobTitle: string;
}

/**
 * A list of People
 */
export type People = Person[];

/**
 * Person
 */
export interface Person {
  firstName: string;
  job?: Job;
  /**
   * Last Name
   */
  lastName: string;
}

Points of Interest

• export const PersonSchema schema must be exported
• export const PersonSchema includes a suffix of Schema so the schema and interface are not confused when using import statements (recommended not requried)
• .label('Person'); Sets interface name using TypeScript conventions (TitleCase Interface name, camlCase property name)

Example Call

import { convertFromDirectory } from 'joi-to-typescript';

convertFromDirectory({
  schemaDirectory: './src/schemas',
  typeOutputDirectory: './src/interfaces',
  debug: true
});

// or to get an interface as a string. Please note that this method is limited
import { convertSchema } from 'joi-to-typescript';
const resultingInterface = convertSchema({}, JobSchema);
resultingInterface?.content = // the interface as a string

Settings

export interface Settings {
  /**
   * The input/schema directory
   * Directory must exist
   */
  schemaDirectory: string;
  /**
   * The output/type directory
   * Will also attempt to create this directory
   */
  typeOutputDirectory: string;
  /**
   * Should interface properties be defaulted to optional or required
   */
  defaultToRequired: boolean;
  /**
   * What schema file name suffix will be removed when creating the interface file name
   * Defaults to `Schema`
   * This ensures that an interface and Schema with the file name are not confused
   */
  schemaFileSuffix: string;
  /**
   * If `true` the console will include more information
   */
  debug: boolean;
  /**
   * File Header content for generated files
   */
  fileHeader: string;
  /**
   * If true will sort properties on interface by name
   * Defaults to `true`
   */
  sortPropertiesByName: boolean;
  /**
   * If true will not output to subDirectories in output/interface directory. It will flatten the structure.
   */
  flattenTree: boolean;
  /**
   * If true will only read the files in the root directory of the input/schema directory. Will not parse through sub-directories.
   */
  rootDirectoryOnly: boolean;
  /**
   * If true will write all exports *'s to root index.ts in output/interface directory.
   */
  indexAllToRoot: boolean;
  /**
   * Comment every interface and property even with just a duplicate of the interface and property name
   * Defaults to `false`
   */
  commentEverything: boolean;
  /**
   * List of files or folders that should be ignored from conversion. These can either be
   * filenames (AddressSchema.ts) or filepaths postfixed with a / (addressSchemas/)
   */
  ignoreFiles: string[];
  /**
   * The indentation characters
   * @default '  ' (two spaces)
   */
  indentationChacters: string;
}

Joi Features Supported

• .label('InterfaceName') - interface Name and in jsDoc
• .description('What this interface is for') - jsdoc
• .valid(['red', 'green', 'blue']) - enumerations
• .optional() - optional properties ?
• .requried() - required properties
• .array(), .object(), .string(), .number(), .boolean() - standard Joi schemas
• .alternatives()
• .allow('') - will be ignored on a string
• .allow(null) - will add as an optional type eg string | null
• .unknown(true) - will add a property [x: string]: any;
• .example() - jsdoc

Joi Features not listed here will probably be ignored

Contributing

• Raise or comment on an Issue with a bug or feature request
• Contribute code via Raising a Pull Request
• Start a Discussion

Recommended Development Environment

Recommended Editor is VS Code, this project is setup with VSCode settings in the ./.vscode directory to keep development consistant.

Best developed on macOS, Linux, or on Windows via WSL. Node 12, 14, or 16

Install nodejs via nvm so you can have multiple versions installed

nvm use # using NVM to select node version
yarn install # using yarn
yarn test # run local tests

yarn coverage # test coverage report
yarn lint # lint the code