@rebasepro/types 0.9.1-canary.1d2d8b5 → 0.9.1-canary.58368ce

package/dist/controllers/data.d.ts

@@ -149,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
@@ -262,10 +271,43 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
     /**
      * 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.
+     * @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).
@@ -345,7 +387,7 @@ export type RebaseData<DB = unknown> = {
  * - The frontend SDK client (`client.data.products.find()`)
  * - Backend framework callbacks & scripts (`context.data.products.find()`)
  *
- * Every accessor returns flat rows (`{ id, ...columns }`) via
+ * 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.
  *

package/dist/controllers/data_driver.d.ts

@@ -65,6 +65,30 @@ export interface SaveProps<M extends Record<string, unknown> = Record<string, un
     previousValues?: Partial<EntityValues<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 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
@@ -135,6 +159,19 @@ export interface DataDriver {
      * @param props
      */
     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 a entity
      * @param props
@@ -203,9 +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 }`) with
- * included relations inlined as plain nested rows — the shape served
- * to app developers through the REST API / SDK client.
+ * 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
  */

package/dist/types/entity_callbacks.d.ts

@@ -74,7 +74,7 @@ export interface AfterReadProps<M extends Record<string, unknown> = Record<strin
      */
     path: string;
     /**
-     * Fetched row (flat — `{ id, ...columns }`)
+     * Fetched row (flat — the table's columns)
      */
     row: Record<string, unknown>;
     /**
@@ -149,7 +149,7 @@ export interface BeforeDeleteProps<M extends Record<string, unknown> = Record<st
      */
     id: string | number;
     /**
-     * Deleted row (flat — `{ id, ...columns }`)
+     * Deleted row (flat — the table's columns)
      */
     row: Record<string, unknown>;
     /**
@@ -175,7 +175,7 @@ export interface AfterDeleteProps<M extends Record<string, unknown> = Record<str
      */
     id: string | number;
     /**
-     * Deleted row (flat — `{ id, ...columns }`)
+     * Deleted row (flat — the table's columns)
      */
     row: Record<string, unknown>;
     /**

package/dist/types/websockets.d.ts

@@ -15,10 +15,34 @@ export interface WebSocketMessage {
     row?: Record<string, unknown> | null;
     error?: string;
 }
+/**
+ * The key columns a collection's rows are addressed by.
+ *
+ * A row is exactly its columns and carries no address, so a subscriber that has
+ * to recognise one — to patch it, or to keep its reference across a refetch —
+ * derives the address from these. The SDK is usable with no collections
+ * declared at all, so the server is the only side that knows them.
+ *
+ * Undefined when the server cannot resolve them: a table with no primary key
+ * and no `id` column has no address, and rows of it cannot be recognised by
+ * anyone.
+ */
+export type WirePrimaryKeys = {
+    fieldName: string;
+    type: "string" | "number";
+    isUUID?: boolean;
+}[];
 export interface CollectionUpdateMessage extends WebSocketMessage {
     type: "collection_update";
     subscriptionId: string;
     rows: Record<string, unknown>[];
+    /**
+     * See {@link WirePrimaryKeys}. Sent with the rows themselves — and not only
+     * with a patch — because a CDC-originated change sends no patch at all: it
+     * invalidates and goes straight to a refetch, and the merge that preserves
+     * unchanged rows' references needs an address to match them by.
+     */
+    pks?: WirePrimaryKeys;
 }
 export interface SingleUpdateMessage extends WebSocketMessage {
     type: "single_update";
@@ -34,9 +58,12 @@ export interface SingleUpdateMessage extends WebSocketMessage {
 export interface CollectionPatchMessage extends WebSocketMessage {
     type: "collection_patch";
     subscriptionId: string;
+    /** The address of the row this patch refers to — derived, never read off it. */
     id: string;
     /** The updated row, or null if deleted */
     row: Record<string, unknown> | null;
+    /** See {@link WirePrimaryKeys}: how the subscriber finds {@link id} in its cache. */
+    pks?: WirePrimaryKeys;
 }
 /**
  * Column metadata returned by table introspection.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.9.1-canary.1d2d8b5",
+  "version": "0.9.1-canary.58368ce",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"

package/src/controllers/data.ts

@@ -161,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
@@ -294,11 +302,43 @@ export interface SDKCollectionClient<
     /**
      * 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.
+     * @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).
@@ -386,7 +426,7 @@ export type RebaseData<DB = unknown> = {
  * - The frontend SDK client (`client.data.products.find()`)
  * - Backend framework callbacks & scripts (`context.data.products.find()`)
  *
- * Every accessor returns flat rows (`{ id, ...columns }`) via
+ * 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.
  *

package/src/controllers/data_driver.ts

@@ -77,6 +77,31 @@ export interface SaveProps<M extends Record<string, unknown> = Record<string, un
     previousValues?: Partial<EntityValues<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 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;
 }
 
 /**
@@ -154,6 +179,20 @@ export interface DataDriver {
      */
     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 a entity
      * @param props
@@ -252,9 +291,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 }`) with
- * included relations inlined as plain nested rows — the shape served
- * to app developers through the REST API / SDK client.
+ * 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
  */

