emdash 1.0.1 → 1.2.0

package/src/redirects/cache.ts

@@ -3,19 +3,19 @@
  *
  * Worker-isolate cache for enabled redirect rules. The middleware populates
  * this on first request; route handlers invalidate it on writes. Cached rules
- * expire so writes handled by another isolate become visible here too.
+ * are revalidated after they expire so writes handled by another isolate
+ * become visible here too.
  *
- * Both exact-match and pattern rules are loaded from one query and cached
- * together: exact rules indexed by source path in a Map, pattern rules
- * pre-compiled into an array. A single warm request issues zero database
- * queries; a cold or expired isolate issues one.
+ * A cold isolate loads the rules from its source and waits for them. Once
+ * warm, requests never wait: an expired cache keeps serving while one
+ * background revalidation asks the source whether the loaded version is still
+ * current and reloads only when it is not.
  *
  * This module deliberately has NO Astro imports so it can be safely imported
  * from handlers, seed, CLI, and tests without dragging in `astro:middleware`.
  */
 
 import { after } from "../after.js";
-import type { Redirect } from "../database/repositories/redirect.js";
 import {
 	createSingleFlightCache,
 	type SingleFlightCache,
@@ -30,15 +30,38 @@ import {
 	validatePattern,
 } from "./patterns.js";
 
+export interface RedirectRule {
+	id: string;
+	source: string;
+	destination: string;
+	type: number;
+}
+
+export interface RedirectRuleSet {
+	/** Identifies the loaded rules for revalidation, or null when they can only be reloaded. */
+	version: string | null;
+	/** Exact rules; a later rule for the same source replaces an earlier one. */
+	exact: RedirectRule[];
+	/** Pattern rules in precedence order. */
+	patterns: RedirectRule[];
+}
+
+export interface RedirectSource {
+	load(): Promise<RedirectRuleSet>;
+	/** Whether `version` is still the source's current rule set. */
+	isCurrent(version: string): Promise<boolean>;
+}
+
 export interface CachedRedirectRule {
-	redirect: Redirect;
+	redirect: RedirectRule;
 	compiled: CompiledPattern;
 }
 
 export interface CachedRedirects {
-	/** Exact-match rules indexed by source path (`source` -> `Redirect`). */
-	exact: Map<string, Redirect>;
-	/** Pattern rules with their compiled regexes, preserving insertion order. */
+	version: string | null;
+	/** Exact-match rules indexed by source path. */
+	exact: Map<string, RedirectRule>;
+	/** Pattern rules with their compiled regexes, in precedence order. */
 	patterns: CachedRedirectRule[];
 }
 
@@ -47,6 +70,7 @@ interface RedirectCacheState {
 	expiresAt: number;
 	generation: number;
 	refresh: SingleFlightCache<CachedRedirects>;
+	revalidatingUntil: number;
 }
 
 const REDIRECT_CACHE_TTL_MS = 30_000;
@@ -62,6 +86,7 @@ const cacheState: RedirectCacheState =
 			expiresAt: 0,
 			generation: 0,
 			refresh: createSingleFlightCache<CachedRedirects>(),
+			revalidatingUntil: 0,
 		};
 		g[REDIRECT_CACHE_KEY] = state;
 		return state;
@@ -75,36 +100,24 @@ export function invalidateRedirectCache(): void {
 	cacheState.generation++;
 	cacheState.redirects = null;
 	cacheState.expiresAt = 0;
+	cacheState.revalidatingUntil = 0;
 	invalidateSingleFlightCache(cacheState.refresh);
 }
 
