@rebasepro/common 0.7.0 → 0.8.0

package/dist/util/builders.d.ts

@@ -1,4 +1,4 @@
-import { AdditionalFieldDelegate, ArrayProperty, BooleanProperty, DateProperty, EntityCallbacks, EntityCollection, EnumValueConfig, EnumValues, GeopointProperty, MapProperty, NumberProperty, Properties, Property, ReferenceProperty, StringProperty, User } from "@rebasepro/types";
+import { AdditionalFieldDelegate, ArrayProperty, BooleanProperty, DateProperty, EntityCallbacks, EntityCollection, EnumValueConfig, EnumValues, FirebaseCollection, FirebaseProperties, GeopointProperty, InferEntityType, MapProperty, MongoDBCollection, MongoProperties, NumberProperty, PostgresCollection, PostgresProperties, Properties, Property, ReferenceProperty, StringProperty, User } from "@rebasepro/types";
 /**
  * Identity function we use to defeat the type system of Typescript and build
  * collection views with all its properties
@@ -6,6 +6,53 @@ import { AdditionalFieldDelegate, ArrayProperty, BooleanProperty, DateProperty,
  * @group Builder
  */
 export declare function buildCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(collection: EntityCollection<M, USER>): EntityCollection<M, USER>;
+/**
+ * Define a PostgreSQL-backed collection with full type inference.
+ *
+ * The `const P` generic captures literal property types from your
+ * `properties` object, which enables autocomplete on `titleProperty`,
+ * `sort`, `propertiesOrder`, `fixedFilter`, and entity callbacks.
+ *
+ * @example
+ * ```ts
+ * const products = defineCollection({
+ *     name: "Products",
+ *     slug: "products",
+ *     table: "products",
+ *     properties: {
+ *         name: { name: "Name", type: "string", validation: { required: true } },
+ *         price: { name: "Price", type: "number" },
+ *     },
+ *     titleProperty: "name",  // ✅ autocomplete: "name" | "price"
+ *     sort: ["price", "asc"], // ✅ autocomplete on first element
+ * });
+ * ```
+ *
+ * @group Builder
+ */
+export declare function defineCollection<const P extends PostgresProperties, USER extends User = User>(collection: Omit<PostgresCollection<InferEntityType<P>, USER>, "properties"> & {
+    properties: P;
+}): PostgresCollection<InferEntityType<P>, USER> & {
+    properties: P;
+};
+/**
+ * Define a Firestore-backed collection with full type inference.
+ * @group Builder
+ */
+export declare function defineCollection<const P extends FirebaseProperties, USER extends User = User>(collection: Omit<FirebaseCollection<InferEntityType<P>, USER>, "properties"> & {
+    properties: P;
+}): FirebaseCollection<InferEntityType<P>, USER> & {
+    properties: P;
+};
+/**
+ * Define a MongoDB-backed collection with full type inference.
+ * @group Builder
+ */
+export declare function defineCollection<const P extends MongoProperties, USER extends User = User>(collection: Omit<MongoDBCollection<InferEntityType<P>, USER>, "properties"> & {
+    properties: P;
+}): MongoDBCollection<InferEntityType<P>, USER> & {
+    properties: P;
+};
 /**
  * Identity function we use to defeat the type system of Typescript and preserve
  * the property keys.

package/dist/util/callbacks.d.ts

@@ -1,4 +1,9 @@
-import { EntityCallbacks, Properties } from "@rebasepro/types";
+import { EntityCallbacks, Properties, RebaseCallContext } from "@rebasepro/types";
+/**
+ * Context passed to entity lifecycle callbacks.
+ * @group Models
+ */
+export type EntityCallbackContext = RebaseCallContext;
 /**
  * Helper function to extract field-level PropertyCallbacks from a properties schema
  * and wrap them into an EntityCallbacks object recursively.

package/dist/util/index.d.ts

@@ -4,6 +4,7 @@ export * from "./entities";
 export * from "./enums";
 export * from "./paths";
 export * from "./resolutions";
+export * from "./policy";
 export * from "./permissions";
 export * from "./references";
 export * from "./navigation_from_path";

package/dist/util/permissions.d.ts

@@ -1,4 +1,4 @@
-import { Entity, EntityCollection, User } from "@rebasepro/types";
+import { Entity, EntityCollection, SecurityOperation, User } from "@rebasepro/types";
 /**
  * Minimal auth context for permission checking.
  * Only requires the user object — avoids forcing callers to construct
@@ -7,7 +7,31 @@ import { Entity, EntityCollection, User } from "@rebasepro/types";
 export interface AuthContext<USER extends User = User> {
     user: USER | null;
 }
-export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, entity: Entity<M> | null, targetOperation: "select" | "insert" | "update" | "delete"): boolean;
+/**
+ * How to resolve a policy result that cannot be decided client-side (a raw-SQL
+ * escape-hatch rule, or a row-column reference with no row in hand).
+ *
+ * - `"allow"` (default): optimistic — used for admin-UI gating, where Postgres
+ *   remains the authoritative gate and hiding a working action is worse than
+ *   showing one the server may reject.
+ * - `"deny"`: fail-closed — used by real enforcement callers (e.g. a driver
+ *   applying policies in-process), so an undecidable rule never silently allows.
+ */
+export type UnknownResolution = "allow" | "deny";
+export interface CheckOperationOptions {
+    onUnknown?: UnknownResolution;
+}
+/**
+ * Decide whether an operation is permitted for a user on a (possibly null) row,
+ * by evaluating the collection's security rules with the shared policy model —
+ * the same model compiled to Postgres RLS DDL, so the decision matches database
+ * enforcement for every non-raw rule.
+ *
+ * @param options.onUnknown how to treat rules that cannot be decided
+ *   client-side (raw SQL, or row predicates with no row). Defaults to `"allow"`
+ *   for optimistic UI gating; enforcement callers should pass `"deny"`.
+ */
+export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, entity: Entity<M> | null, targetOperation: SecurityOperation, options?: CheckOperationOptions): boolean;
 export declare function canReadCollection<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>): boolean;
 export declare function canEditEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;
 export declare function canCreateEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;

