Skip to content
Conjure generator for TypeScript clients
TypeScript Shell JavaScript
Branch: develop
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
.github Excavator: Update policy-bot config (#111) Oct 14, 2019
bin [fix] Fix dumb error in batch script (#97) Jul 9, 2019
changelog
scripts Top level binary type is generated as Blob type with correct response… Aug 8, 2019
src Break: Return ReadableStream<Uint8Array> for binary endpoints (#126) Jan 6, 2020
.bulldozer.yml
.changelog.yml
.excavator.yml Excavator: Auto-label some excavator PRs (#107) Sep 23, 2019
.gitignore
.npmignore
.policy.yml
CONTRIBUTING.md add README and CONTRIBUTING (#39) Jul 9, 2018
LICENSE
README.md
jest.config.js
karma.conf.js Integration tests (#40) Jul 12, 2018
package.json
tslint.json
versions.props Break: Return ReadableStream<Uint8Array> for binary endpoints (#126) Jan 6, 2020
webpack.config.js
yarn.lock Break: Return ReadableStream<Uint8Array> for binary endpoints (#126) Jan 6, 2020

README.md

Autorelease

conjure-typescript NPM License

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 bintray.

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]
  --nodeCompatibleModules  Generate node compatible javascript                        [boolean] [default: false]
  --rawSource              Generate raw source without any package metadata           [boolean] [default: false]
  --productDependencies    Path to a file containing a list of product dependencies                     [string]

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 string Enums.

    export enum EnumExample {
        ONE = "ONE",
        TWO = "TWO"
    }
    
    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.

You can’t perform that action at this time.