@rebasepro/types 0.7.0 → 0.9.0

package/src/controllers/data.ts

@@ -1,29 +1,5 @@
 import { Entity, EntityValues } from "../types/entities";
-
-/**
- * Parameters for querying a collection.
- * Uses PostgREST-style filter syntax for consistency between
- * the SDK (HTTP) and framework (in-process) contexts.
- *
- * @group Data
- */
-/**
- * A where-clause value for a single field.
- *
- * Supports three syntaxes:
- *  1. **Equality shorthand**: raw JS values — `null`, `"active"`, `42`, `true`
- *  2. **Tuple syntax**: `[operator, value]` — `[">", 18]`, `["in", ["a","b"]]`
- *  3. **PostgREST string**: `"eq.published"`, `"gte.18"`, `"in.(a,b)"`
- *
- * @group Data
- */
-export type WhereFieldValue =
-    | string
-    | number
-    | boolean
-    | null
-    | [WhereFilterOpShort, any]
-    | [WhereFilterOpShort, any][];
+import { WhereFilterOp, FilterValues, OrderByTuple } from "../types/filter-operators";
 
 export type WhereValue<T> = T | T[] | null;
 
@@ -34,59 +10,84 @@ export interface LogicalCondition {
 
 export interface FilterCondition {
     column: string;
-    operator: FilterOperator;
+    operator: WhereFilterOp;
     value: unknown;
 }
 
-/** Short operator strings accepted in the tuple syntax. */
-export type WhereFilterOpShort =
-    | "==" | "!=" | ">" | ">=" | "<" | "<="
-    | "eq" | "neq" | "gt" | "gte" | "lt" | "lte"
-    | "in" | "nin" | "not-in"
-    | "array-contains" | "array-contains-any" | "cs" | "csa";
-
+/**
+ * Parameters for querying a collection.
+ *
+ * ## How the filter parameters combine
+ *
+ * `where`, `logical`, and `searchString` are **independent** and, when more
+ * than one is present, are combined with **AND** — every clause must match.
+ * Concretely the backend builds:
+ *
+ * ```text
+ * (where filters, AND-ed together)
+ *   AND (logical group)
+ *   AND (searchString matches, OR-ed across searchable columns)
+ * ```
+ *
+ * So `where` does **not** conflict with or override `logical` — they stack.
+ * If you need `where` fields OR-ed with each other, move them into `logical`
+ * instead. There is no way to OR `where` against `logical`; express anything
+ * that isn't a plain AND of the three groups inside a single `logical` tree.
+ *
+ * ## Pagination precedence
+ *
+ * `limit`/`offset` and `page` describe the same window two ways. If **both
+ * `offset` and `page` are provided, `page` wins** — the backend computes
+ * `offset = (page - 1) * (limit ?? 20)` and ignores the explicit `offset`.
+ * Pick one style per query.
+ *
+ * @group Data
+ */
 export interface FindParams {
-    /** Maximum number of items to return (default: 20) */
+    /** Maximum number of items to return (default: 20). */
     limit?: number;
-    /** Number of items to skip */
+    /**
+     * Number of items to skip. Ignored when {@link FindParams.page} is also
+     * set — `page` takes precedence.
+     */
     offset?: number;
-    /** Page number (1-indexed), alternative to offset */
+    /**
+     * Page number (1-indexed), alternative to {@link FindParams.offset}.
+     * When set, overrides `offset` as `(page - 1) * (limit ?? 20)`.
+     */
     page?: number;
     /**
-     * Filter object. Supports multiple syntaxes per field:
+     * Filter conditions keyed by field name.
+     * Each value is a `[WhereFilterOp, value]` tuple or an array of tuples
+     * for multiple conditions on the same field. Multiple fields, and multiple
+     * tuples on one field, are **AND-ed**; also AND-ed with `logical` and
+     * `searchString` when present (see the interface docs).
      *
-     * **Equality shorthand** — raw JS values (null, string, number, boolean):
-     * ```ts
-     * { company_profile_id: null }
-     * { status: "active" }
-     * { age: 18 }
-     * ```
-     *
-     * **Tuple syntax** — `[operator, value]`:
-     * ```ts
+     * @example
+     * { status: ["==", "active"] }
      * { age: [">=", 18] }
      * { role: ["in", ["admin", "editor"]] }
-     * { deleted_at: ["!=", null] }
-     * ```
-     *
-     * **PostgREST string syntax** (original format):
-     * ```ts
-     * { status: "eq.published" }
-     * { age: "gte.18" }
-     * { role: "in.(admin,editor)" }
-     * ```
-     */
-    where?: Record<string, WhereFieldValue>;
-    /** Logical grouping conditions (AND/OR) */
+     * { age: [[">=", 18], ["<", 65]] }
+     */
+    where?: FilterValues<string>;
+    /**
+     * Logical grouping conditions (AND/OR). Use this for anything `where`
+     * can't express — notably OR-ing conditions. AND-ed with `where` and
+     * `searchString` when present (see the interface docs).
+     */
     logical?: LogicalCondition;
     /**
-     * Sort order. Format: "field:direction".
-     * @example "created_at:desc", "name:asc"
+     * Sort order as a `[field, direction]` tuple.
+     * @example orderBy: ["created_at", "desc"]
      */
-    orderBy?: string;
+    orderBy?: OrderByTuple;
     /** Relations to include in the response */
     include?: string[];
-    /** Full-text search string */
+    /**
+     * Full-text search string. Matched (OR-ed) across the collection's
+     * searchable columns, then AND-ed with `where`/`logical`. This is the
+     * value behind the query builder's `.search()` method.
+     */
     searchString?: string;
 }
 
@@ -106,16 +107,22 @@ export interface FindResponse<M extends Record<string, unknown> = Record<string,
     };
 }
 
