ignotum 0.0.6 → 0.0.7

package/dist/runtime/pagination-B1BzNkh8-BUSTbeSg.d.ts

@@ -0,0 +1,80 @@
+import "./id-Btwac71X-DhnKYsjY.js";
+import { Schema } from "effect";
+//#region ../contracts/dist/descriptor-CVZycwe2.d.ts
+//#region src/schema/descriptor.d.ts
+interface DescriptorField {
+  readonly name: string;
+  readonly value: ValueDescriptor;
+}
+type ValueDescriptor = {
+  readonly type: "array";
+  readonly value: ValueDescriptor;
+} | {
+  readonly type: "boolean";
+} | {
+  readonly type: "date";
+} | {
+  readonly type: "error";
+  readonly tag: string;
+  readonly fields: ReadonlyArray<DescriptorField>;
+} | {
+  readonly type: "id";
+  readonly table: string;
+} | {
+  readonly type: "integer";
+} | {
+  readonly type: "literal";
+  readonly value: string | number | boolean;
+} | {
+  readonly type: "literals";
+  readonly values: ReadonlyArray<string | number | boolean>;
+} | {
+  readonly type: "never";
+} | {
+  readonly type: "null";
+} | {
+  readonly type: "nullable";
+  readonly value: ValueDescriptor;
+} | {
+  readonly type: "number";
+} | {
+  readonly type: "object";
+  readonly fields: ReadonlyArray<DescriptorField>;
+} | {
+  readonly type: "optional";
+  readonly value: ValueDescriptor;
+} | {
+  readonly type: "record";
+  readonly value: ValueDescriptor;
+} | {
+  readonly type: "string";
+} | {
+  readonly type: "union";
+  readonly members: ReadonlyArray<ValueDescriptor>;
+};
+declare const ValueDescriptor: Schema.Codec<ValueDescriptor>;
+declare const ValueDescriptorTypeId: unique symbol;
+interface ValueDescriptorCarrier {
+  readonly [ValueDescriptorTypeId]: ValueDescriptor;
+}
+type DescribedValue<Value extends Schema.Constraint = Schema.Constraint> = Value & ValueDescriptorCarrier;
+type ValueFields = {
+  readonly [fieldName: PropertyKey]: DescribedValue;
+};
+//#endregion
+//#region ../contracts/dist/pagination-B1BzNkh8.d.ts
+//#region src/runtime/pagination.d.ts
+declare const PaginationCursor: Schema.brand<Schema.String, "ignotum/runtime/PaginationCursor">;
+type PaginationCursor = typeof PaginationCursor.Type;
+declare const PaginationOptions: Schema.Struct<{
+  readonly cursor: Schema.NullOr<Schema.brand<Schema.String, "ignotum/runtime/PaginationCursor">>;
+  readonly pageSize: Schema.brand<Schema.Int, "ignotum/runtime/PaginationPageSize">;
+}>;
+type PaginationOptions = typeof PaginationOptions.Type;
+interface PaginationPage<Item> {
+  readonly items: ReadonlyArray<Item>;
+  readonly nextCursor: PaginationCursor | null;
+}
+//#endregion
+export { ValueDescriptorCarrier as a, ValueDescriptor as i, PaginationPage as n, ValueFields as o, DescribedValue as r, PaginationOptions as t };
+//# sourceMappingURL=pagination-B1BzNkh8-BUSTbeSg.d.ts.map

package/dist/runtime/pagination-BKPko9Hm.d.ts

@@ -0,0 +1 @@
+import "./pagination-B1BzNkh8-BUSTbeSg.js";

package/dist/runtime/{schema-B-jMZEbs.js → schema-D9RmboaS.js}

@@ -1,36 +1,67 @@
 import { r as GeneratedId } from "./id-D570vudg.js";
-import { a as ErrorBrand, i as getValueDescriptor, n as attachValueDescriptor, r as descriptorFields } from "./descriptor-t6BOEGw9-BTHR-ZMv.js";
+import { a as PaginationCursor, i as getValueDescriptor, n as attachValueDescriptor, o as PaginationPageSize, r as descriptorFields, s as ErrorBrand } from "./descriptor-t6BOEGw9-C1rwYIlx.js";
 import { Schema, Struct } from "effect";
