@ultimabase/testing 0.0.0-stage → 0.1.1

package/src/feeds.ts

@@ -0,0 +1,197 @@
+// The change feed of the contract (D-154): what each commit changed, once
+// committed, and nothing a rollback or a failed write undid.
+import type { Adapter, Changed } from 'ultimabase'
+import {
+	defineApp,
+	defineModel,
+	definePlugin,
+	master,
+	transaction,
+} from 'ultimabase'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { silent } from './silent.ts'
+
+const M = { as: master }
+
+const Card = defineModel({
+	name: 'Card',
+	fields: (f) => ({
+		title: f.string({ unique: true }),
+		rank: f.number({ integer: true, optional: true }),
+		tags: f.many(() => Tag),
+	}),
+})
+
+const Tag = defineModel({
+	name: 'Tag',
+	fields: (f) => ({ label: f.string(), cards: f.many(() => Card) }),
+})
+
+const long = Array.from({ length: 30 }, (_, index) =>
+	`field${index}`.padEnd(52, 'x'),
+)
+const Wide = defineModel({
+	name: 'Wide',
+	fields: (f) =>
+		Object.fromEntries(
+			long.map((name) => [name, f.string({ optional: true })]),
+		),
+})
+
+/** Written last: once its insert arrives, so have the changes before it. */
+const Mark = defineModel({
+	name: 'Mark',
+	fields: (f) => ({ at: f.number({ integer: true }) }),
+})
+
+const manifest = {
+	name: 'watcher',
+	version: '1.0.0',
+	peerDependencies: { ultimabase: '*' },
+}
+
+/** The changes `seen` holds, one entry per kind and target, lists sorted. */
+function merged(seen: readonly Changed[]): object[] {
+	const entries = new Map<string, { change: Changed; listed?: string[] }>()
+	for (const change of seen) {
+		const target = 'field' in change ? change.field : change.fields?.toSorted()
+		const key = JSON.stringify([change.kind, change.model, target])
+		const rows = 'field' in change ? change.pairs : change.ids
+		const known = entries.get(key)
+		const listed =
+			rows === undefined || (known !== undefined && known.listed === undefined)
+				? undefined
+				: [
+						...(known?.listed ?? []),
+						...rows.map((row) => (typeof row === 'string' ? row : row.join())),
+					]
+		entries.set(key, listed === undefined ? { change } : { change, listed })
+	}
+	return [...entries.values()].map(({ change, listed }) => {
+		const { kind, model } = change
+		const rows = listed?.toSorted()
+		if ('field' in change) return { kind, model, field: change.field, rows }
+		return { kind, model, fields: change.fields?.toSorted(), rows }
+	})
+}
+
+export function feeds(create: () => Adapter): void {
+	describe('the change feed', () => {
+		let seen: Changed[] = []
+		let marks = 0
+		let app: ReturnType<typeof defineApp>
+		const watcher = definePlugin({
+			name: 'watcher',
+			manifest,
+			changed: (changes) => {
+				seen.push(...changes)
+			},
+		})
+		beforeEach(async () => {
+			app = defineApp({
+				database: create(),
+				models: [Card, Tag, Wide, Mark],
+				plugins: [watcher.plugin()],
+				logger: silent,
+			})
+			await app.start()
+			seen = []
+		})
+		afterEach(async () => app.stop())
+
+		/** The changes the commits so far made, once all of them arrived. */
+		const settled = async (): Promise<object[]> => {
+			marks += 1
+			const { id } = await Mark.create({ data: { at: marks } }, M)
+			await vi.waitFor(() => {
+				expect(
+					seen.some((change) => 'ids' in change && change.ids?.includes(id)),
+				).toBe(true)
+			})
+			const changes = merged(seen.filter((change) => change.model !== 'Mark'))
+			seen = []
+			return changes
+		}
+
+		it('reports the rows each commit inserted, updated and deleted', async () => {
+			const a = await Card.create({ data: { title: 'a' } }, M)
+			const b = await Card.create({ data: { title: 'b' } }, M)
+			await Card.update({ where: { id: a.id }, data: { rank: 2 } }, M)
+			await Card.delete({ where: { id: b.id } }, M)
+			expect(await settled()).toEqual([
+				{ kind: 'insert', model: 'Card', rows: [a.id, b.id].toSorted() },
+				{
+					kind: 'update',
+					model: 'Card',
+					fields: ['rank', 'updatedAt'],
+					rows: [a.id],
+				},
+				{ kind: 'delete', model: 'Card', rows: [b.id] },
+			])
+		})
+
+		it('reports the links a write added or removed, not those it found', async () => {
+			const card = await Card.create({ data: { title: 'a' } }, M)
+			const tag = await Tag.create({ data: { label: 'red' } }, M)
+			await settled()
+			const tags = { connect: [{ id: tag.id }] }
+			await Card.update({ where: { id: card.id }, data: { tags } }, M)
+			await Card.update({ where: { id: card.id }, data: { tags } }, M)
+			const pair = [card.id, tag.id].join()
+			const link = { model: 'Card', field: 'tags', rows: [pair] }
+			const updated = { kind: 'update', model: 'Card', fields: ['updatedAt'] }
+			expect(await settled()).toEqual([
+				{ ...updated, rows: [card.id, card.id] },
+				{ kind: 'link', ...link },
+			])
+			const disconnect = [{ id: tag.id }]
+			await Card.update(
+				{ where: { id: card.id }, data: { tags: { disconnect } } },
+				M,
+			)
+			expect(await settled()).toEqual([
+				{ ...updated, rows: [card.id] },
+				{ kind: 'unlink', ...link },
+			])
+		})
+
+		it('reports nothing of a rollback, a failed write or an empty update', async () => {
+			await Card.create({ data: { title: 'a' } }, M)
+			await settled()
+			const failed = transaction(async () => {
+				await Card.create({ data: { title: 'b' } }, M)
+				throw new Error('Stop.')
+			})
+			await expect(failed).rejects.toThrow('Stop.')
+			const taken = Card.create({ data: { title: 'a' } }, M)
+			await expect(taken).rejects.toMatchObject({ code: 'UNIQUE_VIOLATION' })
+			await Card.updateMany({ where: { title: 'none' }, data: { rank: 1 } }, M)
+			expect(await settled()).toEqual([])
+		})
+
+		it("reports a transaction's writes once it commits", async () => {
+			const [a, b] = await transaction(async () => [
+				await Card.create({ data: { title: 'a' } }, M),
+				await Card.create({ data: { title: 'b' } }, M),
+			])
+			expect(await settled()).toEqual([
+				{ kind: 'insert', model: 'Card', rows: [a?.id, b?.id].toSorted() },
+			])
+		})
+
+		it('lists no ids past a thousand, no fields past their limit', async () => {
+			const data = Array.from({ length: 1001 }, (_, index) => ({
+				title: `${index}`,
+			}))
+			await Card.createMany({ data }, M)
+			const wide = await Wide.create({ data: {} }, M)
+			const set = Object.fromEntries(long.map((name) => [name, 'v']))
+			await Wide.update({ where: { id: wide.id }, data: set }, M)
+			expect(await settled()).toEqual([
+				{ kind: 'insert', model: 'Card', rows: undefined },
+				{ kind: 'insert', model: 'Wide', rows: [wide.id] },
+				{ kind: 'update', model: 'Wide', fields: undefined, rows: [wide.id] },
+			])
+		})
+	})
+}