package/dist/util/policy/evaluatePolicy.d.ts

@@ -0,0 +1,31 @@
+import { Entity, PolicyExpression } from "@rebasepro/types";
+/**
+ * Result of evaluating a policy client-side. `"unknown"` means the expression
+ * could not be decided without more information — either a raw-SQL escape-hatch
+ * node (which the client deliberately never guesses) or a row-column reference
+ * with no entity in hand (e.g. list-level gating). Callers decide how to resolve
+ * `"unknown"`: fail-closed for an enforcement decision, optimistic for pure
+ * visibility gating.
+ */
+export type TriState = boolean | "unknown";
+/**
+ * Context for {@link evaluatePolicy}: the acting user (or none) and the row
+ * being evaluated (or none, for collection-level gating).
+ */
+export interface PolicyEvalContext {
+    /** The current user's id, or null/undefined when unauthenticated. */
+    uid?: string | null;
+    /** The current user's application roles. */
+    roles?: string[];
+    /** The row being evaluated, or null when no specific row is available. */
+    entity: Entity | null;
+}
+/**
+ * Evaluates a {@link PolicyExpression} against a user + row, using three-valued
+ * (Kleene) logic so that `"unknown"` sub-results propagate soundly.
+ *
+ * This is the JavaScript twin of {@link policyToPostgres}: both derive from the
+ * same expression, so the admin UI matches database enforcement by construction
+ * for every non-raw rule.
+ */
+export declare function evaluatePolicy(expr: PolicyExpression, ctx: PolicyEvalContext): TriState;

package/dist/util/policy/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./securityRuleToConditions";
+export * from "./policyToPostgres";
+export * from "./evaluatePolicy";

package/dist/util/policy/policyToPostgres.d.ts

