ts-prorm-orm 1.1.0

package/dist/query-builders/functions/json.js

@@ -0,0 +1,427 @@
+"use strict";
+/**
+ * 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']],
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonExtract = jsonExtract;
+exports.jsonContains = jsonContains;
+exports.jsonHasKey = jsonHasKey;
+exports.jsonKeys = jsonKeys;
+exports.jsonTypeOf = jsonTypeOf;
+const operators_1 = require("../../operators");
+// ---------------------------------------------------------------------------
+// Local, self-contained SQL-fragment rendering helpers
+// (deliberately not imported from sql-compiler.ts, per architecture constraints)
+// ---------------------------------------------------------------------------
+function quoteChars(dialect) {
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb':
+        case 'clickhouse':
+            return { open: '`', close: '`', escape: (s) => s.replace(/`/g, '``') };
+        case 'mssql':
+            return { open: '[', close: ']', escape: (s) => s.replace(/\]/g, ']]') };
+        default:
+            // postgres, sqlite, cockroachdb, redshift, db2, snowflake, oracle
+            return { open: '"', close: '"', escape: (s) => s.replace(/"/g, '""') };
+    }
+}
+/** Escape/quote a single identifier segment (no dot-splitting). */
+function quoteIdentifierPart(dialect, part) {
+    const { open, close, escape } = quoteChars(dialect);
+    return `${open}${escape(part)}${close}`;
+}
+/** Escape/quote a possibly dotted identifier path (e.g. `table.column`). */
+function quoteIdentifierPath(dialect, name) {
+    return name
+        .split('.')
+        .map((part) => quoteIdentifierPart(dialect, part))
+        .join('.');
+}
+/**
+ * Escape a string literal for embedding directly into generated SQL text.
+ * MySQL/MariaDB also need backslash escaping (in addition to quote doubling);
+ * every other supported dialect here only needs `'` doubled.
+ */
+function escapeStringLiteral(dialect, value) {
+    if (dialect === 'mysql' || dialect === 'mariadb') {
+        return value.replace(/\\/g, '\\\\').replace(/'/g, "''");
+    }
+    return value.replace(/'/g, "''");
+}
+/**
+ * Render any supported expression argument (plain column name string,
+ * `col()`, `fn()`, or `literal()`/`{ $literal }`) down to a raw SQL fragment
+ * string, using this module's own dialect-aware identifier quoting.
+ */
+function toSqlFragment(dialect, arg) {
+    if (arg !== null && typeof arg === 'object') {
+        if ('$literal' in arg) {
+            return arg.$literal;
+        }
+        const typed = arg;
+        if (typed.__type === 'literal') {
+            return arg.sql;
+        }
+        if (typed.__type === 'col') {
+            return quoteIdentifierPath(dialect, arg.col);
+        }
+        if (typed.__type === 'fn') {
+            const fnExpr = arg;
+            const renderedArgs = fnExpr.args.map((a) => toSqlFragment(dialect, a)).join(', ');
+            return `${fnExpr.fn}(${renderedArgs})`;
+        }
+        throw new Error(`jsonExtract/jsonContains/jsonHasKey/jsonKeys/jsonTypeOf: unsupported expression argument: ${JSON.stringify(arg)}`);
+    }
+    if (typeof arg === 'string') {
+        // Plain strings are treated as column names (consistent with col()).
+        return quoteIdentifierPath(dialect, arg);
+    }
+    throw new Error(`jsonExtract: unsupported expression argument: ${String(arg)}`);
+}
+// ---------------------------------------------------------------------------
+// Path normalization
+// ---------------------------------------------------------------------------
+/** Normalize `path` (dotted string or array of keys/indices) to plain string segments. */
+function normalizePathSegments(path) {
+    if (Array.isArray(path)) {
+        return path.map((p) => String(p));
+    }
+    // Strip a leading '$.' / '$' so callers can pass either 'a.b' or '$.a.b'.
+    const stripped = path.startsWith('$.') ? path.slice(2) : path.startsWith('$') ? path.slice(1) : path;
+    return stripped.split('.').filter((s) => s.length > 0);
+}
+const isArrayIndexSegment = (seg) => /^\d+$/.test(seg);
+/** Build a MySQL/MariaDB/MSSQL/SQLite/Oracle/Db2-style `$.a.b[0]` JSON path string. */
+function buildDollarPath(segments) {
+    let out = '$';
+    for (const seg of segments) {
+        out += isArrayIndexSegment(seg) ? `[${seg}]` : `.${seg}`;
+    }
+    return out;
+}
+/** Build a Postgres/CockroachDB `#>`/`#>>` style `'{a,b}'` path-array literal body. */
+function buildPgPathArray(segments) {
+    return segments.join(',');
+}
+/** Build a Redshift SUPER-navigation dot path: `a.b` or `a[0].b`. */
+function buildDotPath(segments) {
+    return segments
+        .map((seg, i) => (isArrayIndexSegment(seg) ? `[${seg}]` : i === 0 ? seg : `.${seg}`))
+        .join('');
+}
+/** Build a Snowflake VARIANT `:`-path: `:a.b` or `:a[0].b`. */
+function buildSnowflakePath(segments) {
+    return segments
+        .map((seg, i) => (isArrayIndexSegment(seg) ? `[${seg}]` : i === 0 ? `:${seg}` : `.${seg}`))
+        .join('');
+}
+// ---------------------------------------------------------------------------
+// jsonExtract
+// ---------------------------------------------------------------------------
+/**
+ * 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')`.
+ */
+function jsonExtract(dialect, expr, path, options = {}) {
+    const asText = options.asText !== false;
+    const columnRef = toSqlFragment(dialect, expr);
+    const segments = normalizePathSegments(path);
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb': {
+            const dollarPath = escapeStringLiteral(dialect, buildDollarPath(segments));
+            const extracted = `JSON_EXTRACT(${columnRef}, '${dollarPath}')`;
+            return (0, operators_1.literal)(asText ? `JSON_UNQUOTE(${extracted})` : extracted);
+        }
+        case 'mssql': {
+            const dollarPath = escapeStringLiteral(dialect, buildDollarPath(segments));
+            return (0, operators_1.literal)(asText ? `JSON_VALUE(${columnRef}, '${dollarPath}')` : `JSON_QUERY(${columnRef}, '${dollarPath}')`);
+        }
+        case 'sqlite': {
+            const dollarPath = escapeStringLiteral(dialect, buildDollarPath(segments));
+            const extracted = `json_extract(${columnRef}, '${dollarPath}')`;
+            return (0, operators_1.literal)(asText ? `CAST(${extracted} AS TEXT)` : extracted);
+        }
+        case 'postgres':
+        case 'cockroachdb': {
+            const pgPath = escapeStringLiteral(dialect, buildPgPathArray(segments));
+            return (0, operators_1.literal)(asText ? `${columnRef} #>> '{${pgPath}}'` : `${columnRef} #> '{${pgPath}}'`);
+        }
+        case 'oracle': {
+            const dollarPath = escapeStringLiteral(dialect, buildDollarPath(segments));
+            return (0, operators_1.literal)(asText ? `JSON_VALUE(${columnRef}, '${dollarPath}')` : `JSON_QUERY(${columnRef}, '${dollarPath}')`);
+        }
+        case 'snowflake': {
+            const snowPath = buildSnowflakePath(segments);
+            const extracted = `${columnRef}${snowPath}`;
+            return (0, operators_1.literal)(asText ? `${extracted}::STRING` : extracted);
+        }
+        case 'redshift': {
+            const dotPath = buildDotPath(segments);
+            const extracted = `${columnRef}.${dotPath}`;
+            return (0, operators_1.literal)(asText ? `CAST(${extracted} AS VARCHAR)` : extracted);
+        }
+        case 'db2': {
+            // Db2 stores JSON as text (JSON DataType maps to CLOB, see
+            // src/dialects/db2/index.ts getDataTypeSql), so JSON_VAL/JSON_QUERY
+            // operate over the CLOB/VARCHAR content.
+            const dotPath = escapeStringLiteral(dialect, segments.join('.'));
+            const dollarPath = escapeStringLiteral(dialect, buildDollarPath(segments));
+            return (0, operators_1.literal)(asText ? `JSON_VAL(${columnRef}, '${dotPath}')` : `JSON_QUERY(${columnRef}, '${dollarPath}')`);
+        }
+        case 'clickhouse': {
+            const args = [columnRef, ...segments.map((seg) => (isArrayIndexSegment(seg) ? seg : `'${escapeStringLiteral(dialect, seg)}'`))].join(', ');
+            return (0, operators_1.literal)(asText ? `JSONExtractString(${args})` : `JSONExtractRaw(${args})`);
+        }
+        default:
+            throw new Error(`jsonExtract: unsupported dialect '${dialect}'`);
+    }
+}
+// ---------------------------------------------------------------------------
+// jsonContains
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+function jsonContains(dialect, expr, value) {
+    const columnRef = toSqlFragment(dialect, expr);
+    const jsonText = escapeStringLiteral(dialect, JSON.stringify(value));
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb':
+            return (0, operators_1.literal)(`JSON_CONTAINS(${columnRef}, '${jsonText}')`);
+        case 'postgres':
+        case 'cockroachdb':
+            return (0, operators_1.literal)(`${columnRef} @> '${jsonText}'::jsonb`);
+        case 'sqlite':
+            // SQLite has no jsonb-style containment operator; the dialect's own
+            // buildJsonContains() falls back to whole-document equality.
+            return (0, operators_1.literal)(`${columnRef} = '${jsonText}'`);
+        case 'mssql':
+        case 'oracle':
+        case 'snowflake':
+        case 'redshift':
+        case 'db2':
+        case 'clickhouse':
+            throw new Error(`jsonContains: not supported for dialect '${dialect}' - this dialect has no native JSON containment predicate (only key existence / exact path equality), so a correct containment query cannot be generated here.`);
+        default:
+            throw new Error(`jsonContains: unsupported dialect '${dialect}'`);
+    }
+}
+// ---------------------------------------------------------------------------
+// jsonHasKey
+// ---------------------------------------------------------------------------
+/**
+ * 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')`.
+ */
+function jsonHasKey(dialect, expr, key) {
+    const columnRef = toSqlFragment(dialect, expr);
+    const segments = normalizePathSegments(key);
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb': {
+            const dollarPath = escapeStringLiteral(dialect, buildDollarPath(segments));
+            return (0, operators_1.literal)(`JSON_CONTAINS_PATH(${columnRef}, 'one', '${dollarPath}')`);
+        }
+        case 'postgres':
+        case 'cockroachdb': {
+            if (segments.length !== 1) {
+                throw new Error(`jsonHasKey: not supported for dialect '${dialect}' with a nested/dotted key ('${key}') - the '?' key-existence operator only tests top-level keys.`);
+            }
+            return (0, operators_1.literal)(`${columnRef} ? '${escapeStringLiteral(dialect, segments[0])}'`);
+        }
+        case 'sqlite': {
+            const dollarPath = escapeStringLiteral(dialect, buildDollarPath(segments));
+            return (0, operators_1.literal)(`json_extract(${columnRef}, '${dollarPath}') IS NOT NULL`);
+        }
+        case 'mssql': {
+            const dollarPath = escapeStringLiteral(dialect, buildDollarPath(segments));
+            return (0, operators_1.literal)(`JSON_VALUE(${columnRef}, '${dollarPath}') IS NOT NULL`);
+        }
+        case 'oracle':
+        case 'db2': {
+            const dollarPath = escapeStringLiteral(dialect, buildDollarPath(segments));
+            return (0, operators_1.literal)(`JSON_EXISTS(${columnRef}, '${dollarPath}')`);
+        }
+        case 'snowflake': {
+            if (segments.length !== 1) {
+                throw new Error(`jsonHasKey: not supported for dialect '${dialect}' with a nested/dotted key ('${key}') - OBJECT_KEYS() only enumerates the top-level keys of a VARIANT/OBJECT.`);
+            }
+            return (0, operators_1.literal)(`ARRAY_CONTAINS('${escapeStringLiteral(dialect, segments[0])}'::VARIANT, OBJECT_KEYS(${columnRef}))`);
+        }
+        case 'redshift': {
+            const dotPath = buildDotPath(segments);
+            return (0, operators_1.literal)(`${columnRef}.${dotPath} IS NOT NULL`);
+        }
+        case 'clickhouse': {
+            const args = [columnRef, ...segments.map((seg) => (isArrayIndexSegment(seg) ? seg : `'${escapeStringLiteral(dialect, seg)}'`))].join(', ');
+            return (0, operators_1.literal)(`JSONHas(${args})`);
+        }
+        default:
+            throw new Error(`jsonHasKey: unsupported dialect '${dialect}'`);
+    }
+}
+// ---------------------------------------------------------------------------
+// jsonKeys
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+function jsonKeys(dialect, expr) {
+    const columnRef = toSqlFragment(dialect, expr);
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb':
+            return (0, operators_1.literal)(`JSON_KEYS(${columnRef})`);
+        case 'postgres':
+        case 'cockroachdb':
+            return (0, operators_1.literal)(`ARRAY(SELECT jsonb_object_keys(${columnRef}))`);
+        case 'sqlite':
+            return (0, operators_1.literal)(`(SELECT json_group_array(key) FROM json_each(${columnRef}))`);
+        case 'snowflake':
+            return (0, operators_1.literal)(`OBJECT_KEYS(${columnRef})`);
+        case 'clickhouse':
+            return (0, operators_1.literal)(`JSONExtractKeys(${columnRef})`);
+        case 'mssql':
+            // Note: returns a comma-separated string of keys, not a JSON array,
+            // since T-SQL has no scalar function that produces one directly.
+            return (0, operators_1.literal)(`(SELECT STRING_AGG(CAST([key] AS NVARCHAR(MAX)), ',') FROM OPENJSON(${columnRef}))`);
+        case 'oracle':
+        case 'redshift':
+        case 'db2':
+            throw new Error(`jsonKeys: not supported for dialect '${dialect}' - no documented function/operator enumerates JSON object keys as an inline SELECT-list expression for this dialect.`);
+        default:
+            throw new Error(`jsonKeys: unsupported dialect '${dialect}'`);
+    }
+}
+// ---------------------------------------------------------------------------
+// jsonTypeOf
+// ---------------------------------------------------------------------------
+/**
+ * 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).
+ */
+function jsonTypeOf(dialect, expr) {
+    const columnRef = toSqlFragment(dialect, expr);
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb':
+            return (0, operators_1.literal)(`JSON_TYPE(${columnRef})`);
+        case 'postgres':
+        case 'cockroachdb':
+            return (0, operators_1.literal)(`jsonb_typeof(${columnRef})`);
+        case 'sqlite':
+            return (0, operators_1.literal)(`json_type(${columnRef})`);
+        case 'snowflake':
+            return (0, operators_1.literal)(`TYPEOF(${columnRef})`);
+        case 'clickhouse':
+            return (0, operators_1.literal)(`JSONType(${columnRef})`);
+        case 'mssql':
+        case 'oracle':
+        case 'redshift':
+        case 'db2':
+            throw new Error(`jsonTypeOf: not supported for dialect '${dialect}' - no documented function returns a general JSON value type name for this dialect.`);
+        default:
+            throw new Error(`jsonTypeOf: unsupported dialect '${dialect}'`);
+    }
+}