@rebasepro/common 0.13.0 → 0.13.1-canary.g1822133

package/dist/data/buildRebaseData.d.ts

@@ -34,7 +34,16 @@ export declare function buildRebaseData(driver: DataDriver, options?: EntityData
  * admin `RebaseDataContext` — without it the admin renders rows with only their
  * `id`.
  */
-export declare function wrapAsEntityData(sdkData: RebaseSdkData, options?: EntityDataOptions): RebaseData;
+/**
+ * Only the by-slug accessor is asked for, so only that is required.
+ *
+ * Taking a whole `RebaseSdkData` meant taking `RebaseSdkData<unknown>`, whose
+ * dynamic branch is an index signature — and no `RebaseSdkData<DB>` satisfies
+ * it, because its own `collection` method is not a `SDKCollectionClient`. So a
+ * caller holding a *typed* client could not pass it to a function that reads
+ * one method off it, and that method is identical on every instantiation.
+ */
+export declare function wrapAsEntityData(sdkData: Pick<RebaseSdkData, "collection">, options?: EntityDataOptions): RebaseData;
 /**
  * Wrap a Entity-shaped {@link RebaseData} into a flat {@link RebaseSdkData}.
  *

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>;
 /**
@@ -72,4 +124,18 @@ export declare function serializeLogicalCondition(cond: LogicalCondition | Filte
  * deserializeLogicalCondition("or(status.eq.active,age.gte.18)")
  * // → { type: "or", conditions: [...] }
  */
-export declare function deserializeLogicalCondition(str: string): LogicalCondition | FilterCondition;
+/**
+ * How deeply `or(...)`/`and(...)` groups may nest.
+ *
+ * This parser recurses once per level, on a value that arrives in a query
+ * string. Unbounded, twenty thousand levels reached `RangeError: Maximum call
+ * stack size exceeded`, which a caller sees as a 500 about the call stack
+ * rather than a 400 about their filter. Node's 16 KB header cap keeps a GET
+ * below that in practice, but "the HTTP layer happens to stop it" is not a
+ * bound this parser should rely on.
+ *
+ * Thirty-two is far past anything a real filter expresses; the deepest in this
+ * repository's own tests is three.
+ */
+export declare const MAX_LOGICAL_NESTING_DEPTH = 32;
+export declare function deserializeLogicalCondition(str: string, nesting?: number): LogicalCondition | FilterCondition;

package/dist/data/paginate.d.ts

@@ -45,6 +45,26 @@ export declare class RebasePaginationError extends Error {
 }
 /** The one thing a transport has to provide to be paginated. */
 export type PageFinder<M extends Record<string, unknown> = Record<string, unknown>> = (params: FindParams<M>) => Promise<FindResult<M>>;
+/**
+ * Resolve `limit`/`offset`/`page` into the window a read will actually use.
+ *
+ * Lives here, next to the walk, for the reason at the top of this file: every
+ * transport has to mean the same thing by "page two". Four of them did not —
+ * the REST layer strode by {@link DEFAULT_LIST_LIMIT}, the local-first
+ * evaluator by {@link DEFAULT_PAGE_SIZE}, the in-process accessor by 20, and
+ * the published type documented a fourth number. Pages that overlap or skip
+ * rows are the mildest of those outcomes.
+ *
+ * `page` wins over `offset`, as {@link FindParams} documents. `driverOffset`
+ * is the value to hand a driver: it stays `undefined` when the caller named no
+ * offset, because keyset pagination seeks with a `where` clause and must not
+ * look like it is paging by offset.
+ */
+export declare function resolveFindWindow(params?: Pick<FindParams, "limit" | "offset" | "page">): {
+    limit: number;
+    offset: number;
+    driverOffset: number | undefined;
+};
 /**
  * Walk every row a query matches, yielding one row at a time and fetching the
  * next page only when the consumer asks for it.

package/dist/data/query_builder.d.ts

@@ -1,4 +1,4 @@
-import { CollectionAccessor, FilterCondition, FindResponse, LogicalCondition, QueryBuilderInterface, WhereFilterOp, WhereValue } 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,14 +11,14 @@ 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.
      * @example
      * client.collection('users').orderBy('createdAt', 'desc').find()
      */
-    orderBy(column: keyof M & string, direction?: "asc" | "desc"): this;
+    orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): this;
     /**
      * Limit the number of results returned.
      */
@@ -30,7 +30,19 @@ export declare class QueryBuilder<M extends Record<string, unknown> = Record<str
     /**
      * Set a free-text search string if supported by the backend.
      */
-    search(searchString: string): this;
+    search(searchString: string, options?: {
+        explain?: boolean;
+    }): this;
+    /**
+     * Order rows by nearest-neighbour distance to `vector`, closest first.
+     *
+     * Postgres only, over a property declared as `type: "vector"`. Rows come
+     * back with a `_distance`; `where` filters before the ordering.
+     */
+    vectorSearch(property: string, vector: number[], options?: {
+        distance?: "cosine" | "l2" | "inner_product";
+        threshold?: number;
+    }): this;
     /**
      * Include related entities in the response.
      * Relations will be populated with full entity data instead of just IDs.

package/dist/data/resolveDataSource.d.ts

@@ -41,3 +41,39 @@ export declare function createDataSourceRegistry(definitions?: DataSourceDefinit
  * @param registry   optional registry of declared data sources
  */
 export declare function resolveDataSource(collection: DataSourceResolvable | undefined, registry?: DataSourceRegistry): ResolvedDataSource;
+/**
+ * Does a SQL toolchain own this collection's storage?
+ *
+ * "Owns the storage" means: something generates a table for it, pushes that
+ * table to a database, plans its RLS policies, and reports it as drifted when
+ * the two disagree. That is true of a Postgres collection and false of a
+ * Firestore or MongoDB one, whose documents live in a store Rebase never
+ * migrates — and the two were never told apart. Every stage of the SQL
+ * toolchain took "the collections" to mean *all* of them, so a Firestore
+ * collection declared next to the Postgres ones got a `pgTable` in the
+ * generated schema, a `CREATE TABLE` at boot, RLS policies, and a place in the
+ * `db push` include list — where its name shielding a same-named real table
+ * from Atlas's exclude list is the one that can lose data.
+ *
+ * The answer is the resolved engine's {@link DataSourceCapabilities}, not a
+ * name check: an engine registered through `registerDataSourceCapabilities`
+ * gets the same treatment as the built-in ones.
+ *
+ * Deliberately answers **true** for an engine nobody has heard of. Build-time
+ * tooling (the CLI, the schema generator) has no data-source registry to
+ * resolve a `dataSource` key against, so an unknown key resolves to an unknown
+ * engine — and the cost of the two mistakes is not symmetric. Wrongly
+ * including a collection generates a table nothing writes to; wrongly excluding
+ * one silently stops generating a table the app is serving from. Declare
+ * `engine` on a collection that is not SQL-backed and this is exact.
+ */
+export declare function isRelationalCollection(collection: DataSourceResolvable | undefined, registry?: DataSourceRegistry): boolean;
+/**
+ * The subset of `collections` a SQL toolchain owns — see
+ * {@link isRelationalCollection}.
+ *
+ * Every stage that generates SQL from collections starts by calling this, so
+ * the rule lives in one place rather than being re-decided per generator. It
+ * keeps the input order.
+ */
+export declare function relationalCollections<C extends DataSourceResolvable>(collections: readonly C[], registry?: DataSourceRegistry): C[];

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";