@shivaedev/sql 0.0.0 → 0.21.0

package/src/makeQueryClauses.ts

@@ -0,0 +1,36 @@
+import { Effect, Schema } from "effect";
+import type { SqlClient } from "effect/sql";
+import type { Fragment } from "effect/sql/Statement";
+
+const Limit = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0));
+const decodeLimit = Schema.decodeUnknownEffect(Limit);
+interface Order {
+	readonly direction: "asc" | "desc";
+	readonly field: string;
+}
+
+export function makeQueryClauses(
+	sql: SqlClient.SqlClient,
+	fieldAt: (key: string) => Effect.Effect<unknown, Schema.SchemaError>,
+	column: (key: string) => Fragment = (key) => sql`${sql(key)}`,
+) {
+	function orderClause(orderBy: Order | readonly Order[] | undefined) {
+		if (orderBy === undefined) {
+			return Effect.succeed(sql``);
+		}
+		const entries = "field" in orderBy ? [orderBy] : orderBy;
+		if (entries.length === 0) {
+			return Effect.succeed(sql``);
+		}
+		return Effect.map(
+			Effect.forEach(entries, ({ field, direction }) =>
+				Effect.as(fieldAt(field), sql`${column(field)} ${sql.literal(direction === "desc" ? "desc" : "asc")}`),
+			),
+			(columns) => sql`order by ${sql.csv(columns)}`,
+		);
+	}
+	function limitClause(limit: number | undefined) {
+		return limit === undefined ? Effect.succeed(sql``) : Effect.map(decodeLimit(limit), (rowLimit) => sql`limit ${rowLimit}`);
+	}
+	return { decodeLimit, limitClause, orderClause };
+}

package/src/migrationConvention.ts

@@ -0,0 +1,2 @@
+export const MIGRATIONS_DIRECTORY = "src/server/migrations";
+export const MIGRATION_FILE_PATTERN = /^[0-9]{4}_[a-z][a-z0-9]*(?:_[a-z0-9]+)*\.ts$/u;

package/src/migrations.ts

@@ -0,0 +1,58 @@
+import { Duration, Effect, Option } from "effect";
+import * as Reactivity from "effect/reactivity/Reactivity";
+import { Migrator, SqlClient } from "effect/sql";
+import { advisoryXactLock } from "./advisoryXactLock.ts";
+import { postgresRelease } from "./postgresRelease.ts";
+import { runSchemaComponent, type SchemaComponent } from "./SchemaComponent.ts";
+import { transact } from "./transact.ts";
+
+export interface PostgresMigrationOptions<R> {
+	readonly components?: readonly SchemaComponent<R>[];
+	readonly loader: Migrator.Loader<R>;
+	readonly lockTimeout: Duration.Input;
+	readonly release?: string;
+	readonly table?: string;
+}
+
+const migrate = Migrator.make({});
+
+export const migratePostgres = Effect.fn("EffectSql.migratePostgres")(function* <R>({
+	loader,
+	components = [],
+	table = "effect_sql_migrations",
+	lockTimeout,
+	release,
+}: PostgresMigrationOptions<R>) {
+	const sql = yield* SqlClient.SqlClient;
+	const available = yield* Effect.serviceOption(Reactivity.Reactivity);
+	const reactivity = Option.isSome(available) ? available.value : yield* Reactivity.make;
+	const millis = Duration.toMillis(lockTimeout);
+	const timeout = millis === Number.POSITIVE_INFINITY ? "0" : `${Math.max(1, Math.ceil(millis))}ms`;
+	const appliedMigrations = yield* Effect.gen(function* () {
+		yield* sql`select set_config('lock_timeout', ${timeout}, true)`;
+		yield* advisoryXactLock(`effect_sql_migrations:${table}`).pipe(Effect.catchTag("AdvisoryLockOutsideTransaction", Effect.die));
+		yield* sql`create table if not exists ${sql(table)} (
+  migration_id integer primary key,
+  created_at timestamp with time zone not null default now(),
+  name text not null
+)`;
+		const current = [...(yield* loader)].sort(([left], [right]) => left - right);
+		const applied = yield* sql<{ id: number }>`select migration_id as id from ${sql(table)}`.withoutTransform;
+		const appliedIds = new Set(applied.map(({ id }) => id));
+		const latest = applied.reduce((max, { id }) => Math.max(max, id), 0);
+		const missing = current.filter(([id]) => id <= latest && !appliedIds.has(id));
+		if (missing.length > 0) {
+			return yield* Effect.fail(
+				new Migrator.MigrationError({
+					kind: "BadState",
+					message: `Migrations missing from the ledger at or below latest applied id ${latest}: ${missing.map(([id]) => id).join(", ")}`,
+				}),
+			);
+		}
+		return yield* migrate({ loader: Effect.succeed(current), table });
+	}).pipe(transact({ onSqlError: (error) => error }), Effect.provideService(Reactivity.Reactivity, reactivity));
+	for (const component of [...components, ...(release === undefined ? [] : [postgresRelease(release, table)])]) {
+		yield* runSchemaComponent(component.name, component.apply);
+	}
+	return appliedMigrations;
+});

