nexus-shared 1.1.20 → 2.0.0

package/dist/Helpers/CrudBackend.js

@@ -0,0 +1,119 @@
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export class CrudBackend {
+    /** Reads a whole list: an array, or the rows of a page. */
+    readList(result) {
+        if (Array.isArray(result))
+            return result;
+        return [...this.readPage(result).rows];
+    }
+    /**
+     * Changes an action's answer makes to rows, by key: a mass flag that answers each record's new status. Rows without
+     * an entry take the change the action stands for (a toggled flag). Default: none.
+     */
+    answeredChanges(result, rowKey) {
+        void result;
+        void rowKey;
+        return new Map();
+    }
+    /**
+     * The keys of the records an action changed, when its answer lists them: a mass trash where some records could not
+     * move. `null` when the answer does not say, and every record sent counts as changed. Default `null`.
+     */
+    answeredKeys(result, rowKey) {
+        void result;
+        void rowKey;
+        return null;
+    }
+}
+/** The Nexus record status of a flagged record (`ERecordStatus.Flagged`). */
+export const NEXUS_FLAGGED_STATUS = 15;
+/** The Nexus record status of an active record (`ERecordStatus.Active`). */
+export const NEXUS_ACTIVE_STATUS = 0;
+/**
+ * The Nexus backend: pages as `{ searchKeyword, skipCount, maxCount, sorting, sortType }` answered with
+ * `{ results, totalCount, filterCount }`, newest first unless a column is sorted; mass actions send the ids
+ * (`{ description, accountIds }` for descriptions); a flagged record has `recordStatus` 15, a pinned one `isPinned`.
+ */
+export class NexusCrudBackend extends CrudBackend {
+    pageRequest(query, sortKey) {
+        return {
+            searchKeyword: query.search,
+            skipCount: (query.page - 1) * query.pageSize,
+            maxCount: query.pageSize,
+            sorting: query.sort ? (sortKey ?? query.sort.key) : "creationTime",
+            sortType: query.sort ? query.sort.direction : "desc",
+        };
+    }
+    readPage(result) {
+        if (Array.isArray(result))
+            return { rows: result };
+        if (!isRecord(result))
+            return { rows: [] };
+        const rows = (Array.isArray(result.results) ? result.results : []);
+        const total = Number(result.totalCount);
+        const matches = Number(result.filterCount);
+        return {
+            rows,
+            total: Number.isFinite(total) ? total : rows.length,
+            matches: Number.isFinite(matches) ? matches : Number.isFinite(total) ? total : rows.length,
+        };
+    }
+    massRequest(action, keys, values) {
+        return action === "description" ? { description: values?.description ?? null, accountIds: keys } : keys;
+    }
+    isFlagged(row) {
+        return Number(row.recordStatus) === NEXUS_FLAGGED_STATUS;
+    }
+    withFlag(row, on) {
+        return { ...row, recordStatus: on ? NEXUS_FLAGGED_STATUS : NEXUS_ACTIVE_STATUS };
+    }
+    isPinned(row) {
+        return row.isPinned === true;
+    }
+    withPin(row, on) {
+        return { ...row, isPinned: on };
+    }
+    /** Mass answers list the records they changed, with their new `recordStatus` and `isPinned`. */
+    answeredChanges(result, rowKey) {
+        const changes = new Map();
+        const items = Array.isArray(result) ? result : isRecord(result) && Array.isArray(result.results) ? result.results : [];
+        for (const item of items) {
+            if (!isRecord(item))
+                continue;
+            const key = item[rowKey];
+            if (key === undefined || key === null)
+                continue;
+            const change = {};
+            if ("recordStatus" in item)
+                change.recordStatus = item.recordStatus;
+            if ("isPinned" in item)
+                change.isPinned = item.isPinned;
+            if (Object.keys(change).length)
+                changes.set(String(key), change);
+        }
+        return changes;
+    }
+    /** Mass answers list the records they changed (as records, or as ids); other answers say nothing. */
+    answeredKeys(result, rowKey) {
+        const items = Array.isArray(result) ? result : isRecord(result) && Array.isArray(result.results) ? result.results : null;
+        if (!items)
+            return null;
+        const keys = new Set();
+        for (const item of items) {
+            const key = isRecord(item) ? item[rowKey] : item;
+            if (typeof key === "string" || typeof key === "number")
+                keys.add(String(key));
+        }
+        return keys;
+    }
+}
+let current = null;
+/** Registers the app's backend conventions, once, beside its API modules. */
+export function defineCrudBackend(backend) {
+    current = backend;
+    return backend;
+}
+/** The registered backend conventions, or the Nexus ones. */
+export function getCrudBackend() {
+    return (current ??= new NexusCrudBackend());
+}

