ignotum 0.0.6 → 0.0.8

package/dist/runtime/client.js

@@ -1,12 +1,127 @@
-import { a as InvocationId, c as SubscriptionId, i as IdAlphabet, l as TableId, n as DeploymentId, r as GeneratedId, s as RuntimeRequestNonce, t as AppId } from "./id-D570vudg.js";
-import { g as encodeTransportObject, h as decodeTransportValue, l as failureFromWire, s as Result$1, t as ValueDescriptor, u as pending } from "./descriptor-t6BOEGw9-BTHR-ZMv.js";
-import { a as FunctionAddress, c as ServerMessageJson, d as WireSuccess, f as AppStateRevision, i as DeploymentChangedCloseCode, l as WireFailure, m as InvocationKey, n as functionPathOf, o as Operation, p as DeploymentGeneration, r as ClientMessageJson, s as ProtocolErrorCode, u as WireResult } from "./api-DtX8qPrq.js";
-import { Array, Cause, Context, Deferred, Duration, Effect, ErrorReporter, Fiber, HashMap, Layer, ManagedRuntime, Predicate, Schedule, Schema, String } from "effect";
-import { useCallback, useContext, useDebugValue, useDebugValue as useDebugValue$1, useEffect, useEffect as useEffect$1, useErrorBoundary, useId, useImperativeHandle, useLayoutEffect, useMemo, useMemo as useMemo$1, useReducer, useRef, useState, useState as useState$1 } from "preact/hooks";
+import { C as RuntimeRequestNonce, T as TableId, _ as AppId, a as RuntimeFileMetadata, b as IdAlphabet, c as fileFormats, d as fileLimits, f as fileMimeTypes, h as makeFileValue, l as fileGrantUrlOf, m as isFileValue, o as RuntimeFileOccurrence, p as grantFileValue, r as FileId, u as fileIdOf, v as DeploymentId, w as SubscriptionId, x as InvocationId, y as GeneratedId } from "./file-BXf63ulU.js";
+import { b as decodeTransportValue, c as upgrade, d as Result$1, h as pending, m as inspectResult, o as PaginationPageSize, p as failureFromWire, s as initial, t as ValueDescriptor, x as encodeTransportObject } from "./descriptor-C5VA9qRl-C338iC6l.js";
+import { a as FunctionAddress, c as ServerMessageJson, d as WireSuccess, f as AppStateRevision, i as DeploymentChangedCloseCode, l as WireFailure, m as InvocationKey, n as functionPathOf, o as Operation, p as DeploymentGeneration, r as ClientMessageJson, s as ProtocolErrorCode, u as WireResult } from "./api-BTeMI5tx.js";
+import { Array as Array$1, Cause, Context, Deferred, Duration, Effect, ErrorReporter, Fiber, HashMap, Layer, ManagedRuntime, Predicate, Schedule, Schema, String } from "effect";
+import { customAlphabet } from "nanoid";
+import { useCallback, useCallback as useCallback$1, useContext, useDebugValue, useDebugValue as useDebugValue$1, useEffect, useEffect as useEffect$1, useErrorBoundary, useId, useImperativeHandle, useLayoutEffect, useMemo, useMemo as useMemo$1, useReducer, useRef, useState, useState as useState$1 } from "preact/hooks";
 import * as Socket from "effect/unstable/socket/Socket";
 import * as BrowserCrypto from "@effect/platform-browser/BrowserCrypto";
-import { customAlphabet } from "nanoid";
 import { Component, Fragment, cloneElement, createContext, createElement, createRef, h, isValidElement, toChildArray } from "preact";