package/src/migrationsFromDirectory.ts

@@ -0,0 +1,7 @@
+import { Effect, Path } from "effect";
+import { Migrator } from "effect/sql";
+import { MIGRATIONS_DIRECTORY } from "#migrationConvention.ts";
+
+export function migrationsFromDirectory(root: string) {
+	return Effect.flatMap(Path.Path, (path) => Migrator.fromFileSystem(path.join(root, MIGRATIONS_DIRECTORY)));
+}

package/src/notifyPayload.ts

@@ -0,0 +1,34 @@
+import { Effect, Schema } from "effect";
+import { SqlError, UnknownError } from "effect/sql/SqlError";
+
+export const NotificationKeys = Schema.Array(Schema.Union([Schema.String, Schema.Finite]));
+export const decodeKeys = Schema.decodeUnknownEffect(Schema.fromJsonString(NotificationKeys));
+const encoder = new TextEncoder();
+
+export function notificationError(message: string, cause: unknown = message) {
+	return new SqlError({ reason: new UnknownError({ cause, message, operation: "notify" }) });
+}
+
+export const encodeKeys = Effect.fn("PostgresChanges.encodeKeys")(function* (keys: readonly unknown[]) {
+	const valid = yield* Schema.decodeUnknownEffect(NotificationKeys)(keys).pipe(
+		Effect.mapError((cause) => notificationError("PostgreSQL invalidation keys must be strings or finite numbers", cause)),
+	);
+	const payloads: string[] = [];
+	let batch: Array<string | number> = [];
+	for (const key of valid) {
+		const next = [...batch, key];
+		if (encoder.encode(JSON.stringify(next)).length >= 8000) {
+			if (batch.length === 0 || encoder.encode(JSON.stringify([key])).length >= 8000) {
+				return yield* Effect.fail(notificationError("A PostgreSQL invalidation key exceeds the NOTIFY payload limit"));
+			}
+			payloads.push(JSON.stringify(batch));
+			batch = [key];
+		} else {
+			batch = next;
+		}
+	}
+	if (batch.length > 0) {
+		payloads.push(JSON.stringify(batch));
+	}
+	return payloads;
+});

package/src/pendingPostgresMigrations.ts

