Resource-based client for the UCD API with well-known discovery or explicit config

Client

The @ucdjs/client package provides a type-safe API client for interacting with the UCD.js API. It provides resource-based helpers for Unicode data files, versions, manifests, and published server configuration.

Getting Started

Installation

Install the client using your preferred package manager.

npm install @ucdjs/client

Initialization

Create a client instance using createUCDClient(). This fetches /.well-known/ucd-config.json from the provided origin, validates it, and uses the discovered endpoint paths to build the resource wrappers. Unlike resource calls (which return { data, error }), createUCDClient() will throw if discovery or validation fails, so you should wrap it in appropriate error handling.

client.ts

import { createUCDClient } from "@ucdjs/client";

const client = await createUCDClient("https://api.ucdjs.dev");

Usage

The client uses a safe error handling pattern for resource calls. You receive an object containing data and error, and discovery happens only during createUCDClient().

client.ts

// Fetch available Unicode versions
const { data: versions, error } = await client.versions.list();

if (error) {
  console.error("Failed to fetch versions:", error.message);
} else {
  console.log("Available versions:", versions);
}

Discovery vs explicit config

There are two ways to configure the client:

createUCDClient(baseUrl) loads /.well-known/ucd-config.json from the server
createUCDClientWithConfig(baseUrl, config) skips the discovery request and accepts the same config object directly

Both approaches use the same UCDWellKnownConfig shape. The difference is only where that data comes from.

This matters when an installation serves the API from a non-default path. For example, a server can publish:

/.well-known/ucd-config.json on the main origin
/edge/api/files for files
/edge/api/versions for versions

The client types stay the same because the config points the resource wrappers at the correct paths.

client.config.get() and client.manifest.get(version) still read the published well-known documents from the origin. The explicit config is about supplying the endpoint map up front, not changing those helper URLs.

client.ts

import { createUCDClientWithConfig } from "@ucdjs/client";

const client = createUCDClientWithConfig("https://example.com", {
  version: "0.1",
  endpoints: {
    files: "/edge/api/files",
    manifest: "/.well-known/ucd-store/{version}.json",
    versions: "/edge/api/versions",
  },
});

Client flow

Resources

The client provides four primary resource namespaces. You access them as properties on the instantiated client object.

Prop

Type

Examples

const { data: fileContent, error } = await client.files.get("16.0.0/ucd/UnicodeData.txt");

if (error) {
  console.error("Failed to fetch file:", error.message);
  return;
}

console.log("File content:", fileContent);

// List all versions
const { data: versions, error } = await client.versions.list();

if (error) {
  console.error("Failed to fetch versions:", error.message);
  return;
}

// Get file tree for a specific Unicode version
const { data: fileTree } = await client.versions.getFileTree("16.0.0");
console.log("File tree:", fileTree);

const { data: config, error } = await client.config.get();

if (error) {
  console.error("Failed to fetch config:", error.message);
  return;
}

console.log("API Config:", config);

const { data: manifest, error } = await client.manifest.get("16.0.0");

if (error) {
  console.error("Failed to fetch manifest:", error.message);
  return;
}

console.log("Expected files for 16.0.0:", manifest.files);

Client

On this page