@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/dist/api/auth-routes-shared.js

@@ -4,6 +4,9 @@ import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
 import { NotFoundError } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/utils.js";
 const log = createFallbackLogger("kumiko");
+// Content is checked where the mail link is built (bundled-features knows the path rules); a bad
+// value must never void the whole body, or the request would silently send no mail.
+const returnToField = z.string().max(2048).optional().catch(undefined);
 // Cross-device try-first handover: an optional tenant-handover grant the signup-request
 // route forwards to the handler for server-side verification and binding —
 // the grant itself never appears anywhere else (URL, mail, log, response).
@@ -15,6 +18,7 @@ export const SignupRequestBody = z.object({
         token: z.string().min(1).max(4096),
     })
         .optional(),
+    returnTo: returnToField,
 });
 // Shape guard for "handler not registered" — the only legitimate reason to
 // fall back to a single-tenant reply on /auth/tenants or /auth/switch-tenant.
@@ -82,4 +86,5 @@ export function registerTokenRequestRoute(opts) {
 // gains optional fields (locale, deviceId, …).
 const RequestTokenBody = z.object({
     email: z.email(),
+    returnTo: returnToField,
 });

package/dist/api/client-error-route.js

@@ -37,8 +37,13 @@ function inMemoryIpRateLimit(clientIpResolver, now) {
                     windows.delete(ip);
             }
         }
