@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/shared/appLocale.d.ts

@@ -0,0 +1,36 @@
+/** A language tag as Intl writes it (`es-mx` → `es-MX`); undefined for anything Intl does not take as one. */
+export declare function canonicalLocale(value: unknown): string | undefined;
+/** The resource and column `ui.locale: { column }` names, where it names one. */
+export declare function localeColumn(ui: {
+    localeColumn?: string;
+} | undefined): {
+    resource: string;
+    column: string;
+} | undefined;
+/**
+ * The cookie a reader's own pick of an App's language is kept in (the
+ * language picker, client messages.ts), read as their preference where the
+ * App names no column of their row to keep it in (server readerLocale.ts).
+ * One per App, so two Apps on one server keep two choices.
+ */
+export declare const localeCookieName: (appId: string) => string;
+/**
+ * The tag an `Accept-Language` header asks for among `available` (the locales
+ * an App has a catalog for), by BCP 47 lookup: each range in the header's
+ * order of preference, `es-MX` then `es`; undefined where none is offered.
+ */
+export declare function negotiateLocale(header: string | undefined, available: readonly string[]): string | undefined;
+/**
+ * The one resolution, nearest first: the person's own (`ui.locale: { column }`,
+ * read under their grants, else what they picked in this browser), the tenant's (`branding.allow: 'locale'`), then —
+ * for nobody known, on a public page or the sign-in screen — what the browser
+ * asks for among the App's catalogs, then the App's own (`ui.locale`). Undefined
+ * where nothing names one: the reader's browser then decides the figures.
+ */
+export declare function resolveLocale(sources: {
+    person?: string | undefined;
+    tenant?: string | undefined;
+    /** The `Accept-Language` negotiation, asked only for a reader nobody knows. */
+    browser?: string | undefined;
+    app?: string | undefined;
+}): string | undefined;

package/dist/shared/appLocale.js

@@ -0,0 +1,86 @@
+/**
+ * The reader's locale, one resolution for the whole server (`resolveLocale`):
+ * the words an App's captions are said in and the figures Intl writes. Apart
+ * from appUi.ts for the reason appZone.ts is: what a command host or the
+ * notify path needs must not load every look and theme module into `--mcp`
+ * (test/cli-startup.test.ts). The engine's: the client's language picker
+ * keeps its choice in the cookie named here, in the database browser as in
+ * an App.
+ */
+const canonicalTags = new Map();
+/** A language tag as Intl writes it (`es-mx` → `es-MX`); undefined for anything Intl does not take as one. */
+export function canonicalLocale(value) {
+    if (typeof value !== 'string' || !value.trim() || value.length > 35)
+        return undefined;
+    /* Asked on every payload of the same few tags; bounded, as a tag can be a person's own. */
+    if (canonicalTags.has(value))
+        return canonicalTags.get(value);
+    if (canonicalTags.size >= 64)
+        canonicalTags.clear();
+    let tag;
+    try {
+        [tag] = Intl.getCanonicalLocales(value.trim());
+    }
+    catch {
+        tag = undefined;
+    }
+    canonicalTags.set(value, tag);
+    return tag;
+}
+/** The resource and column `ui.locale: { column }` names, where it names one. */
+export function localeColumn(ui) {
+    if (!ui?.localeColumn)
+        return undefined;
+    const [resource, column] = ui.localeColumn.split('.');
+    return { resource, column };
+}
+/**
+ * The cookie a reader's own pick of an App's language is kept in (the
+ * language picker, client messages.ts), read as their preference where the
+ * App names no column of their row to keep it in (server readerLocale.ts).
+ * One per App, so two Apps on one server keep two choices.
+ */
+export const localeCookieName = (appId) => `mistri-locale-${encodeURIComponent(appId)}`;
+/**
+ * The tag an `Accept-Language` header asks for among `available` (the locales
+ * an App has a catalog for), by BCP 47 lookup: each range in the header's
+ * order of preference, `es-MX` then `es`; undefined where none is offered.
+ */
+export function negotiateLocale(header, available) {
+    if (!header || !available.length)
+        return undefined;
+    const offered = new Map(available.map((tag) => [tag.toLowerCase(), tag]));
+    const ranges = header
+        .split(',')
+        .slice(0, 16)
+        .map((part, index) => {
+        const [range, ...params] = part.trim().split(';');
+        const q = params.map((param) => /^\s*q=([0-9.]+)\s*$/.exec(param)?.[1]).find(Boolean);
+        return { range: range.trim(), q: q === undefined ? 1 : Number(q), index };
+    })
+        .filter(({ range, q }) => range && range !== '*' && q > 0 && Number.isFinite(q))
+        .sort((a, b) => b.q - a.q || a.index - b.index);
+    for (const { range } of ranges) {
+        const tag = canonicalLocale(range);
+        if (!tag)
+            continue;
+        /* The tag the header names is kept where its words are offered, so `es-MX` writes Mexico's figures in Spanish words. */
+        const parts = tag.split('-');
+        for (let n = parts.length; n > 0; n--) {
+            const hit = offered.get(parts.slice(0, n).join('-').toLowerCase());
+            if (hit)
+                return n === parts.length ? hit : tag;
+        }
+    }
+    return undefined;
+}
+/**
+ * The one resolution, nearest first: the person's own (`ui.locale: { column }`,
+ * read under their grants, else what they picked in this browser), the tenant's (`branding.allow: 'locale'`), then —
+ * for nobody known, on a public page or the sign-in screen — what the browser
+ * asks for among the App's catalogs, then the App's own (`ui.locale`). Undefined
+ * where nothing names one: the reader's browser then decides the figures.
+ */
+export function resolveLocale(sources) {
+    return (canonicalLocale(sources.person) ?? canonicalLocale(sources.tenant) ?? canonicalLocale(sources.browser) ?? canonicalLocale(sources.app));
+}

