@azurioh/discord-kernel 0.1.0 → 1.0.0

package/src/settings/cache.ts

@@ -0,0 +1,70 @@
+import type { Clock } from "@/clock";
+import type { SettingsChangedNotifier } from "@/settings/ports/settings-changed-notifier";
+
+/** How long a cached read stays fresh without an invalidation: the multi-process safety net (R15). */
+export const SETTINGS_CACHE_TTL_MS = 60_000;
+
+/** Reads of one module's settings for one guild, kept in process. */
+export interface SettingsCache {
+	/**
+	 * The cached value of `(guildId, moduleId)` while fresh, otherwise the result
+	 * of `load`, kept for {@link SETTINGS_CACHE_TTL_MS}. A failed load is not
+	 * kept, and neither is a load that an invalidation overtook.
+	 */
+	read<T>(guildId: string, moduleId: string, load: () => Promise<T>): Promise<T>;
+	/** Forget `(guildId, moduleId)`, so the next read loads again. */
+	invalidate(guildId: string, moduleId: string): void;
+}
+
+interface Entry {
+	readonly value: unknown;
+	readonly expiresAt: number;
+}
+
+/**
+ * Create the settings read cache. It drops an entry when the notifier reports
+ * a change of it, whichever process made the change, and after
+ * {@link SETTINGS_CACHE_TTL_MS} in any case.
+ *
+ * @param deps.clock - tells when an entry expires.
+ * @param deps.notifier - the settings change events to invalidate on.
+ * @returns an empty cache, subscribed to the notifier for its whole life.
+ */
+export function createSettingsCache(deps: {
+	clock: Clock;
+	notifier: SettingsChangedNotifier;
+}): SettingsCache {
+	const { clock } = deps;
+	const entries = new Map<string, Entry>();
+	/** Bumped by each invalidation, so a load that started before one is not kept. */
+	const generations = new Map<string, number>();
+
+	function invalidate(guildId: string, moduleId: string): void {
+		const key = cacheKey(guildId, moduleId);
+		entries.delete(key);
+		generations.set(key, (generations.get(key) ?? 0) + 1);
+	}
+
+	deps.notifier.subscribe((event) => invalidate(event.guildId, event.moduleId));
+
+	return {
+		async read<T>(guildId: string, moduleId: string, load: () => Promise<T>): Promise<T> {
+			const key = cacheKey(guildId, moduleId);
+			const entry = entries.get(key);
+			if (entry !== undefined && clock.now().getTime() < entry.expiresAt) {
+				return entry.value as T;
+			}
+			const generation = generations.get(key);
+			const value = await load();
+			if (generations.get(key) === generation) {
+				entries.set(key, { value, expiresAt: clock.now().getTime() + SETTINGS_CACHE_TTL_MS });
+			}
+			return value;
+		},
+		invalidate,
+	};
+}
+
+function cacheKey(guildId: string, moduleId: string): string {
+	return JSON.stringify([guildId, moduleId]);
+}

package/src/settings/choice.ts

@@ -0,0 +1,9 @@
+/**
+ * A single suggestion offered to a user while they pick a value: the label shown
+ * and the value stored. Vendor-free so the settings core and the command
+ * autocomplete share it without the core depending on discord.js.
+ */
+export interface Choice {
+	readonly name: string;
+	readonly value: string | number;
+}

package/src/settings/decode-stored.ts

