Committing Data Using TypeScript SDK

Essentials of committing data to a repo using a TypeScript SDK generated for your repo by WarmHub

Introduction

Based on the types which you have imported and created in your repo, you can download a SDK which contains type definitions to easily interface with the WarmHub type structure in TypeScript.

Project Structure

The SDK generated by WarmHub is provided in the form of a downloadable .zip file, which contains a TypeScript project. The file structure is as follows:

• src/ : Directory containing your repo's types and scaffolding code

  • schemas.ts contains the TypeScript definitions of the types in your repo, resembling all of the types you may post to your repo. They are expressed in the form of Zod objects and available as TypeScript types.

  • index.ts is the entry point to your program. If you would like to use the project as-is, it contains initialization code for environment variables and an instantiation of the main Client object for committing to your repo.

  • __tests__ contains one unit test which you can run to confirm that you've set up the environment correctly.

• There is a .env file which you may use to set your AUTH_TOKEN .

• package.json, tsconfig.json, and vitest.config.ts configure the project.

Getting Started

Downloading the SDK

To use the TypeScript SDK locally, you'll need a local Node.js and TypeScript development environment:

• Text editor

• Package manager (npm or pnpm)

  • Internet connection

• Command line interface

You will also need a repo with types in it. Once you have prepared your repo, go to the "About" page and select "TypeScript SDK." This will download .zip file to your computer. Unpack the archive, and open the directory in your preferred text editor.

The TypeScript SDK download button is only present in repos in which you have permission to post data. The "Commit Tools" section is hidden in repos which you cannot post data.

The TypeScript SDK button is located in the "Commit Tools" section

Setting up the SDK

After opening the project in your text editor, we can configure the environment variables and set up the packages. Personal Access Tokens are required to authenticate with the commit endpoint. First, generate a token, and paste it into the content of your .env file. The file should look like the following:

AUTH_TOKEN=this_is_your_token

Then, set up and build the project packages:

npm

npm i
npm run build

pnpm

pnpm i
pnpm build

You can validate whether everything has gone correctly by running the unit test:

npm

npm test

pnpm

pnpm build

Creating a Commit

The [your repo]Client object exposes a method commit(Commit). The Commit object has additions, retractions, and revisions in the same structure as if you would post a JSON object manually to your repo's commit endpoint.

import 'dotenv/config';
import { Commit, [org, repo]Client } from "./schemas";

const client = new [org, repo]Client()

const commit = new Commit()

// Assemble your commit below: add, revise, or retract instances
// commit.add(instance)
// commit.revise(revises, revised)
// commit.retract(retraction)

client.commit(commit)

For a walkthrough of using the TypeScript SDK, see the guideCommitting More Data to the Units of Measurement Repo (TS)