@loaders.gl/tile-converter 5.0.0-alpha.6 → 5.0.0-alpha.8

package/dist/v5/conversion-api.d.ts

@@ -0,0 +1,122 @@
+/** A diagnostic produced while inspecting, converting, or validating tiles. */
+export interface TileConversionDiagnostic {
+    /** Stable machine-readable diagnostic code. */
+    readonly code: string;
+    /** Human-readable explanation of the diagnostic. */
+    readonly message: string;
+    /** Severity used by callers to decide whether the result is acceptable. */
+    readonly severity: 'info' | 'warning' | 'error';
+    /** Optional resource that produced the diagnostic. */
+    readonly resourceId?: string;
+}
+/** Typed failure raised when a conversion policy or validation gate rejects a resource. */
+export declare class TileConversionError extends Error {
+    /** Stable machine-readable failure code. */
+    readonly code: string;
+    /** Diagnostics associated with this failure. */
+    readonly diagnostics: readonly TileConversionDiagnostic[];
+    /** Creates a typed conversion failure. */
+    constructor(code: string, message: string, diagnostics?: readonly TileConversionDiagnostic[]);
+}
+/** Progress reported by the portable conversion core. */
+export interface TileConversionProgress {
+    /** Current conversion phase. */
+    readonly phase: 'inspect' | 'convert' | 'validate' | 'finalize';
+    /** Number of input resources consumed so far. */
+    readonly inputResources: number;
+    /** Number of output resources written so far. */
+    readonly outputResources: number;
+    /** Number of input bytes consumed so far. */
+    readonly inputBytes: number;
+    /** Number of output bytes written so far. */
+    readonly outputBytes: number;
+}
+/** Summary returned after a tileset conversion completes. */
+export interface TileConversionReport {
+    /** Completed conversion state. Failed conversions reject with their cause. */
+    readonly state: 'completed';
+    /** Number of input resources consumed. */
+    readonly inputResources: number;
+    /** Number of output resources written. */
+    readonly outputResources: number;
+    /** Number of input bytes consumed. */
+    readonly inputBytes: number;
+    /** Number of output bytes written. */
+    readonly outputBytes: number;
+    /** Largest output resource written. */
+    readonly largestOutputResourceBytes: number;
+    /** Diagnostics reported during conversion and validation. */
+    readonly diagnostics: readonly TileConversionDiagnostic[];
+}
+/** Portable source adapter that resolves and reads a tileset. */
+export interface TileConversionSource<TInspection, TInput> {
+    /** Inspect the source and return its profile-specific metadata. */
+    inspect(signal?: AbortSignal): Promise<TInspection>;
+    /** Stream input resources in deterministic traversal order. */
+    read(inspection: TInspection, signal?: AbortSignal): AsyncIterable<TInput>;
+}
+/** Output adapter whose awaited writes apply backpressure to conversion. */
+export interface TileConversionSink<TOutput> {
+    /** Write one completed output resource and resolve when it can be released. */
+    write(resource: TOutput, signal?: AbortSignal): Promise<void>;
+    /** Finalize the destination after every resource has been written. */
+    finalize(report: TileConversionReport): Promise<void>;
+    /** Abort and clean up a partial destination after a failure. */
+    abort(reason: unknown): Promise<void>;
+}
+/** Codec adapter used to convert one input resource into streamed outputs. */
+export interface TileConversionCodec<TInspection, TInput, TOutput> {
+    /** Convert one input resource into zero or more output resources. */
+    convert(resource: TInput, inspection: TInspection, signal?: AbortSignal): AsyncIterable<TOutput> | Promise<AsyncIterable<TOutput>>;
+    /** Optionally validate each output resource before it is written. */
+    validateOutput?(resource: TOutput, signal?: AbortSignal): Promise<readonly TileConversionDiagnostic[]>;
+}
+/** Options for the portable `convertTileset` operation. */
+export interface ConvertTilesetOptions<TInspection, TInput, TOutput> {
+    /** Injected input resolver and resource reader. */
+    readonly source: TileConversionSource<TInspection, TInput>;
+    /** Injected output codec. */
+    readonly codec: TileConversionCodec<TInspection, TInput, TOutput>;
+    /** Injected destination writer. */
+    readonly sink: TileConversionSink<TOutput>;
+    /** Return the decoded input byte size as a nonnegative safe integer. */
+    readonly measureInputBytes: (resource: TInput) => number;
+    /** Return the byte size of an output resource. */
+    readonly measureOutputBytes: (resource: TOutput) => number;
+    /** Reject a decoded input resource above this byte limit before encoding. Defaults to no limit. */
+    readonly maxInputResourceBytes?: number;
+    /** Reject any output resource larger than this configured byte limit. */
+    readonly maxOutputResourceBytes?: number;
+    /** Cancel inspection, conversion, validation, or writes. */
+    readonly signal?: AbortSignal;
+    /** Receive progress updates after each resource transition. */
+    readonly onProgress?: (progress: TileConversionProgress) => void;
+}
+/** Options for a standalone tileset validation pass. */
+export interface ValidateTilesetOptions<TTileset> {
+    /** Tileset or conversion result to validate. */
+    readonly tileset: TTileset;
+    /** Injected profile-specific validator. */
+    readonly validate: (tileset: TTileset, signal?: AbortSignal) => Promise<readonly TileConversionDiagnostic[]>;
+    /** Cancel validation. */
+    readonly signal?: AbortSignal;
+}
+/** Result of validating a tileset. */
+export interface TileValidationReport {
+    /** False when at least one error diagnostic was reported. */
+    readonly valid: boolean;
+    /** Diagnostics returned by the injected validator. */
+    readonly diagnostics: readonly TileConversionDiagnostic[];
+}
+/** Inspects a tileset with an injected, platform-specific source adapter. */
+export declare function inspectTileset<TInspection, TInput>(source: TileConversionSource<TInspection, TInput>, signal?: AbortSignal): Promise<TInspection>;
+/**
+ * Converts a stream of tileset resources through injected source, codec, and sink adapters.
+ * Decoded inputs are measured and checked against `maxInputResourceBytes` before encoding.
+ * This does not limit source decoding allocations or content retained by a source.
+ * Writes are awaited one resource at a time, keeping queued output bytes bounded by the
+ * largest emitted resource and the configured `maxOutputResourceBytes` limit.
+ */
+export declare function convertTileset<TInspection, TInput, TOutput>(options: ConvertTilesetOptions<TInspection, TInput, TOutput>): Promise<TileConversionReport>;
+/** Validates a tileset through an injected profile-specific validator. */
+export declare function validateTileset<TTileset>(options: ValidateTilesetOptions<TTileset>): Promise<TileValidationReport>;

