conjure-typescript

conjure-typescript

CLI to generate TypeScript Interfaces and clients from Conjure API definitions.

Overview

The generated clients provide a simple Promise based interface for executing strongly typed remote procedure calls from the browser or node.

Usage

The recommended way to use conjure-typescript is via a build tool like gradle-conjure. However, if you don't want to use gradle-conjure, there is also an executable which conforms to RFC 002, published on maven.org.

conjure-typescript generate <input> <output> [..Options]

Generate TypeScript bindings for a Conjure API

Positionals:
  input   The location of the API IR
  output  The output directory for the generated code

Options:
  --version                      Show version number                                                                     [boolean]
  --help                         Show help                                                                               [boolean]
  --packageVersion               The version of the generated package                                                     [string]
  --packageName                  The name of the generated package                                                        [string]
  --flavorizedAliases            Generates flavoured types for compatible aliases.                      [boolean] [default: false]
  --nodeCompatibleModules        Generate node compatible javascript                                    [boolean] [default: false]
  --rawSource                    Generate raw source without any package metadata                       [boolean] [default: false]
  --readonlyInterfaces           Generated interfaces have readonly properties and collections          [boolean] [default: false]
  --productDependencies          Path to a file containing a list of product dependencies                                 [string]
  --generateThrowingServices     Generate services whose methods rethrow thrown API errors               [boolean] [default: true]
  --generateNonThrowingServices  Generate services whose methods return thrown API errors as results    [boolean] [default: false]

SemVer releases

This project is versioned according to SemVer. We consider the generated code to be part of the 'public API' of conjure-typescript, i.e. TypeScript generated by old conjure-typescript and new conjure-typescript (within a major version) should be compatible, so your consumers should be able to upgrade without compilation problems.

We also consider the command line interface and feature flags to be public API.

Example generated objects

• Conjure object: ManyFieldExample

  Objects can easily be instantiated:

  const example: ManyFieldExample = {
    string: "foo",
    integer: 123,
    optionalItem: "bar",
    items: []
  }
  

• Conjure union: UnionTypeExample

  Union types can be one of a few variants. To interact with a union value, users should use the .accept method and define a Visitor that handles each of the possible variants, including the possibility of an unknown variant.

  const unionExample = IUnionTypeExample.string("Hello, world");
  
  const output = IUnionTypeExample.visit(unionExample, {
  
      string: (value: string) => {
          // your logic here!
      },
  
      set: (value: string[]) => {},
  
      // ...
  
      unknown: (unknownType: IUnionTypeExample) => {}
  
  });
  

  Visitors may seem clunky in TypeScript, but they have the upside of compile-time assurance that you've handled all the possible variants. If you upgrade an API dependency and the API author added a new variant, the TypeScript compiler will force you to explicitly deal with this new variant. We intentionally avoid switch statements.

  We also generate type-guards:

  if (IUnionTypeExample.isString(unionTypeExample)) {
      const inner: string = unionTypeExample.string;
  }
  

• Conjure enum: EnumExample

  conjure-typescript leverages TypeScript's namespaces.

  export namespace EnumExample {
      export type ONE = "ONE";
      export type TWO = "TWO";
  
      export const ONE = "ONE" as "ONE";
      export const TWO = "TWO" as "TWO";
  }
  
  export type EnumExample = keyof typeof EnumExample;
  
  console.log(EnumExample.ONE); // prints "ONE"
  

• Conjure alias

  TypeScript uses structural (duck-typing) so aliases are currently elided.

Example Client interfaces

Example service interface: PrimitiveService

export interface IPrimitiveService {
    getPrimitive(): Promise<number>;
}

export class PrimitiveService {
    public getPrimitive(): Promise<number> {
        return this.bridge.callEndpoint<number>({
            endpointName: "getPrimitive",
            endpointPath: "/getPrimitive",
            method: "GET",
            requestMediaType: MediaType.APPLICATION_JSON,
            responseMediaType: MediaType.APPLICATION_JSON,
        });
    }
}

Constructing clients

Use clients from conjure-typescript-runtime which configures the browser's Fetch API with sensible defaults:

import { DefaultHttpApiBridge } from "conjure-client";
const recipes = new RecipeBookService(new DefaultHttpApiBridge({
    baseUrl: "https://some.base.url.com",
    userAgent: {
        productName: "yourProductName",
        productVersion: "1.0.0"
    }
}));

const results: Recipe[] = await recipes.getRecipes();

Contributing

For instructions on how to set up your local development environment, check out the Contributing document.

License

This project is made available under the Apache 2.0 License.