@yedoma-labs/ysyr-import 0.0.0-stage → 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,176 @@
+/**
+ * Rule for one column. `parse` receives the raw cell text and returns the typed value or throws.
+ * The thrown error's message is reported as a `PARSE` row error.
+ */
+interface ColumnRule<T = unknown, R extends boolean = boolean> {
+  /** Empty cells are a `REQUIRED` error. Optional columns yield `undefined` for empty cells. */
+  readonly required?: R;
+  readonly parse: (raw: string) => T;
+}
+interface ColumnOptions<R extends boolean = boolean> {
+  readonly required?: R;
+}
+/** Column name to rule. */
+type Schema = Readonly<Record<string, ColumnRule<unknown, boolean>>>;
+type ValueOf<R> = R extends {
+  readonly parse: (raw: string) => infer T;
+} ? T : never;
+type IsRequired<R> = R extends {
+  readonly required?: infer Q;
+} ? [NonNullable<Q>] extends [true] ? true : false : false;
+/** Row type produced by a schema: required columns are `T`, optional columns `T | undefined`. */
+type InferRow<S extends Schema> = { -readonly [K in keyof S]: IsRequired<S[K]> extends true ? ValueOf<S[K]> : ValueOf<S[K]> | undefined; };
+/** Trimmed text. */
+export declare function string<const R extends boolean = false>(options?: ColumnOptions<R>): ColumnRule<string, R>;
+/** Whole number within the safe integer range, e.g. `-42` or `+7`. */
+export declare function int<const R extends boolean = false>(options?: ColumnOptions<R>): ColumnRule<number, R>;
+/** Finite decimal number with `.` as decimal separator, e.g. `12`, `-0.5`, `1e3`. */
+export declare function number<const R extends boolean = false>(options?: ColumnOptions<R>): ColumnRule<number, R>;
+/** Accepts `true`, `false`, `1` or `0` (case-insensitive). */
+export declare function boolean<const R extends boolean = false>(options?: ColumnOptions<R>): ColumnRule<boolean, R>;
+/** ISO-8601 calendar date `YYYY-MM-DD`, returned as a `Date` at UTC midnight. */
+export declare function date<const R extends boolean = false>(options?: ColumnOptions<R>): ColumnRule<Date, R>;
+/**
+ * One of the given values, compared case-sensitively after trimming.
+ * Named `enumOf` because `enum` is a reserved word in JavaScript.
+ */
+export declare function enumOf<const V extends readonly string[], const R extends boolean = false>(values: V, options?: ColumnOptions<R>): ColumnRule<V[number], R>;
+/** One data record as produced by the parser. */
+interface CsvRecord {
+  /** Data row number, starting at 1. The header line is not counted. Blank lines are skipped. */
+  readonly row: number;
+  /** Physical line on which the record starts, starting at 1. */
+  readonly line: number;
+  /** Raw field values in column order. */
+  readonly values: readonly string[];
+  /**
+   * Set when the record has broken quoting (unterminated quoted field at end of input, or
+   * characters after a closing quote). `values` then holds a best-effort recovery.
+   */
+  readonly quoteError?: string;
+}
+interface LimitOptions {
+  /** Maximum input size in UTF-8 bytes. Default 10 MiB. */
+  readonly maxBytes?: number;
+  /** Maximum number of data rows. Default 100000. */
+  readonly maxRows?: number;
+  /** Maximum length of a single field in UTF-16 code units. Default 10000. */
+  readonly maxFieldLength?: number;
+}
+interface ParseCsvOptions extends LimitOptions {
+  /** Field delimiter, a single character. Default ",". */
+  readonly delimiter?: string;
+  /** Detect the delimiter among `,` `;` and tab from the first line. Off by default. */
+  readonly autoDetectDelimiter?: boolean;
+  /**
+   * `true` (default): the first record is the header line.
+   * An array: the input has no header line and these are the column names.
+   */
+  readonly header?: true | readonly string[];
+}
+/**
+ * Parses CSV text into data records (RFC 4180 quoting, `\n`, `\r\n` and `\r` line endings,
+ * UTF-8 BOM removed). The header line is consumed and not returned.
+ */
+export declare function parseCsvRecords(text: string, options?: ParseCsvOptions): CsvRecord[];
+/** Whole-file error codes. Row-level problems are reported as `RowError`, never thrown. */
+type ImportErrorCode = "MISSING_COLUMN" | "LIMIT_EXCEEDED" | "INVALID_HEADER";
+/** Input limits that can be exceeded. */
+type LimitName = "maxBytes" | "maxRows" | "maxFieldLength";
+interface ImportErrorDetails {
+  /** MISSING_COLUMN: names of the required columns that are absent from the header. */
+  readonly columns?: readonly string[];
+  /** LIMIT_EXCEEDED: the limit that was exceeded. */
+  readonly limit?: LimitName;
+  /** LIMIT_EXCEEDED: the configured maximum. */
+  readonly max?: number;
+}
+/**
+ * Typed error that aborts the whole import. Thrown for a missing required column,
+ * for exceeded input limits, and for a header line with broken quoting.
+ */
+export declare class ImportError extends Error {
+  readonly code: ImportErrorCode;
+  readonly columns: readonly string[];
+  readonly limit: LimitName | undefined;
+  readonly max: number | undefined;
+  constructor(code: ImportErrorCode, message: string, details?: ImportErrorDetails);
+}
+type RowErrorCode = "REQUIRED" | "PARSE" | "VALIDATION" | "UNKNOWN_COLUMN" | "WRONG_FIELD_COUNT" | "PARSE_QUOTE";
+/**
+ * One problem found in one data row. A row can produce several errors (one per column).
+ * `message` is at most 100 characters and contains no control characters or raw input dumps.
+ */
+interface RowError {
+  /** Data row number, starting at 1. The header line is not counted. */
+  readonly row: number;
+  /** Physical line on which the record starts, starting at 1. */
+  readonly line: number;
+  readonly column?: string;
+  readonly code: RowErrorCode;
+  readonly message: string;
+}
+interface ImportSummary {
+  /** Number of data rows in the input. */
+  readonly total: number;
+  /** Number of accepted rows. */
+  readonly accepted: number;
+  /** Number of distinct rejected rows. The `rejected` list can hold more entries (one per error). */
+  readonly rejected: number;
+}
+/** Per-row result passed to the `onRow` callback, in input order. */
+type RowOutcome<T> = {
+  readonly ok: true;
+  readonly row: number;
+  readonly line: number;
+  readonly value: T;
+} | {
+  readonly ok: false;
+  readonly row: number;
+  readonly line: number;
+  readonly errors: readonly RowError[];
+};
+interface ImportOptions<S extends Schema> extends ParseCsvOptions {
+  /** Column schema. Keys are matched against the header names. */
+  readonly columns: S;
+  /** CSV text to parse. Exactly one of `text` or `records` is required. */
+  readonly text?: string;
+  /**
+   * Records from `parseCsvRecords`. Requires `header` with the column names, because the
+   * records do not carry them.
+   */
+  readonly records?: readonly CsvRecord[];
+  /**
+   * `ignore` (default): unknown columns are skipped.
+   * `reject`: a non-empty value in an unknown column is an `UNKNOWN_COLUMN` row error.
+   */
+  readonly unknownColumns?: "ignore" | "reject";
+  /** Row-level check, run only for rows that passed all column checks. Returns an error message. */
+  readonly validate?: (row: InferRow<S>) => string | undefined;
+  /** Called once per row in input order, after the row has been checked. */
+  readonly onRow?: (outcome: RowOutcome<InferRow<S>>) => void;
+}
+interface ImportResult<T> {
+  readonly accepted: T[];
+  /** All row errors. A row can contribute several entries, one per problem. */
+  readonly rejected: RowError[];
+  readonly summary: ImportSummary;
+}
+/**
+ * Imports CSV rows with partial success. Valid rows go to `accepted`, broken rows are collected
+ * in `rejected` with row number, line number, column and reason.
+ *
+ * Throws `ImportError` for whole-file problems (missing required column, limits exceeded).
+ * Storing the accepted rows is up to the caller.
+ */
+export declare function importRows<const S extends Schema>(options: ImportOptions<S>): ImportResult<InferRow<S>>;
+/**
+ * Renders rejected rows as CSV with the header `line,row,column,code,message` and CRLF line endings.
+ *
+ * CSV injection protection: any text cell starting with `=`, `+`, `-`, `@`, tab or CR is prefixed
+ * with `'`, so spreadsheet applications do not evaluate it as a formula. Cells are quoted per
+ * RFC 4180 when they contain a comma, quote or line break.
+ */
+export declare function toErrorReportCsv(rejected: readonly RowError[]): string;
+export type { ColumnOptions, ColumnRule, CsvRecord, ImportErrorCode, ImportErrorDetails, ImportOptions, ImportResult, ImportSummary, InferRow, LimitName, LimitOptions, ParseCsvOptions, RowError, RowErrorCode, RowOutcome, Schema };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Rule for one column. `parse` receives the raw cell text and returns the typed value or throws.
+ * The thrown error's message is reported as a `PARSE` row error.
+ */
+interface ColumnRule<T = unknown, R extends boolean = boolean> {
+  /** Empty cells are a `REQUIRED` error. Optional columns yield `undefined` for empty cells. */
+  readonly required?: R;
+  readonly parse: (raw: string) => T;
+}
+interface ColumnOptions<R extends boolean = boolean> {
+  readonly required?: R;
+}
+/** Column name to rule. */
+type Schema = Readonly<Record<string, ColumnRule<unknown, boolean>>>;
+type ValueOf<R> = R extends {
+  readonly parse: (raw: string) => infer T;
+} ? T : never;
+type IsRequired<R> = R extends {
+  readonly required?: infer Q;
+} ? [NonNullable<Q>] extends [true] ? true : false : false;
+/** Row type produced by a schema: required columns are `T`, optional columns `T | undefined`. */
+type InferRow<S extends Schema> = { -readonly [K in keyof S]: IsRequired<S[K]> extends true ? ValueOf<S[K]> : ValueOf<S[K]> | undefined; };
+/** Trimmed text. */
+export declare function string<const R extends boolean = false>(options?: ColumnOptions<R>): ColumnRule<string, R>;
+/** Whole number within the safe integer range, e.g. `-42` or `+7`. */
+export declare function int<const R extends boolean = false>(options?: ColumnOptions<R>): ColumnRule<number, R>;
+/** Finite decimal number with `.` as decimal separator, e.g. `12`, `-0.5`, `1e3`. */
+export declare function number<const R extends boolean = false>(options?: ColumnOptions<R>): ColumnRule<number, R>;
+/** Accepts `true`, `false`, `1` or `0` (case-insensitive). */
+export declare function boolean<const R extends boolean = false>(options?: ColumnOptions<R>): ColumnRule<boolean, R>;
+/** ISO-8601 calendar date `YYYY-MM-DD`, returned as a `Date` at UTC midnight. */
+export declare function date<const R extends boolean = false>(options?: ColumnOptions<R>): ColumnRule<Date, R>;
+/**
+ * One of the given values, compared case-sensitively after trimming.
+ * Named `enumOf` because `enum` is a reserved word in JavaScript.
+ */
+export declare function enumOf<const V extends readonly string[], const R extends boolean = false>(values: V, options?: ColumnOptions<R>): ColumnRule<V[number], R>;
+/** One data record as produced by the parser. */
+interface CsvRecord {
+  /** Data row number, starting at 1. The header line is not counted. Blank lines are skipped. */
+  readonly row: number;
+  /** Physical line on which the record starts, starting at 1. */
+  readonly line: number;
+  /** Raw field values in column order. */
+  readonly values: readonly string[];
+  /**
+   * Set when the record has broken quoting (unterminated quoted field at end of input, or
+   * characters after a closing quote). `values` then holds a best-effort recovery.
+   */
+  readonly quoteError?: string;
+}
+interface LimitOptions {
+  /** Maximum input size in UTF-8 bytes. Default 10 MiB. */
+  readonly maxBytes?: number;
+  /** Maximum number of data rows. Default 100000. */
+  readonly maxRows?: number;
+  /** Maximum length of a single field in UTF-16 code units. Default 10000. */
+  readonly maxFieldLength?: number;
+}
+interface ParseCsvOptions extends LimitOptions {
+  /** Field delimiter, a single character. Default ",". */
+  readonly delimiter?: string;
+  /** Detect the delimiter among `,` `;` and tab from the first line. Off by default. */
+  readonly autoDetectDelimiter?: boolean;
+  /**
+   * `true` (default): the first record is the header line.
+   * An array: the input has no header line and these are the column names.
+   */
+  readonly header?: true | readonly string[];
+}
+/**
+ * Parses CSV text into data records (RFC 4180 quoting, `\n`, `\r\n` and `\r` line endings,
+ * UTF-8 BOM removed). The header line is consumed and not returned.
+ */
+export declare function parseCsvRecords(text: string, options?: ParseCsvOptions): CsvRecord[];
+/** Whole-file error codes. Row-level problems are reported as `RowError`, never thrown. */
+type ImportErrorCode = "MISSING_COLUMN" | "LIMIT_EXCEEDED" | "INVALID_HEADER";
+/** Input limits that can be exceeded. */
+type LimitName = "maxBytes" | "maxRows" | "maxFieldLength";
+interface ImportErrorDetails {
+  /** MISSING_COLUMN: names of the required columns that are absent from the header. */
+  readonly columns?: readonly string[];
+  /** LIMIT_EXCEEDED: the limit that was exceeded. */
+  readonly limit?: LimitName;
+  /** LIMIT_EXCEEDED: the configured maximum. */
+  readonly max?: number;
+}
+/**
+ * Typed error that aborts the whole import. Thrown for a missing required column,
+ * for exceeded input limits, and for a header line with broken quoting.
+ */
+export declare class ImportError extends Error {
+  readonly code: ImportErrorCode;
+  readonly columns: readonly string[];
+  readonly limit: LimitName | undefined;
+  readonly max: number | undefined;
+  constructor(code: ImportErrorCode, message: string, details?: ImportErrorDetails);
+}
+type RowErrorCode = "REQUIRED" | "PARSE" | "VALIDATION" | "UNKNOWN_COLUMN" | "WRONG_FIELD_COUNT" | "PARSE_QUOTE";
+/**
+ * One problem found in one data row. A row can produce several errors (one per column).
+ * `message` is at most 100 characters and contains no control characters or raw input dumps.
+ */
+interface RowError {
+  /** Data row number, starting at 1. The header line is not counted. */
+  readonly row: number;
+  /** Physical line on which the record starts, starting at 1. */
+  readonly line: number;
+  readonly column?: string;
+  readonly code: RowErrorCode;
+  readonly message: string;
+}
+interface ImportSummary {
+  /** Number of data rows in the input. */
+  readonly total: number;
+  /** Number of accepted rows. */
+  readonly accepted: number;
+  /** Number of distinct rejected rows. The `rejected` list can hold more entries (one per error). */
+  readonly rejected: number;
+}
+/** Per-row result passed to the `onRow` callback, in input order. */
+type RowOutcome<T> = {
+  readonly ok: true;
+  readonly row: number;
+  readonly line: number;
+  readonly value: T;
+} | {
+  readonly ok: false;
+  readonly row: number;
+  readonly line: number;
+  readonly errors: readonly RowError[];
+};
+interface ImportOptions<S extends Schema> extends ParseCsvOptions {
+  /** Column schema. Keys are matched against the header names. */
+  readonly columns: S;
+  /** CSV text to parse. Exactly one of `text` or `records` is required. */
+  readonly text?: string;
+  /**
+   * Records from `parseCsvRecords`. Requires `header` with the column names, because the
+   * records do not carry them.
+   */
+  readonly records?: readonly CsvRecord[];
+  /**
+   * `ignore` (default): unknown columns are skipped.
+   * `reject`: a non-empty value in an unknown column is an `UNKNOWN_COLUMN` row error.
+   */
+  readonly unknownColumns?: "ignore" | "reject";
+  /** Row-level check, run only for rows that passed all column checks. Returns an error message. */
+  readonly validate?: (row: InferRow<S>) => string | undefined;
+  /** Called once per row in input order, after the row has been checked. */
+  readonly onRow?: (outcome: RowOutcome<InferRow<S>>) => void;
+}
+interface ImportResult<T> {
+  readonly accepted: T[];
+  /** All row errors. A row can contribute several entries, one per problem. */
+  readonly rejected: RowError[];
+  readonly summary: ImportSummary;
+}
+/**
+ * Imports CSV rows with partial success. Valid rows go to `accepted`, broken rows are collected
+ * in `rejected` with row number, line number, column and reason.
+ *
+ * Throws `ImportError` for whole-file problems (missing required column, limits exceeded).
+ * Storing the accepted rows is up to the caller.
+ */
+export declare function importRows<const S extends Schema>(options: ImportOptions<S>): ImportResult<InferRow<S>>;
+/**
+ * Renders rejected rows as CSV with the header `line,row,column,code,message` and CRLF line endings.
+ *
+ * CSV injection protection: any text cell starting with `=`, `+`, `-`, `@`, tab or CR is prefixed
+ * with `'`, so spreadsheet applications do not evaluate it as a formula. Cells are quoted per
+ * RFC 4180 when they contain a comma, quote or line break.
+ */
+export declare function toErrorReportCsv(rejected: readonly RowError[]): string;
+export type { ColumnOptions, ColumnRule, CsvRecord, ImportErrorCode, ImportErrorDetails, ImportOptions, ImportResult, ImportSummary, InferRow, LimitName, LimitOptions, ParseCsvOptions, RowError, RowErrorCode, RowOutcome, Schema };
+//# sourceMappingURL=index.d.ts.map