@@ -0,0 +1,40 @@
+import type { SettingsDeclaration } from "@/settings/define-settings";
+import { parseFieldValue, pruneStoredValue } from "@/settings/fields/zod-schema";
+import { isPlainObject } from "@/settings/is-plain-object";
+
+/** Stored values sorted into what a guild can read and what it cannot. */
+export interface DecodedStored {
+	/** The declared fields whose stored value is valid, in stored form. */
+	readonly values: Readonly<Record<string, unknown>>;
+	/** The declared fields whose stored value fails validation, in declared order. */
+	readonly invalidKeys: readonly string[];
+}
+
+/**
+ * Check stored values against a declaration, field by field, without any guild
+ * lookup: a key the declaration no longer declares is ignored, an undeclared
+ * toggle is dropped (FR-017), and a value that fails its field is left out and
+ * reported. An unset field is absent from both outputs.
+ *
+ * @param declaration - the module's current settings declaration.
+ * @param raw - the stored values, or a migration's result: any value; anything
+ * but a plain object holds no field.
+ */
+export function decodeStored(declaration: SettingsDeclaration, raw: unknown): DecodedStored {
+	const stored = isPlainObject(raw) ? raw : {};
+	const values: Record<string, unknown> = {};
+	const invalidKeys: string[] = [];
+	for (const [key, declared] of Object.entries(declaration.fields)) {
+		if (!Object.hasOwn(stored, key)) {
+			continue;
+		}
+		const value = pruneStoredValue({ field: declared, value: stored[key] });
+		const parsed = parseFieldValue({ field: declared, value });
+		if (parsed.ok) {
+			values[key] = parsed.value;
+		} else {
+			invalidKeys.push(key);
+		}
+	}
+	return { values, invalidKeys };
+}

package/src/settings/define-settings.ts