@@ -0,0 +1,42 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import type { PostgresMigrationOptions } from "./migrations.ts";
+import { postgresRelease } from "./postgresRelease.ts";
+import { runSchemaComponent } from "./SchemaComponent.ts";
+
+export interface PendingPostgresMigrations {
+	readonly components: readonly { readonly name: string; readonly detail: string }[];
+	readonly migrations: readonly { readonly id: number; readonly name: string }[];
+}
+
+export const pendingPostgresMigrations = Effect.fn("EffectSql.pendingPostgresMigrations")(function* <R>({
+	loader,
+	components = [],
+	table = "effect_sql_migrations",
+	release,
+}: Pick<PostgresMigrationOptions<R>, "loader" | "table" | "components" | "release">) {
+	const expected = yield* loader;
+	const migrations: { id: number; name: string }[] = [];
+	if (expected.length > 0) {
+		const sql = yield* SqlClient.SqlClient;
+		const identifier = sql`${sql(table)}`.compile()[0];
+		const [ledger] = yield* sql<{ name: string | null }>`select to_regclass(${identifier})::text as name`.withoutTransform;
+		const applied =
+			ledger === undefined || ledger.name === null
+				? []
+				: yield* sql<{ id: number; name: string }>`select migration_id as id, name from ${sql(table)}`.withoutTransform;
+		for (const [id, name] of expected) {
+			if (!applied.some((row) => row.id === id && row.name === name)) {
+				migrations.push({ id, name });
+			}
+		}
+	}
+	const pendingComponents: { name: string; detail: string }[] = [];
+	for (const component of [...components, ...(release === undefined ? [] : [postgresRelease(release, table)])]) {
+		const detail = yield* runSchemaComponent(component.name, component.pending);
+		if (detail !== undefined) {
+			pendingComponents.push({ detail, name: component.name });
+		}
+	}
+	return { components: pendingComponents, migrations } satisfies PendingPostgresMigrations;
+});

package/src/pinnedGroups.ts

@@ -0,0 +1,46 @@
+import { Effect, Schema } from "effect";
+import type { Model } from "effect/schema";
+import type { SqlClient } from "effect/sql";
+import type { RepositoryListFilter } from "#repositoryFilter.ts";
+import { makeFilter } from "#repositoryFilter.ts";
+import { tupleFilter } from "#tupleIn.ts";
+
+export function pinnedGroups(
+	model: Model.Any,
+	sql: SqlClient.SqlClient,
+	partitionBy: readonly string[],
+	input: RepositoryListFilter<Model.Any> = {},
+) {
+	const tuple = input[tupleFilter];
+	if (
+		tuple?.values.length === 0
+		|| Object.values(input).some(
+			(value) => typeof value === "object" && value !== null && "in" in value && Array.isArray(value.in) && value.in.length === 0,
+		)
+	) {
+		return Effect.succeed({ groups: [], remaining: input });
+	}
+	const exactTuple = tuple !== undefined && tuple.fields.length === partitionBy.length && partitionBy.every((key) => tuple.fields.includes(key));
+	let groups: readonly (readonly unknown[])[] = [[]];
+	const remaining = { ...input };
+	if (exactTuple) {
+		groups = tuple.values.map((values) => partitionBy.map((key) => values[tuple.fields.indexOf(key)]));
+		delete remaining[tupleFilter];
+	} else {
+		for (const key of partitionBy) {
+			const value = input[key];
+			if (value === undefined) {
+				return Effect.succeed(undefined);
+			}
+			const values = typeof value === "object" && value !== null && "in" in value && Array.isArray(value.in) ? value.in : [value];
+			groups = groups.flatMap((group) => values.map((entry) => [...group, entry]));
+			delete remaining[key];
+		}
+	}
+	const { fieldAt } = makeFilter(model, sql);
+	return Effect.gen(function* () {
+		const fields = yield* Effect.forEach(partitionBy, fieldAt);
+		const groupsEncoded = yield* Effect.forEach(groups, (group) => Schema.encodeUnknownEffect(Schema.Tuple(fields))(group));
+		return { groups: groupsEncoded, remaining };
+	});
+}

package/src/postgresChanges.ts

