@walkthru-earth/objex 0.1.0

package/dist/utils/column-types.d.ts

@@ -0,0 +1,5 @@
+export type TypeCategory = 'number' | 'string' | 'date' | 'boolean' | 'geo' | 'binary' | 'json' | 'other';
+export declare function classifyType(duckdbType: string): TypeCategory;
+export declare function typeColor(category: TypeCategory): string;
+export declare function typeBadgeClass(category: TypeCategory): string;
+export declare function typeLabel(category: TypeCategory): string;

package/dist/utils/column-types.js

@@ -0,0 +1,137 @@
+const NUMBER_TYPES = [
+    'TINYINT',
+    'SMALLINT',
+    'INTEGER',
+    'BIGINT',
+    'HUGEINT',
+    'UTINYINT',
+    'USMALLINT',
+    'UINTEGER',
+    'UBIGINT',
+    'FLOAT',
+    'DOUBLE',
+    'DECIMAL',
+    'NUMERIC',
+    'REAL',
+    'INT',
+    'INT1',
+    'INT2',
+    'INT4',
+    'INT8',
+    'SIGNED',
+    'SHORT',
+    'LONG'
+];
+const STRING_TYPES = ['VARCHAR', 'TEXT', 'STRING', 'CHAR', 'BPCHAR', 'NAME', 'UUID', 'ENUM'];
+const DATE_TYPES = [
+    'DATE',
+    'TIME',
+    'TIMESTAMP',
+    'TIMESTAMP_S',
+    'TIMESTAMP_MS',
+    'TIMESTAMP_NS',
+    'TIMESTAMP WITH TIME ZONE',
+    'TIMESTAMPTZ',
+    'INTERVAL',
+    'TIMESTAMP_TZ'
+];
+const BOOLEAN_TYPES = ['BOOLEAN', 'BOOL', 'LOGICAL'];
+const GEO_TYPES = [
+    'GEOMETRY',
+    'POINT',
+    'LINESTRING',
+    'POLYGON',
+    'MULTIPOINT',
+    'MULTILINESTRING',
+    'MULTIPOLYGON',
+    'GEOMETRYCOLLECTION',
+    'WKB_GEOMETRY'
+];
+const BINARY_TYPES = ['BLOB', 'BYTEA', 'BINARY', 'VARBINARY'];
+const JSON_TYPES = ['JSON', 'JSONB'];
+export function classifyType(duckdbType) {
+    const upper = duckdbType.toUpperCase().trim();
+    // Handle parameterized types like DECIMAL(18,3), VARCHAR(100)
+    const base = upper.replace(/\(.*\)/, '').trim();
+    if (NUMBER_TYPES.includes(base))
+        return 'number';
+    if (STRING_TYPES.includes(base))
+        return 'string';
+    if (DATE_TYPES.includes(base))
+        return 'date';
+    if (BOOLEAN_TYPES.includes(base))
+        return 'boolean';
+    if (GEO_TYPES.includes(base))
+        return 'geo';
+    if (BINARY_TYPES.includes(base))
+        return 'binary';
+    if (JSON_TYPES.includes(base))
+        return 'json';
+    // Compound types
+    if (base.startsWith('STRUCT') || base.startsWith('MAP') || base.startsWith('UNION'))
+        return 'json';
+    if (base.endsWith('[]') || base.startsWith('LIST'))
+        return 'json';
+    // Fallback checks
+    if (upper.includes('INT') ||
+        upper.includes('FLOAT') ||
+        upper.includes('DOUBLE') ||
+        upper.includes('DECIMAL') ||
+        upper.includes('NUMERIC'))
+        return 'number';
+    if (upper.includes('CHAR') || upper.includes('TEXT') || upper.includes('STRING'))
+        return 'string';
+    if (upper.includes('TIME') || upper.includes('DATE'))
+        return 'date';
+    if (upper.includes('BOOL'))
+        return 'boolean';
+    if (upper.includes('GEOMETRY') || upper.includes('GEO') || upper.includes('WKB'))
+        return 'geo';
+    if (upper.includes('BLOB') || upper.includes('BINARY'))
+        return 'binary';
+    if (upper.includes('JSON') ||
+        upper.includes('STRUCT') ||
+        upper.includes('MAP') ||
+        upper.includes('LIST'))
+        return 'json';
+    return 'other';
+}
+const TYPE_COLORS = {
+    number: 'text-blue-500',
+    string: 'text-green-500',
+    date: 'text-amber-500',
+    boolean: 'text-purple-500',
+    geo: 'text-teal-500',
+    binary: 'text-zinc-500',
+    json: 'text-orange-500',
+    other: 'text-zinc-400'
+};
+const TYPE_BADGE_CLASSES = {
+    number: 'bg-blue-500/10 text-blue-600 dark:text-blue-400 border-blue-500/20',
+    string: 'bg-green-500/10 text-green-600 dark:text-green-400 border-green-500/20',
+    date: 'bg-amber-500/10 text-amber-600 dark:text-amber-400 border-amber-500/20',
+    boolean: 'bg-purple-500/10 text-purple-600 dark:text-purple-400 border-purple-500/20',
+    geo: 'bg-teal-500/10 text-teal-600 dark:text-teal-400 border-teal-500/20',
+    binary: 'bg-zinc-500/10 text-zinc-600 dark:text-zinc-400 border-zinc-500/20',
+    json: 'bg-orange-500/10 text-orange-600 dark:text-orange-400 border-orange-500/20',
+    other: 'bg-zinc-500/10 text-zinc-500 dark:text-zinc-400 border-zinc-500/20'
+};
+const TYPE_LABELS = {
+    number: '#',
+    string: 'Aa',
+    date: 'dt',
+    boolean: 'T/F',
+    geo: 'geo',
+    binary: '01',
+    json: '{}',
+    other: '?'
+};
+export function typeColor(category) {
+    return TYPE_COLORS[category];
+}
+export function typeBadgeClass(category) {
+    return TYPE_BADGE_CLASSES[category];
+}
+export function typeLabel(category) {
+    return TYPE_LABELS[category];
+}