package/dist/shared/appMessages.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A message of an App's catalog, named where a caption goes: `msg('lead.title')`,
+ * `msg('lead.due', { days: 'due_in' })`. The catalogs (`messages/<locale>.ts`)
+ * are read and said on the server (server/app/appMessages.ts): every caption is
+ * a plain string by the time a parser or a browser sees it, in the reader's
+ * language. What is shared is only the shape, so the loader, the check and a
+ * notify rule agree on what a reference is.
+ */
+export interface AppMessageRef {
+    readonly message: string;
+    /** ICU argument → the column path it reads (`{ title: 'thread_id.title' }`). */
+    readonly args?: Readonly<Record<string, string>>;
+}
+/**
+ * The keys whose text a reader reads: a caption, wherever the definition holds
+ * one. Every one takes `msg()` (packages/mistri/schema/app.d.ts, held by test/app-messages.test.ts),
+ * said by the loader however deep it sits, and `mistri messages extract`
+ * lists those still written as literal text. `text` is a caption except where
+ * it names a column: `ui.messages`' `fields`, a composer's `templates`.
+ */
+export declare const CAPTION_KEYS: ReadonlySet<string>;
+/** Whether the value under `key`, in an object found under `parent`, is a caption. */
+export declare const isCaptionKey: (key: string, parent: string | number | undefined) => boolean;
+/** A shape as it is served: each `msg()` it may hold said by the loader, so a caption is a string. */
+export type SaidCaptions<T> = T extends AppMessageRef ? string : T extends readonly (infer Item)[] ? readonly SaidCaptions<Item>[] : T extends object ? {
+    [K in keyof T]: SaidCaptions<T[K]>;
+} : T;
+/** A message's key: dotted words, `lead.title`, `people.payRate`. */
+export declare const MESSAGE_KEY: RegExp;
+/** The arguments the framework supplies itself: a count, a flow notify step's words, a transition's state. */
+export declare const FRAMEWORK_ARGS: readonly ['count', 'message', 'to'];
+/**
+ * Whether a value is what `msg()` made: `{ message }` with a key, and `args`
+ * of names bound to paths. Nothing else in a definition has that shape — a
+ * text rule's or a form's `message` is a sentence, which is never a dotted key
+ * alone in its object.
+ */
+export declare function isMessageRef(raw: unknown): raw is AppMessageRef;
+/**
+ * A caption as a parser reads it: text, trimmed. The loader has said every
+ * `msg()` by now (localizeDefinition); one that reaches a parser was given to
+ * it directly, with no catalog to say it from.
+ */
+export declare function parseCaption(raw: unknown, at: string): string;

