@memberjunction/generic-database-provider 5.32.0 → 5.34.0

package/dist/GenericDatabaseProvider.js

@@ -15,7 +15,7 @@
  *
  * @module @memberjunction/generic-database-provider
  */
-import { DatabaseProviderBase, EntityFieldTSType, EntityPermissionType, InMemoryLocalStorageProvider, Metadata, RunView, QueryInfo, LocalCacheManager, LogError, LogStatus, LogStatusEx, StripStopWords, QueryCacheManager, } from '@memberjunction/core';
+import { DatabaseProviderBase, EntityFieldTSType, EntityPermissionType, InMemoryLocalStorageProvider, Metadata, RunView, QueryInfo, LocalCacheManager, LogError, LogStatus, LogStatusEx, StripStopWords, QueryCacheManager, AfterKeyNotSupportedError, IsKeysetPaginationOrderableType, } from '@memberjunction/core';
 import { MJGlobal, SQLExpressionValidator, UUIDsEqual } from '@memberjunction/global';
 import { QueryPagingEngine } from './queryPagingEngine.js';
 // QueryParameterProcessor is now called internally by RenderPipeline
@@ -23,6 +23,7 @@ import { v4 as uuidv4 } from 'uuid';
 import { SqlLoggingSessionImpl } from './SqlLogger.js';
 // QueryCompositionEngine is now owned by RenderPipeline
 import { RenderPipeline } from './renderPipeline.js';
+import { useJsonArgShape } from './crudSprocFieldRules.js';
 import { QueryEngine, ViewInfo, } from '@memberjunction/core-entities';
 import { AIEngine } from '@memberjunction/aiengine';
 import { QueueManager } from '@memberjunction/queue';
@@ -133,13 +134,18 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
     async CreateSqlLogger(filePath, options) {
         const sessionId = uuidv4();
         const mjCoreSchema = this.ConfigData.MJCoreSchemaName;
+        const dialect = this.getDialect();
         const session = new SqlLoggingSessionImpl(sessionId, filePath, {
             defaultSchemaName: mjCoreSchema,
             // Inject the platform's batch separator as the default so callers don't need to
             // hardcode 'GO'. Callers can still override by passing batchSeparator explicitly.
             batchSeparator: this.PlatformBatchSeparator || undefined,
             ...options
-        });
+        }, 
+        // Pass the platform dialect through so SQL emission (Flyway placeholder escaping etc.)
+        // uses the right form for SQL Server vs. PostgreSQL. Falls back to the constructor's
+        // default (SQLServerDialect) when a subclass hasn't overridden getDialect().
+        dialect ?? undefined);
         // Initialize the session (create file, write header)
         await session.initialize();
         // Store in active sessions map
@@ -678,6 +684,38 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
     get PlatformBatchSeparator() {
         return this.getDialect()?.BatchSeparator() ?? '';
     }
