iceberg-js

library0.8.1jsnpmunverified

Iceberg.js is a small, framework-agnostic JavaScript and TypeScript client specifically designed for interacting with Apache Iceberg REST Catalogs. It provides a thin HTTP wrapper over the official REST API, making it generic enough to work with any Iceberg REST Catalog implementation without vendor lock-in. The current stable version is `0.8.1`. The project maintains an active release cadence, with multiple minor versions released within short intervals, indicating ongoing development towards a stable 1.0.0. Key differentiators include first-class TypeScript support for strong typing, reliance on the native `fetch` API for universal compatibility (Node.js 20+ and modern browsers), and a focused scope on catalog operations, deliberately excluding data reading or Parquet file support.

database http-networking

npm install iceberg-js

github ↗package ↗

INSTALL

IMPORT

SIG · ICEBERG-JS

iceberg-js

databasejavascriptv0.8.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

IcebergRestCatalog

✓ import { IcebergRestCatalog } from 'iceberg-js'

✗ const { IcebergRestCatalog } = require('iceberg-js')

The library primarily uses named exports and is designed for ESM environments. Using CommonJS `require` may lead to runtime errors or incorrect module resolution.

AuthConfig

✓ import type { AuthConfig } from 'iceberg-js'

Importing types like `AuthConfig` should use `import type` for clarity and to ensure they are stripped during compilation, though regular named imports also work in most TypeScript setups.

AccessDelegation

✓ import type { AccessDelegation } from 'iceberg-js'

This type is used for specifying desired access delegation mechanisms, such as 'vended-credentials' or 'remote-signing'.

This quickstart demonstrates how to initialize the IcebergRestCatalog client, create a new namespace, and then define and create a new table within that namespace, including schema and basic properties.

import { IcebergRestCatalog } from 'iceberg-js' const catalog = new IcebergRestCatalog({ baseUrl: 'https://my-catalog.example.com/iceberg/v1', auth: { type: 'bearer', token: process.env.ICEBERG_TOKEN ?? '', // Provide a fallback for process.env }, }) async function setupIceberg() { try { // Create a namespace console.log('Creating namespace...') await catalog.createNamespace({ namespace: ['analytics'] }) console.log('Namespace "analytics" created.') // Create a table console.log('Creating table "events"...') await catalog.createTable( { namespace: ['analytics'] }, { name: 'events', schema: { type: 'struct', fields: [ { id: 1, name: 'id', type: 'long', required: true }, { id: 2, name: 'timestamp', type: 'timestamp', required: true }, { id: 3, name: 'user_id', type: 'string', required: false }, ], 'schema-id': 0, 'identifier-field-ids': [1], }, 'partition-spec': { 'spec-id': 0, fields: [], }, 'write-order': { 'order-id': 0, fields: [], }, properties: { 'write.format.default': 'parquet', }, } ) console.log('Table "events" created in "analytics" namespace.') } catch (error) { console.error('Error during Iceberg setup:', error) } } setupIceberg();

Debug

Known issues

breakingVersion 0.8.0 introduced changes to match the Iceberg Catalog API's return types and error structure more closely. This might require adjustments to existing code that processes responses or handles errors.

fix

Review calls to catalog methods and their error handling; update parsing logic to conform to the new API response and error shapes.

affects: >=0.8.0

breakingVersion 0.8.1 included an alignment of `IcebergType` with the OpenAPI specification. If your application relies on specific internal type definitions that deviate from the standard, this update might introduce type-related breaking changes.

fix

Re-evaluate type usage, especially for schema definitions and data types, to ensure compatibility with the updated `IcebergType` definitions.

affects: >=0.8.1

gotchaThis library is 'Catalog-only' and does not provide functionality for reading or writing data files (e.g., Parquet). It strictly interacts with the Iceberg REST Catalog for metadata operations.

fix

Be aware of this limitation; for data plane operations, you will need to use a separate data processing engine (e.g., Spark, Flink, Trino) that integrates with Iceberg.

affects: all versions

gotchaThe library explicitly targets Node.js version 20.0.0 or higher. Running in older Node.js environments may lead to runtime errors, particularly concerning the native `fetch` API.

fix

Ensure your Node.js development and production environments are running version 20.0.0 or newer.

affects: all versions

gotchaIncorrect configuration of `baseUrl`, `catalogName`, or `auth` options can lead to 4xx HTTP errors (e.g., 401 Unauthorized, 403 Forbidden, 404 Not Found) when interacting with the Iceberg REST Catalog.

fix

Thoroughly verify that `baseUrl` points to the correct catalog endpoint, `catalogName` is specified accurately for multi-catalog setups, and the `auth` object contains valid credentials or configuration.

affects: all versions

Errors

Common errors & fixes

ReferenceError: fetch is not defined

The Node.js environment is older than version 20.0.0, which does not include the native `fetch` API.

fix

Upgrade your Node.js runtime to version 20.0.0 or higher. Alternatively, provide a custom `fetch` implementation in the `IcebergRestCatalog` constructor options if you cannot upgrade Node.js.

TypeError: IcebergRestCatalog is not a constructor

Attempting to use CommonJS `require()` syntax to import the `IcebergRestCatalog` class in a CommonJS module. This library is designed for ESM.

fix

Use ESM `import { IcebergRestCatalog } from 'iceberg-js'` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

HTTP 401 Unauthorized / HTTP 403 Forbidden

The authentication credentials provided in the `auth` option are missing, invalid, or do not have sufficient permissions to access the catalog.

fix

Verify your `auth` configuration in the `IcebergRestCatalog` constructor. Ensure the token is correct, not expired, and has the necessary permissions on the Iceberg REST Catalog.

HTTP 404 Not Found

The `baseUrl` for the Iceberg REST Catalog is incorrect, or if using a `catalogName`, it is misconfigured, leading to an unreachable endpoint.

fix

Double-check the `baseUrl` in your `IcebergRestCatalog` options. If applicable, ensure `catalogName` is set correctly and matches your server's configuration.

Upgrade

Version history

0.8.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/supabase/iceberg-js ↗

packagehttps://www.npmjs.com/package/iceberg-js ↗