@notionhq/custom-blocks 0.1.33 → 0.1.35

package/src/bridge/hostState.ts

@@ -41,17 +41,21 @@ export type InitializedHostState = {
 }
 
 export type DataSourceQueryState = {
+	dataSourceKey: string
 	/** Latest pages from the host as parsed from the bridge. `propertiesByKey` is derived lazily. */
 	items: NotionDataSourcePageBridge[]
 	isLoading: boolean
 	hasMore: boolean
 	error?: CustomBlockQueryDataSourceErrorInfo
-	subscriptionId?: string
 	latestLimit?: number
+	latestQueryIdentity?: string
 }
 
-export function createEmptyDataSourceQueryState(): DataSourceQueryState {
+export function createEmptyDataSourceQueryState(
+	dataSourceKey: string,
+): DataSourceQueryState {
 	return {
+		dataSourceKey,
 		items: [],
 		isLoading: false,
 		hasMore: false,
@@ -97,6 +101,7 @@ export type UpdateDataSourcePageFn = (args: {
 export function getDataSourceQueryView(
 	hostState: CustomBlockHostState,
 	key: string,
+	subscriptionId: string,
 	updateDataSourcePage: UpdateDataSourcePageFn,
 ): DataSourceQueryView {
 	if (hostState.status !== "initialized") {
@@ -104,8 +109,11 @@ export function getDataSourceQueryView(
 	}
 
 	const dataSource = hostState.dataSources.find(entry => entry.key === key)
+	const subscriptionState = hostState.dataSourceState[subscriptionId]
 	const queryState =
-		hostState.dataSourceState[key] ?? createEmptyDataSourceQueryState()
+		subscriptionState?.dataSourceKey === key
+			? subscriptionState
+			: createEmptyDataSourceQueryState(key)
 
 	if (dataSource === undefined) {
 		return {

package/src/bridge/sandboxClient.ts

@@ -68,16 +68,32 @@ export const customBlockHost = {
 }
 
 export const customBlockDataSources = {
-	query: (key: string, options?: UseDataSourceOptions) => {
-		getBridge().queryDataSource(key, options)
+	createSubscriptionId: () => {
+		return getBridge().createDataSourceSubscriptionId()
+	},
+
+	query: (
+		subscriptionId: string,
+		key: string,
+		options?: UseDataSourceOptions,
+	) => {
+		getBridge().queryDataSource(subscriptionId, key, options)
+	},
+
+	release: (subscriptionId: string) => {
+		getBridge().releaseDataSourceSubscription(subscriptionId)
 	},
 
 	getView: (
 		hostState: CustomBlockHostState,
 		key: string,
+		subscriptionId: string,
 	): DataSourceQueryView => {
-		return getDataSourceQueryViewWithBridge(hostState, key, args =>
-			getBridge().updateDataSourcePage(args),
+		return getDataSourceQueryViewWithBridge(
+			hostState,
+			key,
+			subscriptionId,
+			args => getBridge().updateDataSourcePage(args),
 		)
 	},
 }

package/src/react/useDataSource.ts

@@ -1,4 +1,5 @@
-import { useEffect } from "react"
+import { useEffect, useState } from "react"
+import { getDataSourceQueryOptionsIdentity } from "../bridge/dataSources/query.js"
 import { customBlockDataSources } from "../bridge/sandboxClient.js"
 import type { UseDataSourceOptions, UseDataSourceResult } from "../types.js"
 import { useCustomBlockHost } from "./useHostState.js"
@@ -8,7 +9,7 @@ import { useCustomBlockHost } from "./useHostState.js"
  *
  * @param key - The semantic data source key the block is wired to (e.g. `"people"`).
  * @param options - Optional live snapshot options. `limit` defaults to 20 and
- *   is capped at 999.
+ *   is capped at 999. `sorts` are applied in array order.
  *
  * @example
  * const { items, isLoading, hasMore, error } = useDataSource("default", { limit: 25 })
@@ -18,7 +19,10 @@ export function useDataSource(
 	options?: UseDataSourceOptions,
 ): UseDataSourceResult {
 	const host = useCustomBlockHost()
-	const limit = options?.limit
+	const [subscriptionId] = useState(() =>
+		customBlockDataSources.createSubscriptionId(),
+	)
+	const optionsIdentity = getDataSourceQueryOptionsIdentity(options)
 	const matchingDataSource =
 		host.status === "initialized"
 			? host.dataSources.find(dataSource => dataSource.key === key)
@@ -30,10 +34,17 @@ export function useDataSource(
 			return
 		}
 
-		customBlockDataSources.query(key, { limit })
-	}, [matchingDataSource, isInitialized, key, limit])
+		customBlockDataSources.query(subscriptionId, key, options)
+	}, [matchingDataSource, isInitialized, key, optionsIdentity, subscriptionId])
 
-	const view = customBlockDataSources.getView(host, key)
+	useEffect(
+		() => () => {
+			customBlockDataSources.release(subscriptionId)
+		},
+		[subscriptionId],
+	)
+
+	const view = customBlockDataSources.getView(host, key, subscriptionId)
 
 	return {
 		items: view.items,

package/src/types.ts

@@ -24,6 +24,14 @@ import type {
 	ListUsersMessage,
 	ListUsersResultMessage,
 } from "@notionhq/custom-blocks-protocol/messages/listUsers.js"
+import type {
+	CustomBlockCheckboxFilterOperator,
+	CustomBlockContainsFilterOperator,
+	CustomBlockDateFilterOperator,
+	CustomBlockNumberFilterOperator,
+	CustomBlockOptionFilterOperator,
+	CustomBlockTextFilterOperator,
+} from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
 import type { CustomBlockQueryDataSourceErrorInfo } from "@notionhq/custom-blocks-protocol/messages/queryDataSourceResult.js"
 import type { UpdatePageMessage } from "@notionhq/custom-blocks-protocol/messages/updatePage.js"
 import type {
@@ -116,6 +124,44 @@ export type NotionDataSourcePageUpdateInput = NotionDataSourcePageUpdateArgs
  */
 export type NotionDataSourcePageUpdateResult = UpdatePageResult
 
+export type NotionDataSourceTextFilterOperator = CustomBlockTextFilterOperator
+export type NotionDataSourceNumberFilterOperator =
+	CustomBlockNumberFilterOperator
+export type NotionDataSourceCheckboxFilterOperator =
+	CustomBlockCheckboxFilterOperator
+export type NotionDataSourceOptionFilterOperator =
+	CustomBlockOptionFilterOperator
+export type NotionDataSourceContainsFilterOperator =
+	CustomBlockContainsFilterOperator
+export type NotionDataSourceDateFilterOperator = CustomBlockDateFilterOperator
+
+export type NotionDataSourcePropertyAddress =
+	| { key: string; propertyId?: never }
+	| { propertyId: string; key?: never }
+
+export type NotionDataSourcePropertyFilter = NotionDataSourcePropertyAddress &
+	(
+		| { title: NotionDataSourceTextFilterOperator }
+		| { rich_text: NotionDataSourceTextFilterOperator }
+		| { url: NotionDataSourceTextFilterOperator }
+		| { email: NotionDataSourceTextFilterOperator }
+		| { phone_number: NotionDataSourceTextFilterOperator }
+		| { number: NotionDataSourceNumberFilterOperator }
+		| { checkbox: NotionDataSourceCheckboxFilterOperator }
+		| { select: NotionDataSourceOptionFilterOperator }
+		| { multi_select: NotionDataSourceContainsFilterOperator }
+		| { status: NotionDataSourceOptionFilterOperator }
+		| { date: NotionDataSourceDateFilterOperator }
+	)
+
+export type NotionDataSourceSort = NotionDataSourcePropertyAddress & {
+	direction: "ascending" | "descending"
+}
+
+export type NotionDataSourceFilter =
+	| NotionDataSourcePropertyFilter
+	| { and: NotionDataSourcePropertyFilter[] }
+
 /**
  * Return shape of `useDataSource`.
  *
@@ -157,6 +203,15 @@ export type UseDataSourceOptions = {
 	 * Maximum number of rows to request from the host. Defaults to 20.
 	 */
 	limit?: number
+	/**
+	 * Optional property filter. The SDK resolves semantic property keys before
+	 * it sends the query to the host.
+	 */
+	filter?: NotionDataSourceFilter
+	/**
+	 * Optional property sorts. The host applies them in array order.
+	 */
+	sorts?: NotionDataSourceSort[]
 }
 
 /**