@walkthru-earth/objex-utils 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -208,6 +208,60 @@ interface StorageAdapter {
     readonly supportsWrite: boolean;
 }
 
+/**
+ * Provider registry — single source of truth for all cloud storage providers.
+ *
+ * Centralizes endpoint patterns, regions, auth methods, and UI metadata.
+ * Used by ConnectionDialog, browser-cloud adapter, host-detection, url-state, etc.
+ */
+type ProviderId = 's3' | 'gcs' | 'r2' | 'minio' | 'azure' | 'storj' | 'b2' | 'digitalocean' | 'wasabi' | 'contabo' | 'hetzner' | 'linode' | 'ovhcloud';
+interface ProviderRegion {
+    code: string;
+    label: string;
+}
+interface ProviderDef {
+    /** Display label in the UI. */
+    label: string;
+    /** Short description shown as helper text. */
+    description: string;
+    /** Auth method used by this provider. */
+    authMethod: 'sigv4' | 'sas-token';
+    /** Whether the region field is relevant for this provider. */
+    needsRegion: boolean;
+    /** Whether the endpoint field is required. */
+    needsEndpoint: boolean;
+    /** Default region when creating a new connection. */
+    defaultRegion: string;
+    /**
+     * Endpoint template with `{region}` placeholder.
+     * If null, the user must provide a custom endpoint (e.g. MinIO).
+     * If a fixed string (no `{region}`), it's always the same (e.g. GCS).
+     */
+    endpointTemplate: string | null;
+    /** Known regions with labels. Empty = free-form region input. */
+    regions: ProviderRegion[];
+    /** Bucket label override (e.g. Azure uses "Container"). */
+    bucketLabel?: string;
+    /** Default endpoint placeholder shown in the input. */
+    endpointPlaceholder: string;
+    /** URI schemes that map to this provider (lowercase, without "://"). */
+    schemes: string[];
+}
+declare const PROVIDERS: Record<ProviderId, ProviderDef>;
+/** All provider IDs, ordered for the UI. */
+declare const PROVIDER_IDS: ProviderId[];
+/** Get provider def, falling back to S3 for unknown. */
+declare function getProvider(id: string): ProviderDef;
+/** Build endpoint URL from template + region. */
+declare function buildEndpointFromTemplate(id: ProviderId, region: string): string;
+/**
+ * Build the base URL for API requests (endpoint + bucket).
+ * Used by browser-cloud adapter and url-state.
+ */
+declare function buildProviderBaseUrl(provider: ProviderId, endpoint: string, bucket: string, region: string): string;
+/** Check if a provider uses the GCS JSON API (not S3 XML). */
+declare function isGcsProvider(provider: string, endpoint: string): boolean;
+
 /**
  * Minimal adapter for direct HTTPS URLs (source: 'url').
  * Only supports read/head — no listing or writing.
@@ -226,6 +280,34 @@ declare class UrlAdapter implements StorageAdapter {
     copy(): Promise<WriteResult>;
 }
 
+/**
+ * Cloud storage protocol URL utilities — pure TS, no Svelte dependency.
+ *
+ * Converts cloud protocol URLs (s3://, gs://) to HTTPS URLs for browser access.
+ * Provider-aware native scheme lookup.
+ */
+/**
+ * Map provider to its native URI scheme prefix.
+ * Derived from the registry's `schemes` array (first entry is the primary scheme).
+ * Falls back to 's3' for providers without a scheme (S3-compatible).
+ */
+declare function getNativeScheme(provider: string): string;
+/**
+ * Safely decode a percent-encoded URI component.
+ * Returns the original string if decoding fails (malformed sequences).
+ */
+declare function safeDecodeURIComponent(s: string): string;
+/**
+ * Convert a cloud storage protocol URL (s3://, gs://) to an HTTPS URL
+ * for browser access. Returns the original URL if already HTTP(S) or unknown.
+ *
+ * Supported:
+ * - `s3://bucket/key` → `https://s3.{region}.amazonaws.com/{bucket}/{key}`
+ *   (region auto-detected from bucket name when possible)
+ * - `gs://bucket/key` → `https://storage.googleapis.com/{bucket}/{key}`
+ */
+declare function resolveCloudUrl(url: string): string;
+
 type TypeCategory = 'number' | 'string' | 'date' | 'boolean' | 'geo' | 'binary' | 'json' | 'other';
 declare function classifyType(duckdbType: string): TypeCategory;
 declare function typeColor(category: TypeCategory): string;