-export type FilterOperator = WhereFilterOpShort;
+
 
 /**
- * Fluent Query Builder Interface supported on both client and server accessors.
+ * Fluent query builder for the **admin CMS** — resolves to `FindResponse<M>`
+ * (Snapshot-wrapped rows).
+ *
+ * @internal App developers should use {@link SDKQueryBuilderInterface}
+ * (flat rows, returned by `client.data.*` / `context.data.*`). This
+ * Snapshot-flavored variant backs the admin CMS internals only.
+ *
  * @group Data
  */
 export interface QueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>> {
-    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;
-    orderBy(column: keyof M & string, ascending?: "asc" | "desc"): this;
+    orderBy(column: keyof M & string, direction?: "asc" | "desc"): this;
     limit(count: number): this;
     offset(count: number): this;
     search(searchString: string): this;
@@ -125,11 +132,13 @@ export interface QueryBuilderInterface<M extends Record<string, unknown> = Recor
 }
 
 /**
- * A single collection's CRUD accessor.
+ * A single collection's CRUD accessor for the **admin CMS** — every method
+ * resolves to `Snapshot`-wrapped rows (`FindResponse<M>` / `Snapshot<M>`).
  *
- * This is the unified API surface used in both:
- * - The generated SDK (`client.data.products.create(...)`)
- * - Framework callbacks (`context.data.products.create(...)`)
+ * @internal App developers do **not** use this. The public, symmetric surface
+ * is {@link SDKCollectionClient} (flat rows), exposed as `client.data.products`
+ * in the SDK and `context.data.products` in framework callbacks. This
+ * Snapshot-flavored accessor backs the admin CMS view-model only.
  *
  * @group Data
  */
@@ -163,11 +172,6 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      */
     delete(id: string | number): Promise<void>;
 