package/dist/Helpers/CrudHelpers.d.ts

@@ -0,0 +1,76 @@
+import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
+import type { CrudActionName, CrudEndpoints, CrudMassActionName, CrudMode, CrudRowActionName } from "../Interfaces/CrudInterfaces.ts";
+import type { MessageActionName } from "../Interfaces/MessageInterfaces.ts";
+import type { TablePaging } from "../Interfaces/TableInterfaces.ts";
+/** Every list, in the order the CRUD shows them. */
+export declare const CRUD_MODES: readonly CrudMode[];
+/** The built-in actions on one record, per list, in their menu order. */
+export declare const CRUD_ROW_ACTIONS: Readonly<Record<CrudMode, readonly CrudRowActionName[]>>;
+/** The built-in actions on selected records, per list. */
+export declare const CRUD_MASS_ACTIONS: Readonly<Record<CrudMode, readonly CrudMassActionName[]>>;
+/**
+ * The built-in actions a list offers, in menu order, of those `allowed`. A controller without a trash (`trashless`: no
+ * trash endpoint, or trash not asked for) offers Delete where Move to trash would be. A trash the user may not use never
+ * turns into Delete.
+ */
+export declare function crudRowActions(mode: CrudMode, allowed: (action: CrudRowActionName) => boolean, trashless?: boolean): CrudRowActionName[];
+/** The built-in actions on selected records a list offers, with the same Delete for a controller without a trash. */
+export declare function crudMassActions(mode: CrudMode, allowed: (action: CrudMassActionName) => boolean, trashless?: boolean): CrudMassActionName[];
+/** The endpoint of a list: its full list for tables that page in the browser, its pages for server tables. */
+export declare function crudListEndpoint(api: CrudEndpoints, mode: CrudMode, paging: TablePaging): ApiEndpoint | undefined;
+/** The endpoint of a row action. `view` needs none of its own: it shows the row (and calls `details` when there is one). */
+export declare function crudRowEndpoint(api: CrudEndpoints, action: CrudRowActionName): ApiEndpoint | undefined;
+/** The lists a CRUD can offer: asked for, with an endpoint, and allowed. */
+export declare function availableModes(api: CrudEndpoints, paging: TablePaging, wanted: readonly CrudMode[], can: (endpoint: ApiEndpoint) => boolean): CrudMode[];
+/**
+ * Whether a built-in action can run: asked for, with an endpoint, and allowed. View also works without a `details`
+ * endpoint (it shows the row), but a `details` endpoint the user may not call hides it, as in the old CRUD.
+ */
+export declare function actionAllowed(action: CrudActionName, api: CrudEndpoints, wanted: readonly CrudActionName[], can: (endpoint: ApiEndpoint) => boolean): boolean;
+/** Whether a mass action can run: its row action is wanted, and its mass endpoint exists and is allowed. */
+export declare function massActionAllowed(action: CrudMassActionName, api: CrudEndpoints, wanted: readonly CrudActionName[], can: (endpoint: ApiEndpoint) => boolean): boolean;
+/**
+ * Whether a record leaves the list shown after an action. Archive, trash, restore, recover, delete, and moving back to
+ * the trash take it to another list, and unflagging leaves the flagged list. Pinning and unpinning never do: a pinned
+ * record stays in the list it is in. `markOn` is the record's new flag.
+ */
+export declare function leavesList(action: CrudRowActionName | CrudMassActionName, mode: CrudMode, markOn?: boolean): boolean;
+/** The message builder's action for a built-in action: "Guest archived.", "Unpin 3 guests?" */
+export declare function crudMessageAction(action: CrudRowActionName | CrudMassActionName, markOn?: boolean): MessageActionName;
+/** What every CRUD follows, whatever module it shows. `configureCrud` changes it once, for the whole app. */
+export interface CrudSettings {
+    /**
+     * Most records a user may pin. Default 100. Lowering it never unpins anything: a user over the new limit keeps their
+     * pins and can unpin, and may pin again once they are under it.
+     */
+    maxPins: number;
+}
+/**
+ * Changes what every CRUD follows, once, where the app registers its API modules: `configureCrud({ maxPins: 50 })`.
+ * Values left out keep what they had.
+ */
+export declare function configureCrud(changes: Partial<CrudSettings>): CrudSettings;
+/** The settings every CRUD follows. */
+export declare function getCrudSettings(): CrudSettings;
+/**
+ * How many more records may be pinned: the limit less the records pinned, never below zero. `pinned` is `undefined`
+ * when nothing counts the pins (no `pins` endpoint), and then there is no limit to keep.
+ */
+export declare function pinRoom(pinned: number | undefined, max?: number): number;
+/** Default time a CRUD keeps a list: 5 minutes. */
+export declare const CRUD_CACHE_LIFETIME: number;
+/** Lists kept while a page is open, by key, each for a lifetime. Plain values; nothing is written to storage. */
+export declare class CrudCache<T = unknown> {
+    private entries;
+    readonly lifetime: number;
+    private now;
+    constructor(lifetime?: number, now?: () => number);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    /** Replaces a value, keeping its age, so a changed list does not live longer than the list it came from. */
+    update(key: string, value: T): void;
+    /** Drops every entry whose key passes the test. */
+    drop(test: (key: string) => boolean): void;
+    clear(): void;
+    get size(): number;
+}