@@ -0,0 +1,48 @@
+import { Context, type Duration, Effect, Layer, type Queue, type Scope } from "effect";
+import * as Reactivity from "effect/reactivity/Reactivity";
+import { SqlClient } from "effect/sql";
+import type { SqlError } from "effect/sql/SqlError";
+import { listenForChanges } from "./listenForChanges.ts";
+import { encodeKeys } from "./notifyPayload.ts";
+import { BeforeCommit, CommittedSink } from "./transact.ts";
+
+export interface PostgresNotification {
+	readonly payload: string;
+}
+
+export interface PostgresChangeClient extends SqlClient.SqlClient {
+	readonly listen: (channel: string) => Effect.Effect<Queue.Dequeue<PostgresNotification, SqlError>, SqlError, Scope.Scope>;
+}
+
+export interface PostgresChangesOptions {
+	readonly channel: string;
+	readonly client: PostgresChangeClient;
+	readonly heartbeatInterval?: Duration.Input;
+	readonly heartbeatTimeout?: Duration.Input;
+	readonly resync: Effect.Effect<number>;
+	readonly retryDelay?: Duration.Input;
+}
+
+export function postgresChanges(options: PostgresChangesOptions) {
+	return Layer.effectContext(
+		Effect.gen(function* () {
+			yield* listenForChanges(options);
+			const notify = Effect.fn("PostgresChanges.notify")(function* (keys: readonly unknown[]) {
+				const sql = yield* SqlClient.SqlClient;
+				if (sql.transactionService !== options.client.transactionService) {
+					return;
+				}
+				const payloads = yield* encodeKeys(keys);
+				for (const payload of payloads) {
+					yield* sql`select pg_notify(${options.channel}, ${payload})`;
+				}
+			});
+			function committed(keys: readonly unknown[]) {
+				return Effect.flatMap(SqlClient.SqlClient, (sql) =>
+					sql.transactionService === options.client.transactionService ? Effect.void : Reactivity.invalidate(keys),
+				);
+			}
+			return Context.make(BeforeCommit, notify).pipe(Context.add(CommittedSink, committed));
+		}),
+	);
+}

package/src/postgresRelease.ts

@@ -0,0 +1,41 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import type { SchemaComponent } from "./SchemaComponent.ts";
+
+export const readPostgresRelease = Effect.fn("EffectSql.readPostgresRelease")(function* (table = "effect_sql_migrations") {
+	const sql = yield* SqlClient.SqlClient;
+	const name = `${table}_release`;
+	const identifier = sql`${sql(name)}`.compile()[0];
+	const [exists] = yield* sql<{ name: string | null }>`select to_regclass(${identifier})::text as name`.withoutTransform;
+	if (exists === undefined || exists.name === null) {
+		return undefined;
+	}
+	const [row] = yield* sql<{ release: string; recordedAt: Date }>`select release, recorded_at as "recordedAt" from ${sql(name)}`.withoutTransform;
+	return row;
+});
+
+export function postgresRelease(release: string, table = "effect_sql_migrations"): SchemaComponent {
+	return {
+		apply: Effect.gen(function* () {
+			const sql = yield* SqlClient.SqlClient;
+			yield* sql`create table if not exists ${sql(`${table}_release`)} (
+				id boolean primary key default true check (id),
+				release text not null,
+				recorded_at timestamptz not null
+			)`;
+			yield* sql`create table if not exists ${sql(`${table}_workers`)} (
+				process_id text primary key,
+				release text not null,
+				heartbeat timestamptz not null
+			)`;
+			yield* sql`insert into ${sql(`${table}_release`)} (id, release, recorded_at)
+				values (true, ${release}, clock_timestamp())
+				on conflict (id) do update set release = excluded.release, recorded_at = excluded.recorded_at`;
+		}),
+		name: "database release",
+		pending: Effect.gen(function* () {
+			const current = yield* readPostgresRelease(table);
+			return current?.release === release ? undefined : `Expected release ${release}; recorded ${current?.release ?? "none"}`;
+		}),
+	};
+}

package/src/releaseWorkers.ts

@@ -0,0 +1,32 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+
+export const releaseWorkers = Effect.fn("EffectSql.releaseWorkers")(function* (
+	release: string,
+	staleMillis: number,
+	table = "effect_sql_migrations",
+) {
+	const sql = yield* SqlClient.SqlClient;
+	const processId = crypto.randomUUID();
+	const workers = `${table}_workers`;
+	return {
+		claim: sql.withTransaction(
+			Effect.gen(function* () {
+				const [owner] = yield* sql<{ release: string }>`select release from ${sql(`${table}_release`)} where id = true for update`.withoutTransform;
+				if (owner?.release !== release) {
+					return false;
+				}
+				const others = yield* sql`select process_id from ${sql(workers)} where release <> ${release}
+				and heartbeat > clock_timestamp() - ${staleMillis} * interval '1 millisecond'`;
+				if (others.length > 0) {
+					return false;
+				}
+				yield* sql`insert into ${sql(workers)} (process_id, release, heartbeat) values (${processId}, ${release}, clock_timestamp())
+				on conflict (process_id) do update set heartbeat = excluded.heartbeat`;
+				return true;
+			}),
+		),
+		heartbeat: sql`update ${sql(workers)} set heartbeat = clock_timestamp() where process_id = ${processId}`.pipe(Effect.asVoid),
+		remove: sql`delete from ${sql(workers)} where process_id = ${processId}`.pipe(Effect.asVoid),
+	};
+});