@@ -0,0 +1,10 @@
+import { EntityCollection, PolicyExpression } from "@rebasepro/types";
+/**
+ * Compiles a {@link PolicyExpression} to a PostgreSQL boolean SQL string,
+ * suitable for a `USING (...)` / `WITH CHECK (...)` clause.
+ *
+ * This is one of the two consumers of the shared policy model (the other being
+ * {@link evaluatePolicy}); the Postgres schema generators call it so that DDL
+ * and the admin UI derive from the exact same expression.
+ */
+export declare function policyToPostgres(expr: PolicyExpression, collection?: EntityCollection): string;

package/dist/util/policy/securityRuleToConditions.d.ts

@@ -0,0 +1,24 @@
+import { PolicyExpression, SecurityRule } from "@rebasepro/types";
+/**
+ * The normalized `USING` / `WITH CHECK` conditions for a single security rule,
+ * expressed in the engine-agnostic {@link PolicyExpression} model.
+ *
+ * A `null` clause means "this rule contributes no condition for that clause";
+ * consumers apply the default (Postgres denies with `false`).
+ */
+export interface RuleConditions {
+    usingExpr: PolicyExpression | null;
+    withCheckExpr: PolicyExpression | null;
+}
+/**
+ * Desugars a {@link SecurityRule} — its `access`/`ownerField`/`roles` shortcuts,
+ * structured `condition`/`check`, and raw `using`/`withCheck` — into a single
+ * normalized {@link PolicyExpression} pair.
+ *
+ * **This is the linchpin against drift:** both the Postgres DDL generators and
+ * the client-side evaluator consume this one function, so there is exactly one
+ * definition of what a rule means. In particular, application `roles` are folded
+ * into the expression here (AND'd with the base condition, matching how Postgres
+ * generates the clause) rather than being handled separately by each consumer.
+ */
+export declare function securityRuleToConditions(rule: SecurityRule): RuleConditions;

package/dist/util/policy/sqlToPolicy.d.ts

@@ -0,0 +1,20 @@
+import { PolicyExpression } from "@rebasepro/types";
+/**
+ * A tiny, regex-based SQL "parser" for security rules.
+ *
+ * This is NOT a full SQL parser. It is designed to handle the subset of SQL
+ * commonly used in `USING` and `WITH CHECK` clauses, enough to drive the
+ * optimistic client-side UI decision.
+ *
+ * It handles:
+ * - `field = 'literal'`
+ * - `field != 'literal'`
+ * - `field = current_setting('app.user_id')`
+ * - `A AND B`
+ * - `true`
+ * - `IN (...)` (as optimistic true)
+ *
+ * For anything it doesn't understand, it returns a `raw` expression, which
+ * the evaluator treats as "unknown" (and usually optimistic true).
+ */
+export declare function sqlToPolicy(sql: string): PolicyExpression;

package/dist/util/storage.d.ts

@@ -1,4 +1,29 @@
-import { ArrayProperty, EntityValues, StorageConfig, StringProperty, UploadedFileContext } from "@rebasepro/types";
+import { ArrayProperty, EntityValues, StorageConfig, StorageSource, StorageSourceRegistry, StringProperty, UploadedFileContext } from "@rebasepro/types";
+/**
+ * Resolve the {@link StorageSource} to use for a property, given the key
+ * referenced by `StorageConfig.storageSource`.
+ *
+ * Resolution priority:
+ * 1. No `sourceKey` → the default source (backward compatible).
+ * 2. An explicit {@link StorageSourceRegistry} (e.g. `client.storageRegistry`).
+ * 3. A `sources` lookup map (e.g. the `StorageSourcesContext`).
+ * 4. Fall back to the default source.
+ *
+ * Shared by the upload hook, the markdown editor, and the read-only previews
+ * so the resolution logic lives in one place.
+ *
+ * @group Storage
+ */
+export declare function resolveStorageSource(params: {
+    /** Key from `StorageConfig.storageSource`. */
+    sourceKey?: string | null;
+    /** Built sources keyed by storage-source key (e.g. from context). */
+    sources?: Record<string, StorageSource>;
+    /** Optional explicit registry — takes precedence over `sources`. */
+    registry?: StorageSourceRegistry;
+    /** Default source, used when no key is set or the key cannot be resolved. */
+    defaultSource: StorageSource;
+}): StorageSource;
 interface ResolveFilenameStringParams<M extends Record<string, unknown>> {
     input: string | ((context: UploadedFileContext) => (Promise<string> | string));
     storage: StorageConfig;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/common",
   "type": "module",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Awesome Firebase/Firestore-based headless open-source CMS",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -29,14 +29,6 @@
     "headless cms",
     "content manager"
   ],
