@objectstack/driver-sql 4.0.5 → 4.1.0

package/README.md

@@ -276,6 +276,63 @@ const results = await driver.raw(
 );
 ```
 
+> ⚠️ **Raw SQL bypasses driver-level tenant isolation.** The `WHERE
+> organization_id = ?` predicate that `find` / `update` / `delete`
+> auto-apply is **not** added to `driver.raw()` or `engine.execute()`
+> output. Always include the tenant predicate yourself when running raw
+> queries against tenant-scoped tables.
+
+## Tenant Isolation (Row-Level)
+
+When an object declares a tenant field (either explicitly via
+`tenancy.tenantField`, or implicitly by having an `organization_id`
+field), the driver auto-scopes every CRUD call by the caller's
+`options.tenantId`:
+
+| Operation | Scope behavior |
+|---|---|
+| `find`, `findOne`, `count`, `aggregate` | `WHERE <tenantField> = :tenantId` injected |
+| `update`, `delete`, `updateMany`, `deleteMany`, `bulkDelete` | Same `WHERE` injected — cross-tenant writes silently no-op |
+| `create`, `upsert`, `bulkCreate` | `<tenantField>` auto-injected on each row if absent |
+
+The engine (`@objectstack/objectql`) threads `ExecutionContext.tenantId`
+into options for you; manual `driver.find(...)` calls can pass
+`{ tenantId: '...' }` directly.
+
+### Declaring the tenant field
+
+```ts
+// Custom tenant column (default is 'organization_id')
+{
+  name: 'workspace_item',
+  tenancy: { enabled: true, strategy: 'shared', tenantField: 'workspace_id' },
+  fields: {
+    workspace_id: { type: 'string' },
+    /* ... */
+  },
+}
+```
+
+### Bypasses (intentional, documented)
+
+| Path | Tenant-scoped? | Why |
+|---|---|---|
+| Callers that omit `options.tenantId` | No | Seed scripts, boot-time installers, admin tooling |
+| `ExecutionContext.isSystem === true` | No (auto-`bypassTenantAudit`) | Kernel-internal mirrors, scheduled hooks |
+| Explicit `organization_id` on insert row | Wins | Admin tooling can target a specific tenant |
+| `driver.raw()` / `engine.execute(sql)` | No | Raw SQL is on you |
+| `driver.bulkUpdate` | Yes (it loops `update`) | Same scope as `update` |
+
+### Audit warning
+
+The driver logs **one warning per `{object}:{op}`** when a write hits a
+tenant-scoped object without `options.tenantId`. Genuine system writes
+(`ExecutionContext.isSystem === true`) auto-silence; everything else
+surfaces as `[tenant-audit] ...` so missing-context bugs are visible.
+
+Override per call: `options.bypassTenantAudit = true`.
+Override globally: `OS_TENANT_AUDIT=0`.
+
 ## Database-Specific Features
 
 ### PostgreSQL Features

package/dist/index.d.mts

@@ -47,7 +47,7 @@ type SqlDriverConfig = Knex.Config;
 declare class SqlDriver implements IDataDriver {
     readonly name: string;
     readonly version: string;
-    readonly supports: {
+    get supports(): {
         create: boolean;
         read: boolean;
         update: boolean;
@@ -59,6 +59,12 @@ declare class SqlDriver implements IDataDriver {
         savepoints: boolean;
         queryFilters: boolean;
         queryAggregations: boolean;
+        /**
+         * Per-granularity native date bucket support. Granularities marked
+         * `false` (or absent) fall back to in-memory `bucketDateValue()` via
+         * `engine.findData` — see `buildDateBucketExpr()` for the SQL emitted.
+         */
+        queryDateGranularity: Record<string, boolean>;
         querySorting: boolean;
         queryPagination: boolean;
         queryWindowFunctions: boolean;
@@ -85,12 +91,88 @@ declare class SqlDriver implements IDataDriver {
     protected jsonFields: Record<string, string[]>;
     protected booleanFields: Record<string, string[]>;
     protected tablesWithTimestamps: Set<string>;
+    /**
+     * Autonumber field configs per table, captured during initObjects.
+     *
+     * Each entry records:
+     *   - `prefix` + `padWidth`: how to render the next value (`CTR-0007`)
+     *   - `tenantField`: the column to scope the sequence by (defaults to
+     *     `organization_id` if the object has that field, otherwise null →
+     *     sequence is shared globally for that field)
+     *
+     * Numbering is backed by the `_objectstack_sequences` row keyed by
+     * `(object, tenant_id, field)`, not by scanning the data table on each
+     * insert. The sequence row is bootstrapped from the existing MAX on
+     * first use so legacy data is respected.
+     */
+    protected autoNumberFields: Record<string, Array<{
+        name: string;
+        format: string;
+        prefix: string;
+        padWidth: number;
+        tenantField: string | null;
+    }>>;
+    /** Whether the sequences table has been ensured this process. */
+    protected sequencesTableReady: boolean;
+    /** In-flight ensure promise; deduplicates concurrent first calls. */
+    protected sequencesTableEnsurePromise: Promise<void> | null;
+    /**
+     * Per-table tenant-isolation column. Populated during `initObjects` by
+     * detecting an `organization_id` field. When set and the caller passes
+     * `DriverOptions.tenantId`, the driver automatically:
+     *
+     *   - scopes reads/updates/deletes/aggregates to that tenant
+     *   - injects `organization_id` on inserts that omit it
+     *
+     * If `tenantId` is absent (admin / seed / system path) no scope is
+     * applied — preserves backward compatibility for tools that legitimately
+     * need cross-tenant access. Tenant enforcement is therefore opt-in by
+     * the caller, not by the driver.
+     */
+    protected tenantFieldByTable: Record<string, string | null>;
+    /** Throttle table for missing-tenantId warnings ({object}:{op}). */
+    protected tenantAuditWarned: Set<string>;
+    /**
+     * Optional logger sink for security-audit warnings. Tests inject a spy;
+     * production callers wire in their preferred logger. Defaults to
+     * `console.warn` so warnings surface even without setup.
+     */
+    protected logger: {
+        warn: (msg: string, meta?: any) => void;
+    };
     /** Whether the underlying database is a SQLite variant (sqlite3 or better-sqlite3). */
     protected get isSqlite(): boolean;
     /** Whether the underlying database is PostgreSQL. */
     protected get isPostgres(): boolean;
     /** Whether the underlying database is MySQL. */
     protected get isMysql(): boolean;
+    /**
+     * Per-granularity native SQL bucket support, computed from dialect.
+     *
+     * Must match `bucketDateValue()` in @objectstack/objectql exactly:
+     *   year    → 'YYYY'
+     *   month   → 'YYYY-MM'
+     *   day     → 'YYYY-MM-DD'
+     *   quarter → 'YYYY-Q[1-4]'
+     *   week    → 'YYYY-W[01-53]' (ISO-8601)
+     *
+     * Granularities not listed (or set to false) fall back to in-memory bucketing
+     * via engine.findData → applyInMemoryAggregation.
+     */
+    protected get dateGranularityCapabilities(): Record<string, boolean>;
+    /**
+     * Build SQL fragment + bindings for a date bucket expression.
+     * Returns `null` when the current dialect does not support the requested
+     * granularity — callers must fall back to in-memory bucketing.
+     *
+     * Exposed as `{sql, bindings}` (not `Knex.Raw`) so callers can both
+     * `groupByRaw()` and embed the same expression inside a `select() as alias`
+     * with correctly forwarded identifier bindings.
+     */
+    protected buildDateBucketExpr(field: string, granularity: 'day' | 'week' | 'month' | 'quarter' | 'year'): {
+        sql: string;
+        bindings: any[];
+    } | null;
     constructor(config: SqlDriverConfig);
     connect(): Promise<void>;
     checkHealth(): Promise<boolean>;
@@ -104,6 +186,40 @@ declare class SqlDriver implements IDataDriver {
      */
     findStream(object: string, query: QueryAST, options?: DriverOptions): AsyncGenerator<Record<string, any>>;
     create(object: string, data: Record<string, any>, options?: DriverOptions): Promise<any>;
+    /**
+     * Ensure the sequence-counter table exists. Idempotent and cheap after
+     * the first call (cached via `sequencesTableReady`).
+     */
+    protected ensureSequencesTable(): Promise<void>;
+    /**
+     * Bootstrap helper: scan the data table for the highest numeric suffix
+     * matching `prefix` (optionally scoped to a tenant). Used the first time
+     * a sequence row is created so legacy/seeded data continues monotonically.
+     */
+    protected scanMaxNumericTail(queryRunner: Knex | Knex.Transaction, tableName: string, field: string, prefix: string, tenantField: string | null, tenantId: string | null): Promise<number>;
+    /**
+     * Atomically reserve and return the next sequence value for
+     * `(object, tenantId, field)`. Bootstraps from the data-table MAX on
+     * first call so existing seeded records continue monotonically.
+     *
+     * Concurrency:
+     *   - SQLite: a write transaction (`BEGIN IMMEDIATE` via knex) serializes
+     *     all writers; safe in-process. Cross-process SQLite is out of scope.
+     *   - Postgres/MySQL: `SELECT … FOR UPDATE` row lock ensures only one
+     *     transaction reads-modifies-writes at a time. A PK-violation race on
+     *     first insert is retried as an UPDATE.
+     *
+     * Gaps are tolerated by design — a rolled-back insert "burns" a number,
+     * matching standard sequence semantics.
+     */
+    protected getNextSequenceValue(object: string, tableName: string, field: string, prefix: string, tenantField: string | null, tenantId: string | null, parentTrx?: Knex.Transaction): Promise<number>;
+    /**
+     * For each `auto_number` field on the object that the caller did not
+     * provide a value for, reserve the next sequence value scoped to the
+     * record's tenant (or globally if the object has no tenant field) and
+     * render `prefix + zero-padded(value)`.
+     */
+    protected fillAutoNumberFields(object: string, row: Record<string, any>, options?: DriverOptions): Promise<void>;
     update(object: string, id: string | number, data: Record<string, any>, options?: DriverOptions): Promise<any>;
     upsert(object: string, data: Record<string, any>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, any>>;
     delete(object: string, id: string | number, options?: DriverOptions): Promise<boolean>;
@@ -121,6 +237,22 @@ declare class SqlDriver implements IDataDriver {
     updateMany(object: string, query: QueryAST, data: any, options?: DriverOptions): Promise<number>;
     deleteMany(object: string, query: QueryAST, options?: DriverOptions): Promise<number>;
     count(object: string, query?: QueryAST, options?: DriverOptions): Promise<number>;
+    /**
+     * Run a raw SQL string or knex builder through the underlying knex
+     * connection.
+     *
+     * ⚠️ **Tenant isolation bypass.** Unlike `find`/`update`/`delete` etc.,
+     * raw `execute()` does NOT inject the `organization_id` predicate. The
+     * caller is responsible for either:
+     *   - inlining the tenant filter into the SQL (`WHERE organization_id = ?`),
+     *   - or restricting `execute()` to genuinely global queries
+     *     (schema introspection, sys_* tables that opt out of tenancy).
+     *
+     * Prefer the typed CRUD APIs whenever the operation can be expressed
+     * through them — they handle tenancy, soft-delete, and audit warnings
+     * automatically. See `README.md > Tenant Isolation` for the full bypass
+     * matrix.
+     */
     execute(command: any, params?: any[], options?: DriverOptions): Promise<any>;
     beginTransaction(): Promise<Knex.Transaction>;
     /** IDataDriver standard */
@@ -158,6 +290,48 @@ declare class SqlDriver implements IDataDriver {
         _intersectProps: {};
         _unionProps: never;
     }[]>;
+    /**
+     * Resolve the tenant column for the given object, if any.
+     *
+     * Lookup falls back to both the storage-mapped table name and the raw
+     * object name so callers that pass either form get the same answer.
+     * Returns `null` when the object has no tenant-isolation field.
+     */
+    protected resolveTenantField(object: string): string | null;
+    /**
+     * Apply a `WHERE tenant_field = ?` clause to the given query builder
+     * when:
+     *   1. `options.tenantId` is provided by the caller, AND
+     *   2. the object actually has a tenant-isolation field
+     *      (`organization_id` by convention).
+     *
+     * Without a tenantId the call is treated as an unscoped/admin path —
+     * keeps legacy callers, seed scripts, and cross-org tooling working.
+     * This is the single chokepoint for read-side tenant isolation in the
+     * SQL driver; every CRUD method routes through it.
+     */
+    protected applyTenantScope(builder: Knex.QueryBuilder, object: string, options?: DriverOptions): Knex.QueryBuilder;
+    /**
+     * Auto-inject the tenant column on insert rows when:
+     *   1. `options.tenantId` is provided, AND
+     *   2. the object has a tenant-isolation field, AND
+     *   3. the row does not already set that field.
+     *
+     * Explicit values are never overwritten — admins writing to a specific
+     * tenant via raw row data keep that authority.
+     */
+    protected injectTenantOnInsert(object: string, row: Record<string, any>, options?: DriverOptions): void;
+    /**
+     * Surface writes that target a tenant-scoped object but don't carry a
+     * `tenantId`. These are almost always system / seed / admin paths that
+     * forgot to thread the active session context — easy to miss in code
+     * review and impossible to find after a breach.
+     *
+     * Throttled to one warning per `${object}:${op}` so background workers
+     * don't spam the log. Set `options.bypassTenantAudit = true` (or env
+     * `OS_TENANT_AUDIT=0`) to silence intentionally.
+     */
+    protected auditMissingTenant(object: string, op: 'create' | 'update' | 'delete' | 'bulkCreate' | 'bulkDelete' | 'updateMany' | 'deleteMany' | 'upsert', options?: DriverOptions): void;
     protected applyFilters(builder: Knex.QueryBuilder, filters: any): void;
     protected applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp?: 'and' | 'or'): void;
     protected mapSortField(field: string): string;

package/dist/index.d.ts

@@ -47,7 +47,7 @@ type SqlDriverConfig = Knex.Config;
 declare class SqlDriver implements IDataDriver {
     readonly name: string;
     readonly version: string;
-    readonly supports: {
+    get supports(): {
         create: boolean;
         read: boolean;
         update: boolean;
@@ -59,6 +59,12 @@ declare class SqlDriver implements IDataDriver {
         savepoints: boolean;
         queryFilters: boolean;
         queryAggregations: boolean;
+        /**
+         * Per-granularity native date bucket support. Granularities marked
+         * `false` (or absent) fall back to in-memory `bucketDateValue()` via
+         * `engine.findData` — see `buildDateBucketExpr()` for the SQL emitted.
+         */
+        queryDateGranularity: Record<string, boolean>;
         querySorting: boolean;
         queryPagination: boolean;
         queryWindowFunctions: boolean;
@@ -85,12 +91,88 @@ declare class SqlDriver implements IDataDriver {
     protected jsonFields: Record<string, string[]>;
     protected booleanFields: Record<string, string[]>;
     protected tablesWithTimestamps: Set<string>;
+    /**
+     * Autonumber field configs per table, captured during initObjects.
+     *
+     * Each entry records:
+     *   - `prefix` + `padWidth`: how to render the next value (`CTR-0007`)
+     *   - `tenantField`: the column to scope the sequence by (defaults to
+     *     `organization_id` if the object has that field, otherwise null →
+     *     sequence is shared globally for that field)
+     *
+     * Numbering is backed by the `_objectstack_sequences` row keyed by
+     * `(object, tenant_id, field)`, not by scanning the data table on each
+     * insert. The sequence row is bootstrapped from the existing MAX on
+     * first use so legacy data is respected.
+     */
+    protected autoNumberFields: Record<string, Array<{
+        name: string;
+        format: string;
+        prefix: string;
+        padWidth: number;
+        tenantField: string | null;
+    }>>;
+    /** Whether the sequences table has been ensured this process. */
+    protected sequencesTableReady: boolean;
+    /** In-flight ensure promise; deduplicates concurrent first calls. */
+    protected sequencesTableEnsurePromise: Promise<void> | null;
+    /**
+     * Per-table tenant-isolation column. Populated during `initObjects` by
+     * detecting an `organization_id` field. When set and the caller passes
+     * `DriverOptions.tenantId`, the driver automatically:
+     *
+     *   - scopes reads/updates/deletes/aggregates to that tenant
+     *   - injects `organization_id` on inserts that omit it
+     *
+     * If `tenantId` is absent (admin / seed / system path) no scope is
+     * applied — preserves backward compatibility for tools that legitimately
+     * need cross-tenant access. Tenant enforcement is therefore opt-in by
+     * the caller, not by the driver.
+     */
+    protected tenantFieldByTable: Record<string, string | null>;
+    /** Throttle table for missing-tenantId warnings ({object}:{op}). */
+    protected tenantAuditWarned: Set<string>;
+    /**
+     * Optional logger sink for security-audit warnings. Tests inject a spy;
+     * production callers wire in their preferred logger. Defaults to
+     * `console.warn` so warnings surface even without setup.
+     */
+    protected logger: {
+        warn: (msg: string, meta?: any) => void;
+    };
     /** Whether the underlying database is a SQLite variant (sqlite3 or better-sqlite3). */
     protected get isSqlite(): boolean;
     /** Whether the underlying database is PostgreSQL. */
     protected get isPostgres(): boolean;
     /** Whether the underlying database is MySQL. */
     protected get isMysql(): boolean;
+    /**
+     * Per-granularity native SQL bucket support, computed from dialect.
+     *
+     * Must match `bucketDateValue()` in @objectstack/objectql exactly:
+     *   year    → 'YYYY'
+     *   month   → 'YYYY-MM'
+     *   day     → 'YYYY-MM-DD'
+     *   quarter → 'YYYY-Q[1-4]'
+     *   week    → 'YYYY-W[01-53]' (ISO-8601)
+     *
+     * Granularities not listed (or set to false) fall back to in-memory bucketing
+     * via engine.findData → applyInMemoryAggregation.
+     */
+    protected get dateGranularityCapabilities(): Record<string, boolean>;
+    /**
+     * Build SQL fragment + bindings for a date bucket expression.
+     * Returns `null` when the current dialect does not support the requested
+     * granularity — callers must fall back to in-memory bucketing.
+     *
+     * Exposed as `{sql, bindings}` (not `Knex.Raw`) so callers can both
+     * `groupByRaw()` and embed the same expression inside a `select() as alias`
+     * with correctly forwarded identifier bindings.
+     */
+    protected buildDateBucketExpr(field: string, granularity: 'day' | 'week' | 'month' | 'quarter' | 'year'): {
+        sql: string;
+        bindings: any[];
+    } | null;
     constructor(config: SqlDriverConfig);
     connect(): Promise<void>;
     checkHealth(): Promise<boolean>;
@@ -104,6 +186,40 @@ declare class SqlDriver implements IDataDriver {
      */
     findStream(object: string, query: QueryAST, options?: DriverOptions): AsyncGenerator<Record<string, any>>;
     create(object: string, data: Record<string, any>, options?: DriverOptions): Promise<any>;
+    /**
+     * Ensure the sequence-counter table exists. Idempotent and cheap after
+     * the first call (cached via `sequencesTableReady`).
+     */
+    protected ensureSequencesTable(): Promise<void>;
+    /**
+     * Bootstrap helper: scan the data table for the highest numeric suffix
+     * matching `prefix` (optionally scoped to a tenant). Used the first time
+     * a sequence row is created so legacy/seeded data continues monotonically.
+     */
+    protected scanMaxNumericTail(queryRunner: Knex | Knex.Transaction, tableName: string, field: string, prefix: string, tenantField: string | null, tenantId: string | null): Promise<number>;
+    /**
+     * Atomically reserve and return the next sequence value for
+     * `(object, tenantId, field)`. Bootstraps from the data-table MAX on
+     * first call so existing seeded records continue monotonically.
+     *
+     * Concurrency:
+     *   - SQLite: a write transaction (`BEGIN IMMEDIATE` via knex) serializes
+     *     all writers; safe in-process. Cross-process SQLite is out of scope.
+     *   - Postgres/MySQL: `SELECT … FOR UPDATE` row lock ensures only one
+     *     transaction reads-modifies-writes at a time. A PK-violation race on
+     *     first insert is retried as an UPDATE.
+     *
+     * Gaps are tolerated by design — a rolled-back insert "burns" a number,
+     * matching standard sequence semantics.
+     */
+    protected getNextSequenceValue(object: string, tableName: string, field: string, prefix: string, tenantField: string | null, tenantId: string | null, parentTrx?: Knex.Transaction): Promise<number>;
+    /**
+     * For each `auto_number` field on the object that the caller did not
+     * provide a value for, reserve the next sequence value scoped to the
+     * record's tenant (or globally if the object has no tenant field) and
+     * render `prefix + zero-padded(value)`.
+     */
+    protected fillAutoNumberFields(object: string, row: Record<string, any>, options?: DriverOptions): Promise<void>;
     update(object: string, id: string | number, data: Record<string, any>, options?: DriverOptions): Promise<any>;
     upsert(object: string, data: Record<string, any>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, any>>;
     delete(object: string, id: string | number, options?: DriverOptions): Promise<boolean>;
@@ -121,6 +237,22 @@ declare class SqlDriver implements IDataDriver {
     updateMany(object: string, query: QueryAST, data: any, options?: DriverOptions): Promise<number>;
     deleteMany(object: string, query: QueryAST, options?: DriverOptions): Promise<number>;
     count(object: string, query?: QueryAST, options?: DriverOptions): Promise<number>;
+    /**
+     * Run a raw SQL string or knex builder through the underlying knex
+     * connection.
+     *
+     * ⚠️ **Tenant isolation bypass.** Unlike `find`/`update`/`delete` etc.,
+     * raw `execute()` does NOT inject the `organization_id` predicate. The
+     * caller is responsible for either:
+     *   - inlining the tenant filter into the SQL (`WHERE organization_id = ?`),
+     *   - or restricting `execute()` to genuinely global queries
+     *     (schema introspection, sys_* tables that opt out of tenancy).
+     *
+     * Prefer the typed CRUD APIs whenever the operation can be expressed
+     * through them — they handle tenancy, soft-delete, and audit warnings
+     * automatically. See `README.md > Tenant Isolation` for the full bypass
+     * matrix.
+     */
     execute(command: any, params?: any[], options?: DriverOptions): Promise<any>;
     beginTransaction(): Promise<Knex.Transaction>;
     /** IDataDriver standard */
@@ -158,6 +290,48 @@ declare class SqlDriver implements IDataDriver {
         _intersectProps: {};
         _unionProps: never;
     }[]>;
+    /**
+     * Resolve the tenant column for the given object, if any.
+     *
+     * Lookup falls back to both the storage-mapped table name and the raw
+     * object name so callers that pass either form get the same answer.
+     * Returns `null` when the object has no tenant-isolation field.
+     */
+    protected resolveTenantField(object: string): string | null;
+    /**
+     * Apply a `WHERE tenant_field = ?` clause to the given query builder
+     * when:
+     *   1. `options.tenantId` is provided by the caller, AND
+     *   2. the object actually has a tenant-isolation field
+     *      (`organization_id` by convention).
+     *
+     * Without a tenantId the call is treated as an unscoped/admin path —
+     * keeps legacy callers, seed scripts, and cross-org tooling working.
+     * This is the single chokepoint for read-side tenant isolation in the
+     * SQL driver; every CRUD method routes through it.
+     */
+    protected applyTenantScope(builder: Knex.QueryBuilder, object: string, options?: DriverOptions): Knex.QueryBuilder;
+    /**
+     * Auto-inject the tenant column on insert rows when:
+     *   1. `options.tenantId` is provided, AND
+     *   2. the object has a tenant-isolation field, AND
+     *   3. the row does not already set that field.
+     *
+     * Explicit values are never overwritten — admins writing to a specific
+     * tenant via raw row data keep that authority.
+     */
+    protected injectTenantOnInsert(object: string, row: Record<string, any>, options?: DriverOptions): void;
+    /**
+     * Surface writes that target a tenant-scoped object but don't carry a
+     * `tenantId`. These are almost always system / seed / admin paths that
+     * forgot to thread the active session context — easy to miss in code
+     * review and impossible to find after a breach.
+     *
+     * Throttled to one warning per `${object}:${op}` so background workers
+     * don't spam the log. Set `options.bypassTenantAudit = true` (or env
+     * `OS_TENANT_AUDIT=0`) to silence intentionally.
+     */
+    protected auditMissingTenant(object: string, op: 'create' | 'update' | 'delete' | 'bulkCreate' | 'bulkDelete' | 'updateMany' | 'deleteMany' | 'upsert', options?: DriverOptions): void;
     protected applyFilters(builder: Knex.QueryBuilder, filters: any): void;
     protected applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp?: 'and' | 'or'): void;
     protected mapSortField(field: string): string;