package/src/repository.ts

@@ -0,0 +1,147 @@
+import { Data, Effect, type Schema } from "effect";
+import type { Model } from "effect/schema";
+import { SqlClient } from "effect/sql";
+import { type BatchWrites, makeInsertMany } from "#batchWrites.ts";
+import { makeCompositeCrud, type PrimaryKey, type Repository } from "#compositeRepository.ts";
+import { type ConflictColumns, type ConflictWrites, makeConflictWrites } from "#conflictWrites.ts";
+import { makeInsertFromSelect, type SelectWrites } from "#insertFromSelect.ts";
+import { repositoryChanges } from "#repositoryChanges.ts";
+import type { FindManyFilter, RepositoryFilter, RepositoryListFilter } from "#repositoryFilter.ts";
+import { makeQueries, type Queries } from "#repositoryQueries.ts";
+import { type IdColumn, makeVersionedWrites, type VersionColumn, type VersionedWrites } from "#versionedRepository.ts";
+
+type Key<TModel extends Model.Any> = Extract<keyof TModel["fields"] & keyof Row<TModel>, string>;
+type Row<TModel extends Model.Any> = Schema.Struct.Type<TModel["fields"]>;
+
+export interface OrderBy<TModel extends Model.Any> {
+	readonly direction: "asc" | "desc";
+	readonly field: Key<TModel>;
+}
+
+export interface FindMany<TModel extends Model.Any, TKey extends Key<TModel>> {
+	readonly limit?: number;
+	readonly orderBy?: OrderBy<TModel> | readonly [OrderBy<TModel>, ...OrderBy<TModel>[]];
+	readonly select?: readonly [TKey, ...TKey[]];
+	readonly where?: FindManyFilter<TModel>;
+}
+
+export interface LatestPerGroup<TModel extends Model.Any> {
+	readonly limit: number;
+	readonly orderBy: readonly [OrderBy<TModel>, ...OrderBy<TModel>[]];
+	readonly partitionBy: readonly [Key<TModel>, ...Key<TModel>[]];
+	readonly where?: RepositoryListFilter<TModel>;
+}
+
+export class OptimisticConcurrencyError extends Data.TaggedError("OptimisticConcurrencyError")<{
+	readonly tableName: string;
+	readonly id: unknown;
+	readonly expectedVersion: number;
+	readonly reason: "missing" | "stale";
+}> {}
+
+interface RepositoryOptions<TId> {
+	readonly idColumn: TId;
+	readonly spanPrefix: string;
+	readonly tableName: string;
+}
+
+type VersionedRepository<TModel extends Model.Any, TId extends PrimaryKey<TModel>> = Omit<
+	Repository<TModel, TId>,
+	keyof VersionedWrites<TModel, TId>
+> &
+	VersionedWrites<TModel, TId> &
+	Queries<TModel>;
+
+export function makeRepository<
+	TModel extends Model.Any,
+	const TId extends PrimaryKey<TModel>,
+	const TConflict extends ConflictColumns<TModel>,
+	const TWhere extends keyof RepositoryFilter<TModel> = never,
+>(
+	model: TModel,
+	options: RepositoryOptions<TId> & {
+		readonly versionColumn: VersionColumn<TModel, TId>;
+		readonly conflictColumns: TConflict;
+		readonly conflictWhere?: Pick<RepositoryFilter<TModel>, TWhere>;
+	},
+): Effect.Effect<
+	VersionedRepository<TModel, TId> &
+		Pick<ConflictWrites<TModel, never, TModel["fields"][Extract<TWhere, keyof TModel["fields"]>]["EncodingServices"]>, "insertOrIgnore">,
+	never,
+	SqlClient.SqlClient
+>;
+export function makeRepository<TModel extends Model.Any, const TId extends PrimaryKey<TModel>>(
+	model: TModel,
+	options: RepositoryOptions<TId> & {
+		readonly versionColumn: VersionColumn<TModel, TId>;
+		readonly conflictColumns?: never;
+		readonly conflictWhere?: never;
+	},
+): Effect.Effect<VersionedRepository<TModel, TId>, never, SqlClient.SqlClient>;
+export function makeRepository<
+	TModel extends Model.Any,
+	const TId extends PrimaryKey<TModel>,
+	const TConflict extends ConflictColumns<TModel>,
+	const TWhere extends keyof RepositoryFilter<TModel> = never,
+>(
+	model: TModel,
+	options: RepositoryOptions<TId> & {
+		readonly versionColumn?: never;
+		readonly conflictColumns: TConflict;
+		readonly conflictWhere?: Pick<RepositoryFilter<TModel>, TWhere>;
+	},
+): Effect.Effect<
+	Repository<TModel, TId> &
+		BatchWrites<TModel> &
+		SelectWrites<TModel> &
+		Queries<TModel> &
+		ConflictWrites<
+			TModel,
+			TConflict[number] | (TId extends readonly PropertyKey[] ? TId[number] : TId),
+			TModel["fields"][Extract<TWhere, keyof TModel["fields"]>]["EncodingServices"]
+		>,
+	never,
+	SqlClient.SqlClient
+>;
+export function makeRepository<TModel extends Model.Any, const TId extends PrimaryKey<TModel>>(
+	model: TModel,
+	options: RepositoryOptions<TId> & { readonly versionColumn?: never; readonly conflictColumns?: never; readonly conflictWhere?: never },
+): Effect.Effect<Repository<TModel, TId> & BatchWrites<TModel> & SelectWrites<TModel> & Queries<TModel>, never, SqlClient.SqlClient>;
+export function makeRepository<TModel extends Model.Any, TId extends IdColumn<TModel>>(
+	model: TModel,
+	options: RepositoryOptions<TId | readonly [TId, TId, ...TId[]]> & {
+		readonly versionColumn?: string;
+		readonly conflictColumns?: readonly string[];
+		readonly conflictWhere?: Readonly<Record<string, unknown>>;
+	},
+): Effect.Effect<unknown, never, SqlClient.SqlClient> {
+	return Effect.fnUntraced(function* () {
+		const sql = yield* SqlClient.SqlClient;
+		const composite = typeof options.idColumn === "object";
+		const idColumns = (composite ? options.idColumn : [options.idColumn]).map(String);
+		const changes = yield* repositoryChanges(sql, options.tableName, idColumns);
+		const crud = makeCompositeCrud(model, sql, { ...options, columns: idColumns }, changes);
+		const queries = makeQueries(model, sql, options);
+		return options.versionColumn === undefined
+			? {
+					...crud,
+					insertFromSelect: makeInsertFromSelect(model, sql, { ...options, changes }, "insertFromSelect"),
+					insertMany: makeInsertMany(model, sql, { ...options, changes }, "insertMany"),
+					...(options.conflictColumns === undefined
+						? {}
+						: makeConflictWrites(model, sql, { ...options, changes, conflictColumns: options.conflictColumns, idColumns })),
+					...queries,
+				}
+			: {
+					...crud,
+					...makeVersionedWrites(model, sql, {
+						...options,
+						changes,
+						conflict: (id, expectedVersion, reason) => new OptimisticConcurrencyError({ expectedVersion, id, reason, tableName: options.tableName }),
+						idColumns,
+						versionColumn: options.versionColumn,
+					}),
+					...queries,
+				};
+	})();
+}

