ts-prorm-orm 1.1.0 → 1.2.0

package/dist/query-builders/functions/datetime.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Typed date/time function builder API.
+ *
+ * Date truncation, date arithmetic (add/subtract), date-difference, "current
+ * date/time" helpers, and best-effort date formatting differ WILDLY across
+ * the 11 SQL dialects this ORM supports (Postgres `DATE_TRUNC`, MySQL
+ * `DATE_ADD`/`DATEDIFF`, MSSQL `DATEADD`/`DATEDIFF`, Oracle `TRUNC`/
+ * `ADD_MONTHS`, SQLite `strftime`/`julianday`, etc). This module gives callers
+ * a single typed entry point per capability so they never have to hand-write
+ * dialect-specific SQL strings themselves.
+ *
+ * This module is intentionally self-contained, mirroring the approach taken
+ * in `src/query-builders/functions/window.ts`: it does NOT add any new
+ * dispatch branches to the shared SQL compiler (`src/query-builders/
+ * sql-compiler.ts`) or to `src/operators.ts`. Every function below computes
+ * a final, dialect-correct SQL fragment string directly and wraps it with the
+ * existing `literal()` helper from `src/operators.ts` so it slots into
+ * `attributes: [...]` / `where` clauses exactly the way `fn()`/`col()`/
+ * `cast()`/`extract()` do today.
+ *
+ * @example
+ * ```typescript
+ * import { dateTrunc, dateAdd, dateDiff, now, formatDate } from './query-builders/functions/datetime';
+ * import { col } from '../../operators';
+ *
+ * User.findAll({
+ *   attributes: [
+ *     'id',
+ *     dateTrunc('postgres', 'month', col('createdAt')).as('signupMonth'),
+ *     dateAdd('postgres', col('createdAt'), 30, 'day').as('trialEnds'),
+ *     dateDiff('mysql', 'day', col('startDate'), col('endDate')).as('durationDays'),
+ *     now('sqlite').as('rightNow'),
+ *     formatDate('postgres', col('createdAt'), 'YYYY-MM-DD').as('createdAtStr'),
+ *   ],
+ * });
+ * ```
+ */
+import { type FnExpression, type ColExpression, type LiteralExpression } from '../../operators';
+import type { Dialect } from '../../types/index';
+/** Any value accepted where a date/time expression or column is expected. */
+export type DateTimeArg = string | number | Date | ColExpression | FnExpression | LiteralExpression | {
+    $literal: string;
+} | DateTimeExpression | null | undefined;
+/**
+ * A wrapped, dialect-resolved SQL expression produced by the functions below.
+ * Renders through the same `{ $literal }` channel that `Op.literal()` /
+ * `literal()` already produce, so it can be used anywhere an attribute
+ * expression, WHERE value, or ORDER BY expression is accepted.
+ */
+export interface DateTimeExpression {
+    __type: 'literal';
+    sql: string;
+    $literal: string;
+    /** Wrap this expression with an alias, returning an `[expr, alias]` tuple. */
+    as(alias: string): [DateTimeExpression, string];
+}
+export type DateTruncUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
+export type DateAddUnit = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second';
+export type DateDiffUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
+/**
+ * Truncate a date/timestamp expression down to the start of the given unit
+ * boundary (year/quarter/month/week/day/hour/minute/second).
+ *
+ * Dialect notes:
+ * - postgres / cockroachdb / redshift: native `DATE_TRUNC('unit', expr)`.
+ * - mysql / mariadb: NO native DATE_TRUNC exists (verified) — built via
+ *   `DATE_FORMAT`/string-concat + `STR_TO_DATE` workarounds.
+ * - mssql: uses `DATETRUNC(datepart, expr)`, added in SQL Server 2022. For
+ *   older MSSQL versions there is no native equivalent; this targets modern
+ *   SQL Server.
+ * - oracle: `TRUNC(expr, fmt)`. Oracle's TRUNC only truncates down to
+ *   hour/minute ('HH24'/'MI'); truncating to 'second' is a no-op since DATE
+ *   values already carry second precision, so `expr` is returned unchanged.
+ * - sqlite: no native function — built via `strftime()`/string-concat.
+ * - db2: no native DATE_TRUNC — built via `VARCHAR_FORMAT`/`TIMESTAMP_FORMAT`
+ *   round-tripping (Db2's TO_CHAR/TO_DATE equivalents) plus `DAYOFWEEK()`
+ *   for week truncation.
+ * - snowflake: native `DATE_TRUNC('unit', expr)`.
+ * - clickhouse: dedicated `toStartOfYear`/`toStartOfQuarter`/`toStartOfMonth`/
+ *   `toStartOfWeek`/`toStartOfDay`/`toStartOfHour`/`toStartOfMinute`/
+ *   `toStartOfSecond` functions (genuinely different function-per-unit API,
+ *   not a single parameterized function).
+ */
+export declare function dateTrunc(dialect: Dialect, unit: DateTruncUnit, expr: DateTimeArg): DateTimeExpression;
+/**
+ * Add `amount` units of time to a date/timestamp expression.
+ * See dialect notes on {@link dateTrunc} / module doc for the general
+ * per-dialect divergence rationale; per-function notes:
+ * - postgres/cockroachdb: `expr + INTERVAL 'n unit'`.
+ * - redshift: `DATEADD(unit, n, expr)` (SQL-Server-style function, NOT interval
+ *   arithmetic, despite being Postgres-derived).
+ * - mysql/mariadb: `DATE_ADD(expr, INTERVAL n UNIT)`.
+ * - mssql/snowflake: `DATEADD(unit, n, expr)`.
+ * - oracle: day-level uses plain `+`/`-` arithmetic (Oracle DATE math is in
+ *   days); month/year use `ADD_MONTHS`; hour/minute/second are expressed as
+ *   fractional-day arithmetic.
+ * - sqlite: `datetime(expr, '+n units')`.
+ * - db2: labeled-duration arithmetic, e.g. `expr + n DAYS`.
+ * - clickhouse: ANSI `expr + INTERVAL n UNIT`.
+ */
+export declare function dateAdd(dialect: Dialect, expr: DateTimeArg, amount: number, unit: DateAddUnit): DateTimeExpression;
+/**
+ * Subtract `amount` units of time from a date/timestamp expression.
+ * Equivalent to `dateAdd(dialect, expr, -amount, unit)` — see {@link dateAdd}
+ * for per-dialect SQL notes.
+ */
+export declare function dateSub(dialect: Dialect, expr: DateTimeArg, amount: number, unit: DateAddUnit): DateTimeExpression;
+/**
+ * Compute the difference between two date/timestamp expressions
+ * (`end - start`) expressed in the given unit.
+ *
+ * Dialect notes (this is the function with the widest genuine divergence):
+ * - mysql/mariadb: `TIMESTAMPDIFF(UNIT, start, end)` (native, all units).
+ * - mssql/snowflake: `DATEDIFF(unit, start, end)` (native, all units).
+ * - redshift: also has a genuine native `DATEDIFF(datepart, start, end)`
+ *   function (SQL-Server-style), unlike Postgres which has no such function.
+ * - clickhouse: native `dateDiff('unit', start, end)`.
+ * - postgres/cockroachdb: NO native DATEDIFF — day uses date subtraction
+ *   (`end::date - start::date`), sub-day units use
+ *   `EXTRACT(EPOCH FROM (end - start))` scaled, and year/month are computed
+ *   from `EXTRACT(YEAR/MONTH FROM ...)` components.
+ * - oracle: NO native DATEDIFF — DATE subtraction yields a day count
+ *   (`TRUNC(end) - TRUNC(start)` for whole days, scaled for other sub-day
+ *   units); month/year use `MONTHS_BETWEEN`.
+ * - sqlite: NO native DATEDIFF — built on `julianday()` differences (day and
+ *   sub-day units) and `strftime('%Y'/'%m', ...)` component differences
+ *   (month/year, since julianday-based month math is not calendar-exact).
+ * - db2: NO native DATEDIFF — built from `DAYS()` (whole-day difference) and
+ *   `MIDNIGHT_SECONDS()` (intra-day seconds) for day/sub-day units, and
+ *   `YEAR()`/`MONTH()` component differences for month/year.
+ */
+export declare function dateDiff(dialect: Dialect, unit: DateDiffUnit, start: DateTimeArg, end: DateTimeArg): DateTimeExpression;
+/**
+ * Current date-and-time (instant), dialect-appropriate.
+ * - mysql/mariadb: `NOW()`
+ * - postgres/cockroachdb/redshift: `NOW()`
+ * - mssql: `GETDATE()`
+ * - oracle: `SYSTIMESTAMP`
+ * - sqlite: `datetime('now')`
+ * - db2: `CURRENT TIMESTAMP` (special register, no parentheses)
+ * - snowflake: `CURRENT_TIMESTAMP()`
+ * - clickhouse: `now()`
+ */
+export declare function now(dialect: Dialect): DateTimeExpression;
+/**
+ * Current date (no time component), dialect-appropriate.
+ * - mysql/mariadb: `CURDATE()`
+ * - postgres/cockroachdb/redshift: `CURRENT_DATE`
+ * - mssql: `CAST(GETDATE() AS DATE)`
+ * - oracle: `TRUNC(SYSDATE)`
+ * - sqlite: `date('now')`
+ * - db2: `CURRENT DATE` (special register)
+ * - snowflake: `CURRENT_DATE()`
+ * - clickhouse: `today()`
+ */
+export declare function currentDate(dialect: Dialect): DateTimeExpression;
+/**
+ * Current timestamp (ANSI-standard spelling where available), dialect-appropriate.
+ * - mysql/mariadb/postgres/cockroachdb/redshift/db2: `CURRENT_TIMESTAMP`
+ * - mssql: `CURRENT_TIMESTAMP` (ANSI synonym for `GETDATE()`)
+ * - oracle: `CURRENT_TIMESTAMP` (session-timezone-aware; distinct from `SYSTIMESTAMP`)
+ * - sqlite: `CURRENT_TIMESTAMP` (SQLite keyword, UTC)
+ * - snowflake: `CURRENT_TIMESTAMP()`
+ * - clickhouse: `now()` (no distinct `CURRENT_TIMESTAMP`; `now()` is the canonical form)
+ */
+export declare function currentTimestamp(dialect: Dialect): DateTimeExpression;
+/**
+ * Format a date/timestamp expression as a string.
+ *
+ * IMPORTANT: format-token translation here is BEST-EFFORT for a common
+ * subset of tokens, NOT a full strftime-compatible formatting engine. Only
+ * the following tokens are recognized in the input `format` string (case
+ * sensitive, matched longest-first so e.g. `HH24` is not partially consumed
+ * by `HH`):
+ *   - `YYYY` - 4-digit year
+ *   - `MM`   - 2-digit month (01-12)
+ *   - `DD`   - 2-digit day of month (01-31)
+ *   - `HH24` - 2-digit hour, 24-hour clock (00-23)
+ *   - `HH`   - 2-digit hour, 12-hour clock (01-12)
+ *   - `MI`   - 2-digit minute (00-59)
+ *   - `SS`   - 2-digit second (00-59)
+ * Any other characters in `format` (literal separators like `-`, `/`, `:`,
+ * spaces, etc) are passed through unchanged, best-effort, per dialect.
+ *
+ * Dialect notes:
+ * - postgres/cockroachdb/redshift/oracle: `TO_CHAR(expr, format)` — these
+ *   tokens map onto TO_CHAR's native template natively, so the format string
+ *   passes through unchanged.
+ * - mysql/mariadb: `DATE_FORMAT(expr, format)`, tokens translated to `%Y`,
+ *   `%m`, `%d`, `%H`, `%h`, `%i`, `%s`.
+ * - mssql: `FORMAT(expr, format)`, tokens translated to .NET-style `yyyy`,
+ *   `MM`, `dd`, `HH`, `hh`, `mm`, `ss`.
+ * - sqlite: `strftime(format, expr)`, tokens translated to `%Y`, `%m`, `%d`,
+ *   `%H`, `%I`, `%M`, `%S`.
+ * - db2: `VARCHAR_FORMAT(expr, format)` (Db2's TO_CHAR-equivalent); tokens
+ *   pass through unchanged like Oracle/Postgres.
+ * - snowflake: `TO_VARCHAR(expr, format)`; tokens pass through unchanged.
+ * - clickhouse: `formatDateTime(expr, format)`, tokens translated to `%Y`,
+ *   `%m`, `%d`, `%H`, `%I`, `%i`, `%S` (ClickHouse's directives are
+ *   MySQL-`strftime`-like, notably using `%i` for minutes like MySQL).
+ */
+export declare function formatDate(dialect: Dialect, expr: DateTimeArg, format: string): DateTimeExpression;

