@aglyn/aglyn 1.0.0-beta.220 → 1.0.0-beta.222

package/src/lib/data-transfer/derive.d.ts

@@ -0,0 +1,246 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { AglynPostalAddress } from '../foundation/definitions/contact.types';
+import type { TransferField } from './resource';
+/** What a parser did to a cell. */
+export type DerivationKind = 'truncated' | 'lowercased' | 'extracted' | 'dateFormat' | 'ambiguousDate' | 'twoDigitYear' | 'excelSerial' | 'timeDropped' | 'timeAssumed' | 'zoneAssumed' | 'epochTime' | 'thousandsSeparator' | 'decimalComma' | 'ambiguousNumber' | 'negativeParentheses' | 'currencySymbol' | 'currencyAssumed' | 'rounded' | 'percentScaled' | 'booleanWord' | 'phoneNormalized' | 'phoneUnnormalized' | 'phoneExtensionDropped' | 'urlScheme' | 'nameSplit' | 'honorificDropped' | 'addressSplit' | 'listSplit' | 'listDeduplicated';
+/** One thing a parser did, in words a person can check. */
+export interface Derivation {
+    kind: DerivationKind;
+    /** The cell as the file had it. */
+    from: string;
+    /** What it became, as text. */
+    to: string;
+    /** The rule in a sentence: "Read as day/month/year". */
+    note: string;
+    /** A guess that could be wrong; the wizard asks for acknowledgement. */
+    flagged: boolean;
+}
+/** Why a cell could not be read. */
+export type DeriveProblemCode = 'invalidEmail' | 'invalidDate' | 'invalidDateTime' | 'invalidNumber' | 'notInteger' | 'invalidCurrency' | 'invalidPercent' | 'invalidBoolean' | 'invalidUrl' | 'invalidJson';
+export interface DeriveProblem {
+    code: DeriveProblemCode;
+    message: string;
+}
+/** A cell read as a field. */
+export interface DerivedValue<T> {
+    /** `null` when blank or unreadable. */
+    value: T | null;
+    /** The cell was empty. */
+    blank: boolean;
+    /** The cell was blank or read; `false` means it is dropped. */
+    ok: boolean;
+    derivations: Derivation[];
+    problem?: DeriveProblem;
+}
+/** A text cell, trimmed; capped at `maxLength` with a flagged record when cut. */
+export declare function deriveText(raw: unknown, options?: {
+    maxLength?: number;
+    multiline?: boolean;
+}): DerivedValue<string>;
+/**
+ * A yes/no cell as a boolean, or `null` when it is neither.
+ *
+ * The affirmatives are the ones consent and checkbox columns actually
+ * carry; the negatives are listed so that an explicit `no` is a `false`
+ * rather than an unreadable value that gets reported as dropped. An empty
+ * cell reads as `false`, which is what a checkbox column means by it.
+ */
+export declare function parseImportFlag(value: unknown): boolean | null;
+/** A boolean cell; a word other than true/false is recorded. */
+export declare function deriveBoolean(raw: unknown): DerivedValue<boolean>;
+/** An address cell: `mailto:` and a display name stripped, lowercased, checked. */
+export declare function deriveEmail(raw: unknown): DerivedValue<string>;
+/**
+ * A phone cell in E.164 through the platform's `normalizePhone`. A number it
+ * cannot normalize confidently is kept as typed and flagged — dropping a
+ * real number is worse than storing it unformatted. An extension is
+ * removed (E.164 has no place for it) and flagged.
+ */
+export declare function derivePhone(raw: unknown, options?: {
+    defaultCountry?: string;
+}): DerivedValue<string>;
+/** A web address cell: `https://` added to a bare domain, host lowercased, checked. */
+export declare function deriveUrl(raw: unknown): DerivedValue<string>;
+/** How an all-number date's day and month are told apart. */
+export interface DateOptions {
+    /** Fixed by the person, or `auto` to read it from the values. */
+    order?: 'auto' | 'mdy' | 'dmy';
+    /** The order an ambiguous date is read in under `auto`; default `mdy`. */
+    preferredOrder?: 'mdy' | 'dmy';
+    /** Read a bare five-digit number as a spreadsheet serial day; default true. */
+    excelSerials?: boolean;
+    /** Two-digit years below this are 20xx, the rest 19xx; default 50. */
+    twoDigitYearPivot?: number;
+}
+/**
+ * A date cell as `YYYY-MM-DD`.
+ *
+ * ISO dates read as they are; `2024/03/05` and `20240305` are read year
+ * first; an all-number date with the year last is read by `order`, and
+ * under `auto` a value whose day and month could be swapped (`03/05/2024`)
+ * is read in `preferredOrder` and flagged; month names read in either
+ * order; a bare serial number is a spreadsheet's date.
+ */
+export declare function deriveDate(raw: unknown, options?: DateOptions): DerivedValue<string>;
+/** How a date and time without a zone is placed. */
+export interface DateTimeOptions extends DateOptions {
+    /** Minutes east of UTC a zone-less time is read in; default 0 (UTC). */
+    offsetMinutes?: number;
+}
+/**
+ * A date-and-time cell as an ISO instant (`…Z`).
+ *
+ * A time with a zone is exact. A time without one is read in
+ * `offsetMinutes` and flagged; a date alone is midnight there. A ten- or
+ * thirteen-digit number is a Unix time in seconds or milliseconds, and a
+ * serial number with a fraction is a spreadsheet's date and time — both
+ * flagged, because a column of numbers could be something else.
+ */
+export declare function deriveDateTime(raw: unknown, options?: DateTimeOptions): DerivedValue<string>;
+/** Which character a number's decimal point is. */
+export interface NumberOptions {
+    /** Fixed by the person, or `auto` to read it from the value; default `auto`. */
+    decimal?: 'auto' | '.' | ',';
+}
+/**
+ * A locale-formatted number: separators read, parentheses as a minus.
+ * `null` when the text is not a number. Every separator decision is
+ * recorded; a lone `1,234` or `1.234` under `auto` could be a thousand or
+ * one-and-a-bit, so it is read as the thousand and flagged.
+ */
+export declare function parseLocaleNumber(text: string, options?: NumberOptions, derivations?: Derivation[]): number | null;
+/** A number cell. */
+export declare function deriveNumber(raw: unknown, options?: NumberOptions): DerivedValue<number>;
+/** A whole-number cell; a fraction is unreadable rather than rounded away. */
+export declare function deriveInteger(raw: unknown, options?: NumberOptions): DerivedValue<number>;
+/** An amount of money in the currency's smallest unit (cents for USD). */
+export interface CurrencyAmount {
+    amountMinor: number;
+    /** ISO 4217, uppercase. */
+    currency: string;
+}
+/** Currencies whose smallest unit is not the hundredth. */
+export declare const CURRENCY_MINOR_UNITS: Readonly<Record<string, number>>;
+/** How many decimal places a currency's smallest unit is. */
+export declare function currencyMinorUnits(currency: string): number;
+/** What currency a cell is read in when it names none. */
+export interface CurrencyOptions extends NumberOptions {
+    /** ISO 4217; default `USD`. */
+    defaultCurrency?: string;
+}
+/**
+ * A money cell as an amount in minor units and a currency. A symbol or a
+ * three-letter code on either side names the currency; `$` alone is the
+ * default currency when that is a dollar, else US dollars; a bare number
+ * is the default currency. More decimals than the currency has are rounded
+ * and flagged.
+ */
+export declare function deriveCurrency(raw: unknown, options?: CurrencyOptions): DerivedValue<CurrencyAmount>;
+/** Whether a percent is stored as `12` (whole) or `0.12` (fraction) for 12%. */
+export interface PercentOptions extends NumberOptions {
+    /** Default `whole`. */
+    scale?: 'whole' | 'fraction';
+}
+/**
+ * A percent cell. `12%` is twelve percent. A number with no `%` between 0
+ * and 1 (`0.12`) is read as a fraction — twelve percent — and flagged,
+ * because a file of fractions and a file of tiny percents look the same.
+ */
+export declare function derivePercent(raw: unknown, options?: PercentOptions): DerivedValue<number>;
+/** Which rule split a full name. */
+export type NameSplitRule = 'lastCommaFirst' | 'lastWord' | 'surnameParticle' | 'singleWord';
+export interface SplitName {
+    first: string | null;
+    last: string | null;
+    rule: NameSplitRule;
+}
+/**
+ * A full name as first and last. "Last, First" splits at the comma; an
+ * honorific is dropped (and recorded); a suffix stays with the last name; a
+ * surname particle (`van`, `de la`) starts the last name; otherwise the
+ * last word is the last name. Every split is recorded with its rule.
+ */
+export declare function splitFullName(raw: unknown): DerivedValue<SplitName>;
+/**
+ * A one-line address as parts, best effort, always flagged: commas split
+ * it; a trailing country name becomes its two-letter code; `TX 78701`,
+ * a bare postal code or a two-letter region is read from the end; the part
+ * before that is the city; the rest is the street.
+ */
+export declare function parseAddressLine(raw: unknown): DerivedValue<AglynPostalAddress>;
+/** How a list cell is split. */
+export interface ListOptions {
+    /** Default `,` `;` `|` and line breaks. */
+    separators?: RegExp;
+    /** Lowercase every item (tags). */
+    lowercase?: boolean;
+    /** The most items kept. */
+    max?: number;
+}
+/**
+ * A list cell as its items: split on `,` `;` `|` or line breaks, trimmed,
+ * duplicates (in any case) dropped keeping the first spelling. An array
+ * (from a JSON file) is taken item by item.
+ */
+export declare function splitTransferList(raw: unknown, options?: ListOptions): DerivedValue<string[]>;
+/** Options for every parser, by kind. */
+export interface DeriveOptions {
+    date?: DateOptions;
+    dateTime?: DateTimeOptions;
+    number?: NumberOptions;
+    currency?: CurrencyOptions;
+    percent?: PercentOptions;
+    phone?: {
+        defaultCountry?: string;
+    };
+    list?: Omit<ListOptions, 'lowercase'>;
+}
+/** A JSON cell parsed; an object or array from a JSON file passes through. */
+export declare function deriveJson(raw: unknown): DerivedValue<unknown>;
+/** A cell read as the field it was mapped to. */
+export declare function deriveTransferCell(field: TransferField, raw: unknown, options?: DeriveOptions): DerivedValue<unknown>;
+/** A derivation, located. */
+export interface FieldDerivation extends Derivation {
+    fieldId: string;
+}
+/** A cell that could not be read, located. */
+export interface FieldProblem extends DeriveProblem {
+    fieldId: string;
+    /** The cell as the file had it. */
+    raw: string;
+}
+/** A row read field by field. */
+export interface DerivedRow {
+    /** Field id → value; `null` for a mapped blank cell; absent for an unmapped or dropped one. */
+    values: Record<string, unknown>;
+    derivations: FieldDerivation[];
+    problems: FieldProblem[];
+}
+/**
+ * A mapped row read as its fields. `cells` is field id → raw cell (from
+ * {@link mapTransferRow} or a JSON object); a field the catalog does not
+ * know is ignored. `fieldOptions` overrides `options` for one field — the
+ * date order a person chose for that column, say.
+ */
+export declare function deriveTransferRow(fields: ReadonlyMap<string, TransferField>, cells: Readonly<Record<string, unknown>>, options?: DeriveOptions, fieldOptions?: Readonly<Record<string, DeriveOptions>>): DerivedRow;
+/**
+ * One line's cells under a column → field mapping, as field id → raw cell.
+ * Every mapped column is present, blank or not, so a blank cell can mean
+ * "clear" when the person chose that.
+ */
+export declare function mapTransferRow(cells: readonly unknown[], mapping: Readonly<Record<number, string | null | undefined>>): Record<string, unknown>;