juxscript 1.1.233 → 1.1.235

package/lib/data/DataPipeline.d.ts

@@ -0,0 +1,165 @@
+import { DataFrame } from '../storage/DataFrame.js';
+export interface PipelineOptions {
+    dbName?: string;
+    storeName?: string;
+}
+export interface FetchOptions {
+    delimiter?: string;
+    hasHeader?: boolean;
+    headerRow?: number;
+    mimeType?: 'csv' | 'tsv' | 'json' | 'auto';
+}
+/**
+ * DataPipeline — Headless, promise-based data loading and transformation.
+ *
+ * Usage:
+ *   const df = await data.fromUrl('https://example.com/report.csv').result();
+ *   const df = await data.fromStorage('patients').result();
+ *   const df = await data.fromJson(apiResponse).result();
+ *
+ *   // Transform and distribute:
+ *   await data.fromUrl(url)
+ *       .transform(df => df.select('name', 'age').filter(r => r.age > 30))
+ *       .into(myTable);
+ *
+ *   await data.fromStorage('encounters')
+ *       .transform(df => df.distinct('provider'))
+ *       .into(myDropdown, { labelKey: 'provider', valueKey: 'provider' });
+ */
+export declare class DataPipeline {
+    private _driver;
+    private _pending;
+    private _transforms;
+    constructor(options?: PipelineOptions);
+    /**
+     * Load from IndexedDB by key
+     */
+    fromStorage(key: string): this;
+    /**
+     * Load from a URL (CSV, TSV, or JSON)
+     */
+    fromUrl(url: string, options?: FetchOptions): this;
+    /**
+     * Load from a File object directly
+     */
+    fromFile(file: File, options?: FetchOptions): this;
+    /**
+     * Load from an array of row objects
+     */
+    fromRows(rows: Record<string, any>[], columns?: string[]): this;
+    /**
+     * Load from column-oriented data
+     */
+    fromColumns(columns: Record<string, any[]>): this;
+    /**
+     * Load from a JSON response (array of objects or column-oriented)
+     */
+    fromJson(json: Record<string, any>[] | Record<string, any[]> | string): this;
+    /**
+     * Load from a FileUpload component's cached storage key.
+     * Requires .cache() enabled on the FileUpload and a file already uploaded.
+     *
+     * Usage:
+     *   await data().fromUpload(myUpload).select('name').into(myTable);
+     */
+    fromUpload(upload: any): this;
+    /**
+     * Start from an existing DataFrame
+     */
+    from(df: DataFrame): this;
+    /**
+     * Apply an arbitrary transform
+     */
+    transform(fn: (df: DataFrame) => DataFrame): this;
+    /**
+     * Select columns
+     */
+    select(...cols: string[]): this;
+    /**
+     * Filter rows
+     */
+    filter(predicate: (row: Record<string, any>, index: number) => boolean): this;
+    /**
+     * Sort by column
+     */
+    sort(column: string, descending?: boolean): this;
+    /**
+     * Take first N rows
+     */
+    head(n?: number): this;
+    /**
+     * Take last N rows
+     */
+    tail(n?: number): this;
+    /**
+     * Rename columns
+     */
+    rename(mapping: Record<string, string>): this;
+    /**
+     * Add a computed column
+     */
+    withColumn(name: string, fn: (row: Record<string, any>, index: number) => any): this;
+    /**
+     * Drop nulls
+     */
+    dropna(columns?: string[]): this;
+    /**
+     * Drop duplicates
+     */
+    dropDuplicates(columns?: string[]): this;
+    /**
+     * Execute the pipeline and return the DataFrame
+     */
+    result(): Promise<DataFrame>;
+    /**
+     * Execute and return rows as plain objects
+     */
+    toRows(): Promise<Record<string, any>[]>;
+    /**
+     * Execute and return a single column as an array
+     */
+    toArray(column: string): Promise<any[]>;
+    /**
+     * Execute and return distinct values from a column
+     */
+    toDistinct(column: string): Promise<any[]>;
+    /**
+     * Execute and push results into a jux component.
+     *
+     * Supported targets:
+     * - Table: sets columns + rows
+     * - Dropdown/Select: sets options from labelKey/valueKey
+     * - List: sets items
+     * - DataFrameComponent: loads data
+     * - Any object with a .rows() or .options() or .items() method
+     */
+    into(target: any, options?: IntoOptions): Promise<DataFrame>;
+    /**
+     * Execute and persist to IndexedDB
+     */
+    store(key: string, metadata?: Record<string, any>): Promise<DataFrame>;
+    private _loadFromUrl;
+    private _loadFromFile;
+    private _detectMimeType;
+}
+export interface IntoOptions {
+    /** Override which columns to use (for Table targets) */
+    columns?: string[];
+    /** Column name → display label mapping */
+    columnLabels?: Record<string, string>;
+    /** Key for option labels (Dropdown/Select/List targets) */
+    labelKey?: string;
+    /** Key for option values (Dropdown/Select targets) */
+    valueKey?: string;
+}
+/**
+ * Factory function — the primary entry point
+ *
+ * Usage:
+ *   import { data } from 'juxscript';
+ *
+ *   const df = await data().fromStorage('patients').select('name', 'dob').result();
+ *   await data().fromUrl(presignedUrl).filter(r => r.status === 'active').into(myTable);
+ */
+export declare function data(options?: PipelineOptions): DataPipeline;
+//# sourceMappingURL=DataPipeline.d.ts.map