package/dist/query-builders/functions/fulltext.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Typed, cross-dialect full-text-SEARCH-QUERY API.
+ *
+ * Several dialect drivers in this ORM already expose native FULLTEXT
+ * *index creation* helpers (grep `createFulltextIndex` in
+ * `src/dialects/*​/index.ts`: mysql, mariadb, postgres, cockroachdb, mssql,
+ * oracle, sqlite, clickhouse all have one; db2/redshift throw a documented
+ * "not supported" error; snowflake is a documented no-op). What has been
+ * missing is a typed helper for the *query* side — the actual
+ * `MATCH() AGAINST()` / `@@ plainto_tsquery()` / `CONTAINS()` / `MATCH`
+ * predicate that goes in a `WHERE` (or `ORDER BY`, for relevance ranking).
+ * This module fills that gap.
+ *
+ * This module is intentionally self-contained: it does not add any new
+ * dispatch branches to `src/operators.ts`, `src/query-builders/sql-compiler.ts`,
+ * or any `src/dialects/**` file. Every function resolves directly to a final,
+ * dialect-correct SQL fragment string, which is then wrapped with the
+ * existing `literal()` helper from `src/operators.ts` (returns `{ $literal: sql }`,
+ * the same shape produced by `Op.literal(...)` and consumed throughout the
+ * where-builder/sql-compiler for raw-SQL escape hatches).
+ *
+ * IMPORTANT — verified limitation of the current WHERE-clause builder
+ * ---------------------------------------------------------------------
+ * `literal()`/`{ $literal }` is fully supported (and the recommended,
+ * documented way to inject raw SQL) when it is used as the *value* of a
+ * field/operator, e.g.:
+ *   `where: { createdAt: { [Op.lt]: literal('NOW()') } }`
+ * However, at the time this module was written, `WhereBuilder`
+ * (`src/query-builders/where-builder.ts`) and the per-dialect
+ * `buildWhereClause()` implementations only support `{ $literal }` as an
+ * *operator value*; they do not currently accept a bare `{ $literal }` (or a
+ * plain raw-SQL string) as an entire standalone condition — whether at the
+ * top level of `where`, or nested inside `$and`/`Op.and`/`$or`/`Op.or`
+ * arrays. This was verified empirically: such conditions are silently
+ * dropped rather than raising an error (a pre-existing gap in the shared
+ * where-builder, not something this module can fix without editing that
+ * file, which is out of scope here).
+ *
+ * Because of that, the SQL fragments produced by `fullTextMatch()` /
+ * `fullTextRank()` are safe and correct to use:
+ *   - directly in hand-built / raw SQL (`prorm.query(...)`), by reading
+ *     `.$literal` off the returned value,
+ *   - in `attributes: [...]` (SELECT) and `order: [...]` (ORDER BY) arrays,
+ *     both of which DO correctly render raw literal SQL fragments today
+ *     (verified against `sql-compiler.ts`'s `processAttributeValue()` and
+ *     `order-limit-builder.ts`'s `buildOrderItem()`, which passes through
+ *     plain strings/literal SQL unchanged).
+ * They are returned in the canonical `{ $literal: sql }` shape (rather than
+ * a bare string) so that call sites which build `where` conditions through
+ * `Op`-based helpers remain forward-compatible: if/when the WHERE-clause gap
+ * above is fixed, code using this module keeps working with no changes.
+ *
+ * @example
+ * ```typescript
+ * import { fullTextMatch, fullTextRank } from './query-builders/functions/fulltext';
+ *
+ * const match = fullTextMatch('mysql', ['title', 'body'], 'red widgets');
+ * // match.$literal === "MATCH(`title`, `body`) AGAINST('red widgets' IN NATURAL LANGUAGE MODE)"
+ *
+ * // Use for scoring/ordering (works today via ORDER BY / attributes):
+ * const rank = fullTextRank('postgres', 'body', 'red widgets');
+ * Article.findAll({
+ *   attributes: ['id', 'title', [rank, 'relevance']],
+ *   order: [[rank.$literal, 'DESC']],
+ * });
+ *
+ * // Use directly in a raw query for WHERE (recommended today):
+ * await prorm.query(
+ *   `SELECT * FROM articles WHERE ${match.$literal}`
+ * );
+ * ```
+ */
+import { type LiteralValue } from '../../operators';
+import type { Dialect } from '../../types/index';
+/**
+ * Search mode for `fullTextMatch()`.
+ *   - 'natural' (default): natural-language / "find documents about this text" search.
+ *   - 'boolean': operator-aware search (dialect-specific boolean/text-search
+ *     operator syntax, e.g. MySQL boolean-mode `+word -word "phrase"`, MSSQL
+ *     `CONTAINS`, Oracle Text `CONTAINS` operators).
+ *   - 'phrase': exact-phrase search where the dialect has a distinct,
+ *     better-suited construct for it (e.g. Postgres `websearch_to_tsquery`,
+ *     MySQL boolean-mode quoted phrase, MSSQL/SQLite quoted phrase).
+ */
+export type FullTextMatchMode = 'natural' | 'boolean' | 'phrase';
+/**
+ * Companion enum for `FullTextMatchMode`. Provided for callers who prefer a
+ * typed enum over hand-written string literals (e.g. `FullTextSearchMode.Boolean`
+ * instead of `'boolean'`). The two are interchangeable: `FullTextSearchMode`'s
+ * members are assignable to `FullTextMatchMode` (and vice versa, since the
+ * enum is string-valued), and `FullTextMatchOptions.mode` accepts either.
+ * This is purely additive — no existing string-literal call sites need to
+ * change.
+ */
+export declare enum FullTextSearchMode {
+    Natural = "natural",
+    Boolean = "boolean",
+    Phrase = "phrase"
+}
+export interface FullTextMatchOptions {
+    /** Search mode. Defaults to 'natural'. Accepts either the string-literal
+     * union (`'natural' | 'boolean' | 'phrase'`) or the companion
+     * `FullTextSearchMode` enum. */
+    mode?: FullTextMatchMode | FullTextSearchMode;
+    /**
+     * Text search configuration/language for dialects that use one
+     * (currently Postgres/CockroachDB `to_tsvector`/`plainto_tsquery`/
+     * `websearch_to_tsquery`). Defaults to `'english'`.
+     */
+    config?: string;
+}
+/**
+ * Columns argument accepted by every function in this module: a single
+ * column name, or an array of column names. Dotted `table.column` names are
+ * passed through as-is (quoted as a whole), matching the convention used by
+ * `col()` in `src/operators.ts`.
+ */
+export type FullTextColumns = string | string[];
+/**
+ * Build a dialect-correct full-text-search WHERE-predicate SQL fragment.
+ *
+ * Returns `{ $literal: sql }` (see module header for the supported/verified
+ * usage patterns for this shape).
+ *
+ * Per-dialect behavior:
+ *   - mysql/mariadb: `MATCH(col1, col2) AGAINST('term' IN NATURAL LANGUAGE MODE | IN BOOLEAN MODE)`.
+ *     `mode: 'phrase'` uses boolean mode with the term wrapped in `"..."` for
+ *     an exact-phrase match (MySQL boolean-mode phrase syntax).
+ *     NOTE: requires a `FULLTEXT` index on the given column(s) — see
+ *     `createFulltextIndex()` in `src/dialects/mysql/index.ts` / `mariadb/index.ts`.
+ *   - postgres/cockroachdb: `to_tsvector('english', col1 || ' ' || col2) @@ plainto_tsquery('english', 'term')`.
+ *     `mode: 'phrase'` uses `websearch_to_tsquery` instead of `plainto_tsquery`
+ *     for more natural, phrase-aware parsing (supports quoted phrases, `-`,
+ *     `OR`). NOTE: works on any text column; a GIN index
+ *     (`createFulltextIndex()`) is only needed for performance, not correctness.
+ *   - mssql: `mode: 'natural'` (default) uses `FREETEXT(col, 'term')`;
+ *     `mode: 'boolean'` / `mode: 'phrase'` uses `CONTAINS(col, 'term')`
+ *     (phrase mode wraps the term in `"..."`, which is exact-phrase syntax
+ *     for `CONTAINS`). NOTE: requires a full-text index/catalog — see
+ *     `createFulltextIndex()` in `src/dialects/mssql/index.ts`.
+ *   - oracle: `CONTAINS(col, 'term', 1) > 0` (Oracle Text). Multiple columns
+ *     are OR-ed together, since Oracle Text indexes and scores one column at
+ *     a time. NOTE: requires an Oracle Text index — see `createFulltextIndex()`
+ *     in `src/dialects/oracle/index.ts`.
+ *   - sqlite: `col MATCH 'term'`. STRUCTURAL REQUIREMENT (unlike every other
+ *     dialect above): this only works against an FTS5 virtual table/column
+ *     (see `createFulltextIndex()` / `createFTS5Table()` in
+ *     `src/dialects/sqlite/index.ts`) — SQLite has no secondary full-text
+ *     index you can bolt onto an ordinary table the way MySQL/Postgres/MSSQL
+ *     do; the table itself must be an `fts5` virtual table.
+ *   - clickhouse: uses `hasToken(col, 'term')` for a single-token exact
+ *     match, or `multiSearchAny(col, ['term1', 'term2', ...])` when
+ *     `searchTerm` contains multiple whitespace-separated words. Multiple
+ *     columns are OR-ed together. See `createFulltextIndex()` (ClickHouse
+ *     `ngrambf_v1`/`tokenbf_v1` index) in `src/dialects/clickhouse/index.ts`.
+ *   - db2: THROWS. Db2's optional Text Search feature (Net Search Extender)
+ *     has its own `CONTAINS`-like predicate syntax, but it could not be
+ *     verified with confidence here, and `createFulltextIndex()` in
+ *     `src/dialects/db2/index.ts` itself throws
+ *     "Fulltext indexes are not supported in Db2 LUW (requires Net Search
+ *     Extender)" — so there is no verified index-creation path to pair a
+ *     query against either. Throwing here rather than guessing avoids
+ *     shipping silently-wrong SQL.
+ *   - snowflake: FALLBACK, not true full-text search. Snowflake has no
+ *     Postgres-style `tsvector`/`tsquery` full-text search primitive (its
+ *     closest offerings are Cortex Search / Search Optimization Service,
+ *     which are not plain-SQL predicates); `createFulltextIndex()` in
+ *     `src/dialects/snowflake/index.ts` is a documented no-op for the same
+ *     reason. Falls back to `ILIKE '%term%'` (case-insensitive substring
+ *     match — no tokenization, stemming, or relevance ranking).
+ *   - redshift: FALLBACK, not true full-text search. Redshift (unlike
+ *     Postgres, which it forked from) does not implement `tsvector`/`tsquery`;
+ *     `createFulltextIndex()` in `src/dialects/redshift/index.ts` throws
+ *     accordingly. Falls back to `ILIKE '%term%'`, same caveat as Snowflake.
+ *
+ * @param dialect - Target SQL dialect.
+ * @param columns - Column name, or array of column names, to search.
+ * @param searchTerm - The user's search text.
+ * @param options - `{ mode, config }`, see `FullTextMatchOptions`.
+ */
+export declare function fullTextMatch(dialect: Dialect, columns: FullTextColumns, searchTerm: string, options?: FullTextMatchOptions): LiteralValue;
+/**
+ * Build a dialect-correct full-text relevance-SCORE SQL expression, for use
+ * in `SELECT`/`attributes` or `ORDER BY`/`order` — NOT a boolean WHERE
+ * predicate (use `fullTextMatch()` for that).
+ *
+ * Returns `{ $literal: sql }`. This shape is safe to use directly in
+ * `attributes: [...]` and `order: [...]` today (see module header) —
+ * both channels render raw literal SQL fragments correctly, unlike
+ * the WHERE-clause builder.
+ *
+ * Support by dialect:
+ *   - postgres/cockroachdb: `ts_rank(to_tsvector('english', col), plainto_tsquery('english', 'term'))`.
+ *   - mysql/mariadb: `MATCH(col1, col2) AGAINST('term')` — in MySQL/MariaDB,
+ *     using `MATCH() AGAINST()` outside of a boolean context (e.g. in
+ *     `SELECT`/`ORDER BY`) naturally evaluates to the relevance score
+ *     (a floating point number), so the same construct doubles as both a
+ *     predicate (via `fullTextMatch`) and a score.
+ *   - oracle: `SCORE(1)` (Oracle Text). REQUIRES a `CONTAINS(col, 'term', 1) > 0`
+ *     predicate using the *same* label (`1`) to appear in the query's WHERE
+ *     clause (e.g. from `fullTextMatch(dialect, col, term)`), per Oracle Text
+ *     rules — `SCORE(n)` reads the score computed by the `CONTAINS` call
+ *     labeled `n` elsewhere in the same query.
+ *   - mssql, sqlite, clickhouse, db2, redshift, snowflake: THROWS. None of
+ *     these has a genuine, verifiable relevance-scoring mechanism usable as
+ *     a plain SQL expression:
+ *       - mssql: `CONTAINS`/`FREETEXT` are boolean predicates only; ranked
+ *         results require `CONTAINSTABLE`/`FREETEXTTABLE` (table-valued
+ *         functions joined in, not an expression usable inline).
+ *       - sqlite FTS5: ranking requires the `bm25()` auxiliary function,
+ *         which (like MSSQL's *TABLE functions) can only be selected from
+ *         the FTS5 virtual table itself, not expressed against an arbitrary
+ *         base-table column the way `fullTextMatch()`'s column argument
+ *         implies — so it does not fit this API's per-column shape.
+ *       - clickhouse: `hasToken`/`multiSearchAny` return booleans; there is
+ *         no built-in relevance score function.
+ *       - db2/redshift/snowflake: no native full-text search at all (see
+ *         `fullTextMatch()` docs above), so there is nothing to rank.
+ */
+export declare function fullTextRank(dialect: Dialect, columns: FullTextColumns, searchTerm: string, options?: Pick<FullTextMatchOptions, 'config'>): LiteralValue;