package/dist/utils/deck.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared deck.gl utilities for map viewers.
+ *
+ * - GeoJSON overlay: used by FlatGeobufViewer
+ * - GeoArrow overlay: used by GeoParquetMapViewer (zero-copy DuckDB → GPU pipeline)
+ */
+import type { GeoArrowResult } from './geoarrow.js';
+/**
+ * Create an onHover callback that toggles the cursor on the MapLibre canvas.
+ * With `interleaved: false`, deck.gl's own canvas has pointer-events: none,
+ * so getCursor on MapboxOverlay has no visible effect — we must set cursor
+ * directly on the MapLibre map canvas instead.
+ */
+export declare function hoverCursor(map: {
+    getCanvas: () => HTMLElement;
+}): (info: {
+    picked?: boolean;
+}) => void;
+type RGBA = [number, number, number, number];
+/** Distinct fill/line colors per geometry type. */
+export declare const GEOMETRY_COLORS: Record<string, {
+    fill: RGBA;
+    line: RGBA;
+}>;
+/**
+ * GeoJSON accessor: return fill color based on feature geometry type.
+ * Used as deck.gl accessor function for getFillColor / getLineColor.
+ */
+export declare function geojsonFillColor(feature: any): RGBA;
+export declare function geojsonLineColor(feature: any): RGBA;
+/** Lazy-load deck.gl modules (MapboxOverlay + GeoJsonLayer). */
+export declare function loadDeckModules(): Promise<{
+    MapboxOverlay: typeof import("@deck.gl/mapbox").MapboxOverlay;
+    GeoJsonLayer: typeof import("@deck.gl/layers").GeoJsonLayer;
+}>;
+export interface DeckOverlayOptions {
+    layerId: string;
+    data: GeoJSON.FeatureCollection;
+    /** Called with properties and the full GeoJSON Feature (for selection highlight). */
+    onClick?: (properties: Record<string, any>, feature: GeoJSON.Feature) => void;
+    /** Layer-level onHover — use hoverCursor(map) to toggle pointer on MapLibre canvas. */
+    onHover?: (info: {
+        picked?: boolean;
+    }) => void;
+}
+/**
+ * Create a MapboxOverlay with a single GeoJsonLayer.
+ * Colors are assigned per-feature based on geometry type.
+ */
+export declare function createDeckOverlay(modules: {
+    MapboxOverlay: any;
+    GeoJsonLayer: any;
+}, options: DeckOverlayOptions): any;
+/** Lazy-load GeoArrow deck.gl layers + MapboxOverlay + GeoJsonLayer (for selection). */
+export declare function loadGeoArrowModules(): Promise<{
+    GeoArrowArcLayer: typeof import("@geoarrow/deck.gl-layers").GeoArrowArcLayer;
+    GeoArrowColumnLayer: typeof import("@geoarrow/deck.gl-layers").GeoArrowColumnLayer;
+    _GeoArrowH3HexagonLayer: typeof import("@geoarrow/deck.gl-layers")._GeoArrowH3HexagonLayer;
+    GeoArrowHeatmapLayer: typeof import("@geoarrow/deck.gl-layers").GeoArrowHeatmapLayer;
+    GeoArrowPathLayer: typeof import("@geoarrow/deck.gl-layers").GeoArrowPathLayer;
+    GeoArrowPointCloudLayer: typeof import("@geoarrow/deck.gl-layers").GeoArrowPointCloudLayer;
+    GeoArrowPolygonLayer: typeof import("@geoarrow/deck.gl-layers").GeoArrowPolygonLayer;
+    GeoArrowScatterplotLayer: typeof import("@geoarrow/deck.gl-layers").GeoArrowScatterplotLayer;
+    GeoArrowSolidPolygonLayer: typeof import("@geoarrow/deck.gl-layers").GeoArrowSolidPolygonLayer;
+    _GeoArrowTextLayer: typeof import("@geoarrow/deck.gl-layers")._GeoArrowTextLayer;
+    GeoArrowTripsLayer: typeof import("@geoarrow/deck.gl-layers").GeoArrowTripsLayer;
+    MapboxOverlay: typeof import("@deck.gl/mapbox").MapboxOverlay;
+    GeoJsonLayer: typeof import("@deck.gl/layers").GeoJsonLayer;
+}>;
+export interface GeoArrowOverlayOptions {
+    layerId: string;
+    geoArrowResults: GeoArrowResult[];
+    /** Called with properties and the original WKB array index (for selection highlight). */
+    onClick?: (properties: Record<string, any>, sourceIndex: number) => void;
+    /** Layer-level onHover — use hoverCursor(map) to toggle pointer on MapLibre canvas. */
+    onHover?: (info: {
+        picked?: boolean;
+    }) => void;
+}
+/**
+ * Create MapboxOverlay with GeoArrow layers — one per geometry type group.
+ * Returns both the overlay and the data layers array (for adding selection layers later).
+ */
+export declare function createGeoArrowOverlay(modules: Record<string, any>, options: GeoArrowOverlayOptions): {
+    overlay: any;
+    layers: any[];
+};
+/**
+ * Create GeoArrow layers without an overlay — for in-place overlay updates.
+ */
+export declare function createGeoArrowLayers(modules: Record<string, any>, options: GeoArrowOverlayOptions): any[];
+/**
+ * Build a deck.gl GeoJsonLayer that draws a yellow outline around a single feature.
+ * Used for QGIS-style click-selection highlight on the deck.gl canvas (which sits
+ * above MapLibre, so a native MapLibre layer would be hidden).
+ */
+export declare function buildSelectionLayer(GeoJsonLayer: any, feature: GeoJSON.Feature | null): any | null;
+export {};

