@notionhq/custom-blocks 0.1.43 → 0.1.44

package/src/bridge/dataSources/subscribe.ts

@@ -0,0 +1,97 @@
+import type { SubscribeToDataSourceArgs } from "../../types.js"
+import type {
+	CustomBlockHostState,
+	InitializedHostState,
+} from "../hostState.js"
+import { notifyListener } from "../notifyListener.js"
+import { customBlockDataSources, customBlockHost } from "../sandboxClient.js"
+
+export function subscribeToDataSource({
+	key,
+	onSnapshot,
+	options: providedOptions = {},
+}: SubscribeToDataSourceArgs): () => void {
+	const options = structuredClone(providedOptions)
+	const subscriptionId = customBlockDataSources.createSubscriptionId()
+	let active = true
+	let lastSnapshotInputs:
+		| {
+				status: CustomBlockHostState["status"]
+				dataSource: InitializedHostState["dataSources"][number] | undefined
+				queryState: InitializedHostState["dataSourceState"][string] | undefined
+		  }
+		| undefined
+	let lastMatchingSignature: string | null | undefined
+
+	const deliverSnapshotIfChanged = (
+		hostState: CustomBlockHostState,
+		dataSource: InitializedHostState["dataSources"][number] | undefined,
+		queryState: InitializedHostState["dataSourceState"][string] | undefined,
+	) => {
+		if (
+			lastSnapshotInputs !== undefined &&
+			lastSnapshotInputs.status === hostState.status &&
+			lastSnapshotInputs.dataSource === dataSource &&
+			lastSnapshotInputs.queryState === queryState
+		) {
+			return
+		}
+		const snapshot = customBlockDataSources.getView(
+			hostState,
+			key,
+			subscriptionId,
+		)
+		// Record inputs before calling consumer code, which can trigger another notification.
+		lastSnapshotInputs = { status: hostState.status, dataSource, queryState }
+		notifyListener(() => onSnapshot(snapshot))
+	}
+
+	const handleHostChange = () => {
+		if (!active) {
+			return
+		}
+		const hostState = customBlockHost.getState()
+		if (hostState.status !== "initialized") {
+			deliverSnapshotIfChanged(hostState, undefined, undefined)
+			return
+		}
+
+		const dataSource = hostState.dataSources.find(source => source.key === key)
+		const signature =
+			dataSource === undefined ? null : JSON.stringify(dataSource)
+		if (signature !== lastMatchingSignature) {
+			const forceRequery = lastMatchingSignature !== undefined
+			lastMatchingSignature = signature
+			// Querying updates SDK state and calls this listener again.
+			customBlockDataSources.query({
+				subscriptionId,
+				key,
+				options,
+				forceRequery,
+			})
+			return
+		}
+		deliverSnapshotIfChanged(
+			hostState,
+			dataSource,
+			hostState.dataSourceState[subscriptionId],
+		)
+	}
+
+	const unsubscribeHost = customBlockHost.subscribe(handleHostChange)
+	try {
+		handleHostChange()
+	} catch (error) {
+		unsubscribeHost()
+		customBlockDataSources.release(subscriptionId)
+		throw error
+	}
+	return () => {
+		if (!active) {
+			return
+		}
+		active = false
+		unsubscribeHost()
+		customBlockDataSources.release(subscriptionId)
+	}
+}

package/src/bridge/notifyListener.ts

@@ -0,0 +1,14 @@
+/** Report consumer errors without interrupting bridge operations or other listeners. */
+export function notifyListener(listener: () => void): void {
+	try {
+		listener()
+	} catch (error) {
+		if (typeof globalThis.reportError === "function") {
+			globalThis.reportError(error)
+		} else {
+			setTimeout(() => {
+				throw error
+			}, 0)
+		}
+	}
+}

package/src/bridge/sandboxClient.ts

