Contentstack - TypeScript generation library

This library helps to generate TypeScript type definition for the content types available in a Stack.

Installation

$ npm install @contentstack/types-generator

Usage

In NodeJs

require("@contentstack/types-generator") for Common JS (CJS)

OR

import {<< required method >>} from "@contentstack/types-generator" for ECMAScript Modules (ESM)

In Web application

import {<< required method >>} from "@contentstack/types-generator/dist/web"

Usage Guide

1. generateTS() (Available for both NodeJS and Web application)

This is an asynchronous method which generates Typescript type definition of the content types available in a Stack using given inputs. Use this method for REST API.

Input:

Property Name	Description	Data type	Accepted values	Mandatory	Default value
token	Unique identifier used for authorization	String		Yes
tokenType	Type of token being provided (Currently we are supporting only delivery token)	String	delivery	Yes
apiKey	Stack API key	String		Yes
environment	Name of the environment (example: development, staging, production)	String		Yes
region	Contentstack API region	String	US (for AWS NA), EU (for AWS EU), AZURE_NA, AZURE_EU, GCP_NA	Yes
branch	Stack branch name	String		No
prefix	Optional prefix to add for each interface	String		No
includeDocumentation	To add content type documentation in the generated file	boolean	true, false	No	true
systemFields	Boolean flag indicating whether to include system-generated fields in the response	boolean	true, false	No	false

Output:

Returns a Promise that resolves with data or rejects with an error.

If resolved:

Type: String

Data: Generated Typescript type definition

If rejected:

Type: Error Object

Data: An object with error_message

Example usage: generateTS()

import { generateTS } from "@contentstack/types-generator"; // Import statement for NodeJS
import { generateTS } from "@contentstack/types-generator/dist/web"; // Import statement for Web application

async function getTypeDef() {
  try {
    const typeDef = await generateTS({
      token: "<< your_delivery_token >>",
      tokenType: "delivery", // Currently we are supporting only delivery token
      apiKey: "<< your_stack_api_key >>",
      environment: "development",
      region: "US",
      branch: "main",
      prefix: "CS",
      includeDocumentation: true,
      systemFields: false,
    });

    // Handle the resolved promise, e.g., process the typeDef
  } catch (error) {
    // Handle the rejected promise
    // error: { error_message: "Unauthorized! Please check the given token and api key" }
  }
}

getTypeDef();

Example output: generateTS()

/** This is a description. */
interface BuiltinExample {
  /** Title */
  title: string;
  /** URL */
  url: string;
  /** Group1 */
  group1?: {
    /** Group2 */
    group2?: {
      /** Group3 */
      group3?: {
        /** Number */
        number?: number;
      };
    };
  };
  /** SEO */
  seo?: Seo;
  /** Single line textbox */
  single_line?: string;
  /** Multi line textbox */
  multi_line?: string;
  /** Rich text editor */
  rich_text_editor?: string;
  /** Multiple Single Line Textbox */
  multiple_single_line_textbox?: string[];
  /** Markdown */
  markdown?: string;
  /** Multiple Choice */
  multiple_choice?: ("Choice 1" | "Choice 2" | "Choice 3")[];
  /** Single Choice */
  single_choice: "Choice 1" | "Choice 2" | "Choice 3";
  /** Modular Blocks */
  modular_blocks?: ModularBlocks[];
  /** Number */
  number?: number;
  /** Link */
  link?: Link;
  /** File */
  file?: File;
  /** Boolean */
  boolean?: boolean;
  /** Date */
  date?: string;
}

interface ModularBlocks {
  block_1: {
    /** Number */
    number?: number;
    /** Single line textbox */
    single_line?: string;
  };
  block_2: {
    /** Boolean */
    boolean?: boolean;
    /** Date */
    date?: string;
  };
  seo_gf: {
    /** Keywords */
    keywords?: string;
    /** Description */
    description?: string;
  };
}

2. graphqlTS() (Available only for NodeJS)

This is an asynchronous method which generates Typescript type definition of the content types available in a Stack using given inputs for GraphQL. Use this method for GraphQL.

Input:

Property Name	Description	Data type	Accepted values	Mandatory
token	Unique identifier used for authorization. This should be the delivery token of the stack.	String		Yes
apiKey	Stack API key	String		Yes
environment	Name of the environment (example: development, staging, production)	String		Yes
region	Contentstack API region	String	US (for AWS NA), EU (for AWS EU), AZURE_NA, AZURE_EU, GCP_NA	Yes
branch	Stack branch name	String		No
namespace	Identifies the specific namespace within schema	String		No

Output:

Returns a Promise that resolves with data or rejects with an error.

If resolved:

Type: String

Data: Generated Typescript type definition

If rejected:

Type: Error Object

Data: An object with error_message

Example usage: graphqlTS()

import { graphqlTS } from "@contentstack/types-generator"; // Import statement for NodeJS

async function getTypeDef() {
  try {
    const typeDef = await graphqlTS({
      token: "<< your_delivery_token >>", // Currently we are supporting only delivery token
      apiKey: "<< your_stack_api_key >>",
      environment: "development",
      region: "US",
      branch: "main",
      namespace: "<< your_name_space >>",
    });

    // Handle the resolved promise, e.g., process the typeDef
  } catch (error) {
    // Handle the rejected promise
    // error: { error_message: "Unauthorized! Please check the given token and api key" }
  }
}

getTypeDef();