@notionhq/custom-blocks 0.1.34 → 0.1.36

package/src/bridge/dataSources/query.ts

@@ -1,6 +1,8 @@
 import type { NotionDataSource } from "@notionhq/custom-blocks-protocol/dataSources/dataSource.js"
+import { CUSTOM_BLOCK_DATA_SOURCE_SORTABLE_PROPERTY_TYPES } from "@notionhq/custom-blocks-protocol/dataSources/propertySchema.js"
 import type { NotionDataSourceId } from "@notionhq/custom-blocks-protocol/ids.js"
 import {
+	CUSTOM_BLOCK_DATA_SOURCE_QUERY_MAX_SORTS,
 	customBlockCheckboxFilterOperatorSchema,
 	customBlockContainsFilterOperatorSchema,
 	customBlockDateFilterOperatorSchema,
@@ -9,18 +11,24 @@ import {
 	customBlockTextFilterOperatorSchema,
 	type ResolvedCustomBlockDataSourceFilter,
 	type ResolvedCustomBlockDataSourcePropertyFilter,
+	type ResolvedCustomBlockDataSourceSort,
 } from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
 import * as v from "valibot"
 import type { UseDataSourceOptions } from "../../types.js"
+import { unreachable } from "../../utils.js"
 
 const DEFAULT_DATA_SOURCE_QUERY_LIMIT = 20
 const MAX_DATA_SOURCE_QUERY_LIMIT = 999
 const MAX_DATA_SOURCE_QUERY_FILTER_CHILDREN = 25
+const supportedDataSourceSortPropertyTypes = new Set<string>(
+	CUSTOM_BLOCK_DATA_SOURCE_SORTABLE_PROPERTY_TYPES,
+)
 
 export type ResolvedDataSourceQuery = {
 	dataSourceId: NotionDataSourceId
 	limit: number
 	filter?: ResolvedCustomBlockDataSourceFilter
+	sorts?: ResolvedCustomBlockDataSourceSort[]
 	identity: string
 }
 
@@ -32,6 +40,16 @@ export type ResolveDataSourceQueryResult =
 			query: ResolvedDataSourceQuery
 	  }
 