-        if (windows.size > MAX_TRACKED_IPS)
-            windows.clear();
+        // Map keeps insertion order and touched IPs are re-inserted, so the front is the least recently
+        // seen; clear() would let an attacker rotating addresses reset every other IP's window.
+        for (const ip of windows.keys()) {
+            if (windows.size <= MAX_TRACKED_IPS)
+                break;
+            windows.delete(ip);
+        }
     }
     return async (c, next) => {
         const ip = clientIpResolver.resolve(clientIpSourceFromHonoContext(c));
@@ -47,6 +52,7 @@ function inMemoryIpRateLimit(clientIpResolver, now) {
         const existing = windows.get(ip);
         const window = existing && nowMs - existing.startedAt < windowMs ? existing : { count: 0, startedAt: nowMs };
         window.count += 1;
+        windows.delete(ip);
         windows.set(ip, window);
         if (window.count > REPORTS_PER_WINDOW) {
             const resetAtMs = window.startedAt + windowMs;
@@ -67,6 +73,8 @@ export function createClientErrorRoute(options) {
     const app = new Hono();
     const logger = createFallbackLogger("client-errors");
     const routePath = `/api${Routes.clientErrors}`;
+    // Always on: the shared limiter fails open when Redis is down, this per-process window is the floor.
+    app.post(Routes.clientErrors, inMemoryIpRateLimit(options.clientIpResolver, options.now ?? Date.now));
     if (options.resolver) {
         app.post(Routes.clientErrors, httpRouteRateLimit({
             resolver: options.resolver,
@@ -76,9 +84,6 @@ export function createClientErrorRoute(options) {
             ...(options.meter && { meter: options.meter }),
         }));
     }
-    else {
-        app.post(Routes.clientErrors, inMemoryIpRateLimit(options.clientIpResolver, options.now ?? Date.now));
-    }
     app.post(Routes.clientErrors, bodyLimit({
         maxSize: MAX_BODY_BYTES,
         onError: (c) => c.json({ error: { code: "payload_too_large" } }, 413),

package/dist/api/entity-read-access.d.ts

@@ -1,2 +1,3 @@
-import type { AccessRule, Registry } from "../engine/types/index.ts";
+import type { AccessRule, OwnershipMap, Registry } from "../engine/types/index.ts";
 export declare function collectEntityReadAccess(registry: Registry): ReadonlyMap<string, readonly AccessRule[]>;
+export declare function collectEntityRowReadMaps(registry: Registry): ReadonlyMap<string, OwnershipMap>;

package/dist/api/entity-read-access.js

@@ -25,3 +25,17 @@ export function collectEntityReadAccess(registry) {
     }
     return rulesByEntity;
 }
+// Entities whose own access.read narrows rows per role (e.g. Driver sees only assigned rows).
+// A signal for such an entity must not name ids to a role that does not read every row.
+export function collectEntityRowReadMaps(registry) {
+    const mapsByEntity = new Map();
+    for (const [entityName, entity] of registry.getAllEntities()) {
+        const readMap = entity.access?.read;
+        if (readMap === undefined || Object.keys(readMap).length === 0)
+            continue;
+        for (const aggregateType of new Set([entityName, toKebabCase(entityName)])) {
+            mapsByEntity.set(aggregateType, readMap);
+        }
+    }
+    return mapsByEntity;
+}

package/dist/api/export/export-cells-reference.d.ts

@@ -0,0 +1,9 @@
+import type { Cell } from "write-excel-file/node";
+import type { ExportRow } from "./export-rows.ts";
+export type ReferenceCellKind = {
+    readonly kind: "reference";
+    readonly labelField: string;
+    readonly multiple: boolean;
+};
+/** Labels come from the list row's eager-loaded `_refs`; a missing target shows its raw id. */
+export declare function referenceCell(cell: ReferenceCellKind, field: string, row: ExportRow): Cell;

package/dist/api/export/export-cells-reference.js

@@ -0,0 +1,21 @@
+import { isPlainObject } from "../../utils/is-plain-object.js";
+function labelOf(ref, labelField) {
+    if (!isPlainObject(ref))
+        return undefined;
+    const label = ref[labelField];
+    return typeof label === "string" ? label : undefined;
+}
+function refsOf(row, field) {
+    const refs = row["_refs"];
+    return isPlainObject(refs) ? refs[field] : undefined;
+}
+/** Labels come from the list row's eager-loaded `_refs`; a missing target shows its raw id. */
+export function referenceCell(cell, field, row) {
+    const ids = cell.multiple && Array.isArray(row[field]) ? row[field] : [row[field]];
+    const ref = refsOf(row, field);
+    const labels = ids.map((id) => {
+        const target = Array.isArray(ref) ? ref.find((r) => isPlainObject(r) && r["id"] === id) : ref;
+        return labelOf(target, cell.labelField) ?? String(id);
+    });
+    return { value: labels.join(", "), type: String };
+}

package/dist/api/export/export-cells.d.ts

@@ -0,0 +1,11 @@
+import type { Cell } from "write-excel-file/node";
+import type { ExportColumn } from "./export-columns.ts";
+import type { ExportRow } from "./export-rows.ts";
+export type Translate = (key: string) => string;
+export type ExportCellContext = {
+    readonly row: ExportRow;
+    readonly translate: Translate;
+    readonly timeZone: string;
+};
+/** Never emits a formula cell and never reinterprets strings: text always stays text. */
+export declare function toExportCell(column: ExportColumn, context: ExportCellContext): Cell;

package/dist/api/export/export-cells.js

@@ -0,0 +1,136 @@
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { referenceCell } from "./export-cells-reference.js";
+const DATE_FORMAT = "yyyy-mm-dd";
+const TIMESTAMP_FORMAT = "yyyy-mm-dd hh:mm";
+const PLAIN_MONEY_FORMAT = "#,##0.00";
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const CURRENCY_CODE = /^[A-Z]{3}$/;
+function isNullish(value) {
+    return value === null || value === undefined;
+}
+function textCell(value) {
+    return { value, type: String };
+}
+function numberCell(value, format) {
+    return { value, type: Number, ...(format !== undefined && { format }) };
+}
+function toFiniteNumber(value) {
+    const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+    return value !== "" && Number.isFinite(n) ? n : undefined;
+}
+function stringify(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "object" && value !== null) {
+        // Temporal values stringify to ISO via toString; plain data goes through JSON.
+        const text = String(value);
+        return text === "[object Object]" ? JSON.stringify(value) : text;
+    }
+    return String(value);
+}
+function fromEpochMillis(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? undefined : value;
+    if (typeof value === "object" && value !== null && "epochMilliseconds" in value) {
+        return fromEpochMillis(new Date(Number(value.epochMilliseconds)));
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        return fromEpochMillis(new Date(value));
+    }
+    return undefined;
+}
+// Date-only values are anchored at UTC midnight, never parsed through the local zone.
+function toUtcDate(value) {
+    const text = typeof value === "string" ? value : isNullish(value) ? "" : stringify(value);
+    if (ISO_DATE.test(text))
+        return fromEpochMillis(new Date(`${text}T00:00:00Z`));
+    return undefined;
+}
+function dateCell(value) {
+    const date = toUtcDate(value) ?? fromEpochMillis(value);
+    return date === undefined
+        ? textCell(stringify(value))
+        : { value: date, type: Date, format: DATE_FORMAT };
+}
+// The sheet has no time zone, so the instant is shifted to the wall clock of `timeZone` and
+// stored as if that wall clock were UTC.
+function timestampCell(value, timeZone) {
+    const date = fromEpochMillis(value);
+    if (date === undefined)
+        return textCell(stringify(value));
+    const wall = Temporal.Instant.fromEpochMilliseconds(date.getTime()).toZonedDateTimeISO(timeZone);
+    const shifted = new Date(Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute, wall.second));
+    return { value: shifted, type: Date, format: TIMESTAMP_FORMAT };
+}
+// `at` is the wall clock in the record's own zone without offset; reading it as UTC keeps the
+// digits the user saw in the list.
+function locatedTimestampCell(value) {
+    const at = typeof value === "object" && value !== null && "at" in value ? String(value.at) : undefined;
+    const date = at === undefined ? undefined : fromEpochMillis(new Date(`${at}Z`));
+    return date === undefined
+        ? textCell(stringify(value))
+        : { value: date, type: Date, format: TIMESTAMP_FORMAT };
+}
+function moneyCell(value) {
+    if (typeof value !== "object" || value === null || !("amount" in value)) {
+        const n = toFiniteNumber(value);
+        return n === undefined ? textCell(stringify(value)) : numberCell(n, PLAIN_MONEY_FORMAT);
+    }
+    const amount = toFiniteNumber(value.amount);
+    if (amount === undefined)
+        return textCell(stringify(value.amount));
+    const currency = "currency" in value ? String(value.currency) : "";
+    const format = CURRENCY_CODE.test(currency)
+        ? `${PLAIN_MONEY_FORMAT} "${currency}"`
+        : PLAIN_MONEY_FORMAT;
+    return numberCell(amount, format);
+}
+function integerCell(value, kind) {
+    const n = toFiniteNumber(value);
+    if (n === undefined)
+        return textCell(stringify(value));
+    // A bigInt beyond 2^53 would lose digits as a spreadsheet number.
+    if (kind === "bigInt" && !Number.isSafeInteger(n))
+        return textCell(stringify(value));
+    return numberCell(n);
+}
+function optionLabel(prefix, raw, translate) {
+    const text = String(raw);
+    const label = translate(`${prefix}${text}`);
+    return label === `${prefix}${text}` ? text : label;
+}
+function autoCell(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return numberCell(value);
+    if (typeof value === "boolean")
+        return { value, type: Boolean };
+    return textCell(stringify(value));
+}
+function optionCell(cell, value, translate) {
+    const values = cell.kind === "multiSelect" && Array.isArray(value) ? value : [value];
+    return textCell(values.map((v) => optionLabel(cell.optionLabelKeyPrefix, v, translate)).join(", "));
+}
+const SIMPLE_CELL_BUILDERS = {
+    number: (value) => integerCell(value, "number"),
+    decimal: (value) => integerCell(value, "decimal"),
+    bigInt: (value) => integerCell(value, "bigInt"),
+    money: (value) => moneyCell(value),
+    date: (value) => dateCell(value),
+    timestamp: timestampCell,
+    locatedTimestamp: (value) => locatedTimestampCell(value),
+    boolean: (value) => typeof value === "boolean" ? { value, type: Boolean } : textCell(stringify(value)),
+    auto: (value) => autoCell(value),
+    text: (value) => textCell(stringify(value)),
+};
+/** Never emits a formula cell and never reinterprets strings: text always stays text. */
+export function toExportCell(column, context) {
+    const { cell, field } = column;
+    const value = context.row[field];
+    if (isNullish(value))
+        return null;
+    if (cell.kind === "reference")
+        return referenceCell(cell, field, context.row);
+    if ("optionLabelKeyPrefix" in cell)
+        return optionCell(cell, value, context.translate);
+    return SIMPLE_CELL_BUILDERS[cell.kind](value, context.timeZone);
+}

package/dist/api/export/export-ciphertext-guard.d.ts

@@ -0,0 +1,2 @@
+import type { SheetData } from "write-excel-file/node";
+export declare function guardSheetAgainstCiphertext(sheet: SheetData, isProduction?: boolean): SheetData;

package/dist/api/export/export-ciphertext-guard.js

@@ -0,0 +1,27 @@
+import { InternalError } from "../../errors/index.js";
+import { createFallbackLogger } from "../../logging/utils.js";
+import { CIPHERTEXT_RE, CIPHERTEXT_REDACT_RE, CIPHERTEXT_REDACTION } from "../pii-leak-guard.js";
+const log = createFallbackLogger("kumiko:export-xlsx");
+// The response guard only scans JSON, so a workbook needs its own check: a ciphertext in a cell
+// means a raw DB read reached the export. Same policy as the guard: loud outside production,
+// redacted and logged in production.
+function guardText(text, isProduction) {
+    if (!CIPHERTEXT_RE.test(text))
+        return text;
+    const detail = "XLSX export contains a PII ciphertext — a raw DB read leaked into the sheet. " +
+        "Decrypt before returning (decryptStoredPii / executor read path).";
+    if (!isProduction)
+        throw new InternalError({ message: detail });
+    log.error(detail);
+    return text.replace(CIPHERTEXT_REDACT_RE, CIPHERTEXT_REDACTION);
+}
+function guardCell(cell, isProduction) {
+    if (typeof cell !== "object" || cell === null || !("value" in cell))
+        return cell;
+    if (typeof cell.value !== "string")
+        return cell;
+    return { ...cell, value: guardText(cell.value, isProduction) };
+}
+export function guardSheetAgainstCiphertext(sheet, isProduction = process.env["NODE_ENV"] === "production") {
+    return sheet.map((row) => row.map((cell) => guardCell(cell, isProduction)));
+}

package/dist/api/export/export-columns.d.ts

@@ -0,0 +1,29 @@
+import type { EntityDefinition, ListColumnSpec, SessionUser } from "../../engine/types/index.ts";
+import type { ReferenceCellKind } from "./export-cells-reference.ts";
+export type SimpleCellKind = "text" | "number" | "decimal" | "bigInt" | "money" | "date" | "timestamp" | "locatedTimestamp" | "boolean" | "auto";
+export type ExportCellKind = {
+    readonly kind: SimpleCellKind;
+} | ReferenceCellKind | {
+    readonly kind: "select" | "multiSelect";
+    /** `<feature>:entity:<entity>:field:<field>:option:` — the option value is appended. */
+    readonly optionLabelKeyPrefix: string;
+};
+export type ExportColumn = {
+    readonly field: string;
+    readonly headerKey: string;
+    readonly headerFallback: string;
+    readonly cell: ExportCellKind;
+};
+export type ExportColumnSource = {
+    readonly featureName: string;
+    readonly columns: readonly ListColumnSpec[];
+    readonly entity: EntityDefinition | undefined;
+    readonly entityName: string | undefined;
+    readonly user: Pick<SessionUser, "roles">;
+};
+/**
+ * Resolves the requested column ids against the screen's declared columns, in client order.
+ * Virtual columns and, on an entityList, encrypted/sensitive fields are dropped without error:
+ * the zip response bypasses the PII-leak guard, so this is the only place that keeps them out.
+ */
+export declare function resolveExportColumns(source: ExportColumnSource, requested: readonly string[]): ExportColumn[];

package/dist/api/export/export-columns.js

@@ -0,0 +1,85 @@
+import { holdsCiphertextOrSecret } from "../../db/entity-field-encryption.js";
+import { userMayReadFieldInBulk } from "../../engine/field-access.js";
+import { normalizeListColumn } from "../../engine/screen-helpers.js";
+import { exportRejection } from "./export-errors.js";
+const PROJECTION_PSEUDO_ENTITY = "__projection__";
+const FIELD_KIND_BY_TYPE = {
+    number: "number",
+    decimal: "decimal",
+    bigInt: "bigInt",
+    money: "money",
+    date: "date",
+    timestamp: "timestamp",
+    locatedTimestamp: "locatedTimestamp",
+    boolean: "boolean",
+};
+function fieldLabelKey(featureName, entityName, field) {
+    return `${featureName}:entity:${entityName}:field:${field}`;
+}
+function entityCellKind(source, entity, field) {
+    const def = entity.fields[field];
+    if (def?.type === "reference") {
+        return {
+            kind: "reference",
+            labelField: def.labelField ?? "id",
+            multiple: def.multiple === true,
+        };
+    }
+    const type = def?.type ?? "text";
+    if (type === "select" || type === "multiSelect") {
+        return {
+            kind: type,
+            optionLabelKeyPrefix: `${fieldLabelKey(source.featureName, source.entityName ?? "", field)}:option:`,
+        };
+    }
+    return { kind: FIELD_KIND_BY_TYPE[type] ?? "text" };
+}
+function projectionCellKind(valueType) {
+    if (valueType === "number" || valueType === "decimal" || valueType === "bigInt") {
+        return { kind: valueType };
+    }
+    return { kind: valueType === "money" ? "money" : "auto" };
+}
+function isExportableOnEntity(source, entity, field, virtual) {
+    if (virtual || !userMayReadFieldInBulk(entity, field, source.user))
+        return false;
+    return !holdsCiphertextOrSecret(entity, field);
+}
+/**
+ * Resolves the requested column ids against the screen's declared columns, in client order.
+ * Virtual columns and, on an entityList, encrypted/sensitive fields are dropped without error:
+ * the zip response bypasses the PII-leak guard, so this is the only place that keeps them out.
+ */
+export function resolveExportColumns(source, requested) {
+    const declared = new Map(source.columns.map((spec) => normalizeListColumn(spec)).map((c) => [c.field, c]));
+    const seen = new Set();
+    const resolved = [];
+    for (const field of requested) {
+        const column = declared.get(field);
+        if (column === undefined) {
+            throw exportRejection("export_unknown_column", "columns", { column: field });
+        }
+        if (seen.has(field))
+            continue;
+        seen.add(field);
+        const virtual = column.virtual === true;
+        const { entity } = source;
+        if (entity !== undefined && !isExportableOnEntity(source, entity, field, virtual))
+            continue;
+        if (entity === undefined && virtual)
+            continue;
+        const cell = entity !== undefined
+            ? entityCellKind(source, entity, field)
+            : projectionCellKind(column.valueType);
+        const headerEntity = source.entityName ?? PROJECTION_PSEUDO_ENTITY;
+        resolved.push({
+            field,
+            headerKey: column.label ?? fieldLabelKey(source.featureName, headerEntity, field),
+            headerFallback: column.label ?? field,
+            cell,
+        });
+    }
+    if (resolved.length === 0)
+        throw exportRejection("export_no_columns", "columns");
+    return resolved;
+}

package/dist/api/export/export-errors.d.ts

@@ -0,0 +1,4 @@
+import { ValidationError } from "../../errors/index.ts";
+export declare const EXPORT_TOO_MANY_I18N_KEY = "kumiko.list.export-too-many";
+export type ExportRejectReason = "export_invalid_request" | "export_unknown_screen" | "export_not_enabled" | "export_unknown_column" | "export_no_columns";
+export declare function exportRejection(reason: ExportRejectReason, path: string, params?: Readonly<Record<string, unknown>>): ValidationError;

package/dist/api/export/export-errors.js

@@ -0,0 +1,14 @@
+import { ValidationError } from "../../errors/index.js";
+export const EXPORT_TOO_MANY_I18N_KEY = "kumiko.list.export-too-many";
+export function exportRejection(reason, path, params) {
+    return new ValidationError({
+        fields: [
+            {
+                path,
+                code: reason,
+                i18nKey: `kumiko.list.${reason.replace(/_/g, "-")}`,
+                ...(params !== undefined && { params }),
+            },
+        ],
+    });
+}

package/dist/api/export/export-route.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from "hono";
+import type { Registry } from "../../engine/types/index.ts";
+import type { Dispatcher } from "../../pipeline/dispatcher.ts";
+export declare function createExportRoutes(dispatcher: Dispatcher, registry: Registry): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/api/export/export-route.js

@@ -0,0 +1,74 @@
+import { Hono } from "hono";
+import * as z from "zod";
+import { toKumikoError } from "../../errors/index.js";
+import { createI18n, DEFAULT_LOCALE } from "../../i18n/index.js";
+import { isValidIanaTimeZone } from "../../time/index.js";
+import { Routes } from "../api-constants.js";
+import { getUser } from "../auth-middleware.js";
+import { requestContext } from "../request-context.js";
+import { assertPayloadDepthAllowed, queryErrorResponse } from "../routes.js";
+import { EXPORT_TOO_MANY_I18N_KEY, exportRejection } from "./export-errors.js";
+import { readExportRows } from "./export-rows.js";
+import { resolveExportPlan } from "./export-screen.js";
+import { writeExportWorkbook } from "./export-xlsx-writer.js";
+const XLSX_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+const MAX_ID_LENGTH = 200;
+const exportBodySchema = z.object({
+    screen: z.string().max(MAX_ID_LENGTH),
+    payload: z.record(z.string(), z.unknown()).default({}),
+    columns: z.array(z.string().max(MAX_ID_LENGTH)).min(1).max(MAX_ID_LENGTH),
+    timeZone: z.string().max(64).optional(),
+});
+// Browser zone first (what the user saw in the list), then the profile zone, else UTC.
+function exportTimeZone(requested, profile) {
+    for (const candidate of [requested, profile]) {
+        if (candidate !== undefined && isValidIanaTimeZone(candidate))
+            return candidate;
+    }
+    return "UTC";
+}
+function downloadFileName(screenShortId, now) {
+    const safeId = screenShortId.replace(/[^A-Za-z0-9_-]/g, "_");
+    return `${safeId}-${now.toISOString().slice(0, 10)}.xlsx`;
+}
+export function createExportRoutes(dispatcher, registry) {
+    const api = new Hono();
+    const i18n = createI18n(registry, { defaultLocale: DEFAULT_LOCALE });
+    api.post(Routes.exportXlsx, async (c) => {
+        const user = getUser(c);
+        try {
+            const parsed = exportBodySchema.safeParse(await c.req.json().catch(() => undefined));
+            if (!parsed.success)
+                throw exportRejection("export_invalid_request", "body");
+            const body = parsed.data;
+            assertPayloadDepthAllowed(body.payload);
+            const plan = resolveExportPlan(registry, body.screen, body.columns, user);
+            const result = await readExportRows(dispatcher, plan, body.payload, user);
+            if (result.tooMany) {
+                return c.json({
+                    error: {
+                        code: "export_too_many_rows",
+                        httpStatus: 413,
+                        message: `export exceeds the limit of ${plan.maxRows} rows; narrow the filter`,
+                        i18nKey: EXPORT_TOO_MANY_I18N_KEY,
+                        details: { maxRows: plan.maxRows },
+                    },
+                }, 413);
+            }
+            const locale = requestContext.get()?.locale ?? DEFAULT_LOCALE;
+            const bytes = await writeExportWorkbook(plan.columns, result.rows, (key) => i18n.t(key, locale), exportTimeZone(body.timeZone, user.timezone));
+            return new Response(bytes, {
+                status: 200,
+                headers: {
+                    "Content-Type": XLSX_CONTENT_TYPE,
+                    "Cache-Control": "no-store",
+                    "Content-Disposition": `attachment; filename="${downloadFileName(plan.screenShortId, new Date())}"`,
+                },
+            });
+        }
+        catch (e) {
+            return queryErrorResponse(c, toKumikoError(e), Routes.exportXlsx);
+        }
+    });
+    return api;
+}

package/dist/api/export/export-rows.d.ts

@@ -0,0 +1,13 @@
+import type { SessionUser } from "../../engine/types/index.ts";
+import type { Dispatcher } from "../../pipeline/dispatcher.ts";
+import type { ExportPlan } from "./export-screen.ts";
+export type ExportRow = Readonly<Record<string, unknown>>;
+export type ExportRowsResult = {
+    readonly tooMany: false;
+    readonly rows: readonly ExportRow[];
+} | {
+    readonly tooMany: true;
+};
+export declare function sanitizeExportPayload(clientPayload: Readonly<Record<string, unknown>>, plan: Pick<ExportPlan, "screenFilter">): Record<string, unknown>;
+/** Reads the whole filtered list page by page; gives up as soon as more than `maxRows` exist. */
+export declare function readExportRows(dispatcher: Pick<Dispatcher, "query">, plan: ExportPlan, clientPayload: Readonly<Record<string, unknown>>, user: SessionUser): Promise<ExportRowsResult>;

package/dist/api/export/export-rows.js

@@ -0,0 +1,62 @@
+import { MAX_LIST_LIMIT } from "../../engine/entity-handlers.js";
+import { InternalError } from "../../errors/index.js";
+import { isPlainObject } from "../../utils/is-plain-object.js";
+// Paging, sizing and aggregation belong to the server here; `filter` is replaced from the screen
+// below, so a client can neither widen the fixed screen filter nor smuggle another one in.
+const CLIENT_CONTROLLED_PAGING_KEYS = [
+    "limit",
+    "offset",
+    "cursor",
+    "totalCount",
+    "aggregate",
+    "includeDeleted",
+    "filter",
+];
+export function sanitizeExportPayload(clientPayload, plan) {
+    const payload = { ...clientPayload };
+    for (const key of CLIENT_CONTROLLED_PAGING_KEYS)
+        delete payload[key];
+    if (plan.screenFilter !== undefined)
+        payload["filter"] = plan.screenFilter;
+    return payload;
+}
+function parsePage(result, queryType) {
+    if (!isPlainObject(result) || !Array.isArray(result["rows"])) {
+        throw new InternalError({
+            message: `export: query ${queryType} did not return a { rows } envelope`,
+        });
+    }
+    const nextCursor = result["nextCursor"];
+    return {
+        rows: result["rows"].filter(isPlainObject),
+        nextCursor: typeof nextCursor === "string" && nextCursor !== "" ? nextCursor : undefined,
+    };
+}
+/** Reads the whole filtered list page by page; gives up as soon as more than `maxRows` exist. */
+export async function readExportRows(dispatcher, plan, clientPayload, user) {
+    const base = sanitizeExportPayload(clientPayload, plan);
+    const rows = [];
+    const seenCursors = new Set();
+    let cursor;
+    for (;;) {
+        const limit = Math.min(MAX_LIST_LIMIT, plan.maxRows + 1 - rows.length);
+        const pagingPayload = cursor !== undefined
+            ? { ...base, limit, cursor }
+            : rows.length > 0
+                ? { ...base, limit, offset: rows.length }
+                : { ...base, limit };
+        const page = parsePage(await dispatcher.query(plan.queryType, pagingPayload, user), plan.queryType);
+        rows.push(...page.rows);
+        if (rows.length > plan.maxRows)
+            return { tooMany: true };
+        // A short or empty page is the end of the list; a repeated cursor would loop forever.
+        if (page.rows.length < limit || page.rows.length === 0)
+            return { tooMany: false, rows };
+        if (page.nextCursor !== undefined) {
+            if (seenCursors.has(page.nextCursor))
+                return { tooMany: false, rows };
+            seenCursors.add(page.nextCursor);
+        }
+        cursor = page.nextCursor;
+    }
+}

package/dist/api/export/export-screen.d.ts

@@ -0,0 +1,12 @@
+import type { Registry, ScreenFilter, SessionUser } from "../../engine/types/index.ts";
+import { type ExportColumn } from "./export-columns.ts";
+export type ExportPlan = {
+    readonly screenShortId: string;
+    readonly queryType: string;
+    readonly screenFilter: ScreenFilter | undefined;
+    readonly columns: readonly ExportColumn[];
+    readonly maxRows: number;
+};
+type ExportScreenRegistry = Pick<Registry, "getScreen" | "getScreenFeature" | "getEntity">;
+export declare function resolveExportPlan(registry: ExportScreenRegistry, screenQn: string, requestedColumns: readonly string[], user: Pick<SessionUser, "roles">): ExportPlan;
+export {};