package/src/groups.ts

@@ -0,0 +1,185 @@
+// Groups in the contract (D-146): rows with no value form one group, a
+// relation is its target's id or `null` when the caller cannot read it, and
+// the order is total, keys ascending after `orderBy`, nulls last; `having`
+// keeps the groups by their values and aggregates (D-149).
+import type { Adapter, Identity } from 'ultimabase'
+import { defineModel, master } from 'ultimabase'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { suiteUser } from './as-user.ts'
+import { started } from './suite.ts'
+
+const M: { readonly as: Identity } = { as: master }
+const user = { as: suiteUser('00000000-0000-4000-8000-000000000000') }
+
+/** A user reads the teams that are not hidden. */
+const Team = defineModel({
+	name: 'Team',
+	fields: (f) => ({
+		hidden: f.boolean({ default: false }),
+		deals: f.many(() => Deal),
+	}),
+}).with({ access: { read: ({ where }) => where({ hidden: false }) } })
+
+const Deal = defineModel({
+	name: 'Deal',
+	fields: (f) => ({
+		stage: f.enumOf(['b', 'a', 'c']),
+		amount: f.decimal({ precision: 8, scale: 2 }),
+		units: f.number({ integer: true, optional: true }),
+		on: f.dateTime({ optional: true }),
+		region: f.string({ optional: true }),
+		team: f.one(() => Team, { optional: true }),
+	}),
+}).with({ access: { read: () => true } })
+
+const day = (n: number): Date => new Date(Date.UTC(2026, 4, n, 12, 30))
+const stages = async (
+	kept: Promise<readonly { readonly stage: string }[]>,
+): Promise<string[]> => (await kept).map((group) => group.stage)
+
+export function groups(create: () => Adapter): void {
+	describe('groups', () => {
+		started(create, [Team, Deal])
+
+		let red = ''
+		let blue = ''
+		beforeEach(async () => {
+			red = (await Team.create({ data: {} }, M)).id
+			blue = (await Team.create({ data: { hidden: true } }, M)).id
+			const rows = [
+				{ stage: 'a', amount: '1.10', units: 2, on: day(1), region: 'n' },
+				{ stage: 'a', amount: '2.20', units: 3, on: day(1), region: 'n' },
+				{ stage: 'b', amount: '5', on: day(2), region: 's' },
+				{ stage: 'c', amount: '10', units: 1 },
+				{ stage: 'b', amount: '1', units: 4, on: day(2), region: 's' },
+			] as const
+			const teams = [red, blue, red, undefined, red]
+			for (const [at, row] of rows.entries()) {
+				const id = teams[at]
+				const data =
+					id === undefined ? row : { ...row, team: { connect: { id } } }
+				await Deal.create({ data }, M)
+			}
+		})
+
+		it('groups by scalars and dates, the rows with no value together', async () => {
+			const result = await Deal.groupBy(
+				{ by: ['region', 'on'], _count: true, _sum: { amount: true } },
+				M,
+			)
+			expect(result).toStrictEqual([
+				{ region: 'n', on: day(1), _count: 2, _sum: { amount: '3.30' } },
+				{ region: 's', on: day(2), _count: 2, _sum: { amount: '6.00' } },
+				{ region: null, on: null, _count: 1, _sum: { amount: '10.00' } },
+			])
+			const regions = await Deal.groupBy(
+				{ by: ['region'], orderBy: { region: 'desc' } },
+				M,
+			)
+			expect(regions).toStrictEqual([
+				{ region: null },
+				{ region: 's' },
+				{ region: 'n' },
+			])
+		})
+
+		it('sorts by an aggregate, then by the keys, and pages', async () => {
+			const counted = await Deal.groupBy(
+				{ by: ['stage'], orderBy: { _count: 'desc' }, _max: { units: true } },
+				M,
+			)
+			expect(counted).toStrictEqual([
+				{ stage: 'a', _max: { units: 3 } },
+				{ stage: 'b', _max: { units: 4 } },
+				{ stage: 'c', _max: { units: 1 } },
+			])
+			const summed = { _sum: { amount: 'desc' } } as const
+			const sorted = await Deal.groupBy({ by: ['stage'], orderBy: summed }, M)
+			expect(sorted).toStrictEqual([
+				{ stage: 'c' },
+				{ stage: 'b' },
+				{ stage: 'a' },
+			])
+			const paged = await Deal.groupBy(
+				{ by: ['stage'], orderBy: summed, skip: 1, take: 1 },
+				M,
+			)
+			expect(paged).toStrictEqual([{ stage: 'b' }])
+		})
+
+		it('groups by a relation, null when unset or unread', async () => {
+			const args = {
+				by: ['team'],
+				orderBy: { _count: 'desc' },
+				_count: true,
+			} as const
+			expect(await Deal.groupBy(args, M)).toStrictEqual([
+				{ team: { id: red }, _count: 3 },
+				{ team: { id: blue }, _count: 1 },
+				{ team: null, _count: 1 },
+			])
+			expect(await Deal.groupBy(args, user)).toStrictEqual([
+				{ team: { id: red }, _count: 3 },
+				{ team: null, _count: 2 },
+			])
+		})
+
+		it('keeps the groups having passes, by their values and aggregates', async () => {
+			const by = ['stage'] as const
+			const sum = { amount: { _sum: { gt: '5' } } } as const
+			expect(await stages(Deal.groupBy({ by, having: sum }, M))).toEqual([
+				'b',
+				'c',
+			])
+			const counts = {
+				stage: { in: ['a', 'b'] },
+				amount: { _count: 2 },
+			} as const
+			expect(await stages(Deal.groupBy({ by, having: counts }, M))).toEqual([
+				'a',
+				'b',
+			])
+			const average = { units: { _avg: { lt: 3 } } } as const
+			expect(await stages(Deal.groupBy({ by, having: average }, M))).toEqual([
+				'a',
+				'c',
+			])
+			const least = { on: { _min: { gte: day(2) } } } as const
+			expect(await stages(Deal.groupBy({ by, having: least }, M))).toEqual([
+				'b',
+			])
+			const either = {
+				OR: [{ stage: 'c' }, { units: { _max: { gte: 4 } } }],
+			} as const
+			expect(await stages(Deal.groupBy({ by, having: either }, M))).toEqual([
+				'b',
+				'c',
+			])
+			const dated = { NOT: { on: { _min: { equals: null } } } } as const
+			expect(await stages(Deal.groupBy({ by, having: dated }, M))).toEqual([
+				'a',
+				'b',
+			])
+			const counted = await Deal.groupBy(
+				{
+					by: ['stage', 'region'],
+					_count: true,
+					having: { region: { not: null }, amount: { _count: { gt: 1 } } },
+					orderBy: { _sum: { amount: 'desc' } },
+				},
+				M,
+			)
+			expect(counted).toStrictEqual([
+				{ stage: 'b', region: 's', _count: 2 },
+				{ stage: 'a', region: 'n', _count: 2 },
+			])
+		})
+
+		it('gives no groups without rows', async () => {
+			const where = { region: 'w' }
+			expect(
+				await Deal.groupBy({ by: ['stage'], where, _count: true }, M),
+			).toStrictEqual([])
+		})
+	})
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// `@ultimabase/testing` (D-40): an application's tests (D-130), the adapter
+// contract suite (D-94) and a test's user caller (D-80).
+export { asUser } from './as-user.ts'
+export { testAdapter } from './test-adapter.ts'
+export type { TestApplication, TestOptions } from './test-application.ts'
+export { testApplication } from './test-application.ts'

package/src/json-paths.ts

@@ -0,0 +1,185 @@
+// A json value filtered at a path (D-149): `#>` reaches the value, a missing
+// one is unknown, and each operator tests a value of its own JSON type.
+import type { Adapter, CreateDataOf, JsonValue, WhereOf } from 'ultimabase'
+import { defineModel, master } from 'ultimabase'
+import { describe, expect, it } from 'vitest'
+import { started } from './suite.ts'
+
+const M = { as: master }
+
+const Doc = defineModel({
+	name: 'Doc',
+	fields: (f) => ({
+		name: f.string({ unique: true }),
+		meta: f.json({ optional: true }),
+	}),
+})
+
+const rows: readonly CreateDataOf<typeof Doc>[] = [
+	{
+		name: 'ada',
+		meta: {
+			author: { name: 'Ada', age: 36 },
+			tags: ['x', 'y'],
+			items: [{ id: 1, kind: 'a' }, { id: 2 }],
+			note: null,
+			score: 5,
+		},
+	},
+	{
+		name: 'bob',
+		meta: { author: { name: 'bob' }, tags: ['y'], items: [], score: 'high' },
+	},
+	{ name: 'cy', meta: [1, 2, 3] },
+	{ name: 'nil' },
+	{ name: 'str', meta: '50%_off' },
+]
+
+const names = async (where: WhereOf<typeof Doc>): Promise<string[]> =>
+	(await Doc.findMany({ where, orderBy: { name: 'asc' } }, M)).map(
+		(doc) => doc.name,
+	)
+
+/** The rows the path filter keeps, and the rows its `NOT` keeps. */
+const kept = async (meta: object): Promise<[string[], string[]]> => [
+	await names({ meta }),
+	await names({ NOT: { meta } }),
+]
+
+const contains = (
+	path: string[],
+	arrayContains: JsonValue,
+): Promise<string[]> => names({ meta: { path, arrayContains } })
+
+const at = (path: string[], equals: JsonValue): Promise<string[]> =>
+	names({ meta: { path, equals } })
+
+export function jsonPaths(create: () => Adapter): void {
+	describe('json paths', () => {
+		started(create, [Doc])
+
+		const seeded = async (): Promise<void> => {
+			for (const data of rows) await Doc.create({ data }, M)
+		}
+
+		it('tests equality at a path, unknown where the path is missing', async () => {
+			await seeded()
+			const name = ['author', 'name']
+			expect(await kept({ path: name, equals: 'Ada' })).toEqual([
+				['ada'],
+				['bob'],
+			])
+			expect(await kept({ path: name, not: 'Ada' })).toEqual([['bob'], ['ada']])
+			expect(await names({ meta: { path: ['note'], equals: null } })).toEqual([
+				'ada',
+			])
+			expect(await names({ meta: { path: [], equals: [1, 2, 3] } })).toEqual([
+				'cy',
+			])
+			expect(await names({ meta: { path: [], equals: '50%_off' } })).toEqual([
+				'str',
+			])
+			const author = { path: ['author'], equals: { age: 36, name: 'Ada' } }
+			expect(await names({ meta: author })).toEqual(['ada'])
+		})
+
+		it('compares numbers by value and strings by code point', async () => {
+			await seeded()
+			const score = ['score']
+			expect(await kept({ path: score, gt: 3 })).toEqual([['ada'], ['bob']])
+			expect(await kept({ path: score, lt: 10 })).toEqual([['ada'], ['bob']])
+			expect(await kept({ path: score, gte: 'high' })).toEqual([
+				['bob'],
+				['ada'],
+			])
+			expect(await names({ meta: { path: score, lte: 5 } })).toEqual(['ada'])
+			const name = ['author', 'name']
+			expect(await kept({ path: name, gt: 'Z' })).toEqual([['bob'], ['ada']])
+		})
+
+		it('matches strings literally, and insensitively with mode', async () => {
+			await seeded()
+			const name = ['author', 'name']
+			expect(await names({ meta: { path: [], stringContains: '%_' } })).toEqual(
+				['str'],
+			)
+			expect(
+				await names({ meta: { path: name, stringContains: '%' } }),
+			).toEqual([])
+			expect(
+				await names({ meta: { path: name, stringStartsWith: 'a' } }),
+			).toEqual([])
+			const insensitive = { mode: 'insensitive' } as const
+			expect(
+				await names({
+					meta: { path: name, stringStartsWith: 'a', ...insensitive },
+				}),
+			).toEqual(['ada'])
+			expect(
+				await names({
+					meta: { path: name, stringEndsWith: 'B', ...insensitive },
+				}),
+			).toEqual(['bob'])
+			expect(await kept({ path: ['score'], stringContains: 'h' })).toEqual([
+				['bob'],
+				['ada'],
+			])
+		})
+
+		it('tests arrays with arrayContains, arrayStartsWith and arrayEndsWith', async () => {
+			await seeded()
+			const tags = ['tags']
+			expect(await contains(tags, 'y')).toEqual(['ada', 'bob'])
+			expect(await contains(tags, ['y', 'x'])).toEqual(['ada'])
+			expect(await contains(tags, [])).toEqual(['ada', 'bob'])
+			expect(await contains(['items'], { id: 1 })).toEqual(['ada'])
+			expect(await contains([], 2)).toEqual(['cy'])
+			expect(await contains([], [[1]])).toEqual([])
+			expect(await kept({ path: ['author'], arrayContains: 'Ada' })).toEqual([
+				[],
+				['ada', 'bob'],
+			])
+			expect(
+				await names({ meta: { path: tags, arrayStartsWith: 'x' } }),
+			).toEqual(['ada'])
+			expect(await names({ meta: { path: tags, arrayEndsWith: 'y' } })).toEqual(
+				['ada', 'bob'],
+			)
+			const first = { path: ['items'], arrayStartsWith: { kind: 'a', id: 1 } }
+			expect(await kept(first)).toEqual([['ada'], ['bob']])
+			expect(await kept({ path: ['items'], arrayEndsWith: { id: 2 } })).toEqual(
+				[['ada'], ['bob']],
+			)
+		})
+
+		it('reads an array index as PostgreSQL does', async () => {
+			await seeded()
+			expect(await at(['items', '0', 'id'], 1)).toEqual(['ada'])
+			expect(await at(['items', '-1', 'id'], 2)).toEqual(['ada'])
+			expect(await at(['0'], 1)).toEqual(['cy'])
+			expect(await at(['-3'], 1)).toEqual(['cy'])
+			expect(await at(['-0'], 1)).toEqual(['cy'])
+			expect(await at([' 1'], 2)).toEqual(['cy'])
+			expect(await at(['+1'], 2)).toEqual(['cy'])
+			for (const key of ['1 ', '-4', '3', '99999999999', 'one']) {
+				expect(await kept({ path: [key], equals: 2 })).toEqual([[], []])
+			}
+			expect(await at(['tags', '0', 'x'], 'x')).toEqual([])
+		})
+
+		it('filters nothing with a path and no operator', async () => {
+			await seeded()
+			const all = ['ada', 'bob', 'cy', 'nil', 'str']
+			expect(await names({ meta: { path: ['author'] } })).toEqual(all)
+			expect(
+				await names({ meta: { path: ['author'], mode: 'insensitive' } }),
+			).toEqual(all)
+			const both = {
+				path: ['author', 'name'],
+				stringStartsWith: 'A',
+				not: 'Ada',
+			}
+			expect(await names({ meta: both })).toEqual([])
+		})
+	})
+}