-//#region ../contracts/dist/runtime/schema.js
-const FunctionSchemaTypeId = Symbol.for("ignotum/runtime/schema/FunctionSchema");
-const attachFunctionSchema = (schema) => (definition) => {
-	Object.defineProperty(definition, FunctionSchemaTypeId, {
-		configurable: false,
-		enumerable: false,
-		value: schema,
-		writable: false
-	});
-	return definition;
-};
-const getFunctionSchema = (value) => value[FunctionSchemaTypeId];
-//#endregion
 //#region ../contracts/dist/schema/values.js
 const LiteralValueSchema = Schema.Union([
 	Schema.String,
 	Schema.Finite,
 	Schema.Boolean
 ]);
+const schemaIndexLimits = {
+	fieldsPerIndex: 8,
+	indexesPerSchema: 128,
+	indexesPerTable: 16,
+	keyBytes: 4096,
+	nameBytes: 64
+};
+const utf8ByteLength = (value) => {
+	let bytes = 0;
+	for (const character of value) {
+		const point = character.codePointAt(0) ?? 0;
+		bytes += point <= 127 ? 1 : point <= 2047 ? 2 : point <= 65535 ? 3 : 4;
+	}
+	return bytes;
+};
 const table = (fields) => {
 	const tableFields = fields;
-	return {
-		_tag: "Table",
-		descriptor: {
-			type: "object",
-			fields: descriptorFields(tableFields)
-		},
-		fields: tableFields,
-		schema: Schema.Struct(tableFields)
+	const make = (indexes) => {
+		const index = (name, fieldNames) => {
+			if (utf8ByteLength(name) > schemaIndexLimits.nameBytes) throw new Error(`Index names cannot exceed ${schemaIndexLimits.nameBytes} UTF-8 bytes.`);
+			if (name.length === 0) throw new Error("Index names cannot be empty.");
+			if (name.startsWith("$")) throw new Error("Index names beginning with '$' are reserved.");
+			if (Object.hasOwn(indexes, name)) throw new Error(`Duplicate index name '${name}'.`);
+			if (fieldNames.length > schemaIndexLimits.fieldsPerIndex) throw new Error(`Indexes cannot contain more than ${schemaIndexLimits.fieldsPerIndex} fields.`);
+			if (new Set(fieldNames).size !== fieldNames.length) throw new Error(`Index '${name}' contains duplicate fields.`);
+			for (const fieldName of fieldNames) {
+				if (!Object.hasOwn(tableFields, fieldName)) throw new Error(`Index '${name}' references unknown field '${fieldName}'.`);
+				const descriptor = getValueDescriptor(tableFields[fieldName]);
+				if (!(descriptor?.type === "boolean" || descriptor?.type === "date" || descriptor?.type === "id" || descriptor?.type === "integer" || descriptor?.type === "number" || descriptor?.type === "string" || descriptor?.type === "literal" || descriptor?.type === "literals")) throw new Error(`Index '${name}' field '${fieldName}' is not indexable.`);
+				if (descriptor.type === "literals" && !(descriptor.values.every(Schema.is(Schema.Boolean)) || descriptor.values.every(Schema.is(Schema.Finite)) || descriptor.values.every(Schema.is(Schema.String)))) throw new Error(`Index '${name}' field '${fieldName}' mixes value types.`);
+			}
+			const duplicate = Object.values(indexes).find((candidate) => candidate.fields.length === fieldNames.length && candidate.fields.every((fieldName, position) => fieldName === fieldNames[position]));
+			if (duplicate !== void 0) throw new Error(`Index '${name}' duplicates index '${duplicate.name}'.`);
+			if (Object.keys(indexes).length >= schemaIndexLimits.indexesPerTable) throw new Error(`Tables cannot declare more than ${schemaIndexLimits.indexesPerTable} indexes.`);
+			return make({
+				...indexes,
+				[name]: {
+					name,
+					fields: fieldNames
+				}
+			});
+		};
+		return {
+			_tag: "Table",
+			descriptor: {
+				type: "object",
+				fields: descriptorFields(tableFields)
+			},
+			fields: tableFields,
+			index,
+			indexes,
+			schema: Schema.Struct(tableFields)
+		};
 	};
+	return make({});
 };
 const fresh = (value) => value.pipe(Schema.annotate({}));
 const string = () => attachValueDescriptor(fresh(Schema.String), { type: "string" });
@@ -143,6 +174,17 @@ const union = (...members) => {
 		members: members.map(requireDescriptor)
 	});
 };
