@dynamic-entity/server 1.14.0

package/index.d.ts

@@ -0,0 +1,180 @@
+import { I as ImportLimits } from './write-template-C2dCEp48.js';
+export { B as BatchInfo, a as ByteSource, D as DEFAULT_LIMITS, b as ImportRunResult, O as OnBatch, P as PreviewSheetOptions, R as ReadSheetOptions, c as RunImportOptions, S as SheetFormat, d as SheetPreview, e as SheetSource, f as TEMPLATE_EXTENSION, g as TEMPLATE_MEDIA_TYPE, T as TemplateFormat, W as WriteTemplateOptions, h as destroySource, i as detectFormat, j as guardRows, l as limitBytes, p as peek, k as previewSheet, r as readSheet, m as resolveLimits, n as runImport, t as toByteStream, w as writeTemplate } from './write-template-C2dCEp48.js';
+import '@dynamic-entity/core';
+import 'node:stream';
+
+/**
+ * errors.ts — one error type, a closed set of codes, and an envelope that says nothing else.
+ *
+ * **Information disclosure is a threat, so the envelope is the guard.** A stack trace tells an
+ * attacker the library versions in use and the filesystem layout of the host; a parser's own
+ * message tells them which parser. So a response carries a machine-readable `code` and a
+ * message this package wrote, and nothing that came from below it. Whatever the real cause
+ * was stays on the server, reachable through `cause` for the consumer's logger.
+ */
+/**
+ * Why a request failed, in a form a client can branch on.
+ *
+ * Closed on purpose: a client that has to match on message text is a client that breaks when
+ * the text improves, and the wire shape is shared with `ngx-dynamic-entity`.
+ */
+type ImportErrorCode = 
+/** No file part in the multipart body. */
+'NO_FILE'
+/** More file parts than `limits.maxFiles`. */
+ | 'TOO_MANY_FILES'
+/** The body exceeded `limits.maxBytes`, or a field exceeded its own bound. */
+ | 'TOO_LARGE'
+/** The bytes are not a format this package reads. Decided by content, not by filename. */
+ | 'UNSUPPORTED_FORMAT'
+/** The bytes claim a format and are not valid in it. */
+ | 'MALFORMED_FILE'
+/** A zip that inflates out of proportion to its size, or has too many entries. */
+ | 'ARCHIVE_REFUSED'
+/** Rows, columns or one cell past the configured bound. */
+ | 'SHEET_TOO_LARGE'
+/** No config is registered under the requested entity. */
+ | 'UNKNOWN_ENTITY'
+/** The `plan` field is missing, is not JSON, or does not describe this config. */
+ | 'INVALID_PLAN'
+/** The request took longer than `limits.totalTimeoutMs`, or stalled past the idle bound. */
+ | 'TIMEOUT'
+/** The consumer's `onImport` threw. Nothing about *why* crosses the wire. */
+ | 'IMPORT_FAILED'
+/** Anything else. Deliberately the least informative code there is. */
+ | 'INTERNAL';
+/**
+ * What a failing route sends.
+ *
+ * `details` is present only for `INVALID_PLAN`, and carries `validateMappingPlan`'s own
+ * problems — those describe the client's own plan against a config the client already has,
+ * so they disclose nothing the caller did not send.
+ */
+interface ImportErrorBody {
+    error: {
+        code: ImportErrorCode;
+        message: string;
+        details?: unknown;
+    };
+}
+declare class ImportError extends Error {
+    readonly code: ImportErrorCode;
+    readonly status: number;
+    readonly details?: unknown;
+    constructor(code: ImportErrorCode, message: string, options?: {
+        cause?: unknown;
+        details?: unknown;
+    });
+}
+/**
+ * Turn anything thrown into a response body.
+ *
+ * An `ImportError` says what it says. **Everything else becomes `INTERNAL` with a fixed
+ * message** — that is the whole point, and the reason this is a function rather than a
+ * `catch` block per route. A parser that throws `ENOENT: open '/srv/app/tmp/…'` must not be
+ * the thing that answers the request.
+ */
+declare function toErrorBody(error: unknown): {
+    status: number;
+    body: ImportErrorBody;
+};
+
+/**
+ * cell-text.ts — how a typed cell is rendered when text is what has to cross the wire.
+ *
+ * Its own module because both the reader and the preview need it, and a second copy would be
+ * a second place for the date rule to be wrong.
+ */
+/**
+ * Render a cell as the text a mapping screen shows.
+ *
+ * It mirrors `coerceTypedCell`'s date rule on purpose. A preview sample crosses the wire as
+ * text and the browser then runs `coerceCell` over that text, so if this rendered a `Date`
+ * with `String()` the preview would show — and the browser would coerce — a different day
+ * from the one the import will store. That is a preview lying about the only thing it exists
+ * to show, and it would be wrong by exactly one day, silently, only for users at a negative
+ * UTC offset. `run-import.spec.ts` asserts the two agree rather than trusting this comment.
+ */
+declare function sampleText(raw: unknown): string;
+
+/**
+ * guard-zip.ts — open the archive ourselves, and hand the parser only what it should see.
+ *
+ * An `.xlsx` is a zip, and a zip is the one upload format where the bytes on the wire say
+ * nothing about the work they cause. Ten kilobytes can inflate to ten gigabytes. `maxBytes`
+ * bounds what arrives and is therefore the wrong guard entirely for this.
+ *
+ * **Why the archive is rebuilt rather than passed through.** Two reasons, and the second was a
+ * surprise:
+ *
+ * 1. exceljs inflates internally and reports nothing while it does, so a limit applied to its
+ *    output is applied after the memory it was protecting has been spent. The inflated size is
+ *    knowable early only here, so this inflates every entry to *measure* it and refuses at the
+ *    byte that crosses a bound.
+ * 2. **exceljs's streaming reader loses entries when a worksheet precedes the shared strings.**
+ *    It defers such a worksheet to a temp file, and the archive's entry stream then ends at
+ *    that entry — `xl/workbook.xml`, which exceljs's own writer puts *last*, never arrives,
+ *    and the reader throws `Cannot read properties of undefined (reading 'sheets')`. Verified
+ *    by replicating its parse loop: sixteen entries became eight, on two runs out of three.
+ *    Reordering the archive so the strings, the relationships and the workbook all precede the
+ *    worksheet avoids the deferral entirely — thirty-two runs, no failures, chunked and whole.
+ *
+ * Rebuilding also means the parser sees **only the parts an import needs**. The theme, the
+ * document properties, the drawings, the printer settings and every worksheet after the first
+ * are dropped rather than parsed, and a part that is never parsed cannot be hostile.
+ *
+ * What this costs is the retained archive, held **compressed** and therefore bounded by
+ * `maxBytes` — ten megabytes by default, against a fifty-thousand-row workbook's few. Entry
+ * data is re-packed exactly as it arrived; nothing is inflated into memory to be kept.
+ */
+
+/**
+ * Walk an archive under every archive-shaped bound, and return the parts an import needs.
+ *
+ * Parsing stops at the first thing that is not a local file header — the central directory —
+ * because nothing after the last entry inflates and there is nothing there to guard.
+ */
+declare function guardZip(source: AsyncIterable<Uint8Array>, limits: ImportLimits): Promise<Buffer>;
+
+/**
+ * xlsx-source.ts — a workbook, one row at a time.
+ *
+ * exceljs's streaming reader does the XML; this file does the three things around it that
+ * decide whether a server-side xlsx import matches a browser one.
+ *
+ * 1. **Every byte goes through `guardZip` first.** exceljs inflates internally and reports
+ *    nothing while it does, so the only place an archive's real size is knowable early is
+ *    before it gets there.
+ * 2. **Blank rows are put back.** exceljs skips them — a sheet with a gap emits row 3 then
+ *    row 5 — and a reader that passed that through would shift every later row number in
+ *    every error message, and disagree with the CSV path about `skipped`. The row numbers a
+ *    user is shown are the ones in their spreadsheet's gutter, so the gaps are synthesised.
+ * 3. **Cells keep their types.** A date cell arrives as a `Date` at UTC midnight and is
+ *    handed on as one, because `coerceCell` reads a typed cell as its type. Stringifying here
+ *    to tidy the signature is the exact defect this feature already fixed once.
+ *
+ * **What this holds, stated rather than discovered:** the archive's wanted parts, kept
+ * **compressed** and therefore bounded by `maxBytes` — ten megabytes by default, against a
+ * fifty-thousand-row workbook's few. That is the cost of `guardZip` rebuilding the archive
+ * rather than forwarding it, and the reasons it does are in that file. Row data is never
+ * accumulated, which is the part that scales with the file.
+ */
+
+/**
+ * Turn one exceljs cell value into the value a record should be built from.
+ *
+ * A formula cell yields its **result**, never its formula: a sheet someone uploaded may
+ * contain anything, and importing the text `=SUM(A1:A9)` into a field is importing a string
+ * the user never saw. An error cell yields its error text, which fails coercion loudly rather
+ * than importing as blank.
+ */
+declare function cellValue(raw: unknown): unknown;
+/**
+ * Rows of the first worksheet, starting at spreadsheet row 1.
+ *
+ * The first worksheet and no other: a mapping plan addresses one sheet's columns, and picking
+ * a second one silently would import a different file from the one the user previewed.
+ */
+declare function xlsxRows(source: AsyncIterable<Uint8Array>, limits: ImportLimits): AsyncGenerator<unknown[]>;
+
+export { ImportError, type ImportErrorBody, type ImportErrorCode, ImportLimits, cellValue, guardZip, sampleText, toErrorBody, xlsxRows };