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

package/dist/controllers/data.d.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;
 export interface LogicalCondition {
     type: "and" | "or";
@@ -13,19 +13,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"] }
@@ -34,16 +66,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;
 }
 /**
@@ -62,7 +102,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>> {
@@ -77,11 +123,13 @@ export interface QueryBuilderInterface<M extends Record<string, unknown> = Recor
     listen(onUpdate: (data: FindResponse<M>) => void, onError?: (error: Error) => void): () => void;
 }
 /**
- * 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
  */
@@ -101,6 +149,15 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      * @returns The created entity
      */
     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
@@ -110,10 +167,6 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      * Delete a record by ID.
      */
     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).
@@ -137,27 +190,171 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
     include(...relations: string[]): QueryBuilderInterface<M>;
 }
 /**
- * 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.
+ *
+ * @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.
  *
- * 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).
+ * 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, 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>;
+    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
@@ -168,12 +365,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: "eq.published" } })
+     * 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> = {
+    /**
+     * Get a flat collection accessor by slug.
+     *
+     * @example
+     * const accessor = data.collection("products");
+     * await accessor.find({ limit: 10 });
+     */
+    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);
+});

package/dist/controllers/data_driver.d.ts

@@ -1,20 +1,20 @@
-import type { Entity, EntityStatus, EntityValues } from "../types/entities";
-import type { EntityCollection, FilterValues } from "../types/collections";
+import type { EntityStatus, EntityValues } from "../types/entities";
+import type { CollectionConfig, FilterValues } from "../types/collections";
 import type { RebaseContext } from "../rebase_context";
 /**
  * @internal
  */
