⚠️ DEPRECATION NOTICE: The string-based Model class and QueryBuilder are deprecated and will be removed in v2.0.0. Please migrate to LambdaModel for type-safe queries with closure variable support. See Migration Guide.

Salesforce ORM

A TypeScript ORM library for Salesforce with lambda-based queries, full type inference, and closure variable support.

📚 Full Documentation | 🆕 LambdaModel Guide | 🔄 Migration Guide

✨ Core Features

🎯 Type-Safe Lambda Queries

Write queries with full IntelliSense and compile-time type checking:

// Define your model
class Account extends LambdaModel<AccountData> {
  protected static objectName = 'Account';
}

// Query with type safety
const accounts = await Account
  .select(x => ({
    Id: x.Id,           // ✓ IntelliSense works!
    Name: x.Name,       // ✓ Typos caught at compile time
    Industry: x.Industry
  }))
  .limit(10)
  .get();

🔗 Closure Variable Support

Use variables from outer scope naturally:

const industry = 'Technology';
const minRevenue = 1000000;

const accounts = await Account
  .select(x => ({ Id: x.Id, Name: x.Name }))
  .where(x => x.Industry === industry && x.AnnualRevenue > minRevenue)
  .get();

📋 WHERE IN Queries

Array membership with automatic WHERE IN detection:

const industries = ['Technology', 'Finance', 'Healthcare'];

const accounts = await Account
  .select(x => ({ Id: x.Id, Name: x.Name }))
  .where(x => x.Industry.includes(industries))
  .get();
// SOQL: WHERE Industry IN ('Technology', 'Finance', 'Healthcare')

🌳 Relationship Queries with Closures

Query subqueries with full closure support:

const activeStatus = true;

const accounts = await Account
  .select(x => ({
    Name: x.Name,
    ActiveContacts: x.Contacts
      .select(c => ({ Name: c.Name, Email: c.Email }))
      .where(c => c.Active__c === activeStatus)  // ✓ Closures work in subqueries!
  }))
  .get();

🔧 Automatic Model Generation

Generate TypeScript models from Salesforce metadata:

# Initialize configuration
npx sfc init

# Generate models with full type safety
npx sfc scaffold Account Contact Opportunity

🪝 Lifecycle Hooks (Observers)

React to model events without modifying model classes:

class AuditLogObserver implements Observer<Account> {
  async afterCreate(account: Account) {
    console.log(`Account created: ${account.Id}`);
  }
}

Account.observe(new AuditLogObserver());

📄 Smart Pagination

Built-in pagination with metadata:

const { records, totalSize, hasNextPage } = await Account
  .select(x => ({ Id: x.Id, Name: x.Name }))
  .where(x => x.Industry === 'Technology')
  .paginate(1, 20);  // Page 1, 20 per page

Quick Start

Installation

npm install javascript-salesforce-connector

Basic Usage

import { SalesforceConfig, LambdaModel } from 'javascript-salesforce-connector';
import { Account } from './models/Account';

// Configure connection
SalesforceConfig.initialize({
  instanceUrl: 'https://your-instance.salesforce.com',
  apiVersion: 'v59.0'
});
SalesforceConfig.setAccessToken('your-access-token');

// Query with type safety
const industry = 'Technology';
const accounts = await Account
  .select(x => ({ Id: x.Id, Name: x.Name, Industry: x.Industry }))
  .where(x => x.Industry === industry)
  .limit(10)
  .get();

// Create a record
const account = await Account.create({
  Name: 'Acme Corporation',
  Industry: 'Technology'
});

// Update a record
account.Industry = 'Finance';
await account.save();

// Delete a record
await account.delete();

Documentation

📚 View Full Documentation

Getting Started

• Installation & Configuration
• Quick Start Guide

Models

• Defining Models
• Model Generation (CLI)

Querying

• Lambda Queries (Recommended)
• Basic Queries
• Advanced Queries
• Relationships & Subqueries

CRUD Operations

• Creating Records
• Reading Records
• Updating Records
• Deleting Records

Advanced

• Lifecycle Hooks (Observers)
• Closure Variables Deep Dive
• Error Handling

CLI

• CLI Commands Reference
• Authentication Setup

Important Notes

⚠️ Governor Limits: This library does NOT automatically handle Salesforce governor limits. Always use .limit() and proper filtering.

⚠️ Observers vs Salesforce Triggers: Observers are JavaScript/TypeScript hooks that run in your application. They are NOT Salesforce Triggers, Process Builder, or Flows.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Links

• 📦 NPM Package
• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions