@ultimabase/testing 0.0.0-stage → 0.1.1

package/src/aggregates.ts

@@ -0,0 +1,128 @@
+// Aggregates in the contract (D-143): a `null` is skipped, no value gives
+// `null`, strings compare by code point, dates come back as dates. The
+// numbers add up exactly, so both adapters give the same sums.
+import type { Adapter, Identity } from 'ultimabase'
+import { defineModel, master } from 'ultimabase'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { started } from './suite.ts'
+
+const M: { readonly as: Identity } = { as: master }
+
+const Sale = defineModel({
+	name: 'Sale',
+	fields: (f) => ({
+		amount: f.number(),
+		units: f.number({ integer: true, optional: true }),
+		code: f.string({ optional: true }),
+		stage: f.enumOf(['b', 'a', 'c']),
+		on: f.dateTime({ optional: true }),
+		region: f.string(),
+	}),
+})
+
+/** More aggregates than a database function takes arguments. */
+const names = Array.from({ length: 21 }, (_, at) => `n${at}`)
+const Wide = defineModel({
+	name: 'Wide',
+	fields: (f) => Object.fromEntries(names.map((name) => [name, f.number()])),
+})
+
+const day = (n: number): Date => new Date(Date.UTC(2026, 4, n, 12, 30))
+
+export function aggregates(create: () => Adapter): void {
+	describe('aggregates', () => {
+		started(create, [Sale, Wide])
+
+		beforeEach(async () => {
+			await Sale.createMany(
+				{
+					data: [
+						{
+							amount: 1.5,
+							units: 2,
+							code: 'a',
+							stage: 'b',
+							on: day(3),
+							region: 'n',
+						},
+						{
+							amount: 0.25,
+							units: 5,
+							code: 'Z',
+							stage: 'c',
+							on: day(1),
+							region: 'n',
+						},
+						{ amount: -4, code: 'é', stage: 'a', region: 'n' },
+						{ amount: 100, units: 7, stage: 'c', on: day(9), region: 's' },
+					],
+				},
+				M,
+			)
+		})
+
+		it('aggregates the rows `where` selects, skipping nulls', async () => {
+			expect(
+				await Sale.aggregate(
+					{
+						where: { region: 'n' },
+						_count: { _all: true, units: true, on: true },
+						_sum: { amount: true, units: true },
+						_avg: { amount: true, units: true },
+						_min: { amount: true, code: true, on: true, stage: true },
+						_max: { units: true, code: true, on: true, stage: true },
+					},
+					M,
+				),
+			).toStrictEqual({
+				_count: { _all: 3, units: 2, on: 2 },
+				_sum: { amount: -2.25, units: 7 },
+				_avg: { amount: -0.75, units: 3.5 },
+				_min: { amount: -4, code: 'Z', on: day(1), stage: 'a' },
+				_max: { units: 5, code: 'é', on: day(3), stage: 'c' },
+			})
+		})
+
+		it('counts rows and gives null without a value', async () => {
+			expect(await Sale.aggregate({ _count: true }, M)).toStrictEqual({
+				_count: 4,
+			})
+			expect(
+				await Sale.aggregate(
+					{
+						where: { region: 'w' },
+						_count: true,
+						_sum: { amount: true },
+						_avg: { units: true },
+						_min: { on: true },
+						_max: { code: true },
+					},
+					M,
+				),
+			).toStrictEqual({
+				_count: 0,
+				_sum: { amount: null },
+				_avg: { units: null },
+				_min: { on: null },
+				_max: { code: null },
+			})
+		})
+
+		it('takes more aggregates than a function takes arguments', async () => {
+			const all = Object.fromEntries(names.map((name) => [name, true] as const))
+			const row = Object.fromEntries(names.map((name, at) => [name, at]))
+			await Wide.create({ data: row }, M)
+			const result = await Wide.aggregate(
+				{ _count: all, _sum: all, _avg: all, _min: all, _max: all },
+				M,
+			)
+			expect(result).toStrictEqual({
+				_count: Object.fromEntries(names.map((name) => [name, 1])),
+				_sum: row,
+				_avg: row,
+				_min: row,
+				_max: row,
+			})
+		})
+	})
+}

package/src/as-user.ts

@@ -0,0 +1,26 @@
+// The caller of a signed-in user, for a test's `{ as }` (D-80, D-97); the
+// kernel completes it with its plugins' keys (D-121). In an application a
+// user caller comes from a session (D-39).
+import type { Identity } from 'ultimabase'
+
+type UserIdentity = Extract<Identity, { readonly kind: 'user' }>
+
+/** Acts as `user`, the registered user model's record, or `{ id }` without one. */
+export function asUser(user: UserIdentity['user']): Identity {
+	const caller: UserIdentity = Object.freeze({ kind: 'user', user })
+	return caller
+}
+
+/** A user record has an `id`, which is all the contract suites' models read. */
+const isUserRecord = (value: object): value is UserIdentity['user'] =>
+	'id' in value
+
+/**
+ * A user caller of id `id` for the contract suites, whatever user model an
+ * application registers.
+ */
+export function suiteUser(id: string): Identity {
+	const user = { id }
+	if (!isUserRecord(user)) throw new TypeError('A user record has an id.')
+	return asUser(user)
+}

package/src/bulk-returns.ts

@@ -0,0 +1,151 @@
+// The rows a bulk write returns (D-149): `createManyAndReturn` in the order
+// of `data`, `updateManyAndReturn` in `id` order, each as the write left it,
+// read in the write or, after a hook, once it ran.
+import type { Adapter } from 'ultimabase'
+import { defineModel, master } from 'ultimabase'
+import { describe, expect, it } from 'vitest'
+import { suiteUser } from './as-user.ts'
+import { started } from './suite.ts'
+
+const M = { as: master }
+const user = { as: suiteUser('00000000-0000-4000-8000-000000000000') }
+
+const Board = defineModel({
+	name: 'Board',
+	fields: (f) => ({
+		name: f.string(),
+		tickets: f.many(() => Ticket),
+		notes: f.many(() => Note),
+	}),
+}).with({ access: { read: () => true } })
+
+/** No rule, no hook: Master's update of them is one UPDATE (D-133). */
+const Ticket = defineModel({
+	name: 'Ticket',
+	fields: (f) => ({
+		title: f.string(),
+		points: f.number({ integer: true }),
+		board: f.one(() => Board, { optional: true }),
+	}),
+})
+
+/** A user reads the notes that are not hidden; a hook rewrites `bump`. */
+const Note = defineModel({
+	name: 'Note',
+	fields: (f) => ({
+		text: f.string(),
+		hidden: f.boolean({ default: false }),
+		board: f.one(() => Board, { optional: true }),
+	}),
+}).with({
+	access: {
+		read: ({ where }) => where({ hidden: false }),
+		create: () => true,
+		update: () => true,
+	},
+	hooks: {
+		afterCreate: async ({ record }) => {
+			if (record.text !== 'bump') return
+			await Note.update({ where: { id: record.id }, data: { text: 'up' } }, M)
+		},
+	},
+})
+
+export function bulkReturns(create: () => Adapter): void {
+	describe('bulk returns', () => {
+		started(create, [Board, Ticket, Note])
+
+		it('returns the rows created, in the order of data', async () => {
+			const board = await Board.create({ data: { name: 'b' } }, M)
+			const connect = { connect: { id: board.id } }
+			const rows = await Ticket.createManyAndReturn(
+				{
+					data: [
+						{ title: 'z', points: 1, board: connect },
+						{ title: 'a', points: 2 },
+					],
+					select: { title: true, board: { select: { name: true } } },
+				},
+				M,
+			)
+			expect(rows).toStrictEqual([
+				{ title: 'z', board: { name: 'b' } },
+				{ title: 'a', board: null },
+			])
+			const notes = await Note.createManyAndReturn(
+				{
+					data: [{ text: 'bump', hidden: true }, { text: 'n' }],
+					select: { text: true, hidden: true },
+				},
+				user,
+			)
+			expect(notes).toStrictEqual([
+				{ text: 'up', hidden: true },
+				{ text: 'n', hidden: false },
+			])
+		})
+
+		it('returns the rows of one UPDATE in id order, as it left them', async () => {
+			const board = await Board.create({ data: { name: 'b' } }, M)
+			const connect = { connect: { id: board.id } }
+			for (const [title, points] of [
+				['c', 1],
+				['a', 2],
+				['b', 3],
+			] as const) {
+				await Ticket.create({ data: { title, points, board: connect } }, M)
+			}
+			const where = { title: { in: ['c', 'a'] } }
+			const rows = await Ticket.updateManyAndReturn(
+				{
+					where,
+					data: { points: { multiply: 10 } },
+					select: { title: true, points: true },
+				},
+				M,
+			)
+			expect(rows).toStrictEqual([
+				{ title: 'c', points: 10 },
+				{ title: 'a', points: 20 },
+			])
+			const shaped = await Ticket.updateManyAndReturn(
+				{
+					where,
+					data: { points: { increment: 1 } },
+					select: { points: true, board: { select: { _count: true } } },
+				},
+				M,
+			)
+			expect(shaped).toStrictEqual([
+				{ points: 11, board: { _count: { tickets: 3, notes: 0 } } },
+				{ points: 21, board: { _count: { tickets: 3, notes: 0 } } },
+			])
+		})
+
+		it('returns each row its rule lets it update, read or not', async () => {
+			const board = await Board.create({ data: { name: 'b' } }, M)
+			const connect = { connect: { id: board.id } }
+			for (const text of ['q', 'p', 'r']) {
+				await Note.create({ data: { text, board: connect } }, M)
+			}
+			const rows = await Note.updateManyAndReturn(
+				{
+					where: { text: { not: 'r' } },
+					data: { hidden: true },
+					select: {
+						text: true,
+						hidden: true,
+						board: { select: { name: true } },
+					},
+				},
+				user,
+			)
+			expect(rows).toStrictEqual([
+				{ text: 'q', hidden: true, board: { name: 'b' } },
+				{ text: 'p', hidden: true, board: { name: 'b' } },
+			])
+			const none = { where: { text: 'q' }, data: { text: 'x' } }
+			expect(await Note.updateManyAndReturn(none, user)).toEqual([])
+		})
+	})
+}

