ts-prorm-orm 1.1.0

package/dist/errors/utils.js

@@ -0,0 +1,340 @@
+"use strict";
+/**
+ * Error utility functions for the ORM
+ * Provides helpers for error handling and conversion
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapError = wrapError;
+exports.aggregateErrors = aggregateErrors;
+exports.createValidationError = createValidationError;
+exports.isErrorCode = isErrorCode;
+exports.isRetryableError = isRetryableError;
+exports.getRootCause = getRootCause;
+exports.formatError = formatError;
+exports.defaultErrorHandler = defaultErrorHandler;
+const index_1 = require("./index");
+/**
+ * Wraps a database error into the appropriate Prorm error type
+ * @param error - The original error from the database
+ * @param sql - The SQL query that caused the error
+ * @returns The appropriate Prorm error
+ */
+function wrapError(error, sql) {
+    const errorMessage = error.message.toLowerCase();
+    // Check for connection errors
+    if (isConnectionErrorMessage(errorMessage)) {
+        return handleConnectionError(error, sql);
+    }
+    // Check for constraint violations. Foreign key and exclusion constraints
+    // must be checked before the (broader) unique constraint check, since
+    // messages like "FOREIGN KEY constraint failed" or Oracle's
+    // "integrity constraint ... violated - parent key not found" would
+    // otherwise be swallowed by the generic unique-constraint keyword match.
+    if (isForeignKeyConstraintError(errorMessage)) {
+        return handleForeignKeyConstraintError(error, sql);
+    }
+    if (isExclusionConstraintError(errorMessage)) {
+        return handleExclusionConstraintError(error, sql);
+    }
+    if (isUniqueConstraintError(errorMessage)) {
+        return handleUniqueConstraintError(error, sql);
+    }
+    // Check for timeout errors
+    if (isTimeoutError(errorMessage)) {
+        return new index_1.TimeoutError('Query timeout', { parent: error, sql });
+    }
+    // Check for resource locked errors
+    if (isResourceLockedError(errorMessage)) {
+        return new index_1.ResourceLockedError('Resource is locked', { parent: error, sql });
+    }
+    // Default to database error
+    return index_1.DatabaseError.from(error, { sql });
+}
+/**
+ * Handle connection-related errors
+ */
+function handleConnectionError(error, sql) {
+    const message = error.message.toLowerCase();
+    if (message.includes('refused') || message.includes('unable to connect')) {
+        return index_1.ConnectionError.refused({ parent: error });
+    }
+    if (message.includes('timeout') || message.includes('timed out')) {
+        return index_1.ConnectionError.timedOut({ parent: error });
+    }
+    if (message.includes('not reachable') || message.includes('not found')) {
+        return index_1.ConnectionError.unreachable({ parent: error });
+    }
+    return new index_1.ConnectionError(error.message, { parent: error, sql });
+}
+/**
+ * Handle unique constraint errors
+ */
+function handleUniqueConstraintError(error, sql) {
+    // Try to extract field names from error message
+    const fields = extractFieldNames(error.message);
+    return index_1.UniqueConstraintError.from(error, { sql, fields });
+}
+/**
+ * Handle foreign key constraint errors
+ */
+function handleForeignKeyConstraintError(error, sql) {
+    // Try to extract field/table information from error message
+    const info = extractForeignKeyInfo(error.message);
+    return index_1.ForeignKeyConstraintError.from(error, {
+        sql,
+        field: info.field,
+        table: info.table,
+    });
+}
+/**
+ * Handle exclusion constraint errors
+ */
+function handleExclusionConstraintError(error, sql) {
+    // Try to extract constraint name
+    const constraint = extractConstraintName(error.message);
+    return new index_1.ExclusionConstraintError(error.message, { parent: error, sql, constraint });
+}
+/**
+ * Check if error message indicates connection issue
+ */
+function isConnectionErrorMessage(message) {
+    const connectionKeywords = [
+        'connection',
+        'connect',
+        'refused',
+        'timeout',
+        'unreachable',
+        'network',
+        'econnrefused',
+        'econnreset',
+        'enotfound',
+    ];
+    return connectionKeywords.some((keyword) => message.includes(keyword));
+}
+/**
+ * Check if error message indicates unique constraint violation
+ */
+function isUniqueConstraintError(message) {
+    const uniqueKeywords = [
+        'unique',
+        'duplicate',
+        'already exists',
+        'duplicate key',
+        // NOTE: the bare word 'constraint' was previously included here, but it
+        // is far too generic - it also matches foreign key, check, and
+        // exclusion constraint messages (e.g. SQLite's "FOREIGN KEY constraint
+        // failed" or Oracle's "integrity constraint ... violated"), causing
+        // those errors to be misclassified as UniqueConstraintError.
+    ];
+    return uniqueKeywords.some((keyword) => message.includes(keyword));
+}
+/**
+ * Check if error message indicates foreign key constraint violation
+ */
+function isForeignKeyConstraintError(message) {
+    const fkKeywords = [
+        'foreign key',
+        'reference',
+        'referential integrity',
+        'foreign key constraint failed',
+        'foreign key constraint',
+        'has no child',
+        'cannot delete',
+        // Oracle: "ORA-02291: integrity constraint (...) violated - parent key not found"
+        // and "ORA-02292: integrity constraint (...) violated - child record found"
+        // don't mention "foreign key" literally.
+        'parent key not found',
+        'child record found',
+    ];
+    return fkKeywords.some((keyword) => message.includes(keyword));
+}
+/**
+ * Check if error message indicates exclusion constraint violation
+ */
+function isExclusionConstraintError(message) {
+    const exclusionKeywords = ['exclusion', 'OVERLAPS'];
+    return exclusionKeywords.some((keyword) => message.includes(keyword));
+}
+/**
+ * Check if error message indicates timeout
+ */
+function isTimeoutError(message) {
+    const timeoutKeywords = ['timeout', 'timed out', 'etimedout'];
+    return timeoutKeywords.some((keyword) => message.includes(keyword));
+}
+/**
+ * Check if error message indicates resource locked
+ */
+function isResourceLockedError(message) {
+    const lockedKeywords = ['locked', 'busy', 'exclusive', 'sqlite_busy', 'database is locked'];
+    return lockedKeywords.some((keyword) => message.includes(keyword));
+}
+/**
+ * Extract field names from error message
+ */
+function extractFieldNames(message) {
+    // SQLite format: UNIQUE constraint failed: tableName.columnName
+    const sqliteMatch = message.match(/UNIQUE constraint failed:\s*(.+)/i);
+    if (sqliteMatch) {
+        return sqliteMatch[1].split('.').map((s) => s.trim());
+    }
+    // PostgreSQL format: Key (column)=(value) already exists
+    const pgMatch = message.match(/Key \(([^)]+)\)=/i);
+    if (pgMatch) {
+        return [pgMatch[1]];
+    }
+    // MySQL format: Duplicate entry 'value' for key 'key'
+    const mysqlMatch = message.match(/Duplicate entry.*for key '(.+)'/i);
+    if (mysqlMatch) {
+        return [mysqlMatch[1]];
+    }
+    return [];
+}
+/**
+ * Extract foreign key info from error message
+ */
+function extractForeignKeyInfo(message) {
+    // SQLite format: FOREIGN KEY constraint failed
+    const sqliteMatch = message.match(/FOREIGN KEY constraint failed:\s*(.+)/i);
+    if (sqliteMatch) {
+        const parts = sqliteMatch[1].split('.');
+        return { field: parts[1]?.trim(), table: parts[0]?.trim() };
+    }
+    // PostgreSQL format: Key (field)=(value) is not present in table "table"
+    const pgMatch = message.match(/Key \(([^)]+)\)=.*is not present in table "([^"]+)"/i);
+    if (pgMatch) {
+        return { field: pgMatch[1], table: pgMatch[2] };
+    }
+    // MySQL format: Cannot add or update a child row: a foreign key constraint fails
+    const mysqlMatch = message.match(/foreign key constraint fails.*`([^`]+)`.`([^`]+)`/i);
+    if (mysqlMatch) {
+        return { table: mysqlMatch[1], field: mysqlMatch[2] };
+    }
+    return {};
+}
+/**
+ * Extract constraint name from error message
+ */
+function extractConstraintName(message) {
+    // Try to extract constraint name
+    const match = message.match(/constraint ["']?([^"'"]+)["']?/i);
+    return match?.[1];
+}
+/**
+ * Aggregates multiple validation errors into a single ValidationError
+ * @param errors - Array of validation errors or error arrays
+ * @returns A single ValidationError with all errors combined
+ */
+function aggregateErrors(...errors) {
+    const allErrors = [];
+    for (const error of errors) {
+        if (!error)
+            continue;
+        if (error instanceof index_1.ValidationError) {
+            allErrors.push(...error.errors);
+        }
+        else if (Array.isArray(error)) {
+            allErrors.push(...error);
+        }
+        else if (error instanceof Error) {
+            allErrors.push({
+                message: error.message,
+                type: 'Error',
+            });
+        }
+        else if (typeof error === 'string') {
+            allErrors.push({
+                message: error,
+                type: 'String Error',
+            });
+        }
+    }
+    return new index_1.ValidationError('Validation error', allErrors);
+}
+/**
+ * Creates a ValidationError with a single error item
+ */
+function createValidationError(message, path, value) {
+    return new index_1.ValidationError(message, [
+        {
+            message,
+            type: 'Validation Error',
+            path,
+            value,
+        },
+    ]);
+}
+/**
+ * Check if an error is a specific Prorm error type by code
+ */
+function isErrorCode(error, code) {
+    if (error instanceof index_1.PrormError) {
+        return error.code === code;
+    }
+    return false;
+}
+/**
+ * Check if error is retryable
+ */
+function isRetryableError(error) {
+    if (error instanceof index_1.TimeoutError)
+        return true;
+    if (error instanceof index_1.ResourceLockedError)
+        return true;
+    if (error instanceof index_1.ConnectionError) {
+        return (error.code === index_1.ErrorCodes.CONNECTION_TIMED_OUT || error.code === index_1.ErrorCodes.HOST_NOT_REACHABLE);
+    }
+    return false;
+}
+/**
+ * Get the root cause of an error (unwrap nested errors)
+ */
+function getRootCause(error) {
+    if (error instanceof index_1.PrormError && error.parent) {
+        return getRootCause(error.parent);
+    }
+    return error;
+}
+/**
+ * Format error for logging
+ */
+function formatError(error) {
+    if (error instanceof index_1.PrormError) {
+        const lines = [`[${error.name}] ${error.message}`, `  Code: ${error.code}`];
+        if (error.sql) {
+            lines.push(`  SQL: ${error.sql}`);
+        }
+        if (error.parent) {
+            lines.push(`  Parent: ${error.parent.message}`);
+        }
+        if (error instanceof index_1.ValidationError && error.errors.length > 0) {
+            lines.push('  Errors:');
+            for (const err of error.errors) {
+                lines.push(`    - ${err.path || 'unknown'}: ${err.message}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    if (error instanceof Error) {
+        return `[${error.name}] ${error.message}\n${error.stack || ''}`;
+    }
+    return String(error);
+}
+/**
+ * Default error handler that logs and re-throws
+ */
+function defaultErrorHandler(error) {
+    const formattedError = formatError(error);
+    console.error('Error occurred:', formattedError);
+    throw error;
+}
+exports.default = {
+    wrapError,
+    aggregateErrors,
+    createValidationError,
+    isErrorCode,
+    isRetryableError,
+    getRootCause,
+    formatError,
+    defaultErrorHandler,
+};

package/dist/errors.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Re-export all error classes and utilities
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./errors/index"), exports);
+__exportStar(require("./errors/utils"), exports);

package/dist/extensions/catalog/cloud-warehouse-features.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * Cloud warehouse / embedded-engine feature catalog: Snowflake, Redshift,
+ * ClickHouse, and SQLite.
+ *
+ * None of these four dialects have a genuine Postgres-style `CREATE EXTENSION`
+ * mechanism, so every entry below is `isNativeSqlExtension: false`. Instead they
+ * expose installable/enableable capabilities through a mix of:
+ *   - dedicated DDL objects (`CREATE STREAM`, `CREATE EXTERNAL SCHEMA`, `CREATE
+ *     VIRTUAL TABLE ... USING fts5`, table `ENGINE = ...` clauses),
+ *   - account/session-level enablement with no single-statement toggle
+ *     (Snowpark, external functions, Redshift ML),
+ *   - or compile-time/loadable-module features (SQLite's FTS5/R-Tree/JSON1,
+ *     which are compiled into `better-sqlite3` rather than "installed" via SQL).
+ *
+ * `installCommand` is only populated where a real, verifiable single SQL
+ * statement enables the feature; left undefined where enabling it requires
+ * case-by-case DDL, an external console/CLI step, or is compiled in by default.
+ *
+ * Where this ORM's own Snowflake/Redshift/ClickHouse/SQLite dialects (see
+ * `src/dialects/<dialect>/index.ts` and `src/dialects/<dialect>/GAPS.md`)
+ * already implement real support for a capability, the description says so
+ * explicitly and names the relevant method(s); where support is absent, the
+ * description says the capability is reachable only via raw SQL through this
+ * ORM today.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloudWarehouseFeatures = void 0;
+exports.cloudWarehouseFeatures = [
+    // ---------------------------------------------------------------------
+    // Snowflake
+    // ---------------------------------------------------------------------
+    {
+        name: 'Time Travel',
+        dialects: ['snowflake'],
+        category: 'utility',
+        description: 'Query historical versions of a table/schema/database via AT(TIMESTAMP=>...)/AT(OFFSET=>...)/AT(STATEMENT=>...)/BEFORE(STATEMENT=>...), and restore dropped objects with UNDROP. Implemented in this ORM\'s Snowflake dialect (buildTimeTravelClause, wired into buildSelectQuery).',
+        isNativeSqlExtension: false,
+        minVersion: 'Standard edition: 1 day retention; Enterprise+: up to 90 days',
+        docsUrl: 'https://docs.snowflake.com/en/user-guide/data-time-travel',
+    },
+    {
+        name: 'Zero-Copy Clone',
+        dialects: ['snowflake'],
+        category: 'utility',
+        description: 'Instant, storage-efficient copy of a table/schema/database via CREATE TABLE|SCHEMA|DATABASE ... CLONE <source>, optionally combined with a Time Travel clause to clone a historical version. Implemented in this ORM\'s Snowflake dialect (cloneTable/cloneSchema/cloneDatabase).',
+        installCommand: 'CREATE TABLE <target> CLONE <source>',
+        isNativeSqlExtension: false,
+        docsUrl: 'https://docs.snowflake.com/en/sql-reference/sql/create-clone',
+    },
+    {
+        name: 'Streams',
+        dialects: ['snowflake'],
+        category: 'replication',
+        description: 'Native change-data-capture primitive that tracks row-level INSERT/UPDATE/DELETE changes on a table (or view) since it was last consumed. Implemented in this ORM\'s Snowflake dialect (createStream/dropStream/showStreams).',
+        installCommand: 'CREATE STREAM <name> ON TABLE <table>',
+        isNativeSqlExtension: false,
+        docsUrl: 'https://docs.snowflake.com/en/user-guide/streams-intro',
+    },
+    {
+        name: 'Tasks',
+        dialects: ['snowflake'],
+        category: 'scheduling',
+        description: 'Scheduled or DAG-chained SQL/procedure execution (CREATE TASK ... [SCHEDULE=...|AFTER <task>] AS <sql>), Snowflake\'s native job-scheduling primitive, often paired with Streams for incremental ETL. Implemented in this ORM\'s Snowflake dialect (createTask/dropTask/executeTask).',
+        installCommand: "CREATE TASK <name> SCHEDULE = '5 MINUTE' AS <sql>",
+        isNativeSqlExtension: false,
+        docsUrl: 'https://docs.snowflake.com/en/user-guide/tasks-intro',
+    },
+    {
+        name: 'Snowpark',
+        dialects: ['snowflake'],
+        category: 'procedural-language',
+        description: 'Run Python, Java, or Scala UDFs, UDTFs, and stored procedures inside Snowflake\'s compute engine via CREATE FUNCTION/CREATE PROCEDURE ... LANGUAGE PYTHON|JAVA|SCALA, avoiding data movement to an external client. Not implemented in this ORM\'s Snowflake dialect, which only wraps SQL stored procedures (CREATE PROCEDURE ... LANGUAGE SQL); non-SQL UDFs/procedures require hand-written raw SQL today.',
+        installCommand: "CREATE FUNCTION my_udf(x FLOAT) RETURNS FLOAT LANGUAGE PYTHON RUNTIME_VERSION='3.11' HANDLER='udf' AS $$...$$",
+        isNativeSqlExtension: false,
+        docsUrl: 'https://docs.snowflake.com/en/developer-guide/snowpark/index',
+    },
+    {
+        name: 'External Functions',
+        dialects: ['snowflake'],
+        category: 'connectivity',
+        description: 'Call out to AWS Lambda, Azure Functions, or Google Cloud Functions from SQL via CREATE EXTERNAL FUNCTION ... API_INTEGRATION=... AS <endpoint URL>, after first creating an API integration object. Not implemented in this ORM\'s Snowflake dialect; reachable only via raw SQL.',
+        isNativeSqlExtension: false,
+        docsUrl: 'https://docs.snowflake.com/en/sql-reference/external-functions',
+    },
+    {
+        name: 'Cortex AISQL Functions',
+        dialects: ['snowflake'],
+        category: 'machine-learning',
+        description: 'Built-in SQL functions (e.g. SNOWFLAKE.CORTEX.COMPLETE, SUMMARIZE, TRANSLATE, EMBED_TEXT) that call hosted LLMs directly from a query, with no separate install step beyond having ACCOUNTADMIN-granted CORTEX access on the account. Not implemented in this ORM\'s Snowflake dialect; reachable only via raw SQL/attributes.',
+        isNativeSqlExtension: false,
+        docsUrl: 'https://docs.snowflake.com/en/user-guide/snowflake-cortex/aisql',
+    },
+    // ---------------------------------------------------------------------
+    // Redshift
+    // ---------------------------------------------------------------------
+    {
+        name: 'Redshift Spectrum',
+        dialects: ['redshift'],
+        category: 'foreign-data',
+        description: 'Query data directly in S3 (via the Glue/Athena Data Catalog or a Hive metastore) without loading it, using CREATE EXTERNAL SCHEMA ... FROM DATA CATALOG/HIVE METASTORE and CREATE EXTERNAL TABLE. This ORM\'s Redshift dialect explicitly throws on foreign-data-wrapper calls and its error message points callers at Spectrum, but does not itself build CREATE EXTERNAL SCHEMA/TABLE DDL — it must be issued as raw SQL today.',
+        installCommand: "CREATE EXTERNAL SCHEMA spectrum_schema FROM DATA CATALOG DATABASE 'db' IAM_ROLE '<role-arn>'",
+        isNativeSqlExtension: false,
+        docsUrl: 'https://docs.aws.amazon.com/redshift/latest/dg/c-getting-started-using-spectrum.html',
+    },
+    {
+        name: 'Redshift ML',
+        dialects: ['redshift'],
+        category: 'machine-learning',
+        description: "Train and deploy machine learning models from SQL via CREATE MODEL ... FROM (<query>) TARGET <col> FUNCTION <name> IAM_ROLE '<role-arn>', which Redshift compiles to a SageMaker Autopilot job behind the scenes and exposes as a callable SQL function for inference. Not implemented in this ORM's Redshift dialect; reachable only via raw SQL.",
+        isNativeSqlExtension: false,
+        docsUrl: 'https://docs.aws.amazon.com/redshift/latest/dg/machine_learning.html',
+    },
+    {
+        name: 'Federated Query',
+        dialects: ['redshift'],
+        category: 'foreign-data',
+        description: 'Query live data in Amazon RDS/Aurora PostgreSQL or MySQL directly from Redshift via CREATE EXTERNAL SCHEMA ... FROM POSTGRES/MYSQL, without ETL-ing it in first. Not implemented in this ORM\'s Redshift dialect (flagged as a gap with zero representation, not even a pointing error message); reachable only via raw SQL.',
+        installCommand: "CREATE EXTERNAL SCHEMA fed_schema FROM POSTGRES DATABASE 'db' URI '<host>' PORT 5432 IAM_ROLE '<role-arn>' SECRET_ARN '<secret-arn>'",
+        isNativeSqlExtension: false,
+        docsUrl: 'https://docs.aws.amazon.com/redshift/latest/dg/federated-overview.html',
+    },
+    // ---------------------------------------------------------------------
+    // ClickHouse
+    // ---------------------------------------------------------------------
+    {
+        name: 'Kafka Table Engine',
+        dialects: ['clickhouse'],
+        category: 'connectivity',
+        description: 'Streaming ingestion from a Kafka topic by creating a table with ENGINE = Kafka(broker_list, topic, group, format), typically paired with a materialized view that copies rows into a MergeTree table as they arrive. Not implemented as a typed helper in this ORM\'s ClickHouse dialect (createTable only defaults engine to MergeTree()); reachable by passing a raw engine string via TableOptions.engine.',
+        installCommand: "CREATE TABLE kafka_queue (...) ENGINE = Kafka('host:9092', 'topic', 'group1', 'JSONEachRow')",
+        isNativeSqlExtension: false,
+        docsUrl: 'https://clickhouse.com/docs/en/engines/table-engines/integrations/kafka',
+    },
+    {
+        name: 'S3 Table Engine',
+        dialects: ['clickhouse'],
+        category: 'foreign-data',
+        description: 'Read/write data directly in S3 (or S3-compatible storage) by creating a table with ENGINE = S3(path, format), or query it ad hoc via the s3() table function without creating a table at all. Not implemented as a typed helper in this ORM\'s ClickHouse dialect; reachable via a raw engine string or the s3() table function in raw SQL.',
+        installCommand: "CREATE TABLE s3_data (...) ENGINE = S3('https://bucket.s3.amazonaws.com/path/*.csv', 'CSV')",
+        isNativeSqlExtension: false,
+        docsUrl: 'https://clickhouse.com/docs/en/engines/table-engines/integrations/s3',
+    },
+    {
+        name: 'MySQL / PostgreSQL Table Engines',
+        dialects: ['clickhouse'],
+        category: 'foreign-data',
+        description: 'Federated queries against a live MySQL or PostgreSQL database by creating a table with ENGINE = MySQL(host, database, table, user, password) or ENGINE = PostgreSQL(...), or via the mysql()/postgresql() table functions. Not implemented as a typed helper in this ORM\'s ClickHouse dialect; reachable via a raw engine string or table function in raw SQL.',
+        installCommand: "CREATE TABLE mysql_users (...) ENGINE = MySQL('host:3306', 'db', 'users', 'user', 'password')",
+        isNativeSqlExtension: false,
+        docsUrl: 'https://clickhouse.com/docs/en/engines/table-engines/integrations/mysql',
+    },
+    {
+        name: 'Dictionary',
+        dialects: ['clickhouse'],
+        category: 'data-types',
+        description: 'In-memory (or cached) key-value lookup structure backed by another table, file, or HTTP source, created via CREATE DICTIONARY ... SOURCE(...) LAYOUT(...) LIFETIME(...) and queried with dictGet(). Not implemented in this ORM\'s ClickHouse dialect (no createDictionary/dropDictionary methods); reachable only via raw SQL.',
+        installCommand: "CREATE DICTIONARY dict_name (id UInt64, value String) PRIMARY KEY id SOURCE(HTTP(url 'http://...' format 'JSONEachRow')) LAYOUT(HASHED()) LIFETIME(300)",
+        isNativeSqlExtension: false,
+        docsUrl: 'https://clickhouse.com/docs/en/sql-reference/dictionaries',
+    },
+    {
+        name: 'Approximate Aggregate Functions',
+        dialects: ['clickhouse'],
+        category: 'utility',
+        description: 'Approximate cardinality (uniq/uniqCombined/uniqHLL12) and approximate percentile (quantile/quantiles/quantileTDigest) estimation functions for large-scale analytics. Implemented in this ORM\'s ClickHouse dialect as typed Literal-producing helper methods (uniq, uniqCombined, uniqHLL12, uniqExact, quantile, quantiles, quantileExact) usable in query attributes.',
+        isNativeSqlExtension: false,
+        docsUrl: 'https://clickhouse.com/docs/en/sql-reference/aggregate-functions/reference/uniq',
+    },
+    {
+        name: 'User-Defined Functions',
+        dialects: ['clickhouse'],
+        category: 'procedural-language',
+        description: 'Lambda-expression-based SQL UDFs defined via CREATE FUNCTION <name> AS (args) -> <expression>, reusable across queries by name. Not implemented in this ORM\'s ClickHouse dialect; reachable only via raw SQL.',
+        installCommand: 'CREATE FUNCTION my_func AS (x, y) -> x + y',
+        isNativeSqlExtension: false,
+        docsUrl: 'https://clickhouse.com/docs/en/sql-reference/statements/create/function',
+    },
+    // ---------------------------------------------------------------------
+    // SQLite
+    // ---------------------------------------------------------------------
+    {
+        name: 'FTS5',
+        dialects: ['sqlite'],
+        category: 'full-text-search',
+        description: 'Full-text search virtual table module (CREATE VIRTUAL TABLE ... USING fts5(...)) with MATCH queries, BM25 ranking, snippet/highlight functions, and porter/unicode61/trigram/ascii tokenizers. Compiled into better-sqlite3 by default (no separate install statement). Implemented in this ORM\'s SQLite dialect and sqlite-advanced.ts (createFTS5Table, createFTS5FromTable, dropFTS5Table, rebuildFTS5, optimizeFTS5, fts5Search; also used by createFulltextIndex).',
+        isNativeSqlExtension: false,
+        docsUrl: 'https://www.sqlite.org/fts5.html',
+    },
+    {
+        name: 'R-Tree',
+        dialects: ['sqlite'],
+        category: 'spatial-gis',
+        description: 'Spatial indexing virtual table module (CREATE VIRTUAL TABLE ... USING rtree(id, minX, maxX, ...)) for efficient range/bounding-box queries. Compiled into better-sqlite3 by default (no separate install statement). Implemented in this ORM\'s SQLite dialect (createSpatialIndex builds the rtree virtual table); auxiliary (+col) columns and rtree_i32 are not currently supported by that helper.',
+        isNativeSqlExtension: false,
+        docsUrl: 'https://www.sqlite.org/rtree.html',
+    },
+    {
+        name: 'JSON1',
+        dialects: ['sqlite'],
+        category: 'json',
+        description: 'JSON functions and table-valued functions (json_extract, json_set, json_remove, json_each, json_tree, json_valid, json_type) for querying and manipulating JSON stored in TEXT columns. Compiled into better-sqlite3 by default (no separate install statement) and integrated as SQLite\'s default; ~3.38+. Implemented in this ORM (sqlite-advanced.ts JSON1 section, used by json path-query/containment helpers); json_group_array/json_group_object aggregates and json_patch are not yet wired up.',
+        isNativeSqlExtension: false,
+        minVersion: '3.38+ (built-in by default; loadable extension on earlier versions)',
+        docsUrl: 'https://www.sqlite.org/json1.html',
+    },
+];