@rebasepro/common 0.2.1 → 0.2.4

package/dist/index.es.js

@@ -1,5 +1,5 @@
 import { EntityReference, EntityRelation, getDataSourceCapabilities } from "@rebasepro/types";
-import { mergeDeep, getIn as getIn$1, isDefaultFieldConfigId, randomString, toSnakeCase, generateForeignKeyName, removeFunctions, deepClone } from "@rebasepro/utils";
+import { mergeDeep, toSnakeCase, generateForeignKeyName, getIn as getIn$1, isDefaultFieldConfigId, randomString, removeFunctions, deepClone } from "@rebasepro/utils";
 import jsonLogic from "json-logic-js";
 import { deepEqual } from "fast-equals";
 const DEFAULT_ONE_OF_TYPE = "type";
@@ -316,6 +316,241 @@ function segmentsToStrippedPath(paths) {
 function fullPathToCollectionSegments(path) {
   return path.split("/").filter((e, i) => i % 2 === 0);
 }
+function sanitizeRelation(relation, sourceCollection, resolveCollection) {
+  if (!relation.target) {
+    throw new Error("Relation is missing a `target` collection.");
+  }
+  const rawTarget = relation.target;
+  let targetCollection;
+  if (typeof rawTarget === "string") {
+    if (resolveCollection) {
+      targetCollection = resolveCollection(rawTarget);
+    }
+    if (!targetCollection) {
+      targetCollection = {
+        slug: rawTarget,
+        name: rawTarget
+      };
+    }
+  } else if (typeof rawTarget === "function") {
+    const evaluated = rawTarget();
+    if (typeof evaluated === "string") {
+      if (resolveCollection) {
+        targetCollection = resolveCollection(evaluated);
+      }
+      if (!targetCollection) {
+        targetCollection = {
+          slug: evaluated,
+          name: evaluated
+        };
+      }
+    } else {
+      targetCollection = evaluated;
+    }
+  } else if (rawTarget && typeof rawTarget === "object") {
+    targetCollection = rawTarget;
+  }
+  if (!targetCollection) {
+    throw new Error("Relation is missing a valid `target` collection.");
+  }
+  const newRelation = {
+    ...relation
+  };
+  newRelation.target = () => {
+    if (typeof rawTarget === "string") {
+      return resolveCollection && resolveCollection(rawTarget) || targetCollection;
+    } else if (typeof rawTarget === "function") {
+      const evaluated = rawTarget();
+      if (typeof evaluated === "string") {
+        return resolveCollection && resolveCollection(evaluated) || targetCollection;
+      }
+      return evaluated;
+    }
+    return targetCollection;
+  };
+  if (!newRelation.relationName) {
+    newRelation.relationName = toSnakeCase(targetCollection.slug);
+  }
+  if (!newRelation.direction) {
+    if (newRelation.foreignKeyOnTarget) newRelation.direction = "inverse";
+    else if (newRelation.through) newRelation.direction = "owning";
+    else if (newRelation.cardinality === "many") newRelation.direction = "inverse";
+    else newRelation.direction = "owning";
+  }
+  if (!newRelation.joinPath) {
+    const sourceName = toSnakeCase(sourceCollection.slug ?? sourceCollection.name);
+    if (newRelation.cardinality === "one" && newRelation.direction === "owning") {
+      if (!newRelation.localKey) {
+        newRelation.localKey = generateForeignKeyName(newRelation.relationName);
+      }
+    } else if (newRelation.cardinality === "one" && newRelation.direction === "inverse") {
+      if (!newRelation.foreignKeyOnTarget) {
+        let foundForeignKey = false;
+        try {
+          const targetRelations = getDataSourceCapabilities(targetCollection.driver).supportsRelations ? targetCollection.relations || [] : [];
+          for (const targetRel of targetRelations) {
+            if (targetRel.direction === "owning" && targetRel.cardinality === "one" && targetRel.localKey) {
+              try {
+                const targetRelTarget = targetRel.target();
+                if (targetRelTarget.slug === sourceCollection.slug) {
+                  newRelation.foreignKeyOnTarget = targetRel.localKey;
+                  foundForeignKey = true;
+                  break;
+                }
+              } catch (e) {
+                continue;
+              }
+            }
+          }
+        } catch (e) {
+        }
+        if (!foundForeignKey) {
+          const keyPrefix = newRelation.inverseRelationName ? toSnakeCase(newRelation.inverseRelationName) : sourceName;
+          newRelation.foreignKeyOnTarget = generateForeignKeyName(keyPrefix);
+        }
+      }
+    } else if (newRelation.cardinality === "many" && newRelation.direction === "inverse") {
+      let isManyToManyInverse = false;
+      if (newRelation.inverseRelationName && !newRelation.foreignKeyOnTarget) {
+        try {
+          const targetRelations = getDataSourceCapabilities(targetCollection.driver).supportsRelations ? targetCollection.relations || [] : [];
+          for (const targetRel of targetRelations) {
+            if (targetRel.cardinality === "many" && (targetRel.direction === "owning" || !targetRel.direction) && targetRel.relationName === newRelation.inverseRelationName) {
+              isManyToManyInverse = true;
+              break;
+            }
+          }
+          if (!isManyToManyInverse && targetCollection.properties) {
+            for (const [propKey, prop] of Object.entries(targetCollection.properties)) {
+              if (prop.type !== "relation") continue;
+              const relProp = prop;
+              const relName = relProp.relationName || propKey;
+              if (relName === newRelation.inverseRelationName && relProp.cardinality === "many" && (relProp.direction === "owning" || !relProp.direction)) {
+                isManyToManyInverse = true;
+                break;
+              }
+            }
+          }
+        } catch (e) {
+        }
+      }
+      if (!isManyToManyInverse && !newRelation.foreignKeyOnTarget) {
+        newRelation.foreignKeyOnTarget = generateForeignKeyName(sourceName);
+      }
+    } else if (newRelation.cardinality === "many" && newRelation.direction === "owning") {
+      const sourceTableName = getTableName(sourceCollection);
+      const targetTableName = getTableName(targetCollection);
+      newRelation.through = {
+        table: newRelation.through?.table ?? [sourceTableName, targetTableName].sort().join("_"),
+        sourceColumn: newRelation.through?.sourceColumn ?? generateForeignKeyName(sourceName),
+        targetColumn: newRelation.through?.targetColumn ?? generateForeignKeyName(newRelation.relationName)
+      };
+    }
+  }
+  if (newRelation.cardinality === "one" && newRelation.direction === "owning" && !newRelation.localKey && !newRelation.joinPath) {
+    throw new Error(`Configuration Error in relation from '${sourceCollection.name}': An 'owning' one-to-one relation requires a 'localKey'. Check the relation config for '${newRelation.relationName}'`);
+  }
+  if (newRelation.cardinality === "one" && newRelation.direction === "inverse" && !newRelation.foreignKeyOnTarget && !newRelation.joinPath) {
+    throw new Error(`Configuration Error in relation from '${sourceCollection.name}': An 'inverse' one-to-one relation requires a 'foreignKeyOnTarget'. Check the relation config for '${newRelation.relationName}'`);
+  }
+  if (newRelation.cardinality === "many" && newRelation.direction === "inverse" && !newRelation.foreignKeyOnTarget && !newRelation.joinPath && !newRelation.inverseRelationName) {
+    throw new Error(`Configuration Error in relation from '${sourceCollection.name}': An 'inverse' one-to-many relation requires a 'foreignKeyOnTarget'. Check the relation config for '${newRelation.relationName}'`);
+  }
+  return newRelation;
+}
+const _resolvedRelationsCache = /* @__PURE__ */ new WeakMap();
+function resolveCollectionRelations(collection) {
+  const cached = _resolvedRelationsCache.get(collection);
+  if (cached) return cached;
+  if (!getDataSourceCapabilities(collection.driver).supportsRelations) return {};
+  const relCollection = collection;
+  const relations = {};
+  const registeredRelationNames = /* @__PURE__ */ new Set();
+  if (relCollection.relations) {
+    relCollection.relations.forEach((relation) => {
+      try {
+        const normalizedRelation = sanitizeRelation(relation, collection);
+        const relationKey = normalizedRelation.relationName;
+        if (relationKey) {
+          relations[relationKey] = normalizedRelation;
+          registeredRelationNames.add(relationKey);
+        }
+      } catch (e) {
+      }
+    });
+  }
+  if (collection.properties) {
+    Object.entries(collection.properties).forEach(([propKey, prop]) => {
+      const relation = resolvePropertyRelation({
+        propertyKey: propKey,
+        property: prop,
+        sourceCollection: collection
+      });
+      if (relation) {
+        if (relations[propKey]) return;
+        if (!relation.relationName) {
+          relation.relationName = propKey;
+        }
+        const normalizedRelation = sanitizeRelation(relation, collection);
+        relations[propKey] = normalizedRelation;
+        registeredRelationNames.add(normalizedRelation.relationName ?? propKey);
+      }
+    });
+  }
+  _resolvedRelationsCache.set(collection, relations);
+  return relations;
+}
+function resolvePropertyRelation({
+  propertyKey,
+  property,
+  sourceCollection
+}) {
+  if (property.type !== "relation") return void 0;
+  const relProp = property;
+  if (relProp.target) {
+    return {
+      relationName: relProp.relationName || propertyKey,
+      target: relProp.target,
+      cardinality: relProp.cardinality || "one",
+      direction: relProp.direction || "owning",
+      inverseRelationName: relProp.inverseRelationName,
+      localKey: relProp.localKey,
+      foreignKeyOnTarget: relProp.foreignKeyOnTarget,
+      through: relProp.through,
+      joinPath: relProp.joinPath,
+      onUpdate: relProp.onUpdate,
+      onDelete: relProp.onDelete,
+      overrides: relProp.overrides
+    };
+  }
+  console.warn(`Unrecognized or missing relation target for property '${propertyKey}' in collection '${sourceCollection.slug}'`);
+  return void 0;
+}
+function getTableName(collection) {
+  if (getDataSourceCapabilities(collection.driver).supportsRelations) {
+    return collection.table ?? toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
+  }
+  return toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
+}
+function getTableVarName(tableName) {
+  return tableName.replace(/_([a-z])/g, (_, char) => char.toUpperCase());
+}
+function getEnumVarName(tableName, propName) {
+  const tableVar = getTableVarName(tableName);
+  const propVar = propName.charAt(0).toUpperCase() + propName.slice(1);
+  return `${tableVar}${propVar}`;
+}
+function getColumnName(fullColumn) {
+  return fullColumn.includes(".") ? fullColumn.split(".").pop() : fullColumn;
+}
+function findRelation(resolvedRelations, key) {
+  if (resolvedRelations[key]) return resolvedRelations[key];
+  const slugKey = key.replace(/_/g, "-");
+  if (slugKey !== key && resolvedRelations[slugKey]) return resolvedRelations[slugKey];
+  const snakeKey = key.replace(/-/g, "_");
+  if (snakeKey !== key && resolvedRelations[snakeKey]) return resolvedRelations[snakeKey];
+  return void 0;
+}
 function resolveProperty(props) {
   const {
     property,
@@ -545,8 +780,9 @@ function getSubcollections(collection) {
   if (getDataSourceCapabilities(collection.driver).supportsSubcollections && collection.subcollections) {
     return collection.subcollections() ?? [];
   }
-  if (getDataSourceCapabilities(collection.driver).supportsRelations && collection.relations) {
-    const manyRelations = collection.relations.filter((r) => r.cardinality === "many");
+  if (getDataSourceCapabilities(collection.driver).supportsRelations) {
+    const resolvedRelations = resolveCollectionRelations(collection);
+    const manyRelations = Object.values(resolvedRelations).filter((r) => r.cardinality === "many");
     return manyRelations.map((r) => {
       const target = r.target();
       if (!target) return void 0;
@@ -1174,240 +1410,6 @@ const buildPropertyCallbacks = (properties) => {
   }
   return Object.keys(propertyCallbacks).length > 0 ? propertyCallbacks : void 0;
 };
-function sanitizeRelation(relation, sourceCollection, resolveCollection) {
-  if (!relation.target) {
-    throw new Error("Relation is missing a `target` collection.");
-  }
-  const rawTarget = relation.target;
-  let targetCollection;
-  if (typeof rawTarget === "string") {
-    if (resolveCollection) {
-      targetCollection = resolveCollection(rawTarget);
-    }
-    if (!targetCollection) {
-      targetCollection = {
-        slug: rawTarget,
-        name: rawTarget
-      };
-    }
-  } else if (typeof rawTarget === "function") {
-    const evaluated = rawTarget();
-    if (typeof evaluated === "string") {
-      if (resolveCollection) {
-        targetCollection = resolveCollection(evaluated);
-      }
-      if (!targetCollection) {
-        targetCollection = {
-          slug: evaluated,
-          name: evaluated
-        };
-      }
-    } else {
-      targetCollection = evaluated;
-    }
-  }
-  if (!targetCollection) {
-    throw new Error("Relation is missing a valid `target` collection.");
-  }
-  const newRelation = {
-    ...relation
-  };
-  newRelation.target = () => {
-    if (typeof rawTarget === "string") {
-      return resolveCollection && resolveCollection(rawTarget) || targetCollection;
-    } else if (typeof rawTarget === "function") {
-      const evaluated = rawTarget();
-      if (typeof evaluated === "string") {
-        return resolveCollection && resolveCollection(evaluated) || targetCollection;
-      }
-      return evaluated;
-    }
-    return targetCollection;
-  };
-  if (!newRelation.relationName) {
-    newRelation.relationName = toSnakeCase(targetCollection.slug);
-  }
-  if (!newRelation.direction) {
-    if (newRelation.foreignKeyOnTarget) newRelation.direction = "inverse";
-    else if (newRelation.through) newRelation.direction = "owning";
-    else if (newRelation.cardinality === "many") newRelation.direction = "inverse";
-    else newRelation.direction = "owning";
-  }
-  if (!newRelation.joinPath) {
-    const sourceName = toSnakeCase(sourceCollection.slug ?? sourceCollection.name);
-    if (newRelation.cardinality === "one" && newRelation.direction === "owning") {
-      if (!newRelation.localKey) {
-        newRelation.localKey = generateForeignKeyName(newRelation.relationName);
-      }
-    } else if (newRelation.cardinality === "one" && newRelation.direction === "inverse") {
-      if (!newRelation.foreignKeyOnTarget) {
-        let foundForeignKey = false;
-        try {
-          const targetRelations = getDataSourceCapabilities(targetCollection.driver).supportsRelations ? targetCollection.relations || [] : [];
-          for (const targetRel of targetRelations) {
-            if (targetRel.direction === "owning" && targetRel.cardinality === "one" && targetRel.localKey) {
-              try {
-                const targetRelTarget = targetRel.target();
-                if (targetRelTarget.slug === sourceCollection.slug) {
-                  newRelation.foreignKeyOnTarget = targetRel.localKey;
-                  foundForeignKey = true;
-                  break;
-                }
-              } catch (e) {
-                continue;
-              }
-            }
-          }
-        } catch (e) {
-        }
-        if (!foundForeignKey) {
-          const keyPrefix = newRelation.inverseRelationName ? toSnakeCase(newRelation.inverseRelationName) : sourceName;
-          newRelation.foreignKeyOnTarget = generateForeignKeyName(keyPrefix);
-        }
-      }
-    } else if (newRelation.cardinality === "many" && newRelation.direction === "inverse") {
-      let isManyToManyInverse = false;
-      if (newRelation.inverseRelationName && !newRelation.foreignKeyOnTarget) {
-        try {
-          const targetRelations = getDataSourceCapabilities(targetCollection.driver).supportsRelations ? targetCollection.relations || [] : [];
-          for (const targetRel of targetRelations) {
-            if (targetRel.cardinality === "many" && (targetRel.direction === "owning" || !targetRel.direction) && targetRel.relationName === newRelation.inverseRelationName) {
-              isManyToManyInverse = true;
-              break;
-            }
-          }
-          if (!isManyToManyInverse && targetCollection.properties) {
-            for (const [propKey, prop] of Object.entries(targetCollection.properties)) {
-              if (prop.type !== "relation") continue;
-              const relProp = prop;
-              const relName = relProp.relationName || propKey;
-              if (relName === newRelation.inverseRelationName && relProp.cardinality === "many" && (relProp.direction === "owning" || !relProp.direction)) {
-                isManyToManyInverse = true;
-                break;
-              }
-            }
-          }
-        } catch (e) {
-        }
-      }
-      if (!isManyToManyInverse && !newRelation.foreignKeyOnTarget) {
-        newRelation.foreignKeyOnTarget = generateForeignKeyName(sourceName);
-      }
-    } else if (newRelation.cardinality === "many" && newRelation.direction === "owning") {
-      const sourceTableName = getTableName(sourceCollection);
-      const targetTableName = getTableName(targetCollection);
-      newRelation.through = {
-        table: newRelation.through?.table ?? [sourceTableName, targetTableName].sort().join("_"),
-        sourceColumn: newRelation.through?.sourceColumn ?? generateForeignKeyName(sourceName),
-        targetColumn: newRelation.through?.targetColumn ?? generateForeignKeyName(newRelation.relationName)
-      };
-    }
-  }
-  if (newRelation.cardinality === "one" && newRelation.direction === "owning" && !newRelation.localKey && !newRelation.joinPath) {
-    throw new Error(`Configuration Error in relation from '${sourceCollection.name}': An 'owning' one-to-one relation requires a 'localKey'. Check the relation config for '${newRelation.relationName}'`);
-  }
-  if (newRelation.cardinality === "one" && newRelation.direction === "inverse" && !newRelation.foreignKeyOnTarget && !newRelation.joinPath) {
-    throw new Error(`Configuration Error in relation from '${sourceCollection.name}': An 'inverse' one-to-one relation requires a 'foreignKeyOnTarget'. Check the relation config for '${newRelation.relationName}'`);
-  }
-  if (newRelation.cardinality === "many" && newRelation.direction === "inverse" && !newRelation.foreignKeyOnTarget && !newRelation.joinPath && !newRelation.inverseRelationName) {
-    throw new Error(`Configuration Error in relation from '${sourceCollection.name}': An 'inverse' one-to-many relation requires a 'foreignKeyOnTarget'. Check the relation config for '${newRelation.relationName}'`);
-  }
-  return newRelation;
-}
-const _resolvedRelationsCache = /* @__PURE__ */ new WeakMap();
-function resolveCollectionRelations(collection) {
-  const cached = _resolvedRelationsCache.get(collection);
-  if (cached) return cached;
-  if (!getDataSourceCapabilities(collection.driver).supportsRelations) return {};
-  const relCollection = collection;
-  const relations = {};
-  const registeredRelationNames = /* @__PURE__ */ new Set();
-  if (relCollection.relations) {
-    relCollection.relations.forEach((relation) => {
-      const normalizedRelation = sanitizeRelation(relation, collection);
-      const relationKey = normalizedRelation.relationName;
-      if (relationKey) {
-        relations[relationKey] = normalizedRelation;
-        registeredRelationNames.add(relationKey);
-      }
-    });
-  }
-  if (collection.properties) {
-    Object.entries(collection.properties).forEach(([propKey, prop]) => {
-      const relation = resolvePropertyRelation({
-        propertyKey: propKey,
-        property: prop,
-        sourceCollection: collection
-      });
-      if (relation) {
-        if (relations[propKey]) return;
-        if (!relation.relationName) {
-          relation.relationName = propKey;
-        }
-        const normalizedRelation = sanitizeRelation(relation, collection);
-        relations[propKey] = normalizedRelation;
-        registeredRelationNames.add(normalizedRelation.relationName ?? propKey);
-      }
-    });
-  }
-  _resolvedRelationsCache.set(collection, relations);
-  return relations;
-}
-function resolvePropertyRelation({
-  propertyKey,
-  property,
-  sourceCollection
-}) {
-  if (property.type !== "relation") return void 0;
-  const relProp = property;
-  if (relProp.target) {
-    return {
-      relationName: relProp.relationName || propertyKey,
-      target: relProp.target,
-      cardinality: relProp.cardinality || "one",
-      direction: relProp.direction || "owning",
-      inverseRelationName: relProp.inverseRelationName,
-      localKey: relProp.localKey,
-      foreignKeyOnTarget: relProp.foreignKeyOnTarget,
-      through: relProp.through,
-      joinPath: relProp.joinPath,
-      onUpdate: relProp.onUpdate,
-      onDelete: relProp.onDelete,
-      overrides: relProp.overrides
-    };
-  }
-  const relation = (sourceCollection.relations ?? []).find((rel) => rel.relationName === relProp.relationName);
-  if (!relation) {
-    console.warn(`Unrecognized relation format for property '${propertyKey}' in collection '${sourceCollection.slug}'`);
-    return void 0;
-  }
-  return relation;
-}
-function getTableName(collection) {
-  if (getDataSourceCapabilities(collection.driver).supportsRelations) {
-    return collection.table ?? toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
-  }
-  return toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
-}
-function getTableVarName(tableName) {
-  return tableName.replace(/_([a-z])/g, (_, char) => char.toUpperCase());
-}
-function getEnumVarName(tableName, propName) {
-  const tableVar = getTableVarName(tableName);
-  const propVar = propName.charAt(0).toUpperCase() + propName.slice(1);
-  return `${tableVar}${propVar}`;
-}
-function getColumnName(fullColumn) {
-  return fullColumn.includes(".") ? fullColumn.split(".").pop() : fullColumn;
-}
-function findRelation(resolvedRelations, key) {
-  if (resolvedRelations[key]) return resolvedRelations[key];
-  const slugKey = key.replace(/_/g, "-");
-  if (slugKey !== key && resolvedRelations[slugKey]) return resolvedRelations[slugKey];
-  const snakeKey = key.replace(/-/g, "_");
-  if (snakeKey !== key && resolvedRelations[snakeKey]) return resolvedRelations[snakeKey];
-  return void 0;
-}
 function getIn(obj, path) {
   if (!obj || !path) return void 0;
   return path.split(".").reduce((acc, part) => acc && acc[part], obj);
@@ -1730,8 +1732,18 @@ class CollectionRegistry {
     const mergedRelationsRaw = [...extractedRelations];
     for (const manual of manualRelations) {
       const name = manual.relationName;
-      if (!name || !mergedRelationsRaw.find((r) => r.relationName === name)) {
+      if (!name) {
         mergedRelationsRaw.push(manual);
+      } else {
+        const existingIndex = mergedRelationsRaw.findIndex((r) => r.relationName === name);
+        if (existingIndex === -1) {
+          mergedRelationsRaw.push(manual);
+        } else {
+          mergedRelationsRaw[existingIndex] = {
+            ...manual,
+            ...mergedRelationsRaw[existingIndex]
+          };
+        }
       }
     }
     let mergedRelations = mergedRelationsRaw;
@@ -1951,6 +1963,202 @@ class CollectionRegistry {
     };
   }
 }
+const defaultUsersCollection = {
+  name: "Users",
+  singularName: "User",
+  slug: "users",
+  table: "users",
+  schema: "rebase",
+  icon: "Users",
+  group: "Settings",
+  properties: {
+    id: {
+      name: "ID",
+      type: "string",
+      isId: "uuid"
+    },
+    email: {
+      name: "Email",
+      type: "string",
+      validation: {
+        required: true,
+        unique: true
+      }
+    },
+    password_hash: {
+      name: "Password Hash",
+      type: "string",
+      ui: {
+        hideFromCollection: true
+      }
+    },
+    display_name: {
+      name: "Display Name",
+      type: "string"
+    },
+    photo_url: {
+      name: "Photo URL",
+      type: "string"
+    },
+    email_verified: {
+      name: "Email Verified",
+      type: "boolean",
+      defaultValue: false
+    },
+    email_verification_token: {
+      name: "Email Verification Token",
+      type: "string",
+      ui: {
+        hideFromCollection: true
+      }
+    },
+    email_verification_sent_at: {
+      name: "Email Verification Sent At",
+      type: "date",
+      ui: {
+        hideFromCollection: true
+      }
+    },
+    metadata: {
+      name: "Metadata",
+      type: "map",
+      defaultValue: {},
+      ui: {
+        hideFromCollection: true
+      }
+    },
+    created_at: {
+      name: "Created At",
+      type: "date",
+      autoValue: "on_create",
+      ui: {
+        readOnly: true,
+        hideFromCollection: true
+      }
+    },
+    updated_at: {
+      name: "Updated At",
+      type: "date",
+      autoValue: "on_update",
+      ui: {
+        readOnly: true,
+        hideFromCollection: true
+      }
+    }
+  }
+};
+function mapOperator(op) {
+  switch (op) {
+    case "==":
+      return "eq";
+    case "!=":
+      return "neq";
+    case ">":
+      return "gt";
+    case ">=":
+      return "gte";
+    case "<":
+      return "lt";
+    case "<=":
+      return "lte";
+    case "array-contains":
+      return "cs";
+    case "array-contains-any":
+      return "csa";
+    case "not-in":
+      return "nin";
+    default:
+      return op;
+  }
+}
+class QueryBuilder {
+  constructor(collection) {
+    this.collection = collection;
+  }
+  params = {
+    where: {}
+  };
+  /**
+   * Add a filter condition to your query.
+   * @example
+   * client.collection('users').where('age', '>=', 18).find()
+   */
+  where(column, operator, value) {
+    if (!this.params.where) {
+      this.params.where = {};
+    }
+    const mappedOp = mapOperator(operator);
+    let formattedValue = value;
+    if (Array.isArray(value) && ["in", "nin", "cs", "csa"].includes(mappedOp)) {
+      formattedValue = `(${value.join(",")})`;
+    } else if (value === null) {
+      formattedValue = "null";
+    }
+    this.params.where[column] = mappedOp === "eq" ? String(formattedValue) : `${mappedOp}.${formattedValue}`;
+    return this;
+  }
+  /**
+   * Order the results by a specific column.
+   * @example
+   * client.collection('users').orderBy('createdAt', 'desc').find()
+   */
+  orderBy(column, ascending = "asc") {
+    this.params.orderBy = `${column}:${ascending}`;
+    return this;
+  }
+  /**
+   * Limit the number of results returned.
+   */
+  limit(count) {
+    this.params.limit = count;
+    return this;
+  }
+  /**
+   * Skip the first N results.
+   */
+  offset(count) {
+    this.params.offset = count;
+    return this;
+  }
+  /**
+   * Set a free-text search string if supported by the backend.
+   */
+  search(searchString) {
+    this.params.searchString = searchString;
+    return this;
+  }
+  /**
+   * Include related entities in the response.
+   * Relations will be populated with full entity data instead of just IDs.
+   *
+   * @param relations - Relation names to include, or "*" for all.
+   * @example
+   * // Include specific relations
+   * client.data.posts.include("tags", "author").find()
+   *
+   * // Include all relations
+   * client.data.posts.include("*").find()
+   */
+  include(...relations) {
+    this.params.include = relations;
+    return this;
+  }
+  /**
+   * Execute the find query and return the results.
+   */
+  async find() {
+    return this.collection.find(this.params);
+  }
+  /**
+   * Listen to realtime updates matching this query.
+   */
+  listen(onUpdate, onError) {
+    if (!this.collection.listen) {
+      throw new Error("Listen is only available when RebaseClient is configured with a websocketUrl.");
+    }
+    return this.collection.listen(this.params, onUpdate, onError);
+  }
+}
 function convertWhereToFilter(where) {
   if (!where) return void 0;
   const operatorMap = {
@@ -2030,7 +2238,7 @@ function parseOrderBy(orderBy) {
   return [field, direction];
 }
 function createDriverAccessor(driver, slug) {
-  return {
+  const accessor = {
     async find(params) {
       const orderParsed = parseOrderBy(params?.orderBy);
       const entities = await driver.fetchCollection({
@@ -2124,8 +2332,28 @@ function createDriverAccessor(driver, slug) {
         onUpdate: (entity) => onUpdate(entity ?? void 0),
         onError
       });
-    } : void 0
+    } : void 0,
+    // Fluent Query Builder
+    where(column, operator, value) {
+      return new QueryBuilder(accessor).where(column, operator, value);
+    },
+    orderBy(column, ascending) {
+      return new QueryBuilder(accessor).orderBy(column, ascending);
+    },
+    limit(count) {
+      return new QueryBuilder(accessor).limit(count);
+    },
+    offset(count) {
+      return new QueryBuilder(accessor).offset(count);
+    },
+    search(searchString) {
+      return new QueryBuilder(accessor).search(searchString);
+    },
+    include(...relations) {
+      return new QueryBuilder(accessor).include(...relations);
+    }
   };
+  return accessor;
 }
 function buildRebaseData(driver) {
   const cache = /* @__PURE__ */ new Map();
@@ -2155,6 +2383,7 @@ export {
   CollectionRegistry,
   DEFAULT_ONE_OF_TYPE,
   DEFAULT_ONE_OF_VALUE,
+  QueryBuilder,
   addInitialSlash,
   applyPropertyConditions,
   buildAdditionalFieldDelegate,
@@ -2172,8 +2401,10 @@ export {
   canDeleteEntity,
   canEditEntity,
   canReadCollection,
+  checkOperation,
   createRelationRef,
   createRelationRefWithData,
+  defaultUsersCollection,
   enumToObjectEntries,
   evaluateCondition,
   findRelation,