package/src/cascades.ts

@@ -0,0 +1,338 @@
+// The cascades of the contract (D-54, D-102): what a delete does to the rows
+// that reference it, when no hook runs, as Master and as a user.
+import type { Adapter } from 'ultimabase'
+import { defineModel, master } from 'ultimabase'
+import { describe, expect, it } from 'vitest'
+import { suiteUser } from './as-user.ts'
+import { started } from './suite.ts'
+
+const M = { as: master }
+const open = () => true
+
+const Shop = defineModel({
+	name: 'Shop',
+	fields: (f) => ({
+		name: f.string({ unique: true }),
+		aisles: f.many(() => Aisle),
+		items: f.many(() => Item),
+		clerks: f.many(() => Clerk),
+		orders: f.many(() => Order),
+	}),
+}).with({ access: { read: open, delete: open } })
+
+const Aisle = defineModel({
+	name: 'Aisle',
+	fields: (f) => ({
+		label: f.string(),
+		shop: f.one(() => Shop, { onDelete: 'cascade' }),
+		items: f.many(() => Item),
+	}),
+})
+
+/** Reached twice from a shop: through its aisle, and directly. */
+const Item = defineModel({
+	name: 'Item',
+	fields: (f) => ({
+		label: f.string(),
+		aisle: f.one(() => Aisle, { onDelete: 'cascade' }),
+		shop: f.one(() => Shop, { onDelete: 'cascade' }),
+		orders: f.many(() => Order),
+	}),
+})
+
+/** An optional relation sets null by default. */
+const Clerk = defineModel({
+	name: 'Clerk',
+	fields: (f) => ({
+		name: f.string(),
+		shop: f.one(() => Shop, { optional: true }),
+	}),
+})
+
+/** A required relation restricts by default. */
+const Order = defineModel({
+	name: 'Order',
+	fields: (f) => ({
+		ref: f.string(),
+		item: f.one(() => Item),
+		shop: f.one(() => Shop, { onDelete: 'cascade' }),
+	}),
+})
+
+/** A cascade that comes back to its own model. */
+const Folder = defineModel({
+	name: 'Folder',
+	fields: (f) => ({
+		name: f.string(),
+		parent: f.one(() => Folder, {
+			optional: true,
+			onDelete: 'cascade',
+			inverse: 'children',
+		}),
+		children: f.many(() => Folder),
+	}),
+})
+
+/** A model a delete both deletes and empties: its rows are loaded (D-102). */
+const Room = defineModel({
+	name: 'Room',
+	fields: (f) => ({ seats: f.many(() => Seat), spares: f.many(() => Seat) }),
+})
+const Seat = defineModel({
+	name: 'Seat',
+	fields: (f) => ({
+		name: f.string(),
+		room: f.one(() => Room, { onDelete: 'cascade', inverse: 'seats' }),
+		spare: f.one(() => Room, { optional: true, inverse: 'spares' }),
+	}),
+})
+
+/** A model a delete empties twice: its rows are loaded (D-102). */
+const Wall = defineModel({
+	name: 'Wall',
+	fields: (f) => ({
+		fronts: f.many(() => Poster),
+		backs: f.many(() => Poster),
+	}),
+})
+const Poster = defineModel({
+	name: 'Poster',
+	fields: (f) => ({
+		front: f.one(() => Wall, { optional: true, inverse: 'fronts' }),
+		back: f.one(() => Wall, { optional: true, inverse: 'backs' }),
+	}),
+})
+
+const by = (id: string) => ({ connect: { id } })
+const user = { as: suiteUser('00000000-0000-4000-8000-000000000000') }
+
+/** A shop with an aisle, an item in it and a clerk. */
+const stocked = async (name: string) => {
+	const shop = await Shop.create({ data: { name } }, M)
+	const aisle = await Aisle.create(
+		{ data: { label: `${name} aisle`, shop: by(shop.id) } },
+		M,
+	)
+	const item = await Item.create(
+		{
+			data: { label: `${name} item`, aisle: by(aisle.id), shop: by(shop.id) },
+		},
+		M,
+	)
+	const clerk = await Clerk.create(
+		{ data: { name: `${name} clerk`, shop: by(shop.id) } },
+		M,
+	)
+	return { shop, item, clerk }
+}
+const order = async (item: string, shop: string) =>
+	Order.create({ data: { ref: 'o', item: by(item), shop: by(shop) } }, M)
+const counts = async () => [
+	await Shop.count({}, M),
+	await Aisle.count({}, M),
+	await Item.count({}, M),
+	await Order.count({}, M),
+]
+
+export function cascades(create: () => Adapter): void {
+	describe('cascades', () => {
+		started(create, [
+			Shop,
+			Aisle,
+			Item,
+			Clerk,
+			Order,
+			Folder,
+			Room,
+			Seat,
+			Wall,
+			Poster,
+		])
+
+		it('deletes what a delete reaches, by every path, and returns the row as it was', async () => {
+			const reds = await stocked('reds')
+			const blues = await stocked('blues')
+			const removed = await Shop.delete({ where: { name: 'reds' } }, M)
+			expect(removed).toEqual(reds.shop)
+			expect(await counts()).toEqual([1, 1, 1, 0])
+			const clerk = await Clerk.findUnique(
+				{ where: { id: reds.clerk.id }, include: { shop: true } },
+				M,
+			)
+			expect(clerk?.shop).toBeNull()
+			expect(clerk?.updatedAt.getTime()).toBeGreaterThanOrEqual(
+				reds.clerk.updatedAt.getTime(),
+			)
+			const kept = await Clerk.findUnique({ where: { id: blues.clerk.id } }, M)
+			expect(kept).toEqual(blues.clerk)
+		})
+
+		// D-135
+		it('returns the relations and counts of a delete as the caller read them before', async () => {
+			const reds = await stocked('reds')
+			const removed = await Shop.delete(
+				{
+					where: { id: reds.shop.id },
+					include: {
+						aisles: true,
+						clerks: { include: { shop: true } },
+						_count: true,
+					},
+				},
+				M,
+			)
+			expect(removed).toMatchObject({
+				name: 'reds',
+				aisles: [{ label: 'reds aisle' }],
+				clerks: [{ name: 'reds clerk', shop: { name: 'reds' } }],
+				_count: { aisles: 1, items: 1, clerks: 1, orders: 0 },
+			})
+			expect(await counts()).toEqual([0, 0, 0, 0])
+			const blues = await stocked('blues')
+			// A user reads no item: the model gives them no read rule.
+			const theirs = await Shop.delete(
+				{
+					where: { id: blues.shop.id },
+					select: { name: true, items: true, _count: true },
+				},
+				user,
+			)
+			expect(theirs).toEqual({
+				name: 'blues',
+				items: [],
+				_count: { aisles: 0, items: 0, clerks: 0, orders: 0 },
+			})
+			expect(await counts()).toEqual([0, 0, 0, 0])
+		})
+
+		it('refuses a delete a restricting row stops, and writes nothing', async () => {
+			const reds = await stocked('reds')
+			const blues = await stocked('blues')
+			await order(reds.item.id, blues.shop.id)
+			for (const caller of [M, user]) {
+				await expect(
+					Shop.delete({ where: { id: reds.shop.id } }, caller),
+				).rejects.toMatchObject({
+					code: 'RELATION_RESTRICTED',
+					details: { model: 'Order', field: 'item' },
+				})
+			}
+			expect(await counts()).toEqual([2, 2, 2, 1])
+			const clerk = await Clerk.findUnique({ where: { id: reds.clerk.id } }, M)
+			expect(clerk).toEqual(reds.clerk)
+		})
+
+		it('lets go a restricting row the cascade removes', async () => {
+			const reds = await stocked('reds')
+			await order(reds.item.id, reds.shop.id)
+			await Shop.delete({ where: { id: reds.shop.id } }, user)
+			expect(await counts()).toEqual([0, 0, 0, 0])
+		})
+
+		it('refuses a missing row', async () => {
+			await expect(
+				Shop.delete({ where: { name: 'nowhere' } }, M),
+			).rejects.toMatchObject({ code: 'NOT_FOUND' })
+		})
+
+		it('deletes many rows and what they reach, as Master and as a user', async () => {
+			const reds = await stocked('reds')
+			await stocked('blues')
+			await stocked('greens')
+			const names = { name: { in: ['reds', 'blues'] } }
+			const removed = await Shop.deleteMany({ where: names }, M)
+			expect(removed).toEqual({ count: 2 })
+			expect(await counts()).toEqual([1, 1, 1, 0])
+			const clerk = await Clerk.findUnique(
+				{ where: { id: reds.clerk.id }, include: { shop: true } },
+				M,
+			)
+			expect(clerk?.shop).toBeNull()
+			expect(await Shop.deleteMany({ where: names }, M)).toEqual({ count: 0 })
+			expect(await Shop.deleteMany({}, user)).toEqual({ count: 1 })
+			expect(await counts()).toEqual([0, 0, 0, 0])
+		})
+
+		it('deletes many rows chosen by the rows their delete reaches', async () => {
+			await stocked('reds')
+			await stocked('blues')
+			await stocked('greens')
+			// Through a cascade, then through a `setNull`.
+			const aisle = { aisles: { some: { label: 'reds aisle' } } }
+			expect(await Shop.deleteMany({ where: aisle }, M)).toEqual({ count: 1 })
+			const clerk = { clerks: { some: { name: 'blues clerk' } } }
+			expect(await Shop.deleteMany({ where: clerk }, M)).toEqual({ count: 1 })
+			const left = await Shop.findMany({}, M)
+			expect(left.map((shop) => shop.name)).toEqual(['greens'])
+			expect(await counts()).toEqual([1, 1, 1, 0])
+		})
+
+		it('deletes no row of many when a restricting row stops one', async () => {
+			const reds = await stocked('reds')
+			const blues = await stocked('blues')
+			await order(reds.item.id, blues.shop.id)
+			for (const caller of [M, user]) {
+				await expect(
+					Shop.deleteMany({ where: { name: 'reds' } }, caller),
+				).rejects.toMatchObject({
+					code: 'RELATION_RESTRICTED',
+					details: { model: 'Order', field: 'item' },
+				})
+			}
+			expect(await counts()).toEqual([2, 2, 2, 1])
+		})
+
+		it('deletes many trees of one model', async () => {
+			const root = await Folder.create({ data: { name: 'root' } }, M)
+			await Folder.create({ data: { name: 'child', parent: by(root.id) } }, M)
+			await Folder.create({ data: { name: 'other' } }, M)
+			await Folder.create({ data: { name: 'kept' } }, M)
+			const roots = { name: { in: ['root', 'other'] } }
+			expect(await Folder.deleteMany({ where: roots }, M)).toEqual({
+				count: 2,
+			})
+			const left = await Folder.findMany({}, M)
+			expect(left.map((folder) => folder.name)).toEqual(['kept'])
+		})
+
+		it('follows a cascade back to its own model', async () => {
+			const root = await Folder.create({ data: { name: 'root' } }, M)
+			const child = await Folder.create(
+				{ data: { name: 'child', parent: by(root.id) } },
+				M,
+			)
+			await Folder.create({ data: { name: 'leaf', parent: by(child.id) } }, M)
+			await Folder.create({ data: { name: 'other' } }, M)
+			await Folder.delete({ where: { id: root.id } }, M)
+			const left = await Folder.findMany({}, M)
+			expect(left.map((folder) => folder.name)).toEqual(['other'])
+		})
+
+		it('empties the key of a row it leaves, of a model it deletes', async () => {
+			const hall = await Room.create({ data: {} }, M)
+			const lobby = await Room.create({ data: {} }, M)
+			await Seat.create({ data: { name: 'in', room: by(hall.id) } }, M)
+			await Seat.create(
+				{ data: { name: 'out', room: by(lobby.id), spare: by(hall.id) } },
+				M,
+			)
+			await Room.delete({ where: { id: hall.id } }, M)
+			const left = await Seat.findMany({ include: { spare: true } }, M)
+			expect(left).toMatchObject([{ name: 'out', spare: null }])
+		})
+
+		it('empties two keys of a row that names the deleted row twice', async () => {
+			const wall = await Wall.create({ data: {} }, M)
+			const poster = await Poster.create(
+				{ data: { front: by(wall.id), back: by(wall.id) } },
+				M,
+			)
+			await Wall.delete({ where: { id: wall.id } }, M)
+			const left = await Poster.findUnique(
+				{ where: { id: poster.id }, include: { front: true, back: true } },
+				M,
+			)
+			expect(left).toMatchObject({ front: null, back: null })
+		})
+	})
+}