@@ -0,0 +1,214 @@
+import {
+	type AnyField,
+	FIELD_LIMITS,
+	type FieldSpec,
+	LIST_ITEM_KINDS,
+	type Suggestions,
+	unhandledFieldKind,
+} from "@/settings/fields/field";
+import { parseFieldValue } from "@/settings/fields/zod-schema";
+import { SettingsDeclarationError } from "@/settings/settings-declaration-error";
+
+/** A group of fields. Texts are catalog keys. */
+export interface SettingsGroup {
+	readonly label: string;
+	readonly description?: string;
+	readonly order?: number;
+	/** Opaque access declaration: stored, never enforced here (FR-032). */
+	readonly access?: unknown;
+}
+
+/** Module-level presentation hints (FR-020). */
+export interface SettingsUi {
+	readonly icon?: string;
+	/** Group ids in their preferred order. */
+	readonly groupOrder?: readonly string[];
+}
+
+/** Reshapes values stored under an older declaration version. */
+export type SettingsMigration = (fromVersion: number, raw: unknown) => unknown;
+
+/** What a module writes to declare its settings. */
+export interface SettingsDeclarationInput {
+	/** Unique across modules; lowercase kebab-case. */
+	readonly id: string;
+	/** Starts at 1; raised when stored data must be reshaped. */
+	readonly version: number;
+	readonly labels: { readonly title: string; readonly description?: string };
+	readonly fields: Readonly<Record<string, AnyField>>;
+	readonly groups?: Readonly<Record<string, SettingsGroup>>;
+	/** Required when `version > 1`. */
+	readonly migrate?: SettingsMigration;
+	readonly ui?: SettingsUi;
+	/** Opaque access declaration: stored, never enforced here (FR-032). */
+	readonly access?: unknown;
+}
+
+/** A checked settings declaration, typed from what the module wrote. */
+export type SettingsDeclaration<D extends SettingsDeclarationInput = SettingsDeclarationInput> = D;
+
+/**
+ * Declare a module's settings. The declaration is returned unchanged — hints
+ * and access slots included — after the checks that need no guild.
+ *
+ * @param input - the module's declaration; keys and enum values stay literal.
+ * @returns the same declaration, typed for `SettingsValues`.
+ * @throws SettingsDeclarationError when a field has no label, a default fails
+ * its own field, a secret has a default or examples, an enum or static
+ * suggestion list has not 1 to 25 choices, a field names an undeclared group, a
+ * text allows more than 4000 characters, a list more than 25 items or an item
+ * kind lists cannot hold, a toggles field repeats a key or labels an undeclared
+ * one, or the version is above 1 without a migration.
+ */
+export function defineSettings<const D extends SettingsDeclarationInput>(
+	input: D,
+): SettingsDeclaration<D> {
+	checkVersion(input);
+	for (const [key, declared] of Object.entries(input.fields)) {
+		checkField({ declaration: input, key, declared });
+	}
+	return input;
+}
+
+function checkVersion(input: SettingsDeclarationInput): void {
+	if (!Number.isInteger(input.version) || input.version < 1) {
+		throw new SettingsDeclarationError(input.id, "version must be a positive integer");
+	}
+	if (input.version > 1 && input.migrate === undefined) {
+		throw new SettingsDeclarationError(
+			input.id,
+			`version ${input.version} needs a migration from earlier versions`,
+		);
+	}
+}
+
+/** Where a field check failed: the declaration and the field key. */
+interface FieldLocation {
+	readonly declarationId: string;
+	readonly key: string;
+}
+
+function fieldError(params: { at: FieldLocation; reason: string }): SettingsDeclarationError {
+	return new SettingsDeclarationError(
+		params.at.declarationId,
+		`field "${params.at.key}" ${params.reason}`,
+	);
+}
+
+function checkField(params: {
+	declaration: SettingsDeclarationInput;
+	key: string;
+	declared: AnyField;
+}): void {
+	const { declaration, key, declared } = params;
+	const at = { declarationId: declaration.id, key };
+	if (declared.label === undefined) {
+		throw fieldError({ at, reason: "has no label" });
+	}
+	const group = declared.ui?.group;
+	if (group !== undefined && declaration.groups?.[group] === undefined) {
+		throw fieldError({ at, reason: `names the undeclared group "${group}"` });
+	}
+	if (declared.spec.kind === "secret") {
+		checkSecret({ at, declared });
+	}
+	checkSpec({ at, spec: declared.spec });
+	if (declared.default !== undefined && !isValidDefault(declared)) {
+		throw fieldError({ at, reason: "has a default that fails its own validation" });
+	}
+}
+
+function isValidDefault(declared: AnyField): boolean {
+	return parseFieldValue({ field: declared, value: declared.default }).ok;
+}
+
+function checkSecret(params: { at: FieldLocation; declared: AnyField }): void {
+	const { at, declared } = params;
+	if (declared.default !== undefined) {
+		throw fieldError({ at, reason: "is a secret and cannot have a default" });
+	}
+	if (declared.ui?.examples !== undefined) {
+		throw fieldError({ at, reason: "is a secret and cannot have examples" });
+	}
+}
+
+/** Constraints of one kind, recursing into a list's item. */
+function checkSpec(params: { at: FieldLocation; spec: FieldSpec }): void {
+	const { at, spec } = params;
+	switch (spec.kind) {
+		case "enum":
+			checkChoiceCount({ at, count: spec.choices.length });
+			return;
+		case "integer":
+			checkStaticSuggestions({ at, suggest: spec.suggest });
+			return;
+		case "text":
+			if ((spec.maxLength ?? 0) > FIELD_LIMITS.textMaxLength) {
+				throw fieldError({
+					at,
+					reason: `allows more than ${FIELD_LIMITS.textMaxLength} characters`,
+				});
+			}
+			checkStaticSuggestions({ at, suggest: spec.suggest });
+			return;
+		case "list":
+			checkList({ at, spec });
+			return;
+		case "toggles":
+			checkToggles({ at, spec });
+			return;
+		case "channel":
+		case "role":
+		case "user":
+		case "color":
+		case "duration":
+		case "number":
+		case "boolean":
+		case "secret":
+			return;
+		default:
+			unhandledFieldKind(spec);
+	}
+}
+
+function checkList(params: { at: FieldLocation; spec: FieldSpec & { kind: "list" } }): void {
+	const { at, spec } = params;
+	if ((spec.maxItems ?? 0) > FIELD_LIMITS.listMaxItems) {
+		throw fieldError({ at, reason: `allows more than ${FIELD_LIMITS.listMaxItems} items` });
+	}
+	const itemKind = spec.item.spec.kind;
+	if (!LIST_ITEM_KINDS.includes(itemKind)) {
+		throw fieldError({ at, reason: `is a list of ${itemKind}, which lists cannot hold` });
+	}
+	checkSpec({ at, spec: spec.item.spec });
+}
+
+function checkToggles(params: { at: FieldLocation; spec: FieldSpec & { kind: "toggles" } }): void {
+	const { at, spec } = params;
+	if (new Set(spec.keys).size !== spec.keys.length) {
+		throw fieldError({ at, reason: "declares a toggle key more than once" });
+	}
+	for (const key of Object.keys(spec.keyLabels ?? {})) {
+		if (!spec.keys.includes(key)) {
+			throw fieldError({ at, reason: `labels the undeclared toggle key "${key}"` });
+		}
+	}
+}
+
+function checkStaticSuggestions(params: {
+	at: FieldLocation;
+	suggest: Suggestions<unknown> | undefined;
+}): void {
+	if (params.suggest !== undefined && "choices" in params.suggest) {
+		checkChoiceCount({ at: params.at, count: params.suggest.choices.length });
+	}
+}
+
+function checkChoiceCount(params: { at: FieldLocation; count: number }): void {
+	if (params.count < 1 || params.count > FIELD_LIMITS.staticChoices) {
+		throw fieldError({
+			at: params.at,
+			reason: `must have 1 to ${FIELD_LIMITS.staticChoices} choices`,
+		});
+	}
+}

