@visus-io/notion-sdk-ts 3.1.0 → 3.2.0

package/dist/helpers/block.helpers.d.ts

@@ -2,7 +2,9 @@ import type { CodeBlockLanguage, NotionColor, NotionRichText } from '../schemas'
 import { RichTextBuilder } from './richText.helpers';
 /**
  * Accepted rich text input: a plain string, a {@link RichTextBuilder}, or
- * a pre-built `NotionRichText` array.
+ * a pre-built `NotionRichText`.
+ *
+ * @category Rich Text
  */
 export type RichTextInput = string | RichTextBuilder | NotionRichText;
 /** Common options shared by text-bearing blocks. */
@@ -10,7 +12,7 @@ interface TextBlockOptions {
     color?: NotionColor;
     children?: unknown[];
 }
-/** The minimal block object accepted by the Notion API for creation. */
+/** The Notion API accepts this minimal block object for creation. */
 interface BlockObject {
     object: 'block';
     type: string;
@@ -18,7 +20,7 @@ interface BlockObject {
 }
 /** Options for paragraph blocks. */
 interface ParagraphOptions extends TextBlockOptions {
-    /** Icon shown alongside the paragraph. Only meaningful for paragraphs used as tab items. */
+    /** Icon for the paragraph. Applies only to paragraphs used as tab items. */
     icon?: unknown;
 }
 /**
@@ -72,12 +74,12 @@ declare function template(text: RichTextInput, options?: {
     children?: unknown[];
 }): BlockObject;
 /**
- * @deprecated Meeting-notes blocks are server-managed -- their real shape (`title`,
- * `status`, and child block IDs for the summary/notes/transcript) is populated by
- * Notion, not hand-constructed by clients. This helper's `rich_text`-based output no
- * longer matches `blockSchema`'s `meeting_notes` shape and is not a valid way to
- * create a meeting-notes block. Kept only to avoid an abrupt removal from the helper
- * surface; do not use for new code.
+ * @deprecated Notion manages meeting-notes blocks on the server. Notion populates the
+ * real shape (`title`, `status`, and child block IDs for the summary, notes, and
+ * transcript). Clients do not construct this shape by hand. This helper's
+ * `rich_text`-based output no longer matches the `meeting_notes` shape in
+ * `blockSchema`. Do not use this helper to create a meeting-notes block. It remains
+ * only to avoid an abrupt removal from the helper surface. Do not use it in new code.
  */
 declare function meetingNotes(text: RichTextInput, options?: {
     children?: unknown[];
@@ -129,7 +131,10 @@ declare function table(width: number, options?: TableOptions): BlockObject;
 declare function tableRow(cells: RichTextInput[]): BlockObject;
 declare function columnList(columns: unknown[][]): BlockObject;
 declare function column(children: unknown[]): BlockObject;
-/** A single tab: its label becomes the tab's paragraph rich text, `children` its content. */
+/**
+ * A single tab. Its label becomes the tab's paragraph rich text.
+ * Its `children` become the tab's content.
+ */
 interface TabItem {
     label: RichTextInput;
     icon?: unknown;
@@ -137,9 +142,9 @@ interface TabItem {
     children?: unknown[];
 }
 /**
- * Create a tab block. Only `paragraph` blocks may be direct children of a tab block --
- * each tab is modeled as one paragraph, whose rich text is the tab label and whose
- * `children` hold the tab's content.
+ * Create a tab block. A tab block accepts only `paragraph` blocks as direct children.
+ * Each tab is one paragraph. The paragraph's rich text holds the tab label. The
+ * paragraph's `children` hold the tab's content.
  *
  * @example
  * ```ts
@@ -161,9 +166,9 @@ declare function syncedBlock(options?: {
     children?: unknown[];
 }): BlockObject;
 /**
- * Factory functions for constructing Notion block objects.
+ * Factory functions that create Notion block objects.
  *
- * Every function returns a plain object ready to pass to
+ * Every function returns a plain object. Pass this object to
  * `blocks.children.append()` or `pages.create()`.
  *
  * @example
@@ -189,6 +194,8 @@ declare function syncedBlock(options?: {
  *   }),
  * ];
  * ```
+ *
+ * @category Helpers
  */
 export declare const block: {
     paragraph: typeof paragraph;

package/dist/helpers/block.helpers.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.block = void 0;
 const validation_1 = require("../validation");
 const richText_helpers_1 = require("./richText.helpers");
-/** Resolve a {@link RichTextInput} into a `NotionRichText` array. */
+/** Resolve a {@link RichTextInput} into a `NotionRichText`. */
 function resolveRichText(input) {
     if (typeof input === 'string') {
         (0, validation_1.validateStringLength)(input, validation_1.LIMITS.RICH_TEXT_CONTENT, 'Rich text content');
@@ -181,12 +181,12 @@ function template(text, options) {
     };
 }
 /**
- * @deprecated Meeting-notes blocks are server-managed -- their real shape (`title`,
- * `status`, and child block IDs for the summary/notes/transcript) is populated by
- * Notion, not hand-constructed by clients. This helper's `rich_text`-based output no
- * longer matches `blockSchema`'s `meeting_notes` shape and is not a valid way to
- * create a meeting-notes block. Kept only to avoid an abrupt removal from the helper
- * surface; do not use for new code.
+ * @deprecated Notion manages meeting-notes blocks on the server. Notion populates the
+ * real shape (`title`, `status`, and child block IDs for the summary, notes, and
+ * transcript). Clients do not construct this shape by hand. This helper's
+ * `rich_text`-based output no longer matches the `meeting_notes` shape in
+ * `blockSchema`. Do not use this helper to create a meeting-notes block. It remains
+ * only to avoid an abrupt removal from the helper surface. Do not use it in new code.
  */
 function meetingNotes(text, options) {
     return {
@@ -367,9 +367,9 @@ function column(children) {
     };
 }
 /**
- * Create a tab block. Only `paragraph` blocks may be direct children of a tab block --
- * each tab is modeled as one paragraph, whose rich text is the tab label and whose
- * `children` hold the tab's content.
+ * Create a tab block. A tab block accepts only `paragraph` blocks as direct children.
+ * Each tab is one paragraph. The paragraph's rich text holds the tab label. The
+ * paragraph's `children` hold the tab's content.
  *
  * @example
  * ```ts
@@ -411,9 +411,9 @@ function syncedBlock(options) {
 // Public export
 // ---------------------------------------------------------------------------
 /**
- * Factory functions for constructing Notion block objects.
+ * Factory functions that create Notion block objects.
  *
- * Every function returns a plain object ready to pass to
+ * Every function returns a plain object. Pass this object to
  * `blocks.children.append()` or `pages.create()`.
  *
  * @example
@@ -439,6 +439,8 @@ function syncedBlock(options) {
  *   }),
  * ];
  * ```
+ *
+ * @category Helpers
  */
 exports.block = {
     // Text blocks

package/dist/helpers/file.helpers.d.ts

@@ -74,8 +74,8 @@ declare function nativeIcon(name: string, color?: NativeIconColor): NativeIconRe
  */
 declare function customEmojiIcon(id: string): CustomEmojiIconRef;
 /**
- * Helpers for constructing icon objects (emoji, external URL, file upload,
- * native icon, or custom emoji).
+ * Helpers that create icon objects: emoji, external URL, file upload, native
+ * icon, or custom emoji.
  *
  * @example
  * ```ts
@@ -87,6 +87,8 @@ declare function customEmojiIcon(id: string): CustomEmojiIconRef;
  *   // ...
  * });
  * ```
+ *
+ * @category Helpers
  */
 export declare const icon: {
     emoji: typeof emojiIcon;
@@ -114,7 +116,7 @@ declare function externalCover(url: string): ExternalRef;
  */
 declare function fileUploadCover(id: string): FileUploadRef;
 /**
- * Helpers for constructing cover image objects.
+ * Helpers that create cover image objects.
  *
  * @example
  * ```ts
@@ -126,6 +128,8 @@ declare function fileUploadCover(id: string): FileUploadRef;
  *   // ...
  * });
  * ```
+ *
+ * @category Helpers
  */
 export declare const cover: {
     external: typeof externalCover;
@@ -150,10 +154,10 @@ declare function externalFile(url: string): ExternalRef;
  */
 declare function uploadFile(id: string): FileUploadRef;
 /**
- * Helpers for constructing general Notion file objects.
+ * Helpers that create general Notion file objects.
  *
- * Useful for file blocks, image blocks, audio blocks, video blocks,
- * and file property entries.
+ * Use these helpers for file blocks, image blocks, audio blocks, video
+ * blocks, and file property entries.
  *
  * @example
  * ```ts
@@ -162,6 +166,8 @@ declare function uploadFile(id: string): FileUploadRef;
  * notionFile.external('https://example.com/doc.pdf')
  * notionFile.upload('upload-id')
  * ```
+ *
+ * @category Helpers
  */
 export declare const notionFile: {
     external: typeof externalFile;

package/dist/helpers/file.helpers.js

@@ -60,8 +60,8 @@ function customEmojiIcon(id) {
     return { type: 'custom_emoji', custom_emoji: { id } };
 }
 /**
- * Helpers for constructing icon objects (emoji, external URL, file upload,
- * native icon, or custom emoji).
+ * Helpers that create icon objects: emoji, external URL, file upload, native
+ * icon, or custom emoji.
  *
  * @example
  * ```ts
@@ -73,6 +73,8 @@ function customEmojiIcon(id) {
  *   // ...
  * });
  * ```
+ *
+ * @category Helpers
  */
 exports.icon = {
     emoji: emojiIcon,
@@ -107,7 +109,7 @@ function fileUploadCover(id) {
     return { type: 'file_upload', file_upload: { id } };
 }
 /**
- * Helpers for constructing cover image objects.
+ * Helpers that create cover image objects.
  *
  * @example
  * ```ts
@@ -119,6 +121,8 @@ function fileUploadCover(id) {
  *   // ...
  * });
  * ```
+ *
+ * @category Helpers
  */
 exports.cover = {
     external: externalCover,
@@ -150,10 +154,10 @@ function uploadFile(id) {
     return { type: 'file_upload', file_upload: { id } };
 }
 /**
- * Helpers for constructing general Notion file objects.
+ * Helpers that create general Notion file objects.
  *
- * Useful for file blocks, image blocks, audio blocks, video blocks,
- * and file property entries.
+ * Use these helpers for file blocks, image blocks, audio blocks, video
+ * blocks, and file property entries.
  *
  * @example
  * ```ts
@@ -162,6 +166,8 @@ function uploadFile(id) {
  * notionFile.external('https://example.com/doc.pdf')
  * notionFile.upload('upload-id')
  * ```
+ *
+ * @category Helpers
  */
 exports.notionFile = {
     external: externalFile,

package/dist/helpers/filter.helpers.d.ts

@@ -157,6 +157,8 @@ declare function or(...conditions: FilterCondition[]): FilterCondition;
  *   ),
  * });
  * ```
+ *
+ * @category Helpers
  */
 export declare const filter: {
     text: (property: string) => TextFilter;

package/dist/helpers/filter.helpers.js

@@ -305,6 +305,8 @@ function or(...conditions) {
  *   ),
  * });
  * ```
+ *
+ * @category Helpers
  */
 exports.filter = {
     // Property filters

package/dist/helpers/pagination.helpers.d.ts

@@ -1,10 +1,10 @@
 import type { PaginatedList } from '../schemas';
 /**
- * Pagination helper utilities for collecting all results from paginated Notion API endpoints.
+ * Pagination helpers that collect all results from paginated Notion API endpoints.
  *
- * The Notion API uses cursor-based pagination. All list endpoints return a `PaginatedList<T>`
- * with `results`, `next_cursor`, and `has_more` properties. These helpers automate the process
- * of fetching all pages.
+ * The Notion API uses cursor-based pagination. Each list endpoint returns a
+ * `PaginatedList<T>` object with `results`, `next_cursor`, and `has_more` properties.
+ * These helpers fetch every page automatically.
  *
  * @example
  * ```typescript
@@ -35,14 +35,16 @@ import type { PaginatedList } from '../schemas';
  */
 /**
  * Fetch function that returns a paginated list.
- * Receives an optional cursor and returns the next page of results.
+ * This function receives an optional cursor. It returns the next page of results.
+ *
+ * @category Pagination
  */
 export type PaginatedFetchFunction<T> = (cursor?: string) => Promise<PaginatedList<T>>;
 /**
  * Collects all results from a paginated endpoint by automatically following cursors.
  *
- * This function will keep fetching pages until `has_more` is `false`, collecting all
- * results into a single array. Use this when you need all results at once.
+ * This function fetches pages until `has_more` is `false`. It collects all results
+ * into one array. Use this function when you need all results at once.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Array containing all results from all pages
@@ -82,14 +84,16 @@ export type PaginatedFetchFunction<T> = (cursor?: string) => Promise<PaginatedLi
  *   })
  * );
  * ```
+ *
+ * @category Pagination
  */
 export declare function paginate<T>(fetchPage: PaginatedFetchFunction<T>): Promise<T[]>;
 /**
  * Creates an async iterator that yields individual items from paginated results.
  *
- * This function provides memory-efficient iteration over large result sets by fetching
- * one page at a time and yielding items as needed. Use this with `for await...of` when
- * you want to process results one by one without loading everything into memory.
+ * This function iterates over large result sets without loading everything into
+ * memory. It fetches one page at a time and yields items as needed. Use this function
+ * with `for await...of` to process results one at a time.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @yields Individual items from each page
@@ -124,13 +128,15 @@ export declare function paginate<T>(fetchPage: PaginatedFetchFunction<T>): Promi
  *   console.log(result.url);
  * }
  * ```
+ *
+ * @category Pagination
  */
 export declare function paginateIterator<T>(fetchPage: PaginatedFetchFunction<T>): AsyncGenerator<T, void, undefined>;
 /**
- * Collects all results and returns both the items and pagination metadata.
+ * Collects all results. Returns the items together with pagination metadata.
  *
- * This function is useful when you need to know how many pages were fetched
- * or want to track the total number of API calls made.
+ * Use this function when you need the page count or the total number of API
+ * calls.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Object containing all results and pagination metadata
@@ -143,6 +149,8 @@ export declare function paginateIterator<T>(fetchPage: PaginatedFetchFunction<T>
  *
  * console.log(`Fetched ${totalCount} blocks across ${pageCount} pages`);
  * ```
+ *
+ * @category Pagination
  */
 export declare function paginateWithMetadata<T>(fetchPage: PaginatedFetchFunction<T>): Promise<{
     items: T[];
@@ -150,29 +158,33 @@ export declare function paginateWithMetadata<T>(fetchPage: PaginatedFetchFunctio
     totalCount: number;
 }>;
 /**
- * Fetch function for windowed row collection. Same as {@link PaginatedFetchFunction} plus
- * a second parameter carrying the ISO 8601 `created_time` lower bound for the *next*
- * window, present once the previous window was capped at the query result limit
- * (`request_status.type === 'incomplete'`). The caller merges this into their own
- * created_time-ascending query, e.g. `filter.createdTime('Created time').onOrAfter(createdTimeCursor)`.
+ * Fetch function for windowed row collection. It extends
+ * {@link PaginatedFetchFunction} with a second parameter: the ISO 8601
+ * `created_time` lower bound for the next window. This parameter appears only
+ * after the previous window hits the query result limit
+ * (`request_status.type === 'incomplete'`). Merge this bound into your own
+ * created_time-ascending query, for example
+ * `filter.createdTime().onOrAfter(createdTimeCursor)`.
+ *
+ * @category Pagination
  */
 export type WindowedFetchFunction<T extends {
     id: string;
     createdTime: Date;
 }> = (cursor: string | undefined, createdTimeCursor: string | undefined) => Promise<PaginatedList<T>>;
 /**
- * Iterates over every row of a data source query, transparently working around the
- * API's 10,000-result-per-query cap.
- *
- * Data source (and view) queries cap at 10,000 results; when capped, the response's
- * `has_more` is still `false`, so following `next_cursor`/`has_more` alone silently
- * truncates the result set. When a window is capped (`request_status.type ===
- * 'incomplete'`), this starts a new query filtered to `created_time >=` the last row
- * seen, de-duplicating by `id` across the window boundary. Requires the query to be
- * sorted by `created_time` ascending.
- *
- * @param fetchWindow - Function that fetches one page, given the current cursor and
- * (once a window has been capped) a `created_time` lower bound for the next window
+ * Iterates over every row of a data source query. It works around the API's
+ * 10,000-result-per-query cap.
+ *
+ * Data source and view queries cap at 10,000 results. When a query hits this cap, the
+ * response's `has_more` field is still `false`. Following `next_cursor` and `has_more`
+ * alone silently truncates the result set. When a window hits the cap
+ * (`request_status.type === 'incomplete'`), this function starts a new query filtered
+ * to `created_time >=` the last row seen. It de-duplicates rows by `id` across the
+ * window boundary. The query must sort by `created_time` in ascending order.
+ *
+ * @param fetchWindow - Function that fetches one page. Pass the current cursor. After
+ * a window hits the cap, also pass a `created_time` lower bound for the next window.
  * @yields Individual rows across all windows
  *
  * @example
@@ -182,24 +194,28 @@ export type WindowedFetchFunction<T extends {
  *     start_cursor: cursor,
  *     sorts: [{ timestamp: 'created_time', direction: 'ascending' }],
  *     filter: createdTimeCursor
- *       ? filter.and(baseFilter, filter.createdTime('Created time').onOrAfter(createdTimeCursor))
+ *       ? filter.and(baseFilter, filter.createdTime().onOrAfter(createdTimeCursor))
  *       : baseFilter,
  *   }),
  * );
  * ```
+ *
+ * @category Pagination
  */
 export declare function iterateAllDataSourceRows<T extends {
     id: string;
     createdTime: Date;
 }>(fetchWindow: WindowedFetchFunction<T>): AsyncGenerator<T, void, undefined>;
 /**
- * Collects every row of a data source query into an array, transparently working
- * around the API's 10,000-result-per-query cap. See {@link iterateAllDataSourceRows}
- * for the windowing behavior.
+ * Collects every row of a data source query into an array. It works around the API's
+ * 10,000-result-per-query cap. See {@link iterateAllDataSourceRows} for the windowing
+ * behavior.
  *
- * @param fetchWindow - Function that fetches one page, given the current cursor and
- * (once a window has been capped) a `created_time` lower bound for the next window
+ * @param fetchWindow - Function that fetches one page. Pass the current cursor. After
+ * a window hits the cap, also pass a `created_time` lower bound for the next window.
  * @returns Array containing all rows across all windows
+ *
+ * @category Pagination
  */
 export declare function collectAllDataSourceRows<T extends {
     id: string;

package/dist/helpers/pagination.helpers.js

@@ -8,8 +8,8 @@ exports.collectAllDataSourceRows = collectAllDataSourceRows;
 /**
  * Collects all results from a paginated endpoint by automatically following cursors.
  *
- * This function will keep fetching pages until `has_more` is `false`, collecting all
- * results into a single array. Use this when you need all results at once.
+ * This function fetches pages until `has_more` is `false`. It collects all results
+ * into one array. Use this function when you need all results at once.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Array containing all results from all pages
@@ -49,6 +49,8 @@ exports.collectAllDataSourceRows = collectAllDataSourceRows;
  *   })
  * );
  * ```
+ *
+ * @category Pagination
  */
 async function paginate(fetchPage) {
     const all = [];
@@ -63,9 +65,9 @@ async function paginate(fetchPage) {
 /**
  * Creates an async iterator that yields individual items from paginated results.
  *
- * This function provides memory-efficient iteration over large result sets by fetching
- * one page at a time and yielding items as needed. Use this with `for await...of` when
- * you want to process results one by one without loading everything into memory.
+ * This function iterates over large result sets without loading everything into
+ * memory. It fetches one page at a time and yields items as needed. Use this function
+ * with `for await...of` to process results one at a time.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @yields Individual items from each page
@@ -100,6 +102,8 @@ async function paginate(fetchPage) {
  *   console.log(result.url);
  * }
  * ```
+ *
+ * @category Pagination
  */
 async function* paginateIterator(fetchPage) {
     let cursor;
@@ -112,10 +116,10 @@ async function* paginateIterator(fetchPage) {
     } while (cursor);
 }
 /**
- * Collects all results and returns both the items and pagination metadata.
+ * Collects all results. Returns the items together with pagination metadata.
  *
- * This function is useful when you need to know how many pages were fetched
- * or want to track the total number of API calls made.
+ * Use this function when you need the page count or the total number of API
+ * calls.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Object containing all results and pagination metadata
@@ -128,6 +132,8 @@ async function* paginateIterator(fetchPage) {
  *
  * console.log(`Fetched ${totalCount} blocks across ${pageCount} pages`);
  * ```
+ *
+ * @category Pagination
  */
 async function paginateWithMetadata(fetchPage) {
     const items = [];
@@ -146,18 +152,18 @@ async function paginateWithMetadata(fetchPage) {
     };
 }
 /**
- * Iterates over every row of a data source query, transparently working around the
- * API's 10,000-result-per-query cap.
- *
- * Data source (and view) queries cap at 10,000 results; when capped, the response's
- * `has_more` is still `false`, so following `next_cursor`/`has_more` alone silently
- * truncates the result set. When a window is capped (`request_status.type ===
- * 'incomplete'`), this starts a new query filtered to `created_time >=` the last row
- * seen, de-duplicating by `id` across the window boundary. Requires the query to be
- * sorted by `created_time` ascending.
- *
- * @param fetchWindow - Function that fetches one page, given the current cursor and
- * (once a window has been capped) a `created_time` lower bound for the next window
+ * Iterates over every row of a data source query. It works around the API's
+ * 10,000-result-per-query cap.
+ *
+ * Data source and view queries cap at 10,000 results. When a query hits this cap, the
+ * response's `has_more` field is still `false`. Following `next_cursor` and `has_more`
+ * alone silently truncates the result set. When a window hits the cap
+ * (`request_status.type === 'incomplete'`), this function starts a new query filtered
+ * to `created_time >=` the last row seen. It de-duplicates rows by `id` across the
+ * window boundary. The query must sort by `created_time` in ascending order.
+ *
+ * @param fetchWindow - Function that fetches one page. Pass the current cursor. After
+ * a window hits the cap, also pass a `created_time` lower bound for the next window.
  * @yields Individual rows across all windows
  *
  * @example
@@ -167,14 +173,21 @@ async function paginateWithMetadata(fetchPage) {
  *     start_cursor: cursor,
  *     sorts: [{ timestamp: 'created_time', direction: 'ascending' }],
  *     filter: createdTimeCursor
- *       ? filter.and(baseFilter, filter.createdTime('Created time').onOrAfter(createdTimeCursor))
+ *       ? filter.and(baseFilter, filter.createdTime().onOrAfter(createdTimeCursor))
  *       : baseFilter,
  *   }),
  * );
  * ```
+ *
+ * @category Pagination
  */
 async function* iterateAllDataSourceRows(fetchWindow) {
-    const seenIds = new Set();
+    // Rows repeat across a window boundary only when they share the exact `created_time`
+    // used as the next window's lower bound (results are sorted ascending by created_time,
+    // so ties are always contiguous). Tracking only that trailing tie group -- instead of
+    // every id ever yielded -- keeps memory bounded regardless of result set size.
+    let tailTimeMs;
+    let tailIds = new Set();
     let cursor;
     let createdTimeCursor;
     let lastCreatedTime;
@@ -183,10 +196,15 @@ async function* iterateAllDataSourceRows(fetchWindow) {
         const response = await fetchWindow(cursor, createdTimeCursor);
         let yieldedThisWindow = false;
         for (const item of response.results) {
-            if (seenIds.has(item.id)) {
+            const itemTimeMs = item.createdTime.getTime();
+            if (tailTimeMs !== undefined && itemTimeMs === tailTimeMs && tailIds.has(item.id)) {
                 continue;
             }
-            seenIds.add(item.id);
+            if (tailTimeMs === undefined || itemTimeMs > tailTimeMs) {
+                tailTimeMs = itemTimeMs;
+                tailIds = new Set();
+            }
+            tailIds.add(item.id);
             lastCreatedTime = item.createdTime;
             yieldedThisWindow = true;
             yield item;
@@ -214,13 +232,15 @@ async function* iterateAllDataSourceRows(fetchWindow) {
     }
 }
 /**
- * Collects every row of a data source query into an array, transparently working
- * around the API's 10,000-result-per-query cap. See {@link iterateAllDataSourceRows}
- * for the windowing behavior.
+ * Collects every row of a data source query into an array. It works around the API's
+ * 10,000-result-per-query cap. See {@link iterateAllDataSourceRows} for the windowing
+ * behavior.
  *
- * @param fetchWindow - Function that fetches one page, given the current cursor and
- * (once a window has been capped) a `created_time` lower bound for the next window
+ * @param fetchWindow - Function that fetches one page. Pass the current cursor. After
+ * a window hits the cap, also pass a `created_time` lower bound for the next window.
  * @returns Array containing all rows across all windows
+ *
+ * @category Pagination
  */
 async function collectAllDataSourceRows(fetchWindow) {
     const all = [];

package/dist/helpers/parent.helpers.d.ts

@@ -22,8 +22,8 @@ declare function database(databaseId: string): {
 };
 /**
  * Create a data source parent object.
- * Both data_source_id and database_id are required when creating a page
- * with a data source parent.
+ * A page with a data source parent needs both `data_source_id` and
+ * `database_id`.
  *
  * @example
  * ```ts
@@ -51,7 +51,7 @@ declare function workspace(): {
     workspace: true;
 };
 /**
- * Create a block parent object (used for comments on blocks).
+ * Create a block parent object for comments on blocks.
  *
  * @example
  * ```ts
@@ -86,6 +86,8 @@ declare function blockParent(blockId: string): {
  *   rich_text: [...],
  * });
  * ```
+ *
+ * @category Helpers
  */
 export declare const parent: {
     page: typeof page;