@@ -241,6 +323,42 @@ declare function typeLabel(category: TypeCategory): string;
  */
 declare function handleLoadError(err: unknown): string | null;
 
+/**
+ * Escape a CSV field value per RFC 4180.
+ */
+declare function escapeCsvField(value: string): string;
+/**
+ * Serialize column/row data to a CSV string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+declare function serializeToCsv(columns: string[], rows: Record<string, unknown>[]): string;
+/**
+ * Serialize column/row data to a formatted JSON string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+declare function serializeToJson(columns: string[], rows: Record<string, unknown>[]): string;
+
+/**
+ * Pure file entry sorting — framework-agnostic, works in Node.js.
+ */
+
+type SortField = 'name' | 'size' | 'modified' | 'extension';
+type SortDirection = 'asc' | 'desc';
+interface SortConfig {
+    field: SortField;
+    direction: SortDirection;
+}
+/**
+ * Sort file entries by the given config.
+ * Directories always sort before files regardless of sort field.
+ * Returns a new array (does not mutate the input).
+ */
+declare function sortFileEntries(entries: FileEntry[], config: SortConfig): FileEntry[];
+/**
+ * Toggle sort config: same field flips direction, new field starts ascending.
+ */
+declare function toggleSortField(current: SortConfig, field: SortField): SortConfig;
+
 /**
  * Formats a byte count into a human-readable string.
  */
