ultimabase 0.0.0-stage → 0.1.1

package/src/cli-main.ts

@@ -0,0 +1,166 @@
+// The `ultimabase` command (D-105): `dev`, `start`, `sync`, `reset` and
+// `migrate`.
+import { spawn } from 'node:child_process'
+import { dirname, extname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { configPath, load } from './cli-config.ts'
+import { migrateDeploy, migrateStatus, reset } from './cli-deploy.ts'
+import { migrateCreate, sync } from './cli-migrate.ts'
+import { Refused } from './errors.ts'
+
+const usage = `Usage: ultimabase <command> [--config <path>]
+
+  dev                    Start the application, sync its development
+                         database, and restart it when a file changes.
+  start                  Start the application in production.
+  sync [--force]         Sync the development database to the models.
+  reset [--force]        Rebuild the development database from the
+                         migrations: every table is dropped. --force
+                         allows a database on another machine.
+  migrate create <name>  Write the models' changes as a migration, or an
+                         empty one for your SQL.
+  migrate deploy         Apply the pending migrations.
+  migrate status         Say what a deploy would do; exit 1 if anything.`
+
+export type Io = {
+	readonly cwd: string
+	readonly out: (text: string) => void
+	readonly err: (text: string) => void
+	readonly now: () => Date
+	/** Runs Node with `args` until it exits, and returns its exit code. */
+	readonly node: (args: readonly string[]) => Promise<number>
+}
+
+/**
+ * The file `dev` runs under `node --watch`: `serve.ts` beside the sources,
+ * `serve.js` in the published `dist`.
+ */
+const here = fileURLToPath(import.meta.url)
+export const serveFile: string = join(dirname(here), `serve${extname(here)}`)
+
+function runNode(args: readonly string[]): Promise<number> {
+	return new Promise((done, fail) => {
+		const child = spawn(process.execPath, args, { stdio: 'inherit' })
+		const forward = () => child.kill('SIGTERM')
+		process.on('SIGTERM', forward)
+		child.on('error', fail)
+		child.on('exit', (code) => {
+			process.off('SIGTERM', forward)
+			done(code ?? 1)
+		})
+	})
+}
+
+export const processIo: Io = {
+	cwd: process.cwd(),
+	out: (text) => process.stdout.write(`${text}\n`),
+	err: (text) => process.stderr.write(`${text}\n`),
+	now: () => new Date(),
+	node: runNode,
+}
+
+/**
+ * An expected failure, a refusal or an error with a `code` (from Node,
+ * PostgreSQL or the kernel), prints its message; any other, a bug, its
+ * stack (D-105).
+ */
+function report(error: unknown, io: Io): number {
+	if (!(error instanceof Error)) io.err(String(error))
+	else if (
+		error.name === 'Refused' ||
+		typeof Reflect.get(error, 'code') === 'string'
+	)
+		io.err(error.message)
+	else io.err(error.stack ?? error.message)
+	return 1
+}
+
+/** Reads `args`, refusing an option it does not know with its first sentence. */
+function read(args: readonly string[]) {
+	try {
+		return parseArgs({
+			args: [...args],
+			allowPositionals: true,
+			options: {
+				config: { type: 'string' },
+				force: { type: 'boolean', default: false },
+				help: { type: 'boolean', default: false },
+			},
+		})
+	} catch (error) {
+		const message: unknown = Reflect.get(Object(error), 'message')
+		const first = String(message).replace(/\.( .*)?$/s, '')
+		throw new Refused(`${first}. Run \`npx ultimabase --help\`.`)
+	}
+}
+
+async function run(args: readonly string[], io: Io): Promise<number> {
+	const { values, positionals } = read(args)
+	const [command, sub, name, ...rest] = positionals
+	const known =
+		rest.length === 0 &&
+		(command === 'migrate'
+			? (sub === 'create' && name !== undefined) ||
+				(['deploy', 'status'].includes(sub ?? '') && name === undefined)
+			: ['dev', 'start', 'sync', 'reset'].includes(command ?? '') &&
+				sub === undefined)
+	if (values.help) {
+		io.out(usage)
+		return 0
+	}
+	if (!known) {
+		if (command !== undefined)
+			io.err(`Unknown command '${positionals.join(' ')}'.`)
+		io.err(usage)
+		return 1
+	}
+	const path = configPath(io.cwd, values.config)
+	if (command === 'dev') {
+		process.env['NODE_ENV'] ??= 'development'
+		return io.node(['--watch', serveFile, path])
+	}
+	if (command === 'start') process.env['NODE_ENV'] ??= 'production'
+	const app = await load(path)
+	const dir = join(dirname(path), 'migrations')
+	if (command === 'start') await app.app.start()
+	else if (command === 'sync') {
+		const said = await sync(app, values.force)
+		if (said !== undefined) io.out(said)
+	} else if (command === 'reset') {
+		for (const line of await reset(app, dir, values.force)) io.out(line)
+	} else if (sub === 'deploy') {
+		for (const line of await migrateDeploy(app, dir)) io.out(line)
+	} else if (sub === 'status') {
+		const { lines, ok } = await migrateStatus(app, dir)
+		for (const line of lines) io.out(line)
+		return ok ? 0 : 1
+	} else io.out(await migrateCreate(app, dir, name ?? '', io.now()))
+	return 0
+}
+
+/** Runs the command `args` name, and returns its exit code. */
+export async function main(
+	args: readonly string[],
+	io: Io = processIo,
+): Promise<number> {
+	try {
+		return await run(args, io)
+	} catch (error) {
+		return report(error, io)
+	}
+}
+
+/** Starts the application of `path`, for `dev` (D-105). */
+export async function serve(
+	path: string | undefined,
+	io: Io = processIo,
+): Promise<number> {
+	try {
+		const { app } = await load(configPath(io.cwd, path))
+		await app.start()
+		return 0
+	} catch (error) {
+		return report(error, io)
+	}
+}

package/src/cli-migrate.ts

@@ -0,0 +1,143 @@
+// `migrate create` and `sync` (D-105), and the migration files both
+// `migrate` commands read.
+import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { Migration, Statement } from './adapter.ts'
+import type { Internals } from './app-internals.ts'
+import { kernelLogger, schemaOf } from './lifecycle.ts'
+import { Refused } from './errors.ts'
+import { hashOf, migrationsOf, synced } from './migrate.ts'
+
+export const header = '-- ultimabase schema '
+
+/** For a statement a transaction refuses: `create index concurrently`. */
+export const noTransaction = '-- ultimabase no transaction'
+export const create = '`npx ultimabase migrate create <name>`'
+
+export type Folder = {
+	readonly files: readonly Migration[]
+	readonly snapshot: unknown
+}
+
+/** The `.sql` files of `dir` in name order, and its `schema.json`. */
+export async function read(dir: string): Promise<Folder> {
+	if (!existsSync(dir)) return { files: [], snapshot: undefined }
+	const names = (await readdir(dir))
+		.filter((name) => name.endsWith('.sql'))
+		.toSorted()
+	const files = await Promise.all(
+		names.map(async (name) => {
+			// A Windows checkout's line endings change neither checksum nor header.
+			const text = await readFile(join(dir, name), 'utf8')
+			const sql = text.replaceAll('\r\n', '\n')
+			const checksum = createHash('sha256').update(sql).digest('hex')
+			const [first = '', second] = sql.split('\n', 2)
+			const schema = first.startsWith(header)
+				? first.slice(header.length)
+				: undefined
+			return {
+				name,
+				sql,
+				checksum,
+				...(schema === undefined ? {} : { schema }),
+				transaction: second !== noTransaction,
+			}
+		}),
+	)
+	const json = join(dir, 'schema.json')
+	if (!existsSync(json)) {
+		if (files.length > 0) {
+			throw new Refused(
+				'migrations/ holds SQL files but no schema.json: restore it from version control.',
+			)
+		}
+		return { files, snapshot: undefined }
+	}
+	const snapshot: unknown = JSON.parse(await readFile(json, 'utf8'))
+	return { files, snapshot }
+}
+
+/** `yyyyMMddHHmmss`, in UTC. */
+const stamp = (now: Date): string =>
+	now.toISOString().replaceAll(/[-:T]/g, '').slice(0, 'yyyyMMddHHmmss'.length)
+
+function body(
+	hash: string,
+	statements: readonly Statement[],
+	none: string,
+): string {
+	const blocks = statements.map(({ sql, loses, tries, rename }) =>
+		[
+			...(loses === undefined ? [] : [`-- ${loses}.`]),
+			...(tries === undefined ? [] : [`-- ${tries}.`]),
+			...(rename === undefined ? [] : [`-- a rename? write: ${rename.sql};`]),
+			`${sql};`,
+		].join('\n'),
+	)
+	const parts = blocks.length > 0 ? blocks : [none]
+	return `${header}${hash}\n\n${parts.join('\n\n')}\n`
+}
+
+/**
+ * Writes the migration from `schema.json` to the models; with no model
+ * changed, a file for the developer's SQL, as a data migration.
+ */
+export async function migrateCreate(
+	{ options }: Internals,
+	dir: string,
+	name: string,
+	now: Date,
+): Promise<string> {
+	if (!/^[a-z0-9_]+$/.test(name)) {
+		throw new Refused(
+			`"${name}" is not a migration name: use lowercase letters, digits and _.`,
+		)
+	}
+	const migrations = migrationsOf(options.database)
+	const schema = schemaOf(options)
+	const to = migrations.snapshot(schema)
+	const { snapshot: from } = await read(dir)
+	const hash = hashOf(to)
+	const file = `${stamp(now)}_${name}.sql`
+	await mkdir(dir, { recursive: true })
+	if (from !== undefined && hashOf(from) === hash) {
+		const sql = body(hash, [], '-- No model changed: write your SQL here.')
+		await writeFile(join(dir, file), sql, { flag: 'wx' })
+		return `Wrote migrations/${file}: no model changed, write your SQL in it.`
+	}
+	const statements = migrations.plan(from, schema)
+	const sql = body(hash, statements, '-- No statement: only names changed.')
+	await writeFile(join(dir, file), sql, { flag: 'wx' })
+	await writeFile(
+		join(dir, 'schema.json'),
+		`${JSON.stringify(to, null, '\t')}\n`,
+	)
+	return `Wrote migrations/${file}.`
+}
+
+/** Syncs a development database, losing data only with `force`. */
+export async function sync(
+	{ options }: Internals,
+	force: boolean,
+): Promise<string | undefined> {
+	if (process.env['NODE_ENV'] === 'production') {
+		throw new Refused(
+			'sync changes only a development database: run `npx ultimabase migrate deploy` in production.',
+		)
+	}
+	const { database } = options
+	migrationsOf(database)
+	const schema = schemaOf(options)
+	const logger = kernelLogger(options)
+	await database.start(schema, logger)
+	try {
+		const ran = await synced(database, schema, logger, force)
+		return ran === undefined
+			? 'The database already matches the models.'
+			: undefined
+	} finally {
+		await database.stop()
+	}
+}

package/src/cli.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// The `ultimabase` bin (D-105).
+import { main } from './cli-main.ts'
+
+process.exitCode = await main(process.argv.slice(2))

package/src/complete.ts

@@ -0,0 +1,73 @@
+// A user caller completed with its plugins' keys (D-121): once per object,
+// each plugin's `caller` in the order of `plugins`, a key given by one only,
+// a symbol key as a string one (D-126).
+import { isObject } from './query-where.ts'
+import type { Caller, Identity } from './rules.ts'
+
+/** A plugin's `caller`, bound to its context. */
+export type PluginCaller = {
+	readonly plugin: string
+	readonly caller: (identity: Identity) => Promise<unknown>
+}
+
+export type Complete = (identity: Identity) => Promise<Caller>
+
+// The keys every caller holds, which no plugin gives.
+const own = new Set<PropertyKey>(['kind', 'user'])
+
+async function completed(
+	identity: Identity,
+	plugins: readonly PluginCaller[],
+): Promise<Caller> {
+	const keys: { [key: PropertyKey]: unknown } = {}
+	const givers = new Map<PropertyKey, string>()
+	for (const { plugin, caller } of plugins) {
+		const given = await caller(identity)
+		if (!isObject(given)) {
+			throw new TypeError(`${plugin}.caller returns an object of keys.`)
+		}
+		for (const key of Reflect.ownKeys(given)) {
+			if (!Object.prototype.propertyIsEnumerable.call(given, key)) continue
+			const other = own.has(key) ? 'the kernel' : givers.get(key)
+			if (other !== undefined) {
+				throw new Error(
+					`${plugin}.caller gives the caller ${String(key)}, which ${other} gives; a key has one plugin.`,
+				)
+			}
+			givers.set(key, plugin)
+			const value: unknown = Reflect.get(given, key)
+			keys[key] = value
+		}
+	}
+	// Unnecessary only while no plugin declares a key: once one does, the
+	// kernel's types cannot see it given (D-121). caller-keys-typing proves it.
+	// oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- see above.
+	return Object.freeze({ ...identity, ...keys }) as Caller
+}
+
+/**
+ * Completes a user caller the first time the kernel receives it; `plugins`
+ * is read on each call, filled once their contexts exist.
+ */
+export function completer(plugins: readonly PluginCaller[]): Complete {
+	const pending = new WeakMap<object, Promise<Caller>>()
+	const done = new WeakSet<object>()
+	// A completed caller, or a user one when no plugin gives a key.
+	const kept = (identity: Identity): identity is Caller & Identity =>
+		done.has(identity)
+	return async (identity) => {
+		if (identity.kind !== 'user') return identity
+		if (plugins.length === 0) done.add(identity)
+		if (kept(identity)) return identity
+		const known = pending.get(identity)
+		if (known !== undefined) return known
+		const caller = completed(identity, plugins).then((result) => {
+			done.add(result)
+			return result
+		})
+		pending.set(identity, caller)
+		// A failure is not kept: the next request tries again.
+		caller.catch(() => pending.delete(identity))
+		return caller
+	}
+}

package/src/console-logger.ts

@@ -0,0 +1,87 @@
+// The logger the kernel writes to when the application gives none (D-58,
+// D-88, D-93): a readable line in a terminal, one JSON line with pino's
+// fields everywhere else.
+import { styleText } from 'node:util'
+import type { Logger } from './app-options.ts'
+
+type Level = 'info' | 'warn' | 'error'
+
+const colors = { info: 'green', warn: 'yellow', error: 'red' } as const
+
+/** An error as pino's `err` serializer writes it. */
+function serialized(value: unknown): unknown {
+	if (!(value instanceof Error)) return value
+	return { type: value.name, message: value.message, stack: value.stack }
+}
+
+function json(level: Level, fields: object, msg: string | undefined): string {
+	return JSON.stringify({
+		level,
+		time: Date.now(),
+		...Object.fromEntries(
+			Object.entries(fields).map(([key, value]) => [key, serialized(value)]),
+		),
+		...(msg === undefined ? {} : { msg }),
+	})
+}
+
+/** A value as `key=value` shows it: quoted when it would read ambiguously. */
+function shown(value: unknown): string {
+	if (typeof value === 'string' && /^[^\s"=]+$/u.test(value)) return value
+	return JSON.stringify(value) ?? String(value)
+}
+
+/** `10:42:07 INFO  [cache] Warm. size=2`, then each error's stack, indented. */
+function readable(
+	level: Level,
+	fields: object,
+	msg: string | undefined,
+	stream: NodeJS.WriteStream,
+): string {
+	const { name, ...rest }: { readonly name?: unknown } = fields
+	const errors = Object.values(rest).filter((value) => value instanceof Error)
+	const details = Object.entries(rest)
+		.filter(([, value]) => !(value instanceof Error))
+		.map(([key, value]) => `${key}=${shown(value)}`)
+	const line = [
+		styleText('dim', new Date().toTimeString().slice(0, 8), { stream }),
+		styleText(colors[level], level.toUpperCase().padEnd(5), { stream }),
+		name === undefined ? undefined : `[${shown(name)}]`,
+		msg,
+		...details,
+	]
+	const stacks = errors.map((error) =>
+		(error.stack ?? `${error.name}: ${error.message}`).replaceAll(
+			/^/gmu,
+			'    ',
+		),
+	)
+	return [line.filter((part) => part !== undefined).join(' '), ...stacks].join(
+		'\n',
+	)
+}
+
+export function consoleLogger(bindings: object = {}): Logger {
+	const log =
+		(level: Level) =>
+		(first: string | object, message?: string): void => {
+			const fields = {
+				...bindings,
+				...(typeof first === 'string' ? {} : first),
+			}
+			const msg = typeof first === 'string' ? first : message
+			// console.info writes to stdout, console.warn and console.error to stderr.
+			const stream = level === 'info' ? process.stdout : process.stderr
+			console[level](
+				stream.isTTY
+					? readable(level, fields, msg, stream)
+					: json(level, fields, msg),
+			)
+		}
+	return {
+		info: log('info'),
+		warn: log('warn'),
+		error: log('error'),
+		child: (more) => consoleLogger({ ...bindings, ...more }),
+	}
+}

package/src/create-many.ts

@@ -0,0 +1,126 @@
+// `createMany` (D-135): what a `create` runs, on each row of `data`, all or
+// nothing; the rows go in one write (D-99). `createManyAndReturn` returns
+// them in `data`'s order, each as `create` does (D-149).
+import type { Change } from './adapter.ts'
+import { InvalidQuery } from './errors.ts'
+import type { Event } from './hooks.ts'
+import { rereads, runHook, settle, settles } from './hooks.ts'
+import type { Plan as Shaped } from './query-args.ts'
+import { oneKeys } from './query-args.ts'
+import type { Context } from './query-context.ts'
+import { given, shapedRows } from './query-context.ts'
+import { byIds, entries, isObject } from './query-where.ts'
+import { createPlan } from './query-write.ts'
+import type { Commit, Store } from './transaction.ts'
+import type { Draft } from './write-data.ts'
+import { prepared, readData } from './write-data.ts'
+import { guarded } from './write-target.ts'
+import { writingOf } from './writing.ts'
+import { returned } from './writes.ts'
+
+/** A row's data, as `create` reads it, with no write but `connect` on a `one`. */
+function rowData(context: Context, data: unknown, at: string): Draft {
+	const { models, model } = context
+	for (const [name, value] of entries(data, at)) {
+		const field = model.fields.get(name)
+		if (field === undefined || field.kind === 'scalar') continue
+		const path = `${at}.${name}`
+		if (field.kind === 'many') {
+			throw new InvalidQuery(
+				path,
+				`${path} is a many relation, which createMany does not write.`,
+			)
+		}
+		if (
+			!isObject(value) ||
+			Object.keys(value).some((key) => key !== 'connect')
+		) {
+			throw new InvalidQuery(path, `${path} takes only connect in createMany.`)
+		}
+	}
+	return readData(models, model, data, true, at)
+}
+
+/**
+ * Creates the rows of `data`: their ids, or with `at` the rows as it shapes
+ * them, in `data`'s order. The rows come back even when a read rule would
+ * hide them, as `create`'s does (D-86).
+ */
+async function created(
+	context: Context,
+	store: Store,
+	commits: Commit[],
+	data: unknown,
+	at?: Shaped,
+): Promise<readonly unknown[]> {
+	const { model, caller, scope } = context
+	const drafts = Array.isArray(data)
+		? data.map((row: unknown, index) => rowData(context, row, `data.${index}`))
+		: [rowData(context, data, 'data')]
+	const sent: readonly Readonly<Draft>[] = drafts.map((draft) => ({ ...draft }))
+	// One row refused, none written (D-111).
+	for (const each of sent) scope.access?.allow(model, 'create', { data: each })
+	if (drafts.length === 0) return []
+	for (const draft of drafts) {
+		await prepared(model, draft, caller, true)
+		await runHook(model, 'beforeCreate', { caller, data: draft })
+	}
+	const events: Event[] = []
+	const writing = writingOf(scope, store, events)
+	const changes: Change[] = []
+	const ids: string[] = []
+	for (const [index, draft] of drafts.entries()) {
+		const { id, plan } = await createPlan(
+			scope,
+			model,
+			draft,
+			sent[index] ?? {},
+			store,
+		)
+		ids.push(id)
+		events.push({ model, operation: 'create', id }, ...plan.events)
+		await plan.check(writing)
+		changes.push(...(await plan.changes(writing)))
+	}
+	const read = at && { model: model.name, ...at.read, where: byIds(ids) }
+	// An `after*` hook may change the rows: they are read once it ran (D-88).
+	const again = rereads(events)
+	const write = {
+		checks: writing.checks.map(({ check }) => check),
+		changes,
+		...(read && !again && { read }),
+	}
+	// Nothing follows a write without hooks: it may need no transaction.
+	const run = settles(events) ? store.write(write) : store.last(write)
+	const rows = await guarded(run, writing.checks)
+	await settle(store, caller, events, commits)
+	if (at === undefined || read === undefined) return ids
+	const found = new Map(
+		(again ? await store.find(read) : rows).map((row) => [row.id, row]),
+	)
+	const ordered = ids.flatMap((id) => found.get(id) ?? [])
+	return shapedRows(context, store, ordered, at.shape, scope.access)
+}
+
+export async function createMany(
+	context: Context,
+	store: Store,
+	commits: Commit[],
+	args: unknown,
+): Promise<{ readonly count: number }> {
+	const found = given(args, context.model.name, ['data'], ['data'])
+	const ids = await created(context, store, commits, found.get('data'))
+	return { count: ids.length }
+}
+
+export async function createManyAndReturn(
+	context: Context,
+	store: Store,
+	commits: Commit[],
+	args: unknown,
+): Promise<readonly unknown[]> {
+	const keys = ['data', ...oneKeys]
+	const found = given(args, context.model.name, keys, ['data'])
+	const at = await returned(context, found)
+	return created(context, store, commits, found.get('data'), at)
+}

package/src/decimal.ts

@@ -0,0 +1,74 @@
+// Decimal values (D-145): exact numbers as strings, normalized to their
+// field's scale, compared and summed through `BigInt`.
+
+/** A decimal string's shape, as transports describe it. */
+export const decimalPattern = '^-?\\d+(\\.\\d+)?$'
+const shape = new RegExp(decimalPattern)
+
+/** A decimal's digits as a whole number, and how many follow its point. */
+type Exact = { readonly units: bigint; readonly scale: number }
+
+function exact(value: string): Exact {
+	const [whole = '', fraction = ''] = value.split('.')
+	return { units: BigInt(`${whole}${fraction}`), scale: fraction.length }
+}
+
+/** `value`'s units at `to` digits after the point; a cut digit is a 0. */
+const scaled = ({ units, scale }: Exact, to: number): bigint =>
+	to >= scale
+		? units * 10n ** BigInt(to - scale)
+		: units / 10n ** BigInt(scale - to)
+
+function text(units: bigint, scale: number): string {
+	const digits = (units < 0n ? -units : units)
+		.toString()
+		.padStart(scale + 1, '0')
+	const whole = digits.slice(0, digits.length - scale)
+	const sign = units < 0n ? '-' : ''
+	return scale === 0
+		? `${sign}${whole}`
+		: `${sign}${whole}.${digits.slice(-scale)}`
+}
+
+/** A decimal field's precision and scale. */
+export type Digits = { readonly precision: number; readonly scale: number }
+
+/** A field, which has digits if it is a decimal. */
+type Digited = { readonly type: string } & Partial<Digits>
+
+/** The message of a value a decimal `field` cannot hold, if it cannot. */
+export function decimalIssue(
+	value: unknown,
+	field: Digited,
+): string | undefined {
+	const digits = { precision: field.precision ?? 0, scale: field.scale ?? 0 }
+	const expected = `Expected a decimal string of at most ${digits.precision} digits, ${digits.scale} after the point, such as '12.50'.`
+	if (typeof value !== 'string' || !shape.test(value)) return expected
+	const [whole = '', fraction = ''] = value.replace('-', '').split('.')
+	const significant = whole.replace(/^0+/, '').length
+	const decimals = fraction.replace(/0+$/, '').length
+	return significant > digits.precision - digits.scale ||
+		decimals > digits.scale
+		? expected
+		: undefined
+}
+
+/** `value`, which fits, at `scale`: `'012.5'` is `'12.50'`. */
+export const normalized = (value: string, scale: number): string =>
+	text(scaled(exact(value), scale), scale)
+
+/** A value that fits `field`, as stored: a decimal at its scale. */
+export const storedValue = (value: unknown, field: Digited): unknown =>
+	field.type === 'decimal' && typeof value === 'string'
+		? normalized(value, field.scale ?? 0)
+		: value
+
+/** A decimal string's units at `scale`, which order decimals by value. */
+export const unitsOf = (value: string, scale: number): bigint =>
+	scaled(exact(value), scale)
+
+/** The exact sum of decimal strings, at `scale`. */
+export function sumDecimals(values: readonly string[], scale: number): string {
+	const total = values.reduce((sum, value) => sum + unitsOf(value, scale), 0n)
+	return text(total, scale)
+}