package/dist/Helpers/CrudHelpers.js

@@ -0,0 +1,202 @@
+/*
+ * The rules of the CRUD component, with no React: which lists and actions a controller offers, which actions each list
+ * shows, which records leave a list after an action, the settings every CRUD follows (how many records may be pinned),
+ * and the cache of lists kept while the page is open.
+ */
+/** Every list, in the order the CRUD shows them. */
+export const CRUD_MODES = ["normal", "flag", "archive", "trash", "deleted"];
+const ACTIVE_ROW_ACTIONS = ["view", "edit", "flag", "pin", "archive", "trash"];
+const ACTIVE_MASS_ACTIONS = ["flag", "pin", "archive", "description", "trash"];
+/** The built-in actions on one record, per list, in their menu order. */
+export const CRUD_ROW_ACTIONS = {
+    normal: ACTIVE_ROW_ACTIONS,
+    flag: ACTIVE_ROW_ACTIONS,
+    archive: ["view", "restore", "trash"],
+    trash: ["view", "recover", "delete"],
+    deleted: ["view", "trashFromDelete"],
+};
+/** The built-in actions on selected records, per list. */
+export const CRUD_MASS_ACTIONS = {
+    normal: ACTIVE_MASS_ACTIONS,
+    flag: ACTIVE_MASS_ACTIONS,
+    archive: ["restore", "description", "trash"],
+    trash: ["recover", "description", "delete"],
+    deleted: ["trashFromDelete"],
+};
+/**
+ * The built-in actions a list offers, in menu order, of those `allowed`. A controller without a trash (`trashless`: no
+ * trash endpoint, or trash not asked for) offers Delete where Move to trash would be. A trash the user may not use never
+ * turns into Delete.
+ */
+export function crudRowActions(mode, allowed, trashless = false) {
+    const list = [];
+    for (const action of CRUD_ROW_ACTIONS[mode]) {
+        if (action === "trash" && trashless) {
+            if (allowed("delete"))
+                list.push("delete");
+        }
+        else if (allowed(action))
+            list.push(action);
+    }
+    return list;
+}
+/** The built-in actions on selected records a list offers, with the same Delete for a controller without a trash. */
+export function crudMassActions(mode, allowed, trashless = false) {
+    const list = [];
+    for (const action of CRUD_MASS_ACTIONS[mode]) {
+        if (action === "trash" && trashless) {
+            if (allowed("delete"))
+                list.push("delete");
+        }
+        else if (allowed(action))
+            list.push(action);
+    }
+    return list;
+}
+/** The endpoint of a list: its full list for tables that page in the browser, its pages for server tables. */
+export function crudListEndpoint(api, mode, paging) {
+    return paging === "server" ? api.pages?.[mode] : api.lists?.[mode];
+}
+/** The endpoint of a row action. `view` needs none of its own: it shows the row (and calls `details` when there is one). */
+export function crudRowEndpoint(api, action) {
+    if (action === "view")
+        return api.details;
+    if (action === "edit")
+        return api.update;
+    return api[action];
+}
+/** The lists a CRUD can offer: asked for, with an endpoint, and allowed. */
+export function availableModes(api, paging, wanted, can) {
+    return CRUD_MODES.filter(mode => wanted.includes(mode)).filter(mode => {
+        const endpoint = crudListEndpoint(api, mode, paging);
+        return Boolean(endpoint) && can(endpoint);
+    });
+}
+/**
+ * Whether a built-in action can run: asked for, with an endpoint, and allowed. View also works without a `details`
+ * endpoint (it shows the row), but a `details` endpoint the user may not call hides it, as in the old CRUD.
+ */
+export function actionAllowed(action, api, wanted, can) {
+    if (!wanted.includes(action))
+        return false;
+    if (action === "create")
+        return Boolean(api.create) && can(api.create);
+    if (action === "description")
+        return Boolean(api.mass?.description) && can(api.mass.description);
+    if (action === "view")
+        return !api.details || can(api.details);
+    const endpoint = crudRowEndpoint(api, action);
+    return Boolean(endpoint) && can(endpoint);
+}
+/** Whether a mass action can run: its row action is wanted, and its mass endpoint exists and is allowed. */
+export function massActionAllowed(action, api, wanted, can) {
+    if (!wanted.includes(action))
+        return false;
+    const endpoint = api.mass?.[action];
+    return Boolean(endpoint) && can(endpoint);
+}
+/**
+ * Whether a record leaves the list shown after an action. Archive, trash, restore, recover, delete, and moving back to
+ * the trash take it to another list, and unflagging leaves the flagged list. Pinning and unpinning never do: a pinned
+ * record stays in the list it is in. `markOn` is the record's new flag.
+ */
+export function leavesList(action, mode, markOn) {
+    switch (action) {
+        case "archive":
+        case "restore":
+        case "trash":
+        case "recover":
+        case "delete":
+        case "trashFromDelete":
+            return true;
+        case "flag":
+            return mode === "flag" && markOn === false;
+        default:
+            return false;
+    }
+}
+/** The message builder's action for a built-in action: "Guest archived.", "Unpin 3 guests?" */
+export function crudMessageAction(action, markOn) {
+    switch (action) {
+        case "flag":
+            return markOn === false ? "unflag" : "flag";
+        case "pin":
+            return markOn === false ? "unpin" : "pin";
+        case "trashFromDelete":
+            return "trash";
+        case "description":
+            return "update";
+        case "edit":
+        case "view":
+            return "save";
+        default:
+            return action;
+    }
+}
+const DEFAULT_CRUD_SETTINGS = { maxPins: 100 };
+let crudSettings = DEFAULT_CRUD_SETTINGS;
+/**
+ * Changes what every CRUD follows, once, where the app registers its API modules: `configureCrud({ maxPins: 50 })`.
+ * Values left out keep what they had.
+ */
+export function configureCrud(changes) {
+    crudSettings = { ...crudSettings, ...changes };
+    return crudSettings;
+}
+/** The settings every CRUD follows. */
+export function getCrudSettings() {
+    return crudSettings;
+}
+/**
+ * How many more records may be pinned: the limit less the records pinned, never below zero. `pinned` is `undefined`
+ * when nothing counts the pins (no `pins` endpoint), and then there is no limit to keep.
+ */
+export function pinRoom(pinned, max = getCrudSettings().maxPins) {
+    if (pinned === undefined)
+        return Number.POSITIVE_INFINITY;
+    return Math.max(0, max - pinned);
+}
+/** Default time a CRUD keeps a list: 5 minutes. */
+export const CRUD_CACHE_LIFETIME = 5 * 60 * 1000;
+/** Lists kept while a page is open, by key, each for a lifetime. Plain values; nothing is written to storage. */
+export class CrudCache {
+    entries = new Map();
+    lifetime;
+    now;
+    constructor(lifetime = CRUD_CACHE_LIFETIME, now = Date.now) {
+        this.lifetime = lifetime;
+        this.now = now;
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (this.now() - entry.at > this.lifetime) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        if (this.lifetime > 0)
+            this.entries.set(key, { value, at: this.now() });
+    }
+    /** Replaces a value, keeping its age, so a changed list does not live longer than the list it came from. */
+    update(key, value) {
+        const entry = this.entries.get(key);
+        if (entry)
+            entry.value = value;
+    }
+    /** Drops every entry whose key passes the test. */
+    drop(test) {
+        for (const key of [...this.entries.keys()])
+            if (test(key))
+                this.entries.delete(key);
+    }
+    clear() {
+        this.entries.clear();
+    }
+    get size() {
+        return this.entries.size;
+    }
+}