package/src/settings/describe-field.ts

@@ -0,0 +1,155 @@
+import type { TranslateKey } from "@/i18n/translator";
+import {
+	type AnyField,
+	type FieldChoice,
+	type Suggestions,
+	unhandledFieldKind,
+} from "@/settings/fields/field";
+import type { JsonSchemaNode } from "@/settings/fields/zod-schema";
+
+/**
+ * Add a field's translated texts and hints to the JSON Schema of its stored
+ * value: `title`, `description`, `default` and `examples` under their standard
+ * keywords, labelled choices as `oneOf`, and the kernel hints under `x-kernel`.
+ * A secret is write-only and never carries a default or an example.
+ *
+ * @param params.field - the field, or list item, being described.
+ * @param params.schema - the JSON Schema of its stored value, annotated in place.
+ * @param params.translate - translates the field's catalog keys.
+ */
+export function annotateField(params: {
+	field: AnyField;
+	schema: JsonSchemaNode;
+	translate: TranslateKey;
+}): void {
+	const { field, schema, translate } = params;
+	if (field.label !== undefined) {
+		schema.title = translate(field.label);
+	}
+	if (field.description !== undefined) {
+		schema.description = translate(field.description);
+	}
+	if (field.spec.kind === "secret") {
+		schema.writeOnly = true;
+	} else {
+		if (field.default !== undefined) {
+			schema.default = field.default;
+		}
+		if (field.ui?.examples !== undefined) {
+			schema.examples = field.ui.examples;
+		}
+	}
+	if (field.spec.kind === "enum") {
+		delete schema.enum;
+		schema.oneOf = labelledChoices({ choices: field.spec.choices, translate });
+	}
+	if (field.spec.kind === "toggles") {
+		annotateToggles({ field, keyLabels: field.spec.keyLabels, schema, translate });
+	}
+	schema["x-kernel"] = kernelHints({ field, translate });
+}
+
+/** Each toggle gets its translated label and its own default. */
+function annotateToggles(params: {
+	field: AnyField;
+	keyLabels: Readonly<Partial<Record<string, string>>> | undefined;
+	schema: JsonSchemaNode;
+	translate: TranslateKey;
+}): void {
+	const { field, keyLabels, schema, translate } = params;
+	const defaults = field.default as Readonly<Record<string, boolean>>;
+	const properties = schema.properties as Record<string, JsonSchemaNode>;
+	for (const [key, toggle] of Object.entries(properties)) {
+		const label = keyLabels?.[key];
+		if (label !== undefined) {
+			toggle.title = translate(label);
+		}
+		toggle.default = defaults[key];
+	}
+}
+
+/** The `x-kernel` keyword of a field: its kind and every declared hint. */
+function kernelHints(params: { field: AnyField; translate: TranslateKey }): JsonSchemaNode {
+	const { field, translate } = params;
+	const hints: JsonSchemaNode = { kind: field.spec.kind, ...specHints(field) };
+	const { ui } = field;
+	if (ui?.group !== undefined) {
+		hints.group = ui.group;
+	}
+	if (ui?.order !== undefined) {
+		hints.order = ui.order;
+	}
+	if (field.unit !== undefined) {
+		hints.unit = translate(field.unit);
+	}
+	if (ui?.hint !== undefined) {
+		hints.hint = ui.hint;
+	}
+	if (ui?.advanced !== undefined) {
+		hints.advanced = ui.advanced;
+	}
+	return { ...hints, ...suggestionHints({ field, translate }) };
+}
+
+/** Kind-specific hints: accepted channel types. */
+function specHints(field: AnyField): JsonSchemaNode {
+	const { spec } = field;
+	if (spec.kind === "channel" && spec.types !== undefined) {
+		return { channelTypes: spec.types };
+	}
+	return {};
+}
+
+/**
+ * Where a surface finds values to offer: `guild` for Discord entities,
+ * `static` for fixed choices, `dynamic` for a server-side search.
+ */
+function suggestionHints(params: { field: AnyField; translate: TranslateKey }): JsonSchemaNode {
+	const { spec } = params.field;
+	switch (spec.kind) {
+		case "channel":
+		case "role":
+		case "user":
+			return { suggest: "guild" };
+		case "enum":
+			return { suggest: "static" };
+		case "integer":
+		case "text":
+			return spec.suggest === undefined
+				? {}
+				: declaredSuggestions({ suggest: spec.suggest, translate: params.translate });
+		case "color":
+		case "duration":
+		case "number":
+		case "boolean":
+		case "secret":
+		case "list":
+		case "toggles":
+			return {};
+		default:
+			return unhandledFieldKind(spec);
+	}
+}
+
+/** Static suggestions carry their translated choices; a strict search says so. */
+function declaredSuggestions(params: {
+	suggest: Suggestions<string> | Suggestions<number>;
+	translate: TranslateKey;
+}): JsonSchemaNode {
+	const { suggest, translate } = params;
+	if ("choices" in suggest) {
+		return {
+			suggest: "static",
+			choices: labelledChoices({ choices: suggest.choices, translate }),
+		};
+	}
+	return suggest.strict === true ? { suggest: "dynamic", strict: true } : { suggest: "dynamic" };
+}
+
+function labelledChoices(params: {
+	choices: readonly FieldChoice<unknown>[];
+	translate: TranslateKey;
+}): JsonSchemaNode[] {
+	const { choices, translate } = params;
+	return choices.map((choice) => ({ const: choice.value, title: translate(choice.label) }));
+}