-export interface FetchEntityProps<M extends Record<string, unknown> = Record<string, unknown>> {
+export interface FetchOneProps<M extends Record<string, unknown> = Record<string, unknown>> {
     path: string;
-    entityId: string | number;
+    id: string | number;
     databaseId?: string;
-    collection?: EntityCollection<M>;
+    collection?: CollectionConfig<M>;
 }
 /**
  * @internal
  */
-export type ListenEntityProps<M extends Record<string, unknown> = Record<string, unknown>> = FetchEntityProps<M> & {
-    onUpdate: (entity: Entity<M> | null) => void;
+export type ListenOneProps<M extends Record<string, unknown> = Record<string, unknown>> = FetchOneProps<M> & {
+    onUpdate: (row: Record<string, unknown> | null) => void;
     onError?: (error: Error) => void;
 };
 /**
@@ -37,7 +37,7 @@ export interface VectorSearchParams {
  */
 export interface FetchCollectionProps<M extends Record<string, unknown> = Record<string, unknown>> {
     path: string;
-    collection?: EntityCollection<M>;
+    collection?: CollectionConfig<M>;
     filter?: FilterValues<Extract<keyof M, string>>;
     limit?: number;
     offset?: number;
@@ -52,38 +52,74 @@ export interface FetchCollectionProps<M extends Record<string, unknown> = Record
  * @internal
  */
 export type ListenCollectionProps<M extends Record<string, unknown> = Record<string, unknown>> = FetchCollectionProps<M> & {
-    onUpdate: (entities: Entity<M>[]) => void;
+    onUpdate: (rows: Record<string, unknown>[]) => void;
     onError?: (error: Error) => void;
 };
 /**
  * @internal
  */
-export interface SaveEntityProps<M extends Record<string, unknown> = Record<string, unknown>> {
+export interface SaveProps<M extends Record<string, unknown> = Record<string, unknown>> {
     path: string;
     values: Partial<EntityValues<M>>;
-    entityId?: string | number;
+    id?: string | number;
     previousValues?: Partial<EntityValues<M>>;
-    collection?: EntityCollection<M>;
+    collection?: CollectionConfig<M>;
     status: EntityStatus;
+    /**
+     * Write the row with INSERT ... ON CONFLICT DO UPDATE on the primary key
+     * instead of choosing between insert and update up front.
+     *
+     * One statement, so it does not lose the race a read-then-write can, and it
+     * succeeds whether or not the row is already there — what a re-runnable
+     * import needs. Requires every primary key column to be present; without
+     * them there is no conflict target and the row is inserted normally.
+     */
+    upsert?: boolean;
 }
 /**
  * @internal
  */
-export interface DeleteEntityProps<M extends Record<string, unknown> = Record<string, unknown>> {
-    entity: Entity<M>;
-    collection?: EntityCollection<M>;
+export interface SaveManyProps<M extends Record<string, unknown> = Record<string, unknown>> {
+    path: string;
+    /**
+     * The rows to write. A row carrying its primary key updates (or, with
+     * `upsert`, inserts-or-updates) that row; one without inserts.
+     */
+    rows: Partial<EntityValues<M>>[];
+    collection?: CollectionConfig<M>;
+    /** Apply every row as INSERT ... ON CONFLICT DO UPDATE. See {@link SaveProps.upsert}. */
+    upsert?: boolean;
+}
+/**
+ * @internal
+ */
+export interface DeleteProps<M extends Record<string, unknown> = Record<string, unknown>> {
+    row: {
+        id: string | number;
+        path: string;
+        values?: Partial<EntityValues<M>>;
+    };
+    collection?: CollectionConfig<M>;
 }
 export type FilterCombinationValidProps = {
     path: string;
     databaseId?: string;
-    collection: EntityCollection;
+    collection: CollectionConfig;
     filterValues: FilterValues<string>;
     sortBy?: [string, "asc" | "desc"];
 };
 /**
- * Internal driver interface for communicating with the data layer.
- * This is NOT the public API — use `RebaseData` / `context.data` instead.
- * @internal
+ * The integration SPI for plugging a data backend into Rebase.
+ *
+ * Implement this interface to connect a custom backend (or use a built-in
+ * driver such as the Firestore one) and register it on
+ * `<Rebase dataSources>`. Rebase wraps drivers via `buildRebaseData` and
+ * routes collections to them by their `dataSource` key.
+ *
+ * For *consuming* data in application code, use `RebaseData` /
+ * `context.data` instead — this interface is only for providing it.
+ *
+ * @group Datasource
  */
 export interface DataDriver {
     /**
@@ -97,9 +133,9 @@ export interface DataDriver {
     /**
      * Fetch data from a collection
      * @param props
-     * @return Promise of entities
+     * @return Promise of flat rows
      */
-    fetchCollection<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Entity<M>[]>;
+    fetchCollection<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Record<string, unknown>[]>;
     /**
      * Listen to a collection in a given path. If you don't implement this method
      * `fetchCollection` will be used instead, with no real time updates.
@@ -108,27 +144,40 @@ export interface DataDriver {
      */
     listenCollection?<M extends Record<string, unknown> = Record<string, unknown>>(props: ListenCollectionProps<M>): () => void;
     /**
-     * Retrieve an entity given a path and a collection
+     * Retrieve a single row given a path and a collection
      * @param props
      */
-    fetchEntity<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchEntityProps<M>): Promise<Entity<M> | undefined>;
+    fetchOne<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;
     /**
-     * Get realtime updates on one entity.
+     * Get realtime updates on one row.
      * @param props
      * @return Function to cancel subscription
      */
-    listenEntity?<M extends Record<string, unknown> = Record<string, unknown>>(props: ListenEntityProps<M>): () => void;
+    listenOne?<M extends Record<string, unknown> = Record<string, unknown>>(props: ListenOneProps<M>): () => void;
     /**
-     * Save entity to the specified path
+     * Save a row to the specified path
      * @param props
      */
-    saveEntity<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveEntityProps<M>): Promise<Entity<M>>;
+    save<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveProps<M>): Promise<Record<string, unknown>>;
+    /**
+     * Save many rows as one unit of work.
+     *
+     * Every row runs the same pipeline as {@link save} — callbacks, relations
+     * and row-level security all still apply — but they share a single
+     * transaction, so the batch either lands whole or not at all. That, and the
+     * single round trip, is what makes importing tens of thousands of rows
+     * viable without dropping to raw SQL.
+     *
+     * Optional: drivers that cannot do this leave it undefined and callers fall
+     * back to `save` per row.
+     */
+    saveMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveManyProps<M>): Promise<Record<string, unknown>[]>;
     /**
-     * Delete an entity
+     * Delete a entity
      * @param props
      * @return was the whole deletion flow successful
      */
-    deleteEntity<M extends Record<string, unknown> = Record<string, unknown>>(props: DeleteEntityProps<M>): Promise<void>;
+    delete<M extends Record<string, unknown> = Record<string, unknown>>(props: DeleteProps<M>): Promise<void>;
     /**
      * Delete all entities from a collection.
      * @param path Collection path
@@ -139,15 +188,15 @@ export interface DataDriver {
      * @param path Collection path
      * @param name of the property
      * @param value
-     * @param entityId
+     * @param id
      * @param collection
      * @return `true` if there are no other fields besides the given entity
      */
-    checkUniqueField(path: string, name: string, value: unknown, entityId?: string | number, collection?: EntityCollection): Promise<boolean>;
+    checkUniqueField(path: string, name: string, value: unknown, id?: string | number, collection?: CollectionConfig): Promise<boolean>;
     /**
      * Count the number of entities in a collection
      */
-    countEntities?<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;
+    count?<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;
     /**
      * Check if the given filter combination is valid
      * @param props
@@ -165,7 +214,7 @@ export interface DataDriver {
         context: RebaseContext;
         path: string;
         databaseId?: string;
-        collection: EntityCollection;
+        collection: CollectionConfig;
         parentCollectionSlugs?: string[];
         parentEntityIds?: string[];
     }) => Promise<boolean>;
@@ -175,7 +224,7 @@ export interface DataDriver {
     needsInitTextSearch?: boolean;
     /**
      * Optional REST-optimised fetch service. When present, the REST API
-     * generator uses these methods instead of the generic `fetchEntity` /
+     * generator uses these methods instead of the generic `fetchOne` /
      * `fetchCollection` pipeline, enabling include-aware eager-loading.
      */
     restFetchService?: RestFetchService;
@@ -191,8 +240,14 @@ export interface DataDriver {
  * REST-optimised fetch service exposed by drivers that support
  * eager-loading of relations via `include`.
  *
- * The methods return flattened rows (`{ id, ...columns }`) rather
- * than the `Entity<M>` wrapper used by the generic DataDriver API.
+ * The methods return flattened rows — exactly the table's columns, under their
+ * own names and with the types the database returned — and included relations
+ * inlined as plain nested rows. This is the shape served to app developers
+ * through the REST API / SDK client.
+ *
+ * No synthesized `id`: identity is a primary key, which may be named anything
+ * and span several columns, so an address is derived by whoever needs one (see
+ * `buildCompositeId`) rather than written into the row on top of the data.
  *
  * @group DataDriver
  */
@@ -214,5 +269,5 @@ export interface RestFetchService {
     /**
      * Fetch a single flattened entity with optional relation includes.
      */
-    fetchEntityForRest(collectionPath: string, entityId: string | number, include?: string[], databaseId?: string): Promise<Record<string, unknown> | null>;
+    fetchOneForRest(collectionPath: string, id: string | number, include?: string[], databaseId?: string): Promise<Record<string, unknown> | null>;
 }