-  "scripts": {
-    "watch": "vite build --watch",
-    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
-    "test:lint": "eslint \"src/**\" --quiet",
-    "test": "jest --passWithNoTests",
-    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f",
-    "generateIcons": "ts-node --esm src/icons/generateIcons.ts"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -47,10 +39,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/types": "workspace:*",
-    "@rebasepro/utils": "workspace:*",
     "fast-equals": "6.0.0",
-    "json-logic-js": "^2.0.5"
+    "json-logic-js": "^2.0.5",
+    "@rebasepro/utils": "0.8.0",
+    "@rebasepro/types": "0.8.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
@@ -105,5 +97,13 @@
       "^@rebasepro/types$": "<rootDir>/../types/src/index.ts",
       "^@rebasepro/utils$": "<rootDir>/../utils/src/index.ts"
     }
+  },
+  "scripts": {
+    "watch": "vite build --watch",
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
+    "test:lint": "eslint \"src/**\" --quiet",
+    "test": "jest --passWithNoTests",
+    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f",
+    "generateIcons": "ts-node --esm src/icons/generateIcons.ts"
   }
-}
+}

package/src/collections/CollectionRegistry.ts

@@ -1,31 +1,61 @@
 import {
     ArrayProperty,
-    CollectionWithRelations,
-    CollectionWithSubcollections,
+    EntityCallbacks,
+    EngineProperties,
     EntityCollection,
+    getDataSourceCapabilities,
+    getDeclaredSubcollections,
     NumberProperty,
     Properties,
     Property,
     Relation,
     RelationProperty,
-    StringProperty,
-    getDataSourceCapabilities
+    StringProperty
 } from "@rebasepro/types";
 import { deepEqual } from "fast-equals";
 