+const paginationCursor = () => attachValueDescriptor(fresh(PaginationCursor), { type: "string" });
+const pagination = () => fixedObject({
+	cursor: nullable(paginationCursor()),
+	pageSize: attachValueDescriptor(fresh(PaginationPageSize), { type: "integer" })
+});
+const page = (value) => {
+	return fixedObject({
+		items: array(value),
+		nextCursor: nullable(paginationCursor())
+	});
+};
 const error = (tag, fields) => {
 	if (tag === "InternalServerError") throw new Error("The error tag 'InternalServerError' is reserved by Ignotum.");
 	const errorFields = { ...fields };
@@ -190,22 +232,44 @@ const bindValues = (definition) => {
 		};
 		return fixedObject(Struct.assign(tableFields, systemFields));
 	};
+	const boundPagination = () => {
+		return pagination();
+	};
 	return {
 		...values,
 		doc,
-		id: boundId
+		id: boundId,
+		page,
+		pagination: boundPagination
 	};
 };
 //#endregion
+//#region ../contracts/dist/runtime/schema.js
+const FunctionSchemaTypeId = Symbol.for("ignotum/runtime/schema/FunctionSchema");
+const attachFunctionSchema = (schema) => (definition) => {
+	Object.defineProperty(definition, FunctionSchemaTypeId, {
+		configurable: false,
+		enumerable: false,
+		value: schema,
+		writable: false
+	});
+	return definition;
+};
+const getFunctionSchema = (value) => value[FunctionSchemaTypeId];
+//#endregion
 //#region ../contracts/dist/schema/index.js
 const SchemaDefinitionTypeId = Symbol.for("ignotum/schema/SchemaDefinition");