+type DataSourceQueryOptions = {
+	limit?: unknown
+	filter?: unknown
+	sorts?: unknown
+}
+
+type ResolvePropertyFilterResult =
+	| { status: "ok"; filter: ResolvedCustomBlockDataSourcePropertyFilter }
+	| { status: "error"; error: string }
+
 export function resolveDataSourceQuery(args: {
 	dataSources: NotionDataSource[]
 	key: string
@@ -39,21 +57,11 @@ export function resolveDataSourceQuery(args: {
 	warn?: (message: string) => void
 }): ResolveDataSourceQueryResult {
 	const { dataSources, key, options, warn } = args
-	if (options !== undefined && !isPlainRecord(options)) {
-		return {
-			status: "error",
-			error: "Data source query options must be an object.",
-		}
-	}
-	if (
-		options !== undefined &&
-		Object.keys(options).some(key => !["limit", "filter"].includes(key))
-	) {
-		return {
-			status: "error",
-			error: "Data source query options contain unsupported fields.",
-		}
+	const resolvedOptions = resolveDataSourceQueryOptions(options)
+	if (resolvedOptions.status === "error") {
+		return resolvedOptions
 	}
+	const queryOptions = resolvedOptions.options
 	const dataSource = dataSources.find(entry => entry.key === key)
 	if (dataSource === undefined) {
 		return {
@@ -68,19 +76,24 @@ export function resolveDataSourceQuery(args: {
 		}
 	}
 
-	const limit = resolveDataSourceQueryLimit(options?.limit, warn)
+	const limit = resolveDataSourceQueryLimit(queryOptions?.limit, warn)
 	if (limit.status === "error") {
 		return limit
 	}
-	const filter = resolveFilter(options?.filter, dataSource)
+	const filter = resolveFilter(queryOptions?.filter, dataSource)
 	if (filter.status === "error") {
 		return filter
 	}
+	const sorts = resolveSorts(queryOptions?.sorts, dataSource)
+	if (sorts.status === "error") {
+		return sorts
+	}
 
 	const identity = stableJsonStringify({
 		dataSourceId: dataSource.collectionPointer.id,
 		limit: limit.limit,
 		filter: filter.filter ?? null,
+		sorts: sorts.sorts ?? [],
 	})
 	return {
 		status: "ok",
@@ -89,11 +102,64 @@ export function resolveDataSourceQuery(args: {
 			dataSourceId: dataSource.collectionPointer.id,
 			limit: limit.limit,
 			filter: filter.filter,
+			sorts: sorts.sorts,
 			identity,
 		},
 	}
 }
 
+function resolveDataSourceQueryOptions(
+	options: unknown,
+):
+	| { status: "ok"; options?: DataSourceQueryOptions }
+	| { status: "error"; error: string } {
+	if (options === undefined) {
+		return { status: "ok" }
+	}
+	if (
+		typeof options !== "object" ||
+		options === null ||
+		Array.isArray(options)
+	) {
+		return {
+			status: "error",
+			error: "Data source query options must be an object.",
+		}
+	}
+	const prototype = Object.getPrototypeOf(options)
+	if (prototype !== Object.prototype && prototype !== null) {
+		return {
+			status: "error",
+			error: "Data source query options must be an object.",
+		}
+	}
+	const optionsObject = options as Record<string, unknown>
+	if (
+		Object.keys(optionsObject).some(
+			key => !["limit", "filter", "sorts"].includes(key),
+		)
+	) {
+		return {
+			status: "error",
+			error: "Data source query options contain unsupported fields.",
+		}
+	}
+	return {
+		status: "ok",
+		options: {
+			limit: Object.prototype.hasOwnProperty.call(optionsObject, "limit")
+				? optionsObject.limit
+				: undefined,
+			filter: Object.prototype.hasOwnProperty.call(optionsObject, "filter")
+				? optionsObject.filter
+				: undefined,
+			sorts: Object.prototype.hasOwnProperty.call(optionsObject, "sorts")
+				? optionsObject.sorts
+				: undefined,
+		},
+	}
+}
+
 function resolveDataSourceQueryLimit(
 	limit: unknown,
 	warn: ((message: string) => void) | undefined = console.warn,
@@ -144,27 +210,31 @@ function resolveFilter(
 	if (filter === undefined) {
 		return { status: "ok" }
 	}
-	if (!isPlainRecord(filter)) {
+	if (typeof filter !== "object" || filter === null || Array.isArray(filter)) {
 		return {
 			status: "error",
 			error: "Data source query filter must be an object.",
 		}
 	}
-	if ("and" in filter) {
-		if (Object.keys(filter).length !== 1 || !Array.isArray(filter.and)) {
+	const filterObject = filter as Record<string, unknown>
+	if (Object.prototype.hasOwnProperty.call(filterObject, "and")) {
+		if (
+			Object.keys(filterObject).length !== 1 ||
+			!Array.isArray(filterObject.and)
+		) {
 			return {
 				status: "error",
 				error: 'Data source query filter "and" must be an array.',
 			}
 		}
-		if (filter.and.length > MAX_DATA_SOURCE_QUERY_FILTER_CHILDREN) {
+		if (filterObject.and.length > MAX_DATA_SOURCE_QUERY_FILTER_CHILDREN) {
 			return {
 				status: "error",
 				error: `Data source query filter "and" may contain at most ${MAX_DATA_SOURCE_QUERY_FILTER_CHILDREN} children.`,
 			}
 		}
 		const and: ResolvedCustomBlockDataSourcePropertyFilter[] = []
-		for (const child of filter.and) {
+		for (const child of filterObject.and) {
 			const resolved = resolvePropertyFilter(child, dataSource)
 			if (resolved.status === "error") {
 				return resolved
@@ -173,26 +243,119 @@ function resolveFilter(
 		}
 		return { status: "ok", filter: { and } }
 	}
-	return resolvePropertyFilter(filter, dataSource)
+	return resolvePropertyFilter(filterObject, dataSource)
 }
 
-function resolvePropertyFilter(
-	filter: unknown,
+function resolveSorts(
+	sorts: unknown,
 	dataSource: NotionDataSource,
 ):
-	| { status: "ok"; filter: ResolvedCustomBlockDataSourcePropertyFilter }
+	| { status: "ok"; sorts?: ResolvedCustomBlockDataSourceSort[] }
+	| { status: "error"; error: string } {
+	if (sorts === undefined) {
+		return { status: "ok" }
+	}
+	if (!Array.isArray(sorts)) {
+		return {
+			status: "error",
+			error: "Data source query sorts must be an array.",
+		}
+	}
+	if (sorts.length === 0) {
+		return { status: "ok" }
+	}
+	if (sorts.length > CUSTOM_BLOCK_DATA_SOURCE_QUERY_MAX_SORTS) {
+		return {
+			status: "error",
+			error: `Data source query sorts may contain at most ${CUSTOM_BLOCK_DATA_SOURCE_QUERY_MAX_SORTS} entries.`,
+		}
+	}
+
+	const resolvedSorts: ResolvedCustomBlockDataSourceSort[] = []
+	const seenPropertyIds = new Set<string>()
+	for (const sort of sorts) {
+		const resolved = resolveSort(sort, dataSource)
+		if (resolved.status === "error") {
+			return resolved
+		}
+		if (seenPropertyIds.has(resolved.sort.propertyId)) {
+			return {
+				status: "error",
+				error: `Data source query sorts cannot contain duplicate property ID "${resolved.sort.propertyId}".`,
+			}
+		}
+		seenPropertyIds.add(resolved.sort.propertyId)
+		resolvedSorts.push(resolved.sort)
+	}
+	return { status: "ok", sorts: resolvedSorts }
+}
+
+function resolveSort(
+	sort: unknown,
+	dataSource: NotionDataSource,
+):
+	| { status: "ok"; sort: ResolvedCustomBlockDataSourceSort }
 	| { status: "error"; error: string } {
-	if (!isPlainRecord(filter)) {
+	if (typeof sort !== "object" || sort === null || Array.isArray(sort)) {
+		return {
+			status: "error",
+			error: "Data source query sort must be an object.",
+		}
+	}
+	const sortObject = sort as Record<string, unknown>
+	if (
+		Object.keys(sortObject).some(
+			key => !["key", "propertyId", "direction"].includes(key),
+		)
+	) {
+		return {
+			status: "error",
+			error: "Data source query sort contains unsupported fields.",
+		}
+	}
+	const property = resolvePropertyAddress(sortObject, dataSource)
+	if (property.status === "error") {
+		return property
+	}
+	if (!supportedDataSourceSortPropertyTypes.has(property.propertyType)) {
+		return {
+			status: "error",
+			error: `Data source query sorts do not yet support property type "${property.propertyType}".`,
+		}
+	}
+	const direction = sortObject.direction
+	if (
+		!Object.prototype.hasOwnProperty.call(sortObject, "direction") ||
+		(direction !== "ascending" && direction !== "descending")
+	) {
+		return {
+			status: "error",
+			error:
+				'Data source query sort direction must be "ascending" or "descending".',
+		}
+	}
+	return {
+		status: "ok",
+		sort: { propertyId: property.propertyId, direction },
+	}
+}
+
+function resolvePropertyFilter(
+	filter: unknown,
+	dataSource: NotionDataSource,
+): ResolvePropertyFilterResult {
+	if (typeof filter !== "object" || filter === null || Array.isArray(filter)) {
 		return {
 			status: "error",
 			error: "Data source query property filter must be an object.",
 		}
 	}
-	const property = resolvePropertyAddress(filter, dataSource)
+	const filterObject = filter as Record<string, unknown>
+	const property = resolvePropertyAddress(filterObject, dataSource)
 	if (property.status === "error") {
 		return property
 	}
-	const branchKeys = Object.keys(filter).filter(
+	const branchKeys = Object.keys(filterObject).filter(
 		key => key !== "key" && key !== "propertyId",
 	)
 	if (branchKeys.length !== 1) {
@@ -203,8 +366,13 @@ function resolvePropertyFilter(
 		}
 	}
 	const branch = branchKeys[0]
-	const value = filter[branch]
-	if (!isPlainRecord(value) || Object.keys(value).length !== 1) {
+	const value = filterObject[branch]
+	if (
+		typeof value !== "object" ||
+		value === null ||
+		Array.isArray(value) ||
+		Object.keys(value).length !== 1
+	) {
 		return invalidOperator(branch)
 	}
 	if (property.propertyType !== branch) {
@@ -214,132 +382,172 @@ function resolvePropertyFilter(
 		}
 	}
 
-	switch (branch) {
-		case "title": {
-			const parsed = v.safeParse(customBlockTextFilterOperatorSchema, value)
-			return parsed.success
-				? {
-						status: "ok",
-						filter: { propertyId: property.propertyId, title: parsed.output },
-					}
-				: invalidOperator(branch)
-		}
-		case "rich_text": {
-			const parsed = v.safeParse(customBlockTextFilterOperatorSchema, value)
-			return parsed.success
-				? {
-						status: "ok",
-						filter: {
-							propertyId: property.propertyId,
-							rich_text: parsed.output,
-						},
-					}
-				: invalidOperator(branch)
-		}
+	return resolvePropertyFilterBranch({
+		propertyId: property.propertyId,
+		branch,
+		value: value as Record<string, unknown>,
+	})
+}
+
+function resolvePropertyFilterBranch(args: {
+	propertyId: string
+	branch: string
+	value: Record<string, unknown>
+}): ResolvePropertyFilterResult {
+	switch (args.branch) {
+		case "title":
+		case "rich_text":
 		case "url":
 		case "email":
-		case "phone_number": {
-			const parsed = v.safeParse(customBlockTextFilterOperatorSchema, value)
-			if (!parsed.success) {
-				return invalidOperator(branch)
+		case "phone_number":
+			return resolveTextPropertyFilter({
+				propertyId: args.propertyId,
+				branch: args.branch,
+				value: args.value,
+			})
+		case "number":
+			return resolveNumberPropertyFilter(args.propertyId, args.value)
+		case "checkbox":
+			return resolveCheckboxPropertyFilter(args.propertyId, args.value)
+		case "select":
+		case "status":
+			return resolveOptionPropertyFilter({
+				propertyId: args.propertyId,
+				branch: args.branch,
+				value: args.value,
+			})
+		case "multi_select":
+			return resolveMultiSelectPropertyFilter(args.propertyId, args.value)
+		case "date":
+			return resolveDatePropertyFilter(args.propertyId, args.value)
+		default:
+			return {
+				status: "error",
+				error: `Data source query filter branch "${args.branch}" is not supported.`,
 			}
-			if (branch === "url") {
-				return {
-					status: "ok",
-					filter: { propertyId: property.propertyId, url: parsed.output },
-				}
+	}
+}
+
+function resolveTextPropertyFilter(args: {
+	propertyId: string
+	branch: "title" | "rich_text" | "url" | "email" | "phone_number"
+	value: Record<string, unknown>
+}): ResolvePropertyFilterResult {
+	const parsed = v.safeParse(customBlockTextFilterOperatorSchema, args.value)
+	if (!parsed.success) {
+		return invalidOperator(args.branch)
+	}
+	switch (args.branch) {
+		case "title":
+			return {
+				status: "ok",
+				filter: { propertyId: args.propertyId, title: parsed.output },
 			}
-			if (branch === "email") {
-				return {
-					status: "ok",
-					filter: { propertyId: property.propertyId, email: parsed.output },
-				}
+		case "rich_text":
+			return {
+				status: "ok",
+				filter: { propertyId: args.propertyId, rich_text: parsed.output },
 			}
+		case "url":
 			return {
 				status: "ok",
-				filter: {
-					propertyId: property.propertyId,
-					phone_number: parsed.output,
-				},
+				filter: { propertyId: args.propertyId, url: parsed.output },
 			}
-		}
-		case "number": {
-			const parsed = v.safeParse(customBlockNumberFilterOperatorSchema, value)
-			if (
-				parsed.success &&
-				Object.values(parsed.output).every(
-					entry => typeof entry !== "number" || Number.isFinite(entry),
-				)
-			) {
-				return {
-					status: "ok",
-					filter: { propertyId: property.propertyId, number: parsed.output },
-				}
+		case "email":
+			return {
+				status: "ok",
+				filter: { propertyId: args.propertyId, email: parsed.output },
 			}
-			return invalidOperator(branch)
-		}
-		case "checkbox": {
-			const parsed = v.safeParse(customBlockCheckboxFilterOperatorSchema, value)
-			return parsed.success
-				? {
-						status: "ok",
-						filter: {
-							propertyId: property.propertyId,
-							checkbox: parsed.output,
-						},
-					}
-				: invalidOperator(branch)
-		}
-		case "select": {
-			const parsed = v.safeParse(customBlockOptionFilterOperatorSchema, value)
-			return parsed.success
-				? {
-						status: "ok",
-						filter: { propertyId: property.propertyId, select: parsed.output },
-					}
-				: invalidOperator(branch)
-		}
-		case "multi_select": {
-			const parsed = v.safeParse(customBlockContainsFilterOperatorSchema, value)
-			return parsed.success
-				? {
-						status: "ok",
-						filter: {
-							propertyId: property.propertyId,
-							multi_select: parsed.output,
-						},
-					}
-				: invalidOperator(branch)
-		}
-		case "status": {
-			const parsed = v.safeParse(customBlockOptionFilterOperatorSchema, value)
-			return parsed.success
-				? {
-						status: "ok",
-						filter: { propertyId: property.propertyId, status: parsed.output },
-					}
-				: invalidOperator(branch)
-		}
-		case "date": {
-			const parsed = v.safeParse(customBlockDateFilterOperatorSchema, value)
-			if (
-				parsed.success &&
-				Object.values(parsed.output).every(
-					entry => entry === true || isValidIsoDate(entry),
-				)
-			) {
-				return {
-					status: "ok",
-					filter: { propertyId: property.propertyId, date: parsed.output },
-				}
+		case "phone_number":
+			return {
+				status: "ok",
+				filter: { propertyId: args.propertyId, phone_number: parsed.output },
 			}
-			return invalidOperator(branch)
-		}
 		default:
+			return unreachable(args.branch)
+	}
+}
+
+function resolveNumberPropertyFilter(
+	propertyId: string,
+	value: Record<string, unknown>,
+): ResolvePropertyFilterResult {
+	const parsed = v.safeParse(customBlockNumberFilterOperatorSchema, value)
+	if (
+		!parsed.success ||
+		!Object.values(parsed.output).every(
+			entry => typeof entry !== "number" || Number.isFinite(entry),
+		)
+	) {
+		return invalidOperator("number")
+	}
+	return {
+		status: "ok",
+		filter: { propertyId, number: parsed.output },
+	}
+}
+
+function resolveCheckboxPropertyFilter(
+	propertyId: string,
+	value: Record<string, unknown>,
+): ResolvePropertyFilterResult {
+	const parsed = v.safeParse(customBlockCheckboxFilterOperatorSchema, value)
+	return parsed.success
+		? { status: "ok", filter: { propertyId, checkbox: parsed.output } }
+		: invalidOperator("checkbox")
+}
+
+function resolveOptionPropertyFilter(args: {
+	propertyId: string
+	branch: "select" | "status"
+	value: Record<string, unknown>
+}): ResolvePropertyFilterResult {
+	const parsed = v.safeParse(customBlockOptionFilterOperatorSchema, args.value)
+	if (!parsed.success) {
+		return invalidOperator(args.branch)
+	}
+	switch (args.branch) {
+		case "select":
 			return {
-				status: "error",
-				error: `Data source query filter branch "${branch}" is not supported.`,
+				status: "ok",
+				filter: { propertyId: args.propertyId, select: parsed.output },
+			}
+		case "status":
+			return {
+				status: "ok",
+				filter: { propertyId: args.propertyId, status: parsed.output },
 			}
+		default:
+			return unreachable(args.branch)
+	}
+}
+
+function resolveMultiSelectPropertyFilter(
+	propertyId: string,
+	value: Record<string, unknown>,
+): ResolvePropertyFilterResult {
+	const parsed = v.safeParse(customBlockContainsFilterOperatorSchema, value)
+	return parsed.success
+		? { status: "ok", filter: { propertyId, multi_select: parsed.output } }
+		: invalidOperator("multi_select")
+}
+
+function resolveDatePropertyFilter(
+	propertyId: string,
+	value: Record<string, unknown>,
+): ResolvePropertyFilterResult {
+	const parsed = v.safeParse(customBlockDateFilterOperatorSchema, value)
+	if (
+		!parsed.success ||
+		!Object.values(parsed.output).every(
+			entry => entry === true || isValidIsoDate(entry),
+		)
+	) {
+		return invalidOperator("date")
+	}
+	return {
+		status: "ok",
+		filter: { propertyId, date: parsed.output },
 	}
 }
 
@@ -349,13 +557,16 @@ function resolvePropertyAddress(
 ):
 	| { status: "ok"; propertyId: string; propertyType: string }
 	| { status: "error"; error: string } {
-	const hasKey = "key" in value
-	const hasPropertyId = "propertyId" in value
+	const hasKey = Object.prototype.hasOwnProperty.call(value, "key")
+	const hasPropertyId = Object.prototype.hasOwnProperty.call(
+		value,
+		"propertyId",
+	)
 	if (hasKey === hasPropertyId) {
 		return {
 			status: "error",
 			error:
-				"Data source query filters must use exactly one of key or propertyId.",
+				"Data source query filters and sorts must use exactly one of key or propertyId.",
 		}
 	}
 	let propertyId: string
@@ -366,7 +577,12 @@ function resolvePropertyAddress(
 				error: "Data source query property key must be a string.",
 			}
 		}
-		if (!(value.key in dataSource.propertyIdsByKey)) {
+		if (
+			!Object.prototype.hasOwnProperty.call(
+				dataSource.propertyIdsByKey,
+				value.key,
+			)
+		) {
 			return {
 				status: "error",
 				error: `Unknown property key "${value.key}" for data source "${dataSource.key}".`,
@@ -389,13 +605,18 @@ function resolvePropertyAddress(
 		}
 		propertyId = value.propertyId
 	}
-	const propertySchema = dataSource.propertySchemasById[propertyId]
-	if (propertySchema === undefined) {
+	if (
+		!Object.prototype.hasOwnProperty.call(
+			dataSource.propertySchemasById,
+			propertyId,
+		)
+	) {
 		return {
 			status: "error",
 			error: `Unknown property ID "${propertyId}" for data source "${dataSource.key}".`,
 		}
 	}
+	const propertySchema = dataSource.propertySchemasById[propertyId]
 	return {
 		status: "ok",
 		propertyId,
@@ -419,35 +640,38 @@ function normalizeJsonValue(value: unknown): unknown {
 		return value
 	}
 	if (typeof value === "number") {
-		if (!Number.isFinite(value)) {
-			throw new Error("Data source query values must be finite JSON numbers.")
-		}
-		return value
+		return normalizeJsonNumber(value)
 	}
 	if (Array.isArray(value)) {
 		return value.map(entry => normalizeJsonValue(entry))
 	}
-	if (isPlainRecord(value)) {
-		const normalized: Record<string, unknown> = {}
-		for (const key of Object.keys(value).sort()) {
-			const child = value[key]
-			if (child !== undefined) {
-				normalized[key] = normalizeJsonValue(child)
-			}
-		}
-		return normalized
+	if (typeof value === "object") {
+		return normalizeJsonObject(value)
 	}
 	throw new Error("Data source query values must be JSON-compatible.")
 }
 
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-	return (
-		typeof value === "object" &&
-		value !== null &&
-		!Array.isArray(value) &&
-		(Object.getPrototypeOf(value) === Object.prototype ||
-			Object.getPrototypeOf(value) === null)
-	)
+function normalizeJsonNumber(value: number): number {
+	if (!Number.isFinite(value)) {
+		throw new Error("Data source query values must be finite JSON numbers.")
+	}
+	return value
+}
+
+function normalizeJsonObject(value: object): Record<string, unknown> {
+	const prototype = Object.getPrototypeOf(value)
+	if (prototype !== Object.prototype && prototype !== null) {
+		throw new Error("Data source query values must be JSON-compatible.")
+	}
+	const objectValue = value as Record<string, unknown>
+	const normalized: Record<string, unknown> = {}
+	for (const key of Object.keys(objectValue).sort()) {
+		const child = objectValue[key]
+		if (child !== undefined) {
+			normalized[key] = normalizeJsonValue(child)
+		}
+	}
+	return normalized
 }
 
 function isValidIsoDate(value: unknown): boolean {