-    /**
-     * Delete all records in this collection.
-     */
-    deleteAll?(): Promise<void>;
-
     /**
      * Subscribe to a collection for real-time updates.
      * Optional method, may not be supported by all implementations (like stateless HTTP clients).
@@ -186,37 +190,169 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
     count?(params?: FindParams): Promise<number>;
 
     // Fluent Query Builder
-    where<K extends keyof M & string>(column: K, operator: FilterOperator, value: WhereValue<M[K]>): QueryBuilderInterface<M>;
+    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): QueryBuilderInterface<M>;
     where(logicalCondition: LogicalCondition): QueryBuilderInterface<M>;
-    orderBy(column: keyof M & string, ascending?: "asc" | "desc"): QueryBuilderInterface<M>;
+    orderBy(column: keyof M & string, direction?: "asc" | "desc"): QueryBuilderInterface<M>;
     limit(count: number): QueryBuilderInterface<M>;
     offset(count: number): QueryBuilderInterface<M>;
     search(searchString: string): QueryBuilderInterface<M>;
     include(...relations: string[]): QueryBuilderInterface<M>;
 }
 
+// =============================================================================
+// SDK-facing types — flat rows, no Entity wrapper
+// =============================================================================
+
+/**
+ * Pagination metadata returned with collection queries.
+ * @group Data
+ */
+export interface PaginationMeta {
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+
 /**
- * The unified data access object.
+ * Paginated response from a collection query (SDK-facing).
+ * Returns flat rows instead of Entity-wrapped objects.
  *
- * Access collections as dynamic properties: `data.products.find(...)`.
- * In the SDK this is backed by HTTP transport (typed, generated per-project).
- * In the framework this is backed by a Proxy + in-process database driver (dynamic).
+ * @example
+ * const { data, meta } = await rebase.data.posts.find();
+ * console.log(data[0].title); // direct access — no .values
+ * console.log(meta.total);
+ *
+ * @group Data
+ */
+export interface FindResult<M extends Record<string, unknown> = Record<string, unknown>> {
+    /** Array of flat rows matching the query */
+    data: M[];
+    /** Pagination metadata */
+    meta: PaginationMeta;
+}
+
+/**
+ * Fluent Query Builder Interface for the SDK client.
+ * Returns `FindResult<M>` (flat rows) instead of `FindResponse<M>` (Entity-wrapped).
+ *
+ * @group Data
+ */
+export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>> {
+    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where(logicalCondition: LogicalCondition): this;
+    orderBy(column: keyof M & string, direction?: "asc" | "desc"): this;
+    limit(count: number): this;
+    offset(count: number): this;
+    search(searchString: string): this;
+    include(...relations: string[]): this;
+    find(): Promise<FindResult<M>>;
+    count(): Promise<number>;
+    listen(onUpdate: (data: FindResult<M>) => void, onError?: (error: Error) => void): () => void;
+}
+
+/**
+ * SDK collection client — returns flat rows, no Entity wrapper.
+ *
+ * This is the public API surface for app developers using
+ * `createRebaseClient()`. CMS internals use `CollectionAccessor` instead.
+ *
+ * Type parameters:
+ * - `M` — the **Row** shape returned by reads (`find`, `findById`, `listen`).
+ * - `I` — the **Insert** shape accepted by {@link create}. Defaults to
+ *   `Partial<M>`; the generated SDK supplies a dedicated `Insert` type where
+ *   required columns are required and auto-generated / read-only columns are
+ *   omitted, so `create({})` on a table with required fields is a compile error.
+ * - `U` — the **Update** shape accepted by {@link update}. Defaults to
+ *   `Partial<M>`; the generated SDK supplies a dedicated `Update` type.
  *
  * @example
- * // SDK
- * const client = createRebaseClient({ baseUrl: "..." });
- * await client.data.products.create({ name: "Camera", price: 299 });
+ * const { data: posts } = await rebase.data.posts.find();
+ * console.log(posts[0].title);       // flat access
+ * console.log(posts[0].id);          // id at top level
  *
- * // Framework callback
- * callbacks: {
- *   afterSave({ context }) {
- *     await context.data.logs.create({ action: "saved", timestamp: new Date() });
- *   }
- * }
+ * const post = await rebase.data.posts.findById(1);
+ * console.log(post?.title);          // no .values needed
  *
  * @group Data
  */
-export interface RebaseData {
+export interface SDKCollectionClient<
+    M extends Record<string, unknown> = Record<string, unknown>,
+    I = Partial<M>,
+    U = Partial<M>
+> {
+    /**
+     * Find multiple records with optional filtering, pagination, and sorting.
+     */
+    find(params?: FindParams): Promise<FindResult<M>>;
+
+    /**
+     * Find a single record by its ID.
+     */
+    findById(id: string | number): Promise<M | undefined>;
+
+    /**
+     * Create a new record.
+     * @param data The record data to create (the collection's `Insert` shape).
+     * @param id Optional specific ID to use for the new record.
+     * @returns The created row
+     */
+    create(data: I, id?: string | number): Promise<M>;
+
+    /**
+     * Update an existing record by ID.
+     * @param data The fields to update (the collection's `Update` shape).
+     * @returns The updated row.
+     * @throws {RebaseApiError} with status 404 when the record does not exist.
+     */
+    update(id: string | number, data: U): Promise<M>;
+
+    /**
+     * Delete a record by ID.
+     * @throws {RebaseApiError} with status 404 when the record does not exist.
+     */
+    delete(id: string | number): Promise<void>;
+
+    /**
+     * Subscribe to a collection for real-time updates.
+     */
+    listen?(params: FindParams | undefined, onUpdate: (response: FindResult<M>) => void, onError?: (error: Error) => void): () => void;
+
+    /**
+     * Subscribe to a single record for real-time updates.
+     */
+    listenById?(id: string | number, onUpdate: (row: M | undefined) => void, onError?: (error: Error) => void): () => void;
+
+    /**
+     * Count the number of records matching the given filter.
+     */
+    count?(params?: FindParams): Promise<number>;
+
+    // Fluent Query Builder
+    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): SDKQueryBuilderInterface<M>;
+    where(logicalCondition: LogicalCondition): SDKQueryBuilderInterface<M>;
+    orderBy(column: keyof M & string, direction?: "asc" | "desc"): SDKQueryBuilderInterface<M>;
+    limit(count: number): SDKQueryBuilderInterface<M>;
+    offset(count: number): SDKQueryBuilderInterface<M>;
+    search(searchString: string): SDKQueryBuilderInterface<M>;
+    include(...relations: string[]): SDKQueryBuilderInterface<M>;
+}
+
+/**
+ * The unified data access object for the **admin CMS** (Entity-shaped).
+ *
+ * Access collections as dynamic properties: `data.products.find(...)`. Each
+ * accessor returns `Entity`-wrapped records (`{ id, path, values }`) — the
+ * view-model the CMS renders. This is what `useData()` / the admin
+ * `RebaseContext.data` are backed by.
+ *
+ * @internal App developers do **not** use this — they use
+ * {@link RebaseSdkData} (flat rows), which is what the SDK client and backend
+ * `context.data` expose. This Entity-shaped map backs the admin CMS only.
+ *
+ * @group Data
+ */
+export type RebaseData<DB = unknown> = {
     /**
      * Get a collection accessor by slug.
      * Alternative to dynamic property access for cases where
@@ -226,14 +362,90 @@ export interface RebaseData {
      * const accessor = data.collection("products");
      * await accessor.find({ limit: 10 });
      */
-    collection(slug: string): CollectionAccessor;
+    collection<M extends Record<string, unknown> = Record<string, unknown>>(slug: string): CollectionAccessor<M>;
+} & (
+    DB extends Record<string, unknown>
+        ? { [K in keyof DB]: CollectionAccessor<DB[K] extends { Row: infer R extends Record<string, unknown> } ? R : Record<string, unknown>> }
+        : {
+            /**
+             * Dynamic collection accessor.
+             * Access any collection by its slug as a property.
+             *
+             * @example
+             * data.products.find({ where: { status: ["==", "published"] } })
+             */
+            [collectionSlug: string]: CollectionAccessor | ((slug: string) => CollectionAccessor);
+        }
+);
 
+/**
+ * The unified data access object for the **SDK** — flat rows, no Entity wrapper.
+ *
+ * This is the symmetric developer-facing data API, identical in shape on both
+ * sides of the stack:
+ * - The frontend SDK client (`client.data.products.find()`)
+ * - Backend framework callbacks & scripts (`context.data.products.find()`)
+ *
+ * Every accessor returns flat rows (`{ id, ...columns }`) via
+ * {@link SDKCollectionClient} — access fields directly (`row.title`), never
+ * `row.values.title`. The admin CMS uses {@link RebaseData} (Entity) instead.
+ *
+ * @example
+ * // Frontend SDK
+ * const { data: posts } = await client.data.posts.find();
+ * console.log(posts[0].title);        // flat — no .values
+ *
+ * // Backend callback — identical shape
+ * callbacks: {
+ *   beforeSave: async ({ context }) => {
+ *     const product = await context.data.products.findById(id);
+ *     console.log(product?.price);     // flat — no .values
+ *   }
+ * }
+ *
+ * @group Data
+ */
+/**
+ * Extract the `Row` shape from a generated `Database[slug]` entry, falling
+ * back to an open record when the entry is untyped.
+ * @group Data
+ */
+export type RowOf<T> = T extends { Row: infer R extends Record<string, unknown> } ? R : Record<string, unknown>;
+
+/**
+ * Extract the `Insert` shape from a generated `Database[slug]` entry (the
+ * input accepted by `create`), falling back to `Partial<Row>`.
+ * @group Data
+ */
+export type InsertOf<T> = T extends { Insert: infer I extends Record<string, unknown> } ? I : Partial<RowOf<T>>;
+
+/**
+ * Extract the `Update` shape from a generated `Database[slug]` entry (the
+ * input accepted by `update`), falling back to `Partial<Row>`.
+ * @group Data
+ */
+export type UpdateOf<T> = T extends { Update: infer U extends Record<string, unknown> } ? U : Partial<RowOf<T>>;
+
+export type RebaseSdkData<DB = unknown> = {
     /**
-     * Dynamic collection accessor.
-     * Access any collection by its slug as a property.
+     * Get a flat collection accessor by slug.
      *
      * @example
-     * data.products.find({ where: { status: "eq.published" } })
+     * const accessor = data.collection("products");
+     * await accessor.find({ limit: 10 });
      */
-    [collectionSlug: string]: CollectionAccessor | ((slug: string) => CollectionAccessor);
-}
+    collection<M extends Record<string, unknown> = Record<string, unknown>>(slug: string): SDKCollectionClient<M>;
+} & (
+    DB extends Record<string, unknown>
+        ? { [K in keyof DB]: SDKCollectionClient<RowOf<DB[K]>, InsertOf<DB[K]>, UpdateOf<DB[K]>> }
+        : {
+            /**
+             * Dynamic flat collection accessor.
+             * Access any collection by its slug as a property.
+             *
+             * @example
+             * data.products.find({ where: { status: ["==", "published"] } })
+             */
+            [collectionSlug: string]: SDKCollectionClient | ((slug: string) => SDKCollectionClient);
+        }
+);