package/lib/data/DataPipeline.d.ts.map

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

package/lib/data/DataPipeline.js

@@ -0,0 +1,324 @@
+import { DataFrame } from '../storage/DataFrame.js';
+import { TabularDriver } from '../storage/TabularDriver.js';
+/**
+ * DataPipeline — Headless, promise-based data loading and transformation.
+ *
+ * Usage:
+ *   const df = await data.fromUrl('https://example.com/report.csv').result();
+ *   const df = await data.fromStorage('patients').result();
+ *   const df = await data.fromJson(apiResponse).result();
+ *
+ *   // Transform and distribute:
+ *   await data.fromUrl(url)
+ *       .transform(df => df.select('name', 'age').filter(r => r.age > 30))
+ *       .into(myTable);
+ *
+ *   await data.fromStorage('encounters')
+ *       .transform(df => df.distinct('provider'))
+ *       .into(myDropdown, { labelKey: 'provider', valueKey: 'provider' });
+ */
+export class DataPipeline {
+    constructor(options = {}) {
+        this._pending = null;
+        this._transforms = [];
+        this._driver = new TabularDriver(options.dbName ?? 'jux-dataframes', options.storeName ?? 'frames');
+    }
+    /* ═══════════════════════════════════════════════════
+     * SOURCES
+     * ═══════════════════════════════════════════════════ */
+    /**
+     * Load from IndexedDB by key
+     */
+    fromStorage(key) {
+        this._transforms = [];
+        this._pending = this._driver.loadByName(key).then(df => {
+            if (!df)
+                throw new Error(`No data found in storage with key: "${key}"`);
+            return df;
+        });
+        return this;
+    }
+    /**
+     * Load from a URL (CSV, TSV, or JSON)
+     */
+    fromUrl(url, options = {}) {
+        this._transforms = [];
+        this._pending = this._loadFromUrl(url, options);
+        return this;
+    }
+    /**
+     * Load from a File object directly
+     */
+    fromFile(file, options = {}) {
+        this._transforms = [];
+        this._pending = this._loadFromFile(file, options);
+        return this;
+    }
+    /**
+     * Load from an array of row objects
+     */
+    fromRows(rows, columns) {
+        this._transforms = [];
+        this._pending = Promise.resolve(new DataFrame(rows, { columns }));
+        return this;
+    }
+    /**
+     * Load from column-oriented data
+     */
+    fromColumns(columns) {
+        this._transforms = [];
+        this._pending = Promise.resolve(new DataFrame(columns));
+        return this;
+    }
+    /**
+     * Load from a JSON response (array of objects or column-oriented)
+     */
+    fromJson(json) {
+        this._transforms = [];
+        const parsed = typeof json === 'string' ? JSON.parse(json) : json;
+        this._pending = Promise.resolve(new DataFrame(parsed));
+        return this;
+    }
+    /**
+     * Load from a FileUpload component's cached storage key.
+     * Requires .cache() enabled on the FileUpload and a file already uploaded.
+     *
+     * Usage:
+     *   await data().fromUpload(myUpload).select('name').into(myTable);
+     */
+    fromUpload(upload) {
+        this._transforms = [];
+        const key = upload.storageKey;
+        if (!key) {
+            this._pending = Promise.reject(new Error('FileUpload has no cached storage key. Ensure .cache() is enabled and a file has been uploaded.'));
+        }
+        else {
+            this._pending = this._driver.loadByName(key).then((df) => {
+                if (!df)
+                    throw new Error(`No cached data found for key: "${key}"`);
+                return df;
+            });
+        }
+        return this;
+    }
+    /**
+     * Start from an existing DataFrame
+     */
+    from(df) {
+        this._transforms = [];
+        this._pending = Promise.resolve(df.clone());
+        return this;
+    }
+    /* ═══════════════════════════════════════════════════
+     * TRANSFORMS (chained, lazy — applied on .result())
+     * ═══════════════════════════════════════════════════ */
+    /**
+     * Apply an arbitrary transform
+     */
+    transform(fn) {
+        this._transforms.push(fn);
+        return this;
+    }
+    /**
+     * Select columns
+     */
+    select(...cols) {
+        return this.transform(df => df.select(...cols));
+    }
+    /**
+     * Filter rows
+     */
+    filter(predicate) {
+        return this.transform(df => df.filter(predicate));
+    }
+    /**
+     * Sort by column
+     */
+    sort(column, descending) {
+        return this.transform(df => df.sort(column, descending));
+    }
+    /**
+     * Take first N rows
+     */
+    head(n = 5) {
+        return this.transform(df => df.head(n));
+    }
+    /**
+     * Take last N rows
+     */
+    tail(n = 5) {
+        return this.transform(df => df.tail(n));
+    }
+    /**
+     * Rename columns
+     */
+    rename(mapping) {
+        return this.transform(df => df.rename(mapping));
+    }
+    /**
+     * Add a computed column
+     */
+    withColumn(name, fn) {
+        return this.transform(df => df.withColumn(name, fn));
+    }
+    /**
+     * Drop nulls
+     */
+    dropna(columns) {
+        return this.transform(df => df.dropna(columns));
+    }
+    /**
+     * Drop duplicates
+     */
+    dropDuplicates(columns) {
+        return this.transform(df => df.dropDuplicates(columns));
+    }
+    /* ═══════════════════════════════════════════════════
+     * TERMINAL OPERATIONS
+     * ═══════════════════════════════════════════════════ */
+    /**
+     * Execute the pipeline and return the DataFrame
+     */
+    async result() {
+        if (!this._pending)
+            throw new Error('No data source specified. Call fromStorage(), fromUrl(), etc. first.');
+        let df = await this._pending;
+        for (const fn of this._transforms) {
+            df = fn(df);
+        }
+        return df;
+    }
+    /**
+     * Execute and return rows as plain objects
+     */
+    async toRows() {
+        return (await this.result()).toRows();
+    }
+    /**
+     * Execute and return a single column as an array
+     */
+    async toArray(column) {
+        return (await this.result()).col(column);
+    }
+    /**
+     * Execute and return distinct values from a column
+     */
+    async toDistinct(column) {
+        return (await this.result()).distinct(column);
+    }
+    /**
+     * Execute and push results into a jux component.
+     *
+     * Supported targets:
+     * - Table: sets columns + rows
+     * - Dropdown/Select: sets options from labelKey/valueKey
+     * - List: sets items
+     * - DataFrameComponent: loads data
+     * - Any object with a .rows() or .options() or .items() method
+     */
+    async into(target, options = {}) {
+        const df = await this.result();
+        const rows = df.toRows();
+        // Table-like: has .columns() and .rows()
+        if (typeof target.columns === 'function' && typeof target.rows === 'function') {
+            const columnDefs = (options.columns ?? df.columns).map((col) => {
+                const label = options.columnLabels?.[col] ?? col;
+                return { key: col, label };
+            });
+            target.columns(columnDefs).rows(rows);
+            return df;
+        }
+        // DataFrameComponent: has .fromData()
+        if (typeof target.fromData === 'function') {
+            target.fromData(rows);
+            return df;
+        }
+        // Dropdown/Select-like: has .options()
+        if (typeof target.options === 'function') {
+            const labelKey = options.labelKey ?? df.columns[0];
+            const valueKey = options.valueKey ?? (df.columns[1] ?? df.columns[0]);
+            const opts = rows.map(row => ({
+                label: String(row[labelKey] ?? ''),
+                value: row[valueKey]
+            }));
+            target.options(opts);
+            return df;
+        }
+        // List-like: has .items()
+        if (typeof target.items === 'function') {
+            const key = options.labelKey ?? df.columns[0];
+            target.items(rows.map(row => String(row[key] ?? '')));
+            return df;
+        }
+        throw new Error(`Target does not have a recognized API (.columns/.rows, .fromData, .options, or .items)`);
+    }
+    /**
+     * Execute and persist to IndexedDB
+     */
+    async store(key, metadata) {
+        const df = await this.result();
+        await this._driver.store(key, df, metadata);
+        return df;
+    }
+    /* ═══════════════════════════════════════════════════
+     * PRIVATE
+     * ═══════════════════════════════════════════════════ */
+    async _loadFromUrl(url, options) {
+        const mimeType = options.mimeType ?? this._detectMimeType(url);
+        if (mimeType === 'json') {
+            const response = await fetch(url);
+            if (!response.ok)
+                throw new Error(`Fetch failed: ${response.status} ${response.statusText}`);
+            const json = await response.json();
+            return new DataFrame(json);
+        }
+        // CSV/TSV — delegate to driver
+        return this._driver.fetch(url, {
+            autoDetectDelimiter: !options.delimiter,
+            delimiter: options.delimiter,
+            hasHeader: options.hasHeader ?? true,
+            headerRow: options.headerRow
+        });
+    }
+    async _loadFromFile(file, options) {
+        const isExcel = /\.(xlsx?|xls)$/i.test(file.name);
+        if (isExcel) {
+            const sheets = await this._driver.streamFileMultiSheet(file, {
+                headerRow: options.headerRow
+            });
+            const sheetNames = Object.keys(sheets);
+            if (sheetNames.length === 0)
+                throw new Error('No data found in file');
+            return sheets[sheetNames[0]];
+        }
+        const text = await file.text();
+        return this._driver.parseCSV(text, {
+            autoDetectDelimiter: !options.delimiter,
+            delimiter: options.delimiter,
+            hasHeader: options.hasHeader ?? true,
+            headerRow: options.headerRow
+        });
+    }
+    _detectMimeType(url) {
+        const lower = url.toLowerCase().split('?')[0];
+        if (lower.endsWith('.json'))
+            return 'json';
+        if (lower.endsWith('.tsv'))
+            return 'tsv';
+        if (lower.endsWith('.csv'))
+            return 'csv';
+        return 'auto';
+    }
+}
+/**
+ * Factory function — the primary entry point
+ *
+ * Usage:
+ *   import { data } from 'juxscript';
+ *
+ *   const df = await data().fromStorage('patients').select('name', 'dob').result();
+ *   await data().fromUrl(presignedUrl).filter(r => r.status === 'active').into(myTable);
+ */
+export function data(options = {}) {
+    return new DataPipeline(options);
+}