package/dist/shared/appMessages.js

@@ -0,0 +1,78 @@
+/**
+ * The keys whose text a reader reads: a caption, wherever the definition holds
+ * one. Every one takes `msg()` (packages/mistri/schema/app.d.ts, held by test/app-messages.test.ts),
+ * said by the loader however deep it sits, and `mistri messages extract`
+ * lists those still written as literal text. `text` is a caption except where
+ * it names a column: `ui.messages`' `fields`, a composer's `templates`.
+ */
+export const CAPTION_KEYS = new Set([
+    'label',
+    'title',
+    'tab',
+    'description',
+    'heading',
+    'tagline',
+    'subtitle',
+    'placeholder',
+    'empty',
+    'hint',
+    'help',
+    'submitLabel',
+    'lead',
+    'next',
+    'skip',
+    'question',
+    'answer',
+    'text',
+    'noun',
+    'unit',
+    'total',
+    'eyebrow',
+    'alt',
+    'message',
+    'note',
+    'before',
+    'after',
+]);
+/** Whether the value under `key`, in an object found under `parent`, is a caption. */
+export const isCaptionKey = (key, parent) => CAPTION_KEYS.has(key) && !(key === 'text' && (parent === 'fields' || parent === 'templates'));
+/** A message's key: dotted words, `lead.title`, `people.payRate`. */
+export const MESSAGE_KEY = /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z][A-Za-z0-9_-]*)+$/;
+/** An ICU argument's name: no dot, so a path is bound explicitly. */
+const MESSAGE_ARG = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MESSAGE_PATH = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+/** The arguments the framework supplies itself: a count, a flow notify step's words, a transition's state. */
+export const FRAMEWORK_ARGS = ['count', 'message', 'to'];
+const plain = (value) => Boolean(value) &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    [Object.prototype, null].includes(Object.getPrototypeOf(value));
+/**
+ * Whether a value is what `msg()` made: `{ message }` with a key, and `args`
+ * of names bound to paths. Nothing else in a definition has that shape — a
+ * text rule's or a form's `message` is a sentence, which is never a dotted key
+ * alone in its object.
+ */
+export function isMessageRef(raw) {
+    if (!plain(raw) || typeof raw.message !== 'string' || !MESSAGE_KEY.test(raw.message))
+        return false;
+    const keys = Object.keys(raw);
+    if (keys.some((key) => key !== 'message' && key !== 'args'))
+        return false;
+    if (raw.args === undefined)
+        return true;
+    return (plain(raw.args) &&
+        Object.entries(raw.args).every(([name, path]) => MESSAGE_ARG.test(name) && typeof path === 'string' && MESSAGE_PATH.test(path)));
+}
+/**
+ * A caption as a parser reads it: text, trimmed. The loader has said every
+ * `msg()` by now (localizeDefinition); one that reaches a parser was given to
+ * it directly, with no catalog to say it from.
+ */
+export function parseCaption(raw, at) {
+    if (isMessageRef(raw))
+        throw new Error(`[message-missing] ${at}: msg('${raw.message}') is said from the App's messages/ catalogs, which only a loaded App has.`);
+    if (typeof raw !== 'string' || !raw.trim())
+        throw new Error(`Invalid caption at ${at}: it must be non-empty text.`);
+    return raw.trim();
+}