@@ -10,7 +10,6 @@ import type {
 	NotionUserId,
 	UpdatePageArgs,
 	UpdatePageResult,
-	UseDataSourceOptions,
 } from "../types.js"
 import {
 	type CustomBlockHostState,
@@ -18,7 +17,11 @@ import {
 	getDataSourceQueryView as getDataSourceQueryViewWithBridge,
 } from "./hostState.js"
 import type { ManifestLoadResult } from "./loadManifest.js"
-import { type MessageLogEntry, SandboxBridge } from "./SandboxBridge.js"
+import {
+	type MessageLogEntry,
+	type QueryDataSourceArgs,
+	SandboxBridge,
+} from "./SandboxBridge.js"
 
 let bridge: SandboxBridge | undefined
 let didWarnAboutPagesDelete = false
@@ -73,12 +76,8 @@ export const customBlockDataSources = {
 		return getBridge().createDataSourceSubscriptionId()
 	},
 
-	query: (
-		subscriptionId: string,
-		key: string,
-		options?: UseDataSourceOptions,
-	) => {
-		getBridge().queryDataSource(subscriptionId, key, options)
+	query: (args: QueryDataSourceArgs) => {
+		getBridge().queryDataSource(args)
 	},
 
 	release: (subscriptionId: string) => {

package/src/customBlock.ts

@@ -7,6 +7,7 @@ import type { NotionParent } from "@notionhq/custom-blocks-protocol/parent.js"
 import type { NotionTheme } from "@notionhq/custom-blocks-protocol/theme.js"
 import type { NotionUser } from "@notionhq/custom-blocks-protocol/users/user.js"
 import { autoResize } from "./autoResize.js"
+import { subscribeToDataSource } from "./bridge/dataSources/subscribe.js"
 import type {
 	CustomBlockHostState,
 	InitializedHostState,
@@ -72,6 +73,12 @@ export const customBlock = {
 	},
 
 	autoResize,
+
+	/**
+	 * Registers a listener that receives the current query snapshot and later updates.
+	 * Returns a function that removes this listener. Other listeners remain subscribed.
+	 */
+	subscribeToDataSource,
 }
 
 let lastHostState: CustomBlockHostState | undefined

package/src/react/useDataSource.ts

@@ -1,8 +1,22 @@
 import { useEffect, useState } from "react"
 import { getDataSourceQueryOptionsIdentity } from "../bridge/dataSources/query.js"
-import { customBlockDataSources } from "../bridge/sandboxClient.js"
+import { customBlock } from "../customBlock.js"
 import type { UseDataSourceOptions, UseDataSourceResult } from "../types.js"
-import { useCustomBlockHost } from "./useHostState.js"
+
+const EMPTY_DATA_SOURCE_RESULT: UseDataSourceResult = {
+	items: [],
+	propertySchemasById: {},
+	propertyIdsByKey: {},
+	propertySchemasByKey: {},
+	isLoading: false,
+	hasMore: false,
+}
+
+type DataSourceHookState = {
+	key: string
+	optionsIdentity: string
+	snapshot: UseDataSourceResult
+}
 
 /**
  * Reads from the data source mapped to the given semantic `key`.
@@ -18,45 +32,24 @@ export function useDataSource(
 	key: string,
 	options?: UseDataSourceOptions,
 ): UseDataSourceResult {
-	const host = useCustomBlockHost()
-	const [subscriptionId] = useState(() =>
-		customBlockDataSources.createSubscriptionId(),
-	)
 	const optionsIdentity = getDataSourceQueryOptionsIdentity(options)
-	const matchingDataSource =
-		host.status === "initialized"
-			? host.dataSources.find(dataSource => dataSource.key === key)
-			: undefined
-
-	const isInitialized = host.status === "initialized"
+	const [state, setState] = useState<DataSourceHookState>(() => ({
+		key,
+		optionsIdentity,
+		snapshot: EMPTY_DATA_SOURCE_RESULT,
+	}))
 	// biome-ignore lint/correctness/useExhaustiveDependencies(options): Compare options by value through optionsIdentity. Object identity alone must not trigger queries.
-	// biome-ignore lint/correctness/useExhaustiveDependencies(optionsIdentity): Changes to the serialized options must trigger a query even though the callback reads options.
-	// biome-ignore lint/correctness/useExhaustiveDependencies(matchingDataSource): Requery when the matching data source changes, even when the key and options are unchanged.
 	useEffect(() => {
-		if (!isInitialized) {
-			return
-		}
-
-		customBlockDataSources.query(subscriptionId, key, options)
-	}, [matchingDataSource, isInitialized, key, optionsIdentity, subscriptionId])
-
-	useEffect(
-		() => () => {
-			customBlockDataSources.release(subscriptionId)
-		},
-		[subscriptionId],
-	)
-
-	const view = customBlockDataSources.getView(host, key, subscriptionId)
-
-	return {
-		items: view.items,
-		collectionSchema: view.collectionSchema,
-		propertySchemasById: view.propertySchemasById,
-		propertyIdsByKey: view.propertyIdsByKey,
-		propertySchemasByKey: view.propertySchemasByKey,
-		isLoading: view.isLoading,
-		hasMore: view.hasMore,
-		error: view.error,
+		return customBlock.subscribeToDataSource({
+			key,
+			onSnapshot: snapshot => {
+				setState({ key, optionsIdentity, snapshot })
+			},
+			options,
+		})
+	}, [key, optionsIdentity])
+	if (state.key !== key || state.optionsIdentity !== optionsIdentity) {
+		return EMPTY_DATA_SOURCE_RESULT
 	}
+	return state.snapshot
 }

package/src/types.ts

@@ -80,7 +80,7 @@ export type NotionPagePropertyInputMap = {
 }
 
 /**
- * Consumer-facing page shape returned from `useDataSource`. Derived from the bridge payload
+ * Consumer-facing page shape returned from a data source snapshot. Derived from the bridge payload
  * plus the data source's `propertyIdsByKey`.
  */
 export type NotionDataSourcePage = {
@@ -176,14 +176,14 @@ export type NotionDataSourceFilter =
 	| { and: NotionDataSourcePropertyFilter[] }
 
 /**
- * Return shape of `useDataSource`.
+ * Latest live snapshot of a data source query.
  *
  * - `items` — the rows the host has returned so far. Empty until the first response arrives.
  * - `isLoading` — `true` while a query is in flight.
- * - `hasMore` — `true` if the host indicated more rows are available beyond the current page.
+ * - `hasMore` — `true` if the host indicated more rows are available beyond the requested prefix.
  * - `error` — structured error information if the most recent query failed.
  */
-export type UseDataSourceResult = {
+export type DataSourceSnapshot = {
 	items: NotionDataSourcePage[]
 	/**
 	 * Collection/data source schema for the bound Notion data source, including raw property
@@ -211,22 +211,25 @@ export type UseDataSourceResult = {
 	error?: CustomBlockQueryDataSourceErrorInfo
 }
 
-export type UseDataSourceOptions = {
-	/**
-	 * Maximum number of rows to request from the host. Defaults to 20.
-	 */
+export type DataSourceQueryOptions = {
+	/** 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.
-	 */
+	/** Optional property filter. The SDK resolves semantic keys before it sends the query. */
 	filter?: NotionDataSourceFilter
-	/**
-	 * Optional property sorts. The host applies them in array order.
-	 */
+	/** Optional property sorts. The host applies them in array order. */
 	sorts?: NotionDataSourceSort[]
 }
 
+export type SubscribeToDataSourceArgs = {
+	key: string
+	onSnapshot: (snapshot: DataSourceSnapshot) => void
+	options?: DataSourceQueryOptions
+}
+
+export type UseDataSourceResult = DataSourceSnapshot
+
+export type UseDataSourceOptions = DataSourceQueryOptions
+
 /**
  * Parent reference accepted by `sdk.pages.create`. Mirrors Notion's public `POST /v1/pages`
  * parent shape; see https://developers.notion.com/reference/data-source.