package/dist/utils/deck.js

@@ -0,0 +1,208 @@
+/**
+ * Shared deck.gl utilities for map viewers.
+ *
+ * - GeoJSON overlay: used by FlatGeobufViewer
+ * - GeoArrow overlay: used by GeoParquetMapViewer (zero-copy DuckDB → GPU pipeline)
+ */
+// ─── Shared hover cursor helper ─────────────────────────────────────
+/**
+ * Create an onHover callback that toggles the cursor on the MapLibre canvas.
+ * With `interleaved: false`, deck.gl's own canvas has pointer-events: none,
+ * so getCursor on MapboxOverlay has no visible effect — we must set cursor
+ * directly on the MapLibre map canvas instead.
+ */
+export function hoverCursor(map) {
+    return (info) => {
+        map.getCanvas().style.cursor = info.picked ? 'pointer' : '';
+    };
+}
+/** Distinct fill/line colors per geometry type. */
+export const GEOMETRY_COLORS = {
+    point: { fill: [66, 133, 244, 180], line: [25, 103, 210, 220] },
+    linestring: { fill: [0, 172, 193, 160], line: [0, 131, 143, 220] },
+    polygon: { fill: [232, 121, 61, 110], line: [230, 81, 0, 220] }
+};
+/** Lookup colors for a geometry type, falling back to polygon palette. */
+function colorsForType(geomType) {
+    const t = geomType.toLowerCase().replace('multi', '');
+    return GEOMETRY_COLORS[t] ?? GEOMETRY_COLORS.polygon;
+}
+/**
+ * GeoJSON accessor: return fill color based on feature geometry type.
+ * Used as deck.gl accessor function for getFillColor / getLineColor.
+ */
+export function geojsonFillColor(feature) {
+    return colorsForType(feature.geometry?.type ?? 'polygon').fill;
+}
+export function geojsonLineColor(feature) {
+    return colorsForType(feature.geometry?.type ?? 'polygon').line;
+}
+// ─── GeoJSON overlay (FlatGeobufViewer) ──────────────────────────────
+/** Lazy-load deck.gl modules (MapboxOverlay + GeoJsonLayer). */
+export async function loadDeckModules() {
+    const [{ MapboxOverlay }, { GeoJsonLayer }] = await Promise.all([
+        import('@deck.gl/mapbox'),
+        import('@deck.gl/layers')
+    ]);
+    return { MapboxOverlay, GeoJsonLayer };
+}
+/**
+ * Create a MapboxOverlay with a single GeoJsonLayer.
+ * Colors are assigned per-feature based on geometry type.
+ */
+export function createDeckOverlay(modules, options) {
+    const { MapboxOverlay, GeoJsonLayer } = modules;
+    const { layerId, data, onClick, onHover } = options;
+    return new MapboxOverlay({
+        interleaved: false,
+        layers: [
+            new GeoJsonLayer({
+                id: layerId,
+                data,
+                pickable: true,
+                stroked: true,
+                filled: true,
+                pointType: 'circle',
+                getFillColor: geojsonFillColor,
+                getLineColor: geojsonLineColor,
+                getPointRadius: 6,
+                getLineWidth: 2.5,
+                lineWidthMinPixels: 1.5,
+                pointRadiusMinPixels: 4,
+                pointRadiusMaxPixels: 12,
+                autoHighlight: true,
+                highlightColor: [255, 255, 255, 100],
+                onHover,
+                onClick: (info) => {
+                    if (info.object?.properties && onClick) {
+                        onClick({ ...info.object.properties }, info.object);
+                    }
+                }
+            })
+        ]
+    });
+}
+// ─── GeoArrow overlay (GeoParquetMapViewer) ──────────────────────────
+/** Lazy-load GeoArrow deck.gl layers + MapboxOverlay + GeoJsonLayer (for selection). */
+export async function loadGeoArrowModules() {
+    const [{ MapboxOverlay }, geoarrowLayers, { GeoJsonLayer }] = await Promise.all([
+        import('@deck.gl/mapbox'),
+        import('@geoarrow/deck.gl-layers'),
+        import('@deck.gl/layers')
+    ]);
+    return { MapboxOverlay, GeoJsonLayer, ...geoarrowLayers };
+}
+/** Create a single deck.gl layer for one GeoArrowResult. */
+function createLayerForResult(modules, result, layerId, onClick, onHover) {
+    const { GeoArrowScatterplotLayer, GeoArrowPathLayer, GeoArrowPolygonLayer } = modules;
+    const { table, geometryType, sourceIndices } = result;
+    const { fill, line } = colorsForType(geometryType);
+    const handleClick = (info) => {
+        if (!onClick)
+            return;
+        const props = extractPickedProps(info);
+        const srcIdx = sourceIndices[info.index] ?? info.index;
+        onClick(props, srcIdx);
+    };
+    if (geometryType === 'point' || geometryType === 'multipoint') {
+        return new GeoArrowScatterplotLayer({
+            id: layerId,
+            data: table,
+            getFillColor: fill,
+            getRadius: 6,
+            radiusUnits: 'pixels',
+            radiusMinPixels: 4,
+            radiusMaxPixels: 12,
+            pickable: true,
+            autoHighlight: true,
+            highlightColor: [255, 255, 255, 100],
+            _validate: false,
+            onHover,
+            onClick: handleClick
+        });
+    }
+    else if (geometryType === 'linestring' || geometryType === 'multilinestring') {
+        return new GeoArrowPathLayer({
+            id: layerId,
+            data: table,
+            getColor: line,
+            getWidth: 2.5,
+            widthUnits: 'pixels',
+            widthMinPixels: 1.5,
+            pickable: true,
+            autoHighlight: true,
+            highlightColor: [255, 255, 255, 100],
+            _validate: false,
+            onHover,
+            onClick: handleClick
+        });
+    }
+    else {
+        return new GeoArrowPolygonLayer({
+            id: layerId,
+            data: table,
+            getFillColor: fill,
+            getLineColor: line,
+            getLineWidth: 2,
+            lineWidthMinPixels: 1.5,
+            pickable: true,
+            autoHighlight: true,
+            highlightColor: [255, 255, 255, 100],
+            _validate: false,
+            onHover,
+            onClick: handleClick
+        });
+    }
+}
+/**
+ * Create MapboxOverlay with GeoArrow layers — one per geometry type group.
+ * Returns both the overlay and the data layers array (for adding selection layers later).
+ */
+export function createGeoArrowOverlay(modules, options) {
+    const { MapboxOverlay } = modules;
+    const { layerId, geoArrowResults, onClick, onHover } = options;
+    const layers = geoArrowResults.map((result) => createLayerForResult(modules, result, `${layerId}-${result.geometryType}`, onClick, onHover));
+    return { overlay: new MapboxOverlay({ interleaved: false, layers }), layers };
+}
+/**
+ * Create GeoArrow layers without an overlay — for in-place overlay updates.
+ */
+export function createGeoArrowLayers(modules, options) {
+    const { layerId, geoArrowResults, onClick, onHover } = options;
+    return geoArrowResults.map((result) => createLayerForResult(modules, result, `${layerId}-${result.geometryType}`, onClick, onHover));
+}
+// ─── Selection highlight layer (shared by deck.gl viewers) ──────────
+/**
+ * Build a deck.gl GeoJsonLayer that draws a yellow outline around a single feature.
+ * Used for QGIS-style click-selection highlight on the deck.gl canvas (which sits
+ * above MapLibre, so a native MapLibre layer would be hidden).
+ */
+export function buildSelectionLayer(GeoJsonLayer, feature) {
+    if (!feature)
+        return null;
+    return new GeoJsonLayer({
+        id: 'selection-highlight',
+        data: { type: 'FeatureCollection', features: [feature] },
+        pickable: false,
+        stroked: true,
+        filled: false,
+        pointType: 'circle',
+        getLineColor: [255, 200, 0, 255],
+        getLineWidth: 3,
+        lineWidthMinPixels: 2,
+        getPointRadius: 10,
+        pointRadiusMinPixels: 8,
+        pointRadiusMaxPixels: 14
+    });
+}
+/** Convert GeoArrow picking result to plain object (skip geometry column). */
+function extractPickedProps(info) {
+    if (!info.object)
+        return {};
+    const props = {};
+    for (const key of Object.keys(info.object)) {
+        if (key !== 'geometry')
+            props[key] = info.object[key];
+    }
+    return props;
+}