-const defineSchema = (define) => ({
-	_tag: "Schema",
-	[SchemaDefinitionTypeId]: define({
+const defineSchema = (define) => {
+	const definitions = define({
 		table,
 		values
-	})
-});
+	});
+	if (Object.values(definitions).reduce((count, definition) => count + Object.keys(definition.indexes).length, 0) > schemaIndexLimits.indexesPerSchema) throw new Error(`Schemas cannot declare more than ${schemaIndexLimits.indexesPerSchema} indexes.`);
+	return {
+		_tag: "Schema",
+		[SchemaDefinitionTypeId]: definitions
+	};
+};
 const makeFunctionBuilder = (schema, kind) => {
 	const define = (definition) => attachFunctionSchema(schema)({
 		_tag: kind,
@@ -224,4 +288,4 @@ const bindSchema = (schema) => ({
 //#endregion
 export { getFunctionSchema as i, bindSchema as n, defineSchema as r, SchemaDefinitionTypeId as t };
 
-//# sourceMappingURL=schema-B-jMZEbs.js.map
+//# sourceMappingURL=schema-D9RmboaS.js.map

package/dist/runtime/schema-D9RmboaS.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-D9RmboaS.js","names":[],"sources":["../../../contracts/dist/schema/values.js","../../../contracts/dist/runtime/schema.js","../../../contracts/dist/schema/index.js"],"sourcesContent":["import { GeneratedId } from \"../runtime/id.js\";\nimport { a as getValueDescriptor, i as descriptorFields, r as attachValueDescriptor } from \"../descriptor-t6BOEGw9.js\";\nimport { PaginationCursor, PaginationPageSize } from \"../runtime/pagination.js\";\nimport { ErrorBrand } from \"../runtime/result.js\";\nimport { Schema, Struct } from \"effect\";\n//#region src/schema/values.ts\nconst LiteralValueSchema = Schema.Union([\n\tSchema.String,\n\tSchema.Finite,\n\tSchema.Boolean\n]);\nconst schemaIndexLimits = {\n\tfieldsPerIndex: 8,\n\tindexesPerSchema: 128,\n\tindexesPerTable: 16,\n\tkeyBytes: 4096,\n\tnameBytes: 64\n};\nconst utf8ByteLength = (value) => {\n\tlet bytes = 0;\n\tfor (const character of value) {\n\t\tconst point = character.codePointAt(0) ?? 0;\n\t\tbytes += point <= 127 ? 1 : point <= 2047 ? 2 : point <= 65535 ? 3 : 4;\n\t}\n\treturn bytes;\n};\nconst table = (fields) => {\n\tconst tableFields = fields;\n\tconst make = (indexes) => {\n\t\tconst index = (name, fieldNames) => {\n\t\t\tif (utf8ByteLength(name) > schemaIndexLimits.nameBytes) throw new Error(`Index names cannot exceed ${schemaIndexLimits.nameBytes} UTF-8 bytes.`);\n\t\t\tif (name.length === 0) throw new Error(\"Index names cannot be empty.\");\n\t\t\tif (name.startsWith(\"$\")) throw new Error(\"Index names beginning with '$' are reserved.\");\n\t\t\tif (Object.hasOwn(indexes, name)) throw new Error(`Duplicate index name '${name}'.`);\n\t\t\tif (fieldNames.length > schemaIndexLimits.fieldsPerIndex) throw new Error(`Indexes cannot contain more than ${schemaIndexLimits.fieldsPerIndex} fields.`);\n\t\t\tif (new Set(fieldNames).size !== fieldNames.length) throw new Error(`Index '${name}' contains duplicate fields.`);\n\t\t\tfor (const fieldName of fieldNames) {\n\t\t\t\tif (!Object.hasOwn(tableFields, fieldName)) throw new Error(`Index '${name}' references unknown field '${fieldName}'.`);\n\t\t\t\tconst descriptor = getValueDescriptor(tableFields[fieldName]);\n\t\t\t\tif (!(descriptor?.type === \"boolean\" || descriptor?.type === \"date\" || descriptor?.type === \"id\" || descriptor?.type === \"integer\" || descriptor?.type === \"number\" || descriptor?.type === \"string\" || descriptor?.type === \"literal\" || descriptor?.type === \"literals\")) throw new Error(`Index '${name}' field '${fieldName}' is not indexable.`);\n\t\t\t\tif (descriptor.type === \"literals\" && !(descriptor.values.every(Schema.is(Schema.Boolean)) || descriptor.values.every(Schema.is(Schema.Finite)) || descriptor.values.every(Schema.is(Schema.String)))) throw new Error(`Index '${name}' field '${fieldName}' mixes value types.`);\n\t\t\t}\n\t\t\tconst duplicate = Object.values(indexes).find((candidate) => candidate.fields.length === fieldNames.length && candidate.fields.every((fieldName, position) => fieldName === fieldNames[position]));\n\t\t\tif (duplicate !== void 0) throw new Error(`Index '${name}' duplicates index '${duplicate.name}'.`);\n\t\t\tif (Object.keys(indexes).length >= schemaIndexLimits.indexesPerTable) throw new Error(`Tables cannot declare more than ${schemaIndexLimits.indexesPerTable} indexes.`);\n\t\t\treturn make({\n\t\t\t\t...indexes,\n\t\t\t\t[name]: {\n\t\t\t\t\tname,\n\t\t\t\t\tfields: fieldNames\n\t\t\t\t}\n\t\t\t});\n\t\t};\n\t\treturn {\n\t\t\t_tag: \"Table\",\n\t\t\tdescriptor: {\n\t\t\t\ttype: \"object\",\n\t\t\t\tfields: descriptorFields(tableFields)\n\t\t\t},\n\t\t\tfields: tableFields,\n\t\t\tindex,\n\t\t\tindexes,\n\t\t\tschema: Schema.Struct(tableFields)\n\t\t};\n\t};\n\treturn make({});\n};\nconst fresh = (value) => value.pipe(Schema.annotate({}));\nconst string = () => attachValueDescriptor(fresh(Schema.String), { type: \"string\" });\nconst number = () => attachValueDescriptor(fresh(Schema.Finite), { type: \"number\" });\nconst integer = () => attachValueDescriptor(fresh(Schema.Int), { type: \"integer\" });\nconst boolean = () => attachValueDescriptor(fresh(Schema.Boolean), { type: \"boolean\" });\nconst date = () => attachValueDescriptor(fresh(Schema.DateFromMillis), { type: \"date\" });\nconst never = () => attachValueDescriptor(fresh(Schema.Never), { type: \"never\" });\nconst nullValue = () => attachValueDescriptor(fresh(Schema.Null), { type: \"null\" });\nconst literal = (value) => {\n\tSchema.decodeSync(LiteralValueSchema)(value);\n\treturn attachValueDescriptor(Schema.Literal(value), {\n\t\ttype: \"literal\",\n\t\tvalue\n\t});\n};\nconst literals = (...members) => {\n\tSchema.decodeSync(Schema.Array(LiteralValueSchema))(members);\n\treturn attachValueDescriptor(Schema.Literals(members), {\n\t\ttype: \"literals\",\n\t\tvalues: members\n\t});\n};\nconst makeIdSchema = (tableName) => {\n\tconst identifier = `ignotum/id/${tableName}`;\n\treturn attachValueDescriptor(GeneratedId.pipe(Schema.brand(identifier), Schema.annotate({ \"ignotum/table\": tableName })), {\n\t\ttype: \"id\",\n\t\ttable: tableName\n\t});\n};\nconst id = (tableName) => makeIdSchema(tableName);\nconst requireDescriptor = (value) => {\n\tconst descriptor = getValueDescriptor(value);\n\tif (descriptor === void 0) throw new Error(\"Ignotum value combinators require a values validator.\");\n\treturn descriptor;\n};\nconst array = (value) => {\n\treturn attachValueDescriptor(Schema.Array(value), {\n\t\ttype: \"array\",\n\t\tvalue: requireDescriptor(value)\n\t});\n};\nconst assertFieldsExist = (fields, keys, operation) => {\n\tfor (const key of keys) if (!Object.hasOwn(fields, key)) throw new Error(`Cannot ${operation} unknown field '${String(key)}'.`);\n};\nconst fixedObject = (fields) => {\n\tconst pick = (...keys) => {\n\t\tassertFieldsExist(fields, keys, \"pick\");\n\t\treturn fixedObject(Struct.pick(fields, keys));\n\t};\n\tconst omit = (...keys) => {\n\t\tassertFieldsExist(fields, keys, \"omit\");\n\t\treturn fixedObject(Struct.omit(fields, keys));\n\t};\n\tconst extend = (addedFields, ..._validation) => {\n\t\tfor (const key of Reflect.ownKeys(addedFields)) if (Object.hasOwn(fields, key)) throw new Error(`Cannot extend existing field '${String(key)}'.`);\n\t\treturn fixedObject(Struct.assign(fields, addedFields));\n\t};\n\tconst override = (overriddenFields, ..._validation) => {\n\t\tassertFieldsExist(fields, Reflect.ownKeys(overriddenFields), \"override\");\n\t\treturn fixedObject(Struct.assign(fields, overriddenFields));\n\t};\n\tconst partial = () => {\n\t\tconst partialFields = Struct.map(fields, Schema.optional);\n\t\tfor (const name of Reflect.ownKeys(fields)) {\n\t\t\tconst field = fields[name];\n\t\t\tconst partialField = partialFields[name];\n\t\t\tif (field === void 0 || partialField === void 0) continue;\n\t\t\tattachValueDescriptor(partialField, {\n\t\t\t\ttype: \"optional\",\n\t\t\t\tvalue: requireDescriptor(field)\n\t\t\t});\n\t\t}\n\t\treturn fixedObject(partialFields);\n\t};\n\tconst schema = attachValueDescriptor(Schema.Struct(fields), {\n\t\ttype: \"object\",\n\t\tfields: descriptorFields(fields)\n\t});\n\treturn Object.assign(schema, {\n\t\textend,\n\t\tomit,\n\t\toverride,\n\t\tpartial,\n\t\tpick\n\t});\n};\nconst object = (fields) => fixedObject(fields);\nconst optional = (value) => {\n\treturn attachValueDescriptor(Schema.optional(value), {\n\t\ttype: \"optional\",\n\t\tvalue: requireDescriptor(value)\n\t});\n};\nconst nullable = (value) => {\n\treturn attachValueDescriptor(Schema.NullOr(value), {\n\t\ttype: \"nullable\",\n\t\tvalue: requireDescriptor(value)\n\t});\n};\nconst record = (value) => {\n\treturn attachValueDescriptor(Schema.Record(Schema.String, value), {\n\t\ttype: \"record\",\n\t\tvalue: requireDescriptor(value)\n\t});\n};\nconst union = (...members) => {\n\treturn attachValueDescriptor(Schema.Union(members), {\n\t\ttype: \"union\",\n\t\tmembers: members.map(requireDescriptor)\n\t});\n};\nconst paginationCursor = () => attachValueDescriptor(fresh(PaginationCursor), { type: \"string\" });\nconst pagination = () => fixedObject({\n\tcursor: nullable(paginationCursor()),\n\tpageSize: attachValueDescriptor(fresh(PaginationPageSize), { type: \"integer\" })\n});\nconst page = (value) => {\n\treturn fixedObject({\n\t\titems: array(value),\n\t\tnextCursor: nullable(paginationCursor())\n\t});\n};\nconst error = (tag, fields) => {\n\tif (tag === \"InternalServerError\") throw new Error(\"The error tag 'InternalServerError' is reserved by Ignotum.\");\n\tconst errorFields = { ...fields };\n\tReflect.deleteProperty(errorFields, \"_tag\");\n\tconst schema = Schema.TaggedStruct(tag, errorFields).pipe(Schema.brand(ErrorBrand));\n\tconst make = (input) => schema.make(input);\n\tconst definition = Object.assign(make, schema);\n\tObject.setPrototypeOf(definition, Object.getPrototypeOf(schema));\n\tattachValueDescriptor(definition, {\n\t\ttype: \"error\",\n\t\ttag,\n\t\tfields: descriptorFields(errorFields)\n\t});\n\treturn definition;\n};\nconst values = {\n\tarray,\n\tboolean,\n\tdate,\n\terror,\n\tid,\n\tinteger,\n\tliteral,\n\tliterals,\n\tnever,\n\tnull: nullValue,\n\tnullable,\n\tnumber,\n\tobject,\n\toptional,\n\trecord,\n\tstring,\n\tunion\n};\nconst bindValues = (definition) => {\n\tconst boundId = (tableName) => makeIdSchema(tableName);\n\tconst doc = (tableName) => {\n\t\tconst tableDefinition = definition[tableName];\n\t\tif (tableDefinition === void 0) throw new Error(`Unknown table '${tableName}'.`);\n\t\tconst tableFields = tableDefinition.fields;\n\t\tconst systemFields = {\n\t\t\tid: boundId(tableName),\n\t\t\tcreatedAt: date(),\n\t\t\tupdatedAt: date()\n\t\t};\n\t\treturn fixedObject(Struct.assign(tableFields, systemFields));\n\t};\n\tconst boundPagination = () => {\n\t\treturn pagination();\n\t};\n\treturn {\n\t\t...values,\n\t\tdoc,\n\t\tid: boundId,\n\t\tpage,\n\t\tpagination: boundPagination\n\t};\n};\n//#endregion\nexport { bindValues, schemaIndexLimits, table, values };\n\n//# sourceMappingURL=values.js.map","//#region src/runtime/schema.ts\nconst FunctionSchemaTypeId = Symbol.for(\"ignotum/runtime/schema/FunctionSchema\");\nconst attachFunctionSchema = (schema) => (definition) => {\n\tObject.defineProperty(definition, FunctionSchemaTypeId, {\n\t\tconfigurable: false,\n\t\tenumerable: false,\n\t\tvalue: schema,\n\t\twritable: false\n\t});\n\treturn definition;\n};\nconst getFunctionSchema = (value) => value[FunctionSchemaTypeId];\n//#endregion\nexport { FunctionSchemaTypeId, attachFunctionSchema, getFunctionSchema };\n\n//# sourceMappingURL=schema.js.map","import { a as getValueDescriptor, n as ValueDescriptorTypeId, t as ValueDescriptor } from \"../descriptor-t6BOEGw9.js\";\nimport { Result } from \"../runtime/result.js\";\nimport { bindValues, schemaIndexLimits, table, values } from \"./values.js\";\nimport { attachFunctionSchema } from \"../runtime/schema.js\";\nimport { Predicate } from \"effect\";\n//#region src/schema/types.ts\nconst SchemaDefinitionTypeId = Symbol.for(\"ignotum/schema/SchemaDefinition\");\n//#endregion\n//#region src/schema/definition.ts\nconst defineSchema = (define) => {\n\tconst definitions = define({\n\t\ttable,\n\t\tvalues\n\t});\n\tif (Object.values(definitions).reduce((count, definition) => count + Object.keys(definition.indexes).length, 0) > schemaIndexLimits.indexesPerSchema) throw new Error(`Schemas cannot declare more than ${schemaIndexLimits.indexesPerSchema} indexes.`);\n\treturn {\n\t\t_tag: \"Schema\",\n\t\t[SchemaDefinitionTypeId]: definitions\n\t};\n};\nconst isDefinedSchema = (value) => value._tag === \"Schema\" && Predicate.isObject(value[SchemaDefinitionTypeId]);\n//#endregion\n//#region src/schema/server.ts\nconst makeFunctionBuilder = (schema, kind) => {\n\tconst define = (definition) => attachFunctionSchema(schema)({\n\t\t_tag: kind,\n\t\t...definition\n\t});\n\treturn define;\n};\nconst makeFunctionBuilders = (schema) => ({\n\tmutation: makeFunctionBuilder(schema, \"Mutation\"),\n\tquery: makeFunctionBuilder(schema, \"Query\")\n});\nconst bindSchema = (schema) => ({\n\tvalues: bindValues(schema[SchemaDefinitionTypeId]),\n\t...makeFunctionBuilders(schema)\n});\n//#endregion\nexport { Result, SchemaDefinitionTypeId, ValueDescriptor, ValueDescriptorTypeId, bindSchema, bindValues, defineSchema, getValueDescriptor, isDefinedSchema, schemaIndexLimits, table, values };\n\n//# sourceMappingURL=index.js.map"],"mappings":"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"}

package/dist/runtime/server.d.ts

@@ -1,5 +1,5 @@
-import { r as ErrorValue, s as Result$1 } from "./result-BgcHn25t.js";
-import { i as defineSchema$1, n as SchemaAuthoring, t as DefinedSchema } from "./index-Dl_VQGmA.js";
+import { c as Result$1, i as ErrorValue } from "./id-Btwac71X-DhnKYsjY.js";
+import { i as defineSchema$1, n as SchemaAuthoring, t as DefinedSchema } from "./index-B5KSOjGN.js";
 //#region src/server/index.d.ts
 declare const Result: typeof Result$1;
 type Result<Success, Failure extends ErrorValue> = Result$1<Success, Failure>;

package/dist/runtime/server.js

@@ -1,5 +1,5 @@
-import { s as Result$1 } from "./descriptor-t6BOEGw9-BTHR-ZMv.js";
-import { r as defineSchema$1 } from "./schema-B-jMZEbs.js";
+import { l as Result$1 } from "./descriptor-t6BOEGw9-C1rwYIlx.js";
+import { r as defineSchema$1 } from "./schema-D9RmboaS.js";
 //#region src/server/index.ts
 const Result = Result$1;
 const defineSchema = defineSchema$1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ignotum",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Ignotum is an opinionated TypeScript application cloud.",
   "author": "Johannes Schießl",
   "repository": {
@@ -78,10 +78,10 @@
     "@effect/platform-node": "4.0.0-rc.111",
     "@effect/sql-sqlite-node": "4.0.0-rc.111",
     "redis": "6.2.1",
-    "@ignotum/contracts": "1.0.0",
-    "@ignotum/runtime": "1.0.0",
     "@ignotum/deployment": "1.0.0",
-    "@ignotum/shared": "1.0.0"
+    "@ignotum/contracts": "1.0.0",
+    "@ignotum/shared": "1.0.0",
+    "@ignotum/runtime": "1.0.0"
   },
   "engines": {
     "node": ">=22.18.0"

package/src/cli/agent-files.ts

@@ -7,9 +7,11 @@ import gettingStarted from "../../../../docs/user/getting-started.md?raw";
 import index from "../../../../docs/user/index.md?raw";
 import limits from "../../../../docs/user/limits.md?raw";
 import manualSetup from "../../../../docs/user/manual-setup.md?raw";
+import readingData from "../../../../docs/user/reading-data.md?raw";
 import schema from "../../../../docs/user/schema.md?raw";
 import serverFunctions from "../../../../docs/user/server-functions.md?raw";
 import values from "../../../../docs/user/values.md?raw";
+import writingData from "../../../../docs/user/writing-data.md?raw";
 
 export interface AppFile {
   readonly content: string;
@@ -24,9 +26,11 @@ const references = [
   ["index.md", index],
   ["limits.md", limits],
   ["manual-setup.md", manualSetup],
+  ["reading-data.md", readingData],
   ["schema.md", schema],
   ["server-functions.md", serverFunctions],
   ["values.md", values],
+  ["writing-data.md", writingData],
 ] as const;
 
 export const agentAppFiles: ReadonlyArray<AppFile> = [

package/src/client/hooks.ts

@@ -1,9 +1,14 @@
 import { Effect, Schema } from "effect";
-import { useDebugValue, useEffect, useMemo, useState } from "preact/hooks";
+import { useCallback, useDebugValue, useEffect, useMemo, useState } from "preact/hooks";
 
 import { functionPathOf, type FunctionReference } from "../internal/api.js";
-import { pending } from "@ignotum/contracts/runtime/result";
+import { inspectResult, pending, Result as RuntimeResult } from "@ignotum/contracts/runtime/result";
 import type { ErrorValue, QueryResult, SettledResult } from "@ignotum/contracts/runtime/result";
+import {
+  PaginationPageSize,
+  type PaginationOptions,
+  type PaginationPage,
+} from "@ignotum/contracts/runtime/pagination";
 import { encodeTransportObject } from "@ignotum/contracts/runtime/sync";
 import {
   ClientInfrastructureError,
@@ -102,6 +107,163 @@ export function useQuery<Args extends object, Success, Failure extends ErrorValu
   return result;
 }
 
+export type PaginationStatus = "CanLoadMore" | "Exhausted" | "LoadingMore";
+
+export interface PaginatedQueryValue<Item> {
+  readonly items: ReadonlyArray<Item>;
+  readonly loadMore: () => void;
+  readonly status: PaginationStatus;
+}
+
+export interface PaginatedQueryOptions {
+  readonly pageSize?: number;
+}
+
+type PaginationArguments = { readonly pagination: PaginationOptions };
+type ApplicationPaginationArguments<Args extends PaginationArguments> = Omit<Args, "pagination">;
+
+// @effect-diagnostics-next-line missingPipeableSignature:off React hooks are not pipeable functions.
+export function usePaginatedQuery<
+  Args extends PaginationArguments,
+  Item,
+  Failure extends ErrorValue,
+>(
+  reference: keyof ApplicationPaginationArguments<Args> extends never
+    ? FunctionReference<"Query", Args, PaginationPage<Item>, Failure>
+    : never,
+): QueryResult<PaginatedQueryValue<Item>, Failure>;
+export function usePaginatedQuery<
+  Args extends PaginationArguments,
+  Item,
+  Failure extends ErrorValue,
+>(
+  reference: FunctionReference<"Query", Args, PaginationPage<Item>, Failure>,
+  args: NoInfer<ApplicationPaginationArguments<Args>> | QuerySkip,
+  options?: PaginatedQueryOptions,
+): QueryResult<PaginatedQueryValue<Item>, Failure>;
+// @effect-diagnostics-next-line missingPipeableSignature:off React hooks must remain direct calls so hook order is statically visible.
+export function usePaginatedQuery<Args extends object, Item, Failure extends ErrorValue>(
+  reference: FunctionReference<"Query", Args & PaginationArguments, PaginationPage<Item>, Failure>,
+  args?: Args | QuerySkip,
+  options: PaginatedQueryOptions = {},
+): QueryResult<PaginatedQueryValue<Item>, Failure> {
+  const functionPath = functionPathOf(reference);
+  const skipped = isQuerySkip(args);
+  const input = args === undefined || 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);
+  const [refresh, setRefresh] = useState(0);
+  const [state, setState] = useState<{
+    readonly identity: string;
+    readonly result: QueryResult<PaginatedQueryValue<Item>, Failure> | ClientInfrastructureError;
+  }>(() => ({ identity, result: pending() }));
+  const loadMore = useCallback(() => setRequestedPages((count) => count + 1), []);
+
+  useDebugValue({ args: input, function: functionPath, result: state.result });
+
+  useEffect(() => {
+    setRequestedPages(1);
+    setState({ identity, result: pending() });
+  }, [identity, pageSize]);
+
+  useEffect(() => {
+    if (skipped) return;
+
+    let active = true;
+    const releases: Array<() => void> = [];
+
+    void syncRuntime
+      .runPromise(
+        Effect.gen(function* () {
+          const client = yield* SyncClient;
+          const items: Item[] = [];
+          let cursor: PaginationOptions["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 === undefined) {
+              setState({
+                identity,
+                result:
+                  items.length === 0
+                    ? pending()
+                    : RuntimeResult.succeed({ items, loadMore, status: "LoadingMore" }),
+              });
+              return;
+            }
+            if (inspected.type === "Failure") {
+              // SAFETY: pagination changes only the successful value. The
+              // failure channel is the generated query reference's Failure.
+              setState({
+                identity,
+                result: snapshot as QueryResult<PaginatedQueryValue<Item>, Failure>,
+              });
+              return;
+            }
+            // SAFETY: the generated reference and values.page validator couple
+            // this successful snapshot to PaginationPage<Item>.
+            const page = inspected.value as PaginationPage<Item>;
+            items.push(...page.items);
+            cursor = page.nextCursor;
+            if (cursor === null) {
+              setState({
+                identity,
+                result: RuntimeResult.succeed({ items, loadMore, status: "Exhausted" }),
+              });
+              return;
+            }
+          }
+
+          setState({
+            identity,
+            result: RuntimeResult.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;
+}
+
 type Mutation<Args, Success, Failure extends ErrorValue> = [Args] extends [void]
   ? () => Promise<SettledResult<Success, Failure>>
   : (args: Args) => Promise<SettledResult<Success, Failure>>;

package/src/client/index.ts

@@ -9,7 +9,8 @@ export const Result = { match: contractResult.match };
 export type Result<Value, Error extends ErrorValue> = SettledResult<Value, Error>;
 export type QueryResult<Value, Error extends ErrorValue> = ContractQueryResult<Value, Error>;
 export type { InternalServerError } from "@ignotum/contracts/runtime/result";
-export { useMutation, useQuery } from "./hooks.js";
+export { useMutation, usePaginatedQuery, useQuery } from "./hooks.js";
+export type { PaginatedQueryOptions, PaginatedQueryValue, PaginationStatus } from "./hooks.js";
 export { Query } from "./query.js";
 export type { QuerySkip } from "./query.js";
 export { app } from "./app.js";