+    /**
+     * Maximum number of parameters a CRUD stored procedure (`spCreate*`/`spUpdate*`/`spDelete*`)
+     * may declare on this database platform before CodeGen must emit a JSON-arg shape instead.
+     *
+     * - SQL Server: `Infinity` — SS supports up to 2,100 parameters per procedure, far beyond
+     *   any realistic CRUD sproc.
+     * - PostgreSQL: `90` — PG's hard `FUNC_MAX_ARGS` ceiling is 100 (compiled into the server,
+     *   not configurable on managed services like RDS/Aurora). 90 leaves headroom for column
+     *   adds without flipping sproc shape unexpectedly.
+     *
+     * Used by the shared `useJsonArgShape` predicate (CodeGen + provider call-site) to decide
+     * whether a given sproc should emit as typed-args + `_Clear` companions (today's shape) or
+     * as a single-JSONB-arg sproc with key-presence tri-state semantics. See
+     * [plans/json-arg-crud-sprocs.md](../../../plans/json-arg-crud-sprocs.md) and GitHub
+     * issue #2552.
+     */
+    get ProcedureParamLimit() {
+        return Infinity;
+    }
+    /**
+     * Returns true when CRUD sproc generation and call-construction for the
+     * given entity + sproc verb should use a single JSON-arg shape (instead of
+     * typed args + `_Clear` companions).
+     *
+     * Convenience wrapper around the pure `useJsonArgShape` helper, applying
+     * this provider's `ProcedureParamLimit`. CodeGen and runtime call-sites
+     * can invoke this via the provider instance to keep sproc emit and sproc
+     * invocation in lockstep.
+     */
+    UseJsonArgShape(entity, sprocType) {
+        return useJsonArgShape(entity, sprocType, this.ProcedureParamLimit);
+    }
     /**
      * Builds a platform-specific TOP/LIMIT clause for non-paginated row limits.
      * SQL Server: `TOP N`; PostgreSQL returns empty (uses LIMIT via BuildPaginationSQL).
@@ -724,6 +762,138 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
             return null;
         return `SELECT COUNT(*) AS ${this.QuoteIdentifier('TotalRowCount')} FROM ${this.QuoteSchemaAndView(entityInfo.SchemaName, entityInfo.BaseView)}`;
     }
+    /**
+     * Validates that the entity and RunViewParams are compatible with keyset (AfterKey) pagination,
+     * then returns the SQL predicate (`<pk> > 'value'` or `<pk> < 'value'`) and the resolved
+     * order-by direction.
+     *
+     * See {@link AfterKeyNotSupportedError} for the validation rules and {@link RunViewParams.AfterKey}
+     * for the API contract.
+     *
+     * @throws AfterKeyNotSupportedError on validation failure
+     */
+    BuildKeysetSeekClause(entityInfo, params) {
+        const afterKey = params.AfterKey;
+        // 1. Single-column PK requirement
+        const pkFields = entityInfo.PrimaryKeys;
+        if (!pkFields || pkFields.length === 0) {
+            throw new AfterKeyNotSupportedError(entityInfo.Name, 'CompositePK', `AfterKey requires a primary key on entity "${entityInfo.Name}", but none is defined.`);
+        }
+        if (pkFields.length > 1) {
+            throw new AfterKeyNotSupportedError(entityInfo.Name, 'CompositePK', `AfterKey requires a single-column primary key. Entity "${entityInfo.Name}" has a composite PK (${pkFields.length} columns: ${pkFields.map(f => f.Name).join(', ')}). Use StartRow-based pagination for composite-PK entities, or restructure the workload.`);
+        }
+        const pkField = pkFields[0];
+        // 2. Orderable PK type
+        if (!IsKeysetPaginationOrderableType(pkField.Type)) {
+            throw new AfterKeyNotSupportedError(entityInfo.Name, 'UnsupportedPKType', `AfterKey is not supported for entity "${entityInfo.Name}" because its PK column "${pkField.Name}" has type "${pkField.Type}", which is not in the keyset-orderable allowlist.`);
+        }
+        // 3. StartRow conflict
+        if (params.StartRow !== undefined && params.StartRow > 0) {
+            throw new AfterKeyNotSupportedError(entityInfo.Name, 'StartRowConflict', `AfterKey cannot be combined with StartRow > 0. Use one or the other.`);
+        }
+        // 4. AfterKey shape — must contain exactly one key matching the PK column
+        const pairs = afterKey.KeyValuePairs ?? [];
+        if (pairs.length !== 1) {
+            throw new AfterKeyNotSupportedError(entityInfo.Name, 'AfterKeyShape', `AfterKey must contain exactly one key/value pair matching the entity's PK column "${pkField.Name}". Got ${pairs.length} pairs.`);
+        }
+        const pair = pairs[0];
+        if (pair.FieldName?.toLowerCase().trim() !== pkField.Name.toLowerCase().trim()) {
+            throw new AfterKeyNotSupportedError(entityInfo.Name, 'AfterKeyShape', `AfterKey key name "${pair.FieldName}" does not match the entity's PK column "${pkField.Name}".`);
+        }
+        if (pair.Value === null || pair.Value === undefined || pair.Value === '') {
+            throw new AfterKeyNotSupportedError(entityInfo.Name, 'AfterKeyShape', `AfterKey value for "${pkField.Name}" is null/empty. To request the first page, omit AfterKey entirely.`);
+        }
+        // 5. OrderBy compatibility — must be empty, or reference only the PK column
+        let direction = 'ASC';
+        const rawOrderBy = params.OrderBy?.trim() ?? '';
+        if (rawOrderBy.length > 0) {
+            // Accept: "ID", "ID ASC", "ID DESC", "[ID]", "[ID] DESC", '"ID"', etc.
+            // Strip quoting characters and split on whitespace.
+            const stripped = rawOrderBy.replace(/[\[\]"`]/g, '').trim();
+            const tokens = stripped.split(/\s+/);
+            const colName = tokens[0]?.trim();
+            const dirToken = tokens[1]?.toUpperCase().trim();
+            if (!colName || colName.toLowerCase() !== pkField.Name.toLowerCase()) {
+                throw new AfterKeyNotSupportedError(entityInfo.Name, 'IncompatibleOrderBy', `When AfterKey is set, OrderBy must reference only the PK column "${pkField.Name}". Got "${rawOrderBy}".`);
+            }
+            if (tokens.length > 2 || (dirToken && dirToken !== 'ASC' && dirToken !== 'DESC')) {
+                throw new AfterKeyNotSupportedError(entityInfo.Name, 'IncompatibleOrderBy', `When AfterKey is set, OrderBy may only specify a direction (ASC/DESC). Got "${rawOrderBy}".`);
+            }
+            if (dirToken === 'DESC')
+                direction = 'DESC';
+        }
+        // 6. Build the seek predicate. Comparison operator depends on direction.
+        const op = direction === 'ASC' ? '>' : '<';
+        const pkColumnName = this.QuoteIdentifier(pkField.Name);
+        const literalValue = this.formatKeysetSeekValue(pair.Value, pkField.Type);
+        const seekPredicate = `${pkColumnName} ${op} ${literalValue}`;
+        return { seekPredicate, direction, pkColumnName };
+    }
+    /**
+     * Formats a CompositeKey value as a SQL literal for use in a keyset seek predicate.
+     *
+     * This bypasses parameter binding because the entire WHERE clause is built as a string
+     * elsewhere in this provider (consistent with ExtraFilter / OrderBy handling). The seek
+     * value comes from server-side application code, not raw user input — but we still type-
+     * check and escape to defend against any caller passing a tainted value.
+     *
+     * Strategy:
+     * - UUID types: validate strict UUID format, wrap in single quotes
+     * - Numeric types: validate finite number, output bare
+     * - Boolean: output 0/1 (SQL Server) or TRUE/FALSE (caller can override if needed)
+     * - Date/time types: validate ISO-ish string, wrap in single quotes
+     * - String types: escape single quotes by doubling, wrap in single quotes
+     *
+     * @throws AfterKeyNotSupportedError if the value fails type-specific validation
+     */
+    formatKeysetSeekValue(value, sqlType) {
+        const t = (sqlType || '').replace(/\s*\([^)]*\)\s*$/, '').trim().toLowerCase();
+        const asStr = String(value);
+        // UUIDs — validate format strictly
+        if (t === 'uniqueidentifier' || t === 'uuid') {
+            const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+            if (!uuidPattern.test(asStr)) {
+                throw new AfterKeyNotSupportedError('', 'AfterKeyShape', `AfterKey value "${asStr}" is not a valid UUID for ${sqlType} primary key.`);
+            }
+            return `'${asStr}'`;
+        }
+        // Numeric types
+        const numericTypes = new Set([
+            'int', 'bigint', 'smallint', 'tinyint', 'integer', 'bigserial', 'serial',
+            'decimal', 'numeric', 'money', 'smallmoney', 'float', 'real', 'double precision'
+        ]);
+        if (numericTypes.has(t)) {
+            const n = typeof value === 'number' ? value : Number(asStr);
+            if (!Number.isFinite(n)) {
+                throw new AfterKeyNotSupportedError('', 'AfterKeyShape', `AfterKey value "${asStr}" is not a valid numeric value for ${sqlType} primary key.`);
+            }
+            return String(n);
+        }
+        // Boolean / bit
+        if (t === 'bit' || t === 'boolean') {
+            const v = value === true || asStr === 'true' || asStr === '1';
+            return v ? '1' : '0';
+        }
+        // Date / time — accept anything ISO-ish; quote and escape single quotes
+        const dateTypes = new Set([
+            'date', 'datetime', 'datetime2', 'datetimeoffset', 'smalldatetime', 'time',
+            'timestamp', 'timestamp with time zone', 'timestamp without time zone'
+        ]);
+        if (dateTypes.has(t)) {
+            const escaped = asStr.replace(/'/g, "''");
+            // Reject anything containing semicolons or comment markers as a defense-in-depth check
+            if (/;|--|\/\*|\*\//.test(escaped)) {
+                throw new AfterKeyNotSupportedError('', 'AfterKeyShape', `AfterKey value for ${sqlType} primary key contains disallowed characters.`);
+            }
+            return `'${escaped}'`;
+        }
+        // String types (default)
+        const escaped = asStr.replace(/'/g, "''");
+        if (/;|--|\/\*|\*\//.test(escaped)) {
+            throw new AfterKeyNotSupportedError('', 'AfterKeyShape', `AfterKey value contains disallowed characters.`);
+        }
+        return `'${escaped}'`;
+    }
     /**
      * Transforms a user-provided SQL clause (ExtraFilter, OrderBy, etc.) for platform compatibility.
      * PostgreSQL overrides to quote mixed-case identifiers and convert bracket notation.
@@ -786,7 +956,21 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
             const overrideExcludeFilter = params.OverrideExcludeFilter ?? '';
             const saveViewResults = params.SaveViewResults ?? false;
             // ── TOP / pagination mode ──
-            const usingPagination = !!(params.MaxRows && params.MaxRows > 0 && params.StartRow !== undefined && params.StartRow >= 0);
+            // Keyset (AfterKey) takes precedence: validate now so failures are early, predictable,
+            // and never silently degrade to OFFSET. Throws AfterKeyNotSupportedError if invalid.
+            const usingKeyset = !!params.AfterKey;
+            let keysetSeekPredicate = '';
+            let keysetDirection = 'ASC';
+            let keysetPkColumnName = '';
+            if (usingKeyset) {
+                const seek = this.BuildKeysetSeekClause(entityInfo, params);
+                keysetSeekPredicate = seek.seekPredicate;
+                keysetDirection = seek.direction;
+                keysetPkColumnName = seek.pkColumnName;
+            }
+            // usingPagination is the OFFSET-based path; keyset uses TOP/LIMIT semantics like a
+            // non-paginated query, so we never set usingPagination=true when AfterKey is present.
+            const usingPagination = !usingKeyset && !!(params.MaxRows && params.MaxRows > 0 && params.StartRow !== undefined && params.StartRow >= 0);
             let topSQL = '';
             let maxRowsForQuery = 0;
             if (params.IgnoreMaxRows === true) {
@@ -796,6 +980,13 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
                 // pagination — no TOP, will add OFFSET/FETCH or LIMIT/OFFSET later
                 maxRowsForQuery = params.MaxRows;
             }
+            else if (usingKeyset) {
+                // Keyset uses TOP/LIMIT like a non-paginated query — bounded by MaxRows.
+                // MaxRows is required for keyset to make sense (otherwise return whole table).
+                const keysetMaxRows = params.MaxRows && params.MaxRows > 0 ? params.MaxRows : (entityInfo.UserViewMaxRows && entityInfo.UserViewMaxRows > 0 ? entityInfo.UserViewMaxRows : 1000);
+                topSQL = this.BuildTopClause(keysetMaxRows);
+                maxRowsForQuery = keysetMaxRows;
+            }
             else if (params.MaxRows && params.MaxRows > 0) {
                 topSQL = this.BuildTopClause(params.MaxRows);
                 maxRowsForQuery = params.MaxRows;
@@ -859,14 +1050,32 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
                     bHasWhere = true;
                 }
             }
+            // 6. Keyset (AfterKey) seek predicate — only on the data query, NOT the count query.
+            //    The count is the total matching the user-visible filters; the seek predicate is
+            //    a pagination cursor, conceptually distinct from "how many records match overall".
+            const seekPredicateForData = usingKeyset ? keysetSeekPredicate : '';
             if (bHasWhere) {
                 viewSQL += ` WHERE ${whereSQL}`;
                 if (countSQL)
                     countSQL += ` WHERE ${whereSQL}`;
             }
+            if (seekPredicateForData) {
+                viewSQL += bHasWhere ? ` AND (${seekPredicateForData})` : ` WHERE (${seekPredicateForData})`;
+            }
             // ── ORDER BY (transform user-provided clause for platform compatibility) ──
-            const rawOrderBy = params.OrderBy ? params.OrderBy : (viewEntity ? viewEntity.OrderByClause ?? '' : '');
-            const orderBy = rawOrderBy.length > 0 ? this.TransformExternalSQLClause(rawOrderBy, entityInfo) : '';
+            // For keyset (AfterKey) mode, we force ORDER BY <pk> <direction> regardless of the
+            // caller's OrderBy — BuildKeysetSeekClause already validated that any caller-provided
+            // OrderBy referenced the PK and we use the resolved direction.
+            let rawOrderBy;
+            if (usingKeyset) {
+                rawOrderBy = `${keysetPkColumnName} ${keysetDirection}`;
+            }
+            else {
+                rawOrderBy = params.OrderBy ? params.OrderBy : (viewEntity ? viewEntity.OrderByClause ?? '' : '');
+            }
+            const orderBy = rawOrderBy.length > 0
+                ? (usingKeyset ? rawOrderBy : this.TransformExternalSQLClause(rawOrderBy, entityInfo))
+                : '';
             // View run logging (SQL Server-specific, others return null)
             let userViewRunID = '';
             if (viewEntity?.ID && String(viewEntity.ID).length > 0 && saveViewResults && user) {
@@ -876,13 +1085,13 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
                     userViewRunID = logResult.runID;
                 }
                 else if (orderBy.length > 0) {
-                    if (!this.ValidateUserProvidedSQLClause(orderBy))
+                    if (!usingKeyset && !this.ValidateUserProvidedSQLClause(orderBy))
                         throw new Error(`Invalid Order By clause: ${orderBy}, contains one more for forbidden keywords`);
                     viewSQL += ` ORDER BY ${orderBy}`;
                 }
             }
             else if (orderBy.length > 0) {
-                if (!this.ValidateUserProvidedSQLClause(orderBy))
+                if (!usingKeyset && !this.ValidateUserProvidedSQLClause(orderBy))
                     throw new Error(`Invalid Order By clause: ${orderBy}, contains one more for forbidden keywords`);
                 viewSQL += ` ORDER BY ${orderBy}`;
             }
@@ -894,7 +1103,9 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
                 viewSQL += ' ' + this.BuildPaginationSQL(params.MaxRows, params.StartRow);
             }
             else if (!topSQL && maxRowsForQuery > 0) {
-                // Platform doesn't use TOP (e.g., PG uses LIMIT at end of query)
+                // Platform doesn't use TOP (e.g., PG uses LIMIT at end of query).
+                // This also covers the usingKeyset case on PG: topSQL is set to empty by PG's
+                // BuildTopClause, so we fall here and emit LIMIT N at the end.
                 const limitSQL = this.BuildNonPaginatedLimitSQL(maxRowsForQuery);
                 if (limitSQL)
                     viewSQL += ' ' + limitSQL;
@@ -1082,7 +1293,14 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
     }
     /**
      * Builds user search SQL for the given entity and search string.
+     *
      * Supports full-text search (if enabled) and field-by-field LIKE searching.
+     * For the LIKE path:
+     *   - honors EntityField.UserSearchPredicateAPI (Exact / BeginsWith / EndsWith / Contains)
+     *     so index-seekable predicates can be expressed,
+     *   - escapes LIKE metacharacters (%, _, [, ]) in user input with ESCAPE '\\',
+     *   - skips fields that are not sensible text-search targets (non-text types,
+     *     unbounded text columns when FTX is off).
      */
     createViewUserSearchSQL(entityInfo, userSearchString) {
         let sUserSearchSQL = '';
@@ -1106,23 +1324,78 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
             sUserSearchSQL = `${pkName} IN (SELECT ${pkName} FROM ${this.QuoteSchemaAndView(entityInfo.SchemaName, entityInfo.FullTextSearchFunction ?? '')}('${u}'))`;
         }
         else {
+            const escapedTerm = this.escapeLikeTerm(safeUserSearchString);
             for (const field of entityInfo.Fields) {
-                if (field.IncludeInUserSearchAPI) {
-                    let sParam = '';
-                    if (sUserSearchSQL.length > 0)
-                        sUserSearchSQL += ' OR ';
-                    if (field.UserSearchParamFormatAPI && field.UserSearchParamFormatAPI.length > 0)
-                        sParam = field.UserSearchParamFormatAPI.replace('{0}', safeUserSearchString);
-                    else
-                        sParam = ` LIKE '%${safeUserSearchString}%'`;
-                    sUserSearchSQL += `(${this.QuoteIdentifier(field.Name)} ${sParam})`;
-                }
+                if (!field.IncludeInUserSearchAPI)
+                    continue;
+                const sParam = this.buildPerFieldSearchPredicate(field, escapedTerm, safeUserSearchString);
+                if (!sParam)
+                    continue;
+                if (sUserSearchSQL.length > 0)
+                    sUserSearchSQL += ' OR ';
+                sUserSearchSQL += `(${this.QuoteIdentifier(field.Name)} ${sParam})`;
             }
             if (sUserSearchSQL.length > 0)
                 sUserSearchSQL = '(' + sUserSearchSQL + ')';
         }
         return sUserSearchSQL;
     }
+    /**
+     * Build the SQL fragment that compares one EntityField against a user search term.
+     *
+     * Resolution order:
+     *   1. UserSearchParamFormatAPI (custom override) wins if set, with `{0}` replaced
+     *      by the single-quote-escaped raw term. Caller is responsible for escaping
+     *      LIKE metacharacters in their format string if needed.
+     *   2. Otherwise, the field must be a text-searchable type. Non-text and unbounded-
+     *      text fields return '' (caller skips them).
+     *   3. Otherwise, the predicate is chosen from UserSearchPredicateAPI:
+     *        Exact      -> = N'term'                     (index-seekable)
+     *        BeginsWith -> LIKE N'term%' ESCAPE '\\'     (index-seekable)
+     *        EndsWith   -> LIKE N'%term' ESCAPE '\\'
+     *        Contains   -> LIKE N'%term%' ESCAPE '\\'   (default, non-seekable)
+     */
+    buildPerFieldSearchPredicate(field, escapedTerm, rawSafeTerm) {
+        if (field.UserSearchParamFormatAPI && field.UserSearchParamFormatAPI.length > 0) {
+            return field.UserSearchParamFormatAPI.replace('{0}', rawSafeTerm);
+        }
+        if (!this.isTextSearchableType(field))
+            return '';
+        const pred = (field.UserSearchPredicateAPI ?? 'Contains').trim();
+        switch (pred) {
+            case 'Exact':
+                return ` = N'${rawSafeTerm}'`;
+            case 'BeginsWith':
+                return ` LIKE N'${escapedTerm}%' ESCAPE '\\'`;
+            case 'EndsWith':
+                return ` LIKE N'%${escapedTerm}' ESCAPE '\\'`;
+            case 'Contains':
+            default:
+                return ` LIKE N'%${escapedTerm}%' ESCAPE '\\'`;
+        }
+    }
+    /**
+     * Escape characters that have special meaning in SQL Server LIKE patterns.
+     * The backslash itself must be escaped first so its replacement isn't reprocessed.
+     * Pair with `ESCAPE '\\'` on the LIKE clause.
+     */
+    escapeLikeTerm(safeTerm) {
+        return safeTerm.replace(/[\\%_\[\]]/g, m => '\\' + m);
+    }
+    /**
+     * True if the field's column type is appropriate for text-pattern search.
+     * Non-text types are rejected because LIKE forces an implicit per-row CONVERT
+     * to nvarchar. Unbounded (MAX/ntext/text) columns are rejected because the
+     * LIKE path cannot seek them; FTX is the right tool for those.
+     */
+    isTextSearchableType(field) {
+        const t = (field.Type ?? '').toLowerCase();
+        if (t !== 'nvarchar' && t !== 'varchar' && t !== 'char' && t !== 'nchar')
+            return false;
+        if (field.Length === -1)
+            return false;
+        return true;
+    }
     /**************************************************************************/
     // RenderViewWhereClause — View Template Rendering
     /**************************************************************************/
@@ -1177,6 +1450,24 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
     /**************************************************************************/
     // Cache Check Utilities
     /**************************************************************************/
+    /**
+     * Parses a timestamp string sent by the client.
+     *
+     * Accepts both ISO 8601 strings (the canonical form) and all-digit strings
+     * representing milliseconds since epoch. The numeric form has been observed
+     * in the wild from clients whose cache layer round-tripped a Date through a
+     * lossy serializer — `new Date('1778004618383')` returns `Invalid Date`,
+     * but `new Date(Number('1778004618383'))` is a valid timestamp. Returning
+     * `null` on unparseable input lets callers degrade to a stale-cache fallback
+     * instead of throwing `RangeError: Invalid time value` on a downstream
+     * `.toISOString()`.
+     */
+    parseClientTimestamp(raw) {
+        if (!raw)
+            return null;
+        const d = /^\d+$/.test(raw) ? new Date(Number(raw)) : new Date(raw);
+        return isNaN(d.getTime()) ? null : d;
+    }
     /**
      * Compares client cache status with server status to determine if cache is current.
      * Checks both row count and maxUpdatedAt timestamp.
@@ -1184,11 +1475,23 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
     isCacheCurrent(clientStatus, serverStatus) {
         if (clientStatus.rowCount !== serverStatus.rowCount)
             return false;
-        const clientDate = new Date(clientStatus.maxUpdatedAt);
+        // Handle empty result sets: if both sides report no timestamp, matching row count is sufficient
+        const clientEmpty = !clientStatus.maxUpdatedAt || clientStatus.maxUpdatedAt === '';
+        const serverEmpty = !serverStatus.maxUpdatedAt || serverStatus.maxUpdatedAt === '';
+        if (clientEmpty && serverEmpty)
+            return true;
+        const clientDate = this.parseClientTimestamp(clientStatus.maxUpdatedAt);
+        if (!clientDate)
+            return false;
         const serverDate = serverStatus.maxUpdatedAt ? new Date(serverStatus.maxUpdatedAt) : null;
+        // Server has no timestamp (e.g., empty table) — current if row counts match (already checked above)
         if (!serverDate)
             return clientStatus.rowCount === 0;
-        return clientDate.toISOString() === serverDate.toISOString();
+        if (isNaN(serverDate.getTime()))
+            return false;
+        // Compare as epoch milliseconds with 1-second tolerance to handle timestamp
+        // precision differences between SQL Server and JavaScript Date.toISOString()
+        return Math.abs(clientDate.getTime() - serverDate.getTime()) < 1000;
     }
     /**************************************************************************/
     // RunViewsWithCacheCheck — Shared Implementation
@@ -1212,7 +1515,10 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
             const errorResults = [];
             for (let i = 0; i < params.length; i++) {
                 const item = params[i];
-                if (!item.cacheStatus) {
+                // Keyset queries bypass the cache entirely (per the AfterKey API contract):
+                // each call uses a different seek key, so cached entries would never be
+                // reusable. Route directly to standard execution path.
+                if (!item.cacheStatus || item.params.AfterKey) {
                     itemsWithoutCacheCheck.push({ index: i, item });
                     continue;
                 }
@@ -1466,12 +1772,17 @@ export class GenericDatabaseProvider extends DatabaseProviderBase {
             const updatedRows = await this.getUpdatedRowsSince(params, entityInfo, clientMaxUpdatedAt, whereSQL, contextUser);
             const deletedRecordIDs = await this.getDeletedRecordIDsSince(entityInfo.ID, clientMaxUpdatedAt, contextUser);
             // Validation: detect hidden deletes not tracked in RecordChanges
-            const clientMaxUpdatedDate = new Date(clientMaxUpdatedAt);
+            const clientMaxUpdatedDate = this.parseClientTimestamp(clientMaxUpdatedAt);
+            if (!clientMaxUpdatedDate) {
+                // Unparseable client timestamp — can't trust the differential math; fall back.
+                return this.runFullQueryAndReturn(params, viewIndex, contextUser);
+            }
             const newInserts = updatedRows.filter(row => {
                 const createdAt = row['__mj_CreatedAt'];
                 if (!createdAt)
                     return false;
-                return new Date(String(createdAt)) > clientMaxUpdatedDate;
+                const created = new Date(String(createdAt));
+                return !isNaN(created.getTime()) && created > clientMaxUpdatedDate;
             }).length;
             const serverRowCount = serverStatus.rowCount ?? 0;
             const impliedDeletes = clientRowCount + newInserts - serverRowCount;