+//#region ../shared/dist/id.js
+const decodeGenerated = (definition, payload) => Schema.decodeSync(definition)(definition.idPrefix === void 0 ? payload : `${definition.idPrefix}_${payload}`);
+var IdGenerator = class IdGenerator extends Context.Service()("@ignotum/shared/id/IdGenerator") {
+	static layer = Layer.sync(IdGenerator, () => {
+		const generatePayload = customAlphabet(IdAlphabet, 24);
+		return IdGenerator.of({ generate: (definition) => Effect.sync(() => decodeGenerated(definition, generatePayload())) });
+	});
+	static deterministic = (startAt = 1) => Layer.sync(IdGenerator, () => {
+		const counters = /* @__PURE__ */ new Map();
+		return IdGenerator.of({ generate: (definition) => Effect.sync(() => {
+			const counter = (counters.get(definition.idPrefix) ?? startAt - 1) + 1;
+			counters.set(definition.idPrefix, counter);
+			return decodeGenerated(definition, counter.toString(36).padStart(24, "0"));
+		}) });
+	});
+};
+//#endregion
+//#region src/client/files.ts
+const Files = { url: (file) => {
+	const url = fileGrantUrlOf(file);
+	if (url === void 0) throw new Error("This FileValue has no active query grant.");
+	return url;
+} };
+const formatByMime = {};
+for (const format of fileFormats) formatByMime[fileMimeTypes[format]] = format;
+const collectNativeFiles = (value, path, occurrences) => {
+	if (value instanceof File) {
+		occurrences.push({
+			path,
+			value
+		});
+		return;
+	}
+	if (isFileValue(value) || Predicate.isDate(value)) return;
+	if (globalThis.Array.isArray(value)) {
+		for (const [index, child] of value.entries()) collectNativeFiles(child, [...path, index], occurrences);
+		return;
+	}
+	if (!Predicate.isObject(value)) return;
+	for (const [key, child] of Object.entries(value)) collectNativeFiles(child, [...path, key], occurrences);
+};
+const replaceNativeFiles = (value, replacements) => {
+	if (value instanceof File) return replacements.get(value);
+	if (isFileValue(value) || Predicate.isDate(value)) return value;
+	if (globalThis.Array.isArray(value)) return value.map((child) => replaceNativeFiles(child, replacements));
+	if (!Predicate.isObject(value)) return value;
+	return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, replaceNativeFiles(child, replacements)]));
+};
+const prepareMutationArguments = Effect.fn("SyncClient.prepareMutationArguments")(function* (input) {
+	const ids = yield* IdGenerator;
+	const native = [];
+	collectNativeFiles(input, [], native);
+	const unique = new Set(native.map(({ value }) => value));
+	if (unique.size > fileLimits.filesPerMutation) throw new Error(`A mutation may upload at most ${fileLimits.filesPerMutation} files.`);
+	if ([...unique].reduce((total, file) => total + file.size, 0) > fileLimits.mutationBytes) throw new Error(`Mutation uploads may total at most ${fileLimits.mutationBytes} bytes.`);
+	const replacements = /* @__PURE__ */ new Map();
+	const nativeFiles = /* @__PURE__ */ new Map();
+	for (const file of unique) {
+		const format = formatByMime[file.type.toLowerCase()];
+		if (format === void 0) throw new Error(`File '${file.name}' has unsupported media type '${file.type || "unknown"}'.`);
+		if (file.size === 0 || file.size > fileLimits.fileBytes) throw new Error(`File '${file.name}' must be between 1 and ${fileLimits.fileBytes} bytes.`);
+		if (new TextEncoder().encode(file.name).byteLength > fileLimits.filenameBytes) throw new Error(`File '${file.name}' has a filename that is too long.`);
+		const id = yield* ids.generate(FileId);
+		replacements.set(file, makeFileValue(id, {
+			format,
+			name: file.name,
+			size: file.size
+		}));
+		nativeFiles.set(id, file);
+	}
+	return {
+		value: replaceNativeFiles(input, replacements),
+		nativeFiles,
+		occurrences: native.map(({ path, value: file }) => {
+			const replacement = replacements.get(file);
+			if (replacement === void 0) throw new Error("A native file replacement is missing.");
+			return {
+				path,
+				file: {
+					id: fileIdOf(replacement),
+					format: replacement.format,
+					name: replacement.name,
+					size: replacement.size
+				}
+			};
+		})
+	};
+});
+const pathKey = (path) => JSON.stringify(path);
+const applyFileGrants = (value, grants) => {
+	const byPath = new Map(grants.map((grant) => [pathKey(grant.path), grant]));
+	const visit = (current, path) => {
+		const grant = byPath.get(pathKey(path));
+		if (grant !== void 0) {
+			if (!isFileValue(current) || fileIdOf(current) !== grant.file.id) throw new Error("A query file grant does not match its result value.");
+			return grantFileValue(current, grant.url);
+		}
+		if (globalThis.Array.isArray(current)) return current.map((child, index) => visit(child, [...path, index]));
+		if (!Predicate.isObject(current) || Predicate.isDate(current) || isFileValue(current)) return current;
+		return Object.fromEntries(Object.entries(current).map(([key, child]) => [key, visit(child, [...path, key])]));
+	};
+	return visit(value, []);
+};
+//#endregion
+//#region ../contracts/dist/json.js
+const encodeScalar = (value) => Schema.decodeSync(Schema.String)(JSON.stringify(value));
+const encodeCanonicalJson = (value) => {
+	if (value === null || Predicate.isString(value) || Predicate.isNumber(value) || Predicate.isBoolean(value)) return encodeScalar(value);
+	if (Predicate.isObject(value)) return `{${Array$1.map(Array$1.sort(String.Order)(Object.keys(value)), (key) => {
+		const field = Schema.decodeUnknownSync(Schema.Json)(value[key]);
+		return `${encodeScalar(key)}:${encodeCanonicalJson(field)}`;
+	}).join(",")}}`;
+	return `[${Schema.decodeUnknownSync(Schema.Array(Schema.Json))(value).map(encodeCanonicalJson).join(",")}]`;
+};
+//#endregion
 //#region src/client/errors.ts
 /** @effect-diagnostics globalConsole:skip-file */
 var ConnectionUnavailable = class extends Schema.TaggedError()("ConnectionUnavailable", {
@@ -55,16 +170,14 @@ const skip = Object.freeze(new QuerySkipToken());
 const Query = { skip };
 const isQuerySkip = (value) => value === skip;
 //#endregion
-//#region ../contracts/dist/json.js
-const encodeScalar = (value) => Schema.decodeSync(Schema.String)(JSON.stringify(value));
-const encodeCanonicalJson = (value) => {
-	if (value === null || Predicate.isString(value) || Predicate.isNumber(value) || Predicate.isBoolean(value)) return encodeScalar(value);
-	if (Predicate.isObject(value)) return `{${Array.map(Array.sort(String.Order)(Object.keys(value)), (key) => {
-		const field = Schema.decodeUnknownSync(Schema.Json)(value[key]);
-		return `${encodeScalar(key)}:${encodeCanonicalJson(field)}`;
-	}).join(",")}}`;
-	return `[${Schema.decodeUnknownSync(Schema.Array(Schema.Json))(value).map(encodeCanonicalJson).join(",")}]`;
-};
+//#region ../contracts/dist/runtime/index.js
+const IndexIdentity = Schema.String.pipe(Schema.brand("ignotum/runtime/IndexIdentity"));
+const EncodedIndexKey = Schema.String.check(Schema.isPattern(/^(?:[0-9a-f]{2})*$/)).pipe(Schema.brand("ignotum/runtime/EncodedIndexKey"));
+Schema.Union([
+	Schema.Boolean,
+	Schema.Finite,
+	Schema.String
+]);
 Schema.String.pipe(Schema.brand("ignotum/hosted/QueryKey"));
 const TableDependency = Schema.Struct({
 	type: Schema.Literal("Table"),
@@ -75,20 +188,71 @@ const DocumentDependency = Schema.Struct({
 	tableId: TableId,
 	id: GeneratedId
 });
-const DependencyKey = Schema.Union([TableDependency, DocumentDependency]);
-const DependencySet = Schema.Array(DependencyKey);
-const InvalidationSet = Schema.Array(DependencyKey);
+const IndexRangeDependency = Schema.Struct({
+	type: Schema.Literal("IndexRange"),
+	tableId: TableId,
+	index: IndexIdentity,
+	lower: Schema.optional(EncodedIndexKey),
+	upper: Schema.optional(EncodedIndexKey)
+});
+const IndexPointInvalidation = Schema.Struct({
+	type: Schema.Literal("IndexPoint"),
+	tableId: TableId,
+	index: IndexIdentity,
+	key: EncodedIndexKey
+});
+const ReadDependency = Schema.Union([
+	TableDependency,
+	DocumentDependency,
+	IndexRangeDependency
+]);
+const WriteInvalidation = Schema.Union([
+	TableDependency,
+	DocumentDependency,
+	IndexPointInvalidation
+]);
+Schema.Union([ReadDependency, IndexPointInvalidation]);
+const DependencySet = Schema.Array(ReadDependency);
+const InvalidationSet = Schema.Array(WriteInvalidation);
 const RuntimeQueryResult = Schema.Struct({
 	type: Schema.Literal("Query"),
 	result: WireResult,
 	dependencies: DependencySet,
-	observedRevision: AppStateRevision
+	observedRevision: AppStateRevision,
+	files: Schema.optional(Schema.Array(RuntimeFileOccurrence))
+});
+const FileReferenceAdded = Schema.Struct({
+	type: Schema.Literal("AddReference"),
+	file: RuntimeFileMetadata,
+	tableId: TableId,
+	documentId: GeneratedId
+});
+const FileReferenceRemoved = Schema.Struct({
+	type: Schema.Literal("RemoveReference"),
+	fileId: FileId,
+	tableId: TableId,
+	documentId: GeneratedId
+});
+const FileReferenceEffect = Schema.Union([FileReferenceAdded, FileReferenceRemoved]);
+const FileEffectBatch = Schema.Struct({
+	id: InvocationId,
+	committedRevision: AppStateRevision,
+	effects: Schema.Array(FileReferenceEffect)
 });
+Schema.Struct({ appId: AppId });
+Schema.Struct({ batches: Schema.Array(FileEffectBatch) });
+Schema.Struct({
+	appId: AppId,
+	invocationId: InvocationId,
+	acknowledgedAt: Schema.Int
+});
+Schema.Struct({ completed: Schema.Literal(true) });
 const RuntimeMutationSuccess = Schema.Struct({
 	type: Schema.Literal("Mutation"),
 	result: WireSuccess,
 	invalidations: InvalidationSet,
-	committedRevision: AppStateRevision
+	committedRevision: AppStateRevision,
+	fileEffects: Schema.optional(FileEffectBatch)
 });
 const RuntimeMutationFailure = Schema.Struct({
 	type: Schema.Literal("Mutation"),
@@ -111,7 +275,8 @@ const QueryInvocation = Schema.Struct({
 const MutationInvocation = Schema.Struct({
 	...InvocationBase,
 	type: Schema.Literal("Mutation"),
-	invocationId: InvocationId
+	invocationId: InvocationId,
+	files: Schema.optional(Schema.Array(RuntimeFileOccurrence))
 });
 Schema.Union([QueryInvocation, MutationInvocation]);
 Schema.Struct({
@@ -150,23 +315,6 @@ Schema.Union([
 	RuntimeInvocationUnavailable
 ]);
 //#endregion
-//#region ../shared/dist/id.js
-const decodeGenerated = (definition, payload) => Schema.decodeSync(definition)(definition.idPrefix === void 0 ? payload : `${definition.idPrefix}_${payload}`);
-var IdGenerator = class IdGenerator extends Context.Service()("@ignotum/shared/id/IdGenerator") {
-	static layer = Layer.sync(IdGenerator, () => {
-		const generatePayload = customAlphabet(IdAlphabet, 24);
-		return IdGenerator.of({ generate: (definition) => Effect.sync(() => decodeGenerated(definition, generatePayload())) });
-	});
-	static deterministic = (startAt = 1) => Layer.sync(IdGenerator, () => {
-		const counters = /* @__PURE__ */ new Map();
-		return IdGenerator.of({ generate: (definition) => Effect.sync(() => {
-			const counter = (counters.get(definition.idPrefix) ?? startAt - 1) + 1;
-			counters.set(definition.idPrefix, counter);
-			return decodeGenerated(definition, counter.toString(36).padStart(24, "0"));
-		}) });
-	});
-};
-//#endregion
 //#region ../contracts/dist/runtime/functions.js
 const FunctionKind = Schema.Literals(["Mutation", "Query"]);
 Schema.TaggedError()("UnknownFunction", {
@@ -221,47 +369,89 @@ const ClientRoute = Schema.Struct({
 	pathname: ClientPath,
 	artifact: ArtifactReference
 });
-Schema.Struct({
+const DeploymentInventoryV1 = Schema.Struct({
 	formatVersion: Schema.Literal(1),
 	files: Schema.Array(ArtifactFile)
 });
-Schema.Struct({
+initial(DeploymentInventoryV1);
+const ClientManifestV1 = Schema.Struct({
 	formatVersion: Schema.Literal(1),
 	shell: ArtifactReference,
 	routes: Schema.Array(ClientRoute)
 });
+initial(ClientManifestV1);
 const ClientRoutingRoute = Schema.Struct({
 	pathname: ClientPath,
 	artifact: ArtifactPath
 });
-Schema.Struct({
+const ClientRoutingV1 = Schema.Struct({
 	formatVersion: Schema.Literal(1),
 	shell: ArtifactPath,
 	routes: Schema.Array(ClientRoutingRoute)
 });
+initial(ClientRoutingV1);
 const SchemaSnapshotField = Schema.Struct({
 	name: Schema.String,
 	value: ValueDescriptor
 });
-const SchemaSnapshotTable = Schema.Struct({
+const SchemaSnapshotIndex = Schema.Struct({
+	name: Schema.String,
+	fields: Schema.Array(Schema.String)
+});
+const SchemaSnapshotTableV1 = Schema.Struct({
 	name: Schema.String,
 	fields: Schema.Array(SchemaSnapshotField)
 });
-Schema.Struct({
+const SchemaSnapshotV1 = Schema.Struct({
 	formatVersion: Schema.Literal(1),
+	tables: Schema.Array(SchemaSnapshotTableV1)
+});
+const SchemaSnapshotTable = Schema.Struct({
+	name: Schema.String,
+	fields: Schema.Array(SchemaSnapshotField),
+	indexes: Schema.Array(SchemaSnapshotIndex)
+});
+const SchemaSnapshotV2 = Schema.Struct({
+	formatVersion: Schema.Literal(2),
 	tables: Schema.Array(SchemaSnapshotTable)
 });
+upgrade(initial(SchemaSnapshotV1), SchemaSnapshotV2, (snapshot) => ({
+	formatVersion: 2,
+	tables: snapshot.tables.map((table) => ({
+		...table,
+		indexes: []
+	}))
+}));
+const ServerFunctionArtifactV1 = Schema.Struct({
+	address: FunctionAddress,
+	kind: FunctionKind,
+	bundle: ArtifactReference,
+	sourceMap: ArtifactReference
+});
 const ServerFunctionArtifact = Schema.Struct({
 	address: FunctionAddress,
 	kind: FunctionKind,
+	args: Schema.optional(ValueDescriptor),
+	returns: Schema.optional(ValueDescriptor),
+	errors: Schema.optional(ValueDescriptor),
 	bundle: ArtifactReference,
 	sourceMap: ArtifactReference
 });
-Schema.Struct({
+const ServerBuildManifestV1 = Schema.Struct({
 	formatVersion: Schema.Literal(1),
 	schema: ArtifactReference,
+	functions: Schema.Array(ServerFunctionArtifactV1)
+});
+const ServerBuildManifestV2 = Schema.Struct({
+	formatVersion: Schema.Literal(2),
+	schema: ArtifactReference,
 	functions: Schema.Array(ServerFunctionArtifact)
 });
+upgrade(initial(ServerBuildManifestV1), ServerBuildManifestV2, (manifest) => ({
+	formatVersion: 2,
+	schema: manifest.schema,
+	functions: manifest.functions
+}));
 ArtifactPath.make("inventory.json");
 ArtifactPath.make("client/manifest.json");
 ArtifactPath.make("client/shell.html");
@@ -273,8 +463,19 @@ ArtifactPath.make("server/schema.json");
 //#region ../contracts/dist/runtime/transport.js
 const runtimeInvocationPath = "/v1/invoke";
 const runtimeRevisionPath = "/v1/revision";
+const runtimeIndexPreparePath = "/v1/indexes/prepare";
+const runtimeIndexCommitPath = "/v1/indexes/commit";
+const runtimeFileEffectsPath = "/v1/files/effects";
+const runtimeFileEffectsAcknowledgePath = "/v1/files/effects/acknowledge";
 const appSyncPath = `/_ignotum/v1/sync`;
-const RuntimeRequestPath = Schema.Literals([runtimeInvocationPath, runtimeRevisionPath]);
+const RuntimeRequestPath = Schema.Literals([
+	runtimeInvocationPath,
+	runtimeRevisionPath,
+	runtimeIndexPreparePath,
+	runtimeIndexCommitPath,
+	runtimeFileEffectsPath,
+	runtimeFileEffectsAcknowledgePath
+]);
 const RuntimeRequestTimestamp = Schema.FiniteFromString.pipe(Schema.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0)), Schema.brand("ignotum/runtime/RequestTimestamp"));
 const RuntimeRequestSignature = Sha256.pipe(Schema.brand("ignotum/runtime/RequestSignature"));
 Schema.Struct({
@@ -293,6 +494,11 @@ Schema.Struct({
 	deploymentId: Schema.optional(DeploymentId),
 	bodySha256: Sha256
 });
+Schema.Struct({
+	appId: AppId,
+	deploymentId: DeploymentId
+});
+Schema.Struct({ completed: Schema.Literal(true) });
 const RuntimeErrorCode = Schema.Literals([
 	"InvalidRequest",
 	"InvalidSignature",
@@ -391,7 +597,7 @@ const makeQueryCache = (allocateId, sendLifecycleMessage) => {
 		}
 	};
 };
-const resultFromWire = Effect.fn("SyncClient.resultFromWire")((wire) => Effect.succeed(wire.type === "Success" ? Result$1.succeed(wire.value === void 0 ? void 0 : decodeTransportValue(wire.value, wire.dates ?? [])) : failureFromWire(wire.error, wire.dates)));
+const resultFromWire = Effect.fn("SyncClient.resultFromWire")((wire, files = []) => Effect.succeed(wire.type === "Success" ? Result$1.succeed(wire.value === void 0 ? void 0 : applyFileGrants(decodeTransportValue(wire.value, wire.dates ?? []), files)) : failureFromWire(wire.error, wire.dates)));
 const shouldReloadForCloseCode = (code) => code === DeploymentChangedCloseCode;
 const handshakesMatch = (first, next) => first.appId === next.appId && first.deploymentId === next.deploymentId && first.generation === next.generation;
 const handshakeDecision = (remembered, acceptedOnConnection, next) => {
@@ -435,14 +641,19 @@ var SyncClient = class SyncClient extends Context.Service()("ignotum/client/sync
 			const pendingInvocation = HashMap.getUnsafe(invocations, id);
 			if (pendingInvocation === void 0) return Effect.void;
 			invocations = HashMap.remove(invocations, id);
-			return reportClientError(error).pipe(Effect.andThen(Deferred.fail(pendingInvocation.deferred, error)), Effect.asVoid);
+			return reportClientError(error).pipe(Effect.andThen(Deferred.fail(pendingInvocation.prepared, error)), Effect.andThen(Deferred.fail(pendingInvocation.deferred, error)), Effect.asVoid);
 		};
 		const handleMessage = Effect.fn("SyncClient.handleMessage")(function* (message) {
 			switch (message.type) {
 				case "Snapshot":
 					if (queryCache.getById(message.id) === void 0) return;
-					yield* resultFromWire(message.result).pipe(Effect.tap((result) => Effect.sync(() => queryCache.setResult(message.id, result, message.revision))));
+					yield* resultFromWire(message.result, message.files ?? []).pipe(Effect.tap((result) => Effect.sync(() => queryCache.setResult(message.id, result, message.revision))));
 					return;
+				case "MutationPrepared": {
+					const pendingInvocation = HashMap.getUnsafe(invocations, message.id);
+					if (pendingInvocation !== void 0) yield* Deferred.succeed(pendingInvocation.prepared, message.uploads);
+					return;
+				}
 				case "Result": {
 					const pendingInvocation = HashMap.getUnsafe(invocations, message.id);
 					if (pendingInvocation === void 0) return;
@@ -532,24 +743,94 @@ var SyncClient = class SyncClient extends Context.Service()("ignotum/client/sync
 		});
 		const mutate = Effect.fn("SyncClient.mutate")(function* (functionAddress, args) {
 			const invocationId = yield* ids.generate(InvocationId);
+			const preparedArguments = yield* prepareMutationArguments(args).pipe(Effect.provideService(IdGenerator, ids), Effect.mapError((cause) => InvalidMutationArguments.make({
+				cause,
+				function: functionAddress,
+				message: `Mutation arguments for ${functionAddress} contain an unsupported file or value.`
+			})), Effect.tapError(reportClientError));
+			const jsonArgs = yield* Effect.try({
+				try: () => encodeTransportObject(preparedArguments.value),
+				catch: (cause) => InvalidMutationArguments.make({
+					cause,
+					function: functionAddress,
+					message: `Mutation arguments for ${functionAddress} contain an unsupported value.`
+				})
+			}).pipe(Effect.tapError(reportClientError));
 			const deferred = yield* Deferred.make();
-			const message = {
+			const prepared = yield* Deferred.make();
+			const invokeMessage = {
 				type: "Invoke",
 				id: invocationId,
 				kind: "Mutation",
 				function: functionAddress,
-				args
+				args: jsonArgs
+			};
+			const message = preparedArguments.occurrences.length === 0 ? invokeMessage : {
+				type: "PrepareMutation",
+				id: invocationId,
+				kind: "Mutation",
+				function: functionAddress,
+				args: jsonArgs,
+				files: preparedArguments.occurrences
 			};
 			invocations = HashMap.set(invocations, invocationId, {
 				deferred,
 				function: functionAddress,
-				message
+				message,
+				prepared
 			});
-			if (writer !== void 0) yield* sendWith(writer, message).pipe(Effect.catchTags({
-				ConnectionUnavailable: reportClientError,
-				InvalidClientMessage: (error) => rejectInvocation(invocationId, error)
-			}));
-			return yield* Deferred.await(deferred);
+			return yield* Effect.gen(function* () {
+				if (writer !== void 0) yield* sendWith(writer, message).pipe(Effect.catchTags({
+					ConnectionUnavailable: reportClientError,
+					InvalidClientMessage: (error) => rejectInvocation(invocationId, error)
+				}));
+				if (message.type === "PrepareMutation") {
+					const uploads = yield* Deferred.await(prepared);
+					const uploaded = /* @__PURE__ */ new Set();
+					for (const upload of uploads) {
+						if (upload.url === void 0 || uploaded.has(upload.file.id)) continue;
+						const uploadUrl = upload.url;
+						uploaded.add(upload.file.id);
+						const file = preparedArguments.nativeFiles.get(upload.file.id);
+						if (file === void 0) return yield* InvalidServerMessage.make({
+							cause: /* @__PURE__ */ new Error(`Missing native file '${upload.file.id}'.`),
+							message: "The server prepared an unknown application file."
+						});
+						const response = yield* Effect.tryPromise({
+							try: () => fetch(uploadUrl, {
+								method: "PUT",
+								body: file,
+								headers: { "content-type": file.type }
+							}),
+							catch: (cause) => ConnectionUnavailable.make({
+								cause,
+								message: `File '${file.name}' could not be uploaded.`
+							})
+						});
+						if (!response.ok) {
+							const detail = yield* Effect.promise(() => response.text());
+							return yield* InvalidMutationArguments.make({
+								cause: new Error(detail),
+								function: functionAddress,
+								message: `File '${file.name}' was rejected by application storage.`
+							});
+						}
+					}
+					const pendingInvocation = HashMap.getUnsafe(invocations, invocationId);
+					if (pendingInvocation === void 0) return yield* Deferred.await(deferred);
+					invocations = HashMap.set(invocations, invocationId, {
+						...pendingInvocation,
+						message: invokeMessage
+					});
+					if (writer !== void 0) yield* sendWith(writer, invokeMessage).pipe(Effect.catchTags({
+						ConnectionUnavailable: reportClientError,
+						InvalidClientMessage: (error) => rejectInvocation(invocationId, error)
+					}));
+				}
+				return yield* Deferred.await(deferred);
+			}).pipe(Effect.tapError(() => Effect.sync(() => {
+				invocations = HashMap.remove(invocations, invocationId);
+			})));
 		});
 		return SyncClient.of({
 			mutate,
@@ -619,21 +900,140 @@ function useQuery(reference, args) {
 	if (Schema.is(ClientInfrastructureError)(result)) throw result;
 	return result;
 }
+function usePaginatedQuery(reference, args, options = {}) {
+	const functionPath = functionPathOf(reference);
+	const skipped = isQuerySkip(args);
+	const input = args === void 0 || skipped ? {} : args;
+	const jsonArgs = encodeTransportObject(input);
+	const pageSize = Schema.decodeSync(PaginationPageSize)(options.pageSize ?? 20);
+	const identity = skipped ? `skip:${functionPath}` : syncClientInternals.queryIdentity(functionPath, jsonArgs);
+	const [requestedPages, setRequestedPages] = useState$1(1);
+	const [refresh, setRefresh] = useState$1(0);
+	const [state, setState] = useState$1(() => ({
+		identity,
+		result: pending()
+	}));
+	const loadMore = useCallback$1(() => setRequestedPages((count) => count + 1), []);
+	useDebugValue$1({
+		args: input,
+		function: functionPath,
+		result: state.result
+	});
+	useEffect$1(() => {
+		setRequestedPages(1);
+		setState({
+			identity,
+			result: pending()
+		});
+	}, [identity, pageSize]);
+	useEffect$1(() => {
+		if (skipped) return;
+		let active = true;
+		const releases = [];
+		syncRuntime.runPromise(Effect.gen(function* () {
+			const client = yield* SyncClient;
+			const items = [];
+			let cursor = null;
+			for (let pageNumber = 0; pageNumber < requestedPages; pageNumber += 1) {
+				const pageArgs = encodeTransportObject({
+					...input,
+					pagination: {
+						cursor,
+						pageSize
+					}
+				});
+				const observer = yield* client.observe(functionPath, pageArgs);
+				if (!active) {
+					yield* observer.release;
+					return;
+				}
+				const releaseSubscription = observer.subscribe(() => {
+					if (active) setRefresh((version) => version + 1);
+				});
+				releases.push(() => {
+					releaseSubscription();
+					syncRuntime.runFork(observer.release);
+				});
+				const snapshot = observer.getSnapshot();
+				if (Schema.is(ClientInfrastructureError)(snapshot)) {
+					setState({
+						identity,
+						result: snapshot
+					});
+					return;
+				}
+				const inspected = inspectResult(snapshot);
+				if (inspected === void 0) {
+					setState({
+						identity,
+						result: items.length === 0 ? pending() : Result$1.succeed({
+							items,
+							loadMore,
+							status: "LoadingMore"
+						})
+					});
+					return;
+				}
+				if (inspected.type === "Failure") {
+					setState({
+						identity,
+						result: snapshot
+					});
+					return;
+				}
+				const page = inspected.value;
+				items.push(...page.items);
+				cursor = page.nextCursor;
+				if (cursor === null) {
+					setState({
+						identity,
+						result: Result$1.succeed({
+							items,
+							loadMore,
+							status: "Exhausted"
+						})
+					});
+					return;
+				}
+			}
+			setState({
+				identity,
+				result: Result$1.succeed({
+					items,
+					loadMore,
+					status: "CanLoadMore"
+				})
+			});
+		})).catch((error) => {
+			if (active && Schema.is(ClientInfrastructureError)(error)) setState({
+				identity,
+				result: error
+			});
+		});
+		return () => {
+			active = false;
+			for (const release of releases) release();
+		};
+	}, [
+		functionPath,
+		identity,
+		loadMore,
+		pageSize,
+		refresh,
+		requestedPages,
+		skipped
+	]);
+	if (skipped || state.identity !== identity) return pending();
+	const result = state.result;
+	if (Schema.is(ClientInfrastructureError)(result)) throw result;
+	return result;
+}
 const useMutation = (reference) => useMemo$1(() => {
 	const mutate = (args) => {
 		const functionPath = functionPathOf(reference);
 		const input = args === void 0 ? {} : args;
 		return syncRuntime.runPromise(Effect.gen(function* () {
-			const client = yield* SyncClient;
-			const jsonArgs = yield* Effect.try({
-				try: () => encodeTransportObject(input),
-				catch: (cause) => InvalidMutationArguments.make({
-					cause,
-					function: functionPath,
-					message: `Mutation arguments for ${functionPath} contain an unsupported value.`
-				})
-			}).pipe(Effect.tapError(reportClientError));
-			return yield* client.mutate(functionPath, jsonArgs);
+			return yield* (yield* SyncClient).mutate(functionPath, input);
 		}));
 	};
 	return mutate;
@@ -648,6 +1048,6 @@ const app = (definition) => {
 //#region src/client/index.ts
 const Result = { match: Result$1.match };
 //#endregion
-export { Component, Fragment, Query, Result, app, cloneElement, createContext, createElement, createRef, h, isValidElement, toChildArray, useCallback, useContext, useDebugValue, useEffect, useErrorBoundary, useId, useImperativeHandle, useLayoutEffect, useMemo, useMutation, useQuery, useReducer, useRef, useState };
+export { Component, Files, Fragment, Query, Result, app, cloneElement, createContext, createElement, createRef, h, isValidElement, toChildArray, useCallback, useContext, useDebugValue, useEffect, useErrorBoundary, useId, useImperativeHandle, useLayoutEffect, useMemo, useMutation, usePaginatedQuery, useQuery, useReducer, useRef, useState };
 
 //# sourceMappingURL=client.js.map