remult 0.25.8 → 0.26.0

package/src/data-providers/sql-database.js

@@ -10,6 +10,7 @@ var RepositoryImplementation_js_1 = require("../remult3/RepositoryImplementation
 var sort_js_1 = require("../sort.js");
 var valueConverters_js_1 = require("../valueConverters.js");
 var repository_internals_js_1 = require("../remult3/repository-internals.js");
+var isOfType_js_1 = require("../isOfType.js");
 // @dynamic
 var SqlDatabase = /** @class */ (function () {
     function SqlDatabase(sql) {
@@ -18,12 +19,18 @@ var SqlDatabase = /** @class */ (function () {
         this.createdEntities = [];
         if (sql.wrapIdentifier)
             this.wrapIdentifier = function (x) { return sql.wrapIdentifier(x); };
+        if ((0, isOfType_js_1.isOfType)(sql, 'provideMigrationBuilder')) {
+            this.provideMigrationBuilder = function (x) { return sql.provideMigrationBuilder(x); };
+        }
+        if ((0, isOfType_js_1.isOfType)(sql, 'end'))
+            this.end = function () { return sql.end(); };
     }
-    SqlDatabase.getDb = function (remult) {
-        var r = (remult || remult_proxy_js_1.remult).dataProvider;
-        if (!r.createCommand)
-            throw 'the data provider is not an SqlDatabase';
-        return r;
+    SqlDatabase.getDb = function (dataProvider) {
+        var r = (dataProvider || remult_proxy_js_1.remult.dataProvider);
+        if ((0, isOfType_js_1.isOfType)(r, 'createCommand'))
+            return r;
+        else
+            throw 'the data provider is not an SqlCommandFactory';
     };
     SqlDatabase.prototype.createCommand = function () {
         return new LogSQLCommand(this.sql.createCommand(), SqlDatabase.LogToConsole);
@@ -129,6 +136,7 @@ var SqlDatabase = /** @class */ (function () {
                                 transaction: function (z) { return x.transaction(z); },
                                 supportsJsonColumnType: this.sql.supportsJsonColumnType,
                                 wrapIdentifier: this.wrapIdentifier,
+                                end: this.end,
                             }))];
                     case 2:
                         _a.sent();
@@ -141,6 +149,16 @@ var SqlDatabase = /** @class */ (function () {
             });
         }); });
     };
