Getting Started

This tutorial will walk you through setting up a simple node project, generating code and making requests against the API.

Prerequisites

Before starting this guide you will need the following:

• npm & node installed on your environment

• the sfdx-cli installed and a developer or scratch ORG connected

This tutorial will create records, so do not connect with a production org!

Project Setup

Create a new typescript project:

$ mkdir ts-force-example
$ cd ts-force-example
$ mkdir src
$ npm init
$ npm install -D typescript ts-node
$ npx tsc --init

Open tsconfig.json and add the following:

"experimentalDecorators": true

The generated classes use "experimentalDecorators".

Install ts-force

$ npm install ts-force
$ npm install -D ts-force-gen

These two packages should always be on the same version!

Configure code generation

Next we need to create the configuration file which will tell the code generator what to do:

$ npx ts-force-gen --init

You should now see a ts-force-config.json in the folder where you ran the command. It's contents should look something like this:

ts-force-config.json

{
  "$schema": "https://raw.githubusercontent.com/ChuckJonas/ts-force/master/ts-force-gen/ts-force-config.schema.json",
  "sObjects": [
    "Account",
    "Contact"
  ],
  "auth": {
    "username": "[e-mail]"
  },
  "outPath": "./src/generated/"
}

For now, just update the auth.username property to a connected sfdx-cli username.

Alternate authentication methods are supported. To see a full list of options, see "ts-force-config" api section

Run Code Generation

$ npx ts-force-gen

After this completes, you should see that generated classes have been added to src/generated for the sObjects listed in our config.

Using ts-force

We will again use the sfdx-cli obtain a Salesforce access token. To do so from node, we'll need an additional dependency:

$ npm install @salesforce/core

In a production environment, you would likely obtain the access token via oAuth or other means. See the "Connecting with Salesforce" section for more details.

Create a new file src/index.ts and add the following code

src/index.ts

import { AuthInfo, Connection, Org } from '@salesforce/core';
import { Account, Contact } from './generated';
import { CompositeCollection, getStandardError, Rest } from 'ts-force';

// an async self invoking function (main)
(async () => {
  // setup client
  const { accessToken, instanceUrl } = await auth('[e-mail]'); // update username!
  const restInstance = new Rest({
    accessToken,
    instanceUrl,
  });

  // create a new account
  const acmeAccount = new Account({ name: 'acme', industry: 'manufacturing' }, restInstance);
  await acmeAccount.insert();

  console.log(acmeAccount.id);

  // create 2 contacts
  const collection = new CompositeCollection(restInstance);
  await collection.insert([
    new Contact({ accountId: acmeAccount.id, firstName: 'road', lastName: 'runner' }),
    new Contact({ accountId: acmeAccount.id, firstName: 'wile', lastName: 'coyote' }),
  ]);

  // run query contacts on "manufacturing" accounts
  const contacts = await Contact.retrieve(
    (f) => ({
      select: [...f.select('id', 'name'), ...f.parent('account').select('id', 'name')],
      where: [{ field: f.parent('account').select('industry'), val: 'manufacturing' }],
    }),
    { restInstance },
  );

  console.log(contacts.length);
  contacts.forEach((c) => console.log(c.name, c.account?.name));

  // cleanup records
  await acmeAccount.delete();
  await collection.delete(contacts);
})().catch((e) => {
  const stdErr = getStandardError(e);
  console.error(JSON.stringify(stdErr.errorDetails));
});

/* helper function to get connection for SFDX-CLI */
async function auth(username: string) {
  const authInfo = await AuthInfo.create({ username });
  const connection = await Connection.create({ authInfo });
  const org = await Org.create({ connection });
  await org.refreshAuth();
  return org.getConnection();
}

This code does the following:

• Creates a Rest instance from via a sfdx-cli org connection

• Inserts an Account

• Inserts 2 Contacts related to the Account

• Queries Contacts where Account.Industry = 'manufacturing'

• Cleans up (deletes) the created records

See it in action

Use the following command to run the code:

$ npx ts-node src/index

Next Steps

Check out the following resources:

• Connecting with Salesforce

• RestObject API

• SOQL Builder

• Composite API