@rebasepro/common 0.7.0 → 0.8.0

package/src/data/filter-dialect.ts

@@ -0,0 +1,318 @@
+/**
+ * REST wire-format adapter for the unified filter system.
+ *
+ * This module is the ONLY code in the entire codebase that knows about
+ * PostgREST-style dot-syntax strings (`eq.active`, `gt.18`, `in.(a,b)`).
+ * Everything else speaks `FilterValues` exclusively.
+ *
+ * @module
+ */
+
+import {
+    WhereFilterOp,
+    FilterValues,
+    CANONICAL_TO_REST,
+    REST_TO_CANONICAL,
+    RestFilterOp,
+    toCanonicalOp,
+    LogicalCondition,
+    FilterCondition
+} from "@rebasepro/types";
+
+// ---------------------------------------------------------------------------
+// Value coercion (querystring → typed JS values)
+// ---------------------------------------------------------------------------
+
+/**
+ * Coerce a raw querystring value to its natural JS type.
+ * - `"true"` / `"false"` → boolean
+ * - `"null"` → null
+ * - Numeric strings → number
+ * - Everything else → string (unchanged)
+ */
+function coerceValue(raw: string): unknown {
+    if (raw === "true") return true;
+    if (raw === "false") return false;
+    if (raw === "null") return null;
+    if (raw !== "" && !isNaN(Number(raw))) return Number(raw);
+    return raw;
+}
+
+/**
+ * Serialize a JS value to its querystring representation.
+ */
+function stringifyValue(value: unknown): string {
+    if (value === null) return "null";
+    if (typeof value === "boolean") return String(value);
+    return String(value);
+}
+
+// ---------------------------------------------------------------------------
+// Serialize: FilterValues → REST querystring
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize a single condition tuple to a PostgREST dot-string.
+ *
+ * @example
+ * serializeTuple(["==", "active"])           // "eq.active"
+ * serializeTuple(["in", ["admin","editor"]]) // "in.(admin,editor)"
+ * serializeTuple([">=", 18])                 // "gte.18"
+ */
+function serializeTuple(tuple: [WhereFilterOp, unknown] | unknown): string {
+    // If it's already a string, it might be a PostgREST string (with dot)
+    // or a raw value (without dot). In both cases, existing tests expect
+    // them to be passed through or treated as simple equality if no dot.
+    if (typeof tuple === "string") {
+        if (tuple.includes(".")) {
+            const dotIndex = tuple.indexOf(".");
+            const prefix = tuple.substring(0, dotIndex);
+            if ((REST_TO_CANONICAL as any)[prefix]) {
+                return tuple;
+            }
+        }
+        return tuple;
+    }
+
+    // If it's NOT a canonical tuple [WhereFilterOp, value], treat as equality.
+    if (!Array.isArray(tuple) || tuple.length !== 2 || typeof tuple[0] !== "string" || !(CANONICAL_TO_REST as any)[tuple[0]]) {
+        return `eq.${stringifyValue(tuple)}`;
+    }
+
+    const [op, value] = tuple as [WhereFilterOp, unknown];
+    const restOp = CANONICAL_TO_REST[op];
+
+    if (Array.isArray(value)) {
+        const items = value.map(stringifyValue).join(",");
+        return `${restOp}.(${items})`;
+    }
+
+    return `${restOp}.${stringifyValue(value)}`;
+}
+
+/**
+ * Convert `FilterValues` to a PostgREST-style querystring record.
+ *
+ * - Single conditions produce a string value.
+ * - Multiple conditions on the same field produce a string array (repeated params).
+ *
+ * @example
+ * serializeFilter({ status: ["==", "active"] })
+ * // → { status: "eq.active" }
+ *
+ * serializeFilter({ age: [[">=", 18], ["<", 65]] })
+ * // → { age: ["gte.18", "lt.65"] }
+ */
+export function serializeFilter(
+    filter: FilterValues<string> | Record<string, any>
+): Record<string, string | string[]> {
+    const result: Record<string, string | string[]> = {};
+
+    for (const [field, condition] of Object.entries(filter)) {
+        if (condition === undefined) continue;
+
+        // Multiple conditions on the same field: array of tuples
+        // We detect this by checking if the first element is also an array.
+        if (Array.isArray(condition) && condition.length > 0 && Array.isArray(condition[0])) {
+            result[field] = (condition as any[]).map(serializeTuple);
+        } else {
+            // Single condition (could be a tuple, a raw value, or an already-serialized string)
+            result[field] = serializeTuple(condition);
+        }
+    }
+
+    return result;
+}
+
+// ---------------------------------------------------------------------------
+// Deserialize: REST querystring → FilterValues
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a single PostgREST dot-string into a `[WhereFilterOp, unknown]` tuple.
+ *
+ * If the string doesn't match a known operator prefix, falls back to
+ * `["==", originalString]` (treating the whole string as an equality value).
+ */
+function deserializeSingle(raw: string): [WhereFilterOp, unknown] {
+    const dotIndex = raw.indexOf(".");
+    if (dotIndex === -1) {
+        // No dot → equality on the raw value (coerced)
+        return ["==", coerceValue(raw)];
+    }
+
+    const prefix = raw.substring(0, dotIndex);
+    const rest = raw.substring(dotIndex + 1);
+
+    // Check if the prefix is a known REST operator
+    const canonicalOp = (REST_TO_CANONICAL as Record<string, WhereFilterOp | undefined>)[prefix];
+    if (!canonicalOp) {
+        // Not a known operator (e.g., email "user@host.com" or version "1.2.3")
+        // Treat the entire string as an equality value
+        return ["==", raw];
+    }
+
+    // Parse list values: "(admin,editor)" → ["admin", "editor"]
+    if (rest.startsWith("(") && rest.endsWith(")")) {
+        const items = rest.slice(1, -1).split(",").map(s => coerceValue(s.trim()));
+        return [canonicalOp, items];
+    }
+
+    return [canonicalOp, coerceValue(rest)];
+}
+
+/**
+ * Convert a PostgREST-style querystring record to `FilterValues`.
+ *
+ * - String values are parsed as single conditions.
+ * - String arrays (repeated query params) become multiple conditions on the same field.
+ *
+ * @example
+ * deserializeFilter({ status: "eq.active" })
+ * // → { status: ["==", "active"] }
+ *
+ * deserializeFilter({ age: ["gte.18", "lt.65"] })
+ * // → { age: [[">=", 18], ["<", 65]] }
+ */
+export function deserializeFilter(
+    query: Record<string, any>
+): FilterValues<string> {
+    const result: FilterValues<string> = {};
+
+    for (const [field, raw] of Object.entries(query)) {
+        if (raw === undefined) continue;
+
+        // If it's already a canonical tuple [op, value], keep it as is
+        if (Array.isArray(raw) && raw.length === 2 && typeof raw[0] === "string" && toCanonicalOp(raw[0]) === raw[0]) {
+            result[field] = raw as [WhereFilterOp, unknown];
+            continue;
+        }
+
+        if (Array.isArray(raw)) {
+            if (raw.length === 0) continue;
+            
+            // Check if it's an array of canonical tuples
+            if (Array.isArray(raw[0]) && raw[0].length === 2 && typeof raw[0][0] === "string" && toCanonicalOp(raw[0][0]) === raw[0][0]) {
+                result[field] = raw as [WhereFilterOp, unknown][];
+                continue;
+            }
+
+            if (raw.length === 1) {
+                result[field] = typeof raw[0] === "string" ? deserializeSingle(raw[0]) : ["==", raw[0]];
+            } else {
+                // If the elements are strings, they might be PostgREST dot-strings (repeated params)
+                if (typeof raw[0] === "string" && raw[0].includes(".")) {
+                    result[field] = raw.map(r => typeof r === "string" ? deserializeSingle(r) : (["==", r] as [WhereFilterOp, unknown])) as [WhereFilterOp, unknown][];
+                } else {
+                    // Otherwise assume it's a list of values for an implicit "in" or just multiple conditions
+                    result[field] = ["in", raw];
+                }
+            }
+        } else if (typeof raw === "string") {
+            result[field] = deserializeSingle(raw);
+        } else {
+            result[field] = ["==", raw];
+        }
+    }
+
+    return result;
+}
+
+// ---------------------------------------------------------------------------
+// Logical conditions: serialize / deserialize
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize a `LogicalCondition` or `FilterCondition` to its wire-format string.
+ *
+ * @example
+ * serializeLogicalCondition({ column: "status", operator: "==", value: "active" })
+ * // → "status.eq.active"
+ *
+ * serializeLogicalCondition({ type: "or", conditions: [...] })
+ * // → "or(status.eq.active,status.eq.pending)"
+ */
+export function serializeLogicalCondition(
+    cond: LogicalCondition | FilterCondition
+): string {
+    if ("type" in cond) {
+        // LogicalCondition (and/or)
+        const inner = (cond.conditions ?? [])
+            .map(serializeLogicalCondition)
+            .join(",");
+        return `${cond.type}(${inner})`;
+    }
+
+    // FilterCondition
+    const restOp = (CANONICAL_TO_REST as any)[cond.operator] || "eq";
+    if (Array.isArray(cond.value)) {
+        const items = cond.value.map(stringifyValue).join(",");
+        return `${cond.column}.${restOp}.(${items})`;
+    }
+    return `${cond.column}.${restOp}.${stringifyValue(cond.value)}`;
+}
+
+/**
+ * Parse a logical condition wire-format string back into a
+ * `LogicalCondition` or `FilterCondition`.
+ *
+ * @example
+ * deserializeLogicalCondition("status.eq.active")
+ * // → { column: "status", operator: "==", value: "active" }
+ *
+ * deserializeLogicalCondition("or(status.eq.active,age.gte.18)")
+ * // → { type: "or", conditions: [...] }
+ */
+export function deserializeLogicalCondition(
+    str: string
+): LogicalCondition | FilterCondition {
+    // Check for logical group: "and(...)" or "or(...)"
+    const logicalMatch = str.match(/^(and|or)\((.+)\)$/);
+    if (logicalMatch) {
+        const type = logicalMatch[1] as "and" | "or";
+        const innerStr = logicalMatch[2];
+
+        // Split on commas that are not inside parentheses
+        const conditions: (LogicalCondition | FilterCondition)[] = [];
+        let depth = 0;
+        let start = 0;
+        for (let i = 0; i < innerStr.length; i++) {
+            if (innerStr[i] === "(") depth++;
+            else if (innerStr[i] === ")") depth--;
+            else if (innerStr[i] === "," && depth === 0) {
+                conditions.push(deserializeLogicalCondition(innerStr.slice(start, i)));
+                start = i + 1;
+            }
+        }
+        conditions.push(deserializeLogicalCondition(innerStr.slice(start)));
+
+        return { type, conditions };
+    }
+
+    // FilterCondition: "column.op.value"
+    const firstDot = str.indexOf(".");
+    if (firstDot === -1) {
+        return { column: str, operator: "==", value: true };
+    }
+
+    const column = str.substring(0, firstDot);
+    const rest = str.substring(firstDot + 1);
+
+    const secondDot = rest.indexOf(".");
+    if (secondDot === -1) {
+        // "column.value" — treat as equality
+        return { column, operator: "==", value: coerceValue(rest) };
+    }
+
+    const opStr = rest.substring(0, secondDot);
+    let valueStr = rest.substring(secondDot + 1);
+    const operator = toCanonicalOp(opStr) ?? "==";
+
+    // Parse list values
+    if (valueStr.startsWith("(") && valueStr.endsWith(")")) {
+        const items = valueStr.slice(1, -1).split(",").map(s => coerceValue(s.trim()));
+        return { column, operator, value: items };
+    }
+
+    return { column, operator, value: coerceValue(valueStr) };
+}

