@rebasepro/types 0.8.0 → 0.9.1-canary.09aaf62

package/src/controllers/data.ts

@@ -1,5 +1,5 @@
 import { Entity, EntityValues } from "../types/entities";
-import { WhereFilterOp, FilterValues } from "../types/filter-operators";
+import { WhereFilterOp, FilterValues, OrderByTuple } from "../types/filter-operators";
 
 export type WhereValue<T> = T | T[] | null;
 
@@ -17,19 +17,51 @@ export interface FilterCondition {
 /**
  * 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 conditions keyed by field name.
      * Each value is a `[WhereFilterOp, value]` tuple or an array of tuples
-     * for multiple conditions on the same field.
+     * 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).
      *
      * @example
      * { status: ["==", "active"] }
@@ -38,16 +70,24 @@ export interface FindParams {
      * { age: [[">=", 18], ["<", 65]] }
      */
     where?: FilterValues<string>;
-    /** Logical grouping conditions (AND/OR) */
+    /**
+     * 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;
 }
 
@@ -70,7 +110,13 @@ export interface FindResponse<M extends Record<string, unknown> = Record<string,
 
 
 /**
- * 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>> {
@@ -86,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
  */
@@ -113,6 +161,14 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      */
     create(data: Partial<EntityValues<M>>, id?: string | number): Promise<Entity<M>>;
 
+    /**
+     * Create many records in a single transaction.
+     *
+     * See {@link SDKCollectionClient.createMany}. Optional: not every driver can
+     * write in bulk, and callers should fall back to `create` per record.
+     */
+    createMany?(data: Partial<EntityValues<M>>[], options?: { upsert?: boolean }): Promise<Entity<M>[]>;
+
     /**
      * Update an existing record by ID.
      * @returns The updated entity
@@ -124,11 +180,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).
@@ -156,28 +207,192 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
     include(...relations: string[]): QueryBuilderInterface<M>;
 }
 
+// =============================================================================
+// SDK-facing types — flat rows, no Entity wrapper
+// =============================================================================
+
 /**
- * The unified data access object.
+ * Pagination metadata returned with collection queries.
+ * @group Data
+ */
+export interface PaginationMeta {
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+
+/**
+ * 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 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, sent as an `id` column. This is for tables
+     *   whose key *is* `id`: the value goes in as that column. For a table keyed
+     *   on anything else (a `sku`, a composite key), there is no `id` column to
+     *   receive it — put the key in `data` instead, where it belongs among the
+     *   columns.
+     * @returns The created row
+     */
+    create(data: I, id?: string | number): Promise<M>;
+
+    /**
+     * Write many records in a single request and a single transaction.
+     *
+     * Built for imports and ETL, where one call per row means one HTTP round
+     * trip and one transaction per row. Every record still runs the normal
+     * pipeline — callbacks, relations, row-level security — and the batch is
+     * all-or-nothing: if any record is rejected, none of them land and the
+     * error names the offending index.
+     *
+     * A record carrying its primary key updates that row; one without inserts.
+     * With `{ upsert: true }` each record is written as INSERT ... ON CONFLICT
+     * DO UPDATE on the primary key instead, which is what makes a re-runnable
+     * import idempotent.
+     *
+     * Batches are capped server-side (1000 rows by default) because one batch
+     * holds its locks for the whole transaction — chunk larger jobs.
+     *
+     * @returns The written rows, in the order given.
+     *
+     * @example
+     * ```ts
+     * for (const chunk of chunks(rows, 1000)) {
+     *     await client.data.products.createMany(chunk, { upsert: true });
+     * }
+     * ```
+     */
+    createMany(data: I[], options?: { upsert?: boolean }): 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 interface RebaseData {
+export type RebaseData<DB = unknown> = {
     /**
      * Get a collection accessor by slug.
      * Alternative to dynamic property access for cases where
@@ -188,13 +403,89 @@ export interface RebaseData {
      * await accessor.find({ limit: 10 });
      */
     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 (the table's 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);
+        }
+);