@rebasepro/common 0.11.1-canary.gfd39654 → 0.12.0

package/dist/data/buildRebaseData.d.ts

@@ -28,10 +28,10 @@ export declare function buildRebaseData(driver: DataDriver, options?: EntityData
 /**
  * Wrap a flat {@link RebaseSdkData} into a Entity-shaped {@link RebaseData}.
  *
- * This is the **CMS boundary**: the SDK client (`client.data`) returns flat
+ * This is the **admin boundary**: the SDK client (`client.data`) returns flat
  * rows, but the admin renders the `Entity` view-model (`entity.values.*`).
  * `core/Rebase.tsx` wraps `client.data` through this before handing it to the
- * CMS `RebaseDataContext` — without it the admin renders rows with only their
+ * admin `RebaseDataContext` — without it the admin renders rows with only their
  * `id`.
  */
 export declare function wrapAsEntityData(sdkData: RebaseSdkData, options?: EntityDataOptions): RebaseData;
@@ -49,7 +49,11 @@ export declare function wrapAsSdkData(entityData: RebaseData): RebaseSdkData;
  *
  * This is the developer-facing SDK data layer used by backend framework
  * callbacks & scripts (`context.data` / `rebase.data`). It returns flat rows —
- * identical in shape to the frontend SDK client — so the API is symmetric
- * across front and back. The admin CMS uses {@link buildRebaseData} (Entity).
+ * identical in shape to the frontend SDK client, down to how a relation is
+ * served: a foreign key stays a foreign key, and a relation named in `include`
+ * arrives as the target's own columns. The `{ __type: "relation" }` envelope is
+ * the admin's view-model and never reaches here.
+ *
+ * The admin uses {@link buildRebaseData} (Entity) over its own driver.
  */
 export declare function buildSdkData(driver: DataDriver): RebaseSdkData;

package/dist/data/paginate.d.ts

@@ -0,0 +1,75 @@
+import { FindAllParams, FindParams, FindResult, IterateParams } from "@rebasepro/types";
+/**
+ * The pagination engine behind `iterate()` / `findAll()`.
+ *
+ * It lives here, above both transports, on purpose: the HTTP client and the
+ * in-process accessor implement the same `SDKCollectionClient` contract, and a
+ * helper written twice is a helper that drifts. Both call into this file, so
+ * "the SDK paginates like *this*" has exactly one definition.
+ *
+ * Everything below is expressed in terms of a single `find(params)` function,
+ * which is all either transport has to supply.
+ */
+/** Rows requested per page when the caller does not say. */
+export declare const DEFAULT_PAGE_SIZE = 200;
+/** Rows `findAll()` will materialise before it refuses to continue. */
+export declare const DEFAULT_FIND_ALL_MAX_ROWS = 10000;
+/**
+ * Requests one walk may make before it gives up on the server ever saying
+ * `hasMore: false`. At the default page size that is two million rows — far
+ * past any legitimate walk, and short of running forever.
+ */
+export declare const DEFAULT_MAX_PAGES = 10000;
+/** Why a pagination walk refused to continue. */
+export type PaginationErrorCode = 
+/** `findAll()` matched more rows than its ceiling allows. */
+"max-rows"
+/** The walk made its maximum number of requests without the server finishing. */
+ | "max-pages"
+/** A cursor row carried no value for the cursor column. */
+ | "cursor-missing"
+/** Two consecutive pages ended on the same cursor value, so the walk cannot advance. */
+ | "cursor-stalled"
+/** A `cursor` was asked for on one column while `orderBy` sorted by another. */
+ | "cursor-order-mismatch";
+/**
+ * Thrown when a walk stops for a reason the caller needs to know about.
+ *
+ * Every one of these is a case where the alternative would be silent: a
+ * truncated array that looks complete, or a loop that never returns. Check
+ * {@link code} to tell them apart.
+ */
+export declare class RebasePaginationError extends Error {
+    readonly code: PaginationErrorCode;
+    constructor(code: PaginationErrorCode, message: string);
+}
+/** 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>>;
+/**
+ * Walk every row a query matches, yielding one row at a time and fetching the
+ * next page only when the consumer asks for it.
+ *
+ * See {@link SDKCollectionClient.iterate} for the caller-facing contract,
+ * including the offset-drift caveat and the `cursor` alternative.
+ *
+ * @param find   the transport's single-page read
+ * @param params `find()` parameters minus the window, plus the walk options
+ * @param label  the collection name, so an error says which walk failed
+ */
+export declare function paginateFind<M extends Record<string, unknown> = Record<string, unknown>>(find: PageFinder<M>, params?: IterateParams<M>, label?: string): AsyncGenerator<M, void, undefined>;
+/**
+ * {@link paginateFind}, collected into an array under a ceiling.
+ *
+ * See {@link SDKCollectionClient.findAll}.
+ */
+export declare function collectAllPages<M extends Record<string, unknown> = Record<string, unknown>>(find: PageFinder<M>, params?: FindAllParams<M>, label?: string): Promise<M[]>;
+/**
+ * Build the `iterate` / `findAll` pair for one collection from its `find`.
+ *
+ * Both transports call this, which is what keeps the two implementations from
+ * being two implementations.
+ */
+export declare function createPaginationHelpers<M extends Record<string, unknown> = Record<string, unknown>>(find: PageFinder<M>, label: string): {
+    iterate: (params?: IterateParams<M>) => AsyncIterableIterator<M>;
+    findAll: (params?: FindAllParams<M>) => Promise<M[]>;
+};

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from "./data/buildRebaseData";
 export * from "./data/buildRoutedRebaseData";
 export * from "./data/resolveDataSource";
 export * from "./data/query_builder";
+export * from "./data/paginate";
 export * from "./data/filter-dialect";
 export * from "./data/sort-dialect";
 export * from "./table-classification";