package/src/data/query_builder.ts

@@ -1,4 +1,4 @@
-import { FindParams, Entity, FindResponse, CollectionAccessor, QueryBuilderInterface, FilterOperator, LogicalCondition, WhereValue, FilterCondition } from "@rebasepro/types";
+import { FindParams, Entity, FindResponse, CollectionAccessor, QueryBuilderInterface, WhereFilterOp, LogicalCondition, WhereValue, FilterCondition } from "@rebasepro/types";
 
 export function or(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition {
     return { type: "or",
@@ -10,7 +10,7 @@ export function and(...conditions: (FilterCondition | LogicalCondition)[]): Logi
 conditions };
 }
 
-export function cond(column: string, operator: FilterOperator, value: unknown): FilterCondition {
+export function cond(column: string, operator: WhereFilterOp, value: unknown): FilterCondition {
     return { column,
 operator,
 value };
@@ -26,9 +26,9 @@ export class QueryBuilder<M extends Record<string, unknown> = Record<string, unk
      * @example
      * client.collection('users').where('age', '>=', 18).find()
      */
-    where<K extends keyof M & string>(column: K, operator: FilterOperator, value: WhereValue<M[K]>): this;
+    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
     where(logicalCondition: LogicalCondition): this;
-    where(columnOrCondition: string | LogicalCondition, operator?: FilterOperator, value?: unknown): this {
+    where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown): this {
         // Handle LogicalCondition signature
         if (typeof columnOrCondition === "object" && columnOrCondition !== null && "type" in columnOrCondition) {
             this.params.logical = columnOrCondition as LogicalCondition;
@@ -40,18 +40,18 @@ export class QueryBuilder<M extends Record<string, unknown> = Record<string, unk
         }
 
         const column = columnOrCondition as string;
-        const condition: [FilterOperator, unknown] = [operator!, value];
+        const condition: [WhereFilterOp, unknown] = [operator!, value];
         const existing = this.params.where[column];
 
         if (existing === undefined) {
             this.params.where[column] = condition;
         } else if (Array.isArray(existing) && existing.length > 0 && Array.isArray(existing[0])) {
-            (this.params.where[column] as [FilterOperator, unknown][]).push(condition);
+            (this.params.where[column] as [WhereFilterOp, unknown][]).push(condition);
         } else {
             // Convert existing single tuple/value into array of tuples
-            let firstCondition: [FilterOperator, unknown];
+            let firstCondition: [WhereFilterOp, unknown];
             if (Array.isArray(existing) && existing.length === 2 && typeof existing[0] === "string") {
-                firstCondition = existing as [FilterOperator, unknown];
+                firstCondition = existing as [WhereFilterOp, unknown];
             } else {
                 firstCondition = ["==", existing];
             }
@@ -66,8 +66,8 @@ export class QueryBuilder<M extends Record<string, unknown> = Record<string, unk
      * @example
      * client.collection('users').orderBy('createdAt', 'desc').find()
      */
-    orderBy(column: keyof M & string, ascending: "asc" | "desc" = "asc"): this {
-        this.params.orderBy = `${column}:${ascending}`;
+    orderBy(column: keyof M & string, direction: "asc" | "desc" = "asc"): this {
+        this.params.orderBy = `${column}:${direction}`;
         return this;
     }
 

package/src/data/resolveDataSource.ts

@@ -14,8 +14,8 @@ import {
 export interface DataSourceResolvable {
     /** Preferred routing key. */
     dataSource?: string;
-    /** Legacy engine hint / fallback routing key. */
-    driver?: string;
+    /** Engine type discriminant (set on variant collection types). */
+    engine?: string;
     /** Within-engine instance. */
     databaseId?: string;
 }
@@ -41,13 +41,13 @@ export function createDataSourceRegistry(definitions?: DataSourceDefinition[]):
  * editor's capability lookups.
  *
  * Resolution order:
- * 1. The routing **key** is `collection.dataSource`, else the legacy
- *    `collection.driver`, else {@link DEFAULT_DATA_SOURCE_KEY}.
+ * 1. The routing **key** is `collection.dataSource`, else
+ *    {@link DEFAULT_DATA_SOURCE_KEY}.
  * 2. If a definition is registered for that key, it provides `engine`,
  *    `transport`, and `databaseId`.
- * 3. Otherwise values are synthesized for backward compatibility: `engine`
- *    from the legacy `driver` (or the key, or `"postgres"`), `transport`
- *    defaults to `"server"`, and `databaseId` from the collection.
+ * 3. Otherwise values are synthesized: `engine` from `collection.engine`
+ *    (or the key, or `"postgres"`), `transport` defaults to `"server"`,
+ *    and `databaseId` from the collection.
  *
  * `capabilities` are always derived from the resolved `engine`, so two
  * data sources sharing an engine share capabilities.
@@ -59,11 +59,11 @@ export function resolveDataSource(
     collection: DataSourceResolvable | undefined,
     registry?: DataSourceRegistry
 ): ResolvedDataSource {
-    const key = collection?.dataSource ?? collection?.driver ?? DEFAULT_DATA_SOURCE_KEY;
+    const key = collection?.dataSource ?? DEFAULT_DATA_SOURCE_KEY;
     const def = registry?.[key];
 
     const engine = def?.engine
-        ?? collection?.driver
+        ?? collection?.engine
         ?? (key !== DEFAULT_DATA_SOURCE_KEY ? key : "postgres");
 
     const transport = def?.transport ?? "server";

package/src/index.ts

@@ -4,4 +4,5 @@ export * from "./data/buildRebaseData";
 export * from "./data/buildRoutedRebaseData";
 export * from "./data/resolveDataSource";
 export * from "./data/query_builder";
+export * from "./data/filter-dialect";
 export * from "./table-classification";

package/src/util/builders.ts

@@ -7,9 +7,17 @@ import {
     EntityCollection,
     EnumValueConfig,
     EnumValues,
+    FirebaseCollection,
+    FirebaseProperties,
     GeopointProperty,
+    InferEntityType,
     MapProperty,
-    NumberProperty, Properties,
+    MongoDBCollection,
+    MongoProperties,
+    NumberProperty,
+    PostgresCollection,
+    PostgresProperties,
+    Properties,
     Property,
     ReferenceProperty,
     StringProperty,
@@ -32,6 +40,75 @@ export function buildCollection<
     return collection;
 }
 
+// ── defineCollection ─────────────────────────────────────────────────────
+// A smarter builder that uses `const` type-parameter inference (TS 5.0+)
+// to capture literal property types automatically. This gives you
+// autocomplete on `titleProperty`, `sort`, `propertiesOrder`, `fixedFilter`,
+// callbacks, etc. — without writing `as const` or passing manual generics.
+
+/**
+ * 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 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 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 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 };
+
+/**
+ * Implementation — delegates to the correct overload at the type level.
+ * At runtime this is a plain identity function.
+ */
+export function defineCollection(
+    collection: EntityCollection
+): EntityCollection {
+    return collection;
+}
+
 /**
  * Identity function we use to defeat the type system of Typescript and preserve
  * the property keys.

package/src/util/callbacks.ts

@@ -1,4 +1,11 @@
-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 recursively check if there are any callbacks in the properties.

package/src/util/index.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/src/util/permissions.test.ts

@@ -162,9 +162,10 @@ roles: ["author"] }
         expect(canReadCollection(collection, mockAuthController)).toBe(true);
     });
 
-    test("11. Empty roles array [] on rule grants access to everyone (public)", () => {
+    test("11. Empty roles array [] adds no role restriction (public rule stays public)", () => {
         const collection = createMockCollection([
             { operation: "insert",
+access: "public",
 roles: [] }
         ]);
         expect(canCreateEntity(collection, mockAuthController, "test", null)).toBe(true);
@@ -172,9 +173,10 @@ roles: [] }
         expect(canCreateEntity(collection, adminAuthController, "test", null)).toBe(true);
     });
 
-    test("12. Undefined roles on rule grants access to everyone (public)", () => {
+    test("12. Undefined roles on a public rule grants access to everyone", () => {
         const collection = createMockCollection([
-            { operation: "insert" }
+            { operation: "insert",
+access: "public" }
         ]);
         expect(canCreateEntity(collection, mockAuthController, "test", null)).toBe(true);
         expect(canCreateEntity(collection, unauthenticatedController, "test", null)).toBe(true);