package/dist/shared/appNoun.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What a record is called: the resource's `noun` (appModel.ts), said the way
+ * each place needs it — New mid-sentence ("New issue"), a split's detail and
+ * a page as a heading ("Issue"), a list that names nothing as several
+ * ("Issues"). One rule, read by the parsers and the client alike, so a word an
+ * author wrote once is never guessed back out of a label.
+ */
+import { type AppNoun } from './model.js';
+/** The regular plural of a noun an author wrote: "issue" → "issues", "category" → "categories",
+    "address" → "addresses". One no rule makes is written out as `{ one, many }`. */
+export declare function pluralOf(one: string): string;
+/** A noun where a heading starts with it: "issue" → "Issue"; "API key" stays. */
+export declare const headingOf: (noun: string) => string;
+/**
+ * One record's word, mid-sentence: the resource's `noun`, else its table's
+ * name as a person says it ("work_order" → "work order"). Never a list's
+ * label, which may name a layout ("Task calendar") or a workspace ("Inbox"),
+ * and never singularised by rule: a table named in the plural keeps its name
+ * until the resource says its noun.
+ */
+export declare function recordNoun(noun: AppNoun | undefined, tableName: string): string;

package/dist/shared/appNoun.js

@@ -0,0 +1,32 @@
+/**
+ * What a record is called: the resource's `noun` (appModel.ts), said the way
+ * each place needs it — New mid-sentence ("New issue"), a split's detail and
+ * a page as a heading ("Issue"), a list that names nothing as several
+ * ("Issues"). One rule, read by the parsers and the client alike, so a word an
+ * author wrote once is never guessed back out of a label.
+ */
+import { humanName } from './model.js';
+/** The regular plural of a noun an author wrote: "issue" → "issues", "category" → "categories",
+    "address" → "addresses". One no rule makes is written out as `{ one, many }`. */
+export function pluralOf(one) {
+    if (/[^aeiou]y$/i.test(one))
+        return `${one.slice(0, -1)}ies`;
+    if (/(s|x|z|ch|sh)$/i.test(one))
+        return `${one}es`;
+    return `${one}s`;
+}
+/** A noun where a heading starts with it: "issue" → "Issue"; "API key" stays. */
+export const headingOf = (noun) => noun.charAt(0).toUpperCase() + noun.slice(1);
+/**
+ * One record's word, mid-sentence: the resource's `noun`, else its table's
+ * name as a person says it ("work_order" → "work order"). Never a list's
+ * label, which may name a layout ("Task calendar") or a workspace ("Inbox"),
+ * and never singularised by rule: a table named in the plural keeps its name
+ * until the resource says its noun.
+ */
+export function recordNoun(noun, tableName) {
+    if (noun)
+        return noun.one;
+    const said = humanName(tableName) || tableName;
+    return /^[A-Z][a-z]/.test(said) ? said.charAt(0).toLowerCase() + said.slice(1) : said;
+}

package/dist/shared/autoBucket.d.ts

