@protobase/server 0.17.0 → 0.19.0

package/dist/admin-options.d.ts

@@ -13,10 +13,9 @@ export type AdminOptions = {
   basePath?: string;
   /** Applied to every request's transaction with SET LOCAL. Default 15000. */
   statementTimeoutMs?: number;
-  /** List shapes that would sequentially scan a table of more than `seqScanRows` rows (default 10000). Default mode `reject`. */
+  /** Reads that filter, sort or count values by a column no index serves. Default mode `reject`. */
   scanGuard?: {
     mode?: ScanGuardMode;
-    seqScanRows?: number;
   };
   /** Runs inside the write transaction after each create, update and delete. */
   writeHooks?: PipelineHook[];

package/dist/aggregate-service.js

@@ -5,7 +5,7 @@ import { readScope, requestAccess, requireOperation } from "./request-access.js"
 import { readTransaction } from "./transactions.js";
 import { parseParams } from "./params.js";
 import { labelRequests, relatedLabels } from "./related-labels.js";
-import { facetCounts, histogram, series } from "@protobase/query";
+import { facetCounts, histogram, series, withoutField } from "@protobase/query";
 import { sql } from "kysely";
 import { z } from "zod";
 //#region src/aggregate-service.ts
@@ -66,25 +66,36 @@ const facets = async (deps, entry, session, input) => {
 	const params = parseParams(facetParams, input);
 	const { model, filter: checked, scope } = await scoped(deps, entry, session, params.filter);
 	const labels = params.label === void 0 ? [] : await labelRequests(deps, session, model, [params.field], `${params.field}.${params.label}`);
-	return readTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
-		const counts = await facetCounts(trx, model, params.field, checked, {
-			statementTimeoutMs: deps.statementTimeoutMs,
-			...params.limit !== void 0 && { limit: params.limit },
-			scope
-		});
-		const names = (await relatedLabels(trx, labels, counts.map((facet) => ({ [params.field]: facet.value }))))[params.field] ?? {};
-		const named = counts.map((facet) => {
-			const label = facet.value === null ? void 0 : names[String(facet.value)];
-			return label === void 0 ? facet : {
-				...facet,
-				label
-			};
-		});
-		return {
-			field: params.field,
-			facets: named
-		};
+	const others = withoutField(checked, params.field);
+	const warning = await deps.guard(entry, {
+		...others && { filter: others },
+		groupBy: params.field
+	}, {
+		model,
+		scope
 	});
+	return {
+		body: await readTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
+			const counts = await facetCounts(trx, model, params.field, checked, {
+				statementTimeoutMs: deps.statementTimeoutMs,
+				...params.limit !== void 0 && { limit: params.limit },
+				scope
+			});
+			const names = (await relatedLabels(trx, labels, counts.map((facet) => ({ [params.field]: facet.value }))))[params.field] ?? {};
+			const named = counts.map((facet) => {
+				const label = facet.value === null ? void 0 : names[String(facet.value)];
+				return label === void 0 ? facet : {
+					...facet,
+					label
+				};
+			});
+			return {
+				field: params.field,
+				facets: named
+			};
+		}),
+		warning
+	};
 };
 const earliest = async (deps, access, fieldName, scope) => {
 	const target = access.model.fields[fieldName];

package/dist/check-view-queries.d.ts

@@ -0,0 +1,5 @@
+import { ResourceModel, ViewModel } from "@protobase/schema";
+//#region src/check-view-queries.d.ts
+/** Throws one error listing what every view asks for that its resource does not allow; views of unknown resources are left to the other checks. */
+export declare const checkViewQueries: (models: ResourceModel[], views: ViewModel[]) => void;
+//#endregion

package/dist/check-view-queries.js

@@ -0,0 +1,41 @@
+//#region src/check-view-queries.ts
+const widgetName = {
+	facets: "facets filter",
+	range: "range filter",
+	dateRange: "date range filter",
+	toggle: "toggle",
+	flags: "flags filter"
+};
+const filterableErrors = (model, names, what) => names.flatMap((name) => {
+	const field = Object.hasOwn(model.fields, name) ? model.fields[name] : void 0;
+	if (!field) return [`${what} names "${name}", which is not a field of ${model.name}`];
+	return field.filterable ? [] : [`${what} uses "${name}", which is not filterable, so the API refuses it: mark "${name}" .filterable()`];
+});
+const listSortErrors = (model, view) => (view.list?.sort ?? []).flatMap(([name]) => {
+	const field = Object.hasOwn(model.fields, name) ? model.fields[name] : void 0;
+	if (!field) return [`the list sorts by "${name}", which is not a field of ${model.name}`];
+	return field.sortable ? [] : [`the list sorts by "${name}", which is not sortable, so the API refuses it: mark "${name}" .sortable()`];
+});
+const searchErrors = (model, view) => (view.list?.search ?? []).filter((name) => !(model.search ?? []).includes(name)).map((name) => `the list searches "${name}", which ${model.name} does not search: add it to the resource's .search(...)`);
+/**
+* What a view asks the API for that its resource does not allow, which the API refuses only once a page asks: a filter
+* widget or the chart on a field that is not `.filterable()`, a list sorted by one that is not `.sortable()`, and a list
+* search on a field the resource does not search. The server's startup checks the rest of a view.
+*/
+const viewQueryErrors = (view, model) => [
+	...view.filters.flatMap((widget) => filterableErrors(model, widget.kind === "flags" ? widget.fields : [widget.field], `the ${widgetName[widget.kind]}`)),
+	...view.chart ? filterableErrors(model, [view.chart.field], "the chart") : [],
+	...listSortErrors(model, view),
+	...searchErrors(model, view)
+];
+/** Throws one error listing what every view asks for that its resource does not allow; views of unknown resources are left to the other checks. */
+const checkViewQueries = (models, views) => {
+	const byName = new Map(models.map((model) => [model.name, model]));
+	const problems = views.flatMap((view) => {
+		const model = byName.get(view.resource);
+		return model ? viewQueryErrors(view, model).map((problem) => `View "${view.resource}": ${problem}`) : [];
+	});
+	if (problems.length > 0) throw new Error(`The views ask for what their resources do not allow:\n${problems.map((problem) => `  - ${problem}`).join("\n")}`);
+};
+//#endregion
+export { checkViewQueries, viewQueryErrors };

package/dist/check-views.js

@@ -21,6 +21,7 @@ const sensitiveErrors = (view, model) => {
 		["the chart", view.chart ? [view.chart.field] : []],
 		["the sidebar", view.layout.flatMap((item) => item.kind === "sidebar" ? item.fields : [])],
 		["a map", view.layout.flatMap((item) => item.kind === "map" ? [item.latitude, item.longitude] : [])],
+		["a gallery", view.layout.flatMap((item) => item.kind === "gallery" && item.image !== void 0 ? [item.image] : [])],
 		["the recent records", view.nav?.recent ? [view.nav.recent.status] : []],
 		["an action", view.actions.flatMap((action) => action.run?.kind === "update" ? Object.keys(action.run.values) : linkFields(action.run))]
 	].flatMap(([place, names]) => [...new Set(names.filter(sensitive))].map((name) => `sensitive field "${name}" cannot be in ${place}`));
@@ -55,7 +56,11 @@ const linkErrors = (view, model, models, pages) => view.actions.flatMap(({ name,
 });
 const unknownFieldErrors = (view, model) => {
 	const unknown = (names, what) => names.filter((name) => !Object.hasOwn(model.fields, name)).map((name) => `${what} names field "${name}", which ${model.name} does not have`);
-	return [...(view.list?.displays ?? []).flatMap((display) => unknown(displayFields(display), `display "${display.name}"`)), ...view.layout.flatMap((item) => item.kind === "custom" ? unknown(fieldRefsIn(item.props), `custom section ${item.component}`) : [])];
+	return [
+		...(view.list?.displays ?? []).flatMap((display) => unknown(displayFields(display), `display "${display.name}"`)),
+		...view.layout.flatMap((item) => item.kind === "custom" ? unknown(fieldRefsIn(item.props), `custom section ${item.component}`) : []),
+		...view.layout.flatMap((item) => item.kind === "gallery" && item.image !== void 0 ? unknown([item.image], `gallery "${item.title}"`) : [])
+	];
 };
 const widgetErrors = (view, model, fieldTypes) => Object.entries(view.fields).flatMap(([name, hints]) => {
 	const of = hints.widget && fieldTypes[hints.widget.name];
@@ -71,6 +76,10 @@ const sharedPhotosErrors = (view) => {
 	const same = (a, b) => a.resource === b.resource && a.field === b.field && a.image === b.image && a.sort === b.sort;
 	return shown.filter(({ photos }) => !same(photos, shown[0].photos)).map(({ name }) => `display "${name}" photos: the list's records load with one set of photos, so name those of display "${shown[0].name}"`);
 };
+const galleryErrors = (item, resource, model, models) => {
+	const image = item.image === void 0 ? void 0 : model.fields[item.image];
+	return [...image && image.type !== "file" ? [`"${item.image}" is not a file field`] : [], ...item.photos ? cardPhotosErrors(item.photos, resource, models).map((error) => `photos: ${error}`) : []];
+};
 const listOfErrors = (model, name, models) => {
 	const target = models[model.fields[name]?.relation?.resource ?? ""];
 	if (!target) return [`"${name}" points at no resource of the app`];
@@ -80,7 +89,7 @@ const listOfErrors = (model, name, models) => {
 * Fails at startup when a view uses a sensitive field where it would show empty, a display or custom section names a
 * field the resource does not have, labels or colours values its enum does not have, shows a field with a field type of
 * `fieldTypes` (each with the storage types it shows) that does not show it,
-* has a related section, a cards display's photos or favorite button, a `listOf`, a "Save search" button or a
+* has a related section, a cards display's or gallery's photos or a cards display's favorite button, a `listOf`, a "Save search" button or a
 * `searchesOf` that do not fit the resources, cards
 * displays of one list that name different photos, a map that cannot show the
 * record's position or a map display that cannot find the records in its view, or a link to an address the app does not have.
@@ -92,7 +101,11 @@ const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 		const model = models[view.resource];
 		if (!model) return [];
 		const related = view.layout.flatMap((item) => item.kind === "related" ? relatedErrors(item, view.resource, models).map((error) => `related "${item.title}": ${error}`) : []);
-		const photos = [...(view.list?.displays ?? []).flatMap((display) => display.kind === "cards" && display.photos ? cardPhotosErrors(display.photos, view.resource, models).map((error) => `display "${display.name}" photos: ${error}`) : []), ...sharedPhotosErrors(view)];
+		const photos = [
+			...(view.list?.displays ?? []).flatMap((display) => display.kind === "cards" && display.photos ? cardPhotosErrors(display.photos, view.resource, models).map((error) => `display "${display.name}" photos: ${error}`) : []),
+			...sharedPhotosErrors(view),
+			...view.layout.flatMap((item) => item.kind === "gallery" ? galleryErrors(item, view.resource, model, models).map((error) => `gallery "${item.title}": ${error}`) : [])
+		];
 		const favorites = (view.list?.displays ?? []).flatMap((display) => display.kind === "cards" && display.favorite ? [...cardFavoriteErrors(display.favorite, view.resource, models), ...favoriteOwnerErrors(display.favorite, models)].map((error) => `display "${display.name}" favorite: ${error}`) : []);
 		const listOf = view.listOf === void 0 ? [] : listOfErrors(model, view.listOf, models).map((error) => `listOf: ${error}`);
 		const searches = [...view.saveSearch ? saveSearchErrors(view.saveSearch, view.resource, models, views).map((error) => `saveSearch: ${error}`) : [], ...view.searchesOf ? searchesOfErrors(view.searchesOf, view.resource, models).map((error) => `searchesOf: ${error}`) : []];

package/dist/index.d.ts

@@ -37,6 +37,7 @@ import { MapOptions, mapStyleUrl, mapStyleVariable } from "./maps/map-settings.j
 import { RuntimeOptions, runtimeUrl, runtimeVariable, seesRuntime } from "./runtime/runtime-settings.js";
 import { AdminOptions } from "./admin-options.js";
 import { CreateAdminInput, createAdmin } from "./create-admin.js";
+import { checkViewQueries } from "./check-view-queries.js";
 import { ProjectConfig, defineConfig, mergeConfig } from "./project-config.js";
 import { consoleAuditQueue } from "./audit/console-queue.js";
 import { JwtOptions, jwtAuthenticator } from "./auth/jwt.js";
@@ -82,4 +83,4 @@ import { FatalJobError } from "./jobs/run-job.js";
 import { DrainResult, JobsRuntime, StartJobsOptions, startJobs } from "./jobs/runtime.js";
 import { jobsDrainApp } from "./jobs/drain-route.js";
 import { checkJobsSchema, jobsSchema, jobsSchemaMigration } from "./jobs/schema.js";
-export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type CapturedRow, type ChatMessage, type ChatTextPart, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSource, HttpProblem, type IssueTokenOptions, type JobContext, type JobDefinition, type JobOptions, type JobsRuntime, type JwtOptions, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapOptions, type MemberInput, MissingCredentials, ModelError, type ModelSettings, type NewOrganization, type NewUser, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type ProjectConfig, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type QueryOptions, type QueryResult, type ReasoningDetail, type ReasoningEffort, type RecordKeyInput, type RecordPage, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredObject, type StoredOrganization, type StoredUser, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineEmail, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storeFile, streamChatCompletion, subscription, thumbHash, unauthorized, variantPath, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };
+export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type CapturedRow, type ChatMessage, type ChatTextPart, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSource, HttpProblem, type IssueTokenOptions, type JobContext, type JobDefinition, type JobOptions, type JobsRuntime, type JwtOptions, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapOptions, type MemberInput, MissingCredentials, ModelError, type ModelSettings, type NewOrganization, type NewUser, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type ProjectConfig, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type QueryOptions, type QueryResult, type ReasoningDetail, type ReasoningEffort, type RecordKeyInput, type RecordPage, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredObject, type StoredOrganization, type StoredUser, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineEmail, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storeFile, streamChatCompletion, subscription, thumbHash, unauthorized, variantPath, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };

package/dist/index.js

@@ -42,6 +42,7 @@ import { checkSourceNames, sourceOptions, sourcesFor, sourcesVariable } from "./
 import { renderVariant, thumbHash } from "./files/images.js";
 import { createAdmin } from "./create-admin.js";
 import { configExports } from "./resource-source.js";
+import { checkViewQueries } from "./check-view-queries.js";
 import { defineConfig, mergeConfig } from "./project-config.js";
 import { jwtAuthenticator } from "./auth/jwt.js";
 import { withTrustedApps } from "./better-auth/app-tokens.js";
@@ -63,4 +64,4 @@ import { aspectRatio, fileSize, fileType, imageSize, processor } from "./files/p
 import { defineEmail } from "./mail/define-email.js";
 import { startJobs } from "./jobs/runtime.js";
 import { jobsDrainApp } from "./jobs/drain-route.js";
-export { FatalJobError, HttpProblem, MissingCredentials, ModelError, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineEmail, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storeFile, streamChatCompletion, subscription, thumbHash, unauthorized, variantPath, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };
+export { FatalJobError, HttpProblem, MissingCredentials, ModelError, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineEmail, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storeFile, streamChatCompletion, subscription, thumbHash, unauthorized, variantPath, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };

package/dist/list-photos.js

@@ -69,8 +69,7 @@ const recordPhotos = async (deps, request, model, rows) => {
 	const scope = readScope(access);
 	const warning = await deps.guard(access.entry, {
 		filter: filter.filter,
-		...sort && { sort },
-		limit: cardPhotoLimit
+		...sort && { sort }
 	}, {
 		model: access.model,
 		scope

package/dist/list-service.js

@@ -9,8 +9,9 @@ import { readTransaction } from "./transactions.js";
 import { deletedRows, listParams, pageSizeOf, parseParams, seekParams, selectedFields } from "./params.js";
 import { labelRequests, relatedLabels } from "./related-labels.js";
 import { photosRequest, recordPhotos } from "./list-photos.js";
-import { estimateCount, exactCount, listQuery, seekToPosition } from "@protobase/query";
+import { countUpTo, estimateCount, listQuery, seekToPosition } from "@protobase/query";
 //#region src/list-service.ts
+const exactCountLimit = 1e4;
 /**
 * AIP-132 list, the `:search` variant and (with `jump`) `:seek`: both take the same parameters, from the query string or a JSON body.
 * Everything the caller names (filter, order_by, fields, search) is checked against the model as this caller sees it,
@@ -82,7 +83,7 @@ const listRecords = async (deps, entry, session, input, maxFilterLength, jump =
 			etags: await Promise.all(rows.map((row, i) => etagOf(entry, page.rows[i], row))),
 			permissions: deps.rowPermissions(entry.name) ? await rowPermissions(trx, access, rows) : void 0,
 			estimate: await estimateCount(trx, queryModel, filter, scope),
-			...params.count === "exact" && { total: await exactCount(trx, queryModel, filter, scope) },
+			...params.count === "exact" && { counted: await countUpTo(trx, queryModel, 10001, filter, scope) },
 			...params.labels !== void 0 && { labels: await relatedLabels(trx, labels, rows) }
 		};
 	});
@@ -99,7 +100,7 @@ const listRecords = async (deps, entry, session, input, maxFilterLength, jump =
 			next_page_token: result.page.nextCursor ?? "",
 			...position !== void 0 && { prev_page_token: result.page.prevCursor ?? "" },
 			total_size_estimate: result.estimate,
-			...result.total !== void 0 && { total_size: result.total },
+			...result.counted !== void 0 && result.counted <= exactCountLimit && { total_size: result.counted },
 			...result.labels && { labels: result.labels },
 			...included && { photos: included.photos }
 		}

package/dist/map-service.js

@@ -48,7 +48,7 @@ const mapRecords = async (deps, entry, session, input) => {
 			body: {
 				items: body.items,
 				buckets: [],
-				total_size: body.total_size ?? found,
+				total_size: body.total_size ?? (found > 200 ? body.total_size_estimate : found),
 				...body.labels && { labels: body.labels },
 				...body.photos && { photos: body.photos }
 			}

package/dist/openapi/components.js

@@ -93,7 +93,7 @@ const parameters = {
 	count: {
 		name: "count",
 		in: "query",
-		description: "`exact` adds `total_size`, a real count(*)",
+		description: "`exact` adds `total_size`, a count of the matches when at most 10,000 match",
 		schema: {
 			type: "string",
 			enum: ["exact"]

package/dist/openapi/resource-paths.js

@@ -79,7 +79,7 @@ const page = (name, seek = false) => json({
 		},
 		total_size: {
 			type: "integer",
-			description: "Only with count=exact"
+			description: "Only with count=exact, and when at most 10,000 records match"
 		},
 		labels,
 		photos

package/dist/routes/collection.js

@@ -21,7 +21,10 @@ const collectionRoutes = (deps) => {
 			const { body, warning } = await listRecords(deps, entry, session, query);
 			return c.json(body, 200, warningHeader(warning));
 		}
-		if (action === "facets") return c.json(await facets(deps, entry, session, query));
+		if (action === "facets") {
+			const { body, warning } = await facets(deps, entry, session, query);
+			return c.json(body, 200, warningHeader(warning));
+		}
 		if (action === "series") return c.json(await timeSeries(deps, entry, session, query));
 		if (action === "histogram") return c.json(await numericHistogram(deps, entry, session, query));
 		if (action === "map") {

package/dist/scan-guard.js

@@ -1,70 +1,43 @@
 import { HttpProblem } from "./problem.js";
-import { scopeConditions, tableId } from "./sql-parts.js";
-import { filterFields, filterShape } from "./filter-shape.js";
-import { buildListQuery, compileFilter, explainGuard } from "@protobase/query";
-import { sql } from "kysely";
+import { tableIndexes, uncoveredColumns } from "@protobase/query";
 //#region src/scan-guard.ts
-const maxCached = 1e3;
-const filteredQuery = (db, entry, shape, { scope }) => {
-	const { model } = entry;
-	const conditions = [
-		...scopeConditions(scope.fullModel ?? model, scope.tenantValue),
-		...scope.rowFilter ? [compileFilter(model, scope.rowFilter)] : [],
-		...shape.filter ? [compileFilter(model, shape.filter)] : []
-	];
-	let query = db.selectFrom(sql`${tableId(model)}`.as("t")).select(sql.lit(1).as("one"));
-	for (const condition of conditions) query = query.where(condition);
-	return query;
+const reading = (column) => {
+	switch (column.use) {
+		case "filter": return `Filtering on "${column.field}"`;
+		case "access": return `The filter your role is limited by, on "${column.field}",`;
+		case "sort": return `Sorting by "${column.field}"`;
+		case "facet": return `Counting the values of "${column.field}"`;
+	}
 };
-const pagedQuery = async (db, shape, { model, scope }) => {
-	const { query } = await buildListQuery(db, model, shape, scope);
-	return query;
+const describe = (column) => {
+	const kind = column.need === "btree" ? "an index" : column.need === "gin" ? "a GIN index" : "a pg_trgm index";
+	return `${reading(column)} needs ${kind} that serves the column "${column.column}". Add one, for example: ${column.suggestion}`;
 };
-const indexStatement = (entry, fields) => {
-	const { schema, name } = entry.model.table;
-	const table = schema ? `"${schema}"."${name}"` : `"${name}"`;
-	const columns = [...new Set(fields.map((field) => field.column))];
-	if (columns.length === 0) return "an index that covers the filter your role is limited by";
-	return `create index on ${table} (${columns.map((column) => `"${column}"`).join(", ")})`;
-};
-/** Plans each list query shape once (EXPLAIN, never executed) and remembers the verdict. */
+/**
+* Checks that an index serves every column a read filters, sorts or groups by, from the table's indexes in the catalog
+* (read once per table and kept for the process lifetime), so a read is never refused or allowed by how many rows match.
+*/
 const createScanGuard = (db, options = {}) => {
-	const { mode = "reject", seqScanRows } = options;
-	const verdicts = /* @__PURE__ */ new Map();
-	const thresholds = {
-		...seqScanRows && { seqScanRows },
-		sortRows: Number.MAX_SAFE_INTEGER
-	};
-	const judge = async (entry, shape, context) => {
-		const filtered = shape.filter ? await explainGuard(db, filteredQuery(db, entry, shape, context), thresholds) : void 0;
-		const paged = await explainGuard(db, await pagedQuery(db, shape, context), thresholds);
-		const sortField = shape.sort?.[0] && entry.model.fields[shape.sort[0][0]];
-		const suggestions = [...filtered && !filtered.ok ? [indexStatement(entry, filterFields(shape.filter))] : [], ...!paged.ok && sortField ? [indexStatement(entry, [sortField])] : []];
-		return {
-			findings: [...filtered?.findings ?? [], ...paged.findings],
-			suggestion: suggestions[0] ?? indexStatement(entry, filterFields(shape.filter))
-		};
-	};
-	const verdictFor = async (entry, shape, context) => {
-		const key = `${entry.name}|${filterShape(context.scope.rowFilter)}|${filterShape(shape.filter)}|${(shape.sort ?? []).map(([name, direction]) => `${name}:${direction}`).join(",")}`;
-		const known = verdicts.get(key);
+	const { mode = "reject" } = options;
+	const tables = /* @__PURE__ */ new Map();
+	const indexesOf = async (entry) => {
+		const known = tables.get(entry.name);
 		if (known) return known;
-		const verdict = await judge(entry, shape, context);
-		if (verdicts.size >= maxCached) verdicts.delete(verdicts.keys().next().value);
-		verdicts.set(key, verdict);
-		return verdict;
+		const read = await tableIndexes(db, entry.model);
+		tables.set(entry.name, read);
+		return read;
 	};
-	/** Throws a 400 problem for an expensive shape in `reject` mode; in `warn` mode returns the warning text. */
-	return async (entry, shape, context) => {
+	/** Throws a 400 problem for a column no index serves in `reject` mode; in `warn` mode returns the warning text. */
+	return async (entry, query, context) => {
 		if (mode === "off") return void 0;
-		const { findings, suggestion } = await verdictFor(entry, shape, context);
-		const finding = findings[0];
-		if (!finding) return void 0;
-		const detail = `This query would sequentially scan "${finding.relation}" (about ${finding.rows} rows). Add an index, for example: ${suggestion}`;
+		const columns = uncoveredColumns(context.model, await indexesOf(entry), query, context.scope);
+		const first = columns[0];
+		if (!first) return void 0;
+		const detail = describe(first);
 		if (mode === "warn") return detail;
 		throw new HttpProblem(400, "expensive-query", "Bad Request", detail, {
-			findings,
-			suggestion
+			columns,
+			suggestion: first.suggestion
 		});
 	};
 };

package/dist/view-access.js

@@ -14,6 +14,17 @@ const pruneRelated = (item, resource, models) => {
 	} : rest;
 	return relatedErrors(narrowed, resource, models).length === 0 ? narrowed : void 0;
 };
+const pruneGallery = (item, resource, model, models) => {
+	const image = item.image !== void 0 && Object.hasOwn(model.fields, item.image) ? item.image : void 0;
+	const photos = item.photos && cardPhotosErrors(item.photos, resource, models).length === 0 ? item.photos : void 0;
+	if (image === void 0 && photos === void 0) return void 0;
+	return {
+		kind: "gallery",
+		title: item.title,
+		...image !== void 0 && { image },
+		...photos && { photos }
+	};
+};
 const keepDefault = ({ default: opens, displays, ...list }) => {
 	const shown = displays && displays.length > 0 ? displays : void 0;
 	const kept = opens === tableDisplay || shown?.some((display) => display.name === opens);
@@ -97,11 +108,12 @@ const widgetShape = shapes.oneOf({
 		label: shapes.data
 	}, { requires: ["fields"] })
 });
-const layoutShape = (resource, models) => shapes.oneOf({
+const layoutShape = (resource, model, models) => shapes.oneOf({
 	section: shapes.object({
 		kind: shapes.data,
 		title: shapes.data,
 		help: shapes.data,
+		helpWhen: shapes.data,
 		fields: shapes.list(shapes.field, { nonEmpty: true })
 	}, { requires: ["fields"] }),
 	sidebar: shapes.object({
@@ -123,7 +135,8 @@ const layoutShape = (resource, models) => shapes.oneOf({
 		longitude: shapes.field,
 		zoom: shapes.data,
 		sidebar: shapes.data
-	}, { requires: ["latitude", "longitude"] })
+	}, { requires: ["latitude", "longitude"] }),
+	gallery: shapes.map((item) => pruneGallery(item, resource, model, models))
 });
 const linkShape = (model, models) => shapes.map((run) => {
 	return ("to" in run ? addressErrors(run.to, {
@@ -166,12 +179,14 @@ const viewShape = (resource, model, models, prompted) => shapes.object({
 	fields: shapes.keys(),
 	list: listShape(resource, models, prompted),
 	filters: shapes.list(widgetShape),
-	layout: shapes.list(layoutShape(resource, models)),
+	layout: shapes.list(layoutShape(resource, model, models)),
 	chart: shapes.object({
 		field: shapes.field,
 		range: shapes.data,
 		granularity: shapes.data
 	}, { requires: ["field"] }),
+	recordMode: shapes.data,
+	helpWhen: shapes.data,
 	saveFeedback: shapes.data,
 	actions: shapes.list(actionShape(model, models)),
 	listOf: shapes.field,
@@ -181,7 +196,7 @@ const viewShape = (resource, model, models, prompted) => shapes.object({
 });
 /**
 * The view with every reference to a field the caller cannot read removed: list columns, sort, search and displays,
-* field hints, filter widgets, record sections, maps and custom components' props, the chart, title and search result, the
+* field hints, filter widgets, record sections, maps, galleries and custom components' props, the chart, title and search result, the
 * actions that set or read one, and the sidebar's `recent` group. Nothing in it may name a hidden field. Related sections
 * and links are checked against `models`, the caller's view of every resource, and so are `searchesOf`, cards' favorite
 * buttons and the "Save search" button; the buttons stay for a visitor when their resource is one of `prompted`, those

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
-    "@protobase/layout": "0.17.0",
-    "@protobase/query": "0.17.0",
-    "@protobase/schema": "0.17.0",
+    "@protobase/layout": "0.19.0",
+    "@protobase/query": "0.19.0",
+    "@protobase/schema": "0.19.0",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",

package/dist/filter-shape.js

@@ -1,25 +0,0 @@
-//#region src/filter-shape.ts
-/** The filter with its values blanked out: queries that differ only in values share a shape. */
-const filterShape = (filter) => {
-	if (!filter) return "";
-	switch (filter.kind) {
-		case "and":
-		case "or": return `${filter.kind}(${filter.args.map(filterShape).join(",")})`;
-		case "not": return `not(${filterShape(filter.arg)})`;
-		case "compare": return `${filter.field.name}${filter.op}?`;
-		case "search": return "search";
-		default: return `${filter.kind}:${filter.field.name}`;
-	}
-};
-const filterFields = (filter) => {
-	if (!filter) return [];
-	switch (filter.kind) {
-		case "and":
-		case "or": return filter.args.flatMap(filterFields);
-		case "not": return filterFields(filter.arg);
-		case "search": return [];
-		default: return [filter.field];
-	}
-};
-//#endregion
-export { filterFields, filterShape };