package/dist/Helpers/DateHelpers.d.ts

@@ -0,0 +1,88 @@
+import { type CalendarType, type DateInput, type DateParts, type DatePreferences, type DateRange, type DateRangeInput, type DateScript } from "../Interfaces/DateInterfaces.ts";
+export declare const ISO_DATE_PATTERN: RegExp;
+/** Day number of a Gregorian date: days since 1970-01-01, proleptic, no zone (Howard Hinnant's algorithm). */
+export declare function daysFromCivil(year: number, month: number, day: number): number;
+/** The Gregorian date of a day number. */
+export declare function civilFromDays(dayNumber: number): DateParts;
+export declare const partsToIsoDate: ({ year, month, day }: DateParts) => string;
+/** The parts of an ISO date. The text must be a valid date (`isIsoDate`). */
+export declare function isoDateToParts(iso: string): DateParts;
+export declare const isoDateToDayNumber: (iso: string) => number;
+export declare const dayNumberToIsoDate: (dayNumber: number) => string;
+export declare function gregorianMonthLength(year: number, month: number): number;
+/** Whether text is an ISO date that exists: "2026-02-30" is not. */
+export declare function isIsoDate(text: unknown): text is string;
+/**
+ * Turns anything a date can arrive as into an ISO date, or `null`:
+ * - "2026-09-17" (or "2026-9-7") stays that day;
+ * - an ISO date-time with a zone, "2026-09-16T18:15:00Z", becomes the browser's local date of that instant;
+ * - one without a zone, "2026-09-17T00:00:00", keeps its date part;
+ * - a `Date` is read in local time, like `new Date()` for today.
+ * Text that is not a date, or a day that does not exist, gives `null`.
+ */
+export declare function toIsoDate(input: DateInput): string | null;
+/** A `Date` at midnight of the day: in UTC (the default, for JSON and APIs) or in the browser's local time. */
+export declare function isoDateToDate(iso: string, zone?: "utc" | "local"): Date;
+/** Today's date where the browser is. */
+export declare function todayIsoDate(): string;
+export declare const addDays: (iso: string, days: number) => string;
+/** Negative when `a` is before `b`. ISO dates compare as text. */
+export declare const compareIsoDates: (a: string, b: string) => number;
+/** Days from one date to another: `diffDays("2026-09-17", "2026-09-20")` is 3. */
+export declare const diffDays: (from: string, to: string) => number;
+/** 0 for Sunday to 6 for Saturday. */
+export declare const weekdayOf: (iso: string) => number;
+export declare function clampIsoDate(iso: string, min?: string | null, max?: string | null): string;
+/** The days the calendar covers: Gregorian years 1 to 9999, Bikram Sambat 1975 to 2100 (AD 1918 to 2044). */
+export declare const CALENDAR_RANGE: Record<CalendarType, {
+    readonly min: string;
+    readonly max: string;
+}>;
+export declare function daysInMonth(year: number, month: number, calendar: CalendarType): number;
+/** Whether the parts name a day of the calendar. */
+export declare function isValidParts(parts: DateParts, calendar: CalendarType): boolean;
+/** The day as parts of the calendar, or `null` when the Nepali table does not reach it. */
+export declare function toCalendar(iso: string, calendar: CalendarType): DateParts | null;
+/** The ISO date of parts in the calendar, or `null` when the day does not exist. */
+export declare function fromCalendar(parts: DateParts, calendar: CalendarType): string | null;
+/** The same day of another month, or the month's last day when it is shorter. Years stay inside the calendar. */
+export declare function addMonths(parts: DateParts, months: number, calendar: CalendarType): DateParts;
+/** Nepali dates use Devanagari digits and names only when both the calendar and the script say so. */
+export declare const usesDevanagari: (calendar: CalendarType, script: DateScript | undefined) => boolean;
+export declare function getMonthNames(calendar: CalendarType, script?: DateScript, short?: boolean): readonly string[];
+export declare function getWeekdayNames(calendar: CalendarType, script?: DateScript, length?: "long" | "short" | "min"): readonly string[];
+export declare const toDevanagariDigits: (text: string) => string;
+export declare const toLatinDigits: (text: string) => string;
+/**
+ * Writes a day with a format of tokens: `YYYY` `YY` year, `MMMM` `MMM` month name, `MM` `M` month number, `DD` `D` day,
+ * `dddd` `ddd` weekday name. "YYYY-MM-DD" gives 2026-09-17; "dddd, MMMM D, YYYY" gives Thursday, September 17, 2026.
+ * In the Nepali calendar with the Devanagari script, digits and names are Nepali: २०८३-०६-०१.
+ * Returns "" for an empty or invalid input. A day outside the Nepali table is written as its ISO date.
+ */
+export declare function formatDate(input: DateInput, options?: Partial<DatePreferences>): string;
+/** Writes parts of a calendar with a format. `weekday` (0 = Sunday) is needed only for the `dddd` and `ddd` tokens. */
+export declare function formatDateParts(parts: DateParts, calendar: CalendarType, format: string, script?: DateScript, weekday?: number): string;
+/**
+ * Reads a date the user typed, following the order of the format's tokens: with "DD/MM/YYYY", "17/9/2026" and
+ * "17-09-2026" both give "2026-09-17". Month names are matched by their start in any spelling ("Sep", "September",
+ * "Asoj", "असोज"), weekday names are ignored, Devanagari digits are read, and a four-digit number is the year wherever
+ * it stands. In the Nepali calendar the text is a Nepali date, and the result is still the Gregorian ISO date.
+ * Returns `null` for text that is not a date.
+ */
+export declare function parseDateText(text: string, options?: Partial<DatePreferences>): string | null;
+/** Between the start and the end of a range written as text: an en dash with a space on each side. */
+export declare const DATE_RANGE_SEPARATOR = " \u2013 ";
+/** Reads a range input as two ISO dates, `null` for an end not given. A start after the end is swapped. */
+export declare function toDateRange(input: DateRangeInput): DateRange;
+/**
+ * Writes a range as "start – end" in a calendar and format: "2026-09-17 – 2026-09-24". With only a start it is
+ * "2026-09-17 –", with only an end "– 2026-09-24", and "" when empty.
+ */
+export declare function formatDateRange(input: DateRangeInput, options?: Partial<DatePreferences>): string;
+/**
+ * Reads a range the user typed: two dates, each read like `parseDateText`, around " – ", " - ", "—", "→", or " to ",
+ * e.g. "17/9/2026 - 24/9/2026" or "2026-09-17 to 2026-09-24". A date on its own, or with a separator after it, gives
+ * `[date, null]`; a separator before it gives `[null, date]`; an end before the start is swapped. "" gives an empty
+ * range, and text that is not a range gives `null`.
+ */
+export declare function parseDateRangeText(text: string, options?: Partial<DatePreferences>): DateRange | null;