package/src/types/entity_callbacks.ts

@@ -91,7 +91,7 @@ export interface AfterReadProps<M extends Record<string, unknown> = Record<strin
     path: string;
 
     /**
-     * Fetched row (flat — `{ id, ...columns }`)
+     * Fetched row (flat — the table's columns)
      */
     row: Record<string, unknown>
 
@@ -185,7 +185,7 @@ export interface BeforeDeleteProps<M extends Record<string, unknown> = Record<st
     id: string | number;
 
     /**
-     * Deleted row (flat — `{ id, ...columns }`)
+     * Deleted row (flat — the table's columns)
      */
     row: Record<string, unknown>;
 
@@ -217,7 +217,7 @@ export interface AfterDeleteProps<M extends Record<string, unknown> = Record<str
     id: string | number;
 
     /**
-     * Deleted row (flat — `{ id, ...columns }`)
+     * Deleted row (flat — the table's columns)
      */
     row: Record<string, unknown>;
 

package/src/types/websockets.ts

@@ -14,10 +14,31 @@ export interface WebSocketMessage {
     error?: string;
 }
 
+/**
+ * The key columns a collection's rows are addressed by.
+ *
+ * A row is exactly its columns and carries no address, so a subscriber that has
+ * to recognise one — to patch it, or to keep its reference across a refetch —
+ * derives the address from these. The SDK is usable with no collections
+ * declared at all, so the server is the only side that knows them.
+ *
+ * Undefined when the server cannot resolve them: a table with no primary key
+ * and no `id` column has no address, and rows of it cannot be recognised by
+ * anyone.
+ */
+export type WirePrimaryKeys = { fieldName: string; type: "string" | "number"; isUUID?: boolean }[];
+
 export interface CollectionUpdateMessage extends WebSocketMessage {
     type: "collection_update";
     subscriptionId: string;
     rows: Record<string, unknown>[];
+    /**
+     * See {@link WirePrimaryKeys}. Sent with the rows themselves — and not only
+     * with a patch — because a CDC-originated change sends no patch at all: it
+     * invalidates and goes straight to a refetch, and the merge that preserves
+     * unchanged rows' references needs an address to match them by.
+     */
+    pks?: WirePrimaryKeys;
 }
 
 export interface SingleUpdateMessage extends WebSocketMessage {
@@ -35,9 +56,12 @@ export interface SingleUpdateMessage extends WebSocketMessage {
 export interface CollectionPatchMessage extends WebSocketMessage {
     type: "collection_patch";
     subscriptionId: string;
+    /** The address of the row this patch refers to — derived, never read off it. */
     id: string;
     /** The updated row, or null if deleted */
     row: Record<string, unknown> | null;
+    /** See {@link WirePrimaryKeys}: how the subscriber finds {@link id} in its cache. */
+    pks?: WirePrimaryKeys;
 }
 
 /**