Introduction

@kysoql/core is where you build and compile typed SOQL queries. It has no Salesforce HTTP dependency, so you can use it for compile-only workflows or pair it with any executor that implements Kysoql's execution contract.

The API takes inspiration from Kysely, but the behaviour is Salesforce-native. SOQL relationships, aggregates, TYPEOF, FIELDS(), Apex-only clauses, and other Salesforce features are modelled directly rather than squeezed into SQL concepts.

InstallCopy Anchor Link

pnpm add @kysoql/core

Build a typed queryCopy Anchor Link

Most applications generate SalesforceSchema and salesforceSchemaMetadata with @kysoql/codegen:

import { Kysoql } from "@kysoql/core";
import {
  salesforceSchemaMetadata,
  type SalesforceSchema,
} from "./kysoql/salesforce.generated";

const db = new Kysoql<SalesforceSchema>({
  schemaMetadata: salesforceSchemaMetadata,
});

const query = db
  .selectFrom("Account")
  .select(["Id", "Name"])
  .where("Name", "like", "Acme%")
  .orderBy("Name")
  .limit(25);

console.log(query.compile().soql);

You can also hand-author a schema for specialised or offline use cases. Generated schemas are the normal path because they reflect the objects and capabilities of a real Salesforce org.

What core gives youCopy Anchor Link

• immutable query builders with inferred result types
• typed filters, relationship paths, subqueries, aggregates, and Salesforce functions
• schema capability types used by generated metadata
• the QueryExecutor contract for REST, JSforce, and custom transports
• compile-only Apex builders for Apex-specific syntax
• plugins for query and result transformations

Core does not authenticate to Salesforce or make HTTP requests. Use @kysoql/rest for the native transport or @kysoql/jsforce when your application already has a JSforce connection.

Continue with the mental model, or follow getting started for a complete setup.