@@ -0,0 +1,98 @@
+export type AutoUnit = 'day' | 'week' | 'month' | 'quarter';
+/** The key of a `by` written `auto <column>`, wherever it stands in the list: its place and its column. */
+export declare function autoKeyOf(by: string | undefined): {
+    index: number;
+    column: string;
+} | null;
+/** The `by` with its `auto` key written as the unit the chart chose, which is the word the grammar reads. */
+export declare function withUnit(by: string, unit: AutoUnit): string;
+/**
+ * The days a section's query asks about on its `over` column — `created_at = last 90 days`, `this month` — or null
+ * where it sets no window the date grammar can bound (the data's own extent is then the span).
+ */
+export declare function spanDaysOf(query: string | undefined, over: string | undefined, now: Date): number | null;
+/** The phrase a query windows its `over` column by — `last 90 days` in `due_on = last 90 days` — or null. */
+export declare function windowPhraseOf(query: string | undefined, over: string | undefined): string | null;
+/** The days between two dates the data holds, both ends counted. Null where either is not a date. */
+export declare function spanDaysBetween(min: unknown, max: unknown): number | null;
+/** The unit a span of this many days is drawn in, before the data is looked at. */
+export declare function unitForSpan(days: number): AutoUnit;
+/**
+ * The unit the read asks the server for. Where the measure adds up again, a day or a week is read as days and
+ * bucketed here: a week crosses a month's edge, so weeks read from the server could not be coarsened into months
+ * without handing a whole week to one of them. Months and quarters nest, so those are read as they are drawn.
+ */
+export declare function readUnit(base: AutoUnit, addsUp: boolean): AutoUnit;
+/** The label of the period a day, month or quarter label falls in, spelled as the server spells it. */
+export declare function bucketKey(key: string, unit: AutoUnit, weekStart?: number): string;
+/**
+ * A trend's points over its window: the periods that held no rows put back as zero, from the window's first period
+ * to today's, and the read periods added up into the unit the span is drawn in. A count of nothing is 0, and a line
+ * drawn through only the days that had rows said a quiet week was a steady one; three busy days of a week drew no
+ * line at all. Only a count or a sum adds up so: any other measure's points are drawn as read, and labels the read
+ * unit does not spell are left as they came.
+ */
+export declare function trendPoints<R extends {
+    key: unknown;
+    value: unknown;
+}>(rows: readonly R[], read: AutoUnit, unit: AutoUnit, measure: string | undefined, window: {
+    start: Date;
+    end: Date;
+} | undefined, now: Date): Array<{
+    key: unknown;
+    value: unknown;
+}>;
+/**
+ * The unit a chart is drawn in: the span's, stepped up while the data is sparse in it.
+ *
+ * `keys` are the labels of the buckets that hold data, as read (days, or months or quarters, per `readUnit`).
+ * `addsUp` is whether the measure can be re-aggregated; without it the span alone decides.
+ */
+export declare function chooseUnit({ spanDays, base: given, keys, addsUp, weekStart, }: {
+    /** The span in days; or the `base` already chosen for it, where the caller has kept one. */
+    spanDays?: number;
+    base?: AutoUnit;
+    keys: readonly string[];
+    addsUp: boolean;
+    weekStart?: number;
+}): {
+    base: AutoUnit;
+    unit: AutoUnit;
+};
+type Combine = 'add' | 'min' | 'max';
+export interface MeasurePlan {
+    /** What to read per bucket, in the grammar's words: each aggregate the measure is made of, once. */
+    reads: string[];
+    /** How the same aggregate of two buckets becomes one of their union. */
+    combine: Combine[];
+    /** The measure's value from its aggregates, null where it has none (a ratio over nothing). */
+    value(terms: readonly (number | null)[]): number | null;
+}
+/**
+ * A measure as the aggregates it is made of, or null where it cannot be added up again: a median, a distinct
+ * count, a `when` count, or words this does not read. `avg x` is `sum x` over `count x`, which can.
+ */
+export declare function planMeasure(measure: string | undefined): MeasurePlan | null;
+/** One bucket as read: its label, the second key's value where the chart has one, and one number per aggregate the plan reads. */
+interface ReadBucket {
+    key: string;
+    series?: string;
+    terms: readonly (number | null)[];
+}
+/** The read buckets cut into the chosen unit, each aggregate added up (or min'd, or max'd) across the ones it takes in. */
+export declare function coarsen(buckets: readonly ReadBucket[], plan: MeasurePlan, unit: AutoUnit, weekStart?: number): Array<{
+    key: string;
+    series?: string;
+    value: number;
+}>;
+/** The most days a window may span before a fixed `day` chart over it is worth a word. */
+export declare const DAY_BARS_ADVISED = 90;
+/**
+ * The days a dashboard window phrase covers, as it would be said ("last 12 months" is 365): the nominal length of a
+ * `last N unit`, else the dates the phrase resolves to, or null where it is not one the date grammar bounds. (A
+ * resolved `last N` runs to tomorrow, a day more than it is called, which a count of bars should not repeat.)
+ */
+export declare function windowDays(phrase: string, now: Date): number | null;
+/** Whether a chart's `by` cuts days: `day created_at`, in any position. */
+export declare const cutsDays: (by: string | undefined) => boolean;
+export {};