package/dist/utils/evidence-context.d.ts

@@ -0,0 +1,22 @@
+import type { QueryResult } from '../query/engine';
+export declare class EvidenceContext {
+    private connId;
+    private prefix;
+    private results;
+    constructor(connId: string, prefix?: string);
+    /**
+     * Execute a SQL query and store the result under the given name.
+     */
+    executeSql(sql: string, queryName: string): Promise<Record<string, any>[]>;
+    /**
+     * Transform relative file paths in SQL to full S3 URLs.
+     * e.g., read_parquet('data.parquet') → read_parquet('s3://bucket/prefix/data.parquet')
+     */
+    private transformPaths;
+    getResult(queryName: string): {
+        result: QueryResult;
+        rows: Record<string, any>[];
+    } | undefined;
+    getAllResults(): Map<string, Record<string, any>[]>;
+    getColumns(queryName: string): string[];
+}

package/dist/utils/evidence-context.js

@@ -0,0 +1,56 @@
+import { getQueryEngine } from '../query/index.js';
+export class EvidenceContext {
+    connId;
+    prefix;
+    results = new Map();
+    constructor(connId, prefix = '') {
+        this.connId = connId;
+        this.prefix = prefix;
+    }
+    /**
+     * Execute a SQL query and store the result under the given name.
+     */
+    async executeSql(sql, queryName) {
+        const engine = await getQueryEngine();
+        // Transform relative file paths to full paths
+        const transformedSql = this.transformPaths(sql);
+        const result = await engine.query(this.connId, transformedSql);
+        const rows = result.rows ?? [];
+        this.results.set(queryName, { result, rows });
+        return rows;
+    }
+    /**
+     * Transform relative file paths in SQL to full S3 URLs.
+     * e.g., read_parquet('data.parquet') → read_parquet('s3://bucket/prefix/data.parquet')
+     */
+    transformPaths(sql) {
+        if (!this.connId || !this.prefix)
+            return sql;
+        // Match read_parquet('path'), read_csv('path'), read_json('path')
+        return sql.replace(/(read_(?:parquet|csv|json|csv_auto))\('([^']+)'\)/g, (match, fn, path) => {
+            // Skip absolute paths and URLs
+            if (path.startsWith('s3://') || path.startsWith('http') || path.startsWith('/')) {
+                return match;
+            }
+            // Resolve relative path
+            const fullPath = `s3://${this.prefix}/${path}`;
+            return `${fn}('${fullPath}')`;
+        });
+    }
+    getResult(queryName) {
+        return this.results.get(queryName);
+    }
+    getAllResults() {
+        const map = new Map();
+        for (const [name, { rows }] of this.results) {
+            map.set(name, rows);
+        }
+        return map;
+    }
+    getColumns(queryName) {
+        const entry = this.results.get(queryName);
+        if (!entry)
+            return [];
+        return entry.result.columns;
+    }
+}

