@loaders.gl/parquet 4.4.5 → 5.0.0-alpha.2

package/src/lib/encoders/encode-table-to-parquet-js.ts

@@ -0,0 +1,261 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {DataType, Field, ObjectRowTable, Schema, Table} from '@loaders.gl/schema';
+import {concatUint8Arrays} from '../../parquetjs/utils/binary-utils';
+import {ParquetEncoder} from '../../parquetjs/encoder/parquet-encoder';
+import {ParquetSchema} from '../../parquetjs/schema/schema';
+import type {FieldDefinition, SchemaDefinition} from '../../parquetjs/schema/declare';
+import type {ParquetJSWriterOptions} from '../../parquet-js-writer';
+
+/** Encode a plain loaders.gl table with the parquetjs implementation. */
+export async function encodeTableToParquetJs(
+  table: Table,
+  objectRowTable: ObjectRowTable,
+  options: ParquetJSWriterOptions
+): Promise<ArrayBuffer> {
+  const parquetSchema = new ParquetSchema(
+    convertSchemaToParquetSchema(table.schema!, objectRowTable, options)
+  );
+  const chunks: Uint8Array[] = [];
+  const outputStream = {
+    write(chunk: Uint8Array, callback: (error?: Error) => void) {
+      chunks.push(chunk.slice());
+      callback();
+    },
+    close(callback: (error?: Error) => void) {
+      callback();
+    }
+  };
+
+  const encoder = await ParquetEncoder.openStream(
+    parquetSchema,
+    outputStream as any,
+    options.parquet
+  );
+
+  for (const [key, value] of Object.entries(table.schema?.metadata || {})) {
+    encoder.setMetadata(key, value);
+  }
+
+  for (const row of objectRowTable.data) {
+    await encoder.appendRow(row);
+  }
+
+  await encoder.close();
+
+  return concatUint8Arrays(chunks).slice().buffer;
+}
+
+/**
+ * Converts a loaders.gl schema into a parquetjs schema definition.
+ * @param schema table schema
+ * @param objectRowTable table data in object-row form
+ * @returns parquetjs schema definition
+ */
+function convertSchemaToParquetSchema(
+  schema: Schema,
+  objectRowTable: ObjectRowTable,
+  options: ParquetJSWriterOptions
+): SchemaDefinition {
+  const parquetFields: SchemaDefinition = {};
+  const columnEncodings = options.parquet?.columnEncodings || {};
+  const columnDictionaries = options.parquet?.columnDictionaries || {};
+  const fieldNames = new Set(schema.fields.map(field => field.name));
+  for (const columnName of Object.keys(columnEncodings)) {
+    if (!fieldNames.has(columnName)) {
+      throw new Error(`ParquetJSWriter: Unknown column encoding override "${columnName}"`);
+    }
+  }
+  for (const columnName of Object.keys(columnDictionaries)) {
+    if (!fieldNames.has(columnName)) {
+      throw new Error(`ParquetJSWriter: Unknown column dictionary override "${columnName}"`);
+    }
+  }
+
+  for (const field of schema.fields) {
+    parquetFields[field.name] = {
+      ...convertFieldToParquetFieldDefinition(field, objectRowTable.data),
+      encoding: columnEncodings[field.name]
+    };
+  }
+
+  return parquetFields;
+}
+
+/**
+ * Converts one loaders.gl field to the closest parquetjs field definition.
+ * @param field table field metadata
+ * @param rows object rows used for nullability and fallback inference
+ * @returns parquetjs field definition
+ */
+function convertFieldToParquetFieldDefinition(
+  field: Field,
+  rows: Array<Record<string, unknown>>
+): FieldDefinition {
+  const sampleValue = getFirstDefinedValue(rows, field.name);
+  const nullable = field.nullable ?? sampleValue === undefined;
+  const dataType = field.type === 'null' ? getDataTypeFromValue(sampleValue) : field.type;
+
+  switch (dataType) {
+    case 'bool':
+      return {type: 'BOOLEAN', optional: nullable};
+
+    case 'int':
+    case 'int32':
+      return {type: 'INT_32', optional: nullable};
+
+    case 'int8':
+      return {type: 'INT_8', optional: nullable};
+
+    case 'int16':
+      return {type: 'INT_16', optional: nullable};
+
+    case 'uint8':
+      return {type: 'UINT_8', optional: nullable};
+
+    case 'uint16':
+      return {type: 'UINT_16', optional: nullable};
+
+    case 'uint32':
+      return {type: 'UINT_32', optional: nullable};
+
+    case 'int64':
+      return {type: 'INT_64', optional: nullable};
+
+    case 'uint64':
+      return {type: 'UINT_64', optional: nullable};
+
+    case 'float':
+    case 'float32':
+      return {type: 'FLOAT', optional: nullable};
+
+    case 'float16':
+      return {type: 'FLOAT16', optional: nullable};
+
+    case 'float64':
+      return {type: 'DOUBLE', optional: nullable};
+
+    case 'utf8':
+      return {type: 'UTF8', optional: nullable};
+
+    case 'binary':
+      return {type: 'BYTE_ARRAY', optional: nullable};
+
+    case 'date-day':
+      return {type: 'DATE', optional: nullable};
+
+    case 'date-millisecond':
+    case 'timestamp-second':
+    case 'timestamp-millisecond':
+      return {type: 'TIMESTAMP_MILLIS', optional: nullable};
+
+    case 'timestamp-microsecond':
+      return {type: 'TIMESTAMP_MICROS', optional: nullable};
+
+    case 'timestamp-nanosecond':
+      return {type: 'TIMESTAMP_NANOS', optional: nullable};
+
+    case 'time-second':
+    case 'time-millisecond':
+      return {type: 'TIME_MILLIS', optional: nullable};
+
+    case 'time-microsecond':
+      return {type: 'TIME_MICROS', optional: nullable};
+
+    case 'time-nanosecond':
+      return {type: 'TIME_NANOS', optional: nullable};
+
+    default:
+      if (typeof dataType === 'object' && dataType.type === 'decimal') {
+        const physicalType =
+          dataType.precision <= 9
+            ? 'DECIMAL_INT32'
+            : dataType.precision <= 18
+              ? 'DECIMAL_INT64'
+              : 'DECIMAL_FIXED_LEN_BYTE_ARRAY';
+        return {
+          type: physicalType,
+          typeLength:
+            physicalType === 'DECIMAL_FIXED_LEN_BYTE_ARRAY'
+              ? getDecimalByteWidth(dataType.precision)
+              : undefined,
+          precision: dataType.precision,
+          scale: dataType.scale,
+          optional: nullable
+        };
+      }
+      if (typeof dataType === 'object' && dataType.type === 'fixed-size-binary') {
+        return {
+          type: 'FIXED_LEN_BYTE_ARRAY',
+          typeLength: dataType.byteWidth,
+          optional: nullable
+        };
+      }
+
+      throw new Error(
+        `ParquetJSWriter: Unsupported field "${field.name}" with type ${formatDataType(dataType)}`
+      );
+  }
+}
+
+/** Returns the minimum fixed byte width required by one decimal precision. */
+function getDecimalByteWidth(precision: number): number {
+  for (let byteWidth = 1; byteWidth <= 32; byteWidth++) {
+    const maximumPrecision = Math.floor(Math.log10(2 ** (8 * byteWidth - 1) - 1));
+    if (precision <= maximumPrecision) return byteWidth;
+  }
+  throw new Error(`ParquetJSWriter: Decimal precision ${precision} exceeds 32 bytes`);
+}
+
+/**
+ * Finds the first non-nullish value in a column.
+ * @param rows table rows
+ * @param columnName column name
+ * @returns first defined value, if any
+ */
+function getFirstDefinedValue(rows: Array<Record<string, unknown>>, columnName: string): unknown {
+  for (const row of rows) {
+    const value = row[columnName];
+    if (value !== null && value !== undefined) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Infers a loaders.gl data type from a JavaScript value.
+ * @param value sample value
+ * @returns inferred data type
+ */
+function getDataTypeFromValue(value: unknown): DataType {
+  if (typeof value === 'boolean') {
+    return 'bool';
+  }
+  if (typeof value === 'number') {
+    return Number.isInteger(value) ? 'int32' : 'float64';
+  }
+  if (typeof value === 'string') {
+    return 'utf8';
+  }
+  if (value instanceof Date) {
+    return 'timestamp-millisecond';
+  }
+  if (value instanceof Uint8Array) {
+    return 'binary';
+  }
+
+  throw new Error('ParquetJSWriter: Unable to infer a Parquet type from the provided row data');
+}
+
+/**
+ * Formats a loaders.gl data type for error messages.
+ * @param dataType input data type
+ * @returns human-readable type string
+ */
+function formatDataType(dataType: DataType): string {
+  return typeof dataType === 'string' ? dataType : dataType.type;
+}

package/src/lib/geo/geospatial-metadata.ts

@@ -0,0 +1,457 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import * as arrow from 'apache-arrow';
+
+import type {Field, Schema} from '@loaders.gl/schema';
+import {
+  getGeoMetadata,
+  getMetadataValue,
+  setGeoMetadata,
+  setMetadataValue,
+  type GeoArrowEncoding,
+  type GeoArrowMetadata,
+  type GeoColumnMetadata,
+  type GeoMetadata,
+  type GeoParquetGeometryType
+} from '@loaders.gl/gis';
+import {
+  GeoArrowMetadataSchema,
+  GeoParquetMetadataSchema
+} from '@loaders.gl/gis/geospatial-metadata-zod-schema';
+import {convertArrowToSchema} from '@loaders.gl/schema-utils';
+
+const GEOARROW_EXTENSION_NAME_KEY = 'ARROW:extension:name';
+const GEOARROW_EXTENSION_METADATA_KEY = 'ARROW:extension:metadata';
+const GEOPARQUET_VERSION = '1.1.0';
+
+const GEOARROW_ENCODINGS = [
+  'geoarrow.geometry',
+  'geoarrow.geometrycollection',
+  'geoarrow.multipolygon',
+  'geoarrow.polygon',
+  'geoarrow.multilinestring',
+  'geoarrow.linestring',
+  'geoarrow.multipoint',
+  'geoarrow.point',
+  'geoarrow.box',
+  'geoarrow.wkb',
+  'geoarrow.wkt'
+] as const satisfies GeoArrowEncoding[];
+
+const GEOPARQUET_TO_GEOARROW_ENCODINGS = {
+  wkb: 'geoarrow.wkb',
+  point: 'geoarrow.point',
+  linestring: 'geoarrow.linestring',
+  polygon: 'geoarrow.polygon',
+  multipoint: 'geoarrow.multipoint',
+  multilinestring: 'geoarrow.multilinestring',
+  multipolygon: 'geoarrow.multipolygon'
+} as const satisfies Record<string, GeoArrowEncoding>;
+
+const GEOARROW_TO_GEOPARQUET_ENCODINGS = {
+  'geoarrow.wkb': 'wkb',
+  'geoarrow.point': 'point',
+  'geoarrow.linestring': 'linestring',
+  'geoarrow.polygon': 'polygon',
+  'geoarrow.multipoint': 'multipoint',
+  'geoarrow.multilinestring': 'multilinestring',
+  'geoarrow.multipolygon': 'multipolygon'
+} as const;
+
+const GEOARROW_TO_GEOMETRY_TYPE = {
+  'geoarrow.point': 'Point',
+  'geoarrow.linestring': 'LineString',
+  'geoarrow.polygon': 'Polygon',
+  'geoarrow.multipoint': 'MultiPoint',
+  'geoarrow.multilinestring': 'MultiLineString',
+  'geoarrow.multipolygon': 'MultiPolygon'
+} as const satisfies Record<string, GeoParquetGeometryType>;
+
+/** Returns GeoArrow geometry field metadata keyed by column name. */
+function getGeometryColumnsFromSchema(schema: Schema): Record<string, GeoArrowMetadata> {
+  const geometryColumns: Record<string, GeoArrowMetadata> = {};
+  for (const field of schema.fields || []) {
+    const metadata = getGeometryMetadataForField(field.metadata || {});
+    if (metadata) {
+      geometryColumns[field.name] = metadata;
+    }
+  }
+  return geometryColumns;
+}
+
+/** Extracts GeoArrow metadata from one schema field metadata object. */
+function getGeometryMetadataForField(
+  fieldMetadata: Record<string, string>
+): GeoArrowMetadata | null {
+  let metadata: GeoArrowMetadata | null = null;
+  let geoEncoding = getMetadataValue(fieldMetadata, GEOARROW_EXTENSION_NAME_KEY);
+  if (geoEncoding) {
+    geoEncoding = geoEncoding.toLowerCase();
+    if (geoEncoding === 'wkb') {
+      geoEncoding = 'geoarrow.wkb';
+    }
+    if (geoEncoding === 'wkt') {
+      geoEncoding = 'geoarrow.wkt';
+    }
+    if (GEOARROW_ENCODINGS.includes(geoEncoding as GeoArrowEncoding)) {
+      metadata ||= {};
+      metadata.encoding = geoEncoding as GeoArrowEncoding;
+    }
+  }
+
+  const columnMetadata = getMetadataValue(fieldMetadata, GEOARROW_EXTENSION_METADATA_KEY);
+  if (columnMetadata) {
+    try {
+      const parsedMetadata = GeoArrowMetadataSchema.parse(JSON.parse(columnMetadata));
+      metadata = {
+        ...(metadata || {}),
+        ...parsedMetadata
+      };
+    } catch {
+      return metadata;
+    }
+  }
+
+  return metadata;
+}
+
+/**
+ * Applies GeoParquet schema metadata to matching geometry fields as GeoArrow field metadata.
+ *
+ * @param schema - Schema to annotate.
+ * @returns The same schema reference.
+ */
+export function applyGeoParquetToFieldMetadata(schema: Schema): Schema {
+  const geoMetadata = getGeoMetadata(schema.metadata);
+  if (!geoMetadata) {
+    return schema;
+  }
+
+  for (const field of schema.fields) {
+    const columnMetadata = geoMetadata.columns?.[field.name];
+    if (!columnMetadata) {
+      continue;
+    }
+
+    const fieldMetadata = getGeoArrowMetadataFromGeoParquetField(field, columnMetadata);
+    if (!fieldMetadata) {
+      continue;
+    }
+
+    field.metadata ||= {};
+    setMetadataValue(field.metadata, GEOARROW_EXTENSION_NAME_KEY, fieldMetadata.extensionName);
+
+    if (fieldMetadata.extensionMetadata) {
+      setMetadataValue(
+        field.metadata,
+        GEOARROW_EXTENSION_METADATA_KEY,
+        JSON.stringify(fieldMetadata.extensionMetadata)
+      );
+    }
+  }
+
+  return schema;
+}
+
+/**
+ * Creates an Arrow JS table whose schema metadata matches a loaders.gl schema.
+ *
+ * @param table - Arrow JS table to rewrap.
+ * @param schema - loaders.gl schema containing desired field/schema metadata.
+ * @returns Table using the updated Arrow JS schema.
+ */
+export function applyLoadersSchemaToArrowTable(table: arrow.Table, schema: Schema): arrow.Table {
+  const arrowSchema = createArrowJsSchema(table.schema, schema);
+  return new arrow.Table(arrowSchema, table.batches);
+}
+
+/**
+ * Normalizes an Arrow wrapper so GeoParquet metadata is preserved and GeoArrow field metadata is attached.
+ *
+ * @param arrowTable - loaders.gl Arrow table wrapper.
+ * @param schemaMetadata - Optional schema metadata override from the Parquet footer.
+ * @returns Arrow table wrapper with synchronized schema metadata.
+ */
+export function normalizeArrowTableGeoMetadata(
+  arrowTable: {shape: 'arrow-table'; data: arrow.Table; schema?: Schema},
+  schemaMetadata?: Map<string, string> | Record<string, string>
+): {shape: 'arrow-table'; data: arrow.Table; schema: Schema} {
+  const schema = convertArrowToSchema(arrowTable.data.schema);
+  mergeSchemaMetadata(schema, schemaMetadata);
+  applyGeoParquetToFieldMetadata(schema);
+
+  return {
+    shape: 'arrow-table',
+    data: applyLoadersSchemaToArrowTable(arrowTable.data, schema),
+    schema
+  };
+}
+
+/**
+ * Synthesizes GeoParquet schema metadata from GeoArrow field metadata when needed.
+ *
+ * @param schema - Schema to inspect and update.
+ * @returns The same schema reference.
+ */
+export function ensureGeoParquetMetadata(schema: Schema): Schema {
+  schema.metadata ||= {};
+  const rawExistingGeoMetadata = getGeoMetadata(schema.metadata);
+  if (isValidGeoParquetMetadata(rawExistingGeoMetadata)) {
+    return schema;
+  }
+  const existingGeoMetadata: GeoMetadata | undefined = rawExistingGeoMetadata || undefined;
+
+  const geometryColumns = getGeometryColumnsFromSchema(schema);
+  const geometryColumnNames = Object.keys(geometryColumns);
+  if (geometryColumnNames.length === 0) {
+    return schema;
+  }
+
+  const geoMetadata: GeoMetadata = {
+    version: GEOPARQUET_VERSION,
+    primary_column: geometryColumnNames[0],
+    columns: {}
+  };
+
+  for (const geometryColumnName of geometryColumnNames) {
+    const geometryMetadata = geometryColumns[geometryColumnName];
+    const synthesizedColumnMetadata = synthesizeGeoParquetColumnMetadata(geometryMetadata);
+    if (!synthesizedColumnMetadata) {
+      continue;
+    }
+
+    const existingColumnMetadata = existingGeoMetadata?.columns?.[geometryColumnName];
+    geoMetadata.columns[geometryColumnName] = {
+      ...pickValidOptionalGeoParquetColumnMetadata(existingColumnMetadata),
+      ...synthesizedColumnMetadata
+    };
+  }
+
+  if (Object.keys(geoMetadata.columns).length === 0) {
+    return schema;
+  }
+
+  setGeoMetadata(schema.metadata, geoMetadata);
+  return schema;
+}
+
+/**
+ * Ensures an Arrow table wrapper carries valid GeoParquet schema metadata when GeoArrow fields are present.
+ *
+ * @param arrowTable - Arrow table wrapper to inspect and update.
+ * @returns Updated Arrow table wrapper.
+ */
+export function ensureGeoParquetMetadataOnArrowTable(arrowTable: {
+  shape: 'arrow-table';
+  data: arrow.Table;
+  schema?: Schema;
+}): {shape: 'arrow-table'; data: arrow.Table; schema: Schema} {
+  const schema = arrowTable.schema || convertArrowToSchema(arrowTable.data.schema);
+  ensureGeoParquetMetadata(schema);
+
+  return {
+    shape: 'arrow-table',
+    data: applyLoadersSchemaToArrowTable(arrowTable.data, schema),
+    schema
+  };
+}
+
+/**
+ * Returns Parquet file key/value metadata as a plain map.
+ *
+ * @param parquetMetadata - parquet-wasm metadata object.
+ * @returns Metadata map.
+ */
+export function getParquetFileMetadataMap(parquetMetadata: {
+  fileMetadata(): {keyValueMetadata(): Map<string, string>};
+}): Map<string, string> {
+  return parquetMetadata.fileMetadata().keyValueMetadata();
+}
+
+function mergeSchemaMetadata(
+  schema: Schema,
+  schemaMetadata?: Map<string, string> | Record<string, string>
+): void {
+  if (!schemaMetadata) {
+    return;
+  }
+
+  schema.metadata ||= {};
+  for (const [metadataKey, metadataValue] of getMetadataEntries(schemaMetadata)) {
+    setMetadataValue(schema.metadata, metadataKey, metadataValue);
+  }
+}
+
+function createArrowJsSchema(baseSchema: arrow.Schema, schema: Schema): arrow.Schema {
+  const fields = baseSchema.fields.map(baseField => {
+    const nextField = schema.fields.find(field => field.name === baseField.name);
+    if (!nextField?.metadata) {
+      return baseField;
+    }
+
+    return baseField.clone({
+      metadata: createMetadataMap(nextField.metadata)
+    });
+  });
+
+  return new arrow.Schema(
+    fields,
+    createMetadataMap(schema.metadata),
+    baseSchema.dictionaries,
+    baseSchema.metadataVersion
+  );
+}
+
+function getGeoArrowMetadataFromGeoParquetField(
+  field: Field,
+  columnMetadata: GeoColumnMetadata
+): {extensionName: GeoArrowEncoding; extensionMetadata?: Record<string, unknown>} | null {
+  const normalizedEncoding = String(columnMetadata.encoding || '').toLowerCase();
+  const extensionName =
+    GEOPARQUET_TO_GEOARROW_ENCODINGS[
+      normalizedEncoding as keyof typeof GEOPARQUET_TO_GEOARROW_ENCODINGS
+    ];
+
+  if (!extensionName) {
+    return null;
+  }
+
+  if (normalizedEncoding === 'wkb' && field.type !== 'binary') {
+    return null;
+  }
+
+  if (normalizedEncoding !== 'wkb' && (field.type === 'binary' || field.type === 'utf8')) {
+    return null;
+  }
+
+  const extensionMetadata: Record<string, unknown> = {};
+  if (columnMetadata.crs !== undefined) {
+    extensionMetadata.crs = columnMetadata.crs;
+  }
+  if (columnMetadata.crs_type !== undefined) {
+    extensionMetadata.crs_type = columnMetadata.crs_type;
+  }
+  if (columnMetadata.edges === 'spherical') {
+    extensionMetadata.edges = 'spherical';
+  }
+
+  return Object.keys(extensionMetadata).length > 0
+    ? {extensionName, extensionMetadata}
+    : {extensionName};
+}
+
+function isValidGeoParquetMetadata(geoMetadata: GeoMetadata | null): boolean {
+  return GeoParquetMetadataSchema.safeParse(geoMetadata).success;
+}
+
+function synthesizeGeoParquetColumnMetadata(
+  geometryMetadata: GeoArrowMetadata
+): GeoColumnMetadata | null {
+  const encoding = geometryMetadata.encoding
+    ? GEOARROW_TO_GEOPARQUET_ENCODINGS[
+        geometryMetadata.encoding as keyof typeof GEOARROW_TO_GEOPARQUET_ENCODINGS
+      ]
+    : null;
+
+  if (!encoding) {
+    return null;
+  }
+
+  const geometryTypes = Array.isArray(geometryMetadata.geometry_types)
+    ? geometryMetadata.geometry_types
+    : inferGeometryTypesFromGeoArrowEncoding(geometryMetadata.encoding);
+
+  const columnMetadata: GeoColumnMetadata = {
+    encoding,
+    geometry_types: geometryTypes
+  };
+
+  if (geometryMetadata.crs !== undefined && typeof geometryMetadata.crs !== 'string') {
+    columnMetadata.crs = geometryMetadata.crs;
+  }
+  if (geometryMetadata.crs_type === 'projjson' || geometryMetadata.crs_type === 'wkt2:2019') {
+    columnMetadata.crs_type = geometryMetadata.crs_type;
+  }
+  if (geometryMetadata.edges === 'spherical') {
+    columnMetadata.edges = 'spherical';
+  }
+
+  return columnMetadata;
+}
+
+function inferGeometryTypesFromGeoArrowEncoding(
+  encoding?: GeoArrowEncoding
+): GeoParquetGeometryType[] {
+  const geometryType = encoding
+    ? GEOARROW_TO_GEOMETRY_TYPE[encoding as keyof typeof GEOARROW_TO_GEOMETRY_TYPE]
+    : null;
+  return geometryType ? [geometryType] : [];
+}
+
+function pickValidOptionalGeoParquetColumnMetadata(
+  columnMetadata: GeoColumnMetadata | undefined
+): Partial<GeoColumnMetadata> {
+  if (!columnMetadata) {
+    return {};
+  }
+
+  const nextColumnMetadata: Partial<GeoColumnMetadata> = {};
+
+  if (columnMetadata.orientation === 'counterclockwise') {
+    nextColumnMetadata.orientation = columnMetadata.orientation;
+  }
+
+  if (isValidBBox(columnMetadata.bbox)) {
+    nextColumnMetadata.bbox = columnMetadata.bbox;
+  }
+
+  if (typeof columnMetadata.epoch === 'number' && Number.isFinite(columnMetadata.epoch)) {
+    nextColumnMetadata.epoch = columnMetadata.epoch;
+  }
+
+  if (columnMetadata.covering && typeof columnMetadata.covering === 'object') {
+    nextColumnMetadata.covering = columnMetadata.covering;
+  }
+
+  return nextColumnMetadata;
+}
+
+function isValidBBox(
+  bbox: GeoColumnMetadata['bbox']
+): bbox is [number, number, number, number] | [number, number, number, number, number, number] {
+  if (!Array.isArray(bbox) || (bbox.length !== 4 && bbox.length !== 6)) {
+    return false;
+  }
+
+  return bbox.every(value => typeof value === 'number' && Number.isFinite(value));
+}
+
+function getMetadataEntries(
+  metadata: Map<string, string> | Record<string, string>
+): [string, string][] {
+  if (metadata instanceof Map) {
+    return [...metadata.entries()];
+  }
+  return Object.entries(metadata);
+}
+
+function createMetadataMap(
+  metadata: Map<string, string> | Record<string, string> | undefined
+): Map<string, string> {
+  if (!metadata) {
+    return new Map();
+  }
+
+  if (metadata instanceof Map) {
+    return new Map(metadata);
+  }
+
+  return new Map(
+    Object.entries(metadata).map(([metadataKey, metadataValue]) => [
+      metadataKey,
+      String(metadataValue)
+    ])
+  );
+}