package/dist/query-builders/functions/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Barrel export for the typed SQL function-builder library.
+ * Lets callers do `import { rowNumber, jsonExtract, fullTextMatch } from 'prorm'`
+ * instead of hand-writing raw SQL fragments.
+ *
+ * Explicit (not `export *`) because several of these modules independently
+ * declare their own local `SqlExpr` type alias (same shape, different
+ * files) - re-exporting all three under one name is ambiguous.
+ */
+export { count, countDistinct, sum, avg, min, max, stringAgg, arrayAgg, type SqlExpr, type AggOrderBy, type StringAggOptions, type ArrayAggOptions, } from './aggregate';
+export { CaseBuilder, SimpleCaseBuilder, caseWhen, caseOf, type CaseValue, type CaseCondition, } from './conditional';
+export { dateTrunc, dateAdd, dateSub, dateDiff, now, currentDate, currentTimestamp, formatDate, type DateTimeArg, type DateTimeExpression, type DateTruncUnit, type DateAddUnit, type DateDiffUnit, } from './datetime';
+export { fullTextMatch, fullTextRank, type FullTextMatchMode, type FullTextMatchOptions, type FullTextColumns, } from './fulltext';
+export { jsonExtract, jsonContains, jsonHasKey, jsonKeys, jsonTypeOf, type JsonExprArg, type JsonExtractOptions, } from './json';
+export { round, ceil, floor, power, sqrt, abs, sign, mod, random, greatest, least, truncate, type SqlExpr as MathSqlExpr, } from './math';
+export { concat, substring, trim, ltrim, rtrim, upper, lower, length, replace, lpad, rpad, split, repeat, reverse, type TrimOptions, type SqlExpr as StringSqlExpr, } from './string';
+export { WindowFunctionBuilder, rowNumber, rank, denseRank, percentRank, cumeDist, ntile, lag, lead, firstValue, lastValue, nthValue, sumOver, avgOver, countOver, minOver, maxOver, windowFn, NullsOrder, type WindowDialect, type WindowOrderDirection, type WindowNulls, type WindowFrameBoundary, type WindowFrame, type WindowArg, } from './window';