package/dist/utils/export.d.ts

@@ -0,0 +1,2 @@
+export declare function exportToCsv(columns: string[], rows: Record<string, any>[], filename: string): void;
+export declare function exportToJson(columns: string[], rows: Record<string, any>[], filename: string): void;

package/dist/utils/export.js

@@ -0,0 +1,51 @@
+function triggerDownload(content, filename, mimeType) {
+    const blob = new Blob([content], { type: mimeType });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+}
+function formatValue(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+function escapeCsvField(value) {
+    if (value.includes(',') || value.includes('"') || value.includes('\n') || value.includes('\r')) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
+export function exportToCsv(columns, rows, filename) {
+    const header = columns.map(escapeCsvField).join(',');
+    const body = rows
+        .map((row) => columns.map((col) => escapeCsvField(formatValue(row[col]))).join(','))
+        .join('\n');
+    const csv = `${header}\n${body}`;
+    triggerDownload(csv, filename.endsWith('.csv') ? filename : `${filename}.csv`, 'text/csv;charset=utf-8;');
+}
+export function exportToJson(columns, rows, filename) {
+    const data = rows.map((row) => {
+        const obj = {};
+        for (const col of columns) {
+            const val = row[col];
+            if (val instanceof Date) {
+                obj[col] = val.toISOString();
+            }
+            else {
+                obj[col] = val ?? null;
+            }
+        }
+        return obj;
+    });
+    const json = JSON.stringify(data, null, 2);
+    triggerDownload(json, filename.endsWith('.json') ? filename : `${filename}.json`, 'application/json');
+}

package/dist/utils/format.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Formats a byte count into a human-readable string.
+ */
+export declare function formatFileSize(bytes: number): string;
+/**
+ * Formats a unix timestamp (milliseconds) to a human-readable date string.
+ * Shows relative time for recent dates, absolute for older ones.
+ */
+export declare function formatDate(timestamp: number): string;
+/**
+ * Extracts the file extension from a filename, including the leading dot.
+ * Returns an empty string if no extension is found.
+ */
+export declare function getFileExtension(filename: string): string;

package/dist/utils/format.js

@@ -0,0 +1,56 @@
+/**
+ * Formats a byte count into a human-readable string.
+ */
+export function formatFileSize(bytes) {
+    if (bytes < 0)
+        return '0 B';
+    if (bytes === 0)
+        return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const base = 1024;
+    const exponent = Math.min(Math.floor(Math.log(bytes) / Math.log(base)), units.length - 1);
+    const value = bytes / base ** exponent;
+    // Use integer display for bytes, one decimal for everything else
+    if (exponent === 0)
+        return `${bytes} B`;
+    return `${value.toFixed(1)} ${units[exponent]}`;
+}
+/**
+ * Formats a unix timestamp (milliseconds) to a human-readable date string.
+ * Shows relative time for recent dates, absolute for older ones.
+ */
+export function formatDate(timestamp) {
+    if (!timestamp || timestamp <= 0 || !Number.isFinite(timestamp))
+        return '--';
+    const date = new Date(timestamp);
+    const now = Date.now();
+    const diffMs = now - timestamp;
+    const diffSeconds = Math.floor(diffMs / 1000);
+    const diffMinutes = Math.floor(diffSeconds / 60);
+    const diffHours = Math.floor(diffMinutes / 60);
+    const diffDays = Math.floor(diffHours / 24);
+    if (diffSeconds < 60)
+        return 'Just now';
+    if (diffMinutes < 60)
+        return `${diffMinutes}m ago`;
+    if (diffHours < 24)
+        return `${diffHours}h ago`;
+    if (diffDays < 7)
+        return `${diffDays}d ago`;
+    // For older dates, show absolute date
+    return date.toLocaleDateString(undefined, {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric'
+    });
+}
+/**
+ * Extracts the file extension from a filename, including the leading dot.
+ * Returns an empty string if no extension is found.
+ */
+export function getFileExtension(filename) {
+    const lastDot = filename.lastIndexOf('.');
+    if (lastDot <= 0)
+        return '';
+    return filename.slice(lastDot).toLowerCase();
+}