package/src/repositoryChanges.ts

@@ -0,0 +1,49 @@
+import { Effect, Option } from "effect";
+import * as Reactivity from "effect/reactivity/Reactivity";
+import { SqlClient } from "effect/sql";
+import { invalidateOnCommit, transact } from "#transact.ts";
+
+const ITEM_KEY_LIMIT = 1000;
+
+function encodeKeyValue(_key: string, value: unknown) {
+	return typeof value === "bigint" ? String(value) : value;
+}
+
+export type RepositoryChanges = Effect.Success<ReturnType<typeof repositoryChanges>>;
+
+export const repositoryChanges = Effect.fnUntraced(function* (sql: SqlClient.SqlClient, table: string, columns: readonly string[]) {
+	const initial = yield* Effect.serviceOption(Reactivity.Reactivity);
+	const fallback = Option.isSome(initial) ? initial.value : yield* Reactivity.make;
+	function provide<A, E, R>(effect: Effect.Effect<A, E, R | Reactivity.Reactivity | SqlClient.SqlClient>) {
+		return Effect.flatMap(Effect.serviceOption(Reactivity.Reactivity), (current) =>
+			effect.pipe(
+				Effect.provideService(SqlClient.SqlClient, sql),
+				Effect.provideService(
+					Reactivity.Reactivity,
+					Option.getOrElse(current, () => fallback),
+				),
+			),
+		);
+	}
+	function record(rows: readonly Readonly<Record<string, unknown>>[]) {
+		if (rows.length === 0) {
+			return Effect.void;
+		}
+		if (rows.length > ITEM_KEY_LIMIT) {
+			return provide(invalidateOnCommit([table, `${table}:*`]));
+		}
+		const ids = rows.map((row) =>
+			columns.length === 1
+				? row[columns[0] ?? ""]
+				: JSON.stringify(
+						columns.map((column) => row[column]),
+						encodeKeyValue,
+					),
+		);
+		return provide(invalidateOnCommit({ [table]: ids }));
+	}
+	function write<A, E, R>(effect: Effect.Effect<A, E, R>) {
+		return provide(transact(effect, { onSqlError: (error) => error }));
+	}
+	return { record, write };
+});