package/dist/query-builders/functions/json.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Cross-dialect, typed JSON-path function API.
+ *
+ * This module lets callers pull a JSON field/path out of a JSON/JSONB column
+ * (or any expression producing one) as a first-class, typed SQL expression
+ * usable in `attributes` / `SELECT`, without ever having to hand-write raw
+ * SQL strings for it.
+ *
+ * It is intentionally self-contained: it does not rely on (or modify) the
+ * dialect classes in `src/dialects/**` or the compiler in
+ * `src/query-builders/sql-compiler.ts`. Instead it re-derives, per dialect,
+ * the exact SQL fragments that this codebase's own dialect-internal
+ * WHERE-clause JSON helpers already produce (see the JSDoc on each function
+ * below for the specific dialect file/method that was used as the source of
+ * truth), so behavior stays consistent with the rest of the ORM.
+ *
+ * All functions return a `{ $literal: string }` value (the same shape
+ * produced by `literal()` in `src/operators.ts`), so the result can be
+ * dropped directly into `attributes`, e.g.:
+ *
+ * ```ts
+ * User.findAll({
+ *   attributes: ['id', [jsonExtract('postgres', 'data', 'address.city'), 'city']],
+ * });
+ * ```
+ */
+import type { Dialect } from '../../types/index';
+/** Anything that can be used as the "expression" argument to a json function. */
+export type JsonExprArg = string | {
+    __type: 'col';
+    col: string;
+} | {
+    __type: 'fn';
+    fn: string;
+    args: any[];
+} | {
+    __type: 'literal';
+    sql: string;
+} | {
+    $literal: string;
+};
+export interface JsonExtractOptions {
+    /**
+     * When true (the default), extract the value as text/scalar (the
+     * `->>`-equivalent). When false, extract as a JSON-typed sub-value (the
+     * `->`-equivalent), where the dialect distinguishes the two.
+     */
+    asText?: boolean;
+}
+/**
+ * Extract a value at a JSON path from `expr` as a typed, cross-dialect SQL
+ * expression usable in `attributes` / `SELECT`.
+ *
+ * Dialect syntax sources (matched against this codebase's existing internal
+ * dialect helpers where they exist):
+ * - mysql/mariadb: `src/dialects/{mysql,mariadb}/index.ts` `buildJsonExtract` ->
+ *   `JSON_UNQUOTE(JSON_EXTRACT(col, '$.path'))` (asText) / `JSON_EXTRACT(col, '$.path')`.
+ * - mssql: `src/dialects/mssql/index.ts` `buildJsonExtract` ->
+ *   `JSON_VALUE(col, '$.path')` (asText) / `JSON_QUERY(col, '$.path')`.
+ * - sqlite: `src/dialects/sqlite/index.ts` `buildJsonExtract` ->
+ *   `CAST(json_extract(col, '$.path') AS TEXT)` (asText) / `json_extract(col, '$.path')`.
+ * - postgres/cockroachdb: `src/query-builders/where-builder.ts` `#>>`/`#>` handling ->
+ *   `col #>> '{a,b}'` (asText) / `col #> '{a,b}'`.
+ * - oracle: Oracle SQL/JSON functions -> `JSON_VALUE(col, '$.path')` (asText) /
+ *   `JSON_QUERY(col, '$.path')`.
+ * - snowflake: `src/dialects/snowflake/index.ts` `buildJsonQuery` -> `col:a.b::STRING`
+ *   (asText) / `col:a.b` (VARIANT, non-text).
+ * - redshift: SUPER-type dot navigation (see `getDataTypeSql` mapping JSON/JSONB -> SUPER
+ *   in `src/dialects/redshift/index.ts`) -> `CAST(col.a.b AS VARCHAR)` (asText) / `col.a.b`.
+ * - db2: Db2 JSON_VAL/JSON_QUERY path functions -> `JSON_VAL(col, 'a.b')` (asText) /
+ *   `JSON_QUERY(col, '$.a.b')`.
+ * - clickhouse: `JSONExtractString(col, 'a', 'b')` (asText) / `JSONExtractRaw(col, 'a', 'b')`.
+ */
+export declare function jsonExtract(dialect: Dialect, expr: JsonExprArg, path: string | string[], options?: JsonExtractOptions): {
+    $literal: string;
+};
+/**
+ * Does the JSON value in `expr` contain `value` (as a fragment/sub-document,
+ * or, where the dialect has no native containment predicate, as an exact
+ * equality check)?
+ *
+ * - mysql/mariadb: `JSON_CONTAINS(col, '<value-json>')` (matches
+ *   `buildJsonContains` in `src/dialects/{mysql,mariadb}/index.ts`).
+ * - postgres/cockroachdb: native jsonb containment operator -> `col @> '<value-json>'::jsonb`.
+ * - sqlite: SQLite has no containment operator; mirrors the whole-document
+ *   equality fallback used by `buildJsonContains` in
+ *   `src/dialects/sqlite/index.ts` -> `col = '<value-json>'`.
+ * - mssql, oracle, snowflake, redshift, db2, clickhouse: none of these expose
+ *   a native "does this JSON document contain this sub-fragment" predicate
+ *   (as opposed to key existence or exact-path equality), so this throws a
+ *   clear "not supported" error rather than emitting a plausible-looking but
+ *   semantically wrong query.
+ */
+export declare function jsonContains(dialect: Dialect, expr: JsonExprArg, value: unknown): {
+    $literal: string;
+};
+/**
+ * Does the JSON object in `expr` have the given top-level (or path-qualified,
+ * dotted) key?
+ *
+ * - mysql/mariadb: `JSON_CONTAINS_PATH(col, 'one', '$.key')` (matches
+ *   `buildJsonHasKey` in `src/dialects/{mysql,mariadb}/index.ts`).
+ * - postgres/cockroachdb: native `?` key-existence operator -> `col ? 'key'`
+ *   (top-level keys only, matching jsonb semantics).
+ * - sqlite: `json_extract(col, '$.key') IS NOT NULL` (matches
+ *   `buildJsonHasKey` in `src/dialects/sqlite/index.ts`).
+ * - mssql: `JSON_VALUE(col, '$.key') IS NOT NULL` (standard SQL Server
+ *   workaround pattern; note this cannot distinguish "key present with a
+ *   JSON null value" from "key absent").
+ * - oracle: `JSON_EXISTS(col, '$.key')`.
+ * - snowflake: `ARRAY_CONTAINS('key'::VARIANT, OBJECT_KEYS(col))`.
+ * - redshift: SUPER dot-navigation returns SQL NULL for missing attributes,
+ *   so `col.key IS NOT NULL` reliably detects key presence.
+ * - db2: `JSON_EXISTS(col, '$.key')` (Db2 11.5+ JSON path predicates).
+ * - clickhouse: `JSONHas(col, 'key')`.
+ */
+export declare function jsonHasKey(dialect: Dialect, expr: JsonExprArg, key: string): {
+    $literal: string;
+};
+/**
+ * Get the list of top-level keys of a JSON object.
+ *
+ * - mysql/mariadb: `JSON_KEYS(col)` -> native, returns a JSON array of keys.
+ * - postgres/cockroachdb: `ARRAY(SELECT jsonb_object_keys(col))` -> a SQL
+ *   text array of keys.
+ * - sqlite: `(SELECT json_group_array(key) FROM json_each(col))` -> a JSON
+ *   array of keys, built from SQLite's own `json_each` table-valued function.
+ * - snowflake: `OBJECT_KEYS(col)` -> native, returns an ARRAY of keys.
+ * - clickhouse: `JSONExtractKeys(col)` -> native, returns an Array(String).
+ * - mssql: no native function returns a JSON/array value of keys inline;
+ *   `OPENJSON` requires a derived table, so the closest inline expression is
+ *   a scalar subquery producing a comma-separated string (NOT a JSON array):
+ *   `(SELECT STRING_AGG([key], ',') FROM OPENJSON(col))`.
+ * - oracle, redshift, db2: throw "not supported" - none of these dialects
+ *   expose a documented function/operator that enumerates JSON object keys
+ *   as a value usable inline in a SELECT list, so faking one with a fragile
+ *   workaround would be worse than a clear error.
+ */
+export declare function jsonKeys(dialect: Dialect, expr: JsonExprArg): {
+    $literal: string;
+};
+/**
+ * Get the JSON value's type (object/array/string/number/boolean/null/...).
+ *
+ * - mysql/mariadb: `JSON_TYPE(col)` -> native.
+ * - postgres/cockroachdb: `jsonb_typeof(col)` -> native.
+ * - sqlite: `json_type(col)` -> native.
+ * - snowflake: `TYPEOF(col)` -> native (works on VARIANT).
+ * - clickhouse: `JSONType(col)` -> native.
+ * - mssql, oracle, redshift, db2: throw "not supported" - none of these
+ *   expose a documented function that returns the JSON value's type as a
+ *   string (SQL Server's `ISJSON(col, 'object'|'array')` only returns a
+ *   boolean for two of the possible types, not a general type name).
+ */
+export declare function jsonTypeOf(dialect: Dialect, expr: JsonExprArg): {
+    $literal: string;
+};