+    /**
+     * Creates a raw filter for entity filtering.
+     * @param {CustomSqlFilterBuilderFunction} build - The custom SQL filter builder function.
+     * @returns {EntityFilter<any>} - The entity filter with a custom SQL filter.
+     * @example
+     * SqlDatabase.rawFilter(({param}) =>
+          `"customerId" in (select id from customers where city = ${param(customerCity)})`
+        )
+     * @see [Leveraging Database Capabilities with Raw SQL in Custom Filters](https://remult.dev/docs/custom-filter.html#leveraging-database-capabilities-with-raw-sql-in-custom-filters)
+     */
     SqlDatabase.rawFilter = function (build) {
         var _a;
         return _a = {},
@@ -149,7 +167,8 @@ var SqlDatabase = /** @class */ (function () {
             },
             _a;
     };
-    SqlDatabase.filterToRaw = function (repo, condition, sqlCommand, dbNames) {
+    SqlDatabase.filterToRaw = function (repo, condition, sqlCommand, dbNames, wrapIdentifier) {
+        if (wrapIdentifier === void 0) { wrapIdentifier = function (x) { return x; }; }
         return tslib_1.__awaiter(this, void 0, void 0, function () {
             var r, b, _a, _b, _c;
             return tslib_1.__generator(this, function (_d) {
@@ -163,7 +182,7 @@ var SqlDatabase = /** @class */ (function () {
                         _b = [void 0, sqlCommand];
                         _c = dbNames;
                         if (_c) return [3 /*break*/, 2];
-                        return [4 /*yield*/, (0, filter_consumer_bridge_to_sql_request_js_1.dbNamesOf)(r.metadata)];
+                        return [4 /*yield*/, (0, filter_consumer_bridge_to_sql_request_js_1.dbNamesOf)(r.metadata, wrapIdentifier)];
                     case 1:
                         _c = (_d.sent());
                         _d.label = 2;
@@ -515,6 +534,11 @@ var ActualSQLServerDataProvider = /** @class */ (function () {
                         return [2 /*return*/, r.execute(statement).then(function (sqlResult) {
                                 var _a, _b;
                                 (_b = (_a = _this.sql._getSourceSql()).afterMutation) === null || _b === void 0 ? void 0 : _b.call(_a);
+                                if (sqlResult.rows.length != 1)
+                                    throw new Error('Failed to update row with id ' +
+                                        id +
+                                        ', rows updated: ' +
+                                        sqlResult.rows.length);
                                 return _this.buildResultRow(colKeys, sqlResult.rows[0], sqlResult);
                             })];
                 }

package/src/data-providers/web-sql-data-provider.d.ts

@@ -1,6 +1,5 @@
 import type { __RowsOfDataForTesting } from '../__RowsOfDataForTesting.js';
 import type { SqlCommand, SqlImplementation } from '../sql-command.js';
-import type { Remult } from '../context.js';
 import type { EntityMetadata } from '../remult3/remult3.js';
 export declare class WebSqlDataProvider implements SqlImplementation, __RowsOfDataForTesting {
     private databaseName;
@@ -8,7 +7,7 @@ export declare class WebSqlDataProvider implements SqlImplementation, __RowsOfDa
         [tableName: string]: any;
     };
     constructor(databaseName: string, databaseSize?: number);
-    static getDb(remult?: Remult): any;
+    end(): Promise<void>;
     getLimitSqlSyntax(limit: number, offset: number): string;
     entityIsUsedForTheFirstTime(entity: EntityMetadata): Promise<void>;
     ensureSchema(entities: EntityMetadata<any>[]): Promise<void>;

package/src/data-providers/web-sql-data-provider.js

@@ -13,14 +13,10 @@ var WebSqlDataProvider = /** @class */ (function () {
         //@ts-ignore
         this.db = window.openDatabase(databaseName, '1.0', databaseName, databaseSize);
     }
-    // return instance of websql.Database class - see @types/websql
-    WebSqlDataProvider.getDb = function (remult) {
-        var sql = sql_database_js_1.SqlDatabase.getDb(remult);
-        var me = sql._getSourceSql();
-        if (!me.db) {
-            throw 'the data provider is not a WebSqlDataProvider';
-        }
-        return me.db;
+    WebSqlDataProvider.prototype.end = function () {
+        return tslib_1.__awaiter(this, void 0, void 0, function () { return tslib_1.__generator(this, function (_a) {
+            return [2 /*return*/];
+        }); });
     };
     WebSqlDataProvider.prototype.getLimitSqlSyntax = function (limit, offset) {
         return ' limit ' + limit + ' offset ' + offset;

package/src/entity.d.ts

@@ -1,6 +1,7 @@
 import type { Allowed, AllowedForInstance } from './context.js';
 import type { FieldMetadata } from './column-interfaces.js';
 import type { EntityFilter, EntityIdFields, EntityMetadata, EntityOrderBy, EntityRef, FieldsMetadata, LifecycleEvent } from './remult3/remult3.js';
+import type { FilterPreciseValues } from './filter/filter-interfaces.js';
 export interface EntityOptions<entityType = any> {
     /**A human readable name for the entity */
     caption?: string;
@@ -24,18 +25,57 @@ export interface EntityOptions<entityType = any> {
     allowApiInsert?: AllowedForInstance<entityType>;
     /** sets  the `allowApiUpdate`, `allowApiDelete` and `allowApiInsert` properties in a single set */
     allowApiCrud?: Allowed;
-    /** A filter that determines which rows can be queries using the api.
-     * @description
-     * Use apiPrefilter in cases where you to restrict data based on user profile
+    /**
+     * An optional filter that determines which rows can be queried using the API.
+     * This filter is applied to all CRUD operations to ensure that only authorized data is accessible.
+     *
+     * Use `apiPrefilter` to restrict data based on user profile or other conditions.
+     *
      * @example
-     * apiPrefilter: { archive:false }
+     * // Only include non-archived items in API responses
+     * apiPrefilter: { archive: false }
      *
      * @example
-     * apiPrefilter: ()=> remult.isAllowed("admin")?{}:{ archive:false }
-     * @see [EntityFilter](http://remult.dev/docs/entityFilter.html)
+     * // Allow admins to access all rows, but restrict non-admins to non-archived items
+     * apiPrefilter: () => remult.isAllowed("admin") ? {} : { archive: false }
      *
+     * @see [EntityFilter](https://remult.dev/docs/access-control.html#filtering-accessible-rows)
      */
     apiPrefilter?: EntityFilter<entityType> | (() => EntityFilter<entityType> | Promise<EntityFilter<entityType>>);
+    /**
+     * An optional function that allows for preprocessing or modifying the EntityFilter for a specific entity type
+     * before it is used in API CRUD operations. This function can be used to enforce additional access control
+     * rules or adjust the filter based on the current context or specific request.
+     *
+     * @template entityType The type of the entity being filtered.
+     * @param filter The initial EntityFilter for the entity type.
+     * @param event Additional information and utilities for preprocessing the filter.
+     * @returns The modified EntityFilter or a Promise that resolves to the modified EntityFilter.
+     *
+     * @example
+     * ```typescript
+     * @Entity<Task>("tasks", {
+     *   apiPreprocessFilter: async (filter, { getPreciseValues }) => {
+     *     // Ensure that users can only query tasks for specific customers
+     *     const preciseValues = await getPreciseValues();
+     *     if (!preciseValues.customerId) {
+     *       throw new ForbiddenError("You must specify a valid customerId filter");
+     *     }
+     *     return filter;
+     *   }
+     * })
+     * ```
+     */
+    apiPreprocessFilter?: (filter: EntityFilter<entityType>, event: PreprocessFilterEvent<entityType>) => EntityFilter<entityType> | Promise<EntityFilter<entityType>>;
+    /**
+     * Similar to apiPreprocessFilter, but for backend operations.
+     *
+     * @template entityType The type of the entity being filtered.
+     * @param filter The initial EntityFilter for the entity type.
+     * @param event Additional information and utilities for preprocessing the filter.
+     * @returns The modified EntityFilter or a Promise that resolves to the modified EntityFilter.
+     */
+    backendPreprocessFilter?: (filter: EntityFilter<entityType>, event: PreprocessFilterEvent<entityType>) => EntityFilter<entityType> | Promise<EntityFilter<entityType>>;
     /** A filter that will be used for all queries from this entity both from the API and from within the backend.
      * @example
      * backendPrefilter: { archive:false }
@@ -124,3 +164,21 @@ export interface EntityOptions<entityType = any> {
     entityRefInit?: (ref: EntityRef<entityType>, row: entityType) => void;
     apiRequireId?: Allowed;
 }
+/**
+ * Provides additional information and utilities for preprocessing filters in API and backend operations.
+ * @template entityType The type of the entity being filtered.
+ */
+export interface PreprocessFilterEvent<entityType> {
+    /**
+     * Metadata of the entity being filtered.
+     */
+    metadata: EntityMetadata<entityType>;
+    /**
+     * Retrieves precise values for each property in a filter for an entity.
+     * @param filter Optional filter to analyze. If not provided, the current filter being preprocessed is used.
+     * @returns A promise that resolves to a FilterPreciseValues object containing the precise values for each property.
+     
+    * {@Link FilterPreciseValues }
+     */
+    getFilterPreciseValues(filter?: EntityFilter<entityType>): Promise<FilterPreciseValues<entityType>>;
+}

package/src/filter/filter-consumer-bridge-to-sql-request.d.ts

@@ -1,7 +1,7 @@
 import type { FieldMetadata } from '../column-interfaces.js';
 import type { EntityMetadataOverloads, RepositoryOverloads } from '../remult3/RepositoryImplementation.js';
 import type { EntityFilter, EntityMetadata, MembersOnly } from '../remult3/remult3.js';
-import type { SqlCommandWithParameters } from '../sql-command.js';
+import type { HasWrapIdentifier, SqlCommandWithParameters } from '../sql-command.js';
 import type { Filter, FilterConsumer } from './filter-interfaces.js';
 export declare class FilterConsumerBridgeToSqlRequest implements FilterConsumer {
     private r;
@@ -28,25 +28,49 @@ export declare class FilterConsumerBridgeToSqlRequest implements FilterConsumer
     private addToWhere;
     databaseCustom(databaseCustom: CustomSqlFilterObject): void;
 }
-export type CustomSqlFilterBuilderFunction = (builder: CustomSqlFilterBuilder) => void | Promise<any>;
 export interface CustomSqlFilterObject {
     buildSql: CustomSqlFilterBuilderFunction;
 }
-export declare class CustomSqlFilterBuilder {
+/**
+ * Represents a custom SQL filter builder function.
+ * @callback CustomSqlFilterBuilderFunction
+ * @param {CustomSqlFilterBuilder} builder - The custom SQL filter builder instance.
+ * @returns {void | string | Promise<string | void> } - The result of the custom SQL filter builder function.
+ */
+export type CustomSqlFilterBuilderFunction = (builder: CustomSqlFilterBuilder) => void | string | Promise<string | void>;
+/**
+ * Represents a custom SQL filter builder.
+ */
+export declare class CustomSqlFilterBuilder implements SqlCommandWithParameters, HasWrapIdentifier {
     private r;
-    constructor(r: SqlCommandWithParameters);
+    wrapIdentifier: (name: string) => string;
+    constructor(r: SqlCommandWithParameters, wrapIdentifier: (name: string) => string);
     sql: string;
-    /** @deprecated @deprecated use `param` instead*/
+    /** @deprecated  use `param` instead*/
     addParameterAndReturnSqlToken(val: any): string;
-    param<valueType>(val: valueType, field?: FieldMetadata<valueType>): string;
-    filterToRaw<entityType>(repo: RepositoryOverloads<entityType>, condition: EntityFilter<entityType>): Promise<string>;
+    /**
+     * Adds a parameter value.
+     * @param {valueType} val - The value to add as a parameter.
+     * @param {FieldMetadata<valueType>} [field] - The field metadata.
+     * @returns {string} - The SQL token.
+     */
+    param: <valueType>(val: valueType, field?: FieldMetadata<valueType, any>) => string;
+    /**
+     * Converts an entity filter into a raw SQL condition - and appends to it any `backendPrefilter` and `backendPreprocessFilter`
+     * @param {RepositoryOverloads<entityType>} repo - The repository.
+     * @param {EntityFilter<entityType>} condition - The entity filter.
+     * @returns {Promise<string>} - The raw SQL.
+     */
+    filterToRaw: <entityType>(repo: RepositoryOverloads<entityType>, condition: EntityFilter<entityType>) => Promise<string>;
 }
 export declare function isDbReadonly<entityType>(field: FieldMetadata, dbNames: EntityDbNames<entityType>): boolean;
 export declare function shouldNotCreateField<entityType>(field: FieldMetadata, dbNames: EntityDbNames<entityType>): boolean;
+export declare function shouldCreateEntity(entity: EntityMetadata<any>, e: EntityDbNamesBase): boolean;
 export declare type EntityDbNamesBase = {
     $entityName: string;
     $dbNameOf(field: FieldMetadata<any> | string): string;
     toString(): string;
+    wrapIdentifier: (name: string) => string;
 };
 export declare type EntityDbNames<entityType> = {
     [Properties in keyof Required<MembersOnly<entityType>>]: string;

package/src/filter/filter-consumer-bridge-to-sql-request.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fieldDbName = exports.entityDbName = exports.dbNamesOf = exports.shouldNotCreateField = exports.isDbReadonly = exports.CustomSqlFilterBuilder = exports.FilterConsumerBridgeToSqlRequest = void 0;
+exports.fieldDbName = exports.entityDbName = exports.dbNamesOf = exports.shouldCreateEntity = exports.shouldNotCreateField = exports.isDbReadonly = exports.CustomSqlFilterBuilder = exports.FilterConsumerBridgeToSqlRequest = void 0;
 var tslib_1 = require("tslib");
 var sql_database_js_1 = require("../data-providers/sql-database.js");
 var remult_proxy_js_1 = require("../remult-proxy.js");
@@ -215,17 +215,19 @@ var FilterConsumerBridgeToSqlRequest = /** @class */ (function () {
     FilterConsumerBridgeToSqlRequest.prototype.databaseCustom = function (databaseCustom) {
         var _this = this;
         this.promises.push((function () { return tslib_1.__awaiter(_this, void 0, void 0, function () {
-            var item;
+            var item, sql;
             return tslib_1.__generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
                         if (!(databaseCustom === null || databaseCustom === void 0 ? void 0 : databaseCustom.buildSql)) return [3 /*break*/, 2];
-                        item = new CustomSqlFilterBuilder(this.r);
+                        item = new CustomSqlFilterBuilder(this.r, this.nameProvider.wrapIdentifier);
                         return [4 /*yield*/, databaseCustom.buildSql(item)];
                     case 1:
-                        _a.sent();
-                        if (item.sql) {
-                            this.addToWhere('(' + item.sql + ')');
+                        sql = _a.sent();
+                        if (typeof sql !== 'string')
+                            sql = item.sql;
+                        if (sql) {
+                            this.addToWhere('(' + sql + ')');
                         }
                         _a.label = 2;
                     case 2: return [2 /*return*/];
@@ -236,28 +238,45 @@ var FilterConsumerBridgeToSqlRequest = /** @class */ (function () {
     return FilterConsumerBridgeToSqlRequest;
 }());
 exports.FilterConsumerBridgeToSqlRequest = FilterConsumerBridgeToSqlRequest;
+/**
+ * Represents a custom SQL filter builder.
+ */
 var CustomSqlFilterBuilder = /** @class */ (function () {
-    function CustomSqlFilterBuilder(r) {
+    function CustomSqlFilterBuilder(r, wrapIdentifier) {
+        var _this = this;
         this.r = r;
+        this.wrapIdentifier = wrapIdentifier;
         this.sql = '';
+        /**
+         * Adds a parameter value.
+         * @param {valueType} val - The value to add as a parameter.
+         * @param {FieldMetadata<valueType>} [field] - The field metadata.
+         * @returns {string} - The SQL token.
+         */
+        this.param = function (val, field) {
+            if (typeof field === 'object' && field.valueConverter.toDb) {
+                val = field.valueConverter.toDb(val);
+            }
+            return _this.r.param(val);
+        };
+        /**
+         * Converts an entity filter into a raw SQL condition - and appends to it any `backendPrefilter` and `backendPreprocessFilter`
+         * @param {RepositoryOverloads<entityType>} repo - The repository.
+         * @param {EntityFilter<entityType>} condition - The entity filter.
+         * @returns {Promise<string>} - The raw SQL.
+         */
+        this.filterToRaw = function (repo, condition) { return tslib_1.__awaiter(_this, void 0, void 0, function () {
+            return tslib_1.__generator(this, function (_a) {
+                return [2 /*return*/, sql_database_js_1.SqlDatabase.filterToRaw(repo, condition, this, undefined, this.wrapIdentifier)];
+            });
+        }); };
+        this.param.bind(this);
+        this.filterToRaw.bind(this);
     }
-    /** @deprecated @deprecated use `param` instead*/
+    /** @deprecated  use `param` instead*/
     CustomSqlFilterBuilder.prototype.addParameterAndReturnSqlToken = function (val) {
         return this.param(val);
     };
-    CustomSqlFilterBuilder.prototype.param = function (val, field) {
-        if (typeof field === 'object' && field.valueConverter.toDb) {
-            val = field.valueConverter.toDb(val);
-        }
-        return this.r.param(val);
-    };
-    CustomSqlFilterBuilder.prototype.filterToRaw = function (repo, condition) {
-        return tslib_1.__awaiter(this, void 0, void 0, function () {
-            return tslib_1.__generator(this, function (_a) {
-                return [2 /*return*/, sql_database_js_1.SqlDatabase.filterToRaw(repo, condition, this)];
-            });
-        });
-    };
     return CustomSqlFilterBuilder;
 }());
 exports.CustomSqlFilterBuilder = CustomSqlFilterBuilder;
@@ -272,6 +291,11 @@ function shouldNotCreateField(field, dbNames) {
         (field.options.sqlExpression && field.dbName != dbNames.$dbNameOf(field)));
 }
 exports.shouldNotCreateField = shouldNotCreateField;
+function shouldCreateEntity(entity, e) {
+    return (!entity.options.sqlExpression &&
+        e.$entityName.toLowerCase().indexOf('from ') < 0);
+}
+exports.shouldCreateEntity = shouldCreateEntity;
 function dbNamesOf(repo, wrapIdentifierOrOptions) {
     return tslib_1.__awaiter(this, void 0, void 0, function () {
         var options, meta, result, _a, _b, field, r, e_3_1;
@@ -301,6 +325,7 @@ function dbNamesOf(repo, wrapIdentifierOrOptions) {
                                 key = field.key;
                             return result[key];
                         },
+                        _c.wrapIdentifier = options.wrapIdentifier,
                         _c);
                     _e.label = 2;
                 case 2:

package/src/filter/filter-interfaces.d.ts

@@ -1,78 +1,124 @@
 import type { FieldMetadata } from '../column-interfaces.js';
 import type { Remult } from '../context.js';
-import type { EntityFilter, EntityMetadata } from '../remult3/remult3.js';
+import type { EntityFilter, EntityMetadata, MembersOnly } from '../remult3/remult3.js';
 /**
  * The `Filter` class is a helper class that focuses on filter-related concerns. It provides methods
  * for creating and applying filters in queries.
  */
 export declare class Filter {
     private apply;
+    /**
+     * Retrieves precise values for each property in a filter for an entity.
+     * @template entityType The type of the entity being filtered.
+     * @param metadata The metadata of the entity being filtered.
+     * @param filter The filter to analyze.
+     * @returns A promise that resolves to a FilterPreciseValues object containing the precise values for each property.
+     * @example
+     * const preciseValues = await Filter.getPreciseValues(meta, {
+     *   status: { $ne: 'active' },
+     *   $or: [
+     *     { customerId: ["1", "2"] },
+     *     { customerId: "3" }
+     *   ]
+     * });
+     * console.log(preciseValues);
+     * // Output:
+     * // {
+     * //   "customerId": ["1", "2", "3"], // Precise values inferred from the filter
+     * //   "status": undefined,           // Cannot infer precise values for 'status'
+     * // }
+    
+     */
+    static getPreciseValues<entityType>(metadata: EntityMetadata<entityType>, filter: EntityFilter<entityType>): Promise<FilterPreciseValues<entityType>>;
+    /**
+     * Retrieves precise values for each property in a filter for an entity.
+     * @template entityType The type of the entity being filtered.
+     * @param metadata The metadata of the entity being filtered.
+     * @param filter The filter to analyze.
+     * @returns A promise that resolves to a FilterPreciseValues object containing the precise values for each property.
+     * @example
+     * const preciseValues = await where.getPreciseValues();
+     * console.log(preciseValues);
+     * // Output:
+     * // {
+     * //   "customerId": ["1", "2", "3"], // Precise values inferred from the filter
+     * //   "status": undefined,           // Cannot infer precise values for 'status'
+     * // }
+    
+     */
+    getPreciseValues<entityType>(): Promise<FilterPreciseValues<entityType>>;
     /**
      * Creates a custom filter. Custom filters are evaluated on the backend, ensuring security and efficiency.
      * When the filter is used in the frontend, only its name is sent to the backend via the API,
      * where the filter gets translated and applied in a safe manner.
      *
      * @template entityType The entity type for the filter.
-     * @param {function(): EntityFilter<entityType>} rawFilterTranslator A function that returns an `EntityFilter`.
+     * @param {function(): EntityFilter<entityType>} translator A function that returns an `EntityFilter`.
      * @param {string} [key] An optional unique identifier for the custom filter.
      * @returns {function(): EntityFilter<entityType>} A function that returns an `EntityFilter` of type `entityType`.
      *
      * @example
-     * // In an entity class, add a static method for the custom filter
-     * static titleLengthFilter = Filter.createCustom<Task>(() => {
-     *   return SqlDatabase.rawFilter((whereFragment) => {
-     *     whereFragment.sql = 'length(title) > 10';
-     *   });
-     * });
-     *
+     *  class Order {
+     *  //...
+     *  static activeOrdersFor = Filter.createCustom<Order, { year: number }>(
+     *    async ({ year }) => {
+     *      return {
+     *        status: ['created', 'confirmed', 'pending', 'blocked', 'delayed'],
+     *        createdAt: {
+     *          $gte: new Date(year, 0, 1),
+     *          $lt: new Date(year + 1, 0, 1),
+     *        },
+     *      }
+     *    },
+     *  )
+     *}
      * // Usage
-     * console.table(
-     *   await remult.repo(Task).find({
-     *     where: Task.titleLengthFilter()
-     *   })
-     * );
+     * await repo(Order).find({
+     *  where: Order.activeOrders({ year }),
+     *})
+  
+  
      * @see
      * [Sql filter and Custom filter](/docs/custom-filter.html)
      * [Filtering and Relations](/docs/filtering-and-relations.html)
      */
-    static createCustom<entityType>(rawFilterTranslator: (unused: never, r: Remult) => EntityFilter<entityType> | Promise<EntityFilter<entityType>>, key?: string): (() => EntityFilter<entityType>) & customFilterInfo<entityType>;
+    static createCustom<entityType>(translator: (unused: never, r: Remult) => EntityFilter<entityType> | Promise<EntityFilter<entityType>>, key?: string): (() => EntityFilter<entityType>) & customFilterInfo<entityType>;
     /**
      * Creates a custom filter. Custom filters are evaluated on the backend, ensuring security and efficiency.
-     * When the filter is used in the frontend, only its name and value arguments are sent to the backend via the API,
+     * When the filter is used in the frontend, only its name is sent to the backend via the API,
      * where the filter gets translated and applied in a safe manner.
      *
      * @template entityType The entity type for the filter.
-     * @template argsType The type of the argument for the filter.
-     * @param {function(argsType, Remult): EntityFilter<entityType>} rawFilterTranslator A function that takes an argument of type `argsType` and an instance of `Remult`, and returns an `EntityFilter`.
+     * @param {function(): EntityFilter<entityType>} translator A function that returns an `EntityFilter`.
      * @param {string} [key] An optional unique identifier for the custom filter.
-     * @returns {function(argsType): EntityFilter<entityType>} A function that takes an argument of type `argsType` and returns an `EntityFilter` of type `entityType`.
+     * @returns {function(): EntityFilter<entityType>} A function that returns an `EntityFilter` of type `entityType`.
      *
      * @example
-     * // In an entity class, add a static method for the custom filter with parameters
-     * static filterCity = Filter.createCustom<Order, { city: string }>(
-     *   async ({ city }) => {
-     *     const orders = await dbNamesOf(Order);
-     *     const customers = await dbNamesOf(Customer);
-     *     return SqlDatabase.rawFilter(async (whereFragment) => {
-     *       whereFragment.sql = `${orders.customer} in
-     *              (select ${customers.id}
-     *                 from ${customers}
-     *                where ${await whereFragment.filterToRaw(Customer, { city })})`;
-     *     });
-     *   }
-     * );
-     *
+     *  class Order {
+     *  //...
+     *  static activeOrdersFor = Filter.createCustom<Order, { year: number }>(
+     *    async ({ year }) => {
+     *      return {
+     *        status: ['created', 'confirmed', 'pending', 'blocked', 'delayed'],
+     *        createdAt: {
+     *          $gte: new Date(year, 0, 1),
+     *          $lt: new Date(year + 1, 0, 1),
+     *        },
+     *      }
+     *    },
+     *  )
+     *}
      * // Usage
-     * const cityFilter = Order.filterCity({ city: 'New York' });
-     * const ordersInNewYork = await remult.repo(Order).find({ where: cityFilter });
-     *
-     * // The filter is sent to the backend as:
-     * // http://127.0.0.1:3002/api/orders?%24custom%24filterCity=%7B%22city%22%3A%22New%20York%22%7D
+     * await repo(Order).find({
+     *  where: Order.activeOrders({ year }),
+     *})
+  
+     
      * @see
      * [Sql filter and Custom filter](/docs/custom-filter.html)
      * [Filtering and Relations](/docs/filtering-and-relations.html)
      */
-    static createCustom<entityType, argsType>(rawFilterTranslator: (args: argsType, r: Remult) => EntityFilter<entityType> | Promise<EntityFilter<entityType>>, key?: string): ((y: argsType) => EntityFilter<entityType>) & customFilterInfo<entityType>;
+    static createCustom<entityType, argsType>(translator: (args: argsType, r: Remult) => EntityFilter<entityType> | Promise<EntityFilter<entityType>>, key?: string): ((y: argsType) => EntityFilter<entityType>) & customFilterInfo<entityType>;
     /**
      * Translates an `EntityFilter` to a plain JSON object that can be stored or transported.
      *
@@ -135,6 +181,7 @@ export declare class Filter {
      * @returns {Promise<EntityFilter<entityType>>} The resolved entity filter.
      */
     static resolve<entityType>(filter: EntityFilter<entityType> | (() => EntityFilter<entityType> | Promise<EntityFilter<entityType>>)): Promise<EntityFilter<entityType>>;
+    toJson(): any;
 }
 export interface FilterConsumer {
     or(orElements: Filter[]): any;
@@ -194,3 +241,23 @@ export interface customFilterInfo<entityType> {
     };
 }
 export declare function __updateEntityBasedOnWhere<T>(entityDefs: EntityMetadata<T>, where: EntityFilter<T>, r: T): void;
+/**
+ * A mapping of property names to arrays of precise values for those properties.
+ * @example
+ * const preciseValues = await getPreciseValues(meta, {
+ *   status: { $ne: 'active' },
+ *   $or: [
+ *     { customerId: ["1", "2"] },
+ *     { customerId: "3" }
+ *   ]
+ * });
+ * console.log(preciseValues);
+ * // Output:
+ * // {
+ * //   "customerId": ["1", "2", "3"], // Precise values inferred from the filter
+ * //   "status": undefined,           // Cannot infer precise values for 'status'
+ * // }
+ */
+export type FilterPreciseValues<entityType> = {
+    [Properties in keyof MembersOnly<entityType>]?: Partial<entityType[Properties]>[];
+};