package/src/repositoryFilter.ts

@@ -0,0 +1,108 @@
+import { Effect, Schema, SchemaIssue } from "effect";
+import type { Model } from "effect/schema";
+import type { SqlClient } from "effect/sql";
+import { type TupleFilter, tuplePredicate } from "#tupleIn.ts";
+
+export type RepositoryFilter<TModel extends Model.Any> = {
+	readonly [TField in keyof Schema.Struct.Type<TModel["fields"]>]?: Schema.Struct.Type<TModel["fields"]>[TField] | undefined;
+};
+
+export type RepositoryListFilter<TModel extends Model.Any> = Partial<TupleFilter<TModel>> & {
+	readonly [TField in keyof Schema.Struct.Type<TModel["fields"]>]?:
+		| Schema.Struct.Type<TModel["fields"]>[TField]
+		| { readonly in: readonly Schema.Struct.Type<TModel["fields"]>[TField][] }
+		| undefined;
+};
+
+const Ordered = Schema.Union([Schema.String, Schema.Number, Schema.BigInt, Schema.Date, Schema.BigDecimal, Schema.DateTimeUtc]);
+export type OrderedValue = typeof Ordered.Type;
+export type Comparisons<T, TOperand = NonNullable<T>> = [NonNullable<T>] extends [OrderedValue]
+	? { readonly gt?: TOperand; readonly gte?: TOperand; readonly lt?: TOperand; readonly lte?: TOperand }
+	: { readonly gt?: never; readonly gte?: never; readonly lt?: never; readonly lte?: never };
+type Pattern<T> = [NonNullable<T>] extends [string] ? { readonly like?: NonNullable<T> } : { readonly like?: never };
+
+export type FindManyFilter<TModel extends Model.Any> = Partial<TupleFilter<TModel>> & {
+	readonly [TField in keyof Schema.Struct.Type<TModel["fields"]>]?:
+		| Schema.Struct.Type<TModel["fields"]>[TField]
+		| (Comparisons<Schema.Struct.Type<TModel["fields"]>[TField]> & Pattern<Schema.Struct.Type<TModel["fields"]>[TField]>)
+		| { readonly in: readonly Schema.Struct.Type<TModel["fields"]>[TField][] }
+		| undefined;
+};
+
+const operators = { gt: ">", gte: ">=", like: "like", lt: "<", lte: "<=" } as const;
+function isOperator(key: string): key is keyof typeof operators {
+	return Object.hasOwn(operators, key);
+}
+
+export function makeFilter<TModel extends Model.Any>(model: TModel, sql: SqlClient.SqlClient, references?: { readonly tableName: string }) {
+	function fieldAt(key: string) {
+		const field = Object.hasOwn(model.fields, key) ? model.fields[key] : undefined;
+		return field === undefined
+			? Effect.fail(new Schema.SchemaError(new SchemaIssue.Pointer([key], new SchemaIssue.UnexpectedKey(model.ast, key))))
+			: Effect.succeed(field);
+	}
+	function column(key: string) {
+		return references === undefined ? sql`${sql(key)}` : sql`${sql(references.tableName)}.${sql(key)}`;
+	}
+	function reference(value: unknown) {
+		return references !== undefined && typeof value === "object" && value !== null && "excluded" in value && typeof value.excluded === "string"
+			? value.excluded
+			: undefined;
+	}
+	function comparison(key: string, field: Schema.Constraint, operator: string, operand: unknown) {
+		if (!isOperator(operator)) {
+			return Effect.fail(new Schema.SchemaError(new SchemaIssue.Pointer([key, operator], new SchemaIssue.UnexpectedKey(model.ast, operator))));
+		}
+		const incoming = reference(operand);
+		if (incoming !== undefined) {
+			return Effect.as(fieldAt(incoming), sql`${column(key)} ${sql.literal(operators[operator])} excluded.${sql(incoming)}`);
+		}
+		const validate = Schema.decodeUnknownEffect(operator === "like" ? Schema.String : Ordered);
+		return Effect.flatMap(validate(operand), (decoded) =>
+			Effect.map(Schema.encodeEffect(field)(decoded), (encoded) => sql`${column(key)} ${sql.literal(operators[operator])} ${encoded}`),
+		);
+	}
+	function inPredicate(key: string, encoded: readonly unknown[]) {
+		if (references === undefined) {
+			return sql.in(key, encoded);
+		}
+		return encoded.length === 0 ? sql`1 = 0` : sql`${column(key)} in ${sql.in(encoded)}`;
+	}
+	function predicate(key: string, value: unknown, allowIn: boolean, allowComparisons: boolean) {
+		return Effect.flatMap(fieldAt(key), (field) => {
+			const incoming = reference(value);
+			if (incoming !== undefined) {
+				return Effect.as(fieldAt(incoming), sql`${column(key)} = excluded.${sql(incoming)}`);
+			}
+			const encode = Schema.encodeEffect(field);
+			if (allowComparisons && typeof value === "object" && value !== null && Object.keys(value).some(isOperator)) {
+				return Effect.map(
+					Effect.forEach(Object.entries(value), ([operator, operand]) => comparison(key, field, operator, operand)),
+					(predicates) => sql.and(predicates),
+				);
+			}
+			return allowIn && typeof value === "object" && value !== null && "in" in value && Array.isArray(value.in)
+				? Effect.map(
+						Effect.forEach(value.in, (entry) => encode(entry)),
+						(encoded) => inPredicate(key, encoded),
+					)
+				: Effect.map(encode(value), (encoded) => (encoded === null ? sql`${column(key)} is null` : sql`${column(key)} = ${encoded}`));
+		});
+	}
+	function where(input: Readonly<Record<string, unknown>> & Partial<TupleFilter<Model.Any>> = {}, allowIn = false, allowComparisons = false) {
+		return Effect.gen(function* () {
+			const predicates = yield* Effect.forEach(
+				Object.entries(input).filter(([, value]) => value !== undefined),
+				([key, value]) => predicate(key, value, allowIn, allowComparisons),
+			);
+			if (allowIn) {
+				const tuple = yield* tuplePredicate(input, sql, fieldAt);
+				if (tuple !== undefined) {
+					predicates.push(tuple);
+				}
+			}
+			return sql.and(predicates);
+		});
+	}
+	return { fieldAt, where };
+}