@azurioh/discord-kernel 0.1.0 → 1.0.0

package/dist/settings/define-settings.d.ts

@@ -0,0 +1,52 @@
+import { type AnyField } from "../settings/fields/field";
+/** 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 declare function defineSettings<const D extends SettingsDeclarationInput>(input: D): SettingsDeclaration<D>;
+//# sourceMappingURL=define-settings.d.ts.map

package/dist/settings/define-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-settings.d.ts","sourceRoot":"","sources":["../../src/settings/define-settings.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,QAAQ,EAMb,MAAM,yBAAyB,CAAC;AAIjC,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,gDAAgD;AAChD,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,iEAAiE;AACjE,MAAM,MAAM,iBAAiB,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;AAE/E,oDAAoD;AACpD,MAAM,WAAW,wBAAwB;IACxC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IAC1D,mCAAmC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wEAAwE;AACxE,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,wBAAwB,GAAG,wBAAwB,IAAI,CAAC,CAAC;AAEnG;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,CAAC,SAAS,wBAAwB,EACtE,KAAK,EAAE,CAAC,GACN,mBAAmB,CAAC,CAAC,CAAC,CAMxB"}

package/dist/settings/define-settings.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineSettings = defineSettings;
+const field_1 = require("../settings/fields/field");
+const zod_schema_1 = require("../settings/fields/zod-schema");
+const settings_declaration_error_1 = require("../settings/settings-declaration-error");
+/**
+ * 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.
+ */
+function defineSettings(input) {
+    checkVersion(input);
+    for (const [key, declared] of Object.entries(input.fields)) {
+        checkField({ declaration: input, key, declared });
+    }
+    return input;
+}
+function checkVersion(input) {
+    if (!Number.isInteger(input.version) || input.version < 1) {
+        throw new settings_declaration_error_1.SettingsDeclarationError(input.id, "version must be a positive integer");
+    }
+    if (input.version > 1 && input.migrate === undefined) {
+        throw new settings_declaration_error_1.SettingsDeclarationError(input.id, `version ${input.version} needs a migration from earlier versions`);
+    }
+}
+function fieldError(params) {
+    return new settings_declaration_error_1.SettingsDeclarationError(params.at.declarationId, `field "${params.at.key}" ${params.reason}`);
+}
+function checkField(params) {
+    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) {
+    return (0, zod_schema_1.parseFieldValue)({ field: declared, value: declared.default }).ok;
+}
+function checkSecret(params) {
+    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) {
+    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_1.FIELD_LIMITS.textMaxLength) {
+                throw fieldError({
+                    at,
+                    reason: `allows more than ${field_1.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:
+            (0, field_1.unhandledFieldKind)(spec);
+    }
+}
+function checkList(params) {
+    const { at, spec } = params;
+    if ((spec.maxItems ?? 0) > field_1.FIELD_LIMITS.listMaxItems) {
+        throw fieldError({ at, reason: `allows more than ${field_1.FIELD_LIMITS.listMaxItems} items` });
+    }
+    const itemKind = spec.item.spec.kind;
+    if (!field_1.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) {
+    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) {
+    if (params.suggest !== undefined && "choices" in params.suggest) {
+        checkChoiceCount({ at: params.at, count: params.suggest.choices.length });
+    }
+}
+function checkChoiceCount(params) {
+    if (params.count < 1 || params.count > field_1.FIELD_LIMITS.staticChoices) {
+        throw fieldError({
+            at: params.at,
+            reason: `must have 1 to ${field_1.FIELD_LIMITS.staticChoices} choices`,
+        });
+    }
+}
+//# sourceMappingURL=define-settings.js.map

package/dist/settings/define-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-settings.js","sourceRoot":"","sources":["../../src/settings/define-settings.ts"],"names":[],"mappings":"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"}

package/dist/settings/describe-field.d.ts

@@ -0,0 +1,19 @@
+import type { TranslateKey } from "../i18n/translator";
+import { type AnyField } 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 declare function annotateField(params: {
+    field: AnyField;
+    schema: JsonSchemaNode;
+    translate: TranslateKey;
+}): void;
+//# sourceMappingURL=describe-field.d.ts.map

package/dist/settings/describe-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-field.d.ts","sourceRoot":"","sources":["../../src/settings/describe-field.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EACN,KAAK,QAAQ,EAIb,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACrC,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,YAAY,CAAC;CACxB,GAAG,IAAI,CA0BP"}

package/dist/settings/describe-field.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.annotateField = annotateField;
+const field_1 = require("../settings/fields/field");
+/**
+ * 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.
+ */
+function annotateField(params) {
+    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) {
+    const { field, keyLabels, schema, translate } = params;
+    const defaults = field.default;
+    const properties = schema.properties;
+    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) {
+    const { field, translate } = params;
+    const hints = { 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) {
+    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) {
+    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 (0, field_1.unhandledFieldKind)(spec);
+    }
+}
+/** Static suggestions carry their translated choices; a strict search says so. */
+function declaredSuggestions(params) {
+    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) {
+    const { choices, translate } = params;
+    return choices.map((choice) => ({ const: choice.value, title: translate(choice.label) }));
+}
+//# sourceMappingURL=describe-field.js.map

package/dist/settings/describe-field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-field.js","sourceRoot":"","sources":["../../src/settings/describe-field.ts"],"names":[],"mappings":"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"}

package/dist/settings/describe.d.ts

@@ -0,0 +1,27 @@
+import type { Translator } from "../i18n/translator";
+import type { SettingsDeclaration } from "../settings/define-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 declare function describeSettings(params: {
+    declaration: SettingsDeclaration;
+    locale: string;
+    translator: Translator;
+}): SettingsSchema;
+//# sourceMappingURL=describe.d.ts.map

package/dist/settings/describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["../../src/settings/describe.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,4BAA4B,CAAC;AAQrF,qDAAqD;AACrD,MAAM,MAAM,SAAS,GAClB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,SAAS,EAAE,GACpB;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEvE;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACxC,WAAW,EAAE,mBAAmB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;CACvB,GAAG,cAAc,CAwBjB"}

package/dist/settings/describe.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeSettings = describeSettings;
+const locale_1 = require("../i18n/locale");
+const describe_field_1 = require("../settings/describe-field");
+const field_order_1 = require("../settings/field-order");
+const zod_schema_1 = require("../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";
+/**
+ * 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.
+ */
+function describeSettings(params) {
+    const { declaration, translator } = params;
+    const locale = (0, locale_1.resolveLocale)([params.locale], locale_1.SOURCE_LOCALE);
+    const translate = (key) => translator.translate(locale, key);
+    const { $schema, ...fields } = (0, zod_schema_1.fieldsJsonSchema)({
+        fields: declaration.fields,
+        annotate: (field, schema) => (0, describe_field_1.annotateField)({ field, schema, translate }),
+    });
+    const document = {
+        $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 = { 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 };
+}
+/** The declared groups, translated, in the display order every surface shares. */
+function describeGroups(params) {
+    const { declaration, translate } = params;
+    return (0, field_order_1.displayOrder)(declaration).groups.flatMap((id) => {
+        const group = declaration.groups?.[id];
+        return group === undefined ? [] : [describeGroup({ id, group, translate })];
+    });
+}
+function describeGroup(params) {
+    const { id, group, translate } = params;
+    const described = { id, title: translate(group.label) };
+    if (group.description !== undefined) {
+        described.description = translate(group.description);
+    }
+    if (group.order !== undefined) {
+        described.order = group.order;
+    }
+    return described;
+}
+//# sourceMappingURL=describe.js.map

package/dist/settings/describe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.js","sourceRoot":"","sources":["../../src/settings/describe.ts"],"names":[],"mappings":"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"}

package/dist/settings/duration.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function parseDuration(input: string): number | undefined;
+/**
+ * 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 declare function formatDuration(seconds: number): string;
+//# sourceMappingURL=duration.d.ts.map

package/dist/settings/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../../src/settings/duration.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiB/D;AAKD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAWtD"}

package/dist/settings/duration.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDuration = parseDuration;
+exports.formatDuration = formatDuration;
+/**
+ * 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];
+/**
+ * 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.
+ */
+function parseDuration(input) {
+    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"];
+/**
+ * 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`.
+ */
+function formatDuration(seconds) {
+    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;
+}
+//# sourceMappingURL=duration.js.map

package/dist/settings/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../../src/settings/duration.ts"],"names":[],"mappings":";;AAaA,sCAiBC;AAYD,wCAWC;AArDD;;;GAGG;AACH,MAAM,gBAAgB,GAAG,yDAAyD,CAAC;AACnF,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAU,CAAC;AAEpD;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,KAAa;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACpB,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;QAClC,CAAC;IACF,CAAC;IACD,OAAO,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5D,CAAC;AAED,2DAA2D;AAC3D,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC;AAEpD;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,OAAe;IAC7C,IAAI,SAAS,GAAG,OAAO,CAAC;IACxB,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;QAC5C,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;QAC3B,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YAChB,IAAI,IAAI,GAAG,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,CAAC;IACF,CAAC;IACD,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAClC,CAAC"}

package/dist/settings/field-order.d.ts

@@ -0,0 +1,37 @@
+import type { SettingsDeclaration } from "../settings/define-settings";
+/** One place on a settings screen: a field of its own, or a group with its fields in order. */
+type DisplayEntry = {
+    readonly kind: "field";
+    readonly key: string;
+} | {
+    readonly kind: "group";
+    readonly id: string;
+    readonly fields: readonly string[];
+};
+/** The display order of a declaration. */
+export interface DisplayOrder {
+    /** Every declared group, fields or not, ranked. */
+    readonly groups: readonly string[];
+    /** The screen's places, top to bottom: ungrouped fields and groups holding fields. */
+    readonly entries: readonly DisplayEntry[];
+}
+/**
+ * The order every surface shows a declaration in.
+ *
+ * - Groups rank by their position in `ui.groupOrder` (unlisted ones after
+ *   listed ones), then by their own `order` (none after any), then by where
+ *   they stand in declared order: at their first field, or after every field
+ *   for a group with no field, in declaration order.
+ * - Fields rank within their group, and ungrouped fields among themselves,
+ *   by `ui.order` (none after any), then by declaration order.
+ * - On screen, each place is kept by its kind: a group stands where a group's
+ *   first field is declared and an ungrouped field where an ungrouped field
+ *   is declared, then the ranked groups fill the group places and the ranked
+ *   ungrouped fields the field places. With no hint this is declared order.
+ *
+ * @param declaration - the module's settings declaration; left untouched.
+ * @returns every declared group ranked, and the screen's places in order.
+ */
+export declare function displayOrder(declaration: SettingsDeclaration): DisplayOrder;
+export {};
+//# sourceMappingURL=field-order.d.ts.map

package/dist/settings/field-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-order.d.ts","sourceRoot":"","sources":["../../src/settings/field-order.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAKtE,+FAA+F;AAC/F,KAAK,YAAY,GACd;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEvF,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC1C;AAQD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,mBAAmB,GAAG,YAAY,CA2C3E"}