package/dist/v5/feature-arrow.d.ts

@@ -0,0 +1,36 @@
+import type { ArrowTableBatch, Schema } from '@loaders.gl/schema';
+/** Feature attributes and source identifier ready for Arrow normalization. */
+export interface TileFeatureAttributes {
+    /** Stable feature identifier decoded from the source's feature-ID descriptor. */
+    readonly featureId: string | number | bigint;
+    /** Property values interpreted from the source metadata class. */
+    readonly properties: Readonly<Record<string, unknown>>;
+    /** Original class or property-table name, kept distinct between output batches. */
+    readonly metadataClass: string;
+    /** Optional original encoded metadata bytes, preserved without interpretation. */
+    readonly rawMetadata?: Uint8Array;
+}
+/** Explicit Arrow mapping and bounded output size for feature attribute batches. */
+export interface FeatureArrowBatchOptions {
+    /** Declared output columns and types, including the feature-ID column. */
+    readonly schema: Schema;
+    /** Schema field receiving stable feature identifiers. Defaults to `feature_id`. */
+    readonly featureIdField?: string;
+    /** Optional binary field receiving source metadata bytes. */
+    readonly rawMetadataField?: string;
+    /** Maximum number of features in one emitted Arrow record batch. Defaults to 65,536. */
+    readonly batchSize?: number;
+}
+/**
+ * Converts decoded feature attributes to bounded Arrow batches using a caller-declared schema.
+ *
+ * Values retain their source primitive types; nested lists, structs, dictionary enums, and 64-bit
+ * identifiers use the corresponding schema field type. Missing schema fields and incompatible
+ * identifiers fail explicitly. Unknown properties are rejected so a class mapping cannot silently
+ * discard data. Separate metadata classes should be passed separately with their own schema.
+ *
+ * @param features - Features decoded from one source metadata class.
+ * @param options - Explicit Arrow schema and batch configuration.
+ * @returns Arrow table batches whose schema metadata records the source metadata class.
+ */
+export declare function convertFeatureAttributesToArrowBatches(features: readonly TileFeatureAttributes[], options: FeatureArrowBatchOptions): ArrowTableBatch[];