@rebasepro/common 0.13.1-canary.gf57a27e → 0.14.0

package/dist/data/filter-conditions.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The `FilterValues` grammar, one level below the wire codec.
+ *
+ * A field's filter is either one `[op, value]` tuple or an **array** of them —
+ * `{ age: [[">=", 18], ["<", 65]] }` — which is what the fluent builder produces
+ * from two `.where()` calls on the same column. Reading that shape is grammar,
+ * not a driver detail, so every compiler reads it through here.
+ *
+ * It lived only inside the Postgres compiler, and the Mongo one destructured
+ * `const [op, value] = filterParam` regardless: given the array-of-tuples form
+ * `op` bound to `[">=", 18]`, no operator matched, and the condition was
+ * dropped. Both of them. A read asking for adults under 65 returned every row
+ * of the collection with a 200.
+ *
+ * @module
+ */
+import type { WhereFilterOp } from "@rebasepro/types";
+/** One `[operator, value]` condition. */
+export type FilterTuple = [WhereFilterOp, unknown];
+/**
+ * Read one field's filter as the list of conditions it stands for.
+ *
+ * Accepts both declared shapes and normalises them to a list:
+ *
+ * ```ts
+ * toFilterTuples(["==", "active"])          // [["==", "active"]]
+ * toFilterTuples([[">=", 18], ["<", 65]])   // [[">=", 18], ["<", 65]]
+ * ```
+ *
+ * A falsy, non-array or empty param has no conditions in it — the empty list,
+ * so a caller iterating adds nothing rather than compiling a tuple of
+ * `undefined`s and logging about an operator nobody sent.
+ */
+export declare function toFilterTuples(filterParam: unknown): FilterTuple[];

package/dist/data/filter-dialect.d.ts

@@ -9,12 +9,61 @@
  * metadata, so type coercion is the responsibility of the server-side data
  * driver which has access to the collection schema.
  *
- * Commas inside list values are backslash-escaped (`\,`), and literal
- * backslashes are escaped as `\\`.
+ * Structural characters inside a value are backslash-escaped: `,` → `\,`,
+ * `(` → `\(`, `)` → `\)`, and a literal backslash as `\\`. Decoding is
+ * deliberately conservative — only those four sequences are decoded, so a
+ * backslash that arrives unescaped from an older client survives intact.
  *
  * @module
  */
-import { FilterValues, LogicalCondition, FilterCondition } from "@rebasepro/types";
+import { WhereFilterOp, FilterValues, LogicalCondition, FilterCondition } from "@rebasepro/types";
+/**
+ * A filter condition named an operator this dialect does not have.
+ *
+ * ## Why this throws, rather than returning a typed rejection
+ *
+ * `deserializeFilter` is the *shared* codec: the REST ingress
+ * (`packages/server/src/api/rest/query-parser.ts`), the browser SDK and the
+ * admin panel (`buildRebaseData.ts`) all decode through it. Two constraints
+ * follow.
+ *
+ * - It cannot throw the server's `ApiError`. `@rebasepro/common` does not
+ *   depend on `@rebasepro/server` (the dependency runs the other way), and a
+ *   browser client has no error handler to render an `ApiError` with. So the
+ *   rejection is this plain `Error` subclass, whose `message` reads correctly
+ *   wherever it surfaces — a rejected promise in an app, a 400 body over HTTP.
+ * - It cannot be a returned rejection *value*. Every caller assigns the result
+ *   straight into a query it is about to run; a sentinel that none of them
+ *   check would be ignored, which is exactly the silently-wrong-filter failure
+ *   this exists to stop. Throwing is also what this file already does for the
+ *   sibling cases — `serializeTuple` on an unknown canonical operator,
+ *   `deserializeLogicalCondition` past the nesting bound — and the REST parser
+ *   already converts the latter into a 400.
+ *
+ * `statusCode`, `code` and `details` are carried as fields because the server's
+ * Hono error handler duck-types those off any thrown error: a decode path that
+ * forgets to convert still answers 400 with the canonical envelope instead of a
+ * 500 that says "An unexpected error occurred". `query-parser.ts` converts
+ * explicitly all the same — that is the path the contract is stated on, and an
+ * incidental 400 is not a contract.
+ */
+export declare class UnknownFilterOperatorError extends Error {
+    /** The field the condition was written against. */
+    readonly field: string;
+    /** The operator string as it arrived, verbatim. */
+    readonly operator: string;
+    /** Every operator this dialect accepts, in canonical spelling. */
+    readonly validOperators: readonly WhereFilterOp[];
+    /** See the class docblock: read by the server's error handler. */
+    readonly statusCode = 400;
+    readonly code = "UNKNOWN_FILTER_OPERATOR";
+    readonly details: {
+        field: string;
+        operator: string;
+        validOperators: readonly WhereFilterOp[];
+    };
+    constructor(field: string, operator: string);
+}
 /**
  * Convert `FilterValues` (or `WireFilterValues`) to a PostgREST-style
  * querystring record.
@@ -48,6 +97,9 @@ export declare function serializeFilter(filter: FilterValues<string> | Record<st
  *
  * deserializeFilter({ age: ["gte.18", "lt.65"] })
  * // → { age: [[">=", "18"], ["<", "65"]] }
+ *
+ * @throws {UnknownFilterOperatorError} when a condition names an operator this
+ * dialect does not have. See that class for why a rejection here is a throw.
  */
 export declare function deserializeFilter(query: Record<string, unknown>): FilterValues<string>;
 /**

package/dist/data/query_builder.d.ts

@@ -1,4 +1,4 @@
-import { CollectionAccessor, FilterCondition, FindResponse, LogicalCondition, QueryBuilderInterface, WhereFilterOp, WhereValue, type ComputedSortField } from "@rebasepro/types";
+import { CollectionAccessor, FilterCondition, FindResponse, LogicalCondition, QueryBuilderInterface, WhereFilterOp, WhereValueFor, type ComputedSortField } from "@rebasepro/types";
 export declare function or(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
 export declare function and(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
 export declare function cond(column: string, operator: WhereFilterOp, value: unknown): FilterCondition;
@@ -11,7 +11,7 @@ export declare class QueryBuilder<M extends Record<string, unknown> = Record<str
      * @example
      * client.collection('users').where('age', '>=', 18).find()
      */
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
     where(logicalCondition: LogicalCondition): this;
     /**
      * Order the results by a specific column.

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from "./data/buildRoutedRebaseData";
 export * from "./data/resolveDataSource";
 export * from "./data/query_builder";
 export * from "./data/paginate";
+export * from "./data/filter-conditions";
 export * from "./data/filter-dialect";
 export * from "./data/sort-dialect";
 export * from "./table-classification";