Dates, times, and currency

Use Kysoql's literal helpers when a SOQL value has syntax that should not be represented by an ordinary JavaScript string.

Date, DateTime, and Time valuesCopy Anchor Link

import { soqlDate, soqlDateTime } from "@kysoql/core";
import { db } from "./db";

const query = db
  .selectFrom("Opportunity")
  .select(["Id", "CloseDate", "CreatedDate"])
  .where("CloseDate", ">=", soqlDate("2026-09-01"))
  .where("CreatedDate", "<", soqlDateTime("2026-10-01T00:00:00Z"));

The helpers validate the input shape, calendar values, clock values, and timezone offsets. They preserve the value you pass rather than converting it to another timezone.

To use a JavaScript Date, convert it explicitly:

import { soqlDateTime } from "@kysoql/core";

const instant = soqlDateTime(new Date().toISOString());

Use a date literal with Date fields, a datetime literal with DateTime fields, and a time literal with Time fields.

Relative date literalsCopy Anchor Link

import { soqlRelativeDate } from "@kysoql/core";
import { db } from "./db";

const query = db
  .selectFrom("Opportunity")
  .select(["Id", "CloseDate"])
  .where("CloseDate", "=", soqlRelativeDate("THIS_MONTH"))
  .where("CreatedDate", "=", soqlRelativeDate("LAST_N_DAYS", 30));

Common fixed literals include TODAY, YESTERDAY, THIS_WEEK, LAST_MONTH, NEXT_QUARTER, and the fiscal-calendar equivalents.

Parameterized families include LAST_N_DAYS, NEXT_N_WEEKS, N_MONTHS_AGO, and the matching quarter, year, and fiscal variants.

Pass the count separately:

import { soqlRelativeDate } from "@kysoql/core";

soqlRelativeDate("LAST_N_DAYS", 30)

Kysoql compiles that value as LAST_N_DAYS:30.

Salesforce evaluates relative date ranges on the server. Their exact calendar and timezone behaviour comes from Salesforce, not from the JavaScript runtime.

Currency literalsCopy Anchor Link

Use soqlCurrency() when a multi-currency filter needs an explicit ISO code:

import { soqlCurrency } from "@kysoql/core";
import { db } from "./db";

const query = db
  .selectFrom("Opportunity")
  .select(["Id", "Amount"])
  .where("Amount", ">=", soqlCurrency("USD", 5000));
// WHERE Amount >= USD5000

The ISO code must be exactly three uppercase ASCII letters and the value must be finite. Kysoql validates that shape, but Salesforce still decides whether the currency is enabled in the org.

An IN or NOT IN list must use either normal numeric values or ISO-coded currency literals. Do not mix the two forms in one list.

For converting selected currency values into the querying user's currency, see convertCurrency().