@@ -310,6 +428,54 @@ interface HexRow {
  */
 declare function generateHexDump(data: Uint8Array, bytesPerRow?: number): HexRow[];
 
+/**
+ * Generic localStorage helpers with SSR safety.
+ *
+ * Used by connection, settings, and query-history stores to avoid
+ * repeating the same load/persist/try-catch/SSR-guard pattern.
+ */
+/**
+ * Load a JSON value from localStorage.
+ * Returns `defaultValue` on SSR, missing key, or parse error.
+ */
+declare function loadFromStorage<T>(key: string, defaultValue: T): T;
+/**
+ * Persist a JSON-serializable value to localStorage.
+ * Silently no-ops on SSR or storage errors (quota, private browsing).
+ */
+declare function persistToStorage(key: string, value: unknown): void;
+
+interface SqlBlock {
+    name: string;
+    sql: string;
+    startLine: number;
+    endLine: number;
+}
+interface ParsedMarkdownDocument {
+    frontmatter: Record<string, any>;
+    content: string;
+    sqlBlocks: SqlBlock[];
+}
+/**
+ * Parse a markdown document with YAML frontmatter and SQL code blocks.
+ *
+ * Evidence-compatible syntax:
+ * ```sql query_name
+ * SELECT * FROM table
+ * ```
+ */
+declare function parseMarkdownDocument(markdown: string): ParsedMarkdownDocument;
+/**
+ * Interpolate template variables in markdown text.
+ * Supports {queryName.rows[0].columnName} syntax.
+ */
+declare function interpolateTemplates(text: string, queryResults: Map<string, Record<string, any>[]>): string;
+/**
+ * Replace SQL blocks in markdown content with placeholder markers
+ * that can be replaced with rendered components.
+ */
+declare function markSqlBlocks(content: string): string;
+
 /**
  * Lightweight Parquet metadata reader using hyparquet.
  *
@@ -478,4 +644,4 @@ declare function findGeoColumnFromRows(rows: Record<string, unknown>[], schema:
     type: string;
 }[]): string | null;
 
-export { COPY_FEEDBACK_MS, type Connection, type ConnectionConfig, DEFAULT_TARGET_CRS, DUCKDB_INIT_TIMEOUT_MS, type Defaults, type DuckDbReadFn, type FileCategory, type FileEntry, type FileTypeInfo, type GeoArrowGeomType, type GeoArrowResult, type GeoColumnMeta, type GeoParquetMeta, type GeoType, type HexRow, LAYER_HUE_MULTIPLIER, type ListPage, MAX_QUERY_HISTORY_ENTRIES, type MapQueryHandle, type MapQueryResult, type ParquetFileMetadata, type ParsedGeometry, type ParsedStorageUrl, QueryCancelledError, type QueryEngine, type QueryHandle, type QueryResult, SQL_PREVIEW_LENGTH, STORAGE_KEYS, type SchemaField, type StorageAdapter, type StorageProvider, type Tab, type Theme, type TypeCategory, UrlAdapter, VIEWER_DIR_EXTENSIONS, type ViewerKind, WGS84_CODES, type WriteResult, buildDuckDbSource, buildGeoArrowTables, classifyType, describeParseResult, extractBounds, extractEpsgFromGeoMeta, extractGeometryTypes, findGeoColumn, findGeoColumnFromRows, formatDate, formatFileSize, formatValue, generateHexDump, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getViewerKind, handleLoadError, isCloudNativeFormat, isQueryable, jsonReplacerBigInt, looksLikeUrl, normalizeGeomType, parseStorageUrl, parseWKB, readParquetMetadata, toBinary, typeBadgeClass, typeColor, typeLabel };
+export { COPY_FEEDBACK_MS, type Connection, type ConnectionConfig, DEFAULT_TARGET_CRS, DUCKDB_INIT_TIMEOUT_MS, type Defaults, type DuckDbReadFn, type FileCategory, type FileEntry, type FileTypeInfo, type GeoArrowGeomType, type GeoArrowResult, type GeoColumnMeta, type GeoParquetMeta, type GeoType, type HexRow, LAYER_HUE_MULTIPLIER, type ListPage, MAX_QUERY_HISTORY_ENTRIES, type MapQueryHandle, type MapQueryResult, PROVIDERS, PROVIDER_IDS, type ParquetFileMetadata, type ParsedGeometry, type ParsedMarkdownDocument, type ParsedStorageUrl, type ProviderDef, type ProviderId, type ProviderRegion, QueryCancelledError, type QueryEngine, type QueryHandle, type QueryResult, SQL_PREVIEW_LENGTH, STORAGE_KEYS, type SchemaField, type SortConfig, type SortDirection, type SortField, type SqlBlock, type StorageAdapter, type StorageProvider, type Tab, type Theme, type TypeCategory, UrlAdapter, VIEWER_DIR_EXTENSIONS, type ViewerKind, WGS84_CODES, type WriteResult, buildDuckDbSource, buildEndpointFromTemplate, buildGeoArrowTables, buildProviderBaseUrl, classifyType, describeParseResult, escapeCsvField, extractBounds, extractEpsgFromGeoMeta, extractGeometryTypes, findGeoColumn, findGeoColumnFromRows, formatDate, formatFileSize, formatValue, generateHexDump, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getNativeScheme, getProvider, getViewerKind, handleLoadError, interpolateTemplates, isCloudNativeFormat, isGcsProvider, isQueryable, jsonReplacerBigInt, loadFromStorage, looksLikeUrl, markSqlBlocks, normalizeGeomType, parseMarkdownDocument, parseStorageUrl, parseWKB, persistToStorage, readParquetMetadata, resolveCloudUrl, safeDecodeURIComponent, serializeToCsv, serializeToJson, sortFileEntries, toBinary, toggleSortField, typeBadgeClass, typeColor, typeLabel };

package/dist/index.d.ts

@@ -208,6 +208,60 @@ interface StorageAdapter {
     readonly supportsWrite: boolean;
 }
 
+/**
+ * Provider registry — single source of truth for all cloud storage providers.
+ *
+ * Centralizes endpoint patterns, regions, auth methods, and UI metadata.
+ * Used by ConnectionDialog, browser-cloud adapter, host-detection, url-state, etc.
+ */
+type ProviderId = 's3' | 'gcs' | 'r2' | 'minio' | 'azure' | 'storj' | 'b2' | 'digitalocean' | 'wasabi' | 'contabo' | 'hetzner' | 'linode' | 'ovhcloud';
+interface ProviderRegion {
+    code: string;
+    label: string;
+}
+interface ProviderDef {
+    /** Display label in the UI. */
+    label: string;
+    /** Short description shown as helper text. */
+    description: string;
+    /** Auth method used by this provider. */
+    authMethod: 'sigv4' | 'sas-token';
+    /** Whether the region field is relevant for this provider. */
+    needsRegion: boolean;
+    /** Whether the endpoint field is required. */
+    needsEndpoint: boolean;
+    /** Default region when creating a new connection. */
+    defaultRegion: string;
+    /**
+     * Endpoint template with `{region}` placeholder.
+     * If null, the user must provide a custom endpoint (e.g. MinIO).
+     * If a fixed string (no `{region}`), it's always the same (e.g. GCS).
+     */
+    endpointTemplate: string | null;
+    /** Known regions with labels. Empty = free-form region input. */
+    regions: ProviderRegion[];
+    /** Bucket label override (e.g. Azure uses "Container"). */
+    bucketLabel?: string;
+    /** Default endpoint placeholder shown in the input. */
+    endpointPlaceholder: string;
+    /** URI schemes that map to this provider (lowercase, without "://"). */
+    schemes: string[];
+}
+declare const PROVIDERS: Record<ProviderId, ProviderDef>;
+/** All provider IDs, ordered for the UI. */
+declare const PROVIDER_IDS: ProviderId[];
+/** Get provider def, falling back to S3 for unknown. */
+declare function getProvider(id: string): ProviderDef;
+/** Build endpoint URL from template + region. */
+declare function buildEndpointFromTemplate(id: ProviderId, region: string): string;
+/**
+ * Build the base URL for API requests (endpoint + bucket).
+ * Used by browser-cloud adapter and url-state.
+ */
+declare function buildProviderBaseUrl(provider: ProviderId, endpoint: string, bucket: string, region: string): string;
+/** Check if a provider uses the GCS JSON API (not S3 XML). */
+declare function isGcsProvider(provider: string, endpoint: string): boolean;
+
 /**
  * Minimal adapter for direct HTTPS URLs (source: 'url').
  * Only supports read/head — no listing or writing.
@@ -226,6 +280,34 @@ declare class UrlAdapter implements StorageAdapter {
     copy(): Promise<WriteResult>;
 }
 
+/**
+ * Cloud storage protocol URL utilities — pure TS, no Svelte dependency.
+ *
+ * Converts cloud protocol URLs (s3://, gs://) to HTTPS URLs for browser access.
+ * Provider-aware native scheme lookup.
+ */
+/**
+ * Map provider to its native URI scheme prefix.
+ * Derived from the registry's `schemes` array (first entry is the primary scheme).
+ * Falls back to 's3' for providers without a scheme (S3-compatible).
+ */
+declare function getNativeScheme(provider: string): string;
+/**
+ * Safely decode a percent-encoded URI component.
+ * Returns the original string if decoding fails (malformed sequences).
+ */
+declare function safeDecodeURIComponent(s: string): string;
+/**
+ * Convert a cloud storage protocol URL (s3://, gs://) to an HTTPS URL
+ * for browser access. Returns the original URL if already HTTP(S) or unknown.
+ *
+ * Supported:
+ * - `s3://bucket/key` → `https://s3.{region}.amazonaws.com/{bucket}/{key}`
+ *   (region auto-detected from bucket name when possible)
+ * - `gs://bucket/key` → `https://storage.googleapis.com/{bucket}/{key}`
+ */
+declare function resolveCloudUrl(url: string): string;
+
 type TypeCategory = 'number' | 'string' | 'date' | 'boolean' | 'geo' | 'binary' | 'json' | 'other';
 declare function classifyType(duckdbType: string): TypeCategory;
 declare function typeColor(category: TypeCategory): string;
@@ -241,6 +323,42 @@ declare function typeLabel(category: TypeCategory): string;
  */
 declare function handleLoadError(err: unknown): string | null;
 
+/**
+ * Escape a CSV field value per RFC 4180.
+ */
+declare function escapeCsvField(value: string): string;
+/**
+ * Serialize column/row data to a CSV string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+declare function serializeToCsv(columns: string[], rows: Record<string, unknown>[]): string;
+/**
+ * Serialize column/row data to a formatted JSON string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+declare function serializeToJson(columns: string[], rows: Record<string, unknown>[]): string;
+
+/**
+ * Pure file entry sorting — framework-agnostic, works in Node.js.
+ */
+
+type SortField = 'name' | 'size' | 'modified' | 'extension';
+type SortDirection = 'asc' | 'desc';
+interface SortConfig {
+    field: SortField;
+    direction: SortDirection;
+}
+/**
+ * Sort file entries by the given config.
+ * Directories always sort before files regardless of sort field.
+ * Returns a new array (does not mutate the input).
+ */
+declare function sortFileEntries(entries: FileEntry[], config: SortConfig): FileEntry[];
+/**
+ * Toggle sort config: same field flips direction, new field starts ascending.
+ */
+declare function toggleSortField(current: SortConfig, field: SortField): SortConfig;
+
 /**
  * Formats a byte count into a human-readable string.
  */
@@ -310,6 +428,54 @@ interface HexRow {
  */
 declare function generateHexDump(data: Uint8Array, bytesPerRow?: number): HexRow[];
 
+/**
+ * Generic localStorage helpers with SSR safety.
+ *
+ * Used by connection, settings, and query-history stores to avoid
+ * repeating the same load/persist/try-catch/SSR-guard pattern.
+ */
+/**
+ * Load a JSON value from localStorage.
+ * Returns `defaultValue` on SSR, missing key, or parse error.
+ */
+declare function loadFromStorage<T>(key: string, defaultValue: T): T;
+/**
+ * Persist a JSON-serializable value to localStorage.
+ * Silently no-ops on SSR or storage errors (quota, private browsing).
+ */
+declare function persistToStorage(key: string, value: unknown): void;
+
+interface SqlBlock {
+    name: string;
+    sql: string;
+    startLine: number;
+    endLine: number;
+}
+interface ParsedMarkdownDocument {
+    frontmatter: Record<string, any>;
+    content: string;
+    sqlBlocks: SqlBlock[];
+}
+/**
+ * Parse a markdown document with YAML frontmatter and SQL code blocks.
+ *
+ * Evidence-compatible syntax:
+ * ```sql query_name
+ * SELECT * FROM table
+ * ```
+ */
+declare function parseMarkdownDocument(markdown: string): ParsedMarkdownDocument;
+/**
+ * Interpolate template variables in markdown text.
+ * Supports {queryName.rows[0].columnName} syntax.
+ */
+declare function interpolateTemplates(text: string, queryResults: Map<string, Record<string, any>[]>): string;
+/**
+ * Replace SQL blocks in markdown content with placeholder markers
+ * that can be replaced with rendered components.
+ */
+declare function markSqlBlocks(content: string): string;
+
 /**
  * Lightweight Parquet metadata reader using hyparquet.
  *
@@ -478,4 +644,4 @@ declare function findGeoColumnFromRows(rows: Record<string, unknown>[], schema:
     type: string;
 }[]): string | null;
 
-export { COPY_FEEDBACK_MS, type Connection, type ConnectionConfig, DEFAULT_TARGET_CRS, DUCKDB_INIT_TIMEOUT_MS, type Defaults, type DuckDbReadFn, type FileCategory, type FileEntry, type FileTypeInfo, type GeoArrowGeomType, type GeoArrowResult, type GeoColumnMeta, type GeoParquetMeta, type GeoType, type HexRow, LAYER_HUE_MULTIPLIER, type ListPage, MAX_QUERY_HISTORY_ENTRIES, type MapQueryHandle, type MapQueryResult, type ParquetFileMetadata, type ParsedGeometry, type ParsedStorageUrl, QueryCancelledError, type QueryEngine, type QueryHandle, type QueryResult, SQL_PREVIEW_LENGTH, STORAGE_KEYS, type SchemaField, type StorageAdapter, type StorageProvider, type Tab, type Theme, type TypeCategory, UrlAdapter, VIEWER_DIR_EXTENSIONS, type ViewerKind, WGS84_CODES, type WriteResult, buildDuckDbSource, buildGeoArrowTables, classifyType, describeParseResult, extractBounds, extractEpsgFromGeoMeta, extractGeometryTypes, findGeoColumn, findGeoColumnFromRows, formatDate, formatFileSize, formatValue, generateHexDump, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getViewerKind, handleLoadError, isCloudNativeFormat, isQueryable, jsonReplacerBigInt, looksLikeUrl, normalizeGeomType, parseStorageUrl, parseWKB, readParquetMetadata, toBinary, typeBadgeClass, typeColor, typeLabel };
+export { COPY_FEEDBACK_MS, type Connection, type ConnectionConfig, DEFAULT_TARGET_CRS, DUCKDB_INIT_TIMEOUT_MS, type Defaults, type DuckDbReadFn, type FileCategory, type FileEntry, type FileTypeInfo, type GeoArrowGeomType, type GeoArrowResult, type GeoColumnMeta, type GeoParquetMeta, type GeoType, type HexRow, LAYER_HUE_MULTIPLIER, type ListPage, MAX_QUERY_HISTORY_ENTRIES, type MapQueryHandle, type MapQueryResult, PROVIDERS, PROVIDER_IDS, type ParquetFileMetadata, type ParsedGeometry, type ParsedMarkdownDocument, type ParsedStorageUrl, type ProviderDef, type ProviderId, type ProviderRegion, QueryCancelledError, type QueryEngine, type QueryHandle, type QueryResult, SQL_PREVIEW_LENGTH, STORAGE_KEYS, type SchemaField, type SortConfig, type SortDirection, type SortField, type SqlBlock, type StorageAdapter, type StorageProvider, type Tab, type Theme, type TypeCategory, UrlAdapter, VIEWER_DIR_EXTENSIONS, type ViewerKind, WGS84_CODES, type WriteResult, buildDuckDbSource, buildEndpointFromTemplate, buildGeoArrowTables, buildProviderBaseUrl, classifyType, describeParseResult, escapeCsvField, extractBounds, extractEpsgFromGeoMeta, extractGeometryTypes, findGeoColumn, findGeoColumnFromRows, formatDate, formatFileSize, formatValue, generateHexDump, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getNativeScheme, getProvider, getViewerKind, handleLoadError, interpolateTemplates, isCloudNativeFormat, isGcsProvider, isQueryable, jsonReplacerBigInt, loadFromStorage, looksLikeUrl, markSqlBlocks, normalizeGeomType, parseMarkdownDocument, parseStorageUrl, parseWKB, persistToStorage, readParquetMetadata, resolveCloudUrl, safeDecodeURIComponent, serializeToCsv, serializeToJson, sortFileEntries, toBinary, toggleSortField, typeBadgeClass, typeColor, typeLabel };