package/src/settings/describe.ts

@@ -0,0 +1,90 @@
+import { resolveLocale, SOURCE_LOCALE } from "@/i18n/locale";
+import type { TranslateKey, Translator } from "@/i18n/translator";
+import type { SettingsDeclaration, SettingsGroup } from "@/settings/define-settings";
+import { annotateField } from "@/settings/describe-field";
+import { displayOrder } from "@/settings/field-order";
+import { fieldsJsonSchema, type JsonSchemaNode } from "@/settings/fields/zod-schema";
+
+/** URN prefix of a described module: `urn:discord-kernel:settings:<id>:v<version>`. */
+const SCHEMA_ID_PREFIX = "urn:discord-kernel:settings";
+
+/** A JSON value, as a JSON Schema document holds. */
+export type JsonValue =
+	| string
+	| number
+	| boolean
+	| null
+	| readonly JsonValue[]
+	| { readonly [key: string]: JsonValue };
+
+/**
+ * A JSON Schema draft 2020-12 document describing one module's settings, every
+ * text already translated, with kernel hints under the `x-kernel` keyword.
+ */
+export type SettingsSchema = { readonly [keyword: string]: JsonValue };
+
+/**
+ * Describe a module's settings for surfaces other than Discord (FR-030).
+ *
+ * @param params.declaration - the module's settings declaration.
+ * @param params.locale - any locale string; an unsupported one falls back to English.
+ * @param params.translator - translates the declaration's catalog keys.
+ * @returns the translated JSON Schema document of the module.
+ */
+export function describeSettings(params: {
+	declaration: SettingsDeclaration;
+	locale: string;
+	translator: Translator;
+}): SettingsSchema {
+	const { declaration, translator } = params;
+	const locale = resolveLocale([params.locale], SOURCE_LOCALE);
+	const translate: TranslateKey = (key) => translator.translate(locale, key);
+	const { $schema, ...fields } = fieldsJsonSchema({
+		fields: declaration.fields,
+		annotate: (field, schema) => annotateField({ field, schema, translate }),
+	});
+	const document: JsonSchemaNode = {
+		$schema,
+		$id: `${SCHEMA_ID_PREFIX}:${declaration.id}:v${declaration.version}`,
+		title: translate(declaration.labels.title),
+	};
+	if (declaration.labels.description !== undefined) {
+		document.description = translate(declaration.labels.description);
+	}
+	const moduleHints: JsonSchemaNode = { module: declaration.id, version: declaration.version };
+	if (declaration.ui?.icon !== undefined) {
+		moduleHints.icon = declaration.ui.icon;
+	}
+	moduleHints.locale = locale;
+	moduleHints.groups = describeGroups({ declaration, translate });
+	// Zod emits JSON only, and every annotation comes from the declaration's JSON values.
+	return { ...document, ...fields, "x-kernel": moduleHints } as SettingsSchema;
+}
+
+/** The declared groups, translated, in the display order every surface shares. */
+function describeGroups(params: {
+	declaration: SettingsDeclaration;
+	translate: TranslateKey;
+}): JsonSchemaNode[] {
+	const { declaration, translate } = params;
+	return displayOrder(declaration).groups.flatMap((id) => {
+		const group = declaration.groups?.[id];
+		return group === undefined ? [] : [describeGroup({ id, group, translate })];
+	});
+}
+
+function describeGroup(params: {
+	id: string;
+	group: SettingsGroup;
+	translate: TranslateKey;
+}): JsonSchemaNode {
+	const { id, group, translate } = params;
+	const described: JsonSchemaNode = { id, title: translate(group.label) };
+	if (group.description !== undefined) {
+		described.description = translate(group.description);
+	}
+	if (group.order !== undefined) {
+		described.order = group.order;
+	}
+	return described;
+}