-import { enumToObjectEntries, getSubcollections, getTableName, resolveCollectionRelations, findRelation, sanitizeRelation } from "../util";
-import { removeFunctions, mergeDeep, deepClone } from "@rebasepro/utils";
-import { resolveDataSource, DataSourceRegistry } from "../data/resolveDataSource";
+import {
+    enumToObjectEntries,
+    findRelation,
+    getSubcollections,
+    getTableName,
+    resolveCollectionRelations,
+    sanitizeRelation
+} from "../util";
+import { deepClone, mergeDeep, removeFunctions } from "@rebasepro/utils";
+import { DataSourceRegistry, resolveDataSource } from "../data/resolveDataSource";
 
 export class CollectionRegistry {
 
     /**
      * Declared data sources, used during normalization to resolve each
      * collection's engine (so `dataSource`-only collections get the right
-     * capabilities). Empty by default → behaviour keys off `driver` as before.
+     * capabilities). Empty by default.
      */
     private dataSources: DataSourceRegistry = {};
 
+    /**
+     * Global lifecycle callbacks applied to every collection.
+     * Runs on all data paths (REST, WebSocket, `rebase.data`).
+     * Execution order: global → collection → property callbacks.
+     */
+    private _globalCallbacks?: EntityCallbacks;
+
+    /**
+     * Set global lifecycle callbacks that apply to every collection.
+     * Typically called once during backend initialization.
+     */
+    setGlobalCallbacks(callbacks: EntityCallbacks): void {
+        this._globalCallbacks = callbacks;
+    }
+
+    /**
+     * Get the currently registered global callbacks, if any.
+     */
+    getGlobalCallbacks(): EntityCallbacks | undefined {
+        return this._globalCallbacks;
+    }
+
     // Normalized runtime layer (used by Data Grid / UI)
     private collectionsByTableName = new Map<string, EntityCollection>();
     private collectionsBySlug = new Map<string, EntityCollection>();
@@ -183,25 +213,24 @@ export class CollectionRegistry {
         // and for preventing mutation of module-level collection singletons.
         const result = { ...collection } as EntityCollection;
 
-        // 0. For `dataSource`-only collections (no explicit `driver`), resolve
-        //    the engine from the data-source registry and stamp it as `driver`
-        //    on the normalized copy, so downstream capability lookups (which
-        //    read `driver`) are correct. Surgical on purpose: collections that
-        //    already set `driver`, and plain default collections (no driver,
-        //    no dataSource), are left untouched. Only the normalized layer is
-        //    affected — the raw layer used by the collection editor keeps the
-        //    author's original fields.
-        if (result.dataSource && !result.driver) {
-            const engine = resolveDataSource(result, this.dataSources).engine;
-            if (engine) (result as { driver?: string }).driver = engine;
+        // 0. Resolve and stamp `dataSource` and `engine` on the normalized copy.
+        //    After this block every normalized collection has both fields set,
+        //    so downstream code can read them directly without calling
+        //    `resolveDataSource()`.  Only the normalized layer is affected —
+        //    the raw layer used by the collection editor keeps the author's
+        //    original fields.
+        {
+            const resolved = resolveDataSource(result, this.dataSources);
+            if (!result.dataSource) (result as { dataSource?: string }).dataSource = resolved.key;
+            if (!result.engine) (result as { engine?: string }).engine = resolved.engine;
         }
 
         // 1. Extract relations from properties that have inline config (target set)
         const extractedRelations = this.extractRelationsFromProperties(result.properties);
 
         // 2. Merge with manual relations[] (manual entries win on name conflict)
-        const relResult = result as CollectionWithRelations;
-        const manualRelations = getDataSourceCapabilities(result.driver).supportsRelations ? (relResult.relations ?? []) : [];
+        const relResult = result;
+        const manualRelations = getDataSourceCapabilities(result.engine).supportsRelations ? (relResult.relations ?? []) : [];
         const mergedRelationsRaw = [...extractedRelations];
         for (const manual of manualRelations) {
             const name = manual.relationName;
@@ -227,7 +256,7 @@ export class CollectionRegistry {
         //     foreignKeyOnTarget, etc.) are populated. Without this the
         //     property.relation stamp is missing junction-table metadata and
         //     the backend cannot fetch many-to-many data.
-        if (getDataSourceCapabilities(result.driver).supportsRelations) {
+        if (getDataSourceCapabilities(result.engine).supportsRelations) {
             mergedRelations = mergedRelationsRaw.map(r => {
                 try {
                     return sanitizeRelation(r, result, (slug) => this.get(slug));
@@ -244,13 +273,15 @@ export class CollectionRegistry {
 
         // 4. Normalize properties (which stamps relation on each property)
         const properties: Properties = this.normalizeProperties(result.properties, mergedRelations);
-        result.properties = properties;
+        result.properties = properties as EngineProperties;
 
         // Populate childCollections from driver-specific fields
         if (!result.childCollections) {
-            if (getDataSourceCapabilities(result.driver).supportsSubcollections && (result as CollectionWithSubcollections).subcollections) {
-                result.childCollections = (result as CollectionWithSubcollections).subcollections;
-            } else if (getDataSourceCapabilities(result.driver).supportsRelations && relResult.relations) {
+            const capabilities = getDataSourceCapabilities(result.engine);
+            const declaredSubcollections = getDeclaredSubcollections(result);
+            if (capabilities.supportsSubcollections && declaredSubcollections) {
+                result.childCollections = declaredSubcollections;
+            } else if (capabilities.supportsRelations && relResult.relations) {
                 const manyRelations = relResult.relations.filter((r: Relation) => r.cardinality === "many");
                 if (manyRelations.length > 0) {
                     result.childCollections = () => manyRelations.map((r: Relation) => {
@@ -411,8 +442,8 @@ export class CollectionRegistry {
             const relationKey = pathSegments[i];
 
             // Get relations for current collection
-            if (!getDataSourceCapabilities(currentCollection.driver).supportsRelations) {
-                throw new Error(`Relation path navigation requires a collection that supports relations, but '${currentCollection.slug}' uses driver '${currentCollection.driver}'`);
+            if (!getDataSourceCapabilities(currentCollection.engine).supportsRelations) {
+                throw new Error(`Relation path navigation requires a collection that supports relations, but '${currentCollection.slug}' uses engine '${currentCollection.engine}'`);
             }
             const resolvedRelations = resolveCollectionRelations(currentCollection);
             const relation = findRelation(resolvedRelations, relationKey);

package/src/collections/default-collections.ts

@@ -1,4 +1,4 @@
-import type { PostgresCollection } from "@rebasepro/types";
+import { defineCollection } from "../util/builders";
 
 /**
  * Default users collection.
@@ -7,7 +7,7 @@ import type { PostgresCollection } from "@rebasepro/types";
  * Slug-based dedup (Map keyed by slug, last-write-wins) lets developers
  * override by defining their own collection with `slug: "users"`.
  */
-export const defaultUsersCollection: PostgresCollection = {
+export const defaultUsersCollection = defineCollection({
     name: "Users",
     singularName: "User",
     slug: "users",
@@ -48,7 +48,7 @@ unique: true }
             name: "Photo URL",
             type: "string",
             columnName: "photo_url",
-            url: "image"
+            ui: { url: "image" }
         },
         roles: {
             name: "Roles",
@@ -120,4 +120,4 @@ disabled: { hidden: true } }
     },
     listProperties: ["displayName", "email", "roles", "createdAt"],
     propertiesOrder: ["id", "email", "displayName", "roles", "createdAt"]
-};
+});

package/src/data/buildRebaseData.ts

@@ -6,128 +6,13 @@ import {
     FindResponse,
     Entity,
     EntityValues,
-    FilterValues,
     WhereFilterOp,
-    WhereFieldValue,
-    WhereFilterOpShort,
     LogicalCondition,
     WhereValue
 } from "@rebasepro/types";
 import { toSnakeCase } from "@rebasepro/utils";
 import { QueryBuilder } from "./query_builder";
-
-/**
- * Convert where-clause filter object to the internal DataDriver FilterValues format.
- *
- * Supports multiple value formats:
- * - PostgREST string: { status: "eq.published", age: "gte.18" }
- * - Equality shorthand: { company_profile_id: null, status: "active", age: 18 }
- * - Tuple syntax: { age: [">=", 18], role: ["in", ["admin", "editor"]] }
- *
- * Internal:  { status: ["==", "published"], age: [">=", 18] }
- */
-function convertWhereToFilter(where?: Record<string, WhereFieldValue>): FilterValues<string> | undefined {
-    if (!where) return undefined;
-
-    const operatorMap: Record<string, WhereFilterOp> = {
-        "eq": "==",
-        "neq": "!=",
-        "gt": ">",
-        "gte": ">=",
-        "lt": "<",
-        "lte": "<=",
-        "in": "in",
-        "nin": "not-in",
-        "not-in": "not-in",
-        "cs": "array-contains",
-        "csa": "array-contains-any",
-        "==": "==",
-"!=": "!=",
-        ">": ">",
-">=": ">=",
-        "<": "<",
-"<=": "<=",
-        "array-contains": "array-contains",
-        "array-contains-any": "array-contains-any"
-    };
-
-    const filter: FilterValues<string> = {};
-
-    for (const [field, rawValue] of Object.entries(where)) {
-        // Handle null → equality
-        if (rawValue === null) {
-            filter[field] = ["==", null];
-            continue;
-        }
-
-        // Handle boolean → equality
-        if (typeof rawValue === "boolean") {
-            filter[field] = ["==", rawValue];
-            continue;
-        }
-
-        // Handle number → equality
-        if (typeof rawValue === "number") {
-            filter[field] = ["==", rawValue];
-            continue;
-        }
-
-        // Handle tuple or array of tuples
-        if (Array.isArray(rawValue)) {
-            const conditions: [WhereFilterOpShort, unknown][] = Array.isArray(rawValue[0])
-                ? (rawValue as [WhereFilterOpShort, unknown][])
-                : [rawValue as [WhereFilterOpShort, unknown]];
-
-            const mappedConditions: [WhereFilterOp, unknown][] = conditions.map(([rawOp, val]) => {
-                const mappedOp = operatorMap[rawOp] ?? "==";
-                return [mappedOp, val];
-            });
-
-            filter[field] = Array.isArray(rawValue[0]) ? mappedConditions : mappedConditions[0];
-            continue;
-        }
-
-        // Handle PostgREST string format: "op.value"
-        if (typeof rawValue === "string") {
-            const dotIndex = rawValue.indexOf(".");
-            if (dotIndex === -1) {
-                // Plain string equality
-                filter[field] = ["==", rawValue];
-                continue;
-            }
-
-            const op = rawValue.substring(0, dotIndex);
-            let value: unknown = rawValue.substring(dotIndex + 1);
-
-            // Parse list values like "(admin,editor)"
-            if (typeof value === "string" && value.startsWith("(") && value.endsWith(")")) {
-                value = value.slice(1, -1).split(",").map((v: string) => v.trim());
-            }
-
-            // Parse null string
-            if (value === "null") {
-                value = null;
-            }
-            // Parse boolean strings
-            else if (value === "true") {
-                value = true;
-            } else if (value === "false") {
-                value = false;
-            }
-            // Try to parse numbers
-            else if (typeof value === "string" && !isNaN(Number(value)) && value.trim() !== "") {
-                value = Number(value);
-            }
-
-            const mappedOp = operatorMap[op];
-            if (mappedOp) {
-                filter[field] = [mappedOp, value];
-            }
-        }
-    }
-
-    return Object.keys(filter).length > 0 ? filter : undefined;
-}
+import { deserializeFilter } from "./filter-dialect";
 
 /**
  * Parse an orderBy string like "created_at:desc" into [field, direction].
@@ -147,11 +32,14 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
     const accessor: CollectionAccessor<M> = {
         async find(params?: FindParams): Promise<FindResponse<M>> {
             const orderParsed = parseOrderBy(params?.orderBy);
+            // Ensure filters are in canonical [op, value] format even if passed as PostgREST strings
+            const filter = params?.where ? deserializeFilter(params.where as any) : undefined;
+            
             const entities = await driver.fetchCollection<M>({
                 path: slug,
                 limit: params?.limit,
                 offset: params?.offset,
-                filter: convertWhereToFilter(params?.where),
+                filter,
                 orderBy: orderParsed?.[0],
                 order: orderParsed?.[1],
                 searchString: params?.searchString
@@ -208,9 +96,10 @@ values: {} as Record<string, unknown> }
 
         count: driver.countEntities
             ? async (params?: FindParams): Promise<number> => {
+                const filter = params?.where ? deserializeFilter(params.where as any) : undefined;
                 return driver.countEntities!({
                     path: slug,
-                    filter: convertWhereToFilter(params?.where)
+                    filter
                 });
             }
             : undefined,
@@ -224,7 +113,7 @@ values: {} as Record<string, unknown> }
                     path: slug,
                     limit: params?.limit,
                     offset: params?.offset,
-                    filter: convertWhereToFilter(params?.where),
+                    filter: params?.where,
                     orderBy: orderParsed?.[0],
                     order: orderParsed?.[1],
                     searchString: params?.searchString,
@@ -254,7 +143,7 @@ values: {} as Record<string, unknown> }
             } : undefined,
 
         // Fluent Query Builder
-        where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOpShort, value?: unknown) {
+        where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown) {
             const builder = new QueryBuilder<M>(accessor);
             if (typeof columnOrCondition === "object") {
                 return builder.where(columnOrCondition);