-/**
- * Get the cached redirects, or null if the cache is cold.
- */
-function getCachedRedirects(): CachedRedirects | null {
-	if (cacheState.redirects && Date.now() >= cacheState.expiresAt) {
-		invalidateRedirectCache();
-	}
-	return cacheState.redirects;
-}
-
-/** Compile enabled database rows into the in-memory lookup structures. */
-function compileRedirects(redirects: Redirect[]): CachedRedirects {
-	const exact = new Map<string, Redirect>();
+/** Compile a rule set into the in-memory lookup structures. */
+function compileRedirects(rules: RedirectRuleSet): CachedRedirects {
+	const exact = new Map<string, RedirectRule>();
+	for (const rule of rules.exact) exact.set(rule.source, rule);
 	const patterns: CachedRedirectRule[] = [];
-	for (const r of redirects) {
-		if (r.isPattern) {
-			const patternError = validatePattern(r.source);
-			if (patternError) {
-				console.warn(`[emdash:redirects] Skipping redirect ${r.id}: ${patternError}`);
-				continue;
-			}
-			patterns.push({ redirect: r, compiled: compilePattern(r.source) });
-		} else {
-			exact.set(r.source, r);
+	for (const rule of rules.patterns) {
+		const patternError = validatePattern(rule.source);
+		if (patternError) {
+			console.warn(`[emdash:redirects] Skipping redirect ${rule.id}: ${patternError}`);
+			continue;
 		}
+		patterns.push({ redirect: rule, compiled: compilePattern(rule.source) });
 	}
-	return { exact, patterns };
+	return { version: rules.version, exact, patterns };
 }
 
 function installCachedRedirects(redirects: CachedRedirects): CachedRedirects {
@@ -113,17 +126,39 @@ function installCachedRedirects(redirects: CachedRedirects): CachedRedirects {
 	return cacheState.redirects;
 }
 
-export async function loadCachedRedirects(
-	load: () => Promise<Redirect[]>,
-): Promise<CachedRedirects> {
+function revalidateInBackground(source: RedirectSource, cached: CachedRedirects): void {
+	const now = Date.now();
+	if (cacheState.revalidatingUntil > now) return;
+	cacheState.revalidatingUntil = now + REDIRECT_CACHE_TTL_MS;
+	const generation = cacheState.generation;
+	after(async () => {
+		try {
+			if (cached.version !== null && (await source.isCurrent(cached.version))) {
+				if (generation === cacheState.generation) {
+					cacheState.expiresAt = Date.now() + REDIRECT_CACHE_TTL_MS;
+				}
+				return;
+			}
+			const loaded = compileRedirects(await source.load());
+			if (generation === cacheState.generation) installCachedRedirects(loaded);
+		} catch (error) {
+			console.error("[emdash:redirects] revalidating redirects failed:", error);
+		}
+	});
+}
+
+export async function loadCachedRedirects(source: RedirectSource): Promise<CachedRedirects> {
 	for (let attempt = 0; attempt < REDIRECT_CACHE_MAX_REFRESH_ATTEMPTS; attempt++) {
-		const cached = getCachedRedirects();
-		if (cached) return cached;
+		const cached = cacheState.redirects;
+		if (cached) {
+			if (Date.now() >= cacheState.expiresAt) revalidateInBackground(source, cached);
+			return cached;
+		}
 
 		const generation = cacheState.generation;
 		const loaded = await singleFlightCached(
 			cacheState.refresh,
-			async () => compileRedirects(await load()),
+			async () => compileRedirects(await source.load()),
 			{ anchor: (promise) => after(() => promise), ownerTimeoutMs: 30_000 },
 		);
 
@@ -146,7 +181,7 @@ export async function loadCachedRedirects(
 export function matchCachedPatterns(
 	rules: CachedRedirectRule[],
 	pathname: string,
-): { redirect: Redirect; destination: string } | null {
+): { redirect: RedirectRule; destination: string } | null {
 	for (const { redirect, compiled } of rules) {
 		const params = matchPattern(compiled, pathname);
 		if (params) {

package/src/redirects/patterns.ts

@@ -160,20 +160,44 @@ export function compilePattern(source: string): CompiledPattern {
 	};
 }
 
+function toggledTrailingSlash(path: string): string | null {
+	if (path.length <= 1) return null;
+	return path.endsWith("/") ? path.slice(0, -1) : `${path}/`;
+}
+
 /**
  * Match a path against a compiled pattern.
  * Returns captured params or null if no match.
+ *
+ * Trailing slashes are ignored so `/category/arts/feed` and
+ * `/category/arts/feed/` match the same rule, consistent with exact and
+ * catch-all redirects.
  */
 export function matchPattern(
 	compiled: CompiledPattern,
 	path: string,
 ): Record<string, string> | null {
 	const match = path.match(compiled.regex);
-	if (!match) return null;
+	if (match) {
+		const params: Record<string, string> = {};
+		for (let i = 0; i < compiled.paramNames.length; i++) {
+			const value = match[i + 1];
+			if (value !== undefined) {
+				params[compiled.paramNames[i]] = value;
+			}
+		}
+		return params;
+	}
+
+	const alt = toggledTrailingSlash(path);
+	if (!alt) return null;
+
+	const altMatch = alt.match(compiled.regex);
+	if (!altMatch) return null;
 
 	const params: Record<string, string> = {};
 	for (let i = 0; i < compiled.paramNames.length; i++) {
-		const value = match[i + 1];
+		const value = altMatch[i + 1];
 		if (value !== undefined) {
 			params[compiled.paramNames[i]] = value;
 		}

package/src/request-context.ts

@@ -100,7 +100,7 @@ export interface EmDashRequestContext {
 	 */
 	dbIsIsolated?: boolean;
 	/**
-	 * Query recorder attached by middleware when EMDASH_QUERY_LOG_FILE is set.
+	 * Query recorder attached by middleware when EMDASH_QUERY_LOG=1 is set.
 	 * The Kysely `log` hook appends an event per query; middleware flushes
 	 * to NDJSON after the response.
 	 */

package/src/schema/registry.ts

@@ -50,6 +50,7 @@ import type {
 } from "../transfer/schema-importer.js";
 import { chunks, SQL_BATCH_SIZE } from "../utils/chunks.js";
 import { resetRegisteredCollectionsCache } from "./collection-slugs-cache.js";
+import { MAX_SCHEMA_SLUG_LENGTH, SCHEMA_SLUG_PATTERN } from "./slug.js";
 import {
 	type Collection,
 	type CollectionAdminConfig,
@@ -76,7 +77,6 @@ import {
 import { compileUrlPattern } from "./url-pattern.js";
 
 // Regex patterns for schema registry
-const SLUG_VALIDATION_PATTERN = /^[a-z][a-z0-9_]*$/;
 const EC_PREFIX_PATTERN = /^ec_/;
 const SINGLE_QUOTE_PATTERN = /'/g;
 const UNDERSCORE_PATTERN = /_/g;
@@ -2331,15 +2331,18 @@ export class SchemaRegistry {
 			throw new SchemaError(`${type} slug is required`, "INVALID_SLUG");
 		}
 
-		if (!SLUG_VALIDATION_PATTERN.test(slug)) {
+		if (!SCHEMA_SLUG_PATTERN.test(slug)) {
 			throw new SchemaError(
 				`${type} slug must start with a letter and contain only lowercase letters, numbers, and underscores`,
 				"INVALID_SLUG",
 			);
 		}
 
-		if (slug.length > 63) {
-			throw new SchemaError(`${type} slug must be 63 characters or less`, "INVALID_SLUG");
+		if (slug.length > MAX_SCHEMA_SLUG_LENGTH) {
+			throw new SchemaError(
+				`${type} slug must be ${MAX_SCHEMA_SLUG_LENGTH} characters or less`,
+				"INVALID_SLUG",
+			);
 		}
 	}
 

package/src/schema/slug.ts

@@ -0,0 +1,19 @@
+/**
+ * The collection and field slug rule.
+ */
+
+/** Lowercase letter first, then lowercase letters, digits, and underscores. */
+export const SCHEMA_SLUG_PATTERN = /^[a-z][a-z0-9_]*$/;
+
+/** Maximum length of a collection or field slug. */
+export const MAX_SCHEMA_SLUG_LENGTH = 63;
+
+/** Whether `value` is a valid collection or field slug. */
+export function isValidSchemaSlug(value: unknown): value is string {
+	return (
+		typeof value === "string" &&
+		value.length > 0 &&
+		value.length <= MAX_SCHEMA_SLUG_LENGTH &&
+		SCHEMA_SLUG_PATTERN.test(value)
+	);
+}

package/src/search/text-extraction.ts

@@ -8,6 +8,7 @@
 import { toPlainText } from "@portabletext/toolkit";
 
 import type { PortableTextBlock } from "../content/converters/types.js";
+import { isPortableTextVideoBlock } from "../content/converters/video.js";
 
 /**
  * Validate that a value looks like a Portable Text block array.
@@ -44,6 +45,10 @@ function extractCustomBlockText(block: PortableTextBlock): string {
 		return parts.join(" ");
 	}
 
+	if (isPortableTextVideoBlock(block)) {
+		return block.caption ?? "";
+	}
+
 	return "";
 }
 
@@ -51,7 +56,7 @@ function extractCustomBlockText(block: PortableTextBlock): string {
  * Extract plain text from Portable Text blocks
  *
  * Uses @portabletext/toolkit's toPlainText for standard blocks,
- * plus extracts text from custom block types (code, images with alt/caption).
+ * plus extracts text from custom block types (code, images with alt/caption, video captions).
  *
  * @param blocks - Array of Portable Text blocks (or a JSON string)
  * @returns Plain text content

package/src/seed/apply.ts

@@ -40,7 +40,7 @@ import type { MediaValue } from "../fields/types.js";
 import { getI18nConfig, resolveConfiguredLocale } from "../i18n/config.js";
 import { ssrfSafeFetch, validateExternalUrl } from "../import/ssrf.js";
 import { markContentMediaUsageCollectionStaleSafely } from "../media/usage/content-refresh.js";
-import { coalesceObjectCacheWrites } from "../object-cache/index.js";
+import { coalesceObjectCacheWrites, invalidateMenuObjectCache } from "../object-cache/index.js";
 import { BlockTypeRegistry } from "../schema/block-type-registry.js";
 import { normalizeBlocksData, resolveBlockTypes } from "../schema/block-values.js";
 import { SchemaError, SchemaRegistry } from "../schema/registry.js";
@@ -1086,64 +1086,68 @@ async function applySeedWrites(
 		// Shared across menus: translated items reference anchor items in sibling menus.
 		const itemSeedIdMap = new Map<string, { id: string; translationGroup: string }>();
 
-		for (const menu of seed.menus) {
-			const locale = resolveConfiguredLocale(menu.locale ?? defaultLocale);
-			let lookup = db
-				.selectFrom("_emdash_menus")
-				.selectAll()
-				.where("name", "=", menu.name)
-				.where("locale", "=", locale);
-			const existingMenu = await lookup.executeTakeFirst();
-
-			let menuId: string;
-			let translationGroup: string;
-
-			if (existingMenu) {
-				menuId = existingMenu.id;
-				translationGroup = existingMenu.translation_group ?? existingMenu.id;
-				// Clear existing items (menus are recreated)
-				await db.deleteFrom("_emdash_menu_items").where("menu_id", "=", menuId).execute();
-			} else {
-				menuId = ulid();
-				// Resolve translationOf to the source menu's translation_group.
-				translationGroup = menuId;
-				if (menu.translationOf) {
-					const source = menuSeedIdMap.get(menu.translationOf);
-					if (source) translationGroup = source.translationGroup;
-					else
-						console.warn(
-							`menu "${menu.name}" (${locale}): translationOf "${menu.translationOf}" not found yet; minting a fresh group.`,
-						);
+		try {
+			for (const menu of seed.menus) {
+				const locale = resolveConfiguredLocale(menu.locale ?? defaultLocale);
+				let lookup = db
+					.selectFrom("_emdash_menus")
+					.selectAll()
+					.where("name", "=", menu.name)
+					.where("locale", "=", locale);
+				const existingMenu = await lookup.executeTakeFirst();
+
+				let menuId: string;
+				let translationGroup: string;
+
+				if (existingMenu) {
+					menuId = existingMenu.id;
+					translationGroup = existingMenu.translation_group ?? existingMenu.id;
+					// Clear existing items (menus are recreated)
+					await db.deleteFrom("_emdash_menu_items").where("menu_id", "=", menuId).execute();
+				} else {
+					menuId = ulid();
+					// Resolve translationOf to the source menu's translation_group.
+					translationGroup = menuId;
+					if (menu.translationOf) {
+						const source = menuSeedIdMap.get(menu.translationOf);
+						if (source) translationGroup = source.translationGroup;
+						else
+							console.warn(
+								`menu "${menu.name}" (${locale}): translationOf "${menu.translationOf}" not found yet; minting a fresh group.`,
+							);
+					}
+					await db
+						.insertInto("_emdash_menus")
+						.values({
+							id: menuId,
+							name: menu.name,
+							label: menu.label,
+							created_at: new Date().toISOString(),
+							updated_at: new Date().toISOString(),
+							locale,
+							translation_group: translationGroup,
+						})
+						.execute();
+					result.menus.created++;
 				}
-				await db
-					.insertInto("_emdash_menus")
-					.values({
-						id: menuId,
-						name: menu.name,
-						label: menu.label,
-						created_at: new Date().toISOString(),
-						updated_at: new Date().toISOString(),
-						locale,
-						translation_group: translationGroup,
-					})
-					.execute();
-				result.menus.created++;
-			}
 
-			if (menu.id) menuSeedIdMap.set(menu.id, { id: menuId, translationGroup });
-
-			// Create menu items
-			const itemCount = await applyMenuItems(
-				db,
-				menuId,
-				locale,
-				menu.items,
-				null, // parent_id
-				0, // sort_order
-				seedIdMap,
-				itemSeedIdMap,
-			);
-			result.menus.items += itemCount;
+				if (menu.id) menuSeedIdMap.set(menu.id, { id: menuId, translationGroup });
+
+				// Create menu items
+				const itemCount = await applyMenuItems(
+					db,
+					menuId,
+					locale,
+					menu.items,
+					null, // parent_id
+					0, // sort_order
+					seedIdMap,
+					itemSeedIdMap,
+				);
+				result.menus.items += itemCount;
+			}
+		} finally {
+			invalidateMenuObjectCache();
 		}
 	}
 
@@ -1306,6 +1310,10 @@ async function applySeedWrites(
 		}
 	}
 
+	if (result.redirects.created + result.redirects.updated > 0) {
+		const { publishRedirectChanges } = await import("../redirects/artifacts.js");
+		await publishRedirectChanges(db);
+	}
 	await invalidateSeedCaches();
 
 	return { result, complete, progress };

package/src/seed/validate.ts

@@ -14,6 +14,8 @@ import {
 	MAX_COLLECTION_GROUP_LENGTH,
 	MAX_COLLECTION_ICON_LENGTH,
 	MAX_COLLECTION_LIST_COLUMNS,
+	RESERVED_COLLECTION_SLUGS,
+	RESERVED_FIELD_SLUGS,
 } from "../schema/types.js";
 import { compileUrlPattern } from "../schema/url-pattern.js";
 import type { SeedFile, SeedMenuItem, SeedTaxonomy, ValidationResult } from "./types.js";
@@ -187,6 +189,11 @@ export function validateSeed(data: unknown): ValidationResult {
 						);
 					}
 
+					// Reserved slugs pass the format check but are rejected by the schema registry on apply
+					if (RESERVED_COLLECTION_SLUGS.includes(collection.slug)) {
+						errors.push(`${prefix}.slug: collection slug "${collection.slug}" is reserved`);
+					}
+
 					// Check for duplicate slugs
 					if (collectionSlugs.has(collection.slug)) {
 						errors.push(`${prefix}.slug: duplicate collection slug "${collection.slug}"`);
@@ -294,6 +301,11 @@ export function validateSeed(data: unknown): ValidationResult {
 								);
 							}
 
+							// Reserved slugs pass the format check but are rejected by the schema registry on apply
+							if (RESERVED_FIELD_SLUGS.includes(field.slug)) {
+								errors.push(`${fieldPrefix}.slug: field slug "${field.slug}" is reserved`);
+							}
+
 							// Check for duplicate field slugs
 							if (fieldSlugs.has(field.slug)) {
 								errors.push(
@@ -333,6 +345,19 @@ export function validateSeed(data: unknown): ValidationResult {
 								`${fieldPrefix}.indexed: a reference field with a targetCollection stores no column to index`,
 							);
 						}
+
+						if (field.type === "repeater") {
+							const subFields = field.validation?.subFields;
+							if ("fields" in field) {
+								warnings.push(
+									`${fieldPrefix}.fields: repeater sub-fields must be defined in validation.subFields; these fields are ignored`,
+								);
+							} else if (!Array.isArray(subFields) || subFields.length === 0) {
+								warnings.push(
+									`${fieldPrefix}.validation.subFields: repeater needs a non-empty array of sub-fields, so its rows have nothing to edit`,
+								);
+							}
+						}
 					}
 				}
 			}
@@ -716,6 +741,12 @@ export function validateSeed(data: unknown): ValidationResult {
 						if (widget.type === "component" && !widget.componentId) {
 							errors.push(`${widgetPrefix}: componentId is required for component widgets`);
 						}
+
+						if ("settings" in widget) {
+							warnings.push(
+								`${widgetPrefix}.settings: not applied; widget options belong in "props"`,
+							);
+						}
 					}
 				}
 			}

package/src/seo/sitemap-name.ts

@@ -0,0 +1,22 @@
+/**
+ * The `{name}` in a per-collection sitemap path, `/sitemap-{name}.xml`.
+ */
+
+import { isValidSchemaSlug } from "../schema/slug.js";
+
+/** `{collection}` for page 1, `{collection}-{n}` for page n from 2 up. */
+const SITEMAP_NAME_RE = /^([a-z][a-z0-9_]*)(?:-([2-9]|[1-9]\d{1,5}))?$/;
+
+/**
+ * The collection and page a sitemap name refers to, or null when the name
+ * can't belong to any collection (its collection part must be a valid
+ * collection slug).
+ */
+export function parseCollectionSitemapName(
+	name: string,
+): { collection: string; page: number } | null {
+	const match = SITEMAP_NAME_RE.exec(name);
+	const collection = match?.[1];
+	if (!match || !isValidSchemaSlug(collection)) return null;
+	return { collection, page: match[2] ? Number(match[2]) : 1 };
+}

package/src/settings/index.ts

@@ -16,6 +16,7 @@ import { withTransaction } from "../database/transaction.js";
 import type { Database } from "../database/types.js";
 import { getDb } from "../loader.js";
 import { cachedQuery, invalidateObjectCache } from "../object-cache/index.js";
+import { isRecord } from "../plugin-utils.js";
 import {
 	PluginSettingEncryptionError,
 	decryptPluginSetting,
@@ -44,6 +45,9 @@ import type {
 /** Prefix for site settings in the options table */
 const SETTINGS_PREFIX = "site:";
 
+/** Settings stored as one object whose fields are updated individually. */
+const NESTED_SETTING_KEYS = new Set(["seo", "social"]);
+
 function isPluginSettingEnvelopeRecord(value: unknown): value is Record<string, unknown> {
 	return (
 		typeof value === "object" &&
@@ -336,7 +340,8 @@ export async function getSiteSettingsWithDb(
 /**
  * Set site settings (internal function used by admin API)
  *
- * Merges provided settings with existing ones. Only provided fields are updated.
+ * Merges provided settings with existing ones. Only provided fields are updated,
+ * including fields inside `seo` and `social`; `seo.defaultOgImage: null` removes the default image.
  * Media references should include just the mediaId; URLs are resolved on read.
  *
  * @param settings - Partial settings object with values to update
@@ -361,11 +366,12 @@ export async function setSiteSettings(
 ): Promise<void> {
 	const updates: Record<string, unknown> = {};
 	const deletions: string[] = [];
-	const seo = settings.seo;
+	const nestedPatches: [key: string, patch: Record<string, unknown>][] = [];
 
 	for (const [key, value] of Object.entries(settings)) {
-		if (value === undefined || (key === "seo" && seo?.defaultOgImage === null)) continue;
+		if (value === undefined) continue;
 		if (value === null) deletions.push(`${SETTINGS_PREFIX}${key}`);
+		else if (NESTED_SETTING_KEYS.has(key) && isRecord(value)) nestedPatches.push([key, value]);
 		else updates[`${SETTINGS_PREFIX}${key}`] = value;
 	}
 
@@ -375,16 +381,15 @@ export async function setSiteSettings(
 			await transactionOptions.setMany(updates);
 			await transactionOptions.deleteMany(deletions);
 
-			if (seo?.defaultOgImage === null) {
-				const existingSeo =
-					(await transactionOptions.get<SeoSettings>(`${SETTINGS_PREFIX}seo`)) ?? {};
-				const nextSeo = { ...existingSeo, ...seo };
-				delete nextSeo.defaultOgImage;
-				if (Object.keys(nextSeo).length === 0) {
-					await transactionOptions.delete(`${SETTINGS_PREFIX}seo`);
-				} else {
-					await transactionOptions.set(`${SETTINGS_PREFIX}seo`, nextSeo);
+			for (const [key, patch] of nestedPatches) {
+				const optionName = `${SETTINGS_PREFIX}${key}`;
+				const next = { ...(await transactionOptions.get<Record<string, unknown>>(optionName)) };
+				for (const [field, fieldValue] of Object.entries(patch)) {
+					if (fieldValue === null) delete next[field];
+					else if (fieldValue !== undefined) next[field] = fieldValue;
 				}
+				if (Object.keys(next).length === 0) await transactionOptions.delete(optionName);
+				else await transactionOptions.set(optionName, next);
 			}
 		});
 	} finally {

package/src/storage/index.ts

@@ -13,6 +13,8 @@ export type {
 	LocalStorageConfig,
 	UploadResult,
 	DownloadResult,
+	DownloadOptions,
+	ByteRange,
 	ListResult,
 	ListOptions,
 	FileInfo,