package/src/settings/duration.ts

@@ -0,0 +1,54 @@
+/**
+ * Units in their only accepted order, largest first, each with its length in
+ * seconds. Fixing the order makes every duration have one spelling.
+ */
+const DURATION_PATTERN = /^(?:(\d+)d)?\s*(?:(\d+)h)?\s*(?:(\d+)m)?\s*(?:(\d+)s)?$/;
+const UNIT_SECONDS = [86_400, 3600, 60, 1] as const;
+
+/**
+ * Parse a human duration such as `"90s"`, `"15m"`, `"2h"`, `"7d"` or `"1h30m"`
+ * into whole seconds. Units go from days to seconds, each at most once; case
+ * and whitespace between parts are ignored. Returns `undefined` for anything
+ * else, including a bare number and a total beyond the safe integer range.
+ */
+export function parseDuration(input: string): number | undefined {
+	const trimmed = input.trim().toLowerCase();
+	if (trimmed === "") {
+		return undefined;
+	}
+	const match = DURATION_PATTERN.exec(trimmed);
+	if (match === null) {
+		return undefined;
+	}
+	let seconds = 0;
+	for (const [index, unit] of UNIT_SECONDS.entries()) {
+		const amount = match[index + 1];
+		if (amount !== undefined) {
+			seconds += Number(amount) * unit;
+		}
+	}
+	return Number.isSafeInteger(seconds) ? seconds : undefined;
+}
+
+/** Unit suffixes, in the order of {@link UNIT_SECONDS}. */
+const UNIT_SUFFIXES = ["d", "h", "m", "s"] as const;
+
+/**
+ * Write whole seconds the way {@link parseDuration} reads them back, largest
+ * unit first and zero parts left out: `5400` becomes `"1h30m"`, `0` `"0s"`.
+ *
+ * @param seconds - a non-negative whole number of seconds.
+ * @returns the shortest spelling `parseDuration` turns back into `seconds`.
+ */
+export function formatDuration(seconds: number): string {
+	let remaining = seconds;
+	let text = "";
+	for (const [index, unit] of UNIT_SECONDS.entries()) {
+		const amount = Math.floor(remaining / unit);
+		remaining -= amount * unit;
+		if (amount > 0) {
+			text += `${amount}${UNIT_SUFFIXES[index]}`;
+		}
+	}
+	return text === "" ? "0s" : text;
+}