@elaraai/east 0.0.1-beta.1 → 0.0.1-beta.11

package/dist/src/serialization/csv.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ *
+ * CSV serialization following RFC 4180 (Common Format and MIME Type for CSV Files).
+ * @see https://www.rfc-editor.org/rfc/rfc4180
+ */
+import type { ValueTypeOf, ArrayType } from "../types.js";
+import { StructType, OptionType, StringType, BooleanType, DictType } from "../types.js";
+import type { EastTypeValue } from "../type_of_type.js";
+/**
+ * Configuration options for CSV parsing.
+ * All properties are optional with sensible defaults.
+ */
+export type CsvParseOptions = {
+    /** Field delimiter (default: ",") */
+    delimiter?: string;
+    /** Quote character (default: '"') */
+    quoteChar?: string;
+    /** Escape character (default: '"' for doubled quotes) */
+    escapeChar?: string;
+    /** Line ending - auto-detects if not provided */
+    newline?: string;
+    /** Whether first row is headers (default: true) */
+    hasHeader?: boolean;
+    /** String values to treat as null (default: [""]) */
+    nullStrings?: string[];
+    /** Skip rows that are entirely empty (default: true) */
+    skipEmptyLines?: boolean;
+    /** Trim whitespace from field values (default: false) */
+    trimFields?: boolean;
+    /** Map CSV headers to struct field names */
+    columnMapping?: Map<string, string>;
+    /** Error on schema mismatch (default: false) */
+    strict?: boolean;
+};
+/**
+ * Configuration options for CSV serialization.
+ * All properties are optional with sensible defaults.
+ */
+export type CsvSerializeOptions = {
+    /** Field delimiter (default: ",") */
+    delimiter?: string;
+    /** Quote character (default: '"') */
+    quoteChar?: string;
+    /** Escape character (default: '"') */
+    escapeChar?: string;
+    /** Line ending (default: "\r\n") */
+    newline?: string;
+    /** Include header row (default: true) */
+    includeHeader?: boolean;
+    /** String to output for null/none values (default: "") */
+    nullString?: string;
+    /** Always quote all fields (default: false) */
+    alwaysQuote?: boolean;
+};
+/**
+ * East type for CSV parse configuration.
+ */
+export declare const CsvParseConfigType: StructType<{
+    delimiter: OptionType<StringType>;
+    quoteChar: OptionType<StringType>;
+    escapeChar: OptionType<StringType>;
+    newline: OptionType<StringType>;
+    hasHeader: OptionType<BooleanType>;
+    nullStrings: OptionType<ArrayType<StringType>>;
+    skipEmptyLines: OptionType<BooleanType>;
+    trimFields: OptionType<BooleanType>;
+    columnMapping: OptionType<DictType<StringType, StringType>>;
+    strict: OptionType<BooleanType>;
+}>;
+export type CsvParseConfigType = typeof CsvParseConfigType;
+/**
+ * East type for CSV serialize configuration.
+ */
+export declare const CsvSerializeConfigType: StructType<{
+    delimiter: OptionType<StringType>;
+    quoteChar: OptionType<StringType>;
+    escapeChar: OptionType<StringType>;
+    newline: OptionType<StringType>;
+    includeHeader: OptionType<BooleanType>;
+    nullString: OptionType<StringType>;
+    alwaysQuote: OptionType<BooleanType>;
+}>;
+export type CsvSerializeConfigType = typeof CsvSerializeConfigType;
+/**
+ * Converts TypeScript CsvParseOptions to an East config value.
+ */
+export declare function csvParseOptionsToValue(options?: CsvParseOptions): ValueTypeOf<CsvParseConfigType>;
+/**
+ * Converts TypeScript CsvSerializeOptions to an East config value.
+ */
+export declare function csvSerializeOptionsToValue(options?: CsvSerializeOptions): ValueTypeOf<CsvSerializeConfigType>;
+/**
+ * Extracts resolved options from an East config value, applying defaults.
+ */
+export declare function resolveParseConfig(config: ValueTypeOf<CsvParseConfigType>): Required<Omit<CsvParseOptions, 'columnMapping'>> & {
+    columnMapping: Map<string, string>;
+};
+/**
+ * Extracts resolved options from an East config value, applying defaults.
+ */
+export declare function resolveSerializeConfig(config: ValueTypeOf<CsvSerializeConfigType>): Required<CsvSerializeOptions>;
+/**
+ * Location information for CSV parsing errors.
+ */
+export interface CsvLocation {
+    /** 1-indexed row number (excluding header) */
+    row: number;
+    /** 0-indexed column index */
+    column: number;
+    /** Column header name if available */
+    columnName?: string;
+}
+/**
+ * Error thrown during CSV parsing with location information.
+ */
+export declare class CsvError extends Error {
+    location?: CsvLocation | undefined;
+    constructor(message: string, location?: CsvLocation | undefined);
+}
+/**
+ * Creates a type-specialized CSV decoder for Array<Struct>.
+ *
+ * @param structType - The struct type for each row
+ * @param config - Configuration as East value (from CsvParseConfigType)
+ * @param frozen - Whether to freeze the decoded values
+ */
+export declare function decodeCsvFor(structType: EastTypeValue, config?: ValueTypeOf<CsvParseConfigType>, frozen?: boolean): (blob: Uint8Array) => any;
+export declare function decodeCsvFor<T extends StructType>(structType: T, config?: ValueTypeOf<CsvParseConfigType>, frozen?: boolean): (blob: Uint8Array) => ValueTypeOf<ArrayType<T>>;
+/**
+ * Creates a type-specialized CSV encoder for Array<Struct>.
+ *
+ * @param structType - The struct type for each row
+ * @param config - Configuration as East value (from CsvSerializeConfigType)
+ */
+export declare function encodeCsvFor(structType: EastTypeValue, config?: ValueTypeOf<CsvSerializeConfigType>): (value: any[]) => Uint8Array;
+export declare function encodeCsvFor<T extends StructType>(structType: T, config?: ValueTypeOf<CsvSerializeConfigType>): (value: ValueTypeOf<ArrayType<T>>) => Uint8Array;
+//# sourceMappingURL=csv.d.ts.map

package/dist/src/serialization/csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../../../src/serialization/csv.ts"],"names":[],"mappings":"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"}